Ecosystem integration

• Agents.jl
• Unitful and units
• Automatic differentiation
• Measurements

Agents.jl

Agents.jl provides a comprehensive framework for simulation, analysis and visualization of agent-based systems. CellListMap can be used to accelerate these simulations, and the integration of the packages is rather simple, particularly using the PeriodicSystems interface. A complete integration example can be obtained in the Agents documentation (currently at the development branch).

The example will produce the following animation:

Unitful and units

The functions of CellListMap.jl support the propagation of generic (isbits) types, and thus units and thus automatic differentiation and the use of Unitful. A set of working examples can be found in the generic_types.jl file.

We start illustrating the support for unit propagation. We need to define all involved quantities in the same units:

Using the PeriodicSystems interface

The only requirement is to attach proper units to all quantities (positions, cutoff, unitcell, and output variables). Here we compute the square of the distances of the particles within the cutoff:

julia> using CellListMap.PeriodicSystems, Unitful, StaticArrays

julia> system = PeriodicSystem(
           positions = rand(SVector{3,Float64}, 1000)u"nm",
           cutoff = 0.1u"nm",
           unitcell = [1.0,1.0,1.0]u"nm",
           output = 0.0u"nm^2",
           output_name = :sum_sqr
       );

julia> map_pairwise((x,y,i,j,d2,out) -> out += d2, system)
12.467455105066907 nm^2

Units in neighbor lists

CellListMap.neighborlist propagates units correctly:

julia> import CellListMap

julia> positions = rand(SVector{3,Float64}, 1000)u"nm";

julia> cutoff = 0.1u"nm";

julia> CellListMap.neighborlist(positions, cutoff)
1842-element Vector{Tuple{Int64, Int64, Quantity{Float64, 𝐋, Unitful.FreeUnits{(nm,), 𝐋, nothing}}}}:
 (1, 89, 0.09181950064928723 nm)
 (1, 820, 0.0862244300739942 nm)
 ⋮
 (998, 782, 0.07772327062692863 nm)

Automatic differentiation

Allowing automatic differentiation follows the same principles, meaning that we only need to allow the propagation of dual types through the computation by proper initialization of the input data. However, it is easier to work with the low level interface, which accepts matrices as the input for positions and a more fine control of the types of the variables. Matrices are easier input types for auto diff packages.

The variables are each component of each vector, thus the easiest way to represent the points such that automatic differentiation packages understand is by creating a matrix:

julia> x = rand(3,1000)
3×1000 Matrix{Float64}:
 0.186744  0.328719  0.874102  0.503535   …  0.328161  0.0895699  0.917338
 0.176157  0.972954  0.80729   0.624724      0.655268  0.470754   0.327578
 0.648482  0.537362  0.599624  0.0688776     0.92333   0.497984   0.208924

The key here is allow all the types of the parameters to follow the type propagation of the elements of x inside the differentiation routine. The function we define to compute the derivative is, then:

julia> function sum_sqr(x,sides,cutoff)
           cutoff = eltype(x)(cutoff)
           sides = eltype(x).(sides)
           box = Box(sides,cutoff)
           cl = CellList(x,box)
           sum_sqr = zero(eltype(x))
           sum_sqr = map_pairwise!(
               (x,y,i,j,d2,sum_sqr) -> sum_sqr += d2,
               sum_sqr, box, cl
           )
           return sum_sqr
       end

Note that we allow cutoff and sides to be converted to the same type of the input x of the function. For a simple call to the function this is inconsequential:

julia> cutoff = 0.1; sides = [1,1,1];

julia> sum_sqr(x,sides,cutoff)
12.897650398753228

but the conversion is required to allow the differentiation to take place:

julia> ForwardDiff.gradient(x -> sum_sqr(x,sides,cutoff),x)
3×1000 Matrix{Float64}:
 -0.132567   0.029865  -0.101301  …   0.249267    0.0486424  -0.0400487
  0.122421   0.207495  -0.184366     -0.201648   -0.105031    0.218342
  0.0856502  0.288924   0.122445     -0.0147022  -0.103314   -0.0862264

Measurements

Propagating uncertainties through the Measurements and other similar packages requires a different strategy, because within CellListMap only isbits types can be used, which is not the case of the type Measurement type.

In cases like this, it is better to bypass all the internals of CellListMap and provide the data to the function that computes pairwise properties directly as a closure. For example:

A vector of particles with uncertainties in their coordinates can be created with:

julia> using StaticArrays 

julia> x_input = [ SVector{3}(measurement(rand(),0.01*rand()) for i in 1:3) for j in 1:1000 ]
1000-element Vector{SVector{3, Measurement{Float64}}}:
 [0.1658 ± 0.003, 0.9951 ± 0.0054, 0.5067 ± 0.0035]
 [0.2295 ± 0.0074, 0.2987 ± 0.0021, 0.42828 ± 0.00099]
 ⋮
 [0.1362 ± 0.0034, 0.2219 ± 0.0048, 0.2119 ± 0.0072]
 [0.2521 ± 0.0038, 0.4988 ± 0.00013, 0.856046 ± 4.3e-5]

The variables within the CellListMap functions will be stripped from the uncertainties. We do:

julia> unitcell = [1,1,1]

julia> cutoff = 0.1; box = Box(unitcell,cutoff);

julia> x_strip = [ getproperty.(v,:val) for v in x_input ]
1000-element Vector{SVector{3, Float64}}:
 [0.08441931492362276, 0.9911530546181084, 0.07408559584648788]
 [0.12084764467339837, 0.8284551316333133, 0.9021906852432111]
 ⋮
 [0.2418752113326077, 0.4429225751775432, 0.13576355747772784]
 [0.24440380524702654, 0.07148275176890073, 0.26722687487212315]

The cell list is built with the stripped values:

julia> cl = CellList(x_strip,box)
CellList{3, Float64}
  1000 real particles.
  637 cells with real particles.
  1695 particles in computing box, including images.

The result is initialized with the proper type,

julia> result = measurement(0.,0.)
0.0 ± 0.0

and the mapping is performed with the stripped coordinates, but passing the values with uncertainties to the mapped function, which will perform the computation on the pairs with those values:

julia> using LinearAlgebra: norm_sqr

julia> result = map_pairwise!(
           (xᵢ,xⱼ,i,j,d2,sum_sqr) -> begin
               x1 = x_input[i]
               x2 = CellListMap.wrap_relative_to(x_input[j],x1,unitcell)
               sum_sqr += norm_sqr(x2-x1)
               return sum_sqr
           end, 
           result, box, cl
       )
13.14 ± 0.061

In the function above, the xᵢ and xⱼ coordinates, which correspond to the coordinates in x_input[i] and x_input[j], but already wrapped relative to each other, are ignored, because they don't carry the uncertainties. We use only the indexes i and j to recompute the relative position of the particles according to the periodic boundary conditions (using the CellListMap.wrap_relative_to function) and their (squared) distance. Since the x_input array carries the uncertainties, the computation of sum_sqr will propagate them.