You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -17,7 +17,10 @@ The `ParticleSystem` interface facilitates the use of `CellListMap` for the majo
17
17
18
18
## The mapped function
19
19
20
-
The function to be mapped for every pair of particles within the cutoff follows the same interface as the standard interface. It must be of the form
20
+
The purpose of CellListMap is to compute a pairwise-dependent function for all pairs of particles that are closer to
21
+
each other than a defined cutoff. This pairwise function must be implemented by the user and adhere to the following
22
+
interface:
23
+
21
24
```julia
22
25
functionf(x, y, i, j, d2, output)
23
26
# update output variable
@@ -26,6 +29,34 @@ end
26
29
```
27
30
where `x` and `y` are the positions of the particles, already wrapped relative to each other according to the periodic boundary conditions (a minimum-image set of positions), `i` and `j` are the indexes of the particles in the arrays of coordinates, `d2` is the squared distance between the particles, and `output` is the variable to be computed.
28
31
32
+
!!! info
33
+
#### Details of the mapped function interface
34
+
35
+
The input parameters `x`, `y`, `i`, `j`, and `d2` must not be modified by the user. They are the
36
+
the input data that the user may use to update the `output` variable.
37
+
38
+
| Input Parameter | Type | Meaning |
39
+
|:----------------:|:-------:|:-----------|
40
+
| `x` | `SVector` | The coordinates of particle `i` of the pair. |
41
+
| `y` | `SVector` | The coordinates of particle `j` of the pair (minimum-image relative to `x`). |
42
+
| `i` | `Int` | Index of first particle in the original array of coordinates. |
43
+
| `j` | `Int` | Index of second particle in the original array of coordinates. |
44
+
| `d2` | `<:Real` | Squared distance between the particles. |
45
+
| `output` | user defined | the value to be updated |
46
+
47
+
**Notes:** `x` and `y` may be 2D or 3D vectors, depending on the dimension of the system. The type of
48
+
the coordinates of `x`, `y`, and of `d2` are dependent on the input arrays and cutoff, and can be `Float64`,
49
+
`Float32`, unitful quantities, etc.
50
+
51
+
| Return value | Type | Meaning |
52
+
|:----------------:|:-------:|:-----------|
53
+
| `output` | user defined | the updated value of output. |
54
+
55
+
The `output` variable **must** be returned by the function, being it mutable or immutable.
56
+
57
+
58
+
### Basic examples
59
+
29
60
For example, computing the energy, as the sum of the inverse of the distance between particles, can be done with a function like:
30
61
```julia
31
62
functionenergy(d2,u)
@@ -35,9 +66,14 @@ end
35
66
```
36
67
and the additional parameters required by the interface can be eliminated by the use of an anonymous function, directly on the call to the `map_pairwise` function:
37
68
```julia
38
-
u =map_pairwise((x,y,i,j,d2,u) ->energy(d2,u), system)
69
+
u =map_pairwise(
70
+
(x,y,i,j,d2,u) ->energy(d2,u),
71
+
system
72
+
)
39
73
```
40
-
(what `system` is will be explained in the examples below).
74
+
(what `system` is will be explained in the examples below). Note that the `energy` function does not use the `x`, `y`, `i`, and `j` input parameters, such
75
+
that the anonymous function managing the interface could also be written as `(_, _, _, _, d2, u) -> energy(d2, u)`, making explicit the dummy character of
76
+
these variables in the example.
41
77
42
78
Alternatively, the function might require additional parameters, such as the masses of the particles. In this case, we can use a closure to provide such data:
u =map_pairwise((x,y,i,j,d2,u) ->energy(d2,u,masses), system)
50
86
```
51
87
52
-
## Potential energy example
88
+
Here we reinforce the fact that the `energy` functions defined above compute the contribution to the energy of the interaction of *a single* pair
89
+
of particles. This function will be called for every pair of particles within the cutoff, automatically, in the `map_pairwise` call.
53
90
54
91
!!! note
55
92
The `output` of the `CellListMap` computation may be of any kind. Most commonly, it is an energy, a set of forces, or other data type that can be represented either as a number, an array of numbers, or an array of vectors (`SVectors` in particular), such as an arrays of forces.
@@ -58,43 +95,57 @@ u = map_pairwise((x,y,i,j,d2,u) -> energy(d2,u,masses), system)
58
95
59
96
For these types of `output` data the usage does not require the implementation of any data-type dependent function.
60
97
61
-
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.
98
+
## The ParticleSystem constructor
99
+
100
+
## Potential energy example
101
+
102
+
For example, here we read the coordinates of Argon atoms from a PDB file. The coordinates are given as
103
+
vector of `SVector`s. We then compute an "energy", which in this case is simply the sum of `1/d` over all pair of particles, within a cutoff.
62
104
63
105
The `ParticleSystem` constructor receives the properties of the system and sets up automatically the most commonly used data structures necessary.
Now, directly, let us compute a putative energy of the particles, assuming a simple formula which depends on the inverse of the distance between pairs:
121
+
!!! note
122
+
- Systems can be 2 or 3-dimensional.
123
+
- The `unitcell` parameter may be:
124
+
- a vector, in which case the system periodic boundaries are Orthorhombic, this is faster.
125
+
- a matrix, in which case the system periodic boundaries are Triclinic (general).
126
+
- `nothing` (by default), in which case no periodic boundary conditions will be used.
127
+
- `Unitful` quantities can be provided, given appropriate types for all input parameters.
128
+
129
+
Now, let us compute the energy of the particles, assuming a simple formula which depends on the inverse of the distance between pairs:
78
130
79
131
```julia-repl
80
-
julia> map_pairwise!((x,y,i,j,d2,energy) -> energy += 1 / sqrt(d2), system)
81
-
30679.386366872823
132
+
julia> function energy(x, y, i, j, d2, energy)
133
+
energy += 1 / sqrt(d2)
134
+
return energy
135
+
end
136
+
137
+
julia> map_pairwise!(energy, system)
138
+
207.37593043370865
82
139
```
140
+
Note that the first four parameters of `energy` are not used here but are needed to adhere to the interface. The function
141
+
input could be written as `(_, _, _, _, d2, energy)` to make that explicit.
83
142
84
143
The `system.energy` field accesses the resulting value of the computation:
85
144
```julia-repl
86
145
julia> system.energy
87
-
30679.386366872823
146
+
207.37593043370865
88
147
```
89
-
because the `output_name` field was provided. If it is not provided, you can access the output value from the `system.output` field.
90
-
91
-
!!! note
92
-
- Systems can be 2 or 3-dimensional.
93
-
- The `unitcell` parameter may be:
94
-
- a vector, in which case the system periodic boundaries are Orthorhombic, this is faster.
95
-
- a matrix, in which case the system periodic boundaries are Triclinic (general).
96
-
- `nothing` (by default), in which case no periodic boundary conditions will be used.
97
-
- `Unitful` quantities can be provided, given appropriate types for all input parameters.
148
+
because the `output_name` field was provided. If it is not provided, you can access the output value from the `system.energy` field.
98
149
99
150
## Computing forces
100
151
@@ -115,13 +166,15 @@ Importantly, the function *must* return the `forces` array to follow the API.
115
166
Now, let us setup the system with the new type of output variable, which will be now an array of forces with the same type as the positions:
@@ -164,7 +218,7 @@ must be defined. It can be followed for the computation of other general propert
164
218
than for the arrays.
165
219
166
220
```julia
167
-
using CellListMap, StaticArrays
221
+
using CellListMap, StaticArrays, PDBTools
168
222
```
169
223
170
224
The computation of energies and forces in a single call is an interesting example for the definition of a custom `output` type and the required interface functions.
@@ -181,14 +235,14 @@ the default corresponding functions, for our new output type:
181
235
182
236
The copy method creates a new instance of the `EnergyAndForces` type, with copied data:
0 commit comments