Crate cellular_raza_concepts
source ·Expand description
This crate encapsulates concepts which govern an agent-based model specified by cellular_raza. To learn how to design your own concepts please refer to the cellular_raza book.
§Mechanics
Defines how to adjust position,force and velocity of the individual cells.
This concept is extremely central to every cell-agent since it defines the spatial representation of the cell which can be seen by other cells. This means that as long as all cells which should be included in the simulation can be represented by this shared trait, cellular_raza should be able to simulate them.
While a point of the simulation in general is not additive in the general theoretical formulation (due to boundaries for example), it is necessary to have an additive type to effectively use adaptive solvers. We thus need to check and apply boundary conditions independently.
§Interaction
Interactions can arise due to many different mechanisms. The following table shows a short summary of the possible traits which can be used. Some of them should not make sense to use in combination. An engine may chose to implement only certain traits while omitting others.
| Interaction Trait | Description |
|---|---|
| Interaction | Cells are interacting by forces which can have a range larger than the cell itself. Foe example, users can choose to implement their own repulsive and attractive forces. |
| [CellularReactions] | Intracellular reactions may be coupled to an extracellular environment. We can model these reactions via ODEs. |
§Cycle
The Cycle trait is responsible for the implementation of cycles and updates them incrementally.
The main update function is responsible for returning an optional cycle event.
These events can have different effects. For example a cell-division event triggers the
divide method. A mapping of events and functions is depicted in the table below.
| Event | Effect |
|---|---|
Division | The divide function returns (creates) a new cell and modifies the existing cell in-place. This means, that the user is responsible to make sure, that every field of the cell struct is modified correctly in order to simulate cell-division. |
PhasedDeath | The cell enters a dying process and is still continuously updated via update_conditional_phased_death. Once the corresponding function returns true the process is considered complete and the cell is removed. |
Remove | This event removes the cell from the simulation without any further actions. |
§Errors
For Backends it may be useful to define a singular error type (eg. SimulationError) which should be derivable from errors
arising during the simulation process.
It is required for custom error types MyCustomError of the engine to implement the From<MyCustomError> for SimulationError.
Errors should be separated by their ability to be recovered, ignored or handled otherwise.
Since this crate aims to provide an adaptive solving approach, it is desired to have a fallback
mechanism which can be called for errors which may arise due to precision problems.
The following table shows a summary of the errors currently supported. Backends need to be aware of them and implement custom handling schemes to overcome or work around them. Aborting the simulation is an option but must be documented well without introducing undefined behaviour.
| ErrorType | Possible Error Reasons |
|---|---|
| BoundaryError | Solver Accuracy, Domain Implementation bug, Internal engine error |
| CalcError | Solver Accuracy, Bug by user implementation of corresponding function, Internal engine error |
| Captures traits and types related to interactions between cells. |
§Plotting
Visualize components of the simulation directly via the plotters library.
Modules§
- Traits and types which will eventually replace the old Domain definition.
- Contains traits and types which specify cellular reactions specific to the [cpu_os_threads] backend.
Structs§
- Can occur during boundary calculation
- General Calculation Error
- A container struct containing meta-information of a given Cell Some variables such as id are not required and not desired to be initialized by the user. This CellAgentBox acts as a container around the cell to hold these variables.
- Error which occurs during sending, receiving or transmitting information between threads
- Occurs when incorrectly applying a controller effect
- Errors occurring during the final death step of a cell
- Generated by the decompose method. The backend will know how to deal with this type and crate a working simulation from it.
- Errors related to a cell dividing process
- Used to catch errors related to plotting
- Can occur internally when information is not present at expected place
- Ask the wrong object for information and receive this error
- Can occur when generating distributions or drawing samples from them.
- Occurs during setup of a new simulation
- Error related to advancing the simulation time or displaying its progress
Enums§
- Contains all events which can arise during the cell cycle and need to be communciated to the simulation engine (see also Cycle).
- Error during decomposition of a SimulationDomain into multiple subdomains
Traits§
- Creates a new plotting root which can then be drawn upon.
- This trait represents all cycles of a cell and works in tandem with the CycleEvent enum.
- Provides an abstraction of the physical total simulation domain.
- Generate SubDomains from an existing Domain
- Manage the current rng seed of a Domain
- Specifies how to retrieve a unique identifier of an object.
- Trait describing force-interactions between cellular agents.
- Setter and Getter for intracellular values of a cellagent.
- Describes the position of a cell-agent and allows to calculate increments and set/get information of the agent.
- Allows elements of the simulation such as cells and voxels to draw themselves onto a plotting root. Typically, voxels will draw first and cells afterwards.
- Methods for accessing the position of an agent.
- Describes purely intracellular reactions of a cellagent.
- TODO
- TODO
- Assign an VoxelIndex to a given cell.
- Subdomains are produced by decomposing a Domain into multiple physical regions.
- Apply a force on a cell depending on its position and velocity.
- Apply boundary conditions to a cells position and velocity.
- Describes extracellular reactions and fluid dynamics
- Methods for accessing the velocity of an agent
- Mathematical abstraction similar to the well-known
axpymethod.
Type Aliases§
- This is a unique identifier which is deterministic even in multi-threading situations. Its components are
Derive Macros§
- Derive cellular concepts
- This trait derives the different aspects of a SubDomain.