Merge pull request #2325 from akohlmey/fortran-interface

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

``examples/COUPLE/fortran/lammps.f90``.  When linking, you also need to

``fortran/lammps.f90``.  When linking, you also need to

:doc:`link to the LAMMPS library <Build_link>`.  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.

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.

.. versionadded:: 30Sep2020

.. admonition:: 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.

----------

Creating or deleting a LAMMPS object

************************************

With the Fortran interface the creation of a :cpp:class:`LAMMPS

<LAMMPS_NS::LAMMPS>` instance is included in the constructor for

creating the :f:func:`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

:cpp:func:`lammps_open_fortran` or :cpp:func:`lammps_open_no_mpi` from

the C library API to create the class instance.  All arguments are

optional and :cpp:func:`lammps_mpi_init` will be called automatically,

if it is needed.  Similarly, a possible call to :cpp:func:`lammps_finalize`

is integrated into the :f:func:`close` function and triggered with

the optional logical argument set to ``.true.``. Here is a simple example:

.. code-block:: fortran

   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

(:f:func:`file`, :f:func:`command`, :f:func:`commands_list`, and

:f:func:`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:

.. code-block:: fortran

   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

---------------

The ``LIBLAMMPS`` module API

****************************

Below are the detailed descriptions of definitions and interfaces

of the contents of the ``LIBLAMMPS`` Fortran interface to LAMMPS.

.. f:type:: lammps

   Derived type that is the general class of the Fortran interface.

   It holds a reference to the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class instance

   that any of the included calls are forwarded to.

   :f c_ptr handle: reference to the LAMMPS class

   :f close: :f:func:`close`

   :f version: :f:func:`version`

   :f file: :f:func:`file`

   :f command: :f:func:`command`

   :f commands_list: :f:func:`commands_list`

   :f commands_string: :f:func:`commands_string`

.. f:function:: lammps(args[,comm])

   This is the constructor for the Fortran class and will forward

   the arguments to a call to either :cpp:func:`lammps_open_fortran`

   or :cpp:func:`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 :cpp:func:`lammps_open`.

   :p character(len=*) args(*) [optional]: arguments as list of strings

   :o integer comm [optional]: MPI communicator

   :r lammps: an instance of the :f:type:`lammps` derived type

.. f:subroutine:: close([finalize])

   This method will close down the LAMMPS instance through calling

   :cpp:func:`lammps_close`.  If the *finalize* argument is present and

   has a value of ``.true.``, then this subroutine also calls

   :cpp:func:`lammps_mpi_finalize`.

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

.. f:function:: version()

   This method returns the numeric LAMMPS version like :cpp:func:`lammps_version`

   :r integer: LAMMPS version

--------

.. f:subroutine:: file(filename)

   This method will call :cpp:func:`lammps_file` to have LAMMPS read

   and process commands from a file.

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

.. f:subroutine:: command(cmd)

   This method will call :cpp:func:`lammps_command` to have LAMMPS

   execute a single command.

   :p character(len=*) cmd: single LAMMPS command

.. f:subroutine:: commands_list(cmds)

   This method will call :cpp:func:`lammps_commands_list` to have LAMMPS

   execute a list of input lines.

   :p character(len=*) cmd(*): list of LAMMPS input lines

.. f:subroutine:: commands_string(str)

   This method will call :cpp:func:`lammps_commands_string` to have LAMMPS

   execute a block of commands from a string.

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

This directory contains Fortran code which interface LAMMPS as a library

and allows the LAMMPS library interface to be invoked from Fortran codes.

It requires a Fortran compiler that supports the Fortran 2003 standard.

This interface is based on and supersedes the previous Fortran interfaces

in the examples/COUPLE/fortran* folders.  But is fully supported by the

LAMMPS developers and included in the documentation and unit testing.

Details on this Fortran interface and how to build programs using it

are in the manual in the doc/html/pg_fortran.html file.

! -------------------------------------------------------------------------

!   LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator

!   http://lammps.sandia.gov, Sandia National Laboratories

!   Steve Plimpton, sjplimp@sandia.gov

!

!   Copyright (2003) Sandia Corporation.  Under the terms of Contract

!   DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains

!   certain rights in this software.  This software is distributed under

!   the GNU General Public License.

!

!   See the README file in the top-level LAMMPS directory.

! -------------------------------------------------------------------------

!

! Fortran interface to the LAMMPS library implemented as a Fortran 2003

! style module that wraps the C-style library interface in library.cpp

! and library.h using the ISO_C_BINDING module of the Fortran compiler.

!

! Based on the LAMMPS Fortran 2003 module contributed by:

!   Karl D. Hammond <karlh@ugcs.caltech.edu>

!   University of Tennessee, Knoxville (USA), 2012

!

! The Fortran module tries to follow the API of the C-library interface

! closely, but like the Python wrapper it employs an object oriented

! approach.  To accommodate the object oriented approach, all exported

! subroutine and functions have to be implemented in Fortran to then

! call the interfaced C style functions with adapted calling conventions

! as needed.  The C-library interfaced functions retain their names

! starting with "lammps_" while the Fortran versions start with "lmp_".

!

MODULE LIBLAMMPS

  USE, INTRINSIC :: ISO_C_BINDING, ONLY: c_ptr, c_null_ptr, c_loc, &

      c_int, c_char, c_null_char, c_double

  IMPLICIT NONE

  PRIVATE

  PUBLIC :: lammps

  TYPE lammps

      TYPE(c_ptr) :: handle

    CONTAINS

      PROCEDURE :: close              => lmp_close

      PROCEDURE :: file               => lmp_file

      PROCEDURE :: command            => lmp_command

      PROCEDURE :: commands_list      => lmp_commands_list

      PROCEDURE :: commands_string    => lmp_commands_string

      PROCEDURE :: version            => lmp_version

      PROCEDURE :: get_natoms         => lmp_get_natoms

  END TYPE lammps

  INTERFACE lammps

      MODULE PROCEDURE lmp_open

  END INTERFACE lammps

  ! interface definitions for calling functions in library.cpp

  INTERFACE

      FUNCTION lammps_open(argc,argv,comm,handle) &

          BIND(C, name='lammps_open_fortran')

        IMPORT :: c_ptr, c_int

        INTEGER(c_int), VALUE, INTENT(in)     :: argc, comm

        TYPE(c_ptr), DIMENSION(*), INTENT(in) :: argv

        TYPE(c_ptr), INTENT(out)              :: handle

        TYPE(c_ptr)                           :: lammps_open

      END FUNCTION lammps_open

      FUNCTION lammps_open_no_mpi(argc,argv,handle) &

          BIND(C, name='lammps_open_no_mpi')

        IMPORT :: c_ptr, c_int

        INTEGER(c_int), VALUE, INTENT(in)     :: argc

        TYPE(c_ptr), DIMENSION(*), INTENT(in) :: argv

        TYPE(c_ptr), INTENT(out)              :: handle

        TYPE(c_ptr)                           :: lammps_open_no_mpi

      END FUNCTION lammps_open_no_mpi

      SUBROUTINE lammps_close(handle) BIND(C, name='lammps_close')

        IMPORT :: c_ptr

        TYPE(c_ptr), VALUE :: handle

      END SUBROUTINE lammps_close

      SUBROUTINE lammps_mpi_init(handle) BIND(C, name='lammps_mpi_init')

        IMPORT :: c_ptr

        TYPE(c_ptr), VALUE :: handle

      END SUBROUTINE lammps_mpi_init

      SUBROUTINE lammps_mpi_finalize(handle) &

          BIND(C, name='lammps_mpi_finalize')

        IMPORT :: c_ptr

        TYPE(c_ptr), VALUE :: handle

      END SUBROUTINE lammps_mpi_finalize

      SUBROUTINE lammps_file(handle,filename) BIND(C, name='lammps_file')

        IMPORT :: c_ptr

        TYPE(c_ptr), VALUE :: handle

        TYPE(c_ptr), VALUE :: filename

      END SUBROUTINE lammps_file

      SUBROUTINE lammps_command(handle,cmd) BIND(C, name='lammps_command')

        IMPORT :: c_ptr

        TYPE(c_ptr), VALUE :: handle

        TYPE(c_ptr), VALUE :: cmd

      END SUBROUTINE lammps_command

      SUBROUTINE lammps_commands_list(handle,ncmd,cmds) &

          BIND(C, name='lammps_commands_list')

        IMPORT :: c_ptr, c_int

        TYPE(c_ptr), VALUE :: handle

        INTEGER(c_int), VALUE, INTENT(in)     :: ncmd

        TYPE(c_ptr), DIMENSION(*), INTENT(in) :: cmds

      END SUBROUTINE lammps_commands_list

      SUBROUTINE lammps_commands_string(handle,str) &

          BIND(C, name='lammps_commands_string')

        IMPORT :: c_ptr

        TYPE(c_ptr), VALUE :: handle

        TYPE(c_ptr), VALUE :: str

      END SUBROUTINE lammps_commands_string

      SUBROUTINE lammps_free(ptr) BIND(C, name='lammps_free')

        IMPORT :: c_ptr

        TYPE(c_ptr), VALUE :: ptr

      END SUBROUTINE lammps_free

      FUNCTION lammps_version(handle) BIND(C, name='lammps_version')

        IMPORT :: c_ptr, c_int

        TYPE(c_ptr), VALUE :: handle

        INTEGER(c_int) :: lammps_version

      END FUNCTION lammps_version

      FUNCTION lammps_get_natoms(handle) BIND(C, name='lammps_get_natoms')

        IMPORT :: c_ptr, c_double

        TYPE(c_ptr), VALUE :: handle

        REAL(c_double) :: lammps_get_natoms

      END FUNCTION lammps_get_natoms

  END INTERFACE

CONTAINS

  ! Fortran wrappers and helper functions.

  ! Constructor for the LAMMPS class.

  ! Combined wrapper around lammps_open_fortran() and lammps_open_no_mpi()

  TYPE(lammps) FUNCTION lmp_open(args,comm)

    IMPLICIT NONE

    INTEGER,INTENT(in), OPTIONAL :: comm

    CHARACTER(len=*), INTENT(in), OPTIONAL :: args(:)

    TYPE(c_ptr), ALLOCATABLE     :: argv(:)

    TYPE(c_ptr)                  :: dummy=c_null_ptr

    INTEGER :: i,argc

    IF (PRESENT(args)) THEN

        ! convert argument list to c style

        argc = SIZE(args)

        ALLOCATE(argv(argc))

        DO i=1,argc

           argv(i) = f2c_string(args(i))

        END DO

    ELSE

        argc = 1

        ALLOCATE(argv(1))

        argv(1) = f2c_string("liblammps")

    ENDIF

    IF (PRESENT(comm)) THEN

        lmp_open%handle = lammps_open(argc,argv,comm,dummy)

    ELSE

        lmp_open%handle = lammps_open_no_mpi(argc,argv,dummy)

    END IF

    ! Clean up allocated memory

    DO i=1,argc

        CALL lammps_free(argv(i))

    END DO

    DEALLOCATE(argv)

  END FUNCTION lmp_open

  ! Combined Fortran wrapper around lammps_close() and lammps_mpi_finalize()

  SUBROUTINE lmp_close(self,finalize)

    IMPLICIT NONE

    CLASS(lammps) :: self

    LOGICAL,INTENT(in),OPTIONAL :: finalize

    CALL lammps_close(self%handle)

    IF (PRESENT(finalize)) THEN

        IF (finalize) THEN

            CALL lammps_mpi_finalize(self%handle)

        END IF

    END IF

  END SUBROUTINE lmp_close

  INTEGER FUNCTION lmp_version(self)

    IMPLICIT NONE

    CLASS(lammps) :: self

    lmp_version = lammps_version(self%handle)

  END FUNCTION lmp_version

  DOUBLE PRECISION FUNCTION lmp_get_natoms(self)

    IMPLICIT NONE

    CLASS(lammps) :: self

    lmp_get_natoms = lammps_get_natoms(self%handle)

  END FUNCTION lmp_get_natoms

  SUBROUTINE lmp_file(self,filename)

    IMPLICIT NONE

    CLASS(lammps) :: self

    CHARACTER(len=*) :: filename

    TYPE(c_ptr) :: str

    str = f2c_string(filename)

    CALL lammps_file(self%handle,str)

    CALL lammps_free(str)

  END SUBROUTINE lmp_file

  ! equivalent function to lammps_command()

  SUBROUTINE lmp_command(self,cmd)

    IMPLICIT NONE

    CLASS(lammps) :: self

    CHARACTER(len=*) :: cmd

    TYPE(c_ptr) :: str

    str = f2c_string(cmd)

    CALL lammps_command(self%handle,str)

    CALL lammps_free(str)

  END SUBROUTINE lmp_command

  ! equivalent function to lammps_commands_list()

  SUBROUTINE lmp_commands_list(self,cmds)

    IMPLICIT NONE

    CLASS(lammps) :: self

    CHARACTER(len=*), INTENT(in), OPTIONAL :: cmds(:)

    TYPE(c_ptr), ALLOCATABLE     :: cmdv(:)

    INTEGER :: i,ncmd

    ! convert command list to c style

    ncmd = SIZE(cmds)

    ALLOCATE(cmdv(ncmd))

    DO i=1,ncmd

        cmdv(i) = f2c_string(cmds(i))

    END DO

    CALL lammps_commands_list(self%handle,ncmd,cmdv)

    ! Clean up allocated memory

    DO i=1,ncmd

        CALL lammps_free(cmdv(i))

    END DO

    DEALLOCATE(cmdv)

  END SUBROUTINE lmp_commands_list

  ! equivalent function to lammps_commands_string()

  SUBROUTINE lmp_commands_string(self,str)

    IMPLICIT NONE

    CLASS(lammps) :: self

    CHARACTER(len=*) :: str

    TYPE(c_ptr) :: tmp

    tmp = f2c_string(str)

    CALL lammps_commands_string(self%handle,tmp)

    CALL lammps_free(tmp)

  END SUBROUTINE lmp_commands_string

  ! ----------------------------------------------------------------------

  ! local helper functions

  ! copy fortran string to zero terminated c string

  FUNCTION f2c_string(f_string) RESULT(ptr)

    CHARACTER (len=*), INTENT(in)           :: f_string

    CHARACTER (len=1, kind=c_char), POINTER :: c_string(:)

    TYPE(c_ptr) :: ptr

    INTEGER :: i, n

    n = LEN_TRIM(f_string)

    ALLOCATE(c_string(n+1))

    DO i=1,n

        c_string(i) = f_string(i:i)

    END DO

    c_string(n+1) = c_null_char

    ptr = c_loc(c_string(1))

  END FUNCTION f2c_string

END MODULE LIBLAMMPS

// functions and avoid compiler warnings about variable tracking.

// Disable for broken -D_FORTIFY_SOURCE feature.

#if defined(_FORTIFY_SOURCE) && (_FORTIFY_SOURCE > 0)

#define _noopt

#elif defined(__clang__)

#if defined(__clang__)

#  define _noopt __attribute__((optnone))

#elif defined(__INTEL_COMPILER)

#  define _noopt

#elif defined(__GNUC__)

#  if (__GNUC__ > 4) || ((__GNUC__ == 4) && (__GNUC_MINOR__ >= 9))

#    if defined(_FORTIFY_SOURCE) && (_FORTIFY_SOURCE > 0)

#      define _noopt __attribute__((optimize("no-var-tracking-assignments")))

#    else

#      define _noopt __attribute__((optimize("O0","no-var-tracking-assignments")))

#    endif

#  else

#    if defined(_FORTIFY_SOURCE) && (_FORTIFY_SOURCE > 0)

#      define _noopt

#    else

#      define _noopt __attribute__((optimize("O0")))

#    endif

#  endif

#else

#  define _noopt

#endif

add_subdirectory(commands)

add_subdirectory(c-library)

add_subdirectory(cplusplus)

add_subdirectory(fortran)

add_subdirectory(python)

add_subdirectory(force-styles)