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
• Install
• Run
• Test
• Optional features
• IPSAS compliance
• Submodule (SWIFT DOT-FIN)
• Framework and docs

Quick start

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 for a full walkthrough.

Install

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

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 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 and 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.

Framework and docs

• docs/framework_summary.md — Parts I–XVI and module mapping
• docs/WHITE_PAPER.md — Placeholder for canonical white paper
• docs/USER_GUIDE.md — Tutorial and usage
• docs/API_REFERENCE.md — Public API
• docs/DATA_DICTIONARY.md — State variables, sheet I/O, regression columns
• docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md — Consolidated gap list and documentation checklist
• docs/RECOMMENDATIONS.md — Additional recommendations and suggestions
• docs/examples/ — 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)