# Kigali Sim - Montreal Protocol Policy Simulation Tool v=20250926 Kigali Sim is an open source web-based simulation engine for modeling substances, applications, and policies related to the Montreal Protocol and Kigali Amendment. It can model high global warming potential greenhouse gases such as HFCs and supports business-as-usual scenarios as well as policy interventions. ## Project Purpose This tool provides simulation capabilities for: - **Substance modeling**: HFCs, HCFCs, and alternative refrigerants with their Global Warming Potential (GWP) values - **Application modeling**: Equipment types like domestic refrigeration, commercial refrigeration, residential AC, mobile AC - **Policy simulation**: Import restrictions, manufacturing caps, substance replacements, recycling requirements - **Business scenarios**: Manufacturing, imports, equipment lifecycles, service activities, energy consumption - **Impact assessment**: Direct emissions calculations, energy consumption analysis, equipment population tracking Kigali Sim supports both business-as-usual projections and policy intervention scenarios, making it useful for Kigali Amendment Implementation Plans (KIPs) and Montreal Protocol policy analysis. ## QubecTalk Domain Specific Language Kigali Sim uses QubecTalk, a HyperTalk-inspired domain-specific language for defining simulations. QubecTalk programs are human-readable and use natural language constructs. **Note**: In this documentation, pipe symbols (|) indicate command alternatives, not syntax. Chevrons (<) indicate optional values, curly braces ({) indicate required values. Neither are part of actual QubecTalk syntax. **Comments**: Use `#` to add comments. Comments run to the end of the line and are ignored by the interpreter. **Define vs Modify**: Use `define` in the `default` stanza to create new applications and substances for the business-as-usual scenario. Use `modify` in `policy` stanzas to change existing applications and substances defined in the default scenario. ### Program Structure QubecTalk programs are organized into stanzas: ``` start about # Name: "Simulation Name" # Description: "Description" # Author: "Author Name" end about start default # Business as usual scenario end default start policy "Policy Name" # Policy modifications end policy start simulations # Simulation definitions end simulations ``` The about stanza is optional. ### Core Language Features #### Applications and Substances - `define application "name"` - Creates equipment/application type - `uses substance "name"` - Associates substance with application - `equals X tCO2e / mt` - Sets Global Warming Potential in tCO2e units (t is tonnes) - `equals X kgCO2e / kg` - Sets Global Warming Potential in kgCO2e units (kg is kilograms) - `equals X kwh / unit` - Sets energy consumption per unit #### Manufacturing and Trade - `initial charge with {amount} for {stream}` - Sets substance per unit where amount is typically X kg / unit - `enable {stream}` - Marks stream as enabled without setting values (required before recharge operations). By convention, place at top of substance definitions. - `set {stream} to {amount} ` - Sets flow volumes - `change {stream} by {amount} ` - Growth or decay rates where amount is often +X % #### Equipment Lifecycle - `retire {amount} ` - Equipment retirement rate, also called hazard rate or scrap rate (with replacement maintains equipment population) - `recharge {population} with {volume} ` - Service recharging (population = equipment to recharge, volume = substance per unit) - `set priorEquipment to {amount} ` - Pre-existing equipment. #### Sales Assumptions (Bank Tracking) The `assume` command provides control over sales carryover behavior: - `assume no [stream] ` - Sets stream to 0 kg (zero all sales) - `assume only recharge [stream] ` - Sets stream to 0 units (only recharge, no new equipment) - `assume continued [stream] ` - No-op (sales continue from previous year, default behavior) Streams supported: `domestic`, `import`, `sales`, `bank` Examples: ```qubectalk assume only recharge sales during years 2025 to onwards assume no import during year 2030 assume continued domestic assume only recharge bank during years 2 to 5 ``` The `assume` command is particularly useful for bank (equipment) tracking scenarios where you want to model that sales should only cover recharge (servicing) needs rather than adding new equipment. #### Policy Interventions - `cap|floor stream to {amount} ` - Manufacturing/import restrictions and minimums - `replace {amount} of {stream} with "substance" ` - Substance transitions - `recover {amount} with {amount} reuse ` - Recycling with optional stage (eol or recharge) and duration **Note**: When using units (of equipment) in cap, floor, and set commands, those limits apply after recharge calculations. So a cap of 100 units means 100 units on top of recharge for prior equipment. #### Units System Supports automatic unit conversion: kg, mt (metric tons), tCO2e (tons CO2 equivalent), kwh (kilowatt hours), units (equipment), years/months/days (time), % (percentages) #### Number formatting Kigali Sim uses DecimalFormat number formatting (comma for thousands, period for decimal). Alternative formats like `123.456,7` generate suggestions for equivalent supported format `123,456.7`. #### Advanced Features - **Variables**: `define identifier as expression` and `get identifier` (scoped to enclosing start/end block) - **Stream access**: `get {stream}` - access streams like `sales`, `equipment`, `age`, etc. - **Unit conversions**: `get {stream} as {units}` like `get import of "substance" as mt` or `get age as years` - **Age stream**: `get age as years` provides weighted average equipment age for age-dependent policies (read-only, computed) - **Constraints**: `limit expression to [min,max]`, `limit expression to [,max]` (min of negative infinity), `limit expression to [min,]` (max of infinity) - **Uncertainties**: `sample normally from mean of X std of Y`, `sample uniformly from X to Y` - **Math expressions**: Basic arithmetic with `+`, `-`, `*`, `/`, `^`, parentheses - **Logical operators**: `and`, `or`, `xor` for combining boolean expressions - **Comparison operators**: `==`, `!=`, `<`, `>`, `<=`, `>=` for conditions ### Time Simulations may be run with years as the time unit where each time unit is a single step. Use of months or days is reserved for future use. Commands can specify timing with `during year|years X to Y` or `during year X` for individual years. Keywords `beginning` and `onwards` are available. For a simulation running from years 2025 to 2030, the following is valid: `during year|years 2025|beginning to 2030|onwards`. Keywords `at` and `eol` are available for recycling commands. Use `at recharge` for recycling at service time and `at eol` for recycling at equipment retirement. No duration means runs each year. Use `during year beginning` for first year only. ### Streams Streams may be `domestic|import|export|sales|equipment|priorEquipment|bank|age` - `domestic` - domestic manufacturing - `sales` - both `domestic` and `import` - `equipment` - both prior and new equipment - `age` - weighted average equipment age (read-only, Advanced Editor only) **Bank Keyword**: The `bank` keyword is syntactic sugar for the `equipment` stream, provided for semantic clarity when modeling substance banks (total refrigerant in equipment). Using `bank` instead of `equipment` can make code more readable in banking scenarios: ```qubectalk set bank to 1000 units during year 1990 # Same as: set equipment to 1000 units assume only recharge bank during years 2025 to onwards ``` **Age Stream**: The `age` stream tracks the weighted average age of equipment in the population. This is a computed, read-only stream that cannot be set by users: - Age starts at 0 years for initial equipment - Age increases by 1 year each simulation year - With new equipment additions, age is the weighted average based on equipment quantities - Usage: `get age as years` in formulas - Example: `retire (get age as years) * 1 %` for age-dependent retirement - **Advanced Editor only** - not available in Designer UI **Note**: The `enable` command only works with `domestic`, `import`, and `export` streams. Streams must be enabled (either explicitly with `enable` or implicitly by setting non-zero values) before operations like `recharge` that require sales distribution calculations. ### Formatting Use start/end keywords (curly braces not supported). Two spaces per tab recommended. ### Built-in Variables Built-in variables: `yearAbsolute` (current year), `yearsElapsed` (years since start), plus similar for months/days ### Conditional Logic Ternary operations using `if`/`else`/`endif`: ``` set domestic to 100 if testVar > 10 else 50 endif mt ``` Boolean expressions can be combined with `and`, `or`, `xor`: ``` set domestic to 70 if (testA or testB) and testC else 35 endif mt ``` ### Probabilistic simulation Multiple Monte Carlo trials can be specified like `simulate "test" using "policy" from years 1 to 10 across 100 trials` ### Policy Syntax Policies use `then` to chain multiple interventions: ``` simulate "Combined Policy" using "Import Ban" then "Domestic Permit" then "Efficiency Incentive" from years 1 to 20 ``` ### Displacement Changes in one substance can be offset by changes in another. For example: - `cap sales to 1400 mt displacing "R-404A" during years 1 to 5` offsets with another substance - `cap import to 1400 mt displacing "domestic" during years 1 to 5` offsets with another stream This is available for `cap`, `floor`, and `recover`. ### Recycling Stages and Induction The `recover` command supports specifying when recycling occurs and how much induced demand it creates: - `recover {amount} with {amount} reuse` - Defaults to recycling at recharge (service) time with default induction behavior - `recover {amount} with {amount} reuse with {amount} induction` - Explicit induction percentage (0-100%) - `recover {amount} with {amount} reuse with default induction` - Uses default induction behavior based on specification type - `recover {amount} with {amount} reuse at recharge` - Explicitly specifies recycling at service time - `recover {amount} with {amount} reuse at eol` - Specifies recycling at end-of-life (retirement) **Induction Control**: Induction determines how much recycled material adds to the market versus displaces virgin production: - **Units-based specs**: Default 0% induction (displacement behavior) - recycling reduces virgin sales to maintain steady population - **Non-units specs (kg/mt)**: Default 100% induction (induced demand behavior) - recycling adds on top of existing demand - **Explicit specification**: Users can override defaults by specifying exact percentages (0-100%) **100% Induction Recommendations**: - **100% induction means recycled material does not displace virgin material** - it adds to total supply - **100% is recommended for users who are uncertain** as induction is a complex economic phenomenon that can be hard to predict - **Can be paired with other policies**, for example, a cap on virgin (import, domestic) to ensure desired reduction in virgin material alongside increasing supply through expanded recycling stream Examples: ``` recover 20 % with 80 % reuse at recharge # Uses default: 0% for units, 100% for volume recover 15 % with 75 % reuse with 50 % induction at eol # Explicit 50% induction recover 10 % with 90 % reuse with default induction during years 3 to 5 # Uses default behavior recover 25 % with 85 % reuse with 0 % induction during year 2027 to onwards # Full displacement recover 30 % with 95 % reuse with 100 % induction at eol # Full induced demand ``` **Behavioral Differences**: - **0% Induction (Displacement)**: Recycled material reduces virgin material demand. Total equipment population stays constant. - **100% Induction (Induced Demand)**: Recycled material adds to total supply. Equipment population increases due to additional material availability. - **Partial Induction (Mixed)**: Combines both behaviors proportionally. ## Example QubecTalk Program ``` start about # Name: "HFC Refrigeration Analysis" # Description: "Domestic refrigeration HFC phasedown scenario" end about start default define application "dom refrig" uses substance "HFC-134a" enable domestic enable import equals 1430 kgCO2e / kg equals 100 kwh / unit initial charge with 0.12 kg / unit for domestic set domestic to 350000 kg during year 1 change domestic by +5 % each year during years 1 to 5 initial charge with 0.30 kg / unit for import set import to 90000 kg during year 1 change import by +5 % each year during years 1 to 5 retire 6.7 % each year recharge 10 % with 0.12 kg / unit end substance end application end default start policy "HFC Phasedown" modify application "dom refrig" modify substance "HFC-134a" cap domestic to 85% during years 3 to 5 cap import to 85% during years 3 to 5 recover 20 % with 80 % reuse with 25 % induction at eol during years 4 to 10 replace 50% of domestic with "R-600a" during years 6 to onwards # Example: Age-dependent retirement (Advanced Editor only) # retire (get age as years) * 1 % each year during years 5 to onwards end substance uses substance "R-600a" equals 6 tCO2e / mt equals 95 kwh / unit initial charge with 0.05 kg / unit for domestic end substance end application end policy start simulations simulate "business as usual" from years 1 to 10 simulate "with phasedown" using "HFC Phasedown" from years 1 to 10 end simulations ``` ## Web Interface Kigali Sim provides a web interface at https://kigalisim.org with two editing modes: - **Basic Editor**: UI-based point-and-click interface for building simulations - **Advanced Editor**: Code editor for writing QubecTalk directly The Advanced Editor tab accepts QubecTalk code as input and can run probabilistic simulations not available in the Basic Editor. The Basic Editor can also generate QubecTalk code that can be further customized in the Advanced Editor. ### UI Editor Compatibility When working with AI assistants, you may want to specify that only UI Editor compatible features should be used. The UI Editor supports a subset of QubecTalk features for ease of use: **Supported in UI Editor:** - Basic application and substance definitions - Initial charges for domestic, import, export streams - GWP values (`equals` with standard units: tCO2e/kgCO2e per unit/kg/mt) - Energy consumption (`equals` with kwh per unit/kg/mt) - Equipment retirement rates - Stream operations: `set`, `change`, `cap`, `floor` commands - Equipment recharging - Policy modifications: `recycle`, `replace` commands - Induction parameters: `with X % induction` in recover commands - Time durations for commands - Simple numeric values and standard units - Single-substance policies (one substance per policy) - Basic simulation scenarios (single policy chains) **Not Supported in UI Editor (Advanced Editor Only):** - **About stanza**: Metadata and descriptions (`start about`/`end about`) - **Variables**: `define identifier as expression` and `get identifier` - **Mathematical expressions**: Complex calculations, arithmetic operations in commands - **Conditional logic**: `if`/`else`/`endif` constructs, ternary operations - **Boolean operators**: `and`, `or`, `xor` for logical combinations - **Comparison operators**: `==`, `!=`, `<`, `>`, `<=`, `>=` in conditions - **Constraints**: `limit expression to [min,max]` operations - **Probabilistic features**: `sample normally`, `sample uniformly` distributions - **Monte Carlo simulations**: `across X trials` for multiple simulation runs - **Stream access**: `get {stream}` and `get {stream} as {units}` operations - **Age stream**: `get age as years` for equipment age tracking and age-dependent policies - **Complex expressions**: Any mathematical or logical expressions beyond simple numeric values - **Multi-substance policies**: Policies affecting multiple substances simultaneously - **Advanced unit conversions**: Dynamic unit conversion expressions **Example UI-Compatible Code:** ``` start default define application "domestic refrigeration" uses substance "HFC-134a" enable domestic enable import equals 1430 kgCO2e / kg equals 100 kwh / unit initial charge with 0.12 kg / unit for domestic set domestic to 350000 kg during year 1 change domestic by +5 % each year during years 1 to 5 retire 6.7 % each year recharge 10 % with 0.12 kg / unit end substance end application end default start policy "HFC Phasedown" modify application "domestic refrigeration" modify substance "HFC-134a" cap domestic to 85% during years 3 to 5 recover 20 % with 80 % reuse at eol during years 4 to 10 end substance end application end policy start simulations simulate "business as usual" from years 1 to 10 simulate "with phasedown" using "HFC Phasedown" from years 1 to 10 end simulations ``` When requesting UI Editor compatible code, avoid variables, expressions, conditional logic, and probabilistic features. ## Technical Implementation - **Language**: JavaScript with ANTLR4 parser - **Architecture**: Browser-based execution with no server-side computation - **Output formats**: Visualizations, CSV export, emissions metrics - **License**: BSD for code, CC-BY 4.0 for documentation ## Simulation Outputs Kigali Sim generates: - **Emissions projections**: Direct HFC/HCFC emissions in tCO2e - **Equipment population**: Units in use over time - **Consumption data**: Manufacturing and import volumes - **Energy consumption**: Associated electricity usage - **Policy impact**: Comparison between scenarios ## Simulation Exports Kigali Sim provides CSV export functionality from both the web interface and the standalone JAR engine with identical column structures and data formats. ### Export Sources - **Web Interface**: Click "Export CSV" button in the results panel after running a simulation - **JAR Engine**: Generated automatically when running simulations via command line or programmatically ### CSV Column Descriptions **Identification Columns:** - `scenario` - Name of simulation scenario (e.g., "business as usual", "with phasedown") - `trial` - Trial number for Monte Carlo simulations (1 for single-run scenarios) - `year` - Simulation year - `application` - Equipment application (e.g., "domestic refrigeration", "commercial AC") - `substance` - Refrigerant substance (e.g., "HFC-134a", "R-410A") **Production & Trade Volumes (kg/year):** - `domestic` - Domestic manufacturing volume - `import` - Import volume (bulk substance) - `export` - Export volume (bulk substance) - `recycle` - Recycled substance volume **Consumption Impact (tCO2e/year):** - `domesticConsumption` - GHG impact from domestic manufacturing - `importConsumption` - GHG impact from imports - `exportConsumption` - GHG impact from exports - `recycleConsumption` - GHG impact from recycling **Equipment Population (units):** - `population` - Total equipment population in service - `populationNew` - New equipment added in current year **Emissions Sources (tCO2e/year):** - `rechargeEmissions` - Emissions from equipment servicing/leakage - `eolEmissions` - Emissions from end-of-life equipment disposal - `initialChargeEmissions` - Informational metric for GHG potential of new charges **Energy Impact:** - `energyConsumption` - Energy consumption from equipment operation (kwh/year) **Trade Attribution Supplement:** - `importInitialChargeValue` - Substance volume in imported equipment initial charges (kg) - `importInitialChargeConsumption` - GHG impact from imported equipment charges (tCO2e) - `importPopulation` - Equipment units imported with initial charges - `exportInitialChargeValue` - Substance volume in exported equipment initial charges (kg) - `exportInitialChargeConsumption` - GHG impact from exported equipment charges (tCO2e) **Bank Tracking (substance in equipment):** - `bankKg` - Total substance volume contained in all equipment in service (kg) - `bankTCO2e` - Total GHG potential of substance in all equipment in service (tCO2e) - `bankChangeKg` - Change in substance bank from previous year (kg) - `bankChangeTCO2e` - Change in GHG potential of substance bank from previous year (tCO2e) ### Montreal Protocol Attribution Convention Under standard Montreal Protocol reporting, initial charge for imported equipment is typically attributed to the exporting country (equipment manufacturer), while recharge/servicing is attributed to the importing country (equipment operator). Domestically produced and consumed substances are attributed domestically. The trade supplement columns enable user-configurable attribution to support both standard convention and alternative accounting methodologies for international trade reporting. ### Bank Tracking Columns The bank columns (bankKg, bankTCO2e, bankChangeKg, bankChangeTCO2e) represent the substance "bank" - the total amount of substance contained within the equipment population currently in service. This differs from consumption/sales columns which track substance flow volumes. Bank calculations use initial charge values and GWP (Global Warming Potential) from the equals statement to convert equipment population (units) to substance volume (kg) and GHG impact (tCO2e). The change columns show the difference from the previous year, reflecting net increase or decrease in the substance bank. ## Variable Hazards Constant % / year having recharge or retirement recommended for simple scripts but variable hazards can use age of equipment where `get age` yields average age of equipment: ``` uses substance "R-407C" enable import assume only recharge sales initial charge with 10 kg / unit for import equals 1774 kgCO2e / kg set priorEquipment to 100 units during year 2022 retire (get age as years)^2 * 0.195% / year recharge (get age as years) * 0.109% with 10 kg / unit end substance ``` Here leakage hazard rate linearly increases with age and retirement exponentially: 10 year average lifespan with 6% recharge during that lifetime. ## Limitations This tool is unofficial and voluntary, designed to optionally inform Montreal Protocol policy discussions rather than replace official assessment processes.