catcolab-stock-flow

# CatColab Stock-and-Flow Diagrams: Epidemiology & Ecology **Trit**: +1 (PLUS - generator) **Color**: Orange (#FF8C00) ## Overview Stock-and-Flow diagrams in CatColab model systems with: - **Stocks**: Accumulations (populations, inventories, quantities) - **Flows**: Rates of change between stocks - **Links**: Auxiliary connections influencing flow rates - **Mass-action semantics**: Automatic ODE generation This is the foundation for epidemiological models (SIR), ecological models (Lotka-Volterra), and resource dynamics. ## Mathematical Foundation ``` ┌─────────────────────────────────────────────────────┐ │ STOCK-AND-FLOW DIAGRAM │ ├─────────────────────────────────────────────────────┤ │ Stocks (Accumulations): │ │ [S] Susceptible [I] Infected [R] Recovered │ │ │ │ Flows (Rates): │ │ infection: S → I │ │ recovery: I → R │ │ │ │ Links (Influences): │ │ I ──link──► infection (infected influence rate) │ │ │ │ Diagram: │ │ ┌───┐ infection ┌───┐ recovery ┌───┐ │ │ │ S │ ═══════════► │ I │ ═══════════► │ R │ │ │ └───┘ └───┘ └───┘ │ │ ▲ │ │ │ └────── link ─────┘ │ └─────────────────────────────────────────────────────┘ ``` ## Double Theory ```rust // Stock-Flow double theory pub fn th_stock_flow() -> DiscreteDblTheory { let mut cat = FpCategory::new(); // Object type cat.add_ob_generator(name("Stock")); // Morphism types cat.add_mor_generator(name("Flow"), name("Stock"), name("Stock")); cat.add_mor_generator(name("Link"), name("Stock"), name("Stock")); cat.into() } ``` ## Mass-Action ODE Semantics CatColab generates **mass-action ODEs** from stock-flow diagrams: ``` For flow f: A → B influenced by links from stocks {Sᵢ}: rate(f) = k_f · A · ∏ᵢ Sᵢ dA/dt = -rate(f) + (inflows to A) dB/dt = +rate(f) + (other flows) ``` ### SIR Model ODEs ``` Stocks: S, I, R Flows: infection (S→I), recovery (I→R) Links: I influences infection Generated ODEs: dS/dt = -β·S·I dI/dt = +β·S·I - γ·I dR/dt = +γ·I Where β = infection rate, γ = recovery rate ``` ## CatColab Implementation ### Stock Declaration ```typescript { "type": "ObDecl", "name": "Susceptible", "theory_type": "Stock", "description": "population not yet infected" } ``` ### Flow Declaration ```typescript { "type": "MorDecl", "name": "infection", "dom": "Susceptible", "cod": "Infected", "theory_type": "Flow", "description": "rate at which susceptibles become infected" } ``` ### Link Declaration ```typescript { "type": "MorDecl", "name": "contact_influence", "dom": "Infected", "cod": "Susceptible", "theory_type": "Link", "description": "infected population influences infection rate" } ``` ## Practical Examples ### Example 1: SIR Epidemic Model ``` Stocks: S (Susceptible), I (Infected), R (Recovered) Flows: infection: S → I recovery: I → R Links: I → infection (more infected = faster spread) Parameters: β (infection rate): 0.3 γ (recovery rate): 0.1 R₀ = β/γ = 3.0 (epidemic threshold > 1) ``` ### Example 2: SEIR with Exposed ``` Stocks: S, E (Exposed), I, R Flows: exposure: S → E onset: E → I recovery: I → R Links: I → exposure (infected spread disease) Addition: Latency period before becoming infectious ``` ### Example 3: Predator-Prey (Lotka-Volterra) ``` Stocks: Rabbits, Foxes Flows: rabbit_birth: ∅ → Rabbits rabbit_death: Rabbits → ∅ predation: Rabbits → Foxes fox_death: Foxes → ∅ Links: Rabbits → rabbit_birth (reproduction) Foxes → predation (hunting) Foxes → rabbit_death (hunting pressure) ODEs: dR/dt = αR - βRF dF/dt = δRF - γF ``` ### Example 4: Resource Depletion ``` Stocks: Resource, Capital, Population Flows: extraction: Resource → Capital investment: Capital → Capital consumption: Capital → ∅ birth: ∅ → Population death: Population → ∅ Links: Population → extraction Capital → birth Resource → extraction (scarcity effect) ``` ## Analysis Capabilities CatColab provides for stock-flow models: - **ODE Integration**: Numerical simulation - **Steady State**: Fixed point analysis - **Sensitivity**: Parameter sweeps - **Composition**: Combine models via shared stocks ## Stratification & Composition Stock-flow diagrams compose via **stratification**: ```julia # Base SIR model sir = @acset StockFlow begin Stock = [:S, :I, :R] Flow = [(:S, :I), (:I, :R)] end # Age-stratified version (young/old) age_strata = @acset Strata begin Stratum = [:Young, :Old] end # Compose: SIR × Age = 6 stocks (S_young, S_old, ...) stratified_sir = stratify(sir, age_strata) ``` ## GF(3) Triads ``` catcolab-regulatory-networks (-1) ⊗ catcolab-causal-loop (0) ⊗ catcolab-stock-flow (+1) = 0 ✓ catcolab-ologs (-1) ⊗ topos-catcolab (0) ⊗ catcolab-stock-flow (+1) = 0 ✓ ``` ## Commands ```bash # Create stock-flow model just catcolab-new primitive-stock-flow "sir-model" # Generate mass-action ODEs just catcolab-analyze sir-model --odes # Simulate epidemic just catcolab-simulate sir-model --params "β=0.3,γ=0.1" --time 100 # Stratify by age just catcolab-stratify sir-model age-strata # Export to AlgebraicJulia just catcolab-export sir-model --format=julia ``` ## Integration with AlgebraicJulia ```julia using AlgebraicPetri using Catlab # Load CatColab model model = load_stockflow("sir-model.json") # Convert to Petri net petri = stockflow_to_petri(model) # Simulate with DifferentialEquations.jl using OrdinaryDiffEq u0 = [990.0, 10.0, 0.0] # S, I, R prob = ODEProblem(vectorfield(petri), u0, (0.0, 100.0)) sol = solve(prob, Tsit5()) ``` ## References - Baez & Pollard (2017) "A Compositional Framework for Reaction Networks" - Libkind et al. (2022) "An algebraic framework for structured epidemic modeling" - [CatColab Stock-Flow Help](https://catcolab.org/help/logics/primitive-stock-flow) - [AlgebraicPetri.jl](https://algebraicjulia.github.io/AlgebraicPetri.jl/) --- **Skill Name**: catcolab-stock-flow **Type**: Epidemiology / Population Dynamics **Trit**: +1 (PLUS) **GF(3)**: Conserved via triadic composition