SimuCell3D is a C++ cell-based simulation framework designed to simulate tissues in 3 dimensions with high geometrical resolution.
Windows users can manually install SimuCell3D on their machines via a Windows Linux Subsystem (WSL).
- GCC compiler at version 9 or higher
- CMake at version 3.0 or higher
1. Clone this git repository
git clone https://git.bsse.ethz.ch/iber/Publications/2024_runser_simucell3d.git
2. Create a build folder in the repository
mkdir path/to/SimuCell3D/build && cd "$_"
3. Compile the code
cmake -DCMAKE_BUILD_TYPE=Release .. && make -j4
- Docker
1. Clone this git repository
git clone https://git.bsse.ethz.ch/iber/Publications/2024_runser_simucell3d.git
cd path/to/SimuCell3D/
2. Create a docker image
docker build -t simucell3d_docker_img .
3. Create a folder to store the simulation results
mkdir -p simulation_results
SimuCell3D needs 2 input files to initialize the simulations:
1. A parameter file at the XML format (ex: path/to/SimuCell3D/parameters.xml)
2. An initial mesh geometry in the VTK format (ex: path/to/SimuCell3D/data/input_meshes/cube.vtk)
More information on the structure of these files can be found at here and here
cd path/to/SimuCell3D/build
./simucell3d path/to/parameter/file #ex: ./simucell3d ../parameters_default_dynamic.xml
The output files will be saved based on the output folder path specified in the parameter file.
docker run -it -v "$(pwd)/simulation_results":/app/simulation_results simucell3d_docker_img:latest ../parameters_default_dynamic.xml
In this second case, note that the parameter file path is relative to the build folder and only files in the repository can be accessed from the container. To add a file to the container, it must be added to the repository and then the container must be rebuilt. The simulation results will be saved in the simulation_results folder.
The output files of a simulation are structured in the following way:
.
|--
| |-- output_folder_path
| |-- simulation_statistics.csv
| |-- cell_data
| |-- result_0.vtk
| |-- result_1.vtk
| |-- ...
| |-- face_data
| |-- result_0.vtk
| |-- result_1.vtk
| |-- ...
| |-- ...
|...
The output folder path can be specified in the parameter.xml file.
The simulation _statistics.csv file contains simulation statistics such as the cell areas and volumes over time. More information on this file can be found here.
Finally, the cell_data and face_data folders contain meshes of the tissue at different iterations. The cell_data meshes can be used to visualize the cell attributes (ex: volume, pressure etc). Whereas, the face_data meshes are used to visualize the atributes of the faces of the cells (triangle area, adhesion energy etc).
Both type of meshes can be visualized with the rendering software Paraview.
Several tutorials have been added to this repository to explain how to launch simulations or edit the framework: