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.
@@ -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.2.0
7
- date-released: 2026-11-03
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.2.0
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 fastercc."""
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 _fastcc_setup(model, subset, epsilon, flux_tol, threads):
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
- # epsilon is the z-var upper bound (the minimum flux magnitude counted as
73
- # non-zero), so at 0 the bulk-z maximisation can never lift a reaction
74
- # above the threshold and every candidate looks blocked.
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=4), stacklevel=4)
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 _fastcc_bulk_z(model, subset, c, z_var, flux_tol):
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.optimize()
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.optimize()
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.optimize()
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.optimize()
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.optimize()
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, c, z_var, z_constr, mfi_orig = _fastcc_setup(
346
- model, subset, epsilon, flux_tol, threads)
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
- _fastcc_cleanup_z(model, z_var, z_constr)
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
- c = subset - functional
359
- # Random positive weights by column index, fixed for the call: a plain
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
- # Keep the sense while it shrinks c, and switch on a quiet solve. A
367
- # direction that found nothing is thus tried again after the other one
368
- # has shrunk c: what it could not move before may be all that is left.
369
- # Two quiet solves in a row are one of each sense for the same c, and
370
- # then nothing in c can carry flux. (Switching after every solve is
371
- # also exact but took 1.6-5x the time, in simplex iterations spent
372
- # in the unproductive direction.)
373
- while c and quiet < 2:
374
- cs = sorted(c, key=lambda v: v.index)
375
- model.setObjective(grb.LinExpr([w[v.index] for v in cs], cs), sense)
376
- # Retry once after a cold restart: warm-start state can
377
- # accumulate over this loop's many sense-flipping solves and
378
- # yield a spurious non-OPTIMAL status on a feasible region.
379
- if _optimize_with_reset_retry(model) != grb.GRB.OPTIMAL: # pragma: no cover - defensive
380
- raise RuntimeError(
381
- f'Infeasible model (status {model.status})')
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
- nz = {v for v, x in zip(sub, model.getAttr('X', sub))
384
- if abs(x) > flux_tol}
385
- functional |= nz
386
- if nz & c:
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
- return _fastcc_translate(functional, mfi_orig)
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.2.0
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*
@@ -1,6 +1,6 @@
1
1
  [metadata]
2
2
  name = mptool
3
- version = 1.2.0
3
+ version = 1.3.0
4
4
  author = Ove Øyås
5
5
  author_email = ove.oyas@medisin.uio.no
6
6
  description = Enumeration and sampling of minimal pathways in metabolic (sub)networks.
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