mcdc-project · ilhamv · Aug 17, 2026 · Aug 15, 2026 · Aug 14, 2026 · Aug 14, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 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 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+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.
 
 ## [Unreleased]
 
@@ -20,8 +20,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
 
 ### Security
 
+## [0.15.2] - 2026-08-15
+
+### Fixed
+
+- Anticipate empty census-based tallies in batch runs for correct tally recombination, from [@ilhamv]
+- Prevent independent runs with different problem sizes from sharing mutable problem-dependent Numba types, and preserve Python-managed `__pycache__` directories during startup, from [@ilhamv]
+
+### Added
+
+- Add `rebuild_numba_support.py` and the `-r`/`--rebuild` developer option for regenerating Numba support (mcdc_get, mcdc_set, numba_types.py) after object model changes, from [@ilhamv]
+
+### Changed
+
+- Generate shared Numba support independently of simulation preparation and create problem-dependent dtypes locally through pure factories, from [@ilhamv]
+- Organize example documentation under the User Guide and contribution documentation under the Developer Guide, from [@ilhamv]
+
 ## [0.15.1] - 2026-08-12
 
+### Fixed
+
+- Prevent unbounded dependency resolution from selecting incompatible releases that break MC/DC by adding explicit upper bounds for all build, runtime, documentation, and development dependencies, from [@ilhamv]
+
 ### Added
 
 - Add a dedicated CARRE project page, from [@ilhamv]
@@ -32,10 +52,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
 
 - Hide flyout in Read the Docs, from [@ilhamv]
 
-### Fixed
-
-- Prevent unbounded dependency resolution from selecting incompatible releases that break MC/DC by adding explicit upper bounds for all build, runtime, documentation, and development dependencies, from [@ilhamv]
-
 ## [0.15.0] - 2026-08-11
 
 ### Added
@@ -62,6 +78,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
 
 ## [0.14.2] - 2026-07-15
 
+### Fixed
+
+- Fix 2D-vector setter writes nothing (- instead of =) from [@steps-re]
+- Fix delayed neutrons are never sampled (transport/physics/neutron/native.py, fission()) from [@steps-re]
+- Fix delayed emission time uses β instead of λ (transport/physics/neutron/native.py, fission())from [@steps-re]
+- Fix swapped transverse-basis branches (transport/distribution.py, sample_direction()) from [@steps-re]
+- Fix divide-by-zero for a -z reference (transport/distribution.py, sample_white_direction()) from [@steps-re]
+- Fix tally polar_reference corrupted (object_/tally.py) from [@steps-re]
+
 ### Added
 
 - Add layered documentation philosophy
@@ -76,18 +101,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
   - Combined `object_` and `transport` unit test for more efficient fixture reuse from [@massimolarsen]
   - Replace bare assert np.isclose with proper np.testing.assert_allclose from [@steps-re]
 
-### Fixed
-
-- Fix 2D-vector setter writes nothing (- instead of =) from [@steps-re]
-- Fix delayed neutrons are never sampled (transport/physics/neutron/native.py, fission()) from [@steps-re]
-- Fix delayed emission time uses β instead of λ (transport/physics/neutron/native.py, fission())from [@steps-re]
-- Fix swapped transverse-basis branches (transport/distribution.py, sample_direction()) from [@steps-re]
-- Fix divide-by-zero for a -z reference (transport/distribution.py, sample_white_direction()) from [@steps-re]
-- Fix tally polar_reference corrupted (object_/tally.py) from [@steps-re]
-
 ## [0.14.1] - 2026-07-04
 
-### Changed
+### Fixed
 
 - Documentation and packaging metadata fixes
 
@@ -170,6 +186,7 @@ The pre-refactor implementation remains available in the `cement` branch as a re
 - Multi-table distribution table selection sampling from [@melekderman]
 
 [Unreleased]: https://github.com/mcdc-project/mcdc/tree/dev
+[0.15.2]: https://github.com/mcdc-project/mcdc/releases/tag/v0.15.2
 [0.15.1]: https://github.com/mcdc-project/mcdc/releases/tag/v0.15.1
 [0.15.0]: https://github.com/mcdc-project/mcdc/releases/tag/v0.15.0
 [0.14.2]: https://github.com/mcdc-project/mcdc/releases/tag/v0.14.2

diff --git a/CITATION.cff b/CITATION.cff
@@ -34,8 +34,8 @@ keywords:
   - Numba
   - GPU
 license: BSD-3-Clause
-version: 0.15.1
-date-released: '2026-08-12'
+version: 0.15.2
+date-released: '2026-08-15'
 preferred-citation:
   type: article
   authors:

diff --git a/README.md b/README.md
@@ -42,7 +42,7 @@ Complete documentation is available on [Read the Docs](https://mcdc.readthedocs.
 - [Getting Started](https://mcdc.readthedocs.io/en/dev/user_guide/getting_started/index.html)
 - [API Reference](https://mcdc.readthedocs.io/en/dev/reference/python_api/index.html)
 - [Developer Guide](https://mcdc.readthedocs.io/en/dev/developer_guide/index.html)
-- [Contributing](https://mcdc.readthedocs.io/en/dev/contributing/index.html)
+- [Contributing](https://mcdc.readthedocs.io/en/dev/developer_guide/contributing/index.html)
 
 ## Citing
 

diff --git a/docs/source/_static/switcher.json b/docs/source/_static/switcher.json
@@ -5,7 +5,7 @@
     "url": "https://mcdc.readthedocs.io/en/dev/"
   },
   {
-    "name": "0.15.1 (stable)",
+    "name": "0.15.2 (stable)",
     "version": "stable",
     "url": "https://mcdc.readthedocs.io/en/stable/",
     "preferred": true

diff --git a/docs/source/developer_guide/architecture/index.rst b/docs/source/developer_guide/architecture/index.rst
@@ -75,14 +75,17 @@ Paths in the component column are relative to the top-level ``mcdc/`` package.
      - Runtime preparation
      - Derive and expose simulation-specific values that compiled transport requires as literals.
    * - ``code_factory/numba_layers_generator.py``
-     - Runtime preparation
-     - Derives structured dtypes, packs runtime state, generates accessors, and initiates GPU-specific preparation when requested.
+     - Support generation and runtime preparation
+     - Generates the shared Numba support and derives problem-dependent dtypes and prepared runtime state.
+   * - ``numba_types.py``, ``mcdc_get/``, and ``mcdc_set/``
+     - Generated Numba support
+     - Define dtypes for the shared runtime schema, pure factories for problem-dependent dtypes, and accessors for variable-length fields in ``data``.
+   * - ``code_factory/rebuild_numba_support.py``
+     - Development-time generation
+     - Runs the support generator after changes to the object model or generation logic.
    * - Runtime ``simulation`` and ``data``
-     - Prepared runtime data
+     - Prepared runtime state
      - Store fixed-layout state and variable-length numerical data generated by ``numba_layers_generator.py``.
-   * - ``mcdc_get/`` and ``mcdc_set/``
-     - Runtime data access
-     - Provide generated access to variable-length fields stored in ``data``.
    * - ``transport/``
      - Shared transport
      - Implements the particle-transport algorithms used by every execution mode.
@@ -95,8 +98,12 @@ Paths in the component column are relative to the top-level ``mcdc/`` package.
 The ``mcdc/object_`` modules, :class:`mcdc.Simulation`, and ``python_objects_compiler.py`` implement the model-definition and simulation-compilation stages.
 :doc:`simulation_compilation` explains their relationships, while :doc:`../extending/extending_the_object_model` explains how contributors can extend them.
 
-``main.prepare``, ``numba_layers_generator.py``, runtime ``simulation`` and ``data``, and generated ``mcdc_get`` and ``mcdc_set`` implement framework-level runtime preparation and form the data boundary between model compilation and transport.
-:doc:`runtime_data_layout` explains their roles.
+``main.prepare`` and ``numba_layers_generator.py`` use the generated Numba
+support to create the runtime ``simulation`` and ``data`` objects that form the
+data boundary between model compilation and transport.
+:doc:`runtime_data_layout` explains the complete representation,
+:ref:`generated_numba_support` distinguishes its three lifetimes, and
+:ref:`rebuilding_numba_support` gives the object model development workflow.
 
 The ``mcdc/transport`` package implements the shared-transport stage.
 :doc:`transport_execution` explains how the execution modes run it.

diff --git a/docs/source/developer_guide/architecture/runtime_data_layout.rst b/docs/source/developer_guide/architecture/runtime_data_layout.rst
@@ -187,6 +187,59 @@ Packing is performed in two passes:
 
 The structured ``simulation`` dtype can then be finalized because collection sizes, particle-bank sizes, and nested record types are known.
 
+.. _generated_numba_support:
+
+Generated Numba Support and Problem-Dependent Dtypes
+----------------------------------------------------
+
+The derived layout feeds artifacts with three different lifetimes:
+
+Generated Numba support
+   ``mcdc/numba_types.py`` and the modules under ``mcdc/mcdc_get`` and
+   ``mcdc/mcdc_set`` describe the runtime schema developed in the preceding
+   sections. These generated source files are shared by every simulation using
+   that MC/DC source tree. They change with the object model or Numba support
+   generator, not with an input problem.
+
+Problem-dependent dtypes
+   Each call to ``mcdc.main.prepare`` derives collection lengths,
+   particle-bank capacities, and other sizes from one compiled model. Pure
+   factories in ``mcdc.numba_types`` use those sizes to return simulation and
+   particle-bank dtypes local to that preparation. The factories do not
+   install the returned dtypes in shared module globals.
+
+Prepared runtime state
+   ``generate_numba_layers`` uses the problem-dependent dtypes to allocate and
+   pack that simulation's ``simulation`` and ``data`` objects. This state is
+   owned by the prepared simulation and used during transport.
+
+This separation allows independent processes to run differently sized
+problems from the same installation. Each process creates and retains its own
+problem-dependent dtypes, while the generated Numba support remains read-only.
+
+Import and Preparation Order
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Generated Numba support is established at the process level:
+
+#. Importing ``mcdc`` loads the complete object model.
+#. ``mcdc.config`` parses ``-r`` or ``--rebuild`` with the other command-line
+   options, and package initialization calls its MPI-aware rebuild gate. When
+   rebuilding is requested, rank zero regenerates the Numba support and the
+   other ranks in that MPI launch wait for it to finish.
+#. Runtime modules may then import ``numba_types``, ``mcdc_get``, and
+   ``mcdc_set``.
+
+This process-level step does not depend on a :class:`mcdc.Simulation` or its
+compilation. Each simulation is subsequently compiled and prepared using the
+support already established during import. Preparation creates fresh
+problem-dependent dtypes and prepared runtime state for that simulation.
+
+The MPI barrier coordinates ranks within one launch, not independent launches.
+Independent jobs sharing an MC/DC source tree must use previously generated,
+read-only Numba support. See :ref:`rebuilding_numba_support` for the object
+model development workflow and rebuild commands.
+
 .. _simulation_specific_literals:
 
 Static Constants and Simulation-Specific Literals

diff --git a/...ce/contributing/container_development.rst → ...de/contributing/container_development.rst b/...ce/contributing/container_development.rst → ...de/contributing/container_development.rst
diff --git a/...e/contributing/continuous_integration.rst → ...e/contributing/continuous_integration.rst b/...e/contributing/continuous_integration.rst → ...e/contributing/continuous_integration.rst
diff --git a/...ource/contributing/example_validation.rst → ...guide/contributing/example_validation.rst b/...ource/contributing/example_validation.rst → ...guide/contributing/example_validation.rst
diff --git a/docs/source/contributing/index.rst → ...ce/developer_guide/contributing/index.rst b/docs/source/contributing/index.rst → ...ce/developer_guide/contributing/index.rst
@@ -11,9 +11,9 @@ 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:`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:`../developer_guide/index`.
+For software architecture and documentation practices, see the :doc:`../index`.
 
-For implementation guidance specific to compiled transport functions, see :doc:`../developer_guide/extending/writing_numba_compatible_transport_code`.
+For implementation guidance specific to compiled transport functions, see :doc:`../extending/writing_numba_compatible_transport_code`.
 
 Contributions target the ``dev`` branch.
 Prepare a development checkout with the following steps:
@@ -36,7 +36,7 @@ Development Workflow
    pull_requests
 
 MC/DC documentation is an important part of the project and evolves alongside the codebase.
-The :doc:`../developer_guide/documentation/index` guide describes the documentation philosophy, writing guidelines, and the tools used to build and maintain the documentation.
+The :doc:`../documentation/index` guide describes the documentation philosophy, writing guidelines, and the tools used to build and maintain the documentation.
 
 Please note our `code of conduct <https://github.com/mcdc-project/mcdc/blob/dev/CODE_OF_CONDUCT.md>`_, which we take seriously.
 
@@ -117,7 +117,11 @@ In MC/DC the simulation functions (in ``mcdc/transport/simulation.py``) can be c
 Caching behavior is controlled via the ``--caching`` and ``--clear_cache`` command-line flags.
 
 To disable caching, omit the ``--caching`` flag (the default).
-Alternatively a developer could delete the ``__pycache__`` directory or other cache directory which is system dependent (`see more about clearing the numba cache <https://numba.readthedocs.io/en/stable/developer/caching.html>`_)
+Python manages its own ``__pycache__`` directories, and MC/DC does not delete
+them during startup. This allows independent batch launches to safely import
+MC/DC from the same installation. If manual cache removal is necessary, ensure
+that no running job is using the affected cache (`see more about clearing the
+Numba cache <https://numba.readthedocs.io/en/stable/developer/caching.html>`_).
 
 
 MC/DC may eventually enable `Numba's ahead-of-time compilation capabilities <https://numba.readthedocs.io/en/stable/user/pycc.html>`_.
@@ -128,7 +132,7 @@ However if absolutely required by users numba does allow for some `cache sharing
 Adding a New Input
 ------------------
 
-For architectural guidance on adding a model field, embedded configuration, registered object category, or polymorphic subtype, see :doc:`../developer_guide/extending/extending_the_object_model`.
+For architectural guidance on adding a model field, embedded configuration, registered object category, or polymorphic subtype, see :doc:`../extending/extending_the_object_model`.
 Public model classes and configuration are primarily defined in ``mcdc/object_/``.
 Common input-related locations include:
 
@@ -142,6 +146,10 @@ Common input-related locations include:
 #. ``mcdc/object_/technique.py`` — variance reduction techniques
 #. ``mcdc/config.py`` — command-line argument definitions
 
+Changes to runtime-visible fields in the object model also require rebuilding
+the generated Numba support. Follow :ref:`rebuilding_numba_support` for the
+command, edit-test shortcut, and concurrency constraint.
+
 -------
 Testing
 -------
@@ -205,4 +213,4 @@ Adding Documentation
 Documentation is a core part of MC/DC.
 Contributions that introduce new features, modify existing behavior, or change developer workflows should update the relevant documentation accordingly.
 
-See the :doc:`../developer_guide/documentation/index` guide for documentation philosophy, writing guidelines, and instructions for contributing to the documentation.
+See the :doc:`../documentation/index` guide for documentation philosophy, writing guidelines, and instructions for contributing to the documentation.
diff --git a/docs/source/contributing/pull_requests.rst → ...oper_guide/contributing/pull_requests.rst b/docs/source/contributing/pull_requests.rst → ...oper_guide/contributing/pull_requests.rst
diff --git a/docs/source/developer_guide/documentation/sphinx.rst b/docs/source/developer_guide/documentation/sphinx.rst
@@ -67,7 +67,8 @@ For example, the following on ``index.rst`` creates a table of contents on the m
   .. toctree::
      user_guide/index
      theory/index
-     examples/index
+     reference/index
+     developer_guide/index
 
 Sphinx will build an html file for all rst files in the source directory and its subdirectories.
 Sphinx will issue a warning if an html file isn't referenced in any toctree because that means that the generated webpage is not reachable through standard navigation.

diff --git a/docs/source/developer_guide/extending/extending_the_object_model.rst b/docs/source/developer_guide/extending/extending_the_object_model.rst
@@ -321,14 +321,43 @@ For example, the structural part of a mesh subtype follows this pattern:
 No new ``register_object`` branch is needed for a subtype of an already registered family.
 The existing ``isinstance(..., MeshBase)`` or corresponding category check places it in the base collection, while ``sub_type`` and ``sub_ID`` connect it to its concrete packed collection.
 
-Generated Runtime Layers and Accessors
---------------------------------------
+.. _rebuilding_numba_support:
 
-The annotation is the source of truth for generated runtime fields and accessors.
-Do not edit ``mcdc/numba_types.py``, ``mcdc_get``, or ``mcdc_set`` to introduce a field.
-Prepare a representative simulation so ``numba_layers_generator.py`` regenerates those files, then verify the access pattern predicted by the field representation chosen above.
+Rebuilding Numba Support
+------------------------
 
-For example, a variable-length ``Detector.response`` field produces element accessors associated with the ``detector`` label:
+Changes to runtime-visible annotations or object types under ``mcdc/object_``
+require rebuilding the generated Numba support. The annotations are the source
+of truth; do not edit ``mcdc/numba_types.py``, ``mcdc_get``, or ``mcdc_set``
+directly to introduce a field.
+
+Run the rebuild script after changing the object model:
+
+.. code-block:: console
+
+   python mcdc/code_factory/rebuild_numba_support.py
+
+Then verify the access pattern predicted by the field representation chosen
+above, and commit the regenerated files together with the object model change.
+
+During an active ``mcdc/object_`` edit-test cycle, add ``-r`` (or
+``--rebuild``) to the test input-deck command instead. MC/DC then rebuilds the
+generated Numba support during package initialization, after loading the full
+object model and before importing the generated files. Developers who are not
+changing the object model do not need this option.
+
+.. important::
+
+   Within one MPI launch, rank zero performs the rebuild and the other ranks
+   wait. Independent launches do not share that barrier, so do not use ``-r``
+   or ``--rebuild`` from concurrent jobs that share an MC/DC source tree.
+
+Rebuilding refreshes the shared runtime schema. Problem-dependent dtypes and
+prepared runtime state are still created separately for each simulation. See
+:ref:`generated_numba_support` for those lifetimes and the import order.
+
+After rebuilding, a variable-length ``Detector.response`` field should produce
+element accessors associated with the ``detector`` label:
 
 .. code-block:: python
 
@@ -367,7 +396,7 @@ For example, a public ``Detector`` is re-exported from the package and listed by
 Verification Checklist
 ----------------------
 
-An object-model extension should verify all affected layers:
+An object model extension should verify all affected layers:
 
 - Construction accepts valid input and rejects invalid shapes or types.
 - Compilation discovers the object from the intended root.
@@ -379,4 +408,4 @@ An object-model extension should verify all affected layers:
 - API and developer documentation build without warnings.
 
 Add focused unit tests near ``test/unit/test_object_compilation.py`` for compilation behavior and near the relevant transport tests for runtime behavior.
-Use :doc:`../../contributing/example_validation` when an extension changes public examples.
+Use :doc:`../contributing/example_validation` when an extension changes public examples.
diff --git a/docs/source/developer_guide/extending/index.rst b/docs/source/developer_guide/extending/index.rst
@@ -20,7 +20,7 @@ Continue with :doc:`writing_numba_compatible_transport_code` when the extension
 
 For example, a new runtime field with no transport behavior uses the object-model guide, a numerical change using existing fields starts with the transport-code guide, and a new tally subtype follows both in that order.
 
-Use the :doc:`../../contributing/index` for repository setup, test commands, continuous-integration coverage, and pull-request requirements.
+Use the :doc:`../contributing/index` for repository setup, test commands, continuous-integration coverage, and pull-request requirements.
 
 .. toctree::
    :maxdepth: 1