API

mutable struct ABM

Basic structure which contains the user defined parmeters of the model, the user rules of the agents, both in high level definition and the functions already compiled.

Elements

Constructors

function ABM()

Generates an empty instance of ABM to be filled.

function ABM(
    dims;

    agent=OrderedDict{Symbol,DataType}(),
    agentRule::Expr=quote end,
    agentODE::Expr=quote end,
    agentSDE::Expr=quote end,

    model=OrderedDict{Symbol,DataType}(),
    modelRule::Expr=quote end,
    modelODE::Expr=quote end,
    modelSDE::Expr=quote end,

    medium=OrderedDict{Symbol,DataType}(),
    mediumRule::Expr=quote end,
    mediumODE::Expr=quote end,
    mediumSDE::Expr=quote end,

    baseModelInit::Vector{ABM}=ABM[],
    baseModelEnd::Vector{ABM}=ABM[],

    agentAlg::Union{CustomIntegrator,DEAlgorithm} = CBMIntegrators.Euler(),
    agentSolveArgs::Dict{Symbol,Any} = Dict{Symbol,Any}(),

    modelAlg::Union{CustomIntegrator,DEAlgorithm} = CBMIntegrators.Euler(),
    modelSolveArgs::Dict{Symbol,Any} = Dict{Symbol,Any}(),

    mediumAlg::Union{CustomIntegrator,DEAlgorithm} = DifferentialEquations.AutoTsit5(DifferentialEquations.Rosenbrock23()),
    mediumSolveArgs::Dict{Symbol,Any} = Dict{Symbol,Any}(),

    neighborsAlg::Neighbors = CBMNeighbors.Full(),       
    platform::Platform = CPU(),     
)

Generates an agent based model with defined parameters and rules.

For a more extense explanation of how to define rules and parameters, read Usage in the documentation.

macro addAgentCode(arguments)

Macro that returns the special code based on the arguments provided to addAgent.

macro removeAgent()

Macro that returns the special code based on the arguments provided to removeAgent().

macro loopOverNeighbors(code)
macro loopOverNeighbors(it1, code)

Macro that creates the loop function to go over all neighbors of the agent.

It can be declared as

@loopOverNeighbors for iterator in ___
    #code
end

or

@loopOverNeighbors iterator begin
    #code
end

for some iterator symbol. It can only be used in agent rules or DEs.

macro ∂(coord,code)

Discretizes the code term of a drift process. e.g. Agent in 2D

∂(1,m) → (m[i1-1,i2]-m[i1-1,i2])/(2*dx)

the coordinate must be 1, 2 or 3, specifing the axis of differentiation.

macro ∂2(coord,code)

Discretizes the code term of a drift process. e.g. Agent in 2D

∂2(1,m) → (m[i1-1,i2]-2*m[i1,i2]+m[i1-1,i2])/dx^2

the coordinate must be 1, 2 or 3, specifing the axis of differentiation.

macro mediumInside()

Macro that returns true if mesh position is not in the border of the region.

mediumBorder(coord, border)

Macro that returns true if mesh position is in the lower (border=-1) or upper (border=1) border of the axis coordinate 1, 2 or 3.

Basic structure keeping the parameters of all the agents in the current simulation of a model.

Parameters to store information essential for Community simulation

Parameters seen in the kernels that may de used directly by the user

Parameters seen in the kernels that are for internal use

Constructors

function Community()

Creates fully empty community. Auxiliar method for the following method of declaration for the users.

function Community(
    abm::ABM; 

    dt::Union{Nothing,AbstractFloat} = nothing,
    t::AbstractFloat = 0.,
    N::Int = 1,
    id::AbstractArray{Int} = 1:N,
    NMedium::Union{Nothing,Vector{<:Int}} = nothing,
    simBox::Union{Nothing,Matrix{<:Number}} = nothing,

    args...
)

Function to construct a Community that accepts to provide integration algorithms, neighboring algorithms, the computing platform and setting parameters of the community.

For a more specific indication of the usage see the UserGuide.

function loadToPlatform!(com::Community;preallocateAgents::Int=0)

Function that converts the Community data into the appropiate format to be executed in the corresponding platform. It locks the possibility of accessing and manipulating the data by indexing and propety. If preallocateAgents is provided, it allocates that additional number of agents to the community. Preallocating is necesssary as if more agents will be added during the evolution of the model (Going over the number of preallocated agents will run into an error.).

function bringFromPlatform!(com::Community)

Return the Community object from the platform where it is being evolved. It locks the possibility of accessing and manipulating the data by indexing and propety.

function evolve!(community;
    steps,saveEach=1,
    saveToFile=false,fileName=nothing,overwrite=false,
    saveCurrentState=false,
    preallocateAgents=0,
    progressMessage=(com)->nothing)

Performs step number of steps on the community, saving each saveEach number of steps the community instance using the saving function provided in saveFunction (See IO). If saveCurrentState is true, the present instance is saved.

preallocateAgents is an integer to sent to the loadToPlatform! function that allocates empty space for agents if the model has to grow. The maximum number of agents in the final simulation has to be specified in here.

progressMessage is a function that is executed every time we save an step and can be used to print some information of progress.

function step!(community)

Executes all the possible step functions and updates the parameters a single time.

function agentStepRule!(community)

Function that computes a local step of the community a time step dt.

function agentStepDE!(community)

Function that computes a integration step of the community a time step dt using the defined Integrator defined in Agent.

function agentStepRule!(community)

Function that computes a local step of the community a time step dt.

function modelStepDE!(community)

Function that computes a integration step of the community a time step dt using the defined Integrator defined in Agent.

function agentStepRule!(community)

Function that computes a local step of the community a time step dt.

function mediumStepDE!(community)

Function that computes a integration step of the community a time step dt using the defined Integrator defined in Agent.

function update!(community)

Function that updates all the parameters after making a step in the community.

function saveRAM!(community::Community)

Function that stores the present configuration of community in the field Community.pastTimes.

saveJLD2(file::String, community::Community; overwrite=false)

Save in file the current instance of the community. If some other community was being saved here, an error will raise. If overwrite=true is specified, it will remove the previous community.

function loadJLD2(file::String)

Load the Community structure saved in file.

euclidean(x1,x2)
euclidean(x1,x2,y1,y2)
euclidean(x1,x2,y1,y2,z1,z2)

Euclidean distance metric between two positions.

d = (x₁-x₂)²

macro euclidean(it2)
macro euclidean(it1,it2)

Macro that given the iterator symbos it1 and it2, give the corresponding euclidean distanve in the correct dimentions. If it1 is not provided it asumes the default iteration index of agents (i1_).

manhattan(x1,x2)
manhattan(x1,x2,y1,y2)
manhattan(x1,x2,y1,y2,z1,z2)

Manhattan distance metric between two positions.

d = |x₁-x₂|

macro manhattan(it2)
macro manhattan(it1,it2)

Macro that given the iterator symbos it1 and it2, give the corresponding manhattan distanve in the correct dimentions. If it1 is not provided it asumes the default iteration index of agents (i1_).

function cellInMesh(edge,x,xMin,xMax,nX)

Give the integer position in a regular discrete mesh with poits separamtions of edge, given a position in x. The simulation domain being (xMin, xMax) and maximum number of mesh points nX.

e.g Grid with 6 points at [0,.1,.2,.3,.4,.5]

>>> cellInMesh(.1,.29,0.,.5,6)
4

which if the closest point in the mesh.

function intersection2lines(x1,y1,theta1,x2,y2,theta2,inf_eff=100000)

Finds the point of intersection of two lines. You have to provide a point in space and and angle for eachline: (x1,y1,theta1) and (x2,y2,theta2).

If the lines are parallel, it returns a point effectively in the infinite. The effective distance is described by inf_eff`.

Returns the point of intersection.

function point2line(x1,y1,x2,y2,theta2)

Given a point (x1,x2), finds the closest point projected over a line described by a point in the line and the angle: (x2,y2,theta2).

Returns the coordinates of the closest point over the line.

function pointInsideRod(x1,y1,l1,theta1,pxAux,pyAux,separation)

Given a line segment described by it central point (x1,y1), its angle in the plate theta1 and its length l1; and given a point over the save line (pxAux,pyAux), returns the point if inside the segment or the closes extreme of the segment. If provided a separation (0,1), it moves the point that separation.

Returns the coordinates of the closest point over the segment.

function rodIntersection(x1,y1,l1,theta1,x2,y2,l2,theta2;separation=0.99)

Given a two line segment described by it central point (x1,y2), its angle in the plate theta1 and its length l1; finds the closest spheres of both segments.

Returns the coordinates of the closest spheres (x1Aux,y1Aux), (x2Aux,y2Aux).

normal(μ,σ)

Normal distribution radom generation. μ mean, σ std.

uniform(l0,l1)

Uniform distribution radom generation. l0 min, l1 max.

exponential(θ)

Exponential distribution radom generation. θ mean.

" mutable struct CPU <: Platform

CPU platform structure.

" mutable struct GPU <: Platform

CPU platform structure.

Threads and blocks for each rule method

• agentThreads
• agentBlocks
• modelThreads
• modelBlocks
• mediumThreads
• mediumBlocks

mutable struct Euler <: CustomIntegrator

Euler integrator for ODE problems.

mutable struct Heun <: CustomIntegrator

Heun integrator for ODE problems.

mutable struct RungeKutta4 <: CustomIntegrator

RungeKutta4 for ODE integrators

mutable struct EM <: CustomIntegrator

Euler-Majurana integrator for SDE poblems.

mutable struct EulerHeun <: CustomIntegrator

Euler-Heun method for SDE integration.

mutable struct Full <: Neighbors

Method that computes all against all neighbors.

mutable struct VerletTime <: Verlet <: Neighbors

Method that computes VerletList neighbors and updates it at fixed times.

Constructor

function VerletTime(;skin,dtNeighborRecompute,nMaxNeighbors)

mutable struct VerletTime <: Verlet <: Neighbors

Method that computes VerletList neighbors and updates it whenever an agent moves too far from the initial position

Constructor

function VerletDisplacement(;skin,nMaxNeighbors)

mutable struct CellLinked <: Neighbors

Method that computes Cell Linked neighbors and updates it whenever an agent moves too far from the initial position

Constructor

function CellLinked(;cellEdge)

mutable struct CLVD <: Verlet <: Neighbors

Method that computes Cell Linked and Verlet Displacement neighbors algorithms together to compute neighbors and only recompute when they left very far from center.

Constructor

function CLVD(;skin,nMaxNeighbors,cellEdge)

function gridSearch(evalFunction::Function,  
    searchList::Dict{Symbol,<:Vector{<:Number}}; 
    returnAll::Bool=false,
    saveFileName::Union{Nothing,String} = nothing,
    args::Vector{<:Any} = Any[],
    verbose=false)

Function that evaluates a grid of parameter configurations for a model.

function swarmAlgorithm(evalFunction::Function,  
    searchList::Dict{Symbol,<:Union{<:Tuple{<:Number,<:Number},Vector{<:Number}}};
    population::Int=100,
    weightInertia::Number = .1,
    weightGlobalBest::Number = .1, 
    weightPopulationBest::Number = .1, 
    stopMaxGenerations::Int = 10,
    initialisation::Union{Nothing,DataFrame} = nothing,
    returnAll::Bool = false,
    saveFileName::Union{Nothing,String} = nothing,
    args::Vector{<:Any} = Any[],
    verbose=false)

Optimization of the parameter space of a model that uses the Swarm Algorithm.

function beeColonyAlgorithm(
    evalFunction::Function, 
    searchList::Dict{Symbol,<:Tuple{<:Number,<:Number}}; 
    population::Int=100,
    limitCycles::Int = 10,
    stopMaxGenerations::Int = 100,
    returnAll::Bool = false,
    initialisation::Union{Nothing,DataFrame} = nothing,
    saveFileName::Union{Nothing,String} = nothing,
    args::Vector{<:Any} = Any[],
    verbose=false)

Optimization of the parameter space of a model that uses the Bee Colony Algorithm.

function geneticAlgorithm(
    evalFunction::Function,  
    searchList::Dict{Symbol,<:Union{<:Tuple{<:Number,<:Number},Vector{<:Number}}};
    population::Int=100,
    parentSelectionAlg::String = "weighted", #weighted or random
    parentSelectionP::Number = .1, 
    mutationRate::Number = .1, 
    stopMaxGenerations::Int = 10,
    initialisation::Union{Nothing,DataFrame} = nothing,
    returnAll::Bool = false,
    saveFileName::Union{Nothing,String} = nothing,
    args::Vector{<:Any} = Any[],
    verbose=false)

Optimization of the parameter space of a model that uses the Particle Swarm Algorithm.

function plotRods2D!(ax, x, y, d, l, angle; kargs...)

Plot rod shape like cells using Makie functions.

function plotRods2D!(ax, x, y, xs1, ys1, xs2, ys2, markerSphere, markerCylinder, angle; kargs...)

Plot rod shape like cells using Makie functions. This method is useful to make videos of cells.