Repository navigation
How It Works
📌 Guide, not policy. The methodology owns the calculation rules and REPOSITORY_STRUCTURE.md the architecture; where this page differs, the repository wins.
What happens between pressing Run SA-CCR and reading Results, which VBA module does what, and how a script can drive the workbook. The formulas themselves are explained in the regulation section: SA-CCR Overview, Replacement Cost and Collateral, Margining and MPOR and Potential Future Exposure.
EAD = alpha × (RC + PFE) alpha = 1.4
PFE = multiplier × AddOn_aggregate
margined netting set: EAD = min(EAD margined, EAD as if unmargined with C = NICA)
Params ─┐
├─► validate ─► trades ─► hedging sets ─► asset-class ─► netting set
NettingSets │ and buckets add-ons EAD
Trades ─┘ │ │
▼ ▼
Checks Results · HedgingSets
(errors, warnings, Buckets · TradeCalc
what-if differences) │
▼
BankNettingSets · BankTrades ─────────────────► Reconciliation · TradeReconciliation
│
▼
Export evidence (CSV)
| # | Step | Where | What happens |
|---|---|---|---|
| 0 | Prepare | M_Main.ExecuteOperation |
Refuse a second operation; capture calculation mode, events and screen updating; withdraw both reconciliations and the output fingerprint; withdraw the input fingerprint and recalculate the workbook (ERR_RECALC_PENDING if it does not finish) |
| 1 | Clear | CORE_Engine.ClearOutputSheets |
Empty the five output tables, also for validation |
| 2 | Layout | ValidateSchema |
Input sheets present; workbook names valid; NettingSets and Trades headers as expected; no parameter listed twice with different values |
| 3 | Load |
LoadParams, LoadSFTable, LoadFXTable, LoadNettingSets
|
Parameters with range checks and defaults; factor and FX tables; netting sets with MPOR and collateral checks, the client-clearing role, and from 1.0.2 the QCCP and retained-VM columns of a CCP set and the INFO line of each CM, CLIENT and CCP set. A failure here stops the run (RESULT=STOPPED) |
| 4 | Classify | ClassifyRun |
REGULATORY or WHAT-IF against CRE52-CRR-2026-10-09, one What-if: warning per difference |
| 5 | Trades | ProcessTrades |
Per row: class and sub-class, amounts in reporting currency, S/E/M/T, delta (with the CRR lambda), hedging set and bucket, supervisory duration, adjusted notional, maturity factors (unmargined and margined), effective notional. From 1.0.2 the settlement type and next reset date (ReadTradeSettlement): M of an STM trade is the time to its reset; and, in a CCP set whose CCP retains VM, each trade's own margined maturity factor (UseTrade). An invalid trade is excluded with all its reasons; economic-trade groups are checked first and a malformed group rejects every leg |
| 6 | Aggregate | ComputeHedgingSets |
Buckets into hedging sets: IR across the three maturity buckets, FX per pair, credit/equity/commodity by the single-factor formula; add-on per asset class, margined and unmargined |
| 7 | Exposure | ComputeNettingSets |
Per netting set, in order: INVALID, INCOMPLETE, NO TRADES, else RC, multiplier, PFE, EAD, and for a margined set the cap; TOTAL row per regime over VALID sets, and from 1.0.2 an INFO line per regime with CCP sets giving their EAD in that total |
| 8 | Write |
WriteBuckets, WriteHedgingSets, WriteChecks, WriteRunInfo
|
Outputs, Checks (or No issues found.), run summary in Results C4 |
| 9 | Fingerprint | CORE_Engine |
A completed run stores the input fingerprint in SACCR_RunInputs; validation never keeps one |
| 10 | Reconcile |
M_Main.ReconcileAfterRun + CORE_Reconcile
|
Bank figures against Results and TradeCalc, when entered; fingerprints SACCR_ReconInputs / SACCR_TradeReconInputs
|
| 11 | Seal outputs | M_Main.RememberRunOutputs |
Output fingerprint in SACCR_RunOutputs, used by Export evidence
|
| 12 | Restore and report | M_Main |
Recalculate the status cells, restore Excel's settings one by one, show the message (withheld netting sets split by regime, #276) or return the result line |
Every regulatory formula — duration, maturity factor, deltas, IR effective
notional, single-factor aggregation, multiplier, replacement cost — is one of
the public SACCR_* functions, which the engine calls (see
Worksheet Functions). If one returns an error value for
inputs the engine had accepted, the run stops with ERR_FORMULA_DOMAIN.
An unexpected error during a run withdraws everything written so far, logs
Run stopped by error N: … on Checks and in C4, and is reported (or raised in
silent mode). Results never mix two runs.
| Module | Folder | Visibility | Role |
|---|---|---|---|
CORE_Config |
src/core/ |
Internal | Sheet names, workbook names of the tables, column numbers, parameter codes, the reference parameter set, result labels, error numbers |
CORE_Engine |
src/core/ |
Internal | Loads and validates the inputs, calculates every trade, hedging set and netting set, writes the output sheets, owns the input fingerprint |
CORE_Util |
src/core/ |
Internal | Value conversions (text, numbers, ISO dates, Booleans), keyed lookups on a VBA Collection, sheet helpers that locate tables through workbook names |
CORE_Export |
src/core/ |
Internal | CSV encoding of the evidence report and its UTF-8 bytes; reads no sheet |
CORE_Reconcile |
src/core/ |
Internal | Comparison of bank figures with Results and TradeCalc; reads no sheet |
SACCR_Formulas |
src/modules/ |
Public API | The ten SACCR_* worksheet functions, listed in docs/PUBLIC_API.txt
|
M_Main |
src/workbook/ |
Workbook glue | Button macros, silent entry points, status-cell functions, reading and writing the reconciliation sheets and the evidence file |
ThisWorkbook, sh*
|
src/workbook/ |
Document modules | Only Option Explicit
|
TEST_* (11 modules) |
tests/modules/ |
Development only | Harness, case runner, generated cases, the suites, TEST_Suite.Test_RunAll, and the benchmark TEST_Benchmark, which is not a suite (#292) |
Everything in src/core/ declares Option Private Module and may change
without notice; only SACCR_Formulas is a supported interface. The
repository records some known deviations of the imported prototype engine:
CORE_Engine and CORE_Util read and write worksheets from src/core,
M_Main is a standard module kept with the workbook glue, and the engine
calls the public formula module. Separating the engine from Excel I/O is
planned in #220
(v1.3.0).
| Entry point | Kind | Shows a message? | Returns / does |
|---|---|---|---|
RunSACCR |
Button macro | Yes | Full run |
ValidateInputs |
Button macro | Yes | Validation only; Checks |
ClearOutputs |
Button macro | No (C4 records the time) | Empties the outputs |
ExportEvidence |
Button macro | Yes (save dialog) | Evidence CSV |
RunSACCR_Silent |
Function | No: messages to the Immediate window, failures raised to the caller | Result line |
ExportEvidence_Silent(filePath) |
Function | No |
RESULT=OK; lines=…; file=… or RESULT=REFUSED; reason=…
|
ResultsStatus() |
Function | No |
CURRENT, EDITED (from 1.0.1), STALE or NONE
|
ResultsStatusText(…), ReconciliationStatusText(…), TradeReconciliationStatusText(…)
|
Worksheet functions | No | The status cells C5 |
RunSACCR_Silent restores its silent flag also when the run raises. The
macros are not part of docs/PUBLIC_API.txt.
For the demonstration portfolio with the bank figures of the reconciliation screenshot, the repository records:
RESULT=OK; operation=run; errors=5; warnings=0; trades_used=62; trades_read=65; economic_trades_used=62; economic_trades_read=65; incomplete=2; total_ead_crr=48595558.4974488; total_ead_bcbs=40784020.3398879; inputs=3B2754CA; run_class=REGULATORY; reconciliation=DONE; trade_reconciliation=NONE; cleanup=PASS
| Key | Meaning |
|---|---|
RESULT |
OK (completed) or STOPPED (inputs could not be loaded; see Checks) |
operation |
run (the silent entry point always runs) |
errors, warnings
|
ERROR and WARNING lines on Checks |
trades_used, trades_read
|
Legs (rows) used and read |
economic_trades_used, economic_trades_read
|
Economic trades, each counted once |
incomplete |
Netting sets whose EAD was withheld (INVALID or INCOMPLETE) |
total_ead_crr, total_ead_bcbs
|
Totals of each regime's VALID sets, 0 when none; never added together. Numbers always use a decimal point |
inputs |
Input fingerprint, as in Results C4 |
run_class |
REGULATORY or WHAT-IF
|
reconciliation, trade_reconciliation
|
DONE, NONE, FAILED or UNAVAILABLE
|
cleanup |
PASS when Excel's settings were restored; in silent mode a cleanup failure raises ERR_CLEANUP_FAILED with the line in its description |
With the template's empty bank sheets, a fresh run reports
reconciliation=NONE. The fingerprint is that of a workbook built from the
1.0.2 template, whose input headers it covers; the 1.0.1 release workbook gave
7B68D18F for the same inputs and totals.
Errors raised by the workbook macros are in the project range
vbObjectError + 2048 to + 4095. A button macro shows them as
Unexpected error <number>: <description> (except the two marked †, shown
by their description alone); RunSACCR_Silent raises them unchanged.
| Constant | Number | When |
|---|---|---|
ERR_RUN_ACTIVE † |
vbObjectError + 2049 (−2147219455) |
An SA-CCR operation is already running. |
ERR_CLEANUP_FAILED |
+ 2050 (−2147219454) |
Excel settings could not be restored (silent mode) |
ERR_CHECKS_WRITE † |
+ 2053 (−2147219451) |
The Checks sheet could not be written; results withdrawn |
ERR_PARAMS_LAYOUT |
+ 2054 (−2147219450) |
A Params, bank-setting or table name is missing or broken, so no fingerprint can be taken |
ERR_FORMULA_DOMAIN |
+ 2055 (−2147219449) |
A SACCR_* function returned an error for inputs the engine had accepted |
ERR_RECALC_PENDING |
+ 2056 (−2147219448) |
Excel did not finish recalculating the inputs, so the operation was not started and the previous results are no longer reported as current. |
ERR_EXPORT_WRITE |
+ 2057 (−2147219447) |
An older evidence file of that name could not be replaced whole |
ERR_OUTPUT_LAYOUT |
+ 2058 (−2147219446) |
Workbook name '…_Header' is missing or no longer refers to the first header cell, in column C, of … - rebuild the workbook from the template. |
ERR_INJECTED_FAULT (+ 2051) and ERR_TEST_SETUP (+ 2052) belong to the test
seams and the test runner. Invalid inputs are not VBA errors: they are
Checks lines. What to do about each is on Troubleshooting.
- Outputs and Statuses · Reconciliation and Evidence
- Worksheet Functions — the formula building blocks
- Test Catalogue — the suites that exercise these paths
- Regulation: SA-CCR Overview · Potential Future Exposure · Basel vs CRR
- Troubleshooting · Home