principia_materia.phonon_id.bid module

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

Bases: object

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

compute_irreducible_derivatives(known_ID=[])

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

Parameters:: known_ID (array of complex, shape(len(self._chainrule._known_ID_index), )) – The values of the known irreducible derivatives.

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, prefix=None, delta_format=<function format_delta_dirname>, measurement_label=<function format_measurement_label>, jobname_prefix='', config_file='finite_displacements.yml', append=False, dry_run=False)

Create compute jobs for the BID calculations.

The displacement amplitudes applied to the crystal follow the convention discussed in the paper Phys. Rev. B 100, 014303 (2019).

\[u_{\textbf{t}}*{\left(b, \beta\right)} = \sum_{\textbf{q} \in \hat{S}_{BZ}} u_{\textbf{q}}*{\left(b, \beta\right)} e^{2\pi\imag \textbf{t} \cdot \textbf{q}}\]

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.
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.
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, max_search=20)

Find measurements that can solve the chainrule matrix.

The steps are as follows:

Find the number of unknown irreducible derivatives.

2. With test_measurements test measurements, find the maximum rank a single displacement can provide.

3. Assume the initial number of measurement as ceil(n_unknowns/single_measurement_rank).

4. If extra_measurements is none zero, multiply n_measurements by extra_measurements + 1.

5. Start with trying out several sets of n_measurements measurements to see if the chainrule matrices/tensors can reach condition rank==n_unknowns.

6. If above condition can’t be met after several (5) attemps, increase n_measurements by 1 and repeat step 5-6, until the condition is reached. However, after too many failed attempts (20), the code will quit and throw an error saying the measurements can’t be found.

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) – Verbosity.
max_search (int, optional, default to 20) – Number of attempts to search for the measurements.

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()

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_chainrule_matrix(): Compute chainrule matrices/tensors for the set measurements.

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

_fd_errortail

The errortail extrapolated finite displacements results of the BID finite displacements calculations.

Type:: array of complex

set_measurements(measurements): Set measurements, normalize them and compute chainrule matrices/tensor for them.

set_results(job_handler, data_type, prefix=None, 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.

_fd_results

The result of the finite displacements calculations.

Type:: list of arrays of complex, length of number of measurements

class principia_materia.phonon_id.bid.DisplacementGenerator(shape, decimals=8)

Bases: object

Displacement vector generator.

The algorithm of this displacement generator is described in the paper.

Parameters:

shape (tuple of integers) – Shape of the displacement.
decimals (interger) – The decimal points to round up the displacement vector.

astep()

astep_one()

property n

next()

reset()

class principia_materia.phonon_id.bid.RandomDisplacementGenerator(shape, decimals=8)

Bases: object

Random number displacement vector generator.

Generate displacement vectors with purely random numbers.

Parameters:

shape (tuple of integers) – Shape of the displacement.
decimals (interger) – The decimal points to round up the displacement vector.

next()

reset()

principia_materia.phonon_id.bid.format_measurement_label(measurement_index, zero_padding=0)

Format measurement indices into str labels.

Parameters:

measurement_index (int) – The index of the measurement.
zero_padding (int, optional, default to 0) – The amount of zero padding on the left of the measurement indices.

Returns:

label – The label for the measurement.

Return type:

str

principia_materia.phonon_id.bid.get_BID_from_hdf5(h5file, tol=1e-06)

Read data from HDF5 file and construct a BID 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.bid.get_BID_hdf5_wrapper(): HDF5 data wrapper for BID class.

principia_materia.phonon_id.bid.save_BID_to_hdf5(obj, h5file='bid.hdf5', overwrite=False)

Save data of a BID object into a HDF5 file.

Parameters:

obj (BID) – A BID object.
h5file (str or h5py.File/h5py.Group obejct, optional, default to "bid.hdf5") – Path to a HDF5 file or a h5py.File/h5py.Group object.

principia_materia.phonon_id.bid.save_bid_errortails(output, fdtype, deltas, fd_values, result, xcoef, pick, penalty, overwrite=True): Save errortail data of frozen phonon runs into HDF5 file.