PyTrilinos Documentation for Trilinos Release 10.2

There are a number of ways to obtain PyTrilinos documentation. You should start with the Tutorial page and consult the Frequently Asked Questions page for any initial questions.

Running python interactively, you can use the help() or dir() functions on PyTrilinos modules, classes, methods or objects. Within a UNIX shell, you can run pydoc on any class in the PyTrilinos hierarchy. The PyTrilinos docstrings are automatically derived from the Trilinos Doxygen comments, so these help facilities now provide a significant amount of information.

If the python documentation strings do not provide sufficient information, then you should consult this documentation, specifically the Differences Between C++ and Python Implementations pages. If the class or method you are interested in does not appear within these pages, then use the C++ documentation, as the C++ and python interfaces are kept analogous whenever possible.

PyTrilinos Prerequisites
Building PyTrilinos
Known Issues
Differences Between C++ and Python Implementations

PyTrilinos Prerequisites

To build PyTrilinos, you must have the following installed:

Python 2.3 or higher. Some packages require that the python interpreter be able to distinguish between boolean and integer values. This support was first provided in python 2.3. PyTrilinos has been upgraded to work with python 2.6.
The numpy python module. We recommend version 1.0.1 or higher, but backward compatibility has been maintained with versions 0.9.x.
SWIG 1.3.39 or higher. SWIG is the Simple Wrapper and Interface Generator, and is the workhorse for generating the python interface to Trilinos packages. As of this writing, version 1.3.39 is the current release version.

Building PyTrilinos

For release 10.0 and beyond, all of Trilinos has converted from an autotools build system to a CMake build system. CMake can generate several different types of build systems, from the familiar Makefile systems, to Windows Visual Studio Pro systems and Mac OS X XCode systems. This obviously allows Trilinos an entry to Windows platforms. In addition, the autotools version of Trilinos did not support libtool, so the adoption of CMake provides a new and robust support for shared Trilinos libraries.

From the point of view of PyTrilinos, the move to CMake provides for robust and portable shared library support. Shared libraries have been required for PyTrilinos since release 9.0, so this is an important advance. Unfortunately, this portability does not yet extend to Windows, as this capability will require some additional work on all of Trilinos. Therefore, PyTrilinos is not yet available under Windows.

To build PyTrilinos, cmake should be run at the top build directory level with the options:

-D Trilinos_ENABLE_PyTrilinos:BOOL=ON
-D BUILD_SHARED_LIBS:BOOL=ON

Turning the shared libraries on explicitly is required because the Trilinos policy is to not turn on shared libraries implicitly. Turning PyTrilinos on will build python modules for every Trilinos package that has python wrappers defined. If you want to ensure that every available PyTrilinos module is built, you should use the option:

-D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON

This is currently the configuration used by PyTrilinos developers to test the package, so it should be considered a safe way to build PyTrilinos.

Previously, you had to set the environment variable LD_LIBRARY_PATH (DYLD_LIBRARY_PATH on Mac OS X) in order to run PyTrilinos tests. This requirement has been lifted with the adoption of CMake.

Known Issues

64-bit. We routinely build PyTrilinos on a 64-bit platform. Often, then the third-party libraries must be linked as shared libraries as well.
MPICH. PyTrilinos has been successfully built and run using OpenMPI and LAM MPI, but MPICH seems to give it problems. Apparently the MPICH version of mpirun adds command-line arguments to the invocation of the executable, and our python test scripts do not currently handle these properly.
GNU Fortran for Mac OS X. The most popular Fortran installers for the GNU compiler collection, fink and MacPorts, both install gfortran based on gcc version 4.4. For compatibility, this means you should use the same version C and C++ compilers (failure to do so has been demonstrated to result in faulty exception handling, and probably other issues). However, this results in version 4.4 dynamic libraries, which get loaded into python that will almost certainly have been compiled with version 4.0. This situation has been shown to result in non-aligned pointer deallocation errors/warnings. Fink and MacPorts also install OpenMPI versions of mpicc and mpic++ based on gcc 4.0, and mpif77 (etc.) based on gcc 4.4. Therefore, the current recommendation is to compile PyTrilinos with the:
```
-D Trilinos_ENABLE_Fortran:BOOL=OFF
```
option when using GNU compilers on the Mac.

Differences Between C++ and Python Implementations

Teuchos is a package of tools and utilities.
Thyra is a package that supports a common abstract interface for abstract numerical algorithms.
Epetra is a package of linear algebra services, including parallel communication, domain decomposition maps, vectors, sparse matrices and related classes.
TriUtils is a suite of utilities, used extensively by the Trilinos test harness.
EpetraExt provides certain extensions to the Epetra module, such as specialized I/O, transformations and coloring algorithms.
AztecOO is a package of domain-decomposition preconditioned, scaled iterative linear solvers.
Galeri provides a "gallery" of Epetra.CrsMatrix and Epetra.Map examples, useful for testing.
Amesos provides a common interface to a collection of publically available, third-party direct linear solvers. It also includes two small but nice direct solvers, KLU and PARAKLETE.
IFPACK provides incomplete factorization preconditioning, Chebyshev preconditioners, and relaxation-based preconditioning (like Jacobi, Gauss-Seidel and symmetric Gauss-Seidel).
Anasazi is a package of eigensolvers.
ML provides multi-level preconditioning, mostly based on (smoothed) aggregation methods. It offers a variety of smoothers, coarse solvers, and coarsening approaches.
NOX is a package of nonlinear solvers.
LOCA provides support for continuation algorithms, useful for finding turning points, bifurcation points, etc.