Protocol for thermodynamically optimal construction and analysis of metabolic networks using ThermOptCOBRA

Summary

Thermodynamically infeasible cycles violate the second law of thermodynamics but are permitted by stoichiometric flux analysis. Here, we present a protocol for the construction and analysis of metabolic networks using ThermOptCOBRA, a MATLAB extension of the COBRA Toolbox. We describe steps for enumerating cycles (ThermOptEnumerator), determining feasible directions and blocked reactions (ThermOptCC), and building thermodynamically consistent context-specific models using omics data (ThermOptiCS). We then detail procedures for removing loops or sample loopless flux distributions (ThermOptFlux/ADSB-ThermOptFlux).

For complete details on the use and execution of this protocol, please refer to Kumar and Bhatt.¹

Graphical abstract

Highlights

• •Steps for enumerating thermodynamically infeasible cycles (TICs) in metabolic models
• •Instructions for identifying stoichiometrically and thermodynamically blocked reactions
• •Instructions to build compact and thermodynamically consistent context-specific models
• •Steps for generating loopless flux samples and removing loops from flux distributions

Publisher’s note: Undertaking any experimental protocol requires adherence to local institutional guidelines for laboratory safety and ethics.

Thermodynamically infeasible cycles violate the second law of thermodynamics but are permitted by stoichiometric flux analysis. Here, we present a protocol for the construction and analysis of metabolic networks using ThermOptCOBRA, a MATLAB extension of the COBRA Toolbox. We describe steps for enumerating cycles (ThermOptEnumerator), determining feasible directions and blocked reactions (ThermOptCC), and building thermodynamically consistent context-specific models using omics data (ThermOptiCS). We then detail procedures for removing loops or sample loopless flux distributions (ThermOptFlux/ADSB-ThermOptFlux).

Before you begin

Genome-scale metabolic models (GEMs) are essential tools for exploring cellular metabolism and generating phenotype predictions. Despite their widespread utility, traditional constraint-based techniques, such as flux balance analysis² often overlook thermodynamic principles. This oversight frequently results in flux predictions containing thermodynamically infeasible cycles (TICs), which can compromise the reliability of downstream biological interpretations. To address this gap and improve the biological realism of metabolic predictions, thermodynamic constraints must be seamlessly incorporated into modeling workflows. In this protocol, we provide step-by-step instructions for utilizing the ThermOptCOBRA suite to refine GEMs and build context-specific networks using transcriptomics data. The procedures described herein guide users through enumerating TICs, detecting thermodynamically blocked reactions, extracting flux and thermodynamically consistent context-specific models, and obtaining thermodynamically feasible flux samples.

The protocol below describes the specific steps for using ThermOptCOBRA with GEMs from BiGG³ and AGORA2⁴ databases. However, this protocol can be applied to any GEM in standard formats. The protocol requires setting up MATLAB, the COBRA Toolbox, and an optimization solver (Eg: Gurobi, CPLEX) capable of solving linear programming (LP) and mixed-integer linear programming (MILP).

Innovation

ThermOptCOBRA advances constraint-based metabolic modeling by overcoming fundamental limitations in existing algorithms for handling TICs. It introduces a suite of MATLAB algorithms that improves upon both the computational efficiency and accuracy of GEMs: 1) Accelerated TIC Enumeration: While methods like OptFill⁵ can enumerate TICs, ThermOptEnumerator offers a dramatic reduction in computational time, making exhaustive enumeration feasible for complex models. 2) Thermodynamic Consistency Checks: Existing topological methods (e.g., FastCC,⁶ SpectraCC⁷) identify reactions blocked by dead-end metabolites but miss thermodynamically blocked reactions. ThermOptCC successfully identifies both stoichiometrically blocked reactions and thermodynamically blocked reactions. Furthermore, while loopless-FVA methods can also perform thermodynamic consistency checks, ThermOptCC achieves similar outcome significantly faster. 3) Thermodynamically Consistent Context-Specific Models: Algorithms like Fastcore⁶ often inadvertently include TICs to unblock active reactions. ThermOptiCS integrates thermodynamic constraints directly into the extraction process, yielding more compact and strictly thermodynamically consistent context-specific models from transcriptomics data. 4) Robust Loopless Sampling and Elimination: Current loopless sampling techniques (e.g., ADSB-Nint⁸) can still generate samples with loops when TICs are linearly dependent; ThermOptFlux avoids these hidden loops and provides loop elimination from any flux distribution.

By unifying these methodologies as a COBRA Toolbox extension, ThermOptCOBRA provides a accurate, time-efficient workflow to ensure simulated phenotypes reflect thermodynamically viable metabolic states.

Key resources table

REAGENT or RESOURCE	SOURCE	IDENTIFIER
Deposited data
Repository of GEMs – AGORA 2	Heinken et al.4	https://www.vmh.life/files/reconstructions/AGORA2/version2.00/mat_files/
Repository of GEMs – BiGG	King et al.3	http://bigg.ucsd.edu/models
Escherichia coli GEM	Orth et al.9	http://bigg.ucsd.edu/models/iJO1366
Transcriptomics data of Escherichia coli	Bajpe et al.10	https://zenodo.org/records/17833977
Software and algorithms
MATLAB R2023b	The MathWorks Inc.	https://www.mathworks.com
Gurobi Optimizer	Gurobi Optimization, LLC	https://www.gurobi.com/
Localgini	Kumar et al.11	https://github.com/NiravBhattLab/Localgini
LooplessFluxSampler	Saa et al.8	https://github.com/SysBioengLab/looplessFluxSampler
Spectra	Kumar et al.7	https://github.com/bisect-group/SPECTRA/tree/main

Step-by-step method details

Installation of ThermOptCOBRA and the dependencies

Timing: 30–60 min

This section describes the installation and configuration of ThermOptCOBRA and its required software dependencies, including MATLAB, the COBRA Toolbox, and an optimization solver. Successful completion of these steps ensures that the computational environment is correctly configured and ready to perform thermodynamically constrained analyses and related optimization workflows. All the steps mentioned in this protocol were run in Matlab R2023b in a Dell Precision 3640 workstation (IntelCore i7–10700 CPU, 32GB RAM). Optimizations were performed using Gurobi 9.1.2.

• 1.
  Install MATLAB (R2022b or later; this implementation is tested on R2023b).

  • a.
    Other MATLAB toolboxes to be installed are Optimization Toolbox, Statistics and Machine Learning Toolbox, and Parallel Computing Toolbox.
• 2.Install Gurobi 9.1.2 or later (https://www.gurobi.com/downloads/).
• 3.Install COBRA toolbox by running the following command:

>git clone --depth=1 https://github.com/opencobra/cobratoolbox.git.

Note: For detailed instructions on installing the COBRA toolbox, visit https://opencobra.github.io/cobratoolbox/stable/installation.html. ThermOptCOBRA relies on the COBRA toolbox for all its optimization formulations, hence there is a flexibility to use any supported solver. Information regarding which solvers are compatible with specific versions of MATLAB can also be found on the COBRA toolbox website.

• 4.Install ThermOptCOBRA package by running the following command:

>git clone --depth=1 https://github.com/bisect-group/Protocol_ThermOptCOBRA.git.

• 5.Open MATLAB and add to path the ‘cobratoolbox’ repository. This can be done manually or by running the following commands:

>addpath(genpath('cobratoolbox'));

• 6.Initiate the COBRA environment without checking for updates by running the following command:

>initCobraToolbox(0)

• 7.
  Add to path the ‘Protocol_ThermOptCOBRA’repository.

  >addpath(genpath(‘Protocol_ThermOptCOBRA'));
• 8.Change the solver type and set the feasibility and optimality tolerances:

>changeCobraSolver('gurobi','all')

>changeCobraSolverParams('MILP', 'feasTol', 1e-9);

>changeCobraSolverParams('LP', 'feasTol', 1e-9);

>changeCobraSolverParams('MILP', 'optTol', 1e-9);

>changeCobraSolverParams('LP', 'optTol', 1e-9);

Data preparation

Timing: 30–60 min

This section prepares the metabolic model and transcriptomics datasets required by ThermOptCOBRA, ensuring that all inputs are correctly formatted and compatible with downstream analyses.

• 9.
  Download and store all the models from BiGG and AGORA2 database in ‘models’ folder.

  • a.
    AGORA2 models can be obtained from: https://www.vmh.life/files/reconstructions/AGORA2/version2.00/mat_files/
  • b.
    BiGG models can be obtained from: http://bigg.ucsd.edu/models

CRITICAL: All the codes implemented here are for the prokaryotic models. Ensure to include only them. This will be 7,401 models in total (7,302 from AGORA2 database and 99 from BiGG database). The excluded models in BiGG database are RECON1, Recon3D, iAT_PLT_636, iCHOv1, iCHOv1_DG44, iJN746, iLB1027_lipid, iMM1415 and iRC1080. For these models, the TIC enumeration run indefinitely as stated in problem 3 in troubleshooting section.

Note: All the codes further assume that the directory ‘models’ is in the present working directory.

• 10.If building context-specific models (CSMs), transcriptomics data needs to be obtained. The transcriptomics data of Escherichia coli used in this study can be obtained from: https://zenodo.org/records/17833977.

Note: The file ‘log_tpm.csv’ was used in this protocol. The data is log2 transformed normalized gene expression counts (log2(TPM+1)). The file ‘log_tpm.csv ’ should be like the image shown in Figure 1.

Figure 1.

An image of the .xlsx file of the transcriptomics data to be used for context-specific model building

Enumeration of all TICs in the models

Timing: 14–15 h

This step identifies and catalogs all thermodynamically infeasible cycles (TICs) present in the metabolic models while generating a standardized model representation (‘modModel’) that serves as the required input for all subsequent analyses.

• 11.Enumerate all the cycles present in all the metabolic models from the folder ‘models’.

Note: The below snippet of code enumerates the TICs for all the 7,401 metabolic models and stores them in the folder ‘Step_1’.

>path = dir('models');

>path = {path(3:end).name}'; % Name of all the models

>mkdir('Step_1')

>for i=1:numel(path)

> load(['models/',path{i}])

> [TICs,Direction,TIC_Rxns,modModel,opt] = ThermOptEnumMILP(model);

> save(['Step_1/',path{i}],'TICs','Direction','TIC_Rxns','modModel','opt')

>end

Note: The details of the variables stored for each of the models are 1) TICs: A MATLAB cell of all the TICs. The number of elements in the variable ‘TICs’ are the number of TICs. Each element in this cell is a list of reactions involved in a TIC. 2) Direction: A MATLAB cell of the direction of the respective TIC. Here +1 refers to the positive flux −1 refers to the negative flux direction 3) TIC_Rxns: A MATLAB cell of all the reactions from the metabolic model that are involved in the TICs. 4) modModel: A modified COBRA model. The modifications made are i) all the irreversible reactions in the reverse direction are converted to irreversible reactions in forward direction, ii) The absolute maximum value of the bounds are fixed at 1000.

CRITICAL: The ‘modModel’ has to be used in ‘Loopless flux sampling’ section of the protocol. The output ‘Direction’ is in accordance with the ‘modModel’.

Note: ThermOptCOBRA can be implied on any COBRA model given that it has the following fields: S, lb, ub, rxns, c, genes, rules. A loaded COBRA model looks like the image shown in Figure 2.

Figure 2.

An image of the COBRA model loaded in the MATLAB workspace

The required fields for implementing in ThermOptCOBRA are shown with the pointed arrows.

Identification of thermodynamically blocked reactions

Timing: 4–5 h

This step identifies reactions that cannot carry flux under thermodynamic constraints, thereby generating a thermodynamically consistent representation of each metabolic model that is required for downstream context-specific model reconstruction and analysis.

• 12.For all the models get thermodynamically blocked reactions by running the following snippet of code. For each model, a variable ‘Tcc’ will be generated. This is a MATLAB cell of size equal to the number of reactions indicating whether a reaction is thermodynamically blocked (‘Blocked’) or not (‘Unblocked’).

>clear;

>path = dir('models');

>path = {path(3:end).name}';

>if ∼exist('Step_2', 'dir')

> mkdir('Step_2');

>end

>tol=1e-5;

>for i=1:numel(path)

> % Skip if the model has already been processed

> if exist(['Step_2/',path{i}], 'file')

> continue;

> end

> load(['models/',path{i}]);

> [Tcc,modModel] = ThermOptCC(model,tol,0);

> save(['Step_2/',path{i}],'Tcc','modModel');

> clear Tcc model;

>end

Optional: The third input argument to ThermOptCC indicates whether thermodynamically feasible direction is required (1) or only blocked/unblocked details are enough (0). The above step returns only the blocked/unblocked details. The below code snippet returns the thermodynamically feasible directions too.

>clear;

>path = dir('models');

>path = {path(3:end).name}';

>if ∼exist('Step_2_1', 'dir')

> mkdir('Step_2_1');

>end

>tol=1e-5;

>for i=1:numel(path)

> % Skip if the model has already been processed

> if exist(['Step_2_1/',path{i}], 'file')

> continue;

> end

> load(['models/',path{i}]);

> [Tcc,modModel] = ThermOptCC(model,tol,1);

> save(['Step_2_1/',path{i}],'Tcc','modModel');

> clear Tcc model;

>end

Note: For all the models, the default bounds are used without any media specifications. If any media conditions need to be specified, then the ‘model.lb’ and ‘model.ub’ needs to be modified accordingly.

CRITICAL: ThemOptiCS requires a thermodynamically consistent GEM as an input to build the context-specific models. For this, either of the above steps can be utilized. Anyways, returning only the blocked/unblocked status is computationally less expensive compared to the other one.

Optional: ThermOptCC returns both stoichiometrically and thermodynamically blocked reactions. If the user wants to identify the distinct classes of blocked reactions, the following code snippet can be used for any loaded model.

>tol=1e-5;

>Tcc = ThermOptCC(model,tol,0);

>S_T_blkd = find(ismember(Tcc,'Blocked'));

>S_cons = spectraCC(model,tol);

>S_blkd = setdiff(1:numel(model.rxns),S_cons);

>T_blkd = setdiff(S_T_blkd,S_blkd);

The variable ‘S_blkd’ is the indices of all the reactions that are stoichiometrically blocked and the variable ‘T_blkd’ is the indices of all the reactions that are thermodynamically blocked.

Construction of thermodynamically consistent context-specific metabolic models

Timing: ∼6 h

This section reconstructs thermodynamically consistent context-specific metabolic models by integrating transcriptomics data with a genome-scale metabolic model, ensuring that the resulting models retain essential metabolic functions while satisfying thermodynamic constraints.

• 13.Setup the directory and initial parameters. Here, the Escherichia coli metabolic model, iJO1366 is used to demonstrate the ThermOptiCS pipeline.

>clear

>changeCobraSolverParams('MILP', 'feasTol', 1e-9);

>changeCobraSolverParams('LP', 'feasTol', 1e-9);

>% Setup directories

>outputBaseDir = './Step_3/models/';

>mkdir(outputBaseDir)

• 14.Define the core reactions that must be present in the model.

>manual_core = {'BIOMASS_Ec_iJO1366_core_53p95M', 'ATPM'};

• 15.Extract the thermodynamically consistent Escherichia coli model. Here the biomass reaction’s lower bound is set to 80% of the actual biomass value.

Note: This enforces a required metabolic functionality constraint - the context-specific model must be able to sustain at least 80% of maximal growth. This is the same idea as GIMME's¹² "objective fraction."

>load('./models/iJO1366');

>IrR = model.ub<=0; % reactions irreversible in reverse direction

>temp = model.ub(IrR);

>model.S(:,IrR) = -model.S(:,IrR);

>model.ub(IrR) = -1∗model.lb(IrR);

>model.lb(IrR) = -1∗temp;

>% changing all the negative lower bounds to its defaults

>model.lb(model.lb<0)=-1000;

>sol = optimizeCbModel(model);

>model.lb(find(model.c))=0.8∗sol.f;

>[Tcc] = ThermOptCC(model,1e-5,0);

>blkd = find(ismember(Tcc, 'Blocked'));

>model = removeRxns(model,model.rxns(blkd));

• 16.Extract the core reactions from the transcriptomics data using Localgini thresholding algorithm. Note that this step requires transcriptomics data.

>model = buildRxnGeneMat(model);

>% Load the transcriptomics dataset

> tbl = readtable('log_tpm.csv');

>geneExp = struct();

>geneExp.genes = tbl.Geneid;

>geneExp.value = table2array(tbl(:, 2:end));

>geneExp.value = 2.ˆ(geneExp.value)-1;

>geneExp.context = tbl.Properties.VariableNames(2:end)';

>coreRxn = find(ismember(model.rxns, manual_core));

>% Compute reaction importance using Local Gini

>[RxnImp, ∼] = GiniReactionImportance(geneExp, model, 'FASTCORE', 80, 10, 1, coreRxn);

% Create output directory for LG threshold

lgOutputDir = sprintf('%s/', outputBaseDir);

mkdir(lgOutputDir);

% saving the core reaction list

savePath = sprintf('%sm%s.mat', lgOutputDir, 'CoreReactions');

save(savePath, 'RxnImp');

Note: Here we have used Localgini based thresholding algorithm. Anyways, other thresholding methods can also be used to derive the core reactions. The choice of the upper and lower global thresholds was taken based on the analysis made in actual Localgini paper. The users can use other values also to derive the core reactions.

• 17.Reconstruction of context-specific metabolic models.

>numSamples = size(RxnImp, 2);

>for i = 1:numSamples

> fprintf(' Sample %d/%d...\n', i, numSamples);

> core = find(RxnImp(:, i));

> tol = 1e-5;

> max_runtime = 120;

> doTOCC = 0; % The input model is consistent

> m = ThermOptiCS(model, core, tol, doTOCC, max_runtime);

> savePath = sprintf('%sm%d.mat', lgOutputDir, i);

> save(savePath, 'm');

>end

Note: The maximum runtime (‘max_runtime’) is runtime per iteration of MILP. This has to be chosen based on the complexity of the model defined by number of reactions and TICs. For the Escherichia coli model utilized, the MIP gap was less than 0.1% for all the contexts for the set runtime 120 s.

Loopless flux sampling

Timing: ∼37–40 min

This step generates thermodynamically feasible flux distributions for genome-scale or context-specific metabolic models, enabling the characterization of metabolic states while avoiding loops caused by internal flux cycles.

• 18.Flux state of any genome-scale model or context-specific model can be inferred by loopless flux sampling. In this step, the code demonstrates the same using five distinct models as an example.

>clear

>mkdir('Step_4')

>rng(42);

>modelNames = {'Brevibacillus_brevis_FJAT_0809_GLX.mat'

>'e_coli_core.mat'

>'iIT341.mat'

>'iMM904.mat'

>'iYO844.mat'};

>for m = 1:numel(modelNames)

> modelName = modelNames{m};

> load(['./Step_1/',modelName])

> model = modModel;

> model.TICs = TICs;

> model.Direction = Direction;

> model.lb(model.lb<0)=-1000;

> model.ub(:)=1000;

>

> % Set up sampling parameters

> options.numSamples = 1e4;

> options.stepsPerPoint = 1e2;

> options.numDiscarded = 0.1∗options.numSamples;

> options.algorithm = 'ADSB';

> options.loopless = 1;

> options.warmUpFlag = 0;

> options.parallelFlag = 0;

> options.diagnostics = 1;

>

> options.loopcheck = 'TOF'; % which method to use to check the loop

> sampleTOF = looplessFluxSampler(model,options);

> clear modModel model TICs TIC_Rxns Direction

> save(['Step_4/Samples_',modelName])

>end

Loop detection and removal

Timing: ∼5–6 min

This step identifies and removes flux distributions associated with thermodynamically infeasible cycles, ensuring that the resulting flux samples represent biologically meaningful metabolic states.

• 19.The TICs and Directions can be utilized to detect and remove the loops from any flux analysis algorithms. Here, the flux samples obtained from the context-specific metabolic model using CHRR sampler is used to demonstrate the code.

>clear

>changeCobraSolverParams('LP','optTol',1e-7);

>model = 'm4';

>load(['Step_3/models/',model,'.mat'])

> rng(42)

>[TICs,Direction,TIC_Rxns,m,opt] = ThermOptEnumMILP(m);

>nSamples = 100000;

>chrr_samples= chrrSampler(m,100,nSamples);

>

>chrr_samples_no_tic=zeros(size(chrr_samples));

>for i=1:nSamples

> f = chrr_samples(:,i);

> [flux] = ThermOptFlux(m,f,TICs,Direction);

> chrr_samples_no_tic(:,i)=flux;

> clear flux

>end

>

>tbl = table('Size',[nSamples,numel(TIC_Rxns)],'VariableNames',TIC_Rxns,'VariableTypes',repmat({'double'},1,numel(TIC_Rxns)));

>tbl_chrr = tbl;

>tbl_tof = tbl;

>for i =1:numel(TIC_Rxns)

> id = find(ismember(m.rxns,TIC_Rxns{i}));

> tbl_chrr.(TIC_Rxns{i}) = chrr_samples(id,:)';

> tbl_tof.(TIC_Rxns{i}) = chrr_samples_no_tic(id,:)';

>end

>writetable(tbl_tof,['Step_4/TOF_samples_TIC_rxns_LG_TOCS2_',model,'.csv'])

>writetable(tbl_chrr,['Step_4/CHRR_samples_TIC_rxns_LG_TOCS2_',model,'.csv'])

Note: Post-processing projection with ThermOptFlux breaks the uniform-sampling guarantee of native loopless sampling (Step 20) noted in the limitations section. Use Step 20 instead of projection whenever downstream analysis requires: 1) Distributional shapes: Marginals, histograms, modes, quantiles, ranges, or credible intervals. 2) Differential analysis: Comparing conditions where projection bias could mimic biological differences.

The distortion scales with the number of TIC-associated reactions and loop flux magnitude.

Post-processing projection remains useful when only loop-free point estimates/directions are needed, or when reactions don’t participate in TICs.

Expected outcomes

By following the step-by-step procedure for TIC enumeration, users will first generate a comprehensive set of thermodynamically infeasible cycles for their input metabolic model. For example, upon completing the ‘Enumeration of all the TICs in the models’ step, the folder ‘Step_1’ will contain ‘.mat’ files for all the models detailing the ‘TICs’ and the specific reactions involved in each TIC alongside the ‘Direction’ matrix. For example, the model ‘Abiotrophia_defectiva_ATCC_49176’ from the AGORA2 database should have 37 reactions involved in TICs and 48 total TICs. The model ‘iAF692’ from the BiGG database should have 30 reactions involved in TICs and 31 total TICs.

Moving to the thermodynamic consistency check, running ‘Identification of thermodynamically blocked reactions’ will systematically identify the thermodynamically blocked reactions of all the models. The expected outcome of this step is a complete classification array (‘Tcc’) that labels every reaction as either unblocked or entirely blocked due to thermodynamic or stoichiometric infeasibility. This can be further used to refine the models by removing the blocked reactions. For example, the model ‘Abiotrophia_defectiva_ATCC_49176’ must have 329 blocked reactions. The model ‘iAF692’ must have 471 blocked reactions.

When integrating transcriptomics data using ‘Construction of thermodynamically consistent context-specific metabolic models’, the protocol builds a suite of context-specific models corresponding to each input sample. Users can expect these output models, saved automatically in the designated ‘Step_3/models/` directory, to be highly compact and strictly free of thermodynamically blocked reactions. This ensures that the context-specific networks are natively thermodynamically consistent and retains all the core reactions. For example the context-specific model, m1 should have 1543 reactions and 1142 metabolites.

Finally, executing the loopless flux sampling step with the ‘TOF’ option (or post-processing with ‘ThermOptFlux’) will generate robust, sampled flux distributions. The resulting sample matrices represent a solution space entirely devoid of internal loops, yielding biologically realistic flux values for downstream applications. If these expected outcomes, such as perfectly loop-free samples or flux-consistent compact models are not observed, follow the tips in the troubleshooting section.

Limitations

Genome-scale eukaryotic reconstructions exceed the practical reach of complete TIC enumeration on a single workstation. The ThermOptEnumerator runs on Recon1, Recon3D, and Yeast9 returned 51,193, 61,592, and 20,848 TICs respectively before the 7-day wall-clock limit was reached, all with opt = 0 (incomplete). Hence, downstream stages of this protocol cannot yet be applied to such models.

All four ThermOptCOBRA algorithms are downstream consumers of the input GEM. Mis-annotated reaction directions, missing transporter reactions, or curated bounds that violate physiology will be propagated into the TIC set and the direction assignment.

Another limitation concerns flux sampling: applying ‘ThermOptFlux’ as a post-processing step to remove loops from previously generated flux samples (e.g., using CHRR) breaks the mathematical assumption of uniform sampling. By projecting the sample to the nearest thermodynamically feasible point, a geometric bias is introduced. While this is often less detrimental than allowing thermodynamic violations, it must be considered when analyzing volume-associated statistical features.

Finally, the protocol’s reliance on Mixed-Integer Linear Programming (MILP) necessitates the use of a highly optimized solver (like Gurobi). While open-source alternatives like GLPK are effective for smaller models, they lack the scalability required for complex networks. The approach is also highly sensitive to numerical tolerances; minor precision issues or relaxed solver tolerances (e.g., above ‘1e−7′) can lead to the misclassification of feasible reactions as blocked.

Troubleshooting

Problem 1

Gurobi returns an error indicating that optimality conditions are not satisfied during optimizations (such as ‘ThermOptEnumMILP’ or ‘ThermOptiCS’ or ‘CHRR sampling’), the Gurobi solver terminates with an error stating that the optimality condition is not satisfied.

Potential solution

This issue arises because the strict preset numerical tolerances (e.g., ‘1e−9′) conflict with the inherent numerical scaling or condition number of the model’s stoichiometric matrix. The solution is to slightly relax these tolerances. Try incrementally increasing the optimality and feasibility tolerances (e.g., to ‘1e−8′ or ‘1e−7′) by using ‘changeCobraSolverParams(‘MILP’, ‘optTol’, 1e−8);` and ‘changeCobraSolverParams(‘LP’, ‘optTol’, 1e−8);`. However, exercise caution and do not increase them too broadly (e.g., above ‘1e−6′), as excessively lax tolerances can introduce false positives in TIC enumeration or classification.

Problem 2

Rerunning ‘ThermOptCC’ on a thermodynamically consistent model returns additional blocked reactions. After obtaining a thermodynamically consistent model from ‘ThermOptCC’, running the algorithm on the model a second time unexpectedly flags a few more reactions as blocked.

Potential solution

This numerical artifact occurs when the user-defined threshold tolerance for defining a non-zero flux (‘tol’) is too close to the solver’s preset feasibility tolerances. It can also happen if the model is ill-scaled or if specific media conditions force the maximum possible flux to hover right around the preset tolerance boundaries. To resolve this, ensure there is a clear margin between your non-zero flux threshold and the solver’s precision (for example, if ‘feasTol’ is set to ‘1e−9′, ensure ‘tol’ is at least ‘1e−6′ or ‘1e−5′). If the issue persists, consider applying matrix scaling routines to the model to improve numerical stability.

Problem 3

‘ThermOptEnumMILP’ runs indefinitely without terminating on large models. When enumerating TICs, particularly on massive eukaryotic networks, the algorithm appears to hang or continues running for days.

Potential solution

Cycle enumeration is an inherently complex (NP-hard) combinatorial problem, meaning the computational complexity scales exponentially with the number of reactions involved in TICs. As detailed in the ThermOptCOBRA paper, the algorithm successfully achieved complete, exhaustive enumeration for models containing up to a maximum of 224 TIC-associated reactions. However, for massive eukaryotic networks like Recon3D (which have thousands of TIC reactions), exhaustive enumeration identified tens of thousands of TICs but could not complete even after a week of computational time. If your target model exceeds this complexity (significantly more than ∼230 TIC reactions) or if such long runtimes are impractical for your pipeline, you can utilize the optional ‘timeLimit’ input parameter (in seconds) to set an upper bound on execution. For example, calling `[TICs, Direction, TIC_Rxns, modModel, opt] = ThermOptEnumMILP(model, 86400);` restricts the run to 24 hours. Note that if the algorithm hits this limit before finding all cycles, it will terminate early and return empty sets.

Problem 4

MATLAB executes the wrong ‘looplessFluxSampler’ function or ignores the ‘TOF’ option. When running the loopless flux sampler, MATLAB may execute the default COBRA Toolbox version of ‘looplessFluxSampler’ instead of the modified version provided by ThermOptCOBRA. This can result in an “unrecognized option” error or generate samples that still contain loops because the ‘TOF’ formulation was bypassed entirely.

Potential solution

This occurs due to MATLAB path precedence. Because the COBRA Toolbox contains a function with the exact same name, it might “shadow” the ThermOptCOBRA version. To guarantee that MATLAB uses our exact formulation, ensure that the directory containing the ThermOptCOBRA scripts (specifically the provided ‘looplessFluxSampler’ folder) is added to the top of your MATLAB search path. You can do this by running ‘addpath(genpath(‘path/to/ThermOptCOBRA'))` after initializing the COBRA Toolbox. Verify that the correct function is active by typing ‘which looplessFluxSampler’ in the MATLAB command window; the returned path must point to the script inside the ThermOptCOBRA repository.

Problem 5

Errors regarding matrix dimensions or invalid bounds during model initialization. The ‘ThermOptEnumerator’ or ‘ThermOptCC’ functions immediately throw an error before optimization begins, citing ‘NaN′, ‘Inf’, or mismatched matrix dimensions.

Potential solution

This is typically caused by poorly formatted input models. Ensure that the model has valid, finite lower and upper bounds (e.g., replace ‘Inf’ with ‘1000′ and `-Inf’ with `-1000′). Additionally, verify that ‘model.rxns’ and ‘model.mets’ contain no empty strings and that the stoichiometric matrix ‘model.S′ matches the dimensions of the reactions and metabolites.

Problem 6

‘ThermOptiCS’ generates a thermodynamically consistent but suboptimal (less compact) model. The context-specific model generated by ‘ThermOptiCS’ passes all thermodynamic consistency checks, but it appears larger or includes more non-core reactions than expected, indicating a suboptimal minimal network.

Potential solution

This occurs when the MILP solver hits the prescribed ‘timeLimit’ (e.g., 120 seconds) before it can prove global optimality or find the absolute most parsimonious solution. Any incumbent solution returned at this stage is still strictly thermodynamically consistent and functionally valid for downstream analyses. However, if a more compact model is required, you can increase the ‘timeLimit’ parameter passed to the ‘ThermOptiCS’ function (for example, setting it to 600 seconds or higher) to provide the solver with sufficient time to explore the branch-and-bound tree and further minimize the inclusion of non-core reactions.

Resource availability

Lead contact

Further information and requests for resources should be directed to and will be fulfilled by the lead contact, Nirav Pravinbhai Bhatt (niravbhatt@iitm.ac.in).

Technical contact

Technical questions on executing this protocol should be directed to and will be answered by the technical contact, Pavan Kumar (spavaniitm@smail.iitm.ac.in).

Materials availability

No materials have been generated in this study.

Data and code availability

• •This paper analyzes existing, publicly available data. These identifiers for the datasets are listed in the key resources table.
• •Original code for ThermOptCOBRA can be obtained from the GitHub repository: https://github.com/bisect-group/Protocol_ThermOptCOBRA. The codes are also deposited in Zenodo: https://doi.org/10.5281/zenodo.22740745.

Acknowledgments

We thank the Wadhwani School of Data Science & Artificial Intelligence, IIT Madras, for providing the computational resources.

Author contributions

Conceptualization, N.P.B.; investigation, P.K.; funding acquisition, N.P.B.; project administration, N.P.B.; supervision, N.P.B.; writing – original draft, P.K.; writing – review and editing, P.K. and N.P.B.; software, N.P.B.; validation (reproducibility and software testing), P.K. and N.P.B.

Declaration of interests

The authors declare no competing interests.

Declaration of generative AI and AI-assisted technologies in the manuscript preparation process

During the preparation of this work, the authors used Gemini 3.5 flash to improve grammar and check for language errors. The authors reviewed and edited the output as needed and take full responsibility for the content of the published article.