principia_materia.phonon_id.hsbid module

class principia_materia.phonon_id.hsbid.HSBID(structure, supa, order, pg='C1', full_symmetry=False, hidden_order=1, fdtype='c', tol=1e-06)

Bases: object

Use Hierarchical Supercell Bundled Irreducible Derivatives approach to compute phonons and their interactions

Parameters:

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

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

• order (int) – Order of the phonon interaction.

• pg (str or PointGroup object, optional, default to "C1") – The point group.

• full_symmetry (bool, optional, default to False) – If True, use full group analysis (not implemented yet). If False, use little group analysis.

• hidden_order (int, optional, default to 1) – The order of derivatives from first principles.

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

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

property QpointsN

compute_irreducible_derivatives()

Compute irreducible derivatives with finite displacements result and chainrule matrices/tensors.

irreducible_derivatives

The values of all irreducible derivatives in the current system.

Type:

array of complex shape(n_irreducible_derivatives, )

create_jobs(job_handler, deltas, supa_format=<function format_supa_dirname>, delta_format=<function format_delta_dirname>, measurement_label=<function format_measurement_label>, jobname_prefix='', config_file='finite_displacements.yml', bid_filename='bid.hdf5', append=False, dry_run=False)

Create compute jobs for the BID calculations.

Parameters:

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

• deltas (list of numbers, list of arrays, 1-d or 2-d array) –

  Displacement amplitude. Can take following types:

  1. a number, will be broadcast into a shape(n_measurements, 1) array.

  2. an 1-d array of length N, will be broadcast into a shape(n_measurements, N) array.

  3. a 2-d array of shape(n_measurements, N).

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

• supa_format (callable, optional default to function: format_supa_dirname) – A function that format the supercell into a string for directory name.

• 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, ...): ....

• measurement_label (callable, optional, default to format_measurement_label) – A function that format the measurement indices into certain string format. Must be in form of def function(measurement_index, …): …

• jobname_prefix (str) – Prefix for jobnames.

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

• bid_filename (str, optional, default to "bid.hdf5") – The name of HDF5 file to save BID data into.

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

property derivative_order

The order of the finite displacements derivative.

find_measurements(extra_measurements=0, test_measurements=5, verbose=False)

Find measurements in each hierchical supercell that can solve the chainrule matrix.

Parameters:

• extra_measurements (int, optional, default to 0) – The amount of extra measurement, the new number of measurement is calculated with the equation: n_measurements *= extra_measurements + 1.

• test_measurements (int, optional, default to 5) – The number of test measurements.

• verbose (bool, optional, default to False)

get_dynamic_tensors()

Compute dynamic tensors of the irreducible Q-points from irreducible derivatives.

Returns:

dynamic_tensors – (where N_IQ is the number of irreducible Q-points) The dynamic tensors of the irreducible Q-points.

Return type:

array of complex, shape(N_IQ, ) + (norbitals, ) * order

get_fourier_interpolation()

Construct the FourierInterpolation object from dynamic tensors of irreducible Q-points.

Returns:

fourier_interpolation – A FourierInterpolation object.

Return type:

FourierInterpolation

get_irreducible_derivative_names()

load_hsbid(root_directory, bid_filename='bid.hdf5')

Load BID objects from HDF5 files.

Parameters:

• root_directory (str) – The root directory of the HSBID jobs.

• bid_filename (str, optional, default to "bid.hdf5") – The name of HDF5 file to save BID data into.

set_chainrule_derivatives(verbose=False)

Instantiate the ChainruleDerivatives class to compute chainrule matrices/tensors.

Parameters:

verbose (bool, optional, default to False) – Whether to print out the analysis steps in the construction of the ChainruleDerivatives object.

_chainrule

The ChainruleDerivatives object for the system.

Type:

ChainruleDerivatives

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

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 (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.

• output (str, optional, default to None) – Path of the output file. If not None, save the output of errortail fit to the file.

set_hsbid()

Construct hierchical supercells and their BID objects.

set_results(job_handler, data_type, config_file='finite_displacements.yml')

Get finite displacements results from calculations.

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.

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

principia_materia.phonon_id.hsbid.find_hierarchical_supercells(Qpoints, Qpoints_orbits)

Find Hierchical supercells that accommondates the input Q-points.

Find the minimum amount of supercells that for each of the input Q-point, there is a supercell that is the smallest supercell that can accommondate the Q-point according to group theory.

A greedy search is implemented instead of a brute-force search for efficiency.

Parameters:

• Qpoints (array of float, shape(N, order, dim)) – All the Q-points from a FTG.

• Qpoints_orbits (list of arrays of int) – List of arrays each represents an orbit of Q-points that are associated by space group symmetry.

Returns:

supercells – The set of hierarchical supercells.

Return type:

list of shape(dim, dim) arrays of int

principia_materia.phonon_id.hsbid.format_supa_dirname(supa)

principia_materia.phonon_id.hsbid.get_HSBID_from_hdf5(h5file, tol=1e-06)

Read data from HDF5 file and construct a HSBID 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.hsbid.get_HSBID_hdf5_wrapper()

HDF5 data wrapper for LIDMesh configurations.

principia_materia.phonon_id.hsbid.save_HSBID_to_hdf5(obj, h5file='hsbid.hdf5', include_bid=True, overwrite=False)

Save data of a HSBID object into a HDF5 file.

Parameters:

• obj (BID) – A HSBID object.

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