FOUR-QUADRANT_BALANCE_SHEET_MATRIX/README.md

# 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))