OOF2: The Manual

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 ooflib.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 ooflib.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 iterable containers 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):

equation = getEquation('Force_Balance')
field = getField('Displacement')
conjugatePair("Elasticity",
              equation, equation.components(),
              field, field.components()) 

See conjugatePair() for some important details about making sure that the Equation and Field components are in the same order.

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.6.

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 SRC/engine/problem.py.