openmc-depletion-feedback 0.1.0__tar.gz

openmc_depletion_feedback-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: openmc-depletion-feedback
+Version: 0.1.0
+Summary: Reusable OpenMC depletion simulations with optional soluble-species feedback control
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openmc>=0.14
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# openmc-depletion-feedback
+
+An importable wrapper around OpenMC depletion. The package accepts a prepared
+OpenMC `Model` or a directory containing OpenMC XML inputs and runs depletion
+with one function. Provide the reactor geometry, materials, temperatures,
+volumes, cross-section data, and depletion chain for your calculation.
+
+## Install
+
+Install OpenMC and its nuclear data according to the [OpenMC documentation](https://docs.openmc.org/), then install this package:
+
+```bash
+pip install .
+```
+
+Install the released package with:
+```bash
+pip install openmc-depletion-feedback
+```
+
+## Documentation
+
+The full user guide can be found here: [openmc-depletion-feedback documentation](https://qyxen.github.io/openmc-depletion-feedback/)
+
+## Ordinary depletion
+
+```python
+import openmc
+from openmc_depletion_feedback import run_depletion
+
+run_depletion(
+    model="model",  # directory containing geometry.xml, materials.xml, settings.xml, etc.
+    timesteps=[1, 7, 30, 90],
+    timestep_units="d",
+    power=160e6,  # watts
+    chain_file="data/chain.xml",
+    output_dir="depletion-results",
+)
+```
+
+## Soluble-species feedback
+
+Provide a named material containing the soluble species at the stated
+reference concentration. The controller scales the listed nuclide atom
+densities together, leaving every other nuclide in the material untouched.
+Species concentration units are intentionally user-defined, so the same
+controller can represent ppm boron, ppm gadolinium, or another soluble
+absorber when the reference material has been prepared consistently.
+
+```python
+from openmc_depletion_feedback import FeedbackControl, run_depletion
+
+control = FeedbackControl(
+    material_name="Primary coolant",
+    nuclides=("B10", "B11"),
+    reference_concentration=1000,  # ppm represented by the model densities
+    minimum=0,
+    maximum=1000,
+    target_keff=1.005,
+    search_particles=5000,
+    search_batches=30,
+    search_inactive=5,
+)
+run_depletion(
+    model="model",  # directory containing the OpenMC XML inputs
+    timesteps=[1, 7, 30],
+    power=160e6,
+    chain_file="data/chain.xml",
+    control=control,
+    output_dir="controlled-results",
+)
+```
+
+## Citation
+
+Citation metadata is provided in [`CITATION.cff`](CITATION.cff).

openmc_depletion_feedback-0.1.0/README.md

@@ -0,0 +1,76 @@
+# openmc-depletion-feedback
+
+An importable wrapper around OpenMC depletion. The package accepts a prepared
+OpenMC `Model` or a directory containing OpenMC XML inputs and runs depletion
+with one function. Provide the reactor geometry, materials, temperatures,
+volumes, cross-section data, and depletion chain for your calculation.
+
+## Install
+
+Install OpenMC and its nuclear data according to the [OpenMC documentation](https://docs.openmc.org/), then install this package:
+
+```bash
+pip install .
+```
+
+Install the released package with:
+```bash
+pip install openmc-depletion-feedback
+```
+
+## Documentation
+
+The full user guide can be found here: [openmc-depletion-feedback documentation](https://qyxen.github.io/openmc-depletion-feedback/)
+
+## Ordinary depletion
+
+```python
+import openmc
+from openmc_depletion_feedback import run_depletion
+
+run_depletion(
+    model="model",  # directory containing geometry.xml, materials.xml, settings.xml, etc.
+    timesteps=[1, 7, 30, 90],
+    timestep_units="d",
+    power=160e6,  # watts
+    chain_file="data/chain.xml",
+    output_dir="depletion-results",
+)
+```
+
+## Soluble-species feedback
+
+Provide a named material containing the soluble species at the stated
+reference concentration. The controller scales the listed nuclide atom
+densities together, leaving every other nuclide in the material untouched.
+Species concentration units are intentionally user-defined, so the same
+controller can represent ppm boron, ppm gadolinium, or another soluble
+absorber when the reference material has been prepared consistently.
+
+```python
+from openmc_depletion_feedback import FeedbackControl, run_depletion
+
+control = FeedbackControl(
+    material_name="Primary coolant",
+    nuclides=("B10", "B11"),
+    reference_concentration=1000,  # ppm represented by the model densities
+    minimum=0,
+    maximum=1000,
+    target_keff=1.005,
+    search_particles=5000,
+    search_batches=30,
+    search_inactive=5,
+)
+run_depletion(
+    model="model",  # directory containing the OpenMC XML inputs
+    timesteps=[1, 7, 30],
+    power=160e6,
+    chain_file="data/chain.xml",
+    control=control,
+    output_dir="controlled-results",
+)
+```
+
+## Citation
+
+Citation metadata is provided in [`CITATION.cff`](CITATION.cff).

openmc_depletion_feedback-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openmc-depletion-feedback"
+version = "0.1.0"
+description = "Reusable OpenMC depletion simulations with optional soluble-species feedback control"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["openmc>=0.14"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+

openmc_depletion_feedback-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openmc_depletion_feedback-0.1.0/src/openmc_depletion_feedback/__init__.py

@@ -0,0 +1,7 @@
+"""Reusable depletion workflows built on OpenMC."""
+
+from .api import run_depletion
+from .control import FeedbackControl
+
+__all__ = ["FeedbackControl", "run_depletion"]
+

openmc_depletion_feedback-0.1.0/src/openmc_depletion_feedback/api.py

@@ -0,0 +1,336 @@
+"""Public depletion API."""
+
+from pathlib import Path
+import csv
+from types import SimpleNamespace
+
+import openmc
+import openmc.deplete as deplete
+
+
+def _nominal_keff(result):
+    value = getattr(result, "k", getattr(result, "keff", None))
+    if value is None:
+        raise AttributeError("OpenMC operator result does not expose k or keff")
+    return float(getattr(value, "nominal_value", value))
+
+
+def _keff_stats(result):
+    """Return the keff estimate and its reported standard deviation, if any."""
+    value = getattr(result, "k", getattr(result, "keff", None))
+    if value is None:
+        raise AttributeError("OpenMC operator result does not expose k or keff")
+    mean = float(getattr(value, "nominal_value", value))
+    sigma = getattr(value, "std_dev", None)
+    return mean, None if sigma is None else float(sigma)
+
+
+class _FeedbackOperator(deplete.CoupledOperator):
+    def __init__(self, model, chain_file, control):
+        super().__init__(model, chain_file=chain_file)
+        self.control = control
+        self.material = None
+        self.base_densities = None
+        self.original_stats = None
+        self.history_path = None
+        self._step = 0
+        self._trial = 0
+        self._previous_concentration = None
+        self._previous_boc_keff = None
+        self.expected_step_keff_loss = control.expected_step_keff_loss
+        self.search_level = 0
+
+    def initial_condition(self):
+        result = super().initial_condition()
+        c = self.control
+        source = next((m for m in self.model.materials if m.name == c.material_name), None)
+        if source is None:
+            raise ValueError(f"Control material {c.material_name!r} was not found")
+        self.material = openmc.lib.materials[source.id]
+        names = self.material.nuclides
+        dens = self.material.densities
+        resolved = []
+        missing = []
+        for requested in c.nuclides:
+            matches = [n for n in names if n == requested or
+                       (requested.isalpha() and n.startswith(requested) and
+                        n[len(requested):].isdigit())]
+            if not matches:
+                missing.append(requested)
+            else:
+                resolved.extend(matches)
+        if missing:
+            raise ValueError(f"Control material lacks nuclides: {', '.join(missing)}")
+        self.control_nuclides = tuple(dict.fromkeys(resolved))
+        self.base_densities = {n: float(dens[names.index(n)]) for n in self.control_nuclides}
+        settings = openmc.lib.settings
+        self.original_stats = (settings.particles, settings.get_batches(), settings.inactive)
+        self.history_path = Path(self.output_dir) / c.history_file
+        self.history_path.parent.mkdir(parents=True, exist_ok=True)
+        with self.history_path.open("w", newline="") as f:
+            csv.writer(f).writerow([
+                "step", "trial", "phase", "concentration", "keff",
+                "keff_std_dev", "target_keff", "lower_bound", "upper_bound",
+                "search_level", "particles", "batches", "selected",
+                "keff_error", "status", "stopping_reason",
+            ])
+        return result
+
+    def _set_concentration(self, concentration):
+        c = self.control
+        factor = concentration / c.reference_concentration
+        names, dens = self.material.nuclides, self.material.densities.copy()
+        for nuclide, base in self.base_densities.items():
+            dens[names.index(nuclide)] = base * factor
+        self.material.set_densities(names, dens)
+
+    def _transport(self, vec, source_rate, concentration, final=False,
+                   search_level=None):
+        c, settings = self.control, openmc.lib.settings
+        if not final:
+            level = self.search_level if search_level is None else search_level
+            factor = c.refinement_factor ** level
+            base_particles, base_batches, base_inactive = self.original_stats
+            settings.particles = round((c.search_particles or base_particles) * factor)
+            settings.set_batches(round((c.search_batches or base_batches) * factor))
+            if c.search_inactive is not None:
+                settings.inactive = c.search_inactive
+            else:
+                settings.inactive = base_inactive
+        else:
+            settings.particles, batches, settings.inactive = self.original_stats
+            settings.set_batches(batches)
+        self._set_concentration(concentration)
+        return super().__call__(vec, source_rate)
+
+    def _record_trial(self, concentration, mean, sigma, target, lower, upper,
+                      phase, selected=False, status="", stopping_reason=""):
+        settings = getattr(openmc.lib, "settings", None)
+        if settings is None:
+            settings = SimpleNamespace()
+        batches = settings.get_batches() if hasattr(settings, "get_batches") else ""
+        with self.history_path.open("a", newline="") as f:
+            csv.writer(f).writerow([
+                self._step, self._trial, phase, f"{concentration:.8f}",
+                f"{mean:.8f}", "" if sigma is None else f"{sigma:.8f}",
+                f"{target:.8f}", f"{lower:.8f}", f"{upper:.8f}",
+                self.search_level, getattr(settings, "particles", ""), batches,
+                int(selected), f"{abs(mean - target):.8f}", status,
+                stopping_reason,
+            ])
+        self._trial += 1
+
+    def _evaluate(self, vec, source_rate, concentration, target, lower, upper,
+                  phase="search", level=None):
+        previous_level = self.search_level
+        if level is not None:
+            self.search_level = level
+        result = self._transport(vec, source_rate, concentration,
+                                 search_level=level)
+        mean, sigma = _keff_stats(result)
+        self._record_trial(concentration, mean, sigma, target, lower, upper,
+                           phase)
+        self.search_level = previous_level
+        return mean, sigma
+
+    def _confidence_met(self, mean, sigma, target):
+        if sigma is None:
+            return False
+        return abs(mean - target) + self.control.confidence_z * sigma <= self.control.keff_tolerance
+
+    def _target_for_call(self, vec, source_rate):
+        c = self.control
+        if c.target_mode != "end" or self._previous_concentration is None:
+            return c.target_keff + (self.expected_step_keff_loss if c.target_mode == "end" else 0.0)
+
+        # Predictor mode calls the operator once for the depleted state at the
+        # start of the next step. Measure the previous step's loss at its
+        # selected absorber concentration, then filter and bound the estimate.
+        self.search_level = 0
+        current_keff, _ = self._evaluate(
+            vec, source_rate, self._previous_concentration,
+            c.target_keff + self.expected_step_keff_loss,
+            c.minimum, c.maximum, phase="loss_measurement", level=0,
+        )
+        measured_loss = self._previous_boc_keff - current_keff
+        measured_loss = min(c.maximum_step_keff_loss,
+                            max(c.minimum_step_keff_loss, measured_loss))
+        alpha = c.loss_filter_alpha
+        self.expected_step_keff_loss = (
+            (1.0 - alpha) * self.expected_step_keff_loss + alpha * measured_loss
+        )
+        return c.target_keff + self.expected_step_keff_loss
+
+    @staticmethod
+    def _is_bracketed(klo, khi, target):
+        return (klo - target) * (khi - target) <= 0.0
+
+    def _warm_bracket(self, vec, source_rate, target):
+        c = self.control
+        if self._previous_concentration is None:
+            lo, hi = c.minimum, c.maximum
+        else:
+            width = c.warm_start_width
+            center = min(c.maximum, max(c.minimum, self._previous_concentration))
+            lo = max(c.minimum, center - width)
+            hi = min(c.maximum, center + width)
+
+        while True:
+            klo, _ = self._evaluate(vec, source_rate, lo, target, lo, hi,
+                                    phase="bracket")
+            khi, _ = self._evaluate(vec, source_rate, hi, target, lo, hi,
+                                    phase="bracket")
+            if self._is_bracketed(klo, khi, target):
+                return lo, hi, klo, khi, True
+            if lo == c.minimum and hi == c.maximum:
+                return lo, hi, klo, khi, False
+            width *= c.warm_start_expansion
+            center = min(c.maximum, max(c.minimum, self._previous_concentration))
+            new_lo = max(c.minimum, center - width)
+            new_hi = min(c.maximum, center + width)
+            if new_lo == lo and new_hi == hi:
+                new_lo, new_hi = c.minimum, c.maximum
+            lo, hi = new_lo, new_hi
+
+    def _candidate(self, lo, hi, klo, khi, target):
+        if self.control.use_secant and khi != klo:
+            secant = lo + (target - klo) * (hi - lo) / (khi - klo)
+            margin = 0.1 * (hi - lo)
+            if lo + margin <= secant <= hi - margin:
+                return secant
+        return 0.5 * (lo + hi)
+
+    def __call__(self, vec, source_rate):
+        if source_rate == 0.0:
+            return super().__call__(vec, source_rate)
+        c = self.control
+        self._trial = 0
+        target = self._target_for_call(vec, source_rate)
+        lo, hi, klo, khi, bracketed = self._warm_bracket(vec, source_rate, target)
+
+        if not bracketed:
+            selected = lo if abs(klo - target) < abs(khi - target) else hi
+            selected_mean, selected_sigma = (klo, None) if selected == lo else (khi, None)
+            stop_reason = "lower_bound" if selected == c.minimum else "upper_bound"
+            status = "target_unmet"
+        else:
+            increasing = khi > klo
+            selected = 0.5 * (lo + hi)
+            selected_mean, selected_sigma = None, None
+            status, stop_reason = "target_unmet", "max_iterations"
+            for _ in range(c.max_iterations):
+                candidate = self._candidate(lo, hi, klo, khi, target)
+                mean, sigma = self._evaluate(vec, source_rate, candidate,
+                                             target, lo, hi)
+                selected, selected_mean, selected_sigma = candidate, mean, sigma
+
+                # Near-target candidates are rerun with progressively more
+                # histories until their confidence interval supports the
+                # requested keff tolerance, or the refinement budget ends.
+                if abs(mean - target) <= c.keff_tolerance:
+                    for level in range(1, c.max_search_refinements + 1):
+                        if self._confidence_met(mean, sigma, target):
+                            break
+                        mean, sigma = self._evaluate(
+                            vec, source_rate, candidate, target, lo, hi,
+                            phase="refinement", level=level,
+                        )
+                        selected_mean, selected_sigma = mean, sigma
+                    if self._confidence_met(mean, sigma, target):
+                        status, stop_reason = "target_met", "keff_tolerance"
+                        break
+
+                if (mean < target) == increasing:
+                    lo, klo = candidate, mean
+                else:
+                    hi, khi = candidate, mean
+                if hi - lo <= c.tolerance:
+                    status = "target_met" if self._confidence_met(mean, sigma, target) else "target_unmet"
+                    stop_reason = "concentration_tolerance"
+                    if sigma is None or sigma * c.confidence_z > c.keff_tolerance:
+                        stop_reason = "uncertainty_limit"
+                    break
+            else:
+                # The loop exhausted its budget. Keep the last candidate and
+                # distinguish unresolved Monte Carlo uncertainty explicitly.
+                if selected_sigma is None or selected_sigma * c.confidence_z > c.keff_tolerance:
+                    stop_reason = "uncertainty_limit"
+
+        self.search_level = 0
+        result = self._transport(vec, source_rate, selected, final=True)
+        final_mean, final_sigma = _keff_stats(result)
+        target_met = self._confidence_met(final_mean, final_sigma, target)
+        if target_met:
+            status = "target_met"
+            if stop_reason in {"lower_bound", "upper_bound"}:
+                stop_reason = "endpoint_within_tolerance"
+        else:
+            status = "target_unmet"
+            if stop_reason not in {"lower_bound", "upper_bound"}:
+                if final_sigma is None or final_sigma * c.confidence_z > c.keff_tolerance:
+                    stop_reason = "uncertainty_limit"
+                elif abs(final_mean - target) > c.keff_tolerance:
+                    stop_reason = "final_keff_outside_tolerance"
+        self._record_trial(selected, final_mean, final_sigma, target, lo, hi,
+                           "selected_final", selected=True, status=status,
+                           stopping_reason=stop_reason)
+        print(
+            f"[feedback] {status} ({stop_reason}): {selected:g}, "
+            f"keff={final_mean:.6f}, target={target:.6f}"
+        )
+        self._previous_concentration = selected
+        self._previous_boc_keff = final_mean
+        self._step += 1
+        return result
+
+def run_depletion(model, timesteps, power, chain_file, *, timestep_units="d",
+                  integrator="predictor", control=None, output_dir="."):
+    """Run an OpenMC depletion calculation.
+
+    Parameters
+    ----------
+    model : openmc.Model or path-like
+        A prepared OpenMC model (or directory containing OpenMC XML inputs).
+    timesteps : sequence
+        Step durations, interpreted using ``timestep_units``.
+    power : float
+        Reactor power in watts.
+    chain_file : path-like
+        OpenMC depletion chain XML file.
+    control : FeedbackControl, optional
+        Enable feedback by scaling configured nuclide densities in a named
+        material. Omit for an ordinary depletion run.
+    output_dir : path-like
+        Directory for depletion results and feedback history.
+
+    Returns the configured OpenMC integrator after it completes.
+    """
+    chain_file = Path(chain_file)
+    if not chain_file.is_file():
+        raise FileNotFoundError(f"Depletion chain not found: {chain_file}")
+    if not isinstance(model, openmc.Model):
+        model = openmc.Model.from_xml(directory=str(model))
+    missing = [m.name for m in model.materials if m.depletable and (m.volume is None or m.volume <= 0)]
+    if missing:
+        raise ValueError("Depletable materials need positive volumes: " + ", ".join(missing))
+    integrators = {"predictor": deplete.PredictorIntegrator,
+                   "cecm": deplete.CECMIntegrator,
+                   "epc-rk4": deplete.EPCRK4Integrator}
+    try:
+        integrator_name = integrator.lower()
+        integrator_cls = integrators[integrator_name]
+    except (AttributeError, KeyError) as exc:
+        raise ValueError(f"Unsupported integrator {integrator!r}; choose {', '.join(integrators)}") from exc
+    if control is not None and control.target_mode == "end" and integrator_name != "predictor":
+        raise ValueError("target_mode='end' currently requires integrator='predictor'")
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+    operator_cls = _FeedbackOperator if control is not None else deplete.CoupledOperator
+    if control is None:
+        operator = operator_cls(model, chain_file=str(chain_file))
+    else:
+        operator = operator_cls(model, chain_file=str(chain_file), control=control)
+    calculation = integrator_cls(operator, timesteps, power=power,
+                                 timestep_units=timestep_units)
+    calculation.integrate(output_dir=str(output_dir))
+    return calculation
+

openmc_depletion_feedback-0.1.0/src/openmc_depletion_feedback/control.py

@@ -0,0 +1,76 @@
+"""Generic reactivity feedback using a soluble species in one material."""
+
+from dataclasses import dataclass
+from pathlib import Path
+import csv
+
+
+@dataclass
+class FeedbackControl:
+    """Configuration for bounded keff feedback.
+
+    ``reference_concentration`` is the concentration represented by the
+    isotope densities currently in ``material_name``. The controller scales
+    only ``nuclides`` linearly from zero to that reference concentration.
+    Concentration units are user-defined (ppm, g/kg, or another consistent
+    unit); ``minimum`` and ``maximum`` use the same unit.
+    """
+
+    material_name: str
+    nuclides: tuple[str, ...]
+    reference_concentration: float
+    minimum: float
+    maximum: float
+    target_keff: float
+    target_mode: str = "beginning"
+    expected_step_keff_loss: float = 0.01
+    loss_filter_alpha: float = 0.3
+    minimum_step_keff_loss: float = -0.01
+    maximum_step_keff_loss: float = 0.02
+    search_particles: int | None = None
+    search_batches: int | None = None
+    search_inactive: int | None = None
+    max_search_refinements: int = 2
+    refinement_factor: float = 2.0
+    confidence_z: float = 2.0
+    warm_start_width: float = 100.0
+    warm_start_expansion: float = 2.0
+    use_secant: bool = True
+    tolerance: float = 0.001
+    keff_tolerance: float = 0.0005
+    max_iterations: int = 12
+    history_file: str | Path = "feedback_history.csv"
+
+    def __post_init__(self):
+        if not self.material_name or not self.nuclides:
+            raise ValueError("material_name and at least one nuclide are required")
+        if self.reference_concentration <= 0:
+            raise ValueError("reference_concentration must be positive")
+        if not (0 <= self.minimum < self.maximum <= self.reference_concentration):
+            raise ValueError("Require 0 <= minimum < maximum <= reference_concentration")
+        if self.tolerance <= 0 or self.max_iterations < 1:
+            raise ValueError("tolerance and max_iterations must be positive")
+        if self.keff_tolerance <= 0:
+            raise ValueError("keff_tolerance must be positive")
+        for name in ("search_particles", "search_batches"):
+            value = getattr(self, name)
+            if value is not None and value < 1:
+                raise ValueError(f"{name} must be a positive integer")
+        if self.search_inactive is not None and self.search_inactive < 0:
+            raise ValueError("search_inactive must be nonnegative")
+        if self.target_mode not in {"beginning", "end"}:
+            raise ValueError("target_mode must be 'beginning' or 'end'")
+        if not 0.0 <= self.loss_filter_alpha <= 1.0:
+            raise ValueError("loss_filter_alpha must be between 0 and 1")
+        if self.minimum_step_keff_loss > self.maximum_step_keff_loss:
+            raise ValueError("minimum_step_keff_loss must not exceed maximum_step_keff_loss")
+        if self.max_search_refinements < 0:
+            raise ValueError("max_search_refinements must be nonnegative")
+        if self.refinement_factor <= 1.0:
+            raise ValueError("refinement_factor must be greater than 1")
+        if self.confidence_z <= 0:
+            raise ValueError("confidence_z must be positive")
+        if self.warm_start_width <= 0 or self.warm_start_expansion <= 1.0:
+            raise ValueError("warm-start width must be positive and expansion must exceed 1")
+
+

openmc_depletion_feedback-0.1.0/src/openmc_depletion_feedback.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: openmc-depletion-feedback
+Version: 0.1.0
+Summary: Reusable OpenMC depletion simulations with optional soluble-species feedback control
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openmc>=0.14
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# openmc-depletion-feedback
+
+An importable wrapper around OpenMC depletion. The package accepts a prepared
+OpenMC `Model` or a directory containing OpenMC XML inputs and runs depletion
+with one function. Provide the reactor geometry, materials, temperatures,
+volumes, cross-section data, and depletion chain for your calculation.
+
+## Install
+
+Install OpenMC and its nuclear data according to the [OpenMC documentation](https://docs.openmc.org/), then install this package:
+
+```bash
+pip install .
+```
+
+Install the released package with:
+```bash
+pip install openmc-depletion-feedback
+```
+
+## Documentation
+
+The full user guide can be found here: [openmc-depletion-feedback documentation](https://qyxen.github.io/openmc-depletion-feedback/)
+
+## Ordinary depletion
+
+```python
+import openmc
+from openmc_depletion_feedback import run_depletion
+
+run_depletion(
+    model="model",  # directory containing geometry.xml, materials.xml, settings.xml, etc.
+    timesteps=[1, 7, 30, 90],
+    timestep_units="d",
+    power=160e6,  # watts
+    chain_file="data/chain.xml",
+    output_dir="depletion-results",
+)
+```
+
+## Soluble-species feedback
+
+Provide a named material containing the soluble species at the stated
+reference concentration. The controller scales the listed nuclide atom
+densities together, leaving every other nuclide in the material untouched.
+Species concentration units are intentionally user-defined, so the same
+controller can represent ppm boron, ppm gadolinium, or another soluble
+absorber when the reference material has been prepared consistently.
+
+```python
+from openmc_depletion_feedback import FeedbackControl, run_depletion
+
+control = FeedbackControl(
+    material_name="Primary coolant",
+    nuclides=("B10", "B11"),
+    reference_concentration=1000,  # ppm represented by the model densities
+    minimum=0,
+    maximum=1000,
+    target_keff=1.005,
+    search_particles=5000,
+    search_batches=30,
+    search_inactive=5,
+)
+run_depletion(
+    model="model",  # directory containing the OpenMC XML inputs
+    timesteps=[1, 7, 30],
+    power=160e6,
+    chain_file="data/chain.xml",
+    control=control,
+    output_dir="controlled-results",
+)
+```
+
+## Citation
+
+Citation metadata is provided in [`CITATION.cff`](CITATION.cff).

openmc_depletion_feedback-0.1.0/src/openmc_depletion_feedback.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/openmc_depletion_feedback/__init__.py
+src/openmc_depletion_feedback/api.py
+src/openmc_depletion_feedback/control.py
+src/openmc_depletion_feedback.egg-info/PKG-INFO
+src/openmc_depletion_feedback.egg-info/SOURCES.txt
+src/openmc_depletion_feedback.egg-info/dependency_links.txt
+src/openmc_depletion_feedback.egg-info/requires.txt
+src/openmc_depletion_feedback.egg-info/top_level.txt
+tests/test_control.py
+tests/test_feedback_search.py

openmc_depletion_feedback-0.1.0/src/openmc_depletion_feedback.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openmc_depletion_feedback-0.1.0/src/openmc_depletion_feedback.egg-info/requires.txt

@@ -0,0 +1,4 @@
+openmc>=0.14
+
+[test]
+pytest>=7

openmc_depletion_feedback-0.1.0/src/openmc_depletion_feedback.egg-info/top_level.txt

@@ -0,0 +1 @@
+openmc_depletion_feedback

openmc_depletion_feedback-0.1.0/tests/test_control.py

@@ -0,0 +1,42 @@
+import pytest
+
+from openmc_depletion_feedback import FeedbackControl
+
+
+def make_control(**overrides):
+    values = {
+        "material_name": "Coolant",
+        "nuclides": ("B",),
+        "reference_concentration": 1000.0,
+        "minimum": 0.0,
+        "maximum": 1000.0,
+        "target_keff": 1.0,
+    }
+    values.update(overrides)
+    return FeedbackControl(**values)
+
+
+def test_accepts_valid_control():
+    control = make_control()
+
+    assert control.material_name == "Coolant"
+    assert control.nuclides == ("B",)
+    assert control.minimum == 0.0
+    assert control.maximum == 1000.0
+
+
+@pytest.mark.parametrize(
+    "overrides, message",
+    [
+        ({"material_name": ""}, "material_name"),
+        ({"nuclides": ()}, "nuclide"),
+        ({"reference_concentration": 0.0}, "reference_concentration"),
+        ({"minimum": -1.0}, "Require 0 <= minimum"),
+        ({"maximum": 1001.0}, "reference_concentration"),
+        ({"tolerance": 0.0}, "tolerance and max_iterations"),
+        ({"max_iterations": 0}, "tolerance and max_iterations"),
+    ],
+)
+def test_rejects_invalid_control(overrides, message):
+    with pytest.raises(ValueError, match=message):
+        make_control(**overrides)

openmc_depletion_feedback-0.1.0/tests/test_feedback_search.py

@@ -0,0 +1,176 @@
+import csv
+from types import MethodType, SimpleNamespace
+
+import pytest
+
+from openmc_depletion_feedback import FeedbackControl
+from openmc_depletion_feedback.api import _FeedbackOperator, _keff_stats, _nominal_keff
+
+
+def make_operator(tmp_path, keff_at_concentration, **control_options):
+    options = {
+        "material_name": "Coolant",
+        "nuclides": ("B",),
+        "reference_concentration": 1000.0,
+        "minimum": 0.0,
+        "maximum": 1000.0,
+        "target_keff": 1.01,
+        "tolerance": 1.0,
+        "keff_tolerance": 1.0e-8,
+        "max_iterations": 12,
+        "history_file": "feedback.csv",
+    }
+    options.update(control_options)
+    control = FeedbackControl(**options)
+    # Bypass OpenMC initialization: these tests exercise the root-search
+    # control flow with deterministic keff values, not transport physics.
+    operator = object.__new__(_FeedbackOperator)
+    operator.control = control
+    operator.history_path = tmp_path / "feedback.csv"
+    operator._step = 0
+    operator._trial = 0
+    operator._previous_concentration = None
+    operator._previous_boc_keff = None
+    operator.expected_step_keff_loss = control.expected_step_keff_loss
+    operator.search_level = 0
+    operator.calls = []
+    with operator.history_path.open("w", newline="") as f:
+        csv.writer(f).writerow(
+            ["step", "trial", "phase", "concentration", "keff",
+             "keff_std_dev", "target_keff", "lower_bound", "upper_bound",
+             "search_level", "particles", "batches", "selected",
+             "keff_error", "status", "stopping_reason"]
+        )
+
+    def transport(self, vec, source_rate, concentration, final=False, search_level=None):
+        self.calls.append((concentration, final, search_level))
+        value = keff_at_concentration(concentration, search_level, final)
+        if isinstance(value, tuple):
+            value = SimpleNamespace(nominal_value=value[0], std_dev=value[1])
+        else:
+            value = SimpleNamespace(nominal_value=value, std_dev=0.0)
+        return SimpleNamespace(k=value)
+
+    operator._transport = MethodType(transport, operator)
+    return operator
+
+
+def test_nominal_keff_supports_scalar_and_uncertain_values():
+    assert _nominal_keff(SimpleNamespace(k=1.002)) == pytest.approx(1.002)
+    assert _nominal_keff(
+        SimpleNamespace(k=SimpleNamespace(nominal_value=1.002, std_dev=0.0001))
+    ) == pytest.approx(1.002)
+
+
+def test_bisection_finds_decreasing_boron_response_and_writes_history(tmp_path):
+    operator = make_operator(tmp_path, lambda ppm, level, final: 1.02 - 0.00002 * ppm)
+
+    result = operator((object(),), source_rate=1.0)
+
+    assert _nominal_keff(result) == pytest.approx(1.01)
+    assert operator.calls[-1] == (500.0, True, None)
+    with (tmp_path / "feedback.csv").open(newline="") as f:
+        rows = list(csv.DictReader(f))
+    selected = next(row for row in rows if row["selected"] == "1")
+    assert selected["concentration"] == "500.00000000"
+    assert selected["keff"] == "1.01000000"
+    assert selected["keff_std_dev"] == "0.00000000"
+    assert selected["status"] == "target_met"
+    assert selected["stopping_reason"] == "keff_tolerance"
+
+
+def test_bisection_handles_increasing_response(tmp_path):
+    operator = make_operator(tmp_path, lambda ppm, level, final: 1.0 + 0.00002 * ppm)
+    operator.control.target_keff = 1.01
+
+    operator((object(),), source_rate=1.0)
+
+    assert operator.calls[-1] == (500.0, True, None)
+
+
+@pytest.mark.parametrize(
+    "response, expected_concentration, expected_status",
+    [
+        (lambda ppm, level, final: 1.02 - 0.000001 * ppm, 1000.0, "upper_bound"),
+        (lambda ppm, level, final: 1.00 - 0.000001 * ppm, 0.0, "lower_bound"),
+    ],
+)
+def test_unbracketed_target_selects_closest_endpoint(
+    tmp_path, response, expected_concentration, expected_status
+):
+    operator = make_operator(tmp_path, response)
+
+    operator((object(),), source_rate=1.0)
+
+    assert operator.calls[-1] == (expected_concentration, True, None)
+    with (tmp_path / "feedback.csv").open(newline="") as f:
+        row = next(row for row in csv.DictReader(f) if row["selected"] == "1")
+    assert row["stopping_reason"] == expected_status
+
+
+def test_warm_start_searches_local_interval_first(tmp_path):
+    operator = make_operator(
+        tmp_path,
+        lambda ppm, level, final: 1.02 - (0.01 / 620.0) * ppm,
+        warm_start_width=100.0,
+    )
+    operator._previous_concentration = 600.0
+
+    operator((object(),), source_rate=1.0)
+
+    assert operator.calls[:2] == [(500.0, False, None), (700.0, False, None)]
+    assert operator.calls[-1][0] == pytest.approx(620.0)
+    assert operator.calls[-1][1:] == (True, None)
+
+
+def test_search_refines_histories_when_keff_uncertainty_is_too_large(tmp_path):
+    def noisy_response(ppm, level, final):
+        mean = 1.02 - 0.00002 * ppm
+        sigma = 0.0004 if level in (None, 0) else 0.00005
+        return mean, sigma
+
+    operator = make_operator(
+        tmp_path,
+        noisy_response,
+        keff_tolerance=0.0002,
+        max_search_refinements=2,
+        confidence_z=2.0,
+    )
+
+    result = operator((object(),), source_rate=1.0)
+
+    assert _keff_stats(result) == pytest.approx((1.01, 0.0004))
+    assert (500.0, False, 1) in operator.calls
+    with (tmp_path / "feedback.csv").open(newline="") as f:
+        rows = list(csv.DictReader(f))
+    refinements = [row for row in rows if row["phase"] == "refinement"]
+    assert refinements
+    assert refinements[-1]["search_level"] == "1"
+
+
+def test_end_target_compensates_with_filtered_previous_step_loss(tmp_path):
+    operator = make_operator(
+        tmp_path,
+        lambda ppm, level, final: 1.0,
+        target_mode="end",
+        target_keff=1.005,
+        expected_step_keff_loss=0.01,
+        loss_filter_alpha=0.5,
+    )
+    operator._previous_concentration = 300.0
+    operator._previous_boc_keff = 1.02
+    evaluated = {}
+
+    def evaluate(self, vec, source_rate, concentration, target, lower, upper,
+                 phase="search", level=None):
+        evaluated["concentration"] = concentration
+        evaluated["phase"] = phase
+        return 1.012, 0.0001
+
+    operator._evaluate = MethodType(evaluate, operator)
+
+    target = operator._target_for_call((object(),), source_rate=1.0)
+
+    assert evaluated == {"concentration": 300.0, "phase": "loss_measurement"}
+    assert operator.expected_step_keff_loss == pytest.approx(0.009)
+    assert target == pytest.approx(1.014)