1.3.1. The `LIBLAMMPS` Fortran Module¶

The LIBLAMMPS module provides an interface to call LAMMPS from a Fortran code. It is based on the LAMMPS C-library interface and requires a Fortran 2003 compatible compiler to be compiled.

While C libraries have a defined binary interface (ABI) and can thus be used from multiple compiler versions from different vendors for as long as they are compatible with the hosting operating system, the same is not true for Fortran codes. 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 parallel code. Please also note the order of the source files: the lammps.f90 file needs to be compiled first, since it provides the LIBLAMMPS module that is imported by the Fortran code using the interface. A working example code 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 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_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
  TYPE(lammps)     :: lmp       ! derived type to hold LAMMPS instance
  CHARACTER(len=*), DIMENSION(*), PARAMETER :: args = &
      [ 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 shuts down MPI)
  CALL lmp%close(.true.)

END PROGRAM testlib

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 pass individual or multiple commands from strings or lists of strings. This is done similar to how it is implemented in the C-library <pg_lib_execute> 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()

END PROGRAM testcmd

1.3.3. 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 that any of the included calls are forwarded to.

Type fields

% handle [c_ptr] :: reference to the LAMMPS class
% close :: close()
% version :: version()
% file :: file()
% command :: command()
% commands_list :: commands_list()
% commands_string :: commands_string()

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().

Parameters: args (*) [character(len=*),optional] :: arguments as list of strings
Options: comm [integer,optional] :: MPI communicator
Return: lammps :: an instance of 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_mpi_finalize().

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

function version()¶

This method returns the numeric LAMMPS version like lammps_version()

Return: integer :: LAMMPS version

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

subroutine command(cmd)¶

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

Parameters: cmd [character(len=*)] :: single 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=*)] :: list of LAMMPS input lines

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

1.3.1. The LIBLAMMPS Fortran Module¶

1.3.2. Creating or deleting a LAMMPS object¶

Executing LAMMPS commands¶

1.3.3. The LIBLAMMPS module API¶

1.3.1. The `LIBLAMMPS` Fortran Module¶

1.3.3. The `LIBLAMMPS` module API¶