Midterm code push (#1)

* all work I have done untill the midterm: tumor replicated from the nature paper including forces and diffusion modules

* car-t oxygen consumption

* Update README.md

Co-authored-by: Vassil Vassilev <[email protected]>

* Update src/cart_cell.cc

Co-authored-by: Vassil Vassilev <[email protected]>

* still in progress CAR-T displacement

* cleaned comments to follow Doxygen-style

* changed comments to follow doxygen-style

* Remove draft_code_my_own_analysis/ from tracking and add to .gitignore

* remove draft_code_my_own_analysis

* add to gitignore draft_code_my_own_analysis

* fixing comments

* [ci] Add basic github actions infrastructure

* Update CMakeLists.txt

Co-authored-by: Vassil Vassilev <[email protected]>

* Update README.md

Co-authored-by: Vassil Vassilev <[email protected]>

* Update README.md

Co-authored-by: Vassil Vassilev <[email protected]>

* Update src/cart_cell.cc

use *Simulation::GetActive()->GetResourceManager() just once

Co-authored-by: Vassil Vassilev <[email protected]>

* Update src/cart_cell.cc

Co-authored-by: Vassil Vassilev <[email protected]>

* Update src/forces_tumor_cart.cc

Co-authored-by: Vassil Vassilev <[email protected]>

* changed some things to imporve code quality

* cart_cell comments fixed

* changed all comments to /// in the .h and changed some of them

* changed the project name + new readme part Results

* minor change spelling

* 30-days simulation

---------

Co-authored-by: Vassil Vassilev <[email protected]>

Author: salva24

CMakeLists.txt

@@ -14,6 +14,7 @@
 cmake_minimum_required(VERSION 3.19.3)
 project(cart_tumor)
 
+
 # BioDynaMo curretly uses the C++17 standard.
 set(CMAKE_CXX_STANDARD 17)
 

README.md

@@ -14,8 +14,10 @@ The simulation integrates computational modeling and biological insights to expl
 3. [Installation](#installation)
 4. [Building the Simulation](#building-the-simulation)
 5. [Running the Simulation](#running-the-simulation)
-6. [Acknowledgments](#acknowledgments)
-7. [License](#license)
+6. [Visualizing Results](#results)
+7. [Acknowledgments](#acknowledgments)
+8. [License](#license)
+
 
 ---
 
@@ -49,7 +51,8 @@ By adjusting biological and therapeutic parameters, the model enables **in silic
 Clone the repository:
 ```bash
 git clone https://github.com/compiler-research/CARTopiaX.git
-cd cart_tumor
+cd CARTopiaX
+
 ```
 
 ---
@@ -85,7 +88,20 @@ biodynamo run
 **Option 2:**  
 Directly from the build directory:
 ```bash
-./build/cart_tumor
+
+./build/CARTopiaX
+```
+
+---
+
+## Results
+
+Data about tumor growth and diffrent types of cell populations is output in ./output/final_data.csv
+
+To visualize the results in paraview use:
+```bash
+paraview ./output/CARTopiaX/CARTopiaX.pvsm
+
 ```
 
 ---

src/cart_cell.cc

@@ -38,6 +38,7 @@ CartCell::CartCell(const Real3& position) {
   SetNuclearVolume(kDefaultVolumeNucleusCartCell);
 
 
+
   ResourceManager &rm = *Simulation::GetActive()->GetResourceManager();
   // Pointer to oxygen diffusion grid
   oxygen_dgrid_ = rm.GetDiffusionGrid("oxygen");
@@ -64,7 +65,9 @@ CartCell::CartCell(const Real3& position) {
 
 // Cart cells can move if they are alive and not attached to a tumor cell
 bool CartCell::DoesCellMove() {
+
   return (state_ == CartCellState::kAlive && !attached_to_tumor_cell_); 
+
 }
 
 
@@ -135,11 +138,13 @@ Real3 CartCell::CalculateDisplacement(const InteractionForce* force,
   squared_radius=kSquaredMaxDistanceNeighborsForce;
 
   // the physics force to move the point mass
+
   Real3 translation_velocity_on_point_mass{0, 0, 0};
 
   // We check for every neighbor object if they touch us, i.e. push us
   // away and agreagate the velocities
 
+
   uint64_t non_zero_neighbor_forces = 0;
   if (!IsStatic()) {
     auto* ctxt = Simulation::GetActive()->GetExecutionContext();
@@ -161,53 +166,11 @@ Real3 CartCell::CalculateDisplacement(const InteractionForce* force,
     }
   }
 
+
   // Two step Adams-Bashforth approximation of the time derivative for position
   // position(t + dt) ≈ position(t) + dt * [ 1.5 * velocity(t) - 0.5 * velocity(t - dt) ]
   movement_at_next_step += translation_velocity_on_point_mass * kDnew + older_velocity_ * kDold;
 
-  //Debug
-    //     std::ofstream file1("output/movement_at_next_step.csv", std::ios::app);
-    // if (file1.is_open()) {
-
-    //   // Calculate time in days, hours, minutes
-    //   double total_minutes = Simulation::GetActive()->GetScheduler()->GetSimulatedTime();
-    //   // Write data to CSV file
-    //   file1
-    //    << "minute"<<total_minutes << ","
-    //    <<"translation_velocity_on_point_mass"<< translation_velocity_on_point_mass[0]<< ","
-    //    << translation_velocity_on_point_mass[1] << ","
-    //    << translation_velocity_on_point_mass[2] << ","
-    //    << "kDnew" << kDnew << ","
-    //    << "older_velocity_" << older_velocity_[0] << ","
-    //     << older_velocity_[1] << ","
-    //     << older_velocity_[2] << ","
-    //    << "kDold" << kDold << "\n";
-    // }
-
-  //Debug Output forces
-    // std::ofstream file("output/forces.csv", std::ios::app);
-    // if (file.is_open()) {
-      
-    //   // Calculate time in days, hours, minutes
-    //   double total_minutes = Simulation::GetActive()->GetScheduler()->GetSimulatedTime();
-    //   double modulus_total_displacement = movement_at_next_step[0] * movement_at_next_step[0] +
-    //                                      movement_at_next_step[1] * movement_at_next_step[1] +
-    //                                      movement_at_next_step[2] * movement_at_next_step[2];
-    //   modulus_total_displacement = std::sqrt(modulus_total_displacement);
-    //   Real3 position = GetPosition();
-    //   // Write data to CSV file
-    //   file 
-    //    << total_minutes << ","
-    //     << position[0] << ","
-    //    << position[1] << ","
-    //    << position[2] << ","
-    //    << movement_at_next_step[0] << ","
-    //    << movement_at_next_step[1] << ","
-    //    << movement_at_next_step[2] << ","
-    //    << modulus_total_displacement << "\n";
-    // }
-    // End Debug Output
-
   older_velocity_ = translation_velocity_on_point_mass;
 
   // Displacement

src/cart_cell.h

@@ -30,31 +30,22 @@
 
 namespace bdm {
 
-
-/**
- * @brief Enumeration defining the possible states of a CAR-T cell
- * 
- * This enum class represents the different states that a CAR-T cell can be in
- * during its lifecycle in the simulation.
- */
+/// Enumeration defining the possible states of a CAR-T cell
+/// 
+/// This enum class represents the different states that a CAR-T cell can be in
+/// during its lifecycle in the simulation.
 enum class CartCellState : int {
-  /** @brief Living cell state - the cell is alive and functioning normally */
-  kAlive=0,
+  kAlive=0,///< Living cell state - the cell is alive and functioning normally
 
-  /** @brief Apoptotic phase - the cell is undergoing programmed cell death
-   *  characterized by cell shrinkage and controlled death
-   */
-  kApoptotic=1
+  kApoptotic=1///< Apoptotic phase - the cell is undergoing programmed cell death characterized by cell shrinkage and controlled death
 };
 
-/**
- * @brief CAR-T cell class implementation
- * 
- * This class represents a CAR-T (Chimeric Antigen Receptor T-cell) in the simulation.
- * It inherits from the base Cell class and includes specific behaviors and properties
- * related to CAR-T cell biology, including states, volume dynamics, and interactions
- * with tumor cells.
- */
+/// CAR-T cell class implementation
+/// 
+/// This class represents a CAR-T (Chimeric Antigen Receptor T-cell) in the simulation.
+/// It inherits from the base Cell class and includes specific behaviors and properties
+/// related to CAR-T cell biology, including states, volume dynamics, and interactions
+/// with tumor cells.
 class CartCell : public Cell {
   BDM_AGENT_HEADER(CartCell, Cell, 1);
 
@@ -113,134 +104,118 @@ class CartCell : public Cell {
   /// Returns the diffusion grid for immunostimulatory factors
   DiffusionGrid* GetImmunostimulatoryFactorDiffusionGrid() const { return immunostimulatory_factor_dgrid_; }
 
-  /** @brief Change volume using exponential relaxation equation
-   * 
-   * This method explicitly solves the system of exponential relaxation differential
-   * equations using a discrete update step. It is used to grow or shrink the volume
-   * (and proportions) smoothly toward a desired target volume over time. The relaxation
-   * rate controls the speed of convergence and dt=1 (the time_step).
-   * 
-   * @param relaxation_rate_cytoplasm Relaxation rate for cytoplasm volume changes
-   * @param relaxation_rate_nucleus Relaxation rate for nucleus volume changes
-   * @param relaxation_rate_fluid Relaxation rate for fluid volume changes
-   */
+  /// Change volume using exponential relaxation equation
+  /// 
+  /// This method explicitly solves the system of exponential relaxation differential
+  /// equations using a discrete update step. It is used to grow or shrink the volume
+  /// (and proportions) smoothly toward a desired target volume over time. The relaxation
+  /// rate controls the speed of convergence and dt=1 (the time_step).
+  /// 
+  /// @param relaxation_rate_cytoplasm Relaxation rate for cytoplasm volume changes
+  /// @param relaxation_rate_nucleus Relaxation rate for nucleus volume changes
+  /// @param relaxation_rate_fluid Relaxation rate for fluid volume changes
   void ChangeVolumeExponentialRelaxationEquation(real_t relaxation_rate_cytoplasm, real_t relaxation_rate_nucleus, real_t relaxation_rate_fluid);
 
-  /** @brief Calculate displacement of the cell
-   * 
-   * Computes the displacement of the cell based on interaction forces.
-   * 
-   * @param force Pointer to the interaction force object
-   * @param squared_radius The squared radius of the cell
-   * @param dt The time step for the simulation
-   * @return The calculated displacement vector
-   */
+  /// Calculate displacement of the cell
+  /// 
+  /// Computes the displacement of the cell based on interaction forces.
+  /// 
+  /// @param force Pointer to the interaction force object
+  /// @param squared_radius The squared radius of the cell
+  /// @param dt The time step for the simulation
+  /// @return The calculated displacement vector
   Real3 CalculateDisplacement(const InteractionForce* force,
                               real_t squared_radius, real_t dt) override;
 
-  /** @brief Consume or secrete substances
-   * 
-   * Computes new oxygen or immunostimulatory factor concentration after
-   * consumption or secretion by the cell.
-   * 
-   * @param substance_id The ID of the substance (oxygen or immunostimulatory factor)
-   * @param old_concentration The previous concentration of the substance
-   * @return The new concentration after consumption/secretion
-   */
+  /// Consume or secrete substances
+  /// 
+  /// Computes new oxygen or immunostimulatory factor concentration after
+  /// consumption or secretion by the cell.
+  /// 
+  /// @param substance_id The ID of the substance (oxygen or immunostimulatory factor)
+  /// @param old_concentration The previous concentration of the substance
+  /// @return The new concentration after consumption/secretion
   real_t ConsumeSecreteSubstance(int substance_id, real_t old_concentration);
 
-  /** @brief Compute constants for consumption and secretion
-   * 
-   * Updates constants after the cell's change of volume or quantities.
-   * These constants are used in the consumption/secretion differential equations.
-   */
+  /// Compute constants for consumption and secretion
+  /// 
+  /// Updates constants after the cell's change of volume or quantities.
+  /// These constants are used in the consumption/secretion differential equations.
   void ComputeConstantsConsumptionSecretion();
 
-
- /** @name Private Member Variables
-  *  @brief Private attributes of the CAR-T cell
-  *  @{
-  */
  private:
-  /** @brief Current state of the CAR-T cell */
+  /// Current state of the CAR-T cell
   CartCellState state_;
 
-  /** @brief Timer to track time in the current state (in minutes)
-   *  Used for apoptotic state timing
-   */
+  /// Timer to track time in the current state (in minutes)
+  /// Used for apoptotic state timing
   int timer_state_;
 
-  /** @brief Pointer to the oxygen diffusion grid */
+  /// Pointer to the oxygen diffusion grid
   DiffusionGrid* oxygen_dgrid_;
 
-  /** @brief Pointer to the immunostimulatory factor diffusion grid */
+  /// Pointer to the immunostimulatory factor diffusion grid
   DiffusionGrid* immunostimulatory_factor_dgrid_;
 
-  /** @brief Flag indicating if the cell is attached to a tumor cell */
+  /// Flag indicating if the cell is attached to a tumor cell
   bool attached_to_tumor_cell_;
 
-  /** @brief Current time until apoptosis */
+  /// Current time until apoptosis
   real_t current_live_time_;
 
-  /** @brief Fluid fraction of the cell volume */
+  /// Fluid fraction of the cell volume
   real_t fluid_fraction_;
 
-  /** @brief Volume of the nucleus */
+  /// Volume of the nucleus
   real_t nuclear_volume_;
 
-  /** @brief Target cytoplasm solid volume for exponential relaxation
-   *  Used during volume changes following exponential relaxation equation
-   */
+  /// Target cytoplasm solid volume for exponential relaxation
+  /// Used during volume changes following exponential relaxation equation
   real_t target_cytoplasm_solid_;
 
-  /** @brief Target nucleus solid volume for exponential relaxation */
+  /// Target nucleus solid volume for exponential relaxation
   real_t target_nucleus_solid_;
 
-  /** @brief Target fluid fraction for exponential relaxation */
+  /// Target fluid fraction for exponential relaxation
   real_t target_fraction_fluid_;
 
-  /** @brief Target relation between cytoplasm and nucleus volumes */
+  /// Target relation between cytoplasm and nucleus volumes
   real_t target_relation_cytoplasm_nucleus_;
 
-  /** @brief Velocity of the cell in the previous time step */
+  /// Velocity of the cell in the previous time step
   Real3 older_velocity_;
 
-  /** @brief Rate of oxygen consumption by the cell */
+  /// Rate of oxygen consumption by the cell
   real_t oxygen_consumption_rate_;
 
-  /** @brief Rate of immunostimulatory factor secretion by the cell */
+  /// Rate of immunostimulatory factor secretion by the cell
   real_t immunostimulatory_factor_secretion_rate_;
 
-  /** @brief Constant 1 for oxygen consumption/secretion differential equation solution */
+  /// Constant 1 for oxygen consumption/secretion differential equation solution
   real_t constant1_oxygen_;
 
-  /** @brief Constant 2 for oxygen consumption/secretion differential equation solution */
+  /// Constant 2 for oxygen consumption/secretion differential equation solution
   real_t constant2_oxygen_;
 
-  /** @brief Pointer to the attached tumor cell */
+  /// Pointer to the attached tumor cell
   TumorCell* attached_cell_;
 
-  /** @} */ // end of Private Member Variables group
 };
 
-/**
- * @brief Behavior class for controlling CAR-T cell state transitions
- * 
- * This behavior handles the state control logic for CAR-T cells, managing
- * transitions between different cell states such as alive and apoptotic phases.
- * It inherits from the base Behavior class and implements the Run method to
- * execute the state control logic during simulation steps.
- */
+/// Behavior class for controlling CAR-T cell state transitions
+/// 
+/// This behavior handles the state control logic for CAR-T cells, managing
+/// transitions between different cell states: alive and apoptotic phases.
+/// It inherits from the base Behavior class and implements the Run method to
+/// execute the state control logic during simulation steps.
 struct StateControlCart : public Behavior {
   BDM_BEHAVIOR_HEADER(StateControlCart, Behavior, 1);
 
   StateControlCart() { AlwaysCopyToNew(); }
 
   virtual ~StateControlCart() {}
 
-  /** @brief Execute the state control behavior
-   *  @param agent Pointer to the agent (cell) on which to apply the behavior
-   */
+  /// Execute the state control behavior
   void Run(Agent* agent) override;
 };