pyiron_contrib.protocol.compound.thermodynamic_integration module

class pyiron_contrib.protocol.compound.thermodynamic_integration.HarmonicTILD(**kwargs)[source]

Bases: _TILDParent

A serial TILD protocol to compute the free energy change when the system changes from a set of harmonically

oscillating atoms, to a fully interacting system of atoms. The interactions are described by an interatomic potential, for example, an EAM potential.

NOTE: 1. This protocol is as of now untested with DFT pseudopotentials, and only works for sure, with LAMMPS-
based potentials.
  1. Convergence criterion is NOT implemented for this protocol, because it runs serially (and would take

a VERY long time to achieve a good convergence.

Input attributes:

ref_job_full_path (str): Path to the pyiron job to use for evaluating forces and energies. structure (Atoms): The structure evolve. temperature (float): Temperature to run at in K. n_steps (int): How many MD steps to run for. (Default is 100.) temperature_damping_timescale (float): Langevin thermostat timescale in fs. (Default is None, which runs NVE.) time_step (float): MD time step in fs. (Default is 1.) overheat_fraction (float): The fraction by which to overheat the initial velocities. This can be useful for

more quickly equilibrating a system whose initial structure is its fully relaxed positions – in which case equipartition of energy tells us that the kinetic energy should be initialized to double the desired value. (Default is 2.0, assume energy equipartition is a good idea.)

sampling_period (int): Account output every `sampling_period’ for the TI operations. (Default is 1, account

for every MD step.

thermalization_steps (int): Number of steps the system is thermalized for to reach equilibrium. (Default is

10 steps.)

n_lambdas (int): How many mixing pairs to create. (Default is 5.) custom_lambdas (list): Specify the set of lambda values as input. (Default is None.) spring_constant (float): A single spring / force constant that is used to compute the restoring forces

on each atom, thus treating every atom as an independent harmonic oscillator (Einstein atom). (Default is None.)

force_constants (NxNx3x3 matrix): The Hessian matrix, obtained from, for ex. Phonopy. (Default is None, treat

the atoms as independent harmonic oscillators (Einstein atoms.).)

cutoff_factor (float): The cutoff is obtained by taking the first nearest neighbor distance and multiplying

it by the cutoff factor. A default value of 0.45 is chosen, because taking a cutoff factor of ~0.5 sometimes let certain reflections off the hook, and we do not want that to happen. (Default is 0.45.)

use_reflection (boolean): Turn on or off SphereReflection (Default is True.) eq_energy (float): The minimized potential energy of the static (expanded) structure. (Default is None.)

Output attributes:

total_steps (list): The total number of steps for each integration point, up to convergence, or max steps. temperature_mean (list): Mean output temperature for each integration point. temperature_std (list): Standard deviation of the output temperature for each integration point. integrands_mean (list): Mean of the integrands from TILD. integrands_std (list): Standard deviation of the integrands from TILD. integrands_n_samples (list): Number of samples over which the mean and standard deviation are calculated. tild_free_energy_mean (float): Mean calculated via thermodynamic integration. tild_free_energy_std (float): Standard deviation calculated via thermodynamic integration. tild_free_energy_se (float): Standard error calculated via thermodynamic integration. fep_free_energy_mean (float): Mean calculated via free energy perturbation. fep_free_energy_std (float): Standard deviation calculated via free energy perturbation. fep_free_energy_se (float): Standard error calculated via free energy perturbation.

define_execution_flow()[source]

Wire the logic for traversing the graph edges.

define_information_flow()[source]

Connect input and output information inside the graph. Also set the archive clock for all vertices.

define_vertices()[source]

Add child vertices to the graph.

get_classical_harmonic_free_energy(temperatures=None)[source]
Get the total free energy of a harmonic oscillator with this frequency and these atoms. Temperatures are

clipped at 1 micro-Kelvin.

Returns

The sum of the free energy of each atom.

Return type

float/np.ndarray

get_output()[source]

Define the output dictionary to be returned when the graph traversal completes. This synchronizes the behaviour of primitive vertices and compound vertices when they themselves are the child vertex in another graph.

get_quantum_harmonic_free_energy(temperatures=None)[source]
Get the total free energy of a harmonic oscillator with this frequency and these atoms. Temperatures are

clipped at 1 micro-Kelvin.

Returns

The sum of the free energy of each atom.

Return type

float/np.ndarray

class pyiron_contrib.protocol.compound.thermodynamic_integration.HarmonicTILDParallel(**kwargs)[source]

Bases: HarmonicTILD

A version of HarmonicTILD where the evolution of each integration point is executed in parallel, thus giving a

substantial speed-up. A free energy perturbation standard error convergence exit criterion can be applied, that is unavailable in the serial version of the HarmonicTILD protocol. Maximum efficiency for parallelization can be achieved by setting the number of cores the job can use to the number of lambdas, ie., cores / lambdas = 1. Setting the number of cores greater than the number of lambdas gives zero gain, and is wasteful if cores % lambdas != 0.

Input attributes:
sleep_time (float): A delay in seconds for database access of results. For sqlite, a non-zero delay maybe

required. (Default is 0 seconds, no delay.)

convergence_check_steps (int): Check for convergence once every `convergence_check_steps’. (Default is

once every 10 steps.)

default_free_energy_se (float): Initialize default free energy standard error to pass into the child

protocol. (Default is None.)

fe_tol (float): The free energy standard error tolerance. This is the convergence criterion in eV. (Default

is 0.01 eV)

Output attributes: For inherited input and output attributes, refer the HarmonicTILD protocol.

define_execution_flow()[source]

Wire the logic for traversing the graph edges.

define_information_flow()[source]

Connect input and output information inside the graph. Also set the archive clock for all vertices.

define_vertices()[source]

Add child vertices to the graph.

get_output()[source]

Define the output dictionary to be returned when the graph traversal completes. This synchronizes the behaviour of primitive vertices and compound vertices when they themselves are the child vertex in another graph.

get_tild_integrands()[source]

Get the integrand values from the TILD run.

class pyiron_contrib.protocol.compound.thermodynamic_integration.ProtoHarmTILDPar(project=None, job_name=None)[source]

Bases: Protocol, HarmonicTILDParallel

class pyiron_contrib.protocol.compound.thermodynamic_integration.ProtoHarmTILDSer(project=None, job_name=None)[source]

Bases: Protocol, HarmonicTILD

class pyiron_contrib.protocol.compound.thermodynamic_integration.ProtoVacForm(project=None, job_name=None)[source]

Bases: Protocol, VacancyFormation

class pyiron_contrib.protocol.compound.thermodynamic_integration.ProtoVacTILDPar(project=None, job_name=None)[source]

Bases: Protocol, VacancyTILDParallel

class pyiron_contrib.protocol.compound.thermodynamic_integration.ProtoVacTILDSer(project=None, job_name=None)[source]

Bases: Protocol, VacancyTILD

pyiron_contrib.protocol.compound.thermodynamic_integration.ROOT_EV_PER_ANGSTROM_SQUARE_PER_AMU_IN_S = 98226938500000.0

Protocols for thermodynamic integration using langevin dynamics (TILD).

class pyiron_contrib.protocol.compound.thermodynamic_integration.VacancyFormation(**kwargs)[source]

Bases: VacancyTILDParallel

A protocol which combines HarmonicTILD and VacancyTILD to give the Helmholtz free energy of vacancy formation

directly. The formation energy is computed via thermodynamic integration, as well as free energy perturbation. A formation energy standard error convergence criterion can be applied.

Input attributes:
fe_tol (float): The formation energy standard error tolerance. This is the convergence criterion in eV.

The default is set low, in case maximum number of steps need to be run. (Default is 1e-8 eV.)

force_constants_harm_to_inter (NxN matrix): The Hessian matrix, obtained from, for ex. Phonopy, for use in

harmonic to interacting TILD. (Default is None, treat the atoms as independent harmonic oscillators (Einstein atoms.).) Note, that another input, force_constants also exists. But that is only used in interacting to vacancy TILD.

harmonic_to_interacting_lambdas (list): Specify the set of lambda values as input for harmonic to

interacting TILD. (Default is None.)

interacting_to_vacancy_lambdas (list): Specify the set of lambda values as input for interacting to

vacancy TILD. (Default is None.)

default_formation_energy_se (float): Initialize default free energy standard error to pass into the child

protocol. (Default is None.)

Output attributes:
formation_energy_tild (float): The Helmholtz free energy of vacancy formation computed from thermodynamic

integration.

formation_energy_tild_std (float): The tild standard deviation. formation_energy_tild_se (float): The tild standard error of the mean. formation_energy_fep (float): The Helmholtz free energy of vacancy formation computed from free energy

perturbation.

formation_energy_fep_std (float): The fep standard deviation. formation_energy_fep_se (float): The fep standard error of the mean.

For inherited input and output attributes, refer the VacancyTILDParallel protocol.

define_execution_flow()[source]

Wire the logic for traversing the graph edges.

define_information_flow()[source]

Connect input and output information inside the graph. Also set the archive clock for all vertices.

define_vertices()[source]

Add child vertices to the graph.

get_lambdas(integrands='harm_to_inter')[source]

Get the lambda values.

get_output()[source]

Define the output dictionary to be returned when the graph traversal completes. This synchronizes the behaviour of primitive vertices and compound vertices when they themselves are the child vertex in another graph.

get_tild_integrands(integrands='harm_to_inter')[source]

Get the integrand values from the TILD run.

class pyiron_contrib.protocol.compound.thermodynamic_integration.VacancyTILD(**kwargs)[source]

Bases: _TILDParent

A serial TILD protocol to compute the free energy change when the system changes from a fully interacting

system of atoms to the same system with a single vacancy. This is done by ‘decoupling’ one of the atoms of the system from the rest of the atoms, and letting it behave as a harmonic oscillator, thus creating a pseudo-vacancy. The chemical potential of this harmonically oscillating atom is then subtracted from the total free energy change, to give the free energy change between the fully interacting system, and the same system with a vacancy. NOTE: 1. This protocol is as of now untested with DFT pseudopotentials, and only works for sure, with LAMMPS- based potentials. 2. Convergence criterion is NOT implemented for this protocol, because it runs serially (and would take a VERY long time to achieve a good convergence.

Input attributes:

ref_job_full_path (str): Path to the pyiron job to use for evaluating forces and energies. structure (Atoms): The structure evolve. vacancy_id (int): The id of the atom which will be deleted to create a vacancy. (Default is 0, the 0th atom.) temperature (float): Temperature to run at in K. n_steps (int): How many MD steps to run for. (Default is 100.) temperature_damping_timescale (float): Langevin thermostat timescale in fs. (Default is None, which runs NVE.) overheat_fraction (float): The fraction by which to overheat the initial velocities. This can be useful for

more quickly equilibrating a system whose initial structure is its fully relaxed positions – in which case equipartition of energy tells us that the kinetic energy should be initialized to double the desired value. (Default is 2.0, assume energy equipartition is a good idea.)

time_step (float): MD time step in fs. (Default is 1.) sampling_period (int): Account output every `sampling_period’ for the TI operations. (Default is 1, account

for every MD step.

thermalization_steps (int): Number of steps the system is thermalized for to reach equilibrium. (Default is

10 steps.)

n_lambdas (int): How many mixing pairs to create. (Default is 5.) custom_lambdas (list): Specify the set of lambda values as input. (Default is None.) spring_constant (float): A single spring / force constant that is used to compute the restoring forces

on each atom. (Default is None.)

force_constants (NxN matrix): The Hessian matrix, obtained from, for ex. Phonopy. (Default is None, treat

the atoms as independent harmonic oscillators (Einstein atoms.).)

cutoff_factor (float): The cutoff is obtained by taking the first nearest neighbor distance and multiplying

it by the cutoff factor. A default value of 0.45 is chosen, because taking a cutoff factor of ~0.5 sometimes let certain reflections off the hook, and we do not want that to happen. (Default is 0.45.)

use_reflection (boolean): Turn on or off SphereReflection (Default is True.)

Output attributes:

total_steps (list): The total number of steps for each integration point, up to convergence, or max steps. temperature_mean (list): Mean output temperature for each integration point. temperature_std (list): Standard deviation of the output temperature for each integration point. integrands_mean (list): Mean of the integrands from TILD. integrands_std (list): Standard deviation of the integrands from TILD. integrands_n_samples (list): Number of samples over which the mean and standard deviation are calculated. tild_free_energy_mean (float): Mean calculated via thermodynamic integration. tild_free_energy_std (float): Standard deviation calculated via thermodynamic integration. tild_free_energy_se (float): Standard error calculated via thermodynamic integration. fep_free_energy_mean (float): Mean calculated via free energy perturbation. fep_free_energy_std (float): Standard deviation calculated via free energy perturbation. fep_free_energy_se (float): Standard error calculated via free energy perturbation.

define_execution_flow()[source]

Wire the logic for traversing the graph edges.

define_information_flow()[source]

Connect input and output information inside the graph. Also set the archive clock for all vertices.

define_vertices()[source]

Add child vertices to the graph.

get_output()[source]

Define the output dictionary to be returned when the graph traversal completes. This synchronizes the behaviour of primitive vertices and compound vertices when they themselves are the child vertex in another graph.

class pyiron_contrib.protocol.compound.thermodynamic_integration.VacancyTILDParallel(**kwargs)[source]

Bases: VacancyTILD

A version of VacancyTILD where the evolution of each integration point is executed in parallel, thus giving a

substantial speed-up. A free energy perturbation standard error convergence exit criterion can be applied, that is unavailable in the serial version of the VacancyTILD protocol. Maximum efficiency for parallelization can be achieved by setting the number of cores the job can use to the number of lambdas, ie., cores / lambdas = 1. Setting the number of cores greater than the number of lambdas gives zero gain, and is wasteful if cores % lambdas != 0.

Input attributes:
sleep_time (float): A delay in seconds for database access of results. For sqlite, a non-zero delay maybe

required. (Default is 0 seconds, no delay.)

convergence_check_steps (int): Check for convergence once every `convergence_check_steps’. (Default is

once every 10 steps.)

default_free_energy_se (float): Initialize default free energy standard error to pass into the child

protocol. (Default is None.)

fe_tol (float): The free energy standard error tolerance. This is the convergence criterion in eV. (Default

is 0.01 eV)

Output attributes: For inherited input and output attributes, refer the HarmonicTILD protocol.

define_execution_flow()[source]

Wire the logic for traversing the graph edges.

define_information_flow()[source]

Connect input and output information inside the graph. Also set the archive clock for all vertices.

define_vertices()[source]

Add child vertices to the graph.

get_output()[source]

Define the output dictionary to be returned when the graph traversal completes. This synchronizes the behaviour of primitive vertices and compound vertices when they themselves are the child vertex in another graph.

get_tild_integrands()[source]

Get the integrand values from the TILD run.