# Integrating Agents.jl with CellListMap.jl

This example illustrates how to integrate Agents.jl with CellListMap.jl, to accelerate the computation of short-ranged (within a cutoff) interactions in 2D and 3D continuous spaces. CellListMap.jl is a package that allows the computation of pairwise interactions using an efficient and parallel implementation of cell lists.

## The system simulated

The example will illustrate how to simulate a set of particles in 2 dimensions, interacting through a simple repulsive potential of the form:

\[U(r) = k_i k_j\left[r^2 - (r_i+r_j)^2\right]^2~~~\textrm{for}~~~r \leq (r_i+r_j)\]

\[U(r) = 0.0~~~\textrm{for}~~~r \gt (r_i+r_j)\]

where $r_i$ and $r_j$ are the radii of the two particles involved, and $k_i$ and $k_j$ are constants associated to each particle. The potential energy function is a smoothly decaying potential with a maximum when the particles overlap.

Thus, if the maximum sum of radii between particles is much smaller than the size of the system, cell lists can greatly accelerate the computation of the pairwise forces.

Each particle will have different radii and different repulsion force constants and masses.

`using Agents`

Below we define the `Particle`

type, which represents the agents of the simulation. The `Particle`

type, for the `ContinuousAgent{2,Float64}`

space, will have additionally an `id`

and `pos`

(position) and `vel`

(velocity) fields, which are automatically added by the `@agent`

macro.

```
@agent struct Particle(ContinuousAgent{2,Float64})
r::Float64 # radius
k::Float64 # repulsion force constant
mass::Float64
end
PropParticle(; vel, r, k, mass) = (vel, r, k, mass)
```

`PropParticle (generic function with 1 method)`

## Required and data structures for CellListMap.jl

We will use the high-level `ParticleSystem`

interface (requires version ≥0.9.0):

`using CellListMap`

Two auxiliary arrays will be created on model initialization, to be passed to the `ParticleSystem`

data structure:

`positions`

:`CellListMap`

requires a vector of (preferentially) static vectors as the positions of the particles. To avoid creating this array on every call, a buffer to which the`agent.pos`

positions will be copied is stored in this data structure.`forces`

: In this example, the property to be computed using`CellListMap.jl`

is the forces between particles, which are stored here in a`Vector{<:SVector}`

, of the same type as the positions. These forces will be updated by the`map_pairwise!`

function.

Additionally, the computation with `CellListMap.jl`

requires the definition of a `cutoff`

, which will be twice the maximum interacting radii of the particles, and the geometry of the the system, given by the `unitcell`

of the periodic box. For non-periodic systems, use `unitcell = nothing`

.

More complex output data, variable system geometries and other options are supported, according to the CellListMap user guide.

## Model initialization

We create the model with a keyword-accepting function as is recommended in Agents.jl. The keywords here control number of particles and sizes.

```
function initialize_bouncing(;
number_of_particles=10_000,
sides=SVector(500.0, 500.0),
dt=0.001,
max_radius=10.0,
parallel=true
)
# initial random positions
positions = [sides .* rand(SVector{2,Float64}) for _ in 1:number_of_particles]
# We will use CellListMap to compute forces, with similar structure as the positions
forces = similar(positions)
# Space and agents
space2d = ContinuousSpace(sides; periodic=true)
# Initialize CellListMap particle system
system = ParticleSystem(
positions=positions,
unitcell=sides,
cutoff=2 * max_radius,
output=forces,
output_name=:forces, # allows the system.forces alias for clarity
parallel=parallel,
)
# define the model properties
# The system field contains the data required for CellListMap.jl
properties = (
dt=dt,
number_of_particles=number_of_particles,
system=system,
)
model = StandardABM(Particle,
space2d;
agent_step!,
model_step!,
agents_first = false,
properties=properties
)
# Create active agents
for id in 1:number_of_particles
pos = positions[id]
prop_particle = PropParticle(
r = (0.5 + 0.9 * rand()) * max_radius,
k = 10 + 20 * rand(), # random force constants
mass = 10.0 + 100 * rand(), # random masses
vel = 100 * randn(SVector{2}) # initial velocities)
)
add_agent!(pos, Particle, model, prop_particle...)
end
return model
end
```

`initialize_bouncing (generic function with 1 method)`

## Computing the pairwise particle forces

To follow the `CellListMap`

interface, we first need a function that computes the force between a single pair of particles. This function receives the positions of the two particles (already considering the periodic boundary conditions), `x`

and `y`

, their indices in the array of positions, `i`

and `j`

, the squared distance between them, `d2`

, the `forces`

array to be updated and the `model`

properties.

Given these input parameters, the function obtains the properties of each particle from the model, and computes the force between the particles as (minus) the gradient of the potential energy function defined above.

The function *must* return the `forces`

array, to follow the `CellListMap`

API.

```
function calc_forces!(x, y, i, j, d2, forces, model)
p_i = model[i]
p_j = model[j]
d = sqrt(d2)
if d ≤ (p_i.r + p_j.r)
dr = y - x # x and y are minimum-image relative coordinates
fij = 2 * (p_i.k * p_j.k) * (d2 - (p_i.r + p_j.r)^2) * (dr / d)
forces[i] += fij
forces[j] -= fij
end
return forces
end
```

`calc_forces! (generic function with 1 method)`

The `model_step!`

function will use `CellListMap`

to update the forces for all particles. The first argument of the call is the function to be computed for each pair of particles, which closes-over the `model`

data to call the `calc_forces!`

function defined above.

```
function model_step!(model::ABM)
# Update the pairwise forces at this step
map_pairwise!(
(x, y, i, j, d2, forces) -> calc_forces!(x, y, i, j, d2, forces, model),
model.system,
)
return nothing
end
```

`model_step! (generic function with 1 method)`

## Update agent positions and velocities

The `agent_step!`

function will update the particle positions and velocities, given the forces, which are computed in the `model_step!`

function. A simple Euler step is used here for simplicity. Finally, the positions stored in the `ParticleSystem`

structure are updated.

```
function agent_step!(agent, model::ABM)
id = agent.id
dt = abmproperties(model).dt
# Retrieve the forces on agent id
f = model.system.forces[id]
a = f / agent.mass
# Update positions and velocities
v = agent.vel + a * dt
x = agent.pos + v * dt + (a / 2) * dt^2
x = normalize_position(x, model)
agent.vel = v
move_agent!(agent, x, model)
# !!! IMPORTANT: Update positions in the ParticleSystem
model.system.positions[id] = agent.pos
return nothing
end
```

`agent_step! (generic function with 1 method)`

## The simulation

Finally, the function below runs an example simulation, for 1000 steps.

```
function simulate(model=nothing; nsteps=1_000, number_of_particles=10_000)
if isnothing(model)
model = initialize_bouncing(number_of_particles=number_of_particles)
end
Agents.step!(model, nsteps)
end
```

`simulate (generic function with 2 methods)`

Which should be quite fast

```
model = initialize_bouncing()
@time simulate(model)
```

```
StandardABM with 10000 agents of type Particle
agents container: Dict
space: periodic continuous space with [500.0, 500.0] extent and spacing=25.0
scheduler: fastest
properties: dt, number_of_particles, system
```

and let's make a nice video with less particles, to see them bouncing around. The marker size is set by the radius of each particle, and the marker color by the corresponding repulsion constant.

```
using CairoMakie
model = initialize_bouncing(number_of_particles=1000)
abmvideo(
"celllistmap.mp4", model;
framerate=20, frames=200, dt=5,
title="Softly bouncing particles with CellListMap.jl",
agent_size=p -> p.r,
agent_color=p -> p.k
)
```