This repository implements numerical simulations and analysis pipelines for Generalized Lotka–Volterra (GLV) models, with applications to ecological dynamics.
The project combines:
- High-performance numerical solvers (C++)
- Model and orchestration layer (Python)
- Statistical analysis and visualization (R)
- Reproducible reporting (Quarto)
The goal is to provide a reproducible workflow from simulation to inference analysis and publication-quality results.
├── src/ # Core Python package
├── test/ # Unit tests
├── data/ # Input datasets (raw / external)
├── results/ # Intermediary results
├── docs/ # Project documentation and planning
├── Notebooks/ # Exploratory analysis
├── Prompts/ # AI prompts used in project
├── NumericalSolutions/ # High-performance numerical solvers (C++)
├── Synopsis/ # Quarto manuscript (methods, results, etc)
└── Bibliography/ # Bibliography used in project (only references, no pdfs)
git clone git@github.com:alfaceor/GLV.git
cd GLVCreate a conda environment (optional):
conda env create -f environment.yml
conda activate glvInstall package with pip
pip install -e .cd cpp
mkdir build && cd build
cmake ..
makeRun a simulation
glv-simulate outputdir=. run_name=expname
Run the full pipeline:
This project is designed to be reproducible:
- All figures in the paper are generated from scripts in
scripts/ - Intermediate results are stored in
results/ - No manual steps are required beyond running the pipeline
If results differ across systems, please check:
- Python/R versions
- Compiler version for C++
- Random seeds (TODO: specify where controlled)
Run a GLV simulation programmatically:
glv-simulate n_species=2 noise=all noise.std=0.5from theomodels.core import simulate
results = simulate(
params=TODO,
t_span=TODO
)Run unit tests with:
pytest -qThe full manuscript is located in:
Synopsis/
To render:
quarto render Synopsis/- Python: numpy, scipy, pandas, matplotlib
- R: TODO (list packages)
- C++: CMake, standard library (C++11+)
- Quarto (for report generation)
- Add stochastic simulations
- Improve parameter inference methods
- Integrate C++ solver with Python bindings
- Add CI for automated testing
- Improve documentation and examples
Contributions are welcome. Please:
- Open an issue to discuss changes
- Submit a pull request with clear description
- See CONTRIBUTING.md file
This project is licensed under the GLP v3 (see LICENSE file).
See Bibliography/GLV_references.bib for full bibliography.
Carlos Olivares
pip install -e .
To add noise to a single species
# Single species
glv-simulate noise=single noise.id=2 noise.std=0.5
To add noise to all species
# All particles
glv-simulate noise=all noise.std=0.5
To add stochastic noise to selected species
# Selected particles
glv-simulate noise=selected noise.selid='{0:0.1,3:0.9}' noise.default_std=0.5
The human gut microbiota consists of hundreds of interacting species, creating a high-dimensional system where the number of parameters in a Generalized Lotka-Volterra (GLV) model grows quadratically (
While traditional regression methods fail to capture the non-linearities and stochastic nature of these communities, modern machine learning tools like SINDy and Neural ODEs offer a potential solution, yet their performance on ecologically constrained systems remains untested.
This project will establish a comparative framework to determine which dimensionality-reduction and inference techniques best preserve the 'biological truth' of the system while maintaining predictive accuracy under perturbation.
Based on deterministic and stochastic simulations of a Generalized Lotka-Volterra system, determine the conditions to predict accurately the macroscopic ecological consequences of perturbations.
- How to encode this high-dimensional data. PCA, use autoenconders?
- simple regression
- Non-linear mixed effects
- Neural Networks
- SYNDy or MANDy?
- Graphical Neural Networks (GNN)
- Neural ODE
- Physics Informed Neural Network (PINN)
- GPINN?
Title: Benchmarking Sparse vs. Black-Box Inference for Gut Microbiota Stability.
Research Objective: To systematically compare the accuracy of SINDy (Sparse Identification of Non-linear Dynamics) and Neural ODEs in recovering the interaction coefficients (
Title: Physics-Informed Neural Networks (PINNs) for Predicting State Transitions in the Gut Microbiota. Research Objective: To develop a hybrid modeling framework that uses Autoencoders for dimensionality reduction and PINNs to simulate the macroscopic response of the gut microbiota to external perturbations (e.g., antibiotics or dietary shifts). Key Question: Can a reduced-order model effectively predict a "tipping point" or a loss of diversity without modeling every single rare species?
Title: Uncovering the Latent Dynamics of Microbial Ecology through Manifold Learning. Research Objective: To evaluate the effectiveness of Graph Neural Networks (GNNs) and Latent ODEs in encoding high-dimensional taxonomic data into a low-dimensional manifold that preserves the underlying Generalized Lotka-Volterra physics. Key Question: Does a latent-space representation of the microbiota provide a more stable prediction of long-term community equilibrium than species-level GLV models?
python simulate.py --multirun model=GLVdeterministic,GLVstochastic python prepare_data.py ... python train.py --multirun inference=nlme,neural_ode,GNN python evaluate.py
cd Synopsis quarto render report.qmd --to pdf
quarto render report.qmd --to pdf # fast, no HDF5 reads
quarto render report.qmd --to pdf # freeze:auto handles this
See CONTRIBUTING.md