From a46a55eb273551c49fe6250455ec7725cc3479c0 Mon Sep 17 00:00:00 2001 From: Leandro Martinez Date: Wed, 13 May 2026 16:18:22 -0300 Subject: [PATCH] improve documentation of NeighborPair --- CHANGELOG.md | 1 + docs/src/ParticleSystem/introduction.md | 10 + docs/src/assets/NeighborPair.svg | 488 ++++++++++++++++++++++++ src/API/NeighborPair.jl | 4 + 4 files changed, 503 insertions(+) create mode 100644 docs/src/assets/NeighborPair.svg diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d86f3ef..b9acb6d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ CellListMap.jl Changelog Version 0.10.3-DEV -------------- +- ![INFO][badge-info] Clarifty the meaning of `NeighborPair` fields, specifically concerning the minimum-image consideration. - ![INFO][badge-info] Document the possibility of modifying individual positions with `setindex!` and `SVector`s. Version 0.10.2 diff --git a/docs/src/ParticleSystem/introduction.md b/docs/src/ParticleSystem/introduction.md index dacbb80a..2b85d577 100644 --- a/docs/src/ParticleSystem/introduction.md +++ b/docs/src/ParticleSystem/introduction.md @@ -45,6 +45,16 @@ extract from the object using [destructuring syntax](https://docs.julialang.org/ The `output` variable **must** be returned by the function, being it mutable or immutable. +The figure below illustrates the meaning the coordinates in a `NeighborPair` object. + +![../assets/NeighborPair.svg](../assets/NeighborPair.svg) + +Here $$\vec{x}$$ and $$\vec{y}_0$$ are the coordinates as provided by the user, which in this case fall inside the +reference unitcell. But the image $$\vec{y}$$ of $$\vec{y}_0$$ is closer to $$\vec{x}$$. The `NeighborPair` object +will contain the coordinates `pair.x ==`$$\vec{x}$$ and `pair.y ==`$$\vec{y}$$, such that `pair.y - pair.x` will be +tipicaly the vector used, for example, to compute the force between the particles. Also, `pair.d == norm(pair.y - pair.y)` +and corresponds to the norm of $$\vec{y} - \vec{x}$$, as represented in the figure. + ### Basic examples For example, computing the energy, as the sum of the inverse of the distance between particles, can be done with a function like: diff --git a/docs/src/assets/NeighborPair.svg b/docs/src/assets/NeighborPair.svg new file mode 100644 index 00000000..b1e2fd75 --- /dev/null +++ b/docs/src/assets/NeighborPair.svg @@ -0,0 +1,488 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/API/NeighborPair.jl b/src/API/NeighborPair.jl index 05509adf..80ec67b9 100644 --- a/src/API/NeighborPair.jl +++ b/src/API/NeighborPair.jl @@ -11,6 +11,10 @@ Structure that holds the information of a pair of particles that are neighbors w - `d::T`: Euclidean distance between the particles (computed lazily). - `d2::T2`: squared Euclidean distance between the particles. +Specifically, `pair.d == norm(pair.y - pair.x)`, and `pair.d` will be always equal or +smaller than the cutoff, as only pairs within the cutoff are considered `pair.y` +is the minimum image position of particle `pair.i` relative to `pair.x`. + """ struct NeighborPair{N, T, T2} i::Int