gbacpp is a C++ implementation of the growth balance analysis mathematical formalism (GBA; Dourado et al. 2023). The software has been optimized to solve large-scale cell growth models (CGMs), for which available solvers for non-linear constraint-based problems usually struggle. The optimization process relies on a gradient ascent approach, and is preferred for models offering a convex solution space (typically, when all reactions in the metabolic network are linearly independent).
☑️ Note that CGMs must comply to a standardized format. A tutorial is available in the CGM format tutorial.
☑️ When building a CGM, stoichiometric coefficients, and kinetic parameters must be converted following GBA formalism. See the units conversion tutorial.
☑️ gbacpp will integrate CGM evolutionary algorithms in the near future (see Roadmap).
☑️ A complete tutorial on GBA formalism is also available at https://cellgrowthsim.com/.
- 1) Roadmap
- 2) Contributing
- 3) Installation instructions
- 4) First usage
- 5) CGM format tutorial
- 6) Units conversion tutorial
- 7) Copyright
- 8) License
| Task | Status |
|---|---|
| Gradient ascent (best for full column-rank CGMs) |  |
| MCMC algorithm |  |
| Forward-in-time population level simulations | |
| Lineage tracking | |
If you wish to contribute, do not hesitate to reach the developer.
Download the latest release of gbacpp, and save it to a directory of your choice. Open a terminal and use the cd command to navigate to this directory. Then follow the steps below to compile and build the executables.
gbacpp software has been primilary developed for Unix/Linux and macOS systems.
- A C++ compiler (GCC, LLVM, ...; C++17 required),
- CMake
$\geq$ 3.5 (command line version), - GSL
$\geq$ 2.8 (https://www.gnu.org/software/gsl/).
Download the latest release of gbacpp, and save it into a directory of your choice. Open a terminal and use the cd command to navigate to this directory. To install gbacpp, simply call the script install.sh on the command line:
sh install.sh
The script will compile and install the software in the appropriate folder (usually in a bin directory, such as /usr/local/bin).
The binary executable find_cgm_optimum should be available in the terminal. If not, you may need to export the binary path:
export PATH="/usr/bin:$PATH"
To manually compile gbacpp, run the following instructions on the command line:
cd cmake/
and
bash make.sh
To compile the software in DEBUG mode, use make_debug.sh script instead of make.sh:
bash make_debug.sh
This mode should only be used for test or development phases.
Binary executable files are in build/bin folder.
To clean compiled files and binary executables, run:
bash make_clean.sh
Once gbacpp has been compiled and installed, follow the next steps for a first usage of the software.
To run a gradient ascent optimization on a CGM, execute the following command line:
find_cgm_optimum <parameters>
The command line parameters are described below. The description is also available by executing the following command line in a terminal:
find_cgm_optimum -h
-h,--help: Print the help, then exit,-v,--version: Print the current version, then exit,
-path,--model-path: Specify the path of the CGM to be loaded,-name,--model-name: Specify the name of the CGM to be loaded,-condition,--condition: Specify the external condition. Ifallis selected, all conditions are applied.
-
-print,--print-optimum: Indicates if the optimum should be printed in the standard output. This option is useful to pass the result to another program (-verboseoption should not be used), -
-trajectory,--write-trajectory: Indicates if the trajectory should be written as output files. Tracking the optimization trajectory can be useful during tests, -
-output,--output-path: Specify the path of output files, -
-tol,--tolerance: Specify the tolerance value ($10^{-10}$ by default), -
-stable,--stable-count: Specify the maximal number of iterations with unchanged growth rate as a stop criterium ($10,000$ by default), -
-maxt,--max-time: Specify the maximal trajectory time as a stop criterium ($100,000$ by default), -
-verbose,--verbose: Indicates if the program should run in verbose mode (can conflict with the option-print).
In this example, growth rate optimums are calculated for all the external conditions of the Escherichia coli toy model EC12b (see folder ./examples/toy_models).
First, navigate to the folder ./examples using the cd command:
cd ./examples
Then, call the optimization algorithm:
find_cgm_optimum -path ./toy_models -name EC12b -condition all -output ./output -verbose
Here, optimums are calculated for all conditions, and saved in the folder ./examples/output. Verbose mode is activated to get insights in the optimization process.
Ready-to-use examples are available in the folder ./examples (navigate to the folder examples using the cd command):
• model_A_condition_1.sh: This script will run a single gradient ascent on model A in external condition 1 (2 reactions, 2 metabolites). You can execute it using the following command line:
bash model_A_condition_1.sh
At the end of the optimization, CSV files are written in the folder ./examples/output. You can edit the parameter values at will to test the behaviour of the gradient ascent. See below for a full description of the parameters.
• model_B_all_conditions.sh: This script will calculate the optimal growth rate on model B for all external conditions. You can execute it using the following command line:
bash model_B_all_conditions.sh
All the optimums are written in the folder ./examples/output.
A tutorial is available to better understand the content of cell growth model:
A tutorial is available for users starting from standard metabolic models stoichiometric coefficients and kinetic parameters, and wanting to convert them into GBA formalism:
Copyright © 2024-2025 Charles Rocabert. All rights reserved.
MIT License
Copyright (c) 2024-2025 Charles Rocabert
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.