git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@8651 f3b2605a-c512-4ea7-a41b-209d697bcdaa

This commit is contained in:
sjplimp 2012-08-14 16:13:24 +00:00
parent ee321aabc6
commit dd51b1a0c8
4 changed files with 150 additions and 192 deletions

View File

@ -14,8 +14,8 @@
<P>This section describes how to build and use LAMMPS via a Python
interface.
</P>
<UL><LI>11.1 <A HREF = "#py_1">Setting necessary environment variables</A>
<LI>11.2 <A HREF = "#py_2">Building LAMMPS as a shared library</A>
<UL><LI>11.1 <A HREF = "#py_1">Building LAMMPS as a shared library</A>
<LI>11.2 <A HREF = "#py_2">Installing the Python wrapper into Python</A>
<LI>11.3 <A HREF = "#py_3">Extending Python with MPI to run in parallel</A>
<LI>11.4 <A HREF = "#py_4">Testing the Python-LAMMPS interface</A>
<LI>11.5 <A HREF = "#py_5">Using LAMMPS from Python</A>
@ -76,36 +76,7 @@ check which version of Python you have installed, by simply typing
<HR>
<A NAME = "py_1"></A><H4>11.1 Setting necessary environment variables
</H4>
<P>For Python to use the LAMMPS interface, it needs to find two files.
The paths to these files need to be added to two environment variables
that Python checks.
</P>
<P>The first is the environment variable PYTHONPATH. It needs
to include the directory where the python/lammps.py file is.
</P>
<P>For the csh or tcsh shells, add something like this to your ~/.cshrc
file:
</P>
<PRE>setenv PYTHONPATH $<I>PYTHONPATH</I>:/home/sjplimp/lammps/python
</PRE>
<P>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. See the discussion in <A HREF = "Section_start.html#start_5">Section_start
5</A> of the manual about building LAMMPS as a
shared library, for instructions on how to set the LD_LIBRARY_PATH
variable appropriately.
</P>
<P>If your LAMMPS build is not using any auxiliary libraries which are in
non-default directories where the system cannot find them, you
typically just need to add something like this to your ~/.cshrc file:
</P>
<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src
</PRE>
<HR>
<A NAME = "py_2"></A><H4>11.2 Building LAMMPS as a shared library
<A NAME = "py_1"></A><H4>11.1 Building LAMMPS as a shared library
</H4>
<P>Instructions on how to build LAMMPS as a shared library are given in
<A HREF = "Section_start.html#start_5">Section_start 5</A>. A shared library is one
@ -119,15 +90,62 @@ make -f Makefile.shlib foo
</PRE>
<P>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
well as a soft link liblmp.so, which is what the Python wrapper will
load by default. Note that if you are building multiple machine
versions of the shared library, the soft link is always set to the
most recently built version.
</P>
<P>If this fails, see <A HREF = "Section_start.html#start_5">Section_start 5</A> for
more details, especially if your LAMMPS build uses auxiliary
libraries, e.g. ones required by certain packages and found in the
lib/package directories.
more details, especially if your LAMMPS build uses auxiliary libraries
like MPI or FFTW which may not be built as shared libraries on your
system.
</P>
<HR>
<A NAME = "py_2"></A><H4>11.2 Installing the Python wrapper into Python
</H4>
<P>For Python to invoke LAMMPS, there are 2 files it needs to have:
</P>
<UL><LI>python/lammps.py
<LI>src/liblmp.so
</UL>
<P>Lammps.py is the Python wrapper on the LAMMPS library interface.
Liblmp.so is the shared LAMMPS library that Python loads, as described
above.
</P>
<P>You can insure Python can find these files in one of two ways:
</P>
<UL><LI>set two environment variables
<LI>run the python/install.py script
</UL>
<P>If you set the paths to these files as environment variables, you only
have to do it once. For the csh or tcsh shells, add something like
this to your ~/.cshrc file, one line for each of the two files:
</P>
<PRE>setenv PYTHONPATH $<I>PYTHONPATH</I>:/home/sjplimp/lammps/python
setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src
</PRE>
<P>If you run the python/install.py script, you need to rerun it every
time you rebuild LAMMPS (as a shared library) or make changes to the
python/lammps.py file.
</P>
<P>You can invoke install.py from the python directory as
</P>
<PRE>% python install.py
</PRE>
<P>Prefix this command with "sudo" if it does not allow you to copy files
into the Python site-packages directory. If you do this, make sure
that the Python run by root is the same as the Python you run.
E.g. you may need to do something like
</P>
<PRE>% sudo /usr/local/bin/python install.py
</PRE>
<P>You can also invoke install.py from the src directory as
</P>
<PRE>% make install-python
</PRE>
<P>Again, you may need to prefix this with "sudo". In this mode you
cannot control which Python root invokes.
</P>
<HR>

View File

@ -11,8 +11,8 @@
This section describes how to build and use LAMMPS via a Python
interface.
11.1 "Setting necessary environment variables"_#py_1
11.2 "Building LAMMPS as a shared library"_#py_2
11.1 "Building LAMMPS as a shared library"_#py_1
11.2 "Installing the Python wrapper into Python"_#py_2
11.3 "Extending Python with MPI to run in parallel"_#py_3
11.4 "Testing the Python-LAMMPS interface"_#py_4
11.5 "Using LAMMPS from Python"_#py_5
@ -72,36 +72,7 @@ check which version of Python you have installed, by simply typing
:line
:line
11.1 Setting necessary environment variables :link(py_1),h4
For Python to use the LAMMPS interface, it needs to find two files.
The paths to these files need to be added to two environment variables
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, 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. 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.
If your LAMMPS build is not using any auxiliary libraries which are in
non-default directories where the system cannot find them, you
typically just need to add something like this to your ~/.cshrc file:
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src :pre
:line
11.2 Building LAMMPS as a shared library :link(py_2),h4
11.1 Building LAMMPS as a shared library :link(py_1),h4
Instructions on how to build LAMMPS as a shared library are given in
"Section_start 5"_Section_start.html#start_5. A shared library is one
@ -115,15 +86,62 @@ 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
well as a soft link liblmp.so which is what the Python wrapper will
well as a soft link liblmp.so, which is what the Python wrapper will
load by default. Note that if you are building multiple machine
versions of the shared library, the soft link is always set to the
most recently built version.
If this fails, see "Section_start 5"_Section_start.html#start_5 for
more details, especially if your LAMMPS build uses auxiliary
libraries, e.g. ones required by certain packages and found in the
lib/package directories.
more details, especially if your LAMMPS build uses auxiliary libraries
like MPI or FFTW which may not be built as shared libraries on your
system.
:line
11.2 Installing the Python wrapper into Python :link(py_2),h4
For Python to invoke LAMMPS, there are 2 files it needs to have:
python/lammps.py
src/liblmp.so :ul
Lammps.py is the Python wrapper on the LAMMPS library interface.
Liblmp.so is the shared LAMMPS library that Python loads, as described
above.
You can insure Python can find these files in one of two ways:
set two environment variables
run the python/install.py script :ul
If you set the paths to these files as environment variables, you only
have to do it once. For the csh or tcsh shells, add something like
this to your ~/.cshrc file, one line for each of the two files:
setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/python
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src :pre
If you run the python/install.py script, you need to rerun it every
time you rebuild LAMMPS (as a shared library) or make changes to the
python/lammps.py file.
You can invoke install.py from the python directory as
% python install.py :pre
Prefix this command with "sudo" if it does not allow you to copy files
into the Python site-packages directory. If you do this, make sure
that the Python run by root is the same as the Python you run.
E.g. you may need to do something like
% sudo /usr/local/bin/python install.py :pre
You can also invoke install.py from the src directory as
% make install-python :pre
Again, you may need to prefix this with "sudo". In this mode you
cannot control which Python root invokes.
:line

View File

@ -281,13 +281,11 @@ dummy MPI library provided in src/STUBS, since you don't need a true
MPI library installed on your system. See the
src/MAKE/Makefile.serial file for how to specify the 3 MPI variables
in this case. You will also need to build the STUBS library for your
platform before making LAMMPS itself. To build it as a static
library, from the src directory, type "make stubs", or from the STUBS
dir, type "make" and it should create a libmpi_stubs.a suitable for
linking to LAMMPS. To build it as a shared library, from the STUBS
dir, type "make shlib" and it should create a libmpi_stubs.so suitable
for dynamically loading when LAMMPS runs. If either of these builds
fail, you will need to edit the STUBS/Makefile for your platform.
platform before making LAMMPS itself. To build from the src
directory, type "make stubs", or from the STUBS dir, type "make".
This should create a libmpi_stubs.a file suitable for linking to
LAMMPS. If the build fails, you will need to edit the STUBS/Makefile
for your platform.
</P>
<P>The file STUBS/mpi.cpp provides a CPU timer function called
MPI_Wtime() that calls gettimeofday() . If your system doesn't
@ -816,33 +814,20 @@ first "make" command will create a current Makefile.shlib with all the
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
well as a soft link liblmp.so, which the Python wrapper uses by
default.
liblmp_foo.so which another application can link to dyamically. It
will also create a soft link liblmp.so, which the Python wrapper uses
by default.
</P>
<H5><B>Additional requirements for building a shared library:</B>
</H5>
<P>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 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), any packages you have installed that require libraries
provided with LAMMPS (e.g. the USER-ATC package require
lib/atc/libatc.so), and any system libraries (e.g. BLAS or
Fortran-to-C libraries) listed in the lib/package/Makefile.lammps
file.
</P>
<P>If one of these auxiliary libraries does not exist as a shared
library, the second make command should generate a build error. If a
needed library is simply missing from the link list, this will not
generate an error at build time, but will generate a run-time error
when the library is loaded, so be sure all needed libraries are
listed, just as they are when building LAMMPS as a stand-alone code.
</P>
<P>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.
libraries. This will be the case for libraries included with LAMMPS,
such as the dummy MPI library in src/STUBS or any package libraries in
lib/packges, since they are always built as shared libraries with the
-fPIC switch. However, if a library like MPI or FFTW does not exist
as a shared library, the second make command will generate an error.
This means you will need to install a shared library version of the
package. The build instructions for the library should tell you how
to do this.
</P>
<P>As an example, here is how to build and install the <A HREF = "http://www-unix.mcs.anl.gov/mpi">MPICH
library</A>, a popular open-source version of MPI, distributed by
@ -859,43 +844,19 @@ make install
you do not have write privileges for /usr/local/lib. The end result
should be the file /usr/local/lib/libmpich.so.
</P>
<P>Also note that not all of the auxiliary libraries provided with LAMMPS
include Makefiles in their lib directories suitable for building them
as shared libraries. Typically this simply requires 3 steps: (a)
adding a -fPIC switch when files are compiled, (b) adding "-fPIC
-shared" switches when the library is linked with a C++ (or Fortran)
compiler, and (c) 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.
</P>
<H5><B>Additional requirements for using a shared library:</B>
<H5><B>Additional requirement for using a shared library:</B>
</H5>
<P>The operating system finds shared libraries to load at run-time using
the environment variable LD_LIBRARY_PATH. So at a minimum you
must set it to include the lammps src directory where the LAMMPS
shared library file is created.
the environment variable LD_LIBRARY_PATH. So you may wish
to copy the file src/liblmp.so or src/liblmp_g++.so (for example)
to a place the system can find it by default, such as /usr/local/lib,
or you may wish to add the lammps src directory to LD_LIBRARY_PATH.
</P>
<P>For the csh or tcsh shells, you could add something like this to your
~/.cshrc file:
</P>
<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src
</PRE>
<P>If any auxiliary libraries, used by LAMMPS, 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.
</P>
<P>For example, if you are using the dummy MPI library provided in
src/STUBS, and have built the file libmpi_stubs.so, you would add
something like this to your ~/.cshrc file:
</P>
<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/src/STUBS
</PRE>
<P>If you are using the LAMMPS USER-ATC package, and have built the file
lib/atc/libatc.so, you would add something like this to your ~/.cshrc
file:
</P>
<PRE>setenv LD_LIBRARY_PATH $<I>LD_LIBRARY_PATH</I>:/home/sjplimp/lammps/lib/atc
</PRE>
<H5><B>Calling the LAMMPS library:</B>
</H5>
<P>Either flavor of library (static or shared0 allows one or more LAMMPS

View File

@ -275,13 +275,11 @@ dummy MPI library provided in src/STUBS, since you don't need a true
MPI library installed on your system. See the
src/MAKE/Makefile.serial file for how to specify the 3 MPI variables
in this case. You will also need to build the STUBS library for your
platform before making LAMMPS itself. To build it as a static
library, from the src directory, type "make stubs", or from the STUBS
dir, type "make" and it should create a libmpi_stubs.a suitable for
linking to LAMMPS. To build it as a shared library, from the STUBS
dir, type "make shlib" and it should create a libmpi_stubs.so suitable
for dynamically loading when LAMMPS runs. If either of these builds
fail, you will need to edit the STUBS/Makefile for your platform.
platform before making LAMMPS itself. To build from the src
directory, type "make stubs", or from the STUBS dir, type "make".
This should create a libmpi_stubs.a file suitable for linking to
LAMMPS. If the build fails, you will need to edit the STUBS/Makefile
for your platform.
The file STUBS/mpi.cpp provides a CPU timer function called
MPI_Wtime() that calls gettimeofday() . If your system doesn't
@ -810,33 +808,20 @@ first "make" command will create a current Makefile.shlib with all the
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
well as a soft link liblmp.so, which the Python wrapper uses by
default.
[Additional requirements for building a shared library:] :h5
liblmp_foo.so which another application can link to dyamically. It
will also create a soft link liblmp.so, which the Python wrapper uses
by 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 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), any packages you have installed that require libraries
provided with LAMMPS (e.g. the USER-ATC package require
lib/atc/libatc.so), and any system libraries (e.g. BLAS or
Fortran-to-C 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. If a
needed library is simply missing from the link list, this will not
generate an error at build time, but will generate a run-time error
when the library is loaded, so be sure all needed libraries are
listed, just as they are 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.
libraries. This will be the case for libraries included with LAMMPS,
such as the dummy MPI library in src/STUBS or any package libraries in
lib/packges, since they are always built as shared libraries with the
-fPIC switch. However, if a library like MPI or FFTW does not exist
as a shared library, the second make command will generate an error.
This means you will need to install a shared library version of the
package. The build instructions for the library should tell you how
to do this.
As an example, here is how to build and install the "MPICH
library"_mpich, a popular open-source version of MPI, distributed by
@ -853,43 +838,19 @@ You may need to use "sudo make install" in place of the last line if
you do not have write privileges 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 suitable for building them
as shared libraries. Typically this simply requires 3 steps: (a)
adding a -fPIC switch when files are compiled, (b) adding "-fPIC
-shared" switches when the library is linked with a C++ (or Fortran)
compiler, and (c) 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.
[Additional requirements for using a shared library:] :h5
[Additional requirement for using a shared library:] :h5
The operating system finds shared libraries to load at run-time using
the environment variable LD_LIBRARY_PATH. So at a minimum you
must set it to include the lammps src directory where the LAMMPS
shared library file is created.
the environment variable LD_LIBRARY_PATH. So you may wish
to copy the file src/liblmp.so or src/liblmp_g++.so (for example)
to a place the system can find it by default, such as /usr/local/lib,
or you may wish to add the lammps src directory to LD_LIBRARY_PATH.
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
If any auxiliary libraries, used by LAMMPS, 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, and have built the file libmpi_stubs.so, you would 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, and have built the file
lib/atc/libatc.so, you would add something like this to your ~/.cshrc
file:
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/lib/atc :pre
[Calling the LAMMPS library:] :h5
Either flavor of library (static or shared0 allows one or more LAMMPS