BU Object Interface¶
Phase 4, modeling-technique addendum (draft for review). Each BUFM is not just a document — it is a software object with a well-defined manipulation interface, in the OOP sense. This is where our system-architecture expertise (APIs, MCP, DIRAC) shapes the modeling technique.
The class analogy¶
| OOP concept | BU model equivalent |
|---|---|
| Class | one BUFM (RIDER, BCS, SNS, EPS, …) |
| Constructor | load parameter set (market profile) |
| Setters | set parameters, inject inputs |
| Internal methods | economic computation functions |
| Instance state | persisted simulation state (mutable, incremental) |
| Getters | inquiries (ROI, breakeven, cashflow…) |
The computation contract for every internal function:
{parameters, inputs} => {states}
Parameters and inputs go in; state transitions come out. No hidden globals, no reading outside the object boundary except through declared inputs.
Interface surface (three groups)¶
1. Parameters¶
- Environment variables — tax rates, FX, grid tariff: set once per market profile, rarely mutated
- Assumptions — service level, failure rates, cycle life: set per scenario, stress-tested
- Inputs — demand rates, swap volumes per period: injected as the simulation runs
2. State¶
- The BU object persists between manipulations: previous parameter sets, injected inputs, and computed periods remain in the object.
- A simulation is a sequence of incremental manipulations:
set params → inject inputs → advance period → query— repeated across the horizon. - State persistence is what makes incremental what-if analysis cheap: change one assumption, advance, re-query — without rebuilding the world.
3. Inquiries (the standard question set)¶
Every BU object must answer the same core questions, so cross-BU comparison is mechanical:
| Inquiry | Answers |
|---|---|
| RoI | IRR, EBITDA, NPV |
| Breakeven | time-to-breakeven (months), break-even utilization where applicable |
| Cashflow | period cashflow profile across the horizon |
Each BU extends the core with unit-specific queries (RIDER: TCO vs ICE; BCS: LCOB, residual value; SNS: break-even utilization, margin/swap; EPS: anchor-load value).
API / MCP exposure¶
Because every BU object has this uniform interface, each maps naturally onto an API or MCP tool surface:
set_parameters(group, values)apply_inputs(period, values)advance(period)— run internal computationsquery(inquiry)— core + unit-specific
This is the modeling-side contract for the DIRAC/DIRAC-adjacent tooling: a BU class is a service with typed setters and typed queries, not a spreadsheet. It also makes the Phase 5 engine and sensitivity harness straightforward: the harness is just scripted sequences of setter/advance/query calls.
Connection to testing¶
The standard inquiry set doubles as the unit-test assertion surface: each test builds a BU object, applies a scenario, and asserts on query outputs. Object boundary = test boundary.
Presentation¶
Every BUFM renders as a uniform single-page dashboard (inputs/outputs top row, intermediaries second, environment third) — see the BU Dashboard Standard.
Next step (4.4): map Maxwell v12 onto the BU catalog + transaction map — line-by-line provenance, adopt/contrast/reject table.