{"id":51590381,"url":"https://github.com/schmidtdse/kigali-sim","last_synced_at":"2026-07-11T14:01:42.781Z","repository":{"id":277577073,"uuid":"858416855","full_name":"SchmidtDSE/kigali-sim","owner":"SchmidtDSE","description":"Open source tookit to simulate substances and equipment relevant to the Montreal Protocol under configurable scenarios and policies.","archived":false,"fork":false,"pushed_at":"2026-06-11T20:14:24.000Z","size":45585,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-06-11T20:17:27.507Z","etag":null,"topics":["antlr","atmospheric-modelling","environment","java","modeling-and-simulation","policy","wasm"],"latest_commit_sha":null,"homepage":"https://kigalisim.org/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SchmidtDSE.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-16T21:16:40.000Z","updated_at":"2026-06-11T19:45:33.000Z","dependencies_parsed_at":"2025-07-28T23:14:53.523Z","dependency_job_id":"754eacb6-2483-4053-8462-8ab28fe17f29","html_url":"https://github.com/SchmidtDSE/kigali-sim","commit_stats":null,"previous_names":["schmidtdse/montreal-protocol","schmidtdse/kigali-sim"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/SchmidtDSE/kigali-sim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SchmidtDSE%2Fkigali-sim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SchmidtDSE%2Fkigali-sim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SchmidtDSE%2Fkigali-sim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SchmidtDSE%2Fkigali-sim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SchmidtDSE","download_url":"https://codeload.github.com/SchmidtDSE/kigali-sim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SchmidtDSE%2Fkigali-sim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35364269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antlr","atmospheric-modelling","environment","java","modeling-and-simulation","policy","wasm"],"created_at":"2026-07-11T14:01:38.136Z","updated_at":"2026-07-11T14:01:42.768Z","avatar_url":"https://github.com/SchmidtDSE.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kigali Sim\nOpen source engine for simulating substances, applications, and policies relevant to the Montreal Protocol and the Kigali Amendment.\n\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![BSD Licensed](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) [![Build](https://github.com/SchmidtDSE/kigali-sim/actions/workflows/build.yaml/badge.svg?branch=deploy)](https://github.com/SchmidtDSE/kigali-sim/actions/workflows/build.yaml) ![Temurin 21 or higher](https://img.shields.io/badge/Java-Temurin%2021%2B-blue) [![status](https://joss.theoj.org/papers/eafc95ac66aae284563f36fa60f0261d/status.svg)](https://joss.theoj.org/papers/eafc95ac66aae284563f36fa60f0261d)\n\n\u003cbr\u003e\n\n## Quickstart\nWhile 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!\n\n**No code?** Go to https://kigalisim.org and then in the Designer tab:\n\n - Click \"Add Application\" to create a \"Commercial Refrigeration\" application\n - Click \"Add Consumption\" to create HFC-134a (click lookup for GHG equivalency, leave energy consumption at default, check domestic)\n - In your HFC-134a record, add a set record for 1 metric tonne (mt) sales in year 1.\n - In your HFC-134a record, add a change record of +5% each year starting in year 2 to onwards.\n - Click \"Add Simulation\" and make \"Business as Usual\" from year 1 to 10.\n - Click the \"Bank\" radio button for total million units of equipment and see population increase over time.\n\n**With code?** Go to https://kigalisim.org and, in the Editor tab, try the following:\n\n```\nstart default\n\n  define application \"Commercial Refrigeration\"\n  \n    uses substance \"HFC-134a\"\n      enable domestic\n      initial charge with 1 kg / unit for domestic\n      initial charge with 0 kg / unit for import\n      initial charge with 0 kg / unit for export\n      equals 1430 kgCO2e / kg\n      equals 1 kwh / unit\n      set sales to 1 mt during year 1\n      change sales by +5 % during year 2 to onwards\n      retire 5 % / year\n    end substance\n  \n  end application\n\nend default\n\n\nstart simulations\n\n  simulate \"Business as Usual\"\n  from years 1 to 10\n\nend simulations\n```\n\n**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.\n\nNote: We use [WebAssembly](https://webassembly.org/) so simulations run privately on your machine. Continue your journey with a [tutorial](https://kigalisim.org/guide/tutorial_02.html).\n\n\u003cbr\u003e\n\n## Purpose\nThis open source toolkit models substances and equipment related to the Montreal Protocol and Kigali Amendment, including high global warming potential substances.\n\n**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.\n\n**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](https://github.com/SchmidtDSE/kigali-sim/blob/main/paper/paper.md).\n\n**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.\n\n**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](https://ozone.unep.org/treaties/montreal-protocol/articles/article-5-special-situation-developing-countries) 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](https://github.com/SchmidtDSE/kigali-sim?tab=readme-ov-file#llm-assistants).\n\n\u003cbr\u003e\n\n## Setup\nAll executions of simulations are private and local.\n\n### Public hosted browser-based app\nRequiring 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](https://kigalisim.org/privacy.html)).\n\n### Local jar file\nFor those who prefer the command-line interface, install Java (like through [Adoptium](https://adoptium.net/installation)) and download the [latest Kigali Sim jar](https://kigalisim.org/kigalisim-fat.jar). Then, execute simulations with:\n\n```\njava -jar kigalisim-fat.jar run -o output.csv script.qta\n```\n\nHere, 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.\n\nNote that this jar is also posted to GitHub Maven as `org.kigalisim.engine`. See [JavaDoc](https://kigalisim.org/guide/javadoc) and [JSDoc](https://kigalisim.org/guide/jsdoc).\n\n### Docker (CLI)\nFor those who prefer Docker, see `Dockerfile` which installs Java ([Temurin](https://adoptium.net/temurin/releases)) 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:\n\n```\ndocker build -t kigalisim .\ndocker run -v $(pwd):/working kigalisim run -o output.csv script.qta\n```\n\nNote: Windows users should replace `$(pwd)` with `%cd%` for Command Prompt or `${PWD}` for PowerShell.\n\n### AI / Programmatic Access\nFor programmatic or AI-assisted use, some tools are available. See [engine readme](https://github.com/SchmidtDSE/kigali-sim/blob/main/engine/README.md).\n\n### Local UI-based editor\nFor information about running the Kigali Sim IDE locally on your machine, see the [development section of this README](https://github.com/SchmidtDSE/kigali-sim?tab=readme-ov-file#development) for various options including Docker, GitHub Codespaces, or a manual local setup.\n\n\u003cbr\u003e\n\n## Usage\nKigali 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](https://kigalisim.org/guide/) which includes tutorials and reference materials such as a glossary.\n\n### UI-based authoring\nFor users preferring a no-code point-and-click approach to authoring simulations, open the [UI-based editor](https://kigalisim.org/) and then review our [no-code hello world example](https://kigalisim.org/guide/tutorial_02.html). Alternatively, review an [example simulation](https://kigalisim.org/guide/tutorial_02.qta) made using the UI-based editor in order to explore the tools' capabilities.\n\n### Code-based authoring\nFor those preferring to write code, review the [setup instructions](https://github.com/SchmidtDSE/kigali-sim?tab=readme-ov-file#setup) 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):\n\n```\nstart default\n\n  define application \"Commercial Refrigeration\"\n  \n    uses substance \"HFC-134a\"\n      enable domestic\n      initial charge with 1 kg / unit for domestic\n      initial charge with 0 kg / unit for import\n      initial charge with 0 kg / unit for export\n      equals 1430 kgCO2e / kg\n      equals 1 kwh / unit\n      set sales to 1 mt during year 1\n      retire 5 % / year\n      recharge 5 % with 0.85 kg / unit\n    end substance\n\n\n    uses substance \"R-600a\"\n      enable domestic\n      initial charge with 1 kg / unit for domestic\n      initial charge with 0 kg / unit for import\n      initial charge with 0 kg / unit for export\n      equals 3 kgCO2e / kg\n      equals 1 kwh / unit\n      set sales to 1 kg during year 1\n      retire 5 % / year\n      recharge 5 % with 0.85 kg / unit\n    end substance\n  \n  end application\n\nend default\n\n\nstart policy \"Permit\"\n\n  modify application \"Commercial Refrigeration\"\n  \n    modify substance \"HFC-134a\"\n      cap sales to 80 % displacing \"R-600a\" during years 3 to 10\n    end substance\n  \n  end application\n\nend policy\n\n\nstart simulations\n\n  simulate \"Business as Usual\"\n  from years 1 to 10\n\n\n  simulate \"With Permit\"\n    using \"Permit\"\n  from years 1 to 10\n\nend simulations\n```\n\nThis 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.\n\n### Additional resources\nDevelopers can continue their work by going to the [User Guide](https://kigalisim.org/guide/) which had information on other features. See also the [formal QubecTalk language specification](https://kigalisim.org/guide/qubectalk.pdf).\n\n### LLM assistants\nIf desired, AI coding assistants or chatbots can help in using Kigali Sim. We implement the [llms.txt specification](https://llmstxt.org), 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=20260302` and / or `https://kigalisim.org/llms.txt?v=20260302`.\n\n\u003cbr\u003e\n\n## Project Structure\n\nThis repository is organized into three main components:\n\n- **`docs/`**: Documentation including technical specifications and user guides\n- **`engine/`**: Java-based simulation engine that can run standalone or in-browser via WASM\n- **`editor/`**: Web-based editor and analysis tool interface\n\nThese directories and their subdirectories also often have their own `README.md` files with additional details.\n\n\u003cbr\u003e\n\n## Help and Contributions\nFor those with a bug report or a suggestion to improve Kigali Sim, please [open an issue](https://github.com/SchmidtDSE/kigali-sim/issues/new). 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!\n\nFor 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](https://github.com/SchmidtDSE/kigali-sim/issues/new) and try your best to fill in the issue template. Please note that this issue will be public.\n\nFor those interested in contributing to the Kigali Sim open source project as a developer, thank you and please review [CONTRIBUTING.md](https://github.com/SchmidtDSE/kigali-sim/blob/main/CONTRIBUTING.md). Also, please see [our credits page](https://kigalisim.org/guide/credits.html) and our [humans.txt](https://kigalisim.org/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](https://github.com/SchmidtDSE/kigali-sim/blob/main/CODE_OF_CONDUCT.md).\n\n\u003cbr\u003e\n\n## Development\nWe 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.\n\n### Using Docker / Dev Container\nFor those interested in a dev container, please see `.devcontainer`. **IntelliJ** should automatically detect the dev container (see [JetBrains documentation](https://www.jetbrains.com/help/idea/connect-to-devcontainer.html)). **VS Code** users can use an extension:\n\n1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)\n2. Open the project in VS Code\n3. When prompted, click \"Reopen in Container\" or press `F1` and select \"Dev Containers: Reopen in Container\"\n4. The container will build automatically with all required dependencies\n\nOne can also use **GitHub Codespaces**:\n\n1. Navigate to the repository on GitHub\n2. Click the green \"Code\" button\n3. Select the \"Codespaces\" tab\n4. Click \"Create codespace on main\"\n5. The development environment will be set up automatically\n\nSee `DEVELOPING.md` for detailed information about the dev container configuration.\n\nAll the automated checks and development operations described below work in the dev container environment:\n\n- Java testing: `cd engine \u0026\u0026 ./gradlew test`\n- Java linting: `cd engine \u0026\u0026 ./gradlew checkstyleMain` and `cd engine \u0026\u0026 ./gradlew checkstyleTest`\n- ECMAScript / JavaScript linting: `cd editor \u0026\u0026 pnpm exec eslint ./js/*.js` and `cd editor \u0026\u0026 pnpm exec eslint ./test/*.js`\n- ECMAScript / JavaScript testing: `cd editor \u0026\u0026 pnpm exec grunt`\n- Build and run the UI-based editor locally: `cd editor \u0026\u0026 bash ./support/make.sh \u0026\u0026 python3 -m http.server`\n\nNote that, to run front-end tests, you may need to first `bash ./support/make.sh`.\n\n### Other Local Setup\nTo run this system locally outside a dev container, please:\n\n1. Install Java like through [Adoptium](https://adoptium.net).\n\n2. Go to the editor directory:\n\n```bash\ncd engine\n```\n\n3. Run unit tests:\n\n```bash\n./gradlew test\n```\n\n4. Check style:\n\n```bash\n./gradlew checkstyleMain checkstyleTest\n```\n\n5. Build the Jar (Gradle will be setup automatically)\n\n```bash\n./gradlew build\n```\n\nIf working on the front-end, please set up the editor:\n\n1. [Setup Node](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) and [pnpm](https://pnpm.io).\n\n2. Navigate to the editor directory:\n\n```bash\ncd editor\n```\n\n3. Install build dependencies:\n\n```bash\npnpm install\n```\n\n4. Build the project (TeaVM build step for WASM):\n\n```bash\nbash ./support/make.sh\n```\n\n5. Run the front-end tests (may install browser via Puppeteer):\n\n```bash\npnpm exec grunt\n```\n\n6. Run style checks:\n\n```bash\npnpm exec eslint ./js/*.js\npnpm exec eslint ./test/*.js\n```\n\n7. Run a local web server (such as Python http.server):\n\n```bash\npython -m http.server\n```\n\n8. Visit the local hosted webpage using any web browser at the given address.\n\n### Additional resources\nWe have continuous integration and deployment through GitHub actions. For additional information about development, see [DEVELOPING.md](https://github.com/SchmidtDSE/kigali-sim/blob/main/DEVELOPING.md). If you are contributing, see [CONTRIBUTING.md](https://github.com/SchmidtDSE/kigali-sim/blob/main/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](https://github.com/SchmidtDSE/kigali-sim/blob/main/CONTRIBUTING.md#use-of-generative-ai).\n\n\u003cbr\u003e\n\n## Open Source\nWe thank the following Open Source libraries and resources:\n\n- [ACE Editor](https://ace.c9.io/) under [BSD-3](https://github.com/ajaxorg/ace/blob/master/LICENSE).\n- [ANTLR4](https://www.antlr.org/) under [BSD-3](https://www.antlr.org/license.html).\n- [Apache Commons CSV](https://commons.apache.org/proper/commons-csv/) under [Apache-2.0](https://github.com/apache/commons-csv/blob/master/LICENSE.txt).\n- [AWS Lambda Java Core](https://github.com/aws/aws-lambda-java-libs) under [Apache-2.0](https://github.com/aws/aws-lambda-java-libs/blob/main/LICENSE).\n- [AWS Lambda Java Events](https://github.com/aws/aws-lambda-java-libs) under [Apache-2.0](https://github.com/aws/aws-lambda-java-libs/blob/main/LICENSE).\n- [Chart.js](https://www.chartjs.org/) under [MIT](https://github.com/chartjs/Chart.js/blob/master/LICENSE.md).\n- [D3](https://d3js.org/) under [ISC](https://github.com/d3/d3/blob/main/LICENSE).\n- [ESLint]((https://eslint.org/)) under [MIT](https://github.com/eslint/eslint/blob/main/LICENSE).\n- [JSDoc](https://jsdoc.app/) under [Apache-2.0](https://github.com/jsdoc/jsdoc/blob/main/LICENSE).\n- [Papa Parse](https://www.papaparse.com/) under [MIT](https://github.com/mholt/PapaParse/blob/master/LICENSE).\n- [Popper](https://popper.js.org/) under [MIT](https://github.com/floating-ui/floating-ui/blob/master/LICENSE).\n- [Prism.js](https://prismjs.com/) under [MIT](https://github.com/PrismJS/prism/blob/v2/LICENSE).\n- [Public Sans](https://public-sans.digital.gov/) under [OFL-1.1](https://github.com/uswds/public-sans/blob/master/LICENSE.md).\n- [QUnit](https://qunitjs.com/) under [MIT](https://github.com/qunitjs/qunit/blob/main/LICENSE.txt).\n- [SVG Spinners](https://github.com/n3r4zzurr0/svg-spinners?tab=readme-ov-file) under [MIT](https://github.com/n3r4zzurr0/svg-spinners?tab=readme-ov-file)\n- [Tabby](https://github.com/cferdinandi/tabby) under [MIT](https://github.com/cferdinandi/tabby/blob/master/LICENSE.md).\n- [Tippy](https://atomiks.github.io/tippyjs/) under [MIT](https://github.com/atomiks/tippyjs/blob/master/LICENSE).\n- [Webpack](https://webpack.js.org/) under [MIT](https://github.com/webpack/webpack/blob/main/LICENSE).\n- [Global Plastics AI Policy Tool](https://global-plastics-tool.org/) under [BSD-3-Clause](https://github.com/SchmidtDSE/plastics-prototype/blob/main/LICENSE.md).\n- [Josh](https://joshsim.org/) under [BSD-3-Clause](https://github.com/SchmidtDSE/josh/blob/main/LICENSE.md).\n\nWe also use colors from [ColorBrewer 2.0](https://colorbrewer2.org/) 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](https://ozone.unep.org/lists-substances-and-blends) for Global Warming Potential (GWP) values of substances and refrigerant blends. See `editor/json/known_gwp.json`. Additionally, [Pandoc](https://pandoc.org/) under [GPL-2.0](https://github.com/jgm/pandoc/blob/master/COPYRIGHT) 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.\n\n\u003cbr\u003e\n\n## License\nThis project's code is available under the [BSD license](https://github.com/SchmidtDSE/kigali-sim/blob/main/LICENSE.md). All documentation is available under the Creative Commons [CC-BY 4.0 International License](https://creativecommons.org/licenses/by/4.0/deed.en).\n\nThis 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschmidtdse%2Fkigali-sim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschmidtdse%2Fkigali-sim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschmidtdse%2Fkigali-sim/lists"}