Python API

Data structures

Type	Structure	Description
cryst	(lattice, species, positions)	A crystal structure described by a primitive cell lattice, atomic species species, and fractional coordinates positions. Cell vectors are rows of lattice.
slm	(hA, hB, q)	A sublattice match (SLM) described by an integer-matrix triplet.

Functions

crystmatch.enumeration

Enumerate SLMs and CSMs.

cong_slm(slm, gA, gB)

The representative SLM of the congruence class of slm.

Parameters:

Name	Type	Description	Default
slm	slm	(hA, hB, q), representing a SLM.	required
gA	(..., 3, 3) array of ints	The rotation group of the initial crystal structure, whose elements are integer matrices under fractional coordinates.	required
gB	(..., 3, 3) array of ints	The rotation group of the final crystal structure, whose elements are integer matrices under fractional coordinates.	required

Returns:

Name	Type	Description
ss	slm	The representative of the congruence class of slm.
len_cl	int	The size of the congruence class of slm.

create_common_supercell(crystA, crystB, slm)

Create supercell structures representing \(\mathcal{A}\) (initial structure)and \(\sqrt{S^{\text{T}} S}S^{-1}\mathcal{B}\) (rotation-free final structure). Also return the half-distorted supercell and translation cell.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial and final structures.	required
crystB	cryst	The initial and final structures.	required
slm	slm	The SLM of the CSM.	required

Returns:

Name	Type	Description
crystA_sup	cryst	The supercell of \(\mathcal{A}\).
crystB_sup_final	cryst	The supercell of \(\sqrt{S^{\text{T}} S}\mathcal{A}\), which equals the supercell of \((S^{\text{T}} S)^{-1/2}\mathcal{B}\).
c_sup_half	(3, 3) array of floats	The half-distorted supercell, which equals the supercel of \((S^{\text{T}} S)^{1/4}\mathcal{A}\) and that of \((S^{\text{T}} S)^{-1/4}\mathcal{B}\).
f_translate	(3, 3) array of floats	The translation cell (fractional coordinates) of the shuffle whose lattice is generated byc_sup_half.

enumerate_slm(crystA, crystB, mu, kappa_max, tol=0.001, kappa=rmss, likelihood_ratio=100.0, verbose=1)

Enumerating all SLMs of multiplicity mu with kappa smaller than kappa_max.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial crystal structure, usually obtained by load_poscar.	required
crystB	cryst	The final crystal structure, usually obtained by load_poscar.	required
mu	int	The multiplicity of SLMs to enumerate.	required
kappa_max	float	A positive threshold value of kappa to determine the range of singular values to generate.	required
tol	float	The tolerance for determining the pure rotation group of the crystal structures. Default is 1e-3.	0.001
kappa	callable	A function that quantifies the strain of a matrix according to its singular values. Default is rmss, which computes the root-mean-square strain.	rmss
likelihood_ratio	float	The expected likelihood ratio of the enumeration being complete and incomplete. Default is 1e2.	100.0
verbose	int	The level of verbosity. Default is 1.	1

Returns:

Name	Type	Description
slmlist	list of slm	Contains triplets of integer matrices like (hA, hB, q), representing incongruent SLMs.

get_pure_rotation(cryst, tol=0.001)

Find all pure rotations appeared in the space group of cryst.

Parameters:

Name	Type	Description	Default
cryst	3 - tuple	(lattice, species, positions), representing the crystal structure, usually obtained by load_poscar.	required
tol	float	The tolerance for spglib symmetry detection; default is 1e-3.	0.001

Returns:

Name	Type	Description
g	(..., 3, 3) array of ints	A point group of the first kind, containing all pure rotations appeared in the space group of cryst, elements of which are integer matrices (under fractional coordinates).

hnf_int(m)

Decompose square integer matrix m into product of HNF matrix h and unimodular matrix q.

Parameters:

Name	Type	Description	Default
m	(N, N) array of ints	The integer matrix to decompose, with positive determinant.	required

Returns:

Name	Type	Description
h	(N, N) array of ints	The column-style Hermite normal form of m.
q	(N, N) array of ints	The unimodular matrix satisfying m = h @ q.

hnf_list(det)

Enumerate all 3*3 column Hermite normal forms (HNFs) with given determinant.

Parameters:

Name	Type	Description	Default
det	int	The determinant of HNFs.	required

Returns:

Name	Type	Description
l	(..., 3, 3) array of ints	Contains all HNFs with determinant det.

hnf_rational(m, max_divisor=10000)

The Hermite normal form (HNF) of full-row-rank rational matrix m (not necessarily square or integer).

Parameters:

Name	Type	Description	Default
m	(M, N) array_like, M <= N	The full-row-rank rational matrix to reduce.	required
max_divisor	int	A positive integer. The least common multiple of all divisors in m should not be greater than max_divisor.	10000

Returns:

Name	Type	Description
h	(M, N) array	The HNF of m obtained via elementary column operations over integers.

int_arrays_to_pair(crystA, crystB, slm, p, ks, centered=True)

Convert the integer arrays representation (slm, p, translations) of a CSM to a pair of crysts.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial and final structures.	required
crystB	cryst	The initial and final structures.	required
slm	slm	The SLM of the CSM.	required
p	(Z, ) array of ints	The permutaion of the shuffle.	required
ks	(3, Z) array of ints	The lattice-vector translations of the shuffle.	required
centered	bool	Whether to make the centers of crystA_sup and crystB_sup_final coincide. Default is True.	True

Returns:

Name	Type	Description
crystA_sup	cryst	The initial structure, whose lattice vectors and atoms are matched to crystB_sup according to the CSM.
crystB_sup_final	cryst	The final structure, whose lattice vectors and atoms are matched to crystA_sup according to the CSM, with rotation-free orientation.

int_fact(n)

Factorize positive integer n into products of two integers.

Parameters:

Name	Type	Description	Default
n	int	The integer to be factorized.	required

Returns:

Name	Type	Description
l	list of 2-tuples of ints	Contains all (a, b) such that a*b=n.

int_vec_inside(c)

Integer vectors inside the cell c whose elements are integers.

Parameters:

Name	Type	Description	Default
c	(3, 3) array of ints	A matrix whose columns are integer cell vectors.	required

Returns:

Name	Type	Description
v_int	(3, ...) array of ints	Its columns are vectors satisfying v = c @ k, where k[0], k[1], k[2] \(\in [0, 1)\).

load_poscar(filename, to_primitive=True, tol=0.001, verbose=True)

Load the crystal structure from a POSCAR file.

Parameters:

Name	Type	Description	Default
filename	str	The name of the POSCAR file to be read.	required
to_primitive	bool	Using the primitive cell instead of the cell given by the POSCAR file. Default is True.	True
tol	str	The tolerance for spglib symmetry detection; default is 1e-3.	0.001

Returns:

Name	Type	Description
cryst	cryst	The loaded crystal structure, consisting of the lattice vectors, species, and positions.

matrix_gcd(m1, m2, max_divisor=10000)

Return a greatest common divisor of rational matrices m1 and m2.

Parameters:

Name	Type	Description	Default
m1	(3, 3) array_like	Nonsingular rational matrices.	required
m2	(3, 3) array_like	Nonsingular rational matrices.	required
max_divisor	int	A positive integer. The least common multiple of all divisors in m should not be greater than max_divisor.	10000

Returns:

Name	Type	Description
d	(3, 3) array	The greatest common divisor of m1 and m2 in Hermite normal form.

matrix_lcm(m1, m2)

Return a least common multiple of integer matrices m1 and m2.

Parameters:

Name	Type	Description	Default
m1	(3, 3) array_like	Nonsingular integer matrices.	required
m2	(3, 3) array_like	Nonsingular integer matrices.	required

Returns:

Name	Type	Description
m	(3, 3) array	The least common multiple of m1 and m2 in Hermite normal form.

minimize_rmsd(crystA, crystB, slm, accurate=True)

Minimize the RMSD with fixed SLM, variable permutation, overall and lattice-vector translations.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial crystal structure, usually obtained by load_poscar.	required
crystB	cryst	The final crystal structure, usually obtained by load_poscar.	required
slm	slm	Triplets of integer matrices like (hA, hB, q), representing a SLM.	required
accurate	bool	Whether to use the accurate method to minimize the RMSD. If False, the result may be suboptimal. Default is True.	True

Returns:

Name	Type	Description
rmsd	float	The minimum atomic displacement (RMSD) between \((S^{\text{T}} S)^{1/4}\mathcal{A}\) and \((S^{\text{T}} S)^{-1/4}\mathcal{B}\).
p	(Z, ) array of ints	The permutation of the atoms in pB_sup that minimizes the RMSD.
ks	(3, Z) array of ints	The lattice-vector translations (fractional coordinates) of the atoms in pB_sup[:,p] that minimizes the RMSD.
t0	(3, ) array of floats	The overall translation on pB that minimizes the RMSD.

minimize_rmsd_t(c, species, pA, pB)

Minimize the RMSD with fixed SLM, overall translation, variable permutation and lattice-vector translations.

Parameters:

Name	Type	Description	Default
c	(3, 3) array	The matrix whose columns are cell vectors of both crystal structures.	required
species	(N,) array of strs	The array that specifies the type of each ion.	required
pA	(3, N) array	The matrices whose columns are fractional coordinates of atoms.	required
pB	(3, N) array	The matrices whose columns are fractional coordinates of atoms.	required

Returns:

Name	Type	Description
rmsd	float	The minimized RMSD.
p	(Z, ) array of ints	The permutation of the atoms in pB that minimizes the RMSD.
ks	(3, Z) array of ints	The lattice-vector translations of the atoms in pB[:,p] that minimizes the RMSD.

minimize_rmsd_tp(c, pA, pB)

Minimize the RMSD with fixed SLM, overall translation, permutation, and variable lattice-vector translations.

Parameters:

Name	Type	Description	Default
c	(3, 3) array	The matrix whose columns are cell vectors of both crystal structures.	required
pA	(3, N) array	The matrices whose columns are fractional coordinates of atoms.	required
pB	(3, N) array	The matrices whose columns are fractional coordinates of atoms.	required

Returns:

Name	Type	Description
rmsd	float	The minimized RMSD.
ks	(3, Z) array of ints	The lattice-vector translations (fractional coordinates) of the atoms in pB that minimizes the RMSD.

niggli_cell(c)

Reduce cell c to its Niggli cell.

Parameters:

Name	Type	Description	Default
c	(3, 3) array	The cell to be reduced, whose columns are cell vectors.	required

Returns:

Name	Type	Description
cc	(3, 3) array	The Niggli cell, with shortest right-handed cell vectors.
q	(3, 3) array of ints	The unimodular matrix satisfying cc = c @ q.

rmss(x)

Root-mean-square strain of given singular values.

Parameters:

Name	Type	Description	Default
x	(..., 3) array	The singular values of 3*3 matrices.	required

Returns:

Name	Type	Description
rms_strain	(...) array	Root-mean-square of x - 1.

save_poscar(filename, cryst, crystname=None)

Save the crystal structure to a POSCAR file.

Parameters:

Name	Type	Description	Default
filename	str	The name of the file to save, must not already exist in current directory. If filename = None, a string will be returned instead.	required
cryst	cryst	The crystal structure to be saved, consisting of the lattice vectors, species, and positions.	required
crystname	str	A system description to write to the comment line of the POSCAR file. If crystname = None, filename will be used.	None

species_poscar_format(species)

Examine whether a species array is sorted. If so, convert it to the POSCAR format.

Parameters:

Name	Type	Description	Default
species	(N,) array of str	The species array.	required

Returns:

Name	Type	Description
species_unique	(M,) array of str	The unique species in the order of their first appearance in species.
species_counts	(M,) array of int	The number of occurrences of each unique species in species.

unique_filename(message, filename)

Get a unique filename by appending a number to the end of the given filename.

Parameters:

Name	Type	Description	Default
filename	str	The filename to be modified.	required
message	str	A message to print before the filename.	required

Returns:

Name	Type	Description
new_filename	str	The modified filename with a unique number appended.

vector_reduce(v, divisors)

Minimizing the norm of v by adding and subtracting columns of divisors.

Parameters:

Name	Type	Description	Default
v	(N,) array	The vector to be reduced.	required
divisors	(N, ...) array	The vectors used to translate v.	required

Returns:

Name	Type	Description
vv	(N,) array	The reduced v with minimum Euclidean norm.

crystmatch.analysis

Analyze and visualize CSMs.

create_common_supercell(crystA, crystB, slm)

Create supercell structures representing \(\mathcal{A}\) (initial structure)and \(\sqrt{S^{\text{T}} S}S^{-1}\mathcal{B}\) (rotation-free final structure). Also return the half-distorted supercell and translation cell.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial and final structures.	required
crystB	cryst	The initial and final structures.	required
slm	slm	The SLM of the CSM.	required

Returns:

Name	Type	Description
crystA_sup	cryst	The supercell of \(\mathcal{A}\).
crystB_sup_final	cryst	The supercell of \(\sqrt{S^{\text{T}} S}\mathcal{A}\), which equals the supercell of \((S^{\text{T}} S)^{-1/2}\mathcal{B}\).
c_sup_half	(3, 3) array of floats	The half-distorted supercell, which equals the supercel of \((S^{\text{T}} S)^{1/4}\mathcal{A}\) and that of \((S^{\text{T}} S)^{-1/4}\mathcal{B}\).
f_translate	(3, 3) array of floats	The translation cell (fractional coordinates) of the shuffle whose lattice is generated byc_sup_half.

deform_distance(slmlist, s0, crystA, crystB)

The Frobenius distance between deformation gradients.

Parameters:

Name	Type	Description	Default
slmlist	list of slm	A list of SLMs, each represented by a triplet of integer matrices like (hA, hB, q).	required
s0	slm	(hA, hB, q), representing a SLM.	required
crystA	cryst	(lattice, species, positions), representing the crystal structure, usually obtained by load_poscar.	required
crystB	cryst	(lattice, species, positions), representing the crystal structure, usually obtained by load_poscar.	required

Returns:

Name	Type	Description
dlist	(...,) array	Contains Frobenius distances from slmlist to s0, where equivalent SLMs coincide.

deviation_angle(crystA, crystB, slmlist, r, uspfix=False)

Calculate how much each SLM in slmlist differ from a given orientation relationship.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial crystal structure, usually obtained by load_poscar.	required
crystB	cryst	The final crystal structure, usually obtained by load_poscar.	required
slmlist	list of slm	A list of SLMs, each represented by a triplet of integer matrices like (hA, hB, q).	required
r	(3, 3) array	A rotation matrix representing the given orientation relationship.	required
uspfix	bool	Whether to fix the uniformed scaled plane. Default is False.	False

Returns:

Name	Type	Description
anglelist	(...,) array	Contains rotation angles that measure the difference of each SLM and the given orientation.

get_pure_rotation(cryst, tol=0.001)

Find all pure rotations appeared in the space group of cryst.

Parameters:

Name	Type	Description	Default
cryst	3 - tuple	(lattice, species, positions), representing the crystal structure, usually obtained by load_poscar.	required
tol	float	The tolerance for spglib symmetry detection; default is 1e-3.	0.001

Returns:

Name	Type	Description
g	(..., 3, 3) array of ints	A point group of the first kind, containing all pure rotations appeared in the space group of cryst, elements of which are integer matrices (under fractional coordinates).

hnf_int(m)

Decompose square integer matrix m into product of HNF matrix h and unimodular matrix q.

Parameters:

Name	Type	Description	Default
m	(N, N) array of ints	The integer matrix to decompose, with positive determinant.	required

Returns:

Name	Type	Description
h	(N, N) array of ints	The column-style Hermite normal form of m.
q	(N, N) array of ints	The unimodular matrix satisfying m = h @ q.

hnf_list(det)

Enumerate all 3*3 column Hermite normal forms (HNFs) with given determinant.

Parameters:

Name	Type	Description	Default
det	int	The determinant of HNFs.	required

Returns:

Name	Type	Description
l	(..., 3, 3) array of ints	Contains all HNFs with determinant det.

hnf_rational(m, max_divisor=10000)

The Hermite normal form (HNF) of full-row-rank rational matrix m (not necessarily square or integer).

Parameters:

Name	Type	Description	Default
m	(M, N) array_like, M <= N	The full-row-rank rational matrix to reduce.	required
max_divisor	int	A positive integer. The least common multiple of all divisors in m should not be greater than max_divisor.	10000

Returns:

Name	Type	Description
h	(M, N) array	The HNF of m obtained via elementary column operations over integers.

int_arrays_to_pair(crystA, crystB, slm, p, ks, centered=True)

Convert the integer arrays representation (slm, p, translations) of a CSM to a pair of crysts.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial and final structures.	required
crystB	cryst	The initial and final structures.	required
slm	slm	The SLM of the CSM.	required
p	(Z, ) array of ints	The permutaion of the shuffle.	required
ks	(3, Z) array of ints	The lattice-vector translations of the shuffle.	required
centered	bool	Whether to make the centers of crystA_sup and crystB_sup_final coincide. Default is True.	True

Returns:

Name	Type	Description
crystA_sup	cryst	The initial structure, whose lattice vectors and atoms are matched to crystB_sup according to the CSM.
crystB_sup_final	cryst	The final structure, whose lattice vectors and atoms are matched to crystA_sup according to the CSM, with rotation-free orientation.

int_fact(n)

Factorize positive integer n into products of two integers.

Parameters:

Name	Type	Description	Default
n	int	The integer to be factorized.	required

Returns:

Name	Type	Description
l	list of 2-tuples of ints	Contains all (a, b) such that a*b=n.

int_vec_inside(c)

Integer vectors inside the cell c whose elements are integers.

Parameters:

Name	Type	Description	Default
c	(3, 3) array of ints	A matrix whose columns are integer cell vectors.	required

Returns:

Name	Type	Description
v_int	(3, ...) array of ints	Its columns are vectors satisfying v = c @ k, where k[0], k[1], k[2] \(\in [0, 1)\).

load_poscar(filename, to_primitive=True, tol=0.001, verbose=True)

Load the crystal structure from a POSCAR file.

Parameters:

Name	Type	Description	Default
filename	str	The name of the POSCAR file to be read.	required
to_primitive	bool	Using the primitive cell instead of the cell given by the POSCAR file. Default is True.	True
tol	str	The tolerance for spglib symmetry detection; default is 1e-3.	0.001

Returns:

Name	Type	Description
cryst	cryst	The loaded crystal structure, consisting of the lattice vectors, species, and positions.

matrix_gcd(m1, m2, max_divisor=10000)

Return a greatest common divisor of rational matrices m1 and m2.

Parameters:

Name	Type	Description	Default
m1	(3, 3) array_like	Nonsingular rational matrices.	required
m2	(3, 3) array_like	Nonsingular rational matrices.	required
max_divisor	int	A positive integer. The least common multiple of all divisors in m should not be greater than max_divisor.	10000

Returns:

Name	Type	Description
d	(3, 3) array	The greatest common divisor of m1 and m2 in Hermite normal form.

matrix_lcm(m1, m2)

Return a least common multiple of integer matrices m1 and m2.

Parameters:

Name	Type	Description	Default
m1	(3, 3) array_like	Nonsingular integer matrices.	required
m2	(3, 3) array_like	Nonsingular integer matrices.	required

Returns:

Name	Type	Description
m	(3, 3) array	The least common multiple of m1 and m2 in Hermite normal form.

multiplicity(crystA, crystB, slmlist)

Return multiplicities of elements in slmlist.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial crystal structure, usually obtained by load_poscar.	required
crystB	cryst	The final crystal structure, usually obtained by load_poscar.	required
slmlist	list of slm	A list of SLMs, each represented by a triplet of integer matrices like (hA, hB, q).	required

Returns:

Name	Type	Description
mu	int or (...,) array of ints	Multiplicities of each SLM in slmlist.

niggli_cell(c)

Reduce cell c to its Niggli cell.

Parameters:

Name	Type	Description	Default
c	(3, 3) array	The cell to be reduced, whose columns are cell vectors.	required

Returns:

Name	Type	Description
cc	(3, 3) array	The Niggli cell, with shortest right-handed cell vectors.
q	(3, 3) array of ints	The unimodular matrix satisfying cc = c @ q.

orient_matrix(vi, vf, wi, wf)

Rotation matrix r such that r @ vi || vf and r @ wi || wf.

Parameters:

Name	Type	Description	Default
vi	(3,) array_like	Vectors (cartesian coordinates) that satisfy r @ vi || vf.	required
vf	(3,) array_like	Vectors (cartesian coordinates) that satisfy r @ vi || vf.	required
wi	(3,) array_like	Vectors (cartesian coordinates) that satisfy r @ wi || wf.	required
wf	(3,) array_like	Vectors (cartesian coordinates) that satisfy r @ wi || wf.	required

Returns:

Name	Type	Description
r	(3, 3) array	A rotation matrix representing the given orientation relationship.

rmss(x)

Root-mean-square strain of given singular values.

Parameters:

Name	Type	Description	Default
x	(..., 3) array	The singular values of 3*3 matrices.	required

Returns:

Name	Type	Description
rms_strain	(...) array	Root-mean-square of x - 1.

save_poscar(filename, cryst, crystname=None)

Save the crystal structure to a POSCAR file.

Parameters:

Name	Type	Description	Default
filename	str	The name of the file to save, must not already exist in current directory. If filename = None, a string will be returned instead.	required
cryst	cryst	The crystal structure to be saved, consisting of the lattice vectors, species, and positions.	required
crystname	str	A system description to write to the comment line of the POSCAR file. If crystname = None, filename will be used.	None

save_scatter(filename, rmsslist, rmsdlist, colorlist, cmap=plt.cm.get_cmap('viridis'), cbarlabel=None)

Scatter plot of the CSMs with colorbar.

Parameters:

Name	Type	Description	Default
filename	str	The filename of the saved plot.	required
rmsslist	(N,) array_like	The root-mean-square strain of each CSM.	required
rmsdlist	(N,) array_like	The root-mean-square distance of each CSM.	required
colorlist	(N,) array_like	Some quantity of each CSM, which is to be colored.	required
cmap	`matplotlib.colors.Colormap`	The colormap to use. Default is plt.cm.get_cmap('viridis').	get_cmap('viridis')
cbarlabel	str	The label of the colorbar. Default is None, in which case the filename is used.	None

sing_val(crystA, crystB, slmlist)

Return singular values of elements in slmlist.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial crystal structure, usually obtained by load_poscar.	required
crystB	cryst	The final crystal structure, usually obtained by load_poscar.	required
slmlist	list of slm	A list of SLMs, each represented by a triplet of integer matrices like (hA, hB, q).	required

Returns:

Name	Type	Description
sv	(..., 3) array	Contains singular values of each SLM in slmlist.

species_poscar_format(species)

Examine whether a species array is sorted. If so, convert it to the POSCAR format.

Parameters:

Name	Type	Description	Default
species	(N,) array of str	The species array.	required

Returns:

Name	Type	Description
species_unique	(M,) array of str	The unique species in the order of their first appearance in species.
species_counts	(M,) array of int	The number of occurrences of each unique species in species.

unique_filename(message, filename)

Get a unique filename by appending a number to the end of the given filename.

Parameters:

Name	Type	Description	Default
filename	str	The filename to be modified.	required
message	str	A message to print before the filename.	required

Returns:

Name	Type	Description
new_filename	str	The modified filename with a unique number appended.

vector_reduce(v, divisors)

Minimizing the norm of v by adding and subtracting columns of divisors.

Parameters:

Name	Type	Description	Default
v	(N,) array	The vector to be reduced.	required
divisors	(N, ...) array	The vectors used to translate v.	required

Returns:

Name	Type	Description
vv	(N,) array	The reduced v with minimum Euclidean norm.

crystmatch.utilities

Load/save crystal structures and CSMs from/to files.

create_common_supercell(crystA, crystB, slm)

Create supercell structures representing \(\mathcal{A}\) (initial structure)and \(\sqrt{S^{\text{T}} S}S^{-1}\mathcal{B}\) (rotation-free final structure). Also return the half-distorted supercell and translation cell.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial and final structures.	required
crystB	cryst	The initial and final structures.	required
slm	slm	The SLM of the CSM.	required

Returns:

Name	Type	Description
crystA_sup	cryst	The supercell of \(\mathcal{A}\).
crystB_sup_final	cryst	The supercell of \(\sqrt{S^{\text{T}} S}\mathcal{A}\), which equals the supercell of \((S^{\text{T}} S)^{-1/2}\mathcal{B}\).
c_sup_half	(3, 3) array of floats	The half-distorted supercell, which equals the supercel of \((S^{\text{T}} S)^{1/4}\mathcal{A}\) and that of \((S^{\text{T}} S)^{-1/4}\mathcal{B}\).
f_translate	(3, 3) array of floats	The translation cell (fractional coordinates) of the shuffle whose lattice is generated byc_sup_half.

get_pure_rotation(cryst, tol=0.001)

Find all pure rotations appeared in the space group of cryst.

Parameters:

Name	Type	Description	Default
cryst	3 - tuple	(lattice, species, positions), representing the crystal structure, usually obtained by load_poscar.	required
tol	float	The tolerance for spglib symmetry detection; default is 1e-3.	0.001

Returns:

Name	Type	Description
g	(..., 3, 3) array of ints	A point group of the first kind, containing all pure rotations appeared in the space group of cryst, elements of which are integer matrices (under fractional coordinates).

hnf_int(m)

Decompose square integer matrix m into product of HNF matrix h and unimodular matrix q.

Parameters:

Name	Type	Description	Default
m	(N, N) array of ints	The integer matrix to decompose, with positive determinant.	required

Returns:

Name	Type	Description
h	(N, N) array of ints	The column-style Hermite normal form of m.
q	(N, N) array of ints	The unimodular matrix satisfying m = h @ q.

hnf_list(det)

Enumerate all 3*3 column Hermite normal forms (HNFs) with given determinant.

Parameters:

Name	Type	Description	Default
det	int	The determinant of HNFs.	required

Returns:

Name	Type	Description
l	(..., 3, 3) array of ints	Contains all HNFs with determinant det.

hnf_rational(m, max_divisor=10000)

The Hermite normal form (HNF) of full-row-rank rational matrix m (not necessarily square or integer).

Parameters:

Name	Type	Description	Default
m	(M, N) array_like, M <= N	The full-row-rank rational matrix to reduce.	required
max_divisor	int	A positive integer. The least common multiple of all divisors in m should not be greater than max_divisor.	10000

Returns:

Name	Type	Description
h	(M, N) array	The HNF of m obtained via elementary column operations over integers.

int_arrays_to_pair(crystA, crystB, slm, p, ks, centered=True)

Convert the integer arrays representation (slm, p, translations) of a CSM to a pair of crysts.

Parameters:

Name	Type	Description	Default
crystA	cryst	The initial and final structures.	required
crystB	cryst	The initial and final structures.	required
slm	slm	The SLM of the CSM.	required
p	(Z, ) array of ints	The permutaion of the shuffle.	required
ks	(3, Z) array of ints	The lattice-vector translations of the shuffle.	required
centered	bool	Whether to make the centers of crystA_sup and crystB_sup_final coincide. Default is True.	True

Returns:

Name	Type	Description
crystA_sup	cryst	The initial structure, whose lattice vectors and atoms are matched to crystB_sup according to the CSM.
crystB_sup_final	cryst	The final structure, whose lattice vectors and atoms are matched to crystA_sup according to the CSM, with rotation-free orientation.

int_fact(n)

Factorize positive integer n into products of two integers.

Parameters:

Name	Type	Description	Default
n	int	The integer to be factorized.	required

Returns:

Name	Type	Description
l	list of 2-tuples of ints	Contains all (a, b) such that a*b=n.

int_vec_inside(c)

Integer vectors inside the cell c whose elements are integers.

Parameters:

Name	Type	Description	Default
c	(3, 3) array of ints	A matrix whose columns are integer cell vectors.	required

Returns:

Name	Type	Description
v_int	(3, ...) array of ints	Its columns are vectors satisfying v = c @ k, where k[0], k[1], k[2] \(\in [0, 1)\).

load_poscar(filename, to_primitive=True, tol=0.001, verbose=True)

Load the crystal structure from a POSCAR file.

Parameters:

Name	Type	Description	Default
filename	str	The name of the POSCAR file to be read.	required
to_primitive	bool	Using the primitive cell instead of the cell given by the POSCAR file. Default is True.	True
tol	str	The tolerance for spglib symmetry detection; default is 1e-3.	0.001

Returns:

Name	Type	Description
cryst	cryst	The loaded crystal structure, consisting of the lattice vectors, species, and positions.

matrix_gcd(m1, m2, max_divisor=10000)

Return a greatest common divisor of rational matrices m1 and m2.

Parameters:

Name	Type	Description	Default
m1	(3, 3) array_like	Nonsingular rational matrices.	required
m2	(3, 3) array_like	Nonsingular rational matrices.	required
max_divisor	int	A positive integer. The least common multiple of all divisors in m should not be greater than max_divisor.	10000

Returns:

Name	Type	Description
d	(3, 3) array	The greatest common divisor of m1 and m2 in Hermite normal form.

matrix_lcm(m1, m2)

Return a least common multiple of integer matrices m1 and m2.

Parameters:

Name	Type	Description	Default
m1	(3, 3) array_like	Nonsingular integer matrices.	required
m2	(3, 3) array_like	Nonsingular integer matrices.	required

Returns:

Name	Type	Description
m	(3, 3) array	The least common multiple of m1 and m2 in Hermite normal form.

niggli_cell(c)

Reduce cell c to its Niggli cell.

Parameters:

Name	Type	Description	Default
c	(3, 3) array	The cell to be reduced, whose columns are cell vectors.	required

Returns:

Name	Type	Description
cc	(3, 3) array	The Niggli cell, with shortest right-handed cell vectors.
q	(3, 3) array of ints	The unimodular matrix satisfying cc = c @ q.

rmss(x)

Root-mean-square strain of given singular values.

Parameters:

Name	Type	Description	Default
x	(..., 3) array	The singular values of 3*3 matrices.	required

Returns:

Name	Type	Description
rms_strain	(...) array	Root-mean-square of x - 1.

save_poscar(filename, cryst, crystname=None)

Save the crystal structure to a POSCAR file.

Parameters:

Name	Type	Description	Default
filename	str	The name of the file to save, must not already exist in current directory. If filename = None, a string will be returned instead.	required
cryst	cryst	The crystal structure to be saved, consisting of the lattice vectors, species, and positions.	required
crystname	str	A system description to write to the comment line of the POSCAR file. If crystname = None, filename will be used.	None

species_poscar_format(species)

Examine whether a species array is sorted. If so, convert it to the POSCAR format.

Parameters:

Name	Type	Description	Default
species	(N,) array of str	The species array.	required

Returns:

Name	Type	Description
species_unique	(M,) array of str	The unique species in the order of their first appearance in species.
species_counts	(M,) array of int	The number of occurrences of each unique species in species.

unique_filename(message, filename)

Get a unique filename by appending a number to the end of the given filename.

Parameters:

Name	Type	Description	Default
filename	str	The filename to be modified.	required
message	str	A message to print before the filename.	required

Returns:

Name	Type	Description
new_filename	str	The modified filename with a unique number appended.

vector_reduce(v, divisors)

Minimizing the norm of v by adding and subtracting columns of divisors.

Parameters:

Name	Type	Description	Default
v	(N,) array	The vector to be reduced.	required
divisors	(N, ...) array	The vectors used to translate v.	required

Returns:

Name	Type	Description
vv	(N,) array	The reduced v with minimum Euclidean norm.