OOF2: The Manual

8.6. Adding New Material Properties
	Chapter 8. Writing OOF2 Extensions

8.6. Adding New Material Properties

New Material Properties are the most complicated kind of OOF2 extension. Just to make it simpler, there are two ways of doing it. Properties can be written in C++ or they can be written in Python. Python Properties are a bit easier to write and install, but will run significantly more slowly. It may be convenient to develop new Properties in Python and translate them to C++ after the bugs have been worked out.

Whether a Property is written in C++ or Python, the same code elements must be present. Not all of them are necessary for every Property. It is safe simply to omit the unnecessary ones.

A Property consists of a class definition and a PropertyRegistration object. The registration contains metadata about the Property and allows it to be found in the user interface. The class must be a subclass of one of these intermediate base classes:

A FluxProperty contributes to a Flux. For example, Mechanical:Elasticity:Isotropic contributes to Stress.
An EqnProperty contributes directly to an Equation. For example, Mechanical:MassDensity:ConstantMassDensity provides the mass times acceleration term in the Force_Balance equation.
An ??? is neither of the above, but can be used indirectly by other Properties. For example, Orientation is used by all anisotropic Properties. Color is used to display Materials.

See the documentation for each intermediate class for the details.

Property classes perform the following types of tasks (the links below each task lead to detailed documentation, see the pages for the classes for the full list of methods):

Identification. Properties have names by which they are identified in the user interface. They also have a propertyType. A propertyType is a string that identifies the Property's physical role. Each Material instance can have at most one Property of each propertyType. For example, all Properties that provide an elastic modulus have the type 'Elasticity', and all thermal expansion Properties have the type 'ThermalExpansion'. Authors of new types of Property should invent new propertyType strings. Authors of new versions of a preexisting Property should examine the existing PropertyRegistrations and reuse the same propertyType.
- PropertyRegistration
- Property constructor
Cross Referencing. Sometimes a Property needs to use data from other Properties in the same Material. For example, any anisotropic Property will need to find out its Material's Orientation. Cross referencing allows a Property to use propertyType information to locate other Properties. This is done after a Material is constructed but before it is used for numerical computations.
- Property::cross_reference
Precomputation. When constructing the finite element stiffness matrix, the OOF2 program loops over all Elements and asks their Materials to ask their Properties to make their contributions to the matrix. For efficiency, Properties may want to precompute some quantities before this process begins. There are two possible precomputation points: Element- and Node-independent computations that are done before looping over Elements, and Element-dependent ones that are done before looping over Nodes.
Computation. Properties can make contributions to the finite element stiffness matrix and to the right-hand side vector of external “forces”.
- FluxProperty::flux_matrix
- FluxProperty::flux_offset
There are also a few functions that Properties may define that influence the way they're used or the way a computation is done:
- Property::is_symmetric
- PhysicalProperty::integration_order
Postcomputation. This is just like precomputation, but later. It can be done either after the computation on each Element, or after a full solution has been obtained.
Outputs. Many output quantities, such as Field invariants, are defined without reference to Properties, but there are also many outputs, such as energy densities, that depend upon a Property in one way or another, and rely upon the Property's code. See Section 8.7 to learn how to add new outputs.
- Property::output


8.5. Conjugate Pairs		8.7. Adding New Outputs