Adds openPMD extension for the code RHINO

EXT_RHINO.md

@@ -0,0 +1,338 @@
+RHINO Extension to the openPMD Standard for Fuel-Cycle Inventory Data
+=====================================================================
+
+openPMD extension name: `RHINO`
+
+
+Introduction
+------------
+
+This extension defines naming conventions and metadata for fuel-cycle inventory
+data generated by or converted from the RHINO code. RHINO data describes
+species inventories, subsystem configuration, run inputs, derived outputs, and
+provenance for one fuel-cycle run.
+
+The RHINO shim-layer implementation stores one ADIOS2 BP5 openPMD series per
+RHINO run. The current implementation stores a single openPMD iteration and
+places the full time history in particle-style records below the iteration's
+`particlesPath`. This layout is intended for table-like, non-spatial inventory
+data.
+
+This extension uses RHINO in the sense of the Reduced Hydrogen INventory
+Optimization model described by Malone et al. [1].
+
+
+How to Use this Extension
+-------------------------
+
+Files using RHINO-specific names and attributes should include `RHINO` in the
+root `openPMDextension` attribute. The current shim does not set this attribute
+yet, so existing files may need it added to advertise the extension:
+
+```
+  openPMDextension = RHINO
+```
+
+The current RHINO shim layer writes the RHINO species name `Tritium` and does
+not write a `speciesType` attribute.
+
+RHINO files should set the base openPMD root attributes `software`,
+`softwareVersion`, `author`, and `date` when those values are available.
+
+
+Definitions
+-----------
+
+- **RHINO dataset**: An openPMD series that stores data generated by or
+  converted from the RHINO code.
+
+- **Species**: A material or application-defined species tracked by RHINO.
+
+- **Subsystem**: A named RHINO system component through which a species can
+  move or in which a species inventory can be stored.
+
+- **Time history**: A two-dimensional species inventory array whose first axis
+  indexes subsystems and whose second axis indexes simulation time.
+
+- **Steady-state inventory**: A one-dimensional species inventory array whose
+  axis indexes subsystems.
+
+
+Series Attributes
+-----------------
+
+The following additional attributes are defined for the root group (path `/`).
+
+- `softwareDescription`
+  - type: *(string)*
+  - scope: *optional*
+  - description: Human-readable description of the producing software.
+  - example: `RHINO: Fusion Pilot Plant fuel cycle simulation`
+
+- `authorAffiliation`
+  - type: *(string)*
+  - scope: *optional*
+  - description: Affiliation of the author.
+
+- `authorEmail`
+  - type: *(string)*
+  - scope: *optional*
+  - description: Contact email for the author.
+
+- `machine`
+  - type: *(string)*
+  - scope: *optional*
+  - description: Identifier for the machine, facility, or system that generated
+    the input data.
+
+- `comment`
+  - type: *(string)*
+  - scope: *optional*
+  - description: Free-form run comment. The RHINO shim uses this field for
+    input-data provenance.
+
+The current RHINO shim also writes run inputs and derived outputs as root
+attributes with prefixed names:
+
+- `input:<key>:<description>`
+  - type: scalar *(string)*, *(floatX)*, *(intX)*, or *(uintX)*
+  - scope: *optional*
+  - description: RHINO run input. `<key>` is a compact machine-readable name
+    and `<description>` is a human-readable label.
+  - examples:
+    - `input:TBR:Tritium Breeding Ratio`
+    - `input:TBRr:Required Tritium Breeding Ratio`
+    - `input:beta:Burn fraction`
+    - `input:eta:Fueling efficiency`
+    - `input:Ndotminus:Tritium burned per day`
+    - `input:MW:Power output in MW`
+    - `input:I0_SD:Starting inventory`
+
+- `output:<name>`
+  - type: scalar *(string)*, *(floatX)*, *(intX)*, or *(uintX)*
+  - scope: *optional*
+  - description: RHINO-derived output or post-processed quantity.
+  - example: `output:Steady state time (days)`
+
+Iteration Layout
+----------------
+
+RHINO shim output stores one openPMD iteration, normally `/data/0/`, with the
+full simulation time history encoded inside records of that iteration.
+
+The base openPMD iteration attributes apply:
+
+- `time`
+  - type: *(float64 / REAL8)*
+  - value in the RHINO shim implementation: `0.0`
+
+- `dt`
+  - type: *(float64 / REAL8)*
+  - description: RHINO timestep in iteration time units.
+
+- `timeUnitSI`
+  - type: *(float64 / REAL8)*
+  - value in the RHINO shim implementation: `86400.0`
+  - description: The RHINO shim stores time in days.
+
+
+Particle Inventory Layout
+-------------------------
+
+The RHINO shim sets `particlesPath` to `inventory`. Therefore, particle-style
+RHINO records are stored below:
+
+```
+  <basePath>inventory/
+```
+
+These groups are used as table-like containers for non-spatial arrays. RHINO
+inventory readers should interpret the records by the RHINO attributes defined
+here, not as physical particle phase-space data.
+
+The current RHINO shim does not write standard `position/` or
+`positionOffset/` records because the stored data is non-spatial.
+
+### Group `<basePath>inventory/Times/`
+
+The `Times` particle group stores the simulation time coordinate shared by
+species time-history records.
+
+- `description`
+  - type: *(string)*
+  - scope: *recommended*
+  - value in the RHINO shim implementation: `Times`
+
+The following particle record is defined:
+
+- `data`
+  - type: one-dimensional array of *(floatX)*
+  - scope: *required*
+  - description: Time coordinate values.
+  - `unitDimension`: time, equivalent to `(0., 0., 1., 0., 0., 0., 0.)`
+  - `unitSI`: `86400.0`
+
+### Species Inventory Groups
+
+Each species inventory is stored as a particle group named by the RHINO species
+name. The current RHINO shim writes only:
+
+```
+  <basePath>inventory/Tritium/
+```
+
+The following additional attributes are defined for each RHINO species
+inventory group:
+
+- `description`
+  - type: *(string)*
+  - scope: *recommended*
+  - description: Human-readable description of the species inventory group.
+
+- `timeAxis`
+  - type: *(uint32)* or *(intX)*
+  - scope: *required* for two-dimensional time-history records
+  - value in the RHINO shim implementation: `1`
+  - description: Axis index of the time dimension in time-history records.
+
+- `subsystemsAxis`
+  - type: *(uint32)* or *(intX)*
+  - scope: *required* for records indexed by subsystem
+  - value in the RHINO shim implementation: `0`
+  - description: Axis index of the subsystem dimension.
+
+The following particle records are defined for each species inventory group:
+
+- `mass`
+  - type: two-dimensional array of *(floatX)*
+  - scope: *required* for time-history inventory data
+  - description: Species mass inventory by subsystem and time.
+  - shape: `(nSubsystems, nTimes)` when `subsystemsAxis = 0` and
+    `timeAxis = 1`
+  - `unitDimension`: mass, equivalent to `(0., 1., 0., 0., 0., 0., 0.)`
+  - `unitSI`: `1.0e-3` for RHINO shim output, converting stored grams to kg.
+
+- `mass_steady`
+  - type: one-dimensional array of *(floatX)*
+  - scope: *required* when steady-state data is available
+  - description: Steady-state species mass inventory by subsystem.
+  - shape: `(nSubsystems)`
+  - `unitDimension`: mass, equivalent to `(0., 1., 0., 0., 0., 0., 0.)`
+  - `unitSI`: `1.0e-3` for RHINO shim output, converting stored grams to kg.
+
+- `subsystems`
+  - type: record with one component per RHINO subsystem
+  - scope: *recommended*
+  - description: Subsystem definitions and per-subsystem RHINO input metadata.
+    The component names are RHINO subsystem names.
+
+Each component of the `subsystems` record may carry the following attributes:
+
+- `id`
+  - type: *(intX)* or *(uintX)*
+  - scope: *recommended*
+  - description: Numeric subsystem identifier from the RHINO input.
+
+- `processing time`
+  - type: scalar *(floatX)*, *(intX)*, *(uintX)*, or *(string)*
+  - scope: *optional*
+  - description: RHINO processing-time input for the subsystem.
+
+- `nonradioactive loss fraction`
+  - type: scalar *(floatX)*, *(intX)*, *(uintX)*, or *(string)*
+  - scope: *optional*
+  - description: RHINO nonradioactive loss-fraction input.
+
+- `fractional inflows`
+  - type: scalar or array
+  - scope: *optional*
+  - description: RHINO fractional inflow specification.
+
+- `initial mass`
+  - type: scalar *(floatX)*, *(intX)*, *(uintX)*, or *(string)*
+  - scope: *optional*
+  - description: RHINO initial mass input for the subsystem.
+
+- `source`
+  - type: scalar or array
+  - scope: *optional*
+  - description: RHINO source specification.
+
+- `injectors`
+  - type: scalar or array
+  - scope: *optional*
+  - description: RHINO injector specification.
+
+- `label`
+  - type: *(string)*
+  - scope: *optional*
+  - description: Human-readable subsystem label.
+
+The semantic subsystem description is carried by the component name and
+component attributes. Existing shim output may store the shared time coordinate
+as the component dataset payload; readers should not interpret that payload as
+the subsystem definition.
+
+Example RHINO Shim Layout
+-------------------------
+
+The following example shows the RHINO shim layout.
+
+```
+/
+  openPMD = "1.1.0"
+  basePath = "/data/%T/"
+  particlesPath = "inventory"
+  software = "RHINO"
+  softwareVersion = "1.0"
+  softwareDescription = "RHINO: Fusion Pilot Plant fuel cycle simulation"
+  author = "..."
+  authorAffiliation = "..."
+  authorEmail = "..."
+  date = "1234-56-78"
+  machine = ""
+  comment = "Provenance: data path is ..., input file is ..."
+  input:TBR:Tritium Breeding Ratio = ...
+  input:TBRr:Required Tritium Breeding Ratio = ...
+  input:beta:Burn fraction = ...
+  input:eta:Fueling efficiency = ...
+  input:Ndotminus:Tritium burned per day = ...
+  input:MW:Power output in MW = ...
+  input:I0_SD:Starting inventory = ...
+  output:Steady state time (days) = ...
+
+  data/
+    0/
+      time = 0.0
+      dt = ...
+      timeUnitSI = 86400.0
+      inventory/
+        Times/
+          description = "Times"
+          data
+        Tritium/
+          description = "Inventory across subsystems for species Tritium"
+          timeAxis = 1
+          subsystemsAxis = 0
+          mass
+          mass_steady
+          subsystems/
+            <subsystem-name>
+              id = ...
+              processing time = ...
+              nonradioactive loss fraction = ...
+              fractional inflows = ...
+              initial mass = ...
+              source = ...
+              injectors = ...
+              label = ...
+```
+
+
+References
+----------
+
+[1] C. R. Malone, H. B. Flynn, A. D. Somers, P. A. Rowell, and
+G. K. Larsen, "Approach to startup inventory for viable commercial fusion
+power plant," *Fusion Engineering and Design*, vol. 206, 114563, 2024.
+doi: [10.1016/j.fusengdes.2024.114563](https://doi.org/10.1016/j.fusengdes.2024.114563)