mptool 1.0.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.
mptool/consistency.py ADDED
@@ -0,0 +1,365 @@
1
+ """Flux consistency analysis: fastcc and fastercc."""
2
+
3
+ from warnings import warn
4
+
5
+ import gurobipy as grb
6
+ import numpy as np
7
+
8
+ from .model import (
9
+ _check_numeric,
10
+ _is_forward_irreversible,
11
+ _resolve_subset_gurobi,
12
+ _set_solver_params,
13
+ copy_model,
14
+ make_forward_irreversible,
15
+ )
16
+
17
+ # Count of warm-start reset retries performed by
18
+ # :func:`_optimize_with_reset_retry`. Observable test hook: a spurious
19
+ # status-3 in fastercc's second-stage loop is recovered by a single
20
+ # cold re-solve, and tests assert this counter incremented so the retry
21
+ # path cannot silently become vacuous if solver defaults change.
22
+ _reset_retries = 0
23
+
24
+
25
+ def _reset_retry_count():
26
+ """Return the number of warm-start reset retries performed so far."""
27
+ return _reset_retries
28
+
29
+
30
+ def _fastcc_setup(model, subset, epsilon, flux_tol, threads):
31
+ """Shared pre-bulk-z setup for fastcc and fastercc.
32
+
33
+ Validates subset, warns on loose flux_tol, copies the caller's
34
+ model, sets solver params on the copy, runs a feasibility solve,
35
+ resolves the subset to Gurobi Vars, picks the candidate set ``c``
36
+ (forward-only or backward-only reactions in subset), runs
37
+ :func:`make_forward_irreversible` on ``c`` if any backward-only
38
+ members are present, and builds the z-var / z-constraint dicts.
39
+
40
+ Args:
41
+ model (gurobipy.Model): caller's model — not mutated; the
42
+ returned ``model`` is an internal copy.
43
+ subset (Iterable | None): user subset as passed to fastcc /
44
+ fastercc. ``None`` means the full model.
45
+ epsilon (float): minimum flux magnitude considered non-zero
46
+ (z-var upper bound).
47
+ flux_tol (float): zero threshold + solver FeasibilityTol /
48
+ OptimalityTol on the internal copy.
49
+ threads (int): Gurobi solver threads for the internal copy.
50
+
51
+ Returns:
52
+ tuple: ``(model, subset, c, z_var, z_constr, mfi_orig)``.
53
+ ``model`` is the internal copy with params set and
54
+ feasibility-checked; ``subset`` is a set of Vars on that
55
+ copy; ``c`` is the candidate Var set (forward-only
56
+ post-MFI); ``z_var`` / ``z_constr`` map each ``c``-var to
57
+ its auxiliary z-var / z-constraint; ``mfi_orig`` is a
58
+ post-MFI-name → original-name dict for the rev vars MFI
59
+ added (empty if no MFI ran).
60
+
61
+ Raises:
62
+ RuntimeError: If the model is infeasible.
63
+ ValueError: If ``subset`` is an explicitly empty iterable.
64
+ """
65
+ if subset is not None and not subset:
66
+ raise ValueError('subset is empty; pass subset=None to use the full model')
67
+ # epsilon is the z-var upper bound (the minimum flux magnitude counted as
68
+ # non-zero), so at 0 the bulk-z maximisation can never lift a reaction
69
+ # above the threshold and every candidate looks blocked.
70
+ _check_numeric('epsilon', epsilon, minimum=0, exclusive=True)
71
+ _check_numeric('flux_tol', flux_tol, minimum=0, exclusive=True)
72
+ _check_numeric('threads', threads, minimum=0, integer=True)
73
+ if flux_tol > 1e-9:
74
+ warn(f'flux_tol={flux_tol} is looser than the recommended default '
75
+ f'1e-9; this can misclassify reactions as blocked or '
76
+ f'functional.', UserWarning, stacklevel=3)
77
+ model.update()
78
+ model = copy_model(model)
79
+
80
+ model.setObjective(grb.LinExpr())
81
+ # _set_solver_params applies to the internal copy (the caller's
82
+ # model is never touched), so no save/restore is needed.
83
+ _set_solver_params(model, flux_tol, threads, 0)
84
+
85
+ model.optimize()
86
+ if model.status != grb.GRB.OPTIMAL:
87
+ raise RuntimeError(f'Infeasible model (status {model.status})')
88
+
89
+ if subset is None:
90
+ subset = set(model.getVars())
91
+ else:
92
+ subset = _resolve_subset_gurobi(model, subset)
93
+
94
+ c = set(v for v in subset
95
+ if (v.lb == 0 and v.ub > 0) or (v.lb < 0 and v.ub == 0))
96
+
97
+ mfi_orig = {}
98
+ if c and not _is_forward_irreversible(model, subset=c):
99
+ c, mfi_map = make_forward_irreversible(model, subset=c)
100
+ # post → original name for every reaction this MFI invocation
101
+ # actually added (non-identity entries; the post-MFI key has a
102
+ # single-entry value whose key is the original name). Looking
103
+ # up by name rather than stripping a hardcoded suffix keeps the
104
+ # strip step suffix-agnostic — if make_forward_irreversible's
105
+ # ``suffix=`` ever changes, no breakage here. A caller passing
106
+ # in a model that already contains suffix-named forward-only
107
+ # vars (e.g. preprocess_model output) is unaffected: those vars
108
+ # have identity mfi_map entries and don't appear in mfi_orig.
109
+ mfi_orig = {post: next(iter(m)) for post, m in mfi_map.items()
110
+ if post not in m}
111
+
112
+ # Column/row assignment must not depend on set iteration order: `c` is a
113
+ # set whose insertion order derives from a process-dependent string set,
114
+ # and these comprehensions create one variable and one constraint per
115
+ # member. Sorting by `v.index` gives the `_z` columns and their coupling
116
+ # rows a stable layout across processes. (The dicts themselves stay
117
+ # keyed by Var, so every lookup below is unaffected.)
118
+ _c_ordered = sorted(c, key=lambda v: v.index)
119
+
120
+ z_var = {v: model.addVar(0, epsilon, 1, 'continuous', v.varName + '_z')
121
+ for v in _c_ordered}
122
+ model.update()
123
+
124
+ z_constr = {v: model.addConstr(grb.LinExpr([(1, v), (-1, z_var[v])]) >= 0)
125
+ for v in _c_ordered}
126
+ model.update()
127
+
128
+ return model, subset, c, z_var, z_constr, mfi_orig
129
+
130
+
131
+ def _fastcc_bulk_z(model, subset, c, z_var, flux_tol):
132
+ """Shared bulk-z first-stage loop for fastcc and fastercc.
133
+
134
+ Each iteration maximises the sum of z-vars over the current ``c``
135
+ members. Any subset var observed above ``flux_tol`` joins the
136
+ functional set; ``c`` shrinks to exclude newly-found
137
+ functional members. Loop exits when an iteration adds no new
138
+ member of ``c`` to the functional set.
139
+
140
+ Mutates ``c`` in place. Returns the accumulated functional set
141
+ (Gurobi Var instances, post-MFI namespace).
142
+
143
+ The ``v.x > flux_tol`` (not ``abs(v.x) > flux_tol``) check is
144
+ exact: ``c`` is forward-only post-MFI, so for c-members the two
145
+ forms agree. Non-c bidirectional subset vars carrying negative
146
+ flux are deferred to the second-stage passes in the callers,
147
+ which use ``abs(v.x)``.
148
+ """
149
+ functional = set()
150
+ while c:
151
+ w = np.ones(len(c))
152
+ model.setObjective(grb.LinExpr(w, [z_var[v] for v in c]), -1)
153
+ model.optimize()
154
+ if model.status != grb.GRB.OPTIMAL: # pragma: no cover - defensive
155
+ raise RuntimeError(f'Infeasible model (status {model.status})')
156
+
157
+ nz = set(v for v in subset if v.x > flux_tol)
158
+ functional |= nz
159
+
160
+ if not nz & c:
161
+ break
162
+ c -= nz
163
+
164
+ return functional
165
+
166
+
167
+ def _fastcc_cleanup_z(model, z_var, z_constr):
168
+ """Remove z-vars and z-constraints from the model and flush.
169
+
170
+ Called by fastcc / fastercc between the bulk-z stage and the
171
+ second-stage directional probe so the latter sees only the
172
+ original LP structure.
173
+ """
174
+ model.remove(list(z_constr.values()))
175
+ model.remove(list(z_var.values()))
176
+ model.update()
177
+
178
+
179
+ def _fastcc_translate(functional, mfi_orig):
180
+ """Convert a post-MFI Var set to original-namespace ID strings.
181
+
182
+ Identity entries (forward-only originals) pass through unchanged;
183
+ MFI-added rev vars map back to their original names via
184
+ ``mfi_orig``. Suffix-agnostic by construction (the lookup uses
185
+ the dict ``mfi_orig`` built in :func:`_fastcc_setup`, not a
186
+ hardcoded suffix strip).
187
+ """
188
+ return {mfi_orig.get(v.varName, v.varName) for v in functional}
189
+
190
+
191
+ def _optimize_with_reset_retry(model):
192
+ """Optimize ``model``, retrying once after a cold restart if needed.
193
+
194
+ fastercc's second-stage loop issues many warm-started solves on the
195
+ same model while flipping the objective sense over a large, highly
196
+ degenerate objective. This can drive Gurobi's incremental simplex
197
+ state into a spurious INFEASIBLE result on a region that is in fact
198
+ feasible (the model written out at that point reloads and solves as
199
+ feasible). A single :meth:`model.reset` clears the warm-start basis
200
+ so a cold re-solve reports the true status. ``reset`` affects
201
+ solution state only — no tolerance or parameter is changed.
202
+
203
+ On a non-OPTIMAL first solve, resets and re-optimizes once, and
204
+ increments the module-level ``_reset_retries`` counter (an
205
+ observable test hook). Returns the model status after the
206
+ (possibly retried) solve; the caller decides whether to raise.
207
+ """
208
+ model.optimize()
209
+ if model.status != grb.GRB.OPTIMAL:
210
+ global _reset_retries
211
+ _reset_retries += 1
212
+ model.reset()
213
+ model.optimize()
214
+ return model.status
215
+
216
+
217
+ def fastcc(model, subset=None, epsilon=1e-6, flux_tol=1e-9, threads=0):
218
+ """Fast consistency check (FASTCC): finds functional reactions in subset.
219
+
220
+ A reaction is functional if it can carry non-zero flux. The algorithm
221
+ uses LP maximization of pseudo-indicator variables to identify functional
222
+ reactions in bulk, then checks remaining reversible reactions individually.
223
+
224
+ Operates on an internal copy of the model; the caller's model and
225
+ variables are not mutated.
226
+
227
+ Args:
228
+ model (gurobipy.Model): Gurobi model to use.
229
+ subset (Iterable, optional): Reactions to analyze. Can be given as
230
+ reaction IDs, Gurobi variables, or COBRA reactions. ``None``
231
+ (the default) means all reactions in the model. An explicitly
232
+ empty iterable raises ``ValueError``.
233
+ epsilon (float, optional): Minimum flux magnitude considered non-zero.
234
+ Defaults to 1e-6.
235
+ flux_tol (float, optional): Threshold below which a flux value is
236
+ considered zero; also sets the solver's FeasibilityTol and
237
+ OptimalityTol. Defaults to 1e-9.
238
+ threads (int, optional): Gurobi solver threads. Defaults to 0
239
+ (auto). Applied to the internal model copy, not to the
240
+ caller's model.
241
+
242
+ Returns:
243
+ set: Reaction IDs of functional reactions in subset.
244
+
245
+ Raises:
246
+ RuntimeError: If the model is infeasible, or any LP solve fails
247
+ to reach optimal status (uses an explicit raise rather than
248
+ ``assert`` so the guard survives ``python -O``).
249
+ ValueError: If ``subset`` is an explicitly empty iterable.
250
+ """
251
+ model, subset, c, z_var, z_constr, mfi_orig = _fastcc_setup(
252
+ model, subset, epsilon, flux_tol, threads)
253
+
254
+ functional = _fastcc_bulk_z(model, subset, c, z_var, flux_tol)
255
+ # fastcc trusts the bulk-z pass to identify blocked vars: anything
256
+ # still in c after the loop is taken as blocked and skipped in the
257
+ # second-stage probe. (fastercc disagrees — see its comment.)
258
+ blocked = set(c)
259
+
260
+ _fastcc_cleanup_z(model, z_var, z_constr)
261
+
262
+ # Second-stage: one-at-a-time directional probe of remaining vars.
263
+ c = subset - functional - blocked
264
+
265
+ while c:
266
+ v = c.pop()
267
+ model.setObjective(v)
268
+
269
+ model.ModelSense = -1
270
+ model.optimize()
271
+ if model.status != grb.GRB.OPTIMAL: # pragma: no cover - defensive
272
+ raise RuntimeError(f'Infeasible model (status {model.status})')
273
+ functional |= set(v for v in subset if abs(v.x) > flux_tol)
274
+ if abs(v.x) > flux_tol:
275
+ c -= functional
276
+ continue
277
+
278
+ model.ModelSense = 1
279
+ model.optimize()
280
+ if model.status != grb.GRB.OPTIMAL: # pragma: no cover - defensive
281
+ raise RuntimeError(f'Infeasible model (status {model.status})')
282
+ functional |= set(v for v in subset if abs(v.x) > flux_tol)
283
+ if abs(v.x) > flux_tol:
284
+ functional.add(v)
285
+
286
+ c -= functional
287
+
288
+ return _fastcc_translate(functional, mfi_orig)
289
+
290
+
291
+ def fastercc(model, subset=None, epsilon=1e-6, flux_tol=1e-9, threads=0):
292
+ """Faster variant of FASTCC: finds functional reactions in subset.
293
+
294
+ Like ``fastcc`` but handles remaining reversible candidates in bulk
295
+ using simultaneous minimization and maximization passes rather than
296
+ testing one reaction at a time.
297
+
298
+ Operates on an internal copy of the model; the caller's model and
299
+ variables are not mutated.
300
+
301
+ Args:
302
+ model (gurobipy.Model): Gurobi model to use.
303
+ subset (Iterable, optional): Reactions to analyze. Can be given as
304
+ reaction IDs, Gurobi variables, or COBRA reactions. ``None``
305
+ (the default) means all reactions in the model. An explicitly
306
+ empty iterable raises ``ValueError``.
307
+ epsilon (float, optional): Minimum flux magnitude considered non-zero.
308
+ Defaults to 1e-6.
309
+ flux_tol (float, optional): Threshold below which a flux value is
310
+ considered zero; also sets the solver's FeasibilityTol and
311
+ OptimalityTol. Defaults to 1e-9.
312
+ threads (int, optional): Gurobi solver threads. Defaults to 0
313
+ (auto). Applied to the internal model copy, not to the
314
+ caller's model.
315
+
316
+ Returns:
317
+ set: Reaction IDs of functional reactions in subset.
318
+
319
+ Raises:
320
+ RuntimeError: If the model is infeasible, or any LP solve fails
321
+ to reach optimal status (uses an explicit raise rather than
322
+ ``assert`` so the guard survives ``python -O``).
323
+ ValueError: If ``subset`` is an explicitly empty iterable.
324
+ """
325
+ model, subset, c, z_var, z_constr, mfi_orig = _fastcc_setup(
326
+ model, subset, epsilon, flux_tol, threads)
327
+
328
+ functional = _fastcc_bulk_z(model, subset, c, z_var, flux_tol)
329
+ # Anything still in c after the bulk-z loop is not yet proven blocked;
330
+ # the bulk LP can leave functional reactions at zero in a degenerate
331
+ # optimum (e.g. when a post-MFI model contains both X and X_rev as
332
+ # separate forward-only vars — only one can carry flux in any single
333
+ # steady state). Those leftovers flow into the directional
334
+ # second-stage pass via ``subset - functional``.
335
+
336
+ _fastcc_cleanup_z(model, z_var, z_constr)
337
+
338
+ c = subset - functional
339
+ directions = {-1, 1}
340
+
341
+ while c:
342
+ nz = set()
343
+ for i in list(directions):
344
+ w = np.ones(len(c))
345
+ model.setObjective(grb.LinExpr(w, list(c)), i)
346
+ # Retry once after a cold restart: warm-start state can
347
+ # accumulate over this loop's many sense-flipping solves and
348
+ # yield a spurious non-OPTIMAL status on a feasible region.
349
+ if _optimize_with_reset_retry(model) != grb.GRB.OPTIMAL: # pragma: no cover - defensive
350
+ raise RuntimeError(
351
+ f'Infeasible model (status {model.status})')
352
+
353
+ nz |= set(v for v in subset if abs(v.x) > flux_tol)
354
+
355
+ if not nz & c:
356
+ directions.discard(i)
357
+ continue
358
+ c -= nz
359
+
360
+ functional |= nz
361
+
362
+ if not directions:
363
+ break
364
+
365
+ return _fastcc_translate(functional, mfi_orig)