OOF2: The Manual

Chapter 7. Extending OOF2

OOF2 is meant to be easily extended to include new physics. Users with a bit of programming experience can add new Fields, Fluxes, Equations, and especially Material Properties. Adding new Fields and Fluxes is easy, but is not of much use unless new Properties are added that use the Fields and Fluxes. Adding Properties is more complicated, but the individual steps are more-or-less straightforward. Adding Equations is easy if the new equations fit the form of the existing Equation classes. Writing new Equation classes can be tricky, but should not be commonly required.

Chapter 7 describes the structure of extensions to OOF2. Chapter 8 describes the actual contents of extension modules. Both assume that the reader is familiar with the C++ and Python programming languages.

7.1. The Mechanics of Extending OOF2

This section describes how OOF2 extensions are constructed from source files. It doesn't describe how to write the source files. The contents of the source files are discussed in other sections.

There are two ways of building OOF2 extensions. Users building OOF2 from the source distribution can include code for an extension in the SRC/EXTENSIONS directory in the main OOF2 directory. Extensions placed there will be built when OOF2 is built and can be loaded automatically when OOF2 starts. These extensions are called internal extensions.

OOF2 can also load extensions built independently of the installation process, possibly after the fact. Such extensions are called external extensions. Adding external extensions is the only option for users who do not have permission to edit files in the main OOF2 directory tree. External extensions must always be explicitly loaded into OOF2, but there is no other difference in the behavior of internal and external extensions.

OOF2 extension code can consist of three types of files: Python code, C++ code, and swig wrapper files. The Python files are imported directly into OOF2, the C++ code is compiled into a shared library, and the swig wrapper files are converted into more C++ and Python files that constitute a Python extension module. This module links to the extension's shared library, and is imported by the extension's Python code. The structural organization of an OOF2 extension is shown in Figure 7.1. Refer to Figure 7.2 and Figure 7.3 to see how the structure of the source and installation files and directories relates to the conceptual structure in Figure 7.1.

Figure 7.1. Components of an OOF2 Extension

Components of an OOF2 Extension

The anatomy of an OOF2 extension. The red boxes indicate the components of an extension, and the labels on the right indicate their sources. The dotted line delimits one of the Python extension modules within the OOF2 extension. Arrows indicate linkages: the Python modules at the top import Python wrapper modules, which import wrapper libraries, which link to shared libraries built from the extension's C++ code. The core OOF2 modules and libraries can be invoked from any part of the extension code.

[Note] Note

It's necessary to make a distinction between an OOF2 extension and a Python extension module. An OOF2 extension is vaguely defined as a bunch of code that adds some functionality to OOF2. Everything in the yellow, blue, and pink boxes in Figure 7.1 is one OOF2 extension. A Python extension module, on the other hand, is specifically defined as a C++ library and some Python code that allows Python to call functions from the library. One OOF2 extension can contain many Python extension modules.

In all cases, the procedure for creating an OOF2 extension is the same:

  1. Write the C++, python, and swig source code.

  2. Write the control file (DIR.py for internal extensions, setup.py for external extensions).

  3. Build and install the extension using python setup.py .... For external extensions, this is similar to building OOF2. For internal extensions, it's identical.

  4. Run OOF2 and find out what's wrong.

  5. Go to 1.