85 lines
4.7 KiB
Markdown
85 lines
4.7 KiB
Markdown
# Four-Quadrant Balance Sheet Matrix (FQBM)
|
||
|
||
A unified institutional framework for monetary, fiscal, financial, and open-economy dynamics. This codebase implements the full FQBM from the white paper: simulation workbook (eight sheets), Monte Carlo stress engine, differential system model, and empirical regression suite.
|
||
|
||
## Table of contents
|
||
|
||
- [Quick start](#quick-start)
|
||
- [Install](#install)
|
||
- [Run](#run)
|
||
- [Test](#test)
|
||
- [Optional features](#optional-features)
|
||
- [IPSAS compliance](#ipsas-compliance)
|
||
- [Submodule (SWIFT DOT-FIN)](#submodule-swift-dot-fin)
|
||
- [Framework and docs](#framework-and-docs)
|
||
|
||
## Quick start
|
||
|
||
```python
|
||
from fqbm.workbook.runner import run_workbook
|
||
from fqbm.state import FQBMState
|
||
|
||
state = FQBMState(B=100, R=50, C=20, Loans=800, Deposits=700, E_cb=30, E_b=100)
|
||
result = run_workbook(initial_state=state, mc_runs=50, export_path="out.xlsx")
|
||
# Or use a scenario:
|
||
run_workbook(scenario="asia_1997", mc_runs=100, export_path="asia.xlsx")
|
||
```
|
||
|
||
See [docs/USER_GUIDE.md](docs/USER_GUIDE.md) for a full walkthrough.
|
||
|
||
## Install
|
||
|
||
```bash
|
||
cd FOUR-QUADRANT_BALANCE_SHEET_MATRIX
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||
pip install -e .
|
||
```
|
||
|
||
Optional: `pip install pytest` for tests; `pip install streamlit` for the dashboard.
|
||
|
||
## Run
|
||
|
||
- **Workbook (all sheets)**:
|
||
`python -m fqbm.workbook.runner`
|
||
Or from code: `from fqbm.workbook.runner import run_workbook` then `run_workbook(initial_state=..., mc_runs=100, export_path="out.xlsx")`.
|
||
- **Monte Carlo**: `from fqbm.sheets.monte_carlo import run_n_simulations`
|
||
- **Differential model**: `from fqbm.system.differential_model import solve_trajectory, check_stability`
|
||
- **Regressions**: `from fqbm.empirical.regressions import run_inflation_pass_through, run_sovereign_spread, run_capital_flow_sensitivity`
|
||
|
||
## Test
|
||
|
||
```bash
|
||
pytest tests/ -v
|
||
```
|
||
|
||
## Optional features
|
||
|
||
- **Streamlit dashboard**: `pip install streamlit` then `streamlit run scripts/streamlit_dashboard.py`
|
||
- **Historical scenarios (Part XI)**: `run_workbook(scenario="asia_1997")` or `"gfc_2008"`, `"pandemic_2020"`, `"rate_shock_2022"`; `get_case_narrative(name)` for narrative and coded outputs
|
||
- **CBDC / CCP / repo**: `run_workbook(cbdc_params=..., ccp_params=..., shadow_params=...)`; state has `cbdc_liability` after CBDC shift; repo multiplier is in `result["dashboard"]["repo_multiplier"]`
|
||
- **Real data**: `from fqbm.data.pipelines import fetch_fed_h41, fetch_bis_series, fetch_imf_series` (Fed H.4.1, BIS bulk CSV, IMF with optional api_key)
|
||
|
||
## References
|
||
|
||
See [docs/REFERENCES.md](docs/REFERENCES.md) for Chicago Author–Date references and optional weblinks (IPSASB, BIS, IMF, Fed H.4.1).
|
||
|
||
## IPSAS compliance
|
||
|
||
The framework includes an **IPSAS-aligned presentation layer** (IPSAS 1 statement of financial position, IPSAS 24 budget vs actual, and structures for IPSAS 2, 3, 4, 5, 9, 10, 14, 19, 20, 23, 29/41, 38, 46, 48, cash basis, RPG 2, functional/presentation currency). Use `fqbm.ipsas.presentation.statement_of_financial_position(state, entity="central_bank"|"commercial_bank"|"consolidated")`, `budget_vs_actual_structure()`, `budget_actual_from_state(state, budget)`, and other helpers. Excel export adds IPSAS-style sheets when available. See [docs/IPSAS_COMPLIANCE.md](docs/IPSAS_COMPLIANCE.md) and [docs/GAPS_AND_MISSING.md](docs/GAPS_AND_MISSING.md).
|
||
|
||
## Submodule (SWIFT DOT-FIN)
|
||
|
||
This repo includes **SWIFT_DOT-FIN** as a submodule (ledger entries and payloads, creation to transfers). Clone with submodules: `git clone --recurse-submodules <repo>`, or after clone run `git submodule update --init --recursive`. The submodule lives at `SWIFT_DOT-FIN/`. For required components and how DOT-FIN integrates with the matrix ledger (state, quadrants, identities), see [SWIFT_DOT-FIN/COMPONENTS_AND_INTEGRATION.md](SWIFT_DOT-FIN/COMPONENTS_AND_INTEGRATION.md).
|
||
|
||
## Framework and docs
|
||
|
||
- [docs/framework_summary.md](docs/framework_summary.md) — Parts I–XVI and module mapping
|
||
- [docs/WHITE_PAPER.md](docs/WHITE_PAPER.md) — Placeholder for canonical white paper
|
||
- [docs/USER_GUIDE.md](docs/USER_GUIDE.md) — Tutorial and usage
|
||
- [docs/API_REFERENCE.md](docs/API_REFERENCE.md) — Public API
|
||
- [docs/DATA_DICTIONARY.md](docs/DATA_DICTIONARY.md) — State variables, sheet I/O, regression columns
|
||
- [docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md](docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md) — Consolidated gap list and documentation checklist
|
||
- [docs/RECOMMENDATIONS.md](docs/RECOMMENDATIONS.md) — Additional recommendations and suggestions
|
||
- [docs/examples/](docs/examples/README.md) — **Stored example**: due diligence PDF, MT-103, OMNL M1 creation, 15-entity distribution, DOT-FIN/ISO 20022 transmission, and **FQBM → MIFOS/Fineract via API** ([full example doc](docs/examples/TRANSFER_DUE_DILIGENCE_AND_M1_CREATION.md))
|