ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

remove the obsolete legacy fortran 77 wrapper. update Fortran section of manual.

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-12-23 06:55:01 -05:00
parent ca108c6f69
commit 8a2257f568
6 changed files with 31 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
doc/src/Fortran.rst
View File

@ -5,46 +5,52 @@ The :f:mod:`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.
C++, or Fortran other than those in the C library interface and the
LAMMPS Fortran 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
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
:doc:`link to the LAMMPS library <Build_link>`. A typical command line
for a simple program using the Fortran interface would be:
``fortran/lammps.f90`` *and* with the same compiler used to build the
rest of the Fortran code that interfaces to LAMMPS. 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:
.. code-block:: bash
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 :doc:`was compiled
as a static or dynamic library <Build_link>`.
calling the library *from* an MPI-parallelized program. Otherwise,
using the plain Fortran compiler (gfortran, ifort, flang, etc.) will
suffice, since there are no direct references to MPI library features,
definitions and subroutine calls; MPI communicators are referred to by
their integer index representation as required by the Fortran MPI
interface. It may be necessary to link to additional libraries,
depending on how LAMMPS was configured and whether the LAMMPS library
:doc:`was compiled as a static or dynamic library <Build_link>`.
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 :f:mod:`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.
compiled first, since it provides the :f:mod:`LIBLAMMPS` module that
would need to b 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.
.. versionadded:: 9Oct2020
.. versionchanged:: TBD
.. note::
A contributed 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.
A contributed Fortran interface interface is available in the
``examples/COUPLE/fortran2`` folder. However, since the completion
of the :f:mod:`LIBLAMMPS` module, this interface is now deprecated,
no longer actively maintained and will likely be removed in the
future. Please see the ``README`` file in that folder for more
information about it and how to contact its author and maintainer.
----------

2
examples/COUPLE/README
View File

@ -37,8 +37,6 @@ lammps_quest MD with quantum forces, coupling to Quest DFT code
lammps_spparks grain-growth Monte Carlo with strain via MD,
coupling to SPPARKS kinetic MC code
library collection of useful inter-code communication routines
fortran a simple wrapper on the LAMMPS library API that
can be called from Fortran
fortran2 a more sophisticated wrapper on the LAMMPS library API that
can be called from Fortran
fortran_dftb wrapper written by Nir Goldman (LLNL), as an

11
examples/COUPLE/fortran/README
View File

@ -1,11 +0,0 @@
libfwrapper.c is a C file that wraps a few functions of the LAMMPS
library API in src/library.h so that it can be called from Fortran.
See the couple/simple/simple_f77.f90 program for an example of a Fortran
code that does this.
See the README file in that dir for instructions on how to build a
Fortran code that uses this wrapper and links to the LAMMPS library.
This legacy wrapper is deprecated and will be removed in a future
release of LAMMPS. Please use the Fortran 90 module instead.

102
examples/COUPLE/fortran/libfwrapper.c
View File

@ -1,102 +0,0 @@
/* ----------------------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
https://www.lammps.org/, Sandia National Laboratories
LAMMPS development team: developers@lammps.org
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.
------------------------------------------------------------------------- */
/* libwrapper = fortran wrappers for LAMMPS library functions.
See README for compilation instructions */
#include "mpi.h"
#include "stdio.h"
#include "stdlib.h"
#include "string.h"
#include "stdint.h"
#include "library.h" /* this is a LAMMPS include file */
/* wrapper for creating a lammps instance from fortran.
since fortran has no simple way to emit a C-compatible
argument array, we don't support it. for simplicity,
the address of the pointer to the lammps object is
stored in a 64-bit integer on all platforms. */
void lammps_open_(MPI_Fint *comm, int64_t *ptr)
{
*ptr = (int64_t) lammps_open_fortran(0,NULL,*comm);
}
/* no-MPI version of the wrapper from above. */
void lammps_open_no_mpi_(int64_t *ptr)
{
void *obj;
lammps_open_no_mpi(0,NULL,&obj);
*ptr = (int64_t) obj;
}
/* wrapper for shutting down a lammps instance from fortran. */
void lammps_close_(int64_t *ptr)
{
void *obj;
obj = (void *) *ptr;
lammps_close(obj);
}
/* wrapper for passing an input file to lammps from fortran.
since fortran strings are not zero terminated, we have
to pass the length explicitly and make a copy that is. */
void lammps_file_(int64_t *ptr, char *fname, MPI_Fint *len)
{
void *obj;
char *cpy;
obj = (void *) *ptr;
cpy = (char *)calloc(*len + 1,sizeof(char));
memcpy(cpy,fname,*len);
lammps_file(obj,cpy);
free(cpy);
}
/* wrapper for passing a line input to lammps from fortran.
since fortran strings are not zero terminated, we have
to pass the length explicitly and make a copy that is. */
void lammps_command_(int64_t *ptr, char *line, MPI_Fint *len)
{
void *obj;
char *cpy;
obj = (void *) *ptr;
cpy = (char *)calloc(*len + 1,sizeof(char));
memcpy(cpy,line,*len);
lammps_command(obj,cpy);
free(cpy);
}
/* fortran wrapper to get the number of atoms from lammps.
return values require an interface in fortran, so we
make the wrapper into a procedure. */
void lammps_get_natoms_(int64_t *ptr, MPI_Fint *natoms)
{
void *obj;
obj = (void *) *ptr;
*natoms = lammps_get_natoms(obj);
}

13
examples/COUPLE/simple/README
View File

@ -8,9 +8,8 @@ code to perform a coupled calculation.
simple.cpp is the C++ driver
simple.c is the C driver
simple.f90 is the Fortran driver using the new Fortran module
simple_f77.f90 is the Fortran driver using the legacy Fortran wrapper
The 4 codes do the same thing, so you can compare them to see how to
The 3 codes do the same thing, so you can compare them to see how to
drive LAMMPS from each language. See python/example/simple.py
to do something similar from Python. The new Fortran driver requires
a Fortran module that uses the Fortran 03 ISO_C_BINDING module to
@ -45,12 +44,7 @@ the fortran directory:
mpifort -L${HOME}/lammps/src ../../../fortran/lammps.f90 simple.f90 -llammps -o simpleF
This builds the legacy Fortran wrapper and driver with the LAMMPS library
using the mpifort (Fortran) MPI compiler wrapper (assuming GNU gfortran).
mpifort -std=legacy -L${HOME}/lammps/src ../fortran/libfwrapper.c simple.f90 -llammps -o simpleF77
You then run simpleCC, simpleC, simpleF, or simpleF77 on a parallel machine
You then run simpleCC, simpleC, or simpleF on a parallel machine
on some number of processors Q with 2 arguments:
% mpirun -np Q simpleCC P in.lj
@ -72,8 +66,7 @@ of LAMMPS. You could add any functions you wish to this file to
manipulate LAMMPS data however you wish.
The Fortran driver is using the Fortran 03 module which uses a derived
type with type bound subroutines. Only a small subset of the C library
functions are currently accessible through the Fortran module.
type with type bound subroutines.
The C++ driver does the same thing, except that it instantiates LAMMPS
as an object first. Some of the functions in src/library.cpp can be

125
examples/COUPLE/simple/simple_f77.f90
View File

@ -1,125 +0,0 @@
! LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
! https://www.lammps.org/, Sandia National Laboratories
! LAMMPS development team: developers@lammps.org
!
! 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.
! f_driver = simple example of how an umbrella program
! can invoke LAMMPS as a library on some subset of procs
! Syntax: simpleF P in.lammps
! P = # of procs to run LAMMPS on
! must be <= # of procs the driver code itself runs on
! in.lammps = LAMMPS input script
! See README for compilation instructions
PROGRAM f_driver
IMPLICIT NONE
INCLUDE 'mpif.h'
INTEGER, PARAMETER :: fp=20
INTEGER :: n, narg, ierr, me, nprocs, natoms
INTEGER :: lammps, nprocs_lammps, comm_lammps
INTEGER (kind=8) :: ptr
REAL (kind=8), ALLOCATABLE :: x(:)
REAL (kind=8), PARAMETER :: epsilon=0.1
CHARACTER (len=64) :: arg
CHARACTER (len=1024) :: line
! setup MPI and various communicators
! driver runs on all procs in MPI_COMM_WORLD
! comm_lammps only has 1st P procs (could be all or any subset)
CALL mpi_init(ierr)
narg = command_argument_count()
IF (narg /= 2) THEN
PRINT *, 'Syntax: simpleF P in.lammps'
CALL mpi_abort(MPI_COMM_WORLD,1,ierr)
END IF
CALL mpi_comm_rank(MPI_COMM_WORLD,me,ierr);
CALL mpi_comm_size(MPI_COMM_WORLD,nprocs,ierr);
CALL get_command_argument(1,arg)
READ (arg,'(I10)') nprocs_lammps
IF (nprocs_lammps > nprocs) THEN
IF (me == 0) THEN
PRINT *, 'ERROR: LAMMPS cannot use more procs than available'
CALL mpi_abort(MPI_COMM_WORLD,2,ierr)
END IF
END IF
lammps = 0
IF (me < nprocs_lammps) THEN
lammps = 1
ELSE
lammps = MPI_UNDEFINED
END IF
CALL mpi_comm_split(MPI_COMM_WORLD,lammps,0,comm_lammps,ierr)
! open LAMMPS input script on rank zero
CALL get_command_argument(2,arg)
OPEN(UNIT=fp, FILE=arg, ACTION='READ', STATUS='OLD', IOSTAT=ierr)
IF (ierr /= 0) THEN
PRINT *, 'ERROR: Could not open LAMMPS input script'
CALL mpi_abort(MPI_COMM_WORLD,3,ierr);
END IF
! run the input script thru LAMMPS one line at a time until end-of-file
! driver proc 0 reads a line, Bcasts it to all procs
! (could just send it to proc 0 of comm_lammps and let it Bcast)
! all LAMMPS procs call lammps_command() on the line */
IF (lammps == 1) CALL lammps_open(comm_lammps,ptr)
n = 0
DO
IF (me == 0) THEN
READ (UNIT=fp, FMT='(A)', IOSTAT=ierr) line
n = 0
IF (ierr == 0) THEN
n = LEN(TRIM(line))
IF (n == 0 ) THEN
line = ' '
n = 1
END IF
END IF
END IF
CALL mpi_bcast(n,1,MPI_INTEGER,0,MPI_COMM_WORLD,ierr)
IF (n == 0) EXIT
CALL mpi_bcast(line,n,MPI_CHARACTER,0,MPI_COMM_WORLD,ierr)
IF (lammps == 1) CALL lammps_command(ptr,line,n)
END DO
CLOSE(UNIT=fp)
! run 10 more steps followed by a single step */
IF (lammps == 1) THEN
CALL lammps_command(ptr,'run 10',6)
CALL lammps_get_natoms(ptr,natoms)
print*,'natoms=',natoms
CALL lammps_command(ptr,'run 1',5);
END IF
! free LAMMPS object
IF (lammps == 1) CALL lammps_close(ptr);
! close down MPI
CALL mpi_finalize(ierr)
END PROGRAM f_driver