API

Microbe{D,N,B} <: AbstractMicrobe{D,N}

Microbe type of MicrobeAgents.jl. D is the space dimensionality, N the number of motile states, B the type of the behaviors container (inferred, never written by hand).

Fields:

• id::Int identifier used internally
• pos::SVector{D,Float64} position
• vel::SVector{D,Float64} unit direction of motion
• speed::Float64 sampled speed of the current motile state (see speed)
• motility::Motility{N} motility pattern
• rotational_diffusivity::Float64 = 0.0 rotational diffusion coefficient
• radius::Float64 = 0.0 equivalent spherical radius
• behaviors::B = () Tuple or NamedTuple of behaviors (see Behavior)

position(m::AbstractMicrobe)

Return the position of the microbe.

direction(m::AbstractMicrobe)

Return the direction versor of the microbe.

speed(m::AbstractMicrobe)

Return the speed of the microbe: the speed sampled from its current motile state, times the speed_factor of all its behaviors.

speed(motility::Motility)

Return the speed distribution of the current motile state.

velocity(m::AbstractMicrobe)

Return the velocity vector of the microbe (direction times speed).

motilepattern(m::AbstractMicrobe)

Return the motile pattern of the microbe.

rotational_diffusivity(m::AbstractMicrobe)

Return the rotational diffusivity of the microbe.

radius(m::AbstractMicrobe)

Return the radius of the microbe.

state(motility::Motility)

Return the index of active motile state.

motilestate(microbe)

Return the current motile state of microbe.

state(motility::Motility)

Return the list of all motile states.

transition_weights(motility::Motility, i::Integer)

Return the transition weights from the state with index i towards the other motile states.

duration(motility::Motility)

Return the average unbiased duration of the current motile state.

distance(a, b, model)

Evaluate the euclidean distance between a and b respecting the boundary conditions of the model

distancevector(a, b, model)

Evaluate the distance vector from a to b respecting the boundary conditions of the model.

random_speed(microbe, model)

Generate a random speed from the motile pattern of microbe.

random_velocity(model)

Generate a random velocity vector with unit norm respecting the dimensionality of model.

AbstractChemicalField{D}

Abstract type for chemoattractants. Requires dimensionality (D) to be specified. Number type is always assumed to be Float64.

The interface is defined by five core functions:

• chemoattractant: returns the chemoattractant object
• concentration: returns the function for the concentration field
• gradient: returns the function for the concentration gradient
• time_derivative: returns the function for the concentration ramp
• chemoattractant_diffusivity: returns the thermal diffusivity of the chemoattractant

ChemicalField{D} <: AbstractChemicalField{D}

Type for a generic chemical field. Field, gradient and ramp default to 0 everywhere in the domain. Diffusivity defaults to 608 μm²/s everywhere in the domain. (Do not use 0 here, it may mess up some calculations)

chemoattractant(model)

Returns the chemoattractant object from model.

concentration(model)

Returns the function f that defines the concentration field. The returned function has signature f(pos, model) and returns a scalar.

gradient(model)

Returns the function f that defines the gradient of the concentration field. The returned function has signature f(pos, model) and returns a SVector with the same dimensionality as the microbe position pos.

time_derivative(model)

Returns the function f that defines the time derivative of the concentration field. The returned function has signature f(pos, model) and returns a scalar.

chemoattractant_diffusivity(model)

Returns the thermal diffusivity of the chemoattractant compound.

Obstacles(space, primitives; contact = Halt(), margin = nothing, cellsize = nothing)

Static set of solid primitives (a vector of one concrete AbstractObstacle type) in space, whose surfaces interact with microbes through the contact rule (Halt(), Slide(), Reflect(), Randomize() or a function, see contact!). Pass a Tuple of sets as the :obstacles model property. A set is indexed and iterated as its primitives: obstacles(model)[c.set][c.index] is the primitive involved in a contact c (or returned by nearest_surface). Obstacles are ignored by pathfinder_step!: pathfinding and obstacles are not meant to be used together.

Bounded primitives are indexed in a static cell list. cellsize (default: twice the largest bounding radius) and margin (default: half the cell size) only affect performance; queries are fastest when margin exceeds the microbe radius plus the distance travelled in one step.

Walls(space; contact = Halt())

Obstacles made of one ObstacleHalfSpace per side of each non-periodic dimension of space: the domain boundaries.

AbstractObstacle{D}

Supertype of solid primitives in D dimensions, collected into Obstacles.

Required method: sdf(p, x). Optional, to enable spatial indexing: MicrobeAgents.center(p) and MicrobeAgents.boundingradius(p) (a ball enclosing the solid; default radius Inf, i.e. not indexed). Optional: MicrobeAgents.surface_normal(p, x) (default: finite differences of sdf) and MicrobeAgents.isconvex(::Type{<:MyObstacle}) = true for convex solids (exact collisions; non-convex solids are resolved approximately).

ObstacleSphere(center, radius)

Solid sphere (disk in 2D, segment in 1D).

ObstacleHalfSpace(point, normal)

Solid half-space bounded by the plane through point; normal points away from the solid. Unbounded, hence never spatially indexed.

ObstacleBox(lo, hi)

Solid axis-aligned box with opposite corners lo and hi.

ObstacleCapsule(a, b, radius)

Solid capsule: all points within radius of the segment from a to b (rods, fibres).

ObstacleSDF(f, center, boundingradius = Inf; convex = false)

Solid defined by an arbitrary signed distance function f(x::SVector{D}) -> Real (negative inside; it must not overestimate the distance to the surface). center and boundingradius define a ball enclosing the solid, used for spatial indexing (Inf: not indexed). Set convex = true only if the solid is convex: collisions with convex solids are exact, while non-convex solids are found by ray marching, which may miss features thinner than 1% of the larger of the microbe radius and the step length, and leaves shallow overlaps (removed at the end of the step) when sliding along concave parts (prefer unions of convex primitives). Normals are computed by finite differences.

sdf(p::AbstractObstacle, x)

Signed distance from point x to the surface of p (negative inside the solid).

surface_normal(p::AbstractObstacle, x)

Outward unit normal of the surface of p nearest to x (gradient of sdf). Default: central finite differences of sdf.

SurfaceContact{D}

Contact event passed to contact!. Fields:

• set::Int: index of the obstacle set in obstacles(model)
• index::Int: index of the primitive within the set
• point::SVector{D,Float64}: contact point on the surface
• normal::SVector{D,Float64}: outward unit normal of the surface
• displacement::SVector{D,Float64}: displacement still to perform in this step

contact!(rule, microbe, contact::SurfaceContact, model) -> SVector

Apply the contact rule of an obstacle set when microbe touches its surface. Returns the displacement still to perform in the current step; the rule may also modify the microbe (direction, speed, motile state, ...). A plain function used as rule is called as rule(microbe, contact, model).

Halt()

Contact rule: the microbe stops at the surface for the rest of the step, keeping its direction (it leaves once its direction points away from the surface).

Slide(; align = false)

Contact rule: the microbe moves along the surface (normal component of the displacement removed). With align = true the microbe stays on the surface and keeps its direction tangent to it, following curved surfaces along geodesics (straight lines on the surface), until it is reoriented away from the surface.

Reflect()

Contact rule: specular reflection of direction and displacement on the surface.

Randomize()

Contact rule: the microbe takes a random direction, uniformly distributed away from the surface, and continues along it.

obstacles(model)

Returns the Tuple of Obstacles sets of model.

nearest_surface(microbe, model; cutoff = Inf) -> (; distance, normal, set, index)
nearest_surface(x, model; cutoff = Inf)

Closest obstacle surface to microbe (or to point x) within cutoff: distance from the microbe surface (center distance minus radius(microbe)), outward normal, index of the obstacle set in obstacles(model) and of the primitive (index) in the set. distance = Inf (and indices 0) if there is none. In per-step behaviors pass a finite cutoff: with cutoff = Inf the query may visit every cell of the obstacle index.

random_free_position(model; radius = 0.0, maxtries = 10_000)

Random position in the domain at distance ≥ radius from all obstacle surfaces (outside all obstacles). Throws an error after maxtries rejected samples.

adf_to_matrix(adf, sym)

Collect quantity sym from the agent dataframe adf and return it in matrix form with dimensions (times, microbes). Requires all microbes to exist from start to end of the simulations (no removals or insertions).

adf_to_vectors(adf, sym)

Collect quantity sym from the agent dataframe adf and return a vector of such quantity for each microbe id.

unfold(x::AbstractVector, P)

Unfold timeseries x from a periodic domain extending from 0 to P.

unfold(x1::Real, x0::Real, P::Real)

Unfold the value of x1 with respect to x0 from a domain of periodicity P.

unfold!(adf, model; key=:position)
unfold!(adf, extent; key=:position)
unfold!(gdf, model; key=:position)
unfold!(gdf, extent; key=:position)

Unfold the periodic trajectories contained in the agent dataframe adf or in the grouped dataframe gdf where each microbe trajectory was grouped by :id. The second argument can be either the spatial extent of the model, or the model itself from which the extent is automatically extracted.

The keyword argument key=:position determines what column of the dataframe has to be unfolded.

unfold!(x::AbstractVector, P)

Unfold timeseries x from a periodic domain extending from 0 to P. The periodicity P can be either a real number (for a cubic domain) or a collection (AbstractVector or NTuple) with one value for each dimension.

detect_turns!(adf; threshold_angle=0.0, kwargs...)

Detect reorientations in the microbe trajectories in adf. Requires adf to have a velocity column. In order to be detected, a reorientation must be larger than the threshold_angle (in radians); the threshold defaults to 0.

A new column is added to the dataframe, with values true when the microbe has turned with respect to the previous frame, or false otherwise.

Keywords

• vel_key::Symbol = :velocity: name of the column containing microbe velocities
• new_key::Symbol = :has_turned: name of the new column storing turn statistics

run_durations(adf; turns_key=:has_turned)

Evaluate the duration (in frames) of all runs detected during a simulation. The dataframe should already contain a column of Bools with values true for frames when a turn has occurred and false otherwise (see detect_turns!). The function returns a vector of run durations for each microbe.

turns_key defines the name of the column where the turn statistics is stored (defaults to :has_turned).

driftvelocity_point!(adf, target; normalize=false, kwargs...)
driftvelocity_point!(gdf, target; normalize=false, kwargs...)

Evaluate the drift velocity of microbes towards a target point, extracting their positions and velocities from the agent dataframe adf or from the grouped dataframe gdf (grouped by :id). Requires the existence of columns containing the position and velocity of microbes. By convention the drift velocity will be positive for motion towards the target point.

Keywords

• normalize = false: whether drift velocities should be normalized by the instantaneous speed of the microbes
• pos_key::Symbol = :position: name of the column containing microbe positions
• vel_key::Symbol = :velocity: name of the column containing microbe velocities

driftvelocity_direction!(adf, target; normalize=false, kwargs...)
driftvelocity_direction!(gdf, target; normalize=false, kwargs...)

Evaluate the drift velocity of microbes along a target direction, extracting their positions and velocities from the agent dataframe adf or from the grouped dataframe gdf (grouped by :id). Requires the existence of a column containing the velocity of microbes. By convention the drift velocity will be positive for motion along the target directoin.

Keywords

• normalize = false: whether drift velocities should be normalized by the instantaneous speed of the microbes
• vel_key::Symbol = :velocity: name of the column containing microbe velocities