Adding New Modules to PyTrilinos

If you want to add a Trilinos package as a new module in PyTrilinos, here are the necessary steps.

  1. Add the package to the configure script so that PyTrilinos recognizes that it can use it. Within configure.ac, copy and paste one of the

    TAC_ARG_ENABLE_CAN_USE_PACKAGE
    

    macros, and modify the arguments for your package.

  2. If your package uses nested namespaces, then the python interface should use corresponding nested modules. To partially facilitate this, within the src/PyTrilinos (and/or the src-boost/PyTrilinos) directory, make a directory with your package name. Within that directory, create an empty file (via touch, for example) named .dummy.in. At the end of configure.ac, modify the

    AC_CONFIG_FILES
    

    macro to include the argument

    src/PyTrilinos/PACKAGE/.dummy
    

    where PACKAGE is the name of your package (and src could be src-boost if appropriate). This may need to be repeated for more deeply nested namespaces (such as NOX/Epetra, for example).

  3. Tell the Makefile in the source directory (either src or src-boost) to optionally enable the package. Within src/Makefile.am, you will find a series of automake directives that look like

    @HAVE_PYTRILINOS_TEUCHOS_TRUE@ENABLE_TEUCHOS=true
    @HAVE_PYTRILINOS_TEUCHOS_FALSE@ENABLE_TEUCHOS=
    

    Copy and paste one of these sets and change (in this example) the four occurences of TEUCHOS to the (all-caps version of the) name of your package.

  4. Gain access to the exported variables of the package's Makefile. Within this same source directory Makefile.am, include the package export Makefile. For example, for Teuchos, you will see

    # Teuchos
    if HAVE_PYTRILINOS_TEUCHOS
    include $(top_builddir)/../teuchos/Makefile.export.teuchos
    ...
    endif
    

    Change the case-sensitive Teuchos package names to your case-sensitive package names.

  5. Within this same if block within this Makefile.am, set up the build variables. Within the src directory, these variables are

    PACKAGE_INTERFACES = ...
    PACKAGE_PROXIES    = ...
    

    and in the src-boost directory, they are

    PACKAGE_WRAPPERS = ...
    PACKAGE_PROXIES  = ...
    

    where PACKAGE is the (all-caps version of the) name of your package. PACKAGE_INTERFACES should be a space-delimited list of swig interface files. PACKAGE_PROXIES should be a list of python proxy files, each with PyTrilinos/ directory prefix. PACKAGE_WRAPPERS should be a list of boost C++ wrapper files that implement the BOOST_PYTHON_MODULE macro.

    Typically, you will have a single swig interface file named after your package with a .i extension; a single python proxy file named after you package with a .py extension; and a single boost C++ wrapper named after your package with a _wrap.cpp suffix. In src you will need to create the .i file; in src-boost, you will have to create both the _wrap.cpp and .py files.

  6. Again, within this same Makefile.am, after these package-specific definitions, you will find, for example

    PROXIES = ...
    

    where the right-hand side is a list of all of the individual package _PROXIES variables. Add you package to this and other related lists.

  7. This should be sufficient for getting started. From the PyTrilinos main directory, run the bootstrap command to generate the configure and Makefile.in files that will be used by the top-level configure script.