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.
Files changed (56) hide show
  1. sorbflow/__init__.py +41 -0
  2. sorbflow/__main__.py +5 -0
  3. sorbflow/_arrays.py +40 -0
  4. sorbflow/_version.py +3 -0
  5. sorbflow/adapters/__init__.py +1 -0
  6. sorbflow/calibration/__init__.py +5 -0
  7. sorbflow/calibration/batch_objective.py +118 -0
  8. sorbflow/calibration/least_squares.py +207 -0
  9. sorbflow/calibration/measurements.py +49 -0
  10. sorbflow/calibration/profile.py +327 -0
  11. sorbflow/cli.py +64 -0
  12. sorbflow/design/__init__.py +6 -0
  13. sorbflow/design/cad.py +65 -0
  14. sorbflow/design/hydraulics.py +99 -0
  15. sorbflow/equilibrium/__init__.py +17 -0
  16. sorbflow/equilibrium/isotherms.py +117 -0
  17. sorbflow/fit.py +7 -0
  18. sorbflow/io/__init__.py +7 -0
  19. sorbflow/io/experimental.py +159 -0
  20. sorbflow/io/parquet.py +79 -0
  21. sorbflow/io/results.py +50 -0
  22. sorbflow/kinetics/__init__.py +5 -0
  23. sorbflow/kinetics/sphere.py +112 -0
  24. sorbflow/observation.py +174 -0
  25. sorbflow/optimization/__init__.py +5 -0
  26. sorbflow/optimization/nsga2.py +161 -0
  27. sorbflow/optimize.py +5 -0
  28. sorbflow/py.typed +0 -0
  29. sorbflow/reactors/__init__.py +6 -0
  30. sorbflow/reactors/_ldf_jacobian.py +58 -0
  31. sorbflow/reactors/batch.py +87 -0
  32. sorbflow/reactors/column.py +151 -0
  33. sorbflow/reactors/hsdm.py +167 -0
  34. sorbflow/schemas.py +496 -0
  35. sorbflow/simulate.py +6 -0
  36. sorbflow/solvers/__init__.py +7 -0
  37. sorbflow/solvers/integration.py +152 -0
  38. sorbflow/solvers/options.py +74 -0
  39. sorbflow/solvers/results.py +318 -0
  40. sorbflow/uncertainty/__init__.py +5 -0
  41. sorbflow/uncertainty/monte_carlo.py +129 -0
  42. sorbflow/units.py +53 -0
  43. sorbflow/validate/__init__.py +35 -0
  44. sorbflow/web/__init__.py +5 -0
  45. sorbflow/web/__main__.py +6 -0
  46. sorbflow/web/app.py +278 -0
  47. sorbflow/web/config.py +213 -0
  48. sorbflow/web/server.py +302 -0
  49. sorbflow/web/ui.py +50 -0
  50. sorbflow-0.3.0.dist-info/METADATA +121 -0
  51. sorbflow-0.3.0.dist-info/RECORD +56 -0
  52. sorbflow-0.3.0.dist-info/WHEEL +5 -0
  53. sorbflow-0.3.0.dist-info/entry_points.txt +2 -0
  54. sorbflow-0.3.0.dist-info/licenses/LICENSE +202 -0
  55. sorbflow-0.3.0.dist-info/licenses/NOTICE +12 -0
  56. 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,5 @@
1
+ """Monte Carlo propagation and local sensitivity with explicit reproducibility."""
2
+
3
+ from .monte_carlo import MonteCarloResult, local_sensitivity, monte_carlo
4
+
5
+ __all__ = ["MonteCarloResult", "local_sensitivity", "monte_carlo"]
@@ -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)