quantvolt 0.2.0__tar.gz → 0.2.1__tar.gz

{quantvolt-0.2.0 → quantvolt-0.2.1}/Cargo.lock

@@ -237,7 +237,7 @@ dependencies = [
 
 [[package]]
 name = "quantvolt-core"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "ndarray 0.17.2",
  "numpy",

{quantvolt-0.2.0 → quantvolt-0.2.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "quantvolt-core"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"
 publish = false
 readme = "README.md"

{quantvolt-0.2.0 → quantvolt-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantvolt
-Version: 0.2.0
+Version: 0.2.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: Intended Audience :: Science/Research
@@ -130,10 +130,11 @@ Call premium: 45,663 EUR (delta 5,288 EUR per EUR/MWh)
 Book NPV: 9,133 EUR, VaR(95): 11,715 EUR
 ```
 
-Identical inputs give identical outputs: Monte Carlo honours a `seed`, inputs are validated
-eagerly (no silent partial results), results round-trip through plain dicts / JSON, and the
-library never mutates caller data — `quantvolt.testing.assert_input_unchanged` lets you verify
-that last invariant in your own tests.
+Repeated calls with the same inputs, seed, QuantVolt version, architecture, and native build
+produce identical results. Monte Carlo honours a `seed`, inputs are validated eagerly (no silent
+partial results), results round-trip through plain dicts / JSON, and the library never mutates
+caller data — `quantvolt.testing.assert_input_unchanged` lets you verify that last invariant in
+your own tests.
 
 ### Settle a PPA with your own interval data
 
@@ -348,9 +349,6 @@ positions. See [docs/risk-and-assets.md](docs/risk-and-assets.md).
   verify_tutorial_*.py` script): [spark spread to hedge](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-spark),
   [renewable PPA to CFaR](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-ppa), and
   [storage intrinsic to hedge](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-storage)
-- `.kiro/steering/` — product, tech, structure, and coding-style standards
-- `.kiro/specs/power-energy-quant-analysis/` — requirements, design, and task breakdown
-  (the library is spec-driven; the design document is the source of truth for the maths)
 
 ## Development
 

{quantvolt-0.2.0 → quantvolt-0.2.1}/README.md

@@ -91,10 +91,11 @@ Call premium: 45,663 EUR (delta 5,288 EUR per EUR/MWh)
 Book NPV: 9,133 EUR, VaR(95): 11,715 EUR
 ```
 
-Identical inputs give identical outputs: Monte Carlo honours a `seed`, inputs are validated
-eagerly (no silent partial results), results round-trip through plain dicts / JSON, and the
-library never mutates caller data — `quantvolt.testing.assert_input_unchanged` lets you verify
-that last invariant in your own tests.
+Repeated calls with the same inputs, seed, QuantVolt version, architecture, and native build
+produce identical results. Monte Carlo honours a `seed`, inputs are validated eagerly (no silent
+partial results), results round-trip through plain dicts / JSON, and the library never mutates
+caller data — `quantvolt.testing.assert_input_unchanged` lets you verify that last invariant in
+your own tests.
 
 ### Settle a PPA with your own interval data
 
@@ -309,9 +310,6 @@ positions. See [docs/risk-and-assets.md](docs/risk-and-assets.md).
   verify_tutorial_*.py` script): [spark spread to hedge](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-spark),
   [renewable PPA to CFaR](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-ppa), and
   [storage intrinsic to hedge](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-storage)
-- `.kiro/steering/` — product, tech, structure, and coding-style standards
-- `.kiro/specs/power-energy-quant-analysis/` — requirements, design, and task breakdown
-  (the library is spec-driven; the design document is the source of truth for the maths)
 
 ## Development
 

{quantvolt-0.2.0 → quantvolt-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "quantvolt"
-version = "0.2.0"
+version = "0.2.1"
 description = "Quantitative analysis of European power and energy markets"
 readme = "README.md"
 requires-python = ">=3.11"

{quantvolt-0.2.0 → quantvolt-0.2.1}/src/quantvolt/__init__.py

@@ -224,7 +224,7 @@ from .risk import (
     parametric_var,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = [
     "BUILT_IN_COMMODITIES",

{quantvolt-0.2.0 → quantvolt-0.2.1}/src/quantvolt/_validation.py

@@ -1,5 +1,5 @@
 """Reusable boundary-validation guards. Public entry points validate through these before any
-computation (fail loudly; see .kiro/steering/coding-style.md). All raise ValidationError."""
+computation, raising ``ValidationError`` on the first violated constraint."""
 
 from __future__ import annotations
 

{quantvolt-0.2.0 → quantvolt-0.2.1}/src/quantvolt/assets/dispatch_approx.py

@@ -1,42 +1,42 @@
-"""Dispatch heuristics and approximations (Task 74; Req 21.3).
-
-Req 21.3 requires three *caller-selectable* approximations to the dispatch
-optimisation, each trading fidelity for tractability, plus a specific warning when
-the state-aggregation ("bang-bang") one is used. This module implements them as
-**documented input/problem transformations around the exact deterministic solver**
-:func:`quantvolt.assets.dispatch_deterministic.dispatch_deterministic` (eq. B.1) --
-the perfect-foresight optimum that is itself the upper bound the stochastic value
-is measured against (Property 62). Wrapping the deterministic DP (rather than the
-Monte-Carlo :func:`~quantvolt.assets.dispatch_sdp.dispatch_value`) keeps every
-approximation's error *exactly* comparable to a noise-free benchmark: the
+"""Dispatch heuristics and approximations.
+
+Three caller-selectable approximations to the dispatch optimisation, each trading
+fidelity for tractability, plus a specific warning when the state-aggregation
+("bang-bang") one is used. This module implements them as documented input/problem
+transformations around the exact deterministic solver
+``quantvolt.assets.dispatch_deterministic.dispatch_deterministic``: the
+perfect-foresight optimum that is itself the upper bound the stochastic value
+is measured against. Wrapping the deterministic DP (rather than the
+Monte-Carlo ``quantvolt.assets.dispatch_sdp.dispatch_value``) keeps every
+approximation's error exactly comparable to a noise-free benchmark: the
 block-constant, decoupling, and bias identities below are equalities up to float
 tolerance, not statistical statements. The same three transformations apply
-unchanged to the stochastic solver -- a caller may block-average the factor
+unchanged to the stochastic solver: a caller may block-average the factor
 model's per-step structure, divide the simulated horizon, or feed a bang-bang
-plant to :func:`dispatch_value` -- but the *heuristic itself* is the transform, and
+plant to ``dispatch_value``, but the heuristic itself is the transform, and
 it is cleanest to specify and test against the deterministic optimum.
 
 The three approximations
 ------------------------
-- :func:`time_aggregate` -- **time aggregation** (hourly -> 4/8/16-hour blocks).
+- ``time_aggregate``: time aggregation (hourly -> 4/8/16-hour blocks).
   Averages the price/temperature series into equal blocks, solves the (much
   shorter) coarse dispatch, and rescales the coarse value back to the original
   number of hours. Exact on block-constant prices for a unit that incurs no start
   within the horizon; the intra-block ramp/commitment freedom it drops is the
   approximation.
-- :func:`horizon_divide` -- **horizon division** (weekly / monthly sub-horizons).
-  Splits the horizon into consecutive sub-horizons solved *independently* and sums
-  their values. The boundary-state approximation -- each sub-horizon after the
+- ``horizon_divide``: horizon division (weekly / monthly sub-horizons).
+  Splits the horizon into consecutive sub-horizons solved independently and sums
+  their values. The boundary-state approximation: each sub-horizon after the
   first restarts from a cold, restart-ready offline state, dropping the true
-  carried-over commitment state -- decouples the subproblems. Exact when the
+  carried-over commitment state, decouples the subproblems. Exact when the
   periods decouple (zero start costs and non-binding min-run / min-down / ramp).
-- :func:`bang_bang` -- **state aggregation** for steep heat-rate curves. Collapses
+- ``bang_bang``: state aggregation for steep heat-rate curves. Collapses
   the online output grid to the single full-load level, so the unit is either off
-  or running at ``c_max`` ({0, c_max}). Exact for a *linear* (constant marginal)
+  or running at ``c_max`` ({0, c_max}). Exact for a linear (constant marginal)
   heat rate, where the optimal load is always a corner; a downward-biased lower
   bound for a steep (rising-marginal) curve, where the exact optimum runs at an
   efficient part load the approximation cannot represent. Emits
-  :class:`BangBangHedgeWarning` (Req 21.3): hedges are far more sensitive than
+  ``BangBangHedgeWarning``: hedges are far more sensitive than
   values to the heat-curve approximation.
 
 Direction-of-bias summary (the "documented direction" the tests assert)
@@ -70,17 +70,17 @@ from .plant import MaxCapacityCurve, PlantModel
 
 
 class BangBangHedgeWarning(UserWarning):
-    """Advisory that bang-bang state aggregation biases hedges far more than values (Req 21.3).
+    """Advisory that bang-bang state aggregation biases hedges far more than values.
 
     Collapsing the output grid to {0, c_max} pins the operating point to full load,
     so the plant value loses only the (often small) part-load optionality. The
-    *sensitivities* — the deltas and critical-dispatch surfaces used to hedge — are
+    sensitivities (the deltas and critical-dispatch surfaces used to hedge) are
     a different matter: they read the slope of value against price, and the
     approximation replaces the true, curved heat-rate response with a single kink
     at the on/off boundary. A hedge derived from a bang-bang model can therefore be
     badly wrong even when the headline value looks reasonable. The approximation is
-    not rejected — for a sufficiently steep heat curve the value error is genuinely
-    negligible — but the caller is warned so the choice is deliberate.
+    not rejected: for a sufficiently steep heat curve the value error is genuinely
+    negligible, but the caller is warned so the choice is deliberate.
     """
 
 
@@ -109,7 +109,7 @@ def time_aggregate(
     output_step: float | None = None,
     discount_factors: Sequence[float] | None = None,
 ) -> DispatchSchedule:
-    """Time-aggregation heuristic: solve on ``block_hours``-hour blocks, rescale (Req 21.3).
+    """Time-aggregation heuristic: solve on ``block_hours``-hour blocks, rescale.
 
     Each consecutive run of ``block_hours`` periods is averaged into one coarse
     period (power, fuel, temperature, and — if supplied — discount factor), the
@@ -229,21 +229,21 @@ def horizon_divide(
     output_step: float | None = None,
     discount_factors: Sequence[float] | None = None,
 ) -> DispatchSchedule:
-    """Horizon-division heuristic: solve independent sub-horizons and sum (Req 21.3).
+    """Horizon-division heuristic: solve independent sub-horizons and sum.
 
     The horizon is cut into consecutive sub-horizons of length ``sub_horizon`` (the
-    last may be shorter) that are solved *independently* by the deterministic DP and
+    last may be shorter) that are solved independently by the deterministic DP and
     concatenated; ``total_value`` is the sum of the sub-values. This is the weekly /
     monthly sub-period heuristic that keeps each solve small.
 
-    Boundary-state approximation. Only the **first** sub-horizon sees the caller's
+    Boundary-state approximation. Only the first sub-horizon sees the caller's
     initial condition; every later sub-horizon restarts from a cold, restart-ready
-    *offline* state. Dropping the true carried-over commitment state is exactly what
-    decouples the subproblems — and is the approximation. It is **exact** when the
+    offline state. Dropping the true carried-over commitment state is exactly what
+    decouples the subproblems, and is the approximation. It is exact when the
     periods decouple (zero start costs and non-binding min-run / min-down / ramp),
     because the dispatch is then myopic and the start-up state is immaterial. It
-    **typically understates** value otherwise (each boundary can pay a spurious
-    restart cost), but it *can* overstate value when a binding min-run / min-down
+    typically understates value otherwise (each boundary can pay a spurious
+    restart cost), but it can overstate value when a binding min-run / min-down
     constraint that would span a boundary in the full solve is artificially relaxed
     by the cut.
 
@@ -335,34 +335,34 @@ def bang_bang(
     output_step: float | None = None,
     discount_factors: Sequence[float] | None = None,
 ) -> DispatchSchedule:
-    """Bang-bang state aggregation: run at full load or off, {0, c_max} (Req 21.3).
+    """Bang-bang state aggregation: run at full load or off, {0, c_max}.
 
     Collapses the online output grid to a single full-load level so the unit is
-    either off or running at ``c_max`` — the state aggregation Appendix B recommends
-    for a *sufficiently steep* heat-rate curve, where the optimal load is (almost)
+    either off or running at ``c_max``, recommended for a sufficiently steep
+    heat-rate curve, where the optimal load is (almost)
     always a corner. Implemented by solving the deterministic DP on a derived plant
     whose ``c_min`` and ``c_max`` are both pinned to that full-load level; every
     other operating characteristic (heat-rate curve, start costs, ramp, durations)
-    is unchanged. The input plant is **not** mutated — a new :class:`PlantModel` is
+    is unchanged. The input plant is not mutated: a new ``PlantModel`` is
     derived.
 
-    Full-load level. With a constant capacity the pinned level *is* ``c_max``. With a
+    Full-load level. With a constant capacity the pinned level is ``c_max``. With a
     temperature-dependent ``c_max(temp)`` the level is the horizon-minimum ``c_max``
     (the largest constant full-output level feasible in every period); a period
     whose capacity falls below the plant's own ``c_min`` makes the plant infeasible
     there and is rejected, mirroring the deterministic solver's curve check.
 
-    Exactness and bias. For a **linear** (constant-marginal) heat rate the per-MWh
+    Exactness and bias. For a linear (constant-marginal) heat rate the per-MWh
     margin is output-independent, so the exact optimum is a corner and bang-bang is
-    exact. For a **steep** (rising-marginal) curve the exact optimum may run at an
+    exact. For a steep (rising-marginal) curve the exact optimum may run at an
     efficient part load that bang-bang cannot represent, so the value is a
-    **downward-biased lower bound**: whenever the full-load level is reachable in one
+    downward-biased lower bound: whenever the full-load level is reachable in one
     step (ramp rate >= operating range) the bang-bang on/off policy set is a strict
     subset of the exact one, and restricting the load choice can only lose value.
 
-    Warning (Req 21.3). Emits :class:`BangBangHedgeWarning`: hedges (sensitivities
+    Warning. Emits ``BangBangHedgeWarning``: hedges (sensitivities
     and critical-dispatch surfaces) are far more sensitive than the value itself to
-    the heat-rate-curve approximation, because they read the *slope* of value
+    the heat-rate-curve approximation, because they read the slope of value
     against price, which the single on/off kink distorts even where the value error
     is negligible.
 

{quantvolt-0.2.0 → quantvolt-0.2.1}/src/quantvolt/assets/dispatch_deterministic.py

@@ -1,13 +1,12 @@
-"""Perfect-foresight thermal dispatch (Task 72; Req 21.1 partial, 21.4; Property 62).
+"""Perfect-foresight thermal dispatch.
 
 ``dispatch_deterministic`` solves the deterministic optimization of Appendix B
 eq. B.1: with all prices, fuel costs and temperatures known in advance, it finds
 the commitment-and-output schedule that maximizes total margin subject to the
 operational and state-transition constraints. Because it optimizes over the
-*fully known* path, its value is the **upper bound** that any non-anticipating
-(stochastic) policy is tested against — the ``dispatch_value ≤
-dispatch_deterministic`` guarantee of Property 62 (validated with the Task-73
-stochastic engine). ``total_value`` is therefore the headline field.
+fully known path, its value is the upper bound that any non-anticipating
+(stochastic) policy is tested against: the ``dispatch_value <=
+dispatch_deterministic`` guarantee. ``total_value`` is therefore the headline field.
 
 Objective (eq. B.1), per period ``t`` when producing ``q_t``::
 
@@ -61,8 +60,8 @@ Conventions (documented, standard unit-commitment)
   lag is not itself a "start".
 - **Full availability.** The deterministic perfect-foresight benchmark assumes
   no forced outages (derate multiplier ``M ≡ 1``); the plant's ``outage_rate``
-  ``λ`` is consumed only by the stochastic model (Task 73). Perfect foresight
-  *and* no outages is exactly the upper bound Property 62 needs.
+  ``λ`` is consumed only by the stochastic model. Perfect foresight
+  and no outages is exactly what the upper-bound property needs.
 - **Terminal condition.** No salvage or penalty at the horizon end: the unit may
   finish online without having completed its min-run (finite-window truncation).
 - **Discounting.** ``discount_factors`` (default all 1.0, matching eq. B.1's
@@ -112,8 +111,7 @@ class DispatchSchedule:
         stopped: Whether the unit shuts down in the period.
         margins: Per-period contribution to ``total_value`` (discounted cash
             flow, net of any start cost); ``sum(margins) == total_value``.
-        total_value: The optimal total value — the perfect-foresight upper bound
-            (Property 62).
+        total_value: The optimal total value, the perfect-foresight upper bound.
     """
 
     outputs: tuple[float, ...]
@@ -335,8 +333,8 @@ def dispatch_deterministic(
         discount_factors: Per-period discount factors (default all 1.0).
 
     Returns:
-        The optimal :class:`DispatchSchedule`; ``total_value`` is the
-        perfect-foresight upper bound of Property 62.
+        The optimal ``DispatchSchedule``; ``total_value`` is the
+        perfect-foresight upper bound.
 
     Raises:
         ValidationError: If the series are empty or of unequal length; if a

{quantvolt-0.2.0 → quantvolt-0.2.1}/src/quantvolt/assets/dispatch_sdp.py

@@ -1,27 +1,27 @@
-"""Stochastic dispatch valuation (Task 73; Req 21.1, 21.2, 21.5, 21.6; Properties 62-63).
+"""Stochastic dispatch valuation.
 
 ``dispatch_value`` computes the risk-adjusted expected value of a thermal unit by
-stochastic dynamic programming -- the Bellman recursion of Appendix B eqs. B.2-B.3
-solved by backward induction over the *same* commitment state machine as
-:mod:`quantvolt.assets.dispatch_deterministic`. Two solution methods are offered
-(Req 21.2): ``method="tree"`` (recombining lattice / binomial-forest backward
+stochastic dynamic programming: the Bellman recursion of Appendix B eqs. B.2-B.3
+solved by backward induction over the same commitment state machine as
+``quantvolt.assets.dispatch_deterministic``. Two solution methods are offered:
+``method="tree"`` (recombining lattice / binomial-forest backward
 induction) and ``method="lsm"`` (least-squares Monte Carlo, Longstaff-Schwartz).
-Both return a :class:`DispatchResult` carrying the value and the four critical
+Both return a ``DispatchResult`` carrying the value and the four critical
 exercise surfaces of eq. B.5 (start-up / shutdown / ramp-up / ramp-down).
 
 Relationship to the deterministic benchmark
 --------------------------------------------
-The perfect-foresight optimum (:func:`dispatch_deterministic`, eq. B.1) is the
+The perfect-foresight optimum (``dispatch_deterministic``, eq. B.1) is the
 upper bound of any non-anticipating policy: valuing each realised path with
-perfect foresight and averaging bounds the stochastic value from above
-(Property 62). This module reuses the deterministic module's *private* state
+perfect foresight and averaging bounds the stochastic value from above.
+This module reuses the deterministic module's private state
 machine (the status codes, output grid, initial-state translation and the
 feasible-transition enumerator ``_transitions``) so the two solvers optimise over
-an identical feasible set -- the reuse, not a re-implementation, is what makes
-Property 62 hold exactly on shared conventions. Only the immediate-cash-flow
-arithmetic is recomputed here (vectorised over scenarios); the intricate
-feasibility logic is never duplicated. Should ``dispatch_deterministic`` ever
-need to change those helpers, this module must be revisited (documented coupling).
+an identical feasible set: the reuse, not a re-implementation, is what makes
+the upper-bound property hold exactly on shared conventions. Only the
+immediate-cash-flow arithmetic is recomputed here (vectorised over scenarios);
+the intricate feasibility logic is never duplicated. Should ``dispatch_deterministic``
+ever need to change those helpers, this module must be revisited (documented coupling).
 
 Reused state machine (see ``dispatch_deterministic`` for the full account)
 --------------------------------------------------------------------------
@@ -35,42 +35,42 @@ so the Bellman continuation is the plain (undiscounted-further) sum of future
 discounted cash flows -- equivalent to eq. B.2's stepwise ``e^{-r dt}`` when the
 factors are ``e^{-r t dt}``.
 
-The Markov state and the on-peak / off-peak split (Req 21.6, eq. B.4)
----------------------------------------------------------------------
-Appendix B stresses that an hourly power-price *sequence* is **not** Markovian:
+The Markov state and the on-peak / off-peak split (eq. B.4)
+-------------------------------------------------------------
+Appendix B stresses that an hourly power-price sequence is not Markovian:
 tomorrow's on-peak price depends on recent on-peak prices, only weakly on the
-current off-peak price. The fix (eq. B.4) is to carry **two** power spot processes
--- one on-peak, one off-peak -- as separate state coordinates, restoring the
-Markov property. :class:`DispatchFactorModel` implements the split *in the factor
-definition*: ``power_on_index`` and ``power_off_index`` name two coordinates of the
+current off-peak price. The fix (eq. B.4) is to carry two power spot processes,
+one on-peak, one off-peak, as separate state coordinates, restoring the
+Markov property. ``DispatchFactorModel`` implements the split in the factor
+definition: ``power_on_index`` and ``power_off_index`` name two coordinates of the
 simulated log-forward state (they may coincide when every period shares a peak
-kind), and ``peak_kinds[t]`` selects which coordinate is the *active* spot price
+kind), and ``peak_kinds[t]`` selects which coordinate is the active spot price
 for period ``t``. Both coordinates evolve on every step and both enter the LSM
 regression basis / the lattice, so the conditioning information is the full
-Markov state ``(P_on, P_off, G, ...)`` -- exactly the eq. B.4 construction.
+Markov state ``(P_on, P_off, G, ...)``, exactly the eq. B.4 construction.
 
-Risk-adjusted expectation (Req 21.5, consistent with Req 19)
-------------------------------------------------------------
-eq. B.2 optimises under a *risk-adjusted* expectation ``E*``. The factor model's
+Risk-adjusted expectation
+--------------------------
+eq. B.2 optimises under a risk-adjusted expectation ``E*``. The factor model's
 per-step drift ``mu`` is therefore tagged with
-:class:`~quantvolt.numerics.risk_adjustment.DriftKind`, and ``dispatch_value``
-requires :attr:`~quantvolt.numerics.risk_adjustment.DriftKind.RISK_NEUTRAL` -- the
+``quantvolt.numerics.risk_adjustment.DriftKind``, and ``dispatch_value``
+requires ``DriftKind.RISK_NEUTRAL``: the
 pricing / valuation measure in this library's vocabulary ("arbitrage-free
-valuation only"). A :attr:`DriftKind.PHYSICAL` drift is **rejected**: valuing a
+valuation only"). A ``DriftKind.PHYSICAL`` drift is rejected: valuing a
 not-fully-hedgeable asset under the real-world measure would overstate its value,
 the very failure this optimiser guards against. The caller forms the risk-adjusted
 drift ``mu* = mu - lambda_S * sigma`` (eq. 10.5, via
-:func:`~quantvolt.numerics.risk_adjustment.risk_adjusted_drift`) -- for a fully
-tradable factor this collapses to the risk-neutral ``r - y`` -- and tags it
+``quantvolt.numerics.risk_adjustment.risk_adjusted_drift``): for a fully
+tradable factor this collapses to the risk-neutral ``r - y``, and tags it
 ``RISK_NEUTRAL`` to signal "this drift is under the pricing measure ``E*``".
 
 Forced outages (the outage seam)
 --------------------------------
 An optional per-period ``availability`` vector ``M`` in ``(0, 1]`` derates the
 capacity ceiling to ``M_t * c_max(S_t)`` for period ``t`` (eq. B.1's ``M_ti``). A
-caller with an :class:`~quantvolt.market.outages.OutageDataset` supplies
-``M_t = dataset.forced_outage_multiplier(period_hours, installed_capacity_mw)``
-(design 2.23). Online outputs above the derated ceiling become infeasible that
+caller with an ``quantvolt.market.outages.OutageDataset`` supplies
+``M_t = dataset.forced_outage_multiplier(period_hours, installed_capacity_mw)``.
+Online outputs above the derated ceiling become infeasible that
 period; if the derated ceiling falls below ``c_min`` the unit is forced offline
 (eq. B.1 constraint 5).
 
@@ -234,8 +234,8 @@ class DispatchDiagnostics:
 class DispatchFactorModel:
     """Risk-adjusted factor dynamics driving stochastic dispatch (eqs. B.2-B.4).
 
-    The stochastic factors are correlated log-forwards evolved by the Task-62
-    engine ``ΔZ = mu + L·ε`` (GBM). At least a power and a gas coordinate are
+    The stochastic factors are correlated log-forwards evolved by the shared
+    simulation engine ``ΔZ = mu + L·ε`` (GBM). At least a power and a gas coordinate are
     required; the on-peak / off-peak Markov split (eq. B.4) is expressed by naming
     two power coordinates (which may coincide) and a per-period peak label.
     Temperature is supplied deterministically (``temperatures``) -- it drives
@@ -245,13 +245,13 @@ class DispatchFactorModel:
     Attributes:
         log_forward0: Initial log-forward vector ``z0 = log F(0, ·)`` over the
             flattened factor state, dimension ``D`` (``>= 2``).
-        drift: Per-step drift ``mu`` (length ``D``). Must be the **risk-adjusted**
+        drift: Per-step drift ``mu`` (length ``D``). Must be the risk-adjusted
             (pricing-measure) drift and is tagged by ``drift_kind``.
         covariance: Per-step covariance ``C`` (``D x D``), assembled by
-            :func:`~quantvolt.numerics.monte_carlo.build_covariance`.
+            ``quantvolt.numerics.monte_carlo.build_covariance``.
         drift_kind: Measure tag on ``drift``; ``dispatch_value`` requires
-            :attr:`DriftKind.RISK_NEUTRAL` (Req 21.5).
-        peak_kinds: Per-period :class:`PeakKind` selecting the active power
+            ``DriftKind.RISK_NEUTRAL``.
+        peak_kinds: Per-period ``PeakKind`` selecting the active power
             coordinate; its length is the dispatch horizon ``H`` (``>= 1``).
         temperatures: Per-period ambient temperature ``S_t`` (length ``H``).
         power_on_index: Coordinate of ``z0`` used as the on-peak power spot.
@@ -335,11 +335,11 @@ class DispatchFactorModel:
         return self.power_off_index
 
     def simulate(self, seed: int, path_count: int, *, antithetic: bool = True) -> Vector:
-        """Simulate ``(n_paths, H + 1, D)`` log-forward paths (Task-62 engine).
+        """Simulate ``(n_paths, H + 1, D)`` log-forward paths.
 
         Record 0 is ``log_forward0``; record ``t + 1`` holds the prices realised in
-        dispatch period ``t``. Deterministic under ``seed`` (Req 11.2), so a caller
-        (or a Property-62 test) can reproduce the exact scenario set.
+        dispatch period ``t``. Deterministic under ``seed``, so a caller can
+        reproduce the exact scenario set.
         """
         if self.drift.ndim == 1 and self.covariance.ndim == 2:
             return simulate_correlated_forwards(
@@ -431,8 +431,8 @@ def _moves(
     for eq. B.1 constraint 5): a running unit whose min-run timer has not yet reached
     ``d_min`` cannot use ``_transitions``'s own shutdown transition, so if the derate
     also drops every ramp target below ``eff_capacity`` the state machine would offer
-    *no* feasible action at all -- a dead end the reused deterministic state space
-    never has to consider (it assumes full availability, Req 21.4). A physical
+    no feasible action at all, a dead end the reused deterministic state space
+    never has to consider (it assumes full availability). A physical
     derating below ``c_min`` overrides the min-run rule (the unit cannot keep
     producing regardless of the timer), so when no ordinary move survives the filter
     a forced shutdown at zero cash is appended, mirroring the already-documented
@@ -1107,7 +1107,7 @@ _SOLVERS: dict[str, _Solver] = {"lsm": _dispatch_lsm, "tree": _dispatch_tree}
 
 
 def _require_risk_adjusted_drift(drift_kind: DriftKind) -> None:
-    """Reject a physical drift for valuation (Req 21.5; mirror of the VaR guard).
+    """Reject a physical drift for valuation (mirror of the VaR guard).
 
     Valuation optimises under the risk-adjusted expectation ``E*`` (eq. B.2), whose
     drift is ``RISK_NEUTRAL`` in this library's ``DriftKind`` vocabulary
@@ -1141,12 +1141,12 @@ def dispatch_value(
     antithetic: bool = True,
     regression_basis_degree: int = 2,
 ) -> DispatchResult:
-    """Value ``plant`` under uncertainty by stochastic DP (eqs. B.2-B.3; Req 21.1-21.2).
+    """Value ``plant`` under uncertainty by stochastic DP (eqs. B.2-B.3).
 
     Solves the Bellman recursion over the deterministic module's commitment state
-    machine, under the risk-adjusted expectation carried by ``factor_model``
-    (Req 21.5). See the module docstring for the state machine, the on-peak /
-    off-peak Markov split (Req 21.6), the risk-adjusted-drift requirement, the
+    machine, under the risk-adjusted expectation carried by ``factor_model``.
+    See the module docstring for the state machine, the on-peak /
+    off-peak Markov split, the risk-adjusted-drift requirement, the
     forced-outage seam, and the critical-surface representation. All inputs are
     validated before any computation and never mutated.
 
@@ -1157,7 +1157,7 @@ def dispatch_value(
             temperature context (also fixes the horizon ``H``).
         method: ``"lsm"`` (least-squares Monte Carlo) or ``"tree"`` (recombining
             lattice); selected via a dispatch table.
-        seed: Monte Carlo / lattice seed (Req 11.2 determinism); ``>= 0``.
+        seed: Monte Carlo / lattice seed (determinism); ``>= 0``.
         path_count: Simulated paths for ``"lsm"`` (ignored by ``"tree"``); ``>= 1``.
         output_step: Output-grid spacing (MW); defaults to the ramp rate.
         availability: Optional per-period forced-outage multiplier ``M`` in
@@ -1170,7 +1170,7 @@ def dispatch_value(
         initial_uptime: Producing periods already accrued (min-run).
         initial_downtime: Periods already offline (start bucket / min-down); must be
             ``>= 1`` when not ``initial_online`` (delegated to the reused
-            :func:`~quantvolt.assets.dispatch_deterministic._initial_state`).
+            ``quantvolt.assets.dispatch_deterministic._initial_state``).
         evaluation: Independent LSM policy-evaluation sample. By default, the fitted
             policy is evaluated on ``path_count`` fresh paths using ``seed + 1``.
         antithetic: Whether ``"lsm"``'s simulated paths use antithetic variates
@@ -1184,11 +1184,11 @@ def dispatch_value(
             ``"tree"``. Must be ``>= 1``.
 
     Returns:
-        The :class:`DispatchResult` (value + eq. B.5 critical surfaces).
+        The ``DispatchResult`` (value + eq. B.5 critical surfaces).
 
     Raises:
         ValidationError: If ``method`` is unknown; if ``factor_model.drift`` is not
-            risk-adjusted (Req 21.5); if ``path_count`` / ``seed`` /
+            risk-adjusted; if ``path_count`` / ``seed`` /
             ``discount_factors`` / ``availability`` / ``regression_basis_degree`` are
             out of range or mis-sized; if a plant curve is infeasible at a supplied
             temperature; if ``initial_downtime < 1`` while offline; or if the initial