Skip to main content
Skip to main content
Edit this page

Financial functions

financialInternalRateOfReturn​

Calculates the Internal Rate of Return (IRR) for a series of cash flows occurring at regular intervals. IRR is the discount rate at which the Net Present Value (NPV) equals zero.

IRR attempts to solve the following equation:

∑i=0ncashflowi(1+irr)i=0\sum_{i=0}^n \frac{cashflow_i}{(1 + irr)^i} = 0

Syntax

Arguments

  • cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Type: Array of numeric values (Int8, Int16, Int32, Int64, Float32, Float64).
  • guess — Optional initial guess (constant value) for the internal rate of return. Default: 0.1. Type: Float32|Float64.

Returned value

  • Returns the internal rate of return as a Float64 value.
  • Returns NaN if:
    • The calculation cannot converge
    • Input array is empty or has only one element
    • All cash flows are zero
    • Other calculation errors occur

Examples

Basic usage:

With initial guess:

Notes

  • The function uses Newton-Raphson and TOMS748 methods for finding the root.
  • At least one cash flow must be negative and one must be positive for a meaningful IRR calculation.

financialInternalRateOfReturnExtended​

Calculates the Extended Internal Rate of Return (XIRR) for a series of cash flows occurring at irregular intervals. XIRR is the discount rate at which the net present value (NPV) of all cash flows equals zero.

XIRR attempts to solve the following equation (example for ACT_365F):

∑i=0ncashflowi(1+rate)(datei−date0)/365=0\sum_{i=0}^n \frac{cashflow_i}{(1 + rate)^{(date_i - date_0)/365}} = 0

Syntax

Arguments

  • cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Type: Array of numeric values (Int8, Int16, Int32, Int64, Float32, Float64).
  • dates — Array of dates corresponding to each cash flow. Must be sorted in ascending order with unique values. Type: Array of Date or Date32.
  • guess — Optional initial guess (constant value) for the internal rate of return. Default: 0.1. Type: Float32|Float64.
  • daycount — Optional day count convention. Supported values:
    • 'ACT_365F' (default) — Actual/365 Fixed
    • 'ACT_365_25' — Actual/365.25

Returned value

  • Returns the internal rate of return as a Float64 value.
  • Returns NaN if:
    • The calculation cannot converge
    • Input arrays are empty or have only one element
    • All cash flows are zero
    • Dates are not sorted or not unique
    • Other calculation errors occur

Examples

Basic usage:

Using different day count convention:

Notes

  • The function uses Newton-Raphson and TOMS748 methods for finding the root.
  • The dates array must be sorted in ascending order with unique values.

financialNetPresentValueExtended​

Calculates the Extended Net Present Value (XNPV) for a series of cash flows occurring at irregular intervals. XNPV considers the specific timing of each cash flow when calculating present value.

XNPV equation for ACT_365F:

XNPV=∑i=1ncashflowi(1+rate)(datei−date0)/365XNPV=\sum_{i=1}^n \frac{cashflow_i}{(1 + rate)^{(date_i - date_0)/365}}

Syntax

Arguments

  • rate — The discount rate to apply. Type: Float64.
  • cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Must contain at least one positive and one negative value. Type: Array of numeric values (Int8, Int16, Int32, Int64, Float32, Float64).
  • dates — Array of dates corresponding to each cash flow. Must have the same size as cashflows array. Type: Array of Date or Date32.
  • daycount — Optional day count convention. Supported values:
    • 'ACT_365F' (default) — Actual/365 Fixed
    • 'ACT_365_25' — Actual/365.25

Returned value

  • Returns the net present value as a Float64 value.

Examples

Basic usage:

Using different day count convention:

financialNetPresentValue​

Calculates the Net Present Value (NPV) of a series of cash flows assuming equal time intervals between each cash flow.

Default variant:

∑i=0N−1valuesi(1+rate)i\sum_{i=0}^{N-1} \frac{values_i}{(1 + rate)^i}

Variant with start_from_zero set to False (Excel style):

∑i=1Nvaluesi(1+rate)i\sum_{i=1}^{N} \frac{values_i}{(1 + rate)^i}

Syntax

Arguments

  • rate — The discount rate to apply. Type: Float64.
  • cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Type: Array of numeric values (Int8, Int16, Int32, Int64, Float32, Float64).
  • start_from_zero — Optional boolean parameter indicating whether to start the NPV calculation from period 0 (true) or period 1 (false). Default: true.

Returned value

  • Returns the net present value as a Float64 value.

Examples

Basic usage:

With start_from_zero = false (Excel compatibility mode):

Notes

  • When start_from_zero = true, the first cash flow is discounted by (1 + rate)^0, which equals 1
  • When start_from_zero = false, the first cash flow is discounted by (1 + rate)^1, matching Excel's NPV function behavior

financialInternalRateOfReturn​

Introduced in: v25.7

Calculates the Internal Rate of Return (IRR) for a series of cash flows occurring at regular intervals. IRR is the discount rate at which the Net Present Value (NPV) equals zero.

IRR attempts to solve the following equation:

∑i=0ncashflowi(1+irr)i=0\sum_{i=0}^n \frac{cashflow_i}{(1 + irr)^i} = 0

Syntax

Arguments

  • cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Array(Int8/16/32/64) or Array(Float*)
  • [, guess] — Optional initial guess (constant value) for the internal rate of return (default 0.1). Float*

Returned value

Returns the internal rate of return or NaN if the calculation cannot converge, input array is empty or has only one element, all cash flows are zero, or other calculation errors occur. Float64

Examples

simple_example

simple_example_with_guess

financialInternalRateOfReturnExtended​

Introduced in: v25.7

Calculates the Extended Internal Rate of Return (XIRR) for a series of cash flows occurring at irregular intervals. XIRR is the discount rate at which the net present value (NPV) of all cash flows equals zero.

XIRR attempts to solve the following equation (example for ACT_365F):

∑i=0ncashflowi(1+rate)(datei−date0)/365=0\sum_{i=0}^n \frac{cashflow_i}{(1 + rate)^{(date_i - date_0)/365}} = 0

Arrays should be sorted by date in ascending order. Dates need to be unique.

Syntax

Arguments

  • cashflow — An array of cash flows corresponding to the dates in second param. Array(Int8/16/32/64) or Array(Float*)
  • date — A sorted array of unique dates corresponding to the cash flows. Array(Date) or Array(Date32)
  • [, guess] — Optional. Initial guess (constant value) for the XIRR calculation. Float*
  • [, daycount] — Optional day count convention (default 'ACT_365F'). Supported values:
  • 'ACT_365F' - Actual/365 Fixed: Uses actual number of days between dates divided by 365
  • 'ACT_365_25' - Actual/365.25: Uses actual number of days between dates divided by 365.25 String

Returned value

Returns the XIRR value. If the calculation cannot be performed, it returns NaN. Float64

Examples

simple_example

simple_example_with_guess

simple_example_daycount

financialNetPresentValue​

Introduced in: v25.7

Calculates the Net Present Value (NPV) of a series of cash flows assuming equal time intervals between each cash flow.

Default variant (start_from_zero = true):

∑i=0N−1valuesi(1+rate)i\sum_{i=0}^{N-1} \frac{values_i}{(1 + rate)^i}

Excel-compatible variant (start_from_zero = false):

∑i=1Nvaluesi(1+rate)i\sum_{i=1}^{N} \frac{values_i}{(1 + rate)^i}

Syntax

Arguments

  • rate — The discount rate to apply. Float*
  • cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Array(Int8/16/32/64) or Array(Float*)
  • [, start_from_zero] — Optional boolean parameter indicating whether to start the NPV calculation from period 0 (true) or period 1 (false, Excel-compatible). Default: true. Bool

Returned value

Returns the net present value as a Float64 value. Float64

Examples

default_calculation

excel_compatible_calculation

financialNetPresentValueExtended​

Introduced in: v25.7

Calculates the Extended Net Present Value (XNPV) for a series of cash flows occurring at irregular intervals. XNPV considers the specific timing of each cash flow when calculating present value.

XNPV equation for ACT_365F:

XNPV=∑i=1ncashflowi(1+rate)(datei−date0)/365XNPV=\sum_{i=1}^n \frac{cashflow_i}{(1 + rate)^{(date_i - date_0)/365}}

Arrays should be sorted by date in ascending order. Dates need to be unique.

Syntax

Arguments

  • rate — The discount rate to apply. Float*
  • cashflows — Array of cash flows. Each value represents a payment (negative value) or income (positive value). Must contain at least one positive and one negative value. Array(Int8/16/32/64) or Array(Float*)
  • dates — Array of dates corresponding to each cash flow. Must have the same size as cashflows array. Array(Date) or Array(Date32)
  • [, daycount] — Optional day count convention. Supported values: 'ACT_365F' (default) — Actual/365 Fixed, 'ACT_365_25' — Actual/365.25. String

Returned value

Returns the net present value as a Float64 value. Float64

Examples

Basic usage

Using different day count convention