flywheel-engine

Autonomous Compounding Flywheel Dynamics & Counterfactual Policy Simulator
Solves continuous-time Forrester system dynamics and Monte Carlo Tree Search (MCTS) POMDP planning to optimize non-linear compounding growth loops.

---

Strategic Overview

Traditional growth marketing relies on myopic conversion rate optimizations (CRO) that treat marketing channels as static linear funnels. In complex market environments, greedy paid customer acquisition triggers severe balancing friction: audience fatigue, brand entropy, and steep CAC inflation.

flywheel-engine treats enterprise growth as a continuous-time non-linear dynamical system. By modeling stocks of addressable audience, active customer equity, brand trust manifolds, and ad saturation drag, it integrates forward trajectories using Runge-Kutta 4th Order (RK4) and plans multi-quarter interventions via Monte Carlo Tree Search (MCTS) with Upper Confidence Bounds for Trees (UCT).

---

Core Mathematical Architecture

1. Continuous-Time Forrester System Dynamics

The system state vector $\mathbf{x}(t) = [S_{\text{aud}}, S_{\text{act}}, S_{\text{brand}}, S_{\text{drag}}]^\top$ evolves according to coupled non-linear differential equations:

$$\frac{d S_{\text{aud}}}{dt} = \Phi_{\text{organic}}(S_{\text{act}}, S_{\text{brand}}, u_{\text{viral}}) + \Phi_{\text{paid}}(u_{\text{paid}}, S_{\text{drag}}) - \Phi_{\text{conv}}(S_{\text{aud}}, S_{\text{brand}}) - \delta_{\text{aud}} S_{\text{aud}}$$

$$\frac{d S_{\text{act}}}{dt} = \Phi_{\text{conv}}(S_{\text{aud}}, S_{\text{brand}}) - \Phi_{\text{churn}}(S_{\text{act}}, S_{\text{brand}}, u_{\text{retention}})$$

$$\frac{d S_{\text{brand}}}{dt} = \alpha S_{\text{act}} + \beta u_{\text{brand}} - \gamma S_{\text{brand}}$$

$$\frac{d S_{\text{drag}}}{dt} = \frac{\kappa u_{\text{paid}}^{1.3}}{\ln(1 + S_{\text{brand}})} - \lambda S_{\text{drag}}$$

2. Jacobian Sensitivity & Bottleneck Identification

Evaluates the continuous Jacobian matrix $\mathbf{J}_{ij} = \frac{\partial \dot{x}_i}{\partial x_j}$ via finite differences to locate systemic growth bottlenecks and damping factors.

3. MCTS POMDP Policy Planning

Simulates forward trajectories over multi-quarter horizons using UCT action selection:

$$\text{UCT}(a) = \frac{Q(s, a)}{N(s, a)} + c_{\text{puct}} \sqrt{\frac{\ln N(s)}{1 + N(s, a)}}$$

---

Installation & Quickstart

git clone https://github.com/AAH20/flywheel-engine.git
cd flywheel-engine

Zero third-party dependencies. Runs on pure Python 3.10+ standard library.

from flywheel_engine import SystemDynamicsEngine, SystemState, MCTSGrowthPlanner, CounterfactualSimulator

engine = SystemDynamicsEngine()
state = SystemState(audience=5000.0, active_users=500.0, brand_equity=10.0, cac_drag=0.05)

planner = MCTSGrowthPlanner(engine=engine, horizon_months=6, simulations_per_step=100)
action = planner.plan_next_action(state)
print(f"Optimal strategic policy: {action.value}")

---

Running Test Suite

python3 -m unittest discover -s tests -v

---

License

MIT License. Authored by Ahmed Hassan.