Merge pull request #70 from SteSeg/restore_doc3

more documentation

Author: SteSeg

docs/source/benchmark_collection/index.md

@@ -0,0 +1,9 @@
+# Benchmark Collection
+
+Available benchmarks. Each listed name matches the identifier expected by the `Benchmark` parent class (e.g., `OpenmcBenchmark`) in the OFB Python API for instantiation.
+
+```{toctree}
+:maxdepth: 2
+
+oktavian/index
+```

docs/source/benchmark_collection/oktavian/index.md

@@ -0,0 +1,22 @@
+# OKTAVIAN Benchmarks
+
+| **Aspect**                     | **Details**                                                                 |
+|-------------------------------|-----------------------------------------------------------------------------|
+| **Facility**                  | Osaka University, operational since 1981                                    |
+| **Neutron Source**            | 250 keV D⁺ beam on 370 GBq tritium target                                   |
+|                               | D-T fusion up to 3×10¹² neutrons/s                                          |
+| **Experiments (1984–1988)**   | Sphere pile (Al, Co, Cr, Cu, LiF, Mn, Mo, Si, Ti, W, Zr)                    |
+| **Measurement Technique**     | TOF at 11 m, 55° angle                                                      |
+| **Neutron Detector**          | NE-218 liquid scintillator (12.7 cm ⌀ × 5.1 cm)                             |
+| **Gamma Detector**            | NaI scintillator at 5.8 m                                                   |
+| **Source Characterization**   | Same TOF setup; isotropic source assumed for analysis                       |
+| **Background Suppression**    | Polyethylene/iron layered collimator facing detector                        |
+| **Calibration**               | Cf-252 TOF + graphite leakage spectra; Nb foil activation (Nb-92m)          |
+| **Gamma Reactions Observed**  | Mainly (n,n’), (n,2n); minimal (n,xγ) contribution                          |
+
+```{toctree}
+:maxdepth: 1
+
+oktavian_readme
+oktavian_al
+```

docs/source/oktavian_al_benchmark.md renamed to docs/source/benchmark_collection/oktavian/oktavian_al.md

@@ -8,7 +8,7 @@ The experimental setup employed hollow stainless-steel spherical vessels filled
 
 ## Description of Source and Experimental Configuration
 
-![Experimental configuration of OKTAVIAN experiments.](images/oktavian_exp_config.png)
+![Experimental configuration of OKTAVIAN experiments.](../../images/oktavian_exp_config.png)
 
 The experimental configuration is illustrated in the figure above {cite}`konno2023jendl`.
 

docs/source/oktavian_readme.md renamed to docs/source/benchmark_collection/oktavian/oktavian_readme.md

@@ -8,7 +8,8 @@ Welcome to the **OpenMC Fusion Benchmarks** project - a modular, code-agnostic,
 :maxdepth: 2
 
 intro
+quickstart
 user_installation
-oktavian_readme
-oktavian_al_benchmark
+specifications/index
+benchmark_collection/index
 ```

docs/source/index.md

@@ -0,0 +1,56 @@
+# Quickstart Guide
+
+This guide walks you through the basic steps to install the package, load a benchmark, run a simulation, and view results — using the **OpenMC Fusion Benchmarks** framework.
+
+> ⚠️ This guide assumes you have Python 3.9+ and a working OpenMC installation. For OpenMC setup, refer to the [OpenMC documentation](https://docs.openmc.org/en/stable/).
+
+---
+
+## Install the Package
+
+Clone the repository and install dependencies in a clean Python environment:
+
+```shell
+git clone --recurse-submodules https://github.com/eepeterson/openmc_fusion_benchmarks.git
+cd openmc_fusion_benchmarks
+pip install .
+```
+
+You may wish to make use of a virtual environment using [Conda](https://docs.conda.io/projects/conda/en/stable/user-guide/tasks/manage-environments.html), [Mamba](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html) or [Venv](https://docs.python.org/3/library/venv.html).
+
+
+## Run a Benchmark Simulation
+
+Minimal working example of instantiating and running a benchmark with the [OpenMC](https://docs.openmc.org/en/stable/) transport code. 
+
+```python
+import openmc_fusion_benchmarks as ofb
+
+benchmark = ofb.OpenmcBenchmark(name='oktavian_al')
+benchmark.run()
+```
+
+Running in uncertainty quantification mode:
+
+```python
+import openmc_fusion_benchmarks as ofb
+
+benchmark = ofb.OpenmcBenchmark(name='oktavian_al')
+benchmark.run(uq=True)
+```
+
+## Read Results
+
+Results from an OFB benchmark simulation follow a standardized [Xarray](https://docs.xarray.dev/en/stable/) structure and are easily accessible as DataArray objects through the OFB Python API.
+
+```python
+import openmc_fusion_benchmarkas as ofb
+```
+
+## Extract Results From Database
+
+OFB features a standardized, continuously updated database that includes both experimental and computational benchmark results.
+
+```python
+import openmc_fusion_benchmarkas as ofb
+```

docs/source/quickstart.md

@@ -0,0 +1,11 @@
+# Benchmark Specifications
+
+Detailed documentation on the standardized definition of benchmarks `specifications.yaml` and validation against the `benchmark_schema.yaml`.
+
+```{toctree}
+:maxdepth: 2
+
+overview
+structure
+schema
+```

docs/source/specifications/index.md

@@ -0,0 +1,65 @@
+# Overview
+
+The **OpenMC Fusion Benchmarks (OFB)** project uses a structured, YAML-based specification format to define every component of a radiation transport benchmark. This approach ensures **clarity, reproducibility, and automation** in defining, running, and analyzing benchmarks.
+
+Each benchmark is defined by a `specifications.yaml` file that is **validated against a strict schema (`benchmark_schema.yaml`)** to enforce consistency and completeness across the benchmark suite. We define a benchmark `specifications` as:
+
+> The minimum amount of technical data necessary to unambiguously model a benchmark and collect standardized results.
+
+---
+
+## Specifications Sections
+
+The `specifications.yaml` file captures all essential aspects of a benchmark, including:
+
+- **Metadata**  
+  General information such as benchmark name, description, references, authors, and version.
+  
+- **Materials**  
+  Composition, temperature, density, and other nuclear properties defined in a structured format.
+
+- **Geometry**  
+  CAD-based geometry definitions, including references to CAD files and meshing parameters.
+
+- **Sources**  
+  Neutron or photon source definitions, including energy, spatial, and angular distributions.
+
+- **Settings**  
+  Transport code configuration such as particle count, batches, and other run control parameters.
+
+- **Tallies**  
+  Definition of observables (e.g., flux, dose) with filters and expected data structure.
+
+- **Uncertainty Quantification (Optional)**  
+  Setup for input perturbations, sampling, and uncertainty propagation metrics.
+
+- **Irradiation Schedule (Optional)**  
+  Time-dependent irradiation and cooling steps for activation and shutdown dose rate analysis.
+
+---
+
+## Schema Validation
+
+To guarantee interoperability and catch user errors early, every `specifications.yaml` file must conform to the `benchmark_schema.yaml`. The schema:
+
+- Enforces required fields and correct types
+- Validates units, formats, and structure
+- Allows custom extensions while preserving core validation
+
+Validation is automatically handled by the OFB Python API.
+
+---
+
+## Why This Matters
+
+- **Consistency** across all benchmarks  
+- **Automation** of modeling, simulation, and analysis workflows  
+- **Comparability** of results across codes and experiments  
+- **Modularity** to support method testing and rapid development
+
+---
+
+## Learn More
+
+- [Specifications Structure](structure.md) — detailed documentation of `specifications.yaml` structure and syntax
+- [Benchmark Schema](schema.md) — documentation of the `benchmark_schema.yaml` and `specifications` validation

docs/source/specifications/overview.md

@@ -0,0 +1,184 @@
+# Benchmark Schema
+
+The OpenMC Fusion Benchmarks (OFB) project uses a modular, schema-driven format to ensure that all benchmark `specifications` follow a consistent, machine-validated structure.
+
+## Validation
+
+Validation can be performed anually using the OFB Python API:
+
+```python
+import openmc_fusion_benchmarks as ofb
+
+ofb.validate_benchmark('benchmark_name')
+```
+
+Alternatively, you can run the `validate_all_benchmarks.py` script located in the repository’s `scripts/` folder. This script iterates through all benchmark `specifications.yaml` files and validates them against the repository’s `benchmark_schema`.
+
+Validation output looks like:
+
+```shell
+🔍 Validating benchmark file: benchmark_name
+✅ benchmark_name is valid!
+```
+
+Or in case of validation errors:
+
+```shell
+🔍 Validating benchmark file: oktavian_al
+❌ 1 errors found in oktavian_al:
+   - None is not of type 'object' (at ['materials', 1, 'composition', 'data'])
+```
+
+In the example above, the material with `id` 1 is missing a defined composition.
+
+Validation is also automatically triggered when instantiating a `benchmark` object:
+
+```python
+import openmc_fusion_benchmarks as ofb
+
+benchmark = ofb.OpenmcBenchmark(name='benchmark_name')
+```
+```shell
+🔍 Validating benchmark file: benchmark_name
+✅ benchmark_name is valid!
+```
+
+## Purpose of the Schema
+
+To guarantee interoperability and automation, each `specifications.yaml` file must conform to a predefined [JSON Schema](https://json-schema.org/). This enables:
+
+- **Automatic validation** of input files
+- **Improved error reporting** for malformed benchmarks
+- **Robust tooling** for model generation and testing
+- **Future extensibility** of the specification format
+
+## Schema-to-Specifications Mapping
+
+The `benchmark_schema` outlines the main _sections_ expected in a `specifications.yaml` file:
+
+```yaml
+$ref: "#/components/schemas/Benchmark"
+components:
+  schemas:
+    Benchmark:
+      type: object
+      required: 
+        - metadata
+        - materials
+        - geometry
+        - sources
+        - settings
+        - tallies
+      properties:
+        metadata:
+          $ref: '#/components/schemas/Metadata'
+        materials:
+          type: array
+          items:
+            $ref: '#/components/schemas/Material'
+        ...
+```
+
+Some sections are optional and included only when relevant to the benchmark:
+
+```yaml
+        ...
+        irradiation_schedule:
+          $ref: '#/components/schemas/IrradiationSchedule'
+        uncertainty_quantification:
+          $ref: '#/components/schemas/UncertaintyQuantification'
+```
+
+Beyond defining the structure at a high level, the `schema` specifies the internal _hierarchy_ and _data types_ for each object:
+
+```yaml
+Tally:
+  type: object
+  required: [name, particle, filters, scores]
+  properties:
+    name: 
+      type: string
+      ...
+    particle:
+      type: string
+      enum: [neutron, photon, electron, positron]
+    filters:
+      type: array
+      items:
+        type: object
+        required: [type, values]
+    ...
+```
+
+Each section in a benchmark’s `specifications.yaml` is _validated_ against its corresponding `schema` definition.
+
+For example, a `density` object in the `specifications` might appear as:
+```yaml
+density:
+    value: 0.997
+    units: g/cm3
+```
+
+Its `schema` counterpart ensures the expected structure and value types:
+
+```yaml
+density:
+  type: object
+  properties:
+    value:
+      type: number
+    units:
+      type: string
+      enum: [g/cm3]
+  required: [value, units]
+```
+
+Likewise, a complete `material` entry in the `materials` list could be:
+
+```yaml
+- id: 1
+  name: Water
+  composition:
+      composition_type: element
+      fraction_type: atomic
+      data:
+      H: 0.67
+      O: 0.33
+  density:
+      value: 0.997
+      units: g/cm3
+```
+
+And its definition in the `schema` would be:
+
+```yaml
+Material:
+  type: object
+  required: [id, name, composition, density]
+  properties:
+    id:
+      type: integer
+    name:
+      type: string
+    composition:
+      type: object
+      properties:
+        composition_type:
+          type: string
+        fraction_type:
+          type: string
+          enum: [atomic, weight]
+        data:
+          type: object
+          additionalProperties:
+            type: number
+      required: [composition_type, fraction_type, data]
+    density:
+      ...
+```
+
+## Unified Schema Format
+
+The OFB schema is a **single, unified JSON Schema file** that defines the complete structure of a valid `specifications.yaml` file. It includes all top-level sections—such as `metadata`, `geometry`, `materials`, `source`, `tallies`, and others—and their corresponding nested fields.
+
+Although the schema is written modularly (with subschemas for each section), it is maintained as **one file** for simplicity, validation consistency, and ease of distribution.