CellEvoX

CellEvoX is a simulation system for modeling population dynamics, incorporating mutation types and probabilistic distributions. The project is designed with a modular and scalable architecture, leveraging modern C++ standards and libraries such as Qt6, TBB, and Eigen3 for high performance and ease of extensibility.

Visualization

CellEvoX is able to generate visualizations from existing runs:

3D Tumor Growth

2D Clone Growth

• clone_growth_2d.mp4 - an animated clone-growth view built from clone counts over time.
• tumor_growth_3d.mp4 - a spatial replay of the 3D tumor with clone colors.

Both outputs are written under visualizations/ inside the run directory.

Features

• Stochastic and Deterministic Simulation: Supports tau-leap simulation based on Gillespie's algorithm and provides extensibility for new methods.
• Entity-Component-System (ECS) Architecture: Decouples data and behavior for flexible simulation management.
• Mutation Modeling: Implements various mutation types with configurable probabilities and effects.
• Statistical Reporting: Generates detailed statistical snapshots, including mutation histograms and fitness distributions.
• Graphical User Interface (GUI): Developed using QML for real-time visualization and user-friendly interaction.
• Containerized Deployment: Ensures reproducibility and ease of deployment using Docker.

Requirements

• C++23 compatible compiler
• CMake 3.16 or higher
• Qt6 (Quick, QuickControls2, Qml, Core, Gui)
• Intel TBB
• Eigen3
• spdlog
• nlohmann_json
• Python3 with NumPy (for additional utilities)

Installation

Using Docker

1. Log in to GitHub Container Registry:

   docker login ghcr.io

2. Pull the Docker image:

   docker pull ghcr.io/dxrgrabowski/cellevox:main

3. Run the container:

   docker run -it ghcr.io/dxrgrabowski/cellevox:main

4. Follow the instructions of builing on source

Building Docker Image Locally

1. Clone the repository:

   git clone https://github.com/dxrgrabowski/cellevox.git
   cd cellevox

2. Build the Docker image:

   docker build -t cellevox:local .

3. Run the locally built container:

   docker run -it cellevox:local

4. Follow the instructions of builing on source

Building from Source

1. Create a build directory and run CMake:

   mkdir build && cd build
   cmake ..
   make

2. Run the program:

   ./bin/CellEvoX

Usage

1. Configure the simulation by editing the provided configuration file.
2. Run the simulation executable with --config pointing to config file localization.
3. View the generated data and statistical reports created in output directory specified in config. (Docker needs a write permission to output dir)

Recommended Python extras

The existing analysis scripts use matplotlib, numpy, pandas, and networkx. For the new 3D replay, pyvista is recommended but optional because the script falls back to a Matplotlib renderer when PyVista is unavailable.

Example:

pip install pandas networkx pyvista

For MP4 export, make sure ffmpeg is available in the environment. If it is missing, the scripts fall back to GIF output.

Run on an existing output directory

./bin/CellEvoX --analyze /path/to/run_dir

Run the visualization scripts manually

python CellEvoX/scripts/animate_clone_growth_2d.py --input /path/to/run_dir
python CellEvoX/scripts/visualize_tumor_3d.py --input /path/to/run_dir

File Structure

• include/: Header files defining core components.
• src/: Source files implementing the program logic.
• qml/: QML files for the GUI.
• build/: Directory for compiled binaries.

Contributing

Contributions are welcome! Please fork the repository and submit a pull request with your changes.

Contact

For questions or support, contact Dawid Grabowski at dxrsoftware@gmail.com.