amep.evaluate.LDdist#

class amep.evaluate.LDdist(traj: ParticleTrajectory | FieldTrajectory, skip: float = 0.0, nav: int = 10, nbins: int = 50, xmin: float = 0.0, xmax: float = 1.5, ftype: str | None = None, ptype: int | None = None, other: int | None = None, mode: str = 'number', use_voronoi: bool = False, **kwargs)#

Bases: BaseEvaluation

Local density distribution.

__init__(traj: ParticleTrajectory | FieldTrajectory, skip: float = 0.0, nav: int = 10, nbins: int = 50, xmin: float = 0.0, xmax: float = 1.5, ftype: str | None = None, ptype: int | None = None, other: int | None = None, mode: str = 'number', use_voronoi: bool = False, **kwargs) → None#

Calculate the local density distribution and takes an average over several frames (= time average). For particle-based data, the local density is determined via averages over circles with radius rmax if use_voronoi=False or via Voronoi tesselation if use_voronoi=True. For field data, the histogram of the grid values is calculated.

Notes

To calculate the local density distribution for particle-based simulation data, the radius of the particles is needed. If your trajectory does not contain the radii of the particles, you can add the radius (here 0.5) to the trajectory using

for frame in traj:
    frame.add_data("radius", 0.5*np.ones(len(frame.n())))

Parameters:

traj (ParticleTrajectory or FieldTrajectory) – Trajectory object.
skip (float, optional) – Skip this fraction at the beginning of the trajectory. The default is 0.0.
nav (int, optional) – Number of frames to use for the average. The default is 10.
nbins (int) – Number of bins for the histogram. The default is 50.
xmin (float, optional) – Minimum value of the bins. The default is 0.0.
xmax (float, optional) – Maximum value of the bins. The default is 1.5.
ftype (str or None, optional) – Allows to specify for which field in a given FieldTrajectory the local density distribution should be calculated. If None, the local density is calculated for all fields. The default is None.
ptype (int or None, optional) – Particle type of query particle for which the local density is calculated. The default is None (use all particles).
other (int or None, optional) – Particle type of environmental particles. The defautl is None (all particles).
mode (str, optional) – Mode ‘number’ uses the number density, mode ‘mass’ the mass density, and mode ‘packing’ the packing fraction. The default is ‘number’. This keyword is only considered if type(traj)=ParticleTrajectory.
use_voronoi (bool, optional) – If True, Voronoi tesselation is used to determine the local density. If False, averages over circles of radius rmax are used. Note that other is ignored if use_voronoi is set to True. The default is False.
**kwargs – Other keyword arguments are forwarded to the local density functions used such as rmax, pbc, enforce_nd. (see amep.order.voronoi_density(), amep.order.local_number_density(), amep.order.local_mass_density(), amep.order.local_packing_fraction())

Return type:

None.

Examples

>>> import amep
>>> traj = amep.load.traj("../examples/data/lammps.h5amep")
>>> ld1 = amep.evaluate.LDdist(
...     traj, nav=2, mode="number", skip=0.9, xmin=0.0, xmax=1.3
... )
>>> ld2 = amep.evaluate.LDdist(
...     traj, nav=2, mode="mass", skip=0.9, xmin=0.0, xmax=1.3
... )
>>> ld3 = amep.evaluate.LDdist(
...     traj, nav=2, mode="packing", skip=0.9, xmin=0.0, xmax=1.0
... )
>>> ld1.save("./eval/ld_abp.h5", database=True, name="number")
>>> ld2.save("./eval/ld_abp.h5", database=True, name="mass")
>>> ld3.save("./eval/ld_abp.h5", database=True, name="packing")
>>> fig, axs = amep.plot.new()
>>> axs.plot(ld1.ld, ld1.avg, label="number")
>>> axs.plot(ld2.ld, ld2.avg, label="mass")
>>> axs.plot(ld3.ld, ld3.avg, label="packing")
>>> axs.legend()
>>> axs.set_xlabel(r"$\rho$")
>>> axs.set_ylabel(r"$p(\rho)$")
>>> axs.set_title("active Brownian particles")
>>> fig.savefig("./figures/evaluate/evaluate-LDdist_1.png")

>>> traj = amep.load.traj("../examples/data/continuum.h5amep")
>>> ld = amep.evaluate.LDdist(
...     traj, nav=2, skip=0.9, xmin=0.0, xmax=1.1, ftype="c"
... )
>>> ld.save("./eval/ld.h5")
>>> fig, axs = amep.plot.new()
>>> axs.plot(ld.ld, ld.avg)
>>> axs.set_xlabel(r'$c$')
>>> axs.set_ylabel(r'$p(c)$')
>>> axs.set_title("Keller-Segel model")
>>> fig.savefig("./figures/evaluate/evaluate-LDdist_2.png")

Methods

`__init__`(traj[, skip, nav, nbins, xmin, ...])	Calculate the local density distribution and takes an average over several frames (= time average).
`items`()
`keys`()	The keys to the evaluation object.
`save`(path[, backup, database, name])	Stores the evaluation result in an HDF5 file.
`values`()

Attributes

`avg`	Time-averaged LDdist (averaged over the given number of frames).
`frames`	LDdist for each frame.
`indices`	Indices of all frames for which the LDdist has been evaluated.
`ld`	Local density values.
`name`
`times`	Times at which the LDdist is evaluated.

property avg#

Time-averaged LDdist (averaged over the given number of frames).

Returns:: Time-averaged function value.
Return type:: np.ndarray

property frames#

LDdist for each frame.

Returns:: LDdist for each frame.
Return type:: np.ndarray

property indices#

Indices of all frames for which the LDdist has been evaluated.

Returns:: Frame indices.
Return type:: np.ndarray

keys() → list[str]#

The keys to the evaluation object.

Used so Evaluation-objects can be used as dictionaries.

property ld#

Local density values.

Returns:: Local density values.
Return type:: np.ndarray

save(path: str, backup: bool = True, database: bool = False, name: str | None = None) → None#

Stores the evaluation result in an HDF5 file.

Parameters:

path (str) – Path of the ‘.h5’ file in which the data should be stored. If only a directory is given, the filename is chosen as self.name. Raises an error if the given directory does not exist or if the file extension is not ‘.h5’.
backup (bool, optional) – If True, an already existing file is backed up and not overwritten. This keyword is ignored if database=True. The default is True.
database (bool, optional) – If True, the results are appended to the given ‘.h5’ file if it already exists. If False, a new file is created and the old is backed up. If False and the given ‘.h5’ file contains multiple evaluation results, an error is raised. In this case, database has to be set to True. The default is False.
name (str or None, optional) – Name under which the data should be stored in the HDF5 file. If None, self.name is used. The default is None.

Return type:

None.

property times#

Times at which the LDdist is evaluated.

Returns:: Times at which the LDdist is evaluated.
Return type:: np.ndarray