Growth Balance Analysis for C++

   

    

---

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 self-replicating cell (SRC) models, 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.

Note

☑️ Note that SRC models must comply to a standardized format. Guidelines are available in the SRC model format tutorial.

☑️ When building a SRC model, stoichiometric coefficients, and kinetic parameters must be converted following GBA formalism. See the units conversion tutorial.

☑️ The gradient ascent algorithm will be detailed in the documentation soon.

☑️ gbacpp will integrate evolutionary algorithms in the near future (see Roadmap).

☑️ A complete tutorial on GBA formalism is also available at https://cellgrowthsim.com/.

Table of contents

• 1) Roadmap
• 2) Contributing
• 3) Installation instructions
  • 3.1) Supported platforms
  • 3.2) Dependencies
  • 3.3) Installation
  • 3.4) Manual software compilation
• 4) First usage
  • 4.1) Why using a gradient ascent
  • 4.2) Code optimization
  • 4.3) Find an optimum
  • 4.4) Optimization parameters
• 5) SRC model format tutorial
• 6) Units conversion tutorial
• 7) Copyright
• 8) License

1) Roadmap

Task	Status
Gradient ascent (best for full column-rank SRC models with minimal support)
Reload/restart a gradient ascent
Improving gradient ascent stop criteria
Introducing second derivatives in gradient ascent
Handling ODS models
MCMC algorithm
Forward-in-time population level simulations
Lineage tracking

2) Contributing

If you wish to contribute, do not hesitate to reach the developer.

3) Installation instructions

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.

3.1) Supported platforms

gbacpp software has been primilary developed for Unix/Linux and macOS systems.

3.2) Dependencies

• 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/).

3.3) Installation

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_model_optimum should be available in the terminal. If not, you may need to export the binary path. For example:

export PATH="/usr/bin:$PATH"

Tip

If you want to simply compile the software without installing it into your system, follow the next instructions.

3.4) Manual software compilation

• User mode

To manually compile gbacpp, run the following instructions on the command line:

cd cmake/

and

bash make.sh

• Debug mode

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.

• Executable files emplacement

Binary executable files are in build/bin folder.

• Delete compiled files

To clean compiled files and binary executables, run:

bash make_clean.sh

4) First usage

Once gbacpp has been compiled and installed, follow the next steps for a first usage of the software.

4.1) Why using a gradient ascent

Optimizing SRC models is a non-linear constraint-based problem. Solving such a task in much more difficult than linear problems (e.g. FBA problems). A few solvers are available, and can usually handle small SRC models. However, we noticed that these solvers tend to fail when solving larger GBA problems, and are unable to handle genome-scale models.

As GBA formalism provides analytical solutions to calculate the growth rate gradient, we have implemented gbacpp to circumvent this limitation, allowing us to solve large, or even genome-scale SRC models in a reasonable timeframe.

4.2) Code optimization

The gradient ascent implemented here relies on $\dfrac{\partial \mu}{\partial f}$, the growth rate derivative against the flux fraction vector $f$. As presented in Dourado et al. (2023), analytical expressions are available to explicitely calculate these values, while it requires heavy linear algebra.

gbacpp combines two benefits of using C++. Compilers natively optimize calculations (e.g., using vectorization), and we could strongly optimize calculations and memory management. This approach makes gbacpp a fast solution.

4.3) Find an optimum

To run a gradient ascent optimization on a SRC model, execute the following command line:

find_model_optimum <parameters>

The command line parameters are described below. The description is also available by executing the following command line in a terminal:

find_model_optimum -h

4.4) Optimization parameters

• -h, --help: Print the help, then exit,
• -version, --version: Print the current version, then exit,

• Mandatory parameters

• -path, --model-path: Specify the path of the SRC model to be loaded,
• -name, --model-name: Specify the name of the SRC model to be loaded,
• -condition, --condition: Specify the external condition. If all is selected, all conditions are applied.

• Optional parameters

• -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 (⚠️ -verbose option should not be used),
• -optimum, --write-optimum: Indicates if the optimum should be written as output files,
• -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),
• -mutol, --mu-tolerance: Specify the relative growth rate difference tolerance value ($10^{-10}$ by default),
• -conv, --convergence-count: Specify the number of iterations under mu tolerance needed to assume convergence ($10,000$ by default),
• -max, --max-iter: Specify the maximal number of iterations as a stop criterium ($100,000,000$ by default),

• -previous, --use-previous-sol: Indicates if the solution of the previous condition should be used to initiate the next (only works when condition=all)
• -v, --verbose: Indicates if the program should run in verbose mode (can conflict with the option -print).
• -vv, --extra-verbose: Indicates if the program should run in extra-verbose mode (can conflict with the option -print).

5) SRC model format tutorial

A tutorial is available to better understand the content of a self-replicating cell model:

🔗 SRC model format tutorial

6) Units conversion tutorial

A tutorial is available for users starting from standard stoichiometric coefficients and kinetic parameters, and wanting to convert them into GBA formalism:

🔗 Units conversion tutorial

7) Copyright

Copyright © 2024-2025 Charles Rocabert.

8) License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.