public_producer/vendor/markrogoyski/math-php/src/Finance.php

<?php

namespace MathPHP;

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
  */
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;
    }
}