cellular_raza - Agent-based Modeling from a Clean Slate

Jonas Pleyer

- Cellular Agent-based Modeling from a Clean Slate

04/06/2025

cellular Agent-based Modeling

from a Clean Slate

04/06/2025

Jonas Pleyer

<h2>Agent-based Modeling</h2>

- Model Individual Agents (i.e. biological cells)
            - Behaviour of individual agents $\Rightarrow$ Emergent collective phenomena
            - Describe spatial phenomena such as self-organization

---

<h2>Agent-based Modeling</h2>
            <div style="display: grid; grid-template-columns: 1fr 5fr 1fr;">
                <div class="fragment" data-fragment-index="1">
                    <br>
                    <br>
                    <img src="media/mechanics.png">
                </div>
                <div class="fragment" data-fragment-index="1"">

## Cellular Properties

| Property | Examples |
            |---|---|
            | Mechanics | Stochastic Motion, Chemotaxis |
            | Forces | Collision, Friction, Adhesion |
            | Intracellular Dynamics | Reaction Networks, Metabolics |
            | Cycle | Division, Death, Differentiation |

</div>
            <div></div>
            <div class="fragment" data-fragment-index="2">
                <br>
                <br>
                <img src="media/cells_at_iter_0000028000.png" style="border-radius: 10px;">
            </div>
            <div class="fragment" data-fragment-index="2">

## Domain Properties
            | Property | Examples |
            |---|---|
            | Physical Shape | Petri Dish, Mother-Machine |
            | <p style="width: 9em;">Fluid-Dynamics</p> | Diffusion, Flow |
            | Custom | External control of cells |

</div>
            <div></div>
            </div>

## Goals
            - Distinguish abstract `concepts` & implementation<br>
                $\Rightarrow$ Flexibility in model design
            - Fine-grained control over parameters
            - Combine predefined `building-blocks`
                - Allow users to construct their own
            - Multiple backends possible

</div>
                <div class="fragment">
                    Dependency structure
                    <img width="100%" src="media/cellular_raza-dependency-graph.png">
                </div>
            </div>

## Etymology

`cellular_raza` = cell + tabula rasa ("from a clean slate")

</div>

----

## Techniques

- Domain decomposition
              - Split simulation domain into multiple subdomains
              - Execute upate steps in parallel
              - Possible due to locality of interactions
            - Storage Manager
              - Export parts or store complete simulation
              - xml, json or sled (embedded) database

</div>
                <img src="media/spatial-decomposition-square-10.png">
            </div>

---

## High-Level Concepts = generic Traits

<p class="fragment" data-fragment-index="1">Physical Interaction</p>
            <p class="fragment" data-fragment-index="2">Cell Cycle</p>

```rust
            pub trait Interaction<Pos, Vel, Force, Inf = ()> {
                /// Exchange custom information between Agents
                fn get_interaction_information(&self) -> Inf;

/// Calculate forces acting between agents
                fn calculate_force_between(
                    &self,
                    own_pos: &Pos,
                    own_vel: &Vel,
                    ext_pos: &Pos,
                    ext_vel: &Vel,
                    ext_info: &Inf,
                ) -> Result<(Force, Force), CalcError>;
            }
            ```

$\Rightarrow$ Allows for Flexibility<br>
            $\Rightarrow$ Retains performance

</div>

</div>
            <div class="fragment" data-fragment-index="2">

```rust
            pub trait Cycle<Cell = Self, Float = f64> {
                /// Custom update function to modify the cell
                /// Returns event for Division, Death, etc.
                fn update_cycle(
                    rng: &mut ChaCha8Rng,
                    dt: &Float,
                    cell: &mut Cell,
                ) -> Option<CycleEvent>;

fn divide(
                    rng: &mut ChaCha8Rng,
                    cell: &mut Cell
                ) -> Result<Cell, DivisionError>;

fn update_conditional_phased_death(
                    rng: &mut ChaCha8Rng,
                    dt: &Float,
                    cell: &mut Cell,
                ) -> Result<bool, DeathError> {
                    Ok(true)
                }
            }
            ```

</div>
            </div>

----

## Mechanics
            ```rust
            pub trait Mechanics<Pos, Vel, For, Float = f64> {
              fn pos(&self) -> Pos;
              fn velocity(&self) -> Vel;
              fn set_pos(&mut self, pos: &Pos);
              fn set_velocity(&mut self, velocity: &Vel);
              fn calculate_increment(&self, force: For) -> Result<(Pos, Vel), CalcError>;
            }
            ```

| Name | Dim | | | Equations |
            | --- |:---:| ---:|:--- | --- |
            | `Brownian` | 1, 2, 3 | $\dot{\vec{x}}$ | $=$ | $-\frac{D}{k_B T}\nabla V(x) + \sqrt{2D}R(t)$ |
            | `Langevin` | 1, 2, 3 | $M \ddot{\mathbf{X}}$ | $=$ | $- \mathbf{\nabla} U(\mathbf{X})$ <br> $- \gamma M\dot{\mathbf{X}} + \sqrt{2 M \gamma k_{\rm B} T}\mathbf{R}(t)$ |
            | `NewtonDamped` | 1, 2, 3 | $m \ddot{\vec{x}}$ | $=$ | $\vec{F} - \lambda \dot{\vec{x}}$ |
            | `VertexMechanics` | 2 | | | <p style="color: rgba(250, 250, 250, 0.5);" >(Too much space needed)</p> |

----

## Forces
            ```rust
            pub trait Interaction<Pos, Vel, Force, Inf = ()> {

fn get_interaction_information(&self) -> Inf;

fn calculate_force_between(
                  &self,
                  own_pos: &Pos,
                  own_vel: &Vel,
                  ext_pos: &Pos,
                  ext_vel: &Vel,
                  ext_info: &Inf
              ) -> Option<Result<Force, CalcError>>;
            }
            ```

| Name | Dim | Equations |
            | --- |:---:|:---:|
            | `BoundLennardJones` | 1, 2, 3 | $U(r) = 4\epsilon\left[ \left(\frac{\sigma}{r}\right)^{12} - \left(\frac{\sigma}{r}\right)^6\right]$ <br> $V(r)=\min(U(r), \beta)\theta(r-\xi)$ |
            | `BacteriaReactions` | 2 | $\vec{z} = \vec{x_1} - \vec{x_2} \hspace{1cm} r = \|\|\vec{z}\|\|$ <br> $\sigma = \frac{r}{r_1+r_2} \hspace{1.375cm} q=0.2$ <br> $\vec{F} = \epsilon \frac{1+q}{q+\sigma} \theta(\sigma - 1) \frac{1}{r}\vec{z}$ |

----

## Cellular Reactions

```rust
            pub trait CellularReactions<CI, CE = CI> {
              fn get_intracellular(&self) -> CI;

fn set_intracellular(&mut self, concentration_vector: CI);

fn calculate_intra_and_extracellular_reaction_increment(
                  &self,
                  internal_concentration_vector: &CI,
                  external_concentration_vector: &CE
              ) -> Result<(CI, CE), CalcError>;
            }
            ```

| Name | Equations |
            | --- | --- |
            | `BacteriaReactions` | $\dot{V_c} = \frac{u}{1+\nu_I [I]} \sigma [R]V_c$ <br> $\dot{[R]} = \sum\limits_c -\frac{u}{1+\nu_I [I]} \frac{V_c}{V_D} [R] \delta(x-x_c) + D_R\Delta [R]$ <br> $\dot{[I]} = \sum\limits_c b\frac{V_c}{V_D}\delta(x-x_c) + D_I\Delta [I]$ |
            | `NoReactions` | |

----

## Cycle

```rust
              pub trait Cycle<Cell, Float = f64> {

fn update_cycle(
                    rng: &mut ChaCha8Rng,
                    dt: &Float,
                    cell: &mut Cell
                ) -> Option<CycleEvent>;

fn divide(
                    rng: &mut ChaCha8Rng,
                    cell: &mut Cell
                ) -> Result\<Cell, DivisionError>;
              ```

```rust
                // Default method
                // Can be overwritten
                fn update_conditional_phased_death(
                  rng: &mut ChaCha8Rng,
                  dt: &Float,
                  cell: &mut Cell
                ) -> Result<bool, DeathError> {
                  Ok(true)
                }
              }
              ```

</div>

Usually implemented individually for every new Cell-Agent.
            <div class="fragment">

### Example
              ```rust
              impl Cycle<Cell> for Cell {
                  fn update_cycle(rng: &mut ChaCha8Rng, dt: &f64, cell: &mut Cell) -> Option<CycleEvent> {
                      // Increase the current age of the cell
                      cell.current_age += dt;

// If the cell is older than the current age, return a division event
                      if cell.current_age > cell.maximum_age {
                          return Some(CycleEvent::Division)
                      }
                      None
                  }
                  // ...
              }
              ```

</div>

----

## Physical Domain

#### Domain

#### Subdomain

```rust
              pub trait Domain<C, S> {
                type SubDomainIndex;
                type VoxelIndex;

fn get_all_voxel_indices(
                  &self
                ) -> Vec<Self::VoxelIndex>;
              ```

```rust
              pub trait SubDomain<C> {
                type VoxelIndex;

fn get_voxel_index_of(
                    &self,
                    cell: &C
                ) -> Result<Self::VoxelIndex, BoundaryError>;
              ```

```rust
                fn decompose(
                  self,
                  n_subdomains: NonZeroUsize,
                  cells: Vec<C>
                ) -> Result<
                  DecomposedDomain<Self::SubDomainIndex, S, C>,
                  DecomposeError
                >
                  where S: SubDomain<C>;
              }
              ```
              ```rust
                fn get_neighbor_voxel_indices(
                  &self,
                  voxel_index: &Self::VoxelIndex
                ) -> Vec<Self::VoxelIndex>;

fn apply_boundary(
                  &self,
                  cell: &mut C
                ) -> Result<(), BoundaryError>;

fn get_all_indices(
                  &self
                ) -> Vec<Self::VoxelIndex>;
              }
              ```

</div>

| Name | Dim | Description |
            | --- |:---:| --- |
            | `CartesianCuboid` | 1, 2, 3 | Cuboid $[a_0, b_0] \times \dots \times [a_d, b_d] \sub \mathbb{R}^d$ <br> with reflective boundary conditions. |

---

## Working with cellular_raza

<h4 class="fragment" data-fragment-index="1">Derive Macros</h4>
            <h4 class="fragment" data-fragment-index="2">Running a Simulation</h2>

```rust
            // Custom derive macro allows to
            // re-use existing building blocks
            #[derive(
                CellAgent,
                Clone,
                Deserialize,
                Serialize
            )]
            struct Agent {
                #[Mechanics]
                mechanics: Langevin2D,
                #[Interaction]
                interaction: MorsePotential,
            }
            ```

```rust
            // Derive macro for domain
            #[derive(Domain)]
            struct DerivedDomain {
                #[Base]
                base: MyDomain,
            }
            ```

</div><div class="fragment" data-fragment-index="2">

```rust
            // Assign (individual) parameters to agents
            let cells = (0..n_cells).map(|n|
                Agent {
                    mechanics: Langevin2D {..},
                    interaction: MorsePotential {...},
                }
            );

// Set parameters for domain, time and storage
            let domain = CartesianCuboid::from_boundaries_and_n_voxels(..)?;
            let time = FixedStepsize::from_partial_save_interval(..)?;
            let storage = StorageBuilder::new();

let settings = Settings {
                n_threads,
                time,
                storage,
                show_progressbar: true,
            };

run_simulation!(
                domain: domain,
                agents: cells,
                settings: settings,
                aspects: [Mechanics, Interaction]
            )?;
            ```

</div>
            </div>