PyTrilinos Logo PyTrilinos Documentation for the Trilinos Release 7.0 Branch

PyTrilinos Documentation for the Trilinos Release 7.0 Branch

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.

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++ documention, as the C++ and python interfaces are kept identical 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 for release 7.0 has not been tested against 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 or higher, but backward compatibility has been maintained with versions 0.9.x.
  • SWIG 1.3.28 or higher. SWIG is the Simple Wrapper and Interface Generator, and is the workhorse for generating the python interface to Trilinos packages. We recommend the latest version, which is currently 1.3.29.

Building PyTrilinos

To build PyTrilinos, simply include the option --enable-python[-path] when you run configure. This will enable the python wrappers for every Trilinos package that supports them. If, for some reason, you wish to disable the python wrappers for a particular package, you may use --disable-package-python, where you substitute the package name for package.

For MPI builds, it is important that the PyTrilinos extension modules be linked against shared Trilinos libraries. If not, you may encounter problems where an internal attempt to cast certain variable types will fail. Since Trilinos only supports building static libraries, The PyTrilinos package will automatically attempt to create new, shared versions of certain Trilinos libraries, and then re-link the python extension modules against these new shared libraries. This is currently only supported for Linux and Darwin (Mac OS X) operating systems.

If you build PyTrilinos under Linux or Darwin using MPI, 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/src

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, you may need to tell mpirun to export this environment variable in order to use it:

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

Known Issues

  • 64-bit. There are known issues with PyTrilinos on a 64-bit architecture, sometimes manifesting as a build error, sometimes manifesting as a runtime error. This will be a high priority for a future release.
  • Cygwin. Testing under cygwin has resulted in mysterious crashes with no errors reported. This is also a priority for a future release.
  • 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 cannot 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 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.
  • IFPACK provides incomplete factorization preconditioning.
  • Anasazi is a pacakge of eigensolvers.
  • ML provides multi-level (mesh-based and algebraic multigrid) preconditioning.
  • NOX is a package of nonlinear solvers.
  • LOCA provides support for continuation algorithms, useful for finding turning points, bifurcation points, etc.
  • New_Package provides a template for Trilinos developers. The C++ package provides an example for turning a C++ project into a Trilinos package, and the python module provides an example for providing a python interface to a Trilinos package.

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