stochops 0.1.0__py3-none-any.whl

stochops/__init__.py

@@ -0,0 +1,55 @@
+"""stochops: A fluent Monte Carlo & Latin Hypercube Sampling simulation engine for OpenSeesPy."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from stochops.adaptive.solver_fallback import AdaptiveAnalysisRunner, ConvergenceError
+from stochops.builder import SimulationBuilder, SimulationEngine
+from stochops.execution.process_pool import ProcessPoolEngine
+from stochops.parameters import (
+    BaseParameter,
+    ContinuousParam,
+    DiscreteParam,
+    Distribution,
+    GroundMotionSetParam,
+)
+from stochops.protocols import (
+    ExecutionEngine,
+    ParametricModel,
+    ResultSink,
+    Sampler,
+)
+from stochops.samplers.lhs import LHSSampler
+from stochops.samplers.mc import MCSampler
+from stochops.sinks.parquet import ParquetSink
+
+try:
+    __version__ = version("stochops")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0-dev"
+
+__all__ = [
+    # Core Orchestration
+    "SimulationBuilder",
+    "SimulationEngine",
+    # Parameter Definitions
+    "BaseParameter",
+    "ContinuousParam",
+    "DiscreteParam",
+    "Distribution",
+    "GroundMotionSetParam",
+    # Sampling Strategies
+    "LHSSampler",
+    "MCSampler",
+    # Parallel Execution Engines
+    "ProcessPoolEngine",
+    # Data Persistence Sinks
+    "ParquetSink",
+    # Adaptive Solver Utilities
+    "AdaptiveAnalysisRunner",
+    "ConvergenceError",
+    # Strategy Protocols
+    "ParametricModel",
+    "Sampler",
+    "ExecutionEngine",
+    "ResultSink",
+]

stochops/adaptive/__init__.py

@@ -0,0 +1,6 @@
+"""Adaptive solver utilities for stochops."""
+
+from stochops.adaptive.solver_fallback import AdaptiveAnalysisRunner
+from stochops.exceptions import ConvergenceError
+
+__all__ = ["AdaptiveAnalysisRunner", "ConvergenceError"]

stochops/adaptive/solver_fallback.py

@@ -0,0 +1,89 @@
+"""Adaptive solver fallback and automated substepping for OpenSeesPy analyses."""
+
+import openseespy.opensees as ops
+
+from stochops.exceptions import ConvergenceError
+
+__all__ = ["AdaptiveAnalysisRunner", "ConvergenceError"]
+
+
+class AdaptiveAnalysisRunner:
+    """Orchestrates adaptive algorithm switching and recursive substepping during OpenSeesPy analyses.
+
+    Intercepts numerical divergence during transient step evaluations by cycling through alternative
+    solution algorithms and executing recursive step-halving before failing.
+    """
+
+    def __init__(
+        self,
+        algorithms: list[str] | None = None,
+        enable_substepping: bool = True,
+        max_substep_depth: int = 4,
+    ) -> None:
+        """Initializes the AdaptiveAnalysisRunner.
+
+        Args:
+            algorithms: Ordered list of OpenSees solution algorithms to attempt upon non-convergence.
+                Defaults to ["Newton", "KrylovNewton", "NewtonWithLineSearch", "BFGS", "Broyden"].
+            enable_substepping: Whether to execute recursive step-halving if all algorithms fail.
+            max_substep_depth: Maximum recursion depth for substepping (depth 4 = dt / 16).
+        """
+        self.algorithms = algorithms or [
+            "Newton",
+            "KrylovNewton",
+            "NewtonWithLineSearch",
+            "BFGS",
+            "Broyden",
+        ]
+        self.enable_substepping = enable_substepping
+        self.max_substep_depth = max_substep_depth
+        self.primary_algorithm = self.algorithms[0]
+
+    def analyze_step(self, dt: float) -> None:
+        """Executes a single dynamic transient analysis step with adaptive retries.
+
+        Args:
+            dt: Time step increment for the analysis step.
+
+        Raises:
+            ConvergenceError: If all algorithm options and substepping levels fail to converge.
+        """
+        # 1. Attempt primary algorithm
+        ops.algorithm(self.primary_algorithm)
+        ok = ops.analyze(1, dt)
+        if ok == 0:
+            return
+
+        # 2. Fallback sequence: try alternative solution algorithms
+        for fallback_alg in self.algorithms[1:]:
+            ops.algorithm(fallback_alg)
+            ok = ops.analyze(1, dt)
+            if ok == 0:
+                # Reset algorithm to primary for subsequent steps
+                ops.algorithm(self.primary_algorithm)
+                return
+
+        # 3. Fallback sequence: recursive step-halving
+        if self.enable_substepping:
+            self._execute_substep(dt / 2.0, current_depth=1)
+            ops.algorithm(self.primary_algorithm)
+            return
+
+        raise ConvergenceError(
+            f"Analysis step failed to converge at dt={dt} across all candidate algorithms."
+        )
+
+    def _execute_substep(self, reduced_dt: float, current_depth: int) -> None:
+        """Recursively splits a failing step into two half-steps."""
+        if current_depth > self.max_substep_depth:
+            raise ConvergenceError(
+                f"Maximum substepping depth ({self.max_substep_depth}) exceeded at dt={reduced_dt}."
+            )
+
+        # Execute two half-steps to cover the original step interval
+        for _ in range(2):
+            try:
+                self.analyze_step(reduced_dt)
+            except ConvergenceError:
+                # If a half-step fails, recurse deeper
+                self._execute_substep(reduced_dt / 2.0, current_depth + 1)

stochops/builder.py

@@ -0,0 +1,140 @@
+"""Simulation builder and engine orchestration for stochops."""
+
+from collections.abc import Callable
+from typing import Any
+
+from stochops.protocols import (
+    ExecutionEngine,
+    ParametricModel,
+    ResultSink,
+    Sampler,
+)
+
+
+class SimulationEngine:
+    """Orchestrates batch generation, execution dispatch, and data streaming."""
+
+    def __init__(
+        self,
+        model: ParametricModel | Callable[[dict[str, Any]], dict[str, Any]],
+        sampler: Sampler,
+        execution_engine: ExecutionEngine,
+        sink: ResultSink,
+        batch_size: int = 100,
+    ) -> None:
+        self.model = model
+        self.sampler = sampler
+        self.execution_engine = execution_engine
+        self.sink = sink
+        self.batch_size = batch_size
+
+    def run(self, total_samples: int) -> None:
+        """Executes the simulation pipeline across total_samples in chunks of batch_size.
+
+        Args:
+            total_samples: Total number of Monte Carlo / LHS realizations to run.
+        """
+        if total_samples <= 0:
+            raise ValueError("total_samples must be greater than zero.")
+
+        remaining = total_samples
+        try:
+            while remaining > 0:
+                current_batch_size = min(self.batch_size, remaining)
+
+                # 1. Generate sample realizations
+                samples = self.sampler.sample(current_batch_size)
+
+                # 2. Dispatch batch across worker processes
+                results = self.execution_engine.run_batch(self.model, samples)
+
+                # 3. Stream results to persistent sink
+                self.sink.write(results)
+
+                remaining -= current_batch_size
+        finally:
+            # Always ensure storage buffers are flushed, file locks released,
+            # and long-lived worker resources are shut down.
+            self.sink.close()
+            self.execution_engine.close()
+
+
+class SimulationBuilder:
+    """Fluent builder for constructing an immutable SimulationEngine instance."""
+
+    def __init__(self) -> None:
+        self._model: (
+            ParametricModel | Callable[[dict[str, Any]], dict[str, Any]] | None
+        ) = None
+        self._sampler: Sampler | None = None
+        self._execution_engine: ExecutionEngine | None = None
+        self._sink: ResultSink | None = None
+        self._batch_size: int = 100
+
+    def model(
+        self, model: ParametricModel | Callable[[dict[str, Any]], dict[str, Any]]
+    ) -> "SimulationBuilder":
+        """Sets the structural model evaluation callback."""
+        self._model = model
+        return self
+
+    def sampler(self, sampler: Sampler) -> "SimulationBuilder":
+        """Sets the sampling strategy (e.g., LHSSampler)."""
+        self._sampler = sampler
+        return self
+
+    def execution_engine(
+        self, engine: ExecutionEngine
+    ) -> "SimulationBuilder":
+        """Sets the parallel dispatch engine (e.g., ProcessPoolEngine)."""
+        self._execution_engine = engine
+        return self
+
+    def sink(self, sink: ResultSink) -> "SimulationBuilder":
+        """Sets the data persistence sink (e.g., ParquetSink)."""
+        self._sink = sink
+        return self
+
+    def batch_size(self, batch_size: int) -> "SimulationBuilder":
+        """Sets the chunk size for batch processing and memory management."""
+        if batch_size <= 0:
+            raise ValueError("batch_size must be greater than zero.")
+        self._batch_size = batch_size
+        return self
+
+    def build(self) -> SimulationEngine:
+        """Validates strategy protocol slots and constructs the SimulationEngine.
+
+        Raises:
+            ValueError: If any required strategy (model, sampler, engine, sink) is missing.
+        """
+        missing_slots: list[str] = []
+
+        if self._model is None:
+            missing_slots.append("model (via .model())")
+        if self._sampler is None:
+            missing_slots.append("sampler (via .sampler())")
+        if self._execution_engine is None:
+            missing_slots.append("execution_engine (via .execution_engine())")
+        if self._sink is None:
+            missing_slots.append("sink (via .sink())")
+
+        if missing_slots:
+            raise ValueError(
+                "Cannot build SimulationEngine. Missing required strategy slots: "
+                + ", ".join(missing_slots)
+            )
+
+        # Assert non-None for mypy strict checking after validation
+        assert self._model is not None
+        assert self._sampler is not None
+        assert self._execution_engine is not None
+        assert self._sink is not None
+
+        return SimulationEngine(
+            model=self._model,
+            sampler=self._sampler,
+            execution_engine=self._execution_engine,
+            sink=self._sink,
+            batch_size=self._batch_size,
+        )

stochops/exceptions.py

@@ -0,0 +1,5 @@
+"""Domain-specific exceptions for stochops."""
+
+
+class ConvergenceError(RuntimeError):
+    """Raised when all adaptive fallback strategies and substepping attempts fail to converge."""

stochops/execution/__init__.py

@@ -0,0 +1,5 @@
+"""Parallel execution engines for stochops."""
+
+from stochops.execution.process_pool import ProcessPoolEngine
+
+__all__ = ["ProcessPoolEngine"]

stochops/execution/process_pool.py

@@ -0,0 +1,151 @@
+"""Process pool execution engine implementation for stochops.
+
+Provides process-isolated parallel evaluation using Python's multiprocessing spawn context
+to prevent C++ static memory contamination and segfaults in OpenSeesPy.
+"""
+
+import multiprocessing as mp
+from collections.abc import Callable
+from concurrent.futures import BrokenExecutor, ProcessPoolExecutor
+from typing import Any
+
+from stochops.exceptions import ConvergenceError
+from stochops.protocols.model import ParametricModel
+
+# Tokens used to conservatively classify failures thrown by user models as
+# solver divergences even when the raised exception type is unknown to stochops.
+_DIVERGENCE_TOKENS = ("convergence", "converge", "krylov", "substep", "step failed")
+_MAX_RETRIES = 1
+
+
+def _worker_entrypoint(
+    evaluator: ParametricModel | Callable[[dict[str, Any]], dict[str, Any]],
+    sample_id: int,
+    sample: dict[str, Any],
+) -> dict[str, Any]:
+    """Top-level worker execution wrapper for process boundary isolation.
+
+    Traps model execution exceptions (e.g. ConvergenceError, runtime errors) to ensure
+    individual realization failures do not crash the parallel worker pool.
+    """
+    record: dict[str, Any] = {
+        "sample_id": sample_id,
+        **sample,
+    }
+
+    try:
+        edps = evaluator(sample)
+        if not isinstance(edps, dict):
+            raise TypeError(f"Model evaluator must return a dictionary of EDPs, got {type(edps).__name__}")
+
+        return {
+            **record,
+            "status": "CONVERGED",
+            "error_type": None,
+            "error_message": None,
+            **edps,
+        }
+    except Exception as err:
+        error_class = type(err).__name__
+        status_flag = _classify_failure(err)
+        return {
+            **record,
+            "status": status_flag,
+            "error_type": error_class,
+            "error_message": str(err),
+        }
+
+
+def _classify_failure(err: Exception) -> str:
+    """Classifies a trapped worker exception as ``DIVERGED`` or ``FAILED``.
+
+    Uses structural type checks (``isinstance``) against stochops' own
+    ``ConvergenceError`` in preference to fragile string matching on exception
+    class names, with a conservative message-token fallback for exceptions
+    raised by user models that do not derive from stochops exceptions.
+    """
+    if isinstance(err, ConvergenceError):
+        return "DIVERGED"
+
+    message = str(err).lower()
+    if any(token in message for token in _DIVERGENCE_TOKENS):
+        return "DIVERGED"
+
+    return "FAILED"
+
+
+class ProcessPoolEngine:
+    """Parallel execution engine implementing the ExecutionEngine protocol.
+
+    Uses a spawned process pool executor to isolate each worker's memory space,
+    ensuring OpenSees C++ static variables do not leak across consecutive realizations.
+
+    The worker pool is created lazily on the first batch and reused across
+    subsequent batches, so OpenSeesPy is imported exactly once per worker
+    process. Call :meth:`close` to release the pool, or it is released
+    automatically when :class:`~stochops.builder.SimulationEngine.run` finishes.
+
+    ``num_workers`` defaults to the system CPU count, which may be aggressive
+    for memory-heavy finite-element models; consider passing a lower value.
+    """
+
+    def __init__(self, num_workers: int | None = None) -> None:
+        """Initializes the ProcessPoolEngine.
+
+        Args:
+            num_workers: Number of parallel worker processes. Defaults to system CPU count.
+        """
+        self.num_workers = num_workers or mp.cpu_count()
+        self._executor: ProcessPoolExecutor | None = None
+
+    def _get_executor(self) -> ProcessPoolExecutor:
+        """Returns the lazily-created persistent process pool."""
+        if self._executor is None:
+            # Force 'spawn' context to guarantee clean process isolation for C++ libraries
+            ctx = mp.get_context("spawn")
+            self._executor = ProcessPoolExecutor(max_workers=self.num_workers, mp_context=ctx)
+        return self._executor
+
+    def run_batch(
+        self,
+        evaluator: ParametricModel | Callable[[dict[str, Any]], dict[str, Any]],
+        samples: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """Dispatches a batch of parameter realizations across the worker pool.
+
+        Args:
+            evaluator: The model evaluation callback.
+            samples: List of parameter dictionaries to evaluate.
+
+        Returns:
+            List of result dictionaries containing execution metadata, input parameters,
+            and evaluated EDPs (or failure diagnostics).
+        """
+        if not samples:
+            return []
+
+        last_error: Exception | None = None
+        for attempt in range(_MAX_RETRIES + 1):
+            try:
+                executor = self._get_executor()
+                futures = [
+                    executor.submit(_worker_entrypoint, evaluator, idx, sample)
+                    for idx, sample in enumerate(samples)
+                ]
+                return [future.result() for future in futures]
+            except BrokenExecutor as err:
+                # Worker crashed (e.g. segfault). Recreate the pool and retry once.
+                last_error = err
+                if attempt < _MAX_RETRIES and self._executor is not None:
+                    self._executor.shutdown(wait=False, cancel_futures=True)
+                    self._executor = None
+                    continue
+                break
+
+        raise RuntimeError("Process pool workers crashed repeatedly; batching aborted.") from last_error
+
+    def close(self) -> None:
+        """Shuts down the persistent worker pool, releasing all worker processes."""
+        if self._executor is not None:
+            self._executor.shutdown(wait=True)
+            self._executor = None

stochops/parameters.py

@@ -0,0 +1,152 @@
+"""Parameter definitions and distribution transformations for stochops."""
+
+import warnings
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+import numpy as np
+from scipy.stats import gumbel_r, lognorm, norm, uniform
+
+
+# Distribution Enum
+class Distribution(str, Enum):
+    NORMAL = "normal"
+    LOGNORMAL = "lognormal"
+    GUMBEL = "gumbel"
+    UNIFORM = "uniform"
+
+
+# Discrete Transformation Registry
+TransformFunc = Callable[[float, float, float], float]
+
+def _normal_ppf(u: float, mean: float, std: float) -> float:
+    return float(norm.ppf(u, loc=mean, scale=std))
+
+def _lognormal_ppf(u: float, mean: float, std: float) -> float:
+    shape = np.sqrt(np.log(1.0 + (std / mean) ** 2))
+    scale = mean / np.sqrt(1.0 + (std / mean) ** 2)
+    return float(lognorm.ppf(u, s=shape, scale=scale))
+
+def _gumbel_ppf(u: float, mean: float, std: float) -> float:
+    beta = std * np.sqrt(6) / np.pi
+    mu = mean - 0.5772156649 * beta
+    return float(gumbel_r.ppf(u, loc=mu, scale=beta))
+
+def _uniform_ppf(u: float, mean: float, std: float) -> float:
+    low = mean - np.sqrt(3) * std
+    high = mean + np.sqrt(3) * std
+    return float(uniform.ppf(u, loc=low, scale=high - low))
+
+DIST_REGISTRY: dict[Distribution, TransformFunc] = {
+    Distribution.NORMAL: _normal_ppf,
+    Distribution.LOGNORMAL: _lognormal_ppf,
+    Distribution.GUMBEL: _gumbel_ppf,
+    Distribution.UNIFORM: _uniform_ppf,
+}
+
+
+# 3. Base Parameter Contract
+class BaseParameter(ABC):
+    name: str
+
+    @abstractmethod
+    def transform_unit_draw(self, u: float) -> Any:
+        ...
+
+
+# 4. Lean Continuous Parameter Class
+@dataclass(frozen=True)
+class ContinuousParam(BaseParameter):
+    name: str
+    dist: Distribution
+    mean: float
+    std: float
+    max_value: float | None = None
+    min_value: float | None = None
+
+    def transform_unit_draw(self, u: float) -> float:
+        u_clamped = float(np.clip(u, 1e-9, 1.0 - 1e-9))
+        
+        # O(1) Registry Dispatch
+        transform_fn = DIST_REGISTRY[self.dist]  # Guaranteed valid by __post_init__
+        val = transform_fn(u_clamped, self.mean, self.std)
+
+        if self.min_value is not None:
+            val = max(self.min_value, val)
+        if self.max_value is not None:
+            val = min(self.max_value, val)
+
+        return val
+
+
+@dataclass(frozen=True)
+class DiscreteParam(BaseParameter):
+    name: str
+    choices: list[Any]
+    probabilities: list[float] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.choices:
+            raise ValueError("DiscreteParam choices cannot be empty.")
+
+        if self.probabilities is not None:
+            if len(self.probabilities) != len(self.choices):
+                raise ValueError(
+                    f"DiscreteParam probabilities length {len(self.probabilities)} "
+                    f"does not match choices length {len(self.choices)}."
+                )
+            probs = np.asarray(self.probabilities, dtype=float)
+            if not np.all(np.isfinite(probs)) or np.any(probs < 0.0):
+                raise ValueError(
+                    "DiscreteParam probabilities must be finite and non-negative."
+                )
+            if probs.sum() <= 0.0:
+                raise ValueError(
+                    "DiscreteParam probabilities must have a positive sum."
+                )
+            # Normalize so the probabilities sum to 1.0
+            normalized = (probs / probs.sum()).tolist()
+            object.__setattr__(self, "probabilities", normalized)
+
+    def transform_unit_draw(self, u: float) -> Any:
+        u_clamped = float(np.clip(u, 0.0, 1.0 - 1e-9))
+        if self.probabilities is None:
+            idx = min(int(np.floor(u_clamped * len(self.choices))), len(self.choices) - 1)
+            return self.choices[idx]
+        
+        cdf = np.cumsum(self.probabilities)
+        idx = min(int(np.searchsorted(cdf, u_clamped, side="right")), len(self.choices) - 1)
+        return self.choices[idx]
+
+
+@dataclass(frozen=True)
+class GroundMotionSetParam(BaseParameter):
+    name: str
+    records: list[Any]
+
+    def transform_unit_draw(self, u: float) -> Any:
+        u_clamped = float(np.clip(u, 0.0, 1.0 - 1e-9))
+        idx = min(int(np.floor(u_clamped * len(self.records))), len(self.records) - 1)
+        return self.records[idx]
+
+@dataclass(frozen=True)
+class Parameter:
+    """Legacy simple parameter dataclass.
+
+    Deprecated in favour of :class:`ContinuousParam`. Kept for backwards
+    compatibility; constructing one emits a ``DeprecationWarning``.
+    """
+    name: str
+    dist: Distribution
+    mean: float
+    std: float
+
+    def __post_init__(self) -> None:
+        warnings.warn(
+            "Parameter is deprecated; use ContinuousParam instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )

stochops/protocols/__init__.py

@@ -0,0 +1,11 @@
+from stochops.protocols.engine import ExecutionEngine
+from stochops.protocols.model import ParametricModel
+from stochops.protocols.sampler import Sampler
+from stochops.protocols.sink import ResultSink
+
+__all__ = [
+    "ParametricModel",
+    "Sampler",
+    "ExecutionEngine",
+    "ResultSink",
+]

stochops/protocols/engine.py

@@ -0,0 +1,35 @@
+from collections.abc import Callable
+from typing import Any, Protocol, runtime_checkable
+
+from stochops.protocols.model import ParametricModel
+
+
+@runtime_checkable
+class ExecutionEngine(Protocol):
+    """Protocol for worker dispatch and isolation strategies."""
+
+    def run_batch(
+        self,
+        evaluator: ParametricModel | Callable[[dict[str, Any]], dict[str, Any]],
+        samples: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """Dispatches a batch of samples across worker processes.
+
+        Args:
+            evaluator: The model evaluation callable.
+            samples: List of parameter dictionaries to evaluate.
+
+        Returns:
+            List of result dictionaries containing execution metadata, parameters,
+            and evaluated EDPs.
+        """
+        ...
+
+    def close(self) -> None:
+        """Releases any long-lived worker resources held by the engine.
+
+        Called once by the simulation engine after a campaign finishes.
+        Implementations must be safe to call multiple times and must be a
+        no-op if no resources were ever allocated.
+        """
+        ...

stochops/protocols/model.py

@@ -0,0 +1,19 @@
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ParametricModel(Protocol):
+    """Protocol for user-defined structural evaluation callbacks."""
+
+    def __call__(self, parameters: dict[str, Any]) -> dict[str, Any]:
+        """Executes a single structural realization given input parameters.
+
+        Args:
+            parameters: Dictionary mapping parameter names to sampled physical values
+                (e.g., {"fc": 30e6, "fy": 420e6}).
+
+        Returns:
+            Dictionary of extracted Engineering Demand Parameters (EDPs)
+            (e.g., {"max_drift": 0.012, "base_shear_kN": 150.5}).
+        """
+        ...