Skip to content

PHITS Workflow

RAMAL-EBX has one Case -> Job -> Attempt -> Result evidence path with local and remote execution targets. Odin owns Project, Case, Job, Attempt, and Result state; tools/run_case_attempt.py owns strict preparation and verification; PHITS remains the external solver. Remote SSH/MPI is transport only and never creates a second Job or Result type.

Basic workflow

  1. Open or create a Project and set its PHITS launcher and multiplier file.
  2. Import a PHITS input as a Design, or author a Design in the Design workspace. Research-specific feature comments and Case Controls may be authored in the PHITS input. RAMAL preserves them as researcher-owned data but does not provide a procedure selector, research template, or scientific acceptance criterion.

One-dimensional scanned Gaussian source

For an industrial broad-plate source, use Design > Source with a Gaussian disk (s-type = 13), a single z plane (z0 = z1), and local +Z direction. Enable 1-D scanned Gaussian and declare the scan axis (x or y), the absolute minimum and maximum Gaussian-centre positions in cm, the local Gaussian FWHM in cm, the finite support diameter/cutoff in cm, and the quadrature position count. The count must be odd, must include the centre, and must be in 3..500; the initial profile is Uniform only. These controls are source metadata, not beam-current or scan-frequency controls.

The managed Design representation preserves one exact line in [Source]:

$ ramal:source-scan enabled=1 axis=x min_cm=-50 max_cm=50 fwhm_cm=2 support_diameter_cm=3 positions=101 profile=uniform

RAMAL exports one <source> PHITS subsection per declared position. For the uniform continuous line, inclusive nodes use normalized trapezoidal quadrature: with h = 1/(N-1), endpoint weights are h/2, interior weights are h, and the weights sum to exactly 1. Each subsection retains the electron energy, s-type = 13, local FWHM, z plane, direction, particle, restriction, and transform. The [Source] card declares totfact = 1; current, pulse rate, frequency, and workload never enter these weights. PHITS s-type = 13 has no native finite radial cutoff, so the support diameter is RAMAL-owned for preview and generic finite-footprint validation; it is not silently presented as a PHITS hard truncation.

Source orientation and room axes

s-type = 13 is always authored in a local frame: the Gaussian footprint is local X-Y and the directed beam is local +Z. The Source inspector's world-axis presets create a native PHITS transform for that complete source definition, so a Down (-Y) preset produces a world X-Z footprint and world -Y beam in a Y-up room. The preset rotates the source card only; the converter, cooling, backing, and support geometry must be built or oriented normal to the same world axis. Paper 1 uses Down (-Y) as its primary D4 configuration and retains horizontal +Z delivery as an application-supported alternative; these are Project choices, not application-wide defaults.

Case creation rejects non-finite or reversed scan ranges, non-positive FWHM or support, unsupported source type/direction, even or out-of-range counts, and unsupported profiles. The current generic validator does not claim exact containment inside a converter face because converter ownership is not exposed through the reusable source API; finite converter-edge verification remains a required project gate. 3. Save the Design and resolve blocking geometry, source, result-field, tally, material, and Result-specification validation issues. The Design declares the target quantity, units, normalizations, multiplier, scale, particles, and primary particle; RAMAL-EBX does not supply a research target. An axis-aligned Analysis Region can score the voxel field, a direct PHITS region mean, or both. Both retains the spatial Result and adds a one-bin target mean with its native Monte Carlo relative error.

The Design Result field offers two explicit PHITS presets: H(10) ambient dose equivalent (-200) and H using ICRU Report 95 (-204). Selecting one derives an editable field ID, the pSv-per-primary-source-particle unit and normalization, the PHITS multiplier, and a unit source-to-output scale. The source particle is inherited into the guided field and follows later source-particle edits. Mesh limits and scored particle pages remain user choices; the scored pages are independent of the source particle used for intrinsic normalization. Custom or imported fields remain intact until the user selects a preset, and raw changes are available under Advanced overrides. Guided setup does not create a separate dose-rate tally; operating current remains the source normalization basis. 4. In Simulate, create an immutable Case from the saved Design. Case creation writes the RAMAL Case record plus a solver-clean input.inp; all $ ramal:* metadata remains in the Case record. The researcher owns methodology, predefined ranges, Dataset inclusion, limitations, and conclusions. 5. Request a Job with explicit positive maxcas, maxbch, rseed, replica index, and execution target. The target is local or a configured remote profile ID; Job is the requested execution, not evidence. 6. RAMAL allocates the next Attempt ID, copies solver-clean input to scene.phits.inp, snapshots RAMAL metadata separately, and specializes only execution controls. It never overwrites an earlier Attempt. 7. The runner records the exact executed input, command, controls, times, PHITS version, return code, logs, outputs, and result roles. Local execution starts PHITS. Remote execution atomically stages that prepared Attempt, starts a detached worker on RAMAL's dedicated tmux server, and uses phits.in with file=scene.phits.inp. 8. On solver completion, required outputs and Analysis Region reports are checked. Only a succeeded Attempt can publish a completed Result. 9. Analyze opens the Result, loads dose and uncertainty fields, and reconstructs the exact Attempt geometry in a separate immutable Scene_State.

Transport Data Check

Before a local Run starts, Simulate inspects the frozen Case input together with the PHITS installation selected by the Project. It reports the used non-void materials, requested and effective neutron/photonuclear suffixes, resolved table paths, and any natural-composition consequence. The check is an execution-target readiness diagnostic: it never rewrites Case materials or transport settings and it does not block Design save or Case creation.

The GUI states are Ready, Warning, Action required, and Unverified. Ready describes executable transport dependencies only. A separate Research model review: Required indicator is set when natural-composition omission or renormalization is present; these findings do not change an otherwise-ready transport status. H-1 (1001.20u) is omitted because no evaluated photonuclear table is applicable to that nuclide. Missing photonuclear tables for other nuclides remain a Warning because PHITS may use its reaction-model fallback. A known missing neutron dependency is Action required and blocks only a local Run. If the target is remote, local files are not pretended to describe it; the report remains Unverified and the target is checked when PHITS initializes there. Recheck refreshes the external file inspection without restarting RAMAL. Neutron selection follows the frozen input's explicit nuclide suffix, then material NLIB, then the first applicable neutron suffix in the effective xsdir; tally particle selection does not decide whether an initialization dependency is present. Relative table paths follow the xsdir directory declaration (the standard PHITS layout is <PHITS root>/XS); natural-abundance files remain under its data directory.

The Materials Inspector exposes an optional Neutron library override (nlib) for each material. Leave it empty to use the normal PHITS/material resolution; enter a suffix such as 20c or 50c to select that material's low-energy neutron table family. The value is owned by the Material and is emitted as nlib = <suffix> immediately after its mat[...] card. Recheck Transport Data uses the frozen Case input and reports the missing isotope tables for the selected family; it never changes the Case or material automatically.

For actionable missing neutron rows with a resolved continuous-energy suffix, the shared persisted-Run and new-Run details view lets the researcher choose an official, already-downloaded neutron.7z. The researcher selects which missing nuclides to install (all are selected initially), sees the resolved destination and an unknown storage estimate until the archive is inspected, and explicitly starts the operation. Rows whose neutron suffix cannot be resolved are shown as missing-required but are not offered for installation because no safe archive member can be derived. RAMAL extracts only those selected neutron files, stages them, merges the archive's exact xsdir.txt registrations atomically without reordering the existing global .50c/.20c precedence, and verifies both files and registrations. It never downloads data, accepts licenses, or changes the immutable Case, Design, or material composition. If only natural-composition omissions remain, installation is not offered; the researcher must create a separate Design/material sensitivity variant for that comparison.

After an Attempt has started, Simulate also shows a compact Observed transport findings summary beside the selected Attempt. It classifies evidence persisted in that Attempt's immutable run.log and phits.out, including missing-library messages where PHITS used a physical-model fallback and resolved neutron tables that lack gamma-ray production cross sections. This post-run summary is not a replacement for the pre-run readiness check and does not mark the Case unusable, install data, or change physics/material settings; the complete files remain available under Diagnostics.

The Result document is not trusted by itself. Opening it validates the canonical Case, Job, Attempt, manifest, result roles, fields, and exact execution input. If any check fails, the previous Analyze scene remains open.

Certified GUI path

The supported user path needs no runner command or repository script:

  1. In Projects, create or open a Project with a valid PHITS launcher and multiplier file.
  2. In Design, enter the Design name, choose Start New Design, and author or import the geometry, materials, source, and dose output. Save Design performs PHITS validation. Continue only when the activity panel says Create a new immutable Case.
  3. Choose Continue to Simulate, review the generated Case record, and choose the final Create Case action. The source Design remains editable; the new Case is immutable.
  4. Choose Run Case, review the histories, batches, reproducible seed, and execution target, then choose Create Run & Start Attempt. Progress and diagnostics remain in Simulate.
  5. A succeeded Attempt publishes a Result and opens it in Analyze. Confirm RESULT VERIFIED before using the field, uncertainty, or data provenance and traceability in scientific analysis.
  6. After restarting RAMAL, reopen the Project, go to Simulate, select the Case and Run, select its completed Result, and choose Open in Analyze. This re-verifies the persisted source records before restoring the Result view.

On macOS, the Design-name field, workflow buttons, and full-width catalog selections are mirrored into the native accessibility tree. An accessibility press remains live through the following ImGui draw only; an unconsumed press is discarded before a later screen can trigger it.

Remote PHITS transport

Remote profiles live outside the Project at ~/Library/Application Support/RAMAL-EBX/remote-profiles.json and contain one strict profiles array without an application format-version field. The Simulate and Study creation UIs offer local plus valid profile IDs; a Study propagates its selected target to its ordinary member Jobs. The transport strictly validates profile paths, SSH tokens, MPI environment names, and optional SSH routing values before use. SSH uses -p, SCP uses -P, and both use the same alias and private control socket. This supports a trusted local forward without disabling host-key checking or confusing the tunnel endpoint with the remote host identity.

AnyDesk VPN connects only the two AnyDesk endpoints and cannot reach other devices on the remote endpoint's LAN. When fz-mm1 is an internal LAN host, use an AnyDesk forward TCP tunnel instead: local 2222 to 10.10.180.64:22, then select a separate profile with ssh_host=127.0.0.1, ssh_port=2222, and ssh_host_key_alias=fz-mm1. Keep the AnyDesk session/tunnel active throughout staging, watching, and transfer. This follows the AnyDesk VPN scope and AnyDesk TCP-tunnelling procedure.

The remote worker is detached on the RAMAL-owned ramal-ebx tmux server rather than the user's long-lived default server, so stale shell/network environment cannot leak into MPI. SSH and SCP operations share a private, short-lived OpenSSH control connection; staging, launch, watching, and transfer therefore do not open route-breaking gaps or repeat full handshakes.

For a remote Run, the GUI records maxbch as the smallest multiple of mpi_processes - 1 that is not below the requested batch count, then records maxcas as the smallest value whose product with that batch count meets or exceeds the requested total histories. A 32-rank profile therefore turns a 1,000 x 1 request into 33 x 31 = 1,023 histories. All worker ranks remain active, PHITS does not rewrite the recorded schedule, and the Run form displays the rounded schedule before submission. The worker rejects incompatible persisted controls rather than silently changing them.

The worker writes only its operational state outside the remote Attempt. Its terminal manifest inventories the generated phits.in, MPI launcher, worker, hostfile snapshot, execution data provenance, logs, region reports, and result files. RAMAL transfers that directory into a sibling staging directory, checks the complete recorded controls, input, multiplier, contract, roles, regions, and manifest, then atomically replaces only the current prepared Attempt.

The normal primary progress display is filtered bat[...] ncas=... lines and histories / (maxcas * maxbch). Attempt history is selectable: older Attempts replay their persisted batch progress, while Diagnostics exposes their complete phits.out and run.log. Active remote transport tails remain separately available in Diagnostics. Watches long-poll and reconnect automatically; manual recovery is for restart/reopen recovery, not normal monitoring. Closing RAMAL or switching Projects detaches local monitoring and does not cancel the remote cluster worker. Stop Run is the explicit remote cancellation path and waits for a terminal transferred Attempt before changing the Job outcome.

Every generated MPI command starts with /usr/bin/env -u HYDRA_CONFIG_FILE and -envnone, so Hydra cannot propagate the submission host's interface to every rank. Each node retains its host-local zsh interface setup. Optional mpi_environment values are emitted as -genv arguments after -envnone.

Retry and stop behavior

Stopping a local Attempt records it as stopped and leaves the Case unchanged. A remote Stop Run requests cancellation from the detached worker; reconnection continues until its terminal Attempt transfers and then records the outcome. A retry creates a new Attempt identity and execution directory under the Job. Existing Attempt directories and Results are never overwritten. Result integrity is not the same claim as Monte Carlo convergence, experimental validation, or physical correctness.

Study execution

For multiple related Cases, create a Study in Research. The Study, not the Research workspace, references Project-local Cases. Creation records the member list, optional reference role, shared tally domain/grid, named regions, inclusion criteria, and ordinary Jobs with deterministic nonzero seeds.

study_run.odin runs those Jobs sequentially by reusing the same transient simulation.odin service and the same Case/Attempt mechanism. Study output is not a new result type: its Jobs, Attempts, and Results are ordinary records and can be opened in Analyze. Assessment re-verifies each member and records whether its positive, finite, reportable dose Result meets the predefined inclusion criteria. The detached current member survives a close or Project switch, but Study_Run orchestration itself remains transient; keep RAMAL open when a Study must advance automatically through all remaining members.

Exact runner boundary

The internal runner operations are:

python3 tools/run_case_attempt.py --prepare-attempt ...
python3 tools/run_case_attempt.py --execute-prepared-attempt <attempt-directory>
python3 tools/run_case_attempt.py --verify-succeeded-attempt <attempt-directory>
python3 tools/run_case_attempt.py --resolve-result-roles <attempt-directory>

These commands exist for RAMAL development, debugging, and the GUI's strict child-process boundary; they are not a supported end-user entry point. The GUI invokes the runner through the process group owned by process.odin/simulation.odin. There is no command-line branch in main.odin and no second execution implementation.

Evidence vocabulary

An Artifact is a file listed by path inside a manifest. It is not a Project-level record. The scientific records are Case, Job, Attempt, and Result.