diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst index aa599a3dbd..2dd04439a1 100644 --- a/doc/src/Fortran.rst +++ b/doc/src/Fortran.rst @@ -3,7 +3,9 @@ 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. +requires a 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. While C libraries have a defined binary interface (ABI) and can thus be used from multiple compiler versions from different vendors for as long @@ -19,12 +21,20 @@ 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. +calling the library from an MPI parallel code. Otherwise, using the +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 shared 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`` 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 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. .. versionadded:: 9Oct2020 @@ -57,9 +67,10 @@ 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: +if it is needed. Similarly, a possible call to +:cpp:func:`lammps_mpi_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 @@ -81,10 +92,10 @@ the optional logical argument set to ``.true.``. Here is a simple example: 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 one to -use the command line to configure accelerator and suffix settings, +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 +from the command line and more. Here is a correspondingly adapted version of the previous example: .. code-block:: fortran @@ -165,6 +176,57 @@ Below is a small demonstration of the uses of the different functions: --------------- +Accessing system properties +=========================== + +The C-library interface allows the :doc:`extraction of different kinds +of information ` about the active simulation +instance and also - in some cases - to apply modifications to it. In +some cases, the C-library interface makes pointers to internal data +structures accessible, thus when accessing them from Fortran, special +care is needed to avoid data corruption and crashes. Thus please see +the documentation of the individual type bound procedures for details. + +Below is an example demonstrating some of the possible uses. + +.. code-block:: fortran + + PROGRAM testprop + USE LIBLAMMPS + USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t + TYPE(lammps) :: lmp + INTEGER(kind=8) :: natoms + REAL(c_double), POINTER :: dt + INTEGER(c_int64_t), POINTER :: ntimestep + REAL(kind=8) :: pe, ke + + lmp = lammps() + CALL lmp%file('in.sysinit') + natoms = INT(lmp%get_natoms(),8) + WRITE(6,'(A,I8,A)') 'Running a simulation with', natoms, ' atoms' + WRITE(6,'(I8,A,I8,A,I3,A)') lmp%extract_setting('nlocal'), ' local and', & + lmp%extract_setting('nghost'), ' ghost atom. ', & + lmp%extract_setting('ntypes'), ' atom types' + + CALL lmp%command('run 2 post no') + dt = lmp%extract_global('dt') + ntimestep = lmp%extract_global('ntimestep') + WRITE(6,'(A,I4,A,F4.1,A)') 'At step:', ntimestep, ' Changing timestep from', dt, ' to 0.5' + dt = 0.5 + CALL lmp%command('run 2 post no') + + WRITE(6,'(A,I4)') '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 + +--------------- + The ``LIBLAMMPS`` module API **************************** @@ -292,7 +354,7 @@ Procedures Bound to the lammps Derived Type This function will call :cpp:func:`lammps_get_natoms` and return the number of atoms in the system. - :r real(C_double): number of atoms + :r real(c_double): number of atoms -------- @@ -302,16 +364,17 @@ Procedures Bound to the lammps Derived Type of the corresponding thermodynamic keyword. :p character(len=\*) name: string with the name of the thermo keyword - :r real(C_double): value of the requested thermo property or 0.0_C_double + :r real(c_double): value of the requested thermo property or `0.0_c_double` -------- .. f:subroutine:: extract_box([boxlo][, boxhi][, xy][, yz][, xz][, pflags][, boxflag]) - This subroutine will call :cpp:func:`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. + This subroutine will call :cpp:func:`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. :o real(c_double) boxlo [dimension(3),optional]: vector in which to store lower-bounds of simulation box @@ -377,17 +440,18 @@ Procedures Bound to the lammps Derived Type .. 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. + 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, + 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, .. code-block:: fortran @@ -398,14 +462,14 @@ Procedures Bound to the lammps Derived Type ! ... [commands to set up LAMMPS/etc.] comm%MPI_VAL = lmp%get_mpi_comm() - should assign an MPI_F08 communicator properly. + should assign an `MPI_F08` communicator properly. -------- .. f:function:: extract_setting(keyword) Query LAMMPS about global settings. See the documentation for the - :c:func:`lammps_extract_setting` function from the C library. + :cpp:func:`lammps_extract_setting` function from the C library. :p character(len=\*) keyword: string containing the name of the thermo keyword :r integer(c_int): value of the queried setting or :math:`-1` if unknown @@ -414,35 +478,36 @@ Procedures Bound to the lammps Derived Type .. f:function:: extract_global(name) - This function calls :c:func:`lammps_extract_global` and returns either a - string or a pointer to internal global LAMMPS data, depending on the data - requested through *name*. + This function calls :cpp:func:`lammps_extract_global` and returns + either a string or a pointer to internal global LAMMPS data, + depending on the data requested through *name*. 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 :doc:`clear` - command has been issued, which wipes out and recreates the contents of - the :cpp:class:`LAMMPS ` class. + 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 :doc:`clear` command has been + issued, which wipes out and recreates the contents of the + :cpp:class:`LAMMPS ` class. For example, .. code-block:: fortran PROGRAM demo - USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_int64_t + USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_int64_t USE LIBLAMMPS TYPE(lammps) :: lmp - INTEGER(C_int), POINTER :: nlocal - INTEGER(C_int64_t), POINTER :: ntimestep + INTEGER(c_int), POINTER :: nlocal + INTEGER(c_int64_t), POINTER :: ntimestep CHARACTER(LEN=10) :: units - REAL(C_double), POINTER :: dt + REAL(c_double), POINTER :: dt lmp = lammps() ! other commands nlocal = lmp%extract_global('nlocal') @@ -457,11 +522,13 @@ Procedures Bound to the lammps Derived Type the size of the current time step, and the units being used into the variables *nlocal*, *ntimestep*, *dt*, and *units*, respectively. - *Note*: if this function 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. + .. note:: + + if this function 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. :p character(len=\*) name: string with the name of the extracted property :r polymorphic: pointer to LAMMPS data. The left-hand side of the assignment @@ -469,11 +536,11 @@ Procedures Bound to the lammps Derived Type pointer (e.g., ``INTEGER (c_int), POINTER :: nlocal``) to the extracted property. If expecting vector data, the pointer should have dimension ":". - .. warning:: +.. warning:: - Modifying the data in the location pointed to by the returned pointer - may lead to inconsistent internal data and thus may cause failures or - crashes or bogus simulations. In general it is thus usually better - to use a LAMMPS input command that sets or changes these parameters. - Those will take care of all side effects and necessary updates of - settings derived from such settings. + Modifying the data in the location pointed to by the returned pointer + may lead to inconsistent internal data and thus may cause failures or + crashes or bogus simulations. In general it is thus usually better + to use a LAMMPS input command that sets or changes these parameters. + Those will take care of all side effects and necessary updates of + settings derived from such settings. diff --git a/doc/src/Library_properties.rst b/doc/src/Library_properties.rst index e023c78185..a5c9c79c64 100644 --- a/doc/src/Library_properties.rst +++ b/doc/src/Library_properties.rst @@ -15,21 +15,21 @@ This section documents the following functions: -------------------- -The library interface allows extraction of different kinds of -information about the active simulation instance and also -modifications to it. This enables combining of a LAMMPS simulation -with other processing and simulation methods computed by the calling -code, or by another code that is coupled to LAMMPS via the library -interface. In some cases the data returned is direct reference to the -original data inside LAMMPS, cast to a void pointer. In that case the -data needs to be cast to a suitable pointer for the calling program to -access it, and you may need to know the correct dimensions and -lengths. This also means you can directly change those value(s) from -the calling program, e.g. to modify atom positions. Of course, this -should be done with care. When accessing per-atom data, please note -that this data is the per-processor **local** data and is indexed -accordingly. Per-atom data can change sizes and ordering at every -neighbor list rebuild or atom sort event as atoms migrate between +The 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. This enables combining of a +LAMMPS simulation with other processing and simulation methods computed +by the calling code, or by another code that is coupled to LAMMPS via +the library interface. In some cases the data returned is direct +reference to the original data inside LAMMPS, cast to a void pointer. +In that case the data needs to be cast to a suitable pointer for the +calling program to access it, and you may need to know the correct +dimensions and lengths. This also means you can directly change those +value(s) from the calling program, e.g. to modify atom positions. Of +course, this should be done with care. When accessing per-atom data, +please note that this data is the per-processor **local** data and is +indexed accordingly. Per-atom data can change sizes and ordering at +every neighbor list rebuild or atom sort event as atoms migrate between sub-domains and processors. .. code-block:: C diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 937836a9b9..aba474d257 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -1094,6 +1094,7 @@ flagHI flaglog flagN flagVF +flang fld floralwhite Florez