amep.order.local_mass_density#

amep.order.local_mass_density(coords: ndarray, box_boundary: ndarray, radius: float | ndarray, mass: float | ndarray, other_coords: ndarray | None = None, rmax: float = 5.0, pbc: bool = True, enforce_nd: int | None = None, verbose: bool = False) → ndarray#

Calculates the local mass density based on averages over circles with radius rmax. Fractional neighbor counting is used instead of calculating the exact volume or area overlaps between the particles and the circle. A linear mapping is used (as in Ref. [1]).

References

Parameters:

coords (np.ndarray of shape (N,3)) – Coordinates at which the local density is calculated.
box_boundary (np.ndarray of shape (3,2)) – Boundary of the simulation box in the form of np.array([[xmin, xmax], [ymin, ymax], [zmin, zmax]]).
radius (float or np.ndarray) – Radius of the particles. If given as an array (e.g., for differently sized particles), the array must have the same shape as coords (or other_coords if given).
mass (float or np.ndarray) – Mass of the particles. If given as an array (e.g., for differently sized particles), the array must have the same shape as coords (or other_coords if given).
other_coords (np.ndarray of shape (M,3) or None, optional) – Coordinates of particles whose local density is calculated. If None, coords is used. The default is None.
rmax (float, optional) – Radius of the sphere/circle over which the density is calculated. The default is 1.0.
pbc (bool, optional) – If True, periodic boundary conditions are used. The default is True.
enforce_nd (int or None, optional) – Enforce to perform the calculation in this number of dimensions. If None, a suitable number of dimensions is guessed from the given coords. The default is None.
verbose (bool, optional) – If True, runtime information is printed. The default is False.

Raises:

ValueError – Invalid radius, mass, rmax, or enforce_nd.

Returns:

Local mass density for each particle in coords.

Return type:

np.ndarray of shape (N,)

Examples

>>> import amep
>>> traj = amep.load.traj("../examples/data/lammps.h5amep")
>>> frame = traj[-1]
>>> ld = amep.order.local_mass_density(
...     frame.coords(), frame.box, frame.radius(),
...     frame.mass(), rmax=5.0, pbc=True
... )
>>> fig, axs = amep.plot.new(figsize=(3.6,3))
>>> mp = amep.plot.particles(
...     axs, frame.coords(), frame.box, frame.radius(),
...     values=ld
... )
>>> cax = amep.plot.add_colorbar(
...     fig, axs, mp, label="local mass density"
... )
>>> axs.set_xlabel(r"$x$")
>>> axs.set_ylabel(r"$y$")
>>> fig.savefig("./figures/order/order-local_mass_density.png")