OOF2: The Manual

Chapter 8. Writing OOF2 Extensions

[Warning] Warning

This chapter has not yet been updated for OOF2 version 2.1. A partial discussion of the differences between the 2.0 and 2.1 extension APIs may be found at http://www.ctcms.nist.gov/oof/oof2/property_api_21.html.

This chapter describes the contents of the source files for OOF2 extensions. Chapter 7 describes how to assemble the source files into a loadable extension module.

8.1. Adding New Fields, Fluxes, and Equations

New Fields, Fluxes, and Equations can be added with just a few lines of Python code. The OOF2 Field, Flux, and Equation classes represent global objects — there is only one instance of the Temperature field, for example, although the field may be defined on more than one Mesh, or on none at all. Creating a Field, Flux, or Equation object makes it available for use in a Mesh, and records some information about it, such as its name and dimension.

To create a Field, Flux, or Equation, simply create an object by calling its (Python) constructor,[48] and pass the object to the function problem.advertise. problem is a module in oof2.engine. For example:

from oof2.engine import problem
from oof2.SWIG.engine import field
problem.advertise(field.ScalarField("Temperature")) 

OOF2 predefines some Fields, Fluxes, and Equations in SRC/engine/problem.py. Refer to that file for examples.

The Field subclasses defined in oof2.SWIG.engine.field are:

These classes actually define CompoundFields, which represent the in-plane part of a Field. All of the Field class methods, when applied directly to a CompoundField, act on the in-plane part (which is why the vector field is called TwoVectorField. The out-of-plane part, which is also a Field object, is accessible through the CompoundField's out_of_plane method.

The Python function getCompoundField(name) in the oof2.SWIG.engine.field module returns the CompoundField with the given name. After

tfield = problem.advertise(field.ScalarField("Temperature")) 

the function call field.getCompoundField('Temperature') returns an object identical to tfield.

The Flux subclasses defined in oof2.SWIG.engine.flux are:

The Equation subclasses defined in oof2.SWIG.engine.equation are:

The Equation constructors each take a name, a Flux, and a dimension. The name allows Equations to be retrieved via the Python function getEquation(name) from oof2.SWIG.engine.equation. The Flux is the Flux that the Equation operates on, and the dimension is an integer specifying how many components the equation has. (The divergence of a vector Flux has one component, and the divergence of a tensor flux has three components. A PlaneFluxEquation has as many components as there are out-of-plane components of the associated Flux.)

The Python form of the DivergenceEquation constructor also can take optional arguments specifying whether or not the Equation contains first-order (kinetic) or second-order (dynamic) time derivatives. This facility is still under development, and so the documentation is incomplett.

As an example, the following code fully defines the quantities necessary to solve the static heat conductivity problem (except for the thermal conductivity Material Property, which is discussed later).

from oof2.engine.problem import advertise
from oof2.SWIG.engine.field import ScalarField
from oof2.SWIG.engine.flux import VectorFlux
from oof2.SWIG.engine.equation import DivergenceEquation, PlaneFluxEquation

Temperature = advertise(ScalarField('Temperature'))
Heat_Flux = advertise(VectorFlux('Heat_Flux'))
HeatBalanceEqn = advertise(DivergenceEquation('Heat_Eqn', Heat_Flux, 1))
HeatOutOfPlane = advertise(PlaneFluxEquation('Plane_Heat_Flux', Heat_Flux, 1))
      

8.6. OOF2 Class and Function Reference

This section contains the reference pages for the classes and functions that can be used when programming OOF2 extensions. Both the C++ and Python interfaces are documented, when appropriate. In general, only functions that are relevant to building OOF2 extensions are listed, and base class functions are not listed again in the derived classes.

8.6.1. Field, Flux, and Equation Classes

Table of Contents

Field — Base class for fields
CompoundField — A Field with both in- and out-of-plane parts.
ScalarField — A scalar-valued Field
TwoVectorField — A two dimensional vector-valued Field object
Flux — Base class for Fluxes
VectorFlux — A vector-valued Flux
SymmetricTensorFlux — A 3×3 symmetric tensor valued Flux
FluxData — Store data during flux matrix computation
Equation — Base class for Equations
DivergenceEquation — An Equation subclass for divergence equations
PlaneFluxEquation — An Equation subclass for enforcing plane-flux constraints

8.6.2. Field Iterators and Related Objects

Table of Contents

IndexP — Generic wrapper for index objects
IteratorP — An IndexP that can loop over a range of values
FieldIndex — Base class for index objects
FieldIterator — Base class for FieldIndexes that loop over components
ScalarFieldIndex — Index object for a scalar Field
VectorFieldIndex — Index a vector field
OutOfPlaneVectorFieldIndex — Index the out-of-plane components of a vector
SymTensorIndex — Index a symmetric 3×3 tensor
OutOfPlaneSymTensorIndex — Index the out-of-plane components of a 3×3 symmetric tensor
ScalarFieldIteratorIterate over the components of a scalar field
VectorFieldIterator — Iterate over the components of a vector Field
OutOfPlaneVectorFieldIterator — Loop over the out-of-plane components of a vector Field
SymTensorIterator — Iterate over the components of a symmetric 3×3 tensor
SymTensorInPlaneIterator — Iterate over the in-plane components of a symmetric 3×3 tensor
SymTensorOutOfPlaneIterator — Iterate over the out-of-plane components of a symmetric 3×3 tensor
OutOfPlaneSymTensorIterator — Iterate over the out-of-plane components of a symmetric 3×3 tensor
Planarity — Specify the range of component iterators

8.6.3. Property- and Material-related Classes

Table of Contents

Property — Base class for material properties
PropertyRegistration — Register new Properties
Material — Collection of Properties

8.6.4. Parameter Classes

Table of Contents

Parameter — Parameter classes for OOF2 menu commands, Properties, Outputs, and RegisteredClasses.

8.6.5. Output-related Classes

Table of Contents

Output — Compute output data on a Mesh
PropertyOutput — Compute Property-dependent data on a Mesh
PropertyOutputRegistration — Define a new Property-dependent output quantity
PropertyOutputInit — Initialize Property Outputs
definePositionOutput, defineScalarOutput, defineAggregateOutput — Install Outputs in the GUI
OutputVal — Wrappers for Output data
OutputValue — Wrapper for OutputVal classes

8.6.6. Mesh, Subproblem, and Element Classes

Table of Contents

FEMesh — C++ FE mesh class
CSubProblem — C++ subproblem class
Element — Element class for finite element meshes
Node, FuncNode — Node classes for finite element meshes
ElementNodeIterator — Iterate over Nodes in an Element
ElementShapeFuncIterator — Base class for other Node iterators
ElementMapNodeIterator — Iterate over mapping nodes in an Element
ElementFuncNodeIterator — Iterate over function nodes in an Element
ElementCornerNodeIterator — Iterate over the corner Nodes of an Element
DegreeOfFreedom — Degree of freedom at a Node

8.6.7. Coordinate Classes

Table of Contents

Coord — Coordinate classes
MasterCoord — Position in master coordinate space
Point — Python point class

8.6.8. Miscellaneous Classes and Functions

Table of Contents

acquirePyLock — ensure thread-safe Python API calls
ErrError — Classes and functions for handling exceptions
advertise — announce the creation of Fields, Fluxes, and Equations
conjugatePair — Establish conjugacy relations
loadFile — Specify an external file of documentation


[48] Fields, Fluxes, and Equations are C++ classes, but they should be instantiated by calling their swigged Python constructors.