A physics solver for the interior ballistics of guns — closed-breech and recoilless — covering forward calculation, constrained design, optimization, tube strength, and guidance diagrams, with both a desktop GUI and a browser-based GUI.
中文说明 (Chinese) · MIT License · Theory · User Guide · Wiki · Live reference site
The desktop GUI mid-solve: pressure/velocity trace (top), barrel pressure profile (bottom), and the resulting design summary (left panel) for a 76mm gun.
- What is PIBS?
- Which interface should I use?
- Quick start
- The theory, in brief
- What's included
- Installation
- Documentation
- Bundled data
- Contributing
- Credits
- License
Given a gun's caliber, projectile mass, propellant charge, and barrel, PIBS computes the full pressure and velocity trace from ignition to muzzle exit — how hard the propellant pushes, how fast the shot accelerates, and how pressure differs between the breech and the shot base at every instant. Point it the other way and it solves the inverse problem: given a target muzzle velocity and peak pressure, it finds the grain size and barrel length that will hit them.
The physics is the "Serebryakov system" of reduced-variable interior ballistics — the formulation used in Soviet and Chinese ordnance literature — solved numerically in pure Python (adaptive Runge-Kutta-Fehlberg integration, Dekker root-finding, Golden Section Search for peaks). See The theory, in brief below, or the full derivation in docs/THEORY.md.
It handles both conventional closed-breech guns and recoilless guns (which vent propellant gas through a rear nozzle to cancel recoil) with equal fidelity — validated against 48 bundled real-world reference designs (autocannons, howitzers, tank guns, and recoilless rifles), each solving within ~1-2% of its historically documented performance.
Both the desktop app and the browser app share the same solver core and now cover the same calculations:
Desktop app (run_pibs.py) |
Web app (streamlit_app.py) |
|
|---|---|---|
| Forward calculation (design → performance) | ✅ | ✅ |
| Constrained design (targets → web/length) | ✅ | ✅ |
| Optimization (min bore volume / min barrel length) | ✅ | ✅ |
| Tube strength / autofrettage | ✅ | ✅ |
| Guidance diagrams (design-space sweep) | ✅ | ✅ |
| Conventional guns | ✅ | ✅ |
| Recoilless guns | ✅ | ✅ |
| Runs headless / on a server, no display needed | ❌ | ✅ |
| Save/load custom design & propellant files | ✅ | ❌ (bundled presets only) |
| Localization (English / 中文) | ✅ | ❌ (English only) |
Use the web app if you don't have a desktop session, want to explore designs quickly, or are deploying somewhere like Streamlit Community Cloud. Use the desktop app if you need to save/load your own custom design or propellant files, or want the Chinese-language interface.
git clone https://github.com/timeout187/Phoenix-s-Interior-Ballistic-Solver-PIBS.git
cd Phoenix-s-Interior-Ballistic-Solver-PIBS
python -m venv .venv
.venv\Scripts\activate.bat # Windows — use `source .venv/bin/activate` on Linux/macOS
pip install -e ".[dev,streamlit]"Then run either interface:
python run_pibs.py # desktop GUI
streamlit run streamlit_app.py # web GUI, opens http://localhost:8501Fastest way to see it work: open the web GUI, leave the sidebar on "Demo (load example)", pick any preset from the dropdown (e.g. Guns/76x385_ZiS-3_UOF-354AM), and click Load & Solve. No input required — it solves a real, historically-documented gun design instantly and shows the full pressure/velocity trace.
A full step-by-step walkthrough of every mode in both GUIs — including a worked constrained-design example and a worked recoilless-gun example with real numbers — is in docs/USER_GUIDE.md.
(Full derivation with equations: docs/THEORY.md)
- Reduced (dimensionless) variables. Pressure, travel, velocity, and time are all non-dimensionalized against charge- and gun-specific scales, which is what makes the same equations apply across wildly different calibers and charges.
- Propellant burns via a cubic form function. How fast the burning surface area grows or shrinks as a grain burns depends on its geometry (sphere, cylinder, strip, or multi-perforated grains) — multi-perforated grains burn progressively (surface area increasing) until the perforations merge, then degressively as slivers burn out, which is why they're standard in high-performance guns.
- Pressure follows from energy conservation and the Nobel-Abel (covolume) equation of state, without needing a separate energy ODE.
- Breech, average, and shot-base pressure are three different numbers at three different times — solved via one of three closed-form "Lagrange problem" models (Lagrange / Pidduck / Mamontov) for how gas pressure distributes along a tube with a moving mass at one end.
- Recoilless guns add two more tracked state variables (outflow mass fraction and a reduced temperature ratio) and size the rear nozzle throat so its thrust exactly cancels the breech reaction — the "recoilless condition." This is also why recoilless guns are markedly less efficient than closed-breech guns for the same propellant: energy that would accelerate the shot is deliberately vented instead (confirmed by the bundled examples: ~7% thermal efficiency for a 105mm recoilless design vs. ~33% for a similar-pressure 76mm conventional gun).
- Everything is solved numerically: adaptive Runge-Kutta-Fehlberg for the ODE system, the Dekker method (a Brent's-method relative) for root-finding, and Golden Section Search for locating pressure peaks.
The interior ballistics problem is formulated after the system named after M.E. Serebryakov, widely used in the Soviet Union and People's Republic of China, solved in reduced form for both conventional and recoilless guns. Supports shaped propellant described by a cubic form function, including sphere, strip, cylinder, and multi-perforated cylinder/prism/rosette grains.
- Forward calculation: given a design, compute its full pressure/velocity trace.
- Constrained design: given target velocity and pressure, solve for the grain web size and barrel length.
- Optimization: solve the minimum bore volume, or minimum barrel length, problem for a given performance target.
- Tube strength & autofrettage: size barrel wall thickness against a Tresca yield criterion, with or without autofrettage.
- Guidance diagrams: sweep the charge-ratio / loading-density design space and map every feasible design meeting a target.
40 bundled propellant compositions sourced from public literature (pibs/ballistics/resource/propellants.csv), hot-loadable/extensible. 48 bundled real gun/propellant reference designs across autocannons, howitzers, gun-howitzers, tank guns, and recoilless rifles (pibs/examples/) — every one validated to solve within ~1-2% of its documented performance (see docs/USER_GUIDE.md §8 or run python run_examples.py yourself). Design save/load and data export supported in the desktop app.
Compromising between ease of development, distribution, and runtime speed, the following algorithms are implemented in pure Python:
- Numerical integration up to user-specified precision using high-order, adaptive Runge Kutta Fehlberg method.
- Root-finding via the Dekker method, a variant of Brent's method that opportunistically employs polynomial and bisection steps to speed up convergence.
- Maxima found via Golden Section Search (GSS).
Requires Python ≥ 3.9. The desktop app additionally needs tkinter and a display (standard on Windows/most Linux desktop installs, not available on headless servers — use the web app there instead).
git clone https://github.com/timeout187/Phoenix-s-Interior-Ballistic-Solver-PIBS.git
cd Phoenix-s-Interior-Ballistic-Solver-PIBS
python -m venv .venvActivate the virtual environment:
# Windows
.venv\Scripts\activate.bat
# Linux / macOS
source .venv/bin/activateInstall what you need:
pip install -e ".[dev]" # desktop app + dev tools
pip install -e ".[streamlit]" # web app
pip install -e ".[dev,streamlit]" # bothRun it:
python run_pibs.py # desktop GUI
streamlit run streamlit_app.py # web GUI
python generate_executable.py # build a standalone Windows executable
python run_examples.py # solve every bundled example and check it against its target| Document | Covers |
|---|---|
docs/THEORY.md |
The full theoretical/numerical model: reduced-variable ODE system, propellant form functions, the Nobel-Abel equation of state, the three pressure-gradient solutions, the recoilless nozzle extension, numerical methods, and efficiency metrics. |
docs/USER_GUIDE.md |
Zero-to-hundred usage instructions for both GUIs: install, every mode, a full parameter glossary, worked examples (conventional and recoilless, with real solved numbers), and a troubleshooting table for every error the solver can raise. |
| Project Wiki | The same Theory and User Guide content, browsable natively on GitHub with sidebar navigation. |
| Live reference site | The same content again, as a single formatted page with a table of contents. |
CONTRIBUTING.md |
Open items looking for help (Linux/macOS compatibility, new example designs). |
pibs/ballistics/resource/propellants.csv— 40 propellant compositions with literature sourcing.pibs/examples/— 48 real gun/propellant reference designs, organized by category (Autocannons, Guns, Howitzers, Gun-Howitzer, Recoilless).excluded_examples/holds additional presets (including naval guns) not wired into the demo dropdown by default.- Both are used directly by the demo mode in the web GUI and by
run_examples.py— add a new design by dropping a JSON file in the same schema intopibs/examples/(e.g. saved from the desktop app's Design → Save); nothing else needs to change.
Contributions are welcome — issues and pull requests for features or problems encountered are appreciated. See CONTRIBUTING.md for known open items (Linux/macOS compatibility work, new example designs and propellant sources).
PIBS was created and is maintained by Jinpeng Zhai, published at Prethea-Phoenixia/Phoenix-s-Interior-Ballistic-Solver-PIBS — all of the interior-ballistics modeling, the desktop GUI, the bundled example designs and propellant data, and the underlying research are their work.
This fork — timeout187/Phoenix-s-Interior-Ballistic-Solver-PIBS — is maintained by Hasan Ahmed (timeout187), who directed and specified everything added here: the browser-based (Streamlit) GUI covering the same calculations including constrained design, optimization, tube strength, and guidance diagrams; the docs/THEORY.md and docs/USER_GUIDE.md reference documentation; run_examples.py; and this GitHub Pages / wiki publishing setup — implemented with Claude (Anthropic).
- tcl/tk themes "awdark" & "awlight" from awthemes
- Monospaced, CJK-compatible font Sarasa Gothic
The interior-ballistics model follows (as cited in the source and bundled example descriptions):
- 金志明 (2014). 《枪炮内弹道学》(Interior Ballistics of Guns).
- 鲍廷钰，邱文坚 (1995). 《内弹道学》(Interior Ballistics).
- 王连荣，张佩勤 (1987). 《火炮内弹道计算手册》(Gun Interior Ballistics Calculation Handbook), National Defense Industry Press.
- 兵器工业部第二管理局 (1982). 《国产火炮手册》(Domestic Gun Handbook).
- Multiple Russian-language ordnance service manuals (cited per-example in
pibs/examples/*.json).
PIBS is free and open-source software released under the MIT License. You may use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies, for any purpose, commercial or non-commercial, provided the copyright notice and license text are included. See LICENSE for the full text.
The original upstream project was released into the public domain under the Unlicense, whose terms explicitly permit relicensing — this fork (including the original code it incorporates) is licensed under MIT as noted above.