cellular_raza_core::backend

Module chili

Source
Expand description

🌶️ A modular, reusable, general-purpose backend

§Usage

In the following example, we provide an extremely short basic usage of the run_simulation macro. It performs the numerical integration of a well-defined problem. We assume that the MyAgent struct and MyDomain have already been defined and implement the Mechanics concept. More details about how to use pre-existing building blocks or derive their functionality is provided by the cellular_raza_building_blocks crate. We will then solve our system for the Mechanics aspect.

// Initialize agents, domain, solving time and how to store results
let agents = (0..10).map(|n| MyAgent {
        /* Define the agent's properties */
    });
let domain = MyDomain {/* Define the domain*/};
let time = FixedStepsize::from_partial_save_interval(t0, dt, tmax, save_interval)?;
let storage = StorageBuilder::new().priority([StorageOption::Memory]);

// Group them together
let settings = Settings {
    n_threads,
    time,
    storage,
    show_progressbar: false,
};

// This will perform the numerical simulation
let storage_access = run_simulation!(
    agents: agents,
    domain: domain,
    settings: settings,
    aspects: [Mechanics],
    core_path: cellular_raza_core,
)?;

// Use calculated results
let history = storage_access.cells.load_all_elements()?;
for (iteration, cells) in history {
    // ...
}

This example cannot contain all the functionality which the chili backend provides. We encourage the user to look at the cellular-raza.com/guides and cellular-raza.com/showcase sections to get started.

§Internals

The chili backend uses procedural macros to generate code which results in a fully working simulation. The methods, functions and objects used in this way are formualted with generics. This enables us to write general-purpose solvers for a wide range of problems. The most important macro is the run_simulation macro which can be solely used to run simulations. This macro itself can be broken down into smaller pieces.

These macros take a subset of keyword arguments of the run_simulation macro. The arguments are documented under the run_simulation macro.

§Main Loop

The run_main macro constructs the main loop of the simulation. It inserts functions depending on the given simulation aspects. They can be grouped into 6 steps Below, we show a list of all these functions and their corresponding aspects.

§Step 1 - Send Information

In this step, each sub

AspectsFunctionPurpose
Mechanics && Interactionupdate_mechanics_interaction_step_1Send PosInformation between threads to get back ForceInformation
DomainForcecalculate_custom_domain_forceUses the SubDomainForce trait to add custom external force.
ReactionsContactupdate_contact_reactions_step_1Sends ReactionsContactInformation between threads.
ReactionsExtraupdate_reactions_extra_step_1Sends ReactionsExtraBorderInfo between threads.
syncWait for threads to have finished until proceeding.
§Step 2 - Calculate and Return
AspectsFunctionPurpose
Mechanics && Interactionupdate_mechanics_interaction_step_2Calculate forces and return ForceInformation to the original sender.
ReactionsContactupdate_contact_reactions_step_2Calculates the combined increment and returns ReactionsContactReturn
ReactionsExtraupdate_reactions_extra_step_2Returns ReactionsExtraBorderReturn
§Step 3 - Receive and Apply
AspectsFunctionPurpose
Mechanics && Interactionupdate_mechanics_interaction_step_3Receives the ForceInformation and adds within the aux_storage.
ReactionsContactupdate_contact_reactions_step_3Receives the ReactionsContactReturn and adds within the aux_storage.
ReactionsExtraupdate_reactions_extra_step_3Receives the ReactionsExtraBorderReturn.
§Pure Local Functions - Perform Update
AspectsFunctionPurpose
Mechanicslocal_mechanics_updatePerforms numerical integration of the position and velocity.
Interactionlocal_interaction_react_to_neighborsPerforms changes due to neighbor counting.
Cyclelocal_cycle_updateAdvances the cycle of the cell. This may introduce aCycleEvent
Reactionslocal_reactions_intracellularCalculates increment from purely intracellular reactions.
ReactionsContactlocal_update_contact_reactionsPerforms the update of the contact reactions.
ReactionsExtralocal_subdomain_update_reactions_extraPerforms the update of the extracellular reactions.
Reactions || ReactionsContact || ReactionsExtralocal_reactions_use_incrementCalculates increment from purely intracellular reactions.
§Step 4 - Treat Cell Positions
AspectsFunctionPurpose
Mechanicsapply_boundaryApply a boundary condition.
Cycleupdate_cell_cycle_4Performs cell-division and other cycle events.
Mechanicssort_cells_in_voxels_step_1Checks if cells need to be sent to different subdomain and sends them.
§Step 5 - Include new Cells
AspectsFunctionPurpose
Mechanicssort_cells_in_voxels_step_2Include newly received cells into correct subdomains.

§Return Type

After the simulation is done, we return a StorageAccess struct to interoperate with stored results.

Re-exports§

Macros§

Structs§

Enums§

  • CycleEvent
    Contains all events which can arise during the cell cycle and need to be communciated to the simulation engine (see also Cycle).
  • DecomposeError
    Error during decomposition of a SimulationDomain into multiple subdomains
  • HandlingStrategy
    Contains handling strategies for errors which can arise during the simulation process.
  • SimulationError
    Covers all errors that can occur in this Simulation The errors are listed from very likely to be a user error from almost certainly an internal error.

Traits§

  • BuildFromGraph
    Construct a BTreeMap of the type from a graph
  • Communicator
    Handles communications between different simulation processes.
  • DefaultFrom
    Used to construct initial (empty) AuxStorage variants.
  • ErrorHandler
    Handle any error which may occur as specified by SimulationError
  • FromMap
    Constructs a collection of Items from a map (graph)
  • SyncSubDomains
    Responsible for syncing the simulation between different threads.
  • UpdateCycle
    Trait which describes how to store intermediate information on the cell cycle.
  • UpdateInteraction
    Interface to store intermediate information about interactions.
  • UpdateMechanics
    Used to store intermediate information about last positions and velocities. Can store up to N values.
  • UpdateReactions
    Interface to store intermediate information about cellular reactions.
  • UpdateReactionsContact
    Used to update properties of the cell related to the ReactionsContact trait.
  • Xapy
    Mathematical abstraction similar to the well-known axpy method.

Functions§

Derive Macros§