1LAMMPS.F90 defines a Fortran 2003 module, LAMMPS, which wraps all functions in 2src/library.h so they can be used directly from Fortran-encoded programs. 3 4All functions in src/library.h that use and/or return C-style pointers have 5Fortran wrapper functions that use Fortran-style arrays, pointers, and 6strings; all C-style memory management is handled internally with no user 7intervention. See --USE-- for notes on how this interface differs from the 8C interface (and the Python interface). 9 10This interface was created by Karl Hammond who you can contact with 11questions: 12 13Karl D. Hammond 14University of Tennessee, Knoxville 15karlh at ugcs.caltech.edu 16karlh at utk.edu 17 18------------------------------------- 19 20--COMPILATION-- 21 22First, be advised that mixed-language programming is not trivial. It requires 23you to link in the required libraries of all languages you use (in this case, 24those for Fortran, C, and C++), as well as any other libraries required. 25You are also advised to read the --USE-- section below before trying to 26compile. 27 28The following steps will work to compile this module (replace ${LAMMPS_SRC} 29with the path to your LAMMPS source directory). 30 31Steps 3-5 are accomplished, possibly after some modifications to 32the makefile, by make using the attached makefile. Said makefile also builds 33the dynamically-linkable library (liblammps_fortran.so). 34 35** STATIC LIBRARY INSTRUCTIONS ** 36 (1) Compile LAMMPS as a static library. 37 Call the resulting file ${LAMMPS_LIB}, which will have an actual name 38 like liblmp_openmpi.a. If compiling using the MPI stubs in 39 ${LAMMPS_SRC}/STUBS, you will need to know where libmpi_stubs.a 40 is as well (I'll call it ${MPI_STUBS} hereafter) 41 (2) Copy said library to your Fortran program's source directory or replace 42 ${LAMMPS_LIB} with its full path in the instructions below. 43 (3) Compile (but don't link!) LAMMPS.F90. Example: 44 mpif90 -c LAMMPS.f90 45 OR 46 gfortran -c LAMMPS.F90 47 NOTE: you may get a warning such as, 48 subroutine lammps_open_wrapper (argc, argv, communicator, ptr) & 49 Variable 'communicator' at (1) is a parameter to the BIND(C) 50 procedure 'lammps_open_wrapper' but may not be C interoperable 51 This is normal (see --IMPLEMENTATION NOTES--). 52 53 (4) Compile (but don't link) LAMMPS-wrapper.cpp. You will need its header 54 file as well. You will have to provide the locations of LAMMPS's 55 header files. For example, 56 mpicxx -c -I${LAMMPS_SRC} LAMMPS-wrapper.cpp 57 OR 58 g++ -c -I${LAMMPS_SRC} -I${LAMMPS_SRC}/STUBS LAMMPS-wrapper.cpp 59 OR 60 icpc -c -I${LAMMPS_SRC} -I${LAMMPS_SRC}/STUBS LAMMPS-wrapper.cpp 61 (5) OPTIONAL: Make a library from the object files so you can carry around 62 two files instead of three. Example: 63 ar rs liblammps_fortran.a LAMMPS.o LAMMPS-wrapper.o 64 This will create the file liblammps_fortran.a that you can use in place 65 of "LAMMPS.o LAMMPS-wrapper.o" later. Note that you will still 66 need to have the .mod file from part (3). 67 68 It is also possible to add LAMMPS.o and LAMMPS-wrapper.o into the 69 LAMMPS library (e.g., liblmp_openmpi.a) instead of creating a separate 70 library, like so: 71 ar rs ${LAMMPS_LIB} LAMMPS.o LAMMPS-wrapper.o 72 In this case, you can now use the Fortran wrapper functions as if they 73 were part of the usual LAMMPS library interface (if you have the module 74 file visible to the compiler, that is). 75 (6) Compile (but don't link) your Fortran program. Example: 76 mpif90 -c myfreeformatfile.f90 77 mpif90 -c myfixedformatfile.f 78 OR 79 gfortran -c myfreeformatfile.f90 80 gfortran -c myfixedformatfile.f 81 The object files generated by these steps are collectively referred to 82 as ${my_object_files} in the next step(s). 83 84 IMPORTANT: If the Fortran module from part (3) is not in the current 85 directory or in one searched by the compiler for module files, you will 86 need to include that location via the -I flag to the compiler, like so: 87 mpif90 -I${LAMMPS_SRC}/examples/COUPLE/fortran2 -c myfreeformatfile.f90 88 89 (7) Link everything together, including any libraries needed by LAMMPS (such 90 as the C++ standard library, the C math library, the JPEG library, fftw, 91 etc.) For example, 92 mpif90 LAMMPS.o LAMMPS-wrapper.o ${my_object_files} \ 93 ${LAMMPS_LIB} -lmpi_cxx -lstdc++ -lm 94 OR 95 gfortran LAMMPS.o LAMMPS-wrapper.o ${my_object_files} \ 96 ${LAMMPS_LIB} ${MPI_STUBS} -lstdc++ -lm 97 OR 98 ifort LAMMPS.o LAMMPS-wrapper.o ${my_object_files} \ 99 ${LAMMPS_LIB} ${MPI_STUBS} -cxxlib -lm 100 Any other required libraries (e.g. -ljpeg, -lfftw) should be added to 101 the end of this line. 102 103You should now have a working executable. 104 105** DYNAMIC LIBRARY INSTRUCTIONS ** 106 (1) Compile LAMMPS as a dynamic library 107 (make makeshlib && make -f Makefile.shlib [targetname]). 108 (2) Compile, but don't link, LAMMPS.F90 using the -fPIC flag, such as 109 mpif90 -fPIC -c LAMMPS.f90 110 (3) Compile, but don't link, LAMMPS-wrapper.cpp in the same manner, e.g. 111 mpicxx -fPIC -c LAMMPS-wrapper.cpp 112 (4) Make the dynamic library, like so: 113 mpif90 -fPIC -shared -o liblammps_fortran.so LAMMPS.o LAMMPS-wrapper.o 114 (5) Compile your program, such as, 115 mpif90 -I${LAMMPS_SRC}/examples/COUPLE/fortran2 -c myfreeformatfile.f90 116 where ${LAMMPS_SRC}/examples/COUPLE/fortran2 contains the .mod file from 117 step (3) 118 (6) Link everything together, such as 119 mpif90 ${my_object_files} -L${LAMMPS_SRC} \ 120 -L${LAMMPS_SRC}/examples/COUPLE/fortran2 -llammps_fortran \ 121 -llammps_openmpi -lmpi_cxx -lstdc++ -lm 122 123If you wish to avoid the -L flags, add the directories containing your 124shared libraries to the LIBRARY_PATH environment variable. At run time, you 125will have to add these directories to LD_LIBRARY_PATH as well; otherwise, 126your executable will not find the libraries it needs. 127 128------------------------------------- 129 130--USAGE-- 131 132To use this API, your program unit (PROGRAM/SUBROUTINE/FUNCTION/MODULE/etc.) 133should look something like this: 134 program call_lammps 135 use LAMMPS 136 ! Other modules, etc. 137 implicit none 138 type (lammps_instance) :: lmp ! This is a pointer to your LAMMPS instance 139 real (C_double) :: fix 140 real (C_double), dimension(:), pointer :: fix2 141 ! Rest of declarations 142 call lammps_open_no_mpi ('lmp -in /dev/null -screen out.lammps',lmp) 143 ! Set up rest of program here 144 call lammps_file (lmp, 'in.example') 145 call lammps_extract_fix (fix, lmp, '2', 0, 1, 1, 1) 146 call lammps_extract_fix (fix2, lmp, '4', 0, 2, 1, 1) 147 call lammps_close (lmp) 148 end program call_lammps 149 150Important notes: 151 * Though I dislike the use of pointers, they are necessary when communicating 152 with C and C++, which do not support Fortran's ALLOCATABLE attribute. 153 * There is no need to deallocate C-allocated memory; this is done for you in 154 the cases when it is done (which are all cases when pointers are not 155 accepted, such as global fix data) 156 * All arguments which are char* variables in library.cpp are character (len=*) 157 variables here. For example, 158 call lammps_command (lmp, 'units metal') 159 will work as expected. 160 * The public functions (the only ones you can use) have interfaces as 161 described in the comments at the top of LAMMPS.F90. They are not always 162 the same as those in library.h, since C strings are replaced by Fortran 163 strings and the like. 164 * The module attempts to check whether you have done something stupid (such 165 as assign a 2D array to a scalar), but it's not perfect. For example, the 166 command 167 call lammps_extract_global (nlocal, ptr, 'nlocal') 168 will give nlocal correctly if nlocal is a pointer to type INTEGER, but it 169 will give the wrong answer if nlocal is a pointer to type REAL. This is a 170 feature of the (void*) type cast in library.cpp. There is no way I can 171 check this for you! It WILL catch you if you pass it an allocatable or 172 fixed-size array when it expects a pointer. 173 * Arrays constructed from temporary data from LAMMPS are ALLOCATABLE, and 174 represent COPIES of data, not the originals. Functions like 175 lammps_extract_atom, which return actual LAMMPS data, are pointers. 176 * IMPORTANT: Due to the differences between C and Fortran arrays (C uses 177 row-major vectors, Fortran uses column-major vectors), all arrays returned 178 from LAMMPS have their indices swapped. 179 * An example of a complete program, simple.f90, is included with this 180 package. 181 182------------------------------------- 183 184--TROUBLESHOOTING-- 185 186Compile-time errors (when compiling LAMMPS.F90, that is) probably indicate 187that your compiler is not new enough to support Fortran 2003 features. For 188example, GCC 4.1.2 will not compile this module, but GCC 4.4.0 will. 189 190If your compiler balks at 'use, intrinsic :: ISO_C_binding,' try removing the 191intrinsic part so it looks like an ordinary module. However, it is likely 192that such a compiler will also have problems with everything else in the 193file as well. 194 195If you get a segfault as soon as the lammps_open call is made, check that you 196compiled your program AND LAMMPS-wrapper.cpp using the same MPI headers. Using 197the stubs for one and the actual MPI library for the other will cause Bad 198Things to happen. 199 200If you find run-time errors, please pass them along via the LAMMPS Users 201mailing list (please CC me as well; address above). Please provide a minimal 202working example along with the names and versions of the compilers you are 203using. Please make sure the error is repeatable and is in MY code, not yours 204(generating a minimal working example will usually ensure this anyway). 205 206------------------------------------- 207 208--IMPLEMENTATION NOTES-- 209 210The Fortran procedures have the same names as the C procedures, and 211their purpose is the same, but they may take different arguments. Here are 212some of the important differences: 213 * lammps_open and lammps_open_no_mpi take a string instead of argc and 214 argv. This is necessary because C and C++ have a very different way 215 of treating strings than Fortran. If you want the command line to be 216 passed to lammps_open (as it often would be from C/C++), use the 217 GET_COMMAND intrinsic to obtain it. 218 * All C++ functions that accept char* pointers now accept Fortran-style 219 strings within this interface instead. 220 * All of the lammps_extract_[something] functions, which return void* 221 C-style pointers, have been replaced by generic subroutines that return 222 Fortran variables (which may be arrays). The first argument houses the 223 variable/pointer to be returned (pretend it's on the left-hand side); all 224 other arguments are identical except as stipulated above. 225 Note that it is not possible to declare generic functions that are selected 226 based solely on the type/kind/rank (TKR) signature of the return value, 227 only based on the TKR of the arguments. 228 * The SHAPE of the first argument to lammps_extract_[something] is checked 229 against the "shape" of the C array (e.g., double vs. double* vs. double**). 230 Calling a subroutine with arguments of inappropriate rank will result in an 231 error at run time. 232 * The indices i and j in lammps_extract_fix are used the same way they 233 are in f_ID[i][j] references in LAMMPS (i.e., starting from 1). This is 234 different than the way library.cpp uses these numbers, but is more 235 consistent with the way arrays are accessed in LAMMPS and in Fortran. 236 * The char* pointer normally returned by lammps_command is thrown away 237 in this version; note also that lammps_command is now a subroutine 238 instead of a function. 239 * The pointer to LAMMPS itself is of type(lammps_instance), which is itself 240 a synonym for type(C_ptr), part of ISO_C_BINDING. Type (C_ptr) is 241 C's void* data type. 242 * This module will almost certainly generate a compile-time warning, 243 such as, 244 subroutine lammps_open_wrapper (argc, argv, communicator, ptr) & 245 Variable 'communicator' at (1) is a parameter to the BIND(C) 246 procedure 'lammps_open_wrapper' but may not be C interoperable 247 This happens because lammps_open_wrapper actually takes a Fortran 248 INTEGER argument, whose type is defined by the MPI library itself. The 249 Fortran integer is converted to a C integer by the MPI library (if such 250 conversion is actually necessary). 251 * lammps_extract_global returns COPIES of the (scalar) data, as does the 252 C version. 253 * lammps_extract_atom, lammps_extract_compute, and lammps_extract_fix 254 have a first argument that will be associated with ACTUAL LAMMPS DATA. 255 This means the first argument must be: 256 * The right rank (via the DIMENSION modifier) 257 * A C-interoperable POINTER type (i.e., INTEGER (C_int) or 258 REAL (C_double)). 259 * lammps_extract_variable returns COPIES of the data, as the C library 260 interface does. There is no need to deallocate using lammps_free. 261 * The 'data' argument to lammps_gather_atoms and lammps_scatter atoms must 262 be ALLOCATABLE. It should be of type INTEGER or DOUBLE PRECISION. It 263 does NOT need to be C inter-operable (and indeed should not be). 264 * The 'count' argument of lammps_scatter_atoms is unnecessary; the shape of 265 the array determines the number of elements LAMMPS will read. 266