quantvolt 0.2.0__cp311-abi3-win_amd64.whl

quantvolt/__init__.py

@@ -0,0 +1,426 @@
+"""quantvolt — quantitative analysis of European power and energy markets.
+
+Pure-computation analytics core (see .kiro/steering/). The optional data-adapters layer
+(`quantvolt[data]`) and the native Rust Monte Carlo kernels (`quantvolt._core`) are separate,
+and the core never imports them.
+
+This module is a curated Facade over the subsystems: the domain value objects, the curve
+builder, the pricing entry points, and the risk/portfolio engines. Deeper or more specialised
+names stay on their sub-packages (``quantvolt.numerics``, ``quantvolt.stats``,
+``quantvolt.market``, ``quantvolt.workflow``, ``quantvolt.testing``).
+"""
+
+from __future__ import annotations
+
+from .assets import (
+    BangBangHedgeWarning,
+    DispatchDiagnostics,
+    DispatchFactorModel,
+    DispatchResult,
+    FactorTransform,
+    MonteCarloEvaluation,
+    PhysicalFactorMapping,
+    PlantModel,
+    StorageModel,
+    ValuationSource,
+    bang_bang,
+    dispatch_deterministic,
+    dispatch_value,
+    horizon_divide,
+    storage_intrinsic,
+    storage_value,
+    time_aggregate,
+    valuation_benchmark,
+    var_applicability_guard,
+)
+from .curvemodels import MultifactorForwardModel, SchwartzSmithParams
+from .curves import (
+    ArbitrageChecker,
+    ArbitrageWarning,
+    CurveBuilder,
+    CurveBuildResult,
+    check_arbitrage,
+)
+from .exceptions import (
+    ArbitrageError,
+    AuthenticationError,
+    DataSourceError,
+    DataUnavailableError,
+    EnergyQuantError,
+    ExpiredContractError,
+    InsufficientDataError,
+    MissingTenorError,
+    NativeExtensionError,
+    NoPricingDataError,
+    NumericalError,
+    RateLimitError,
+    ScenarioNotFoundError,
+    ValidationError,
+)
+from .hedging import (
+    PpaNominationCandidate,
+    PpaNominationColumns,
+    PpaNominationFit,
+    PpaNominationObjective,
+    PpaWalkForwardResult,
+    apply_ppa_nomination,
+    calibrate_ppa_nomination,
+    linear_cross_hedge,
+    variance_min_hedge,
+    walk_forward_ppa_nomination,
+)
+from .models import (
+    BUILT_IN_COMMODITIES,
+    CachedAssetValuation,
+    CapFloorStripContract,
+    CapFloorType,
+    ChangeInLawAllocation,
+    CommodityConfig,
+    CurtailmentTreatment,
+    CurveNode,
+    DeliveryPeriod,
+    DeliverySchedule,
+    DiscountCurve,
+    ForwardContract,
+    ForwardCurve,
+    FuturesContract,
+    Granularity,
+    Greeks,
+    Hub,
+    IndexationStep,
+    InstrumentPriceRecord,
+    Moneyness,
+    NegativePriceClause,
+    NegativePriceTreatment,
+    OptionSide,
+    OptionType,
+    PipelineRight,
+    PlantConfig,
+    PowerDeliveryInterval,
+    PowerHedgeContract,
+    PowerHedgePosition,
+    PowerHedgeType,
+    PpaAvailabilityGuarantee,
+    PpaContract,
+    PpaContractMetadata,
+    PpaCreditSupportType,
+    PpaPriceTerms,
+    PpaReconciliationPeriod,
+    PpaReconciliationTerms,
+    PpaSettlementType,
+    PpaTerms,
+    PpaToleranceBand,
+    PpaVolumeBasis,
+    PpaVolumeTerms,
+    PriceUnit,
+    RiskType,
+    SettlementType,
+    SpreadOptionContract,
+    SwapContract,
+    TollingAgreement,
+    TransmissionRight,
+    TransportDirection,
+    VanillaOptionContract,
+    VolatilitySurface,
+    VolatilityTenor,
+    convert_price,
+)
+from .portfolio import (
+    Instrument,
+    MarketData,
+    Portfolio,
+    PortfolioSettlement,
+    PortfolioValuation,
+    Position,
+    PricedPosition,
+    SettledPortfolioPosition,
+    settle_energy_portfolio,
+    value_portfolio,
+)
+from .pricing import (
+    AsianOptionRequest,
+    BachelierOptionRequest,
+    BachelierOptionResult,
+    BarrierOptionRequest,
+    CapFloorRequest,
+    CapFloorResult,
+    ExoticOptionResult,
+    FuturesPricingResult,
+    ImpliedVolResult,
+    LookbackOptionRequest,
+    MissingImbalancePricePolicy,
+    MtMPosition,
+    MtMPositionResult,
+    MtMResult,
+    PowerHedgeDataColumns,
+    PowerHedgeSettlement,
+    PpaDataColumns,
+    PpaIntervalSettlement,
+    PpaPeriodValuation,
+    PpaPeriodVolume,
+    PpaReconciliationColumns,
+    PpaValuationResult,
+    PpaVolumeProfile,
+    SpreadOptionRequest,
+    SpreadOptionResult,
+    SwapPricingResult,
+    TollingResult,
+    TransportRightResult,
+    VanillaOptionRequest,
+    VanillaOptionResult,
+    basis,
+    build_volatility_surface,
+    calendar_spread,
+    classify_moneyness,
+    clean_spread,
+    crack_spread,
+    dark_spread,
+    forward_spread,
+    futures_delta,
+    implied_heat_rate,
+    implied_vol,
+    make_ppa_pricer,
+    mark_to_market,
+    power_cap_payoff,
+    power_floor_payoff,
+    price_asian,
+    price_bachelier_option,
+    price_barrier,
+    price_cap_floor,
+    price_futures,
+    price_lookback,
+    price_ppa,
+    price_spark_spread_option,
+    price_spread_option,
+    price_swap,
+    price_tolling_agreement,
+    price_vanilla_option,
+    reconcile_ppa_ledger,
+    settle_power_hedge_interval,
+    settle_power_hedges_frame,
+    settle_ppa_frame,
+    settle_ppa_interval,
+    spark_spread,
+    value_transport_right,
+)
+from .risk import (
+    CashflowStrategyComparison,
+    CashflowStrategyMetrics,
+    DeltaMatrix,
+    ExcludedPosition,
+    RiskEngine,
+    RiskResult,
+    ScenarioCatalogue,
+    ScenarioResult,
+    ScenarioShock,
+    aggregate_delta,
+    cash_flow_at_risk,
+    compare_cashflow_strategies,
+    credit_var,
+    delta_gamma_var,
+    ewma_covariance,
+    garch11_covariance,
+    monte_carlo_var,
+    parametric_var,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "BUILT_IN_COMMODITIES",
+    "ArbitrageChecker",
+    "ArbitrageError",
+    "ArbitrageWarning",
+    "AsianOptionRequest",
+    "AuthenticationError",
+    "BachelierOptionRequest",
+    "BachelierOptionResult",
+    "BangBangHedgeWarning",
+    "BarrierOptionRequest",
+    "CachedAssetValuation",
+    "CapFloorRequest",
+    "CapFloorResult",
+    "CapFloorStripContract",
+    "CapFloorType",
+    "CashflowStrategyComparison",
+    "CashflowStrategyMetrics",
+    "ChangeInLawAllocation",
+    "CommodityConfig",
+    "CurtailmentTreatment",
+    "CurveBuildResult",
+    "CurveBuilder",
+    "CurveNode",
+    "DataSourceError",
+    "DataUnavailableError",
+    "DeliveryPeriod",
+    "DeliverySchedule",
+    "DeltaMatrix",
+    "DiscountCurve",
+    "DispatchDiagnostics",
+    "DispatchFactorModel",
+    "DispatchResult",
+    "EnergyQuantError",
+    "ExcludedPosition",
+    "ExoticOptionResult",
+    "ExpiredContractError",
+    "FactorTransform",
+    "ForwardContract",
+    "ForwardCurve",
+    "FuturesContract",
+    "FuturesPricingResult",
+    "Granularity",
+    "Greeks",
+    "Hub",
+    "ImpliedVolResult",
+    "IndexationStep",
+    "Instrument",
+    "InstrumentPriceRecord",
+    "InsufficientDataError",
+    "LookbackOptionRequest",
+    "MarketData",
+    "MissingImbalancePricePolicy",
+    "MissingTenorError",
+    "Moneyness",
+    "MonteCarloEvaluation",
+    "MtMPosition",
+    "MtMPositionResult",
+    "MtMResult",
+    "MultifactorForwardModel",
+    "NativeExtensionError",
+    "NegativePriceClause",
+    "NegativePriceTreatment",
+    "NoPricingDataError",
+    "NumericalError",
+    "OptionSide",
+    "OptionType",
+    "PhysicalFactorMapping",
+    "PipelineRight",
+    "PlantConfig",
+    "PlantModel",
+    "Portfolio",
+    "PortfolioSettlement",
+    "PortfolioValuation",
+    "Position",
+    "PowerDeliveryInterval",
+    "PowerHedgeContract",
+    "PowerHedgeDataColumns",
+    "PowerHedgePosition",
+    "PowerHedgeSettlement",
+    "PowerHedgeType",
+    "PpaAvailabilityGuarantee",
+    "PpaContract",
+    "PpaContractMetadata",
+    "PpaCreditSupportType",
+    "PpaDataColumns",
+    "PpaIntervalSettlement",
+    "PpaNominationCandidate",
+    "PpaNominationColumns",
+    "PpaNominationFit",
+    "PpaNominationObjective",
+    "PpaPeriodValuation",
+    "PpaPeriodVolume",
+    "PpaPriceTerms",
+    "PpaReconciliationColumns",
+    "PpaReconciliationPeriod",
+    "PpaReconciliationTerms",
+    "PpaSettlementType",
+    "PpaTerms",
+    "PpaToleranceBand",
+    "PpaValuationResult",
+    "PpaVolumeBasis",
+    "PpaVolumeProfile",
+    "PpaVolumeTerms",
+    "PpaWalkForwardResult",
+    "PriceUnit",
+    "PricedPosition",
+    "RateLimitError",
+    "RiskEngine",
+    "RiskResult",
+    "RiskType",
+    "ScenarioCatalogue",
+    "ScenarioNotFoundError",
+    "ScenarioResult",
+    "ScenarioShock",
+    "SchwartzSmithParams",
+    "SettledPortfolioPosition",
+    "SettlementType",
+    "SpreadOptionContract",
+    "SpreadOptionRequest",
+    "SpreadOptionResult",
+    "StorageModel",
+    "SwapContract",
+    "SwapPricingResult",
+    "TollingAgreement",
+    "TollingResult",
+    "TransmissionRight",
+    "TransportDirection",
+    "TransportRightResult",
+    "ValidationError",
+    "ValuationSource",
+    "VanillaOptionContract",
+    "VanillaOptionRequest",
+    "VanillaOptionResult",
+    "VolatilitySurface",
+    "VolatilityTenor",
+    "aggregate_delta",
+    "apply_ppa_nomination",
+    "bang_bang",
+    "basis",
+    "build_volatility_surface",
+    "calendar_spread",
+    "calibrate_ppa_nomination",
+    "cash_flow_at_risk",
+    "check_arbitrage",
+    "classify_moneyness",
+    "clean_spread",
+    "compare_cashflow_strategies",
+    "convert_price",
+    "crack_spread",
+    "credit_var",
+    "dark_spread",
+    "delta_gamma_var",
+    "dispatch_deterministic",
+    "dispatch_value",
+    "ewma_covariance",
+    "forward_spread",
+    "futures_delta",
+    "garch11_covariance",
+    "horizon_divide",
+    "implied_heat_rate",
+    "implied_vol",
+    "linear_cross_hedge",
+    "make_ppa_pricer",
+    "mark_to_market",
+    "monte_carlo_var",
+    "parametric_var",
+    "power_cap_payoff",
+    "power_floor_payoff",
+    "price_asian",
+    "price_bachelier_option",
+    "price_barrier",
+    "price_cap_floor",
+    "price_futures",
+    "price_lookback",
+    "price_ppa",
+    "price_spark_spread_option",
+    "price_spread_option",
+    "price_swap",
+    "price_tolling_agreement",
+    "price_vanilla_option",
+    "reconcile_ppa_ledger",
+    "settle_energy_portfolio",
+    "settle_power_hedge_interval",
+    "settle_power_hedges_frame",
+    "settle_ppa_frame",
+    "settle_ppa_interval",
+    "spark_spread",
+    "storage_intrinsic",
+    "storage_value",
+    "time_aggregate",
+    "valuation_benchmark",
+    "value_portfolio",
+    "value_transport_right",
+    "var_applicability_guard",
+    "variance_min_hedge",
+    "walk_forward_ppa_nomination",
+]

quantvolt/_core.pyi

@@ -0,0 +1,89 @@
+"""Type stubs for the native Rust extension `quantvolt._core` (built by maturin)."""
+
+import numpy as np
+import numpy.typing as npt
+
+def asian_monte_carlo(
+    forward: float,
+    strike: float,
+    sigma: float,
+    time_to_expiry: float,
+    discount_factor: float,
+    averaging_points: int,
+    is_call: bool,
+    geometric: bool,
+    seed: int,
+    path_count: int,
+    antithetic: bool = True,
+) -> tuple[float, float]:
+    """Return ``(premium, standard_error)``. Native Rust MC kernel (Task 59).
+
+    Driftless GBM under the forward measure with ``averaging_points`` equally spaced
+    fixings; ``antithetic`` (default ``True``) draws ``(+eps, -eps)`` pairs (an odd
+    ``path_count`` rounds up to the next even number when antithetic is on).
+    ``premium = DF * mean(payoff)`` and ``standard_error =
+    DF * std(payoff, ddof=1) / sqrt(n)``. Deterministic per ``seed`` (Req 11.2) — the
+    stream is seeded-Rust-RNG reproducible, not NumPy-matching. Raises ``ValueError``
+    for ``path_count < 1``, ``averaging_points < 1``, or non-finite float inputs.
+    """
+    ...
+
+def simulate_ou(
+    x0: float,
+    kappa: float,
+    mu: float,
+    sigma: float,
+    dt: float,
+    steps: int,
+    seed: int,
+    path_count: int,
+) -> npt.NDArray[np.float64]:
+    """Simulate seeded Ornstein-Uhlenbeck (mean-reverting) paths (Task 59, GBM / OU).
+
+    Euler recursion ``x_{t+dt} = x_t + kappa*(mu - x_t)*dt + sigma*sqrt(dt)*z``. Returns a
+    ``float64`` array of shape ``(path_count, steps + 1)`` with ``x0`` in column 0.
+    Deterministic per ``seed`` (Req 11.2) — seeded-Rust-RNG reproducible, not
+    NumPy-matching. Inputs are validated by the ``numerics.monte_carlo`` wrapper.
+    """
+    ...
+
+def simulate_correlated_forwards(
+    z0: npt.NDArray[np.float64],
+    drift: npt.NDArray[np.float64],
+    cov: npt.NDArray[np.float64],
+    steps: int,
+    path_count: int,
+    seed: int,
+    antithetic: bool,
+) -> npt.NDArray[np.float64]:
+    """Correlated multi-commodity log-forward simulation (Appendix A, Task 62).
+
+    ``z0``/``drift`` are length-``D`` vectors and ``cov`` a ``(D, D)`` symmetric PSD
+    covariance (validated Python-side before this call). Returns a ``float64`` array of
+    shape ``(n_paths, steps + 1, D)`` with record 0 equal to ``z0``. Increment law
+    ``ΔZ = μ + L·ε`` with ``L = chol(cov)`` (eqs A.9-A.13); a zero-variance state index
+    stays frozen (eq A.5). Antithetic variates draw ``(+ε, -ε)`` pairs (odd
+    ``path_count`` rounds up). Deterministic per ``seed`` (Req 11.2). Raises
+    ``ValueError`` on shape/finiteness violations or a non-PSD ``cov`` (defensive; the
+    wrapper already gates PSD).
+    """
+    ...
+
+def simulate_correlated_forwards_term(
+    z0: npt.NDArray[np.float64],
+    drift_steps: npt.NDArray[np.float64],
+    covariance_steps: npt.NDArray[np.float64],
+    active_steps: npt.NDArray[np.bool_],
+    path_count: int,
+    seed: int,
+    antithetic: bool,
+) -> npt.NDArray[np.float64]:
+    """Simulate time-varying correlated state paths (Appendix A).
+
+    ``drift_steps`` has shape ``(steps, D)``, ``covariance_steps`` has shape
+    ``(steps, D, D)``, and ``active_steps`` has shape ``(steps, D)``. An inactive
+    coordinate is held exactly fixed during that step, representing the advancing
+    first-live-tenor index. Returns ``(n_paths, steps + 1, D)``. Raises ``ValueError``
+    for invalid shapes, non-finite inputs, or non-PSD covariance matrices.
+    """
+    ...

quantvolt/_validation.py

@@ -0,0 +1,63 @@
+"""Reusable boundary-validation guards. Public entry points validate through these before any
+computation (fail loudly; see .kiro/steering/coding-style.md). All raise ValidationError."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sized
+
+from .exceptions import ValidationError
+
+
+def require_positive(name: str, value: float) -> None:
+    if not value > 0:
+        raise ValidationError(f"{name} must be > 0, got {value!r}")
+
+
+def require_non_negative(name: str, value: float) -> None:
+    if not math.isfinite(value) or value < 0:
+        raise ValidationError(f"{name} must be finite and >= 0, got {value!r}")
+
+
+def require_in_range(name: str, value: float, lo: float, hi: float) -> None:
+    if not (lo <= value <= hi):
+        raise ValidationError(f"{name} must be in [{lo}, {hi}], got {value!r}")
+
+
+def require_probability(name: str, value: float) -> None:
+    if not (0.0 <= value <= 1.0):
+        raise ValidationError(f"{name} must be in [0, 1], got {value!r}")
+
+
+def require_discount_factor(name: str, value: float) -> None:
+    if not (0.0 < value <= 1.0):
+        raise ValidationError(f"{name} must be in (0, 1], got {value!r}")
+
+
+def require_correlation(name: str, value: float) -> None:
+    if not (-1.0 < value < 1.0):
+        raise ValidationError(f"{name} must be in (-1, 1), got {value!r}")
+
+
+def require_non_empty(name: str, value: Sized) -> None:
+    if len(value) == 0:
+        raise ValidationError(f"{name} must be non-empty")
+
+
+def require_finite(name: str, value: float) -> None:
+    """Require one finite real-valued scalar."""
+    if not math.isfinite(value):
+        raise ValidationError(f"{name} must be finite, got {value!r}")
+
+
+def require_integer_at_least(name: str, value: int, minimum: int) -> None:
+    """Require a genuine integer at or above ``minimum`` (booleans are rejected)."""
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
+        raise ValidationError(f"{name} must be an integer >= {minimum}, got {value!r}")
+
+
+def require_length(name: str, value: Sized, expected: int) -> None:
+    """Require an exact collection length."""
+    actual = len(value)
+    if actual != expected:
+        raise ValidationError(f"{name} must have length {expected}, got {actual}")

quantvolt/assets/__init__.py

@@ -0,0 +1,76 @@
+"""quantvolt.assets — physical-asset optimization (Reqs 21-23).
+
+Thermal-generation dispatch, gas storage, and long-dated valuation governance.
+This package holds the *operational* asset models: equipment and operating
+constraints translated into optimization states, feasible actions, cash flows,
+and asset optionality — the guard against unconstrained financial analogies
+overstating physical value.
+"""
+
+from __future__ import annotations
+
+from .dispatch_approx import BangBangHedgeWarning, bang_bang, horizon_divide, time_aggregate
+from .dispatch_deterministic import DispatchSchedule, dispatch_deterministic
+from .dispatch_sdp import (
+    DispatchDiagnostics,
+    DispatchFactorModel,
+    DispatchResult,
+    FactorTransform,
+    MonteCarloEvaluation,
+    PeakKind,
+    PhysicalFactorMapping,
+    dispatch_value,
+)
+from .long_dated import (
+    BenchmarkResult,
+    CorporatePremium,
+    LowerBoundResult,
+    ValuationSource,
+    VarApplicabilityVerdict,
+    furthest_forward_lower_bound,
+    valuation_benchmark,
+    var_applicability_guard,
+)
+from .plant import PlantModel, StartCost, StartState
+from .storage import (
+    IntrinsicResult,
+    StorageFactorModel,
+    StorageModel,
+    StorageValueResult,
+    storage_intrinsic,
+    storage_value,
+)
+
+__all__ = [
+    "BangBangHedgeWarning",
+    "BenchmarkResult",
+    "CorporatePremium",
+    "DispatchDiagnostics",
+    "DispatchFactorModel",
+    "DispatchResult",
+    "DispatchSchedule",
+    "FactorTransform",
+    "IntrinsicResult",
+    "LowerBoundResult",
+    "MonteCarloEvaluation",
+    "PeakKind",
+    "PhysicalFactorMapping",
+    "PlantModel",
+    "StartCost",
+    "StartState",
+    "StorageFactorModel",
+    "StorageModel",
+    "StorageValueResult",
+    "ValuationSource",
+    "VarApplicabilityVerdict",
+    "bang_bang",
+    "dispatch_deterministic",
+    "dispatch_value",
+    "furthest_forward_lower_bound",
+    "horizon_divide",
+    "storage_intrinsic",
+    "storage_value",
+    "time_aggregate",
+    "valuation_benchmark",
+    "var_applicability_guard",
+]

quantvolt/assets/_tolerance.py

@@ -0,0 +1,19 @@
+"""Shared floating-point tolerance for discretised grid / feasibility comparisons.
+
+:mod:`~quantvolt.assets.storage` and :mod:`~quantvolt.assets.dispatch_deterministic`
+each discretise a continuous state (inventory volume, output level) onto a uniform
+grid and then compare floats against grid boundaries / ramp limits / capacity ceilings.
+Both encode the *same* tolerance for the *same* reason — absorbing floating-point
+rounding in grid-step arithmetic (``floor(span / step + eps)``) and in ``<=``/``>=``
+feasibility checks at a grid boundary — so it is defined once here rather than as two
+independently chosen ``1e-9`` literals.
+
+This is distinct from :mod:`~quantvolt.assets.dispatch_sdp`'s
+``_SURFACE_SLOPE_EPS``, which guards a regression-slope near-singularity (a
+different tolerance for a different purpose) and is not consolidated here.
+"""
+
+from __future__ import annotations
+
+#: Grid-alignment / feasibility tolerance shared by storage and deterministic dispatch.
+GRID_EPS = 1e-9