User Guide

PIBS User Guide — Zero to Hundred

This is a complete, practical walkthrough of PIBS: installing it, running both GUIs, understanding every input and output, and working through real worked examples. Everything here uses the example presets already bundled in pibs/examples/ — no invented numbers. For the physics behind the numbers, see Theory.

1. Which interface do I use?

	Desktop app (run_pibs.py)	Web app (streamlit_app.py)
Forward calculation (design → performance)	✅	✅
Constrained design (targets → web/length)	✅	❌
Optimization (min bore volume / min length)	✅	❌
Tube strength / autofrettage	✅	❌
Guidance diagrams	✅	❌
Runs without a display / on a server	❌ (needs tkinter + a screen)	✅
Conventional guns	✅	✅
Recoilless guns	✅	✅

Start with the web app if you just want to explore designs or don't have a desktop session; use the desktop app once you need constrained design, structural sizing, or optimization.

2. Installation

git clone https://github.com/timeout187/Phoenix-s-Interior-Ballistic-Solver-PIBS.git
cd Phoenix-s-Interior-Ballistic-Solver-PIBS
python -m venv .venv

Activate the virtual environment:

# Windows
.venv\Scripts\activate.bat
# Linux / macOS
source .venv/bin/activate

Install what you need:

pip install -e ".[dev]"          # desktop app + dev tools
pip install -e ".[streamlit]"    # web app
pip install -e ".[dev,streamlit]"  # both

Requires Python ≥ 3.9 (the desktop app additionally needs a system with tkinter and a display — standard on Windows/most Linux desktop installs, not available on headless servers).

3. Running the apps

python run_pibs.py            # desktop GUI
streamlit run streamlit_app.py  # web GUI, opens http://localhost:8501

4. Worked example #1 — Web GUI, Demo mode, conventional gun

This walks through exactly what you'll see using the bundled Guns/76x385_ZiS-3_UOF-354AM preset — the 76×385mm round fired from the Soviet ZiS-3 divisional gun (M1942).

1. Open the web app, leave the sidebar on "Demo (load example)".
2. In the Example dropdown, pick Guns/76x385_ZiS-3_UOF-354AM.
3. Click Load & Solve.

The design loaded (verbatim from the bundled JSON, not re-typed) is:

Parameter	Value
Caliber	76.2 mm
Shot mass	6.2 kg
Charge mass	1.08 kg
Chamber volume	1.484 L
Chambrage ratio	1.1
Start pressure	30.0 MPa
Travel	2687.0 mm
Web (grain thickness)	8.2872 mm
Propellant	[GAU Table] composition
Grain geometry	SEVEN_PERF_CYLINDER (7-perforation cylinder)

Solved result (actual solver output, reproducible by running the preset yourself):

Metric	Computed	Design target (from preset)
Muzzle velocity	684.8 m/s	680 m/s
Peak avg. pressure	261.3 MPa	261.3 MPa
Time to shot exit	7.32 ms	—
Burnout travel	1548 mm (57.6% of barrel)	—
Thermal efficiency	33.0%	—
Ballistic efficiency	28.9%	—
Piezometric efficiency	51.9%	—

A few points from the full trace (see §7 for what each column means):

Event	Time	Travel	Burnt	Velocity	Avg P	Breech P	Shot P
SHOT_START	0 ms	0 mm	2.4%	0 m/s	30.0 MPa	30.7 MPa	28.6 MPa
PEAK_AVG_P	2.80 ms	262 mm	51.7%	270 m/s	261.3 MPa	267.6 MPa	248.9 MPa
BURNOUT	5.57 ms	1548 mm	100%	603 m/s	100.2 MPa	102.8 MPa	95.3 MPa
SHOT_EXIT	7.32 ms	2687 mm	100%	684.8 m/s	53.2 MPa	54.6 MPa	50.6 MPa

Notice breech pressure is always a bit higher than average, which is always higher than shot-base pressure — that's the pressure gradient from §6 of the theory doc, not numerical noise. Also notice the propellant is fully burnt (100%) well before the shot exits (57.6% of the way down the barrel) — pressure past that point falls off purely from volume expansion of already-generated gas, with no more energy being added.

5. Worked example #2 — Recoilless gun (answers "can I use this for recoilless?")

Yes — recoilless guns are fully supported, in both GUIs, with the same solver fidelity as conventional guns. Four recoilless presets ship with the project, covering 75mm–105mm designs, and every one of them solves to within ~1% of its stated design target (see §8). Here's Recoilless/105x607_Type75(M40A1)_HEAT-FS — the 105mm HEAT-FS round for the Type 75 (M40A1) recoilless rifle:

1. In the web app sidebar, either pick this preset under Demo (load example), or select Manual input → Gun Type RECOILLESS (which pre-fills matching defaults for a from-scratch recoilless design).

Parameter	Value
Caliber	105.0 mm
Shot mass	7.96 kg
Charge mass	3.6 kg
Chamber volume	7.2 L
Chambrage ratio	1.7
Start pressure	5.48 MPa
Travel	2683.0 mm
Web	0.834 mm
Propellant	Pyroxylin
Grain geometry	FOURTEEN_PERF_ROSETTE
Nozzle expansion ratio	1.125
Nozzle efficiency	100%

Solved result:

Metric	Computed	Design target
Muzzle velocity	502.9 m/s	503 m/s
Peak breech pressure (the design's constraint)	71.30 MPa	71.3 MPa
Thermal efficiency	7.3%	—
Ballistic efficiency	6.2%	—
Piezometric efficiency	71.0%	—

Compare the 7.3% thermal efficiency here against 33.0% for the conventional ZiS-3 above, using a similar-caliber, similar-pressure design — that ~4-5× efficiency gap is the real, expected physical cost of a recoilless gun venting propellant gas out the nozzle to cancel recoil (see Theory §9), not a bug.

What recoilless-specific outputs mean: Nozzle Expansion Ratio is the nozzle exit-to-throat area ratio; Nozzle Efficiency is a 0-100% loss factor for non-ideal nozzle flow. If a combination of caliber, chambrage and expansion ratio can't physically fit a large-enough throat into the breech face, the solver raises "Achieving recoilless condition necessitates a larger throat area than could be fit into breech face" — an infeasible-design error, not a numerical failure; widen the chambrage ratio or nozzle expansion to fix it.

What's not available for recoilless guns in the web GUI (desktop app only): constrained design (solving for web/length from a velocity+ pressure target) and tube structural sizing.

6. Manual input mode (either gun type)

Use this to explore a design of your own rather than a bundled preset. Switching the Gun Type radio immediately reloads all fields with a self-consistent starting design for that type (a conventional gun and a recoilless gun need very different pressure/web combinations — see the two worked examples above for why) — you can just click Solve Gun immediately to see a working baseline, then change fields from there.

Field reference (web GUI manual mode):

Field	Meaning	Core parameter
Caliber	Bore diameter	caliber
Shot Mass	Projectile mass	shot_mass
Charge Mass	Propellant mass	charge_mass
Chamber Volume	Volume behind the shot at start	chamber_volume
Travel / Barrel Length	Distance shot travels in the bore	length_gun
Chambrage Ratio	Chamber cross-section ÷ bore cross-section	chambrage
Start Pressure	Pressure at which the shot begins to move	start_pressure
Web	Grain half-thickness × 2 (full web)	web
Bore Resistance	Friction/engraving work, as %	drag_coefficient
Propellant Composition	Chemical propellant (from propellants.csv)	propellant.composition
Grain Geometry	Physical grain shape	propellant.main_geom
Grain 1/α, 1/β	Shape ratios (see Theory §3.1)	propellant.main_r1/r2
Sample Points	How many points to sample along the trace	step
Nozzle Expansion Ratio (recoilless only)	Nozzle exit area ÷ throat area	nozzle_expansion
Nozzle Efficiency (recoilless only)	Non-ideal nozzle flow loss factor	nozzle_efficiency

7. Reading the output

Summary metrics: muzzle velocity, time to exit, the three peak pressures (average/breech/shot-base — see Theory §6 for why they differ), burnout travel, and the three efficiency figures (Theory §10).

Table Data — one row per named event plus evenly-spaced samples:

Column	Meaning
Event	SHOT_START, SAMPLE, FRACTURE, BURNOUT, PEAK_*_P, SHOT_EXIT (see Theory §8)
Time	Elapsed since ignition
Travel	Shot position in the bore
Burnup	Fraction of propellant consumed (ψ, as %)
Velocity	Shot velocity
Avg / Breech / Shot Pressure	The three pressure definitions
Temperature	Local gas temperature (Nobel-Abel EOS)

Download the table as CSV from the button below it for further analysis (spreadsheets, plotting elsewhere, etc.).

8. Running the full bundled example set

run_examples.py (repo root) solves every preset under pibs/examples/ — the same corpus the web GUI's demo dropdown draws from — and checks the computed muzzle velocity and design-constrained peak pressure against the target values recorded in each preset:

python run_examples.py                 # every example
python run_examples.py Recoilless       # only examples whose label contains "Recoilless"
python run_examples.py --csv out.csv    # also dump every sampled event of every example

Current result running the full corpus: 48 of 48 examples solve successfully, with computed muzzle velocity within ~1-2% of the stated target for essentially every case (autocannons, howitzers, gun-howitzers, and all 4 recoilless designs). This script is a regression check: if you modify the solver core, re-run it — any example that starts failing or drifting materially off-target is worth investigating.

To add a new case, drop a new preset JSON in the same schema under pibs/examples/ (e.g. save one from the desktop app's Design → Save) — run_examples.py and the web GUI's demo dropdown both pick it up automatically, no code changes needed.

9. Troubleshooting

Errors are raised by the solver itself with a specific cause — the common ones:

Error	Cause	Fix
"Initial burnup fraction is solved to be negative"	Loading density Δ = charge_mass / chamber_volume exceeds the propellant's own solid density (ρ_p, ~1600 kg/m³ for most compositions) — physically, more mass than could fit as solid propellant	Reduce charge mass or increase chamber volume so Δ < ρ_p
"...greater than unity"	Start pressure too high relative to loading density (roughly, start_pressure > f·Δ)	Lower start pressure, or raise charge mass / lower chamber volume to increase Δ
"Squib load condition detected"	Shot stalls in the bore — insufficient propulsive force	Web/geometry mismatch (see below), or genuinely too little charge for the shot mass and travel
"Nobel-Abel EoS is generally accurate enough below 600MPa..."	Pressure exceeded the model's validity ceiling	Web too small / geometry too fast-burning for the charge and chamber — the design is likely unrealistic as specified
"Achieving recoilless condition necessitates a larger throat area..."	Recoilless-only: nozzle can't physically fit	Increase chambrage ratio or reduce nozzle expansion ratio
"Auxiliary grains must complete combustion in advance of the primary grains"	Mixed-charge web ratio inconsistent	Adjust Web Aux / Main so the auxiliary grain burns out first

The single most common mistake building a design from scratch: pairing a web thickness tuned for one grain geometry with a different geometry default. A given web value means something very different for a sphere vs. a 7-perforation cylinder (surface-to-volume ratio and burn progression are shape-dependent — see Theory §3.1) — the web GUI's manual mode avoids this by keying its defaults to grain geometry per gun type, but if you change geometry, re-check the web value makes sense for that shape (or start from a bundled preset with that geometry and adjust from there).

10. Where to go next

• Theory — the full physical/numerical model.
• pibs/examples/ — all 48 bundled reference designs, organized by category (Autocannons, Guns, Howitzers, Gun-Howitzer, Recoilless). excluded_examples/ holds additional presets (including Naval) not wired into the demo dropdown/runner by default.
• pibs/ballistics/resource/propellants.csv — the 40 bundled propellant compositions with literature sourcing.
• Desktop app Data menu — load/save designs and propellants, including your own.