Structures and files¶

Systems¶

System ¶

System(positions=None, box=None, *, table=None, elements=None, types=None, info=None, topology=None)

One atomic configuration: a table of per-atom properties in a box.

A system never changes. Arrays given to it are copied. Methods named with_*, filter, gather and sort return a new system; columns that are not changed are shared, not copied. The values of each atom are read by name, system["positions"].

Parameters:

Name	Type	Description	Default
`positions`	`array_like`	(N, 3) float64 positions in Å. Give either this or `table`.	`None`
`box`	`Box or array_like`	Simulation box, or anything `Box` accepts as lattice vectors. Default: a non-periodic box around the atoms (`Box.enclosing`).	`None`
`table`	`DataFrame`	Per-atom table with a `positions` column of 3 numbers per atom. Give either this or `positions`.	`None`
`elements`	`str or sequence of str`	Chemical symbol of every atom, or one symbol for all atoms. Stored in the `element` column.	`None`
`types`	`int32 or sequence of int32`	Atom types (from 1) of every atom, or one type for all atoms. Stored in the `type` column.	`None`
`info`	`mapping`	Global information such as `energy` (eV) or `timestep`.	`None`
`topology`	`Topology`	Bonds, angles, dihedrals and impropers, with atom indices into the table.	`None`

Raises:

Type	Description
`InvalidParameter`	If the inputs are inconsistent: neither or both of `positions` and `table`, wrong shapes, non-finite positions, unknown chemical symbols, types below 1, missing values in standard columns, or topology indices beyond the number of atoms.

table `property` ¶

table

Per-atom properties, one row per atom. A copy that shares the columns: changing it in place does not change the system; use the with_* methods for a changed system.

box `property` ¶

box

The simulation box.

info `property` ¶

info

Global information, read-only.

topology `property` ¶

topology

Bonds, angles, dihedrals and impropers, or None.

with_table ¶

with_table(table)

New system with a different per-atom table, for operations of polars on the whole table that have no method of their own, such as a join.

Parameters:

Name	Type	Description	Default
`table`	`DataFrame`	New table with the same number of atoms in the same order, since the topology refers to rows by position. Use `sort` or `gather` to reorder atoms and `filter` to remove them.	required

Raises:

Type	Description
`InvalidParameter`	If the number of rows differs or the table is invalid.

with_columns ¶

with_columns(*columns, **named)

New system with added or replaced columns.

Parameters:

Name	Type	Description	Default
`*columns`	`Any`	polars expressions or Series, as for `DataFrame.with_columns`, or results of analyses, whose per-atom values are added.	`()`
`**named`	`Any`	Columns by name: polars expressions or Series, NumPy arrays of shape (N,) or (N, ...), or single values for all atoms. A result of an analysis gets the name as a prefix of its columns, which keeps those of two runs with different parameters.	`{}`

Returns:

Type	Description
`System`	New system; other columns are shared with this one.

with_box ¶

with_box(box, scale_positions=False)

New system in a different box.

Parameters:

Name	Type	Description	Default
`box`	`Box or array_like`	The new box, or lattice vectors for `Box`.	required
`scale_positions`	`bool`	If True, keep the fractional coordinates of the atoms, so that they deform with the box. If False (default), keep the Cartesian positions.	`False`

with_info ¶

with_info(values=None, /, **updates)

New system with other global information.

Parameters:

Name	Type	Description	Default
`values`	`mapping`	Information that replaces all of this system's; `{}` clears it. Without, the information of this system.	`None`
`**updates`	`Any`	Entries to add or replace afterwards. An entry set to None is removed.	`{}`

Raises:

Type	Description
`InvalidParameter`	If values is not a mapping.

with_topology ¶

with_topology(topology)

New system with a different topology, or none.

select ¶

select(*columns)

New system with only the given columns, in that order.

Parameters:

Name	Type	Description	Default
`*columns`	`str \| Expr`	Column names, or polars expressions that compute columns, as for `DataFrame.select`; `positions` must be among them.	`()`

Returns:

Type	Description
`System`	The same atoms with these columns; the box, the information and the topology are kept.

Raises:

Type	Description
`InvalidParameter`	For an unknown column, an expression that cannot be computed or does not give one value per atom, or without `positions`.

drop ¶

drop(*columns)

New system without the given columns.

Parameters:

Name	Type	Description	Default
`*columns`	`str`	Names of the columns to remove; `positions` cannot be.	`()`

Raises:

Type	Description
`InvalidParameter`	For an unknown column, or for `positions`.

rename ¶

rename(names)

New system with columns renamed.

Parameters:

Name	Type	Description	Default
`names`	`mapping`	The new name of each column to rename, such as `{"c_stress": "stress"}`. A column given a standard name, such as `charge`, is checked as one.	required

Raises:

Type	Description
`InvalidParameter`	For an unknown column, a name taken by another column, or a new name for `positions`.

where ¶

where(*conditions, **equal)

The atoms that meet every condition, as a mask.

Parameters:

Name	Type	Description	Default
`*conditions`	`Any`	Each a boolean mask of length N, a polars expression, or a condition written as a Python expression over the columns, such as `"positions.x > 5 and element == 'Cu'"`, as described in Selecting and ordering atoms in the documentation.	`()`
`**equal`	`Any`	Columns and the value each must equal, such as `element="Cu"`.	`{}`

Returns:

Type	Description
`ndarray`	(N,) bool, true for the atoms that meet every condition; every atom without conditions.

Raises:

Type	Description
`InvalidParameter`	For a mask of the wrong length, an unknown column or component, a condition that cannot be read or does not give true or false.

filter ¶

filter(*conditions, **equal)

New system with the atoms that meet every condition, in their order.

Parameters:

Name	Type	Description	Default
`*conditions`	`Any`	Each a boolean mask of length N, a polars expression, or a condition written as a Python expression over the columns, such as `"positions.x > 5 and element == 'Cu'"`, as described in Selecting and ordering atoms in the documentation.	`()`
`**equal`	`Any`	Columns and the value each must equal, such as `element="Cu"`.	`{}`

Returns:

Type	Description
`System`	The atoms kept. Topology terms whose atoms are all kept are kept and renumbered; the others are dropped.

Raises:

Type	Description
`InvalidParameter`	For a mask of the wrong length, an unknown column or component, a condition that cannot be read or does not give true or false.

gather ¶

gather(atoms)

New system with the atoms of the given indices, in that order.

Parameters:

Name	Type	Description	Default
`atoms`	`array_like`	Integer indices; negative ones count from the end; each atom at most once.	required

Returns:

Type	Description
`System`	The atoms, in the given order. Topology terms whose atoms are all given are kept and renumbered; the others are dropped.

Raises:

Type	Description
`InvalidParameter`	For indices that are not integers, out of range or repeated.

sort ¶

sort(*by, descending=False)

New system with the atoms sorted.

Parameters:

Name	Type	Description	Default
`*by`	`str \| Expr`	Columns, components written `column.component` such as `"positions.z"`, or polars expressions; atoms equal in the first are sorted by the second, and so on. Atoms equal in all keep their order. Elements sort by atomic number.	`()`
`descending`	`bool or sequence of bool`	Sort from the largest, for all keys or for each. Default False.	`False`

Returns:

Type	Description
`System`	The atoms in sorted order, with the topology renumbered.

Raises:

Type	Description
`InvalidParameter`	Without a key, or for an unknown column or component.

Box ¶

Box(matrix, origin=(0.0, 0.0, 0.0), pbc=True)

Simulation box: three lattice vectors, an origin and periodicity.

Parameters:

Name	Type	Description	Default
`matrix`	`float64 or array_like`	Lattice vectors in Å. A number gives a cube, three numbers an orthogonal box with these edge lengths, and a (3, 3) array a general box whose rows are the lattice vectors a, b, c.	required
`origin`	`array_like of float64`	Position of the corner of the box in Å. Default (0, 0, 0).	`(0.0, 0.0, 0.0)`
`pbc`	`bool or sequence of 3 bool`	Whether the box is periodic along a, b and c. Default True.	`True`

Raises:

Type	Description
`InvalidParameter`	If the lattice vectors are not finite, have the wrong shape or are linearly dependent, or if origin or pbc are invalid.

matrix `property` ¶

matrix

(3, 3) lattice vectors in Å, one per row. Read-only.

origin `property` ¶

origin

(3,) corner of the box in Å. Read-only.

pbc `property` ¶

pbc

(3,) bool, periodicity along a, b, c. Read-only.

inverse `property` ¶

inverse

(3, 3) inverse of matrix. Read-only.

volume `property` ¶

volume

Volume in Å³.

lengths `property` ¶

lengths

(3,) lengths of a, b, c in Å.

angles `property` ¶

angles

(3,) angles alpha, beta, gamma in degrees.

alpha is between b and c, beta between a and c, and gamma between a and b.

thickness `property` ¶

thickness

(3,) distances in Å between opposite faces of the box.

Entry i is the distance between the two faces that are not crossed by lattice vector i.

is_orthogonal `property` ¶

is_orthogonal

Whether the lattice vectors lie along +x, +y and +z.

from_lengths_angles `classmethod` ¶

from_lengths_angles(a, b, c, alpha=90.0, beta=90.0, gamma=90.0, origin=(0.0, 0.0, 0.0), pbc=True)

Box from edge lengths and angles.

a lies along x and b in the xy plane.

Parameters:

Name	Type	Description	Default
`a`	`float64`	Edge lengths in Å.	required
`b`	`float64`	Edge lengths in Å.	required
`c`	`float64`	Edge lengths in Å.	required
`alpha`	`float64`	Angles in degrees between b and c, a and c, and a and b. Default 90.	`90.0`
`beta`	`float64`	Angles in degrees between b and c, a and c, and a and b. Default 90.	`90.0`
`gamma`	`float64`	Angles in degrees between b and c, a and c, and a and b. Default 90.	`90.0`
`origin`	`ArrayLike`	As for `Box`.	`(0.0, 0.0, 0.0)`
`pbc`	`ArrayLike`	As for `Box`.	`(0.0, 0.0, 0.0)`

Raises:

Type	Description
`InvalidParameter`	If the lengths are not positive or the angles do not form a box.

enclosing `classmethod` ¶

enclosing(positions, padding=1.0)

Non-periodic orthogonal box around a set of positions.

Parameters:

Name	Type	Description	Default
`positions`	`array_like`	(N, 3) float64 positions in Å. N may be 0.	required
`padding`	`float64`	Distance in Å between the outermost atoms and the box faces. Default 1.0; must be positive.	`1.0`

Returns:

Type	Description
`Box`	Box with `pbc` False in all directions.

from_lammps `classmethod` ¶

from_lammps(lo, hi, tilt=(0.0, 0.0, 0.0), pbc=True)

Box from LAMMPS bounds and tilt factors.

Parameters:

Name	Type	Description	Default
`lo`	`array_like`	(xlo, ylo, zlo) float64 and (xhi, yhi, zhi) in Å.	required
`hi`	`array_like`	(xlo, ylo, zlo) float64 and (xhi, yhi, zhi) in Å.	required
`tilt`	`array_like of float64`	Tilt factors (xy, xz, yz) in Å. Default zero.	`(0.0, 0.0, 0.0)`
`pbc`	`bool \| ArrayLike`	As for `Box`.	`True`

to_fractional ¶

to_fractional(positions)

Fractional coordinates of Cartesian positions.

Parameters:

Name	Type	Description	Default
`positions`	`array_like`	(..., 3) float64 positions in Å.	required

Returns:

Type	Description
`ndarray`	(..., 3) float64 coordinates in units of the lattice vectors, relative to `origin`.

to_cartesian ¶

to_cartesian(fractional)

Cartesian positions of fractional coordinates.

Parameters:

Name	Type	Description	Default
`fractional`	`array_like`	(..., 3) float64 coordinates in units of the lattice vectors.	required

Returns:

Type	Description
`ndarray`	(..., 3) float64 positions in Å.

wrap ¶

wrap(positions)

Map positions into the box along periodic directions.

Parameters:

Name	Type	Description	Default
`positions`	`array_like`	(N, 3) float64 positions in Å.	required

Returns:

Name	Type	Description
`wrapped`	`ndarray`	(N, 3) float64 positions in Å. Their fractional coordinates lie in [0, 1) along periodic directions; other directions are unchanged.
`image`	`ndarray`	(N, 3) int64 image flags, so that `positions = wrapped + image @ matrix` up to rounding. Zero along non-periodic directions.

minimum_image ¶

minimum_image(vectors)

Shortest periodic images of displacement vectors.

Parameters:

Name	Type	Description	Default
`vectors`	`array_like`	(N, 3) float64 displacement vectors in Å.	required

Returns:

Type	Description
`ndarray`	(N, 3) float64 vectors, each the shortest among all vectors that differ from the input by a lattice vector along periodic directions. Exact for boxes whose tilt factors stay within half the corresponding edge length, as LAMMPS requires.

to_lammps ¶

to_lammps()

This box in LAMMPS restricted triclinic form.

The box is rotated so that a lies along +x and b in the xy plane with a positive y component. A left-handed set of lattice vectors is first made right-handed by swapping b and c, which describes the same lattice.

Returns:

Type	Description
`LammpsBox`	Bounds, tilt factors and the rotation to apply to positions and other vectors.

allclose ¶

allclose(other, rtol=1e-10, atol=1e-10)

Whether two boxes are equal within a tolerance.

Parameters:

Name	Type	Description	Default
`other`	`Box`	The box to compare with.	required
`rtol`	`float64`	Relative and absolute tolerances in Å, as in `numpy.allclose`.	`1e-10`
`atol`	`float64`	Relative and absolute tolerances in Å, as in `numpy.allclose`.	`1e-10`

Topology ¶

Topology(bonds=None, angles=None, dihedrals=None, impropers=None)

Bonds, angles, dihedrals and impropers of a molecular system.

Each kind of term is a polars DataFrame with an atoms column of 0-based atom indices (rows of the system's table), a type column of integer types starting at 1, an optional type_label column, and any further columns.

Parameters:

Name	Type	Description	Default
`bonds`	`DataFrame or array_like`	Terms with 2, 3, 4 and 4 atoms. An (M, k) integer array gives atom indices with all types equal to 1. Atom order follows LAMMPS: the central atom of an angle is the second one, dihedral atoms follow the chain, and improper order depends on the improper style.	`None`
`angles`	`DataFrame or array_like`	Terms with 2, 3, 4 and 4 atoms. An (M, k) integer array gives atom indices with all types equal to 1. Atom order follows LAMMPS: the central atom of an angle is the second one, dihedral atoms follow the chain, and improper order depends on the improper style.	`None`
`dihedrals`	`DataFrame or array_like`	Terms with 2, 3, 4 and 4 atoms. An (M, k) integer array gives atom indices with all types equal to 1. Atom order follows LAMMPS: the central atom of an angle is the second one, dihedral atoms follow the chain, and improper order depends on the improper style.	`None`
`impropers`	`DataFrame or array_like`	Terms with 2, 3, 4 and 4 atoms. An (M, k) integer array gives atom indices with all types equal to 1. Atom order follows LAMMPS: the central atom of an angle is the second one, dihedral atoms follow the chain, and improper order depends on the improper style.	`None`

Raises:

Type	Description
`InvalidParameter`	If a table has the wrong shape or types, negative indices, a term with a repeated atom, missing values, or a type below 1.

bonds `property` ¶

bonds

Bonds: atoms holds 2 atom indices.

angles `property` ¶

angles

Angles: atoms holds 3 atom indices, the vertex in the middle.

dihedrals `property` ¶

dihedrals

Dihedrals: atoms holds 4 atom indices along the chain.

impropers `property` ¶

impropers

Impropers: atoms holds 4 atom indices.

tables ¶

tables()

All four tables, keyed by kind.

max_atom_index ¶

max_atom_index()

Largest atom index used by any term, or -1 if there are none.

remap ¶

remap(mapping)

Topology after atoms are renumbered or removed.

Parameters:

Name	Type	Description	Default
`mapping`	`ndarray`	(N,) int64, for each old atom index, its new index, or -1 if the atom is removed. Terms that contain a removed atom are dropped.	required

Returns:

Type	Description
`Topology`	New topology with renumbered atoms.

LammpsBox ¶

Bases: NamedTuple

A box in LAMMPS restricted triclinic form.

Attributes:

Name	Type	Description
`lo`	`ndarray`	(3,) float64, (xlo, ylo, zlo) in Å.
`hi`	`ndarray`	(3,) float64, (xhi, yhi, zhi) in Å.
`tilt`	`ndarray`	(3,) float64, tilt factors (xy, xz, yz) in Å.
`rotation`	`ndarray`	(3, 3) float64 rotation matrix. A position or other vector `v` (row vector) of the original box becomes `v @ rotation` in the LAMMPS box. It is exactly the identity when the box already has this form.

Files¶

read ¶

read(path, format=None, *, frame=0, **options)

Reads one frame of a file.

Parameters:

Name	Type	Description	Default
`path`	`str or PathLike`	The file. Compressed files (gzip, bzip2, xz, zstd) are recognized from their content.	required
`format`	`str`	Format name; by default it is found from the file name with `detect_format`.	`None`
`frame`	`int32`	Index of the frame to read, for files that hold several frames. Negative values count from the end. Default 0, the first frame.	`0`
`**options`		Options of the format; see the page of each format.	`{}`

Returns:

Type	Description
`System`	The frame.

Raises:

Type	Description
`UnsupportedFormat`	If the format is unknown or cannot be read.
`InvalidParameter`	If the frame does not exist.
`FileFormatError`	If the file does not follow its format.

write ¶

write(path, systems, format=None, **options)

Writes systems to a file.

Parameters:

Name	Type	Description	Default
`path`	`str or PathLike`	The file; it is replaced if it exists. The suffix .gz, .bz2, .xz or .zst compresses it.	required
`systems`	`System or iterable of System`	One system, or several for formats that hold several frames. An iterator, such as a generator, is written one system at a time.	required
`format`	`str`	Format name; by default it is found from the file name with `detect_format`.	`None`
`**options`		Options of the format; see the page of each format.	`{}`

Raises:

Type	Description
`UnsupportedFormat`	If the format is unknown or cannot be written.
`InvalidParameter`	If the format holds one frame and not exactly one system is given, or if a system cannot be written in the format.

formats ¶

formats()

The file formats MDAPY can read or write.

Returns:

Type	Description
`DataFrame`	One row per format, with columns `name`, `description`, `extensions`, `read`, `write` and `multiple_frames`.

detect_format ¶

detect_format(path)

The format of a file, from its name.

A compression suffix (.gz, .bz2, .xz, .zst) is ignored. The extension is compared first; file name patterns, such as data.* for LAMMPS data files, are used only when no extension matches.

Parameters:

Name	Type	Description	Default
`path`	`str or PathLike`	The file name; the file need not exist.	required

Returns:

Type	Description
`str`	The format name.

Raises:

Type	Description
`UnsupportedFormat`	If no format, or more than one, matches the name.

Mapped ¶

Mapped(frames, function)

Bases: Sequence[System]

Frames through a function, each computed when it is used, as Trajectory.map gives them.

map ¶

map(function)

These frames through one more function, as Trajectory.map.

Trajectories¶

read_trajectory ¶

read_trajectory(path, format=None, *, topology=None, **options)

Opens the frames of files without reading them.

Parameters:

Name	Type	Description	Default
`path`	`str, os.PathLike or sequence of them`	The file; a pattern with ``, such as `"dump..lammpstrj"`, for the files it matches in the order of the numbers in their names; or files in order. The frames of each file follow those of the file before.	required
`format`	`str`	Format name for every file; by default that of the name of each file, with `detect_format`, or of the first file when a name tells nothing.	`None`
`topology`	`System`	A system, such as one read from a LAMMPS data file, whose atoms the frames move: each frame gets its atoms, matched by id, in their order, with their topology and the columns the frame lacks, such as charges, molecules and masses; the box of the frame with the periodicity of the system. Atoms missing from a frame are left out with their bonds, angles and so on.	`None`
`**options`		Options of the format, used for every frame.	`{}`

Returns:

Type	Description
`Trajectory`	The frames. Frames are found as far as they are used, so iterating over a long file starts at once.

Raises:

Type	Description
`UnsupportedFormat`	If the format is unknown or cannot be read.
`FileNotFoundError`	If no file matches a pattern.
`InvalidParameter`	For an empty list of files; on reading a frame with a topology, if it has atoms not in the topology, if ids repeat, or if without ids the numbers of atoms differ.

Trajectory ¶

Trajectory(frames, options, indices, topology=None)

Bases: Sequence[System]

The frames of a file, read when they are used.

Create it with mdapy.io.read_trajectory. Indexing with an integer reads one frame; indexing with a slice gives a trajectory of the selected frames; iterating reads the frames one after the other. The file stays open until close is called, the trajectory is used as a context manager, or no trajectory of the file is used any more.

path `property` ¶

path

Name of the file, or the pattern or first file of several.

format `property` ¶

format

Format of the file, or of the first of several.

file_of ¶

file_of(index)

The file that holds a frame, without reading the frame.

Parameters:

Name	Type	Description	Default
`index`	`int32`	The index of the frame; negative ones count from the end.	required

Returns:

Type	Description
`str`	The path of the file.

Raises:

Type	Description
`IndexError`	If there is no such frame.

map ¶

map(function)

The frames through a function, each computed when it is used.

Parameters:

Name	Type	Description	Default
`function`	`callable`	A function of a frame that gives a system, such as a pipeline of analyses that adds their columns.	required

Returns:

Type	Description
`Mapped`	A sequence of the frames through the function, with `len`, indexing, slices (themselves mapped) and iteration, which reads the frames one after the other; `map` adds another function. Analyses of trajectories and `mdapy.transform.remove_drift` or `mdapy.transform.smooth_trajectory` take it as they take the trajectory.

close ¶

close()

Releases the files, also for the slices of this trajectory.

Neighbors¶

NeighborList ¶

NeighborList(system, cutoff, offsets, j, shifts, distances, num_neighbors=None, areas=None)

Pairs of atoms within a cutoff, the nearest neighbors of each atom, or the atoms that share a Voronoi face, including periodic images.

Build one with build. Pairs are grouped by the first atom: the pairs of atom i are offsets[i]:offsets[i + 1]. The vector from atom i to the image of atom j is x[j] - x[i] + shifts @ box.matrix.

Attributes:

Name	Type	Description
`system`	`System`	The system the list was built for.
`cutoff`	`float64`	Every pair is closer than it, in Å.
`num_neighbors`	`int32 or None`	The number of pairs of each atom in a list of nearest neighbors, None otherwise.
`voronoi`	`bool`	Whether the pairs are the atoms that share a Voronoi face.
`offsets`	`ndarray`	(N + 1,) int64.
`j`	`ndarray`	(P,) `mdapy.index_dtype`, the second atom of each pair.
`shifts`	`ndarray`	(P, 3) int8 periodic image of the second atom.
`distances`	`ndarray`	(P,) float64 distances in Å.
`areas`	`ndarray or None`	(P,) float64 area in Å² of the Voronoi face of each pair in a list of Voronoi neighbors, None otherwise.

counts `property` ¶

counts

(N,) int64 number of pairs of each atom.

i `property` ¶

(P,) mdapy.index_dtype first atom of each pair, made from the offsets on each access, not kept.

vectors `property` ¶

vectors

(P, 3) float64 vectors from the first atom to the second, in Å, computed from the positions and the shifts on each access, not kept.

build `classmethod` ¶

build(system, cutoff=None, *, num_neighbors=None, voronoi=False, face_threshold=0.0, relative_face_threshold=0.0, edge_threshold=0.0, progress=None, cancel=None)

All pairs of atoms closer than a cutoff, the nearest neighbors of each atom, or the atoms that share a Voronoi face.

Parameters:

Name	Type	Description	Default
`system`	`System`	The atoms and the box. Any box works; a box thinner than the cutoff gives several images of the same neighbor, and images of the atom itself.	required
`cutoff`	`float64`	Cutoff radius in Å, positive.	`None`
`num_neighbors`	`int32`	Number of nearest neighbors of each atom, positive.	`None`
`voronoi`	`bool`	The neighbors of an atom are the atoms across the faces of its Voronoi cell that count. Give one of cutoff, num_neighbors and voronoi.	`False`
`face_threshold`	`float64`	With voronoi, the faces that count, as in `mdapy.analysis.VoronoiAnalysis`. Default 0.	`0.0`
`relative_face_threshold`	`float64`	With voronoi, the faces that count, as in `mdapy.analysis.VoronoiAnalysis`. Default 0.	`0.0`
`edge_threshold`	`float64`	With voronoi, the faces that count, as in `mdapy.analysis.VoronoiAnalysis`. Default 0.	`0.0`
`progress`	`callable`	Called as `progress(done, total)` while the list is built.	`None`
`cancel`	`CancelToken`	Stops the search.	`None`

Returns:

Type	Description
`NeighborList`	With a cutoff, every pair closer than it, grouped by the first atom. With num_neighbors, that many pairs per atom, nearest first (ties by the second atom, then the image). With voronoi, a pair for each face that counts of the cell of the first atom, with its area; the walls of the box are left out. Lists of nearest and of Voronoi neighbors have as cutoff the largest distance, slightly enlarged.

Raises:

Type	Description
`InvalidParameter`	For an invalid cutoff, num_neighbors or threshold, when a system without periodic directions has num_neighbors atoms or fewer, when a periodic image is more than 127 boxes away, or, with voronoi, for two atoms at the same position.

fits ¶

fits(system)

Whether the list holds the pairs of a system: the one it was built for, or any with the same positions in the same box, whatever its other columns.

Parameters:

Name	Type	Description	Default
`system`	`System`	The system.	required

Returns:

Type	Description
`bool`	True when the list serves the system.

within ¶

within(cutoff)

The pairs closer than a smaller cutoff, without a new search.

Parameters:

Name	Type	Description	Default
`cutoff`	`float64`	Cutoff radius in Å, positive and at most the cutoff of this list.	required

Returns:

Type	Description
`NeighborList`	The pairs closer than cutoff, in their order; this list itself when cutoff is its own.

sorted ¶

sorted()

The same pairs, each atom's sorted by distance, ties by atom and then image as in a list of nearest neighbors.

Returns:

Type	Description
`NeighborList`	A list with the pairs of each atom nearest first.

expand_selection ¶

expand_selection(system, atoms, *, cutoff=None, num_neighbors=None, bonds=False, iterations=1)

Atoms and their neighbors: a selection grown by the atoms near it.

Parameters:

Name	Type	Description	Default
`system`	`System`	The atoms and the box.	required
`atoms`	`array_like`	A boolean mask or indices of the atoms selected.	required
`cutoff`	`float64`	Add the atoms closer than this in Å to a selected atom.	`None`
`num_neighbors`	`int32`	Add the num_neighbors nearest neighbors of each selected atom.	`None`
`bonds`	`bool`	Add the atoms bonded to a selected atom, by the bonds of the topology.	`False`
`iterations`	`int32`	How many times the selection grows, each time by the neighbors of all the atoms selected so far. Default 1.	`1`

Returns:

Type	Description
`ndarray`	(N,) bool, the atoms selected and those added.

Raises:

Type	Description
`InvalidParameter`	If not exactly one of cutoff, num_neighbors and bonds is given, if iterations is negative or not an integer, if atoms is not a mask or indices of the system, and as `NeighborList.build`.
`MissingProperty`	With bonds, if the system has no bonds.

find_overlapping ¶

find_overlapping(system, distance, *, keep_one=True, atoms=None)

Atoms closer than a distance to another atom.

Parameters:

Name	Type	Description	Default
`system`	`System`	The atoms and the box.	required
`distance`	`float64`	Two atoms closer than this in Å overlap.	required
`keep_one`	`bool`	Whether to select only the atom of the higher index of each pair that overlaps, so that deleting the selection leaves no pair that close and keeps one atom of each group of atoms that all overlap, or both. Default True.	`True`
`atoms`	`array_like`	A boolean mask or indices of the atoms considered; the others neither overlap nor are selected. Default all of them.	`None`

Returns:

Type	Description
`ndarray`	(N,) bool, the atoms selected.

Raises:

Type	Description
`InvalidParameter`	If atoms is not a mask or indices of the system, and as `NeighborList.build` for the distance.

Structures and files¶

Systems¶

System ¶

table property ¶

box property ¶

info property ¶

topology property ¶

with_table ¶

with_columns ¶

with_box ¶

with_info ¶

with_topology ¶

select ¶

drop ¶

rename ¶

where ¶

filter ¶

gather ¶

sort ¶

Box ¶

matrix property ¶

origin property ¶

pbc property ¶

inverse property ¶

volume property ¶

lengths property ¶

angles property ¶

thickness property ¶

is_orthogonal property ¶

from_lengths_angles classmethod ¶

enclosing classmethod ¶

from_lammps classmethod ¶

to_fractional ¶

to_cartesian ¶

wrap ¶

minimum_image ¶

to_lammps ¶

allclose ¶

Topology ¶

bonds property ¶

angles property ¶

dihedrals property ¶

impropers property ¶

tables ¶

max_atom_index ¶

remap ¶

LammpsBox ¶

Files¶

read ¶

write ¶

formats ¶

detect_format ¶

Mapped ¶

map ¶

Trajectories¶

read_trajectory ¶

Trajectory ¶

path property ¶

format property ¶

file_of ¶

map ¶

close ¶

Neighbors¶

NeighborList ¶

counts property ¶

i property ¶

vectors property ¶

build classmethod ¶

fits ¶

within ¶

sorted ¶

expand_selection ¶

find_overlapping ¶

table `property` ¶

box `property` ¶

info `property` ¶

topology `property` ¶

matrix `property` ¶

origin `property` ¶

pbc `property` ¶

inverse `property` ¶

volume `property` ¶

lengths `property` ¶

angles `property` ¶

thickness `property` ¶

is_orthogonal `property` ¶

from_lengths_angles `classmethod` ¶

enclosing `classmethod` ¶

from_lammps `classmethod` ¶

bonds `property` ¶

angles `property` ¶

dihedrals `property` ¶

impropers `property` ¶

path `property` ¶

format `property` ¶

counts `property` ¶

i `property` ¶

vectors `property` ¶

build `classmethod` ¶