PyTrilinos Logo PyTrilinos Documentation for Trilinos Release 9.0

PyTrilinos Documentation for Trilinos Release 9.0

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

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.5.
  • The numpy python module. Compatibility with the now-obsolete Numeric module has been upgraded to compatibility with the newer numpy module. We recommend version 1.0.1 or higher, but backward compatibility has been maintained with versions 0.9.x.
  • SWIG 1.3.31 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.35 is the current release version.

Building PyTrilinos

To build PyTrilinos for release 9.0, configure Trilinos with the --enable-pytrilinos option. If you wish to specify a specific python to compile against, use --with-python=path.

PyTrilinos python modules are compiled shared objects. If these shared libraries are linked against static libraries, it can cause problems. One problem is that the run-time typing employed by the Teuchos::ParameterList class can get confused if a parameter is set by one package and then evaluated by the Teuchos package. Other problems crop up under MPI builds where cross-package inheritance is not recognized properly.

For these reasons, PyTrilinos needs to re-link static Trilinos libraries as shared before linking the python extension modules. This requirement is universal for release 9.0. PyTrilinos takes care of this automatically, although the procedure is rather ad-hoc, and only supported currently for Linux and Mac OS X. Other platforms will link against static Trilinos libraries, and risk the problems described above. If you desire a port to a specific platform, send email to pytrilinos-users@software.sandia.gov.

If you build PyTrilinos under Linux or Darwin under release 9.0, and you wish to test the PyTrilinos modules prior to installing Trilinos, the python test scripts will not be able to find these new shared libraries and will fail. To correct this, you must set an environment variable so that the shared libraries can be found. Under LINUX, this environment variable is LD_LIBRARY_PATH. Under Darwin, this environment variable is DYLD_LIBRARY_PATH. The value that needs to be added to this environment variable is

BUILD/package/PyTrilinos/shared

where BUILD should be replaced with the path to your Trilinos build directory. If other path(s) are already specified in this environment variable, simply separate multiple paths with a colon (:).

Furthermore, for MPI you may need to tell mpirun to export this environment variable in order to use it:

mpirun -x LD_LIBRARY_PATH -np 4 testEpetra_Vector.py -t

Known Issues

  • 64-bit. We routinely build PyTrilinos on a 64-bit platform.

    This usually requires that Trilinos and all third-party libraries be compiled as position-independent code (typically an -fPIC compile option). Often, then the third-party libraries must be linked as shared libraries as well.

  • MPICH. PyTrilinos has been successfully built and run using 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.

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.

Current PyTrilinos Modules and Wrapped Header Files

  • PyTrilinos.Amesos
    • Amesos.h
    • Amesos_BaseSolver.h
    • Amesos_ConfigDefs.h
    • Amesos_Klu.h
    • Amesos_Lapack.h
    • Amesos_Mumps.h
    • Amesos_Pardiso.h
    • Amesos_Scalapack.h
    • Amesos_Superlu.h
    • Amesos_Superludist.h
    • Amesos_Taucs.h
    • Amesos_Umfpack.h
    • Amesos_config.h
  • PyTrilinos.Anasazi
    • AnasaziBasicSort.hpp
    • AnasaziOutputManager.hpp
  • PyTrilinos.AztecOO
    • AztecOO.h
    • AztecOO_Version.h
    • az_aztec_defs.h
  • PyTrilinos.Epetra
    • Epetra_BasicDirectory.h
    • Epetra_BasicRowMatrix.h
    • Epetra_BlockMap.h
    • Epetra_CombineMode.h
    • Epetra_Comm.h
    • Epetra_CompObject.h
    • Epetra_CrsGraph.h
    • Epetra_CrsMatrix.h
    • Epetra_CrsSingletonFilter.h
    • Epetra_DArray.h
    • Epetra_DataAccess.h
    • Epetra_Directory.h
    • Epetra_DistObject.h
    • Epetra_Distributor.h
    • Epetra_Export.h
    • Epetra_FECrsGraph.h
    • Epetra_FECrsMatrix.h
    • Epetra_FEVbrMatrix.h
    • Epetra_FEVector.h
    • Epetra_FastCrsMatrix.h
    • Epetra_Flops.h
    • Epetra_IArray.h
    • Epetra_Import.h
    • Epetra_IntSerialDenseMatrix.h
    • Epetra_IntSerialDenseVector.h
    • Epetra_IntVector.h
    • Epetra_InvOperator.h
    • Epetra_JadMatrix.h
    • Epetra_LinearProblem.h
    • Epetra_LinearProblemRedistor.h
    • Epetra_LocalMap.h
    • Epetra_Map.h
    • Epetra_MapColoring.h
    • Epetra_MpiComm.h
    • Epetra_MpiDistributor.h
    • Epetra_MultiVector.h
    • Epetra_NumPyIntSerialDenseMatrix.h
    • Epetra_NumPyIntSerialDenseVector.h
    • Epetra_NumPyIntVector.h
    • Epetra_NumPyMultiVector.h
    • Epetra_NumPySerialDenseMatrix.h
    • Epetra_NumPySerialDenseVector.h
    • Epetra_Object.h
    • Epetra_OffsetIndex.h
    • Epetra_Operator.h
    • Epetra_PyOperator.h
    • Epetra_PyRowMatrix.h
    • Epetra_RowMatrix.h
    • Epetra_RowMatrixTransposer.h
    • Epetra_SerialComm.h
    • Epetra_SerialDenseMatrix.h
    • Epetra_SerialDenseOperator.h
    • Epetra_SerialDenseSVD.h
    • Epetra_SerialDenseSolver.h
    • Epetra_SerialDenseVector.h
    • Epetra_SerialDistributor.h
    • Epetra_SerialSpdDenseSolver.h
    • Epetra_SerialSymDenseMatrix.h
    • Epetra_SrcDistObject.h
    • Epetra_Time.h
    • Epetra_Util.h
    • Epetra_VbrMatrix.h
    • Epetra_Vector.h
    • Epetra_Version.h
  • PyTrilinos.EpetraExt
    • EpetraExt_BlockMapIn.h
    • EpetraExt_BlockMapOut.h
    • EpetraExt_CrsMatrixIn.h
    • EpetraExt_HDF5.h
    • EpetraExt_MapColoring.h
    • EpetraExt_MapColoringIndex.h
    • EpetraExt_MultiVectorIn.h
    • EpetraExt_MultiVectorOut.h
    • EpetraExt_RowMatrixOut.h
    • EpetraExt_Transform.h
    • EpetraExt_Version.h
    • EpetraExt_XMLReader.h
    • EpetraExt_XMLWriter.h
  • PyTrilinos.Galeri
    • Galeri_CrsMatrices.h
    • Galeri_Maps.h
    • Galeri_Utils.h
    • Galeri_VbrMatrices.h
    • Galeri_Version.h
  • PyTrilinos.IFPACK
    • Ifpack.h
    • Ifpack_ConfigDefs.h
    • Ifpack_IC.h
    • Ifpack_ICT.h
    • Ifpack_ILU.h
    • Ifpack_ILUT.h
    • Ifpack_PointRelaxation.h
    • Ifpack_Preconditioner.h
    • Ifpack_Utils.h
    • Ifpack_Version.h
    • Ifpack_config.h
  • PyTrilinos.ML
    • MLAPI_Aggregation.h
    • MLAPI_BaseObject.h
    • MLAPI_BaseOperator.h
    • MLAPI_CompObject.h
    • MLAPI_Eig.h
    • MLAPI_EpetraBaseOperator.h
    • MLAPI_Expressions.h
    • MLAPI_Gallery.h
    • MLAPI_InverseOperator.h
    • MLAPI_InverseOperator.h
    • MLAPI_Krylov.h
    • MLAPI_MultiVector.h
    • MLAPI_MultiVector_Utils.h
    • MLAPI_Operator.h
    • MLAPI_Operator_Utils.h
    • MLAPI_PyMatrix.h
    • MLAPI_Space.h
    • MLAPI_TimeObject.h
    • MLAPI_Workspace.h
    • ml_MultiLevelPreconditioner.h
    • ml_config.h
  • PyTrilinos.NOX.Abstract
    • NOX_Abstract_Group.H
    • NOX_Abstract_Vector.H
  • PyTrilinos.NOX.Epetra
    • NOX_Epetra_FiniteDifference.H
    • NOX_Epetra_FiniteDifferenceColoring.H
    • NOX_Epetra_Group.H
    • NOX_Epetra_Interface_Jacobian.H
    • NOX_Epetra_Interface_Preconditioner.H
    • NOX_Epetra_Interface_Required.H
    • NOX_Epetra_Vector.H
  • PyTrilinos.NOX.LAPACK
    • NOX_LAPACK_Group.H
    • NOX_LAPACK_Interface.H
    • NOX_LAPACK_Vector.H
  • PyTrilinos.NOX.Parameter
    • NOX_Parameter_List.H
  • PyTrilinos.NOX.Solver
    • NOX_Solver_Generic.H
    • NOX_Solver_Manager.H
    • NOX_StatusTest_Generic.H
  • PyTrilinos.NOX.StatusTest
    • NOX_StatusTest_Combo.H
    • NOX_StatusTest_FiniteValue.H
    • NOX_StatusTest_Generic.H
    • NOX_StatusTest_MaxIters.H
    • NOX_StatusTest_NormF.H
    • NOX_StatusTest_NormUpdate.H
    • NOX_StatusTest_NormWRMS.H
    • NOX_StatusTest_Stagnation.H
  • PyTrilinos.NOX.TopLevel
    • NOX_Version.H
    • Utils_enums.H
  • PyTrilinos.New_Package
    • New_Package_Version.h
    • Newp_Hello.h
    • Newp_Jambo.h
  • PyTrilinos.Teuchos
    • Teuchos_ParameterList.hpp
    • Teuchos_PyDictParameterList.hpp
    • Teuchos_Version.hpp
  • PyTrilinos.Thyra
    • Thyra_DefaultSpmdVectorSpaceDecl.hpp
    • Thyra_LinearOpBaseDecl.hpp
    • Thyra_MultiVectorBaseDecl.hpp
    • Thyra_ScalarProdVectorSpaceBaseDecl.hpp
    • Thyra_SpmdVectorSpaceBaseDecl.hpp
    • Thyra_SpmdVectorSpaceDefaultBaseDecl.hpp
    • Thyra_VectorBaseDecl.hpp
    • Thyra_VectorSpaceBaseDecl.hpp
    • Thyra_VectorSpaceDefaultBaseDecl.hpp
    • Thyra_VectorStdOpsDecl.hpp
  • PyTrilinos.TriUtils
    • Trilinos_Util_CrsMatrixGallery.h
    • Trilinos_Util_Version.h