Add VVP docs

CHANGELOG.md

@@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
 
 - Add piece-wise linear spatial distribution for source definition, from [@ilhamv]
 - Add overriding option N_active, from [@ilhamv]
+- Add MC/DC-VVP project documentation with verification case narratives, published results, and VVP result-generation and publication steps in the release checklist, from [@ilhamv]
 
 ### Changed
 

docs/source/developer_guide/contributing/index.rst

@@ -9,6 +9,7 @@ It is intended for both occasional contributors and project maintainers.
 
 Start with the setup steps below.
 Use :doc:`continuous_integration` to understand automated checks and :doc:`container_development` when developing in the project container.
+Use :doc:`unit_testing` for the role and organization of focused component tests.
 Use :doc:`example_validation` when changing the public API or example problems.
 Read :doc:`pull_requests` before preparing a contribution.
 For software architecture and documentation practices, see the :doc:`../index`.
@@ -32,6 +33,7 @@ Development Workflow
 
    continuous_integration
    container_development
+   unit_testing
    example_validation
    pull_requests
 

docs/source/developer_guide/contributing/unit_testing.rst

@@ -0,0 +1,10 @@
+.. _developer_unit_testing:
+
+============
+Unit Testing
+============
+
+Unit tests provide focused verification of MC/DC functions, data transformations, interfaces, and edge cases in isolation.
+They are maintained with the MC/DC codebase and are separate from :doc:`MC/DC's Verification, Validation, and Performance (VVP) <../../project/vvp/index>`, which tests complete simulations through full-transport problems and convergence studies.
+
+This page will document the organization, scope, and development practices of the MC/DC unit-test suite.

docs/source/developer_guide/release_policy.rst

@@ -95,6 +95,10 @@ Prepare the Release
 #. Confirm whether the release changes the supported Python versions.
    If it does, update ``pyproject.toml``, the compatibility workflows, installation documentation, and ``CHANGELOG.md``.
 #. Confirm the required local checks, continuous-integration workflows, and distribution artifact tests pass on the release candidate; resolve any dependency incompatibilities they expose and update ``pyproject.toml`` and ``CHANGELOG.md`` as needed.
+#. Run the applicable `MC/DC-VVP campaign <https://github.com/mcdc-project/mcdc-vvp>`_ with the release candidate and the corresponding MC/DC-VVP version.
+   Process the completed suites and review their convergence, reference, and comparison results for unexpected behavior.
+#. Run ``python prepare_release.py`` in MC/DC-VVP to collect the processed PNG figures and GIF animations into its flat ``release/`` asset directory.
+   Confirm that the prepared assets cover the documented VVP cases and that their names match the links used by the MC/DC documentation.
 
 Integrate the Release
 ^^^^^^^^^^^^^^^^^^^^^
@@ -122,6 +126,9 @@ Publish from Main
    * **Release label:** select **Latest**.
    * **Finish:** click **Publish release** when creating the release, or **Update release** when editing an existing release.
 
+#. Replace the assets attached to the mutable `VVP results release <https://github.com/mcdc-project/mcdc/releases/tag/vvp-results>`_ with the contents of the prepared MC/DC-VVP ``release/`` directory.
+   Update its release notes to identify the MC/DC and MC/DC-VVP versions used for the published campaign.
+#. Confirm that every VVP figure and animation referenced by the documentation is available from the ``vvp-results`` release and renders on its case page.
 #. Confirm that the automatically triggered `Publish Python Package to PyPI <https://github.com/mcdc-project/mcdc/actions/workflows/publish-pypi.yml>`_ and `Check citation metadata <https://github.com/mcdc-project/mcdc/actions/workflows/check_citation.yml>`_ workflows complete successfully, and that the release is available from the `stable Read the Docs site <https://mcdc.readthedocs.io/en/stable/>`_.
 #. Smoke-test the published PyPI package in a clean environment with ``python -m pip install "mcdc==X.Y.Z"``, then run a minimal MC/DC simulation.
 

docs/source/index.rst

@@ -74,6 +74,7 @@ More resources
 --------------
 
 - Learn from complete input decks in :doc:`user_guide/examples/index`.
+- Review the :doc:`MC/DC verification, validation, and performance (VVP)<project/vvp/index>` evidence.
 - Explore the ongoing :doc:`CARRE research program <project/carre>`, its collaboration opportunities, and the :doc:`MC/DC publication record <project/publications>`.
 - Follow the contribution workflow in :doc:`developer_guide/contributing/index`.
 

docs/source/project/index.rst

@@ -4,11 +4,15 @@
 Project
 =======
 
-The Project pages present the research programs shaping MC/DC, the capabilities under active development, and the publications documenting this work.
-MC/DC is currently developed as part of the `Center for Advancing the Radiation Resilience of Electronics (CARRE) <https://carre-psaapiv.org/>`_ and builds on its origins in the `Center for Exascale Monte Carlo Neutron Transport (CEMeNT) <https://cement-psaap.github.io/>`_.
+The Project pages present the research programs shaping MC/DC, the evidence supporting its development, and the publications documenting the work.
+
+The :doc:`CARRE <carre>` page describes MC/DC's role in the Center for Advancing the Radiation Resilience of Electronics and its foundation in the Center for Exascale Monte Carlo Neutron Transport.
+The :doc:`Verification, Validation, and Performance <vvp/index>` pages explain how MC/DC is assessed and present the published VVP results.
+The :doc:`Publications <publications>` page collects research associated with MC/DC and its past and ongoing research programs.
 
 .. toctree::
    :maxdepth: 1
 
    carre
+   vvp/index
    publications

docs/source/project/vvp/index.rst

@@ -0,0 +1,79 @@
+.. _project_vvp:
+
+=========================================
+Verification, Validation, and Performance
+=========================================
+
+`MC/DC Verification, Validation, and Performance (MC/DC-VVP) <https://github.com/mcdc-project/mcdc-vvp>`_ provides the evidence used to assess the correctness, physical credibility, and computational behavior of MC/DC.
+The campaigns are maintained alongside MC/DC so that repeatable systematic problems exercise major code changes.
+VVP focuses on full-transport problems that test complete simulations, complementing the component-level verification provided separately by :doc:`unit tests <../../developer_guide/contributing/unit_testing>`.
+
+
+Three kinds of evidence
+-----------------------
+
+There are three kinds of evidence: verification, validation, and performance.
+
+1. **Verification** asks whether MC/DC solves its stated mathematical problems correctly.
+
+   a. **Analytical verification** compares MC/DC with an analytical, semi-analytical, or manufactured reference solution and checks for the expected statistical convergence rate.
+
+   b. **Code-to-code verification** compares independently implemented transport codes and checks whether their relative differences decrease at the expected Monte Carlo rate.
+      Agreement between codes increases confidence but does not establish correctness because the codes may share assumptions or biases.
+
+2. **Validation** asks whether an MC/DC model reproduces experimental observations within the relevant measurement, model, and nuclear-data uncertainties.
+   Validation assesses the combined physical model, data, and implementation against experimental evidence.
+
+3. **Performance** studies measure quantities such as runtime, throughput, memory use, and parallel scalability.
+   They characterize computational efficiency separately from numerical correctness and physical fidelity.
+
+The development campaign currently reports neutron-transport verification.
+Validation and performance results will be added as their suites mature.
+
+Organization
+------------
+
+MC/DC-VVP uses **suite**, **case**, and **task** as its standard hierarchy.
+
+.. code-block:: text
+
+   suite
+   └── case
+       └── task
+
+A **suite** is a related collection of VVP problems that shares a launch and processing workflow.
+A **case** is one physical or mathematical problem definition together with its model, reference, and result-processing logic.
+A **task** is one execution of a case at one sampling level, such as a selected source-particle count or number of active eigenvalue cycles.
+
+A suite answers a broad verification, validation, or performance question, a case exercises a particular problem and capability set, and repeated tasks expose how its result changes with sampling effort.
+
+For example, the analytical neutron fixed-source verification suite contains the AZURV1 case, which is executed as a sequence of source-particle-count tasks:
+
+.. code-block:: text
+
+   analytical neutron fixed-source suite
+   └── AZURV1 case
+       ├── task: N_particle = 100,000
+       ├── task: N_particle = 215,443
+       ├── ...
+       └── task: N_particle = 10,000,000
+
+This example describes verification, where repeated sampling levels reveal an error-convergence trend.
+The same hierarchy applies to validation and performance, but their tasks will likely represent different variations, such as experimental configurations for validation or hardware and scaling points for performance.
+
+Current status and next steps
+-----------------------------
+
+The :doc:`verification program <verification/index>` currently covers analytical and code-to-code neutron transport.
+Each case page presents its problem definition, reference solution, convergence study, and published results as one narrative.
+The figures and animations are loaded from the rolling `VVP results release <https://github.com/mcdc-project/mcdc/releases/tag/vvp-results>`_, which is updated when a new MC/DC campaign is published.
+The initial result set was generated from the development branches in preparation for MC/DC v0.16.0.
+
+Future campaigns will extend the program with :doc:`validation <validation/index>` against experimental observations and :doc:`performance <performance/index>` studies of computational efficiency and scalability.
+
+.. toctree::
+   :hidden:
+
+   verification/index
+   validation/index
+   performance/index

docs/source/project/vvp/performance/index.rst

@@ -0,0 +1,8 @@
+.. _project_vvp_performance:
+
+===========
+Performance
+===========
+
+Performance studies characterize computational efficiency separately from numerical correctness and physical fidelity.
+This section will report problem and hardware configurations together with runtime, throughput, memory use, and parallel-scaling results when the performance suites mature.

docs/source/project/vvp/validation/index.rst

@@ -0,0 +1,8 @@
+.. _project_vvp_validation:
+
+==========
+Validation
+==========
+
+Validation assesses whether an MC/DC model reproduces experimental observations within the relevant measurement, model, and nuclear-data uncertainties.
+This section will present each experimental configuration, its computational model and data, the measured quantities, and the resulting comparison when the validation suites mature.

docs/source/project/vvp/verification/_derivations/azurv1.inc

@@ -0,0 +1,87 @@
+With unit neutron speed and unit total cross section, the one-group angular flux satisfies
+
+.. math::
+
+   \frac{\partial \psi}{\partial t}
+   +\mu\frac{\partial \psi}{\partial x}
+   +\psi
+   =\frac{c}{2}\phi,
+   \qquad
+   \phi(x,t)=\int_{-1}^{1}\psi(x,\mu,t)\,d\mu,
+
+with the isotropic pulse represented by
+
+.. math::
+
+   \psi(x,\mu,0^+)=\frac{1}{2}\delta(x).
+
+The effective production ratio is
+
+.. math::
+
+   c=\frac{\Sigma_s+\nu\Sigma_f}{\Sigma_t}.
+
+Fourier transformation in space with wavenumber :math:`p` and Laplace transformation in time with variable :math:`s` give
+
+.. math::
+
+   \widetilde{\psi}(p,\mu,s)
+   =\frac{1+c\widetilde{\phi}(p,s)}
+          {2(s+1+ip\mu)}.
+
+Integrating over direction defines
+
+.. math::
+
+   L(p,s)
+   =\frac{1}{2}\int_{-1}^{1}\frac{d\mu}{s+1+ip\mu}
+   =\frac{1}{2ip}
+     \ln\left(\frac{s+1+ip}{s+1-ip}\right),
+
+so the transformed scalar flux is
+
+.. math::
+
+   \widetilde{\phi}(p,s)=\frac{L(p,s)}{1-cL(p,s)}.
+
+Ganapol's inversion of these transforms can be written for :math:`|x|<t` by defining
+
+.. math::
+
+   \eta=\frac{x}{t},
+   \qquad
+   q=\frac{1+\eta}{1-\eta},
+   \qquad
+   \xi(u)=\frac{\ln q+iu}{\eta+i\tan(u/2)}.
+
+The real-space scalar flux used by the reference generator is
+
+.. math::
+
+   \phi(x,t)
+   =\frac{e^{-t}}{2t}
+    \left[
+      1+\frac{ct}{4\pi}(1-\eta^2)
+      \int_0^\pi
+      \sec^2\left(\frac{u}{2}\right)
+      \mathop{\mathrm{Re}}\left\{
+        \xi(u)^2
+        \exp\left[
+          \frac{ct}{2}(1-\eta^2)\xi(u)
+        \right]
+      \right\}
+      \,du
+    \right].
+
+Causality gives :math:`\phi(x,t)=0` for :math:`t=0` or :math:`|x|\geq t` in the regular, bin-averaged solution.
+For spatial cell :math:`[x_j,x_{j+1}]` and time interval :math:`[t_k,t_{k+1}]`, the plotted reference is
+
+.. math::
+
+   \overline{\phi}_{k,j}
+   =\frac{1}{\Delta t_k\Delta x_j}
+    \int_{x_j}^{x_{j+1}}
+    \int_{t_k}^{t_{k+1}}
+    \phi(x,t)\,dt\,dx.
+
+Adaptive quadrature evaluates the angular-inversion integral and both bin integrations.

docs/source/project/vvp/verification/_derivations/code_to_code.inc

@@ -0,0 +1,35 @@
+Suppose :math:`R_i^{(m)}(N)` is the estimate from participating code :math:`m` in tally bin :math:`i` at common sampling level :math:`N`.
+For :math:`M` participating codes, the fixed comparison field is the arithmetic mean at the largest shared sample,
+
+.. math::
+
+   R_i^*=\frac{1}{M}\sum_{m=1}^{M}R_i^{(m)}(N_{\max}).
+
+This same field normalizes every sampling level.
+For each code pair :math:`a<b`, the pointwise relative difference is
+
+.. math::
+
+   d_i^{(a,b)}(N)
+   =\frac{R_i^{(a)}(N)-R_i^{(b)}(N)}{R_i^*},
+
+evaluated only where :math:`R_i^*\neq0`.
+With :math:`P=M(M-1)/2` code pairs, the reported pair-averaged 2-norm is
+
+.. math::
+
+   D_2(N)
+   =\left[
+      \frac{1}{P}
+      \sum_{a<b}\left\|d^{(a,b)}(N)\right\|_2^2
+    \right]^{1/2},
+
+and the maximum relative difference is
+
+.. math::
+
+   D_{\max}(N)
+   =\max_{a<b}\max_i\left|d_i^{(a,b)}(N)\right|.
+
+For the current two-code campaign, these expressions reduce to the norm and maximum of the single MC/DC–OpenMC difference field.
+If the codes differ only through independent Monte Carlo noise and increase their sampling together, both metrics should decrease proportionally to :math:`N^{-1/2}`.

docs/source/project/vvp/verification/_derivations/shem361_eigenvalue.inc

@@ -0,0 +1,36 @@
+Let :math:`\alpha` multiply the original capture contribution, so the total cross section used by the eigenproblem is
+
+.. math::
+
+   \Sigma_t^{(\alpha)}
+   =\Sigma_t+(\alpha-1)\Sigma_c.
+
+The infinite homogeneous medium has no leakage, and its group balance is
+
+.. math::
+
+   \left[D(\Sigma_t^{(\alpha)})-\Sigma_s\right]\phi
+   =\frac{1}{k}\nu\Sigma_f\phi.
+
+Defining
+
+.. math::
+
+   L=D(\Sigma_t^{(\alpha)})-\Sigma_s,
+   \qquad
+   F=\nu\Sigma_f,
+
+gives the generalized eigenproblem
+
+.. math::
+
+   F\phi=kL\phi.
+
+All finite, nearly real eigenpairs are retained, and the eigenpair with the largest real eigenvalue supplies the physical fundamental mode.
+Its sign is selected so that the group sum is positive, and the spectrum is normalized by
+
+.. math::
+
+   \sum_{g=1}^{361}\phi_g=1.
+
+The resulting dominant eigenvalue is the reference multiplication factor and the normalized eigenvector is the reference energy spectrum.

docs/source/project/vvp/verification/_derivations/shem361_fixed.inc

@@ -0,0 +1,39 @@
+Let :math:`\phi\in\mathbb{R}^{361}` be the group-flux spectrum, with matrices written in outgoing-by-incoming group order.
+Increasing capture by 50 percent changes the total cross section to
+
+.. math::
+
+   \Sigma_t'=\Sigma_t+0.5\Sigma_c.
+
+In an infinite homogeneous medium there is no leakage, so the steady group balance is
+
+.. math::
+
+   D(\Sigma_t')\phi
+   =\Sigma_s\phi+\nu\Sigma_f\phi+Q,
+
+where :math:`D(a)` denotes the diagonal matrix formed from vector :math:`a`.
+Collecting the loss and production terms gives
+
+.. math::
+
+   A\phi=Q,
+   \qquad
+   A=D(\Sigma_t')-\Sigma_s-\nu\Sigma_f.
+
+The isotropic external source is placed entirely in group 361, so
+
+.. math::
+
+   Q_g=\begin{cases}
+   1, & g=361,\\
+   0, & \text{otherwise}.
+   \end{cases}
+
+The analytical spectrum is therefore the direct linear-system solution
+
+.. math::
+
+   \phi=A^{-1}Q.
+
+Because the medium is homogeneous and infinite, this group balance is the complete transport solution and requires no spatial discretization.