Skip to content

RAMAL-EBX Architecture

The live source is the authority. This document is a compact ownership map of that source and the data flow it implements. It does not describe removed formats or compatibility behavior.

Runtime shape

Normal startup enters main.odin, initializes SDL, the GPU device, development shader freshness, ImGui, and App_State, then runs one editor frame loop. The executable does not dispatch a command-line mode or hide a second worker mode.

app_state.odin owns only the application state shape and lifecycle. Frame polling, UI dispatch, rendering, and task polling are in app_runtime.odin. app_project.odin stages Project open/close and swaps Project-owned state as one operation.

The user-facing surface begins at the Project Library. Opening a Project exposes three primary lifecycle workspaces and one separate optional workspace:

Project Library -> Open Project
                   ├── Lifecycle: Design | Simulate | Analyze
                   └── Research

Research uses the same Project-local records without becoming a fourth lifecycle stage.

The records and their normal data provenance are:

Project
├── Design                         editable PHITS intent
├── Case                           immutable scenario
│   └── Job -> Attempt -> Result   execution traceability and output
└── Study -> Assessment            comparison definition and assessed Results
    └── Dataset -> Model -> Prediction -> Verification

Study members reference Project-local Cases; the diagram shows composition, not that a Study owns or copies those Cases.

Application and Project boundary

RAMAL-EBX is the reusable research application. A paper, experiment, or research programme is Project data inside that application; it is not a compiled subsystem or application mode.

The application owns reusable GUI mechanisms:

  • PHITS Design authoring, import, validation, and visualization;
  • parameter declaration and immutable Case generation;
  • local and remote execution, monitoring, and Result inspection;
  • Study construction, Result comparison, and Assessment;
  • Dataset construction, declared partitions, surrogate-model training and evaluation;
  • prediction and independent PHITS verification; and
  • strict record identity, consistency, and integrity checks.

Each Project owns its scientific question, energy and source domains, quantities, units, normalization, materials, geometries, scan definitions, transport settings, inclusion criteria, Dataset specification, model experiments, references, Results, and limitations.

A Project may expose a missing application capability. Development then adds the smallest reusable GUI operation that satisfies the underlying researcher need and stores the scientific values in Project records. Application code must not promote one Project's energies, materials, geometry family, dose quantity, PHITS multiplier, source mode, threshold, Dataset target, model choice, or scientific acceptance criterion into application-wide behavior.

Application validation may enforce declared structure and consistency. It does not choose scientific criteria. Project-specific examples, templates, benchmark data, and specifications remain Project assets rather than normal application control flow.

Ownership map

Project and storage

  • project.odin owns the Project descriptor, Project catalog, Project paths, creation, duplication, identity changes, and whole-Project deletion.
  • project_storage.odin owns shared Project-relative path validation, resolution, IDs, UTC timestamps, and SHA-256 helpers.
  • storage.odin owns atomic and exclusive file writes.
  • app_project.odin owns staged Project loading, Project switching, and clearing Project-owned runtime state.
  • owned_string.odin owns the explicit owned-string cleanup used by the data structures.

Project data is strict and contained in its canonical workspace. Project deletion stops Project-owned work and removes the complete Project directory.

Design, PHITS, and geometry

  • design.odin owns Design catalog entries, Design input paths, titles, identity changes, and Design directory operations.
  • design_phits.odin owns the active Design PHITS source and import/save/ reload synchronization.
  • design_phits_edit.odin owns PHITS source, tally, profile-tally, assessment-point, and analysis-region editing.
  • design_geometry_edit.odin owns geometry authoring operations and their connection to CSG services.
  • design_history.odin owns Design undo/redo snapshots.
  • geometry.odin owns PHITS surfaces, cells, materials, expressions, and CSG meaning.
  • phits.odin owns PHITS domain types, cards, import, and generation.
  • phits_document.odin owns PHITS block parsing and preservation of untouched/unknown text sections at the external-format boundary.
  • phits_transform.odin owns PHITS TRCL transforms.
  • analysis_region.odin owns named analysis-region definitions stored in the RAMAL Design record.

Each Design has a RAMAL JSON record and a solver-clean PHITS input. RAMAL-only metadata stays in the record; every persisted .inp omits $ ramal:* lines. Cases and Attempts preserve both forms, but PHITS receives only the clean input.

Preview and rendering

  • csg_mesh.odin evaluates PHITS cell expressions and extracts inspection meshes with Marching Cubes.
  • csg_mesh_cache.odin owns CPU/disk mesh caching.
  • preview_mesh_job.odin owns asynchronous preview-mesh work.
  • cell_diagnostic_cache.odin owns cached cell diagnostics.
  • renderer.odin owns the GPU scene renderer.
  • renderer_cells.odin owns renderer cell models.
  • renderer_preview.odin owns preview mesh preparation and GPU upload data.
  • editor_viewport_interaction.odin owns selection, camera/ray input, and gizmos.
  • editor_geometry.odin owns shared cached cell-mesh, diagnostic, bounds, and picking queries used across editor and renderer flows.
  • editor_viewport_overlays.odin owns labels, diagnostic overlays, and scientific drawing.

Scene_State in scene_state.odin contains one Geometry, one PHITS_State, dirty state, and Design history. It is shared as a data shape, not a domain record: the editable Design uses one instance, while Analyze reconstructs a separate instance from the verified Attempt input for an immutable Result. A generated CSG mesh or renderer cache never becomes geometry truth.

Cases and execution

  • case.odin owns the immutable Case input, its Result_Contract implementation schema, persistence, catalog, and creation from a valid saved Design.
  • job.odin owns the requested execution, run controls, Job persistence, and Job catalog. Job.execution_target is the stable selector: local or a safe remote-profile ID.
  • attempt.odin owns one non-overwriting try, its paths, manifest shape, and calls to the strict verifier.
  • simulation.odin owns one transient execution state, local process control, remote submit/watch/transfer recovery, and handoff to Result publication.
  • remote_phits.odin owns strict profile loading, target validation, and the contained operational sidecar beside an untransferred Attempt.
  • process.odin owns process-group start/stop control.
  • result.odin owns completed Result documents, publication, catalogs, and opened-Result identity.
  • dose_field.odin owns loaded dose/uncertainty field data used by Analyze.

tools/run_case_attempt.py is the strict Python boundary for preparing, inventorying, and verifying one Attempt. Local Jobs execute it directly. Remote Jobs use tools/remote_phits.py and its staged remote_phits_worker.py only as SSH/MPI transport: the worker completes the same manifest shape, then the terminal Attempt is transferred atomically and passes the same verifier before result.odin can publish a Result. The GUI and Study runner do not own a parallel Job or Result model.

Studies and research

  • study.odin owns persistent Study definitions, Project-local Case member references, Study catalogs, and Study creation.
  • study_run.odin owns transient sequential Study orchestration. It reuses simulation.odin for each ordinary Job.
  • assessment.odin owns persisted quality assessments and recomputed regional metrics.
  • research_index.odin reconstructs the Project-local index for Studies, Datasets, Models, Predictions, and Prediction Verifications. It also owns fail-closed dependency checks for Research-record deletion. The index is runtime state, not a persisted Project-level record.
  • ml_task.odin owns one transient, stoppable Python ML task and its log. It launches repository tools with the configured python3; dependency failures surface directly in the task log.
  • tools/build_dataset.py builds and verifies Datasets from Study assessments that meet their declared inclusion criteria.
  • tools/ramal_ml.py contains the implemented reduced-order ML algorithms.
  • tools/model_pipeline.py finalizes Models, evaluates the final-test partition, creates Predictions, and verifies Predictions against PHITS Results.

Research is the workspace containing these workflows. It is not an additional record or a second catalog of scientific truth.

Explicit editor ownership

editor_shell.odin owns the persistent shell, Project Library boundary, three-stage Project lifecycle navigation, separate Research access, global Design save/close safety, and workspace dispatch. The Project Library and workspace files own their bodies:

  • editor_project_ui.odin — Project Library and Project management.
  • editor_design_ui.odin — Design shell, catalog layout, viewport, and draw flow.
  • editor_design_geometry_ui.odin — geometry and cell authoring panels.
  • editor_design_material_ui.odin — material authoring panels.
  • editor_design_phits_ui.odin — PHITS source/tally/assessment panels.
  • editor_design_validation.odin — Design readiness and diagnostics.
  • editor_design_analysis_ui.odin — Design analysis-region controls.
  • editor_simulate_ui.odin — Case, Job, Attempt, and Result execution UI.
  • editor_analysis_ui.odin — completed Result view and Analyze controls.
  • editor_research_ui.odin — Research overview and navigation.
  • editor_study_ui.odin — Study and Assessment stages.
  • editor_ml_ui.odin — Dataset, Model, Prediction, and Verification stages.

The shell does not contain a fallback layout or workspace-specific domain ownership.

Runtime/data flow

  1. Project open is staged by app_project.odin; catalogs and the Research index are rebuilt from the canonical Project directories.
  2. Design edits mutate the editable Scene_State and save a PHITS input.
  3. Case creation records that input and its Result specification immutably under cases/.
  4. Simulate creates a Job. Each execution allocates the next Attempt, copies the Case input to scene.phits.inp, applies only run controls, and snapshots decisive inputs and hashes.
  5. A local Job executes PHITS directly. A remote Job stages that prepared Attempt, runs detached under the selected SSH/MPI profile, then transfers the terminal immutable Attempt back atomically. Both paths verify the same complete manifest before result.odin publishes a Result.
  6. Analyze verifies the Result again, loads its fields, and imports the exact Attempt input into the separate immutable Scene_State.
  7. A Study creates ordinary Jobs for its Case members and study_run.odin executes them sequentially. Assessment re-verifies the resulting Results.
  8. ML tools compose the verified records and run in the Python process group.

If Result opening fails, the previous Analyze scene and fields remain in place.

Remote operational state is intentionally not a Project record. A strict sidecar adjacent to the still-prepared local Attempt records the remote path, RAMAL-owned tmux identity, and watch state. It is never part of the manifest inventory. Closing or switching Projects stops only local SSH monitoring; the detached remote worker remains recoverable after reopening the original Project.

Deletion and dependency ownership

  • Project deletion cascades the whole Project directory.
  • Case deletion removes the Case directory, including its Job, Attempt, and Result records. It is blocked when any Study references that Case.
  • Design deletion removes the Design directory and leaves immutable Cases intact. Design ID rename is blocked once managed Cases exist; this preserves data provenance and traceability. The code does not claim that Design deletion itself is blocked by a Case.
  • Research deletion is checked by research_index.odin. A malformed or unavailable index fails closed. Study deletion is blocked by Dataset references; Dataset deletion by Model references; Model deletion by Prediction references. A Prediction Verification is deleted with its owning Prediction, not independently. A Study deletion never deletes Case evidence.

Integrity vocabulary

An Artifact is only a file listed by relative path in a manifest. It is not a Project-level domain record. The Project, Design, Case, Job, Study, Assessment, and Result catalogs plus the Research index are reconstructed runtime indexes; Simulation, Study_Run, and ML_Task are transient services/state.