The first is the environment variable PYTHONPATH. It needs to include the directory where the python/lammps.py file is.
-For the csh or tcsh shells, you could add something like this to your -~/.cshrc file: +
For the csh or tcsh shells, add something like this to your ~/.cshrc +file:
setenv PYTHONPATH $PYTHONPATH:/home/sjplimp/lammps/python
The second is the environment variable LD_LIBRARY_PATH, which is used by the operating system to find dynamic shared libraries when it loads -them. It needs to include the directory where the shared LAMMPS -library will be. Normally this is the LAMMPS src dir, as explained in -the following section. +them. See the discussion in Section_start +5 of the manual about building LAMMPS as a +shared library, for instructions on how to set the LD_LIBRARY_PATH +variable appropriately.
-For the csh or tcsh shells, you could add something like this to your -~/.cshrc file: -
-setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/home/sjplimp/lammps/src --
As discussed below, if your LAMMPS build includes auxiliary libraries, -they must also be available as shared libraries for Python to -successfully load LAMMPS. If they are not in default places where the -operating system can find them, then you also have to add their paths -to the LD_LIBRARY_PATH environment variable. -
-For example, if you are using the dummy MPI library provided in -src/STUBS, you need to add something like this to your ~/.cshrc file: -
-setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/home/sjplimp/lammps/src/STUBS --
If you are using the LAMMPS USER-ATC package, you need to add -something like this to your ~/.cshrc file: -
-setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/home/sjplimp/lammps/lib/atc -
>From the src directory, type -
-make makeshlib -make -f Makefile.shlib foo +
From the src directory, type
+make makeshlib +make -f Makefile.shlib foo +
where foo is the machine target name, such as linux or g++ or serial. This should create the file liblmp_foo.so in the src directory, as well as a soft link liblmp.so which is what the Python wrapper will @@ -138,47 +118,7 @@ load by default. If you are building multiple machine versions of the shared library, the soft link is always set to the most recently built version.
-Note that as discussed in below, a LAMMPS build may depend on several -auxiliary libraries, which are specified in your low-level -src/Makefile.foo file. For example, an MPI library, the FFTW library, -a JPEG library, etc. Depending on what LAMMPS packages you have -installed, the build may also require additional libraries from the -lib directories, such as lib/atc/libatc.so or lib/reax/libreax.so. -
-You must insure that each of these libraries exist in shared library -form (*.so file for Linux systems), or either the LAMMPS shared -library build or the Python load of the library will fail. For the -load to be successful all the shared libraries must also be in -directories that the operating system checks. See the discussion in -the preceding section about the LD_LIBRARY_PATH environment variable -for how to insure this. -
-Note that some system libraries, such as MPI, if you installed it -yourself, may not be built by default as shared libraries. The build -instructions for the library should tell you how to do this. -
-For example, here is how to build and install the MPICH -library, a popular open-source version of MPI, distributed by -Argonne National Labs, as a shared library in the default -/usr/local/lib location: -
- - -./configure --enable-shared -make -make install --
You may need to use "sudo make install" in place of the last line if -you do not have write priveleges for /usr/local/lib. The end result -should be the file /usr/local/lib/libmpich.so. -
-Note that not all of the auxiliary libraries provided with LAMMPS have -shared-library Makefiles in their lib directories. Typically this -simply requires a Makefile.foo that adds a -fPIC switch when files are -compiled and a "-fPIC -shared" switches when the library is linked -with a C++ (or Fortran) compiler, as well as an output target that -ends in ".so", like libatc.o. As we or others create and contribute -these Makefiles, we will add them to the LAMMPS distribution. +
See Section_start 5 for more details.
All of these except pyMPI work by wrapping the MPI library (which must be available on your system as a shared library, as discussed above), @@ -272,7 +212,7 @@ and type:
If you get no errors, you're ready to use LAMMPS from Python. If the load fails, the most common error to see is
-"CDLL: asdfasdfasdf" +
OSError: Could not load LAMMPS dynamic library
which means Python was unable to load the LAMMPS shared library. This can occur if it can't find the LAMMMPS library; see the environment diff --git a/doc/Section_python.txt b/doc/Section_python.txt index 7386e8b53e..eb83d5607d 100644 --- a/doc/Section_python.txt +++ b/doc/Section_python.txt @@ -81,37 +81,17 @@ that Python checks. The first is the environment variable PYTHONPATH. It needs to include the directory where the python/lammps.py file is. -For the csh or tcsh shells, you could add something like this to your -~/.cshrc file: +For the csh or tcsh shells, add something like this to your ~/.cshrc +file: setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/python :pre The second is the environment variable LD_LIBRARY_PATH, which is used by the operating system to find dynamic shared libraries when it loads -them. It needs to include the directory where the shared LAMMPS -library will be. Normally this is the LAMMPS src dir, as explained in -the following section. - -For the csh or tcsh shells, you could add something like this to your -~/.cshrc file: - -setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src :pre - -As discussed below, if your LAMMPS build includes auxiliary libraries, -they must also be available as shared libraries for Python to -successfully load LAMMPS. If they are not in default places where the -operating system can find them, then you also have to add their paths -to the LD_LIBRARY_PATH environment variable. - -For example, if you are using the dummy MPI library provided in -src/STUBS, you need to add something like this to your ~/.cshrc file: - -setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src/STUBS :pre - -If you are using the LAMMPS USER-ATC package, you need to add -something like this to your ~/.cshrc file: - -setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/lib/atc :pre +them. See the discussion in "Section_start +5"_Section_start.html#start_5 of the manual about building LAMMPS as a +shared library, for instructions on how to set the LD_LIBRARY_PATH +variable appropriately. :line @@ -122,10 +102,10 @@ Instructions on how to build LAMMPS as a shared library are given in that is dynamically loadable, which is what Python requires. On Linux this is a library file that ends in ".so", not ".a". ->From the src directory, type +From the src directory, type make makeshlib -make -f Makefile.shlib foo +make -f Makefile.shlib foo :pre where foo is the machine target name, such as linux or g++ or serial. This should create the file liblmp_foo.so in the src directory, as @@ -134,47 +114,7 @@ load by default. If you are building multiple machine versions of the shared library, the soft link is always set to the most recently built version. -Note that as discussed in below, a LAMMPS build may depend on several -auxiliary libraries, which are specified in your low-level -src/Makefile.foo file. For example, an MPI library, the FFTW library, -a JPEG library, etc. Depending on what LAMMPS packages you have -installed, the build may also require additional libraries from the -lib directories, such as lib/atc/libatc.so or lib/reax/libreax.so. - -You must insure that each of these libraries exist in shared library -form (*.so file for Linux systems), or either the LAMMPS shared -library build or the Python load of the library will fail. For the -load to be successful all the shared libraries must also be in -directories that the operating system checks. See the discussion in -the preceding section about the LD_LIBRARY_PATH environment variable -for how to insure this. - -Note that some system libraries, such as MPI, if you installed it -yourself, may not be built by default as shared libraries. The build -instructions for the library should tell you how to do this. - -For example, here is how to build and install the "MPICH -library"_mpich, a popular open-source version of MPI, distributed by -Argonne National Labs, as a shared library in the default -/usr/local/lib location: - -:link(mpich,http://www-unix.mcs.anl.gov/mpi) - -./configure --enable-shared -make -make install :pre - -You may need to use "sudo make install" in place of the last line if -you do not have write priveleges for /usr/local/lib. The end result -should be the file /usr/local/lib/libmpich.so. - -Note that not all of the auxiliary libraries provided with LAMMPS have -shared-library Makefiles in their lib directories. Typically this -simply requires a Makefile.foo that adds a -fPIC switch when files are -compiled and a "-fPIC -shared" switches when the library is linked -with a C++ (or Fortran) compiler, as well as an output target that -ends in ".so", like libatc.o. As we or others create and contribute -these Makefiles, we will add them to the LAMMPS distribution. +See "Section_start 5"_Section_start.html#start_5 for more details. :line @@ -193,7 +133,7 @@ These include "maroonmpi"_http://code.google.com/p/maroonmpi/ "mpi4py"_http://code.google.com/p/mpi4py/ "myMPI"_http://nbcr.sdsc.edu/forum/viewtopic.php?t=89&sid=c997fefc3933bd66204875b436940f16 -"Pypar"_http://datamining.anu.edu.au/~ole/pypar :ul +"Pypar"_http://code.google.com/p/pypar :ul All of these except pyMPI work by wrapping the MPI library (which must be available on your system as a shared library, as discussed above), @@ -229,6 +169,11 @@ sudo python setup.py install :pre The "sudo" is only needed if required to copy Numpy files into your Python distribution's site-packages directory. + + + + + To install Pypar (version pypar-2.1.0_66 as of April 2009), unpack it and from its "source" directory, type @@ -268,7 +213,10 @@ and type: If you get no errors, you're ready to use LAMMPS from Python. If the load fails, the most common error to see is -"CDLL: asdfasdfasdf" + +OSError: Could not load LAMMPS dynamic library + + which means Python was unable to load the LAMMPS shared library. This can occur if it can't find the LAMMMPS library; see the environment diff --git a/doc/Section_start.html b/doc/Section_start.html index f16a963e6b..58a44ecf19 100644 --- a/doc/Section_start.html +++ b/doc/Section_start.html @@ -785,15 +785,15 @@ more info on wrapping and running LAMMPS from Python. make -f Makefile.lib foo
where foo is the machine name. This kind of library is typically used -to statically link a driver application to all of LAMMPS, so that you -can insure all dependencies are satisfied at compile time. Note that +to statically link a driver application to LAMMPS, so that you can +insure all dependencies are satisfied at compile time. Note that inclusion or exclusion of any desired optional packages should be done before typing "make makelib". The first "make" command will create a -current Makefile.lib with all the file names in your src dir. The 2nd -"make" command will use it to build LAMMPS as a static library, using -the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The build -will create the file liblmp_foo.a which another application can link -to. +current Makefile.lib with all the file names in your src dir. The +second "make" command will use it to build LAMMPS as a static library, +using the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The +build will create the file liblmp_foo.a which another application can +link to.
To build LAMMPS as a shared library (*.so file on Linux), which can be dynamically loaded, type @@ -806,7 +806,7 @@ wrapping LAMMPS with Python; see Section_python< for details. Again, note that inclusion or exclusion of any desired optional packages should be done before typing "make makelib". The first "make" command will create a current Makefile.shlib with all the -file names in your src dir. The 2nd "make" command will use it to +file names in your src dir. The second "make" command will use it to build LAMMPS as a shared library, using the SHFLAGS and SHLIBFLAGS settings in src/MAKE/Makefile.foo. The build will create the file liblmp_foo.so which another application can link to dyamically, as @@ -815,15 +815,87 @@ default.
Note that for a shared library to be usable by a calling program, all the auxiliary libraries it depends on must also exist as shared -libraries, and be find-able by the operating system. Else you will -get a run-time error when the shared library is loaded. For LAMMPS, -this includes all libraries needed by main LAMMPS (e.g. MPI or FFTW or -JPEG), system libraries needed by main LAMMPS (e.g. extra libs needed -by MPI), or packages you have installed that require libraries +libraries, and the operating system must be able to find them. For +LAMMPS, this includes all libraries needed by main LAMMPS (e.g. MPI or +FFTW or JPEG), system libraries needed by main LAMMPS (e.g. extra libs +needed by MPI), or packages you have installed that require libraries provided with LAMMPS (e.g. the USER-ATC package require lib/atc/libatc.so) or system libraries (e.g. BLAS or Fortran-to-C -libraries) listed in the lib/package/Makefile.lammps file. See the -discussion about the LAMMPS shared library in +libraries) listed in the lib/package/Makefile.lammps file. +
+If one of these auxiliary libraries does not exist as a shared +library, the second make command should generate a build error. The +build will not generate an error, if a needed library is simply +missing from the link list; this will generate a run-time error when +the library is loaded, so be sure all needed libraries are listed, +as they would be when building LAMMPS as a stand-alone code. +
+Note that if you install them yourself, some libraries, such as MPI, +may not build by default as shared libraries. The build instructions +for the library should tell you how to do this. +
+For example, here is how to build and install the MPICH +library, a popular open-source version of MPI, distributed by +Argonne National Labs, as a shared library in the default +/usr/local/lib location: +
+ + +./configure --enable-shared +make +make install ++
You may need to use "sudo make install" in place of the last line if +you do not have write priveleges for /usr/local/lib. The end result +should be the file /usr/local/lib/libmpich.so. +
+Also note that not all of the auxiliary libraries provided with LAMMPS +include Makefiles in their lib directories for building them as shared +libraries. Typically this simply requires adding a -fPIC switch when +files are compiled and "-fPIC -shared" switches when the library is +linked with a C++ (or Fortran) compiler, and creating an output target +that ends in ".so", like libatc.o. As we or others create and +contribute these Makefiles, we will add them to the LAMMPS +distribution. +
+You must insure that each of these libraries exist in shared library +form (*.so file for Linux systems), or either the LAMMPS shared +library build or the Python load of the library will fail. For the +load to be successful all the shared libraries must also be in +directories that the operating system checks. See the discussion in +the preceding section about the LD_LIBRARY_PATH environment variable +for how to insure this. +
+The second is the environment variable LD_LIBRARY_PATH, which is used +by the operating system to find dynamic shared libraries when it loads +them. +
+It needs to include the directory where the shared LAMMPS +library will be. Normally this is the LAMMPS src dir, as explained in +the following section. +
+For the csh or tcsh shells, you could add something like this to your +~/.cshrc file: +
+setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/home/sjplimp/lammps/src ++
As discussed below, if your LAMMPS build includes auxiliary libraries, +they must also be available as shared libraries for Python to +successfully load LAMMPS. If they are not in default places where the +operating system can find them, then you also have to add their paths +to the LD_LIBRARY_PATH environment variable. +
+For example, if you are using the dummy MPI library provided in +src/STUBS, you need to add something like this to your ~/.cshrc file: +
+setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/home/sjplimp/lammps/src/STUBS ++
If you are using the LAMMPS USER-ATC package, you need to add +something like this to your ~/.cshrc file: +
+setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/home/sjplimp/lammps/lib/atc ++
See the discussion about the LAMMPS shared library in Section_python for details about how to build shared versions of these libraries, and how to insure the operating system can find them, by setting the LD_LIBRARY_PATH environment diff --git a/doc/Section_start.txt b/doc/Section_start.txt index 4688b8d437..87e9c4452c 100644 --- a/doc/Section_start.txt +++ b/doc/Section_start.txt @@ -779,15 +779,15 @@ make makelib make -f Makefile.lib foo :pre where foo is the machine name. This kind of library is typically used -to statically link a driver application to all of LAMMPS, so that you -can insure all dependencies are satisfied at compile time. Note that +to statically link a driver application to LAMMPS, so that you can +insure all dependencies are satisfied at compile time. Note that inclusion or exclusion of any desired optional packages should be done before typing "make makelib". The first "make" command will create a -current Makefile.lib with all the file names in your src dir. The 2nd -"make" command will use it to build LAMMPS as a static library, using -the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The build -will create the file liblmp_foo.a which another application can link -to. +current Makefile.lib with all the file names in your src dir. The +second "make" command will use it to build LAMMPS as a static library, +using the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The +build will create the file liblmp_foo.a which another application can +link to. To build LAMMPS as a shared library (*.so file on Linux), which can be dynamically loaded, type @@ -800,7 +800,7 @@ wrapping LAMMPS with Python; see "Section_python"_Section_python.html for details. Again, note that inclusion or exclusion of any desired optional packages should be done before typing "make makelib". The first "make" command will create a current Makefile.shlib with all the -file names in your src dir. The 2nd "make" command will use it to +file names in your src dir. The second "make" command will use it to build LAMMPS as a shared library, using the SHFLAGS and SHLIBFLAGS settings in src/MAKE/Makefile.foo. The build will create the file liblmp_foo.so which another application can link to dyamically, as @@ -809,20 +809,106 @@ default. Note that for a shared library to be usable by a calling program, all the auxiliary libraries it depends on must also exist as shared -libraries, and be find-able by the operating system. Else you will -get a run-time error when the shared library is loaded. For LAMMPS, -this includes all libraries needed by main LAMMPS (e.g. MPI or FFTW or -JPEG), system libraries needed by main LAMMPS (e.g. extra libs needed -by MPI), or packages you have installed that require libraries +libraries, and the operating system must be able to find them. For +LAMMPS, this includes all libraries needed by main LAMMPS (e.g. MPI or +FFTW or JPEG), system libraries needed by main LAMMPS (e.g. extra libs +needed by MPI), or packages you have installed that require libraries provided with LAMMPS (e.g. the USER-ATC package require lib/atc/libatc.so) or system libraries (e.g. BLAS or Fortran-to-C -libraries) listed in the lib/package/Makefile.lammps file. See the -discussion about the LAMMPS shared library in +libraries) listed in the lib/package/Makefile.lammps file. + +If one of these auxiliary libraries does not exist as a shared +library, the second make command should generate a build error. The +build will not generate an error, if a needed library is simply +missing from the link list; this will generate a run-time error when +the library is loaded, so be sure all needed libraries are listed, +as they would be when building LAMMPS as a stand-alone code. + +Note that if you install them yourself, some libraries, such as MPI, +may not build by default as shared libraries. The build instructions +for the library should tell you how to do this. + +For example, here is how to build and install the "MPICH +library"_mpich, a popular open-source version of MPI, distributed by +Argonne National Labs, as a shared library in the default +/usr/local/lib location: + +:link(mpich,http://www-unix.mcs.anl.gov/mpi) + +./configure --enable-shared +make +make install :pre + +You may need to use "sudo make install" in place of the last line if +you do not have write priveleges for /usr/local/lib. The end result +should be the file /usr/local/lib/libmpich.so. + +Also note that not all of the auxiliary libraries provided with LAMMPS +include Makefiles in their lib directories for building them as shared +libraries. Typically this simply requires adding a -fPIC switch when +files are compiled and "-fPIC -shared" switches when the library is +linked with a C++ (or Fortran) compiler, and creating an output target +that ends in ".so", like libatc.o. As we or others create and +contribute these Makefiles, we will add them to the LAMMPS +distribution. + + +You must insure that each of these libraries exist in shared library +form (*.so file for Linux systems), or either the LAMMPS shared +library build or the Python load of the library will fail. For the +load to be successful all the shared libraries must also be in +directories that the operating system checks. See the discussion in +the preceding section about the LD_LIBRARY_PATH environment variable +for how to insure this. + + + +The second is the environment variable LD_LIBRARY_PATH, which is used +by the operating system to find dynamic shared libraries when it loads +them. + +It needs to include the directory where the shared LAMMPS +library will be. Normally this is the LAMMPS src dir, as explained in +the following section. + +For the csh or tcsh shells, you could add something like this to your +~/.cshrc file: + +setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src :pre + +As discussed below, if your LAMMPS build includes auxiliary libraries, +they must also be available as shared libraries for Python to +successfully load LAMMPS. If they are not in default places where the +operating system can find them, then you also have to add their paths +to the LD_LIBRARY_PATH environment variable. + +For example, if you are using the dummy MPI library provided in +src/STUBS, you need to add something like this to your ~/.cshrc file: + +setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src/STUBS :pre + +If you are using the LAMMPS USER-ATC package, you need to add +something like this to your ~/.cshrc file: + +setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/lib/atc :pre + + + + + + + + + + +See the discussion about the LAMMPS shared library in "Section_python"_Section_python.html for details about how to build shared versions of these libraries, and how to insure the operating system can find them, by setting the LD_LIBRARY_PATH environment variable correctly. + + Either flavor of library allows one or more LAMMPS objects to be instantiated from the calling program. diff --git a/doc/units.html b/doc/units.html index 0462ba6ee1..ebf4dd9048 100644 --- a/doc/units.html +++ b/doc/units.html @@ -58,6 +58,11 @@ results from a unitless LJ simulation into physical quantities.
Note that for LJ units, the default mode of thermodyamic output via +the thermo_style command is to normalize energies +by the number of atoms, i.e. energy/atom. This can be changed via the +thermo_modify norm command. +
For style real, these are the units: