OOF2: The Manual

PropertyRegistration
	Property and Material Classes

Name

PropertyRegistration — Register new Properties

Synopsis

from ooflib.engine.propertyregistration import PropertyRegistration

class PropertyRegistration:
  def __init__(self, name, subclass, ordering, propertyType, params= [], outputs= [], secret= False, tip= None, discussion= None)
  def fluxInfo(self, fluxes, fields= [None], time_derivs= [], nonlinear= False, time_dependent= False)
  def eqnInfo(self, equations, fields= [None], time_derivs= [], nonlinear= False, time_dependent= False)
  def getParameter(self, name)

Source Files

SRC/engine/propertyregistration.py

Description

Every new Property class must have a single PropertyRegistration object. The PropertyRegistration contains metadata about the Property and inserts it in the global list of all Property classes, which allows it to appear in the user interface.

PropertyRegistrations are defined only in Python, even for Properties that are defined in C++. This means that all C++ Property subclasses must be swigged, in order to be accessible to their PropertyRegistration objects. It's sufficient to swig the Property subclass and the constructor. Other Property methods do not have to be made available in Python.

Once a PropertyRegistration has been created, it is unnecessary to store a reference to it explicitly. All PropertyRegistrations are stored a static list in the Property class.

There are three subclasses of Property from which all other Properties are derived. All of them use the same PropertyRegistration class, but differ^[71] in how additional metadata must be added to the registration:

Registrations for FluxProperties must call PropertyRegistration.fluxInfo().
Registrations for EqnProperties must call PropertyRegistration.eqnInfo().
Registrations for AuxiliaryProperties should not call either function.

These functions should be called immediately after the PropertyRegistrations are created.

Methods

`PropertyRegistration.init(name, subclass, ordering, params, propertyType, ...)`

The only required constructor parameters are name, subclass, ordering, and propertyType. The others can all be omitted if they're not needed for a particular Property.

When creating a PropertyRegistration, it's advisable to use Python keyword arguments so that it's clear which parameters have been omitted.

Parameters
name

name is a string containing the name of the Property, as it will appear in scripts and in the GUI. In the GUI, Properties are arranged hierarchically in a tree. The name is a colon separated string, in which each segment is a branch of the Property tree. For example, the cubic elasticity property's name is Mechanical:Elasticity:Anisotropic:Cubic, and it appears in the GUI like this:

subclass

This is the Property subclass that is being registered. It must either be a swigged C++ Property subclass, a Python class derived from a swigged C++ Property subclass, or a Python class derived from PyFluxProperty or from PyEqnProperty. Note that the argument is the actual class, not an instance of the class.

ordering

ordering determines this Property's position when listed in the GUI. It has no other significance. It can be either an integer or a floating point number. Nodes of the Property tree in the GUI are listed in order of increasing ordering. The ordering of an intermediate node in the tree is taken to be the smallest ordering of any of its children.

propertyType

The propertyType is a string that categorizes the Property. No two Properties in a Material can have the same propertyType. The function Material::fetchProperty locates Properties by their propertyType.

When registering a new Property, it's important to use the same propertyType that was used for other Properties of that type. The existing OOF2 propertyTypes are given in Table 8. If a new Property doesn't belong in any of the existing types and doesn't conflict with them, it is possible to create a new type. It is just a character string.

params
The arguments for every Property's constructor are a name, a registration, and a variable number of additional values that quantify the Property's behavior. These additional arguments are determined by the PropertyRegistration's params argument. params is a Python list of Parameter subclass instances. Each entry in the list specifies a type (which is implied by the Parameter subclass), a constructor argument name, a default value, and a help string. The parameters must appear in the same order in the params list as they do in the Property constructor's argument list.

For example, a mass density Property could have a FloatParameter called density,
```
params = [FloatParameter('density', value=1.0, tip='mass density')] 
```
while a triclinic thermal expansion Property would have a TriclinicRank2TensorParameter (for the modulus) and a FloatParameter for the zero-stress temperature:
```
params = [TriclinicRank2TensorParameter(
                     name='alpha',
                     value=TriclinicRank2Tensor(xx=1, yy=1, zz=1),
                     tip='Thermal expansion tensor'),
          FloatParameter('T0', 0.0, tip='Stress free temperature')
         ] 
```
See Parameter for a list of all of OOF2's built-in Parameter types and their constructor arguments.
outputs

outputs is a list of strings, each one the name of an PropertyOutput to which the Property's output function contributes.

secret

secret should be set to True if the Property should not appear in the GUI. It will still be available in scripts, for those who are in the know.

tip

tip is a short string describing the Property. It should be something suitable for displaying as a pop-up tooltip in the GUI.

discussion

discussion is a longer string describing the Property, meant to be included in the OOF2 Manual. The string should be written in DocBook XML version 4.5. The manual will embed it inside a <refsect1> element.^[72]

Since it's often inconvenient to include large blocks of text inside a PropertyRegistration, the text can be put into a separate file, and discussion can be set to xmlmenudump.loadFile(filename). loadFile() doesn't actually read the file unless the OOF2 Manual is being generated, so there's no cpu or memory cost to doing it this way. In any case, the discussion argument is optional. Omitting it has no consequences except when generating the manual.

`fluxInfo(self, fluxes, fields=[None], time_derivs=[0], nonlinear=False, time_dependent=False)`

fluxInfo() adds additional metadata to Properties that are derived from FluxProperty. It must be called after the PropertyRegistration for the FluxProperty is created.

For example, this is how isotropic elasticity is registered in SRC/engine/properties/elasticity/iso/iso.spy:

from ooflib.engine import problem
from ooflib.engine import propertyregistration
            
reg = propertyregistration.PropertyRegistration(
    name="Mechanical:Elasticity:Isotropic",
    subclass=IsoElasticityProp,
    ...     other PropertyRegistration parameters go here
)

reg.fluxInfo(fluxes=[problem.Stress],
             fields=[problem.Displacement],
             time_derivs=[0])

This indicates that the registered Property contributes to the Stress flux, uses the Displacement field, and no time derivatives of the Field.

Parameters

fluxes

A list of all of the Fluxes that the Property contributes to. The Fluxes can be obtained by importing the module defining them (problem.py in the example above) or by calling getFlux().

fields

A list of all of the Fields that contribute to the Flux via this Property. When solving equations, the Property will not be used unless all of the listed Fields are defined.

The default value of fields is [None], meaning the the Property can be used even if no Fields are defined. Setting fields to [] (an empty list) will disable the Property.

time_derivs

A list of integers, indicating which time derivatives of fields are used in this Property. 0 is the Field itself, 1 is its first time derivative, and 2 is its second time derivative. In the example above, time_derivs=[0] because only the 0^th order time derivative is required to compute the Stress. If isotropic viscosity had been used, time_derivs=[1] would have been used.

If the fields list contains more than one Field, time_derivs should include the derivative orders for all of the Fields. That is, if any one Field's n^th derivative is used, n should be in the list.

The default value of time_derivs is [0].

nonlinear

Set nonlinear to True if the Property is a nonlinear function of the Fields or their time derivatives. The default value is False.

time_dependent

Set time_dependent to True if any part of the Property itself (not the Fields) changes in a time dependent way. For example, if the elastic modulus were an explicit function of time, you'd set time_dependence=True in its registration. The default value is False.

`eqnInfo(self, equations, fields=[None], time_derivs=[], nonlinear=False, time_dependent=False)`

eqnInfo() adds additional metadata to Properties that are derived from EqnProperty. It must be called after the PropertyRegistration for the EqnProperty is created.

For example, this is how heat capacity is registered in SRC/engine/properties/heatcapacity/heatcapacity.spy:

from ooflib.SWIG.engine import equation
from ooflib.SWIG.engine import field
from ooflib.engine import propertyregistration

reg = propertyregistration.PropertyRegistration(
    name='Thermal:HeatCapacity:ConstantHeatCapacity',
    subclass=HeatCapacityProp,
    ...     other PropertyRegistration parameters go here
    )
reg.eqnInfo(equations=[equation.getEquation("Heat_Eqn")],
            fields=[field.getField("Temperature")],
            time_derivs=[1])

This indicates that the registered Property makes direct contributions to the Heat_Eqn equation,^[73] using the first time derivative of the Temperature.

Parameters

equations

A list of all the Equations that the Property contributes to directly. If the Property contributes to a Flux that appears in the Equation, use fluxInfo() instead. The Equations may be obtained by calling getEquation() as in the example above, or by importing the module defining them (ooflib.engine.property, for the built-in Equations).

fields

A list of all of the Fields that contribute to the Equation via this Property. When solving equations, the Property will not be used unless all of the listed Fields are defined.

The default value of fields is [None], meaning the the Property can be used even if no Fields are defined. Setting fields to [] (an empty list) will disable the Property.

time_derivs

A list of integers, indicating which time derivatives of fields are used in this Property. 0 is the Field itself, 1 is its first time derivative, and 2 is its second time derivative. In the example above, time_derivs=[1] because the heat capacity multiplies the first time derivative of Temperature in the heat equation.

If the fields list contains more than one Field, time_derivs should include the derivative orders for all of the Fields. That is, if any one Field's n^th derivative is used, n should be in the list.

The default value of time_derivs is [0].

nonlinear

Set nonlinear to True if the Property is a nonlinear function of the Fields or their time derivatives. The default value is False.

time_dependent

Set time_dependent to True if any part of the Property itself (not the Fields) changes in a time dependent way. For example, if the heat capacity were an explicit function of time, you'd set time_dependence=True in its registration. The default value is False.

Property Types

The following table lists the propertyTypes used in OOF2 PropertyRegistrations. Not all of the types listed here are fully available yet — some are still in development or reserved for future use. Some are defined in the internal extensions that are distributed with OOF2.

Table 8. Property Types

`propertyType`	Base Class	Equation or Flux	Role
`'ChargeDensity'`	EqnProperty	Coulomb_Eqn	Source term
`'Color'`	AuxiliaryProperty		Display color
`'Current'`	FluxProperty	Charge_Flux	Migration coefficient (coefficient of Voltage gradient)^[a]
`'Damping'`	EqnProperty	Force_Balance	Coefficient of first time derivative of Displacement
`'DielectricPermittivity'`	FluxProperty	Total_Polarization	Dielectric permittivity (coefficient of the Voltage gradient
`'Diffusivity'`	FluxProperty	Atom_Flux	Chemical diffusivity (coefficient of the gradient of Concentration)^[a]
`'Elasticity'`	FluxProperty	Stress	Elastic modulus (coefficient of the gradient of Displacement)
`'ForceDensity'`	EqnProperty	Force_Balance	Source term
`'HeatCapacity'`	EqnProperty	Heat_Eqn	Heat capacity (coefficient of the first time derivative of Temperature)
`'HeatSource'`	EqnProperty	Heat_Eqn	Source term
`'IonDiffusion'`	FluxProperty	Charge_Flux, Atom_Flux	Coupling between Voltage and Concentration.^[a]
`'MassDensity'`	EqnProperty	Force_Balance	Mass density (coefficient of the second time derivative of Displacement)
`'Mobility'`	EqnProperty	Atom_Eqn	Mobility (coefficient of the first time derivative of Concentration)^[a]
`'Orientation'`	AuxiliaryProperty		Crystalline orientation
`'PiezoElectricity'`	FluxProperty	Total_Polarization, Stress	Piezoelectric modulus (coupling between Displacement and Voltage)
`'Plasticity'`	FluxProperty	Stress	Reserved for future use.
`'PyroElasticity'`	FluxProperty	Total_Polarization	Temperature-dependent polarization
`'StressFreeStrain'`	FluxProperty	Stress	Constant Displacement-independent Stress offset.
`'ThermalConductivity'`	FluxProperty	Heat_Flux	Thermal conductivity (coefficient the gradient of Temperature)
`'ThermalExpansion'`	FluxProperty	Stress	Thermal expansion (Temperature dependent Stress)
`'ViscoElasticity'`	FluxProperty	Stress	Viscoelasticity (coefficient of the gradient of the time derivative of Displacement)
`'ZStrain'`	FluxProperty	Stress	Contribution to Stress that gives a fixed non-zero strain.
^[a]Defined in `EXTENSIONS`.

^[71]Yes, this is ugly from an OO perspective.

^[72] The simplest legal discussion string has the form

<para>blah blah blah</para>

^[73]Note that in this example the Equation and Field are retrieved from the ooflib.SWIG.engine.field and ooflib.SWIG.engine.equation modules by getField() and getEquation() instead of via variables declared in the ooflib.engine.problem module, as in the earlier example. Both methods work.


Property and Material Classes		Property