/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.numbers.combinatorics;

/**
 * Computation of <a href="https://en.wikipedia.org/wiki/Stirling_number">Stirling numbers</a>.
 *
 * @since 1.2
 */
public final class Stirling {
    /** Stirling S1 error message. */
    private static final String S1_ERROR_FORMAT = "s(n=%d, k=%d)";
    /** Stirling S2 error message. */
    private static final String S2_ERROR_FORMAT = "S(n=%d, k=%d)";
    /** Overflow threshold for n when computing s(n, 1). */
    private static final int S1_OVERFLOW_K_EQUALS_1 = 21;
    /** Overflow threshold for n when computing s(n, n-2). */
    private static final int S1_OVERFLOW_K_EQUALS_NM2 = 92682;
    /** Overflow threshold for n when computing s(n, n-3). */
    private static final int S1_OVERFLOW_K_EQUALS_NM3 = 2761;
    /** Overflow threshold for n when computing S(n, n-2). */
    private static final int S2_OVERFLOW_K_EQUALS_NM2 = 92683;
    /** Overflow threshold for n when computing S(n, n-3). */
    private static final int S2_OVERFLOW_K_EQUALS_NM3 = 2762;

    /**
     * Precomputed Stirling numbers of the first kind.
     * Provides a thread-safe lazy initialization of the cache.
     */
    private static final class StirlingS1Cache {
        /** Maximum n to compute (exclusive).
         * As s(21,3) = 13803759753640704000 is larger than Long.MAX_VALUE
         * we must stop computation at row 21. */
        static final int MAX_N = 21;
        /** Stirling numbers of the first kind. */
        static final long[][] S1;

        static {
            S1 = new long[MAX_N][];
            // Initialise first two rows to allow s(2, 1) to use s(1, 1)
            S1[0] = new long[] {1};
            S1[1] = new long[] {0, 1};
            for (int n = 2; n < S1.length; n++) {
                S1[n] = new long[n + 1];
                S1[n][0] = 0;
                S1[n][n] = 1;
                for (int k = 1; k < n; k++) {
                    S1[n][k] = S1[n - 1][k - 1] - (n - 1) * S1[n - 1][k];
                }
            }
        }
    }

    /**
     * Precomputed Stirling numbers of the second kind.
     * Provides a thread-safe lazy initialization of the cache.
     */
    private static final class StirlingS2Cache {
        /** Maximum n to compute (exclusive).
         * As S(26,9) = 11201516780955125625 is larger than Long.MAX_VALUE
         * we must stop computation at row 26. */
        static final int MAX_N = 26;
        /** Stirling numbers of the second kind. */
        static final long[][] S2;

        static {
            S2 = new long[MAX_N][];
            S2[0] = new long[] {1};
            for (int n = 1; n < S2.length; n++) {
                S2[n] = new long[n + 1];
                S2[n][0] = 0;
                S2[n][1] = 1;
                S2[n][n] = 1;
                for (int k = 2; k < n; k++) {
                    S2[n][k] = k * S2[n - 1][k] + S2[n - 1][k - 1];
                }
            }
        }
    }

    /** Private constructor. */
    private Stirling() {
        // intentionally empty.
    }

    /**
     * Returns the <em>signed</em> <a
     * href="https://mathworld.wolfram.com/StirlingNumberoftheFirstKind.html">
     * Stirling number of the first kind</a>, "{@code s(n,k)}". The number of permutations of
     * {@code n} elements which contain exactly {@code k} permutation cycles is the
     * nonnegative number: {@code |s(n,k)| = (-1)^(n-k) s(n,k)}
     *
     * @param n Size of the set
     * @param k Number of permutation cycles ({@code 0 <= k <= n})
     * @return {@code s(n,k)}
     * @throws IllegalArgumentException if {@code n < 0}, {@code k < 0} or {@code k > n}.
     * @throws ArithmeticException if some overflow happens, typically for n exceeding 20
     * (s(n,n-1) is handled specifically and does not overflow)
     */
    public static long stirlingS1(int n, int k) {
        checkArguments(n, k);

        if (n < StirlingS1Cache.MAX_N) {
            // The number is in the small cache
            return StirlingS1Cache.S1[n][k];
        }

        // Simple cases
        // https://en.wikipedia.org/wiki/Stirling_numbers_of_the_first_kind#Simple_identities
        if (k == 0) {
            return 0;
        } else if (k == n) {
            return 1;
        } else if (k == 1) {
            checkN(n, k, S1_OVERFLOW_K_EQUALS_1, S1_ERROR_FORMAT);
            // Note: Only occurs for n=21 so avoid computing the sign with pow(-1, n-1) * (n-1)!
            return Factorial.value(n - 1);
        } else if (k == n - 1) {
            return -BinomialCoefficient.value(n, 2);
        } else if (k == n - 2) {
            checkN(n, k, S1_OVERFLOW_K_EQUALS_NM2, S1_ERROR_FORMAT);
            // (3n-1) * binom(n, 3) / 4
            return productOver4(3L * n - 1, BinomialCoefficient.value(n, 3));
        } else if (k == n - 3) {
            checkN(n, k, S1_OVERFLOW_K_EQUALS_NM3, S1_ERROR_FORMAT);
            return -BinomialCoefficient.value(n, 2) * BinomialCoefficient.value(n, 4);
        }

        // Compute using:
        // s(n + 1, k) = s(n, k - 1)     - n       * s(n, k)
        // s(n, k)     = s(n - 1, k - 1) - (n - 1) * s(n - 1, k)

        // n >= 21 (MAX_N)
        // 2 <= k <= n-4

        // Start at the largest easily computed value: n < MAX_N or k < 2
        final int reduction = Math.min(n - StirlingS1Cache.MAX_N, k - 2) + 1;
        int n0 = n - reduction;
        int k0 = k - reduction;

        long sum = stirlingS1(n0, k0);
        while (n0 < n) {
            k0++;
            sum = Math.subtractExact(
                sum,
                Math.multiplyExact(n0, stirlingS1(n0, k0))
            );
            n0++;
        }

        return sum;
    }

    /**
     * Returns the <a
     * href="https://mathworld.wolfram.com/StirlingNumberoftheSecondKind.html">
     * Stirling number of the second kind</a>, "{@code S(n,k)}", the number of
     * ways of partitioning an {@code n}-element set into {@code k} non-empty
     * subsets.
     *
     * @param n Size of the set
     * @param k Number of non-empty subsets ({@code 0 <= k <= n})
     * @return {@code S(n,k)}
     * @throws IllegalArgumentException if {@code n < 0}, {@code k < 0} or {@code k > n}.
     * @throws ArithmeticException if some overflow happens, typically for n exceeding 25 and
     * k between 20 and n-2 (S(n,n-1) is handled specifically and does not overflow)
     */
    public static long stirlingS2(int n, int k) {
        checkArguments(n, k);

        if (n < StirlingS2Cache.MAX_N) {
            // The number is in the small cache
            return StirlingS2Cache.S2[n][k];
        }

        // Simple cases
        if (k == 0) {
            return 0;
        } else if (k == 1 || k == n) {
            return 1;
        } else if (k == 2) {
            checkN(n, k, 64, S2_ERROR_FORMAT);
            return (1L << (n - 1)) - 1L;
        } else if (k == n - 1) {
            return BinomialCoefficient.value(n, 2);
        } else if (k == n - 2) {
            checkN(n, k, S2_OVERFLOW_K_EQUALS_NM2, S2_ERROR_FORMAT);
            // (3n-5) * binom(n, 3) / 4
            return productOver4(3L * n - 5, BinomialCoefficient.value(n, 3));
        } else if (k == n - 3) {
            checkN(n, k, S2_OVERFLOW_K_EQUALS_NM3, S2_ERROR_FORMAT);
            return BinomialCoefficient.value(n - 2, 2) * BinomialCoefficient.value(n, 4);
        }

        // Compute using:
        // S(n, k) = k * S(n - 1, k) + S(n - 1, k - 1)

        // n >= 26 (MAX_N)
        // 3 <= k <= n-3

        // Start at the largest easily computed value: n < MAX_N or k < 3
        final int reduction = Math.min(n - StirlingS2Cache.MAX_N, k - 3) + 1;
        int n0 = n - reduction;
        int k0 = k - reduction;

        long sum = stirlingS2(n0, k0);
        while (n0 < n) {
            k0++;
            sum = Math.addExact(
                Math.multiplyExact(k0, stirlingS2(n0, k0)),
                sum
            );
            n0++;
        }

        return sum;
    }

    /**
     * Check {@code 0 <= k <= n}.
     *
     * @param n N
     * @param k K
     * @throws IllegalArgumentException if {@code n < 0}, {@code k < 0} or {@code k > n}.
     */
    private static void checkArguments(int n, int k) {
        // Combine all checks with a single branch:
        // 0 <= n; 0 <= k <= n
        // Note: If n >= 0 && k >= 0 && n - k < 0 then k > n.
        // Bitwise or will detect a negative sign bit in any of the numbers
        if ((n | k | (n - k)) < 0) {
            // Raise the correct exception
            if (n < 0) {
                throw new CombinatoricsException(CombinatoricsException.NEGATIVE, n);
            }
            throw new CombinatoricsException(CombinatoricsException.OUT_OF_RANGE, k, 0, n);
        }
    }

    /**
     * Check {@code n <= threshold}, or else throw an {@link ArithmeticException}.
     *
     * @param n N
     * @param k K
     * @param threshold Threshold for {@code n}
     * @param msgFormat Error message format
     * @throws ArithmeticException if overflow is expected to happen
     */
    private static void checkN(int n, int k, int threshold, String msgFormat) {
        if (n > threshold) {
            throw new ArithmeticException(String.format(msgFormat, n, k));
        }
    }

    /**
     * Return {@code a*b/4} without intermediate overflow.
     * It is assumed that:
     * <ul>
     * <li>The coefficients a and b are positive</li>
     * <li>The product (a*b) is an exact multiple of 4</li>
     * <li>The result (a*b/4) is an exact integer that does not overflow a {@code long}</li>
     * </ul>
     *
     * <p>A conditional branch is performed on the odd/even property of {@code b}.
     * The branch is predictable if {@code b} is typically the same parity.
     *
     * @param a Coefficient a
     * @param b Coefficient b
     * @return {@code a*b/4}
     */
    private static long productOver4(long a, long b) {
        // Compute (a*b/4) without intermediate overflow.
        // The product (a*b) must be an exact multiple of 4.
        // If b is even: ((b/2) * a) / 2
        // If b is odd then a must be even to make a*b even: ((a/2) * b) / 2
        return (b & 1) == 0 ?
            ((b >>> 1) * a) >>> 1 :
            ((a >>> 1) * b) >>> 1;
    }
}
