Try Online: CPlantBox Web App

Introduction

CPlantBox is a functional-structural plant model that is built in a modular way that can be used at several levels of complexity. CPlantBox describes the geometry of plants by their individual organs, such as roots, stems, and leaves, which evolve over time. It can model functional aspects such as water and carbon dynamics within the plant, and provides general tools to build plant soil-interaction models. To solve partial differential equations CPlantBox can use the finite volume solver DuMu^x and offers simplified Python interfaces in the repository dumux-rosi.

Installation

Python wheels

CPlantBox Python wheel support is being validated for Python 3.11+ on Linux and macOS. See doxygen/wheels.md for the current supported-platform matrix, local wheel build commands, and CI artifact usage.

Linux - with Python script

This installation method requires Ubuntu >= 20.04 and Python (>= 3.7, <3.14). For CPlantBox without dumux-rosi, download the Python file "installCPlantBox.py", and run it:

sudo apt-get update
sudo apt-get upgrade
[ ! -d 'cpbenv' ] && python3 -m venv cpbenv &&  source cpbenv/bin/activate ||  source cpbenv/bin/activate
wget https://raw.githubusercontent.com/Plant-Root-Soil-Interactions-Modelling/CPlantBox/master/installCPlantBox.py
python3 installCPlantBox.py

For CPlantBox with dumux-rosi, download and run the Python file "installDumuxRosi_Ubuntu.py" (the file is based on the DuMu^x installation file).

sudo apt-get update
sudo apt-get upgrade
[ ! -d 'cpbenv' ] && python3 -m venv cpbenv &&  source cpbenv/bin/activate ||  source cpbenv/bin/activate
wget https://raw.githubusercontent.com/Plant-Root-Soil-Interactions-Modelling/CPlantBox/master/installDumuxRosi_Ubuntu.py
python3 installDumuxRosi_Ubuntu.py

The script will install DuMu^x and CPlantBox, and CPlantBox is setup within the virtual environment 'cpbenv'. Activate the 'cpbenv' environment when using CPlantBox:

source cpbenv/bin/activate

By default, your local repository will only track the master branch. This allows for a quicker download and lower use of memory. In case you would like to switch between branches, you have two options:

1. Use the switch_branch.py script:

python3 switch_branch.py <branch_to_switch_to>

2. Install all the branches initially, by running

python3 installDumuxRosi_Ubuntu.py full

You can then change branch by doing

git checkout <branch_to_switch_to>

Linux - using a conda or Python environment

1. Clone the repository (master only) by

git clone --depth 1 -b master https://github.com/Plant-Root-Soil-Interactions-Modelling/CPlantBox.git

or, to download all branches:

git clone https://github.com/Plant-Root-Soil-Interactions-Modelling/CPlantBox.git

Initialize the repository by

cd CPlantBox
git submodule update --init --recursive

2. Create the an environment

For conda use

conda env create -f environment.yml
conda activate cpb

For Python use

python3 -m venv cpb
source cpb/bin/activate
pip install -r requirements.txt

Finally, initialize CMake and build and install CPlantBox:

cmake .
make install

3. Test the installation by running a tutorial example, e.g.:

cd tutorial/examples/
python example1a_small.py

Mac - with Python script

This installation method requires homebrew, Python (>= 3.7, <3.14) and clang (>=15, <=18). If you do not have a clang version within the given range, see the instruction on the Wiki.
For CPlantBox without dumux-rosi, download the Python file "installCPlantBox_Mac.py", and run it:

[ ! -d 'cpbenv' ] && python3 -m venv cpbenv &&  source cpbenv/bin/activate ||  source cpbenv/bin/activate
wget https://raw.githubusercontent.com/Plant-Root-Soil-Interactions-Modelling/CPlantBox/master/installCPlantBox_Mac.py
python3 installCPlantBox_Mac.py
source ~/.zshrc

For CPlantBox with dumux-rosi, download and run the Python file "installDumuxRosi_Mac.py" (the file is based on the DuMu^x installation file).

[ ! -d 'cpbenv' ] && python3 -m venv cpbenv &&  source cpbenv/bin/activate ||  source cpbenv/bin/activate
wget https://raw.githubusercontent.com/Plant-Root-Soil-Interactions-Modelling/CPlantBox/master/installDumuxRosi_Mac.py
python3 installDumuxRosi_Mac.py
source ~/.zshrc

The script will install DuMu^x and CPlantBox in the virtual environment 'cpbenv'. Activate the 'cpbenv' environment when using CPlantBox:

source cpbenv/bin/activate

NB: when running for the first time, 'import vtk' may take a long time.

Windows

CPlantBox is currently not available on windows. Some pointers to setup a Linux environment on windows are given on the wiki.

Installation on the JSC agrocluster

Please refer to the wiki

Folder sructure

/doxygen Code documentation
/modelparameter Plant parameter files
/src CPlantBox C++ codes
/test Python tests for all CPlantBox classes
/tutorial learn to use CPlantBox
/experimental Specific applications (in sub-folders). contrary to scripts in /tutorial, might not be kept up to date

Code documentation

Install doxygen and graphviz (for call graphs):

sudo apt install doxygen graphviz

Create the documentation by running doxygen from the doxygen/ folder:

cd doxygen/
doxygen Doxyfile

The HTML documentation will be written to doxygen/html/. Open doxygen/html/index.html in a browser to browse the documentation. Collaboration diagrams giving an overview of the code are in the doxygen/uml/ folder.

Online resources

WebApps

The official CPlantBox webapp helps to demonstrate the impact of various CPlantBox parameters and to analyse and explore the resulting 3D plant geometry.

Jupyter notebooks

Direct links to notebooks from the summer school of 2025:

1. Structure definition and analysis
2. Water flow in CPlantBox
3. Online repository

For the third repository, you need to go the folder dumux/CPlantBox/tutorial/jupyter/summer_school_2025 to access the notebooks.