Skip to content

RAMAL-EBX Research Workflow

This document describes the Research workflow implemented by the live code. It is deliberately project-neutral. Research is a GUI workspace for Study, Assessment, Dataset, Model, Prediction, and Verification records; it is not itself a persisted record and it does not introduce another PHITS runner.

Exact persistent shapes are documented in FILE_FORMATS.md. Executable code and validators remain authoritative.

Implementation boundary

This document describes available software behavior, not the methodology or scientific status of an active Project. A Project record owns its research question, accepted Results, inclusion criteria, and claims. Implemented capability does not establish their suitability or physical validity.

The implemented Dataset path currently supports:

  • scalar continuous or binary features declared in each immutable Case input;
  • an immutable scientific specification and uncertainty record for each Case;
  • one exact tally grid and scientific target specification across all samples;
  • exact [z,y,x] material-fraction, dominant-material, density, dry-air, signed-distance, region-mask, and primary-evaluation tensors;
  • a per-incident-electron dose target with reversible PHITS dose-rate Results;
  • a common positive, reportable voxel mask; and
  • deterministic reduced-order surrogate models.

The Dataset boundary supports spatial geometry tensors. The current trainer uses scalar features and reportable dose fields; any Project that requires a spatial model must define and verify that separate scientific specification.

1. Create immutable physical Cases

Each Case is one immutable PHITS scenario created from a saved Design. The Case records the immutable input path, source Design ID, and expected Result specification. Input-derived source, transport, tally, feature, material, Cell, and region facts remain directly readable from the immutable PHITS input.

Case creation may apply declared Design controls to an owned scene copy before publishing the immutable input. A supplied value set must cover every declared control exactly once. A malformed or physically inconsistent control declaration prevents publication.

Research declarations in PHITS comments are researcher-owned data. RAMAL preserves them, verifies that the persisted manifest reproduces the immutable input, and does not interpret them as protocol compliance, scientific acceptance, or Dataset eligibility. The researcher chooses methodology, inclusion criteria, acceptable ranges, limitations, and which Results are included in a Dataset.

The Case boundary must state the actual modeled system. Accelerator hardware, products, conveyors, converters, supports, or surrounding structures that are not present in the input are outside the scientific claim.

2. Declare current scalar features

Every feature selected by a current Dataset occurs exactly once in the immutable Case input. Continuous values remain numeric:

$ ramal:feature id=energy-mev value=5.0 unit=MeV
$ ramal:feature id=wall-thickness-cm value=40.0 unit=cm

Binary values use readable category IDs:

$ ramal:feature id=converter-state value=absent unit=category

The Dataset builder requires every selected declaration to match the exact feature definition, unit, domain, and numeric encoding. Missing, duplicate, non-finite, non-integral binary, or unrecognized category values fail closed.

A Case may preserve additional declarations for data provenance and traceability even when a particular Dataset does not learn them.

3. Run and assess a Study

A Study selects existing Project-local Cases and a replica count. Running it schedules ordinary Case Jobs through the same local or remote runner used by the Simulate workspace. It does not create or specialize Cases.

Study members share one immutable scientific specification and tally grid. The Study also records:

  • the physical evaluation domain;
  • explicit evaluation regions;
  • the maximum acceptable PHITS relative statistical error;
  • minimum reportable coverage; and
  • an optional reference Case.

Assessment re-reads and verifies the Study, Result, Attempt manifest, and regional fields. Missing, failed, ambiguous, unscored, non-positive, or high-error Results cannot meet the inclusion criteria. An unscored voxel is never rewritten as a zero-dose voxel.

A successful PHITS process is an execution result. It becomes eligible for a Dataset only after the Study Assessment records that it meets the predefined inclusion criteria.

4. Build the current Dataset

The Dataset specification binds one Study and one Assessment, declares the feature definitions, selects members meeting the inclusion criteria, and assigns whole configurations to train, validation, or final-test.

The partitioning method is declared-whole-configuration. No builder or trainer may randomly reassign samples. If paired_feature_id names a binary feature, every non-paired feature configuration must contain one member from each category and the pair must remain in one partition. Otherwise paired_feature_id is empty.

The builder independently verifies all upstream data provenance and then requires:

  • one exact scientific target and coordinate grid;
  • unique physical feature vectors and Results;
  • positive finite target values in the retained field;
  • relative statistical error within the Study limit; and
  • a common reportable mask meeting the declared minimum coverage.

dose.npy contains the reportable target in the intrinsic unit and normalization recorded by the shared Case specification. dose-rate.npy preserves the declared PHITS output field, and current-multiplier.npy preserves the exact positive set: c1[...] scale between them. The filenames identify storage roles; Dataset target metadata defines the physical quantity. Alongside scalar features, errors, partitions, masks, and coordinates, the Dataset carries full-grid material fractions, dominant-material IDs, density, dry-air fraction, signed distance, Case region masks, and the primary evaluation mask in canonical [z,y,x] order. Verification reconstructs those tensors from every immutable Case rather than trusting the NPY files alone.

The current exact room exporter supports baked, untransformed RPP Cells. Fine source-head transport geometry remains in the authoritative PHITS input and its static source specification; expanding room tensor support beyond that current family requires a new verified exporter rather than silent approximation.

5. Train and finalize the current surrogate Model

The current trainer compares exactly three deterministic candidates:

  1. nearest-training-configuration;
  2. quadratic-log-dose-pod-ridge; and
  3. log-dose-pod-rbf-gp.

The POD representation is learned from training fields only. Model-selection log_rmse selects the candidate. The final-test partition is not used during model selection. Model publication is non-overwriting and records the Dataset path, training procedure, arrays, metrics, and artifact paths.

This reduced-order surrogate path should be treated as a baseline when a future spatial Paper 1 pipeline is implemented.

6. Evaluate the untouched final test

Explicit final evaluation opens the final-test partition after the Model is finalized. Results include aggregate and per-configuration metrics, plus per-category metrics for every binary feature. The exact evaluation object is reproducible from the finalized Model and Dataset.

Scientific reporting must not rely on one aggregate score when distinct source modes, geometry families, dose bands, or regions are part of the claim.

7. Predict and independently verify

A current Prediction contains an in-domain scalar feature vector for one finalized Model. Binary inputs remain numeric in the record and appear as category controls in the GUI. Invalid feature counts, order, categories, or domains fail closed.

Prediction Verification binds a separately created immutable matching PHITS Case and Result. It records Result data provenance and traceability, reportable coverage, PHITS relative error, field error, and uncertainty comparison. A Prediction is never promoted into a PHITS Result.

GUI and task ownership

The GUI is the only supported user workflow. Dataset, Model, Prediction, and Verification scripts are implementation backends invoked by the Research workspace; direct script use is development and debugging only.

Simulation, Study_Run, and ML_Task are transient state. Project, Design, Case, Job, Attempt, Result, Study, Assessment, Dataset, Model, Prediction, and Prediction Verification are persisted records. Catalogs and the Research_Index are rebuilt runtime indexes.

Deletion and dependencies

The rebuilt Research index fails closed on malformed records and enforces the dependency direction:

Study -> Dataset -> Model -> Prediction

Deleting a Study never deletes the Cases, Jobs, Attempts, or Results that supplied it. Prediction Verification belongs to its Prediction and is removed with it. Destructive Research actions remain blocked when dependency evidence is unavailable or malformed.