principia_materia.phonon_id.fd_series module

class principia_materia.phonon_id.fd_series.FDSeries(structure, supa, order, fdtype='c', tol=1e-06)

Bases: object

Execute a series of finite displacements calculations.

In calculations of phonons and their interactions, a seiries of finite displacements calculations from the same structure are usually needed for both BID and LID methods. This class manages a series of finite displacement calculations, and serves as a simple interface between our finite displacement engine and the phonon interaction analysis tools.

Parameters:

  • structure (CrystalFTG object or a structure file of CrystalFTG) – The crystal structure.

  • supa (array of int, shape(dim, dim)) – Supercell matrix.

  • order (int) – Order of the derivative.

  • fdtype (str, choice of ["c", "f", "b"]) – Type of finite displacement.

  • tol (float, optional, default to 1.0E-6) – Error tolerence.

create_jobs(job_handler, prefix=None, delta_format=<function format_delta_dirname>, jobname_prefix='', config_file='finite_displacements.yml', append=False, skip_zero=False, dry_run=False)

Create compute jobs for the finite displacements calculations.

Parameters:

  • job_handler (ComputeJobSeries or JobsDB) – Either a ComputeJobSeries or a JobsDB object as the interface to the jobs.

  • prefix (str, optional, default to None) – Prefix to the jobnames.

  • delta_format (callable, optional, default to function: format_delta_dirname.) – A function that format a delta into a string for directory name. Must be in form of def function(delta, ...): ....

  • jobname_prefix (str) – Prefix for jobnames.

  • config_file (str, optional, default to "finite_displacements.yml") – The name of the finite displacements configuration file.

  • dry_run (bool, optional, default to False) – If True, don’t actually create the job.

project_fd_results(basis)

Project the finite displacement result onto a given bases.

Parameters:

basis (array of float or complex, shape(N, supercell.natoms, ndim)) – An array of basis to project upon.

Returns:

projection – The result of finite displacements projected onto the input basis.

Return type:

array of float or complex, shape(n_delta, n_meas, N)

set_deltas(deltas, append=False)

Set displacement amplitudes.

Parameters:

  • deltas (float or array of float) – The displacement amplitude.

  • append (bool, optional, default to False) – If True, add the input deltas to existing deltas.

set_errortail_results(pick_min=3, pick_max=None, consecutive=False, penalty=<function penalty_linear_mse>, separate_complex=True, return_pick=False, return_penalty=False)

Compute error tail for the finite displacements result.

Parameters:

  • pick_min (int, optional, default to 3) – The minimum number of picks for delta selection.

  • pick_max (int, optional, default to None) – The maximum number of picks for delta selection. If None, the pick n scheme is used with n=pick_min. If not None, the pick N schcme is used with N=[pick_min, pick_max].

  • consecutive_picks (bool, optional, default to False) – Whether to pick consecutive deltas in the picking process.

  • penalty (callable, optional, default to penalty_linear_mse) – The penalty function to determine the best fit.

  • separate_complex (bool, optional, default to False) – Whether to fit real and imaginary part of the complex data points separetely.

  • return_pick (bool, optional, default to False) – Whether to return the indices of the picked points.

  • return_penalty (bool, optional, default to False) – Whether to return the result of the penalty function.

set_jobname_prefix(jobname_prefix='')
set_measurement_alias(alias, alias_name)
set_measurements(measurements, measurement_names=None)

Set measurements vectors and their names.

The measurements vectors will be used to displace the structure and the names will be used as directory names that accommodates the compute jobs for the calculation.

Parameters:

  • measurements (array of numbers) – A series of measurements, each measurement consists of self.order number of displacement vectors.

  • measurement_names (list of str) – Name of the measurement sets, used to naming the directories.

set_results(job_handler, data_type, prefix=None, fill=0.0, skip_zero=False, config_file='finite_displacements.yml')

Collect computation results and compute finite displacements.

Parameters:

  • job_handler (ComputeJobSeries or JobsDB) – Either a ComputeJobSeries or a JobsDB object as the interface to the jobs.

  • data_type (str, choices of "forces" and "energy") – Type of data to read from compute jobs.

  • prefix (str, optional, default to None) – Prefix to the jobnames.

  • config_file (str, optional, default to "finite_displacements.yml") – The name of the finite displacements configuration file.

_fd_results

The result of finite displacements calculations.

Type:

array of float, shape(n_delta, n_meas, supercell.natoms, ndim)

principia_materia.phonon_id.fd_series.format_delta_dirname(delta, max_decimal=8, default_padding=4, prefix='delta_', suffix='')

Format directory name with delta

Parameters:

  • delta (float) – Delta value

  • max_decimal (int, optional, default to 8) – Maximum allowed digits after decimal point, any digit after that will be rounded.

  • default_padding (int, optional, default to 4) – Default 0 padding after the decimal point.

  • prefix (str, optional, default to "delta_") – Prefix of the name before formatted the delta value.

  • suffix (str, optional, default to "") – Suffix of the name behind formatted the delta value,

principia_materia.phonon_id.fd_series.get_FDSeries_from_hdf5(h5file, tol=1e-06)

Read data from HDF5 file and construct a FDSeries object.

Parameters:

  • h5file (str or h5py.File/h5py.Group obejct) – Path to a HDF5 file or a h5py.File/h5py.Group object.

  • tol (float, optional, default to 1.0E-6) – Error tolerance.

principia_materia.phonon_id.fd_series.get_FDSeries_hdf5_wrapper()

HDF5 data wrapper for FDSeries class.

principia_materia.phonon_id.fd_series.get_FDSeries_results_hdf5_wrapper()

HDF5 data wrapper for FDSeries class.

principia_materia.phonon_id.fd_series.save_FDSeries_results_to_hdf5(obj, h5file='fdseries_results.hdf5', overwrite=False)

Save the results of a FDSeries object into a HDF5 file.

Parameters:

  • obj (FDSeries) – A FDSeries object.

  • h5file (str or h5py.File/h5py.Group obejct, optional, default to "fdseries_results.hdf5") – Path to a HDF5 file or a h5py.File/h5py.Group object.

  • overwrite (bool, optional, default to False) – When the file exists, whether to replace the content of the file with the content to be saved.

principia_materia.phonon_id.fd_series.save_FDSeries_to_hdf5(obj, h5file='fdseries.hdf5', overwrite=False)

Save data of a FDSeries object into a HDF5 file.

Parameters:

  • obj (FDSeries) – A FDSeries object.

  • h5file (str or h5py.File/h5py.Group obejct, optional, default to "fdseries.hdf5") – Path to a HDF5 file or a h5py.File/h5py.Group object.

  • overwrite (bool, optional, default to False) – When the file exists, whether to replace the content of the file with the content to be saved.