mptool 1.2.0__tar.gz → 1.3.0__tar.gz
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-1.2.0 → mptool-1.3.0}/CHANGELOG.md +27 -0
- {mptool-1.2.0 → mptool-1.3.0}/CITATION.cff +2 -2
- {mptool-1.2.0 → mptool-1.3.0}/PKG-INFO +22 -1
- {mptool-1.2.0 → mptool-1.3.0}/README.md +21 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool/__init__.py +9 -2
- {mptool-1.2.0 → mptool-1.3.0}/mptool/consistency.py +364 -67
- {mptool-1.2.0 → mptool-1.3.0}/mptool.egg-info/PKG-INFO +22 -1
- {mptool-1.2.0 → mptool-1.3.0}/setup.cfg +1 -1
- {mptool-1.2.0 → mptool-1.3.0}/LICENSE +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/MANIFEST.in +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool/__main__.py +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool/fva.py +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool/io.py +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool/mapping.py +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool/model.py +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool/mps.py +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool/preprocess.py +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool/reproduce.py +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool/validate.py +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool.egg-info/SOURCES.txt +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool.egg-info/dependency_links.txt +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool.egg-info/requires.txt +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/mptool.egg-info/top_level.txt +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/pyproject.toml +0 -0
- {mptool-1.2.0 → mptool-1.3.0}/setup.py +0 -0
|
@@ -5,6 +5,33 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [1.3.0] — 2026-11-11
|
|
9
|
+
|
|
10
|
+
A minor release adding two functions. `is_consistent` checks whether
|
|
11
|
+
every reaction in a subset can carry flux and stops at the first one
|
|
12
|
+
it proves blocked. `require_consistent` builds on it a `requirements`
|
|
13
|
+
callback that keeps a set of reactions functional. On iML1515 and a
|
|
14
|
+
CarveMe universe, sampling with this callback returned the same MPs as a
|
|
15
|
+
plain fastercc callback in about 0.4 of the time per draw. Results of
|
|
16
|
+
existing functions are unchanged.
|
|
17
|
+
|
|
18
|
+
### Added
|
|
19
|
+
|
|
20
|
+
- `is_consistent(model, subset)` returns whether every reaction in `subset`
|
|
21
|
+
can carry non-zero flux. It answers as `fastercc(model, subset) == subset`
|
|
22
|
+
does, except possibly for a reaction whose maximum flux is below `epsilon`,
|
|
23
|
+
and it stops at the first reaction it proves blocked. An infeasible model
|
|
24
|
+
gives False, not an exception.
|
|
25
|
+
`return_zeros=True` also returns the reactions that carry no flux in any
|
|
26
|
+
solution the check read; deleting them all together leaves a True result
|
|
27
|
+
True.
|
|
28
|
+
- `require_consistent(subset)` returns a `requirements` callback for
|
|
29
|
+
`enumerate_mps` and `sample_mps` that keeps every reaction in `subset`
|
|
30
|
+
functional. It answers through `is_consistent` and returns its zero-flux
|
|
31
|
+
reactions, so the search can skip them without a solve. Like any
|
|
32
|
+
requirements callback it needs `preprocess=False`, with `subset` in the
|
|
33
|
+
preprocessed model's IDs.
|
|
34
|
+
|
|
8
35
|
## [1.2.0] — 2026-11-03
|
|
9
36
|
|
|
10
37
|
A minor release: `sample_mps` reports how many draws returned each MP and
|
|
@@ -3,8 +3,8 @@ message: "If you use this software, please cite both the software and the paper
|
|
|
3
3
|
title: mptool
|
|
4
4
|
abstract: Enumeration and sampling of minimal pathways in metabolic (sub)networks.
|
|
5
5
|
type: software
|
|
6
|
-
version: 1.
|
|
7
|
-
date-released: 2026-11-
|
|
6
|
+
version: 1.3.0
|
|
7
|
+
date-released: 2026-11-11
|
|
8
8
|
license: MIT
|
|
9
9
|
repository-code: "https://gitlab.com/csb.ethz/mptool"
|
|
10
10
|
url: "https://gitlab.com/csb.ethz/mptool"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: mptool
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.3.0
|
|
4
4
|
Summary: Enumeration and sampling of minimal pathways in metabolic (sub)networks.
|
|
5
5
|
Home-page: https://gitlab.com/csb.ethz/mptool
|
|
6
6
|
Author: Ove Øyås
|
|
@@ -368,6 +368,27 @@ Violate it and returned sets may not be support-minimal, and `chunks=None` and
|
|
|
368
368
|
`chunks=k` may disagree. There is no post-hoc remedy — checking every subset is
|
|
369
369
|
exponential.
|
|
370
370
|
|
|
371
|
+
### Keeping reactions functional: `require_consistent`
|
|
372
|
+
|
|
373
|
+
A common requirement is that a set of reactions must stay able to carry flux.
|
|
374
|
+
`require_consistent(ids)` builds that callback. It answers with
|
|
375
|
+
`is_consistent`, which runs fastercc's algorithm on the reactions in `ids` but
|
|
376
|
+
stops at the first reaction it proves blocked, and it returns the reactions
|
|
377
|
+
that had zero flux in every solution the check read, so mptool can delete
|
|
378
|
+
those without a solve. The criterion is monotone. The IDs are those of the
|
|
379
|
+
preprocessed model:
|
|
380
|
+
|
|
381
|
+
```python
|
|
382
|
+
pre, subset, _ = mpt.preprocess_model(model, subset=model.boundary,
|
|
383
|
+
compress=False)
|
|
384
|
+
core = ['PGI', 'PFK', 'GAPD'] # IDs of `pre`
|
|
385
|
+
mps, acceptance = mpt.sample_mps(
|
|
386
|
+
pre, subset=subset, preprocess=False, n_samples=10,
|
|
387
|
+
requirements=mpt.require_consistent(core))
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
A run with this callback cannot be exported (`export=`).
|
|
391
|
+
|
|
371
392
|
## Publications
|
|
372
393
|
|
|
373
394
|
### *Scalable enumeration and sampling of minimal metabolic pathways for organisms and communities*
|
|
@@ -330,6 +330,27 @@ Violate it and returned sets may not be support-minimal, and `chunks=None` and
|
|
|
330
330
|
`chunks=k` may disagree. There is no post-hoc remedy — checking every subset is
|
|
331
331
|
exponential.
|
|
332
332
|
|
|
333
|
+
### Keeping reactions functional: `require_consistent`
|
|
334
|
+
|
|
335
|
+
A common requirement is that a set of reactions must stay able to carry flux.
|
|
336
|
+
`require_consistent(ids)` builds that callback. It answers with
|
|
337
|
+
`is_consistent`, which runs fastercc's algorithm on the reactions in `ids` but
|
|
338
|
+
stops at the first reaction it proves blocked, and it returns the reactions
|
|
339
|
+
that had zero flux in every solution the check read, so mptool can delete
|
|
340
|
+
those without a solve. The criterion is monotone. The IDs are those of the
|
|
341
|
+
preprocessed model:
|
|
342
|
+
|
|
343
|
+
```python
|
|
344
|
+
pre, subset, _ = mpt.preprocess_model(model, subset=model.boundary,
|
|
345
|
+
compress=False)
|
|
346
|
+
core = ['PGI', 'PFK', 'GAPD'] # IDs of `pre`
|
|
347
|
+
mps, acceptance = mpt.sample_mps(
|
|
348
|
+
pre, subset=subset, preprocess=False, n_samples=10,
|
|
349
|
+
requirements=mpt.require_consistent(core))
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
A run with this callback cannot be exported (`export=`).
|
|
353
|
+
|
|
333
354
|
## Publications
|
|
334
355
|
|
|
335
356
|
### *Scalable enumeration and sampling of minimal metabolic pathways for organisms and communities*
|
|
@@ -59,6 +59,12 @@ Public functions::
|
|
|
59
59
|
flux-coupled reactions into single variables.
|
|
60
60
|
fastcc Identify flux-consistent reactions (fast version).
|
|
61
61
|
fastercc Identify flux-consistent reactions (faster).
|
|
62
|
+
is_consistent Whether every reaction in a subset can carry flux
|
|
63
|
+
(fastercc's algorithm, stopping at the first
|
|
64
|
+
blocked reaction); optionally the reactions with
|
|
65
|
+
zero flux in every solution it read.
|
|
66
|
+
require_consistent A ``requirements`` callback for enumerate_mps /
|
|
67
|
+
sample_mps that keeps a subset functional.
|
|
62
68
|
|
|
63
69
|
To apply FVA-tight bounds without compressing, run :func:`mptool.fva` and pass
|
|
64
70
|
the result to :func:`mptool.set_bounds`.
|
|
@@ -79,7 +85,8 @@ from .io import (load_cobra_model, load_cobra_models,
|
|
|
79
85
|
from .mapping import translate_mcs, translate_mps
|
|
80
86
|
from .model import create_lp, copy_model, make_forward_irreversible, set_bounds
|
|
81
87
|
from .fva import compress, fva
|
|
82
|
-
from .consistency import fastcc, fastercc
|
|
88
|
+
from .consistency import (fastcc, fastercc, is_consistent,
|
|
89
|
+
require_consistent)
|
|
83
90
|
from .preprocess import preprocess_model
|
|
84
91
|
from .mps import enumerate_mps, sample_mps
|
|
85
92
|
from .reproduce import rerun
|
|
@@ -102,7 +109,7 @@ __all__ = [
|
|
|
102
109
|
'load_mapping', 'save_mapping',
|
|
103
110
|
'load_weights',
|
|
104
111
|
'make_forward_irreversible', 'fva', 'compress',
|
|
105
|
-
'fastcc', 'fastercc',
|
|
112
|
+
'fastcc', 'fastercc', 'is_consistent', 'require_consistent',
|
|
106
113
|
'validate_mps', 'validate_solutions',
|
|
107
114
|
'translate_mps', 'translate_mcs',
|
|
108
115
|
'__version__',
|
|
@@ -1,7 +1,9 @@
|
|
|
1
|
-
"""Flux consistency analysis: fastcc and
|
|
1
|
+
"""Flux consistency analysis: fastcc, fastercc and the subset check built on
|
|
2
|
+
fastercc (:func:`is_consistent`, :func:`require_consistent`)."""
|
|
2
3
|
|
|
3
4
|
from warnings import warn
|
|
4
5
|
|
|
6
|
+
import cobra
|
|
5
7
|
import gurobipy as grb
|
|
6
8
|
import numpy as np
|
|
7
9
|
|
|
@@ -22,6 +24,11 @@ from .model import (
|
|
|
22
24
|
# path cannot silently become vacuous if solver defaults change.
|
|
23
25
|
_reset_retries = 0
|
|
24
26
|
|
|
27
|
+
# Count of LP solves made by this module (setup, first and second stage,
|
|
28
|
+
# reset retries). Private measurement hook, like ``_reset_retries``; it
|
|
29
|
+
# never changes what a solve does.
|
|
30
|
+
_lp_solves = 0
|
|
31
|
+
|
|
25
32
|
# Seed of fastercc's second-stage objective weights. Any fixed value
|
|
26
33
|
# works; fixing it makes fastercc deterministic.
|
|
27
34
|
_SECOND_STAGE_SEED = 20261102
|
|
@@ -32,7 +39,28 @@ def _reset_retry_count():
|
|
|
32
39
|
return _reset_retries
|
|
33
40
|
|
|
34
41
|
|
|
35
|
-
def
|
|
42
|
+
def _lp_solve_count():
|
|
43
|
+
"""Return the number of LP solves this module has made so far."""
|
|
44
|
+
return _lp_solves
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _optimize(model):
|
|
48
|
+
"""``model.optimize()``, counted in ``_lp_solves``."""
|
|
49
|
+
global _lp_solves
|
|
50
|
+
_lp_solves += 1
|
|
51
|
+
model.optimize()
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class _ProvenBlocked(Exception):
|
|
55
|
+
"""A subset reaction is proven blocked, or the model is infeasible.
|
|
56
|
+
|
|
57
|
+
Raised inside :func:`_fastercc_core` with ``check=True`` and caught by
|
|
58
|
+
:func:`is_consistent`; it never reaches a caller.
|
|
59
|
+
"""
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _fastcc_setup(model, subset, epsilon, flux_tol, threads, *,
|
|
63
|
+
check=False, warn_tol=True, stacklevel=3):
|
|
36
64
|
"""Shared pre-bulk-z setup for fastcc and fastercc.
|
|
37
65
|
|
|
38
66
|
Validates subset, warns on loose flux_tol, copies the caller's
|
|
@@ -52,6 +80,16 @@ def _fastcc_setup(model, subset, epsilon, flux_tol, threads):
|
|
|
52
80
|
flux_tol (float): zero threshold + solver FeasibilityTol /
|
|
53
81
|
OptimalityTol on the internal copy.
|
|
54
82
|
threads (int): Gurobi solver threads for the internal copy.
|
|
83
|
+
check (bool): Raise :class:`_ProvenBlocked` instead of going on
|
|
84
|
+
when a subset reaction has bounds (0, 0), and instead of
|
|
85
|
+
``RuntimeError`` when the feasibility solve reports the model
|
|
86
|
+
infeasible (INFEASIBLE or INF_OR_UNBD; the objective is zero,
|
|
87
|
+
so the latter cannot mean unbounded).
|
|
88
|
+
warn_tol (bool): Warn on a loose ``flux_tol``. False when the
|
|
89
|
+
caller has already warned (:func:`require_consistent` checks
|
|
90
|
+
once, when it is built, not on every call).
|
|
91
|
+
stacklevel (int): Frames between this helper and the user's call,
|
|
92
|
+
for the warnings.
|
|
55
93
|
|
|
56
94
|
Returns:
|
|
57
95
|
tuple: ``(model, subset, c, z_var, z_constr, mfi_orig)``.
|
|
@@ -64,21 +102,16 @@ def _fastcc_setup(model, subset, epsilon, flux_tol, threads):
|
|
|
64
102
|
added (empty if no MFI ran).
|
|
65
103
|
|
|
66
104
|
Raises:
|
|
67
|
-
RuntimeError: If the model is infeasible
|
|
105
|
+
RuntimeError: If the model is infeasible (with ``check=False``) or
|
|
106
|
+
the feasibility solve fails otherwise.
|
|
68
107
|
ValueError: If ``subset`` is an explicitly empty iterable.
|
|
108
|
+
_ProvenBlocked: See ``check``.
|
|
69
109
|
"""
|
|
70
110
|
if subset is not None and not subset:
|
|
71
111
|
raise ValueError('subset is empty; pass subset=None to use the full model')
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
_check_numeric('epsilon', epsilon, minimum=0, exclusive=True)
|
|
76
|
-
_check_numeric('flux_tol', flux_tol, minimum=0, exclusive=True)
|
|
77
|
-
_check_numeric('threads', threads, minimum=0, integer=True)
|
|
78
|
-
if flux_tol > 1e-9:
|
|
79
|
-
warn(f'flux_tol={flux_tol} is looser than the recommended default '
|
|
80
|
-
f'1e-9; this can misclassify reactions as blocked or '
|
|
81
|
-
f'functional.', UserWarning, stacklevel=3)
|
|
112
|
+
_check_args(epsilon, flux_tol, threads)
|
|
113
|
+
if warn_tol:
|
|
114
|
+
_warn_loose_flux_tol(flux_tol, stacklevel + 1)
|
|
82
115
|
model.update()
|
|
83
116
|
model = copy_model(model)
|
|
84
117
|
|
|
@@ -87,15 +120,24 @@ def _fastcc_setup(model, subset, epsilon, flux_tol, threads):
|
|
|
87
120
|
# model is never touched), so no save/restore is needed.
|
|
88
121
|
_set_solver_params(model, flux_tol, threads, 0)
|
|
89
122
|
|
|
90
|
-
model.optimize()
|
|
91
|
-
if model.status != grb.GRB.OPTIMAL:
|
|
92
|
-
raise RuntimeError(f'Infeasible model (status {model.status})')
|
|
93
|
-
|
|
94
123
|
if subset is None:
|
|
95
124
|
subset = set(model.getVars())
|
|
96
125
|
else:
|
|
97
126
|
subset = _resolve_subset_gurobi(
|
|
98
|
-
model, _subset_ids(model, subset, stacklevel=
|
|
127
|
+
model, _subset_ids(model, subset, stacklevel=stacklevel + 1),
|
|
128
|
+
stacklevel=stacklevel + 1)
|
|
129
|
+
|
|
130
|
+
# A reaction with bounds (0, 0) is blocked without a solve; fastercc
|
|
131
|
+
# reaches the same verdict after its second stage.
|
|
132
|
+
if check and any(v.lb == 0 and v.ub == 0 for v in subset):
|
|
133
|
+
raise _ProvenBlocked
|
|
134
|
+
|
|
135
|
+
_optimize(model)
|
|
136
|
+
if model.status != grb.GRB.OPTIMAL:
|
|
137
|
+
if check and model.status in (grb.GRB.INFEASIBLE,
|
|
138
|
+
grb.GRB.INF_OR_UNBD):
|
|
139
|
+
raise _ProvenBlocked
|
|
140
|
+
raise RuntimeError(f'Infeasible model (status {model.status})')
|
|
99
141
|
|
|
100
142
|
c = set(v for v in subset
|
|
101
143
|
if (v.lb == 0 and v.ub > 0) or (v.lb < 0 and v.ub == 0))
|
|
@@ -134,7 +176,28 @@ def _fastcc_setup(model, subset, epsilon, flux_tol, threads):
|
|
|
134
176
|
return model, subset, c, z_var, z_constr, mfi_orig
|
|
135
177
|
|
|
136
178
|
|
|
137
|
-
def
|
|
179
|
+
def _check_args(epsilon, flux_tol, threads):
|
|
180
|
+
"""The numeric argument checks shared by every function here."""
|
|
181
|
+
# epsilon is the z-var upper bound (the minimum flux magnitude counted as
|
|
182
|
+
# non-zero), so at 0 the bulk-z maximisation can never lift a reaction
|
|
183
|
+
# above the threshold and every candidate looks blocked.
|
|
184
|
+
_check_numeric('epsilon', epsilon, minimum=0, exclusive=True)
|
|
185
|
+
_check_numeric('flux_tol', flux_tol, minimum=0, exclusive=True)
|
|
186
|
+
_check_numeric('threads', threads, minimum=0, integer=True)
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def _warn_loose_flux_tol(flux_tol, stacklevel):
|
|
190
|
+
"""Warn when ``flux_tol`` is looser than the recommended 1e-9.
|
|
191
|
+
|
|
192
|
+
``stacklevel`` counts frames from this function to the user's call.
|
|
193
|
+
"""
|
|
194
|
+
if flux_tol > 1e-9:
|
|
195
|
+
warn(f'flux_tol={flux_tol} is looser than the recommended default '
|
|
196
|
+
f'1e-9; this can misclassify reactions as blocked or '
|
|
197
|
+
f'functional.', UserWarning, stacklevel=stacklevel)
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def _fastcc_bulk_z(model, subset, c, z_var, flux_tol, on_solve=None):
|
|
138
201
|
"""Shared bulk-z first-stage loop for fastcc and fastercc.
|
|
139
202
|
|
|
140
203
|
Each iteration maximises the sum of z-vars over the current ``c``
|
|
@@ -151,14 +214,19 @@ def _fastcc_bulk_z(model, subset, c, z_var, flux_tol):
|
|
|
151
214
|
forms agree. Non-c bidirectional subset vars carrying negative
|
|
152
215
|
flux are deferred to the second-stage passes in the callers,
|
|
153
216
|
which use ``abs(v.x)``.
|
|
217
|
+
|
|
218
|
+
``on_solve``, if given, is called after every optimal solve (the zero
|
|
219
|
+
report of :func:`is_consistent` reads each solution there).
|
|
154
220
|
"""
|
|
155
221
|
functional = set()
|
|
156
222
|
while c:
|
|
157
223
|
w = np.ones(len(c))
|
|
158
224
|
model.setObjective(grb.LinExpr(w, [z_var[v] for v in c]), -1)
|
|
159
|
-
model
|
|
225
|
+
_optimize(model)
|
|
160
226
|
if model.status != grb.GRB.OPTIMAL: # pragma: no cover - defensive
|
|
161
227
|
raise RuntimeError(f'Infeasible model (status {model.status})')
|
|
228
|
+
if on_solve is not None:
|
|
229
|
+
on_solve()
|
|
162
230
|
|
|
163
231
|
nz = set(v for v in subset if v.x > flux_tol)
|
|
164
232
|
functional |= nz
|
|
@@ -211,15 +279,124 @@ def _optimize_with_reset_retry(model):
|
|
|
211
279
|
observable test hook). Returns the model status after the
|
|
212
280
|
(possibly retried) solve; the caller decides whether to raise.
|
|
213
281
|
"""
|
|
214
|
-
model
|
|
282
|
+
_optimize(model)
|
|
215
283
|
if model.status != grb.GRB.OPTIMAL:
|
|
216
284
|
global _reset_retries
|
|
217
285
|
_reset_retries += 1
|
|
218
286
|
model.reset()
|
|
219
|
-
model
|
|
287
|
+
_optimize(model)
|
|
220
288
|
return model.status
|
|
221
289
|
|
|
222
290
|
|
|
291
|
+
def _fastercc_core(model, subset, epsilon, flux_tol, threads, *,
|
|
292
|
+
check=False, zeros=False, warn_tol=True, stacklevel=4):
|
|
293
|
+
"""fastercc's algorithm, shared by :func:`fastercc` and the checks.
|
|
294
|
+
|
|
295
|
+
With ``check=False`` this is fastercc. With ``check=True`` it raises
|
|
296
|
+
:class:`_ProvenBlocked` as soon as a subset reaction is proven blocked:
|
|
297
|
+
a subset reaction has bounds (0, 0); the feasibility solve reports the
|
|
298
|
+
model infeasible; the first stage ends on a solve that finds no new
|
|
299
|
+
functional reaction while ``|c|`` one-way candidates remain and
|
|
300
|
+
``|c| * flux_tol < epsilon``; or the second stage ends on two quiet
|
|
301
|
+
solves, one in each sense, for the same candidates. Otherwise both
|
|
302
|
+
stages run exactly as in fastercc, with the same solves.
|
|
303
|
+
|
|
304
|
+
With ``zeros=True``, every bulk-z and second-stage solution is read over
|
|
305
|
+
all of the model's own variables (not the z-variables), and the IDs that
|
|
306
|
+
stay at or below ``flux_tol`` in all of them are returned, in the input
|
|
307
|
+
model's namespace. The setup's feasibility solution is not read: it
|
|
308
|
+
certifies nothing.
|
|
309
|
+
|
|
310
|
+
Returns:
|
|
311
|
+
tuple: ``(functional, zero_ids)``: the functional IDs, as fastercc
|
|
312
|
+
returns them, and the zero IDs (``None`` with ``zeros=False``),
|
|
313
|
+
both in the input model's namespace. IDs, not Vars: the
|
|
314
|
+
internal copy is freed on return.
|
|
315
|
+
|
|
316
|
+
Raises:
|
|
317
|
+
_ProvenBlocked: With ``check=True``, see above.
|
|
318
|
+
RuntimeError, ValueError: As :func:`fastercc`.
|
|
319
|
+
"""
|
|
320
|
+
model, subset, c, z_var, z_constr, mfi_orig = _fastcc_setup(
|
|
321
|
+
model, subset, epsilon, flux_tol, threads, check=check,
|
|
322
|
+
warn_tol=warn_tol, stacklevel=stacklevel)
|
|
323
|
+
|
|
324
|
+
# The model's own columns come first: setup appended the z columns
|
|
325
|
+
# after them, so removing those later leaves these indices in place.
|
|
326
|
+
n = model.numVars - len(z_var)
|
|
327
|
+
track = model.getVars()[:n] if zeros else None
|
|
328
|
+
moved = np.zeros(n, dtype=bool) if zeros else None
|
|
329
|
+
|
|
330
|
+
def record():
|
|
331
|
+
moved[np.abs(model.getAttr('X', track)) > flux_tol] = True
|
|
332
|
+
|
|
333
|
+
functional = _fastcc_bulk_z(model, subset, c, z_var, flux_tol,
|
|
334
|
+
on_solve=record if zeros else None)
|
|
335
|
+
# The loop stops either with c empty or on a solve that found no new
|
|
336
|
+
# member of c. In that quiet solve every member of c carries at most
|
|
337
|
+
# flux_tol, so sum(z) <= |c| * flux_tol at the optimum, while a member
|
|
338
|
+
# able to carry flux a would make it at least min(a, epsilon). So
|
|
339
|
+
# min(a, epsilon) <= |c| * flux_tol for every leftover, which proves
|
|
340
|
+
# them blocked (up to a < epsilon; is_consistent's docstring) only when
|
|
341
|
+
# |c| * flux_tol < epsilon. Otherwise the leftovers go on to the second
|
|
342
|
+
# stage, as in fastercc.
|
|
343
|
+
if check and c and len(c) * flux_tol < epsilon:
|
|
344
|
+
raise _ProvenBlocked
|
|
345
|
+
|
|
346
|
+
_fastcc_cleanup_z(model, z_var, z_constr)
|
|
347
|
+
if zeros:
|
|
348
|
+
track = model.getVars()
|
|
349
|
+
|
|
350
|
+
c = subset - functional
|
|
351
|
+
# Random positive weights by column index, fixed for the call: a plain
|
|
352
|
+
# sum misses reactions whose fluxes cancel (DECISIONS.md 2026-11-02).
|
|
353
|
+
w = 1.0 + np.random.default_rng(_SECOND_STAGE_SEED).random(model.numVars)
|
|
354
|
+
sub = sorted(subset, key=lambda v: v.index)
|
|
355
|
+
sense = grb.GRB.MINIMIZE
|
|
356
|
+
quiet = 0 # consecutive solves that found nothing for the current c
|
|
357
|
+
|
|
358
|
+
# Keep the sense while it shrinks c, and switch on a quiet solve. A
|
|
359
|
+
# direction that found nothing is thus tried again after the other one
|
|
360
|
+
# has shrunk c: what it could not move before may be all that is left.
|
|
361
|
+
# Two quiet solves in a row are one of each sense for the same c, and
|
|
362
|
+
# then nothing in c can carry flux. (Switching after every solve is
|
|
363
|
+
# also exact but took 1.6-5x the time, in simplex iterations spent
|
|
364
|
+
# in the unproductive direction.)
|
|
365
|
+
while c and quiet < 2:
|
|
366
|
+
cs = sorted(c, key=lambda v: v.index)
|
|
367
|
+
model.setObjective(grb.LinExpr([w[v.index] for v in cs], cs), sense)
|
|
368
|
+
# Retry once after a cold restart: warm-start state can
|
|
369
|
+
# accumulate over this loop's many sense-flipping solves and
|
|
370
|
+
# yield a spurious non-OPTIMAL status on a feasible region.
|
|
371
|
+
if _optimize_with_reset_retry(model) != grb.GRB.OPTIMAL: # pragma: no cover - defensive
|
|
372
|
+
raise RuntimeError(
|
|
373
|
+
f'Infeasible model (status {model.status})')
|
|
374
|
+
|
|
375
|
+
if zeros:
|
|
376
|
+
x = np.abs(model.getAttr('X', track))
|
|
377
|
+
moved[x > flux_tol] = True
|
|
378
|
+
nz = {v for v in sub if x[v.index] > flux_tol}
|
|
379
|
+
else:
|
|
380
|
+
nz = {v for v, x in zip(sub, model.getAttr('X', sub))
|
|
381
|
+
if abs(x) > flux_tol}
|
|
382
|
+
functional |= nz
|
|
383
|
+
if nz & c:
|
|
384
|
+
c -= nz
|
|
385
|
+
quiet = 0
|
|
386
|
+
else:
|
|
387
|
+
quiet += 1
|
|
388
|
+
sense = -sense
|
|
389
|
+
|
|
390
|
+
if check and c:
|
|
391
|
+
raise _ProvenBlocked
|
|
392
|
+
|
|
393
|
+
zero_ids = None
|
|
394
|
+
if zeros:
|
|
395
|
+
zero_ids = {mfi_orig.get(v.varName, v.varName)
|
|
396
|
+
for v, m in zip(track, moved) if not m}
|
|
397
|
+
return _fastcc_translate(functional, mfi_orig), zero_ids
|
|
398
|
+
|
|
399
|
+
|
|
223
400
|
def fastcc(model, subset=None, epsilon=1e-6, flux_tol=1e-9, threads=0):
|
|
224
401
|
"""Fast consistency check (FASTCC): finds functional reactions in subset.
|
|
225
402
|
|
|
@@ -275,7 +452,7 @@ def fastcc(model, subset=None, epsilon=1e-6, flux_tol=1e-9, threads=0):
|
|
|
275
452
|
model.setObjective(v)
|
|
276
453
|
|
|
277
454
|
model.ModelSense = -1
|
|
278
|
-
model
|
|
455
|
+
_optimize(model)
|
|
279
456
|
if model.status != grb.GRB.OPTIMAL: # pragma: no cover - defensive
|
|
280
457
|
raise RuntimeError(f'Infeasible model (status {model.status})')
|
|
281
458
|
functional |= set(v for v in subset if abs(v.x) > flux_tol)
|
|
@@ -284,7 +461,7 @@ def fastcc(model, subset=None, epsilon=1e-6, flux_tol=1e-9, threads=0):
|
|
|
284
461
|
continue
|
|
285
462
|
|
|
286
463
|
model.ModelSense = 1
|
|
287
|
-
model
|
|
464
|
+
_optimize(model)
|
|
288
465
|
if model.status != grb.GRB.OPTIMAL: # pragma: no cover - defensive
|
|
289
466
|
raise RuntimeError(f'Infeasible model (status {model.status})')
|
|
290
467
|
functional |= set(v for v in subset if abs(v.x) > flux_tol)
|
|
@@ -342,52 +519,172 @@ def fastercc(model, subset=None, epsilon=1e-6, flux_tol=1e-9, threads=0):
|
|
|
342
519
|
``assert`` so the guard survives ``python -O``).
|
|
343
520
|
ValueError: If ``subset`` is an explicitly empty iterable.
|
|
344
521
|
"""
|
|
345
|
-
model, subset,
|
|
346
|
-
|
|
522
|
+
functional, _ = _fastercc_core(model, subset, epsilon, flux_tol, threads)
|
|
523
|
+
return functional
|
|
347
524
|
|
|
348
|
-
functional = _fastcc_bulk_z(model, subset, c, z_var, flux_tol)
|
|
349
|
-
# Anything still in c after the bulk-z loop is not yet proven blocked;
|
|
350
|
-
# the bulk LP can leave functional reactions at zero in a degenerate
|
|
351
|
-
# optimum (e.g. when a post-MFI model contains both X and X_rev as
|
|
352
|
-
# separate forward-only vars — only one can carry flux in any single
|
|
353
|
-
# steady state). Those leftovers flow into the directional
|
|
354
|
-
# second-stage pass via ``subset - functional``.
|
|
355
525
|
|
|
356
|
-
|
|
526
|
+
def is_consistent(model, subset=None, epsilon=1e-6, flux_tol=1e-9, threads=0,
|
|
527
|
+
return_zeros=False):
|
|
528
|
+
"""Whether every reaction in subset can carry non-zero flux.
|
|
529
|
+
|
|
530
|
+
The answer is ``fastercc(model, subset) == subset``, found with
|
|
531
|
+
fastercc's algorithm, but the check stops as soon as a blocked subset
|
|
532
|
+
reaction is proven:
|
|
533
|
+
|
|
534
|
+
- a subset reaction has bounds (0, 0) (no solve);
|
|
535
|
+
- the model is infeasible;
|
|
536
|
+
- in the first stage, the first solve that finds no new functional
|
|
537
|
+
reaction among the ``|c|`` remaining one-way subset reactions
|
|
538
|
+
(exactly one bound zero) proves them all blocked, provided
|
|
539
|
+
``|c| * flux_tol < epsilon`` (fewer than 1 000 at the defaults);
|
|
540
|
+
with more, they go on to the second stage, as in fastercc;
|
|
541
|
+
- in the second stage, the first pair of quiet solves, one in each
|
|
542
|
+
sense, for the same remaining set.
|
|
543
|
+
|
|
544
|
+
It returns True only when every subset reaction carries flux above
|
|
545
|
+
``flux_tol`` in one of the solutions it read. An accepted check thus
|
|
546
|
+
makes the same solves as :func:`fastercc`; a rejected one makes fewer.
|
|
547
|
+
Only the subset is checked, as with ``fastercc(model, subset)``.
|
|
548
|
+
|
|
549
|
+
The first-stage rule leaves a tolerance band. In a quiet bulk solve
|
|
550
|
+
every remaining one-way candidate carries at most ``flux_tol``, so the
|
|
551
|
+
bulk optimum is at most ``|c| * flux_tol``, while a candidate able to
|
|
552
|
+
carry flux ``a`` would make it at least ``min(a, epsilon)``. So
|
|
553
|
+
``min(a, epsilon) <= |c| * flux_tol`` for each, and when
|
|
554
|
+
``|c| * flux_tol < epsilon`` (the only case in which the check stops
|
|
555
|
+
there) every remaining candidate has ``a <= |c| * flux_tol < epsilon``.
|
|
556
|
+
fastercc hands such candidates to its second stage, which can still
|
|
557
|
+
find a flux above ``flux_tol`` in one of them; this check calls it
|
|
558
|
+
blocked. So the two can disagree only on a reaction whose maximum flux
|
|
559
|
+
is below ``epsilon``.
|
|
357
560
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
# sum misses reactions whose fluxes cancel (DECISIONS.md 2026-11-02).
|
|
361
|
-
w = 1.0 + np.random.default_rng(_SECOND_STAGE_SEED).random(model.numVars)
|
|
362
|
-
sub = sorted(subset, key=lambda v: v.index)
|
|
363
|
-
sense = grb.GRB.MINIMIZE
|
|
364
|
-
quiet = 0 # consecutive solves that found nothing for the current c
|
|
561
|
+
Operates on an internal copy of the model; the caller's model and
|
|
562
|
+
variables are not mutated.
|
|
365
563
|
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
564
|
+
Args:
|
|
565
|
+
model (gurobipy.Model): Gurobi model to use.
|
|
566
|
+
subset (Iterable, optional): Reactions to check. Can be given as
|
|
567
|
+
reaction IDs, Gurobi variables, or COBRA reactions. ``None``
|
|
568
|
+
(the default) means all reactions in the model. An explicitly
|
|
569
|
+
empty iterable raises ``ValueError``. IDs that name no reaction
|
|
570
|
+
of ``model`` are ignored with a ``UserWarning`` that names them;
|
|
571
|
+
if none does, ``ValueError``.
|
|
572
|
+
epsilon (float, optional): Minimum flux magnitude considered non-zero.
|
|
573
|
+
Defaults to 1e-6.
|
|
574
|
+
flux_tol (float, optional): Threshold below which a flux value is
|
|
575
|
+
considered zero; also sets the solver's FeasibilityTol and
|
|
576
|
+
OptimalityTol. Defaults to 1e-9.
|
|
577
|
+
threads (int, optional): Gurobi solver threads. Defaults to 0
|
|
578
|
+
(auto). Applied to the internal model copy, not to the
|
|
579
|
+
caller's model.
|
|
580
|
+
return_zeros (bool, optional): Also return the IDs of the model's
|
|
581
|
+
reactions (all of them, not only the subset's) that carry no
|
|
582
|
+
flux above ``flux_tol`` in any LP solution the check read.
|
|
583
|
+
Meaningful only when the result is True: then every subset
|
|
584
|
+
reaction keeps the solution that certified it when all of these
|
|
585
|
+
reactions are deleted together, so the result stays True. With
|
|
586
|
+
a False result the set is empty. Defaults to False.
|
|
382
587
|
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
c -= nz
|
|
388
|
-
quiet = 0
|
|
389
|
-
else:
|
|
390
|
-
quiet += 1
|
|
391
|
-
sense = -sense
|
|
588
|
+
Returns:
|
|
589
|
+
bool | tuple: True if every subset reaction is functional, False
|
|
590
|
+
if one is blocked or the model is infeasible. With
|
|
591
|
+
``return_zeros=True``, ``(result, zero_ids)``.
|
|
392
592
|
|
|
393
|
-
|
|
593
|
+
Raises:
|
|
594
|
+
RuntimeError: If an LP solve after the feasibility solve fails to
|
|
595
|
+
reach optimal status (a solver failure, not a property of the
|
|
596
|
+
model).
|
|
597
|
+
ValueError: If ``subset`` is an explicitly empty iterable, names no
|
|
598
|
+
reaction of ``model``, or a numeric argument is invalid.
|
|
599
|
+
"""
|
|
600
|
+
try:
|
|
601
|
+
_, zero_ids = _fastercc_core(
|
|
602
|
+
model, subset, epsilon, flux_tol, threads, check=True,
|
|
603
|
+
zeros=return_zeros)
|
|
604
|
+
except _ProvenBlocked:
|
|
605
|
+
return (False, set()) if return_zeros else False
|
|
606
|
+
return (True, zero_ids) if return_zeros else True
|
|
607
|
+
|
|
608
|
+
|
|
609
|
+
def require_consistent(subset, epsilon=1e-6, flux_tol=1e-9, threads=0):
|
|
610
|
+
"""A ``requirements`` callback that keeps every subset reaction functional.
|
|
611
|
+
|
|
612
|
+
For the ``requirements`` argument of :func:`mptool.enumerate_mps` and
|
|
613
|
+
:func:`mptool.sample_mps`: a set of reactions passes only if every
|
|
614
|
+
reaction in ``subset`` can still carry non-zero flux. The callback
|
|
615
|
+
answers with :func:`is_consistent` on the model copy it receives and
|
|
616
|
+
returns ``(result, zero_ids)``, so mptool can skip, without a solve,
|
|
617
|
+
reactions that carry no flux in the check's solutions or in its own LP.
|
|
618
|
+
The criterion is monotone: deleting more reactions only shrinks the
|
|
619
|
+
feasible region, so it cannot make a blocked reaction functional again.
|
|
620
|
+
|
|
621
|
+
Requirements need ``preprocess=False``: preprocess the model with
|
|
622
|
+
:func:`mptool.preprocess_model` and pass its output. The IDs in
|
|
623
|
+
``subset`` are therefore IDs of that preprocessed model (``_rev``
|
|
624
|
+
halves, merged names with ``compress=True``), not of the original one.
|
|
625
|
+
A subset reaction that may be in the MP subset as well is allowed:
|
|
626
|
+
once it is deleted its bounds are (0, 0) and the check fails without a
|
|
627
|
+
solve.
|
|
628
|
+
|
|
629
|
+
Each call copies the model and runs fastercc's LPs on the copy, so a
|
|
630
|
+
callback call costs about one fastercc call on the subset. A run that
|
|
631
|
+
uses this callback cannot be exported (``export=``): the callback is a
|
|
632
|
+
closure, which the export bundle cannot record.
|
|
633
|
+
|
|
634
|
+
Args:
|
|
635
|
+
subset (Iterable, optional): Reactions to keep functional, as IDs,
|
|
636
|
+
Gurobi variables or COBRA reactions; stored as IDs. ``None``
|
|
637
|
+
means every reaction of the model the callback receives. An
|
|
638
|
+
explicitly empty iterable raises ``ValueError``.
|
|
639
|
+
epsilon (float, optional): As in :func:`is_consistent`.
|
|
640
|
+
Defaults to 1e-6.
|
|
641
|
+
flux_tol (float, optional): As in :func:`is_consistent`. Checked,
|
|
642
|
+
and warned about if loose, once here, not on every call.
|
|
643
|
+
Defaults to 1e-9.
|
|
644
|
+
threads (int, optional): Gurobi threads for each check. Defaults
|
|
645
|
+
to 0 (auto).
|
|
646
|
+
|
|
647
|
+
Returns:
|
|
648
|
+
callable: ``requirements(model) -> (bool, set[str])``.
|
|
649
|
+
|
|
650
|
+
Raises:
|
|
651
|
+
ValueError: If ``subset`` is empty or a numeric argument is invalid.
|
|
652
|
+
|
|
653
|
+
Example::
|
|
654
|
+
|
|
655
|
+
model, subset, _ = mpt.preprocess_model(cobra_model, subset,
|
|
656
|
+
compress=False)
|
|
657
|
+
mps, acceptance = mpt.sample_mps(
|
|
658
|
+
model, subset, preprocess=False, n_samples=10,
|
|
659
|
+
requirements=mpt.require_consistent(core_ids))
|
|
660
|
+
"""
|
|
661
|
+
ids = None
|
|
662
|
+
if subset is not None:
|
|
663
|
+
ids = set()
|
|
664
|
+
for x in subset:
|
|
665
|
+
if isinstance(x, grb.Var):
|
|
666
|
+
ids.add(x.varName)
|
|
667
|
+
elif isinstance(x, cobra.Reaction):
|
|
668
|
+
ids.add(x.id)
|
|
669
|
+
elif isinstance(x, str):
|
|
670
|
+
ids.add(x)
|
|
671
|
+
else:
|
|
672
|
+
warn('Subset can only contain strings, variables or reactions',
|
|
673
|
+
stacklevel=2)
|
|
674
|
+
if not ids:
|
|
675
|
+
raise ValueError('subset is empty; pass subset=None to require '
|
|
676
|
+
'every reaction of the model')
|
|
677
|
+
ids = frozenset(ids)
|
|
678
|
+
_check_args(epsilon, flux_tol, threads)
|
|
679
|
+
_warn_loose_flux_tol(flux_tol, 2)
|
|
680
|
+
|
|
681
|
+
def requirements(model):
|
|
682
|
+
try:
|
|
683
|
+
_, zero_ids = _fastercc_core(
|
|
684
|
+
model, ids, epsilon, flux_tol, threads, check=True,
|
|
685
|
+
zeros=True, warn_tol=False, stacklevel=3)
|
|
686
|
+
except _ProvenBlocked:
|
|
687
|
+
return False, set()
|
|
688
|
+
return True, zero_ids
|
|
689
|
+
|
|
690
|
+
return requirements
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: mptool
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.3.0
|
|
4
4
|
Summary: Enumeration and sampling of minimal pathways in metabolic (sub)networks.
|
|
5
5
|
Home-page: https://gitlab.com/csb.ethz/mptool
|
|
6
6
|
Author: Ove Øyås
|
|
@@ -368,6 +368,27 @@ Violate it and returned sets may not be support-minimal, and `chunks=None` and
|
|
|
368
368
|
`chunks=k` may disagree. There is no post-hoc remedy — checking every subset is
|
|
369
369
|
exponential.
|
|
370
370
|
|
|
371
|
+
### Keeping reactions functional: `require_consistent`
|
|
372
|
+
|
|
373
|
+
A common requirement is that a set of reactions must stay able to carry flux.
|
|
374
|
+
`require_consistent(ids)` builds that callback. It answers with
|
|
375
|
+
`is_consistent`, which runs fastercc's algorithm on the reactions in `ids` but
|
|
376
|
+
stops at the first reaction it proves blocked, and it returns the reactions
|
|
377
|
+
that had zero flux in every solution the check read, so mptool can delete
|
|
378
|
+
those without a solve. The criterion is monotone. The IDs are those of the
|
|
379
|
+
preprocessed model:
|
|
380
|
+
|
|
381
|
+
```python
|
|
382
|
+
pre, subset, _ = mpt.preprocess_model(model, subset=model.boundary,
|
|
383
|
+
compress=False)
|
|
384
|
+
core = ['PGI', 'PFK', 'GAPD'] # IDs of `pre`
|
|
385
|
+
mps, acceptance = mpt.sample_mps(
|
|
386
|
+
pre, subset=subset, preprocess=False, n_samples=10,
|
|
387
|
+
requirements=mpt.require_consistent(core))
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
A run with this callback cannot be exported (`export=`).
|
|
391
|
+
|
|
371
392
|
## Publications
|
|
372
393
|
|
|
373
394
|
### *Scalable enumeration and sampling of minimal metabolic pathways for organisms and communities*
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|