From 8a2257f5689e4f3d554dacfba58237d38bdecbd1 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Fri, 23 Dec 2022 06:55:01 -0500 Subject: [PATCH] remove the obsolete legacy fortran 77 wrapper. update Fortran section of manual. --- doc/src/Fortran.rst | 50 ++++++----- examples/COUPLE/README | 2 - examples/COUPLE/fortran/README | 11 --- examples/COUPLE/fortran/libfwrapper.c | 102 --------------------- examples/COUPLE/simple/README | 13 +-- examples/COUPLE/simple/simple_f77.f90 | 125 -------------------------- 6 files changed, 31 insertions(+), 272 deletions(-) delete mode 100644 examples/COUPLE/fortran/README delete mode 100644 examples/COUPLE/fortran/libfwrapper.c delete mode 100644 examples/COUPLE/simple/simple_f77.f90 diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst index 98e6194861..3cfd41c9cd 100644 --- a/doc/src/Fortran.rst +++ b/doc/src/Fortran.rst @@ -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 `. 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 `. 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 `. +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 `. 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. ---------- diff --git a/examples/COUPLE/README b/examples/COUPLE/README index d1e8f01c60..6dd3ddf100 100644 --- a/examples/COUPLE/README +++ b/examples/COUPLE/README @@ -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 diff --git a/examples/COUPLE/fortran/README b/examples/COUPLE/fortran/README deleted file mode 100644 index f5a1dd873a..0000000000 --- a/examples/COUPLE/fortran/README +++ /dev/null @@ -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. diff --git a/examples/COUPLE/fortran/libfwrapper.c b/examples/COUPLE/fortran/libfwrapper.c deleted file mode 100644 index 6c44906a59..0000000000 --- a/examples/COUPLE/fortran/libfwrapper.c +++ /dev/null @@ -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); -} - diff --git a/examples/COUPLE/simple/README b/examples/COUPLE/simple/README index 61ee0c324e..2ab0407dea 100644 --- a/examples/COUPLE/simple/README +++ b/examples/COUPLE/simple/README @@ -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 diff --git a/examples/COUPLE/simple/simple_f77.f90 b/examples/COUPLE/simple/simple_f77.f90 deleted file mode 100644 index ac1c03f061..0000000000 --- a/examples/COUPLE/simple/simple_f77.f90 +++ /dev/null @@ -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