Skip to content

Commit

Permalink
renamed PeriodicSystem to ParticleSystem
Browse files Browse the repository at this point in the history
  • Loading branch information
@lmiq
lmiq committed May 2, 2024
1 parent fe61121 commit 9e81e90
Show file tree
Hide file tree
Showing 11 changed files with 258 additions and 220 deletions.
2 changes: 1 addition & 1 deletion docs/make.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ makedocs(
sitename="CellListMap.jl",
pages = [
"Overview" => "index.md",
"PeriodicSystems interface" => "PeriodicSystems.md",
"ParticleSystem interface" => "ParticleSystem.md",
"Neighbor lists" => "neighborlists.md",
"Low level interface" => "LowLevel.md",
"Ecosystem integration" => "ecosystem.md",
Expand Down
2 changes: 1 addition & 1 deletion docs/src/LowLevel.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Low level interface

Since version `0.7.22` we strongly encourage the use of the `PeriodicSystems` interface. Yet,
Since version `0.8.30` we strongly encourage the use of the `ParticleSystem` interface. Yet,
the low level interface is still available. To use it, load the package as usual:
```julia
using CellListMap
Expand Down
62 changes: 30 additions & 32 deletions docs/src/PeriodicSystems.md → docs/src/ParticleSystem.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# PeriodicSystems interface
# ParticleSystem interface

The `PeriodicSystems` interface facilitates the use of `CellListMap` for the majority of cases.
The `ParticleSystem` interface facilitates the use of `CellListMap` for the majority of cases.

!!! note
- This interface requires `CellListMap.jl` version `0.8.30` or greater.
Expand All @@ -15,7 +15,7 @@ The `PeriodicSystems` interface facilitates the use of `CellListMap` for the maj
The `PeriodicSystems` interface was available until version `0.8.29` by loading
the `CellistMap.PeriodicSystems` module. This is still possible, but no longer
necessary in version `0.8.30` or greater. The `PeriodicSystems` submodule will be
deprecated in future versions.
deprecated in future versions in favor of the `ParticleSystem` interface..

## The mapped function

Expand Down Expand Up @@ -62,12 +62,12 @@ u = map_pairwise((x,y,i,j,d2,u) -> energy(d2,u,masses), system)

For example, let us build a system of random particles in a cubic box, and compute an "energy", which in this case is simply the sum of `1/d` over all pair of particles, within a cutoff.

The `PeriodicSystem` constructor receives the properties of the system and sets up automatically the most commonly used data structures necessary.
The `ParticleSystem` constructor receives the properties of the system and sets up automatically the most commonly used data structures necessary.

```julia-repl
julia> using CellListMap, StaticArrays
julia> system = PeriodicSystem(
julia> system = ParticleSystem(
xpositions = rand(SVector{3,Float64},1000),
unitcell=[1.0,1.0,1.0],
cutoff = 0.1,
Expand Down Expand Up @@ -119,7 +119,7 @@ Now, let us setup the system with the new type of output variable, which will be
```julia-repl
julia> positions = rand(SVector{3,Float64},1000);
julia> system = PeriodicSystem(
julia> system = ParticleSystem(
xpositions = positions,
unitcell=[1,1,1],
cutoff = 0.1,
Expand Down Expand Up @@ -236,7 +236,7 @@ To finally define the system and compute the properties:
```julia-repl
positions = rand(SVector{3,Float64},1000);
system = PeriodicSystem(
system = ParticleSystem(
xpositions = positions,
unitcell=[1.0,1.0,1.0],
cutoff = 0.1,
Expand Down Expand Up @@ -270,7 +270,7 @@ If the `map_pairwise!` function will compute energy and/or forces in a iterative

### Updating coordinates

The coordinates can be updated (mutated, or the array of coordinates can change in size by pushing or deleting particles), simply by directly accessing the `xpositions` field of the system. The `xpositions` array is a `Vector` of `SVector` (from `StaticArrays`), with coordinates copied from the input array provided. Thus, the coordinates in the `PeriodicSystem` structure must be updated independently of updates in the original array of coordinates.
The coordinates can be updated (mutated, or the array of coordinates can change in size by pushing or deleting particles), simply by directly accessing the `xpositions` field of the system. The `xpositions` array is a `Vector` of `SVector` (from `StaticArrays`), with coordinates copied from the input array provided. Thus, the coordinates in the `ParticleSystem` structure must be updated independently of updates in the original array of coordinates.

Let us exemplify the interface with the computation of forces:

Expand All @@ -279,7 +279,7 @@ julia> using CellListMap, StaticArrays
julia> positions = rand(SVector{3,Float64}, 1000);
julia> system = PeriodicSystem(
julia> system = ParticleSystem(
xpositions = positions,
unitcell=[1,1,1],
cutoff = 0.1,
Expand Down Expand Up @@ -341,7 +341,7 @@ The unit cell can be updated to new dimensions at any moment, with the `update_u

```julia-repl
julia> update_unitcell!(system, SVector(1.2, 1.2, 1.2))
PeriodicSystem1 of dimension 3, composed of:
ParticleSystem1 of dimension 3, composed of:
Box{OrthorhombicCell, 3}
unit cell matrix = [ 1.2, 0.0, 0.0; 0.0, 1.2, 0.0; 0.0, 0.0, 1.2 ]
cutoff = 0.1
Expand Down Expand Up @@ -374,7 +374,7 @@ The cutoff can also be updated, using the `update_cutoff!` function:

```julia-repl
julia> update_cutoff!(system, 0.2)
PeriodicSystem1 of dimension 3, composed of:
ParticleSystem1 of dimension 3, composed of:
Box{OrthorhombicCell, 3}
unit cell matrix = [ 1.0, 0.0, 0.0; 0.0, 1.0, 0.0; 0.0, 0.0, 1.0 ]
cutoff = 0.2
Expand Down Expand Up @@ -403,7 +403,7 @@ julia> map_pairwise!((x,y,i,j,d2,forces) -> update_forces!(x,y,i,j,d2,forces), s

If the computation involves two sets of particle, a similar interface is available.
The only difference is that the coordinates of the two sets must be provided to
the `PeriodicSystem` constructor as the `xpositions` and `ypositions` arrays.
the `ParticleSystem` constructor as the `xpositions` and `ypositions` arrays.

We will illustrate this interface by computing the minimum distance between two
sets of particles, which allows us to showcase further the definition of custom
Expand Down Expand Up @@ -455,7 +455,7 @@ julia> xpositions = rand(SVector{3,Float64},1000);
julia> ypositions = rand(SVector{3,Float64},1000);
julia> system = PeriodicSystem(
julia> system = ParticleSystem(
xpositions = xpositions,
ypositions = ypositions,
unitcell=[1.0,1.0,1.0],
Expand Down Expand Up @@ -522,7 +522,7 @@ julia> xpositions = rand(SVector{3,Float64},10^6);
julia> ypositions = rand(SVector{3,Float64},10^6);
julia> system = PeriodicSystem(
julia> system = ParticleSystem(
xpositions = xpositions,
ypositions = ypositions,
unitcell=[1.0,1.0,1.0],
Expand All @@ -543,7 +543,7 @@ By activating the `show_progress` flag, a nice progress bar is shown.
### Fine control of the paralellization

The number of batches launched in parallel runs can be tunned by the
`nbatches` keyword parameter of the `PeriodicSystem` constructor.
`nbatches` keyword parameter of the `ParticleSystem` constructor.
By default, the number of batches is defined as heuristic function
dependent on the number of particles, and possibly returns optimal
values in most cases. For a detailed discussion about this parameter,
Expand All @@ -553,7 +553,7 @@ For example, to set the number of batches for cell list calculation
to 4 and the number of batches for mapping to 8, we can do:

```julia-repl
julia> system = PeriodicSystem(
julia> system = ParticleSystem(
xpositions = rand(SVector{3,Float64},1000),
unitcell=[1,1,1],
cutoff = 0.1,
Expand All @@ -574,7 +574,7 @@ To compute different properties without recomputing cell lists, use `update_list
the call of `map_pairwise` methods, for example,
```julia
using CellListMap, StaticArrays
system = PeriodicSystem(xpositions=rand(SVector{3,Float64},1000), output=0.0, cutoff=0.1, unitcell=[1,1,1])
system = ParticleSystem(xpositions=rand(SVector{3,Float64},1000), output=0.0, cutoff=0.1, unitcell=[1,1,1])
# First call, will compute the cell lists
map_pairwise((x,y,i,j,d2,u) -> u += d2, system)
# Second run: do not update the cell lists but compute a different property
Expand All @@ -586,10 +586,10 @@ option if the cutoff, unitcell, or any other property of the system changed.

For systems with two sets of particles, the
coordinates of the `xpositions` set can be updated, preserving the cell lists computed for the `ypositions`, but this requires
setting `autoswap=false` in the construction of the `PeriodicSystem`:
setting `autoswap=false` in the construction of the `ParticleSystem`:
```julia
using CellListMap, StaticArrays
system = PeriodicSystem(
system = ParticleSystem(
xpositions=rand(SVector{3,Float64},1000),
ypositions=rand(SVector{3,Float64},2000),
output=0.0, cutoff=0.1, unitcell=[1,1,1],
Expand All @@ -603,9 +603,9 @@ map_pairwise((x,y,i,j,d2,u) -> u += sqrt(d2), system; update_lists = false)
### Control CellList cell size

The cell sizes of the construction of the cell lists can be controled with the keyword `lcell`
of the `PeriodicSystem` constructor. For example:
of the `ParticleSystem` constructor. For example:
```julia-repl
julia> system = PeriodicSystem(
julia> system = ParticleSystem(
xpositions = rand(SVector{3,Float64},1000),
unitcell=[1,1,1],
cutoff = 0.1,
Expand All @@ -629,23 +629,21 @@ larger values of `lcell` may improve the performance. To be tested by the user.
### Coordinates as matrices

!!! compat
Support for input coordinates in matrix format in the `PeriodicSystem` interface was introduced
in version `0.8.28`.
Support for input coordinates in matrix format in the `PeriodicSystem` interface was introduced in version `0.8.28`.

Coordinates can also be provided as matrices of size `(D,N)` where `D` is the dimension (2 or 3) and
`N` is the number of particles. For example:
Coordinates can also be provided as matrices of size `(D,N)` where `D` is the dimension (2 or 3) and `N` is the number of particles. For example:

```jldoctest; filter = r"\d+" => ""
julia> using CellListMap
julia> system = PeriodicSystem(
julia> system = ParticleSystem(
xpositions=rand(2,100),
ypositions=rand(2,200),
cutoff=0.1,
unitcell=[1,1],
output=0.0,
)
PeriodicSystem2{output} of dimension 2, composed of:
ParticleSystem2{output} of dimension 2, composed of:
Box{OrthorhombicCell, 2}
unit cell matrix = [ 1.0 0.0; 0.0 1.0 ]
cutoff = 0.1
Expand Down Expand Up @@ -681,7 +679,7 @@ inverse of the distance between the particles is computed.
```julia
using CellListMap
using StaticArrays
system = PeriodicSystem(
system = ParticleSystem(
xpositions = rand(SVector{3,Float64},1000),
unitcell=[1.0,1.0,1.0],
cutoff = 0.1,
Expand All @@ -700,7 +698,7 @@ function of the previous example.
using CellListMap
using StaticArrays
positions = rand(SVector{3,Float64},1000)
system = PeriodicSystem(
system = ParticleSystem(
xpositions = positions,
unitcell=[1.0,1.0,1.0],
cutoff = 0.1,
Expand Down Expand Up @@ -756,7 +754,7 @@ function energy_and_forces!(x,y,i,j,d2,output::EnergyAndForces)
end
# Initialize system
positions = rand(SVector{3,Float64},1000);
system = PeriodicSystem(
system = ParticleSystem(
xpositions = positions,
unitcell=[1.0,1.0,1.0],
cutoff = 0.1,
Expand Down Expand Up @@ -797,7 +795,7 @@ reducer!(md1::MinimumDistance, md2::MinimumDistance) = md1.d < md2.d ? md1 : md2
# Build system
xpositions = rand(SVector{3,Float64},1000);
ypositions = rand(SVector{3,Float64},1000);
system = PeriodicSystem(
system = ParticleSystem(
xpositions = xpositions,
ypositions = ypositions,
unitcell=[1.0,1.0,1.0],
Expand Down Expand Up @@ -846,7 +844,7 @@ function init_system(;N::Int=200)
positions = rand(Vec2D, N)
unitcell = [1.0, 1.0]
cutoff = 0.1
system = PeriodicSystem(
system = ParticleSystem(
positions=positions,
cutoff=cutoff,
unitcell=unitcell,
Expand Down
6 changes: 3 additions & 3 deletions docs/src/ecosystem.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

## Agents.jl

[Agents.jl](https://juliadynamics.github.io/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](https://juliadynamics.github.io/Agents.jl/dev/examples/celllistmap/) can be obtained in the `Agents` documentation (currently at the development branch).
[Agents.jl](https://juliadynamics.github.io/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 `ParticleSystem` interface. A [complete integration example](https://juliadynamics.github.io/Agents.jl/dev/examples/celllistmap/) can be obtained in the `Agents` documentation (currently at the development branch).

The example will produce the following animation:

Expand All @@ -23,14 +23,14 @@ The functions of CellListMap.jl support the propagation of generic (isbits) type

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

### Using the PeriodicSystems interface
### Using the ParticleSystem 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-repl
julia> using CellListMap, Unitful, StaticArrays
julia> system = PeriodicSystem(
julia> system = ParticleSystem(
positions = rand(SVector{3,Float64}, 1000)u"nm",
cutoff = 0.1u"nm",
unitcell = [1.0,1.0,1.0]u"nm",
Expand Down
64 changes: 47 additions & 17 deletions docs/src/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,55 @@

It maps a generic function to be computed for each pair of particles, using periodic boundary conditions of any type. Parallel and serial implementations can be used. The user defined function will be evaluated only for the pairs closer to each other than the desired cutoff distance.

## Overview

`CellListMap` is a package that implements a fast scheme for computing properties of systems of particles in 2 or 3 dimensions, within a cutoff. In brief, it is designed to replace double loops running over the pairs of particles of a system. Naively, a loop over all pair of particles is written as:
```julia
for i in 1:N
for j in i+1:N
# compute distance, possibly considering periodic boundary conditions
d = distance(particle[i],particle[j])
if d <= cutoff
# compute property dependent on d
end
end
end
```
where `N` is the number of particles. Alternatively, if the interaction is between two disjoint sets of particles, the loop is
```julia
for i in 1:N
for j in 1:M
# compute distance, possibly considering periodic boundary conditions
d = distance(first_set[i], second_set[j])
if d <= cutoff
# compute property dependent on d
end
end
end
```
where `N` and `M` are the numbers of particles of each set. If the cutoff is significantly smaller than the dimension of the system,
these loops are very expensive, and it is possible to avoid looping over particles that are farther from each other than the cutoff.

CellListMap implements an efficient cell-list scheme, with optimizations, to substitute such double-loops while taking into account
periodic boundary conditions.

### High level interface for periodic system

Since version `0.8.30`, a simpler, higher level interface was introduced, that will facilitate the use of `CellListMap` without any loss in performance. The new interface is flexible enough for the majority of applications. See the [ParticleSystem interface](@ref) menu for details.

### Cutoff-delimited neighbor lists

The user might be more comfortable in using the package to compute the list of neighboring particles. A custom interface for this application is provided though the [Neighbor lists](@ref) interface.

Note that, in general, neighbor lists are used to compute other pairwise dependent properties, and these can be, in principle, computed directly with `CellListMap` without the need to explicitly compute or store the lists of neighbors.

### Lower level interface

The [Low level interface](@ref) allows the customization and optimization of very demanding calculations (although the ParticleSystem interface does not have any performance limitation and is easier to use).

## Installation

This is a [Julia](http://julialang.org) package. Install `Julia` first following the instructions in the [download page](https://julialang.org/downloads/), or using [juliaup](https://github.com/JuliaLang/juliaup).
This is a [Julia](http://julialang.org) package. Install `Julia` first following the instructions in the [download page](https://julialang.org/downloads/).

Once Julia is installed, install the `CellListMap` package from the Julia REPL with:

Expand All @@ -28,19 +74,3 @@ Please ask for help if having any difficulty using the package. Reach us by:
- Joining us at Zulip-chat in the [m3g stream](https://julialang.zulipchat.com/#narrow/stream/435348-m3g) of the Julia Zulip forum.
- Sending an e-mail to: [[email protected]](mailto:[email protected]?subject="ComplexMixtures.jl help").

## Overview

### High level interface for periodic system

Since version `0.7.22`, a new simpler, higher level interface was introduced, that will facilitate the use of `CellListMap` without any loss in performance. The new interface is flexible enough for the majority of applications. It may become the default interface in the future. See the [PeriodicSystems interface](@ref) menu for details.

### Cutoff-delimited neighbor lists

The user might be more comfortable in using the package to compute the list of neighboring particles. A custom interface for this application is provided though the [Neighbor lists](@ref) interface.

Note that, in general, neighbor lists are used to compute other pairwise dependent properties, and these can be, in principle, computed directly with `CellListMap` without the need to compute or store the lists of neighbors.

### Lower level interface

The [Low level interface](@ref) allows the customization and optimization of very demanding calculations (although the PeriodicSystems interface does not have any performance limitation and is easier to use).

2 changes: 1 addition & 1 deletion src/CellListMap.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ include("./show.jl")
include("./Box.jl")
include("./CellLists.jl")
include("./CellOperations.jl")
include("./PeriodicSystems.jl")
include("./ParticleSystem.jl")
include("./CoreComputing.jl")

"""
Expand Down
Loading

0 comments on commit 9e81e90

Please sign in to comment.