Update VVP for refactored MC/DC

.github/workflows/black_lint.yml

@@ -0,0 +1,27 @@
+name: Black Style Check
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  black-lint:
+    name: Lint with Black
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install Black
+        run: |
+          pip install --upgrade pip
+          pip install black
+
+      - name: Run Black (check mode)
+        run: black --check .

.gitignore

@@ -1,19 +1,29 @@
-configs/launch_config.py
-configs/user_config.py
+# Local configuration
+/configs/launch_config.py
+/configs/user_config.py
 
-results
+# Python caches
+__pycache__/
 
-tallies.out
-statepoint*
-tmp*
-submit.pbs
-*png
-__pycache__
+# Verification results
+/results/
+
+# Simulation output
 output*
-*.core
-*xml
-*DS_Store
+statepoint*
+tallies.out
 summary.h5
 mgxs.h5
-*gif
+*.xml
+
+# Generated plots
+*.png
+*.gif
+
+# Batch and temporary files
+submit.pbs
+tmp*
+*.core
 
+# Operating-system files
+.DS_Store

.pre-commit-config.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 26.1.0
+    hooks:
+      - id: black
+        language_version: python3.14

CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/), and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html) as a guide.
+MC/DC-VVP release numbers align with the corresponding compatible MC/DC release.
+
+## [Unreleased]
+
+Target release: 0.16.0, the first versioned MC/DC-VVP release.
+
+### Added
+
+- Add the analytical neutron $k$-eigenvalue suite with subcritical and supercritical SHEM-361 cases, analytical matrix-eigenvalue references, active-cycle convergence studies, and uncertainty plots, from [@ilhamv]
+- Add energy-dependent weight-window and time-census variants of the infinite homogeneous SHEM-361 problem, from [@ilhamv]
+- Add AZURV1 variants for basic variance-reduction techniques, analytical spatial weight windows, time censuses, and census-based tallies, from [@ilhamv]
+- Add top-level and suite-level READMEs describing layouts, configuration, launching, processing, cases, and references, from [@ilhamv]
+- Add shared platform, user, and launch configuration for local and HPC campaigns, from [@ilhamv]
+
+### Changed
+
+- Migration to Maestro-based launch, from [@ilhamv]
+- Update analytical fixed-source cases for the simulation-owned MC/DC interface and unified material model, from [@ilhamv]
+- Standardize **suite** and **case** as the VVP repository's organizational terminology, from [@ilhamv]
+- Organize fixed-source cases around consistent input, reference, processing, and optional plotting scripts, from [@ilhamv]
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+[Unreleased]: https://github.com/ilhamv/mcdc-vvp/tree/master
+[@ilhamv]: https://github.com/ilhamv

README.md

@@ -6,69 +6,93 @@
 
 A collection of verification, validation, and performance (VVP) test suites for [MC/DC](https://github.com/mcdc-project/mcdc).
 
-The repository provides a unified framework for launching, processing, and organizing MC/DC verification campaigns on local workstations and HPC platforms. Each verification, validation, and performance suite is self-contained and can be executed independently, while the top-level workflow enables reproducible campaign-wide execution. On supported HPC systems, campaign orchestration is performed using [Maestro](https://github.com/llnl/maestrowf).
+The repository provides a unified framework for launching, processing, and organizing MC/DC-VVP campaigns on local workstations and HPC platforms.
+Each suite is self-contained and can be executed independently, while the top-level workflow enables reproducible campaign-wide execution.
+Workflow orchestration is performed using [Maestro](https://github.com/llnl/maestrowf).
 
-## Repository organization
+## Directory layout
 
 ```text
-configs/        Shared platform, user, and launch configurations
-verification/   Verification test suites
-validation/     Validation test suites
-performance/    Performance test suites
-results/        Processed results from completed campaigns
-
-launch.py       Launch all enabled suites
-process.py      Process all enabled suites
+configs/               Shared platform, user, and launch configurations
+verification/          Verification suites and their cases
+results/metadata.yaml  Append-only launch and processing history
+results/<launch_id>/   Processed results for one recorded launch
+
+launch.py              Launch all enabled suites
+process.py             Process one recorded launch
 ```
 
-Each suite contains its own launch and processing workflow and may also be executed manually without the top-level scripts.
+MC/DC-VVP uses **suite** and **case** as standard terms for its two organizational levels:
+
+- A **suite** is a self-contained collection of related VVP cases with a shared launch and processing workflow.
+- A **case** is one individual problem definition and its inputs, reference solution or data, and processing logic.
 
-## Quick start
+The top-level workflow launches and processes enabled suites, while each suite workflow runs and processes its cases.
+Every integrated suite provides a README that describes its layout, configuration, workflow, and cases.
 
-1. Create a user launch configuration:
+## Configuration
+
+Create the local launch configuration:
 
 ```bash
 cp configs/launch_config.py.template configs/launch_config.py
 ```
 
-2. Edit `configs/launch_config.py` to enable the desired suites and select the target platform.
+Edit `configs/launch_config.py` to enable the desired suites and set their platform and launch options.
+Use `platform=None` for local execution or a name from `configs/platform_config.py` for HPC execution.
+
+For HPC execution, also create `configs/user_config.py` from its template and provide the account and optional queue, reservation, and Python paths for the target platform.
 
-3. Launch the enabled suites:
+## Launching and processing
+
+Launch locally enabled suites configured with `platform=None`:
 
 ```bash
-# Local execution
 python launch.py
+```
+
+Launch enabled suites configured for a specific HPC platform:
 
-# HPC execution
+```bash
 python launch.py --platform tuolumne
 ```
 
-4. After all jobs have completed, process the results:
+The `--platform` option selects suites with a matching configured platform.
+
+After the latest launch has completed, process all suites submitted by that launch:
 
 ```bash
 python process.py
 ```
 
-Processed figures, metadata, and summary results are written to the `results/` directory.
+Process a specific recorded launch by passing the launch ID printed by `launch.py` and stored in `results/metadata.yaml`:
 
-## Verification suites
+```bash
+python process.py 20260817T120000123456Z
+```
+
+Each launch is processed into its own `results/<launch_id>/` directory, which contains a metadata snapshot and the suite result hierarchy.
+Reprocessing one launch replaces only that launch's subfolder and does not affect results from other launches.
+
+## Suites
 
 ### Analytical verification
 
-Analytical verification demonstrates the expected statistical convergence of MC/DC by comparing numerical solutions against analytical reference solutions as the number of source particles is increased.
+Analytical verification demonstrates the expected statistical convergence of MC/DC by comparing numerical solutions against analytical reference solutions as the sampling effort is increased.
 
 | Physics | Suite | Description |
 | :------ | :---- | :---------- |
-| Neutron transport | Analytical fixed-source | Multigroup steady-state and transient fixed-source verification problems, including Reed's problem, AZURV1 variants, and infinite SHEM-361 benchmarks. |
+| Neutron transport | [Fixed-source](verification/analytical/neutron/fixed_source/README.md) | Multigroup steady-state and transient fixed-source cases, including Reed's problem, AZURV1 variants, and infinite SHEM-361 benchmarks. |
+| Neutron transport | [$k$-eigenvalue](verification/analytical/neutron/k_eigenvalue/README.md) | Infinite homogeneous SHEM-361 criticality cases with analytical eigenvalue and energy-spectrum references. |
 
 ### Benchmark verification
 
-Benchmark verification compares MC/DC against established reference Monte Carlo codes on problems without analytical solutions.
+Benchmark verification compares MC/DC against established reference Monte Carlo codes for cases without analytical solutions.
 
 | Physics | Suite | Description |
 | :------ | :---- | :---------- |
-| Neutron transport (multigroup) | Benchmark multigroup | Time-dependent benchmark problems, including the Kobayashi Dog-Leg and C5G7 transient benchmarks. |
-| Neutron transport (continuous energy) | Benchmark continuous energy | Continuous-energy benchmark problems for representative reactor systems. |
+| Neutron transport (multigroup) | Benchmark multigroup | Time-dependent benchmark cases, including the Kobayashi Dog-Leg and C5G7 transient benchmarks. |
+| Neutron transport (continuous energy) | [Benchmark continuous energy](verification/benchmark/neutron/continuous_energy/README.md) | Continuous-energy benchmark cases for representative reactor systems. |
 
 ## Validation
 
@@ -84,11 +108,4 @@ Performance suites evaluate computational performance, scalability, and efficien
 
 ## Documentation
 
-Comprehensive user and developer documentation will be available on Read the Docs. It will include:
-
-- Framework architecture
-- Launch and processing workflow
-- Platform and user configuration
-- Adding new suites
-- Adding new verification cases
-- Developer guidelines
+The top-level and suite READMEs provide the repository-specific documentation for MC/DC-VVP.

configs/launch_config.py.template

@@ -6,4 +6,11 @@ LAUNCH_CONFIG = {
         "walltime": None,
         "rewrite": False,
     },
+    "verification/analytical/neutron/k_eigenvalue": {
+        "enabled": False,
+        "platform": None,
+        "mpi": False,
+        "walltime": None,
+        "rewrite": False,
+    },
 }

configs/user_config.py.template

@@ -4,6 +4,6 @@ USER_CONFIG = {
         "queue": "the_queue_here",
         "reservation": None,
         "maestro_python": None,
-	"mcdc_python": None,
+	    "mcdc_python": None,
     },
 }