`calphy` input keywords#

The inputfile is yaml formatted. In this section the possible keys in the inputfile is discussed. The table below gives a quick overview of all available keywords in calphy.

A sample file looks like this:

calculations:
- key1: value1
  key2: value2
  md:
    key1: value1
    key2: value2

`calculations`#

`calculations` block#

All other options are specified in blocks. The main block is the calculations block. This block can list all the calculations that calphy should perform and it can have more than one entry. A sample calculation block is shown below.

calculations:
- mode: ts 
  temperature: [1300, 1400]
  pressure: [0]
  lattice: [fcc]
  repeat: [2, 2, 2]
  reference_phase: solid
  n_iterations: 1

The various keys are-

`element`#

type: string/list of strings
default: None
example:

element: 'Cu'
element: ['Cu', 'Zr']

Chemical symbol(s) of the element(s) in the simulation.

`mass`#

type: float/list of floats
default: 1.0
example:

mass: 63.546
mass: [63.546, 91.224]

Mass of the element(s) in the simulation. It should follow the same order as that of element, and should be of the same length.

`mode`#

type: string, fe or ts or alchemy or melting_temperature or tscale or pscale or composition_scaling
default: None
example:

mode: fe
mode: ts

Calculation mode. A small description of the different modes are given below.

fe performs a direct free energy calculation
ts performs a direct free energy calculation followed by reversible scaling to find temperature dependence.
alchemy is used for switching between two different interatomic potentials, or for integration over concentration.
melting_temperature can be used for automated calculation of melting temperature.
tscale is used for similar purpose as ts, but scales the temperature directly.
pscale calculates the free energy as a function of the pressure.
composition_scaling performs integration over composition.

`temperature`#

type: float or list of floats
default: None
example:

temperature: 1200
temperature: [1200, 1300]

Temperatures for the simulation in Kelvin. The way temperature is used in calphy depends on the selected mode of calculation.

mode ts or tscale, a temperature sweep is carried out. In that case, only two values of temperature should be specified.
mode melting_temperature, if provided it is used as an initial guess temperature. If not, the experimental melting temperature is used as a guess value.
all other modes, a calculation is launched for each temperature on the list.

`pressure`#

type: None or float or list of floats
default: 0
example:

pressure: None
pressure: 0
pressure: [0,0,0]
pressure: [0, 10000]
pressure: [[1,1,1], [1000, 1000, 1000]]

Pressure for the simulation in bars. Depending on the pressure input, other options are automatically set. These options are iso and fix_lattice. iso decides if the barostat relaxes the system isotropically or anisotropically. fix_lattice does not relax the lattice at all. A table consistning of possible pressure input options and their effect is below:

`pressure` input options
Type	Example	`iso`	`fix_lattice`	`mode`	Restrictions
`None`	`pressure: None`	True	True	`fe`, `alchemy`	None
scalar	`pressure: 100`	True	False	all except `pscale`	None
`(1,)`	`pressure: [100]`	True	False	all except `pscale`	None
`(2,)`	`pressure: [100, 200]`	True	False	`pscale`	None
`(3,)`	`pressure: [100, 100, 100]`	False	False	all except `pscale`	px=py=pz
`(1,3)`	`pressure: [[100, 100, 100]]`	False	False	all except `pscale`	px=py=pz
`(2,3)`	`pressure: [[100, 100, 100], [200, 200, 200]]`	False	False	`pscale`	px=py=pz

`lattice`#

type: string or list of strings
default: None
example:

lattice: FCC
lattice: [FCC, LQD]
lattice: [FCC, conf.data]

Lattice to be used for the calculations. The lattice option can use either LAMMPS for creation of input structure or use an input file in the LAMMPS data format. To use LAMMPS to create the structure, the keyword specified should be from the following: bcc, fcc, hcp, diamond, and sc. Lattice creation can only be used for single species. The preferred method is to provide a LAMMPS data file can be specified which contains the configuration.

`reference_phase`#

type: string or list of strings
default: None
example:

state: solid
state: [solid, liquid]

The protocol to be used for the calculation. The reference_phase input is closely related to the lattice command. It should be of the same length as the lattice input. For each of the lattice specified, reference_phase command specifies which reference state to use.

`lattice_constant`#

type: float or list of floats
default: experimental lattice constant
example:

lattice_constant: 3.68
lattice_constant: [3.68, 5.43]

Lattice constant for input structures. Lattice constant values to be used for initial structure creation. Only required if the structure lattice is specified. If not specified, experimental lattice constant is used.

`repeat`#

type: list of ints of length 3
default: [1, 1, 1]
example:

repeat: [3,3,3]

repeat command specifies the number of unit cells required in each x, y and z directions. This is only used if structure lattice is specified.

`n_iterations`#

type: int
default: 1
example:

n_iterations: 3

The number of backward and forward integrations to be carried out in all modes. If more than one integration cycle is used, the errors can also be evaluated.

`temperature_high`#

type: float
default: 2*temperature
example:

temperature_high: 1600

The temperature used to melt a solid structure to create a liquid. If reference_phase is chosen as liquid, calphy performs a melting cycle to create an equilibrated liquid structure. calphy starts from the given input structure, and heats it using 2 times the highest temperature provided in the temperature option. If the structure is not melted, the temperature is increased progressively. temperature_high keyword can be used to set the temperature to overheat the structure and melt it.

`npt`#

type: bool
default: True \
example:

npt: True

npt determines if calculations are carried out in the NPT ensemble. This option is used with modes alchemy, and ts. The effect is described below:

for mode ts: the reversible scaling approach is carried out in NPT if npt is True, otherwise the NVT ensemble is used.
for mode alchemy: If npt is False, the NVT ensemble is used, meaning that the calculated work during alchemical transformation is calculated on the equilibrated volume of the first pair style.

`pair_style`#

type: string or list of strings
default: None
example:

pair_style: eam/alloy
pair_style: [eam/alloy, eam/alloy]
pair_style: eam/fs
pair_style: pace

The pair style command for LAMMPS. All styles supported in LAMMPS can be used with calphy. Except for mode alchemy, only the first value in the list will be used. For mode alchemy, there should be two pair styles specified, and the alchemical transformation is carried out between the two.

`pair_coeff`#

type: string or list of strings
default: None
example:

pair_coeff: "* * Cu_EAM/Cu01.eam.alloy Cu"
pair_coeff: ["* * Cu_EAM/Cu01.eam.alloy Cu", "* * Cu_EAM/Cu02.eam.alloy Cu"]
pair_coeff: "* * CuZr_EAM/CuZr.eam.fs Cu Zr"

The pair coeff command for LAMMPS. It should be the same length as pair_style. Except for mode alchemy, only the first value in the list will be used. For mode alchemy, there should be two pair styles specified, and the alchemical transformation is carried out between the two.

`potential_file`#

type: string
default: None
example:

pair_coeff: "/home/calc/potential.inp"

If specified, the pair_style and pair_coeff commands are not used, but rather the potential is read in from the provided input file using include command in LAMMPS. This allows the use of more complex or multiple potential files. Due to the hybrid/scaled styles employed in calphy, this option only works with mode fe and reference_phase solid.

`n_equilibration_steps`#

type: int
default: 25000
example:

n_equilibration_steps: 10000

The number of time steps for equilibrating the system.

`n_switching_steps`#

type: int or list of ints
default: 50000
example:

n_switching_steps: 10000
n_switching_steps: [10000, 20000]

The number of switching steps. If a list of two integers is provided, the first value is used for mode fe while the second value will be used for all other modes.

`n_print_steps`#

type: int
default: 0
example:

n_print_steps: 100

Record MD trajectory during temperature sweep runs in the given interval of time steps. Default 0, trajectories are never recorded.

`spring_constants`#

type: list of floats
default: None
example:

spring_constants: 1.2
spring_constants: [1.2, 1.3]

Spring constants for Einstein crystal. If specified, the automatic calculation is not performed. Should be equal to the number of species in the system.

`equilibration_control`#

type: str
default: None
example:

equilibration_control: berendsen
equilibration_control: nose-hoover

The barostat and thermostat combination to be used for the equilibration stage. By default, Berendsen will be used for solid reference and Nose-Hoover will be used for liquid. The damping parameters can be tuned using the nose_hoover block or the berendsen block. Used only for equilibration stage.

`melting_cycle`#

type: bool
default: True
example:

melting_cycle: True
melting_cycle: False

If True, a melting cycle is carried out to melt the given input structure. Only used if the reference_phase is "liquid".

`folder_prefix`#

type: string
default: None
example:

folder_prefix: set1

Prefix string to be added to folder names for calculation. Folders for calculations in calphy are named as mode-lattice-temperature-pressure. Therefore, if more than one calculation is run with the same parameters, they will be overwritten. To prevent this, folder_prefix can be used. If folder_prefix is provided, the folders will be named as folder_prefix-mode-lattice-temperature-pressure.

`md` block#

MD block consists of the various options required for the MD runs. An example block is given below and the keys are discussed.

md:
  timestep: 0.001
  thermostat_damping: 0.1
  barostat_damping: 0.1

`timestep`#

type: float
default: 0.001
example:

timestep: 0.001

The timestep for MD in picoseconds.

`thermostat_damping`#

type: float
default: 0.1
example:

thermostat_damping: 0.1

The thermostat damping constant for MD. For damping during equilibration stage see equilibration_control.

`barostat_damping`#

type: float
default: 0.1
example:

barostat_damping: 0.1

Pressure damping for MD. For damping during equilibration stage see equilibration_control.

`n_small_steps`#

type: int
default: 10000
example:

n_small_steps: 10000

The number of time steps for equilibration cycles to calculate spring constant and average volume.

`n_every_steps`#

type: int
default: 10
example:

n_every_steps: 100

Keywords to tune how often average values are recorded in LAMMPS. Please see here for more details.

`n_repeat_steps`#

type: int
default: 10
example:

n_repeat_steps: 10

Keywords to tune how often average values are recorded in LAMMPS. Please see here for more details.

`n_cycles`#

type: int
default: 100
example:

n_cycles: 100

Number of cycles to try converging the pressure of the system. If the pressure is not converged after n_cycles, an error will be raised. In each n_cycle, n_small_steps MD steps will be run.

`init_commands`#

type: list of strings
default: None
example:

init_commands:
  - timestep 0.002
  - atom_style charge
  - neighbor 0.6 bin

Provides the possibility to replace or add initial commands when the LAMMPS object is initialised. If the command is already used in calphy, for example timestep or atom_style they will be replaced. If it is a new command, it will be added. This commands receive higher priority than the ones that already exist. For examples if you provide timestep: 0.002 in the md block, and timestep 0.004 in init_commands, the timestep used would be 0.004.

`queue` block#

This block consists of the options for specifying the scheduler for carrying out the calculations. An example block is given below-

queue:
  scheduler: local
  cores: 2
  jobname: ti
  walltime: "23:50:00"
  queuename: shorttime
  memory: 3GB
  modules:
    - anaconda/4
  commands:
    - conda activate env

`scheduler`#

type: string
default: local
example:

scheduler: slurm

The scheduler to be used for the job. Can be local, slurm or sge. The code has been tested only on local and slurm.

`cores`#

type: int
default: 1
example:

cores: 4

The number of cores to be used for the job.

`jobname`#

type: string
default: calphy
example:

jobname: cu

Name of the job. Not used for local.

`walltime`#

type: string
example:

walltime: "23:50:00"

Walltime for the job. Not used for local.

`queuename`#

type: string
example:

queuename: "shorttime"

Name of the queue. Not used for local.

`memory`#

type: string
example:

memory: 3GB

Memory to be used per core. Not used for local.

`commands`#

type: list of strings
example:

command:
 - source .bashrc
 - conda activate ace
 - module load lammps

Command that will be run before the actual calculations are carried out. This section can be used to specify commands that need to be run before the actual calculation. If the calculations are run within a conda environment, the activate command for conda should be specified here. If additional modules need to be loaded, that can also be specified here.

`modules`#

type: list of strings
example:

modules:
  - anaconda
  - lammps

List of modules to be loaded before running the calculations. The given module names will be prefixed by module load.

`options`#

type: string
example:

options:
  - memory: 3GB

Extra options to be added to the submission script.

`tolerance` block#

This block helps to tune the internal convergence parameters that calphy uses. Generally, tuning these parameters are not required.

tolerance:
   spring_constant: 0.01
   solid_fraction: 0.7
   liquid_fraction: 0.05
   pressure: 0.5

`spring_constant`#

type: float
default: 0.01
example:

spring_constant: 0.01

tolerance for the convergence of spring constant calculation.

`solid_fraction`#

type: float
default: 0.7
example:

solid_fraction: 0.7

The minimum amount of solid particles that should be there in solid.

`liquid_fraction`#

type: float
default: 0.05
example:

liquid_fraction: 0.05

Maximum fraction of solid atoms allowed in liquid after melting.

`pressure`#

type: float
default: 0.5
example:

pressure: 0.5

tolerance for the convergence of pressure.

`melting_temperature` block#

This block contains keywords that are used only for the mode melting_temperature.

melting_temperature:
   step: 200
   attempts: 5

`step`#

type: int
example:

step: 200

Temperature interval for search of melting temperature. Only used if mode is melting_temperature.

`attempts`#

type: int
example:

attempts: 5

The number of maximum attempts to try find the melting temperature in a automated manner. Only used if mode is melting_temperature.

`composition_scaling` block#

This block contains keywords that are used only for the mode composition_scaling.

composition_scaling:
  output_chemical_composition:
     - Cu: 513
     - Zr: 511

`output_chemical_composition`#

type: list
example:

output_chemical_composition:
   - Cu: 513
   - Zr: 511

The output chemical composition in number of atoms. The total number of atoms should be equal to the input provided.

`nose_hoover` block#

This block contains keywords that are used only for the equilibration stage if equilibration_control is nose_hoover.

nose_hoover:
   thermostat_damping: 0.1
   barostat_damping: 0.1

`thermostat_damping`#

type: float
default: 0.1
example:

thermostat_damping: 0.1

The thermostat damping constant for equilibration MD.

`barostat_damping`#

type: float
default: 0.1
example:

barostat_damping: 0.1

Pressure damping for equilibration MD.

`berendsen` block#

This block contains keywords that are used only for the equilibration stage if equilibration_control is berendsen.

berendsen:
   thermostat_damping: 100.0
   barostat_damping: 100.0

`thermostat_damping`#

type: float
default: 100.0
example:

thermostat_damping: 100.0 

The thermostat damping constant for equilibration MD.

`barostat_damping`#

type: float
default: 100.0
example:

barostat_damping: 100.0  

Pressure damping for equilibration MD.

calphy input keywords#

calculations#

md#

queue#

tolerance#

melting_temperature#

composition_scaling#

nose_hoover#

berendsen#

calculations block#

element#

mass#

mode#

temperature#

pressure#

lattice#

reference_phase#

lattice_constant#

repeat#

n_iterations#

temperature_high#

npt#

pair_style#

pair_coeff#

potential_file#

n_equilibration_steps#

n_switching_steps#

n_print_steps#

spring_constants#

equilibration_control#

melting_cycle#

folder_prefix#

md block#

timestep#

thermostat_damping#

barostat_damping#

n_small_steps#

n_every_steps#

n_repeat_steps#

n_cycles#

init_commands#

queue block#

scheduler#

cores#

jobname#

walltime#

queuename#

memory#

commands#

modules#

options#

tolerance block#

spring_constant#

solid_fraction#

liquid_fraction#

pressure#

melting_temperature block#

step#

attempts#

composition_scaling block#

output_chemical_composition#

nose_hoover block#

thermostat_damping#

barostat_damping#

berendsen block#

thermostat_damping#

barostat_damping#

`calphy` input keywords#

`calculations`#

`md`#

`queue`#

`tolerance`#

`melting_temperature`#

`composition_scaling`#

`nose_hoover`#

`berendsen`#

`calculations` block#

`element`#

`mass`#

`mode`#

`temperature`#

`pressure`#

`lattice`#

`reference_phase`#

`lattice_constant`#

`repeat`#

`n_iterations`#

`temperature_high`#

`npt`#

`pair_style`#

`pair_coeff`#

`potential_file`#

`n_equilibration_steps`#

`n_switching_steps`#

`n_print_steps`#

`spring_constants`#

`equilibration_control`#

`melting_cycle`#

`folder_prefix`#

`md` block#

`timestep`#

`thermostat_damping`#

`barostat_damping`#

`n_small_steps`#

`n_every_steps`#

`n_repeat_steps`#

`n_cycles`#

`init_commands`#

`queue` block#

`scheduler`#

`cores`#

`jobname`#

`walltime`#

`queuename`#

`memory`#

`commands`#

`modules`#

`options`#

`tolerance` block#

`spring_constant`#

`solid_fraction`#

`liquid_fraction`#

`pressure`#

`melting_temperature` block#

`step`#

`attempts`#

`composition_scaling` block#

`output_chemical_composition`#

`nose_hoover` block#

`thermostat_damping`#

`barostat_damping`#

`berendsen` block#

`thermostat_damping`#

`barostat_damping`#