OOF2: The Manual
| Chapter 7. Extending OOF2 | ||
|---|---|---|
|
 |
|
Table of Contents
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.
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
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]](IMAGES/note.png) |
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:
-
Write the control file (
DIR.pyfor internal extensions,setup.pyfor external extensions). -
Build and install the extension using
python setup.py .... For external extensions, this is similar to building OOF2. For internal extensions, it's identical. -
Run OOF2 and find out what's wrong.
-
Go to 1.
|
|
|
|
| 6.8. Searchable Index of Reference Pages |  |
7.2. External Extensions |