Module chili

Available on crate feature chili only.

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.

prepare_types Defines types used in simulation
- build_aux_storage AuxStorage struct used to store intermediate values for update steps of aspects
- build_communicator Type which handles communication between threads
test_compatibility Test compatibility of all types involved
run_main Defines main loop and performs the simulation

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

Aspects	Function	Purpose
`Mechanics && Interaction`	update_mechanics_interaction_step_1	Send PosInformation between threads to get back ForceInformation
`DomainForce`	calculate_custom_domain_force	Uses the SubDomainForce trait to add custom external force.
`ReactionsContact`	update_contact_reactions_step_1	Sends ReactionsContactInformation between threads.
`ReactionsExtra`	update_reactions_extra_step_1	Sends ReactionsExtraBorderInfo between threads.
	sync	Wait for threads to have finished until proceeding.

§Step 2 - Calculate and Return

Aspects	Function	Purpose
`Mechanics && Interaction`	update_mechanics_interaction_step_2	Calculate forces and return ForceInformation to the original sender.
`ReactionsContact`	update_contact_reactions_step_2	Calculates the combined increment and returns ReactionsContactReturn
`ReactionsExtra`	update_reactions_extra_step_2	Returns ReactionsExtraBorderReturn

§Step 3 - Receive and Apply

Aspects	Function	Purpose
`Mechanics && Interaction`	update_mechanics_interaction_step_3	Receives the ForceInformation and adds within the `aux_storage`.
`ReactionsContact`	update_contact_reactions_step_3	Receives the ReactionsContactReturn and adds within the `aux_storage`.
`ReactionsExtra`	update_reactions_extra_step_3	Receives the ReactionsExtraBorderReturn.

§Pure Local Functions - Perform Update

Aspects	Function	Purpose
`Mechanics`	local_mechanics_update	Performs numerical integration of the position and velocity.
`Interaction`	local_interaction_react_to_neighbors	Performs changes due to neighbor counting.
`Cycle`	local_cycle_update	Advances the cycle of the cell. This may introduce aCycleEvent
`Reactions`	local_reactions_intracellular	Calculates increment from purely intracellular reactions.
`ReactionsContact`	local_update_contact_reactions	Performs the update of the contact reactions.
`ReactionsExtra`	local_subdomain_update_reactions_extra	Performs the update of the extracellular reactions.
`Reactions` \|\| `ReactionsContact` \|\| `ReactionsExtra`	local_reactions_use_increment	Calculates increment from purely intracellular reactions.

§Step 4 - Treat Cell Positions

Aspects	Function	Purpose
`Mechanics`	apply_boundary	Apply a boundary condition.
`Cycle`	update_cell_cycle_4	Performs cell-division and other cycle events.
`Mechanics`	sort_cells_in_voxels_step_1	Checks if cells need to be sent to different subdomain and sends them.

§Step 5 - Include new Cells

Aspects	Function	Purpose
`Mechanics`	sort_cells_in_voxels_step_2	Include 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§

pub use crate::storage::StorageError;

Macros§

aux_storage_constructor: Returns code which can be used to initialize a new empty AuxStorage.
build_aux_storage: Allows for the creation of a general AuxStorage struct which functions via the defined Update traits in the chili backend.
build_communicator: Automatically build communicator struct depending on simulation aspects.
communicator_generics_placeholders: Inserts as many blanks as generics were used to create the communicator struct by build_communicator!.
prepare_types: Prepare simulation types before executing the simulation via the run_main macro. Prepares communicator and auxiliary storage types with build_communicator! and build_aux_storage!.
run_main: Runs a with user-defined concepts. Assumes that types have been prepared with prepare_types!.
run_simulation: Performs a complete numerical simulation.
run_test_for_aspects: Run a particularly structured test multiple times for combinations of aspects
test_compatibility: Checks if defined types and concepts are compatible before actually executing the simulation.

Structs§

AuxStorageCycle: Stores intermediate information about the cell cycle.
AuxStorageInteraction: Helper storage for number of neighbors of Interaction trait.
AuxStorageMechanics: Stores intermediate information about the mechanics of a cell.
AuxStorageReactions: Helper storage for values regarding intracellular concentrations for the Reactions trait.
AuxStorageReactionsContact: Implementor of the UpdateReactionsContact trait.
BarrierSync: This very simple implementation uses the [hurdles::Barrier] struct which should in theory perform faster than the std::sync::Barrier struct from the standard library.
CellBox: Wrapper around the user-defined CellAgent
CellIdentifier: Unique identifier which is given to every cell in the simulation
ChannelComm: Sender-Receiver Communicator based on [crossbeam_channel].
DefaultHandler: Handles any error which is encountered and caught (i.e. no panics) during runtime.
ForceInformation: Return type to the requested PosInformation.
IndexError: Can occur internally when information is not present at expected place
PosInformation: Send about the position of cells between threads.
ReactionsContactInformation: This information will be sent from one cell to another to determine their combined reactions.
ReactionsContactReturn: This informatino is returned after receiving ReactionsContactInformation and delivers the increment.
ReactionsExtraBorderInfo: Carries information about the border given by the ReactionsExtra trait between subdomains.
ReactionsExtraBorderReturn: Return information of border value after having obtained the SubDomainReactions::BorderInfo
RingBuffer: A ring Buffer with constant size. Makes use of a fixed-size array internally.
RingBufferIter: Iterator of the RingBuffer struct.
RingBufferIterRef: Produced by the iter method of the RingBuffer.
SendCell: Send cell and its AuxStorage between threads.
Settings: Specify settings surrounding execution and storage
SimulationRunner: Intermediate object which gets consumed once the simulation is run
SimulationSetup: Struct containing all necessary information to construct a fully working simulation and run it.
StorageAccess: Gathers the StorageManager for cells and voxels of the previously run simulation
SubDomainBox: Encapsulates a subdomain with cells and other simulation aspects.
SubDomainPlainIndex: Identifier or subdomains
UDGraph: Undirected graph
Voxel: Stores information related to a voxel of the physical simulation domain.
VoxelPlainIndex: Identifier for voxels used internally to get rid of user-defined ones.

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§

construct_simulation_runner: Construct a new SimulationRunner from a given auxiliary storage and communicator object
local_cycle_update: Advances the cycle of a cell by a small time increment dt.
local_interaction_react_to_neighbors: Perform the Interaction::react_to_neighbors function and clear current neighbors.
local_mechanics_update: We assume that cells implement the Mechanics and Interaction traits. In this last step, all ForceInformation are gathered and used to update the cells positions and velocities.
local_reactions_intracellular: Calculates the increment from the Reactions trait.
local_reactions_use_increment: Ensures that intracellular increments have been cleared before the next update step.
local_subdomain_update_reactions_extra: Performs the increment operation.
local_update_contact_reactions: Updates the cells intracellular values from the obtained contact informations
mechanics_adams_bashforth_2: Two-step Adams-Bashforth method.
mechanics_adams_bashforth_3: Three-step Adams-Bashforth method.
mechanics_euler: Classical euler solver for the Mechanics trait.
reactions_contact_adams_bashforth_3rd: Calculates the increment introduced by the ReactionsContact aspect.
validate_map: Validates a given map.

Derive Macros§

AuxStorage: Derives the update traits UpdateCycle, UpdateMechanics, UpdateInteraction, UpdateReactions and UpdateReactionsContact
Communicator: Derives the Communicator trait.
FromMap: Derives the FromMap trait.

Module chiliCopy item path