Introduction to PyTrilinos Development
======================================

The purpose of PyTrilinos is to provide a high-level, dynamic and
interactive interface to selected Trilinos packages.  Being a
PyTrilinos developer requires that you are, or will become, an expert
in the following areas:

* **C++.** The vast majority of Trilinos development is in C++, and
  much of that development takes advantage of advanced C++ or
  object-oriented techniques such as polymorphism, templating and
  reference-counted memory management.  A high level of comfort with
  C++ is required.

* **Python.** Obviously, PyTrilinos is a package of python modules, so
  familiarity with the language is a must.  Beyond that, however, it
  is important to understand the philosophical underpinnings of the
  language (which are very different from C++) in order to develop
  interfaces that are "pythonic", i.e. that are consistent with the
  many conventions of the language.

* **Trilinos.** At a bare minimum, a PyTrilinos developer should have
  a decent level of expertise regarding the Trilinos package that is
  to be wrapped, as well as those packages that the package interacts
  with.  This expertise would include related development tools such
  as the CMake build system and the GIT version control system.

* **SWIG.** SWIG is the Simple Wrapper and Interface Gernerator, and
  is the workhorse for generating the code that gets compiled to
  become python extension modules.  The 'S' in SWIG comes from the
  fact that SWIG can read and parse a header file and generate code
  that will compile, can be imported into a python shell, and mimics
  the C/C++ interface (within the constraints of the language).
  However, SWIG is very powerful, and almost all of its provisions can
  be overwritten by the python interface developer.  Trilinos is
  sufficiently complex that such overrides are commonplace, and the
  PyTrilinos developer must have a high degree of comfort doing this.

* **The Python C/API.** When such overrides are necessary, it usually
  involves writing code that is compliant with the Python C/API.  In
  addition to the structs and function prototypes provided by the
  Python C/API, this means a thorough understanding of python
  exception handling (essential for a dynamic language) and reference
  counting (which requires more programmer intervention in C than in
  C++).

* **NumPy.** NumPy is the accepted standard python package for
  handling arrays of contiguous (or strided) homogeneous data.  Any
  PyTrilinos classes or arguments that involve arrays of data should
  provide an interface that is highly compatible with NumPy.

Each of these languages, libraries, tools and interfaces have
extensive documentation available on-line, and should be accessed
frequently by the PyTrilinos developer.  The purpose of this
Developers Guide is detail how these tools are used together to
generate PyTrilinos, and to document certain conventions that have
been adopted for all PyTrilinos packages.
