An open Python toolkit for conceptual refinery sizing that shows how different crudes change yields, sulfur and catalytic cracker temperature, and flags crudes that push the plant past its limits.
Open-source tools · How-to · Refining & Petrochemicals
How to use refinery-design-opensource: test what a crude does to a refinery
Revised
· v1.0.0 · what changed
Code: github.com/herrrickshaw/refinery-design-opensource
Watch the walkthrough
Watch on YouTube: youtu.be/hRybax78vn0
What it is for
Different crudes load a refinery very differently. The plant must stay inside its unit limits, or the crude is a poor fit. This toolkit lets you ask: which crudes can run, where does the fluid catalytic cracker (FCC) overheat, and how complex is the plant.
It covers assays, distillation, FCC heat balance and riser behaviour, blending, gross refining margin, petrochemicals and a Nelson complexity check against a published refinery (Paradip). It is conceptual sizing, not detailed engineering.
Who it is for
- Refining and petrochemical analysts who want a transparent first-pass tool
- Students learning how crude quality affects a plant
- Non-programmers who want an AI assistant to run the examples and explain the output
- Detailed engineering design or licensor-grade work. Use a licensed simulator for that.
- Anything needing reforming, hydrocracking, alkylation, sulfur recovery or a hydrogen plant. These are not covered.
- Treating FCC yields as plant-validated. The kinetics are not fitted to plant data.
What you need
| Requirement | Why | How to get it |
|---|---|---|
| Python 3.10 or newer | required by pyproject.toml | python.org or brew install python |
| pip packages | the toolkit installs itself with streamlit as a dependency; pytest and openpyxl come with the dev extra | pip install -e ".[dev]" |
| Disk and time | small install; the test suite took about 15 to 41 seconds in the demo | a normal laptop is enough |
| Not needed | no API key, no database, no GPU, no licensed simulator | all data is public or built in |
Get the code and an AI assistant
You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:
| Tool | What you need | Best for |
|---|---|---|
| GitHub | Free account to fork or star; git to clone, or the green Code button, then Download ZIP, or open in Codespaces | Getting the code and keeping up with updates |
| Claude Code | Claude subscription or API key; run claude inside the cloned folder | Letting the AI read and run the whole repo |
| Gemini CLI | Google account; run gemini inside the cloned folder | The same hands-on workflow with Gemini |
| Claude.ai, Gemini or ChatGPT in the browser | A chat account; upload README.md and the files you care about (or paste the output of git ls-files) | Understanding the project and asking questions without installing anything |
| Other tools (Copilot Chat, Cursor, Codex CLI) | Open the cloned folder in the tool and point it at README.md first | Editing and extending the code |
git clone https://github.com/herrrickshaw/refinery-design-opensource.git
cd refinery-design-opensource
claude # or: geminiInstall
- Get the code
git clone https://github.com/herrrickshaw/refinery-design-opensource.git cd refinery-design-opensource - Create an environment and install with test tools
python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]"
Quick start: commands and what you should see
Run the tests
pytest -q267 passed (the README says 263; the demo counted 267). Run time was 41.26 s the first time and 15.45 s on a second run.
Run eight crudes through one refinery
python examples/full_refinery_worked_example.pyA table by crude. Bakken (API 44.0) gives 95.1% light products and a regenerator at 682 C. Cold Lake Blend (API 19.5) gives 72.3% light products, 16.7% petcoke and 867 C. Six of the eight crudes carry a ! warning for FCC regenerator temperature.
See what blending heavy crude into a light base does (same script)
python examples/full_refinery_worked_example.pyAdding Cold Lake to Azeri BTC raises regenerator temperature from 677 C at 0% to 800 C at 50%, which exceeds the roughly 760 C limit. Light products fall from 93.6% to 82.4%.
Look at the FCC heat balance and riser
python examples/fcc_worked_example.pyFor Dalia VGO at a 530 C riser outlet: regenerator 755 C, conversion 67.1 wt%, gasoline 47.45 wt%, coke 5.90 wt%. A sweep from 500 to 560 C shows conversion rising from 56.6 to 75.9 wt%.
Check the model against a real refinery
python examples/paradip_check.pyNelson complexity for Paradip ranges from 7.55 to 11.92 depending on unit counting, against a published 10.6. It brackets 10.6 only when ambiguous units are included. A fitted crude basket predicts vacuum gas oil at 28.1% of crude against a published 28.0%.
Open the interactive app (from the README, not run in the demo)
streamlit run streamlit_app.pyA browser app for the same calculations.
Ways to use it
| Method | How it works |
|---|---|
| Command line | Run any script in examples/. The README lists eleven, including petrochemical evaluation, crude sourcing, safety review and a dual-feed cracker. |
| Library import | Import from the refinery_design package (assay, distillation, fcc, grm, petrochemical, safety and more). |
| Streamlit app | streamlit run streamlit_app.py for an interactive version. |
| Through an AI assistant | Open the folder in Claude Code or Gemini CLI, or upload the README to a chat assistant, and ask for runs and explanations in plain language. |
Sample prompts for your AI assistant
Copy, paste and edit the parts in [brackets].
- Explain this repo in plain English. What is an FCC and why does regenerator temperature matter?
- Run examples/full_refinery_worked_example.py and tell me which crudes are flagged and why.
- Add my crude, with API [value], sulfur [value] wt% and TAN [value], and show how it compares with Bakken and Cold Lake.
- How much Cold Lake can I blend into [base crude] before the regenerator passes about 760 C?
- Which parts of this model are calibrated to published ranges, and which are only directional heuristics?
- What would I need to add to cover hydrocracking or reforming?
Limits and honest caveats
- Conceptual sizing, not detailed engineering design, and not a substitute for a licensed simulator or licensor design.
- FCC kinetics are calibrated to typical published ranges, not fitted to plant data.
- Feed-quality effects are directional heuristics with illustrative magnitudes.
- The Paradip Nelson index brackets the published 10.6 only with ambiguous-unit readings.
- Not covered: reforming, hydrocracking, alkylation, sulfur recovery, hydrogen plant.
- The README quotes 263 tests; the demo ran 267. Interactive app steps come from the README and were not captured.
Sources: the repository README (herrrickshaw/refinery-design-opensource), pyproject.toml, the examples folder and the demo run of 18 October 2026.
- v1.0.0 — 18 October 2026 — first published.
About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.
