The Mathematics of Compound Interest, Continuous Capital Accumulation & FIRE Velocity

/**
 * Quantitative Financial Engineering & Compound Interest Engine
 * Implements discrete compounding, ordinary annuities, and continuous limits.
 */
export interface InvestmentScheduleInput {
  initialPrincipal: number;     // Starting capital ($)
  monthlyContribution: number;  // Periodic monthly cash injection ($)
  annualNominalRate: number;    // Annual interest rate (e.g. 0.08 for 8%)
  compoundingFrequency: number; // 1 = Annual, 12 = Monthly, 365 = Daily
  durationYears: number;        // Elapsed time in years
  annualInflationRate: number;  // Expected inflation rate (e.g. 0.025 for 2.5%)
}

export interface YearMilestone {
  year: number;
  nominalBalance: number;
  realPurchasingPower: number;
  totalContributions: number;
  totalInterestEarned: number;
}

export interface PortfolioSimulationOutput {
  nominalEndingBalance: number;
  realEndingBalance: number;
  totalContributed: number;
  totalCompoundReturn: number;
  compoundInterestPercentage: number;
  milestones: YearMilestone[];
}

export class FinancialCalculatorEngine {
  public static simulate(input: InvestmentScheduleInput): PortfolioSimulationOutput {
    const {
      initialPrincipal,
      monthlyContribution,
      annualNominalRate,
      compoundingFrequency,
      durationYears,
      annualInflationRate
    } = input;

    const milestones: YearMilestone[] = [];
    let currentBalance = initialPrincipal;
    let totalContributed = initialPrincipal;

    const r = annualNominalRate;
    const n = compoundingFrequency;
    const ratePerPeriod = r / n;

    // Monthly contribution logic synced to compounding periods
    const periodsPerMonth = n / 12;

    for (let year = 1; year <= durationYears; year++) {
      for (let month = 1; month <= 12; month++) {
        // Add monthly contribution
        currentBalance += monthlyContribution;
        totalContributed += monthlyContribution;

        // Apply compounding periods within the month
        for (let p = 0; p < periodsPerMonth; p++) {
          currentBalance *= (1 + ratePerPeriod);
        }
      }

      // Calculate real balance using Fisher inflation equation
      const cumulativeInflationFactor = Math.pow(1 + annualInflationRate, year);
      const realBalance = currentBalance / cumulativeInflationFactor;
      const totalInterestEarned = currentBalance - totalContributed;

      milestones.push({
        year,
        nominalBalance: Math.round(currentBalance * 100) / 100,
        realPurchasingPower: Math.round(realBalance * 100) / 100,
        totalContributions: Math.round(totalContributed * 100) / 100,
        totalInterestEarned: Math.round(totalInterestEarned * 100) / 100
      });
    }

    const nominalEndingBalance = Math.round(currentBalance * 100) / 100;
    const realEndingBalance = milestones[milestones.length - 1].realPurchasingPower;
    const totalCompoundReturn = Math.round((nominalEndingBalance - totalContributed) * 100) / 100;
    const compoundInterestPercentage = Math.round((totalCompoundReturn / nominalEndingBalance) * 10000) / 100;

    return {
      nominalEndingBalance,
      realEndingBalance,
      totalContributed: Math.round(totalContributed * 100) / 100,
      totalCompoundReturn,
      compoundInterestPercentage,
      milestones
    };
  }

  /**
   * Continuous Compounding Limit (Bernoulli Limit)
   */
  public static calculateContinuous(principal: number, annualRate: number, years: number): number {
    return Math.round(principal * Math.exp(annualRate * years) * 100) / 100;
  }
}