Open source engine for simulating substances, applications, and policies relevant to the Montreal Protocol and the Kigali Amendment.
While it can certainly can also run locally on the JVM, the fastest way to try Kigali Sim is from your browser. Make a simulation in 3 minutes without any installation required!
No code? Go to https://kigalisim.org and then in the Designer tab:
- Click "Add Application" to create a "Commerical Refrigeration" application
- Click "Add Consumption" to create HFC-134a (click lookup for GHG equivalency, leave energy consumption at default, check domestic)
- In your HFC-134a record, add a set record for 1 metric tonne (mt) sales in year 1.
- Click "Add Simulation" and make "Business as Usual" from year 1 to 10.
- Click the "Bank" radio button for total million units of equipment and see population increase over time.
With code? Go to https://kigalisim.org and, in the Editor tab, try the following:
start default
define application "Commercial Refrigeration"
uses substance "HFC-134a"
enable domestic
initial charge with 1 kg / unit for domestic
initial charge with 0 kg / unit for import
initial charge with 0 kg / unit for export
equals 1430 kgCO2e / kg
equals 1 kwh / unit
set sales to 1 mt during year 1
retire 5 % / year
end substance
end application
end default
start simulations
simulate "Business as Usual"
from years 1 to 10
end simulations
Can't decide? The UI-based authoring steps we provided generate the code seen above so you can move between UI-based and code-based authoring. Just go between the designer and editor tabs.
Note: We use WebAssembly so simluations run privately on your machine. Continue your journey with a tutorial.
This open source toolkit models substances and equipment related to the Montreal Protocol and Kigali Amendment, including high global warming potential substances.
What it does: Models substances, applications, and policies related to the Montreal Protocol, focusing on hydrofluorocarbons and their alternatives within the Kigali Amendment. Supports business-as-usual simulation and "stacking" policy simulations on top. Simulates emissions, energy, substance consumption, equipment populations, and trade longitudinally.
How it does it: Stock and flow modeling with user-defined structures for applications and substances. Features both UI-based authoring and code-based editing using the QubecTalk domain specific language (DSL). Design details available in our paper draft.
Where it does it: Portable execution through web-based bespoke IDE, command line, or integration into larger workflows. Available on WebAssembly (WASM) or Java Virtual Machine (JVM). Supports parallelization and probabilistic simulation via Monte Carlo.
Who it serves: Intended for researchers working on stock and flow modeling of these substances and policy makers like those working on Kigali Amendment Implementation Plans (KIPs). With ongoing Article 5 use, it was co-created with over a dozen countries and supporting organizations. Serves community members with varied programming backgrounds and offers optional AI assistance.
All executions of simulations are private and local.
Requiring no new local software installation, use the public hosted version of the tool at https://kigalisim.org. Simulations are run locally on your own machine through WebAssembly and Kigali Sim will not send your simulation code / data to external machines without your permission. We simply provide public static file hosting (see privacy).
For those who prefer the command-line interface, install Java (like through Adoptium) and download the latest Kigali Sim jar. Then, execute simulations with:
java -jar kigalisim-fat.jar run -o output.csv script.qta
Here, you may replace script.qta with the path to your QubecTalk script and output.csv with the path to where you would like to write results.
Note that this jar is also posted to GitHub Maven as org.kigalisim.engine. See JavaDoc.
For those who prefer Docker, see Dockerfile which installs Java (Temurin) and can be used to run simulations from the command line. For example, the following builds the image and runs script.qta with output to output.csv through the mounted working directory:
docker build -t kigalisim .
docker run -v $(pwd):/working kigalisim run -o output.csv script.qta
Note: Windows users should replace $(pwd) with %cd% for Command Prompt or ${PWD} for PowerShell.
For information about running the Kigali Sim IDE locally on your machine, see the development section of this README for various options including Docker, GitHub Codespaces, or a manual local setup.
Kigali Sim authors can choose to use a UI-based editor which does not require writing code or the QubecTalk domain-specific programming language. The easiest way to get started is through the User's Guide which includes tutorials and reference materials such as a glossary.
For users preferring a no-code point-and-click approach to authoring simulations, open the UI-based editor and then review our no-code hello world example. Alternatively, review an example simulation made using the UI-based editor in order to explore the tools' capabilities.
For those preferring to write code, review the setup instructions and then consider this example of a permitting system to replace a high global warming potential substance with one exhibiting a lower GWP. This demonstrates all of the basic building blocks of Kigali Sim model (applications, substances, policies, and simulations):
start default
define application "Commercial Refrigeration"
uses substance "HFC-134a"
enable domestic
initial charge with 1 kg / unit for domestic
initial charge with 0 kg / unit for import
initial charge with 0 kg / unit for export
equals 1430 kgCO2e / kg
equals 1 kwh / unit
set sales to 1 mt during year 1
retire 5 % / year
recharge 5 % with 0.85 kg / unit
end substance
uses substance "R-600a"
enable domestic
initial charge with 1 kg / unit for domestic
initial charge with 0 kg / unit for import
initial charge with 0 kg / unit for export
equals 3 kgCO2e / kg
equals 1 kwh / unit
set sales to 1 kg during year 1
retire 5 % / year
recharge 5 % with 0.85 kg / unit
end substance
end application
end default
start policy "Permit"
modify application "Commercial Refrigeration"
modify substance "HFC-134a"
cap sales to 80 % displacing "R-600a" during years 3 to 10
end substance
end application
end policy
start simulations
simulate "Business as Usual"
from years 1 to 10
simulate "With Permit"
using "Permit"
from years 1 to 10
end simulations
This can be run using the editor tab at https://kigalisim.org/ or locally via java -jar kigalisim-fat.jar run -o output.csv script.qta or similar.
Developers can continue their work by going to the User Guide which had information on other features. See also the formal QubecTalk language specification.
If desired, AI coding assistants or chatbots can help in using Kigali Sim. We implement the llms.txt specification, a standard that allows users to bring their own LLM assistants to the tool. Direct your AI to read https://kigalisim.org/llms-full.txt?v=20260128 and / or https://kigalisim.org/llms.txt?v=20260128.
This repository is organized into three main components:
docs/: Documentation including technical specifications and user guidesengine/: Java-based simulation engine that can run standalone or in-browser via WASMeditor/: Web-based editor and analysis tool interface
These directories and their subdirectories also often have their own README.md files with additional details.
For those with a bug report or a suggestion to improve Kigali Sim, please open an issue. It's OK if you do not have all of the details sorted out and we are happy to help you refine your report. That said, some basic information is requested and please complete the issue template to the best of your ability. We will help you take it from there!
For those seeking help with using Kigali Sim, we recommend that you consider starting with the "Get Help" button within the application if you are comfortable sharing your work with us. This free and private support channel offered by the project maintainers (currently the University of California DSE). If you do not want to share your simulation with us or are instructed to file a public help request, please open an issue and try your best to fill in the issue template. Please note that this issue will be public.
For those interested in contributing to the Kigali Sim open source project as a developer, thank you and please review CONTRIBUTING.md. Also, please see our credits page and our humans.txt for more information about the community behind this open source project. If you are unsure which issue might be best for getting started, please look for the "good first issue" tag. For information about community standards and expectations, please see CODE_OF_CONDUCT.md.
We have some basic getting started steps in this developer quickstart for those using Docker / Dev Container, GitHub Codespaces or compatible, or a manual local setup.
For those interested in a dev container, please see .devcontainer. IntelliJ should automatically detect the dev container (see JetBrains documentation). VS Code users can use an extension:
- Install the Dev Containers extension
- Open the project in VS Code
- When prompted, click "Reopen in Container" or press
F1and select "Dev Containers: Reopen in Container" - The container will build automatically with all required dependencies
One can also use GitHub Codespaces:
- Navigate to the repository on GitHub
- Click the green "Code" button
- Select the "Codespaces" tab
- Click "Create codespace on main"
- The development environment will be set up automatically
See DEVELOPING.md for detailed information about the dev container configuration.
All the automated checks and development operations described below work in the dev container environment:
- Java testing:
cd engine && ./gradlew test - Java linting:
cd engine && ./gradlew checkstyleMainandcd engine && ./gradlew checkstyleTest - ECMAScript / JavaScript linting:
cd editor && pnpm exec eslint ./js/*.jsandcd editor && pnpm exec eslint ./test/*.js - ECMAScript / JavaScript testing:
cd editor && pnpm exec grunt - Build and run the UI-based editor locally:
cd editor && bash ./support/make.sh && python3 -m http.server
To run this system locally outside a dev container, please:
-
Install Java like through Adoptium.
-
Go to the editor directory:
cd engine- Run unit tests:
./gradlew test- Check style:
./gradlew checkstyleMain checkstyleTest- Build the Jar (Gradle will be setup automatically)
./gradlew buildIf working on the front-end, please set up the editor:
-
Setup Node and pnpm.
-
Navigate to the editor directory:
cd editor- Install build dependencies:
pnpm install- Build the project (TeaVM build step for WASM):
bash ./support/make.sh- Run the front-end tests (may install browser via Puppeteer):
pnpm exec grunt- Run style checks:
pnpm exec eslint ./js/*.js
pnpm exec eslint ./test/*.js- Run a local web server (such as Python http.server):
python -m http.server- Visit the local hosted webpage using any web browser at the given address.
We have continuous integration and deployment through GitHub actions. For additional information about development, see DEVELOPING.md. If you are contributing, see CONTRIBUTING.md. Finally, if you are using an AI coding assistant to write code you want to donate to the project, please review the AI contribution guidelines.
We thank the following Open Source libraries and resources:
- ACE Editor under BSD-3.
- ANTLR4 under BSD-3.
- Apache Commons CSV under Apache-2.0.
- Chart.js under MIT.
- D3 under ISC.
- ESLint under MIT.
- Papa Parse under MIT.
- Popper under MIT.
- Prism.js under MIT.
- Public Sans under OFL-1.1.
- QUnit under MIT.
- SVG Spinners under MIT
- Tabby under MIT.
- Tippy under MIT.
- Webpack under MIT.
- Global Plastics AI Policy Tool under BSD-3-Clause.
- Josh under BSD-3-Clause.
We also use colors from ColorBrewer 2.0 by Cynthia Brewer, Mark Harrower, Ben Sheesley, Andy Woodruff, and David Heyman at The Pennsylvania State University. Additionally, we use data from UNEP Ozone Secretariat for Global Warming Potential (GWP) values of substances and refrigerant blends. See editor/json/known_gwp.json. Additionally, Pandoc under GPL-2.0 is invoked from CI / CD but exclusively for optional documentation generation (invoked as an executable). Not a compile-time or run-time dependency of Kigali Sim itself or any of its components and it is used in a completely isolated CI / CD pipeline from the rest of the project.
This project's code is available under the BSD license. All documentation is available under the Creative Commons CC-BY 4.0 International License.
This privacy-respecting simulation platform offers essential tools to assist policy and research efforts. Informed by various perspectives from across the Montreal Protocol ecosystem of actors, we believe that this project is owned by its community. It is available to the public as an optional open source resource.