diff --git a/EXT_RHINO.md b/EXT_RHINO.md new file mode 100644 index 0000000..a3f6b4f --- /dev/null +++ b/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::` + - type: scalar *(string)*, *(floatX)*, *(intX)*, or *(uintX)* + - scope: *optional* + - description: RHINO run input. `` is a compact machine-readable name + and `` 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:` + - 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: + +``` + 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 `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: + +``` + 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/ + + 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)