\(\renewcommand{\AA}{\text{Å}}\)

1.3.1. The LIBLAMMPS Fortran Module

The LIBLAMMPS module provides an interface to call LAMMPS from Fortran. It is based on the LAMMPS C library interface and requires a fully Fortran 2003-compatible compiler to be compiled. It is designed to be self-contained and not require any support functions written in C, C++, or Fortran other than those in the C library interface and the module itself.

While C libraries have a defined binary interface (ABI) and can thus be used from multiple compiler versions from different vendors as long as they are compatible with the hosting operating system, the same is not true for Fortran programs. Thus, the LAMMPS Fortran module needs to be compiled alongside the code using it from the source code in fortran/lammps.f90. When linking, you also need to link to the LAMMPS library. A typical command line for a simple program using the Fortran interface would be:

mpifort -o testlib.x lammps.f90 testlib.f90 -L. -llammps

Please note that the MPI compiler wrapper is only required when the calling the library from an MPI-parallelized program. Otherwise, using the plain Fortran compiler (gfortran, ifort, flang, etc.) will suffice. It may be necessary to link to additional libraries, depending on how LAMMPS was configured and whether the LAMMPS library was compiled as a static or dynamic library.

If the LAMMPS library itself has been compiled with MPI support, the resulting executable will still be able to run LAMMPS in parallel with mpirun, mpiexec or equivalent. Please also note that the order of the source files matters: the lammps.f90 file needs to be compiled first, since it provides the LIBLAMMPS module that is imported by the Fortran code that uses the interface. A working example can be found together with equivalent examples in C and C++ in the examples/COUPLE/simple folder of the LAMMPS distribution.

New in version 9Oct2020.

Work in Progress

This Fortran module is work in progress and only the documented functionality is currently available. The final implementation should cover the entire range of functionality available in the C and Python library interfaces.

Note

A contributed (and more complete!) Fortran interface that more closely resembles the C library interface is available in the examples/COUPLE/fortran2 folder. Please see the README file in that folder for more information about it and how to contact its author and maintainer.


1.3.2. Creating or deleting a LAMMPS object

With the Fortran interface, the creation of a LAMMPS instance is included in the constructor for creating the lammps() derived type. To import the definition of that type and its type-bound procedures, you need to add a USE LIBLAMMPS statement. Internally, it will call either lammps_open_fortran() or lammps_open_no_mpi() from the C library API to create the class instance. All arguments are optional and lammps_mpi_init() will be called automatically if it is needed. Similarly, a possible call to lammps_mpi_finalize() is integrated into the close() function and triggered with the optional logical argument set to .TRUE.. Here is a simple example:

PROGRAM testlib
  USE LIBLAMMPS                 ! include the LAMMPS library interface
  IMPLICIT NONE
  TYPE(lammps) :: lmp           ! derived type to hold LAMMPS instance
  CHARACTER(LEN=*), PARAMETER :: args(3) = &
      [ CHARACTER(LEN=12) :: 'liblammps', '-log', 'none' ]

  ! create a LAMMPS instance (and initialize MPI)
  lmp = lammps(args)
  ! get and print numerical version code
  PRINT*, 'LAMMPS Version: ', lmp%version()
  ! delete LAMMPS instance (and shutdown MPI)
  CALL lmp%close(.TRUE.)
END PROGRAM testlib

It is also possible to pass command line flags from Fortran to C/C++ and thus make the resulting executable behave similarly to the standalone executable (it will ignore the -in/-i flag, though). This allows using the command line to configure accelerator and suffix settings, configure screen and logfile output, or to set index style variables from the command line and more. Here is a correspondingly adapted version of the previous example:

PROGRAM testlib2
  USE LIBLAMMPS                 ! include the LAMMPS library interface
  IMPLICIT NONE
  TYPE(lammps) :: lmp           ! derived type to hold LAMMPS instance
  CHARACTER(LEN=128), ALLOCATABLE :: command_args(:)
  INTEGER :: i, argc

  ! copy command line flags to `command_args()`
  argc = COMMAND_ARGUMENT_COUNT()
  ALLOCATE(command_args(0:argc))
  DO i=0, argc
    CALL GET_COMMAND_ARGUMENT(i, command_args(i))
  END DO

  ! create a LAMMPS instance (and initialize MPI)
  lmp = lammps(command_args)
  ! get and print numerical version code
  PRINT*, 'Program name:   ', command_args(0)
  PRINT*, 'LAMMPS Version: ', lmp%version()
  ! delete LAMMPS instance (and shuts down MPI)
  CALL lmp%close(.TRUE.)
  DEALLOCATE(command_args)
END PROGRAM testlib2

1.3.3. Executing LAMMPS commands

Once a LAMMPS instance is created, it is possible to “drive” the LAMMPS simulation by telling LAMMPS to read commands from a file or to pass individual or multiple commands from strings or lists of strings. This is done similarly to how it is implemented in the C library interface. Before handing off the calls to the C library interface, the corresponding Fortran versions of the calls (file(), command(), commands_list(), and commands_string()) have to make a copy of the strings passed as arguments so that they can be modified to be compatible with the requirements of strings in C without affecting the original strings. Those copies are automatically deleted after the functions return. Below is a small demonstration of the uses of the different functions:

PROGRAM testcmd
  USE LIBLAMMPS
  TYPE(lammps) :: lmp
  CHARACTER(LEN=512) :: cmds
  CHARACTER(LEN=40), ALLOCATABLE :: cmdlist(:)
  CHARACTER(LEN=10) :: trimmed
  INTEGER :: i

  lmp = lammps()
  CALL lmp%file('in.melt')
  CALL lmp%command('variable zpos index 1.0')
  ! define 10 groups of 10 atoms each
  ALLOCATE(cmdlist(10))
  DO i=1, 10
    WRITE(trimmed,'(I10)') 10*i
    WRITE(cmdlist(i),'(A,I1,A,I10,A,A)')       &
        'group g', i-1, ' id ', 10*(i-1)+1, ':', ADJUSTL(trimmed)
  END DO
  CALL lmp%commands_list(cmdlist)
  ! run multiple commands from multi-line string
  cmds = 'clear' // NEW_LINE('A') //                       &
      'region  box block 0 2 0 2 0 2' // NEW_LINE('A') //  &
      'create_box 1 box' // NEW_LINE('A') //               &
      'create_atoms 1 single 1.0 1.0 ${zpos}'
  CALL lmp%commands_string(cmds)
  CALL lmp%close(.TRUE.)
END PROGRAM testcmd

1.3.4. Accessing system properties

The C library interface allows the extraction of different kinds of information about the active simulation instance and also—in some cases—to apply modifications to it, and the Fortran interface provides access to the same data using Fortran-style, C-interoperable data types. In some cases, the Fortran library interface makes pointers to internal LAMMPS data structures accessible; when accessing them through the library interfaces, special care is needed to avoid data corruption and crashes. Please see the documentation of the individual type-bound procedures for details.

Below is an example demonstrating some of the possible uses.

PROGRAM testprop
  USE LIBLAMMPS
  USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t
  USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY : OUTPUT_UNIT
  TYPE(lammps) :: lmp
  INTEGER(KIND=c_int64_t), POINTER :: natoms
  REAL(KIND=c_double), POINTER :: dt
  INTEGER(KIND=c_int64_t), POINTER :: ntimestep
  REAL(KIND=c_double) :: pe, ke

  lmp = lammps()
  CALL lmp%file('in.sysinit')
  natoms = lmp%extract_global('natoms')
  WRITE(OUTPUT_UNIT,'(A,I0,A)') 'Running a simulation with ', natoms, ' atoms'
  WRITE(OUTPUT_UNIT,'(I0,A,I0,A,I0,A)') lmp%extract_setting('nlocal'), &
      ' local and ', lmp%extract_setting('nghost'), ' ghost atoms. ', &
      lmp%extract_setting('ntypes'), ' atom types'

  CALL lmp%command('run 2 post no')
  dt = lmp%extract_global('dt')
  ntimestep = lmp%extract_global('ntimestep')
  WRITE(OUTPUT_UNIT,'(A,I0,A,F4.1,A)') 'At step: ', ntimestep, &
      '  Changing timestep from', dt, ' to 0.5'
  dt = 0.5_c_double
  CALL lmp%command('run 2 post no')

  WRITE(OUTPUT_UNIT,'(A,I0)') 'At step: ', ntimestep
  pe = lmp%get_thermo('pe')
  ke = lmp%get_thermo('ke')
  PRINT*, 'PE = ', pe
  PRINT*, 'KE = ', ke

  CALL lmp%close(.TRUE.)
END PROGRAM testprop

1.3.5. The LIBLAMMPS module API

Below are the detailed descriptions of definitions and interfaces of the contents of the LIBLAMMPS Fortran interface to LAMMPS.

type  lammps

Derived type that is the general class of the Fortran interface. It holds a reference to the LAMMPS class instance to which any of the included calls are forwarded.

Type fields:

function  lammps([args][,comm])

This is the constructor for the Fortran class and will forward the arguments to a call to either lammps_open_fortran() or lammps_open_no_mpi(). If the LAMMPS library has been compiled with MPI support, it will also initialize MPI, if it has not already been initialized before.

The args argument with the list of command line parameters is optional and so it the comm argument with the MPI communicator. If comm is not provided, MPI_COMM_WORLD is assumed. For more details please see the documentation of lammps_open().

Options:
  • args [character(len=*),dimension(:),optional] :: arguments as list of strings

  • comm [integer,optional] :: MPI communicator

Call to:

lammps_open_fortran() lammps_open_no_mpi()

Return:

lammps :: an instance of the lammps derived type

Note

The MPI_F08 module, which defines Fortran 2008 bindings for MPI, is not directly supported by this interface due to the complexities of supporting both the MPI_F08 and MPI modules at the same time. However, you should be able to use the MPI_VAL member of the MPI_comm derived type to access the integer value of the communicator, such as in

PROGRAM testmpi
  USE LIBLAMMPS
  USE MPI_F08
  TYPE(lammps) :: lmp
  lmp = lammps(MPI_COMM_SELF%MPI_VAL)
END PROGRAM testmpi
type  lammps_style

This derived type is there to provide a convenient interface for the style constants used with extract_compute(), extract_fix(), and extract_variable(). Assuming your LAMMPS instance is called lmp, these constants will be lmp%style%global, lmp%style%atom, and lmp%style%local. These values are identical to the values described in _LMP_STYLE_CONST for the C library interface.

Type fields:
  • % global [integer(c_int)] :: used to request global data

  • % atom [integer(c_int)] :: used to request per-atom data

  • % local [integer(c_int)] :: used to request local data

type  lammps_type

This derived type is there to provide a convenient interface for the type constants used with extract_compute(), extract_fix(), and extract_variable(). Assuming your LAMMPS instance is called lmp, these constants will be lmp%type%scalar, lmp%type%vector, and lmp%type%array. These values are identical to the values described in _LMP_TYPE_CONST for the C library interface.

Type fields:
  • % scalar [integer(c_int)] :: used to request scalars

  • % vector [integer(c_int)] :: used to request vectors

  • % array [integer(c_int)] :: used to request arrays (matrices)

Procedures Bound to the lammps Derived Type

subroutine  close([finalize])

This method will close down the LAMMPS instance through calling lammps_close(). If the finalize argument is present and has a value of .TRUE., then this subroutine also calls lammps_kokkos_finalize() and lammps_mpi_finalize().

Options:

finalize [logical,optional] :: shut down the MPI environment of the LAMMPS library if .TRUE..

Call to:

lammps_close() lammps_mpi_finalize() lammps_kokkos_finalize()


subroutine  error(error_type, error_text)

This method is a wrapper around the lammps_error() function and will dispatch an error through the LAMMPS Error class.

New in version 3Nov2022.

Parameters:
  • error_type [integer(c_int)] :: constant to select which Error class function to call

  • error_text [character(len=*)] :: error message

Call to:

lammps_error()


subroutine  file(filename)

This method will call lammps_file() to have LAMMPS read and process commands from a file.

Parameters:

filename [character(len=*)] :: name of file with LAMMPS commands

Call to:

lammps_file()


subroutine  command(cmd)

This method will call lammps_command() to have LAMMPS execute a single command.

Parameters:

cmd [character(len=*)] :: single LAMMPS command

Call to:

lammps_command()


subroutine  commands_list(cmds)

This method will call lammps_commands_list() to have LAMMPS execute a list of input lines.

Parameters:

cmd [character(len=*),dimension(:)] :: list of LAMMPS input lines

Call to:

lammps_commands_list()


subroutine  commands_string(str)

This method will call lammps_commands_string() to have LAMMPS execute a block of commands from a string.

Parameters:

str [character(len=*)] :: LAMMPS input in string

Call to:

lammps_commands_string()


function  get_natoms()

This function will call lammps_get_natoms() and return the number of atoms in the system.

Call to:

lammps_get_natoms()

Return:

natoms [real(c_double)] :: number of atoms

Note

If you would prefer to get the number of atoms in its native format (i.e., as a 32- or 64-bit integer, depending on how LAMMPS was compiled), this can be extracted with extract_global().


function  get_thermo(name)

This function will call lammps_get_thermo() and return the value of the corresponding thermodynamic keyword.

New in version 3Nov2022.

Parameters:

name [character(len=*)] :: string with the name of the thermo keyword

Call to:

lammps_get_thermo()

Return:

value [real(c_double)] :: value of the requested thermo property or 0.0_c_double


subroutine  extract_box([boxlo][, boxhi][, xy][, yz][, xz][, pflags][, boxflag])

This subroutine will call lammps_extract_box(). All parameters are optional, though obviously at least one should be present. The parameters pflags and boxflag are stored in LAMMPS as integers, but should be declared as LOGICAL variables when calling from Fortran.

New in version 3Nov2022.

Options:
  • boxlo [real(c_double),dimension(3),optional] :: vector in which to store lower-bounds of simulation box

  • boxhi [real(c_double),dimension(3),optional] :: vector in which to store upper-bounds of simulation box

  • xy [real(c_double),optional] :: variable in which to store xy tilt factor

  • yz [real(c_double),optional] :: variable in which to store yz tilt factor

  • xz [real(c_double),optional] :: variable in which to store xz tilt factor

  • pflags [logical,dimension(3),optional] :: vector in which to store periodicity flags (.TRUE. means periodic in that dimension)

  • boxflag [logical,optional] :: variable in which to store boolean denoting whether the box will change during a simulation (.TRUE. means box will change)

Call to:

lammps_extract_box()

Note

Note that a frequent use case of this function is to extract only one or more of the options rather than all seven. For example, assuming “lmp” represents a properly-initialized LAMMPS instance, the following code will extract the periodic box settings into the variable “periodic”:

! code to start up
logical :: periodic(3)
! code to initialize LAMMPS / run things / etc.
call lmp%extract_box(pflags = periodic)

subroutine  reset_box(boxlo, boxhi, xy, yz, xz)

This subroutine will call lammps_reset_box(). All parameters are required.

New in version 3Nov2022.

Parameters:
  • boxlo [real(c_double),dimension(3)] :: vector of three doubles containing the lower box boundary

  • boxhi [real(c_double),dimension(3)] :: vector of three doubles containing the upper box boundary

  • xy [real(c_double)] :: x–y tilt factor

  • yz [real(c_double)] :: y–z tilt factor

  • xz [real(c_double)] :: x–z tilt factor

Call to:

lammps_reset_box()


subroutine  memory_usage(meminfo)

This subroutine will call lammps_memory_usage() and store the result in the three-element array meminfo.

New in version 3Nov2022.

Parameters:

meminfo [real(c_double),dimension(3)] :: vector of three doubles in which to store memory usage data

Call to:

lammps_memory_usage()


function  get_mpi_comm()

This function returns a Fortran representation of the LAMMPS “world” communicator.

New in version 3Nov2022.

Call to:

lammps_get_mpi_comm()

Return:

comm [integer] :: Fortran integer equivalent to the MPI communicator LAMMPS is using

Note

The C library interface currently returns type int instead of type MPI_Fint, which is the C type corresponding to Fortran INTEGER types of the default kind. On most compilers, these are the same anyway, but this interface exchanges values this way to avoid warning messages.

Note

The MPI_F08 module, which defines Fortran 2008 bindings for MPI, is not directly supported by this function. However, you should be able to convert between the two using the MPI_VAL member of the communicator. For example,

USE MPI_F08
USE LIBLAMMPS
TYPE (lammps) :: lmp
TYPE (MPI_Comm) :: comm
! ... [commands to set up LAMMPS/etc.]
comm%MPI_VAL = lmp%get_mpi_comm()

should assign an MPI_F08 communicator properly.


function  extract_setting(keyword)

Query LAMMPS about global settings. See the documentation for the lammps_extract_setting() function from the C library.

New in version 3Nov2022.

Parameters:

keyword [character(len=*)] :: string containing the name of the thermo keyword

Call to:

lammps_extract_setting()

Return:

setting [integer(c_int)] :: value of the queried setting or \(-1\) if unknown


function  extract_global(name)

This function calls lammps_extract_global() and returns either a string or a pointer to internal global LAMMPS data, depending on the data requested through name.

New in version 3Nov2022.

Note that this function actually does not return a value, but rather associates the pointer on the left side of the assignment to point to internal LAMMPS data (with the exception of string data, which are copied and returned as ordinary Fortran strings). Pointers must be of the correct data type to point to said data (typically INTEGER(c_int), INTEGER(c_int64_t), or REAL(c_double)) and have compatible kind and rank. The pointer being associated with LAMMPS data is type-, kind-, and rank-checked at run-time via an overloaded assignment operator. The pointers returned by this function are generally persistent; therefore it is not necessary to call the function again, unless a clear command command has been issued, which wipes out and recreates the contents of the LAMMPS class.

For example,

PROGRAM demo
  USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_int64_t, c_int, c_double
  USE LIBLAMMPS
  TYPE(lammps) :: lmp
  INTEGER(c_int), POINTER :: nlocal => NULL()
  INTEGER(c_int64_t), POINTER :: ntimestep => NULL()
  REAL(c_double), POINTER :: dt => NULL()
  CHARACTER(LEN=10) :: units
  lmp = lammps()
  ! other commands
  nlocal = lmp%extract_global('nlocal')
  ntimestep = lmp%extract_global('ntimestep')
  dt = lmp%extract_global('dt')
  units = lmp%extract_global('units')
  ! more commands
  lmp.close(.TRUE.)
END PROGRAM demo

would extract the number of atoms on this processor, the current time step, the size of the current time step, and the units being used into the variables nlocal, ntimestep, dt, and units, respectively.

Note

If extract_global() returns a string, the string must have length greater than or equal to the length of the string (not including the terminal NULL character) that LAMMPS returns. If the variable’s length is too short, the string will be truncated. As usual in Fortran, strings are padded with spaces at the end. If you use an allocatable string, the string must be allocated prior to calling this function, but you can automatically reallocate it to the correct length after the function returns, viz.,

PROGRAM test
  USE LIBLAMMPS
  TYPE(lammps) :: lmp
  CHARACTER(LEN=:), ALLOCATABLE :: str
  lmp = lammps()
  CALL lmp%command('units metal')
  ALLOCATE ( CHARACTER(LEN=80) :: str )
  str = lmp%extract_global('units')
  str = TRIM(str) ! re-allocates to length len_trim(str) here
  PRINT*, LEN(str), LEN_TRIM(str)
END PROGRAM test

will print the number 5 (the length of the word “metal”) twice.

Parameters:

name [character(len=*)] :: string with the name of the property to extract

Call to:

lammps_extract_global()

Return:

pointer [polymorphic] :: pointer to LAMMPS data. The left-hand side of the assignment should be either a string (if expecting string data) or a C-compatible pointer (e.g., INTEGER(c_int), POINTER :: nlocal) to the extracted property. If expecting vector data, the pointer should have dimension “:”.

Warning

Modifying the data in the location pointed to by the returned pointer may lead to inconsistent internal data and thus may cause failures, crashes, or bogus simulations. In general, it is much better to use a LAMMPS input command that sets or changes these parameters. Using an input command will take care of all side effects and necessary updates of settings derived from such settings.


function  extract_atom(name)

This function calls lammps_extract_atom() and returns a pointer to LAMMPS data tied to the Atom class, depending on the data requested through name.

New in version 3Nov2022.

Note that this function actually does not return a pointer, but rather associates the pointer on the left side of the assignment to point to internal LAMMPS data. Pointers must be of the correct type, kind, and rank (e.g., INTEGER(c_int), DIMENSION(:) for “type”, “mask”, or “tag”; INTEGER(c_int64_t), DIMENSION(:) for “tag” if LAMMPS was compiled with the -DLAMMPS_BIGBIG flag; REAL(c_double), DIMENSION(:,:) for “x”, “v”, or “f”; and so forth). The pointer being associated with LAMMPS data is type-, kind-, and rank-checked at run-time.

Parameters:

name [character(len=*)] :: string with the name of the property to extract

Call to:

lammps_extract_atom()

Return:

pointer [polymorphic] :: pointer to LAMMPS data. The left-hand side of the assignment should be a C-interoperable pointer of appropriate kind and rank (e.g., INTEGER(c_int), POINTER :: mask(:)) to the extracted property. If expecting vector data, the pointer should have dimension “:”; if expecting matrix data, the pointer should have dimension “:,:”.

Warning

Pointers returned by this function are generally not persistent, as per-atom data may be redistributed, reallocated, and reordered at every re-neighboring operation. It is advisable to re-bind pointers using extract_atom() between runs.

Array index order

Two-dimensional arrays returned from extract_atom() will be transposed from equivalent arrays in C, and they will be indexed from 1 instead of 0. For example, in C,

void *lmp;
double **x;
/* more code to setup, etc. */
x = lammps_extract_atom(lmp, "x");
printf("%f\n", x[5][1]);

will print the y-coordinate of the sixth atom on this processor. Conversely,

TYPE(lammps) :: lmp
REAL(c_double), DIMENSION(:,:), POINTER :: x => NULL()
! more code to setup, etc.
x = lmp%extract_atom("x")
PRINT '(f0.6)', x(2,6)

will print the y-coordinate of the sixth atom on this processor (note the transposition of the two indices). This is not a choice, but rather a consequence of the different conventions adopted by the Fortran and C standards decades ago: in C, the block of data

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

interpreted as a \(4\times4\) matrix would be

\[\begin{split}\begin{bmatrix} 1 & 2 & 3 & 4 \\ 5 & 6 & 7 & 8 \\ 9 & 10 & 11 & 12 \\ 13 & 14 & 15 & 16 \end{bmatrix},\end{split}\]

that is, in row-major order. In Fortran, the same block of data is interpreted in column-major order, namely,

\[\begin{split}\begin{bmatrix} 1 & 5 & 9 & 13 \\ 2 & 6 & 10 & 14 \\ 3 & 7 & 11 & 15 \\ 4 & 8 & 12 & 16 \end{bmatrix}.\end{split}\]

This difference in interpretation of the same block of data by the two languages means, in effect, that matrices from C or C++ will be transposed when interpreted in Fortran.

Note

If you would like the indices to start at 0 instead of 1 (which follows typical notation in C and C++, but not Fortran), you can create another pointer and associate it thus:

REAL(c_double), DIMENSION(:,:), POINTER :: x, x0
x = lmp%extract_atom("x")
x0(0:,0:) => x

The above would cause the dimensions of x to be (1:3, 1:nmax) and those of x0 to be (0:2, 0:nmax\(-\)1).


function  extract_compute(id, style, type)

This function calls lammps_extract_compute() and returns a pointer to LAMMPS data tied to the Compute class, specifically data provided by the compute identified by id. Computes may provide global, per-atom, or local data, and those data may be a scalar, a vector, or an array. Since computes may provide multiple kinds of data, the user is required to specify which set of data is to be returned through the style and type variables.

New in version 3Nov2022.

Note that this function actually does not return a value, but rather associates the pointer on the left side of the assignment to point to internal LAMMPS data. Pointers must be of the correct data type to point to said data (i.e., REAL(c_double)) and have compatible rank. The pointer being associated with LAMMPS data is type-, kind-, and rank-checked at run-time via an overloaded assignment operator.

For example,

TYPE(lammps) :: lmp
REAL(c_double), DIMENSION(:), POINTER :: COM
! code to setup, create atoms, etc.
CALL lmp%compute('compute COM all com')
COM = lmp%extract_compute('COM', lmp%style%global, lmp%style%type)

will bind the variable COM to the center of mass of the atoms created in your simulation. The vector in this case has length 3; the length (or, in the case of array data, the number of rows and columns) is determined for you based on data from the Compute class.

Array index order

Two-dimensional arrays returned from extract_compute() will be transposed from equivalent arrays in C, and they will be indexed from 1 instead of 0. See the note at extract_atom() for further details.

The following combinations are possible (assuming lmp is the name of your LAMMPS instance):

Style

Type

Type to assign to

Returned data

lmp%style%global

lmp%type%scalar

REAL(c_double), POINTER

Global scalar

lmp%style%global

lmp%type%vector

REAL(c_double), DIMENSION(:), POINTER

Global vector

lmp%style%global

lmp%type%array

REAL(c_double), DIMENSION(:,:), POINTER

Global array

lmp%style%atom

lmp%type%vector

REAL(c_double), DIMENSION(:), POINTER

Per-atom vector

lmp%style%atom

lmp%type%array

REAL(c_double), DIMENSION(:,:), POINTER

Per-atom array

lmp%style%local

lmp%type%vector

REAL(c_double), DIMENSION(:), POINTER

Local vector

lmp%style%local

lmp%type%array

REAL(c_double), DIMENSION(:,:), POINTER

Local array

Parameters:
  • id [character(len=*)] :: compute ID from which to extract data

  • style [integer(c_int)] :: value indicating the style of data to extract (global, per-atom, or local)

  • type [integer(c_int)] :: value indicating the type of data to extract (scalar, vector, or array)

Call to:

lammps_extract_compute()

Return:

pointer [polymorphic] :: pointer to LAMMPS data. The left-hand side of the assignment should be a C-compatible pointer (e.g., REAL(c_double), POINTER :: x) to the extracted property. If expecting vector data, the pointer should have dimension “:”; if expecting array (matrix) data, the pointer should have dimension “:,:”.

Note

If the compute’s data are not already computed for the current step, the compute will be invoked. LAMMPS cannot easily check at that time if it is valid to invoke a compute, so it may fail with an error. The caller has to check to avoid such an error.

Warning

The pointers returned by this function are generally not persistent, since the computed data may be re-distributed, re-allocated, and re-ordered at every invocation. It is advisable to re-invoke this function before the data are accessed or make a copy if the data are to be used after other LAMMPS commands have been issued. Do not modify the data returned by this function.


function  extract_fix(id, style, type[, nrow][, ncol])

This function calls lammps_extract_fix() and returns a pointer to LAMMPS data tied to the Fix class, specifically data provided by the fix identified by id. Fixes may provide global, per-atom, or local data, and those data may be a scalar, a vector, or an array. Since many fixes provide multiple kinds of data, the user is required to specify which set of data is to be returned through the style and type variables.

New in version 3Nov2022.

Global data are calculated at the time they are requested and are only available element-by-element. As such, the user is expected to provide the nrow variable to specify which element of a global vector or the nrow and ncol variables to specify which element of a global array the user wishes LAMMPS to return. The ncol variable is optional for global scalar or vector data, and both nrow and ncol are optional when a global scalar is requested, as well as when per-atom or local data are requested. The following combinations are possible (assuming lmp is the name of your LAMMPS instance):

Style

Type

nrow

ncol

Type to assign to

Returned data

lmp%style%global

lmp%type%scalar

Ignored

Ignored

REAL(c_double)

Global scalar

lmp%style%global

lmp%type%vector

Required

Ignored

REAL(c_double)

Element of global vector

lmp%style%global

lmp%type%array

Required

Required

REAL(c_double)

Element of global array

lmp%style%atom

lmp%type%scalar

(not allowed)

lmp%style%atom

lmp%type%vector

Ignored

Ignored

REAL(c_double), DIMENSION(:), POINTER

Per-atom vector

lmp%style%atom

lmp%type%array

Ignored

Ignored

REAL(c_double), DIMENSION(:,:), POINTER

Per-atom array

lmp%style%local

lmp%type%scalar

(not allowed)

lmp%style%local

lmp%type%vector

Ignored

Ignored

REAL(c_double), DIMENSION(:), POINTER

Per-atom vector

lmp%style%local

lmp%type%array

Ignored

Ignored

REAL(c_double), DIMENSION(:,:), POINTER

Per-atom array

In the case of global data, this function returns a value of type real(c_double). For per-atom or local data, this function does not return a value but instead associates the pointer on the left side of the assignment to point to internal LAMMPS data. Pointers must be of the correct data type to point to said data (i.e., REAL(c_double)) and have compatible rank. The pointer being associated with LAMMPS data is type-, kind-, and rank-checked at run-time via an overloaded assignment operator.

For example,

TYPE(lammps) :: lmp
REAL(c_double) :: dr, dx, dy, dz
! more code to set up, etc.
lmp%command('fix george all recenter 2 2 2')
! more code
dr = lmp%extract_fix("george", lmp%style%global, lmp%style%scalar)
dx = lmp%extract_fix("george", lmp%style%global, lmp%style%vector, 1)
dy = lmp%extract_fix("george", lmp%style%global, lmp%style%vector, 2)
dz = lmp%extract_fix("george", lmp%style%global, lmp%style%vector, 3)

will extract the global scalar calculated by fix recenter into the variable dr and the three elements of the global vector calculated by fix recenter into the variables dx, dy, and dz, respectively.

If asked for per-atom or local data, extract_compute() returns a pointer to actual LAMMPS data. The pointer so returned will have the appropriate size to match the internal data, and will be type/kind/rank-checked at the time of the assignment. For example,

TYPE(lammps) :: lmp
REAL(c_double), DIMENSION(:), POINTER :: r
! more code to set up, etc.
lmp%command('fix state all store/state 0 x y z')
! more code
r = lmp%extract_fix('state', lmp%style%atom, lmp%type%array)

will bind the pointer r to internal LAMMPS data representing the per-atom array computed by fix store/state when three inputs are specified. Similarly,

TYPE(lammps) :: lmp
REAL(c_double), DIMENSION(:), POINTER :: x
! more code to set up, etc.
lmp%command('fix state all store/state 0 x')
! more code
x = lmp%extract_fix('state', lmp%style%atom, lmp%type%vector)

will associate the pointer x with internal LAMMPS data corresponding to the per-atom vector computed by fix store/state when only one input is specified. Similar examples with lmp%style%atom replaced by lmp%style%local will extract local data from fixes that define local vectors and/or arrays.

Warning

The pointers returned by this function for per-atom or local data are generally not persistent, since the computed data may be redistributed, reallocated, and reordered at every invocation of the fix. It is thus advisable to re-invoke this function before the data are accessed or to make a copy if the data are to be used after other LAMMPS commands have been issued.

Note

LAMMPS cannot easily check if it is valid to access the data, so it may fail with an error. The caller has to avoid such an error.

Parameters:
  • id [character(len=*)] :: string with the name of the fix from which to extract data

  • style [integer(c_int)] :: value indicating the style of data to extract (global, per-atom, or local)

  • type [integer(c_int)] :: value indicating the type of data to extract (scalar, vector, or array)

  • nrow [integer(c_int)] :: row index (used only for global vectors and arrays)

  • ncol [integer(c_int)] :: column index (only used for global arrays)

Call to:

lammps_extract_fix()

Return:

data [polymorphic] :: LAMMPS data (for global data) or a pointer to LAMMPS data (for per-atom or local data). The left-hand side of the assignment should be of type REAL(c_double) and have appropriate rank (i.e., DIMENSION(:) if expecting per-atom or local vector data and DIMENSION(:,:) if expecting per-atom or local array data). If expecting local or per-atom data, it should have the POINTER attribute, but if expecting global data, it should be an ordinary (non-POINTER) variable.

Array index order

Two-dimensional global, per-atom, or local array data from extract_fix() will be transposed from equivalent arrays in C (or in the ordinary LAMMPS interface accessed through thermodynamic output), and they will be indexed from 1, not 0. This is true even for global data, which are returned as scalars—this is done primarily so the interface is consistent, as there is no choice but to transpose the indices for per-atom or local array data. See the similar note under extract_atom() for further details.


function  extract_variable(name[, group])

This function calls lammps_extract_variable() and returns a scalar, vector, or string containing the value of the variable identified by name. When the variable is an equal-style variable (or one compatible with that style such as internal), the variable is evaluated and the corresponding value returned. When the variable is an atom-style variable, the variable is evaluated and a vector of values is returned. With all other variables, a string is returned. The group argument is only used for atom style variables and is ignored otherwise. If group is absent for atom-style variables, the group is assumed to be “all”.

New in version 3Nov2022.

This function returns the values of the variables, not pointers to them. Vectors pointing to atom-style variables should be of type REAL(c_double), be of rank 1 (i.e., DIMENSION(:)), and have the ALLOCATABLE attribute.

Note

Unlike the C library interface, the Fortran interface does not require you to deallocate memory when you are through; this is done for you, behind the scenes.

For example,

TYPE(lammps) :: lmp
REAL(c_double) :: area
! more code to set up, etc.
lmp%command('variable A equal lx*ly')
! more code
area = lmp%extract_variable("A")

will extract the xy cross-sectional area of the simulation into the variable area.

Parameters:

name [character(len=*)] :: variable name to evaluate

Options:

group [character(len=*),optional] :: group for which to extract per-atom data (if absent, use “all”)

Call to:

lammps_extract_variable()

Return:

data [polymorphic] :: scalar of type REAL(c_double) (for equal-style variables and others that are equal-compatible), vector of type REAL(c_double), DIMENSION(:), ALLOCATABLE for atom- or vector-style variables, or CHARACTER(LEN=*) for string-style and compatible variables. Strings whose length is too short to hold the result will be truncated. Allocatable strings must be allocated before this function is called; see note at extract_global() regarding allocatable strings. Allocatable arrays (for atom- and vector-style data) will be reallocated on assignment.

Note

LAMMPS cannot easily check if it is valid to access the data referenced by the variables (e.g., computes, fixes, or thermodynamic info), so it may fail with an error. The caller has to make certain that the data are extracted only when it is safe to evaluate the variable and thus an error and crash are avoided.


subroutine  gather_atoms(name, count, data)

This function calls lammps_gather_atoms() to gather the named atom-based entity for all atoms on all processors and return it in the vector data. The vector data will be ordered by atom ID, which requires consecutive atom IDs (1 to natoms).

New in version 3Nov2022.

If you need a similar array but have non-consecutive atom IDs, see gather_atoms_concat(); for a similar array but for a subset of atoms, see gather_atoms_subset().

The data array will be ordered in groups of count values, sorted by atom ID (e.g., if name is x and count = 3, then data = x[1][1], x[2][1], x[3][1], x[1][2], x[2][2], x[3][2], x[1][3], \(\dots\)); data must be ALLOCATABLE and will be allocated to length (count \(\times\) natoms), as queried by extract_setting().

Parameters:
  • name [character(len=*)] :: desired quantity (e.g., x or mask)

  • count [integer(c_int)] :: number of per-atom values you expect per atom (e.g., 1 for type, mask, or charge; 3 for x, v, or f). Use count = 3 with image if you want a single image flag unpacked into x/y/z components.

  • data [real(c_double),dimension(:),allocatable] :: array into which to store the data. Array must have the ALLOCATABLE attribute and be of rank 1 (i.e., DIMENSION(:)). If this array is already allocated, it will be reallocated to fit the length of the incoming data.

Call to:

lammps_gather_atoms()

Note

If you want data from this function to be accessible as a two-dimensional array, you can declare a rank-2 pointer and reassign it, like so:

USE, INTRINSIC :: ISO_C_BINDING
USE LIBLAMMPS
TYPE(lammps) :: lmp
REAL(c_double), DIMENSION(:), ALLOCATABLE, TARGET :: xdata
REAL(c_double), DIMENSION(:,:), POINTER :: x
! other code to set up, etc.
CALL lmp%gather_atoms('x',3,xdata)
x(1:3,1:size(xdata)/3) => xdata

You can then access the y-component of atom 3 with x(2,3). See the note about array index order at extract_atom().


subroutine  gather_atoms_concat(name, count, data)

This function calls lammps_gather_atoms_concat() to gather the named atom-based entity for all atoms on all processors and return it in the vector data.

New in version 3Nov2022.

The vector data will not be ordered by atom ID, and there is no restriction on the IDs being consecutive. If you need the IDs, you can do another gather_atoms_concat() with name set to id.

If you need a similar array but have consecutive atom IDs, see gather_atoms(); for a similar array but for a subset of atoms, see gather_atoms_subset().

Parameters:
  • name [character(len=*)] :: desired quantity (e.g., x or mask)

  • count [integer(c_int)] :: number of per-atom values you expect per atom (e.g., 1 for type, mask, or charge; 3 for x, v, or f). Use count = 3 with image if you want a single image flag unpacked into x/y/z components.

  • data [real(c_double),dimension(:),allocatable] :: array into which to store the data. Array must have the ALLOCATABLE attribute and be of rank 1 (i.e., DIMENSION(:)). If this array is already allocated, it will be reallocated to fit the length of the incoming data.

Call to:

lammps_gather_atoms_concat()


subroutine  gather_atoms_subset(name, count, ids, data)

This function calls lammps_gather_atoms_subset() to gather the named atom-based entity for the atoms in the array ids from all processors and return it in the vector data.

New in version 3Nov2022.

This subroutine gathers data for the requested atom IDs and stores them in a one-dimensional array allocated by the user. The data will be ordered by atom ID, but there is no requirement that the IDs be consecutive. If you wish to return a similar array for all the atoms, use gather_atoms() or gather_atoms_concat().

The data array will be in groups of count values, sorted by atom ID in the same order as the array ids (e.g., if name is x, count = 3, and ids is [100, 57, 210], then data might look like [x(1,100), x(2,100), x(3,100), x(1,57), x(2,57), x(3,57), x(1,210), \(\dots\)]; ids must be provided by the user, and data must be of rank 1 (i.e., DIMENSION(:)) and have the ALLOCATABLE attribute.

Parameters:
  • name [character(len=*)] :: desired quantity (e.g., x or mask)

  • count [integer(c_int)] :: number of per-atom values you expect per atom (e.g., 1 for type, mask, or charge; 3 for x, v, or f). Use count = 3 with image if you want a single image flag unpacked into x/y/z components.

  • ids [integer(c_int),dimension(:)] :: atom IDs corresponding to the atoms to be gathered

  • data [real(c_double),dimension(:),allocatable] :: array into which to store the data. Array must have the ALLOCATABLE attribute and be of rank 1 (i.e., DIMENSION(:)). If this array is already allocated, it will be reallocated to fit the length of the incoming data.

Call to:

lammps_gather_atoms_subset()


subroutine  scatter_atoms(name, data)

This function calls lammps_scatter_atoms() to scatter the named atom-based entities in data to all processors.

New in version 3Nov2022.

This subroutine takes data stored in a one-dimensional array supplied by the user and scatters them to all atoms on all processors. The data must be ordered by atom ID, with the requirement that the IDs be consecutive. Use scatter_atoms_subset() to scatter data for some (or all) atoms, in any order.

The data array needs to be ordered in groups of count values, sorted by atom ID (e.g., if name is x and count = 3, then data = [x(1,1) x(2,1) x(3,1) x(1,2) x(2,2) x(3,2) x(1,3) \(\dots\)]; data must be of length (count \(\times\) natoms).

Parameters:
  • name [character(len=*)] :: quantity to be scattered (e.g., x or charge)

  • data [polymorphic,dimension(:)] :: per-atom values packed in a one-dimensional array containing the data to be scattered. This array must have length natoms (e.g., for type or charge) or length natoms\(\times 3\) (e.g., for x or f). The array data must be rank 1 (i.e., DIMENSION(:)) and be of type INTEGER(c_int) (e.g., for mask or type) or of type REAL(c_double) (e.g., for x or charge or f).

Call to:

lammps_scatter_atoms()


subroutine  scatter_atoms_subset(name, ids, data)

This function calls lammps_scatter_atoms_subset() to scatter the named atom-based entities in data to all processors.

New in version 3Nov2022.

This subroutine takes data stored in a one-dimensional array supplied by the user and scatters them to a subset of atoms on all processors. The array data contains data associated with atom IDs, but there is no requirement that the IDs be consecutive, as they are provided in a separate array, ids. Use scatter_atoms() to scatter data for all atoms, in order.

The data array needs to be organized in groups of 1 or 3 values, depending on which quantity is being scattered, with the groups in the same order as the array ids. For example, if you want data to be the array [x(1,1) x(2,1) x(3,1) x(1,100) x(2,100) x(3,100) x(1,57) x(2,57) x(3,57)], then ids would be [1 100 57] and name would be x.

Parameters:
  • name [character(len=*)] :: quantity to be scattered (e.g., x or charge)

  • ids [integer(c_int),dimension(:)] :: atom IDs corresponding to the atoms being scattered

  • data [polymorphic,dimension(:)] :: per-atom values packed into a one-dimensional array containing the data to be scattered. This array must have either the same length as ids (for mask, type, etc.) or three times its length (for x, f, etc.); the array must be rank 1 and be of type INTEGER(c_int) (e.g., for mask or type) or of type REAL(c_double) (e.g., for charge, x, or f).

Call to:

lammps_scatter_atoms_subset()


subroutine  gather_bonds(data)

Gather type and constituent atom information for all bonds.

New in version 3Nov2022.

This function copies the list of all bonds into an allocated array. The array will be filled with (bond type, bond atom 1, bond atom 2) for each bond. The array is allocated to the right length (i.e., three times the number of bonds). The array data must be of the same type as the LAMMPS tagint type, which is equivalent to either INTEGER(c_int) or INTEGER(c_int64_t), depending on whether -DLAMMPS_BIGBIG was used when LAMMPS was built. If the supplied array does not match, an error will result at run-time.

An example of how to use this routine is below:

PROGRAM bonds
  USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_int
  USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY : OUTPUT_UNIT
  USE LIBLAMMPS
  IMPLICIT NONE
  INTEGER(c_int), DIMENSION(:), ALLOCATABLE, TARGET :: bonds
  INTEGER(c_int), DIMENSION(:,:), POINTER :: bonds_array
  TYPE(lammps) :: lmp
  INTEGER :: i
  ! other commands to initialize LAMMPS, create bonds, etc.
  CALL lmp%gather_bonds(bonds)
  bonds_array(1:3,1:SIZE(bonds)/3) => bonds
  DO i = 1, SIZE(bonds)/3
    WRITE(OUTPUT_UNIT,'(A,1X,I4,A,I4,1X,I4)') 'bond', bonds(1,i), &
      '; type = ', bonds(2,i), bonds(3,i)
  END DO
END PROGRAM bonds
Parameters:

data [integer(kind=*),allocatable] :: array into which to copy the result. *The KIND parameter is either c_int or, if LAMMPS was compiled with -DLAMMPS_BIGBIG, kind c_int64_t.

Call to:

lammps_gather_bonds()


subroutine  create_atoms([id,] type, x, [v,] [image,] [bexpand])

This method calls lammps_create_atoms() to create additional atoms from a given list of coordinates and a list of atom types. Additionally, the atom IDs, velocities, and image flags may be provided.

New in version 3Nov2022.

Parameters:
  • type [integer(c_int),dimension(N)] :: vector of \(N\) atom types (required/see note below)

  • x [real(c_double),dimension(3N)] :: vector of \(3N\) x/y/z positions of the new atoms, arranged as \([x_1,y_1,z_1,x_2,y_2,\dotsc]\) (required/see note below)

Options:
  • id [integer(kind=*),dimension(N)] :: vector of \(N\) atom IDs; if absent, LAMMPS will generate them for you. *The KIND parameter should be c_int unless LAMMPS was compiled with -DLAMMPS_BIGBIG, in which case it should be c_int64_t.

  • v [real(c_double),dimension(3N)] :: vector of \(3N\) x/y/z velocities of the new atoms, arranged as \([v_{1,x},v_{1,y},v_{1,z},v_{2,x}, \dotsc]\); if absent, they will be set to zero

  • image [integer(kind=*),dimension(N)] :: vector of \(N\) image flags; if absent, they are set to zero. *The KIND parameter should be c_int unless LAMMPS was compiled with -DLAMMPS_BIGBIG, in which case it should be c_int64_t. See note below.

  • bexpand [logical] :: if .TRUE., atoms outside of shrink-wrap boundaries will be created, not dropped, and the box dimensions will be extended. Default is .FALSE.

Call to:

lammps_create_atoms()

Note

The type and x arguments are required, but they are declared OPTIONAL in the module because making them mandatory would require id to be present as well. To have LAMMPS generate the ids for you, use a call something like

lmp%create_atoms(type=new_types, x=new_xs)

Note

When LAMMPS has been compiled with -DLAMMPS_BIGBIG, it is not possible to include the image parameter but omit the id parameter. Either id must be present, or both id and image must be absent. This is required because having all arguments be optional in both generic functions creates an ambiguous interface. This limitation does not exist if LAMMPS was not compiled with -DLAMMPS_BIGBIG.


function  find_pair_neighlist(style[, exact][, nsub][, reqid])

Find index of a neighbor list requested by a pair style.

New in version 3Nov2022.

This function determines which of the available neighbor lists for pair styles matches the given conditions. It first matches the style name. If exact is .TRUE., the name must match exactly; if .FALSE., a regular expression or sub-string match is done. If the pair style is hybrid or hybrid/overlay, the style is matched against the sub-styles instead. If the same pair style is used multiple times as a sub-style, the nsub argument must be \(> 0\); this argument represents the nth instance of the sub-style (same as for the pair_coeff command, for example). In that case, nsub\({} = 0\) will not produce a match, and the function will return \(-1\).

The final condition to be checked is the request ID (reqid). This will usually be zero, but some pair styles request multiple neighbor lists and set the request ID to a value greater than zero.

Parameters:

style [character(len=*)] :: String used to search for pair style instance.

Options:
  • exact [logical] :: Flag to control whether style should match exactly or only a regular expression/sub-string match is applied. Default: .TRUE..

  • nsub [integer(c_int)] :: Match nsubth hybrid sub-style instance of the same style. Default: 0.

  • reqid [integer(c_int)] :: Request ID to identify the neighbor list in case there are multiple requests from the same pair style instance. Default: 0.

Call to:

lammps_find_pair_neighlist()

Return:

index [integer(c_int)] :: Neighbor list index if found, otherwise \(-1\).


function  find_fix_neighlist(id[, reqid])

Find index of a neighbor list requested by a fix.

New in version 3Nov2022.

The neighbor list request from a fix is identified by the fix ID and the request ID. The request ID is typically zero, but will be \(>0\) for fixes with multiple neighbor list requests.

Parameters:

id [character(len=*)] :: Identifier of fix instance

Options:

reqid [integer(c_int)] :: request ID to identify the neighbor list in cases in which there are multiple requests from the same fix. Default: 0.

Call to:

lammps_find_fix_neighlist()

Return:

index [integer(c_int)] :: neighbor list index if found, otherwise \(-1\)


function  find_compute_neighlist(id[, reqid])

Find index of a neighbor list requested by a compute.

New in version 3Nov2022.

The neighbor list request from a compute is identified by the compute ID and the request ID. The request ID is typically zero, but will be \(> 0\) in case a compute has multiple neighbor list requests.

Parameters:

id [character(len=*)] :: Identifier of compute instance.

Options:

reqid [integer(c_int)] :: request ID to identify the neighbor list in cases in which there are multiple requests from the same compute. Default: 0.

Call to:

lammps_find_compute_neighlist()

Return:

index [integer(c_int)] :: neighbor list index if found, otherwise \(-1\).


function  neighlist_num_elements(idx)

Return the number of entries in the neighbor list with the given index.

New in version 3Nov2022.

Parameters:

idx [integer(c_int)] :: neighbor list index

Call to:

lammps_neighlist_num_elements()

Return:

inum [integer(c_int)] :: number of entries in neighbor list, or \(-1\) if idx is not a valid index.


function  version()

This method returns the numeric LAMMPS version like lammps_version() does.

Call to:

lammps_version()

Return:

version [integer] :: LAMMPS version


subroutine  get_os_info(buffer)

This function can be used to retrieve detailed information about the hosting operating system and compiler/runtime environment.

New in version 3Nov2022.

A suitable buffer has to be provided. The assembled text will be truncated so as not to overflow this buffer. The string is typically a few hundred bytes long.

Parameters:

buffer [character(len=*)] :: string that will house the information.

Call to:

lammps_get_os_info()


function  config_has_mpi_support()

This function is used to query whether LAMMPS was compiled with a real MPI library or in serial.

New in version 3Nov2022.

Call to:

lammps_config_has_mpi_support()

Return:

has_mpi [logical] :: .FALSE. when compiled with STUBS, .TRUE. if complied with MPI.


function  config_has_gzip_support()

Check if the LAMMPS library supports reading or writing compressed files via a pipe to gzip or similar compression programs.

New in version 3Nov2022.

Several LAMMPS commands (e.g., read_data command, write_data command, dump styles atom, custom, and xyz) support reading and writing compressed files via creating a pipe to the gzip program. This function checks whether this feature was enabled at compile time. It does not check whether gzip or any other supported compression programs themselves are installed and usable.

Call to:

lammps_config_has_gzip_support()

Return:

has_gzip [logical]


function  config_has_png_support()

Check if the LAMMPS library supports writing PNG format images.

New in version 3Nov2022.

The LAMMPS dump style image supports writing multiple image file formats. Most of them, however, need support from an external library, and using that has to be enabled at compile time. This function checks whether support for the PNG image file format is available in the current LAMMPS library.

Call to:

lammps_config_has_png_support()

Return:

has_png [logical]


function  config_has_jpeg_support()

Check if the LAMMPS library supports writing JPEG format images.

New in version 3Nov2022.

The LAMMPS dump style image supports writing multiple image file formats. Most of them, however, need support from an external library, and using that has to be enabled at compile time. This function checks whether support for the JPEG image file format is available in the current LAMMPS library.

Call to:

lammps_config_has_jpeg_support()

Return:

has_jpeg [logical]


function  config_has_ffmpeg_support()

Check if the LAMMPS library supports creating movie files via a pipe to ffmpeg.

New in version 3Nov2022.

The LAMMPS dump style movie supports generating movies from images on-the-fly via creating a pipe to the ffmpeg program. This function checks whether this feature was enabled at compile time. It does not check whether the ffmpeg itself is installed and usable.

Call to:

lammps_config_has_ffmpeg_support()

Return:

has_ffmpeg [logical]


function  config_has_exceptions()

Check whether LAMMPS errors will throw C++ exceptions.

New in version 3Nov2022.

In case of an error, LAMMPS will either abort or throw a C++ exception. The latter has to be enabled at compile time. This function checks if exceptions were enabled.

When using the library interface with C++ exceptions enabled, the library interface functions will “catch” them, and the error status can then be checked by calling has_error(). The most recent error message can be retrieved via get_last_error_message(). This can allow one to restart a calculation or delete and recreate the LAMMPS instance when a C++ exception occurs. One application of using exceptions this way is the LAMMPS shell. If C++ exceptions are disabled and an error happens during a call to LAMMPS or the Fortran API, the application will terminate.

Call to:

lammps_config_has_exceptions()

Return:

has_exceptions [logical]


function  config_has_package(name)

Check whether a specific package has been included in LAMMPS

New in version 3Nov2022.

This function checks whether the LAMMPS library in use includes the specific LAMMPS package provided as argument.

Call to:

lammps_config_has_package()

Return:

has_package [logical]


function  config_package_count()

Count the number of installed packages in the LAMMPS library.

New in version 3Nov2022.

This function counts how many LAMMPS packages are included in the LAMMPS library in use. It directly calls the C library function lammps_config_package_count().

Call to:

lammps_config_package_count()

Return:

npackages [integer(c_int)] :: number of packages installed


subroutine  config_package_name(idx, buffer)

Get the name of a package in the list of installed packages in the LAMMPS library.

New in version 3Nov2022.

This subroutine copies the name of the package with the index idx into the provided string buffer. If the name of the package exceeds the length of the buffer, it will be truncated accordingly. If the index is out of range, buffer is set to an empty string.

Parameters:
  • idx [integer(c_int)] :: index of the package in the list of included packages \((0 \le idx < \text{package count})\)

  • buffer [character(len=*)] :: string to hold the name of the package

Call to:

lammps_config_package_name()


subroutine  installed_packages(package[, length])

Obtain a list of the names of enabled packages in the LAMMPS shared library and store it in package.

New in version 3Nov2022.

This function is analogous to the :py:func`installed_packages` function in the Python API. The optional argument length sets the length of each string in the vector package (default: 31).

Parameters:

package [character(len=:),dimension(:),allocatable] :: list of packages; must have the ALLOCATABLE attribute and be of rank 1 (i.e., DIMENSION(:)) with allocatable length.

Options:

length [integer,optional] :: length of each string in the list. Default: 31.

Call to:

lammps_config_package_count() lammps_config_package_name()


function  config_accelerator(package, category, setting)

This function calls lammps_config_accelerator() to check the availability of compile time settings of included accelerator packages in LAMMPS.

New in version 3Nov2022.

Supported packages names are “GPU”, “KOKKOS”, “INTEL”, and “OPENMP”. Supported categories are “api” with possible settings “cuda”, “hip”, “phi”, “pthreads”, “opencl”, “openmp”, and “serial”; and “precision” with possible settings “double”, “mixed”, and “single”.

Parameters:
  • package [character(len=*)] :: string with the name of the accelerator package

  • category [character(len=*)] :: string with the name of the setting

  • setting [character(len=*)] :: string with the name of the specific setting

Call to:

lammps_config_accelerator()

Return:

available [logical] :: .TRUE. if the combination of package, category, and setting is available, otherwise .FALSE..


function  has_gpu_device()

Checks for the presence of a viable GPU package device.

New in version 3Nov2022.

This function calls lammps_has_gpu_device(), which checks at runtime whether an accelerator device is present that can be used with the GPU package.

More detailed information about the available device or devices can be obtained by calling the get_gpu_device_info() subroutine.

Call to:

lammps_has_gpu_device()

Return:

available [logical] :: .TRUE. if a viable device is available, .FALSE. if not.


subroutine  get_gpu_device_info(buffer)

Get GPU package device information.

New in version 3Nov2022.

Calls lammps_get_gpu_device_info() to retrieve detailed information about any accelerator devices that are viable for use with the GPU package. It will fill buffer with a string that is equivalent to the output of the nvc_get_device or ocl_get_device or hip_get_device tools that are compiled alongside LAMMPS if the GPU package is enabled.

A suitable-length Fortran string has to be provided. The assembled text will be truncated so as not to overflow this buffer. This string can be several kilobytes long if multiple devices are present.

Parameters:

buffer [character(len=*)] :: string into which to copy the information.

Call to:

lammps_get_gpu_device_info()


function  has_style(category, name)

Check whether a specific style has been included in LAMMPS.

New in version 3Nov2022.

This function calls lammps_has_style() to check whether the LAMMPS library in use includes the specific style name associated with a specific category provided as arguments. Please see lammps_has_style() for a list of valid categories.

Parameters:
  • category [character(len=*)] :: category of the style

  • name [character(len=*)] :: name of the style

Call to:

lammps_has_style()

Return:

has_style [logical] :: .TRUE. if included, .FALSE. if not.


function  style_count(category)

Count the number of styles of category in the LAMMPS library.

New in version 3Nov2022.

This function counts how many styles in the provided category are included in the LAMMPS library currently in use. Please see lammps_has_style() for a list of valid categories.

Parameters:

category [character(len=*)] :: category of styles to count

Call to:

lammps_style_count()

Return:

count [integer(c_int)] :: number of styles in category


subroutine  style_name(category, idx, buffer)

Look up the name of a style by index in the list of styles of a given category in the LAMMPS library.

New in version 3Nov2022.

This function calls lammps_style_name() and copies the name of the category style with index idx into the provided string buffer. The length of buffer must be long enough to contain the name of the style; if it is too short, the name will be truncated accordingly. If idx is out of range, buffer will be the empty string and a warning will be issued.

Parameters:
  • category [character(len=*)] :: category of styles

  • idx [integer(c_int)] :: index of the style in the list of category styles \((1 \leq idx \leq \text{style count})\)

  • buffer [character(len*)] :: string buffer to copy the name of the style into

Call to:

lammps_style_name()


function  has_id(category, name)

This function checks if the current LAMMPS instance a category ID of the given name exists. Valid categories are: compute, dump, fix, group, molecule, region, and variable.

New in version 3Nov2022.

Parameters:
  • category [character(len=*)] :: category of the ID

  • name [character(len=*)] :: name of the ID

Call to:

lammps_has_id()

Return:

has_id [logical] :: .TRUE. if category style name exists, .FALSE. if not.


function  id_count(category)

This function counts how many IDs in the provided category are defined in the current LAMMPS instance. Please see has_id() for a list of valid categories.

New in version 3Nov2022.

Parameters:

category [character(len=*)] :: category of the ID

Call to:

lammps_id_count()

Return:

count [integer(c_int)] :: number of IDs in category


subroutine  id_name(category, idx, buffer)

Look up the name of an ID by index in the list of IDs of a given category.

New in version 3Nov2022.

This function copies the name of the category ID with the index idx into the provided string buffer. The length of the buffer must be long enough to hold the string; if the name of the style exceeds the length of the buffer, it will be truncated accordingly. If buffer is ALLOCATABLE, it must be allocated before the function is called. If idx is out of range, buffer is set to an empty string and a warning is issued.

Parameters:
  • category [character(len=*)] :: category of IDs

  • idx [integer(c_int)] :: index of the ID in the list of category styles (\(0 \leq idx < count\))

  • buffer [character(len=*)] :: string into which to copy the name of the style

Call to:

lammps_id_name()


function  plugin_count()

This function counts the number of loaded plugins.

New in version 3Nov2022.

Call to:

lammps_plugin_count()

Return:

n [integer(c_int)] :: number of loaded plugins


subroutine  plugin_name(idx, stylebuf, namebuf)

Look up the style and name of a plugin by its index in the list of plugins.

New in version 3Nov2022.

This function copies the name of the style plugin with the index idx into the provided C-style string buffer. The length of the buffer must be provided as buf_size argument. If the name of the style exceeds the length of the buffer, it will be truncated accordingly. If the index is out of range, both strings are set to the empty string and a warning is printed.

Parameters:
  • idx [integer(c_int)] :: index of the plugin in the list all or style plugins

  • stylebuf [character(len=*)] :: string into which to copy the style of the plugin

  • namebuf [character(len=*)] :: string into which to copy the style of the plugin

Call to:

lammps_plugin_name()


function  encode_image_flags(ix, iy, iz)

Encodes three integer image flags into a single imageint.

New in version 3Nov2022.

This function performs the bit-shift, addition, and bit-wise OR operations necessary to combine the values of three integers representing the image flags in the \(x\)-, \(y\)-, and \(z\)-directions. Unless LAMMPS is compiled with -DLAMMPS_BIGBIG, those integers are limited to 10-bit signed integers \([-512,512]\). If -DLAMMPS_BIGBIG was used when compiling, then the return value is of kind c_int64_t instead of kind c_int, and the valid range for the individual image flags becomes \([-1048576,1048575]\) (i.e., the range of a 21-bit signed integer). There is no check on whether the arguments conform to these requirements.

Parameters:
  • ix [integer(c_int)] :: image flag in \(x\)-direction

  • iy [integer(c_int)] :: image flag in \(y\)-direction

  • iz [integer(c_int)] :: image flag in \(z\)-direction

Return:

imageint [integer(kind=*)] :: encoded image flag. *The KIND parameter is c_int unless LAMMPS was built with -DLAMMPS_BIGBIG, in which case it is c_int64_t.

Note

The fact that the programmer does not know the KIND parameter of the return value until compile time means that it is impossible to define an interface that works for both sizes of imageint. One side effect of this is that you must assign the return value of this function to a variable; it cannot be used as the argument to another function or as part of an array constructor. For example,

my_images = [lmp%encode_image_flags(0,0,0), lmp%encode_image_flags(1,0,0)]

will not work; instead, do something like

my_images(1) = lmp%encode_image_flags(0,0,0)
my_images(2) = lmp%encode_image_flags(1,0,0)

subroutine  decode_image_flags(image, flags)

This function does the reverse operation of encode_image_flags(): it takes the image flag and performs the bit-shift and bit-masking operations to decode it and stores the resulting three integers into the array flags.

New in version 3Nov2022.

Parameters:
  • image [integer(kind=*)] :: encoded image flag. *The KIND parameter is either c_int or, if LAMMPS was compiled with -DLAMMPS_BIGBIG, c_int64_t. Kind compatibility is checked at run-time.

  • flags [integer(c_int),dimension(3)] :: three-element vector where the decoded image flags will be stored.


subroutine  flush_buffers()

This function calls lammps_flush_buffers(), which flushes buffered output to be written to screen and logfile. This can simplify capturing output from LAMMPS library calls.

New in version 3Nov2022.

Call to:

lammps_flush_buffers()


function  is_running()

Check if LAMMPS is currently inside a run or minimization.

New in version 3Nov2022.

This function can be used from signal handlers or multi-threaded applications to determine if the LAMMPS instance is currently active.

Call to:

lammps_is_running()

Return:

is_running [logical] :: .FALSE. if idle or .TRUE. if active


subroutine  force_timeout()

Force a timeout to stop an ongoing run cleanly.

New in version 3Nov2022.

This function can be used from signal handlers or multi-threaded applications to cleanly terminate an ongoing run.

Call to:

lammps_force_timeout()


function  has_error()

Check if there is a (new) error message available.

New in version 3Nov2022.

This function can be used to query if an error inside of LAMMPS has thrown a C++ exception.

Note

This function will always report “no error” when the LAMMPS library has been compiled without -DLAMMPS_EXCEPTIONS, which turns fatal errors aborting LAMMPS into C++ exceptions. You can use the library function lammps_config_has_exceptions() to check if this is the case.

Call to:

lammps_has_error()

Return:

has_error [logical] :: .TRUE. if there is an error.


subroutine  get_last_error_message(buffer[, status])

Copy the last error message into the provided buffer.

New in version 3Nov2022.

This function can be used to retrieve the error message that was set in the event of an error inside of LAMMPS that resulted in a C++ exception. A suitable buffer for a string has to be provided. If the internally-stored error message is longer than the string and the string does not have ALLOCATABLE length, it will be truncated accordingly. The optional argument status indicates the kind of error: a “1” indicates an error that occurred on all MPI ranks and is often recoverable, while a “2” indicates an abort that would happen only in a single MPI rank and thus may not be recoverable, as other MPI ranks may be waiting on the failing MPI rank(s) to send messages.

Note

This function will do nothing when the LAMMPS library has been compiled without -DLAMMPS_EXCEPTIONS, which turns errors aborting LAMMPS into C++ exceptions. You can use the function config_has_exceptions() to check whether this is the case.

Parameters:

buffer [character(len=*)] :: string buffer to copy the error message into

Options:

status [integer(c_int),optional] :: 1 when all ranks had the error, 2 on a single-rank error.

Call to:

lammps_get_last_error_message()