Help for CPlantBox developers

Rules for contributing

To limit the size of the repository, large files should not be added to the history of a branch. Therefore, it is recommended to not commit/add result files when commiting changes. You can do it by writing/putting all your result files in a result folder adding a 'gitignore' file in the parent folder, similar to the one in experimental/phloem_flow/for_dumuxRosi.
For security, changes cannot be pushed directly to the master and stable branches. The steps for pushing a change are:

• commit and add your changes: git add -A && git commit -m "Your Message"
• push you adapted branch to the repository under a new name to create a new branch: git push origin <your local branch name>:<temporary branch name for github>
• go on github and make a merge request from to the master branch
  At regular intervals, the master branch will be merged into a new stable branch that will be the new default branch for users.

Testing new modules

Once new modules have been added/existing modules have been modified, check for backward compatibility by running the scripts in the test folder. In the root folder run:
cd test
for f in *.py; do python3 "$f"; done This will launch all the test files.

Troubleshooting

If an error is thrown in the C++ core code while using the python wrapping, it might be easier to debug by running troubleshoot assistants for C++.

• install the gdb debugger
• open CPlantBox/CMakeLists.txt
• replace set(CMAKE_BUILD_TYPE Release) by set(CMAKE_BUILD_TYPE Debug) and #add_subdirectory(tutorial) by add_subdirectory(tutorial). Delete the CMakeCache.txt file and the two .so fies in the CPlantBox root folder. Re-compile CPlantBox.
• got to CPlantBox/tutorial/examples/old_cpp
• create a .cpp file based on the python script which threw the error. Use the pre-existing .cpp files as templates
• open CPlantBox/tutorial/examples/old_cpp/CMakeLists.txt
• replace add_executable(test test_plant.cpp) by add_executable(test <the name of your cpp file>.cpp)
• go back to the root folder and rebuild CPlantBox
• go back to CPlantBox/tutorial/examples/old_cpp
• run gdb test (or gdb --args executablename arg1 to pass commandline arguments) and then r. If an error occurs, send bt to do backtracking.

Compiling the sundial and suitsparse libraries

The PiafMunch phloem module requires the suitsparse and sundial libraries. Those libraries are already compiled and the header files are in the 'CPlantBox/src/external' folder. In case it becomes necessary to re-compile the libraries, follow the instructions below to install the libraries in '/usr/local'. You can then either copy-paste the necessary libraries and headers from '/usr/local' to 'CPlantBox/src/external' or change the install path.

Using CPlantBox without installing

In case you do not wish to run make install after building CPlantBox, you can add the code snippet below atthe beginning of the Python files to run the examples:

import types
import importlib
import os
import sys
SRC_PATH = "../../src/"
sys.path.append("../.."); sys.path.append(SRC_PATH)
plantbox = types.SimpleNamespace()

for name in os.listdir(SRC_PATH):
    folder_path = os.path.join(SRC_PATH, name)
    if os.path.isdir(folder_path) and not name.startswith('__'):
        try:
            module = importlib.import_module(name)
            setattr(plantbox, name, module)
            sys.modules[f'plantbox.{name}'] = module
        except ModuleNotFoundError:
            pass

suitsparse (5.3.0)

To compile suitspares, you might need to install first its dependencies. Thus, run:

sudo apt install libopenblas-dev

Then download the zip folder containing suitsparse from https://github.com/DrTimothyAldenDavis/SuiteSparse/releases/tag/v5.3.0 Note that the full compilation of the whole SuiteSparse package is not required: PiafMunch requires the SuiteSparseConfig, BTF, AMD, COLAMD and KLU (1.3.9) libraries only. After unzipping and going into the SuiteSparse root folder, run:

cd GraphBLAS/build ; cmake .. ; make 
cd ../build ; sudo make install
cd ../..
make library
sudo make install INSTALL=  /usr/local

sundials (4.0.2)

Download sundials from: https://github.com/m-giraud/sundials4.0.2_bu or from: https://github.com/LLNL/sundials Then run:

sudo apt install cmake-curses-gui
ccmake -S. -BBuild

This will open a GUI where you can manually adapt the CMake options. Set the following install paths and options: ==> KLU_lib : /usr/local/lib ==> KLU_include: /usr/local/include ==> CMAKE_C_FLAG: -fPIC Then, press 'g' to generate and exit. Then, run:

cmake --build Build
cd ../Build
sudo make install

The header files and libraries are at /usr/local/lib, /usr/local/include. You do not need all the libraries and header files of SuitSparse and Sundials. Compile and paste the ones which have the same name as those in 'src/external/suitsparse' and 'src/external/sundials'.