Dolibarr / dolibarr

htdocs/includes/markrogoyski/math-php/src/Finance.php

Indentation +770 added lines, -770 removed lines

@@ -5,776 +5,776 @@
 use MathPHP\Exception\OutOfBoundsException;
 
 /**
-  * General references on financial functions and formulas:
-  * - Open Document Format for Office Applications (OpenDocument) Version 1.2 Part 2:
-  *   Recalculated Formula (OpenFormula) Format. 29 September 2011. OASIS Standard.
-  *   http://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os-part2.html#__RefHeading__1018228_715980110
-  * - https://wiki.openoffice.org/wiki/Documentation/How_Tos/Calc:_Derivation_of_Financial_Formulas#Loans_and_Annuities
-  */
+ * General references on financial functions and formulas:
+ * - Open Document Format for Office Applications (OpenDocument) Version 1.2 Part 2:
+ *   Recalculated Formula (OpenFormula) Format. 29 September 2011. OASIS Standard.
+ *   http://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os-part2.html#__RefHeading__1018228_715980110
+ * - https://wiki.openoffice.org/wiki/Documentation/How_Tos/Calc:_Derivation_of_Financial_Formulas#Loans_and_Annuities
+ */
 class Finance
 {
-    /**
-     * Floating-point range near zero to consider insignificant.
-     */
-    public const EPSILON = 1e-6;
-
-    /**
-     * Consider any floating-point value less than epsilon from zero as zero,
-     * ie any value in the range [-epsilon < 0 < epsilon] is considered zero.
-     * Also used to convert -0.0 to 0.0.
-     *
-     * @param float $value
-     * @param float $epsilon
-     *
-     * @return float
-     */
-    private static function checkZero(float $value, float $epsilon = self::EPSILON): float
-    {
-        return \abs($value) < $epsilon ? 0.0 : $value;
-    }
-
-    /**
-     * Financial payment for a loan or annuity with compound interest.
-     * Determines the periodic payment amount for a given interest rate,
-     * principal, targeted payment goal, life of the annuity as number
-     * of payments, and whether the payments are made at the start or end
-     * of each payment period.
-     *
-     * Same as the =PMT() function in most spreadsheet software.
-     *
-     * The basic monthly payment formula derivation:
-     * https://en.wikipedia.org/wiki/Mortgage_calculator#Monthly_payment_formula
-     *
-     *       rP(1+r)ᴺ
-     * PMT = --------
-     *       (1+r)ᴺ-1
-     *
-     * The formula is adjusted to allow targeting any future value rather than 0.
-     * The 1/(1+r*when) factor adjusts the payment to the beginning or end
-     * of the period. In the common case of a payment at the end of a period,
-     * the factor is 1 and reduces to the formula above. Setting when=1 computes
-     * an "annuity due" with an immediate payment.
-     *
-     * Examples:
-     * The payment on a 30-year fixed mortgage note of $265000 at 3.5% interest
-     * paid at the end of every month.
-     *   pmt(0.035/12, 30*12, 265000, 0, false)
-     *
-     * The payment on a 30-year fixed mortgage note of $265000 at 3.5% interest
-     * needed to half the principal in half in 5 years:
-     *   pmt(0.035/12, 5*12, 265000, 265000/2, false)
-     *
-     * The weekly payment into a savings account with 1% interest rate and current
-     * balance of $1500 needed to reach $10000 after 3 years:
-     *   pmt(0.01/52, 3*52, -1500, 10000, false)
-     * The present_value is negative indicating money put into the savings account,
-     * whereas future_value is positive, indicating money that will be withdrawn from
-     * the account. Similarly, the payment value is negative
-     *
-     * How much money can be withdrawn at the end of every quarter from an account
-     * with $1000000 earning 4% so the money lasts 20 years:
-     *  pmt(0.04/4, 20*4, 1000000, 0, false)
-     *
-     * @param  float $rate
-     * @param  int   $periods
-     * @param  float $present_value
-     * @param  float $future_value
-     * @param  bool  $beginning adjust the payment to the beginning or end of the period
-     *
-     * @return float
-     */
-    public static function pmt(float $rate, int $periods, float $present_value, float $future_value = 0.0, bool $beginning = false): float
-    {
-        $when = $beginning ? 1 : 0;
-
-        if ($rate == 0) {
-            return - ($future_value + $present_value) / $periods;
-        }
-
-        return - ($future_value + ($present_value * \pow(1 + $rate, $periods)))
-            /
-            ((1 + $rate * $when) / $rate * (\pow(1 + $rate, $periods) - 1));
-    }
-
-    /**
-     * Interest on a financial payment for a loan or annuity with compound interest.
-     * Determines the interest payment at a particular period of the annuity. For
-     * a typical loan paid down to zero, the amount of interest and principle paid
-     * throughout the lifetime of the loan will change, with the interest portion
-     * of the payment decreasing over time as the loan principle decreases.
-     *
-     * Same as the =IPMT() function in most spreadsheet software.
-     *
-     * See the PMT function for derivation of the formula. For IPMT, we have
-     * the payment equal to the interest portion and principle portion of the payment:
-     *
-     * PMT = IPMT + PPMT
-     *
-     * The interest portion IPMT on a regular annuity can be calculated by computing
-     * the future value of the annuity for the prior period and computing the compound
-     * interest for one period:
-     *
-     * IPMT = FV(p=n-1) * rate
-     *
-     * For an "annuity due" where payment is at the start of the period, period=1 has
-     * no interest portion of the payment because no time has elapsed for compounding.
-     * To compute the interest portion of the payment, the future value of 2 periods
-     * back needs to be computed, as the definition of a period is different, giving:
-     *
-     * IPMT = (FV(p=n-2) - PMT) * rate
-     *
-     * By thinking of the future value at period 0 instead of the present value, the
-     * given formulas are computed.
-     *
-     * Example of regular annuity and annuity due for a loan of $10.00 paid back in 3 periods.
-     * Although the principle payments are equal, the total payment and interest portion are
-     * lower with the annuity due because a principle payment is made immediately.
-     *
-     *                       Regular Annuity |  Annuity Due
-     * Period   FV       PMT    IPMT   PPMT  |   PMT    IPMT    PPMT
-     *   0     -10.00                        |
-     *   1      -6.83   -3.67  -0.50  -3.17  |  -3.50   0.00   -3.50
-     *   2      -3.50   -3.67  -0.34  -3.33  |  -3.50  -0.33   -3.17
-     *   3       0.00   -3.67  -0.17  -3.50  |  -3.50  -0.17   -3.33
-     *                -----------------------|----------------------
-     *             SUM -11.01  -1.01 -10.00  | -10.50  -0.50  -10.00
-     *
-     * Examples:
-     * The interest on a payment on a 30-year fixed mortgage note of $265000 at 3.5% interest
-     * paid at the end of every month, looking at the first payment:
-     *   ipmt(0.035/12, 1, 30*12, 265000, 0, false)
-     *
-     * @param  float $rate
-     * @param  int   $period
-     * @param  int   $periods
-     * @param  float $present_value
-     * @param  float $future_value
-     * @param  bool  $beginning adjust the payment to the beginning or end of the period
-     *
-     * @return float
-     */
-    public static function ipmt(float $rate, int $period, int $periods, float $present_value, float $future_value = 0.0, bool $beginning = false): float
-    {
-        if ($period < 1 || $period > $periods) {
-            return \NAN;
-        }
-
-        if ($rate == 0) {
-            return 0;
-        }
-
-        if ($beginning && $period == 1) {
-            return 0.0;
-        }
-
-        $payment = self::pmt($rate, $periods, $present_value, $future_value, $beginning);
-        if ($beginning) {
-            $interest = (self::fv($rate, $period - 2, $payment, $present_value, $beginning) - $payment) * $rate;
-        } else {
-            $interest = self::fv($rate, $period - 1, $payment, $present_value, $beginning) * $rate;
-        }
-
-        return self::checkZero($interest);
-    }
-
-    /**
-     * Principle on a financial payment for a loan or annuity with compound interest.
-     * Determines the principle payment at a particular period of the annuity. For
-     * a typical loan paid down to zero, the amount of interest and principle paid
-     * throughout the lifetime of the loan will change, with the principle portion
-     * of the payment increasing over time as the loan principle decreases.
-     *
-     * Same as the =PPMT() function in most spreadsheet software.
-     *
-     * See the PMT function for derivation of the formula.
-     * See the IPMT function for derivation and use of PMT, IPMT, and PPMT.
-     *
-     * With derivations for PMT and IPMT, we simply compute:
-     *
-     * PPMT = PMT - IPMT
-     *
-     * Examples:
-     * The principle on a payment on a 30-year fixed mortgage note of $265000 at 3.5% interest
-     * paid at the end of every month, looking at the first payment:
-     *   ppmt(0.035/12, 1, 30*12, 265000, 0, false)
-     *
-     * @param  float $rate
-     * @param  int   $period
-     * @param  int   $periods
-     * @param  float $present_value
-     * @param  float $future_value
-     * @param  bool  $beginning adjust the payment to the beginning or end of the period
-     *
-     * @return float
-     */
-    public static function ppmt(float $rate, int $period, int $periods, float $present_value, float $future_value = 0.0, bool $beginning = false): float
-    {
-        $payment = self::pmt($rate, $periods, $present_value, $future_value, $beginning);
-        $ipmt    = self::ipmt($rate, $period, $periods, $present_value, $future_value, $beginning);
-
-        return $payment - $ipmt;
-    }
-
-    /**
-     * Number of payment periods of an annuity.
-     * Solves for the number of periods in the annuity formula.
-     *
-     * Same as the =NPER() function in most spreadsheet software.
-     *
-     * Solving the basic annuity formula for number of periods:
-     *        log(PMT - FV*r)
-     *        ---------------
-     *        log(PMT + PV*r)
-     * n = --------------------
-     *          log(1 + r)
-     *
-     * The (1+r*when) factor adjusts the payment to the beginning or end
-     * of the period. In the common case of a payment at the end of a period,
-     * the factor is 1 and reduces to the formula above. Setting when=1 computes
-     * an "annuity due" with an immediate payment.
-     *
-     * Examples:
-     * The number of periods of a $475000 mortgage with interest rate 3.5% and monthly
-     * payment of $2132.96  paid in full:
-     *   nper(0.035/12, -2132.96, 475000, 0)
-     *
-     * @param  float $rate
-     * @param  float $payment
-     * @param  float $present_value
-     * @param  float $future_value
-     * @param  bool  $beginning adjust the payment to the beginning or end of the period
-     *
-     * @return float
-     */
-    public static function periods(float $rate, float $payment, float $present_value, float $future_value, bool $beginning = false): float
-    {
-        $when = $beginning ? 1 : 0;
-
-        if ($rate == 0) {
-            return - ($present_value + $future_value) / $payment;
-        }
-
-        $initial = $payment * (1.0 + $rate * $when);
-        return \log(($initial - $future_value * $rate) / ($initial + $present_value * $rate)) / \log(1.0 + $rate);
-    }
-
-    /**
-     * Annual Equivalent Rate (AER) of an annual percentage rate (APR).
-     * The effective yearly rate of an annual percentage rate when the
-     * annual percentage rate is compounded periodically within the year.
-     *
-     * Same as the =EFFECT() function in most spreadsheet software.
-     *
-     * The formula:
-     * https://en.wikipedia.org/wiki/Effective_interest_rate
-     *
-     *        /     i \ ᴺ
-     * AER = | 1 +  -  |  - 1
-     *        \     n /
-     *
-     * Examples:
-     * The AER of APR 3.5% interest compounded monthly.
-     *   aer(0.035, 12)
-     *
-     * @param  float $nominal
-     * @param  int $periods
-     *
-     * @return float
-     */
-    public static function aer(float $nominal, int $periods): float
-    {
-        if ($periods == 1) {
-            return $nominal;
-        }
-
-        return \pow(1 + ($nominal / $periods), $periods) - 1;
-    }
-
-    /**
-     * Annual Nominal Rate of an annual effective rate (AER).
-     * The nominal yearly rate of an annual effective rate when the
-     * annual effective rate is compounded periodically within the year.
-     *
-     * Same as the =NOMINAL() function in most spreadsheet software.
-     *
-     * See:
-     * https://en.wikipedia.org/wiki/Nominal_interest_rate
-     *
-     *           /          1/N    \
-     * NOMINAL = | (AER + 1)    -1 | * N
-     *           \                 /
-     *
-     * Examples:
-     * The nominal rate of AER 3.557% interest compounded monthly.
-     *   nominal(0.03557, 12)
-     *
-     * @param  float $aer
-     * @param  int $periods
-     *
-     * @return float
-     */
-    public static function nominal(float $aer, int $periods): float
-    {
-        if ($periods == 1) {
-            return $aer;
-        }
-
-        return (\pow($aer + 1, 1 / $periods) - 1) * $periods;
-    }
-
-    /**
-     * Future value for a loan or annuity with compound interest.
-     *
-     * Same as the =FV() function in most spreadsheet software.
-     *
-     * The basic future-value formula derivation:
-     * https://en.wikipedia.org/wiki/Future_value
-     *
-     *                   PMT*((1+r)ᴺ - 1)
-     * FV = -PV*(1+r)ᴺ - ----------------
-     *                          r
-     *
-     * The (1+r*when) factor adjusts the payment to the beginning or end
-     * of the period. In the common case of a payment at the end of a period,
-     * the factor is 1 and reduces to the formula above. Setting when=1 computes
-     * an "annuity due" with an immediate payment.
-     *
-     * Examples:
-     * The future value in 5 years on a 30-year fixed mortgage note of $265000
-     * at 3.5% interest paid at the end of every month. This is how much loan
-     * principle would be outstanding:
-     *   fv(0.035/12, 5*12, 1189.97, -265000, false)
-     *
-     * The present_value is negative indicating money borrowed for the mortgage,
-     * whereas payment is positive, indicating money that will be paid to the
-     * mortgage.
-     *
-     * @param  float $rate
-     * @param  int   $periods
-     * @param  float $payment
-     * @param  float $present_value
-     * @param  bool  $beginning adjust the payment to the beginning or end of the period
-     *
-     * @return float
-     */
-    public static function fv(float $rate, int $periods, float $payment, float $present_value, bool $beginning = false): float
-    {
-        $when = $beginning ? 1 : 0;
-
-        if ($rate == 0) {
-            $fv = -($present_value + ($payment * $periods));
-            return self::checkZero($fv);
-        }
-
-        $initial  = 1 + ($rate * $when);
-        $compound = \pow(1 + $rate, $periods);
-        $fv       = - (($present_value * $compound) + (($payment * $initial * ($compound - 1)) / $rate));
-
-        return self::checkZero($fv);
-    }
-
-    /**
-     * Present value for a loan or annuity with compound interest.
-     *
-     * Same as the =PV() function in most spreadsheet software.
-     *
-     * The basic present-value formula derivation:
-     * https://en.wikipedia.org/wiki/Present_value
-     *
-     *            PMT*((1+r)ᴺ - 1)
-     * PV = -FV - ----------------
-     *                   r
-     *      ---------------------
-     *             (1 + r)ᴺ
-     *
-     * The (1+r*when) factor adjusts the payment to the beginning or end
-     * of the period. In the common case of a payment at the end of a period,
-     * the factor is 1 and reduces to the formula above. Setting when=1 computes
-     * an "annuity due" with an immediate payment.
-     *
-     * Examples:
-     * The present value of a bond's $1000 face value paid in 5 year's time
-     * with a constant discount rate of 3.5% compounded monthly:
-     *   pv(0.035/12, 5*12, 0, -1000, false)
-     *
-     * The present value of a $1000 5-year bond that pays a fixed 7% ($70)
-     * coupon at the end of each year with a discount rate of 5%:
-     *   pv(0.5, 5, -70, -1000, false)
-     *
-     * The payment and future_value is negative indicating money paid out.
-     *
-     * @param  float $rate
-     * @param  int   $periods
-     * @param  float $payment
-     * @param  float $future_value
-     * @param  bool  $beginning adjust the payment to the beginning or end of the period
-     *
-     * @return float
-     */
-    public static function pv(float $rate, int $periods, float $payment, float $future_value, bool $beginning = false): float
-    {
-        $when = $beginning ? 1 : 0;
-
-        if ($rate == 0) {
-            $pv = -$future_value - ($payment * $periods);
-            return self::checkZero($pv);
-        }
-
-        $initial  = 1 + ($rate * $when);
-        $compound = \pow(1 + $rate, $periods);
-        $pv       = (-$future_value - (($payment * $initial * ($compound - 1)) / $rate)) / $compound;
-
-        return self::checkZero($pv);
-    }
-
-    /**
-     * Net present value of cash flows. Cash flows are periodic starting
-     * from an initial time and with a uniform discount rate.
-     *
-     * Similar to the =NPV() function in most spreadsheet software, except
-     * the initial (usually negative) cash flow at time 0 is given as the
-     * first element of the array rather than subtracted. For example,
-     *   spreadsheet: =NPV(0.01, 100, 200, 300, 400) - 1000
-     * is done as
-     *   MathPHP::npv(0.01, [-1000, 100, 200, 300, 400])
-     *
-     * The basic net-present-value formula derivation:
-     * https://en.wikipedia.org/wiki/Net_present_value
-     *
-     *  n      Rt
-     *  Σ   --------
-     * t=0  (1 / r)ᵗ
-     *
-     * Examples:
-     * The net present value of 5 yearly cash flows after an initial $1000
-     * investment with a 3% discount rate:
-     *  npv(0.03, [-1000, 100, 500, 300, 700, 700])
-     *
-     * @param  float $rate
-     * @param  array<float> $values
-     *
-     * @return float
-     */
-    public static function npv(float $rate, array $values): float
-    {
-        $result = 0.0;
-
-        for ($i = 0; $i < \count($values); ++$i) {
-            $result += $values[$i] / (1 + $rate) ** $i;
-        }
-
-        return $result;
-    }
-
-    /**
-     * Interest rate per period of an Annuity.
-     *
-     * Same as the =RATE() formula in most spreadsheet software.
-     *
-     * The basic rate formula derivation is to solve for the future value
-     * taking into account the present value:
-     * https://en.wikipedia.org/wiki/Future_value
-     *
-     *                        ((1+r)ᴺ - 1)
-     * FV + PV*(1+r)ᴺ + PMT * ------------ = 0
-     *                             r
-     * The (1+r*when) factor adjusts the payment to the beginning or end
-     * of the period. In the common case of a payment at the end of a period,
-     * the factor is 1 and reduces to the formula above. Setting when=1 computes
-     * an "annuity due" with an immediate payment.
-     *
-     * Not all solutions for the rate have real-value solutions or converge.
-     * In these cases, NAN is returned.
-     *
-     * @param  float $periods
-     * @param  float $payment
-     * @param  float $present_value
-     * @param  float $future_value
-     * @param  bool  $beginning
-     * @param  float $initial_guess
-     *
-     * @return float
-     */
-    public static function rate(float $periods, float $payment, float $present_value, float $future_value, bool $beginning = false, float $initial_guess = 0.1): float
-    {
-        $when = $beginning ? 1 : 0;
-
-        $func = function ($x, $periods, $payment, $present_value, $future_value, $when) {
-            return $future_value + $present_value * (1 + $x) ** $periods + $payment * (1 + $x * $when) / $x * ((1 + $x) ** $periods - 1);
-        };
-
-        return self::checkZero(NumericalAnalysis\RootFinding\NewtonsMethod::solve($func, [$initial_guess, $periods, $payment, $present_value, $future_value, $when], 0, self::EPSILON, 0));
-    }
-
-    /**
-     * Internal rate of return.
-     * Periodic rate of return that would provide a net-present value (NPV) of 0.
-     *
-     * Same as =IRR formula in most spreadsheet software.
-     *
-     * Reference:
-     * https://en.wikipedia.org/wiki/Internal_rate_of_return
-     *
-     * Examples:
-     * The rate of return of an initial investment of $100 with returns
-     * of $50, $40, and $30:
-     *  irr([-100, 50, 40, 30])
-     *
-     * Solves for NPV=0 using Newton's Method.
-     * @param array<float> $values
-     * @param float $initial_guess
-     *
-     * @return float
-     *
-     * @throws OutOfBoundsException
-     *
-     * @todo: Use eigenvalues to find the roots of a characteristic polynomial.
-     * This will allow finding all solutions and eliminate the need of the initial_guess.
-     */
-    public static function irr(array $values, float $initial_guess = 0.1): float
-    {
-        $func = function ($x, $values) {
-            return Finance::npv($x, $values);
-        };
-
-        if (\count($values) <= 1) {
-            return \NAN;
-        }
-
-        $root = NumericalAnalysis\RootFinding\NewtonsMethod::solve($func, [$initial_guess, $values], 0, self::EPSILON, 0);
-        if (!\is_nan($root)) {
-            return self::CheckZero($root);
-        }
-        return self::checkZero(self::alternateIrr($values));
-    }
-
-    /**
-     * Alternate IRR implementation.
-     *
-     * A more numerically stable implementation that converges to only one value.
-     *
-     * Based off of Better: https://github.com/better/irr
-     *
-     * @param  array<float> $values
-     *
-     * @return float
-     */
-    private static function alternateIrr(array $values): float
-    {
-        $rate = 0.0;
-        for ($iter = 0; $iter < 100; $iter++) {
-            $m = -1000;
-            for ($i = 0; $i < \count($values); $i++) {
-                $m = \max($m, -$rate * $i);
-            }
-            $f = [];
-            for ($i = 0; $i < \count($values); $i++) {
-                $f[$i] = \exp(-$rate * $i - $m);
-            }
-            $t = 0;
-            for ($i = 0; $i < \count($values); $i++) {
-                $t += $f[$i] * $values[$i];
-            }
-            if (\abs($t) < (self::EPSILON * \exp($m))) {
-                break;
-            }
-            $u = 0;
-            for ($i = 0; $i < \count($values); $i++) {
-                $u += $f[$i] * $i * $values[$i];
-            }
-            if ($u == 0) {
-                return \NAN;
-            }
-            $rate += $t / $u;
-        }
-        return \exp($rate) - 1;
-    }
-
-    /**
-     * Modified internal rate of return.
-     * Rate of return that discounts outflows (investments) at the financing rate,
-     * and reinvests inflows with an expected rate of return.
-     *
-     * Same as =MIRR formula in most spreadsheet software.
-     *
-     * The formula derivation:
-     * https://en.wikipedia.org/wiki/Modified_internal_rate_of_return
-     *
-     *       _____________________________
-     *     n/ FV(re-invested cash inflows)
-     *  -  /  ----------------------------  - 1.0
-     *   \/   PV(discounted cash outflows)
-     *
-     * Examples:
-     * The rate of return of an initial investment of $100 at 5% financing
-     * with returns of $50, $40, and $30 reinvested at 10%:
-     *  mirr([-100, 50, 40, 30], 0.05, 0.10)
-     *
-     * @param  array<float> $values
-     * @param  float $finance_rate
-     * @param  float $reinvestment_rate
-     *
-     * @return float
-     */
-    public static function mirr(array $values, float $finance_rate, float $reinvestment_rate): float
-    {
-        $inflows  = array();
-        $outflows = array();
-
-        for ($i = 0; $i < \count($values); $i++) {
-            if ($values[$i] >= 0) {
-                $inflows[]  = $values[$i];
-                $outflows[] = 0;
-            } else {
-                $inflows[]  = 0;
-                $outflows[] = $values[$i];
-            }
-        }
-
-        $nonzero = function ($x) {
-            return $x != 0;
-        };
-
-        if (\count(\array_filter($inflows, $nonzero)) == 0 || \count(\array_filter($outflows, $nonzero)) == 0) {
-            return \NAN;
-        }
-
-        $root        = \count($values) - 1;
-        $pv_inflows  = self::npv($reinvestment_rate, $inflows);
-        $fv_inflows  = self::fv($reinvestment_rate, $root, 0, -$pv_inflows);
-        $pv_outflows = self::npv($finance_rate, $outflows);
-
-        return self::checkZero(\pow($fv_inflows / -$pv_outflows, 1 / $root) - 1);
-    }
-
-    /**
-     * Discounted Payback of an investment.
-     * The number of periods to recoup cash outlays of an investment.
-     *
-     * This is commonly used with discount rate=0 as simple payback period,
-     * but it is not a real financial measurement when it doesn't consider the
-     * discount rate. Even with a discount rate, it doesn't consider the cost
-     * of capital or re-investment of returns.
-     *
-     * Avoid this when possible. Consider NPV, MIRR, IRR, and other financial
-     * functions.
-     *
-     * Reference:
-     * https://en.wikipedia.org/wiki/Payback_period
-     *
-     * The result is given assuming cash flows are continous throughout a period.
-     * To compute payback in terms of whole periods, use ceil() on the result.
-     *
-     * An investment could reach its payback period before future cash outlays occur.
-     * The payback period returned is defined to be the final point at which the
-     * sum of returns becomes positive.
-     *
-     * Examples:
-     * The payback period of an investment with a $1,000 investment and future returns
-     * of $100, $200, $300, $400, $500:
-     *  payback([-1000, 100, 200, 300, 400, 500])
-     *
-     * The discounted payback period of an investment with a $1,000 investment, future returns
-     * of $100, $200, $300, $400, $500, and a discount rate of 0.10:
-     *  payback([-1000, 100, 200, 300, 400, 500], 0.1)
-     *
-     * @param  array<float> $values
-     * @param  float $rate
-     *
-     * @return float
-     */
-    public static function payback(array $values, float $rate = 0.0): float
-    {
-        $last_outflow = -1;
-        for ($i = 0; $i < \count($values); $i++) {
-            if ($values[$i] < 0) {
-                $last_outflow = $i;
-            }
-        }
-
-        if ($last_outflow < 0) {
-            return 0.0;
-        }
-
-        $sum            = $values[0];
-        $payback_period = -1;
-
-        for ($i = 1; $i < \count($values); $i++) {
-            $prevsum         = $sum;
-            $discounted_flow = $values[$i] / (1 + $rate) ** $i;
-            $sum            += $discounted_flow;
-            if ($sum >= 0) {
-                if ($i > $last_outflow) {
-                    return ($i - 1) + (-$prevsum / $discounted_flow);
-                }
-                if ($payback_period == -1) {
-                    $payback_period = ($i - 1) + (-$prevsum / $discounted_flow);
-                }
-            } else {
-                $payback_period = -1;
-            }
-        }
-        if ($sum >= 0) {
-            return $payback_period;
-        }
-
-        return \NAN;
-    }
-
-    /**
-     * Profitability Index.
-     * The Profitability Index, also referred to as Profit Investment
-     * Ratio (PIR) and Value Investment Ratio (VIR), is a comparison of
-     * discounted cash inflows to discounted cash outflows. It can be
-     * used as a decision criteria of an investment, using larger than 1
-     * to choose an investment, and less than 1 to pass.
-     *
-     * The formula derivation:
-     * https://en.wikipedia.org/wiki/Profitability_index
-     *
-     * PV(cash inflows)
-     * ----------------
-     * PV(cash outflows)
-     *
-     * The formula is usually stated in terms of the initial investmest,
-     * but it is generalized here to discount all future outflows.
-     *
-     * Examples:
-     * The profitability index of an initial $100 investment with future
-     * returns of $50, $50, $50 with a 10% discount rate:
-     *  profitabilityIndex([-100, 50, 50, 50], 0.10)
-     *
-     * @param  array<float> $values
-     * @param  float $rate
-     *
-     * @return float
-     */
-    public static function profitabilityIndex(array $values, float $rate): float
-    {
-        $inflows  = array();
-        $outflows = array();
-
-        for ($i = 0; $i < \count($values); $i++) {
-            if ($values[$i] >= 0) {
-                $inflows[]  = $values[$i];
-                $outflows[] = 0;
-            } else {
-                $inflows[]  = 0;
-                $outflows[] = -$values[$i];
-            }
-        }
-
-        $nonzero = function ($x) {
-            return $x != 0;
-        };
-
-        if (\count(\array_filter($outflows, $nonzero)) == 0) {
-            return \NAN;
-        }
-
-        $pv_inflows  = self::npv($rate, $inflows);
-        $pv_outflows = self::npv($rate, $outflows);
-
-        return $pv_inflows / $pv_outflows;
-    }
+	/**
+	 * Floating-point range near zero to consider insignificant.
+	 */
+	public const EPSILON = 1e-6;
+
+	/**
+	 * Consider any floating-point value less than epsilon from zero as zero,
+	 * ie any value in the range [-epsilon < 0 < epsilon] is considered zero.
+	 * Also used to convert -0.0 to 0.0.
+	 *
+	 * @param float $value
+	 * @param float $epsilon
+	 *
+	 * @return float
+	 */
+	private static function checkZero(float $value, float $epsilon = self::EPSILON): float
+	{
+		return \abs($value) < $epsilon ? 0.0 : $value;
+	}
+
+	/**
+	 * Financial payment for a loan or annuity with compound interest.
+	 * Determines the periodic payment amount for a given interest rate,
+	 * principal, targeted payment goal, life of the annuity as number
+	 * of payments, and whether the payments are made at the start or end
+	 * of each payment period.
+	 *
+	 * Same as the =PMT() function in most spreadsheet software.
+	 *
+	 * The basic monthly payment formula derivation:
+	 * https://en.wikipedia.org/wiki/Mortgage_calculator#Monthly_payment_formula
+	 *
+	 *       rP(1+r)ᴺ
+	 * PMT = --------
+	 *       (1+r)ᴺ-1
+	 *
+	 * The formula is adjusted to allow targeting any future value rather than 0.
+	 * The 1/(1+r*when) factor adjusts the payment to the beginning or end
+	 * of the period. In the common case of a payment at the end of a period,
+	 * the factor is 1 and reduces to the formula above. Setting when=1 computes
+	 * an "annuity due" with an immediate payment.
+	 *
+	 * Examples:
+	 * The payment on a 30-year fixed mortgage note of $265000 at 3.5% interest
+	 * paid at the end of every month.
+	 *   pmt(0.035/12, 30*12, 265000, 0, false)
+	 *
+	 * The payment on a 30-year fixed mortgage note of $265000 at 3.5% interest
+	 * needed to half the principal in half in 5 years:
+	 *   pmt(0.035/12, 5*12, 265000, 265000/2, false)
+	 *
+	 * The weekly payment into a savings account with 1% interest rate and current
+	 * balance of $1500 needed to reach $10000 after 3 years:
+	 *   pmt(0.01/52, 3*52, -1500, 10000, false)
+	 * The present_value is negative indicating money put into the savings account,
+	 * whereas future_value is positive, indicating money that will be withdrawn from
+	 * the account. Similarly, the payment value is negative
+	 *
+	 * How much money can be withdrawn at the end of every quarter from an account
+	 * with $1000000 earning 4% so the money lasts 20 years:
+	 *  pmt(0.04/4, 20*4, 1000000, 0, false)
+	 *
+	 * @param  float $rate
+	 * @param  int   $periods
+	 * @param  float $present_value
+	 * @param  float $future_value
+	 * @param  bool  $beginning adjust the payment to the beginning or end of the period
+	 *
+	 * @return float
+	 */
+	public static function pmt(float $rate, int $periods, float $present_value, float $future_value = 0.0, bool $beginning = false): float
+	{
+		$when = $beginning ? 1 : 0;
+
+		if ($rate == 0) {
+			return - ($future_value + $present_value) / $periods;
+		}
+
+		return - ($future_value + ($present_value * \pow(1 + $rate, $periods)))
+			/
+			((1 + $rate * $when) / $rate * (\pow(1 + $rate, $periods) - 1));
+	}
+
+	/**
+	 * Interest on a financial payment for a loan or annuity with compound interest.
+	 * Determines the interest payment at a particular period of the annuity. For
+	 * a typical loan paid down to zero, the amount of interest and principle paid
+	 * throughout the lifetime of the loan will change, with the interest portion
+	 * of the payment decreasing over time as the loan principle decreases.
+	 *
+	 * Same as the =IPMT() function in most spreadsheet software.
+	 *
+	 * See the PMT function for derivation of the formula. For IPMT, we have
+	 * the payment equal to the interest portion and principle portion of the payment:
+	 *
+	 * PMT = IPMT + PPMT
+	 *
+	 * The interest portion IPMT on a regular annuity can be calculated by computing
+	 * the future value of the annuity for the prior period and computing the compound
+	 * interest for one period:
+	 *
+	 * IPMT = FV(p=n-1) * rate
+	 *
+	 * For an "annuity due" where payment is at the start of the period, period=1 has
+	 * no interest portion of the payment because no time has elapsed for compounding.
+	 * To compute the interest portion of the payment, the future value of 2 periods
+	 * back needs to be computed, as the definition of a period is different, giving:
+	 *
+	 * IPMT = (FV(p=n-2) - PMT) * rate
+	 *
+	 * By thinking of the future value at period 0 instead of the present value, the
+	 * given formulas are computed.
+	 *
+	 * Example of regular annuity and annuity due for a loan of $10.00 paid back in 3 periods.
+	 * Although the principle payments are equal, the total payment and interest portion are
+	 * lower with the annuity due because a principle payment is made immediately.
+	 *
+	 *                       Regular Annuity |  Annuity Due
+	 * Period   FV       PMT    IPMT   PPMT  |   PMT    IPMT    PPMT
+	 *   0     -10.00                        |
+	 *   1      -6.83   -3.67  -0.50  -3.17  |  -3.50   0.00   -3.50
+	 *   2      -3.50   -3.67  -0.34  -3.33  |  -3.50  -0.33   -3.17
+	 *   3       0.00   -3.67  -0.17  -3.50  |  -3.50  -0.17   -3.33
+	 *                -----------------------|----------------------
+	 *             SUM -11.01  -1.01 -10.00  | -10.50  -0.50  -10.00
+	 *
+	 * Examples:
+	 * The interest on a payment on a 30-year fixed mortgage note of $265000 at 3.5% interest
+	 * paid at the end of every month, looking at the first payment:
+	 *   ipmt(0.035/12, 1, 30*12, 265000, 0, false)
+	 *
+	 * @param  float $rate
+	 * @param  int   $period
+	 * @param  int   $periods
+	 * @param  float $present_value
+	 * @param  float $future_value
+	 * @param  bool  $beginning adjust the payment to the beginning or end of the period
+	 *
+	 * @return float
+	 */
+	public static function ipmt(float $rate, int $period, int $periods, float $present_value, float $future_value = 0.0, bool $beginning = false): float
+	{
+		if ($period < 1 || $period > $periods) {
+			return \NAN;
+		}
+
+		if ($rate == 0) {
+			return 0;
+		}
+
+		if ($beginning && $period == 1) {
+			return 0.0;
+		}
+
+		$payment = self::pmt($rate, $periods, $present_value, $future_value, $beginning);
+		if ($beginning) {
+			$interest = (self::fv($rate, $period - 2, $payment, $present_value, $beginning) - $payment) * $rate;
+		} else {
+			$interest = self::fv($rate, $period - 1, $payment, $present_value, $beginning) * $rate;
+		}
+
+		return self::checkZero($interest);
+	}
+
+	/**
+	 * Principle on a financial payment for a loan or annuity with compound interest.
+	 * Determines the principle payment at a particular period of the annuity. For
+	 * a typical loan paid down to zero, the amount of interest and principle paid
+	 * throughout the lifetime of the loan will change, with the principle portion
+	 * of the payment increasing over time as the loan principle decreases.
+	 *
+	 * Same as the =PPMT() function in most spreadsheet software.
+	 *
+	 * See the PMT function for derivation of the formula.
+	 * See the IPMT function for derivation and use of PMT, IPMT, and PPMT.
+	 *
+	 * With derivations for PMT and IPMT, we simply compute:
+	 *
+	 * PPMT = PMT - IPMT
+	 *
+	 * Examples:
+	 * The principle on a payment on a 30-year fixed mortgage note of $265000 at 3.5% interest
+	 * paid at the end of every month, looking at the first payment:
+	 *   ppmt(0.035/12, 1, 30*12, 265000, 0, false)
+	 *
+	 * @param  float $rate
+	 * @param  int   $period
+	 * @param  int   $periods
+	 * @param  float $present_value
+	 * @param  float $future_value
+	 * @param  bool  $beginning adjust the payment to the beginning or end of the period
+	 *
+	 * @return float
+	 */
+	public static function ppmt(float $rate, int $period, int $periods, float $present_value, float $future_value = 0.0, bool $beginning = false): float
+	{
+		$payment = self::pmt($rate, $periods, $present_value, $future_value, $beginning);
+		$ipmt    = self::ipmt($rate, $period, $periods, $present_value, $future_value, $beginning);
+
+		return $payment - $ipmt;
+	}
+
+	/**
+	 * Number of payment periods of an annuity.
+	 * Solves for the number of periods in the annuity formula.
+	 *
+	 * Same as the =NPER() function in most spreadsheet software.
+	 *
+	 * Solving the basic annuity formula for number of periods:
+	 *        log(PMT - FV*r)
+	 *        ---------------
+	 *        log(PMT + PV*r)
+	 * n = --------------------
+	 *          log(1 + r)
+	 *
+	 * The (1+r*when) factor adjusts the payment to the beginning or end
+	 * of the period. In the common case of a payment at the end of a period,
+	 * the factor is 1 and reduces to the formula above. Setting when=1 computes
+	 * an "annuity due" with an immediate payment.
+	 *
+	 * Examples:
+	 * The number of periods of a $475000 mortgage with interest rate 3.5% and monthly
+	 * payment of $2132.96  paid in full:
+	 *   nper(0.035/12, -2132.96, 475000, 0)
+	 *
+	 * @param  float $rate
+	 * @param  float $payment
+	 * @param  float $present_value
+	 * @param  float $future_value
+	 * @param  bool  $beginning adjust the payment to the beginning or end of the period
+	 *
+	 * @return float
+	 */
+	public static function periods(float $rate, float $payment, float $present_value, float $future_value, bool $beginning = false): float
+	{
+		$when = $beginning ? 1 : 0;
+
+		if ($rate == 0) {
+			return - ($present_value + $future_value) / $payment;
+		}
+
+		$initial = $payment * (1.0 + $rate * $when);
+		return \log(($initial - $future_value * $rate) / ($initial + $present_value * $rate)) / \log(1.0 + $rate);
+	}
+
+	/**
+	 * Annual Equivalent Rate (AER) of an annual percentage rate (APR).
+	 * The effective yearly rate of an annual percentage rate when the
+	 * annual percentage rate is compounded periodically within the year.
+	 *
+	 * Same as the =EFFECT() function in most spreadsheet software.
+	 *
+	 * The formula:
+	 * https://en.wikipedia.org/wiki/Effective_interest_rate
+	 *
+	 *        /     i \ ᴺ
+	 * AER = | 1 +  -  |  - 1
+	 *        \     n /
+	 *
+	 * Examples:
+	 * The AER of APR 3.5% interest compounded monthly.
+	 *   aer(0.035, 12)
+	 *
+	 * @param  float $nominal
+	 * @param  int $periods
+	 *
+	 * @return float
+	 */
+	public static function aer(float $nominal, int $periods): float
+	{
+		if ($periods == 1) {
+			return $nominal;
+		}
+
+		return \pow(1 + ($nominal / $periods), $periods) - 1;
+	}
+
+	/**
+	 * Annual Nominal Rate of an annual effective rate (AER).
+	 * The nominal yearly rate of an annual effective rate when the
+	 * annual effective rate is compounded periodically within the year.
+	 *
+	 * Same as the =NOMINAL() function in most spreadsheet software.
+	 *
+	 * See:
+	 * https://en.wikipedia.org/wiki/Nominal_interest_rate
+	 *
+	 *           /          1/N    \
+	 * NOMINAL = | (AER + 1)    -1 | * N
+	 *           \                 /
+	 *
+	 * Examples:
+	 * The nominal rate of AER 3.557% interest compounded monthly.
+	 *   nominal(0.03557, 12)
+	 *
+	 * @param  float $aer
+	 * @param  int $periods
+	 *
+	 * @return float
+	 */
+	public static function nominal(float $aer, int $periods): float
+	{
+		if ($periods == 1) {
+			return $aer;
+		}
+
+		return (\pow($aer + 1, 1 / $periods) - 1) * $periods;
+	}
+
+	/**
+	 * Future value for a loan or annuity with compound interest.
+	 *
+	 * Same as the =FV() function in most spreadsheet software.
+	 *
+	 * The basic future-value formula derivation:
+	 * https://en.wikipedia.org/wiki/Future_value
+	 *
+	 *                   PMT*((1+r)ᴺ - 1)
+	 * FV = -PV*(1+r)ᴺ - ----------------
+	 *                          r
+	 *
+	 * The (1+r*when) factor adjusts the payment to the beginning or end
+	 * of the period. In the common case of a payment at the end of a period,
+	 * the factor is 1 and reduces to the formula above. Setting when=1 computes
+	 * an "annuity due" with an immediate payment.
+	 *
+	 * Examples:
+	 * The future value in 5 years on a 30-year fixed mortgage note of $265000
+	 * at 3.5% interest paid at the end of every month. This is how much loan
+	 * principle would be outstanding:
+	 *   fv(0.035/12, 5*12, 1189.97, -265000, false)
+	 *
+	 * The present_value is negative indicating money borrowed for the mortgage,
+	 * whereas payment is positive, indicating money that will be paid to the
+	 * mortgage.
+	 *
+	 * @param  float $rate
+	 * @param  int   $periods
+	 * @param  float $payment
+	 * @param  float $present_value
+	 * @param  bool  $beginning adjust the payment to the beginning or end of the period
+	 *
+	 * @return float
+	 */
+	public static function fv(float $rate, int $periods, float $payment, float $present_value, bool $beginning = false): float
+	{
+		$when = $beginning ? 1 : 0;
+
+		if ($rate == 0) {
+			$fv = -($present_value + ($payment * $periods));
+			return self::checkZero($fv);
+		}
+
+		$initial  = 1 + ($rate * $when);
+		$compound = \pow(1 + $rate, $periods);
+		$fv       = - (($present_value * $compound) + (($payment * $initial * ($compound - 1)) / $rate));
+
+		return self::checkZero($fv);
+	}
+
+	/**
+	 * Present value for a loan or annuity with compound interest.
+	 *
+	 * Same as the =PV() function in most spreadsheet software.
+	 *
+	 * The basic present-value formula derivation:
+	 * https://en.wikipedia.org/wiki/Present_value
+	 *
+	 *            PMT*((1+r)ᴺ - 1)
+	 * PV = -FV - ----------------
+	 *                   r
+	 *      ---------------------
+	 *             (1 + r)ᴺ
+	 *
+	 * The (1+r*when) factor adjusts the payment to the beginning or end
+	 * of the period. In the common case of a payment at the end of a period,
+	 * the factor is 1 and reduces to the formula above. Setting when=1 computes
+	 * an "annuity due" with an immediate payment.
+	 *
+	 * Examples:
+	 * The present value of a bond's $1000 face value paid in 5 year's time
+	 * with a constant discount rate of 3.5% compounded monthly:
+	 *   pv(0.035/12, 5*12, 0, -1000, false)
+	 *
+	 * The present value of a $1000 5-year bond that pays a fixed 7% ($70)
+	 * coupon at the end of each year with a discount rate of 5%:
+	 *   pv(0.5, 5, -70, -1000, false)
+	 *
+	 * The payment and future_value is negative indicating money paid out.
+	 *
+	 * @param  float $rate
+	 * @param  int   $periods
+	 * @param  float $payment
+	 * @param  float $future_value
+	 * @param  bool  $beginning adjust the payment to the beginning or end of the period
+	 *
+	 * @return float
+	 */
+	public static function pv(float $rate, int $periods, float $payment, float $future_value, bool $beginning = false): float
+	{
+		$when = $beginning ? 1 : 0;
+
+		if ($rate == 0) {
+			$pv = -$future_value - ($payment * $periods);
+			return self::checkZero($pv);
+		}
+
+		$initial  = 1 + ($rate * $when);
+		$compound = \pow(1 + $rate, $periods);
+		$pv       = (-$future_value - (($payment * $initial * ($compound - 1)) / $rate)) / $compound;
+
+		return self::checkZero($pv);
+	}
+
+	/**
+	 * Net present value of cash flows. Cash flows are periodic starting
+	 * from an initial time and with a uniform discount rate.
+	 *
+	 * Similar to the =NPV() function in most spreadsheet software, except
+	 * the initial (usually negative) cash flow at time 0 is given as the
+	 * first element of the array rather than subtracted. For example,
+	 *   spreadsheet: =NPV(0.01, 100, 200, 300, 400) - 1000
+	 * is done as
+	 *   MathPHP::npv(0.01, [-1000, 100, 200, 300, 400])
+	 *
+	 * The basic net-present-value formula derivation:
+	 * https://en.wikipedia.org/wiki/Net_present_value
+	 *
+	 *  n      Rt
+	 *  Σ   --------
+	 * t=0  (1 / r)ᵗ
+	 *
+	 * Examples:
+	 * The net present value of 5 yearly cash flows after an initial $1000
+	 * investment with a 3% discount rate:
+	 *  npv(0.03, [-1000, 100, 500, 300, 700, 700])
+	 *
+	 * @param  float $rate
+	 * @param  array<float> $values
+	 *
+	 * @return float
+	 */
+	public static function npv(float $rate, array $values): float
+	{
+		$result = 0.0;
+
+		for ($i = 0; $i < \count($values); ++$i) {
+			$result += $values[$i] / (1 + $rate) ** $i;
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Interest rate per period of an Annuity.
+	 *
+	 * Same as the =RATE() formula in most spreadsheet software.
+	 *
+	 * The basic rate formula derivation is to solve for the future value
+	 * taking into account the present value:
+	 * https://en.wikipedia.org/wiki/Future_value
+	 *
+	 *                        ((1+r)ᴺ - 1)
+	 * FV + PV*(1+r)ᴺ + PMT * ------------ = 0
+	 *                             r
+	 * The (1+r*when) factor adjusts the payment to the beginning or end
+	 * of the period. In the common case of a payment at the end of a period,
+	 * the factor is 1 and reduces to the formula above. Setting when=1 computes
+	 * an "annuity due" with an immediate payment.
+	 *
+	 * Not all solutions for the rate have real-value solutions or converge.
+	 * In these cases, NAN is returned.
+	 *
+	 * @param  float $periods
+	 * @param  float $payment
+	 * @param  float $present_value
+	 * @param  float $future_value
+	 * @param  bool  $beginning
+	 * @param  float $initial_guess
+	 *
+	 * @return float
+	 */
+	public static function rate(float $periods, float $payment, float $present_value, float $future_value, bool $beginning = false, float $initial_guess = 0.1): float
+	{
+		$when = $beginning ? 1 : 0;
+
+		$func = function ($x, $periods, $payment, $present_value, $future_value, $when) {
+			return $future_value + $present_value * (1 + $x) ** $periods + $payment * (1 + $x * $when) / $x * ((1 + $x) ** $periods - 1);
+		};
+
+		return self::checkZero(NumericalAnalysis\RootFinding\NewtonsMethod::solve($func, [$initial_guess, $periods, $payment, $present_value, $future_value, $when], 0, self::EPSILON, 0));
+	}
+
+	/**
+	 * Internal rate of return.
+	 * Periodic rate of return that would provide a net-present value (NPV) of 0.
+	 *
+	 * Same as =IRR formula in most spreadsheet software.
+	 *
+	 * Reference:
+	 * https://en.wikipedia.org/wiki/Internal_rate_of_return
+	 *
+	 * Examples:
+	 * The rate of return of an initial investment of $100 with returns
+	 * of $50, $40, and $30:
+	 *  irr([-100, 50, 40, 30])
+	 *
+	 * Solves for NPV=0 using Newton's Method.
+	 * @param array<float> $values
+	 * @param float $initial_guess
+	 *
+	 * @return float
+	 *
+	 * @throws OutOfBoundsException
+	 *
+	 * @todo: Use eigenvalues to find the roots of a characteristic polynomial.
+	 * This will allow finding all solutions and eliminate the need of the initial_guess.
+	 */
+	public static function irr(array $values, float $initial_guess = 0.1): float
+	{
+		$func = function ($x, $values) {
+			return Finance::npv($x, $values);
+		};
+
+		if (\count($values) <= 1) {
+			return \NAN;
+		}
+
+		$root = NumericalAnalysis\RootFinding\NewtonsMethod::solve($func, [$initial_guess, $values], 0, self::EPSILON, 0);
+		if (!\is_nan($root)) {
+			return self::CheckZero($root);
+		}
+		return self::checkZero(self::alternateIrr($values));
+	}
+
+	/**
+	 * Alternate IRR implementation.
+	 *
+	 * A more numerically stable implementation that converges to only one value.
+	 *
+	 * Based off of Better: https://github.com/better/irr
+	 *
+	 * @param  array<float> $values
+	 *
+	 * @return float
+	 */
+	private static function alternateIrr(array $values): float
+	{
+		$rate = 0.0;
+		for ($iter = 0; $iter < 100; $iter++) {
+			$m = -1000;
+			for ($i = 0; $i < \count($values); $i++) {
+				$m = \max($m, -$rate * $i);
+			}
+			$f = [];
+			for ($i = 0; $i < \count($values); $i++) {
+				$f[$i] = \exp(-$rate * $i - $m);
+			}
+			$t = 0;
+			for ($i = 0; $i < \count($values); $i++) {
+				$t += $f[$i] * $values[$i];
+			}
+			if (\abs($t) < (self::EPSILON * \exp($m))) {
+				break;
+			}
+			$u = 0;
+			for ($i = 0; $i < \count($values); $i++) {
+				$u += $f[$i] * $i * $values[$i];
+			}
+			if ($u == 0) {
+				return \NAN;
+			}
+			$rate += $t / $u;
+		}
+		return \exp($rate) - 1;
+	}
+
+	/**
+	 * Modified internal rate of return.
+	 * Rate of return that discounts outflows (investments) at the financing rate,
+	 * and reinvests inflows with an expected rate of return.
+	 *
+	 * Same as =MIRR formula in most spreadsheet software.
+	 *
+	 * The formula derivation:
+	 * https://en.wikipedia.org/wiki/Modified_internal_rate_of_return
+	 *
+	 *       _____________________________
+	 *     n/ FV(re-invested cash inflows)
+	 *  -  /  ----------------------------  - 1.0
+	 *   \/   PV(discounted cash outflows)
+	 *
+	 * Examples:
+	 * The rate of return of an initial investment of $100 at 5% financing
+	 * with returns of $50, $40, and $30 reinvested at 10%:
+	 *  mirr([-100, 50, 40, 30], 0.05, 0.10)
+	 *
+	 * @param  array<float> $values
+	 * @param  float $finance_rate
+	 * @param  float $reinvestment_rate
+	 *
+	 * @return float
+	 */
+	public static function mirr(array $values, float $finance_rate, float $reinvestment_rate): float
+	{
+		$inflows  = array();
+		$outflows = array();
+
+		for ($i = 0; $i < \count($values); $i++) {
+			if ($values[$i] >= 0) {
+				$inflows[]  = $values[$i];
+				$outflows[] = 0;
+			} else {
+				$inflows[]  = 0;
+				$outflows[] = $values[$i];
+			}
+		}
+
+		$nonzero = function ($x) {
+			return $x != 0;
+		};
+
+		if (\count(\array_filter($inflows, $nonzero)) == 0 || \count(\array_filter($outflows, $nonzero)) == 0) {
+			return \NAN;
+		}
+
+		$root        = \count($values) - 1;
+		$pv_inflows  = self::npv($reinvestment_rate, $inflows);
+		$fv_inflows  = self::fv($reinvestment_rate, $root, 0, -$pv_inflows);
+		$pv_outflows = self::npv($finance_rate, $outflows);
+
+		return self::checkZero(\pow($fv_inflows / -$pv_outflows, 1 / $root) - 1);
+	}
+
+	/**
+	 * Discounted Payback of an investment.
+	 * The number of periods to recoup cash outlays of an investment.
+	 *
+	 * This is commonly used with discount rate=0 as simple payback period,
+	 * but it is not a real financial measurement when it doesn't consider the
+	 * discount rate. Even with a discount rate, it doesn't consider the cost
+	 * of capital or re-investment of returns.
+	 *
+	 * Avoid this when possible. Consider NPV, MIRR, IRR, and other financial
+	 * functions.
+	 *
+	 * Reference:
+	 * https://en.wikipedia.org/wiki/Payback_period
+	 *
+	 * The result is given assuming cash flows are continous throughout a period.
+	 * To compute payback in terms of whole periods, use ceil() on the result.
+	 *
+	 * An investment could reach its payback period before future cash outlays occur.
+	 * The payback period returned is defined to be the final point at which the
+	 * sum of returns becomes positive.
+	 *
+	 * Examples:
+	 * The payback period of an investment with a $1,000 investment and future returns
+	 * of $100, $200, $300, $400, $500:
+	 *  payback([-1000, 100, 200, 300, 400, 500])
+	 *
+	 * The discounted payback period of an investment with a $1,000 investment, future returns
+	 * of $100, $200, $300, $400, $500, and a discount rate of 0.10:
+	 *  payback([-1000, 100, 200, 300, 400, 500], 0.1)
+	 *
+	 * @param  array<float> $values
+	 * @param  float $rate
+	 *
+	 * @return float
+	 */
+	public static function payback(array $values, float $rate = 0.0): float
+	{
+		$last_outflow = -1;
+		for ($i = 0; $i < \count($values); $i++) {
+			if ($values[$i] < 0) {
+				$last_outflow = $i;
+			}
+		}
+
+		if ($last_outflow < 0) {
+			return 0.0;
+		}
+
+		$sum            = $values[0];
+		$payback_period = -1;
+
+		for ($i = 1; $i < \count($values); $i++) {
+			$prevsum         = $sum;
+			$discounted_flow = $values[$i] / (1 + $rate) ** $i;
+			$sum            += $discounted_flow;
+			if ($sum >= 0) {
+				if ($i > $last_outflow) {
+					return ($i - 1) + (-$prevsum / $discounted_flow);
+				}
+				if ($payback_period == -1) {
+					$payback_period = ($i - 1) + (-$prevsum / $discounted_flow);
+				}
+			} else {
+				$payback_period = -1;
+			}
+		}
+		if ($sum >= 0) {
+			return $payback_period;
+		}
+
+		return \NAN;
+	}
+
+	/**
+	 * Profitability Index.
+	 * The Profitability Index, also referred to as Profit Investment
+	 * Ratio (PIR) and Value Investment Ratio (VIR), is a comparison of
+	 * discounted cash inflows to discounted cash outflows. It can be
+	 * used as a decision criteria of an investment, using larger than 1
+	 * to choose an investment, and less than 1 to pass.
+	 *
+	 * The formula derivation:
+	 * https://en.wikipedia.org/wiki/Profitability_index
+	 *
+	 * PV(cash inflows)
+	 * ----------------
+	 * PV(cash outflows)
+	 *
+	 * The formula is usually stated in terms of the initial investmest,
+	 * but it is generalized here to discount all future outflows.
+	 *
+	 * Examples:
+	 * The profitability index of an initial $100 investment with future
+	 * returns of $50, $50, $50 with a 10% discount rate:
+	 *  profitabilityIndex([-100, 50, 50, 50], 0.10)
+	 *
+	 * @param  array<float> $values
+	 * @param  float $rate
+	 *
+	 * @return float
+	 */
+	public static function profitabilityIndex(array $values, float $rate): float
+	{
+		$inflows  = array();
+		$outflows = array();
+
+		for ($i = 0; $i < \count($values); $i++) {
+			if ($values[$i] >= 0) {
+				$inflows[]  = $values[$i];
+				$outflows[] = 0;
+			} else {
+				$inflows[]  = 0;
+				$outflows[] = -$values[$i];
+			}
+		}
+
+		$nonzero = function ($x) {
+			return $x != 0;
+		};
+
+		if (\count(\array_filter($outflows, $nonzero)) == 0) {
+			return \NAN;
+		}
+
+		$pv_inflows  = self::npv($rate, $inflows);
+		$pv_outflows = self::npv($rate, $outflows);
+
+		return $pv_inflows / $pv_outflows;
+	}
 }

htdocs/includes/markrogoyski/math-php/src/NumericalAnalysis/RootFinding/NewtonsMethod.php

Indentation +43 added lines, -43 removed lines

@@ -12,50 +12,50 @@
  */
 class NewtonsMethod
 {
-    /**
-     * Use Newton's Method to find the x which produces $target = $function(x) value
-     * $args is an array of parameters to pass to $function, but having the element that
-     * will be changed and serve as the initial guess in position $position.
-     *
-     * @param callable     $function     f(x) callback function
-     * @param array<mixed> $args         Parameters to pass to callback function. The initial value for the
-     *                                   parameter of interest must be in this array.
-     * @param int|float    $target       Value of f(x) we a trying to solve for
-     * @param float        $tol          Tolerance; How close to the actual solution we would like.
-     * @param int          $position     Which element in the $args array will be changed; also serves as initial guess
-     * @param int          $iterations
-     *
-     * @return int|float
-     *
-     * @throws Exception\OutOfBoundsException if the tolerance is not valid
-     */
-    public static function solve(callable $function, array $args, $target, float $tol, int $position = 0, int $iterations = 100)
-    {
-        Validation::tolerance($tol);
+	/**
+	 * Use Newton's Method to find the x which produces $target = $function(x) value
+	 * $args is an array of parameters to pass to $function, but having the element that
+	 * will be changed and serve as the initial guess in position $position.
+	 *
+	 * @param callable     $function     f(x) callback function
+	 * @param array<mixed> $args         Parameters to pass to callback function. The initial value for the
+	 *                                   parameter of interest must be in this array.
+	 * @param int|float    $target       Value of f(x) we a trying to solve for
+	 * @param float        $tol          Tolerance; How close to the actual solution we would like.
+	 * @param int          $position     Which element in the $args array will be changed; also serves as initial guess
+	 * @param int          $iterations
+	 *
+	 * @return int|float
+	 *
+	 * @throws Exception\OutOfBoundsException if the tolerance is not valid
+	 */
+	public static function solve(callable $function, array $args, $target, float $tol, int $position = 0, int $iterations = 100)
+	{
+		Validation::tolerance($tol);
 
-        // Initialize
-        $args1 = $args;
-        $guess = $args[$position];
-        $i     = 0;
+		// Initialize
+		$args1 = $args;
+		$guess = $args[$position];
+		$i     = 0;
 
-        do {
-            $args1[$position] = $guess + $tol; // load the initial guess into the arguments
-            $args[$position]  = $guess;        // load the initial guess into the arguments
-            $y                = $function(...$args);
-            $y_at_xplusdelx   = $function(...$args1);
-            $slope            = ($y_at_xplusdelx - $y) / $tol;
-            $del_y            = $target - $y;
-            if (\abs($slope) < $tol) {
-                return \NAN;
-            }
-            $guess            = $del_y / $slope + $guess;
-            $dif              = \abs($del_y);
-            $i++;
-        } while ($dif > $tol && $i < $iterations);
+		do {
+			$args1[$position] = $guess + $tol; // load the initial guess into the arguments
+			$args[$position]  = $guess;        // load the initial guess into the arguments
+			$y                = $function(...$args);
+			$y_at_xplusdelx   = $function(...$args1);
+			$slope            = ($y_at_xplusdelx - $y) / $tol;
+			$del_y            = $target - $y;
+			if (\abs($slope) < $tol) {
+				return \NAN;
+			}
+			$guess            = $del_y / $slope + $guess;
+			$dif              = \abs($del_y);
+			$i++;
+		} while ($dif > $tol && $i < $iterations);
 
-        if ($dif > $tol) {
-            return \NAN;
-        }
-        return $guess;
-    }
+		if ($dif > $tol) {
+			return \NAN;
+		}
+		return $guess;
+	}
 }

htdocs/includes/markrogoyski/math-php/src/NumericalAnalysis/RootFinding/Validation.php

Indentation +27 added lines, -27 removed lines

@@ -9,32 +9,32 @@
  */
 class Validation
 {
-    /**
-     * Throw an exception if the tolerance is negative.
-     *
-     * @param int|float $tol Tolerance; How close to the actual solution we would like.
-     *
-     * @throws Exception\OutOfBoundsException if $tol (the tolerance) is negative
-     */
-    public static function tolerance($tol): void
-    {
-        if ($tol < 0) {
-            throw new Exception\OutOfBoundsException('Tolerance must be greater than zero.');
-        }
-    }
+	/**
+	 * Throw an exception if the tolerance is negative.
+	 *
+	 * @param int|float $tol Tolerance; How close to the actual solution we would like.
+	 *
+	 * @throws Exception\OutOfBoundsException if $tol (the tolerance) is negative
+	 */
+	public static function tolerance($tol): void
+	{
+		if ($tol < 0) {
+			throw new Exception\OutOfBoundsException('Tolerance must be greater than zero.');
+		}
+	}
 
-    /**
-     * Verify that the start and end of of an interval are distinct numbers.
-     *
-     * @param int|float $a The start of the interval
-     * @param int|float $b The end of the interval
-     *
-     * @throws Exception\BadDataException if $a = $b
-     */
-    public static function interval($a, $b): void
-    {
-        if ($a === $b) {
-            throw new Exception\BadDataException('Start point and end point of interval cannot be the same.');
-        }
-    }
+	/**
+	 * Verify that the start and end of of an interval are distinct numbers.
+	 *
+	 * @param int|float $a The start of the interval
+	 * @param int|float $b The end of the interval
+	 *
+	 * @throws Exception\BadDataException if $a = $b
+	 */
+	public static function interval($a, $b): void
+	{
+		if ($a === $b) {
+			throw new Exception\BadDataException('Start point and end point of interval cannot be the same.');
+		}
+	}
 }