Skip to content

File Formats

A Project workspace contains its descriptor and editable PHITS Designs.

The descriptor is strict JSON with exactly two fields:

{
  "project_id": "stable-workspace-id",
  "display_name": "Research Workspace"
}

Legacy descriptors containing solver paths, Design references, or scientific policy are rejected and must be reset explicitly; they are never loaded through compatibility defaults.

Application Execution Profile catalog

execution-profiles.json lives in the operating-system user configuration directory, outside every Project. Its root contains only profiles; every profile contains exactly these fields:

id, display_name, enabled, kind
phits_version, completion_adapter
executable_path, runtime_resource_paths, process_count
ssh_user, ssh_host, ssh_port, ssh_host_key_alias
remote_root, python_path, tmux_path, mpirun_path, hostfile_path, exclusive

Local profiles require empty remote transport fields. Disabled profiles may retain incomplete settings for correction, but unsafe paths, unsafe SSH tokens, duplicate IDs or display names, unknown fields, and process counts outside 1..4096 reject the complete candidate catalog without replacing the last valid in-memory or on-disk catalog. Enabled profiles additionally require a PHITS 3.x declaration compatible with the built-in phits-3-report-v1 completion adapter, an executable path, and at least one runtime-resource path. Credentials are not catalog fields.

The separate one-time entry point ./tools/run_macos_app.sh --migrate-execution-profiles handles the former remote-profiles.json; normal application startup reads only the new catalog. Migration renames the source to a byte-for-byte .backup, discards phits_sha256, preserves the remaining non-secret fz-mm1 settings, and emits the profile disabled with version, runtime resources, and adapter unset for explicit review. Existing new catalogs or backups make conversion a no-op.

Workspace orientation

<project-id>.ramal-project
designs/<directory>/design.inp
calculations/calculation-YYYYMMDD-HHMMMYT/calculation.json
calculations/calculation-YYYYMMDD-HHMMMYT/input/design.inp
calculations/calculation-YYYYMMDD-HHMMMYT/input/<relative-dependency>
calculations/calculation-YYYYMMDD-HHMMMYT/work/<frozen-inputs-and-produced-files>
calculations/calculation-YYYYMMDD-HHMMMYT/runner/runner.json
calculations/calculation-YYYYMMDD-HHMMMYT/runner/remote-state.json
calculations/calculation-YYYYMMDD-HHMMMYT/runner/output.log

New Calculation identities use their creation minute in fixed Malaysia Time, for example calculation-20260921-1637MYT. A second Calculation created in the same minute receives -02, then the next available numeric suffix. Existing published Calculation identities remain unchanged.

Each per-Design directory contributes only its root design.inp; sibling and included files are ordinary dependencies, not additional Designs. The PHITS bytes are authoritative, [Title] supplies the display name, and no Design record, block identity, source index, or metadata sidecar is persisted. New Designs contain UTF-8 LF [Title], the researcher-supplied title, and [End] only. Imports remain byte-exact until edited; missing boundaries require an explicit source insertion. Non-UTF-8 inputs remain read-only until explicit conversion.

Calculation creation stages the Design, the complete selected relative dependency closure, the resolved non-secret Execution Profile snapshot, identity, timestamps, adapter identity/version, and initial lifecycle together; only a successful directory rename makes the record visible. Queued records start FIFO per Execution Profile only while a GUI session has the Project open. The GUI atomically claims each profile slot with runner/runner.json and starts the application executable in runner mode. Local execution stages work through a replace-safe temporary directory. Remote execution derives its persistent path and tmux session solely from Project and Calculation identity, stages the same frozen closure without rewriting authored bytes, and uses private persistent SSH control sockets with pinned host-key identity. The MPI worker temporarily writes PHITS's fixed phits.in control file, permits only MPICH/Hydra's named temporary files outside work, and removes the control file before evidence capture. Transport loss preserves Running; terminal remote state is published only after a contained, link-free transfer has atomically replaced local work and the common completion adapter has verified the captured evidence. Reopening observes durable runner or remote state rather than submitting again.

Executable owners

Current readers and validators define the accepted shapes and integrity rules.