From c92df79d8512806c26a8039757568500b376696f Mon Sep 17 00:00:00 2001 From: Sarath Menon Date: Tue, 5 Apr 2022 14:35:06 +0200 Subject: [PATCH] update documentation --- docs/source/documentation/inputfile.md | 384 +++++++++++++++---------- 1 file changed, 240 insertions(+), 144 deletions(-) diff --git a/docs/source/documentation/inputfile.md b/docs/source/documentation/inputfile.md index 2d984a2..a0245f8 100644 --- a/docs/source/documentation/inputfile.md +++ b/docs/source/documentation/inputfile.md @@ -11,13 +11,12 @@ The inputfile is `yaml` formatted. In this section the possible keys in the inpu | :-: | :-: | :-: | :-: | :-: | | [mode](#mode) | [lattice](#lattice) | [reference_phase](#reference_phase) | [temperature](#temperature) | [pressure](#pressure) | | [temperature_high](#temperature_high) | [lattice_constant](#lattice_constant) | [repeat](#repeat) | [n_iterations](#n_iterations) | [n_switching_steps](#n_switching_steps) | -| [n_equilibration_steps](#n_equilibration_steps) | [pair_style](#pair_style) | [pair_coeff](#pair_coeff) | +| [n_equilibration_steps](#n_equilibration_steps) | [pair_style](#pair_style) | [pair_coeff](#pair_coeff) | [n_print_steps](#n_print_steps) | | `md` block | | | | | | :-: | :-: | :-: | :-: | :-: | | [timestep](#timestep) | [n_small_steps](#n_small_steps) | [n_every_steps](#n_every_steps) | [n_repeat_steps](#n_repeat_steps) | [n_cycles](#n_cycles) | -| [thermostat_damping](#thermostat_damping) | [barostat_damping](#barostat_damping) | [te](#te) | -| [ts](#ts) [traj_interval](#traj_interval) | +| [thermostat_damping](#thermostat_damping) | [barostat_damping](#barostat_damping) | | `queue` block | | | | | | :-: | :-: | :-: | :-: | :-: | @@ -30,7 +29,10 @@ The inputfile is `yaml` formatted. In this section the possible keys in the inpu | `melting_temperature` block | | | | | | :-: | :-: | :-: | :-: | :-: | -| [guess](#guess) | [step](#step) | [attempts](#attempts) | +| [step](#step) | [attempts](#attempts) | + +--- +--- ## main keys @@ -61,6 +63,7 @@ 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. +--- --- ## `calculations` block @@ -105,36 +108,53 @@ Calculation mode. A small description of the different modes are given below. #### `temperature` -_type_: float or list of floats +_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. If the `mode` is `fe` or `alchemy`, a calculation is launched for each temperature on the list. If the mode is `ts` or `mts`, a temperature sweep is carried out. In that case, only two values of temperature should be specified. +Temperatures for the simulation in Kelvin. The way temperature is used in `calphy` depends on the selected mode of calculation. +- mode `ts` or `tscale` or `mts`, 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_: list of floats +_type_: None or float or list of floats +_default_: None _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. Calculations are performed at each pressure specified for all modes except `pscale`. For each pressure specified in the list, one calculation will be started. For example, in the following combination- +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: -``` -mode: fe -temperature: [1000, 1200] -pressure: [0, 10000] -``` +| `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 | -A total of 2 temperatures * 2 pressures, 4 calculations will be started. If the mode is `ts` for the same configuration above, 2 calculations will be started. However if mode is `pscale`, 2 temperatures*1 pressure range, total of two calculations will be started. +--- #### `lattice` -_type_: string of list of strings +_type_: string or list of strings +_default_: None _example_: ``` lattice: FCC @@ -143,21 +163,27 @@ 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`, `DIA`, `SC` and `LQD`. LAMMPS lattice creation can **only be used for single species**. If `LQD` is specified, a solid structure will be first created and melted within the MD run. Alternatively, a LAMMPS data file can be specified which contains the configuration. - -#### `state` + +--- + +#### `reference_phase` -_type_: string of list of strings +_type_: string or list of strings +_default_: None _example_: ``` state: solid state: [solid, liquid] ``` -The protocol to be used for the calculation. The `state` 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, `state` command specifies which reference state to use. +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_: list of floats +_type_: float or list of floats +_default_: Experimental lattice constant _example_: ``` lattice_constant: 3.68 @@ -166,31 +192,12 @@ 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 is created through LAMMPS. If not specified, the experimental lattice constant will be used. -#### `iso` - -_type_: list of bools -_example_: -``` -iso: True -iso: [True, False] -``` - -Specify whether the barostat will control the pressure isotropically or anisotropically. - -#### `fix_lattice` - -_type_: list of bools -_example_: -``` -fix_lattice: True -fix_lattice: [True, False] -``` - -This option can be used to skip the equilibriation cycle. For example, if you need to calculate the free energy of a strained lattice, this option can be set to True. Then, either a data file with the strained structure can be provided, or `lattice_constant` option can be used to specify a strained lattice constant. +--- #### `repeat` -_type_: list of ints of length 3 +_type_: list of ints of length 3 +_default_: [1, 1, 1] _example_: ``` repeat: [3,3,3] @@ -198,51 +205,49 @@ 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 `lattice` command uses one of the LAMMPS structure keywords. -#### `nsims` +--- + +#### `n_iterations` _type_: int _example_: ``` -nsims: 3 +n_iterations: 3 ``` -The number of backward and forward integrations to be carried out in the non-equilibrium method. If more than one integration cycle is used, the errors can also be evaluated. - -#### `thigh` +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. -_type_: float +--- + +#### `temperature_high` + +_type_: float +_default_: 2*temperature _example_: ``` -thigh: 1600 +temperature_high: 1600 ``` -The temperature used to melt a solid structure to create a liquid. If `state` 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. `thigh` keyword can be used to set the temperature to overheat the structure and melt it. +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 +_type_: bool +_default_: True _example_: ``` npt: True ``` -`npt` determines if alchemical transformations are carried out in the NPT ensemble. If False, the calculations are carried out in the NVT ensemble. This means that the calculated work during alchemical transformation is calculated on the equilibrated volume of the first pair style. Only used for mode `alchemy`. +`npt` determines if calculations are carried out in the NPT ensemble. This option is used with modes `alchemy`, `ts` and `mts`. The effect is described below: +- for mode `ts` and `mts`: the reversible scaling approach is carried out in NPT if `npt` is True, otherwise the `NVT` ensemble is used. -## `md` block +- 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. -MD block consists of the various options required for the MD runs. An example block is given below and the keys are discussed. - -``` -md: - pair_style: eam/alloy - pair_coeff: "* * Cu_EAM/Cu01.eam.alloy Cu" - timestep: 0.001 - tdamp: 0.1 - pdamp: 0.1 - te: 10000 - ts: 15000 -``` +--- #### `pair_style` @@ -250,153 +255,175 @@ _type_: string or list of strings _example_: ``` pair_style: eam/alloy +pair_style: [eam/alloy, eam/alloy] pair_style: eam/fs pair_style: pace ``` The [pair style](https://lammps.sandia.gov/doc/pair_style.html) 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 +_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](https://lammps.sandia.gov/doc/pair_coeff.html) 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. -#### `timestep` +--- -_type_: float +#### `n_equilibration_steps` + +_type_: int +_default_: 25000 _example_: ``` -timestep: 0.001 +n_equilibration_steps: 10000 ``` -The timestep for MD in picoseconds. +--- -#### `tdamp` +The number of time steps for equilibrating the system. -_type_: float +#### `n_switching_steps` + +_type_: int or list of ints +_default_: 50000 _example_: ``` -tdamp: 0.1 +n_switching_steps: 10000 +n_switching_steps: [10000, 20000] ``` -The thermostat damping constant for MD. A [Langevin thermostat](https://docs.lammps.org/fix_langevin.html) is used for calculations in calphy. +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. -#### `pdamp` +--- -_type_: float +#### `n_print_steps` + +_type_: int +_default_: 0 _example_: ``` -pdamp: 0.1 +n_print_steps: 100 ``` -Pressure damping for MD. A [Parrinello-Rahman](https://docs.lammps.org/fix_nh.html) barostat is used for calculations in calphy. - -#### `te` +Record MD trajectory during temperature sweep runs in the given interval of time steps. Default 0, trajectories are never recorded. -_type_: int -_example_: -``` -te: 10000 -``` +--- +--- -The number of time steps for equilibrating the system. +## `md` block -#### `ts` +MD block consists of the various options required for the MD runs. An example block is given below and the keys are discussed. -_type_: int -_example_: ``` -ts: 10000 +md: + timestep: 0.001 + thermostat_damping: 0.1 + barostat_damping: 0.1 ``` -The number of time steps for switching between the system of interest and reference system. +--- -#### `tguess` +#### `timestep` -_type_: int +_type_: float +_default_: 0.001 _example_: ``` -tguess: 1300 +timestep: 0.001 ``` -An initial starting guess for melting temperature. Only used if mode is `melting_temperature`. +The timestep for MD in picoseconds. + +--- -#### `dtemp` +#### `thermostat_damping` -_type_: int +_type_: float +_default_: 0.1 _example_: ``` -dtemp: 200 +thermostat_damping: 0.1 ``` -Temperature interval for search of melting temperature. Only used if mode is `melting_temperature`. +The thermostat damping constant for MD. + +--- -#### `maxattempts` +#### `barostat_damping` -_type_: int +_type_: float +_default_: 0.1 _example_: ``` -maxattempts: 5 +barostat_damping: 0.1 ``` -The number of maximum attempts to try find the melting temperature in a automated manner. Only used if mode is `melting_temperature`. +Pressure damping for MD. -#### `nsmall` +--- -_type_: int +#### `n_small_steps` + +_type_: int +_default_: 10000 _example_: ``` -nsmall: 10000 +n_small_steps: 10000 ``` The number of time steps for equilibration cycles to calculate spring constant and average volume. - -#### `nevery` -_type_: int -_example_: -``` -nevery: 100 -``` +--- -Keywords to tune how often average values are recorded in LAMMPS. Please see [here](https://docs.lammps.org/fix_ave_time.html) for more details. - -#### `nrepeat` +#### `n_every_steps` -_type_: int +_type_: int +_default_: 10 _example_: ``` -nrepeat: 10 +n_every_steps: 100 ``` Keywords to tune how often average values are recorded in LAMMPS. Please see [here](https://docs.lammps.org/fix_ave_time.html) for more details. -#### `ncycles` +--- -_type_: int +#### `n_repeat_steps` + +_type_: int +_default_: 10 _example_: ``` -ncycles: 100 +n_repeat_steps: 10 ``` -Number of cycles to try converging the pressure of the system. If the pressure is not converged after `ncycles`, an error will be raised. In each `ncycle`, `nsmall` MD steps will be run. +Keywords to tune how often average values are recorded in LAMMPS. Please see [here](https://docs.lammps.org/fix_ave_time.html) for more details. -#### `traj_interval` +--- -_type_: int +#### `n_cycles` + +_type_: int +_default_: 100 _example_: ``` -traj_interval: 100 +n_cycles: 100 ``` -Record MD trajectory during temperature sweep runs in the given interval of time steps. Default 0, trajectories are never recorded. +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. +--- +--- ## `queue` block @@ -416,6 +443,8 @@ queue: - conda activate env ``` +--- + #### `scheduler` _type_: string @@ -426,6 +455,8 @@ 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 @@ -435,7 +466,9 @@ cores: 4 ``` The number of cores to be used for the job. - + +--- + #### `jobname` _type_: string @@ -446,6 +479,8 @@ jobname: cu Name of the job. Not used for `local`. +--- + #### `walltime` _type_: string @@ -455,7 +490,9 @@ walltime: "23:50:00" ``` Walltime for the job. Not used for `local`. - + +--- + #### `queuename` _type_: string @@ -466,6 +503,8 @@ queuename: "shorttime" Name of the queue. Not used for `local`. +--- + #### `memory` _type_: string @@ -476,6 +515,8 @@ memory: 3GB Memory to be used per core. Not used for `local`. +--- + #### `commands` _type_: list of strings @@ -488,7 +529,9 @@ command: ``` 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 @@ -501,6 +544,8 @@ modules: List of modules to be loaded before running the calculations. The given module names will be prefixed by `module load`. +--- + #### `options` _type_: string @@ -512,59 +557,110 @@ options: Extra options to be added to the submission script. -## `conv` block +--- +--- + +## `tolerance` block This block helps to tune the internal convergence parameters that `calphy` uses. Generally, tuning these parameters are not required. ``` -conv: - k_tol: 0.01 - solid_frac: 0.7 - liquid_frac: 0.05 - p_tol: 0.5 +tolerance: + spring_constant: 0.01 + solid_fraction: 0.7 + liquid_fraction: 0.05 + pressure: 0.5 ``` -#### `k_tol` +--- -_type_: float +#### `spring_constant` + +_type_: float +_default_: 0.01 _example_: ``` -ktol: 0.01 +spring_constant: 0.01 ``` tolerance for the convergence of spring constant calculation. -#### `solid_frac` +--- + +#### `solid_fraction` _type_: float +_default_: 0.7 _example_: ``` -solid_frac: 0.7 +solid_fraction: 0.7 ``` The minimum amount of solid particles that should be there in solid. -#### `liquid_frac` +--- + +#### `liquid_fraction` _type_: float +_default_: 0.05 _example_: ``` -liquid_frac: 0.05 +liquid_fraction: 0.05 ``` Maximum fraction of solid atoms allowed in liquid after melting. -#### `p_tol` +--- + +#### `pressure` _type_: float +_default_: 0.5 _example_: ``` -p_tol: 0.5 +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`. + +---