SRTC User Manual

Running SRTC from the release bundle. These docs are written against the srtc command line. In the distributed bundle that command lives inside the container, so run it through Compose from the unpacked bundle directory:

docker compose run --rm -v "$PWD":/io backend srtc --help

Files you pass in should sit under the mounted /io, and that is also where to write outputs. On Linux the container runs as an unprivileged user, so add --user "$(id -u):$(id -g)" when writing to a mounted directory or the run fails with a permission error creating the output directory:

docker compose run --rm --user "$(id -u):$(id -g)" -v "$PWD":/io backend \
  srtc -i examples/fwd_transport/oltaris_al_si.deck -o /io/out/results.out \
     --depth-g-cm2 1.0 --histories 100000 --seed 1

The physics libraries are already in place, and the shipped example decks resolve against them, so the examples below run as written. See Downloads to get the bundle, and the Viewer guide for the browser GUI, which needs none of this.

This manual explains how to build, configure, run, and interpret results from SRTC (Space Radiation Transport Code — Rust prototype). It is written for analysts running 1D slab shielding studies, not for developers modifying the source tree.

For module internals and physics models, see Architecture and program flow and Physics and data references.

1. What SRTC does

SRTC transports primary space-radiation particles through a 1D stack of shielding layers defined in areal density (g/cm²). srtc run drives the 1D forward Monte Carlo; the 3D forward and adjoint Monte Carlo engines are driven by srtc mc3d (see 3D Monte Carlo transport).

For each 1D forward MC run the code:

1. Draws primary particle histories from input spectra (see §5.9 History sampling).
2. Steps through shield layers (continuous energy loss + discrete nuclear/EM interactions).
3. Scores dose in a detector slab and transmitted particle spectra.

Supported primary sources today include protons, electrons, neutrons, and heavy ions (where tables exist). Photons are secondaries only — they are produced during transport (for example bremsstrahlung) and appear in output tallies, but cannot be specified as a primary spectrum.

Geometry is slab-equivalent (HZETRN-style), not full 3D Geant4 geometry.

2. Installation and build

SRTC is distributed as a self-contained container bundle — see Downloads. Docker is the only prerequisite.

tar xzf srtc-<version>-<arch>.tar.gz
./srtc-<version>-<arch>/install.sh
# -> http://localhost:8080

That starts the browser GUI and brings the physics libraries with it; nothing else needs installing. To use the command line described below, run it through Compose from the unpacked bundle directory:

docker compose run --rm -v "$PWD":/io backend srtc --help

3. Quick start

3.1 Single run (MCNP-style)

The recommended invocation uses -i for the input deck and -o for organized output:

srtc \
  -i examples/fwd_transport/oltaris_al_si.deck \
  -o output/al_1gcm2/results.out \
  --depth-g-cm2 1.0 \
  --histories 100000 \
  --seed 1

This creates a folder (here output/al_1gcm2/) containing:

If -o is omitted, results go to output/<deck_stem>/ by default and a CSV dose row is also printed to stdout.

4. Command-line reference

4.1 Primary mode (no subcommand)

srtc -i <input.deck|input.toml> -o <output path> [options]

History count and --sampling

The CLI flag --histories (alias --histories-per-bin) sets the history count. Its meaning depends on the sampling mode:

Deck override (recommended for reproducible studies):

TRANSPORT HISTORIES=100000 SAMPLING=FIXED_PER_BIN
TRANSPORT HISTORIES=1000000 SAMPLING=POPULATION

If the deck sets HISTORIES=, it overrides the CLI default. --sampling on the command line overrides the deck sampling mode.

Output path behaviour

When --debug is set, _debug is appended to the output directory name (e.g. output/al_1gcm2_debug/) and debug artifacts are written there alongside the normal run files.

4.2 Analysis and validation subcommands

# OLTARIS dose-vs-depth sweep (forward MC)
srtc compare-oltaris --histories 100000 --seed 1

# Shield2Dose vs SRTC forward MC (proton + electron), parallel depths
srtc compare-shield2dose --histories 100000 --jobs 48

# Shield2Dose vs forward MC, AP9 proton + AE9 electron depth sweep
srtc compare-all --histories 100000 --mg-data-dir /data/jendl-5

# 1D forward MC vs 3D adjoint MC on the same IRENE spectra (needs geometry_3d)
srtc compare-transport-modes --histories 100000 --jobs 12

# Finite vs semi-infinite slab geometry references vs forward MC
srtc compare-slab-geometries --mg-data-dir /data/jendl-5

Common options: --histories, --seed, --jobs, --data-dir, --mg-data-dir.

4.3 Data pipeline subcommands

srtc data fetch   --manifest data/manifests/default.toml
srtc data process --manifest data/manifests/default.toml --out data/processed
srtc data run-library --materials Al,Si --out /data/jendl-5
srtc data build-multigroup --materials Al,Si --out /data/jendl-5
srtc data inspect --data-dir data/processed --particle proton --material Al

4.4 Legacy run subcommand

srtc run examples/fwd_transport/oltaris_al_si.deck --histories 100000 --depth-g-cm2 1.0

Equivalent to srtc -i … with the same global options.

5. Input files

SRTC accepts NOVICE-style .deck files (recommended) or TOML configs. Decks support multi-layer shields, inline spectra, and mixed proton/electron primaries.

5.1 Deck structure

A minimal deck contains:

MATERIAL NAME=AL ...
MATERIAL NAME=SI ...
SPECTRUM PARTICLE=PROTON FILE=../test_spectrums/350kmx350kmx53deg_proton_0gcm2.csv ...
SHIELD MATERIAL=AL
DETECTOR MATERIAL=SI THICKNESS_CM=0.01 AREA_CM2=1.0
PHYSICS DATA_DIR=../data/processed
TRANSPORT EMIN_MEV=0.1 MAX_STEPS=20000 STEP_FRACTION=0.03
END

5.2 Deck cards

Comments start with #, !, or * at the beginning of a line.

The legacy SOURCE card is not accepted. Put particle type, units, and spectrum data on each SPECTRUM card.

5.3 SPECTRUM cards

Each SPECTRUM line defines one primary particle and how its fluence is tabulated.

Required field: PARTICLE (PROTON, ELECTRON, NEUTRON, … — not PHOTON).

Optional fields: UNIT, FORM, INTERP (defaults: differential, log-linear energy bins).

File-backed spectrum (traceable external archive)

SPECTRUM PARTICLE=PROTON \
  FILE=../test_spectrums/350kmx350kmx53deg_proton_0gcm2.csv \
  UNIT=PER_DAY_CM2_MEV FORM=DIFFERENTIAL INTERP=LOG_LINEAR

FILE, SPECTRUM, and PATH are equivalent field names for the CSV path.

Inline spectrum (self-contained in the deck)

SPECTRUM PARTICLE=ELECTRON UNIT=PER_DAY_CM2_MEV FORM=DIFFERENTIAL INTERP=LOG_LINEAR
0.1 5.0e4
1.0 2.0e4
10.0 2.0e3
END_SPECTRUM

Each data line is energy_MeV value (differential flux unless FORM=INTEGRAL).

Mixed proton + electron environment

Repeat SPECTRUM cards — see examples/fwd_transport/proton_electron_mixed.deck:

SPECTRUM PARTICLE=PROTON FILE=../test_spectrums/350kmx350kmx53deg_proton_0gcm2.csv ...
SPECTRUM PARTICLE=ELECTRON ...
0.1 5.0e4
...
END_SPECTRUM

Histories and sampling are configured on the TRANSPORT card (or CLI). See §5.9 History sampling.

5.9 History sampling

SRTC supports two ways to draw forward Monte Carlo primaries from a tabulated spectrum:

Fixed per bin (SAMPLING=FIXED_PER_BIN, default) — run a fixed number of histories in each adjacent energy interval between tabulated points. Within each bin, energy is sampled (log-linear or linear per INTERP=). Each history weight is

w = φ(E) × (bin Jacobian) / histories_per_bin

so the weighted sum in a bin estimates that bin's contribution to the differential spectrum integral. This gives equal statistical effort per bin regardless of flux magnitude.

Population (SAMPLING=POPULATION) — run a fixed total number of histories per primary particle. Each history picks a bin with probability proportional to that bin's integrated fluence, then samples energy within the bin. Weights correct for the bin selection probability so the total weighted sum estimates the full spectrum integral.

Example deck lines:

TRANSPORT EMIN_MEV=0.1 MAX_STEPS=20000 STEP_FRACTION=0.03 \
  HISTORIES=100000 SAMPLING=FIXED_PER_BIN

TRANSPORT HISTORIES=5000000 SAMPLING=POPULATION METHOD=MONTE_CARLO

CLI equivalents:

srtc -i case.deck --histories 100000 --sampling fixed_per_bin
srtc -i case.deck --histories 1000000 --sampling population

5.10 Transport methods

SRTC supports three transport methods:

The 3D engines need the geometry_3d feature and multigroup_coupled.h5 under PHYSICS DATA_DIR= (built automatically for deck materials on first run, or via srtc data build-multigroup). See 3D Monte Carlo transport.

Setting TRANSPORT METHOD=MC3D_FORWARD or MC3D_ADJOINT in a 1D deck is accepted but srtc run will point you at srtc mc3d rather than running it.

Use the 1D forward MC for dose-depth curves — the validated path for slab and sphere-equivalent studies — and the 3D adjoint MC for a detector buried in real geometry, which is where adjoint pays off. The 3D engine reads multigroup_coupled.h5 from its xs_path. See the viewer guide to drive the same engine from the browser GUI, which is the easier route for most adjoint work.

5.11 Debug physics mode

srtc --debug -i examples/fwd_transport/electron_al_si.deck -o output/debug_run/results.out

• Forces 100 histories per spectrum bin (forward MC only)
• Writes {output_dir}_debug/ containing:
  • multigroup/ — coupled multigroup cross-section CSVs per material (forward + transposed)
  • physics_catalog.md / .csv — expected interactions and data sources
  • mc_interactions/ — sampled interaction counts from the short MC run
  • spectrum/ — external input spectrum tabulation plus every MC primary sample for plotting

spectrum/ debug files (plot sampled vs external)

Plot {particle}_external.csv as the expected spectrum and overlay {particle}_sampled_scatter.csv (or histogram {particle}_sampled.csv weights) to verify sampling.

5.4 External spectrum CSV format

Two columns: energy in MeV, flux value. A header row is skipped automatically.

"Energy (EU*)","Particle = proton_Depth in aluminum = 0"
0.1040279,13773110
0.1596987,12515310

Reference spectra live under test_spectrums/ (OLTARIS validation set).

5.5 Transport geometry mode

TRANSPORT GEOMETRY= controls electron angular/range corrections used after shield traversal:

TRANSPORT EMIN_MEV=0.1 MAX_STEPS=20000 STEP_FRACTION=0.03 GEOMETRY=SPHERICAL_4PI

Supported values are:

• STRAIGHT_AHEAD — default legacy 1D areal-depth transport with no angular correction.
• INFINITE_SLAB — finite-thickness planar shield response with electron multiple-scattering transmission correction.
• SPHERICAL_4PI — finite-thickness spherical shell / ray-tracing response approximation; same physics as INFINITE_SLAB with a depth-dependent blend so thin/medium Al matches Shield2Dose.

SEMI_INFINITE_SLAB is intentionally not a dose-depth mode here. It usually means a half-space backscatter/albedo problem, not a finite rear-surface shielding response curve.

5.6 Ray-trace sectoring (TRANSPORT METHOD=RAYTRACE)

Deterministic 4π ray grid that maps shield slant depth onto a tabulated dose-depth curve. Useful when dose depends only on areal shielding thickness along straight-line paths from a point detector.

RAYTRACE_CURVE NAME=AL_PROTON FILE=curves/ap9_proton_al.csv
RAYTRACE N_AZIMUTH=180 N_POLAR=90 GEOMETRY=SPHERE CURVE=AL_PROTON
TRANSPORT METHOD=RAYTRACE

Dose-depth CSV files begin with a units header (depth (mm Aluminum), dose (Gy)) followed by numeric rows. Multiple curves can be registered with RAYTRACE_CURVE and selected via RAYTRACE CURVE=name.

Spectrum mode (protons / neutrons): register per-depth transmitted spectra with RAYTRACE_SPECTRUM NAME=… FILE=… (directory of *_proton_*gcm2.csv files), then RAYTRACE MODE=SPECTRUM SPECTRUM=proton SPECTRUM=NAME GEOMETRY=SPHERE. The detector spectrum is the solid-angle sum S(E) = Σ wᵢ Sᵢ(E). See raytrace.md.

Full reference: Ray-trace transport. Example deck: examples/raytrace/spherical_al.deck.

For a finite cubic shield, set GEOMETRY=CUBE; slant depth uses the analytic τ = ρ·min(h/|n̂_i|) formula documented in raytrace.md.

Run:

docker compose run --rm backend srtc raytrace \
  -i examples/raytrace/spherical_al.deck \
  -o output/raytrace/spherical.csv

5.6 Materials

SRTC includes the 411-material PNNL Materials Compendium. Any compendium material name, slug, or alias can be used directly in MATERIAL, SHIELD, LAYER, and DETECTOR cards.

Use quotes when the name contains spaces or punctuation:

LAYER ORDER=1 MATERIAL="Aluminum, alloy 6061-O" THICKNESS_MM=2.0
LAYER ORDER=2 MATERIAL="Polyethylene, Borated" THICKNESS_MM=5.0
DETECTOR MATERIAL="Bone Equivalent Plastic, B-110" THICKNESS_MM=1.0 AREA_CM2=1.0

Slug forms also work and are convenient for unquoted decks:

LAYER ORDER=1 MATERIAL=water_liquid THICKNESS_MM=2.0

Common short aliases are preserved: AL, SI, SS, PE, FE, W, and WATER.

The compendium provides material composition and density. SRTC uses exact physics tables when available; for compendium materials without dedicated tables, it applies composition-based fallback scaling until full per-material processed tables are generated.

Examples: examples/fwd_transport/compendium_alloy_stack.deck and examples/fwd_transport/compendium_tissue_detector.deck.

5.7 Layered shield stacks

For spacecraft-style stacks, define layers instead of using --depth-g-cm2:

LAYER ORDER=1 MATERIAL=STEEL THICKNESS_G_CM2=0.50
LAYER ORDER=2 MATERIAL=AL THICKNESS_G_CM2=2.00
LAYER ORDER=3 MATERIAL=PE THICKNESS_G_CM2=1.00

ORDER=1 is the entry face (first material hit by incoming radiation). Example: examples/fwd_transport/spacecraft_stack.deck.

Thickness in mm

You can specify geometric thickness in millimetres instead of areal density. SRTC converts to g/cm² internally using:

thickness_g_cm2 = DENSITY_G_CM3 × THICKNESS_MM / 10

When using THICKNESS_MM on a LAYER, SHIELD, or DETECTOR card, SRTC converts using the compendium density. Add a MATERIAL NAME=... DENSITY_G_CM3=... card only when you need to override the default density:

MATERIAL NAME=AL DENSITY_G_CM3=2.698
LAYER ORDER=1 MATERIAL=AL THICKNESS_MM=10.0

MATERIAL NAME=SI DENSITY_G_CM3=2.33
DETECTOR MATERIAL=SI THICKNESS_MM=0.1 AREA_CM2=1.0

Do not combine THICKNESS_MM and THICKNESS_G_CM2 on the same card. Areal thickness (THICKNESS_G_CM2) does not require an explicit density on the MATERIAL card.

When LAYER cards are present, --depth-g-cm2 does not change the shield geometry.

5.8 TOML configuration

TOML is supported for simple single-particle cases. Example: examples/fwd_transport/oltaris_al_si.toml.

Optional transport fields:

[transport]
method = "monte_carlo"          # or "mc3d_forward" / "mc3d_adjoint" / "raytrace"
histories = 100000
sampling = "fixed_per_bin"      # or "population"
min_energy_mev = 0.1

Layer stacks and mixed spectra are deck-only today. See Input, output, and CLI for the full TOML schema.

6. Example workflows

6.1 OLTARIS Al/Si proton benchmark

Single aluminum slab, silicon detector, OLTARIS orbit spectrum:

srtc \
  -i examples/fwd_transport/oltaris_al_si.deck \
  -o output/oltaris_1gcm2/results.out \
  --depth-g-cm2 1.0 \
  --histories 100000 --seed 1

6.2 Shielding thickness sweep

Vary areal thickness with repeated runs (single SHIELD slab):

for d in 0.5 1.0 2.0 5.0; do
  srtc \
    -i examples/fwd_transport/oltaris_al_si.deck \
    -o "output/al_${d}gcm2/results.out" \
    --depth-g-cm2 "$d" \
    --histories 100000 --seed 1
done

Compare the *_dose.out files or plot dose_rad_day vs depth_g_cm2.

6.3 Layered spacecraft stack

srtc \
  -i examples/fwd_transport/spacecraft_stack.deck \
  -o output/spacecraft_stack/results.out \
  --histories 100000 --seed 1

Edit THICKNESS_G_CM2 on each LAYER line to study design changes.

6.4 Mixed proton and electron primaries

srtc \
  -i examples/fwd_transport/proton_electron_mixed.deck \
  -o output/mixed_env/results.out \
  --histories 100000 --seed 1

Check results.out for the file vs inline source listing and per-particle dose columns.

6.5 Compendium material names

srtc \
  -i examples/fwd_transport/compendium_alloy_stack.deck \
  -o output/compendium_alloy/results.out \
  --histories 100000 --seed 1

This example uses quoted compendium material names and millimetre thicknesses without explicit density cards.

6.7 3D adjoint Monte Carlo run

Adjoint dose comes from the 3D multigroup Monte Carlo engine:

srtc mc3d --config examples/mc3d_adjoint/mc3d_demo.toml

That writes a tally.json (per-detector dose and spectra) next to the configured output_path, and optional tracks.json for the viewer. See 3D Monte Carlo transport for the TOML schema and the CSG geometry format.

6.8 Debug physics verification

srtc --debug \
  -i examples/fwd_transport/electron_al_si.deck \
  -o output/electron_debug/results.out

Output directory becomes output/electron_debug_debug/ with multigroup CSVs, physics catalog, MC interaction statistics, and spectrum/ CSVs for comparing sampled primaries to the external input spectrum.

6.9 Population sampling example

Equal total histories weighted by flux (contrast with default per-bin stratification):

srtc \
  -i examples/fwd_transport/oltaris_al_si.deck \
  -o output/al_pop/results.out \
  --histories 1000000 \
  --sampling population

6.10 Full OLTARIS depth comparison

Automated sweep against reference dose-vs-depth data:

srtc compare-oltaris --histories 100000 --seed 1

Output directory (default): tests/comparisons/oltaris/1d/

7. Understanding output

7.1 results.out

Text summary including:

• Input deck path and output directory
• Shield depth or layer stack description
• Primary sources (file path or inline point count per particle)
• Total and particle-resolved dose (rad/day) with absolute standard deviations
• Paths to *_dose.out and *_spectrum.out

7.2 *_dose.out

Single-row CSV with columns:

depth_g_cm2,dose_rad_day,dose_std_dev_rad,
proton_dose_rad_day,proton_dose_std_dev_rad,
neutron_dose_rad_day,neutron_dose_std_dev_rad,
electron_dose_rad_day,electron_dose_std_dev_rad,
photon_dose_rad_day,photon_dose_std_dev_rad,
proton_peak_MeV,histories

• dose_std_dev_rad — absolute standard deviation of the run dose estimate in rad/day.
• Particle columns — energy deposited in the detector by each species; photons and neutrons appear when secondaries reach the detector.

7.3 *_spectrum.out

Transmitted fluence binned in energy, per particle type plus a total row:

shield_depth_g_cm2,particle,bin_low_MeV,bin_high_MeV,weighted_counts

8. Physics data

8.1 Runtime libraries

Point PHYSICS DATA_DIR= at /data/jendl-5 (shipped inside the bundle):

See data/README.md for layout. Bootstrap seed CSVs remain under data/xs_sample/ for the build pipeline only.

8.2 Processing external libraries

To fetch and normalize manifest-driven data:

srtc data fetch   --manifest data/manifests/default.toml
srtc data process --manifest data/manifests/default.toml \
  --out data/processed

Then set PHYSICS DATA_DIR=data/processed in your deck.

Inspect loaded values:

srtc data inspect \
  --data-dir data/processed \
  --particle proton --material Al

9. Example decks in the repository

10. Troubleshooting

Deck parse errors

Errors use the form line N (SECTION): message, for example:

Error: parsing deck file examples/my_case.deck

Caused by:
    line 12 (SPECTRUM): missing END_SPECTRUM before 'SHIELD'

Common fixes:

Paths in FILE= are resolved relative to the deck file's directory.

Stale executable

If behaviour does not match this manual after an update:

srtc --help

Low statistics / large error bars

Increase --histories (for example 500000 or 1000000) and/or check that spectrum integrals are reasonable (very small flux → few useful histories).

Layer stack vs --depth-g-cm2

• Single slab: SHIELD MATERIAL=AL + --depth-g-cm2
• Multi-layer: LAYER cards only; CLI depth is a label in spectrum output, not extra shielding

11. Further reading