# KigaliSim - Montreal Protocol Policy Simulation Tool
v=20250910

KigaliSim 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

KigaliSim 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
KigaliSim 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, the pipe symbol (|) is used to indicate different command options or alternatives, not as part of the actual QubecTalk syntax. For example, `set domestic|import to X kg during year Y` means both `set domestic to X kg during year Y` and `set import to X kg during year Y` are valid. Similarly, chevrons (<) mean a value may be provided while curly braces ({) mean a value must be provided but are only provided for documentation purposes and are not part of 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}` - Explicitly marks a stream as enabled without setting values (required before operations like recharge that need sales recalculation). By convention, enable statements should be placed at the top of substance definitions within application definitions, though this is not enforced by the language.
- `set {stream} to {amount} <during>` - Sets flow volumes
- `change {stream} by {amount} <during>` - Growth or decay rates where amount is often +X %

#### Equipment Lifecycle
- `retire {amount} <during>` - Equipment retirement rate
- `recharge {population} with {volume} <during>` - Service recharging where population specifies equipment to recharge and volume is substance per unit.
- `set priorEquipment to {amount} <during>` - Pre-existing equipment.

#### Policy Interventions
- `cap|floor stream to {amount} <displacing> <during>` - Manufacturing/import restrictions and minimums
- `replace {amount} of {stream} with "substance" <during>` - Substance transitions
- `recover {amount} with {amount} reuse <at {stage}> <during>` - 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 requires DecimalFormat number formatting (comma for thousands separator, period for decimal point). Both formatting conventions are internationally valid, but Kigali Sim uses the DecimalFormat format for consistency with the technologies it leverages. Alternative format numbers like `123.456,7` will generate a message with a suggestion for the equivalent supported format `123,456.7`. Numbers like `123,456` or `123.456` are interpreted as DecimalFormat without error.

#### Advanced Features
- **Variables**: `define identifier as expression` and `get identifier` (scoped to enclosing start/end block)
- **Stream access**: `get {stream}`
- **Unit conversions**: `get {stream} as {units}` like `get import of "substance" as mt`
- **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.

To specify when a command should run, during may be appended like `cap equipment to 0 units during year|years 1 to 5` or `cap equipment to 0 units during year|years 2028 to 2033`. This may also be an individual time like `during year 2028`.

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 though `each year` may also be optionally written to apply to all years.

To have a command only run in the first year, use `during year beginning` which, for a simulation running 2025 to 2030, is the same as `during year 2030`.

### Streams
Streams may be `domestic|import|export|sales|equipment|priorEquipment`

 - `domestic` is domestic manufacturing (as opposed to `import` or `export`)
 - `sales` is both `domestic` and `import`
 - `equipment` is both equipment which entered into service prior steps (`priorEquipment`) and new equipment in the current step

**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
Curly braces are not supported, start and end keywords must be used. It is recommended but not required to use two spaces per tab.

### Built-in Variables
Special variables available in expressions:
- `yearAbsolute` - The current absolute year number
- `yearsElapsed` - Years since simulation start (starts at 0)
- Similar variables for other time units: `monthAbsolute`, `monthsElapsed`, `dayAbsolute`, `daysElapsed`

### 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 100% induction (induced demand behavior)
- `recover {amount} with {amount} reuse with {amount} induction` - Explicit induction percentage (0-100%)
- `recover {amount} with {amount} reuse with default induction` - Uses 100% induction (induced demand behavior)
- `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%)

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

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

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

KigaliSim 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

## Limitations

This tool is unofficial and voluntary, designed to optionally inform Montreal Protocol policy discussions rather than replace official assessment processes.