pdyna.structural module

pdyna.structural: The collection of structural processing functions.

pdyna.structural.apply_pbc_cart_vecs(vecs, mymat)

Apply PBC to a set of vectors wrt. lattice matrix. (vectorised version)

Parameters:

• vecs (numpy.ndarray) – The vectors.

• mymat (numpy.ndarray) – The lattice matrix.

Returns:

The corresponding vectors with PBC applied.

Return type:

numpy.ndarray

pdyna.structural.apply_pbc_cart_vecs_single_frame(vecs, mymat)

Apply PBC to a set of vectors wrt. lattice matrix.

Parameters:

• vecs (numpy.ndarray) – The vectors.

• mymat (numpy.ndarray) – The lattice matrix.

Returns:

The corresponding vectors with PBC applied.

Return type:

numpy.ndarray

pdyna.structural.calc_displacement(pymatgen_molecule, pymatgen_molecule_ideal, irrep_distortions)

Compute the displacement of the atoms in the molecule for matching.

Parameters:

• pymatgen_molecule (pymatgen.Molecule) – The molecule to be transformed.

• pymatgen_molecule_ideal (pymatgen.Molecule) – The reference molecule.

• irrep_distortions (numpy.ndarray) – The basis irreps for matching.

Returns:

The processed displacement of the atoms.

Return type:

numpy.ndarray

pdyna.structural.calc_displacement_full(pymatgen_molecule, pymatgen_molecule_ideal, irrep_distortions)

Compute the displacement of the atoms in the molecule for matching.

Parameters:

• pymatgen_molecule (pymatgen.Molecule) – The molecule to be transformed.

• pymatgen_molecule_ideal (pymatgen.Molecule) – The reference molecule.

• irrep_distortions (numpy.ndarray) – The basis irreps for matching.

Returns:

The processed displacement of the atoms.

Return type:

numpy.ndarray

pdyna.structural.calc_distortion_from_order_manual(bx, ideal_coords, dict_basis)

Compute the rotation of six bond vectors with arbitrary order, used in non-ortho structure.

Parameters:

• bx (numpy.ndarray) – The six B-X bond vectors.

• ideal_coords (numpy.ndarray) – The ideal coordinates.

• dict_basis (dict) – The basis dictionary imported.

Returns:

The distortion amplitudes. numpy.ndarray: The rotation matrix. float: The RMSD of the fitting.

Return type:

numpy.ndarray

pdyna.structural.calc_distortions_from_bond_vectors(bx)

Compute the tilting and distortion from the six B-X bond vectors.

Parameters:

bx (numpy.ndarray) – The six B-X bond vectors.

Returns:

The octahedral distortion. numpy.ndarray: Rotation matrix of the octahedron with respect to the reference. float: The RMSD of the fitting.

Return type:

numpy.ndarray

pdyna.structural.calc_distortions_from_bond_vectors_full(bx)

Compute the tilting and distortion from the six B-X bond vectors.

Parameters:

bx (numpy.ndarray) – The six B-X bond vectors.

Returns:

The octahedral distortion. numpy.ndarray: Rotation matrix of the octahedron with respect to the reference. float: The RMSD of the fitting.

Return type:

numpy.ndarray

pdyna.structural.calc_rotation_from_arbitrary_order(bx)

Compute the rotation of six bond vectors with arbitrary order, used in non-ortho structure.

Parameters:

bx (numpy.ndarray) – The six B-X bond vectors.

Returns:

The rotation angles. numpy.ndarray: The rotation matrix.

Return type:

numpy.ndarray

pdyna.structural.centmass_organic(st0pos, latmat, env)

Find the center of mass of organic A-site.

Parameters:

• st0pos (numpy.ndarray) – The atomic positions.

• latmat (numpy.ndarray) – The lattice matrix.

• env (list) – The environment of the A-site.

Returns:

The center of mass positions.

Return type:

numpy.ndarray

pdyna.structural.centmass_organic_vec(pos, latmat, env)

Find the center of mass of organic A-site. (vectorised version)

Parameters:

• pos (numpy.ndarray) – The atomic positions.

• latmat (numpy.ndarray) – The lattice matrix.

• env (list) – The environment of the A-site.

Returns:

The center of mass positions.

Return type:

numpy.ndarray

pdyna.structural.convert_xb_to_bx(xb)

Convert the X-to-B connectivity matrix to the ordinary B-to-X connectivity matrix.

Parameters:

xb (numpy.ndarray) – The X-to-B connectivity matrix of octahedra.

Returns:

The B-X connectivity matrix with shape (N, 6).

Return type:

numpy.ndarray

pdyna.structural.distance_matrix(v1, v2, latmat, get_vec=False)

Compute the distance matrix between two sets of vectors, using the apparent matrix multiplication method. Should only be used for the case with alpha, beta, gamma angles all close to 90 degrees.

Parameters:

• v1 (numpy.ndarray) – The first set of coordinate vectors.

• v2 (numpy.ndarray) – The second set of coordinate vectors.

• latmat (numpy.ndarray) – The lattice matrix.

• get_vec (bool) – Whether to return the distance vectors.

Returns:

The distance matrix.

Return type:

numpy.ndarray

pdyna.structural.distance_matrix_ase(v1, v2, asecell, pbc, get_vec=False)

Compute the distance matrix between two sets of vectors, using the algorithm implemented in ASE.

Parameters:

• v1 (numpy.ndarray) – The first set of coordinate vectors.

• v2 (numpy.ndarray) – The second set of coordinate vectors.

• asecell (ase.Atoms) – The Atoms object of the system.

• pbc (list of bool) – Periodic boudary condition in three directions as defined in ASE.

• get_vec (bool) – Whether to return the distance vectors.

Returns:

The distance matrix.

Return type:

numpy.ndarray

pdyna.structural.distance_matrix_ase_replace(v1, v2, asecell, newcell, pbc, get_vec=False)

Compute the distance matrix between two sets of vectors, using the algorithm implemented in ASE, with a new cell. Uses not the cell object in the Atoms object, but a new cell matrix.

Parameters:

• v1 (numpy.ndarray) – The first set of coordinate vectors.

• v2 (numpy.ndarray) – The second set of coordinate vectors.

• asecell (ase.Atoms) – The Atoms object of the system.

• newcell (numpy.ndarray) – The new cell matrix.

• pbc (list of bool) – Periodic boudary condition in three directions as defined in ASE.

• get_vec (bool) – Whether to return the distance vectors.

Returns:

The distance matrix.

Return type:

numpy.ndarray

pdyna.structural.distance_matrix_handler(v1, v2, latmat, asecell=None, pbc=None, complex_pbc=False, replace=True, get_vec=False)

Compute the distance matrix between two sets of vectors, with different methods depending on requirement.

Parameters:

• v1 (numpy.ndarray) – The first set of coordinate vectors.

• v2 (numpy.ndarray) – The second set of coordinate vectors.

• latmat (numpy.ndarray) – The lattice matrix.

• asecell (ase.Atoms) – The Atoms object of the system.

• pbc (list of bool) – Periodic boudary condition in three directions as defined in ASE.

• complex_pbc (bool) – Whether to use the ASE algorithm.

• replace (bool) – Whether to use a new cell matrix.

• get_vec (bool) – Whether to return the distance vectors.

Returns:

The distance matrix.

Return type:

numpy.ndarray

pdyna.structural.find_B_cage_and_disp(pos, mymat, cent, Bs)

Find the displacement of A-site with respect to the capsulating B-X cage.

Parameters:

• pos (numpy.ndarray) – The atomic positions.

• mymat (numpy.ndarray) – The lattice matrix.

• cent (numpy.ndarray) – The center of mass of A-site.

• Bs (list) – The indices of the B-site atoms.

Returns:

The relative displacement of A-site to its surrounding.

Return type:

numpy.ndarray

pdyna.structural.find_polytype_network(Bpos_frame, Xpos_frame, r, mymat, neigh_list)

Resolve the octahedral connectivity and output the polytype information.

Parameters:

• Bpos_frame (numpy.ndarray) – Coordinate array of B-sites.

• Xpos_frame (numpy.ndarray) – Coordinate array of X-sites.

• r (numpy.ndarray) – Distance matrix of B-X sites.

• mymat (numpy.ndarray) – Lattice matrix of the frame.

• neigh_list (numpy.ndarray) – The B-X connectivity matrix of octahedra with shape (N, 6).

Returns:

List of strings indicating the local polytype connecivity of each octahedron. list: List of arrays indicating the shared X-sites with neighbouring B-sites. dict: Dictionary of octahedra categories.

Return type:

list

pdyna.structural.find_population_gap(r, find_range, init, tol=0)

Find the 1D classifier value to separate two populations.

Parameters:

• r (numpy.ndarray) – The input distance matrix array.

• find_range (list) – The distance range to find the classifier.

• init (numpy.ndarray) – The initial guess of the classifier.

• tol (float) – The tolerance of the classifier.

Returns:

The classifier value.

Return type:

float

pdyna.structural.fit_octahedral_network_defect_tol(Bpos_frame, Xpos_frame, r, mymat, fpg_val_BX, structure_type)

Resolve the octahedral connectivity with a defect tolerance.

Parameters:

• Bpos_frame (numpy.ndarray) – Coordinate array of B-sites.

• Xpos_frame (numpy.ndarray) – Coordinate array of X-sites.

• r (numpy.ndarray) – Distance matrix of B-X sites.

• mymat (numpy.ndarray) – Lattice matrix of the frame.

• fpg_val_BX (list) – Defined B-X bond information at the beginning of the class.

• structure_type (int) – Structure type indicating orientation and connectivity of octahedra.

Returns:

The B-X connectivity matrix of octahedra with shape (N, 6).

Return type:

numpy.ndarray

pdyna.structural.fit_octahedral_network_defect_tol_non_orthogonal(Bpos_frame, Xpos_frame, r, mymat, fpg_val_BX, structure_type, rotmat)

Resolve the octahedral connectivity with a defect tolerance.

Parameters:

• Bpos_frame (numpy.ndarray) – Coordinate array of B-sites.

• Xpos_frame (numpy.ndarray) – Coordinate array of X-sites.

• r (numpy.ndarray) – Distance matrix of B-X sites.

• mymat (numpy.ndarray) – Lattice matrix of the frame.

• fpg_val_BX (list) – Defined B-X bond information at the beginning of the class.

• structure_type (int) – Structure type indicating orientation and connectivity of octahedra.

• rotmat (numpy.ndarray) – Rotation matrix of the structure to align with orthogonal directions.

Returns:

The B-X connectivity matrix of octahedra with shape (N, 6).

Return type:

numpy.ndarray

pdyna.structural.fit_octahedral_network_frame(Bpos_frame, Xpos_frame, r, mymat, fpg_val_BX, rotated, rotmat)

Resolve the octahedral connectivity.

Parameters:

• Bpos_frame (numpy.ndarray) – Coordinate array of B-sites.

• Xpos_frame (numpy.ndarray) – Coordinate array of X-sites.

• r (numpy.ndarray) – Distance matrix of B-X sites.

• mymat (numpy.ndarray) – Lattice matrix of the frame.

• fpg_val_BX (list) – Defined B-X bond information at the beginning of the class.

• rotated (bool) – If the structure is rotated.

• rotmat (numpy.ndarray) – Rotation matrix of the structure to align with orthogonal directions.

Returns:

The B-X connectivity matrix of octahedra with shape (N, 6).

Return type:

numpy.ndarray

pdyna.structural.get_cart_from_frac(frac, latmat)

Get cartesian coordinates from fractional coordinates.

Parameters:

• frac (numpy.ndarray) – The fractional coordinates.

• latmat (numpy.ndarray) – The lattice matrix.

Returns:

The corresponding cartesian coordinates.

Return type:

numpy.ndarray

pdyna.structural.get_frac_from_cart(cart, latmat)

Get fractional coordinates from cartesian coordinates.

Parameters:

• cart (numpy.ndarray) – The cartesian coordinates.

• latmat (numpy.ndarray) – The lattice matrix.

Returns:

The corresponding fractional coordinates.

Return type:

numpy.ndarray

pdyna.structural.get_volume(lattice)

Calculate the volume of the lattice.

Parameters:

lattice (numpy.ndarray) – The lattice matrix.

Returns:

The volume of the lattice.

Return type:

float

pdyna.structural.match_bx_arbitrary(bx)

Find the order of atoms in octahedron through matching with the reference. Used in structure_type 3.

Parameters:

bx (numpy.ndarray) – The six B-X bond vectors.

Returns:

The order of atoms matching to the reference. numpy.ndarray: rotation matrices for alignment. float: The RMSD of the fitting.

Return type:

list

pdyna.structural.match_bx_orthogonal(bx)

Find the order of atoms in octahedron through matching with the reference. Used in structure_type 1.

Parameters:

bx (numpy.ndarray) – The six B-X bond vectors.

Returns:

The order of atoms matching to the reference.

Return type:

list

pdyna.structural.match_bx_orthogonal_rotated(bx, rotmat)

Find the order of atoms in octahedron through matching with the reference. Used in structure_type 2.

Parameters:

• bx (numpy.ndarray) – The six B-X bond vectors.

• rotmat (numpy.ndarray) – The rotation matrix for alignment.

Returns:

The order of atoms matching to the reference.

Return type:

list

pdyna.structural.match_mixed_halide_octa_dot(bx, hals)

Find the configuration class in binary-mixed halide octahedron.

Parameters:

• bx (numpy.ndarray) – The six B-X bond vectors.

• hals (list) – The list of symbols of halide species.

Returns:

The configuration class and the configuration

Return type:

tuple

pdyna.structural.match_molecules_extra(molecule_transform, molecule_reference)

Hungarian matching to output the transformation matrix

Parameters:

• molecule_transform (pymatgen.Molecule) – The molecule to be transformed.

• molecule_reference (pymatgen.Molecule) – The reference molecule.

Returns:

The transformed molecule. numpy.ndarray: The rotation matrix. float: The RMSD of the fitting.

Return type:

pymatgen.Molecule

pdyna.structural.octahedra_coords_into_bond_vectors(raw, mymat)

Convert the coordinates of an octahedron to six B-X bond vectors.

Parameters:

• raw (numpy.ndarray) – The raw coordinates of an octahedron.

• mymat (numpy.ndarray) – The lattice matrix of the structure.

Returns:

The six B-X bond vectors.

Return type:

numpy.ndarray

pdyna.structural.periodicity_fold(arrin, n_fold=4)

Handle abnormal tilting numbers.

Parameters:

• arrin (numpy.ndarray) – The input array of tilting angles.

• n_fold (int) – nfold of angle range.

Returns:

The folded tilting angles.

Return type:

numpy.ndarray

pdyna.structural.pseudocubic_lat(traj, allow_equil=0, zdrc=2, lattice_tilt=None)

Compute the pseudo-cubic lattice parameters.

Parameters:

• traj (Trajectory) – The main class instance.

• allow_equil (float) – The fraction of the trajectory to be considered as equilibration.

• zdrc (int) – The z direction for pseudo-cubic lattice paramter reading. a,b,c = 0,1,2.

• lattice_tilt (numpy.ndarray) – If the primary B-B bond is not along orthogonal directions, in degrees.

Returns:

The pseudo-cubic lattice parameters.

Return type:

numpy.ndarray

pdyna.structural.quick_match_octahedron(bx)

Compute the rotation status of an octahedron with a reference. Used in connectivity type 3.

Parameters:

bx (numpy.ndarray) – The six B-X bond vectors.

Returns:

The rotation matrix. numpy.ndarray: The rotated coordinates. float: The RMSD of the fitting.

Return type:

numpy.ndarray

pdyna.structural.resolve_octahedra(Bpos, Xpos, readfr, at0, enable_refit, multi_thread, latmat, fpg_val_BX, neigh_list, orthogonal_frame, structure_type, complex_pbc, ref_initial=None, rtr=None)

Compute octahedral tilting and distortion from the trajectory coordinates and octahedral connectivity.

Parameters:

• Bpos (numpy.ndarray) – Coordinate array of B-sites.

• Xpos (numpy.ndarray) – Coordinate array of X-sites.

• readfr (list) – List of frame numbers to be computed.

• at0 (ASE Atoms) – Atoms object of the initial frame.

• enable_refit (bool) – Enabling of structure refitting during computation if a large distortion is found.

• multi_thread (bool) – Enable multi-threading for computation.

• latmat (numpy.ndarray) – Lattice matrix of all frames, with a shape of (N, 3, 3).

• fpg_val_BX (list) – Defined B-X bond information at the beginning of the class.

• neigh_list (numpy.ndarray) – The B-X connectivity matrix of octahedra with shape (N, 6).

• orthogonal_frame (bool) – If the structure is 3D perovskite and aligned in the orthogonal directions.

• structure_type (int) – Structure type indicating orientation and connectivity of octahedra.

• complex_pbc (bool) – If the cell has strong tilts.

• ref_initial (numpy.ndarray, optional) – For non-orthogonal structure, the individual reference for each octahedron.

• rtr (numpy.ndarray, optional) – A (3, 3) rotation matrix from orthogonal directions if specified.

Returns:

Computed array of octahedral distortion with a shape of (N, dist_dim). numpy.ndarray: Computed array of octahedral tilting with a shape of (N, 3). numpy.ndarray: Record of structural refitting if parameter enable_refit is True, shape is (N, 2), giving a frame number and a bool indicating if refit is performed.

Return type:

numpy.ndarray

pdyna.structural.simply_calc_distortion(traj)

Compute the octahedral distortion of the time-averaged structure.

Parameters:

traj (Trajectory) – The main class instance.

Returns:

The octahedral distortion. numpy.ndarray: The standard deviations of octahedral distortion.

Return type:

numpy.ndarray

pdyna.structural.structure_time_average_ase(traj, start_ratio=0.5, end_ratio=0.98, cif_save_path=None, force_periodicity=False)

Compute the time-averaged structure through the ASE interface.

Parameters:

• traj (Trajectory) – The main class instance.

• start_ratio (float) – The starting ratio of the trajectory to be considered.

• end_ratio (float) – The ending ratio of the trajectory to be considered.

• cif_save_path (str) – The path to save the CIF file.

• force_periodicity (bool) – If the periodic images are considered.

Returns:

The time-averaged Pymatgen structure object

Return type:

pymatgen.Structure

pdyna.structural.structure_time_average_ase_organic(traj, tavgspan, start_ratio=0.5, end_ratio=0.98, cif_save_path=None)

Compute the time-averaged structure, with the organic A-site treated differently.

Parameters:

• traj (Trajectory) – The main class instance.

• tavgspan (int) – The time span for averaging.

• start_ratio (float) – The starting ratio of the trajectory to be considered.

• end_ratio (float) – The ending ratio of the trajectory to be considered.

• cif_save_path (str) – The path to save the CIF file.

Returns:

The time-averaged Pymatgen structure object

Return type:

pymatgen.Structure

pdyna.structural.tqdm_joblib(tqdm_object)

Supportive function for adding progress bar within joblib parallelized computation.

pdyna.structural.traj_time_average(Allpos, latmat, MDTimestep, twindow)

Compute the time-averaged structure from coordinates.

Parameters:

• Allpos (numpy.ndarray) – Coordinate array of all atoms.

• latmat (numpy.ndarray) – Lattice matrix of all frames, with a shape of (N, 3, 3).

• MDTimestep (float) – Time step of the MD simulation.

• twindow (float) – Time window for averaging.

Returns:

Time-averaged coordinates. numpy.ndarray: Time-averaged lattice matrix. int: Number of atoms in the time-averaged structure.

Return type:

numpy.ndarray