LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

pair_coeff command

Syntax:

pair_coeff I J args 

Examples:

pair_coeff 2 2 1.0 1.0 2.5
pair_coeff 2 * 1.0 1.0
pair_coeff 3* 1*2 1.0 1.0 2.5
pair_coeff * * 1.0 1.0
pair_coeff 2 2 niu3
pair_coeff * * nialhjea 1 1 2
pair_coeff * 3 morse.table ENTRY1
pair_coeff 1 2 lj/cut 1.0 1.0 2.5 

Description:

Specify the pairwise force field coefficients for one or more pairs of atom types. The number and meaning of the coefficients depends on the pair style. Pair coefficients can also be set in the data file read read_data command or in a restart file.

I and J can be specified in one of two ways. Explicit numeric values can be used for each, as in the 1st example above. In this case, I <= J is required. LAMMPS sets the coefficients for the symmetric J,I interaction to the same values.

A wild-card asterik can be used with the I,J arguments to set the coefficients for multiple pairs of atom types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the number of atom types, then an asterik with no numeric values means all types from 1 to N. A leading asterik means all types from 1 to n (inclusive). A trailing asterik means all types from n to N (inclusive). A middle asterik means all types from m to n (inclusive). Note that only type pairs with I <= J are set; if asteriks imply type pairs where J < I, they are ignored.

Note that using 2 pair_coeff commands for the same I,J pair is perfectly valid. For example, these commands set the coeffs for all I,J pairs, then overwrite the coeffs for just the I,J = 2,3 pair:

pair_coeff * * 1.0 1.0 2.5
pair_coeff 2 3 2.0 1.0 1.12 

A line in a data file that specifies pair coefficients uses the exact same format as the arguments of the pair_coeff command in an input script, with the exception of the I,J type arguments. In each line of the "Pair Coeffs" section of a data file, only a single type I is specified, which sets the coefficients for type I interacting with type I. This is because the section has exactly N lines, where N = the number of atom types. For this reason, the wild-card asterik should also not be used as part of the I argument. Thus in a data file, the line corresponding to the 1st example above would be listed as

2 1.0 1.0 2.5 

If coefficients for type pairs with I not equal J are not set explicity by a pair_coeff command, they are inferred from the I,I and J,J settings by mixing rules; see the pair_modify command for a discussion. Exceptions to the mixing rules of the pair_modify command are discussed below.

Here are the coefficients specified by the pair_coeff command for each pair style. Note that when allowed, cutoff arguments are optional; if they are specified for a particular I,J pair they override the global cutoff(s) specified by the pair_style command.

The units of each coefficient are shown in parenthesis.


For styles buck, buck/coul/cut, and buck/coul/long, specify 3, 4, or 5 coefficients:

The latter 2 coefficients are optional. If not specified, the global LJ and Coulombic cutoffs are used. If only one cutoff is specified, it is used as the cutoff for both LJ and Coulombic interactions for this type pair. If both coefficients are specified, they are used as the LJ and Coulombic cutoffs for this type pair.

For buck/coul/long only the LJ cutoff can be specified since a Coulombic cutoff cannot be specified for an individual I,J type pair. All type pairs use the same global Coulombic cutoff specified in the pair_style command.


The dipole styles are not yet implemented in LAMMPS. They will enable a point dipole and charge to be assigned to each atom and the resulting charge-dipole and dipole-dipole interactions to be computed.


For style dpd, specify 3 or 4 coefficients:

The last coefficient is optional. If not specified, the global DPD cutoff is used.


For style eam, potential values are read from a file that is in the DYNAMO single-element funcfl format.

Note that unlike for other potentials, you do not set cutoffs for EAM potentials in the pair_style or pair_coeff command; they are specified in the EAM potential files.

For style eam you must assign a potential file to each I,I pair of atom types by using a single pair_coeff argument:

Thus the following command

pair_coeff *2 1*2 cuu3 

will read the cuu3 potential file and use the tabulated Cu values for F, phi, rho that it contains for type pairs 1,1 and 2,2 (type pairs 1,2 and 2,1 are ignored). In effect, this makes atom types 1 and 2 in LAMMPS be Cu atoms. Different single-element files can be assigned to different atom types to model an alloy system. The mixing to create alloy potentials for type pairs with I != J is done automatically the same way that the serial DYANMO code originally did it; you do not need to specify coefficients for these type pairs.

There are several funcl files in the potentials directory of the LAMMPS distribution. A DYNAMO single-element funcfl file is formatted as follows:

On line 2, all values but the mass are ignored by LAMMPS. The mass is in atomic mass units which is converted by LAMMPS to the appropriate internal mass units. On line 3, Nrho and Nr are the number of tabulated values in the subsequent arrays, drho and dr are the spacing in density and distance space for the values in those arrays, and the specified cutoff becomes the pairwise cutoff used by LAMMPS for the potential. The units of dr are Angstroms; I'm not sure of the units for drho - some measure of electron density.

Following the 3 header lines are 3 arrays of tabulated values:

The values for each array can be listed as multiple values per line, so long as each array starts on a new line. The individual values are (for example) phi(r) for r = 0,dr,2*dr, ... (Nr-1)*dr.


For style eam/alloy, potential values are read from a file that is in the DYNAMO multi-element setfl format.

Only one pair_coeff command can be used (one file). DYNAMO setfl files contain information for M elements. These are mapped to LAMMPS atom types by specifying N additional arguments after the filename, where N is the number of LAMMPS atom types:

As an example, the nialhjea setfl file has tabulated EAM values for 3 elements and their alloy interactions: Ni, Al, and H. If your LAMMPS simulation has 4 atoms types and you want the 1st 3 to be Ni, and the 4th to be Al, you would use the following pair_coeff command:

pair_coeff * * nialhjea 1 1 1 2 

The 1st 2 arguments must be * * so as to span all LAMMPS atom types. The first three "1" values map LAMMPS atom types 1,2,3 to the 1st element (Ni) in the setfl file. The final "2" value maps LAMMPS atom type 4 to the 2nd element = Al. If a mapping value is "0", the mapping is not performed. This is useful when EAM potentials are part of the hybrid pair style, to represent non-EAM atom types.

There is one setfl file (nialhjea) in the potentials directory of the LAMMPS distribution. A DYNAMO multi-element setfl file is formatted as follows:

The meaning of the values in line 5 is the same as for the funcfl file described above. Note that the cutoff is a global value, valid for all pairwise interactions for all element pairings.

Following the 5 header lines are Nelements sections, one for each element, each with the following format:

As with the funcfl files, only the mass is used by LAMMPS from the 1st line. The F and rho arrays are unique to a single element and are formatted the same as in a funcfl file.

Following the Nelements sections, values for the pair potential phi arrays are listed for all i,j element pairs in the same format as other arrays. Since these interactions are symmetric (i,j = j,i) only phi arrays with i >= j are listed, in the following order: i,j = (1,1), (2,1), (2,2), (3,1), (3,2), (3,3), (4,1), ..., (Nelements, Nelements). The tabulated values for each phi function are listed in setfl files as r*phi, rather than as phi (in funcfl files).


For style eam/fs, the form of the pair_coeff command is exactly the same as for style eam/alloy, e.g.

pair_coeff * * filename 1 1 1 2 

where there are N additional arguments after the filename, where N is the number of LAMMPS atom types. The N values determine the mapping of LAMMPS atom types to EAM elements in the file, as described in style eam/alloy.

The difference is that files read by eam/fs are in a more general format than the DYNAMO setfl format read by eam/alloy, so that the i,j density functionals for all pairs of elements are included as needed by the Finnis/Sinclair formulation of the EAM.

There is one FS file (nialhjea_FS) in the potentials directory of the LAMMPS distribution. It is formatted as follows:

The 5-line header section is identical to an EAM setfl file.

Following the header are Nelements sections, one for each element I, each with the following format:

Following the Nelements sections, values for the pair potential phi arrays are listed in the same manner (r*phi) as in EAM setfl files. Note that the rho arrays in Finnis/Sinclair can be asymmetric (i,j != j,i) so there are Nelements^2 of them listed in the file. But the phi arrays are still symmetric, so only phi arrays for i >= j are listed.


For styles gran/hertzian, gran/history, and gran/no_history, there are no individual atom type coefficients that can be set. All global settings are made via the pair_style command.


For styles lj/charmm/coul/charmm, lj/charmm/coul/charmm/implicit, and lj/charmm/coul/long, specify 2 or 4 coefficients:

Note that sigma is defined as in the LJ formula above as the zero-crossing distance for the potential, not as the energy minimum at 2^(1/6) sigma.

The latter 2 coefficients are optional. If they are specified, they are used in the Lennard-Jones formula between 2 atoms of these types which are also first and fourth atoms in any dihedral. No cutoffs are specified because this CHARMM force field does not allow varying cutoffs for individual atom pairs; all pairs use the global cutoff(s) specified in the pair_style command.


For styles lj/class2, lj/class2/coul/cut, and lj/class2/coul/long, specify 2, 3, or 4 coefficients:

The latter 2 coefficients are optional. If not specified, the global class 2 and Coulombic cutoffs are used. If only one cutoff is specified, it is used as the cutoff for both class 2 and Coulombic interactions for this type pair. If both coefficients are specified, they are used as the class 2 and Coulombic cutoffs for this type pair.

For lj/class2/coul/long only the class 2 cutoff can be specified since a Coulombic cutoff cannot be specified for an individual I,J type pair. All type pairs use the same global Coulombic cutoff specified in the pair_style command.


For styles lj/cut, lj/cut/coul/cut, lj/cut/coul/debye, lj/cut/coul/long, and lj/cut/coul/long/tip4p specify 2, 3, or 4 coefficients:

Note that sigma is defined as in the LJ formula above as the zero-crossing distance for the potential, not as the energy minimum at 2^(1/6) sigma.

The latter 2 coefficients are optional. If not specified, the global LJ and Coulombic cutoffs are used. If only one cutoff is specified, it is used as the cutoff for both LJ and Coulombic interactions for this type pair. If both coefficients are specified, they are used as the LJ and Coulombic cutoffs for this type pair.

For lj/cut/coul/long and lj/cut/coul/long/tip4p only the LJ cutoff can be specified since a Coulombic cutoff cannot be specified for an individual I,J type pair. All type pairs use the same global Coulombic cutoff specified in the pair_style command.


For style lj/expand, specify 3 or 4 coefficients:

The delta values can be positive or negative. Note that the cutoff does not include the delta distance. I.e. the actual force cutoff is the sum of cutoff + delta.

The last coefficient is optional. If not specified, the global LJ cutoff is used.


For style morse, specify 3 or 4 coefficients:

The last coefficient is optional. If not specified, the global morse cutoff is used.


For style soft, specify 2 or 3 coefficients:

Astart and Astop are the values of the prefactor at the start and end of the next run. At intermediate times the value of A will be ramped between these 2 values. Note that before performing a 2nd run, you will want to adjust the values of Astart and Astop for all type pairs, or switch to a new pair style.

The last coefficient is optional. If not specified, the global soft cutoff is used.


For style table, specify 2 or 3 coefficients:

The filename specifies a file containing tabulated energy and force values. The keyword specifies a section of the file. The cutoff is an optional coefficient. If not specified, the outer cutoff in the table itself (see below) will be used to build an interpolation table that extend to the largest tablulated distance. If specified, only file values up to the cutoff are used to create the interpolation table.

The format of a tabulated file is as follows (without the parenthesized comments):

# Morse potential for Fe   (one or more comment or blank lines) 
MORSE_FE                   (keyword is first text on line)
N 500 R 1.0 10.0           (N, R, RSQ, BITMAP, FPRIME parameters)
                           (blank)
1 1.0 25.5 102.34          (index, r, energy, force)
2 1.02 23.4 98.5
...
500 10.0 0.001 0.003 

A section begins with a non-blank line whose 1st character is not a "#"; blank lines or lines starting with "#" can be used as comments between sections. The first line begins with a keyword which identifies the section. The line can contain additional text, but the initial text must match the argument specified in the pair_coeff command. The next line lists (in any order) one or more parameters for the table. Each parameter is a keyword followed by one or more numeric values.

The parameter "N" is required; its value is the number of table entries that follow. All other parameters are optional. If "R" or "RSQ" or "BITMAP" does not appear, then the distances in each line of the table are used as-is to perform spline interpolation. In this case, the table values can be spaced in r uniformly or however you wish to position table values in regions of large gradients.

If used, the parameters "R" or "RSQ" are followed by 2 values rlo and rhi. If specified, the distance associated with each energy and force value is computed from these 2 values (at high accuracy), rather than using the (low-accuracy) value listed in each line of the table. For "R", distances uniformly spaced between rlo and rhi are computed; for "RSQ", squared distances uniformly spaced between rlo*rlo and rhi*rhi are computed.

If used, the parameter "BITMAP" is also followed by 2 values rlo and rhi. These values, along with the "N" value determine the ordering of the N lines that follow and what distance is associated with each. This ordering is complex, so it is not documented here, since this file is typically produced by the pair_write command with its bitmap option. When the table is in BITMAP format, the "N" parameter in the file must be equal to 2^M where M is the value specified in the pair_style command. Also, a cutoff parameter cannot be used as an optional 3rd argument in the pair_coeff command; the entire table extent as specified in the file must be used.

If used, the parameter "FPRIME" is followed by 2 values fplo and fphi which are the derivative of the force at the innermost and outermost distances listed in the table. These values are needed by the spline construction routines. If not specified by the "FPRIME" parameter, they are estimated (less accurately) by the first 2 and last 2 force values in the table. This parameter is not used by BITMAP tables.

Following a blank line, the next N lines list the tabulated values. On each line, the 1st value is the index from 1 to N, the 2nd value is r (in distance units), the 3rd value is the energy (in energy units), and the 4th is the force (in force units). The r values must increase from one line to the next (unless the BITMAP parameter is specified).

Note that one file can contain many sections, each with a tabulated potential. LAMMPS reads the file section by section until it finds one that matches the specified keyword.


For style yukawa, specify 1 or 2 coefficients:

The last coefficient is optional. If not specified, the global yukawa cutoff is used.


For style hybrid, each pair_coeff command assigns one of the sub-styles specified in the pair_style command to a set of atom type pairs. The arguments of the pair_coeff command are the same as they would be for the sub-style itself, except that an additional argument is added (after the type pairs) which specifies which sub-style is being used. For example, consider a simulation with 3 atom types: types 1 and 2 are Ni atoms, type 3 are LJ atoms with charges. The following commands would set up the hybrid simulation:

atom_style hybrid eam charge
pair_style hybrid eam lj/cut/coul/cut 10.0 lj/cut 8.0
pair_coeff 1*2 1*2 eam niu3
pair_coeff 3 3 lj/cut/coul/cut 1.0 1.0
pair_coeff 1*2 3 lj/cut 0.5 1.2 

The atom_style hybrid command is needed because atoms in the simulation will have both EAM and charge attributes.


Restrictions:

This command must come after the simulation box is defined by a read_data, read_restart, or create_box command.

Related commands:

pair_style, pair_modify, read_data, read_restart, pair_write

Default: none