`potable`

input format¶

## [EAM-ADP-Dipole]¶

*Added in: 0.4.0*

Section defining the dipole functions for angular dependent (ADP) EAM models. See ADP Style EAM Models.

Potential forms are defined between pairs of species in the same way as in the [Pair] section:

```
SPECIES_A-SPECIES_B : POTENTIAL_FORM PARM_1 PARAM_2 ... PARAM_N
```

Where:

`SPECIES_A-SPECIESB`

gives the pair of species for which the dipole function is defined. e.g. Al-Cu would define a function for aluminium and copper.`POTENTIAL_FORM PARAM_1 PARAM_2 ... PARAM_N`

defines the potential form in the same way as in the [Pair] section.

## [EAM-ADP-Quadrupole]¶

*Added in: 0.4.0*

Section defining the quadrupole functions for angular dependent (ADP) EAM models. See ADP Style EAM Models.

Potential forms are defined between pairs of species in the same way as in the [Pair] section:

```
SPECIES_A-SPECIES_B : POTENTIAL_FORM PARM_1 PARAM_2 ... PARAM_N
```

Where:

`SPECIES_A-SPECIESB`

gives the pair of species for which the dipole function is defined. e.g. Al-Cu would define a function for aluminium and copper.`POTENTIAL_FORM PARAM_1 PARAM_2 ... PARAM_N`

defines the potential form in the same way as in the [Pair] section.

## [EAM-Density]¶

The density functions for embedded atom models are specified in this section. The input takes different forms depending on whether the standard embedded atom model or Finnis-Sinclair variant are being used.

Both standards have the following general form:

```
INTERACTION : POTENTIAL_FORM PARAM_1 PARAM_2 ... PARAM_N
```

Where:

`POTENTIAL_FORM PARAM_1 ...`

: density functions use the same rules to instantiate potential forms as in the [Pair] section.

`INTERACTION`

specifies the density this potential-form represents:

Standard EAM:standard EAM uses the same function for the density surrounding any central atom of any given species. Consequently in these cases`INTERACTION`

is a single species label. So the density function of aluminium would take the form:[EAM-Density] Al : POTENIAL_FORM ...

Finnis-Sinclair:in this variant of EAM density functions change depending on types of the cental atom and surrounding atom to be embedded. Consequently the following form is used:[EAM-Density] A->B : POTENTIAL_FORM ...

Where

`A`

is the central atom type and`B`

is the type of the embedding atom. To define a density function for the density of nickel being embedded at an aluminium site this would be used:[EAM-Density] Al->Ni : POTENTIAL_FORM ...It should be noted that

`A->B`

and`B->A`

must be specified separately even if the same density function is used for both. If not given null (i.e.`as.zero`

) density functions are implicitly defined for missing interactions.

See also

## [EAM-Embed]¶

Embedding functions for many-body models are defined in this section.

Entries have the following form:

```
SPECIES : POTENTIAL_FORM PARAM_1 PARAM_2 ... PARAM_N
```

Where:

`SPECIES`

is atomic type at which the surrounding electron density will be embedded using the specified potential form.`POTENTIAL_FORM PARAM_1 ...`

: embedding functions instantiate potential forms in the same way as in the [Pair] section.

Note

Embedding functions are tabulated using rho values. The resolution and extent of functions in rho are defined by `drho`

, `nrho`

and `cutoff_rho`

in the [Tabulation] section.

See also

## [Pair]¶

Pair-potentials are defined in this section of the file. See [Pair] section for full description.

See also

See also:

- Potential-forms are parametrised in this section:
List of Potential Forms - reference list of pre-defined potential forms.

Custom functions are defined in the

`[Potential-Form]`

section:- [Potential-Form] section - custom potential-forms are introduced here.
- [Potential-Form] - reference information for
`[Potential-Form]`

section.

**Potential-modifiers are described in thiese sections:**- Potential modifiers - are introduced here.
- List of Potential Modifiers - list of potential-modifiers.

## [Potential-Form]¶

Custom functional forms are defined in this section. See [Potential-Form] section where it is introduced.

See also

- The syntax used by the mathematical expressions defined in the
`[Potential-Form]`

is defined here.

### Python maths functions supported in mathematical expressions¶

The mathematical expressions used in the `[Potential-Form]`

section of `potable`

input allow a subset of functions from the math module to be used. These are accesible via the `pymath.*`

namespace prefix. An example of this is provided here: Formula syntax

The list of functions accessible through `pymath.*`

are below. In general, functions that return multiple values do not appear:

- This function is called slightly differently than in native Python.
- In Python you pass in a single iterable to this function. This expression:
`math.fsum([1,2,3,4])`

would be written`pymath.fsum(1,2,3,4)`

in a`potable`

formula.

## [Tabulation]¶

The section of the input file which defines how a model should be tabulated.

### Fields¶

#### cutoff¶

Item: | `cutoff` |
---|---|

Format: | float |

Description: | Defines upper bound of functions tabulated in terms of separation. This is used in a pair with ns tabulated in terms of separation. This directive is used together with nr (number of rows) or dr (step size) to give the extent and resolution of a tabulated function. |

#### cutoff_rho¶

Item: | `cutoff_rho` |
---|---|

Format: | float |

Description: | Used to define cutoff for functions tabulated in terms of electron density (rho) e.g. for [EAM-Embed] functions. This option defines the upper bound of rho values included in the tabulation of these functions. This directive is used together with nrho or cutoff_rho to define resolution and extent of density functions. |

#### dr¶

Item: | `dr` |
---|---|

Format: | float |

Description: | Defines the step size between rows of functions tabulated in terms of separation. This directive is used together with nr or cutoff to define resolution and extent of these functions. |

#### drho¶

Item: | `drho` |
---|---|

Format: | float |

Description: | Used to define resolution of functions tabulated in terms of electron density (rho) e.g. for [EAM-Embed] functions. This option defines the rho increment for such functions. This directive is used together with nrho or cutoff_rho to define resolution and extent of these functions. |

#### nr¶

Item: | `nr` |
---|---|

Format: | int |

Description: | Defines the number of rows when functions are tabulated in terms of separation. This directive is used either with dr or cutoff to give the range and resolution of the tabulated function. |

#### nrho¶

Item: | `nrho` |
---|---|

Format: | int |

Description: | Used to define cutoff (in conjunction with `drho` ) for functions tabulated in terms of electron density (rho) e.g. for [EAM-Embed] functions. This option defines the number of rho values included in the tabulation of these functions. This directive is used together with nrho or cutoff_rho to define resolution and extent of density functions. |

#### target¶

Item: | `target` |
---|---|

Format: | str |

Valid Options: | `DL_POLY|DLPOLY` ,
`DL_POLY_EAM_fs` ,
`DL_POLY_EAM` ,
`eam_adp` ,
`excel` ,
`excel_eam` ,
`excel_eam_fs` ,
`GULP` ,
`LAMMPS_eam_alloy|setfl` ,
`LAMMPS` ,
`setfl_fs` |

Description: | Specifies the format that tabulation will be written in. |

## [Table-Form]¶

The `[Table-Form]`

section is used to define functions from pre-tabulated data that may be used in the same way as a custom `[Potentia-Form]`

. Data is specified using the `x`

and `y`

options or the `xy`

option.

To provide a continuous function interpolation is performed between data points, the interpolation method is set using the `interpolation`

option.

### Naming Table Form¶

To allow a `[Table-Form]`

to be used in sections such as `[Pair]`

, `[EAM-Embed]`

and `[EAM-Density]`

it is necessary to give it a unique label. This is done by including it in the section header following a colon:

```
[Table-Form:NAME]
```

Therefore to create a `[Table-Form]`

named `tabulated`

the following definition could be used:

```
[Table-Form:tabulated]
interpolation: cubic_spline
x : 0.0 1.0 2.0 3.0
y : 0.0 2.0 3.0 4.0
```

This could then be referenced in another section using this name. e.g.

```
[Pair]
Si-O : tabulated
```

### Fields¶

#### interpolation¶

Item: | `interpolation` |
---|---|

Format: | Currently this option only accepts `cubic_spline` |

Description: | Sets interpolation type. |

#### x¶

Item: | `x` |
---|---|

Format: | List of space separated float values. |

Description: | Define x values of tabulated data. Must be used with `y` option. |

Example: | To define a linear function the following could be used: |

```
[Table-Form:linear]
interpolation: cubic_spline
x : 0.0 1.0 2.0 3.0
y : 0.0 2.0 3.0 4.0
```

#### xy¶

Item: | `xy` |
---|---|

Format: | List of space separated float values. |

Description: | Allows x and y values of data to be specified as series of pairs. |

Example: | To define a linear function the following could be used: |

```
[Table-Form:linear]
interpolation: cubic_spline
xy: 0.0 0.0
1.0 2.0
2.0 3.0
3.0 4.0
```

## [Variables]¶

*Added in: 0.4.0*

This section allows values to be specified for use in multiple places in the `potable`

file. Values are actually string snippets with variable place-holders replaced throughout the file before potential tabulation is performed. Variables are specified like this:

```
[Variables]
VARIABLE_NAME_1 : VARIABLE_VALUE_1
VARIABLE_NAME_2 : VARIABLE_VALUE_2
...
VARIABLE_NAME_N : VARIABLE_VALUE_N
```

These values may then be referenced elsewhere in the file through place-holders with the this form `${VARIABLE_NAME}`

. With the place-holder replaced with the value from the `[Variables]`

section before tabulation is performed.

This feature makes use of the string interpolation from Python’s `configparser`

module using the extended interpolation syntax. This allows values from other sections in the file to be referenced using this placeholder format: `${SECTION:NAME}`

.

### Example¶

```
[Variables]
nsteps : 10000
rho : 0.32
[Tabulation]
target : LAMMPS
nr : ${nsteps}
dr : 0.1
[Species]
Gd.atomic_number : 64
O.atomic_number : 8
[Pair]
Gd-O : spline(
as.zbl ${Species:Gd.atomic_number} ${Species:O.atomic_number}
>=0.8
as.buck 1000.0 ${rho} 0.0)
O-O : as.buck 500 ${rho} 32.0
```