calphy package#

Submodules#

calphy.alchemy module#

calphy.helpers module#

calphy.input module#

calphy: a Python library and command line interface for automated free energy calculations.

Copyright 2021 (c) Sarath Menon^1, Yury Lysogorskiy^2, Ralf Drautz^2 ^1: Max Planck Institut für Eisenforschung, Dusseldorf, Germany ^2: Ruhr-University Bochum, Bochum, Germany

calphy is published and distributed under the Academic Software License v1.0 (ASL). calphy is distributed in the hope that it will be useful for non-commercial academic research, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. calphy API is published and distributed under the BSD 3-Clause “New” or “Revised” License See the LICENSE FILE for more details.

More information about the program can be found in: Menon, Sarath, Yury Lysogorskiy, Jutta Rogal, and Ralf Drautz. “Automated Free Energy Calculation from Atomistic Simulations.” Physical Review Materials 5(10), 2021 DOI: 10.1103/PhysRevMaterials.5.103801

For more information contact: sarath.menon@ruhr-uni-bochum.de/yury.lysogorskiy@icams.rub.de

class calphy.input.Berendsen(*, thermostat_damping: float = 100.0, barostat_damping: float = 100.0)[source]#

Bases: BaseModel

barostat_damping: float#
model_config: ClassVar[ConfigDict] = {'title': 'Specific input options for Berendsen thermostat'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

thermostat_damping: float#
class calphy.input.Calculation(*, monte_carlo: Optional[MonteCarlo] = MonteCarlo(n_steps=1, n_swaps=0, reverse_swap=True, swap_types=[1, 2]), composition_scaling: Optional[CompositionScaling] = CompositionScaling(output_chemical_composition={}, restrictions=[]), md: Optional[MD] = MD(timestep=0.001, n_small_steps=10000, n_every_steps=10, n_repeat_steps=10, n_cycles=100, thermostat_damping=0.1, barostat_damping=0.1, cmdargs='', init_commands=[]), nose_hoover: Optional[NoseHoover] = NoseHoover(thermostat_damping=0.1, barostat_damping=0.1), berendsen: Optional[Berendsen] = Berendsen(thermostat_damping=100.0, barostat_damping=100.0), queue: Optional[Queue] = Queue(scheduler='local', cores=1, jobname='calphy', walltime='23:59:00', queuename='', memory='3GB', commands=[], options=[], modules=[]), tolerance: Optional[Tolerance] = Tolerance(lattice_constant=0.0002, spring_constant=0.1, solid_fraction=0.7, liquid_fraction=0.05, pressure=0.5), uhlenbeck_ford_model: Optional[UFMP] = UFMP(p=50.0, sigma=1.5), melting_temperature: Optional[MeltingTemperature] = MeltingTemperature(guess=None, step=200, attempts=5), element: List[str] = [], n_elements: int = 0, mass: List[float] = [], kernel: int = 0, inputfile: str = '', mode: Optional[str] = None, lattice: str = '', file_format: str = 'lammps-data', pressure: Annotated[list[float], Len(min_length=3, max_length=3)]]] = 0, temperature: Union[float, list[float]] = 0, temperature_high: float = 0.0, melting_cycle: bool = True, pair_style: Optional[List[str]] = None, pair_coeff: Optional[List[str]] = None, potential_file: Optional[str] = None, fix_potential_path: bool = True, reference_phase: str = '', lattice_constant: float = 0, repeat: list[int] = [1, 1, 1], script_mode: bool = False, lammps_executable: Optional[str] = None, mpi_executable: Optional[str] = None, npt: bool = True, n_equilibration_steps: int = 25000, n_switching_steps: Union[int, list[int]] = [50000, 50000], n_print_steps: int = 0, n_iterations: int = 1, equilibration_control: Optional[str] = None, folder_prefix: Optional[str] = None, spring_constants: Optional[List[float]] = None, phase_name: str = '', reference_composition: float = 0.0)[source]#

Bases: BaseModel

berendsen: Optional[Berendsen]#
composition_scaling: Optional[CompositionScaling]#
create_folders()[source]#

Create the necessary folder for calculation

Parameters:

calc (dict) – calculation block

Returns:

folder – create folder

Return type:

string

create_identifier()[source]#

Generate an identifier

Parameters:

calc (dict) – a calculation dict

Returns:

identistring – unique identification string

Return type:

string

element: List[str]#
equilibration_control: Optional[str]#
file_format: str#
fix_paths(potlist)[source]#

Fix paths for potential files to complete ones

fix_potential_path: bool#
folder_prefix: Optional[str]#
get_folder_name()[source]#
inputfile: str#
kernel: int#
lammps_executable: Optional[str]#
lattice: str#
lattice_constant: float#
mass: List[float]#
md: Optional[MD]#
melting_cycle: bool#
melting_temperature: Optional[MeltingTemperature]#
mode: Optional[str]#
model_config: ClassVar[ConfigDict] = {'title': 'Main input class'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None#

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

  • self – The BaseModel instance.

  • context – The context.

monte_carlo: Optional[MonteCarlo]#
mpi_executable: Optional[str]#
n_elements: int#
n_equilibration_steps: int#
n_iterations: int#
n_print_steps: int#
n_switching_steps: Union[int, list[int]]#
nose_hoover: Optional[NoseHoover]#
npt: bool#
pair_coeff: Optional[List[str]]#
pair_style: Optional[List[str]]#
phase_name: str#
potential_file: Optional[str]#
pressure: Annotated[list[float], Len(min_length=3, max_length=3)]]]#
queue: Optional[Queue]#
reference_composition: float#
reference_phase: str#
repeat: list[int]#
property savefile#
script_mode: bool#
spring_constants: Optional[List[float]]#
temperature: Union[float, list[float]]#
temperature_high: float#
tolerance: Optional[Tolerance]#
uhlenbeck_ford_model: Optional[UFMP]#
class calphy.input.CompositionScaling(*, output_chemical_composition: dict = {}, restrictions: List[str] = [])[source]#

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {'title': 'Composition scaling input options'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None#

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

  • self – The BaseModel instance.

  • context – The context.

output_chemical_composition: dict#
restrictions: List[str]#
class calphy.input.MD(*, timestep: float = 0.001, n_small_steps: int = 10000, n_every_steps: int = 10, n_repeat_steps: int = 10, n_cycles: int = 100, thermostat_damping: Union[float, list[float]] = 0.1, barostat_damping: Union[float, list[float]] = 0.1, cmdargs: str = '', init_commands: List = [])[source]#

Bases: BaseModel

barostat_damping: Union[float, list[float]]#
cmdargs: str#
init_commands: List#
model_config: ClassVar[ConfigDict] = {'title': 'MD specific input options'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_cycles: int#
n_every_steps: int#
n_repeat_steps: int#
n_small_steps: int#
thermostat_damping: Union[float, list[float]]#
timestep: float#
class calphy.input.MeltingTemperature(*, guess: Optional[float] = None, step: int = 200, attempts: int = 5)[source]#

Bases: BaseModel

attempts: int#
guess: Optional[float]#
model_config: ClassVar[ConfigDict] = {'title': 'Input options for melting temperature mode'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

step: int#
class calphy.input.MonteCarlo(*, n_steps: int = 1, n_swaps: int = 0, reverse_swap: bool = True, swap_types: list[int] = [1, 2])[source]#

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {'title': 'Options for Monte Carlo moves during particle swap moves'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_steps: int#
n_swaps: int#
reverse_swap: bool#
swap_types: list[int]#
class calphy.input.NoseHoover(*, thermostat_damping: float = 0.1, barostat_damping: float = 0.1)[source]#

Bases: BaseModel

barostat_damping: float#
model_config: ClassVar[ConfigDict] = {'title': 'Specific input options for Nose-Hoover thermostat'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

thermostat_damping: float#
class calphy.input.Queue(*, scheduler: str = 'local', cores: int = 1, jobname: str = 'calphy', walltime: str = '23:59:00', queuename: str = '', memory: str = '3GB', commands: List = [], options: List = [], modules: List = [])[source]#

Bases: BaseModel

commands: List#
cores: int#
jobname: str#
memory: str#
model_config: ClassVar[ConfigDict] = {'title': 'Options for configuring queue'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

modules: List#
options: List#
queuename: str#
scheduler: str#
walltime: str#
class calphy.input.Tolerance(*, lattice_constant: float = 0.0002, spring_constant: float = 0.1, solid_fraction: float = 0.7, liquid_fraction: float = 0.05, pressure: float = 0.5)[source]#

Bases: BaseModel

lattice_constant: float#
liquid_fraction: float#
model_config: ClassVar[ConfigDict] = {'title': 'Tolerance settings for convergence'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pressure: float#
solid_fraction: float#
spring_constant: float#
class calphy.input.UFMP(*, p: float = 50.0, sigma: float = 1.5)[source]#

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {'title': 'UFM potential input options'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

p: float#
sigma: float#
calphy.input.generate_metadata()[source]#
calphy.input.load_job(filename)[source]#
calphy.input.read_inputfile(file)[source]#
calphy.input.save_job(job)[source]#
calphy.input.to_list(v: Any) → List[Any][source]#

calphy.integrators module#

calphy: a Python library and command line interface for automated free energy calculations.

Copyright 2021 (c) Sarath Menon^1, Yury Lysogorskiy^2, Ralf Drautz^2 ^1: Max Planck Institut für Eisenforschung, Dusseldorf, Germany ^2: Ruhr-University Bochum, Bochum, Germany

calphy is published and distributed under the Academic Software License v1.0 (ASL). calphy is distributed in the hope that it will be useful for non-commercial academic research, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. calphy API is published and distributed under the BSD 3-Clause “New” or “Revised” License See the LICENSE FILE for more details.

More information about the program can be found in: Menon, Sarath, Yury Lysogorskiy, Jutta Rogal, and Ralf Drautz. “Automated Free Energy Calculation from Atomistic Simulations.” Physical Review Materials 5(10), 2021 DOI: 10.1103/PhysRevMaterials.5.103801

For more information contact: sarath.menon@ruhr-uni-bochum.de/yury.lysogorskiy@icams.rub.de

calphy.integrators.calculate_entropy_mix(conc)[source]#

Calculate the entropy of mixing

Parameters:

conc (float) – concentration

Returns:

s – entropy

Return type:

float

calphy.integrators.calculate_fe_impurity(temp, natoms, fepure, feimpure)[source]#

Calculate energy change of mixing, imput energies are in eV/atom

Parameters:

  • temp (float) – temperature

  • natoms (int) – number of atoms

  • fepure (float) – free energy of pure phase

  • feimpure (float) – free energy of impure phase

Returns:

dg – entropy of mixing

Return type:

float

calphy.integrators.calculate_fe_mix(temp, fepure, feimpure, concs, natoms=4000)[source]#

Calculate energy of mixing

Parameters:

  • temp (float) – temperature

  • fepure (float) – free energy of the pure phase

  • feimpure (float) – energy due to impurity

  • concs (list of floats) – concentration array

  • natoms (int) – number of atoms

Returns:

fes – free energy with concentration

Return type:

list of floats

calphy.integrators.fe(x, coef, sum_spline, index)[source]#

Fe inbuilt method

calphy.integrators.find_fe(p, x)[source]#

Find free energy of UF system

Parameters:

  • x (float) – x value of system

  • coef (list of floats) – Coefficients of system

Returns:

fe – free energy of UF system

Return type:

float

calphy.integrators.find_w(mainfolder, calc, full=False, solid=True, composition_integration=False)[source]#

Integrate the irreversible work and dissipation for independent simulations

Parameters:

  • mainfolder (string) – main simulation folder

  • nsims (int, optional) – number of independent simulations, default 5

  • full (bool, optional) – If True return error values, default False

  • usecols (tuple, optional) – Columns to read in from data file. Default (0, 1)

Returns:

  • ws (float) – average irreversible work

  • qs (float) – average energy dissipation, only returned if full is True

  • err (float) – Error in free energy, only returned if full is True

calphy.integrators.get_einstein_crystal_fe(calc, vol, k, cm_correction=True, return_contributions=False)[source]#

Get the free energy of einstein crystal

Parameters:

  • calc (Calculation object) – contains all input parameters

  • vol (float) – converged volume per atom

  • k (spring constant, float) – units - eV/Angstrom^2

  • cm_correction (bool, optional, default - True) – add the centre of mass correction to free energy

  • return_contributions (bool, optional, default - True) – If True, return individual contributions to the reference free energy.

Returns:

  • F_tot (float) – total free energy of reference crystal

  • F_e (float) – Free energy of Einstein crystal without centre of mass correction. Only if return_contributions is True.

  • F_cm (float) – centre of mass correction. Only if return_contributions is True.

Notes

The equations for free energy of Einstein crystal and centre of mass correction are from https://doi.org/10.1063/5.0044833.

calphy.integrators.get_ideal_gas_fe(temp, rho, natoms, mass, concentration)[source]#

Get the free energy of an single/binary ideal gas

Parameters:

  • temp (temperature, float) – the reference temperature in K

  • rho (number density, float) – units - no of atoms/ angstrom^3

  • natoms (int) – total number of atoms

  • mass (atomic mass, float) – units - g/mol

  • xa (concentration of species a, float, optional) – default 1

  • xb (concentration of species b, float, optional) – default 0

Returns:

fe – free energy/atom of ideal gas system

Return type:

float

calphy.integrators.get_uhlenbeck_ford_fe(temp, rho, p, sigma)[source]#

Get the excess free energy of Uhlenbeck-Ford model

Parameters:

  • temp (temperature, float) – units - K

  • rho (density, float) – units - no of atoms/ angstrom^3

  • p (uf scale, float) –

  • sigma (uf length scale, float) –

Returns:

fe – excess free energy/atom of uf system

Return type:

float

calphy.integrators.integrate_dcc(folder1, folder2, nsims=1, scale_energy=True, full=False, stdscale=0.25, fit_order=None)[source]#

Integrate Dynamic Clausius-Clapeyron equation

Parameters:

  • folder1 (string) – Calculation folder for calculation of the first phase

  • folder2 (string) – Calculation folder for calculation of the second phase

  • nsims (int) – Number of iterations, default 1

  • full (bool) – If True, return error, default False

  • stdscale (float) – Function used to smooth the integrand. If a value is provided, values in the greater than stdscale*std_dev and less than -stdscale*std_dev are identified as steps/peaks and smoothened. Default 0.25

  • fit_order (None) – If specified, a final fitting is done to remove kinks in the values Optional, default None.

calphy.integrators.integrate_mass(flambda, ref_mass, target_masses, target_counts, temperature, natoms)[source]#
calphy.integrators.integrate_path(calc, fwdfilename, bkdfilename, solid=True, composition_integration=False)[source]#

Get a filename with columns du and dlambda and integrate

Parameters:

  • fwdfilename (string) – name of fwd integration file

  • bkdfilename (string) – name of bkd integration file

  • usecols (list) – column numbers to be used from input file

Returns:

  • w (float) – irreversible work in switching the system

  • q (float) – heat dissipation during switching of system

calphy.integrators.integrate_ps(simfolder, f0, natoms, pi, pf, nsims=1, return_values=False)[source]#

Carry out the reversible scaling integration

Parameters:

  • simfolder (string) – main simulation folder

  • f0 (float) – initial free energy for integration

  • nsims (int, optional) – number of independent switching

Return type:

None

Notes

Writes the output in a file pressure_sweep.dat

calphy.integrators.integrate_rs(simfolder, f0, t, natoms, p=0, nsims=5, scale_energy=False, return_values=False)[source]#

Carry out the reversible scaling integration

Parameters:

  • simfolder (string) – main simulation folder

  • f0 (float) – initial free energy for integration

  • t (float) – initial temperature

  • nsims (int, optional) – number of independent switching

  • scale_energy (bool, optional) – if True, scale energy with switching parameter

Return type:

None

Notes

Writes the output in a file reversible_scaling.dat

calphy.integrators.press(x, coef)[source]#

Find pressure of system

Parameters:

  • x (float) – x value for UF system

  • coef (list of floats) – coefficients

Returns:

result – result pressure

Return type:

float, optional

calphy.integrators.remove_peaks(w, stdscale)[source]#
calphy.integrators.remove_steps(w, stdscale)[source]#

calphy.kernel module#

calphy.lattice module#

calphy.liquid module#

calphy.queuekernel module#

calphy.scheduler module#

calphy.solid module#

calphy.splines module#

calphy: a Python library and command line interface for automated free energy calculations.

Copyright 2021 (c) Sarath Menon^1, Yury Lysogorskiy^2, Ralf Drautz^2 ^1: Max Planck Institut für Eisenforschung, Dusseldorf, Germany ^2: Ruhr-University Bochum, Bochum, Germany

calphy is published and distributed under the Academic Software License v1.0 (ASL). calphy is distributed in the hope that it will be useful for non-commercial academic research, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. calphy API is published and distributed under the BSD 3-Clause “New” or “Revised” License See the LICENSE FILE for more details.

More information about the program can be found in: Menon, Sarath, Yury Lysogorskiy, Jutta Rogal, and Ralf Drautz. “Automated Free Energy Calculation from Atomistic Simulations.” Physical Review Materials 5(10), 2021 DOI: 10.1103/PhysRevMaterials.5.103801

For more information contact: sarath.menon@ruhr-uni-bochum.de/yury.lysogorskiy@icams.rub.de

The splines are from:

# Supplemental Material for The Uhlenbeck-Ford model: Exact virial coefficients and application as a reference system in fluid-phase free-energy calculations” # Authors: Rodolfo Paula Leite(1), Rodrigo Freitas(2), Rodolfo Azevedo(3), and Maurice de Koning(1) # 1 - Instituto de Física “Gleb Wataghin”, Universidade Estadual de Campinas, UNICAMP, 13083-859, Campinas, São Paulo, Brazil # 2 - Department of Materials Science and Engineering, University of California, Berkeley, CA 94720, U.S.A. # 3 - Instituto de Computação, Universidade Estadual de Campinas, UNICAMP, 13083-852, Campinas, São Paulo, Brazil

Module contents#