Quick-start guide for users

We will describe how to run a simulation with OpenSimRoot. First it is important to know how OpenSimRoot operates. OpenSimRoot takes as input an .xml file. This file contains the parameters for the simulation you want to run. This includes parameters like: The duration of the simulation, the environmental parameters, the initial root structure, the properties of the different types of roots etc. OpenSimRoot uses this data to run the simulation and then gives the output that the user has requested. This output can consist of aggregated variables, like the total root length, the amount of water/nitrogen depleted from the soil but OpenSimRoot can also put out files that, for example, contain the entire root structure at each day. This can be viewed by ParaView. As a sidenote, it is possible to specify an entire root structure (with the appropriate time parameters) which OpenSimRoot will then grow. This can be used to compare the simulated results to a real result.


First we choose an output directory. It is strongly advised you make separate directories for OpenSimRoot, the .xml files you will use as input and your output. While this requires you to enter slightly longer file paths in the terminal, your files will be much more organized. For example: In the parent directory of OpenSimRoot, create a directory called: "SimRootOutputs" with a subdirectory called: "OutputTest". In the parent directory, create a directory called "SimRootData" where you can store .xml files. In this example, there is a subdirectory in there called: "InputFiles" that contains the .xml we will run, runBean.xml. In the OpenSimRoot/OpenSimRoot/tests there are some .xml files that could be used as well.

Now use cd to move to the output directory, starting from the parent directory, this would be: cd SimRootOutputs/OutputTest. Now we will tell OpenSimRoot to open the file runBean.xml by executing:

../../OpenSimRoot/OpenSimRoot/StaticBuild/OpenSimRoot -f, ../../SimRootData/InputFiles/runBean.xml


The first part is the path to the OpenSimRoot executable. -ftells OpenSimRoot that we want to open a file. The last part is the path to the file we want to take as input.

After the simulation is complete, the "OutputTest" directory contains (depending on what was specified) files called tabled_output.tabwarnings.txt, some .vtu files and some .pvd files. The contains the values of variables like the nitrogen depletion, the dry weight of the plant and the total root length on each day. warnings.txt has an obvious meaning. The .vtu and .pvd files contain the geometric root model and can be visualized with ParaView.


To do this, open ParaView and open VisualizationRoots.pvd, then click "Apply" in the "Properties" window on the left. You will probably not see anything because at time t=0 there is no root structure yet! Click the "Play" button in the top bar and you will see the root structure as it is growing. By default, the root structure is uniformly colored so this only shows us the topology of the root system. To see more relevant information, in the properties window, under the header "Coloring", select something else instead of "Solid Color" to see the property you selected colored. By default, the "Color Space" option (in the "Color Map Editor" on the right) is set to "Diverging", I prefer RGB but see what suits you the best. You can choose a different color mapping and alter the sensitivity by adjusting the circles and curve in the "Mapping Data" section on the right. Double click on a circle in the bar at the bottom to choose a different color.