pdyna.core module

pdyna.core: The three core classes for structural analysis.

Three forms of data are available for processing, namely MD trajectory, single structure frame, and dataset containing mulitple structure frames. The input to each class is the original files of strucures and/or a set of parameters that describe the structures. It returns the processed data class (with callable attributes) and a series of printouts and figures.

class pdyna.core.Dataset(data_format: str, data_path: str)[source]

Bases: object

Class representing the local configuration dataset to analyze. Initialize the class with reading the dataset.

Parameters:

  • data_format (str) – Data format. Currently compatible formats are ‘mlab’ and ‘extxyz’.

  • data_path (str) – Path of input files.

data_format: str
data_path: str
featurize(uniname='test', saveFigures=False, tilt_corr_NN1=True, system_overwrite=None)[source]

Core function for featurizing the perovskite trajectory. The parameters are used to enable various featurization functions and handle their functionality.

Parameters:

  • uniname (str) – A unique user-defined name for this trajectory, will be used in printing and figure saving. Default is “test”.

  • saveFigures (bool) – Whether to save produced figures. Default is False.

  • tilt_corr_NN1 (bool) – Enable first NN correlation of tilting, reflecting the Glazer notation. Default is True.

  • system_overwrite (dict) – Contains X-site and B-site info, and the default bond lengths. Default is None.

class pdyna.core.Frame(data_format: str, data_path: str)[source]

Bases: object

Class for analysis of single-frame structure. Initialize the class with reading the raw data.

Parameters:

  • data_format (str) – Data format based on the software. Currently compatible formats are ‘poscar’ and ‘cif’.

  • data_path (tuple) – The input file path. - poscar: poscar_path - cif: cif_path

analysis(uniname='test', saveFigures=False, align_rotation=[0, 0, 0], tilt_corr_spatial=False, max_tilt_of_plot=None, min_tilt_of_plot=None, system_overwrite=None)[source]

Core function for analysing perovskite trajectory. The parameters are used to enable various analysis functions and handle their functionality.

Parameters:

  • uniname (str) – A unique user-defined name for this trajectory, will be used in printing and figure saving. Default is “test”.

  • saveFigures (bool) – Whether to save produced figures. Default is False.

  • align_rotation (list) – Rotation angles about [a, b, c] in degrees to match orthogonal directions. Default is [0, 0, 0].

  • tilt_corr_spatial (bool) – Enable spatial correlation beyond NN1. Default is False.

  • max_tilt_of_plot (float) – Maximum tilt angle for plotting. Default is None.

  • min_tilt_of_plot (float) – Minimum tilt angle for plotting. Default is None.

  • system_overwrite (dict) – Contains X-site and B-site info, and the default bond lengths. Default is None.

data_format: str
data_path: str
tilting_and_distortion(uniname, saveFigures, tilt_corr_spatial, max_tilt_of_plot, min_tilt_of_plot)[source]

Octhedral tilting and distribution analysis.

class pdyna.core.Trajectory(data_format: str, data_path: tuple)[source]

Bases: object

Main class representing the MD trajectory to analyze. Initialize the class with reading the raw data.

Parameters:

  • data_format (str) – Data format based on the MD software. Currently compatible formats are ‘vasp’, ‘xyz’, ‘ase-traj’, ‘extxyz’, ‘pdb’, and ‘lammps’.

  • data_path (tuple) –

    The input file path. - vasp: (poscar_path, xdatcar_path, incar_path) - lammps: (dump.out_path, MD setting tuple) - xyz: (xyz_path, MD setting tuple) - ase-trajectory: (ase_traj_path, MD setting tuple) - pdb: (pdb_path, MD setting tuple) - extxyz: (extxyz_path, init_extxyz_file, MD setting tuple)

    Format for MD setting tuple: (Ti, Tf, tstep), this is the same for all formats except VASP which uses the INCAR file.

Allpos

The atomic positions of all frames.

Type:

numpy.ndarray

latmat

The lattice matrix of all frames.

Type:

numpy.ndarray

uniname

The unique name of the trajectory, given by the user.

Type:

str

st0

The initial structure in Pymatgen format.

Type:

Structure

at0

The initial structure in ASE format.

Type:

Atoms

Xindex

The indices of X-site atoms. The same for other site types.

Type:

list

natom

The number of atoms in the structure.

Type:

int

species_set

The set of atomic species.

Type:

set

formula

The chemical formula of the structure.

Type:

str

nframe

The number of frames in the trajectory.

Type:

int

atomic_symbols

The list of atomic symbols.

Type:

list

MDsetting

The MD settings.

Type:

dict

MDTimestep

The time step between recorded frames.

Type:

float

Tgrad

The temperature gradient.

Type:

float

allow_equil

The fraction of the trajectory to be considered as equilibration.

Type:

float

read_every

The sampling (skipping) of steps to read.

Type:

int

timing

The time usgae of each constituent process.

Type:

dict

octahedra

The octahedral network information.

Type:

numpy.ndarray

prop_lib

The dictionary of computed properties.

Type:

dict

Lat

The lattice parameters of processed frames.

Type:

numpy.ndarray

Distortion

The octahedral distortions of processed frames.

Type:

numpy.ndarray

Tilting

The octahedral tilting angles of processed frames.

Type:

numpy.ndarray

Tilting_Corr

The tilting correlation of processed frames.

Type:

numpy.ndarray

MOvec

The molecular orientation vectors of processed frames.

Type:

numpy.ndarray

spatialCorr

The spatial correlation function of tilting.

Type:

numpy.ndarray

spatialCorrLength

The fitted spatial correlation length of tilting.

Type:

numpy.ndarray

data_format: str
data_path: tuple
dynamics(read_mode: int, uniname='test', allow_equil=0.5, read_every=0, coords_time_average=0, saveFigures=False, lib_saver=False, lib_overwrite=False, preset=0, toggle_lat=False, toggle_tavg=False, toggle_tilt_distort=False, toggle_MO=False, toggle_RDF=False, toggle_site_disp=False, smoother=0, lat_method=1, zdir=2, leading_crop=0.0, vis3D_lat=0, start_ratio=None, tavg_save_dir='.', Asite_reconstruct=False, structure_type=1, multi_thread=1, rotation_from_orthogonal=None, tilt_corr_NN1=True, structure_ref_NN1=None, full_NN1_corr=False, tilt_corr_spatial=False, tiltautoCorr=False, octa_locality=False, enable_refit=False, symm_n_fold=0, tilt_recenter=False, tilt_domain=False, vis3D_domain=0, MOautoCorr=False, MO_corr_spatial=False, draw_MO_anime=False, system_overwrite=None)[source]

Core function for analysing perovskite trajectory.

The parameters are used to enable various analysis functions and handle their functionality.

Parameters:

  • read_mode (int) – Key parameter, define the reading mode. 1: static mode (time-independent), 2: transient mode (time/temperature-dependent). No default.

  • uniname (str) – A unique user-defined name for this trajectory, will be used in printing and figure saving. Default is “test”.

  • allow_equil (float) – Take the first x fraction of the trajectory as equilibration, this part will not be computed. Default is 0.5.

  • read_every (int) – Read only every n steps, default is 0 which the code will decide an appropriate value according to the system size.

  • coords_time_average (float) – Time-averaging of coordinates, input t>0 as the average time window with a unit of picosecond. Use with caution. Default is 0.

  • saveFigures (bool) – Whether to save produced figures. Default is False.

  • lib_saver (bool) – Whether to save computed material properties in lib file. Default is False.

  • lib_overwrite (bool) – Whether to overwrite existing lib entry (True), or just change upon them (False). Default is False.

  • preset (int) – Presets of useful function toggles, if specified as non-0, the individual toggles will be disabled. 0: no preset, 1: lat & tilt_distort, 2: lat & tilt_distort & tavg & MO, 3: all. Default is 0.

  • toggle_lat (bool) – Switch of lattice parameter calculation. Default is False.

  • toggle_tavg (bool) – Switch of time averaged structure. Default is False.

  • toggle_tilt_distort (bool) – Switch of octahedral tilting and distortion calculation. Default is False.

  • toggle_MO (bool) – Switch of molecular orientation (MO) calculation (for organic A-site). Default is False.

  • toggle_RDF (bool) – Switch of radial distribution function (RDF) calculation. Default is False.

  • toggle_site_disp (bool) – Switch of A-site cation displacement calculation. Default is False.

  • smoother (int) – Whether to use S-G smoothing on time-dependent outputs, 0: disabled, >0: average window in picosecond. Default is 0.

  • lat_method (int) – Lattice parameter analysis methods, 1: direct lattice cell dimension, 2: pseudo-cubic lattice parameter (only available in 3D connectivity). Default is 1.

  • zdir (int) – Specified z-direction in case of lat_method 2. Default is 2 (axis c of sample).

  • leading_crop (float) – Remove the first x fraction of the trajectory on plotting. Default is 0.00.

  • vis3D_lat (int) – 3D visualization of lattice parameter in time. Default is 0.

  • start_ratio (float) – Time-averaging structure ratio, e.g. 0.9 means only averaging the last 10% of trajectory. Default is None.

  • tavg_save_dir (str) – Directory for saving the time-averaging structures. Default is “.”.

  • Asite_reconstruct (bool) – Setting a different time-averaging algo for organic A-sites, needs the time correlation function of MD to work (MOautoCorr = True). Default is False.

  • structure_type (int) – Define connectivity of the perovskite. 1: 3C polytype, 2: other non-perovskite with orthogonal reference enabled, 3: other non-perovskite with initial config as reference, 4: 3C structure with defects (experimental). Default is 1.

  • multi_thread (int) – If >1, enable multi-threading in this calculation. Default is 1.

  • rotation_from_orthogonal (list) – None: code will detect if the BX6 frame is not orthogonal to the principle directions, only manually input this [x,y,z] rotation angles in degrees if told by the code. Default is None.

  • tilt_corr_NN1 (bool) – Enable first NN correlation of tilting, reflecting the Glazer notation. Default is True.

  • structure_ref_NN1 (dict) – Dict of vectors (numpy.ndarray) of an octahedron to its NN1 neighbours classified into groups and labeled with dict keys. Default is None.

  • full_NN1_corr (bool) – Include off-diagonal correlation terms (tilt_corr_NN1 = True only gives the diagonal terms). Default is False.

  • tilt_corr_spatial (bool) – Enable computing of spatial correlation beyond NN1. Default is False.

  • tiltautoCorr (bool) – Compute Tilting autocorrelation time constant. Default is False.

  • octa_locality (str) – Compute differentiated properties within binary mixed-X sample, default species are “I” and “Br”, “homo” is homogeneous mixing of X-sites, “hetero” is for segregated grains of X-sites. Default is False.

  • enable_refit (bool) – Refit the octahedral network in case of detected change of geometry, enabling this option will turns off the multi-threading. Default is False.

  • symm_n_fold (int) – Tilting range, 0: auto, 2: [-90,90], 4: [-45,45], 8: [0,45]. Default is 0.

  • tilt_recenter (bool) – Whether to eliminate the shift in tilting values according to the mean value of population. Default is False.

  • tilt_domain (bool) – Compute the time constant of tilt correlation domain formation. Default is False.

  • vis3D_domain (int) – 3D visualization of tilt domain in time. 0: off, 1: apparent tilting, 2: tilting correlation status. Default is 0.

  • MOautoCorr (bool) – Compute MO reorientation time constant. Default is False.

  • MO_corr_spatial (bool) – Enable spatial correlation function of MO. Default is False.

  • draw_MO_anime (bool) – Plot the MO in 3D animation and snapshot, can be time-consuming. Default is False.

  • system_overwrite (dict) – Contains X-site and B-site info, and the default bond lengths. Default is None.

lattice_parameter(uniname, lat_method, read_mode, allow_equil, zdir, smoother, leading_crop, saveFigures, title, vis3D_lat)[source]

Lattice parameter analysis methods.

molecular_orientation(uniname, read_mode, allow_equil, MOautoCorr, MO_corr_spatial, title, saveFigures, smoother, draw_MO_anime)[source]

A-site molecular orientation (MO) analysis.

property_processing(allow_equil, read_mode, octa_locality, uniname, saveFigures)[source]

Post-processing of computed properties.

radial_distribution(allow_equil, uniname, saveFigures)[source]

Radial distribution function (RDF) analysis.

site_displacement(allow_equil, uniname, saveFigures)[source]

A-site cation displacement analysis.

system_test(B_sites=None, X_sites=None)[source]

System test for a single-frame structure, to output the structural information for a full trajectory reading.

tilting_and_distortion(uniname, multi_thread, read_mode, read_every, allow_equil, tilt_corr_NN1, tilt_corr_spatial, enable_refit, symm_n_fold, saveFigures, smoother, title, orthogonal_frame, structure_type, tilt_domain, vis3D_domain, tilt_recenter, full_NN1_corr, tiltautoCorr, structure_ref_NN1)[source]

Octhedral tilting and distribution analysis.