sorbflow 0.3.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sorbflow/__init__.py +41 -0
- sorbflow/__main__.py +5 -0
- sorbflow/_arrays.py +40 -0
- sorbflow/_version.py +3 -0
- sorbflow/adapters/__init__.py +1 -0
- sorbflow/calibration/__init__.py +5 -0
- sorbflow/calibration/batch_objective.py +118 -0
- sorbflow/calibration/least_squares.py +207 -0
- sorbflow/calibration/measurements.py +49 -0
- sorbflow/calibration/profile.py +327 -0
- sorbflow/cli.py +64 -0
- sorbflow/design/__init__.py +6 -0
- sorbflow/design/cad.py +65 -0
- sorbflow/design/hydraulics.py +99 -0
- sorbflow/equilibrium/__init__.py +17 -0
- sorbflow/equilibrium/isotherms.py +117 -0
- sorbflow/fit.py +7 -0
- sorbflow/io/__init__.py +7 -0
- sorbflow/io/experimental.py +159 -0
- sorbflow/io/parquet.py +79 -0
- sorbflow/io/results.py +50 -0
- sorbflow/kinetics/__init__.py +5 -0
- sorbflow/kinetics/sphere.py +112 -0
- sorbflow/observation.py +174 -0
- sorbflow/optimization/__init__.py +5 -0
- sorbflow/optimization/nsga2.py +161 -0
- sorbflow/optimize.py +5 -0
- sorbflow/py.typed +0 -0
- sorbflow/reactors/__init__.py +6 -0
- sorbflow/reactors/_ldf_jacobian.py +58 -0
- sorbflow/reactors/batch.py +87 -0
- sorbflow/reactors/column.py +151 -0
- sorbflow/reactors/hsdm.py +167 -0
- sorbflow/schemas.py +496 -0
- sorbflow/simulate.py +6 -0
- sorbflow/solvers/__init__.py +7 -0
- sorbflow/solvers/integration.py +152 -0
- sorbflow/solvers/options.py +74 -0
- sorbflow/solvers/results.py +318 -0
- sorbflow/uncertainty/__init__.py +5 -0
- sorbflow/uncertainty/monte_carlo.py +129 -0
- sorbflow/units.py +53 -0
- sorbflow/validate/__init__.py +35 -0
- sorbflow/web/__init__.py +5 -0
- sorbflow/web/__main__.py +6 -0
- sorbflow/web/app.py +278 -0
- sorbflow/web/config.py +213 -0
- sorbflow/web/server.py +302 -0
- sorbflow/web/ui.py +50 -0
- sorbflow-0.3.0.dist-info/METADATA +121 -0
- sorbflow-0.3.0.dist-info/RECORD +56 -0
- sorbflow-0.3.0.dist-info/WHEEL +5 -0
- sorbflow-0.3.0.dist-info/entry_points.txt +2 -0
- sorbflow-0.3.0.dist-info/licenses/LICENSE +202 -0
- sorbflow-0.3.0.dist-info/licenses/NOTICE +12 -0
- sorbflow-0.3.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
"""Thin integration boundary; model equations and conservation live in reactors."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Callable
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
|
|
8
|
+
import numpy as np
|
|
9
|
+
from scipy.integrate import BDF, Radau, solve_ivp
|
|
10
|
+
from scipy.sparse import csc_matrix
|
|
11
|
+
|
|
12
|
+
from .._arrays import FloatArray
|
|
13
|
+
from .options import SolverOptions
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class SimulationError(RuntimeError):
|
|
17
|
+
"""Integration, physical-state or conservation checks failed; no success result."""
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@dataclass(frozen=True, slots=True)
|
|
21
|
+
class IntegrationOutput:
|
|
22
|
+
samples: FloatArray
|
|
23
|
+
checkpoints: FloatArray
|
|
24
|
+
nfev: int
|
|
25
|
+
njev: int
|
|
26
|
+
nlu: int
|
|
27
|
+
accepted_steps: int
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@dataclass(frozen=True, slots=True)
|
|
31
|
+
class StreamingIntegrationOutput:
|
|
32
|
+
"""Requested samples and counters; internal states are consumed by a callback."""
|
|
33
|
+
|
|
34
|
+
samples: FloatArray
|
|
35
|
+
nfev: int
|
|
36
|
+
njev: int
|
|
37
|
+
nlu: int
|
|
38
|
+
accepted_steps: int
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
STREAMING_METHODS = {"BDF": BDF, "Radau": Radau}
|
|
42
|
+
StateCallback = Callable[[FloatArray, str, int, float], None]
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def integrate(
|
|
46
|
+
rhs: Callable[[float, FloatArray], FloatArray],
|
|
47
|
+
initial: FloatArray,
|
|
48
|
+
times: FloatArray,
|
|
49
|
+
atol: FloatArray,
|
|
50
|
+
options: SolverOptions,
|
|
51
|
+
sparsity: csc_matrix | None = None,
|
|
52
|
+
jac: Callable[[float, FloatArray], csc_matrix] | None = None,
|
|
53
|
+
) -> IntegrationOutput:
|
|
54
|
+
"""Retain internal accepted states as well as dense output for diagnostics."""
|
|
55
|
+
if options.history != "dense":
|
|
56
|
+
raise ValueError("Streaming history is not implemented for this reactor/model")
|
|
57
|
+
if options.jacobian == "analytic" and jac is None:
|
|
58
|
+
raise ValueError("Analytic Jacobian is not implemented for this reactor/model")
|
|
59
|
+
jac_options = {"jac_sparsity": sparsity} if jac is None else {"jac": jac}
|
|
60
|
+
try:
|
|
61
|
+
solution = solve_ivp(
|
|
62
|
+
rhs,
|
|
63
|
+
(0, float(times[-1])),
|
|
64
|
+
initial,
|
|
65
|
+
method=options.method,
|
|
66
|
+
rtol=options.rtol,
|
|
67
|
+
atol=atol,
|
|
68
|
+
dense_output=True,
|
|
69
|
+
max_step=np.inf if options.max_step_s is None else options.max_step_s,
|
|
70
|
+
**jac_options,
|
|
71
|
+
)
|
|
72
|
+
except (ValueError, FloatingPointError, OverflowError) as exc:
|
|
73
|
+
raise SimulationError(f"Integration failed: {exc}") from exc
|
|
74
|
+
if not solution.success or solution.sol is None:
|
|
75
|
+
raise SimulationError(f"Integrator did not complete: {solution.message}")
|
|
76
|
+
sampled = np.asarray(solution.sol(times), dtype=np.float64)
|
|
77
|
+
checkpoints = np.concatenate((solution.y, sampled), axis=1)
|
|
78
|
+
if not np.all(np.isfinite(checkpoints)):
|
|
79
|
+
raise SimulationError("Nonfinite integration state")
|
|
80
|
+
return IntegrationOutput(
|
|
81
|
+
sampled, checkpoints, solution.nfev, solution.njev, solution.nlu, solution.t.size - 1
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def integrate_streaming(
|
|
86
|
+
rhs: Callable[[float, FloatArray], FloatArray],
|
|
87
|
+
initial: FloatArray,
|
|
88
|
+
times: FloatArray,
|
|
89
|
+
atol: FloatArray,
|
|
90
|
+
options: SolverOptions,
|
|
91
|
+
sparsity: csc_matrix | None = None,
|
|
92
|
+
jac: Callable[[float, FloatArray], csc_matrix] | None = None,
|
|
93
|
+
on_state: StateCallback | None = None,
|
|
94
|
+
) -> StreamingIntegrationOutput:
|
|
95
|
+
"""Consume every accepted state and discard each dense interpolant after sampling.
|
|
96
|
+
|
|
97
|
+
The caller must accumulate physical diagnostics through on_state, then consume
|
|
98
|
+
returned samples. Samples have Fortran layout, matching solve_ivp's OdeSolution.
|
|
99
|
+
BDF assigns an exact internal boundary to the next segment, Radau to the previous
|
|
100
|
+
one; this mirrors solve_ivp's alt_segment selection without retaining its history.
|
|
101
|
+
Callback state arrays are transient and must not be mutated or retained without
|
|
102
|
+
copying. No scipy private integration interfaces are used.
|
|
103
|
+
"""
|
|
104
|
+
if options.jacobian == "analytic" and jac is None:
|
|
105
|
+
raise ValueError("Analytic Jacobian is not implemented for this reactor/model")
|
|
106
|
+
if times.ndim != 1 or times.size < 2 or times[0] != 0:
|
|
107
|
+
raise ValueError("Streaming times must start at zero and contain at least two points")
|
|
108
|
+
if not np.all(np.isfinite(times)) or np.any(np.diff(times) <= 0):
|
|
109
|
+
raise ValueError("Streaming times must be finite and strictly increasing")
|
|
110
|
+
jac_options = {"jac_sparsity": sparsity} if jac is None else {"jac": jac}
|
|
111
|
+
samples = np.empty((initial.size, times.size), dtype=np.float64, order="F")
|
|
112
|
+
ptr, steps = 0, 0
|
|
113
|
+
finite_states = bool(np.all(np.isfinite(initial)))
|
|
114
|
+
try:
|
|
115
|
+
solver = STREAMING_METHODS[options.method](
|
|
116
|
+
rhs, float(0), initial, float(times[-1]), vectorized=False,
|
|
117
|
+
rtol=options.rtol, atol=atol,
|
|
118
|
+
max_step=np.inf if options.max_step_s is None else options.max_step_s,
|
|
119
|
+
**jac_options,
|
|
120
|
+
)
|
|
121
|
+
if on_state is not None:
|
|
122
|
+
on_state(initial, "accepted", 0, float(0))
|
|
123
|
+
while solver.status == "running":
|
|
124
|
+
message = solver.step()
|
|
125
|
+
if solver.status == "failed":
|
|
126
|
+
raise SimulationError(f"Integrator did not complete: {message}")
|
|
127
|
+
interpolant = solver.dense_output()
|
|
128
|
+
start = ptr
|
|
129
|
+
if options.method == "BDF":
|
|
130
|
+
# The last segment additionally owns the final integration time.
|
|
131
|
+
while ptr < times.size and (
|
|
132
|
+
times[ptr] < solver.t
|
|
133
|
+
or (solver.status == "finished" and times[ptr] <= solver.t)
|
|
134
|
+
):
|
|
135
|
+
ptr += 1
|
|
136
|
+
else:
|
|
137
|
+
while ptr < times.size and times[ptr] <= solver.t:
|
|
138
|
+
ptr += 1
|
|
139
|
+
if ptr > start:
|
|
140
|
+
samples[:, start:ptr] = interpolant(times[start:ptr])
|
|
141
|
+
del interpolant
|
|
142
|
+
steps += 1
|
|
143
|
+
finite_states = finite_states and bool(np.all(np.isfinite(solver.y)))
|
|
144
|
+
if on_state is not None:
|
|
145
|
+
on_state(solver.y, "accepted", steps, float(solver.t))
|
|
146
|
+
except (ValueError, FloatingPointError, OverflowError) as exc:
|
|
147
|
+
raise SimulationError(f"Integration failed: {exc}") from exc
|
|
148
|
+
if ptr != times.size:
|
|
149
|
+
raise SimulationError(f"Streaming sampler assigned {ptr} of {times.size} requested times")
|
|
150
|
+
if not finite_states or not np.all(np.isfinite(samples)):
|
|
151
|
+
raise SimulationError("Nonfinite integration state")
|
|
152
|
+
return StreamingIntegrationOutput(samples, solver.nfev, solver.njev, solver.nlu, steps)
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"""Explicit numerical settings with physical absolute tolerances."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from typing import Literal
|
|
7
|
+
|
|
8
|
+
import numpy as np
|
|
9
|
+
from numpy.typing import ArrayLike
|
|
10
|
+
|
|
11
|
+
from .._arrays import FloatArray, real_array
|
|
12
|
+
from ..units import finite_scalar
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
16
|
+
class SolverOptions:
|
|
17
|
+
"""BDF/Radau tolerances; positive finite settings are never silently clamped."""
|
|
18
|
+
|
|
19
|
+
method: Literal["BDF", "Radau"] = "BDF"
|
|
20
|
+
rtol: float = 1e-7
|
|
21
|
+
atol_concentration_kg_m3: float = 1e-10
|
|
22
|
+
atol_loading_kg_kg: float = 1e-12
|
|
23
|
+
atol_mass_kg: float = 1e-12
|
|
24
|
+
mass_rtol: float = 1e-6
|
|
25
|
+
mass_reference_kg: float = 1e-12
|
|
26
|
+
max_step_s: float | None = None
|
|
27
|
+
axial_cells: int = 100
|
|
28
|
+
radial_cells: int = 20
|
|
29
|
+
jacobian: Literal["finite_difference", "analytic"] = "finite_difference"
|
|
30
|
+
history: Literal["dense", "streaming"] = "dense"
|
|
31
|
+
|
|
32
|
+
def __post_init__(self) -> None:
|
|
33
|
+
if self.method not in ("BDF", "Radau"):
|
|
34
|
+
raise ValueError("Only BDF and Radau are supported")
|
|
35
|
+
if self.jacobian not in ("finite_difference", "analytic"):
|
|
36
|
+
raise ValueError("jacobian must be finite_difference or analytic")
|
|
37
|
+
if self.history not in ("dense", "streaming"):
|
|
38
|
+
raise ValueError("history must be dense or streaming")
|
|
39
|
+
for name in (
|
|
40
|
+
"rtol",
|
|
41
|
+
"atol_concentration_kg_m3",
|
|
42
|
+
"atol_loading_kg_kg",
|
|
43
|
+
"atol_mass_kg",
|
|
44
|
+
"mass_rtol",
|
|
45
|
+
"mass_reference_kg",
|
|
46
|
+
"max_step_s",
|
|
47
|
+
):
|
|
48
|
+
value = getattr(self, name)
|
|
49
|
+
if name == "max_step_s" and value is None:
|
|
50
|
+
continue
|
|
51
|
+
number = finite_scalar(value, name)
|
|
52
|
+
if number <= 0:
|
|
53
|
+
raise ValueError(f"{name} must be positive")
|
|
54
|
+
object.__setattr__(self, name, number)
|
|
55
|
+
if not 100 * np.finfo(float).eps <= self.rtol < 1:
|
|
56
|
+
raise ValueError("rtol must be >=100*machine epsilon and <1")
|
|
57
|
+
if self.mass_rtol >= 1:
|
|
58
|
+
raise ValueError("mass_rtol must be <1")
|
|
59
|
+
if type(self.axial_cells) is not int or self.axial_cells < 2:
|
|
60
|
+
raise ValueError("axial_cells must be an integer >=2")
|
|
61
|
+
if type(self.radial_cells) is not int or self.radial_cells < 2:
|
|
62
|
+
raise ValueError("radial_cells must be an integer >=2")
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def sample_times(duration_s: float, requested: ArrayLike | None) -> FloatArray:
|
|
66
|
+
"""Require an ordered full-horizon observation grid, not an integration step size."""
|
|
67
|
+
result = (
|
|
68
|
+
np.linspace(0, duration_s, 201) if requested is None else real_array(requested, "time_s")
|
|
69
|
+
)
|
|
70
|
+
if result.ndim != 1 or result.size < 2:
|
|
71
|
+
raise ValueError("time_s must be a one-dimensional array with at least two points")
|
|
72
|
+
if result[0] != 0 or result[-1] != duration_s or np.any(np.diff(result) <= 0):
|
|
73
|
+
raise ValueError("time_s must strictly increase from zero to duration_s")
|
|
74
|
+
return result
|
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
"""Numerical results with explicit mass diagnostics and reproducibility metadata."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import json
|
|
7
|
+
import platform
|
|
8
|
+
from dataclasses import asdict, dataclass
|
|
9
|
+
from datetime import UTC, datetime
|
|
10
|
+
from importlib.metadata import version
|
|
11
|
+
from typing import Literal
|
|
12
|
+
from uuid import uuid4
|
|
13
|
+
|
|
14
|
+
import numpy as np
|
|
15
|
+
|
|
16
|
+
from .._arrays import FloatArray
|
|
17
|
+
from .._version import VERSION
|
|
18
|
+
from ..schemas import RunManifest
|
|
19
|
+
from .integration import IntegrationOutput, SimulationError
|
|
20
|
+
from .options import SolverOptions
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
24
|
+
class SolverDiagnostics:
|
|
25
|
+
"""Mass and nonnegativity checks include internal accepted states."""
|
|
26
|
+
|
|
27
|
+
nfev: int
|
|
28
|
+
njev: int
|
|
29
|
+
nlu: int
|
|
30
|
+
accepted_steps: int
|
|
31
|
+
max_abs_mass_residual_kg: float
|
|
32
|
+
max_scaled_mass_residual: float
|
|
33
|
+
min_concentration_kg_m3: float
|
|
34
|
+
min_loading_kg_kg: float
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
38
|
+
class SimulationResult:
|
|
39
|
+
"""Arrays use (time, axial cell); a batch has a single cell and no z coordinate.
|
|
40
|
+
|
|
41
|
+
Read-only array snapshots prevent accidental in-place modification. Mass balance
|
|
42
|
+
and state diagnostics accompany every result.
|
|
43
|
+
"""
|
|
44
|
+
|
|
45
|
+
reactor: Literal["batch", "column"]
|
|
46
|
+
time_s: FloatArray
|
|
47
|
+
concentration_kg_m3: FloatArray
|
|
48
|
+
loading_kg_kg: FloatArray
|
|
49
|
+
inventory_kg: FloatArray
|
|
50
|
+
inlet_mass_kg: FloatArray
|
|
51
|
+
outlet_mass_kg: FloatArray
|
|
52
|
+
mass_residual_kg: FloatArray
|
|
53
|
+
z_m: FloatArray | None
|
|
54
|
+
config_json: str
|
|
55
|
+
options_json: str
|
|
56
|
+
numerical_sha256: str
|
|
57
|
+
manifest: RunManifest
|
|
58
|
+
diagnostics: SolverDiagnostics
|
|
59
|
+
radial_loading_kg_kg: FloatArray | None = None
|
|
60
|
+
r_m: FloatArray | None = None
|
|
61
|
+
|
|
62
|
+
def __post_init__(self) -> None:
|
|
63
|
+
for name in (
|
|
64
|
+
"time_s",
|
|
65
|
+
"concentration_kg_m3",
|
|
66
|
+
"loading_kg_kg",
|
|
67
|
+
"inventory_kg",
|
|
68
|
+
"inlet_mass_kg",
|
|
69
|
+
"outlet_mass_kg",
|
|
70
|
+
"mass_residual_kg",
|
|
71
|
+
"z_m",
|
|
72
|
+
"radial_loading_kg_kg",
|
|
73
|
+
"r_m",
|
|
74
|
+
):
|
|
75
|
+
value = getattr(self, name)
|
|
76
|
+
if value is not None:
|
|
77
|
+
copied = np.array(value, dtype=np.float64, copy=True)
|
|
78
|
+
copied.setflags(write=False)
|
|
79
|
+
object.__setattr__(self, name, copied)
|
|
80
|
+
|
|
81
|
+
@property
|
|
82
|
+
def outlet_concentration_kg_m3(self) -> FloatArray:
|
|
83
|
+
"""Last finite-volume cell, or the perfectly mixed liquid for a batch."""
|
|
84
|
+
return self.concentration_kg_m3[:, -1]
|
|
85
|
+
|
|
86
|
+
def to_json(self) -> str:
|
|
87
|
+
"""Serialize full fields plus units, inputs and numerical evidence."""
|
|
88
|
+
data = {
|
|
89
|
+
"result_schema_version": 2,
|
|
90
|
+
"reactor": self.reactor,
|
|
91
|
+
"result_kind": "numerical_simulation",
|
|
92
|
+
"units": {
|
|
93
|
+
"time_s": "s",
|
|
94
|
+
"z_m": "m",
|
|
95
|
+
"concentration_kg_m3": "kg/m^3",
|
|
96
|
+
"loading_kg_kg": "kg/kg_dry_adsorbent",
|
|
97
|
+
"inventory_kg": "kg",
|
|
98
|
+
"inlet_mass_kg": "kg",
|
|
99
|
+
"outlet_mass_kg": "kg",
|
|
100
|
+
"mass_residual_kg": "kg",
|
|
101
|
+
"r_m": "m",
|
|
102
|
+
"radial_loading_kg_kg": "kg/kg_dry_adsorbent",
|
|
103
|
+
},
|
|
104
|
+
"config": json.loads(self.config_json),
|
|
105
|
+
"solver_options": json.loads(self.options_json),
|
|
106
|
+
"numerical_sha256": self.numerical_sha256,
|
|
107
|
+
"manifest": json.loads(self.manifest.to_json()),
|
|
108
|
+
"diagnostics": asdict(self.diagnostics),
|
|
109
|
+
}
|
|
110
|
+
for name in (
|
|
111
|
+
"time_s",
|
|
112
|
+
"z_m",
|
|
113
|
+
"concentration_kg_m3",
|
|
114
|
+
"loading_kg_kg",
|
|
115
|
+
"inventory_kg",
|
|
116
|
+
"inlet_mass_kg",
|
|
117
|
+
"outlet_mass_kg",
|
|
118
|
+
"mass_residual_kg",
|
|
119
|
+
"radial_loading_kg_kg",
|
|
120
|
+
"r_m",
|
|
121
|
+
):
|
|
122
|
+
value = getattr(self, name)
|
|
123
|
+
data[name] = None if value is None else value.tolist()
|
|
124
|
+
return json.dumps(data, sort_keys=True, allow_nan=False, separators=(",", ":"))
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def check_physics(
|
|
128
|
+
concentration: FloatArray,
|
|
129
|
+
loading: FloatArray,
|
|
130
|
+
inventory: FloatArray,
|
|
131
|
+
inlet: FloatArray,
|
|
132
|
+
outlet: FloatArray,
|
|
133
|
+
initial_mass: float,
|
|
134
|
+
options: SolverOptions,
|
|
135
|
+
integrated: IntegrationOutput,
|
|
136
|
+
) -> SolverDiagnostics:
|
|
137
|
+
"""Check accepted+requested states; never clip away negative states or lost mass."""
|
|
138
|
+
residual = inventory - initial_mass - inlet + outlet
|
|
139
|
+
scale = np.maximum(np.maximum(initial_mass, inlet), options.mass_reference_kg)
|
|
140
|
+
min_c, min_q = float(np.min(concentration)), float(np.min(loading))
|
|
141
|
+
if min_c < -10 * options.atol_concentration_kg_m3:
|
|
142
|
+
raise SimulationError(f"Negative liquid concentration: {min_c} kg/m^3")
|
|
143
|
+
if min_q < -10 * options.atol_loading_kg_kg:
|
|
144
|
+
raise SimulationError(f"Negative solid loading: {min_q} kg/kg")
|
|
145
|
+
if (
|
|
146
|
+
not np.all(np.isfinite(inventory))
|
|
147
|
+
or np.any(np.abs(residual) > options.atol_mass_kg + options.mass_rtol * scale)
|
|
148
|
+
or np.any(np.abs(residual) / scale > options.mass_rtol)
|
|
149
|
+
):
|
|
150
|
+
raise SimulationError(
|
|
151
|
+
"Global mass-conservation check failed: "
|
|
152
|
+
f"max absolute residual={np.max(np.abs(residual)):.6g} kg; "
|
|
153
|
+
f"max scaled residual={np.max(np.abs(residual) / scale):.6g}; "
|
|
154
|
+
f"requested mass_rtol={options.mass_rtol:.6g}"
|
|
155
|
+
)
|
|
156
|
+
return SolverDiagnostics(
|
|
157
|
+
nfev=integrated.nfev,
|
|
158
|
+
njev=integrated.njev,
|
|
159
|
+
nlu=integrated.nlu,
|
|
160
|
+
accepted_steps=integrated.accepted_steps,
|
|
161
|
+
max_abs_mass_residual_kg=float(np.max(np.abs(residual))),
|
|
162
|
+
max_scaled_mass_residual=float(np.max(np.abs(residual) / scale)),
|
|
163
|
+
min_concentration_kg_m3=min_c,
|
|
164
|
+
min_loading_kg_kg=min_q,
|
|
165
|
+
)
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
class PhysicsViolation(SimulationError):
|
|
170
|
+
"""Physical-state failure with a location, retaining the dense-path message."""
|
|
171
|
+
|
|
172
|
+
def __init__(self, message: str, location: dict[str, object] | None) -> None:
|
|
173
|
+
super().__init__(message)
|
|
174
|
+
self.location = location
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
class StreamingPhysics:
|
|
178
|
+
"""Bounded-memory checks over all accepted states followed by requested samples."""
|
|
179
|
+
|
|
180
|
+
def __init__(self, *, cells: int, area: float, dz: float, epsilon: float,
|
|
181
|
+
rho_b: float, initial_mass: float, options: SolverOptions,
|
|
182
|
+
n_states: int, block: int = 64) -> None:
|
|
183
|
+
if type(block) is not int or block < 1 or cells < 2 or n_states != 2*cells+2:
|
|
184
|
+
raise ValueError("Invalid streaming buffer dimensions")
|
|
185
|
+
self.cells, self.area, self.dz = cells, area, dz
|
|
186
|
+
self.epsilon, self.rho_b, self.initial_mass = epsilon, rho_b, initial_mass
|
|
187
|
+
self.options = options
|
|
188
|
+
self.buffer = np.empty((n_states, block), order="F")
|
|
189
|
+
self.meta: list[tuple[str, int, float]] = []
|
|
190
|
+
self.min_c, self.min_q = np.inf, np.inf
|
|
191
|
+
self.max_abs_res, self.max_scaled_res = 0., 0.
|
|
192
|
+
self.locations: dict[str, dict[str, object]] = {}
|
|
193
|
+
self.nonfinite: dict[str, object] | None = None
|
|
194
|
+
self.mass_violation: dict[str, object] | None = None
|
|
195
|
+
self.inventory_nonfinite = False
|
|
196
|
+
self.columns = 0
|
|
197
|
+
|
|
198
|
+
def inventory(self, states: FloatArray) -> FloatArray:
|
|
199
|
+
block = np.asfortranarray(states)
|
|
200
|
+
return np.asarray(self.area*self.dz*(self.epsilon*np.sum(block[:self.cells], axis=0)
|
|
201
|
+
+ self.rho_b*np.sum(block[self.cells:2*self.cells], axis=0)))
|
|
202
|
+
|
|
203
|
+
def push_state(self, y: FloatArray, kind: str, index: int, t: float) -> None:
|
|
204
|
+
if y.shape != (self.buffer.shape[0],):
|
|
205
|
+
raise ValueError("Streaming state dimension mismatch")
|
|
206
|
+
self.buffer[:, len(self.meta)] = y
|
|
207
|
+
self.meta.append((kind, index, t))
|
|
208
|
+
if len(self.meta) == self.buffer.shape[1]:
|
|
209
|
+
self._flush()
|
|
210
|
+
|
|
211
|
+
def _flush(self) -> None:
|
|
212
|
+
if self.meta:
|
|
213
|
+
self._process(self.buffer[:, :len(self.meta)], self.meta)
|
|
214
|
+
self.meta = []
|
|
215
|
+
|
|
216
|
+
def push_block(self, samples: FloatArray, metas: list[tuple[str, int, float]]) -> None:
|
|
217
|
+
if (samples.ndim != 2 or samples.shape[0] != self.buffer.shape[0]
|
|
218
|
+
or samples.shape[1] != len(metas)):
|
|
219
|
+
raise ValueError("Streaming sample dimensions mismatch")
|
|
220
|
+
self._flush()
|
|
221
|
+
if metas:
|
|
222
|
+
self._process(np.asfortranarray(samples), metas)
|
|
223
|
+
|
|
224
|
+
def _process(self, states: FloatArray, metas: list[tuple[str, int, float]]) -> None:
|
|
225
|
+
count = states.shape[1]
|
|
226
|
+
self.columns += count
|
|
227
|
+
|
|
228
|
+
def location(j: int) -> dict[str, object]:
|
|
229
|
+
kind, index, time = metas[j]
|
|
230
|
+
return {"kind": kind, "index": index, "time_s": time}
|
|
231
|
+
|
|
232
|
+
finite = np.isfinite(states)
|
|
233
|
+
if not np.all(finite):
|
|
234
|
+
if self.nonfinite is None:
|
|
235
|
+
j = int(np.flatnonzero(~finite.all(axis=0))[0])
|
|
236
|
+
self.nonfinite = location(j)
|
|
237
|
+
return
|
|
238
|
+
c, q = states[:self.cells], states[self.cells:2*self.cells]
|
|
239
|
+
for name, values, attr in (("concentration", c, "min_c"), ("loading", q, "min_q")):
|
|
240
|
+
row, j = divmod(int(np.argmin(values)), count)
|
|
241
|
+
value = float(values[row, j])
|
|
242
|
+
if value < getattr(self, attr):
|
|
243
|
+
setattr(self, attr, value)
|
|
244
|
+
self.locations[name] = {**location(j), "cell": row, "value": value}
|
|
245
|
+
inventory = self.inventory(states)
|
|
246
|
+
inlet, outlet = states[-2], states[-1]
|
|
247
|
+
residual = inventory-self.initial_mass-inlet+outlet
|
|
248
|
+
scale = np.maximum(np.maximum(self.initial_mass, inlet), self.options.mass_reference_kg)
|
|
249
|
+
abs_res = np.abs(residual)
|
|
250
|
+
scaled = abs_res/scale
|
|
251
|
+
self.inventory_nonfinite |= not bool(np.all(np.isfinite(inventory)))
|
|
252
|
+
for values, attr, name in ((abs_res, "max_abs_res", "mass_absolute"),
|
|
253
|
+
(scaled, "max_scaled_res", "mass_scaled")):
|
|
254
|
+
j = int(np.argmax(values))
|
|
255
|
+
if values[j] > getattr(self, attr):
|
|
256
|
+
setattr(self, attr, float(values[j]))
|
|
257
|
+
self.locations[name] = location(j)
|
|
258
|
+
violation = ((abs_res > self.options.atol_mass_kg+self.options.mass_rtol*scale)
|
|
259
|
+
| (scaled > self.options.mass_rtol))
|
|
260
|
+
if self.mass_violation is None and np.any(violation):
|
|
261
|
+
self.mass_violation = location(int(np.flatnonzero(violation)[0]))
|
|
262
|
+
|
|
263
|
+
def finalize(self, nfev: int, njev: int, nlu: int, steps: int) -> SolverDiagnostics:
|
|
264
|
+
self._flush()
|
|
265
|
+
if not self.columns:
|
|
266
|
+
raise ValueError("No states were checked")
|
|
267
|
+
o = self.options
|
|
268
|
+
if self.nonfinite is not None:
|
|
269
|
+
raise PhysicsViolation("Nonfinite integration state", self.nonfinite)
|
|
270
|
+
if self.min_c < -10*o.atol_concentration_kg_m3:
|
|
271
|
+
raise PhysicsViolation(f"Negative liquid concentration: {self.min_c} kg/m^3",
|
|
272
|
+
self.locations.get("concentration"))
|
|
273
|
+
if self.min_q < -10*o.atol_loading_kg_kg:
|
|
274
|
+
raise PhysicsViolation(f"Negative solid loading: {self.min_q} kg/kg",
|
|
275
|
+
self.locations.get("loading"))
|
|
276
|
+
if self.inventory_nonfinite or self.mass_violation is not None:
|
|
277
|
+
raise PhysicsViolation("Global mass-conservation check failed: "
|
|
278
|
+
f"max absolute residual={self.max_abs_res:.6g} kg; "
|
|
279
|
+
f"max scaled residual={self.max_scaled_res:.6g}; "
|
|
280
|
+
f"requested mass_rtol={o.mass_rtol:.6g}", self.mass_violation)
|
|
281
|
+
return SolverDiagnostics(nfev=nfev, njev=njev, nlu=nlu, accepted_steps=steps,
|
|
282
|
+
max_abs_mass_residual_kg=self.max_abs_res,
|
|
283
|
+
max_scaled_mass_residual=self.max_scaled_res,
|
|
284
|
+
min_concentration_kg_m3=float(self.min_c), min_loading_kg_kg=float(self.min_q))
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
def result_metadata(
|
|
288
|
+
config_json: str,
|
|
289
|
+
times: FloatArray,
|
|
290
|
+
options: SolverOptions,
|
|
291
|
+
reactor: str,
|
|
292
|
+
code_revision: str,
|
|
293
|
+
) -> tuple[str, str, RunManifest]:
|
|
294
|
+
"""Fingerprint physical problem, observation times and numerical method separately."""
|
|
295
|
+
options_json = json.dumps(asdict(options), sort_keys=True, allow_nan=False)
|
|
296
|
+
canonical = json.dumps(
|
|
297
|
+
{
|
|
298
|
+
"config": json.loads(config_json),
|
|
299
|
+
"solver": asdict(options),
|
|
300
|
+
"time_s": times.tolist(),
|
|
301
|
+
"reactor": reactor,
|
|
302
|
+
},
|
|
303
|
+
sort_keys=True,
|
|
304
|
+
separators=(",", ":"),
|
|
305
|
+
allow_nan=False,
|
|
306
|
+
)
|
|
307
|
+
fingerprint = hashlib.sha256(canonical.encode()).hexdigest()
|
|
308
|
+
manifest = RunManifest(
|
|
309
|
+
run_id=str(uuid4()),
|
|
310
|
+
created_utc=datetime.now(UTC).isoformat(),
|
|
311
|
+
config_sha256=hashlib.sha256(config_json.encode()).hexdigest(),
|
|
312
|
+
code_revision=code_revision,
|
|
313
|
+
python_version=platform.python_version(),
|
|
314
|
+
seed=0,
|
|
315
|
+
package_versions=tuple(f"{p}=={version(p)}" for p in ("numpy", "scipy", "pint"))
|
|
316
|
+
+ (f"sorbflow=={VERSION}",),
|
|
317
|
+
)
|
|
318
|
+
return options_json, fingerprint, manifest
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
"""Reproducible Monte Carlo and finite-difference sensitivity, independent of solvers."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import json
|
|
7
|
+
from collections.abc import Callable
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
|
|
10
|
+
import numpy as np
|
|
11
|
+
from numpy.typing import ArrayLike
|
|
12
|
+
|
|
13
|
+
from .._arrays import FloatArray, real_array
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
17
|
+
class MonteCarloResult:
|
|
18
|
+
"""Actual samples and sampling uncertainty; not posterior credibility by itself."""
|
|
19
|
+
|
|
20
|
+
inputs_si: FloatArray
|
|
21
|
+
outputs_si: FloatArray
|
|
22
|
+
mean: FloatArray
|
|
23
|
+
standard_deviation: FloatArray
|
|
24
|
+
standard_error_mean: FloatArray
|
|
25
|
+
probabilities: FloatArray
|
|
26
|
+
quantiles: FloatArray
|
|
27
|
+
seed: int
|
|
28
|
+
model_id: str
|
|
29
|
+
samples_sha256: str
|
|
30
|
+
|
|
31
|
+
def __post_init__(self) -> None:
|
|
32
|
+
for name in (
|
|
33
|
+
"inputs_si",
|
|
34
|
+
"outputs_si",
|
|
35
|
+
"mean",
|
|
36
|
+
"standard_deviation",
|
|
37
|
+
"standard_error_mean",
|
|
38
|
+
"probabilities",
|
|
39
|
+
"quantiles",
|
|
40
|
+
):
|
|
41
|
+
array = np.array(getattr(self, name), dtype=np.float64, copy=True)
|
|
42
|
+
array.setflags(write=False)
|
|
43
|
+
object.__setattr__(self, name, array)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def monte_carlo(
|
|
47
|
+
evaluate: Callable[[FloatArray], ArrayLike],
|
|
48
|
+
sampler: Callable[[np.random.Generator, int], ArrayLike],
|
|
49
|
+
*,
|
|
50
|
+
n_samples: int,
|
|
51
|
+
seed: int,
|
|
52
|
+
model_id: str,
|
|
53
|
+
probabilities: ArrayLike = (0.025, 0.5, 0.975),
|
|
54
|
+
) -> MonteCarloResult:
|
|
55
|
+
"""Propagate sampled parameters in SI without silently rejecting failed cases.
|
|
56
|
+
|
|
57
|
+
Sampler returns (n_samples, n_parameters), and may encode correlations or
|
|
58
|
+
non-normal distributions. Each evaluate result is a scalar or a fixed vector.
|
|
59
|
+
Preserve the evaluator/sampler source and model_id separately for reproduction.
|
|
60
|
+
"""
|
|
61
|
+
if type(n_samples) is not int or n_samples < 2:
|
|
62
|
+
raise ValueError("n_samples must be an integer >=2")
|
|
63
|
+
if type(seed) is not int or not 0 <= seed < 2**64:
|
|
64
|
+
raise ValueError("seed must be an unsigned 64-bit integer")
|
|
65
|
+
if not isinstance(model_id, str) or not model_id.strip():
|
|
66
|
+
raise ValueError("model_id must identify the configured model and sampler")
|
|
67
|
+
p = real_array(probabilities, "probabilities")
|
|
68
|
+
if p.ndim != 1 or not p.size or np.any(p < 0) or np.any(p > 1) or np.any(np.diff(p) <= 0):
|
|
69
|
+
raise ValueError("probabilities must strictly increase within [0,1]")
|
|
70
|
+
inputs = real_array(sampler(np.random.default_rng(seed), n_samples), "samples")
|
|
71
|
+
if inputs.ndim != 2 or inputs.shape[0] != n_samples or inputs.shape[1] == 0:
|
|
72
|
+
raise ValueError("Sampler must return (n_samples, n_parameters)")
|
|
73
|
+
rows: list[FloatArray] = []
|
|
74
|
+
for i, sample in enumerate(inputs):
|
|
75
|
+
try:
|
|
76
|
+
output = np.atleast_1d(real_array(evaluate(sample.copy()), "model output"))
|
|
77
|
+
if output.ndim != 1 or output.size == 0 or (rows and output.shape != rows[0].shape):
|
|
78
|
+
raise ValueError("Model output shape must remain a nonempty vector")
|
|
79
|
+
except Exception as exc:
|
|
80
|
+
raise RuntimeError(
|
|
81
|
+
f"Monte Carlo failed at sample {i}; no samples were discarded"
|
|
82
|
+
) from exc
|
|
83
|
+
rows.append(output)
|
|
84
|
+
outputs = np.stack(rows)
|
|
85
|
+
std = np.std(outputs, axis=0, ddof=1)
|
|
86
|
+
header = json.dumps(
|
|
87
|
+
{"inputs": inputs.shape, "outputs": outputs.shape, "model_id": model_id}, sort_keys=True
|
|
88
|
+
).encode()
|
|
89
|
+
digest = hashlib.sha256(
|
|
90
|
+
header + inputs.astype("<f8").tobytes() + outputs.astype("<f8").tobytes()
|
|
91
|
+
).hexdigest()
|
|
92
|
+
return MonteCarloResult(
|
|
93
|
+
inputs_si=inputs,
|
|
94
|
+
outputs_si=outputs,
|
|
95
|
+
mean=np.mean(outputs, axis=0),
|
|
96
|
+
standard_deviation=std,
|
|
97
|
+
standard_error_mean=std / np.sqrt(n_samples),
|
|
98
|
+
probabilities=p,
|
|
99
|
+
quantiles=np.quantile(outputs, p, axis=0),
|
|
100
|
+
seed=seed,
|
|
101
|
+
model_id=model_id,
|
|
102
|
+
samples_sha256=digest,
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def local_sensitivity(
|
|
107
|
+
evaluate: Callable[[FloatArray], ArrayLike],
|
|
108
|
+
point_si: ArrayLike,
|
|
109
|
+
steps_si: ArrayLike,
|
|
110
|
+
) -> FloatArray:
|
|
111
|
+
"""Central numerical Jacobian (outputs, parameters), with caller-chosen SI steps.
|
|
112
|
+
|
|
113
|
+
No clipping or one-sided substitution is applied at physical boundaries.
|
|
114
|
+
Repeat with smaller steps to assess truncation and numerical error.
|
|
115
|
+
"""
|
|
116
|
+
point, steps = real_array(point_si, "point_si"), real_array(steps_si, "steps_si")
|
|
117
|
+
if point.ndim != 1 or not point.size or point.shape != steps.shape or np.any(steps <= 0):
|
|
118
|
+
raise ValueError("Matched nonempty point and positive step vectors are required")
|
|
119
|
+
columns: list[FloatArray] = []
|
|
120
|
+
for i, step in enumerate(steps):
|
|
121
|
+
plus, minus = point.copy(), point.copy()
|
|
122
|
+
plus[i] += step
|
|
123
|
+
minus[i] -= step
|
|
124
|
+
a = np.atleast_1d(real_array(evaluate(plus), "model output"))
|
|
125
|
+
b = np.atleast_1d(real_array(evaluate(minus), "model output"))
|
|
126
|
+
if a.ndim != 1 or a.shape != b.shape or (columns and a.shape != columns[0].shape):
|
|
127
|
+
raise ValueError("Model output shape changed during differentiation")
|
|
128
|
+
columns.append((a - b) / (2 * step))
|
|
129
|
+
return np.column_stack(columns)
|