Skip to content

PHITS Workflow

The supported researcher path covers authoritative PHITS Design authoring, Project-independent Execution Profile management, sandboxed local and remote Calculations, verified Result publication, frozen-geometry and typed voxel-field inspection, and universal Raw analysis.

Researcher path

  1. Project — Create or open a workspace containing editable Designs.
  2. Design — Create or import a PHITS input, edit it through structured controls or direct source editing, validate it, and save it.
  3. Execution Profiles — Independently list, create, edit, validate, and remove local or remote PHITS environments from application configuration. Disabled drafts may be incomplete; enabling requires a declared PHITS version, the compatible built-in completion adapter, safe resolved paths and transport tokens, and a valid process count.
  4. Calculate — Select a Design and compatible local or remote profile, review detected and manually added relative dependencies, then atomically freeze the byte-exact input and dependency closure. The Calculation enters one durable per-profile FIFO queue. The independent runner uses the same lifecycle for either transport. Local work executes through the macOS sandbox. Remote work derives its sandbox and detached tmux session only from Project and Calculation identity, stages the complete frozen closure over pinned-host SSH, isolates Hydra environment inheritance, and reconnects after GUI or transport loss without resubmission. The Calculate card mirrors the authoritative remote state and combined stdout/stderr while execution continues. A remote process exit remains Running as Finalizing locally until its contained output, logs, and diagnostics are captured locally and verified by the configured completion adapter. Stop cancels setup before transport or interrupts the remote tmux session, and reaches Stopped only after local process-group or remote termination is confirmed. Result publication asserts adapter-compatible completion and evidence integrity only; it makes no local-versus-remote scientific-equivalence claim.
  5. Analyze — Open any Project Result in a viewport-first, read-only workspace. The scene is reconstructed only from that Calculation's immutable input/design.inp and declared infl: dependency closure, so later Design changes cannot alter Result geometry. For any verified Succeeded PHITS Result, the built-in voxel adapter asynchronously matches the frozen rectilinear tally declaration to the exact declared report, VTK values, and paired relative-error artifacts; validates the artifact structure, scientific identity, particles, grid, ordered coordinates, values, and uncertainties; and renders selectable source voxels in the frozen geometry. Compatibility follows the validated tally and artifact contract rather than a hard-coded PHITS version. The toolbar shows the active Result and field identity, while the inspector reports the selected voxel's exact index, coordinates, value, particle, uncertainty, validity, and artifact provenance. Stale adapter completions are discarded when Result selection changes. Unsupported or malformed geometry or rich artifacts produce local diagnostics while the evidence rail and universal Raw inspector remain available. Raw inspects every created or changed contained regular file with paged searchable text or a bounded binary preview, plus copy, export, reveal, and operating-system open actions. Frozen inputs, profile settings, stdout, stderr, diagnostics, and lifecycle remain adjacent Calculation evidence rather than Result artifacts.

Analyze uses one spatial probe across the frozen-geometry viewport, inspector, active orthogonal slice, X/Y/Z profiles, and plot cursor. Hover previews a voxel without replacing the lock; click locks it. Profile and heatmap dragging, exact slice-cell controls, and domain-level keyboard actions move the same probe bidirectionally. Profiles retain source coordinates, quantity, unit, particle identity, values, and paired relative errors; orthogonal slices retain source-axis orientation and bounds. A visible, ordered transformation stack owns the shared field display: logarithmic scaling defaults to the complete positive source range, the reversible robust shortcut selects the positive 2nd–98th percentile range, invalid ordering is rejected with an explanation, and reset restores the defaults. Exact zero, negative, invalid, and unscored categories remain labelled outside the logarithmic scale. The default 3D view ray-marches an LOD-bounded 3D texture through the frozen field bounds, with reviewed broad-range, low-dose-emphasis, and high-dose-emphasis transfer presets plus an expandable normalized RGBA curve editor. Frozen geometry is subdued through contextual transparency while the selected structure remains opaque. The labelled Source, Fine, Balanced, or Coarse display LOD states show the actual display-grid and source-grid voxel counts; sampled states say explicitly that they are display samples, while probes, plots, tables, statistics, recipes, and exports continue to use exact source voxels. These operations change only presentation; exact inspector values and immutable Result bytes remain unchanged. The viewport cutaway clips only frozen geometry along a selectable X, Y, or Z plane, so enclosed dose voxels and the shared probe remain visible without changing Result data.

Execution Profile credentials are never stored in the catalog. SSH authentication remains in external operating-system or SSH-agent/keychain storage. The catalog records only non-secret executable, runtime-resource, transport, and process settings.

The PHITS input remains solver-owned: RAMAL metadata is not injected into or interpreted from it. Unrecognized PHITS content remains available for direct inspection and editing rather than receiving invented application meaning.

The functional 3D viewport remains central. The left PHITS Explorer presents pre-section content, every literal section occurrence, and every safely indexed subject in authoritative byte order. Choosing a subject updates the shared revision-checked selection and routes its applicable structured controls and PHITS guidance into permanent contextual Properties. Properties also shows an editable exact-source excerpt only for that subject's reliable owned byte range; opaque subjects remain exactly editable without invented fields. A collapsible, vertically resizable source drawer beneath the viewport shows the complete authoritative input and moves its selection and keyboard focus to the active Design subject.

Structured controls target PHITS 3.37 as an authoring preview, not a supported authoring version. Exact source remains available for documented constructs that do not yet have complete section-specific controls and PHITS help.

New Designs start as UTF-8 LF [Title], the supplied title, and [End]. Imported files are never normalized or repaired automatically. Missing or misplaced boundary sections are diagnosed; explicit repair actions insert only the requested source bytes, while empty and PHITS-invalid sections remain saveable.

Committed structured, exact-source, and full-document changes use one application-level edit transaction: an exact byte range or insertion anchor plus the expected document revision. Accepted edits advance the revision, update dirty and source-selection state, rebuild disposable interpretation, and enter the shared chronological undo history. Continuous direct typing coalesces into one history step. An exact-source excerpt additionally requires its selected owned range to remain current. A stale revision or subject is rejected without changing source; an externally changed file replaces the stale in-memory draft rather than being merged or overwritten. Undo and redo restore authoritative bytes, source selection, and derived state together.

The Design Properties panel shows the PHITS world medium. Ordinary new Designs start at Air; selecting Vacuum writes a materialless world cell (material 0) into the authoritative input. Selecting Air writes the canonical dry-air material and world cell. The choice enters the same source revision, dirty state, and undo history as other edits, and Calculate freezes the saved source bytes. Imported materialless world cells reopen as Vacuum. Ambiguous or conflicting imported world cards require exact-source editing rather than an unsafe automatic rewrite.

Saving is independent of PHITS validity. Incomplete or invalid UTF-8 source remains editable and saveable. Non-UTF-8 input remains byte-preserved and read-only until the researcher explicitly converts it from Properties.

Repository scripts and direct PHITS invocation remain development and debugging tools, not supported researcher workflows.

The former remote-profiles.json is available only to the separate one-time migration entry point, ./tools/run_macos_app.sh --migrate-execution-profiles; normal application startup never reads it. Migration preserves the fz-mm1 non-secret settings, renames the source to remote-profiles.json.backup, discards the obsolete executable hash, and creates a disabled profile whose PHITS version, runtime resources, and completion adapter must be reviewed before launch.

Output reader compatibility

Analyze uses the same reader for compatible artifact structures regardless of the producer's PHITS version. An unfamiliar release label does not block inspection, and a familiar release label does not make malformed data acceptable. PHITS version remains unchanged in the Calculation evidence. Reader-contract revisions, where used for reproducible interpretation, identify RAMAL interpretation behavior rather than an allowed PHITS release list.

The voxel reader still needs a Succeeded Calculation, understood frozen tally context, the declared report and its value/error artifacts, safe contained paths, interpretable quantity/units/normalization, and consistent particle pages and grids. Removing a producer-version check does not create missing VTK files, supply missing uncertainty, or convert an unsupported output family into dose. Unsupported structures remain inspectable through Raw with a diagnostic; extending a reader requires a concrete format example and tests rather than another release whitelist. Execution completion/version-provenance checks and input-authoring guidance are separate and are unchanged by this reader correction.

The PHITS manual's tally output description identifies the tally input echo, named output, and generated companion-file conventions. The VTK legacy-format specification defines the format header, dataset structure, coordinates, and data associations. The artifact format and its explicit semantics determine what can be decoded; the VTK format header is not a PHITS release identifier.

analyze_voxel_reader_test.odin holds synthetic version-label independence and invalid-artifact/context regression cases. These are tests of reader behavior, not records of executing multiple PHITS releases or validating a physical model.

Source map