Structure builder

Crystals and alloys

build_crystal

build_crystal(structure, a, *, c=None, elements='X', orientation=None, repeat=(1, 1, 1))

A perfect crystal in a periodic box, optionally along chosen crystal directions.

Parameters:

Name	Type	Description	Default
structure	str	One of mdapy.build.STRUCTURES: "sc", "bcc", "fcc", "diamond", "cscl", "rocksalt", "zincblende", "fluorite", "l1_2", "perovskite", "hcp", "wurtzite", "lonsdaleite", "graphite" or "graphene".	required
a	float64	Lattice constant in Å.	required
c	float64	Lattice constant c of a hexagonal structure in Å; by default the ideal sqrt(8/3) a, and needed for graphite and graphene.	None
elements	str or sequence of str	The element of every atom, or of each sublattice of the structure. Default "X".	'X'
orientation	sequence of three directions	The crystal directions along the three box vectors: [hkl] in the cubic cell, orthogonal; or [uvw] or [hkil] in the hexagonal cell, linearly independent. Default the cell itself.	None
repeat	sequence of int32	Number of periods along each box vector. Default (1, 1, 1).	(1, 1, 1)

Returns:

Type	Description
System	The crystal, ordered by z, then y, then x.

random_alloy

random_alloy(system, fractions, *, seed=None)

The system with its elements drawn at random in given fractions.

Parameters:

Name	Type	Description	Default
system	System	The sites, for example a crystal from build_crystal.	required
fractions	mapping of str to float64	Fraction of each element, positive; they are normalized to sum to 1.	required
seed	int64 or Generator	Seed of the random order; the same seed gives the same alloy.	None

Returns:

Type	Description
System	The system with a new element column. The number of atoms of each element is its fraction of the atoms, rounded so that the counts add up, the largest remainders rounded up.

sqs_alloy

sqs_alloy(system, fractions, *, shells=3, weights=None, steps=100000, temperature=1.0, seed=None, progress=None, cancel=None)

A special quasirandom structure: elements in given fractions on the sites of a perfect lattice, arranged so that the pairs of the nearest shells of neighbors are those of a random alloy.

Parameters:

Name	Type	Description	Default
system	System	The sites, a perfect lattice such as from build_crystal.	required
fractions	mapping of str to float64	Fraction of each element, positive; normalized to sum to 1, with the counts of random_alloy.	required
shells	int32	The number of shells of neighbors made random, 1 to 10. Default 3.	3
weights	sequence of float64	The weight of each shell in the deviation minimized. Default all 1.	None
steps	int64	Number of swaps of two atoms tried. Default 100000.	100000
temperature	float64	The starting temperature of the annealing, in units of the typical change of a swap; 0 accepts only improvements. Default 1.	1.0
seed	int64 or Generator	Seed of the starting alloy and of the swaps.	None

Returns:

Type	Description
System	The system with a new element column.

Defects

add_vacancies

add_vacancies(system, count=None, *, atoms=None, seed=None)

The system without some of its atoms.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
count	int32	Number of atoms removed at random.	None
atoms	array_like	Instead of count, the indices of the atoms removed, or a boolean mask.	None
seed	int64 or Generator	Seed of the random choice.	None

Returns:

Type	Description
System	The other atoms, in their order.

add_interstitials

add_interstitials(system, element, count=None, *, positions=None, min_distance=1.0, seed=None, attempts=1000)

The system with atoms added at given or random positions.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
element	str	The element of the added atoms.	required
count	int32	Number of atoms added at random positions in the box, each at least min_distance from every other atom.	None
positions	array_like	Instead of count, the (M, 3) positions of the added atoms in Å.	None
min_distance	float64	With count, the smallest distance in Å to the other atoms. Default 1.	1.0
seed	int64 or Generator	Seed of the random positions.	None
attempts	int32	With count, the number of random positions tried for each atom before giving up. Default 1000.	1000

Returns:

Type	Description
System	The atoms of the system followed by the added ones; columns other than the positions and the elements are those of the system, the added atoms taking the values of the first atom.

substitute

substitute(system, element, count=None, *, atoms=None, seed=None)

The system with some of its atoms of another element.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
element	str	The new element.	required
count	int32	Number of atoms changed at random.	None
atoms	array_like	Instead of count, the indices of the atoms changed, or a boolean mask.	None
seed	int64 or Generator	Seed of the random choice.	None

Returns:

Type	Description
System	The same atoms, those chosen of the element.

slip

slip(system, displacement, *, height=None, axis=2)

The system with the atoms above a plane moved, such as to make a stacking fault.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
displacement	array_like	(3,) float64 displacement in Å of the atoms above the plane, along it.	required
height	float64	The plane, at this fractional coordinate along the box vector of axis. Default 0.5, the middle of the box.	None
axis	int32 or str	The box vector normal to the plane, 0, 1, 2 or x, y, z. Default z.	2

Returns:

Type	Description
System	The atoms, those above the plane moved. Along a periodic axis the box vector moves with them, so that the box holds the one plane of slip.

add_vacuum

add_vacuum(system, thickness, *, axis=2)

The system in a box longer along one of its vectors, such as for a slab with two surfaces.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
thickness	float64	Length in Å added to the box along the vector of axis.	required
axis	int32 or str	The box vector made longer, 0, 1, 2 or x, y, z. Default z.	2

Returns:

Type	Description
System	The same atoms, unwrapped across the boundary of that axis so that none is cut off, in the longer box; the periodicity is kept.

Dislocations

insert_dislocation

insert_dislocation(system, burgers, *, line=2, normal=1, center=None, poisson=1 / 3, elastic=None, orientation=None)

The system with a straight dislocation along a box axis, its atoms displaced as isotropic or anisotropic elasticity predicts.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
burgers	array_like	(3,) float64 Burgers vector in Å, in the plane of cut: its part along line is the screw part, the rest the edge part.	required
line	int32 or str	The Cartesian axis along the dislocation line, 0, 1, 2 or x, y, z. Default z.	2
normal	int32 or str	The Cartesian axis normal to the plane of cut, other than line. Default y.	1
center	array_like	(3,) float64, a point of the dislocation line in Å. Default the center of the box.	None
poisson	float64	Poisson's ratio, from -1 to below 0.5, for isotropic elasticity. Default 1/3.	1 / 3
elastic	array_like of float64	Elastic constants of a cubic crystal for anisotropic elasticity: (C11, C12, C44) or the (6, 6) Voigt matrix, in any unit, in the axes of the cubic cell. Default isotropic elasticity.	None
orientation	array_like	The crystal directions along x, y and z, orthogonal, with elastic. Default the axes of the cubic cell.	None

Returns:

Type	Description
System	The same atoms, displaced; the box is unchanged.

edge_dislocation

edge_dislocation(cell, repeat)

An edge dislocation between two crystals, with one more period along x below its line than above.

Parameters:

Name	Type	Description	Default
cell	System	An orthogonal periodic cell whose period along x is the Burgers vector, such as fcc along [1-10], [11-2], [111].	required
repeat	tuple of int32	(nx, ny, nz): above the line nx periods along x, below it nx + 1; ny along y, the line; nz along z in all, at least 2.	required

Returns:

Type	Description
System	The lower crystal compressed and the upper one stretched along x to nx + 1/2 periods, in a box periodic along x and y but not z; the line lies between them, at the middle of x.

Dislocation dataclass

Dislocation(structure, orientation, burgers, partial=False, core=(0.5, 0.5))

A straight dislocation in a cubic crystal.

Attributes:

Name	Type	Description
structure	str	A cubic structure of build_crystal, such as "bcc", "fcc" or "diamond".
orientation	tuple of three directions	The crystal directions along x, y and z, orthogonal and right-handed: x in the glide plane, y normal to it, z along the line.
burgers	tuple of float64	The Burgers vector in the axes of the cubic cell, in units of the lattice constant, in the glide plane: the one the dislocation analysis, as OVITO's, finds along +z.
partial	bool	A single Shockley partial, which bounds a stacking fault on its -x side. Default False.
core	tuple of float64	Where the line lies: (s, t), s rows of atoms along x from a row of the plane of atoms below it and t of the way to the plane above. Default (0.5, 0.5).

dislocation_cylinder

dislocation_cylinder(dislocation, a, elastic, radius, *, elements='X', length=1, fixed=6.0, dissociation=0.0)

A cylinder of crystal around a straight dislocation along its axis, displaced as anisotropic elasticity predicts, the atoms of its outer shell fixed.

Parameters:

Name	Type	Description	Default
dislocation	str or Dislocation	The dislocation: a name of mdapy.build.DISLOCATIONS or one of your own.	required
a	float64	Lattice constant in Å.	required
elastic	array_like of float64	The elastic constants in the axes of the cubic cell: (C11, C12, C44) or the (6, 6) Voigt matrix, in any unit.	required
radius	float64	Radius of the cylinder in Å.	required
elements	str or sequence of str	As for build_crystal. Default "X".	'X'
length	int32	Number of periods of the crystal along the line. Default 1.	1
fixed	float64	Thickness in Å of the outer shell whose atoms are fixed. Default 6.	6.0
dissociation	float64	Distance in Å between the two Shockley partials of an fcc or diamond dislocation, rounded to whole rows of atoms; 0 for a perfect one. Default 0.	0.0

Returns:

Type	Description
System	The cylinder along z in a box periodic along z only, the line at the middle of x and y; movable is False for the atoms of the fixed shell.

dislocation_quadrupole

dislocation_quadrupole(dislocation, a, elastic, repeat, *, elements='X', dissociation=0.0)

A periodic crystal with a dipole of straight dislocations of opposite Burgers vectors, whose periodic images make a quadrupolar lattice, displaced as anisotropic elasticity predicts.

Parameters:

Name	Type	Description	Default
dislocation	str or Dislocation	The dislocation: a name of mdapy.build.DISLOCATIONS or one of your own, not a partial.	required
a	float64	Lattice constant in Å.	required
elastic	array_like of float64	The elastic constants in the axes of the cubic cell: (C11, C12, C44) or the (6, 6) Voigt matrix, in any unit.	required
repeat	tuple of int32	Periods of the oriented crystal along x, y and z, at least 2 along x and y.	required
elements	str or sequence of str	As for build_crystal. Default "X".	'X'
dissociation	float64	Distance in Å between the two Shockley partials of each fcc or diamond dislocation, rounded to whole rows of atoms; 0 for perfect ones. Default 0.	0.0

Returns:

Type	Description
System	The crystal in a periodic box tilted by the plastic strain of the dipole: the dislocation at a quarter of x and y, the opposite one half a box away along both. With an edge part, the slab of atoms between their glide planes that the cut sweeps is taken away.

Polycrystals

build_polycrystal

build_polycrystal(unit, box, grains, *, orientations=None, min_distance=None, seed=None)

A polycrystal: each grain the crystal of a unit cell, rotated, filling the Voronoi cell of its seed in a periodic box.

Parameters:

Name	Type	Description	Default
unit	System	The crystal of every grain, in a periodic box: a unit cell or any periodic arrangement, such as twin lamellae.	required
box	Box or array_like	The box of the polycrystal, periodic in every direction: a Box or its lattice vectors. Along an axis no longer than the box of unit, the polycrystal is columnar: every grain spans that axis, its box takes the length of the unit there, and the grains turn about it.	required
grains	int32 or array_like	Number of grains, with seeds at random positions, or the (G, 3) positions of the seeds in Å.	required
orientations	array_like	(G, 3, 3) float64 rotation of each grain, taking the axes of unit to those of the box; in a columnar polycrystal rotations about its axis. Uniformly random by default.	None
min_distance	float64	Of two atoms closer than this, in Å, the later is removed: atoms of neighboring grains that come too close, and the copies of atoms on the faces of a cell. Default 0.7 times the nearest distance in unit.	None
seed	int64 or Generator	Seed of the random seeds and orientations.	None

Returns:

Type	Description
System	The atoms with a grain column, numbered as the seeds; each seed is a site of the unit in its grain. info["seeds"] holds the (G, 3) positions of the seeds.

random_rotations

random_rotations(count, seed=None)

Rotation matrices drawn uniformly over all orientations.

Parameters:

Name	Type	Description	Default
count	int32	Number of rotations.	required
seed	int64 or Generator	Seed of the random rotations.	None

Returns:

Type	Description
ndarray	(count, 3, 3) float64 rotation matrices.

rotations_about

rotations_about(axis, angles)

Rotation matrices about one Cartesian axis, as the turns of the grains of a columnar polycrystal.

Parameters:

Name	Type	Description	Default
axis	int32 or str	The axis: x, y, z or 0, 1, 2.	required
angles	array_like of float64	The angles in degrees, counterclockwise seen from the end of the axis.	required

Returns:

Type	Description
ndarray	(G, 3, 3) float64 rotation matrices.

gradient_seeds

gradient_seeds(box, sizes, *, axis=2, columns=None, seed=None)

The seeds of a polycrystal whose grain size changes along one box vector.

Parameters:

Name	Type	Description	Default
box	Box or array_like	The box of the polycrystal: a Box or its lattice vectors.	required
sizes	array_like	(K, 2) float64, the positions along the box vector, as fractions from 0 to 1, and the grain size in Å there, linear between them; the first at 0 and the last at 1, in increasing order.	required
axis	int32 or str	The box vector along which the size changes. Default z.	2
columns	int32 or str	The box vector of the columns of a columnar polycrystal: the seeds lie in one plane, and a grain size is the diameter of the circle of the same area. By default the seeds fill the box, and a grain size is the diameter of the sphere of the same volume.	None
seed	int64 or Generator	Seed of the random seeds.	None

Returns:

Type	Description
ndarray	(G, 3) float64 positions of the seeds in Å, for build_polycrystal.

twin_lamellae

twin_lamellae(cell, layers)

A crystal of twin lamellae: lamellae of layers atomic planes normal to z, each the mirror image of the next across the plane between them.

Parameters:

Name	Type	Description	Default
cell	System	A periodic crystal whose third box vector is along z and whose atoms lie on equally spaced planes normal to z, such as fcc with z along [111].	required
layers	int32	Number of atomic planes in each lamella, at least 2.	required

Returns:

Type	Description
System	Two lamellae, 2 layers planes along z, with the box of cell in x and y; repeated along z, the twin boundaries are equally spaced.

add_graphene

add_graphene(polycrystal, *, layers=1, coverage=1.0, clearance=3.0, bond=1.42, spacing=3.35, seed=None)

Graphene on the grain boundaries of a polycrystal.

Parameters:

Name	Type	Description	Default
polycrystal	System	A polycrystal from build_polycrystal, with the seeds of its grains in info["seeds"] and a grain column.	required
layers	int32	Number of graphene layers on each boundary, AB stacked and centered on it; where two faces meet, each layer ends where the planes halfway between the faces cross. Default 1.	1
coverage	float64	Fraction of the area of the boundaries covered, from 0 to 1: whole faces between two grains are covered, in random order, until the fraction is reached. Default 1, every face.	1.0
clearance	float64	Atoms of the polycrystal closer than this to a carbon atom, in Å, are removed. Default 3, about the distance of graphene from copper.	3.0
bond	float64	Carbon-carbon bond length of graphene in Å. Default 1.42.	1.42
spacing	float64	Distance between graphene layers in Å. Default 3.35.	3.35
seed	int64 or Generator	Seed of the random faces and orientations of the graphene.	None

Returns:

Type	Description
System	The atoms of the polycrystal left and the carbon atoms of the graphene, whose grain is -1; of two carbon atoms of different faces closer than 0.85 bond, where faces meet, the later is left out.

Raises:

Type	Description
MissingProperty	If the polycrystal has no seeds in its info.
InvalidParameter	For layers below 1, a coverage outside 0 to 1, or lengths that are not positive.

Transforming

replicate

replicate(system, repeat)

Copies of the system side by side along the lattice vectors.

Parameters:

Name	Type	Description	Default
system	System	The system to copy.	required
repeat	int32 or sequence of 3 int32	Number of copies along a, b and c, at least 1; more than 1 only along periodic directions.	required

Returns:

Type

Description

System

The copies, one after another with the copy along a changing fastest, in a box with the lattice vectors multiplied by repeat. Ids and molecules (those above 0) of each copy are offset by the largest of the original; topology terms are copied within each copy. With an image column, each atom is placed by its unwrapped position and its image flags are those of the new box; without one, the copies are translated. energy and virial are left out of the info.

Raises:

Type	Description
InvalidParameter	If repeat is not 1 or 3 positive integers, or is above 1 along a non-periodic direction.

wrap

wrap(system)

The atoms moved into the box along the periodic directions.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required

Returns:

Type	Description
System	The same system with fractional coordinates in [0, 1) along periodic directions. An image column is updated so that the unwrapped positions do not change.

unwrap

unwrap(system)

The atoms at their unwrapped positions.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with an image column.	required

Returns:

Type	Description
System	The same system with positions plus image flags times the lattice vectors, and the image flags set to zero.

Raises:

Type	Description
MissingProperty	If the system has no image column.

affine

affine(system, matrix, translation=(0.0, 0.0, 0.0), *, box=True, vectors=VECTORS, atoms=None)

The system with its atoms, and its box, mapped by an affine transformation.

Parameters:

Name	Type	Description	Default
system	System	The system to transform.	required
matrix	array_like	(3, 3) float64 linear part M of the transformation, acting on Cartesian column vectors: a position x goes to M x + t.	required
translation	array_like	(3,) float64 translation t in Å. Default none.	(0.0, 0.0, 0.0)
box	bool	Whether the box transforms too: its vectors by M, its origin by M and t. Default True.	True
vectors	sequence of str	The columns of vectors, of three components, that turn with M without the translation, where the system has them. Default velocities, forces and displacement.	VECTORS
atoms	array_like	A boolean mask or indices of the atoms that move, with their vectors; the others stay as they are. Default all of them.	None

Returns:

Type	Description
System	The system with the positions, the vectors and, with box, the box transformed; its other columns and its information as they are.

Raises:

Type	Description
InvalidParameter	If the matrix is not (3, 3) of finite numbers, or singular while the box transforms; if the translation is not 3 finite numbers; if atoms is not a mask or indices of the system; or if a column of vectors does not hold three numbers per atom.

combine

combine(system, other)

The atoms of other added after those of system, as OVITO's combine datasets.

Parameters:

Name	Type	Description	Default
system	System	The atoms and the box that are kept.	required
other	System	The atoms added, at their positions; its box is not used.	required

Returns:

Type

Description

System

The atoms of both in the box of system, with the columns of either: zeros where one has no column (the element X for element). Where system has an id column, the added atoms are numbered on from its largest id in their order; molecules of other above 0 are offset by the largest molecule of system. The topology terms of both, those of other moved to its atoms. The info of system, without energy and virial.

Raises:

Type	Description
InvalidParameter	If a column has types in the two that cannot be joined, such as text in one and numbers in the other.

slice

slice(system, normal, distance=0.0, *, width=0.0, invert=False, miller=False, through=None, atoms=None)

The atoms on one side of a plane, or in a slab about it.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
normal	array_like or str	(3,) the normal of the plane in Cartesian coordinates, of any length, or an axis "x", "y" or "z"; with miller, the Miller indices hkl of the plane in the vectors of the box.	required
distance	float64	The plane holds the points x with n . x = distance in Å, n the unit normal; with miller, it lies distance interplanar spacings d_hkl from the origin of the box. Default 0.	0.0
width	float64	Keep the atoms closer to the plane than width / 2 in Å instead. Default 0: keep those on the side the normal points away from.	0.0
invert	bool	Keep the other atoms. Default False.	False
miller	bool	The normal holds Miller indices. Default False.	False
through	array_like	(3,) float64, a point in Å the plane passes through, instead of distance.	None
atoms	array_like	A boolean mask or indices of the atoms the plane acts on; the others are kept. Default all.	None

Returns:

Type	Description
System	The atoms kept, in their order, in the same box.

Raises:

Type	Description
InvalidParameter	As slice_mask.

slice_mask

slice_mask(system, normal, distance=0.0, *, width=0.0, invert=False, miller=False, through=None, atoms=None)

Which atoms slice keeps.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
normal	array_like or str	(3,) the normal of the plane in Cartesian coordinates, of any length, or an axis "x", "y" or "z"; with miller, the Miller indices hkl of the plane in the vectors of the box.	required
distance	float64	The plane holds the points x with n . x = distance in Å, n the unit normal; with miller, it lies distance interplanar spacings d_hkl from the origin of the box. Default 0.	0.0
width	float64	Keep the atoms closer to the plane than width / 2 in Å instead. Default 0: keep those on the side the normal points away from.	0.0
invert	bool	Keep the other atoms. Default False.	False
miller	bool	The normal holds Miller indices. Default False.	False
through	array_like	(3,) float64, a point in Å the plane passes through, instead of distance.	None
atoms	array_like	A boolean mask or indices of the atoms the plane acts on; the others are kept. Default all.	None

Returns:

Type	Description
ndarray	(N,) bool whether each atom is kept.

Raises:

Type	Description
InvalidParameter	For a normal that is zero or not three numbers or an axis, Miller indices given as an axis, a negative width, a point not of three numbers, both a distance and a point, and atoms that are not a mask or indices of the system.

create_bonds

create_bonds(system, cutoff)

Bonds between the atoms closer than a cutoff, as OVITO's create bonds.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
cutoff	float64 or covalent	Bonds between atoms closer than this in Å, also across periodic boundaries; or "covalent", between atoms closer than 1.2 times the sum of their covalent radii, as mdapy.visualization.covalent_bonds finds them (needs an element column).	required

Returns:

Type	Description
System	The system with these bonds in its topology, each pair once, the first atom before the second; bonds it had are replaced, its angles, dihedrals and impropers kept.

Raises:

Type	Description
InvalidParameter	For a cutoff that is neither positive nor "covalent".