### Installation

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Install the ExcelFinancialFunctions library using the .NET CLI.

```APIDOC
## Installation

Install the library via NuGet to add Excel-compatible financial calculations to your .NET project.

```bash
dotnet add package ExcelFinancialFunctions
```
```

--------------------------------

### Install ExcelFinancialFunctions NuGet Package

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use the dotnet CLI to add the ExcelFinancialFunctions package to your .NET project.

```bash
dotnet add package ExcelFinancialFunctions
```

--------------------------------

### Build Project with .NET CLI

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/tests/ExcelFinancialFunctions.ConsoleTests/README.md

Builds the ExcelFinancialFunctions project and its console test project. Ensure Excel 2013 or later is installed for Interop tests.

```powershell
PS tests\ExcelFinancialFunctions.ConsoleTests> dotnet build

Microsoft (R) Build Engine version 16.11.0+0538acc04 for .NET
Copyright (C) Microsoft Corporation. All rights reserved.

  ExcelFinancialFunctions -> \src\ExcelFinancialFunctions\bin\Debug\netstandard2.0\ExcelFinancialFunctions.dll
  ExcelFinancialFunctions.ConsoleTests -> \tests\ExcelFinancialFunctions.ConsoleTests\bin\Debug\net48\ExcelFinancialFunctions.ConsoleTests.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:00.75
```

--------------------------------

### Add ExcelFinancialFunctions Package via .NET CLI

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/PackageReadmeFile.md

Use the `dotnet add package` command to include the ExcelFinancialFunctions library in your project. This command fetches and installs the latest version from NuGet.

```powershell
PS> dotnet add package ExcelFinancialFunctions

  Determining projects to restore...
info : Adding PackageReference for package 'ExcelFinancialFunctions' into project 
info :   GET https://api.nuget.org/v3/registration5-gz-semver2/excelfinancialfunctions/index.json
info :   OK https://api.nuget.org/v3/registration5-gz-semver2/excelfinancialfunctions/index.json 69ms
info : Restoring packages for project.csproj...
info : PackageReference for package 'ExcelFinancialFunctions' version '2.4.1' added to file 'project.csproj'.
info : Committing restore...
log  : Restored project.csproj (in 72 ms).
```

--------------------------------

### Dollar Conversion Functions

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Converts between fractional and decimal dollar price notations. Requires the fractional part and the denominator for conversion.

```csharp
using Excel.FinancialFunctions;

// Convert fractional dollar (1 and 2/16) to decimal
double dollarDe = Financial.DollarDe(fractionalDollar: 1.125, fraction: 16.0);
// Returns: 1.78125
```

```csharp
// Convert decimal to fractional notation
double dollarFr = Financial.DollarFr(decimalDollar: 1.125, fraction: 16.0);
// Returns: 1.02 (represents 1 and 2/16)
```

--------------------------------

### Calculate Mortgage Payment in F#

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use the `Financial.Pmt` function to calculate the monthly payment for a mortgage. Ensure correct parameters for interest rate, number of periods, and principal amount.

```fsharp
open System
open Excel.FinancialFunctions

// Calculate mortgage payment
let monthlyPayment =
    Financial.Pmt(0.005, 180., 200000., 0., PaymentDue.EndOfPeriod)
// Returns: -1687.713656
```

--------------------------------

### Calculate Coupon Payment Dates and Day Counts

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Provides functions to determine the number of days, days before settlement, days to next coupon, number of coupons, and specific coupon dates for bond calculations.

```csharp
using System;
using Excel.FinancialFunctions;

DateTime settlement = new DateTime(1984, 3, 4);
DateTime maturity = new DateTime(1990, 4, 5);
Frequency freq = Frequency.Quarterly;
DayCountBasis basis = DayCountBasis.UsPsa30_360;

// Number of days in coupon period containing settlement
double coupDays = Financial.CoupDays(settlement, maturity, freq, basis);
// Returns: 90.0

// Days from beginning of coupon period to settlement
double coupDaysBS = Financial.CoupDaysBS(settlement, maturity, freq, basis);
// Returns: 59.0

// Days from settlement to next coupon date
double coupDaysNC = Financial.CoupDaysNC(settlement, maturity, freq, basis);
// Returns: 31.0

// Number of coupons between settlement and maturity
double coupNum = Financial.CoupNum(settlement, maturity, freq, basis);
// Returns: 25.0

// Next coupon date after settlement
DateTime nextCoupon = Financial.CoupNCD(settlement, maturity, freq, basis);

// Previous coupon date before settlement
DateTime prevCoupon = Financial.CoupPCD(settlement, maturity, freq, basis);
```

--------------------------------

### Discount and Interest Rate Calculations

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates discount rates, interest rates, effective annual rates, and nominal annual rates. Specify the day count basis for accurate calculations.

```csharp
using System;
using Excel.FinancialFunctions;

// Discount rate for a security
double disc = Financial.Disc(
    settlement: new DateTime(2023, 1, 15),
    maturity: new DateTime(2024, 1, 15),
    pr: 95.0,
    redemption: 100.0,
    basis: DayCountBasis.Actual360
);
```

```csharp
// Interest rate for a fully invested security
double intRate = Financial.IntRate(
    settlement: new DateTime(2023, 1, 15),
    maturity: new DateTime(2024, 1, 15),
    investment: 1000.0,
    redemption: 1050.0,
    basis: DayCountBasis.Actual360
);
```

```csharp
// Effective annual interest rate
double effect = Financial.Effect(nominalRate: 0.0525, npery: 4.0);
// Returns: 0.05354266737 (5.35% effective from 5.25% nominal quarterly)
```

```csharp
// Nominal annual interest rate from effective rate
double nominal = Financial.Nominal(effectRate: 0.0535, npery: 4.0);
// Returns: approximately 0.0525
```

--------------------------------

### Calculate Total Payment in C#

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/PackageReadmeFile.md

Employ the `Financial.Pmt` static method to determine the total payment (principal and interest) for a loan. This function requires rate, number of periods, present value, and optionally future value and payment type.

```csharp
using Excel.FinancialFunctions;

Console.WriteLine( Financial.Pmt(rate: 0.005, nper: 180, pv: 200000, fv: 0, typ: PaymentDue.EndOfPeriod) );
// Displays -1687.7136560969248
```

--------------------------------

### Pduration - Periods to Reach Target Value

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the number of periods required for an investment to reach a specified future value at a given interest rate. Requires rate, present value, and future value.

```csharp
using Excel.FinancialFunctions;

// How many periods at 5% to double your money?
double pduration = Financial.Pduration(
    rate: 0.05,     // 5% per period
    pv: 1000,       // Present value
    fv: 2000        // Future value (double)
);
// Returns: approximately 14.2 periods
```

--------------------------------

### Core Enumerations

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Explains the core enumerations used for specifying parameters in financial calculations.

```APIDOC
## Core Enumerations

The library provides several enumerations to specify calculation parameters, matching Excel's options.

```csharp
using Excel.FinancialFunctions;

// PaymentDue - When payments are due
PaymentDue.EndOfPeriod       // 0 - Payments at end of period (default)
PaymentDue.BeginningOfPeriod // 1 - Payments at beginning of period

// DayCountBasis - Day count conventions for bond calculations
DayCountBasis.UsPsa30_360    // 0 - US 30/360
DayCountBasis.ActualActual   // 1 - Actual/Actual
DayCountBasis.Actual360      // 2 - Actual/360
DayCountBasis.Actual365      // 3 - Actual/365
DayCountBasis.Europ30_360    // 4 - European 30/360

// Frequency - Coupon payment frequency
Frequency.Annual     // 1 - Once per year
Frequency.SemiAnnual // 2 - Twice per year
Frequency.Quarterly  // 4 - Four times per year
```
```

--------------------------------

### Use IPmt and Pmt in F#

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/README.md

Call financial functions like IPmt and Pmt using F# syntax, accessing them from the Excel.FinancialFunctions module. Note the use of floating-point literals for numerical arguments.

```fsharp
open Excel.FinancialFunctions

printfn "%f" <| Financial.IPmt (0.005, 53., 180., 200000., 0., PaymentDue.EndOfPeriod) 
// Displays -796.374758

printfn "%f" <| Financial.Pmt (0.005, 180., 200000., 0., PaymentDue.EndOfPeriod) 
// Displays -1687.713656
```

--------------------------------

### Core Enumerations for Financial Calculations

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

These enumerations specify parameters like payment timing and day count conventions, mirroring Excel's options.

```csharp
using Excel.FinancialFunctions;

// PaymentDue - When payments are due
PaymentDue.EndOfPeriod       // 0 - Payments at end of period (default)
PaymentDue.BeginningOfPeriod // 1 - Payments at beginning of period

// DayCountBasis - Day count conventions for bond calculations
DayCountBasis.UsPsa30_360    // 0 - US 30/360
DayCountBasis.ActualActual   // 1 - Actual/Actual
DayCountBasis.Actual360      // 2 - Actual/360
DayCountBasis.Actual365      // 3 - Actual/365
DayCountBasis.Europ30_360    // 4 - European 30/360

// Frequency - Coupon payment frequency
Frequency.Annual     // 1 - Once per year
Frequency.SemiAnnual // 2 - Twice per year
Frequency.Quarterly  // 4 - Four times per year
```

--------------------------------

### Calculate Net Present Value (NPV)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the NPV of an investment using a discount rate and future cash flows. Assumes cash flows occur at the end of each period.

```csharp
using Excel.FinancialFunctions;

// NPV of investment with initial cost and future returns
double npv = Financial.Npv(
    rate: 0.14,                                  // 14% discount rate
    values: new double[] { 1.0, 3.0, 4.0 }       // Cash flows (periods 1, 2, 3)
);
// Returns: 5.90 (approximately)
```

```csharp
// More realistic example: $10,000 investment returning $3,000/year for 5 years
double[] cashFlows = { -10000, 3000, 3000, 3000, 3000, 3000 };
// Note: NPV assumes cash flows at end of periods starting with period 1
// For period 0 cash flow, add it separately
double projectNpv = cashFlows[0] + Financial.Npv(0.10, new double[] { 3000, 3000, 3000, 3000, 3000 });
// Returns: 1372.36 (approximately - positive NPV indicates good investment)
```

--------------------------------

### Calculate Present Value of Investment (Pv)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use Pv to calculate the current worth of a series of future payments, often used to determine loan affordability. Payments should be negative.

```csharp
using Excel.FinancialFunctions;

// How much can you borrow if you can afford $1,500/month at 5% for 30 years?
double presentValue = Financial.Pv(
    rate: 0.05 / 12,                // Monthly rate
    nper: 360,                      // 30 years * 12 months
    pmt: -1500,                     // Monthly payment
    fv: 0,                          // No future value
    typ: PaymentDue.EndOfPeriod
);
// Returns: 279422.43 (approximately - the loan amount you can afford)
```

--------------------------------

### Calculate Total Payment in F#

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/PackageReadmeFile.md

Use the `Financial.Pmt` function in F# to calculate the total periodic payment for a loan. Ensure all required parameters, such as rate, number of periods, and present value, are provided.

```fsharp
open Excel.FinancialFunctions

printfn "%f" <| Financial.Pmt (0.005, 180., 200000., 0., PaymentDue.EndOfPeriod) 
// Displays -1687.713656
```

--------------------------------

### CoupDays Algorithm Discrepancy

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/README.md

Illustrates a difference in the coupDays algorithm where Excel does not strictly adhere to coupDays = coupDaysBS + coupDaysNC. This implementation ensures the equality holds, potentially differing from Excel by +/- one or two days around leap years.

```text
coupDays = coupDaysBS + coupDaysNC.
```

--------------------------------

### Use IPmt and Pmt in C#

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/README.md

Call financial functions like IPmt and Pmt as static methods from the Financial class within the Excel.FinancialFunctions namespace. Ensure correct parameter types, including the PaymentDue enum for payment timing.

```csharp
using Excel.FinancialFunctions;

Console.WriteLine( Financial.IPmt(rate: 0.005, per: 53, nper: 180, pv: 200000, fv: 0, typ: PaymentDue.EndOfPeriod) );
// Displays -796.3747578439793

Console.WriteLine( Financial.Pmt(rate: 0.005, nper: 180, pv: 200000, fv: 0, typ: PaymentDue.EndOfPeriod) );
// Displays -1687.7136560969248
```

--------------------------------

### Calculate Internal Rate of Return (IRR)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the IRR for a series of periodic cash flows. An initial guess can be provided to help convergence.

```csharp
using Excel.FinancialFunctions;

// IRR for investment with initial cost and future returns
double irr = Financial.Irr(
    values: new double[] { -123.0, 12.0, 15.0, 50.0, 200.0 },
    guess: 0.14                     // Initial guess
);
// Returns: 0.260952337 (26.1% annual return)
```

```csharp
// Overload without guess (defaults to 10%)
double irr2 = Financial.Irr(new double[] { -123.0, 12.0, 15.0, 50.0, 200.0 });
// Returns: 0.260952337
```

--------------------------------

### Calculate Net Present Value for Non-Periodic Cash Flows (XNPV)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the NPV for cash flows that occur at irregular intervals. Requires a discount rate and a series of dates corresponding to the cash flows.

```csharp
using System;
using Excel.FinancialFunctions;

// XNPV with irregular dates
double xnpv = Financial.XNpv(
    rate: 0.14,
    values: new double[] { 1.0, 3.0, 4.0 },
    dates: new DateTime[] {
        new DateTime(1970, 3, 2),
        new DateTime(1988, 2, 3),
        new DateTime(1999, 3, 5)
    }
);
// Returns: 1.375214
```

--------------------------------

### ISPmt - Interest Payment (Simple Interest)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the interest paid during a specific period using the simple interest method. Requires rate, period, total periods, and present value.

```csharp
using Excel.FinancialFunctions;

// Interest in period 3 of a 10-period loan
double ispmt = Financial.ISPmt(
    rate: 0.15,     // 15% interest rate
    per: 3.0,       // Period 3
    nper: 10.0,     // Total periods
    pv: 100.0       // Present value
);
// Returns: -10.5
```

--------------------------------

### Calculate Internal Rate of Return (IRR) in F#

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use the `Financial.Irr` function to calculate the internal rate of return for a series of cash flows. Provide an array of cash flows and an initial guess.

```fsharp
// Calculate IRR
let irr = Financial.Irr([| -123.; 12.; 15.; 50.; 200. |], 0.14)
// Returns: 0.260952337
```

--------------------------------

### Calculate Future Value of Investment (Fv)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use Fv to determine the future value of an investment with periodic, constant payments and a constant interest rate. Ensure payments are negative for cash outflow.

```csharp
using Excel.FinancialFunctions;

// Calculate future value after investing $500/month for 10 years at 7% annual return
double futureValue = Financial.Fv(
    rate: 0.07 / 12,                // Monthly rate (7% annual / 12)
    nper: 120,                      // 10 years * 12 months
    pmt: -500,                      // Monthly investment (negative = cash outflow)
    pv: 0,                          // Starting with nothing
    typ: PaymentDue.EndOfPeriod
);
// Returns: 86084.72 (approximately)
```

```csharp
// Future value with initial investment of $10,000
double fvWithInitial = Financial.Fv(0.07/12, 120, -500, -10000, PaymentDue.EndOfPeriod);
// Returns: approximately $106,129
```

--------------------------------

### Calculate Bond Yield in F#

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use the `Financial.Yield` function to calculate the yield of a bond. This requires settlement and maturity dates, coupon rate, price, redemption value, and frequency.

```fsharp
// Calculate bond yield
let bondYield =
    Financial.Yield(
        DateTime(2008, 2, 15),
        DateTime(2016, 11, 15),
        0.0575,
        95.04287,
        100.0,
        Frequency.SemiAnnual,
        DayCountBasis.UsPsa30_360
    )
// Returns: 0.065
```

--------------------------------

### Rri - Rate of Return for Investment Growth

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Returns the equivalent interest rate for the growth of an investment over a specified number of periods. Requires the number of periods, present value, and future value.

```csharp
using Excel.FinancialFunctions;

// What rate turns $1000 into $2000 in 10 periods?
double rri = Financial.Rri(
    nper: 10,       // Number of periods
    pv: 1000,       // Present value
    fv: 2000        // Future value
);
// Returns: approximately 0.0718 (7.18% per period)
```

--------------------------------

### Calculate Principal Payment (PPmt)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the principal portion of a payment for a specific period. This can be used to verify that IPmt + PPmt equals the total Pmt.

```csharp
using Excel.FinancialFunctions;

// Calculate principal portion of payment 53
double principalPayment = Financial.PPmt(
    rate: 0.005,
    per: 53,
    nper: 180,
    pv: 200000,
    fv: 0,
    typ: PaymentDue.EndOfPeriod
);
// Returns: -891.3388982529454

// Verify: IPmt + PPmt should equal Pmt
double totalPayment = Financial.IPmt(0.005, 53, 180, 200000, 0, PaymentDue.EndOfPeriod)
                    + Financial.PPmt(0.005, 53, 180, 200000, 0, PaymentDue.EndOfPeriod);
// Returns: -1687.7136560969248 (equals Pmt result)
```

--------------------------------

### Calculate Extended Net Present Value (XNPV) in F#

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use the `Financial.XNpv` function to calculate the net present value for a schedule of cash flows that occurs at specific times. This function accepts a discount rate, cash flows, and corresponding dates.

```fsharp
// Tuple parameter style also works
let xnpvResult =
    Financial.XNpv(
        0.14,
        [1.; 3.; 4.],
        [DateTime(1970, 3, 2); DateTime(1988, 2, 3); DateTime(1999, 3, 5)]
    )
// Returns: 1.375214
```

--------------------------------

### VDB Depreciation Algorithm Discrepancy

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/README.md

Highlights a discrepancy in the VDB depreciation algorithm where Excel's depreciation for period (0,1) differs from the sum of depreciations for (0,0.5) and (0.5,1). Using '1' (no_switch) as the last parameter in this library ensures expected behavior, unlike Excel's potential deviation.

```text
VDB(100,10,13,0,0.5,1,0) + VDB(100,10,13,0.5,1,1,0) <> VDB(100,10,13,0,1,1,0)
```

--------------------------------

### Run Fast Console Tests with vstest.console.exe

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/tests/ExcelFinancialFunctions.ConsoleTests/README.md

Executes only the 'Fast' category tests using the vstest.console.exe tool. This serves as a smoke test for the console tests.

```powershell
PS \tests\ExcelFinancialFunctions.ConsoleTests> vstest.console.exe bin\Debug\net48\ExcelFinancialFunctions.ConsoleTests.dll --TestCaseFilter:"Category=Fast"

Microsoft (R) Test Execution Command Line Tool Version 16.11.0
Copyright (c) Microsoft Corporation.  All rights reserved.

A total of 1 test files matched the specified pattern.
NUnit Adapter 4.1.0.0: Test execution started
Running selected tests in \tests\ExcelFinancialFunctions.ConsoleTests\bin\Debug\net48\ExcelFinancialFunctions.ConsoleTests.dll
   NUnit3TestExecutor discovered 69 of 69 NUnit test cases using Current Discovery mode, Non-Explicit run
  Passed RunMatrix("IRR") [912 ms]
...
Test Run Successful.
Total tests: 69
     Passed: 69
 Total time: 5.2782 Seconds
```

--------------------------------

### Calculate Interest Payment in F#

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/PackageReadmeFile.md

In F#, call the `Financial.IPmt` function from the `Excel.FinancialFunctions` module to compute the interest payment. Note the use of floating-point literals for numerical arguments.

```fsharp
open Excel.FinancialFunctions

printfn "%f" <| Financial.IPmt (0.005, 53., 180., 200000., 0., PaymentDue.EndOfPeriod) 
// Displays -796.374758
```

--------------------------------

### Pv - Present Value of an Investment

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the present value of an investment - the total amount that a series of future payments is worth now.

```APIDOC
## Pv - Present Value of an Investment

### Description
Calculates the present value of an investment - the total amount that a series of future payments is worth now.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **rate** (double) - Required - The interest rate per period.
- **nper** (int) - Required - The total number of payment periods.
- **pmt** (double) - Required - The payment made each period (must be constant).
- **fv** (double) - Optional - The future value, or a cash balance you want to attain after the last payment is made. Defaults to 0.
- **typ** (PaymentDue) - Optional - When payments are due. Defaults to PaymentDue.EndOfPeriod.

### Request Example
```csharp
// Example usage:
Financial.Pv(rate: 0.05 / 12, nper: 360, pmt: -1500, fv: 0, typ: PaymentDue.EndOfPeriod);
```

### Response
#### Success Response (double)
- Returns the present value of an investment.

#### Response Example
```json
279422.43
```
```

--------------------------------

### Calculate Interest Payment in C#

Source: https://github.com/fsprojects/excelfinancialfunctions/blob/master/PackageReadmeFile.md

Use the `Financial.IPmt` static method from the `Excel.FinancialFunctions` namespace to calculate the interest payment for a loan. Ensure the `PaymentDue` enum is correctly specified.

```csharp
using Excel.FinancialFunctions;

Console.WriteLine( Financial.IPmt(rate: 0.005, per: 53, nper: 180, pv: 200000, fv: 0, typ: PaymentDue.EndOfPeriod) );
// Displays -796.3747578439793
```

--------------------------------

### Calculate Bond Price with Negative Yield

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

An extension method to calculate bond price that allows for negative yields, which is not supported by standard Excel functions.

```csharp
// PriceAllowNegativeYield - Extension for negative yields (not in Excel)
double priceNegYield = Financial.PriceAllowNegativeYield(
    new DateTime(2020, 1, 1),
    new DateTime(2025, 1, 1),
    0.02,
    -0.005,                                 // Negative yield
    100.0,
    Frequency.Annual,
    DayCountBasis.ActualActual
);
```

--------------------------------

### Calculate Modified Internal Rate of Return (MIRR)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the MIRR, considering both the cost of borrowing (finance rate) and the reinvestment rate for positive cash flows.

```csharp
using Excel.FinancialFunctions;

// MIRR with finance rate of 14% and reinvestment rate of 12%
double mirr = Financial.Mirr(
    values: new double[] { -123.0, 12.0, 15.0, 50.0, 200.0 },
    financeRate: 0.14,              // Cost of borrowing
    reinvestRate: 0.12              // Return on reinvested cash
);
// Returns: 0.2409336873 (24.1% - typically lower than IRR)
```

--------------------------------

### Calculate Cumulative Interest Paid (CumIPmt)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use CumIPmt to find the total interest paid on a loan within a specified range of periods. Payments should be negative.

```csharp
using Excel.FinancialFunctions;

// Total interest paid in year 1 (payments 1-12) on a $200,000 loan at 6%
double yearOneInterest = Financial.CumIPmt(
    rate: 0.005,                    // Monthly rate
    nper: 180,                      // Total periods
    pv: 200000,                     // Present value
    startPeriod: 1,                 // Start period
    endPeriod: 12,                  // End period
    typ: PaymentDue.EndOfPeriod
);
// Returns: -11635.23 (approximately - negative indicates payment)
```

```csharp
// Total interest over life of loan
double totalInterest = Financial.CumIPmt(0.005, 180, 200000, 1, 180, PaymentDue.EndOfPeriod);
// Returns: -103788.45 (approximately)
```

--------------------------------

### Calculate Internal Rate of Return for Non-Periodic Cash Flows (XIRR)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the IRR for cash flows that occur at irregular intervals. Requires a series of dates corresponding to the cash flows.

```csharp
using System;
using Excel.FinancialFunctions;

// XIRR for irregular cash flow dates
double xirr = Financial.XIrr(
    values: new double[] { -10000, 2750, 4250, 3250, 2750 },
    dates: new DateTime[] {
        new DateTime(2020, 1, 1),   // Initial investment
        new DateTime(2020, 3, 1),   // First return
        new DateTime(2020, 10, 30), // Second return
        new DateTime(2021, 2, 15),  // Third return
        new DateTime(2021, 4, 1)    // Fourth return
    },
    guess: 0.1
);
// Returns annual rate of return accounting for actual dates
```

```csharp
// Example from tests
double xirr2 = Financial.XIrr(
    new double[] { -177900000.0, 8799805.85 },
    new DateTime[] { new DateTime(2020, 7, 3), new DateTime(2021, 2, 25) }
);
// Returns: -0.990247691899517
```

--------------------------------

### Calculate Periodic Payment (Pmt)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the periodic payment for a loan or investment. Returns a negative value for payments (cash outflows). Use PaymentDue enum for payment timing.

```csharp
using Excel.FinancialFunctions;

// Calculate monthly payment for a $200,000 mortgage at 6% annual interest (0.5% monthly) over 15 years (180 months)
double monthlyPayment = Financial.Pmt(
    rate: 0.005,                    // Monthly interest rate (6% / 12)
    nper: 180,                      // Total number of payments
    pv: 200000,                     // Present value (loan amount)
    fv: 0,                          // Future value (0 for fully paid off loan)
    typ: PaymentDue.EndOfPeriod     // Payments at end of month
);
// Returns: -1687.7136560969248

// Calculate payment with beginning of period payments
double paymentBOP = Financial.Pmt(0.005, 180, 200000, 0, PaymentDue.BeginningOfPeriod);
// Returns: -1679.316573 (slightly less due to earlier payment timing)
```

--------------------------------

### AmorDegrc and AmorLinc Depreciation Methods

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates depreciation using French accounting methods. AmorDegrc uses a coefficient, while AmorLinc is linear and prorated. Ensure correct date parameters and basis for accurate results.

```csharp
using System;
using Excel.FinancialFunctions;

// AMORDEGRC - Depreciation with coefficient
double amorDegrc = Financial.AmorDegrc(
    cost: 100.0,
    datePurchased: new DateTime(2014, 1, 1),
    firstPeriod: new DateTime(2016, 1, 1),
    salvage: 50.0,
    period: 1.0,
    rate: 0.3,
    basis: DayCountBasis.ActualActual,
    excelCompliant: true                    // Match Excel's rounding behavior
);
// Returns: 23.0
```

```csharp
// AMORLINC - Linear depreciation (prorated)
double amorLinc = Financial.AmorLinc(
    cost: 100.0,
    datePurchased: new DateTime(2014, 1, 1),
    firstPeriod: new DateTime(2016, 1, 1),
    salvage: 50.0,
    period: 1.0,
    rate: 0.3,
    basis: DayCountBasis.ActualActual
);
```

--------------------------------

### Calculate Number of Periods (NPer)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use NPer to find out how many periods an investment needs to reach a target future value, given a constant payment and interest rate. Payments should be negative.

```csharp
using Excel.FinancialFunctions;

// How many months to pay off $200,000 at 6% with $2,000/month payments?
double periods = Financial.NPer(
    rate: 0.005,                    // Monthly rate (6% / 12)
    pmt: -2000,                     // Monthly payment
    pv: 200000,                     // Loan amount
    fv: 0,                          // Pay off completely
    typ: PaymentDue.EndOfPeriod
);
// Returns: approximately 139 months (11.6 years)
```

--------------------------------

### Calculate Interest Payment (IPmt)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the interest portion of a payment for a specific period within an amortization schedule. Ensure correct rate, period, and total periods are provided.

```csharp
using Excel.FinancialFunctions;

// Calculate interest portion of payment 53 for the same mortgage
double interestPayment = Financial.IPmt(
    rate: 0.005,                    // Monthly interest rate
    per: 53,                        // Period number (53rd payment)
    nper: 180,                      // Total number of payments
    pv: 200000,                     // Present value
    fv: 0,                          // Future value
    typ: PaymentDue.EndOfPeriod
);
// Returns: -796.3747578439793

// Calculate interest for first payment (highest interest portion)
double firstInterest = Financial.IPmt(0.005, 1, 180, 200000, 0, PaymentDue.EndOfPeriod);
// Returns: -1000.0 (0.5% of $200,000)
```

--------------------------------

### Calculate Interest Rate per Period (Rate)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use Rate to determine the interest rate per period for an annuity, which requires iterative calculation. An initial guess can improve performance.

```csharp
using Excel.FinancialFunctions;

// What interest rate gives $200,000 loan, $1,687.71 payment, 180 periods?
double rate = Financial.Rate(
    nper: 180,                      // Number of periods
    pmt: -1687.71,                  // Payment per period
    pv: 200000,                     // Present value
    fv: 0,                          // Future value
    typ: PaymentDue.EndOfPeriod,
    guess: 0.1                      // Initial guess (10%)
);
// Returns: 0.005 (0.5% monthly = 6% annual)
```

```csharp
// Overload without guess (defaults to 10%)
double rate2 = Financial.Rate(180, -1687.71, 200000, 0, PaymentDue.EndOfPeriod);
// Returns: 0.005
```

--------------------------------

### Calculate Future Value with Variable Interest Rates (FvSchedule)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the future value of a principal amount after applying a series of compound interest rates over multiple periods.

```csharp
using Excel.FinancialFunctions;

// FV with varying annual interest rates
double fvSchedule = Financial.FvSchedule(
    principal: 100.0,
    schedule: new double[] { 0.13, 0.14, -0.20, 0.34, -0.12 }  // 5 years of rates
);
// Returns: 121.5236352
```

--------------------------------

### Calculate Bond Price

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the price per $100 face value of a security with periodic interest payments. Use for standard bond valuation.

```csharp
using System;
using Excel.FinancialFunctions;

// Calculate bond price given yield
double price = Financial.Price(
    settlement: new DateTime(2008, 2, 15),
    maturity: new DateTime(2016, 11, 15),
    rate: 0.0575,                           // Coupon rate
    yld: 0.065,                             // Desired yield
    redemption: 100.0,
    frequency: Frequency.SemiAnnual,
    basis: DayCountBasis.UsPsa30_360
);
// Returns: 95.04287 (price per $100 face value)
```

--------------------------------

### Calculate Cumulative Principal Paid (CumPrinc)

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Use CumPrinc to determine the total principal paid on a loan within a specified range of periods. The result is negative, indicating a payment.

```csharp
using Excel.FinancialFunctions;

// Principal paid in year 1 on a $200,000 loan at 6% over 15 years
double yearOnePrincipal = Financial.CumPrinc(
    rate: 0.005,
    nper: 180,
    pv: 200000,
    startPeriod: 1,
    endPeriod: 12,
    typ: PaymentDue.EndOfPeriod
);
// Returns: -8617.33 (approximately)
```

--------------------------------

### YearFrac - Fraction of Year Between Dates

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the fraction of a year represented by the number of days between two dates, based on a specified day count basis.

```csharp
using System;
using Excel.FinancialFunctions;

// Fraction of year between two dates
double yearFrac = Financial.YearFrac(
    startDate: new DateTime(2023, 1, 1),
    endDate: new DateTime(2023, 7, 1),
    basis: DayCountBasis.Actual365
);
// Returns: approximately 0.4932 (about half a year)
```

--------------------------------

### Treasury Bill Calculations

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Functions for U.S. Treasury bill calculations. Requires settlement and maturity dates. The discount rate is crucial for yield and price calculations.

```csharp
using System;
using Excel.FinancialFunctions;

DateTime settlement = new DateTime(2023, 1, 15);
DateTime maturity = new DateTime(2023, 7, 15);

// Bond-equivalent yield for a T-bill
double tbillEq = Financial.TBillEq(settlement, maturity, discount: 0.045);
```

```csharp
// Price per $100 face value
double tbillPrice = Financial.TBillPrice(settlement, maturity, discount: 0.045);
```

```csharp
// Yield for a T-bill
double tbillYield = Financial.TBillYield(settlement, maturity, pr: 97.5);
```

--------------------------------

### Fv - Future Value of an Investment

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the future value of an investment based on periodic, constant payments and a constant interest rate.

```APIDOC
## Fv - Future Value of an Investment

### Description
Calculates the future value of an investment based on periodic, constant payments and a constant interest rate.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **rate** (double) - Required - The interest rate per period.
- **nper** (int) - Required - The total number of payment periods.
- **pmt** (double) - Required - The payment made each period (must be constant).
- **pv** (double) - Optional - The present value, or the lump-sum amount that a series of future payments is worth right now. Defaults to 0.
- **typ** (PaymentDue) - Optional - When payments are due. Defaults to PaymentDue.EndOfPeriod.

### Request Example
```csharp
// Example usage:
Financial.Fv(rate: 0.07 / 12, nper: 120, pmt: -500, pv: 0, typ: PaymentDue.EndOfPeriod);
```

### Response
#### Success Response (double)
- Returns the future value of an investment.

#### Response Example
```json
86084.72
```
```

--------------------------------

### Pmt - Periodic Payment for an Annuity

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the periodic payment for a loan or investment.

```APIDOC
## Pmt - Periodic Payment for an Annuity

Calculates the periodic payment for a loan or investment based on constant payments and a constant interest rate. Returns a negative value for payments (cash outflows).

```csharp
using Excel.FinancialFunctions;

// Calculate monthly payment for a $200,000 mortgage at 6% annual interest (0.5% monthly) over 15 years (180 months)
double monthlyPayment = Financial.Pmt(
    rate: 0.005,                    // Monthly interest rate (6% / 12)
    nper: 180,                      // Total number of payments
    pv: 200000,                     // Present value (loan amount)
    fv: 0,                          // Future value (0 for fully paid off loan)
    typ: PaymentDue.EndOfPeriod     // Payments at end of month
);
// Returns: -1687.7136560969248

// Calculate payment with beginning of period payments
double paymentBOP = Financial.Pmt(0.005, 180, 200000, 0, PaymentDue.BeginningOfPeriod);
// Returns: -1679.316573 (slightly less due to earlier payment timing)
```
```

--------------------------------

### CumIPmt - Cumulative Interest Paid

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the cumulative interest paid on a loan between two periods.

```APIDOC
## CumIPmt - Cumulative Interest Paid

### Description
Calculates the cumulative interest paid on a loan between two periods.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **rate** (double) - Required - The interest rate per period.
- **nper** (int) - Required - The total number of payment periods.
- **pv** (double) - Required - The present value.
- **startPeriod** (int) - Required - The first period in the calculation.
- **endPeriod** (int) - Required - The last period in the calculation.
- **typ** (PaymentDue) - Optional - When payments are due. Defaults to PaymentDue.EndOfPeriod.

### Request Example
```csharp
// Example usage for year 1 interest:
Financial.CumIPmt(rate: 0.005, nper: 180, pv: 200000, startPeriod: 1, endPeriod: 12, typ: PaymentDue.EndOfPeriod);

// Example usage for total interest:
Financial.CumIPmt(0.005, 180, 200000, 1, 180, PaymentDue.EndOfPeriod);
```

### Response
#### Success Response (double)
- Returns the cumulative interest paid. Negative indicates payment.

#### Response Example
```json
-11635.23
```
```

--------------------------------

### Rate - Interest Rate per Period

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the interest rate per period of an annuity using iterative calculation.

```APIDOC
## Rate - Interest Rate per Period

### Description
Calculates the interest rate per period of an annuity using iterative calculation.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **nper** (int) - Required - The total number of payment periods.
- **pmt** (double) - Required - The payment made each period (must be constant).
- **pv** (double) - Required - The present value.
- **fv** (double) - Optional - The future value. Defaults to 0.
- **typ** (PaymentDue) - Optional - When payments are due. Defaults to PaymentDue.EndOfPeriod.
- **guess** (double) - Optional - Your guess for the rate. Defaults to 0.1 (10%).

### Request Example
```csharp
// Example usage with guess:
Financial.Rate(nper: 180, pmt: -1687.71, pv: 200000, fv: 0, typ: PaymentDue.EndOfPeriod, guess: 0.1);

// Example usage without guess:
Financial.Rate(180, -1687.71, 200000, 0, PaymentDue.EndOfPeriod);
```

### Response
#### Success Response (double)
- Returns the interest rate per period.

#### Response Example
```json
0.005
```
```

--------------------------------

### PPmt - Principal Payment for a Specific Period

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the principal portion of a payment for a specific period.

```APIDOC
## PPmt - Principal Payment for a Specific Period

Calculates the principal portion of a payment for a specific period.

```csharp
using Excel.FinancialFunctions;

// Calculate principal portion of payment 53
double principalPayment = Financial.PPmt(
    rate: 0.005,
    per: 53,
    nper: 180,
    pv: 200000,
    fv: 0,
    typ: PaymentDue.EndOfPeriod
);
// Returns: -891.3388982529454

// Verify: IPmt + PPmt should equal Pmt
double totalPayment = Financial.IPmt(0.005, 53, 180, 200000, 0, PaymentDue.EndOfPeriod)
                    + Financial.PPmt(0.005, 53, 180, 200000, 0, PaymentDue.EndOfPeriod);
// Returns: -1687.7136560969248 (equals Pmt result)
```
```

--------------------------------

### CumPrinc - Cumulative Principal Paid

Source: https://context7.com/fsprojects/excelfinancialfunctions/llms.txt

Calculates the cumulative principal paid on a loan between two periods.

```APIDOC
## CumPrinc - Cumulative Principal Paid

### Description
Calculates the cumulative principal paid on a loan between two periods.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **rate** (double) - Required - The interest rate per period.
- **nper** (int) - Required - The total number of payment periods.
- **pv** (double) - Required - The present value.
- **startPeriod** (int) - Required - The first period in the calculation.
- **endPeriod** (int) - Required - The last period in the calculation.
- **typ** (PaymentDue) - Optional - When payments are due. Defaults to PaymentDue.EndOfPeriod.

### Request Example
```csharp
// Example usage for year 1 principal:
Financial.CumPrinc(rate: 0.005, nper: 180, pv: 200000, startPeriod: 1, endPeriod: 12, typ: PaymentDue.EndOfPeriod);
```

### Response
#### Success Response (double)
- Returns the cumulative principal paid. Negative indicates payment.

#### Response Example
```json
-8617.33
```
```