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/__init__.py +107 -0
- mptool/__main__.py +430 -0
- mptool/consistency.py +365 -0
- mptool/fva.py +1207 -0
- mptool/io.py +289 -0
- mptool/mapping.py +237 -0
- mptool/model.py +636 -0
- mptool/mps.py +2793 -0
- mptool/preprocess.py +389 -0
- mptool/reproduce.py +361 -0
- mptool/validate.py +284 -0
- mptool-1.0.0.dist-info/METADATA +399 -0
- mptool-1.0.0.dist-info/RECORD +17 -0
- mptool-1.0.0.dist-info/WHEEL +5 -0
- mptool-1.0.0.dist-info/licenses/LICENSE +21 -0
- mptool-1.0.0.dist-info/top_level.txt +1 -0
- mptool-1.0.0.dist-info/zip-safe +1 -0
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)
|