OOF2: The Manual

	Warning
	This section 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.

Finite element problems which lead to a symmetric stiffness matrix can be solved efficiently by the conjugate gradient method. OOF2 needs to be told how to construct a symmetric matrix, though.

Consider a simple elasticity problem. The degrees of freedom are the components of the displacement at each node of the mesh. The equations are the components of the force balance at each node. In the stiffness matrix, degrees of freedom correspond to columns and equations correspond to rows. The matrix will be symmetric if the columns and rows are ordered so that the force component and node of the n^th row are the same as the displacement component and node of the n^th column.

In general, this correspondence is not trivial. If the stress in the example above came from material properties other than elasticity, the matrix would not necessarily be symmetric. Including thermal expansion can make an elasticity problem asymmetric.

The function conjugatePair in the oof2.SWIG.engine.conjugate module establishes the correspondence between Field and Equation components that is necessary to build a symmetric matrix. After creating Fields and Equations, call conjugatePair like this:

from oof2.SWIG.engine.conjugate import conjugatePair
conjugatePair(proptype, equation, eqncomp, field, fieldcomp) 

where proptype is the PropertyType of the Property that will be symmetrized by this conjugacy pair; equation is an Equation object; field is a Field object, and eqncomp and fieldcomp are either FieldIndex objects or lists of them. For example, the following code establishes the correspondence between the x and y components of the displacement field and the force balance equation (import statements have been omitted for conciseness):

ForceBalanceEquation = getEquation('Force_Balance')
Displacement = getCompoundField('Displacement')
x = VectorFieldIndex(0)
y = VectorFieldIndex(1)
conjugatePair("Elasticity", ForceBalanceEquation, [x,y],
                            Displacement, [x, y]) 

Calling conjugatePair is necessary but not sufficient for OOF2 to create symmetric stiffness matrices. The Properties that contribute to the stiffness matrix must also support symmetry. This is discussed in Section 8.4.

It is not required that conjugatePair be called on all defined fields and equations, but failing to do so will make the conjugate gradient solver unavailable for problems involving these fields and equations.

It is also not necessary to call the conjugatePair for the predefined fields in OOF2, since conjugacy is predefined for these fields and equations in the problem.py file.