Particle transport (beta)¶
Charged particles through a design's solids and its solved magnetic field: muons through a tracker in a solenoid's
bore, electrons showering in iron, geantinos counting an acceptance. Geant4 runs in axmp-transport, a separate
program; the package drives it from Python with axionmultiphysics.particles, which plans a run into chunks of
events, starts the program on them, merges the chunks in a fixed order and estimates the requested outputs with their
statistical errors. The package's library, its Python module and the axmp command never link Geant4: they exchange
files with axmp-transport, as they do with axmp-mesher and gmsh.
Beta
The job format, the output arrays, the driver's interface and the command line may change between minor versions. Every number is Monte Carlo with statistical errors only: the dependence on the physics list and the approximations of Geant4's models are not estimated. Statistical error is not the total error. Nothing here is validated against measured data; the validation page lists what is checked against closed forms and published formulas.
This product includes software developed by Members of the Geant4 Collaboration ( http://cern.ch/geant4 ).
A first run¶
import axionmultiphysics as axmp
from axionmultiphysics import particles, solids
res = axmp.Design(doc).solve(workdir="runs/solenoid")
fm = res.export_field_map("runs/solenoid/fieldmap", tol=1e-4) # docs/guides/field_maps.md
sol = solids.from_partition(partition, materials, region_materials) # docs/guides/solids.md
r = particles.transport(axmp.Design(doc), res, solids=sol, field_map="runs/solenoid/fieldmap",
sources=[{"type": "gun", "particle": "mu+", "momentum_eV_c": 2e8,
"at_m": [0, 0, 0], "direction": [1, 0, 0]}],
outputs={"trk": {"hits": {"in": ["layer_0", "layer_1"], "track": "primary"}},
"E": {"deposit": {"in": "layer_0"}}, "Em": {"mean": {"of": "E"}}},
events=10000, workdir="runs/solenoid/muons", seed=1)
print(r["Em"]) # e.g. "1.234e3 +- 0.012e3 (10000 events)": a Measured, value and statistical error
hits = r.hits("trk") # chunk, event, track, parent, pdg, region, x_m, p_eV_c, t_s, ekin_eV
particles.transport(design, results, ...) is the route from a solved design: its regions are the solids (passed as
solids=: this version does not run the partition export for the call, which without solids= raises
particle.partition_unavailable; the solids document that Design.export_gdml returns can be passed, a route that
the validation does not cover yet), its field the map (exported from results into <workdir>/fieldmap when
field_map is not given; every patch serves its record's regions). Everything else goes to particles.run, which is
particles.plan + particles.execute + particles.merge on a work directory and works with any solids list and
any fields:
r = particles.run("runs/w", solids=sol, fields=[{"type": "uniform", "B_T": [0, 0, 1.5]}],
sources=[...], outputs={...}, events=100000, chunk_events=1000, jobs=8, seed=7)
r = particles.extend("runs/w", events=200000) # bitwise equal to a direct run of 200 000 events
r = particles.load("runs/w") # the merged result from disk, nothing run again
particles.capabilities() says what this installation has (never raises): the program (found, path, its
--check document, ok), whether the mesher exports partitions for the API route (partition_export, false in this
version for both geometries) and the event generator (none in this version).
The driver: axionmultiphysics.particles¶
particles.plan(workdir, *, solids, sources, outputs, events, fields=(), seed=1, chunk_events=1000, jobs=1,
physics_list="FTFP_BERT", production_cut_m=7e-4, integrator=None, outside="refuse",
quantum_eV=1e-3, stop=None, threads=1, program=None) -> dict # run.json's content
particles.execute(workdir, *, workers=1)
particles.merge(workdir, *, allow_failed_chunks=False) -> ParticleResults
particles.run(workdir, **plan_kwargs, workers=None, allow_failed_chunks=False) -> ParticleResults
particles.extend(workdir, *, events, workers=1, chunk_events=None, allow_failed_chunks=False) -> ParticleResults
particles.load(workdir) -> ParticleResults
particles.transport(design, results, *, sources, outputs, events, composition=None, solids=None, field_map=None,
map_tol=1e-4, track_volumes=None, workdir=None, **run_kwargs) -> ParticleResults
particles.resolve_materials(doc, *, program=None) -> dict
The module is pure Python (numpy, scipy); importing it imports nothing of Geant4. It finds the program as program=,
else $AXMP_TRANSPORT, else axmp-transport next to axmp, else on PATH; without one, plan raises
build.requires_program (build it with -DAXMP_BUILD_TRANSPORT=ON and set AXMP_TRANSPORT).
plan validates everything before it writes anything, and refuses with a named code (below): the event count
(events is required: a run never defaults to a number of events), the seed (an integer in [0, 2^64),
events.invalid otherwise: two seeds equal modulo 2^64 would be one run recorded as two), the source, the physics
list, the outputs, the fields and their coverage of the solids, the integrator, a tally that could overflow, and the
geometry (Geant4's overlap check, particle.geometry_overlap). A numeric argument of the wrong type or range
(jobs, threads, workers, production_cut_m, quantum_eV, a seed that is not an integer) and a debug that
is not an object raise a plain ValueError instead. It resolves the NIST compositions of the solids against Geant4's tables
(resolve_materials, below), then writes the work directory:
<workdir>/run.json the plan, updated by execute, merge and extend
<workdir>/exchange/solids.json the resolved solids list both Geant4 routes read
<workdir>/exchange/job_<j>.json one job file per block of chunks; exchange/commands.txt: their command lines
<workdir>/out/chunk_<k>/ the program's chunks; out/record_<j>.json
<workdir>/results.json, merged/ written by merge
<workdir>/logs/ the program's output per process, with its exit status
<workdir>/.lock the workdir's lock
One driver per workdir. plan, execute, merge and extend (and run and transport) hold an exclusive
lock on the workdir (fcntl.flock on <workdir>/.lock) while they work; another process that tries meanwhile is
refused with events.workdir_busy and changes nothing (load only reads and takes no lock).
Field maps of a run. The job files name a map that lies inside the workdir (the one transport() exports into
<workdir>/fieldmap) relative to it (../fieldmap), so a copied or moved workdir reads its own map; every other
map by its real absolute path, so a workdir reached through a symbolic link finds it either way. run.json records
each map's path relative to the workdir and the SHA-256 of its manifest (fields[i].manifest_sha256; the manifest
lists every patch array's checksum). execute, extend and run compare it, where the job files point, before any
program starts, and refuse a map that changed or vanished with events.field_map_changed, naming the map and
changing nothing: an extension would otherwise mix two fields.
workdir must be new, empty, or hold a planned run (which is planned again: its chunks are removed;
events.workdir_not_empty otherwise). The run is cut into ceil(events / chunk_events) chunks (the last one short
when events is not a multiple), and the chunks into jobs contiguous blocks of near-equal length, one job file each
(fewer when there are fewer chunks). threads is the --threads of every process.
execute starts the job files, workers processes at a time (run defaults workers to the number of job
files). A process that fails (non-zero exit status) has its incomplete chunks run again once, in one new process; a
chunk still incomplete is failed. A chunk counts as complete once its manifest exists (the program writes it last
and then renames the chunk's directory); the merge checks every array against its checksum.
merge reads every planned chunk: it is complete when its manifest's chunk, chunk_seed and events are the
plan's (otherwise the merge is refused, events.chunk_mismatch) and every array matches its SHA-256 (otherwise the
chunk counts as missing). The merged sample is the longest complete prefix of chunks 0, 1, 2, ... (with
allow_failed_chunks=True, every complete chunk). A prefix of a sequence of independent chunks is an unbiased sample
whatever made the others fail, and it is what an extension continues. Fewer events than requested make a
partial result: partial true, missing_chunks (the planned chunks not merged), warning events.partial.
Events are merged in (chunk, event) order, so the result does not depend on jobs, workers or threads.
extend(workdir, events=N2) (N2 at least the events requested so far, events.invalid otherwise; the same
chunk_events, events.chunk_events_mismatch otherwise) reuses every complete full chunk (its checksums checked),
runs a short last chunk again in full and replaces it, runs the new chunks, and merges: the result equals, bit for
bit, a direct run of N2 events (arrays, tallies and results.json, timings aside).
Stop rules. stop={"output": NAME, "rel_error": r} (NAME an aggregate output) merges the smallest prefix of
K >= 20 chunks for which the output on chunks 0..K-1 has stat_error / |value| <= r, or the planned chunks. It is
evaluated on prefixes of complete chunks in index order, so the result does not depend on the number of workers;
chunks beyond K that completed are kept on disk as beyond_stop and not merged. execute evaluates the rule each
time a job file's process exits, and then stops the others and starts no more: the rule saves compute only at the
boundaries of job files. With the default jobs=1 every chunk runs; plan jobs well above workers (for example a
few chunks per job file) when the rule is meant to end the run early. run.json's stop records
reason (rel_error or events), chunks and events.
Command line.
python -m axionmultiphysics.particles {execute,merge,extend} WORKDIR [--workers N] [--allow-failed-chunks] [--events N]
prints one JSON document, {"status": "complete" | "partial", "events", "events_requested", "missing_chunks"}, and
exits 0 when complete, with exit status 5 when partial, 1 when refused ({"error", "code"} on stdout), 2 for a
usage error (a malformed command, --workers or --events that is not a positive integer, or --events given to
execute or merge; nothing is changed). --allow-failed-chunks applies to the merge that execute, merge and
extend end with (the Python execute only runs and takes no such option). A scheduler can run the commands of exchange/commands.txt itself (one per job file) and then
merge.
Sources¶
Exactly one source in this version, a gun:
{"type": "gun", "particle": "mu+", "momentum_eV_c": 1e9, "at_m": [0, 0, -0.5], "direction": [0, 0, 1],
"spot_sigma_m": 0.001}
particle: a name of Geant4's particle table (axmp-transport --checklists it) or a PDG code; a name it lacks is refused withparticle.unknown_particle, whose message lists candidates (muon->mu-,mu+;electron->e-;pion->pi+,pi-,pi0; close spellings);- exactly one of
energy_eV(kinetic) andmomentum_eV_c, positive; a momentum is converted to kinetic energy with the mass of Geant4's particle table; direction: a non-zero vector (normalised) or"isotropic"(uniform on the sphere; a point source);spot_sigma_m(default 0): a Gaussian spot, sigma per transverse coordinate, in the plane throughat_mperpendicular todirection;at_mmust lie in a region of the solids (their surfaces included):planlocates it in the solids list and refuses a point beyond the world or in the world or a void, where the primary would have no volume to start in or would leave the domain at once (particle.source_invalid). The program refuses a job file whoseat_mlies outside the world (exit status 2, nothing written), and ends the process (status 4, with a message) if a spot draws a vertex beyond the world.
Every event draws first u0 = G4UniformRand() (recorded as first_flat), then, for an isotropic direction,
u1, u2: cos(theta) = 1 - 2 u1, phi = 2 pi u2; for a spot, u1, u2: rho = sigma sqrt(-2 ln(1 - u1)), psi = 2 pi u2,
the offset rho (cos(psi) e1 + sin(psi) e2) with e1 the unit vector of d x z (x when d is along z) and e2 = d x e1.
Any other refusal of the source is particle.source_invalid.
Outputs¶
outputs is {name: spec} (names [A-Za-z_][A-Za-z0-9_]*), each spec with exactly one kind:
| kind | spec | value |
|---|---|---|
| per-event variable | {"deposit": {"in": REGION or [REGIONS]}} |
the energy deposited per event, eV |
| per-event variable | {"hit": {"in": REGION, "of": "x" \| "y" \| "z" \| "r" \| "phi" \| "t" \| "E_kin", "track": "primary" \| "any"}} |
at the event's first hit in the region (default track: the primary); undefined (NaN) when there is none; m, rad, s, eV |
| per-event variable | {"primary": {"of": "x" \| "y" \| "z" \| "px" \| "py" \| "pz" \| "E_kin"}} |
the primary as generated; m, eV/c, eV |
| aggregate | {"mean": {"of": VAR, "where": W}}, {"std": ...}, {"quantile": {"of": VAR, "q": q, "where": W}} |
Measured |
| aggregate | {"fraction": {"where": W}}, {"count": {"where": W}} |
Measured (over all events) |
| histogram | {"histogram": {"of": VAR, "bins": n, "range": [lo, hi], "where": W}} |
r.histogram(name) |
| tally | {"tally": {"grid": G, "in": [REGIONS]}} |
r.tally(name) |
| hits | {"hits": {"in": [REGIONS], "track": "any" \| "primary", "particles": [NAMES], "max_per_event": n, "keep_events": m}} |
r.hits(name) |
W(optional) is{VAR: {"gt" | "ge" | "lt" | "le": x, "defined": true | false}, ...}(all must hold) or{"any": [W, ...]}. An undefined value satisfies only{"defined": false}.- A grid
Gis{"type": "cylindrical", "r_m": [r0, r1], "z_m": [z0, z1], "bins": [nr, nz]}(full rings) or{"type": "cartesian", "x_m": [..], "y_m": [..], "z_m": [..], "bins": [nx, ny, nz]}. A step's deposit goes to the bin of the step's midpoint; a deposit outside the grid or outsidein(default: every region) is not tallied. - A hit is one record per step that enters a volume of the listed regions (its pre-step point lies on the
volume's boundary, and the track's previous step is longer than Geant4's surface tolerance, 1e-12 m), taken at
that point: track and parent IDs, PDG code, region (index in the solids'
regions), position, momentum, global time since the primary vertex, kinetic energy. At mostmax_per_eventrecords per event (default 100; the rest are counted as dropped); withkeep_events, only the first m events in (chunk, event) order keep records. At some interfaces Geant4 takes a zero-length step back and forth across a face; the step after it records nothing, so no point is recorded twice. An excursion into a neighbouring volume shallower than deltaChord (0.25 mm) is collapsed by Geant4 to such a step: its entry is recorded and its return is not (measured: 11 such pairs among 174 375 hits of 5000 protons crossing slabs of 1 T and 0.2 T at grazing angles, none at normal incidence).results.jsongivesrecords,dropped,events_with_recordsandevents_without_records. - Anything else is refused with
particle.output_invalid, naming the output.
Results and estimators¶
r[name] -> Measured # an aggregate; KeyError for other names
r.histogram(name) # edges (numpy.linspace(lo, hi, bins + 1)), counts per [lo_i, hi_i), errors, underflow,
# overflow, undefined
r.tally(name) # edges, edep_eV (mean deposit per event per bin), stat_error, q_dep_J_m3, volume_m3,
# events, quantum_eV, lo, hi (the exact 128-bit batch sums), batch_events
r.events(names=None) # chunk, event and the per-event variables, numpy arrays in (chunk, event) order
r.hits(name) # chunk, event, track, parent, pdg, region, x_m, p_eV_c, t_s, ekin_eV
r.record, r.outputs, r.n_events, r.events_requested, r.partial, r.missing_chunks, r.warnings, r.workdir
A Measured is a float carrying stat_error, error (the estimator), events, events_defined, units,
mc (true), and upper_limit, cl, interval where they apply. Arithmetic on it returns a plain float, so an error
is never carried along silently. It prints its value to the decimal place its error supports (the PDG rule: the
three leading digits of the error decide two significant digits for 100-354, one for 355-949, and 950-999 round up
to 1000 with two), as "0.9981 +- 0.0021 (2000 events)" or "(1.235 +- 0.031)e-7 (2000 events)".
| output | value | statistical error (error) |
|---|---|---|
mean |
the mean of the selected defined values | s / sqrt(n), s with ddof 1 (sem); none below n = 2 |
fraction |
k / N over all merged events | the Clopper-Pearson interval at 68.27 % (interval) and half its width (clopper_pearson) |
count |
k | sqrt(k) (poisson) |
| zero counts | 0 | none: the exact one-sided 95 % limit, 1 - 0.05^(1/N) for a fraction, -ln 0.05 = 3.0 for a count (upper_limit, cl); printed "< 0.26 (95 % CL, 10 events)", never 0 +- 0 |
| no merged event | NaN | none, and no limit (reason: no events), for every aggregate |
std, quantile, tallies |
on all merged events | batch means (batch_means) |
Batch means: chunk k belongs to batch k mod 20; v_b is the statistic on batch b's events (a tally: its bin sum times
the quantum over the batch's events), w_b = n_b / N, and sigma^2 = B / (B - 1) sum w_b^2 (v_b - vbar)^2 with
vbar = sum w_b v_b and B = 20. Below 20 merged chunks there is no such error (stat_error None, warning
stat.too_few_chunks). The functions estimate_mean(values), estimate_fraction(k, n), estimate_count(k) and
batch_means(values, weights) are the same estimators for your own arrays.
Tallies are exact. Every event's deposit in a bin is rounded to quantum_eV (default 1e-3 eV) and added as an
integer, per chunk in 64 bits and per batch in 128 bits (two limbs, merged/tally_<name>_lo.npy unsigned and
_hi.npy signed, exact value hi x 2^64 + lo): the sums do not depend on the order of the threads or the chunks, and
none can wrap. A plan whose chunk could reach 2^63 quanta (chunk_events x (kinetic plus rest energy) /
quantum_eV) is refused with particle.tally_overflow.
results.json (schema axionmultiphysics.particles-results/1) carries beta, mc (the sentence "Monte Carlo
(beta): N events, seed S; statistical errors only; physics-list dependence not estimated"), seed, events,
partial, missing_chunks and per output its record: aggregates {"value", "stat_error", "error", "events",
"events_defined", "units", "mc": true, "beta": true} (plus interval, upper_limit, cl), histograms their
arrays, tallies the file names of their batch arrays, hits their counts.
run.json (schema axionmultiphysics.particles-run/1) records beta, seed, stage and instance,
chunk_events, events_requested, every chunk (index, seed, events, job, status: planned, complete,
failed or beyond_stop, attempts, sha256 of its manifest), the program (path, versions, data sets, command
lines), the physics list, production_cut_m, integrator (with stepper), quantum_eV, outside, fields (as
given, map paths relative to the work directory, plus each map's tol and its patches' error records), sources,
outputs, stop, materials_resolved, warnings, partial, missing_chunks and events. Outside the program's
record and timing it holds no time, host or absolute path.
Seeds¶
One master seed (default 1, always recorded) gives every chunk its seed:
chunk_seed(seed, k) = derive_seed(seed, "transport", "transport", k), where derive_seed(seed, *keys) starts from
z = seed mod 2^64 and for each key sets z = mix(((z XOR h(key)) + 0x9E3779B97F4A7C15) mod 2^64), mix being
SplitMix64's output function, h(int) the int mod 2^64 and h(str) the first 8 bytes (little-endian) of the SHA-256 of
its UTF-8. It is injective in the last key, so the chunks of one run have distinct seeds. Every event of a chunk is
seeded from (chunk seed, event index) as the program describes below (particles.event_words gives its four words).
Fields¶
fields is a list; each entry serves the regions it names (default: every region for an analytic field, the patch
record's regions for a map patch):
| entry | field |
|---|---|
{"type": "uniform", "B_T": [bx, by, bz], "regions": [...]} |
Geant4's G4UniformMagField |
{"type": "current_loop", "radius_m": a, "current_A": I, "z_m": z0, "regions": [...]} |
a circular filament on the z axis in the plane z = z0, counter-clockwise seen from +z for I > 0 (closed form with complete elliptic integrals) |
{"type": "map", "path": dir, "patch": name, "regions": [...]} |
one patch of an axionmultiphysics.fieldmap/1 map (Field maps) |
{"type": "map", "path": dir} |
every patch of a map, each serving its record's regions; the map's zero_field_regions are field-free |
A region served twice is refused (particle.field_ambiguous), an unknown region or a malformed entry with
particle.field_invalid (also a write_map patch named without regions).
One field per volume. Every logical volume gets a field object and a field manager of its own, a field-free one
where no field serves its region, so that no volume inherits its mother's field (Geant4 hands a mother's field
manager to daughters that have none). Every field manager uses the same integrator: Geant4's templated Dormand-Prince
4(5) stepper with G4IntegrationDriver (G4ChordFinder's kTemplatedStepperType; recorded as
"stepper": "G4TDormandPrince45+G4IntegrationDriver"), never the interpolation, B-field, FSAL or QSS drivers. A step
near a boundary is integrated past it and the boundary is then located by re-integrating from the step's start, so
only the field within about deltaIntersection of the boundary enters the trajectory. A patch is correct about one
grid cell beyond its region (its margin), so delta_intersection_m must be at most 0.1 of the finest spacing of the
attached patches (refused by the driver with particle.integrator_invalid, and by the program for any job file
it is handed: exit status 2, nothing written). Measured on a field jump at a sphere (1 T
inside, 0.2 T outside): per-volume patches correct to 1 um beyond the boundary give the exact piecewise circles to
2e-6 m; a field that is zero at once beyond the boundary, a single point-located field, the interpolation driver or a
deltaIntersection of 0.1 mm give 2e-4 to 6e-3 m. That accuracy holds for a track that enters a volume deeper than
about deltaChord (0.25 mm): Geant4 can miss a volume that a chord of the step enters by less, so a track that grazes
the sphere (entering by 1e-7 to 5e-5 m) leaves it with errors of up to 2.5e-3 m (0.5 GeV/c) and 7.6e-3 m
(0.1 GeV/c), equivalent to an error of at most deltaChord in its impact parameter; entries of 1 to 3 mm are exact to
7e-6 m and 5e-5 m. A track started within a micrometre of an interface and parallel to it is the same case.
integrator takes any of delta_chord_m (2.5e-4), delta_one_step_m (1e-5), delta_intersection_m (1e-6),
epsilon_min (5e-5), epsilon_max (1e-3) and min_step_m (1e-5), Geant4's defaults; positive, with
epsilon_min <= epsilon_max <= 1e-2. A delta_intersection_m above 0.1 of the thinnest tube of the solids warns
particle.delta_intersection_not_small.
Outside the maps. At set-up the driver checks that each region served by a patch lies in the patch's box
enlarged by its margin (kind 1: the solids' (r, z) extent; kind 3: the corners of the solids' bounding cylinder in
the patch frame), and that, when fields is not empty, every region is served or field-free by a map's
zero_field_regions; otherwise it refuses with particle.field_outside_map, naming the region and the patch. With
outside="zero" the run proceeds instead: unserved regions are field-free, a field call outside a patch's box plus
margin at a point inside the volume returns 0 and is counted (outside_calls), and the result warns
particle.field_outside_map with the total count and each map's boundary_ratio. During the run, a stepper's
trial point beyond a patch's box outside the volume (tens of mm beyond a volume whose face is the box face) takes the
value of the box's nearest point and is not counted: such values do not enter the trajectory.
The domain. The world and the voids (solids without a region) end the transport's domain: a track that is in
them leaves it, its kinetic energy added to the event's exit_eV. A track is in them when it leaves the world, or at
the end of a step longer than the surface tolerance that started in the world or a void and whose first micrometre
(at most half the step) lies in the world or a void by a locate of Geant4's navigator without history. A step that
merely ends in the world is no exit: at an interface between two regions Geant4 can report the world (the mother of
both) for one zero-length step and return the track on the next.
Physics¶
physics_list is one of FTFP_BERT (the default), FTFP_BERT_EMZ (Geant4's most precise electromagnetic option)
and QGSP_BIC (particle.physics_list_unknown otherwise, naming them; a high-precision neutron list *_HP is
refused with particle.physics_list_unavailable). production_cut_m (default 0.7 mm) is one production cut for all
particles and regions. Geant4 kills particles that loop in a field without progress; their number and energy are
recorded per event, and the result warns particle.looping_killed when their energy exceeds 1e-6 of the deposited
energy. A track that Geant4's navigator abandons as stuck (not moving for 25 steps, GeomNav0003; seen for a track
that snakes along an interface where the field reverses, which a solved map does not hold but adjacent uniform
fields of opposite sign do) is ended where it stands instead of the event being aborted: the event and its chunk
complete, the track's number and kinetic energy are recorded per event (abandoned_killed, abandoned_eV; not in
exit_eV), and the result warns particle.track_abandoned.
Materials: NIST compositions¶
particles.resolve_materials(doc) returns the solids document with its NIST compositions resolved against the
Geant4 the program is built with (axmp-transport --nist); the driver runs it before every run and records
materials_resolved (per material as: nist or one_component, and NIST's data). A material whose block is
exactly {"nist": X} at X's own density (within 1e-9) becomes the NIST material itself; any other keeps one
component and takes X's mean excitation energy and state where the document gives none; a density more than 1 %
from NIST's warns particle.density_differs_from_nist. The residual of the second case and the reasons are in
Solids for particle transport.
Codes¶
| code | kind | raised for |
|---|---|---|
build.requires_program |
error | axmp-transport is not found (or not executable). |
events.count_missing |
error | No events: a run never defaults to a number of events. |
events.invalid |
error | events or chunk_events not a positive integer; a seed outside [0, 2^64); an extension below the events requested so far; a work directory without a planned run. |
events.workdir_not_empty |
error | plan into a directory that holds other files and no run.json. |
events.workdir_busy |
error | plan, execute, merge or extend on a workdir whose lock another process holds (the command line: exit 1 and the code). |
events.chunk_events_mismatch |
error | extend with a chunk_events other than the plan's. |
events.chunk_mismatch |
error | A chunk whose manifest names another chunk, seed or number of events than the plan. |
events.partial |
warning | Fewer events merged than requested (exit status 5 on the command line). |
stat.too_few_chunks |
warning | Fewer than 20 merged chunks: std, quantile and tallies carry no statistical error. |
particle.unknown_particle |
error | A particle Geant4's table lacks; the message lists candidates. |
particle.source_invalid |
error | Not exactly one gun, an unknown key, both or neither of energy_eV and momentum_eV_c, a non-positive energy, a zero direction, a negative spot, a spot with an isotropic direction, a position outside every region of the solids. |
particle.output_invalid |
error | An output (or a stop) that is not one of the forms above. |
particle.field_invalid |
error | A malformed field, an unknown region, a map patch without regions, an outside other than refuse or zero. |
particle.field_ambiguous |
error | A region served by two fields; transport() given both fields= and field_map=. |
particle.field_outside_map |
error, or warning with outside="zero" |
A region beyond its patch's box plus margin, or a region served by no field; with outside="zero", the count of calls outside the maps. |
particle.integrator_invalid |
error | An unknown or non-positive integrator value, epsilon_min > epsilon_max or epsilon_max > 1e-2, a delta_intersection_m above 0.1 of the finest map spacing. |
particle.delta_intersection_not_small |
warning | delta_intersection_m above 0.1 of the thinnest tube of the solids. |
particle.physics_list_unknown |
error | A physics list other than the three offered. |
particle.physics_list_unavailable |
error | A high-precision neutron list (*_HP): not offered in this version. |
particle.tally_overflow |
error | A chunk whose tally could reach 2^63 quanta. |
particle.partition_unavailable |
error | transport() without solids=: this version does not run the design's partition export for it (capabilities()["partition_export"] is false). |
particle.density_differs_from_nist |
warning | A NIST composition more than 1 % from NIST's density. |
particle.looping_killed |
warning | Looping tracks killed carrying more than 1e-6 of the deposited energy. |
particle.track_abandoned |
warning | Tracks that Geant4's navigator abandoned as stuck (GeomNav0003) were ended; their number and energy are in the arrays abandoned_killed and abandoned_eV. |
events.field_map_changed |
error | execute, extend or run on a workdir whose field map changed or vanished since the plan (its manifest's SHA-256). |
The codes of the solids list (particle.partition_invalid, particle.geometry_overlap, ...) are in
Solids for particle transport. Each error is an AxionMultiPhysicsError with code and hint,
whose message names the offending item and ends with . Hint: ...; each warning a particles.ParticleWarning whose
message starts with its code.
Limits of this version¶
- One gun per run; no event generator yet.
- The transport is validated with axisymmetric solids lists only. 3D lists (
tessellatedsolids fromDesign.export_gdmlof a 3D design) are built and checked byaxmp-transport --geometry(volumes, masses, overlaps), but no transport through them is validated yet (the 3D dipole of the demonstration skips). transport()needssolids=: it does not run the partition export itself (capabilities()["partition_export"]).- Statistical errors only; the physics-list dependence is not estimated (compare
FTFP_BERTwithQGSP_BICorFTFP_BERT_EMZby hand where it matters). No energy-balance check yet. - Reproducible bit for bit on one build, compiler and platform; another build agrees statistically only.
The program axmp-transport¶
axmp-transport reads a job file, transports events, and writes NPY arrays and a run record. Its modes: transport
(the driver's), probe (the fields at given points) and hello (muons through a silicon slab: a check of the
toolchain). axmp-transport --geometry solids.json builds a solids list in Geant4 and checks it for overlaps (see
Solids for particle transport); axmp-transport --nist NAME [NAME ...] prints Geant4's own data of NIST
materials.
Licences¶
The source of axmp-transport is BSD-3-Clause. The running program links Geant4 (Geant4 Software License) and the
LGPL-3 CLHEP that every Geant4 build contains. For that reason it is a separate program, it is built only on request
(-DAXMP_BUILD_TRANSPORT=ON, off by default and always off when building a wheel), and no wheel contains Geant4 or
CLHEP code. Geant4's data sets are distributed by CERN and are never redistributed or downloaded by this package. The
full rule is in Installation: licensing of each wheel.
Building it¶
You need a Geant4 from 11.2 up to, not including, 11.5, built multithreaded (GEANT4_BUILD_MULTITHREADED=ON), with
its data sets installed (Geant4's GEANT4_INSTALL_DATA=ON, or an existing installation). The 12 data sets that
Geant4 11.4 installs by default are 1.65 GB compressed and about 2.2 GB unpacked; Geant4 finds them under
<prefix>/share/Geant4/data, or where GEANT4_DATA_DIR or the variable of a data set points. 11.4.3 is the version the
project is tested with; another version in the range is accepted and reported as untested by --check.
cmake -S . -B build -DAXMP_BUILD_TRANSPORT=ON -DGeant4_DIR=<geant4 prefix>/lib64/cmake/Geant4
cmake --build build --target axmp-transport
The configure refuses a Geant4 outside the range or without multithreading and says what to change. (Geant4's own
version file checks only the lower end of the range that find_package asks for, so the upper end is checked
explicitly.)
Checking an installation¶
prints one JSON document on stdout (Geant4's banner and messages go to stderr): the program and Geant4 versions,
whether that Geant4 is the tested one, the physics lists and modes offered, and the Geant4 data sets with where each
was found, whether it is ok or missing, and whether the offered physics list requires it (FTFP_BERT reads G4EMLOW, G4PARTICLEXS, PhotonEvaporation and
G4ENSDFSTATE). ok is true when every
required data set is present. "geometry": true says that the program has the geometry mode, "nist": true that it
has --nist; modes lists hello, transport and probe, physics_lists the three offered, stepper the pinned
integration driver, and particles Geant4's particle table once FTFP_BERT has built it (name: PDG code, mass in
eV, charge; ions left out).
prints {"schema": "axionmultiphysics.transport-nist/1", "materials": {NAME: {"density_kg_m3",
"mean_excitation_eV", "state", "T_K", "pressure_Pa", "elements": {symbol: mass fraction}}}}, each value converted
once from Geant4's units and written so that it reads back as the same double; a name Geant4's NIST manager does not
know ends it with exit status 2 (named on stderr, nothing on stdout).
Running a job¶
The run manager is always Geant4's tasking run manager with N threads (default 1), also for N = 1. Relative paths
in the job resolve against the directory of the job file. Unknown or missing keys, wrong types and values out of
range are refused before Geant4 starts, and so is a delta_intersection_m above 0.1 of the finest spacing of the
map patches the job attaches (exit status 2, nothing written). A job file of the mode transport (schema
axionmultiphysics.transport-job/1), as the driver writes it:
{"schema": "axionmultiphysics.transport-job/1", "mode": "transport", "out": "../out", "record": "../out/record_0.json",
"chunks": [{"index": 0, "seed": 1234, "events": 1000}],
"physics_list": "FTFP_BERT", "production_cut_m": 0.0007,
"solids": "solids.json",
"fields": [{"type": "map", "path": "/data/run1/fieldmap", "patch": "air", "regions": ["air"]}],
"outside": "refuse",
"integrator": {"delta_chord_m": 0.00025, "delta_one_step_m": 1e-05, "delta_intersection_m": 1e-06,
"epsilon_min": 5e-05, "epsilon_max": 0.001, "min_step_m": 1e-05},
"source": {"type": "gun", "particle": "mu+", "momentum_eV_c": 1e9, "at_m": [0, 0, 0], "direction": [0, 0, 1],
"spot_sigma_m": 0.0},
"quantum_eV": 0.001,
"tallies": [{"name": "q", "grid": {"type": "cylindrical", "r_m": [0, 0.5], "z_m": [-1, 1], "bins": [10, 20]},
"regions": ["iron"]}],
"hits": [{"name": "tracker", "regions": ["layer_0", "layer_1"], "track": "any", "particles": null,
"max_per_event": 100}]}
chunks is a list of {index, seed, events} run in the listed order in one process (the geometry and the physics
are built once), one BeamOn each; seed is an integer in [0, 2^64). Every region is named explicitly (the driver
resolves the defaults). fields, tallies and hits may be empty. debug is for tests only (fail_chunks: the
process ends with status 4 on reaching one of these chunks, before running it).
Mode probe. {"schema", "mode": "probe", "out", "solids", "fields", "outside", "probe": {"points":
"points.npy"}} with an (n, 3) float64 array of points in m: each point is located in its volume (a navigator of
the built geometry) and that volume's field object is evaluated as the stepper would. It writes
<out>/probe/B_T.npy ((n, 3), tesla), <out>/probe/region.npy ((n,) int32, the index in the solids' regions,
-1 for the world and the voids, whose field is 0) and <out>/probe/manifest.json (outside_calls). Map patches are
evaluated as FieldMap.evaluate evaluates them (bilinear in (r, z) for kind 1 with B_x = B_r cos(phi) - B_phi
sin(phi), B_y = B_r sin(phi) + B_phi cos(phi); trilinear for kind 3 in the patch frame, rotated back; clamped within
the margin), within 1e-12 of the field's scale. A point beyond its patch's box plus margin ends the probe with exit
status 4 and fieldmap.outside_map on stderr (outside: "refuse") or gets 0 and is counted ("zero").
Mode hello. Muons through a silicon slab in an optional uniform field: a check of the toolchain, the seeding
and the reproducibility.
{"schema": "axionmultiphysics.transport-job/1", "mode": "hello", "out": "out",
"chunks": [{"index": 0, "seed": 1, "events": 200}],
"hello": {"particle": "mu-", "energy_eV": [5.0e8, 1.5e9], "field_T": [0.0, 1.0, 0.0], "target_thickness_m": 0.01}}
A world box of half-lengths 1 m of G4_Galactic; a box of half-lengths 0.5 m by 0.5 m by half the thickness of
G4_Si at the origin. The gun starts at (0, 0, -0.5 m) along +z with kinetic energy low + (high - low) u, u
being the first random number of the event. A non-zero field_T attaches a uniform field to the whole world. Its
arrays are event, seed_words, first_flat, ekin_eV, edep_eV (in the target), n_steps, n_tracks and
field_calls.
Exit status. 0 success. 2 usage or invalid job. 3 refused at set-up: a required data set is missing, Geant4 is
not multithreaded, SeedOncePerCommunication is not 0, or Geant4 does not build the pinned integration driver. 4
failure during the run: any Geant4 exception that is not a warning, including one that would abort a single event,
ends the process with this status and writes no output for the chunk in progress (events are never dropped); so does
a field call outside a map at a point inside its volume with outside: "refuse" (fieldmap.outside_map). An error
is one line on stderr that starts with axmp-transport: error:. Nothing is written under out when the status is 2
or 3.
Chunk outputs¶
For every chunk k, <out>/chunk_<k>/ holds one NPY file per array and manifest.json; the directory is written as
chunk_<k>.<pid>.tmp (a directory of the writing process's own, so that a program left running by a killed driver
cannot collide with a new one) and renamed when complete, replacing an earlier chunk_<k> (a chunk that did not
finish is never renamed). Row i of every per-event array is event i of the chunk, whatever order the threads finished in.
Mode transport:
| array | dtype, shape | content |
|---|---|---|
event |
<u8 (n,) |
event index |
seed_words |
<u4 (n, 4) |
the four words that seeded the event |
first_flat |
<f8 (n,) |
u0, the first random number of the event |
primary |
<f8 (n, 7) |
x, y, z [m], px, py, pz [eV/c], E_kin [eV] of the primary as generated |
edep_eV |
<f8 (n, R) |
energy deposited per region (R regions, the solids' regions order) |
exit_eV |
<f8 (n,) |
kinetic energy of tracks entering the world or a void |
n_steps, n_tracks, field_calls, outside_calls, looping_killed |
<u8 (n,) |
per event |
looping_eV |
<f8 (n,) |
kinetic energy of the looping tracks killed |
abandoned_killed |
<u8 (n,) |
tracks Geant4's navigator abandoned as stuck (GeomNav0003), ended by the program |
abandoned_eV |
<f8 (n,) |
their kinetic energy (booked here, not in exit_eV) |
hits_<name>_count, hits_<name>_dropped |
<u4 (n,) |
records kept and dropped per event |
hits_<name>_event |
<u8 (m,) |
the hit records, sorted by event, then in the event's step order |
hits_<name>_track, _parent, _pdg, _region |
<i4 (m,) |
|
hits_<name>_x_m, hits_<name>_p_eV_c |
<f8 (m, 3) |
the pre-step point's position; momentum |
hits_<name>_t_s, hits_<name>_ekin_eV |
<f8 (m,) |
global time since the primary vertex; kinetic energy |
tally_<name> |
<i8 (grid bins) |
sum over the chunk's events of each event's bin total rounded to the quantum |
manifest.json (schema axionmultiphysics.transport/1) records chunk, chunk_seed, events, threads, the
versions, physics_list, production_cut_m, integrator (with stepper), quantum_eV, outside, regions,
arrays (each array's file, dtype, shape and SHA-256), counters (field_calls, outside_calls,
looping_killed, looping_eV, abandoned_killed, abandoned_eV, hits_dropped) and timing. The record (record, default <out>/record.json)
records the status, the mode, the threads, the chunks run, seed_once_per_communication (always 0), the totals of
field calls, outside calls, looping tracks killed and abandoned tracks, and timing: startup_s, the time from the start of the
process to the first event (Geant4's initialisation, physics tables and thread start; about 1 s for FTFP_BERT on
the cluster's nodes, whatever the number of threads), and total_s.
Seeding and reproducibility¶
The seed of an event depends only on the chunk seed and the event's index in the chunk. The four 32-bit words are the
outputs 2e and 2e+1 of the SplitMix64 sequence that starts at the chunk seed (the outputs of the generator of
Steele, Lea and Flood, 2014), low half first. They are installed with G4Random::setTheSeeds(words, 4) as the first
statement of the primary generator's GeneratePrimaries, on a MixMax engine, in every mode. Geant4 seeds the event
itself first; the words overwrite that, so the chunk size is not limited by Geant4's refill of its seeds after 10 000
events. The program refuses to start when Geant4's SeedOncePerCommunication is not 0, the mode in which the seeds of
events would depend on the thread that ran them.
An event is therefore the same whatever --threads is, whichever chunks ran before it in the process, and whichever
position it has in a longer chunk with the same seed: the arrays of a chunk are bitwise identical in all those runs
(the manifests differ in threads and timing only). This holds for one build, compiler and platform; another build
agrees statistically only.