dscribe.core.system module¶

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class dscribe.core.system.System(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None, wyckoff_positions=None, equivalent_atoms=None)[source]¶

Bases: ase.atoms.Atoms

Represents atomic systems that are used internally by the package. Inherits from the ase.Atoms class, but adds the possibility to cache various time-consuming quantities that can be shared when creating multiple descriptors.

static from_atoms(atoms)[source]¶: Creates a System object from ASE.Atoms object.

get_cell_inverse()[source]¶: Get the matrix inverse of the lattice matrix.

get_displacement_tensor()[source]¶

A matrix where the entry A[i, j, :] is the vector self.cartesian_pos[j] - self.cartesian_pos[i].

For periodic systems the distance of an atom from itself is the smallest displacement of an atom from one of it’s periodic copies, and the distance of two different atoms is the distance of two closest copies.

Returns: 3D matrix containing the pairwise distance vectors.
Return type: np.array

get_distance_matrix()[source]¶

Calculates the distance matrix A defined as:

\[A_{ij} = \lvert \mathbf{r}_i - \mathbf{r}_j \rvert\]

For periodic systems the distance of an atom from itself is the smallest displacement of an atom from one of it’s periodic copies, and the distance of two different atoms is the distance of two closest copies.

Returns: Symmetric 2D matrix containing the pairwise distances.
Return type: np.array

get_distance_matrix_within_radius(radius, pos=None, output_type='coo_matrix')[source]¶

Calculates a sparse distance matrix by only considering distances within a certain cutoff. Uses a k-d tree to reach O(n log(N)) time complexity.

Parameters

radius (float) – The cutoff radius within which distances are calculated. Distances outside this radius are not included.
output_type (str) – Which container to use for output data. Options: “dok_matrix”, “coo_matrix”, “dict”, or “ndarray”. Default: “dok_matrix”.

Returns

Symmetric sparse 2D matrix containing the pairwise distances.

Return type

dok_matrix | np.array | coo_matrix | dict

get_inverse_distance_matrix()[source]¶

Calculates the inverse distance matrix A defined as:

\[A_{ij} = \frac{1}{\lvert \mathbf{r}_i - \mathbf{r}_j \rvert }\]

For periodic systems the distance of an atom from itself is the smallest displacement of an atom from one of it’s periodic copies, and the distance of two different atoms is the distance of two closest copies.

Returns: Symmetric 2D matrix containing the pairwise inverse distances.
Return type: np.array

set_cell(cell, scale_atoms=False)[source]¶

Set unit cell vectors.

Parameters:

cell: 3x3 matrix or length 3 or 6 vector: Unit cell. A 3x3 matrix (the three unit cell vectors) or just three numbers for an orthorhombic cell. Another option is 6 numbers, which describes unit cell with lengths of unit cell vectors and with angles between them (in degrees), in following order: [len(a), len(b), len(c), angle(b,c), angle(a,c), angle(a,b)]. First vector will lie in x-direction, second in xy-plane, and the third one in z-positive subspace.
scale_atoms: bool: Fix atomic positions or move atoms with the unit cell? Default behavior is to not move the atoms (scale_atoms=False).
apply_constraint: bool: Whether to apply constraints to the given cell.

Examples:

Two equivalent ways to define an orthorhombic cell:

>>> atoms = Atoms('He')
>>> a, b, c = 7, 7.5, 8
>>> atoms.set_cell([a, b, c])
>>> atoms.set_cell([(a, 0, 0), (0, b, 0), (0, 0, c)])

FCC unit cell:

>>> atoms.set_cell([(0, b, b), (b, 0, b), (b, b, 0)])

Hexagonal unit cell:

>>> atoms.set_cell([a, a, c, 90, 90, 120])

Rhombohedral unit cell:

>>> alpha = 77
>>> atoms.set_cell([a, a, a, alpha, alpha, alpha])

set_pbc(pbc)[source]¶: Set periodic boundary condition flags.

set_positions(newpositions, apply_constraint=True)[source]¶: Set positions, honoring any constraints. To ignore constraints, use apply_constraint=False.

set_scaled_positions(scaled)[source]¶: Set positions relative to unit cell.

to_cartesian(scaled_positions, wrap=False)[source]¶

Used to transofrm a set of relative positions to the cartesian basis defined by the cell of this system.

Parameters

positions (numpy.ndarray) – The positions to scale
wrap (numpy.ndarray) – Whether the positions should be wrapped inside the cell.

Returns

The cartesian positions

Return type

numpy.ndarray

to_scaled(positions, wrap=False)[source]¶

Used to transform a set of positions to the basis defined by the cell of this system.

Parameters

positions (numpy.ndarray) – The positions to scale
wrap (numpy.ndarray) – Whether the positions should be wrapped inside the cell.

Returns

The scaled positions

Return type

numpy.ndarray