Every number on this page is derived directly from the FINCO production engine. Formulas link to their exact source files. Run corpus verification →

FINCO Protocol / Model Methodology

How the FINCO financial model calculates every number.

A project-finance professional can read this document, trace every formula to its exact production source file, and reproduce the output for the Generic Solar Reference model using only the parameters listed here.

SEMESTRIAL periods DSCR-sculpted debt Unlevered Project IRR Newton–Raphson XIRR 25% corporate tax Solar / Wind / Data Center / EV Charging

Introduction

Model scope and design principles.

The FINCO financial engine is a deterministic, pure-Python project-finance model for infrastructure and renewable-energy assets. It covers four calculation phases:

  1. Phase 2A — Operating model: Revenue, OPEX, EBITDA, depreciation.
  2. Phase 2B — Tax + CFADS: Phase 2A plus annual corporate tax and canonical CFADS.
  3. Phase 2C — Senior debt: Phase 2B plus DSCR-sculpted debt sizing.
  4. Returns: Project IRR (unlevered), Equity IRR, Sponsor XIRR, MOIC.

Each phase builds strictly on the one before it. Financial economics are never changed to make methodology easier to explain; this document traces every formula to the production authority.

Reading this document. Orange boxes quote the exact formula from production source code. Each formula carries a source-file authority tag. The Verify route runs a deterministic corpus check against the same source at any time.

Temporal framework

Period convention: SEMESTRIAL.

The engine divides time into semiannual (6-month) periods. Each operating year is represented by exactly two periods (H1 and H2). Construction years may use the same grid.

# finco_core/engine/period_engine.py PeriodFrequency.SEMESTRIAL # = 2 periods per year # Day fraction — two conventions in use: day_fraction_ops = days_in_period / 365 # ACT/365 inclusive — revenue, OPEX, generation day_fraction_debt = days_in_period / 360 # ACT/360 exclusive — senior interest only # Operating period count: operating_period_count = horizon_years × 2 # (2 per year)
finco_core/engine/period_engine.py

Period indexing

Under the default COD_ANCHOR_TWO_CONSTRUCTION_COLUMNS convention, indices 0 and 1 are construction columns; operating periods start at index 2. Each period carries: start_date, end_date, year_index (1-based operating year), period_in_year (1 = H1, 2 = H2), and day_fraction.

COD stub roll: if COD falls within 7 days before a semiannual boundary, the first operating period snaps to that boundary.


Capital expenditure

CAPEX structure.

CAPEX is the sum of all hard and soft development costs incurred during the construction phase. The engine uses a bottom-up taxonomy of named line items, each with an asset class and (optionally) a spending profile across construction periods.

# finco_core/inputs/_models.py total_capex_before_idc = ( hard_capex_keur + commitment_fees_keur + bank_fees_keur + other_financial_keur + vat_costs_keur + reserve_accounts_keur ) total_capex = total_capex_before_idc + idc_keur
finco_core/inputs/_models.py

Hard CAPEX line items include: Production Units (solar modules / wind turbines), EPC Contract, Grid Connection, Civil Works, Soft Costs, Owner's Engineering, Commissioning, Audit & Legal, Contingencies, Insurance, Lease & Tax, Project Acquisition, Project Rights.

Each line item carries a spending_profile tuple defining how costs are distributed across construction sub-periods. Interest During Construction (IDC) and bank fees are zeroed in the generic factory path; they are available as explicit inputs for project-specific models.


Revenue

Generation and revenue calculation.

Revenue is calculated bottom-up from physical generation, then split between PPA-contracted and merchant volumes.

# finco_core/revenue/generation.py # Physical generation per period: generation_mwh = ( capacity_mw × operating_hours_p50 × day_fraction × (plant_availability × grid_availability) × (1 − pv_degradation) ^ (year_index − 1) ) # Revenue split: ppa_mwh = generation_mwh × ppa_share merchant_mwh = generation_mwh − ppa_mwh energy_revenue_keur = ( ppa_mwh × ppa_tariff + merchant_mwh × market_price ) / 1000 # CO₂ revenue (if enabled): co2_revenue_keur = generation_mwh × co2_eur_mwh / 1000 # Balancing cost deduction: balancing_cost_keur = ( gross_merchant_revenue_keur × balancing_cost_pv + generation_mwh × balancing_eur_mwh / 1000 ) revenue_keur = energy_revenue_keur − balancing_cost_keur + co2_revenue_keur
finco_core/revenue/generation.py

For the Generic Solar Reference model, ppa_share = 1.0 for the first 10 PPA years (all generation contracted); thereafter the full volume switches to merchant pricing. PV degradation compounds annually.


Operating costs

OPEX projection.

Each OPEX line item has a Year 1 amount and an annual escalation rate. The schedule applies period-level day-fractions so that H1 and H2 periods receive their proportional share of annual cost.

# finco_core/opex/projections.py # Annual amount at year y: opex_year_v = y1_amount_keur × (1 + annual_inflation) ^ (year_index − 1) # Period amount: opex_period = opex_year_v × day_fraction
finco_core/opex/projections.py

Step changes are supported: when a step change is defined for a given year, the new level becomes the permanent base from that year forward (sustained, not one-off).


Earnings before interest, tax, depreciation & amortisation

EBITDA formula.

# finco_core/ebitda.py — single line, no adjustments ebitda_keur = revenue_keur − opex_keur
finco_core/ebitda.py

EBITDA at this layer carries no financing income, no depreciation add-back, and no non-cash adjustments. It is computed once per period by calculate_ebitda_keur() and re-used by every downstream calculation — tax, CFADS, DSCR, LLCR.


Corporate income tax

Tax calculation.

The engine computes corporate tax on an annual basis (calendar tax year), then distributes cash payment to the H2 period of the tax year. This produces the "clean cash tax timing" pattern used by the Solar and Wind reference models.

# finco_core/tax/engine.py # Taxable income per period: taxable_profit = ( EBITDA − tax_depreciation − deductible_interest # SHL + senior (subject to ATAD cap) + fiscal_reintegration − loss_carryforward_used ) # Tax liability: tax_liability = max(0, taxable_profit × corporate_rate) # ATAD interest limitation (EU anti-avoidance): atad_deductible_interest = max(ebitda × 0.30, 3_000.0) # kEUR floor # Loss carryforward: FIFO queue, max 5 years, 100% utilisation cap # Cash payment: H2 periods only (period_in_year == 2)
finco_core/tax/engine.py
Tax parameterSolar Reference valueAuthority
Corporate rate25.0%TaxParams.corporate_rate
Loss carryforward years5 yearsTaxParams.loss_carryforward_years
Utilisation cap100%TaxParams.loss_carryforward_cap
ATAD EBITDA limit30%TaxParams.atad_ebitda_limit
ATAD minimum interest3,000 kEURTaxParams.atad_min_interest_keur
Tax depreciation modeBook-based percentageBOOK_BASED_PERCENTAGE
Tax dep. book basis %100%tax_deductible_book_dep_pct

Cash flow available for debt service

CFADS formula.

# financial_engine/cfads.py line 91 — single authoritative location # Phase 2B definition: pre-debt-service, pre-DSRA cfads_keur = ebitda_keur + financing_income_keur − cash_tax_keur
financial_engine/cfads.py:91

calculate_canonical_cfads() is the single authoritative function. No other module in the codebase re-derives CFADS inline — all consumers call this function. For the Solar and Wind reference models, financing_income_keur = 0; the term is reserved for models that earn interest on cash reserve accounts.

CFADS is computed per semiannual period. The construction periods (indices 0 and 1) produce CFADS = 0.


Senior debt sizing

Backward induction + fixed-point iteration.

The senior debt size is determined by one of four sizing modes. For the Solar and Wind reference models, DSCR-sculpted (FLAT_DSCR_SCULPTED) is used; the binding constraint switches to GEARING_CAP when gearing capacity is the tighter limit.

Step 1 — DSCR backward induction

# financial_engine/senior_debt/solver.py:247–260 # Starting condition: closing_maturity = 0 # For t from maturity down to first repayment period: allowed_ds_t = max(0, cfads_t / dscr_target_t) × availability_t opening_t = (closing_t + allowed_ds_t) / (1 + rate_t × day_frac_t) # D = opening at first repayment period = DSCR capacity

Step 2 — Sizing mode selection

# financial_engine/senior_debt/solver.py:785 DSCR_SCULPTED: D = dscr_capacity GEARING_CAP: D = eligible_project_cost × maximum_gearing COMBINED_MINIMUM: D = min(dscr_capacity, gearing_capacity) # binding is lower EXPLICIT: D = schedule provided by caller

Step 3 — Fixed-point iteration

# financial_engine/senior_debt/solver.py # Convergence tested per field: converged = (|Δ| ≤ abs_tol) OR (|Δ| / max(|a|, |b|, 1) ≤ rel_tol) # Fields checked: debt_size, opening, interest, principal, # closing, CFADS, cash_tax # Finalisation sub-loop enforces exact interest/CFADS self-consistency.
financial_engine/senior_debt/solver.py

Forward roll — debt service schedule

# financial_engine/senior_debt/sculpting.py # Interest (rolling balance): interest_t = opening_balance × rate × day_fraction # DSCR-sculpted principal: max_ds_t = max(0, cfads_t / target_dscr) principal_t = max(0, min(max_ds_t − interest_t, balance_t)) # Level-principal alternative (for GEARING_CAP or EXPLICIT sizing modes): level_install = opening_debt / n_repayment_periods # Solar reference: FLAT_DSCR_SCULPTED amortization regardless of binding constraint.
financial_engine/senior_debt/sculpting.py

Coverage ratios

DSCR and LLCR.

# AUTHORITATIVE DSCR — clean engine (financial_engine/senior_debt/sculpting.py): # Used for debt sizing and KPI reporting (base_dscr in senior_debt schedules). dscr = cfads / debt_service # cfads = ebitda + financing_income − cash_tax dscr = None # when debt_service == 0 (no division — not inf) # LLCR — post-sizing, informational (financial_engine/valuation/model.py): llcr_t = Σ[ cfads_s / (1 + all_in_rate)^(s−t+1) for s in remaining_debt_life ] / debt_balance_t
financial_engine/senior_debt/sculpting.py · financial_engine/valuation/model.py
Institutional note — dual DSCR definitions. Two DSCR definitions exist in the codebase:
  1. Authoritative (sizing + covenant reporting): cfads / debt_service — numerator is CFADS (= EBITDA + financing_income − cash_tax). Zero-DS periods: DSCR = None. Source: financial_engine/senior_debt/sculpting.py.
  2. Legacy utility (NOT used for sizing): ebitda / debt_service — numerator is raw EBITDA. Zero-DS periods: returns inf. Source: finco_core/debt/covenants.py::dscr().
The two definitions differ whenever financing_income ≠ 0 or cash_tax ≠ 0. The legacy utility is not called from the production debt sizing or waterfall path. All KPI output uses the authoritative CFADS-based definition.

The lock-up DSCR gate is 1.10 for the Solar reference model: when dscr < 1.10 in any operating period, distributions to equity are blocked. LLCR is defined in the model architecture but is not configured in the Solar reference run (production output: min_llcr = None, status: C2_COVERAGE_CFADS_CASE_NOT_CONFIGURED). LLCR is informational only — it is not a debt sizing constraint.

Sizing vs amortization — important distinction. For the Solar Reference, the binding size constraint is GEARING: the loan amount is capped at 75% × 35,978 (Total Project Uses) = 26,983 kEUR, because the DSCR capacity (36,238 kEUR) exceeds the gearing cap. Once the loan size is set by the gearing cap, the amortization schedule is still determined by DSCR-sculpted repayment (FLAT_DSCR_SCULPTED mode): each period's principal repayment is sized so that CFADS / debt service = target DSCR. Gearing constrains the size; DSCR sculpting determines the shape of repayment.

Debt service reserve account

DSRA mechanics.

# finco_core/waterfall/dsra_engine.py # Initial DSRA (funded at financial close by equity): initial_dsra = (dsra_months / 12) × first_period_payment × periods_per_year # Target DSRA in each period (rolling target): target_dsra = (dsra_months / 12) × current_period_payment × periods_per_year # Top-up from operating cash: top_up = min(available_fcf × 0.5, gap_to_target) # Release: DSRA balance released to distributions in final 2 operating periods.
finco_core/waterfall/dsra_engine.py

The Solar reference model has dsra_months = 6 in its configuration parameter, but the active production mode is dsra_support_mode = DebtServiceReserveSupportMode.NONE. This means: no reserve is funded at financial close, no reserve movements occur in any period, and debt_service_reserve_requirement_keur = 0. The terminal DSRA balance is 0 (status: NOT_APPLICABLE).

In short: the DSRA parameter exists and is configurable, but the Solar reference model intentionally runs without an active reserve. Full DSRA mechanics — initial funding by equity, rolling target top-up from operating cash, and release at maturity — are exercised when dsra_support_mode ≠ NONE in a project-specific model.

TRUST_PACK_SOLAR_DSRA_RUNTIME_RECONCILIATION: Solar Reference production output — dsra_support_mode = NONE, debt_service_reserve_requirement_keur = 0.0, terminal DSRA = 0. Configuration parameter dsra_months = 6 is stored but overridden by the active mode at runtime.

Shareholder loan

SHL schedule and waterfall priority.

# finco_core/waterfall/shl_engine.py gross_interest = shl_balance × shl_rate × day_fraction net_interest = gross_interest × (1 − wht_rate) cash_interest = min(net_interest, available_cash) pik_interest = gross_interest − cash_interest # PIK accretes at gross rate interest_wht = cash_interest × (wht_rate / (1 − wht_rate))
finco_core/waterfall/shl_engine.py

WHT is levied only on the cash-paid interest component, not on PIK accretion. Waterfall priority: SHL ranks junior to senior debt and ahead of equity distributions. The Solar reference model uses CASH_SWEEP repayment mode; SHL principal is swept from post-senior-debt cash after the senior loan reaches full maturity.

Repayment modes available: bullet, cash_sweep, pik, accrued, pik_then_sweep, partial_pay_sweep.


Project return

Project IRR — unlevered definition.

The Project IRR measures the return on the total project investment as if it were financed entirely with equity. It is explicitly unlevered: no senior debt service, no SHL interest, no financing benefits appear in the cash flows.

# financial_engine/project_returns/model.py lines 251–264 # Construction phases: outflows at the date of each CAPEX draw cf_construction[t] = −hard_capex_investment_t # Operating phases: EBITDA minus unlevered cash tax cf_operating[t] = ebitda_t − unlevered_cash_tax_t # Unlevered cash tax (from waterfall_engine.py line 1274): unlevered_cash_tax = tax_rate × max(0, ebitda − depreciation) # Net unlevered cash flow: net_ucf[t] = cf_operating[t] + terminal_component_t − cf_construction[t] # Project IRR = XIRR(net_ucf, dates)
financial_engine/project_returns/model.py
Excluded from Project IRR: explicit financing costs (IDC, bank fees, DSRA funding) are tracked separately in excluded_financing_cost_uses_keur and excluded_reserve_funding_keur and do not enter the unlevered cash flows. Soft costs and development fees that form part of CAPEX are included.

Equity and sponsor returns

Three distinct return metrics.

The engine produces three distinct return metrics. Each uses a different set of cash flows; comparing them directly is meaningful only when their definitions are understood.

1. Project IRR — unlevered

# financial_engine/project_returns/model.py # Authority: C1_UNLEVERED_HARD_CAPEX_PLUS_EBITDA_MINUS_ZERO_FINANCING_INTEREST_CASH_TAX construction_cf[t] = −hard_capex_draw_t operating_cf[t] = ebitda_t − unlevered_tax_t # no debt service project_irr = xirr(construction_cf + operating_cf, dates) # Solar reference: 11.77%

2. Equity IRR — legal equity only (EQUITY_ONLY)

# finco_core/waterfall/waterfall_engine.py # Solar reference equity_irr_method = 'equity_only' initial_outflow = share_capital_contributed_keur # 500 kEUR for Solar ref periodic_cf = equity_distributions_t # post-senior, post-SHL equity_irr = xirr(−initial_outflow + periodic_cf, dates) # Solar reference: 45.95% (leveraged; SHL excluded from this metric)

3. Total Sponsor XIRR — all sponsor cash (equity + SHL)

# financial_engine/sponsor_returns/model.py contributions = share_capital + shl_cash_contributed # 500 + 7,750 = 8,250 kEUR receipts = shl_cash_interest + shl_principal_repaid + equity_distributions total_sponsor_xirr = xirr(−contributions + receipts, dates) # Solar reference: 16.61% (diluted by SHL cost of carry)
finco_core/waterfall/waterfall_engine.py financial_engine/sponsor_returns/model.py financial_engine/project_returns/model.py
MetricPerspectiveSolar ReferenceCash flow basis
Project IRRUnlevered project11.77%CAPEX outflows + EBITDA − unlevered tax
Equity IRRLegal equity only45.95%Share capital contributions & equity distributions
Total Sponsor XIRRAll sponsor cash16.61%Share capital + SHL contributions & all receipts

Return calculation

XIRR date convention.

# finco_core/sponsor/xirr.py # Year fraction = actual calendar days since first cash-flow date / 365 # ACT/365F-style (fixed 365 denominator), not ACT/ACT. Excel XIRR-compatible. year_fractions = [(d − d₀).days / 365.0 for d in dates] # NPV at rate r: npv(r) = Σ[ cf_t / (1 + r)^year_frac_t ] # Newton–Raphson iteration, tolerance = 1×10⁻⁷, max 200 iterations # Fallback: bisection if Newton–Raphson diverges
finco_core/sponsor/xirr.py

XIRR is a pure-Python implementation — no external financial library. robust_xirr() tries Newton–Raphson first; on non-convergence, it falls back to bisection. Both paths are exercised in the regression suite.


Scenario and sensitivity analysis

Built-in scenarios and shock registry.

Scenarios

ScenarioP50 yieldCAPEXOPEXDegradationTariff
Base×1.000×1.000×1.000×1.000×1.000
Downside×0.900×1.050×1.100×1.150×0.950
Upside×1.050×0.970×0.950×0.900×1.030
app/scenarios.py · SCENARIO_RULES

Sensitivities

Default shock levels: ±5%, ±10%, ±15%. Shock variables: capex, opex, ppa_price, merchant_price, yield, availability, interest_rate, tax_rate. Results are displayed as tornado charts in the Model UI.

app/services/sensitivity_service.py · SHOCK_REGISTRY

Engine-reconciled canonical reference values

Generic Solar Reference: 64 MW, 25-year project.

Engine-reconciled canonical reference values. Every number in this section is produced by run_project("Generic Solar Reference", "Base") via the FINCO production runtime path (financial_engine.shareholder_waterfall.run_project_shareholder_waterfall_model, authority: CLEAN_PRODUCTION_READY). Values are stable across runs on the same codebase revision. The project_code = REF-SOLAR-A.

Identity & timeline

ParameterValueAuthority
Reference codeREF-SOLAR-Aproject_factories.py:508
Capacity64 MWcapacity_mw=64.0
Financial close2030-01-01info.financial_close
COD2031-03-01info.cod_date
Construction14 monthsconstruction_months=14
Operating horizon25 yearshorizon_years=25
Period frequencySEMESTRIALPeriodFrequency.SEMESTRIAL
Operating periods5025 × 2

CAPEX breakdown (kEUR)

Line itemAmount (kEUR)Asset class
Solar Modules20,000epc_contract
Civil Works5,000epc_other
Soft Costs3,000audit_legal
Inverters3,000production_units
Grid Connection2,000grid_connection
Total CAPEX33,000515.6 kEUR/MW

OPEX (Year 1)

Line itemY1 amount (kEUR)Inflation
Technical Management1502.0%/yr
Insurance1002.0%/yr
Maintenance802.0%/yr
Lease & Tax502.0%/yr
Total Y1 OPEX3805.9 kEUR/MW

Technical & revenue assumptions

ParameterValue
Operating hours P501,500 hr/yr
Operating hours P90-10yr1,400 hr/yr
Plant availability99.0%
PV degradation0.4%/yr
PPA tariff50.0 EUR/MWh
PPA term10 years
PPA escalation2.0%/yr

Financing structure

ParameterValue
Total Project Uses (33,000 CAPEX + IDC, lender fees, initial DSRA)35,978 kEUR
Senior debt (drawn)26,983 kEUR
Senior gearing75.0%
Binding constraintGEARING (75% cap on Total Project Uses)
DSCR capacity (headroom)36,238 kEUR
Senior tenor15 years
Senior base rate3.0%
Senior margin250 bps
Senior all-in rate5.5%
Target DSCR1.20×
Lock-up DSCR1.10×
DSRA6 months
Shareholder loan7,750 kEUR @ 8.0%
SHL repaymentCash sweep (after senior maturity)
Share capital500 kEUR
Total sponsor equity8,250 kEUR

Engine outputs — Phase 2C base case (P50)

11.77%
Project IRR
Unlevered XIRR
hard CAPEX + EBITDA − unlevered tax
45.95%
Equity IRR
EQUITY_ONLY method
legal equity (500 kEUR) only
16.61%
Total Sponsor XIRR
Share capital + SHL
contributions & receipts
1.25×
Min DSCR
Base CFADS / senior DS
operating periods
147,815
Total EBITDA (kEUR)
25-year cumulative
50 semiannual periods
123,129
Total CFADS (kEUR)
Pre-debt-service
operating periods only
24,686
Total cash tax (kEUR)
Corporate income tax
paid H2 each year

Full operating model summary

LineTotal (kEUR, 25yr)Formula authority
Total Revenue159,925finco_core/revenue/generation.py
Total OPEX12,110finco_core/opex/projections.py
Total EBITDA147,815finco_core/ebitda.py
Total cash tax paid24,686finco_core/tax/engine.py
Total CFADS123,129financial_engine/cfads.py:91

Sources & uses reconciliation

Total project costs (Uses) must equal total funding sources (Sources). For the Solar Reference, Sources and Uses balance at 35,978 kEUR (33,000 CAPEX plus construction-period IDC, commitment and structuring fees, and the initial DSRA funding):

SourcesAmount (kEUR)Basis
Senior debt26,98375.0% × 35,978 (gearing cap on Total Project Uses, binding)
Share capital500FinancingParams.share_capital_keur
Shareholder loan (SHL)8,494Derived residual after senior debt and share capital (no plug: Sources = Uses)
Total Sources35,978= Total Uses (CAPEX 33,000 + IDC 545 + commitment fee 230 + structuring fee 270 + initial DSRA 1,934)

Representative period cash-flow walkthrough

The first operating period (Y2031-H1: 2031-03-01 → 2031-06-30) illustrates how each line in the waterfall connects. Two separate day-count conventions apply in the same period: revenue and OPEX use ACT/365 inclusive (122 calendar days, day fraction = 122/365 = 0.3342); senior interest uses ACT/360 exclusive (121 days, day fraction = 121/360 = 0.3361).

Bank (P90_10Y) case vs Base (P50) case — debt sculpting uses bank CFADS. The engine runs two separate operating-model phases before sizing debt. The base case (P50 yield, 1,500 hr/yr) produces the revenue and CFADS reported in financial statements and KPIs. The bank case (P90_10Y yield, 1,400 hr/yr) is used exclusively to size the DSCR-sculpted principal repayment in each period (derive_debt_sizing_operating_input(), financial_engine/orchestrator.py). Bank revenue = base revenue × (1,400 / 1,500); bank CFADS = bank revenue − OPEX. The sculpted principal therefore equals bank_CFADS / target_DSCR − interest — producing a conservative repayment schedule that the bank case cash flows can always service at exactly the target DSCR.
LineY2031-H1 (kEUR)Formula / authority
Revenue (base, P50)1,572.5capacity × hours_p50 × tariff × day_fracACT/365
OPEX127.0y1_amount × (1+infl)^(yr−1) × day_fracACT/365
EBITDA (base, P50)1,445.4Revenue − OPEX
Cash tax0H1 period — tax cash paid in H2 only
CFADS (base, P50)1,445.4EBITDA + fin. income − cash tax
Revenue (bank, P90_10Y)1,467.61,572.5 × (1,400 / 1,500) — used for debt sculpting only
CFADS (bank, P90_10Y)1,340.61,467.6 − 127.0 — sculpting input, not reported in statements
Senior interest498.826,983 × 5.5% × (121/360) — ACT/360 exclusive day-count
Senior principal618.4bank_CFADS / target_DSCR − interest = 1,340.6 / 1.20 − 498.8
Total senior DS1,117.2interest + principal
Achieved DSCR (P50)1.29×base CFADS / senior DS = 1,445.4 / 1,117.2
Closing senior balance26,365.026,983.3 − 618.4

Target DSCR (1.20×) is the sculpting parameter — it controls how large each principal repayment is relative to bank-case CFADS. Achieved DSCR (1.29× in Y2031-H1) is the runtime ratio of base-case CFADS to actual debt service; it varies by period and exceeds 1.20× whenever base CFADS > bank CFADS (i.e., P50 yield > P90_10Y yield). The minimum achieved DSCR across all operating periods is reported as min_dscr in KPIs (runtime value: 1.25×).

How to reproduce this example. Primary authority: run_project("Generic Solar Reference", "Base") from app.api.project_runner. This returns all KPIs via the CLEAN_PRODUCTION_READY path. Direct-engine alternative: call create_generic_solar_reference() from app.project_factories, then run_project_financing_model(pi) from financial_engine.financing.project. Both paths produce identical economics on the same codebase revision.


Model governance

Working state vs Last Run.

The FINCO workspace maintains two distinct model states that must not be conflated:

  • Working state: the current parameter values in the workspace UI. These may have been edited since the last calculation. The working state is draft; it has not been validated by the engine.
  • Last Run: the frozen engine output produced by the most recent calculation. All published KPIs, schedules, and distributions are bound to Last Run. If the working state has been modified after the last run, the workspace is marked stale; if no run has been performed, it is NOT_RUN.

The Generic Solar Reference canonical model is always in a known Last Run state: its inputs are frozen, its outputs are deterministic, and the results on this page are bound to that Last Run. Any change to working state requires a new engine run before the outputs update.

TRUST_PACK_WORKING_LAST_RUN_CONTRACT: Export and report generation are bound exclusively to Last Run, not to working state. A stale or NOT_RUN workspace cannot produce a verified export.

Reproducibility

Run identity and reproducibility.

Each engine run is identified by a composite set of immutable inputs. Providing the same inputs to the same codebase revision produces bitwise-identical outputs:

Identity axisSolar Reference value
Reference modelGeneric Solar Reference
ScenarioBase
Production authorityCLEAN_PRODUCTION_READY
Engine entry pointfinancial_engine.shareholder_waterfall
Period frequencySEMESTRIAL (2/yr)
Horizon25 years (50 operating periods)
Calculation count1 (clean single-pass)

The engine is deterministic and stateless: there are no random draws, no external data fetches, and no time-dependent values. Re-running the model on the same codebase revision and inputs always produces the same output.

TRUST_PACK_REPRODUCIBILITY_CONTRACT: run_project("Generic Solar Reference", "Base") → Project IRR = 11.77%, Senior debt = 26,983 kEUR, Total Sponsor XIRR = 16.61%. These values are stable and auditable on any build of the current codebase.

D4 — Cash waterfall

Cash waterfall priority order (G2C covenant-gated).

The full G2C covenant-gated waterfall is implemented in financial_engine/shareholder_waterfall/model.py::run_project_shareholder_waterfall_model. Cash is applied in strict priority order each operating period:

#Waterfall stepFormulaSource
1Senior debt serviceCFADS − (interest + principal) = post-senior cashfinancial_engine/senior_debt/sculpting.py
2DSRA top-up / drawcash adjusted for DSRA movements → cash_after_dsra_keurfinancial_engine/dsra/model.py::run_cash_dsra_model
3DSRF commitment feeda_inflow = reserve_adjusted_cash − dsrf_feefinancial_engine/financing/dsrf.py
4Distribution Account rollda_available = da_inflow + da_closing[t−1]financial_engine/shareholder_waterfall/model.py
5Lock-up gate checkGate A: DSCR < lockup_dscr (default 1.10) AND within senior maturity → blockdistribution gate Component A
6SHL cash interestpaid from released DA cash after gatefinancial_engine/shl/
7SHL principalpaid from DA cash after interestfinancial_engine/shl/
8Legal equity distributionmax(0, da_release − shl_interest − shl_principal)financial_engine/shareholder_waterfall/model.py
Distribution gate — five components (G2C). Cash is locked to the Distribution Account (not released to SHL/equity) if ANY gate component fires:
  • A: DSCR < lockup_dscr (default 1.10×) AND within senior maturity — DSCR lockup gate
  • B: construction not complete — construction state gate
  • C: Distribution Account balance < 0 — DA negative gate
  • D: DSRA underfunded (cash gap to target > tolerance) — DSRA top-up gate
  • E: J-DSRA underfunded — always False for single-tranche senior-only projects (j_dsra_closing_keur = 0 hardcoded; not modelled)
DSRF note: DSRF (letter-of-credit reserve facility) has a fee engine but no draw engine (DSRF_AVAILABLE_SUPPORT_ONLY_NO_DRAW_ENGINE). Actual LoC draws are not modelled; gate Component D availability check is based on DSRA cash balance only, not DSRF draw capacity.

BULLET SHL fail-closed: after an unpaid BULLET maturity, all subsequent equity distributions are zeroed and IRR metrics carry ReturnMetricStatus.UNPAID_SHL_AT_CONTRACTUAL_MATURITY.
financial_engine/shareholder_waterfall/model.py

D7 — Statement reconciliation & institutional gaps

Explicit institutional gaps and modelling boundaries.

The following gaps are explicitly documented. They are truthful model boundaries, not defects. A lender or project-finance analyst relying on FINCO outputs should apply independent adjustments for each gap where material.

GapDescriptionImplication
DSCR dual definition Two DSCR definitions exist in the codebase: (1) Clean engine (authoritative): CFADS / senior_DS with None for zero-DS periods. (2) Legacy utility (finco_core/debt/covenants.py): EBITDA / senior_DS with inf for zero-DS. Results differ whenever financing_income ≠ 0 or cash_tax ≠ 0. Lender analysis relying on the covenant utility may see a higher numerator than the engine reports.
XIRR vs periodic IRR FINCO uses true date-aware XIRR (365-day year). Bank models often compute a periodic IRR from semi-annual cash flows then annualise: (1 + r_semi)^2 - 1. These are numerically different. Project IRR in FINCO (11.56% for Solar Reference) is not directly comparable to a periodic-semi-annual IRR × 2. The difference is material for short first periods.
Country-specific interest limitation not modelled Interest deductibility limitation is configured via a model-level ATAD annual calculation (atad_ebitda_limit × EBITDA, floor atad_de_minimis_threshold_keur_annual). This is a configurable financial contract modelled in financial_engine/tax/atad.py::calculate_annual_atad(). Country-specific interest limitation regimes beyond this configured calculation are not implemented. In jurisdictions where local interest limitation rules impose a stricter cap than the configured ATAD parameters, the modelled tax may be understated. FINCO is a pre-feasibility / indicative model, not a tax-filing system.
DSRF: no draw engine DSRF (Debt Service Reserve Facility — letter-of-credit format) has a fee engine but NO draw engine. The reserve support gate uses DSRF_AVAILABLE_SUPPORT_ONLY_NO_DRAW_ENGINE. Actual draws from a LoC are not modelled. DSRF cash availability is overstated if the LoC would be drawn but the model treats the gate as open. For project-specific models using DSRF, the distribution gate Component D (DSRA underfunding) may not fire correctly.
Junior debt not implemented run_project_shareholder_waterfall_model raises ValueError ('G2C_JUNIOR_DEBT_WATERFALL_NOT_IMPLEMENTED') if junior_or_other_project_funding_keur > 0. Mezzanine or junior tranche structures cannot be modelled.
Single currency (kEUR) All monetary values are in kEUR. Multi-currency structures are not in scope for V1. FX exposure, currency swaps, and non-EUR projects require conversion outside the model.
Financial statements not in clean engine The formal balance sheet and cash-flow statement (finco_core/financial_statements/) use WaterfallPeriod objects from the legacy engine path. They are not connected to the clean Phase 2C engine result pipeline. _PHASE_2C_UNAVAILABLE = ('financial_statements', 'returns'). BS/CFS in the export workbook may reflect a different path than the KPIs computed via the clean engine. Reconciliation between KPI outputs and formal financial statements should be treated with care.
Refinancing not modelled Senior debt runs to its contractual maturity. Refinancing is not implemented. Models with a practical refinancing date (e.g., year 7 re-fi of a 15-year loan) cannot capture the lower margin post-re-fi. Project IRR will be understated if a material refinancing benefit is expected.
Canonical last run: no UUID linkage ResolvedExportAuthority.run_id = None for the CANONICAL_LAST_RUN export path. The workspace stores a compact-timestamp last_runtime_snapshot_id, not a UUID run_id. Canonical export provenance cannot be cross-referenced to a RunRecord by UUID. Audit trail linking exported workbook to a specific RunRecord by UUID is not available on the canonical path. The git_sha and input_fingerprint remain traceable.
app/model_methodology_registry.py · INSTITUTIONAL_GAPS (public_visible=True)

Scope and limitations

What this model does and does not cover.

  • Asset classes covered today: Solar PV, Wind (onshore/offshore), Data Center, EV Charging Hub. Storage is in preview (reference workflow only).
  • Currency: All monetary values are in kEUR (thousands of Euros). Multi-currency models are not in scope for V1.
  • Period frequency: SEMESTRIAL only. Annual and quarterly modes exist in the codebase but are not exposed in the current UI.
  • Tax: A single corporate-income-tax jurisdiction is modelled. Transfer pricing, consolidated group tax, or country-specific interest limitation regimes beyond the configured ATAD parameters are not implemented.
  • Merchant price: The engine accepts a user-supplied merchant price curve or a default linear escalation from a base price. No stochastic price simulation is performed.
  • Inflation: Cost items escalate at user-supplied annual rates. The model does not produce real-terms versus nominal-terms comparison.
  • Refinancing: Not modelled. The senior debt schedule runs to its contractual maturity.
  • Distributions waterfall: The full covenant-gated waterfall (DSCR lock-up, DSRA top-up, SHL sweep, equity distribution) is implemented in financial_engine/shareholder_waterfall/model.py.
  • LLCR: Informational only — not a debt sizing constraint. Production output for Solar Reference: min_llcr = None (status: C2_COVERAGE_CFADS_CASE_NOT_CONFIGURED).
  • Excel / XLSX export reconciliation: TRUST_PACK_SOLAR_EXCEL_RECONCILIATION = PASS. The Institutional XLSX Export (P1.2) is delivered. The workbook includes a Returns sheet (Project IRR, Equity IRR, Total Sponsor XIRR), a Run Identity sheet (run_id, project_id, engine version, export timestamp), and a Reconciliation sheet with explicit numeric checks: Sources = Uses, CAPEX detail = total, Revenue detail = runtime total, OPEX exported, Debt service period sum = runtime total, and all three return metrics exported = runtime values within tolerance. All reconciliation checks PASS for the Generic Solar Reference.