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	✅	✅
Save/load custom design & propellant files	✅	❌ (bundled presets only)
Localization (English / 中文)	✅	❌ (English only)

Both interfaces now cover the same calculations. Use the web app if you don't have a desktop session, want to explore designs quickly, or are deploying somewhere headless; use the desktop app if you need to save/load your own custom design or propellant files, or want the Chinese-language interface.

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 §10 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 §11). 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.

Constrained design and tube structural sizing for recoilless guns are also available in the web GUI — see §7 and §8.

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. Constrained design mode (web GUI)

Select Constrained design in the sidebar. This solves the inverse problem (Theory §11.1): given a target velocity and pressure, a chosen charge-to-shot mass ratio, and a chamber loading density, it finds the grain web size and barrel length that hit those targets exactly — rather than you specifying web/length directly.

Worked example: leave everything at its CONVENTIONAL default (which mirrors the ZiS-3 example's real charge ratio and loading density — Charge / Shot Mass Ratio 0.174, Load Fraction 45.5%) and click Solve Constrained Design. Solved output (reproducible):

Solved quantity	Value	Reference (ZiS-3 actual)
Web	8.2849 mm	8.2872 mm
Chamber Volume	1.482 L	1.484 L
Barrel Length	2596.7 mm	2687.0 mm
Charge Mass	1.079 kg	1.08 kg

Running the resulting design forward gives muzzle velocity 680.0 m/s and peak avg. pressure 261.3 MPa — exactly the target values entered, by construction. The small differences from the ZiS-3 reference numbers come from the constrained solver finding a self-consistent design meeting those two targets at that charge ratio and loading density, not necessarily bit-identical geometry to the historical gun (which had other constraints, like a fixed production barrel length, that this solve doesn't know about).

Optimize load fraction: toggle this on to have the solver search for the loading density that minimizes chamber+barrel volume or barrel length alone (find_min_v(), Theory §11.2), instead of using the fixed value you specify. This searches the entire feasible range and can land near the Max Barrel Length search ceiling — if solving fails with "Solution requires excessive tube length", raise that ceiling or narrow the charge ratio.

Lock barrel length: check this to fix barrel length yourself and solve only for web size (known_bore=True internally) — useful when the barrel length is a hard constraint (e.g. matching an existing gun) rather than something to solve for.

This mode works identically for RECOILLESS — switching Gun Type reloads matching defaults (based on the 105mm M40A1 example) and adds the Nozzle Expansion Ratio / Nozzle Efficiency fields, same as manual input mode.

8. Tube strength & autofrettage (web GUI)

After any successful solve — demo, manual, or constrained — an optional "Tube strength & autofrettage" section appears below the results. Expand it, set material density, yield strength, and safety factor, choose whether to autofrettage, and click Compute Tube Strength (Theory §11.3).

It reports estimated tube mass and plots the barrel cross-section: bore radius, outer radius, and (if autofrettaged) the elastic-plastic junction radius, along the length of the tube. For the ZiS-3 constrained-design result above with steel at 7850 kg/m³ density, 1000 MPa yield strength, 1.35 safety factor, and autofrettage enabled, this comes out to ~55 kg of tube — a plausible mass for a 76mm gun barrel.

9. Guidance diagram mode (web GUI)

Select Guidance diagram in the sidebar. This sweeps a grid of charge-to-shot mass ratios and chamber loading densities and plots every combination that reaches the target velocity/pressure (Theory §11.4) — a scatter of feasible designs, colored by the resulting barrel length, so you can see the volume/length trade-off across the whole design space at a glance, plus a full data table (downloadable as CSV).

This mode runs the sweep sequentially in the browser session (no multiprocessing — see Theory §11.4 for why), so it's slower than the desktop app's parallelized version. The form caps the sweep at 40 charge-ratio steps and warns if you exceed it; keep Step no finer than you need. A default-sized sweep (charge ratio 0.10–0.30 in steps of 0.02, 5% load-fraction steps) for a conventional gun takes on the order of 30 seconds and finds several dozen feasible designs.

10. 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.).

11. 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.

12. 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
"Solution requires excessive tube length..."	Constrained design only: the chosen charge ratio / loading density can't reach the design velocity within the barrel-length search ceiling	Raise Max Barrel Length, increase charge ratio, or lower the velocity target
"Propellant load too low to achieve design velocity"	Constrained design only: even at 100% burn, this charge can't reach the theoretical max velocity v_j (Theory §2) ≥ the target	Increase charge-to-shot mass ratio
"Design velocity exceeded before peak pressure point..."	Constrained design only: the shot would reach the target velocity before pressure peaks — an inconsistent target/charge combination	Lower the velocity target or raise the pressure target relative to it

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).

13. 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.