pip install gba
gbapy is a Python package that provides tools for building and analyzing self-replicating cell (SRC) models based on the growth balance analysis (GBA) mathematical formalism (Dourado et al. 2023). This approach, built exclusively on the first principles of fitness maximization, mass conservation, nonlinear reaction kinetics, and constant cell density, allows to study resource allocation in models of whole self-replicating cells (Dourado et al. 2025).
The module offers two core components:
- 🔧 A builder class, to construct SRC models of any size from first principles,
- 📈 A model class, to manipulate and optimize models once they are built.
Tip
Start by reading the complete description of GBA formalism, then follow the tutorials below to learn the required format:
- 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.
In this first step, you build the structure of a simple SRC model from scratch. The Builder object is used to declare the main biological entities of the system, define how they interact through reactions, and specify the external conditions that will later be tested during optimization.
from gba import Builder, Model, Protein, Metabolite, Reaction
from gba import SpeciesLocation, ReactionType, ReactionDirection
builder = Builder(name="toy")
### Add general information to the model (stored in the ODS sheet named 'Info')
builder.add_info(category="General", key="Name", content="toy")
builder.add_info(category="General", key="Description", content="Toy model")
### Create and add the proteins used by the enzymes in the model (one protein per enzyme):
### - Protein masses are given in Da.
p1 = Protein(id="p1", mass=1000000.0)
p2 = Protein(id="p2", mass=1000000.0)
builder.add_proteins([p1, p2])
### Create and add the metabolites used in the model:
### - x_G is external glucose
### - G is internal glucose
### - Protein is a generic protein product
### - Metabolite masses are given in Da
x_G = Metabolite(id="x_G", species_location=SpeciesLocation.EXTERNAL, mass=180.0)
G = Metabolite(id="G", species_location=SpeciesLocation.INTERNAL, mass=180.0)
Protein = Metabolite(id="Protein", species_location=SpeciesLocation.INTERNAL,mass=180.0)
builder.add_metabolites([x_G, G, Protein])
### Create a transport reaction that imports glucose into the cell:
### - The enzyme is composed of one protein p1
### - The reaction is irreversible
### - kcat values are given in 1/h
### - KM values are given in g/L
rxn1 = Reaction(id="rxn1", lb=0.0, ub=1000.0,
reaction_type=ReactionType.TRANSPORT,
metabolites={"x_G":-1.0, "G": 1.0},
proteins={"p1": 1.0})
rxn1.add_kcat_value(direction=ReactionDirection.FORWARD, kcat_value=45000.0)
rxn1.add_km_value(metabolite_id="x_G", km_value=0.00013)
rxn1.complete(kcat_value=0.0, km_value=0.0)
builder.add_reaction(rxn1)
### Create a ribosome-like reaction that uses internal glucose to produce protein:
### - The enzyme is composed of one protein p2
### - The reaction is irreversible
ribosome = Reaction(id="Ribosome", lb=0.0, ub=1000.0,
reaction_type=ReactionType.METABOLIC,
metabolites={"G":-1.0, "Protein": 1.0},
proteins={"p2": 1.0})
ribosome.add_kcat_value(direction=ReactionDirection.FORWARD, kcat_value=45000.0)
ribosome.add_km_value(metabolite_id="G", km_value=0.00013)
ribosome.complete(kcat_value=0.0, km_value=0.0)
builder.add_reaction(ribosome)
### Convert the model quantities to the GBA formalism (see Dourado et al. 2023)
builder.convert(ribosome_mass_kcat=4.55, ribosome_mass_km=8.3)
builder.build_GBA_model()
### Set the total cell density in g/L (here, the dry weight density)
builder.set_rho(340.0)
### Create a series of external conditions with decreasing external glucose concentration (g/L)
x_G_conc = 1.0
for i in range(25):
builder.add_condition(condition_id=str(i+1), metabolites={"x_G": x_G_conc})
x_G_conc *= 2/3
### Export the model to an ODS file
builder.export_to_ods()
In the second step, the exported ODS file is loaded back as a Model object so that numerical computations can be performed. The workflow first finds a feasible initial state, then solves the optimization problem for each glucose concentration.
from gba import read_ods_model
### Load the ODS model file created in the previous step
model = read_ods_model(name="toy")
### Find an initial feasible solution before running the optimization
model.find_initial_solution()
### Compute the optimal solution for each external condition
model.find_optimum_by_condition()
### Plot the growth rate mu as a function of external glucose concentration x_G
model.plot(x="x_G", y="mu", title="Growth rate", logx=True)
### Export the optimization results to a CSV file
model.export_optimization_data()
The final figure shows the predicted growth rate as a function of external glucose concentration.
The easiest way to install gbapy is from PyPI:
pip install gba
Important
gbacpp software is required to run optimization tasks.
gbapy has been primilary developed for Unix/Linux and macOS systems.
- gbacpp is required to run optimization tasks.
- The Python API of GUROBI optimizer must be installed and requires a user license (free for academics).
If you want to install gbapy manually, download the latest release, and save it to a directory of your choice. Open a terminal, navigate to the gbapy/ directory and run:
sh install.sh
Tip
You can later uninstall the module using sh uninstall.sh.
Documentation coming soon ...
If you wish to contribute, do not hesitate to reach the developer.
Copyright © 2024-2026 Charles Rocabert, Furkan Mert, Jérémie Muller-Prokob.
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/.