OOF2: The Manual

Name

PropertyRegistration — Register new Properties

Synopsis

from oof2.engine.propertyregistration import PropertyRegistration

class PropertyRegistration:
   def __init__(self, name, subclass, modulename, ordering,
                params=[], fields=[], fluxes=[],
                propertyType=None, outputs=[],
                nonlinear=0, secret=0,
                tip=parameter.emptyTipString, discussion=parameter.emptyTipString)
	    

Description

Every new Property class must have a single PropertyRegistration object. The PropertyRegistration contains meta-data 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. It's sufficient to swig the class and the constructor. Other methods do not have to be made available in Python.

PropertyRegistration constructor parameters

The only required parameters are name, subclass, modulename, and ordering. The others can all be omitted if they're not needed for a particular Property. The default values for the optional parameters are given in the synopsis, above.

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

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 class 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 PyPropertyWrapper. Note that the argument is the actual class, not an instance of the class.

modulename

modulename is a string containing the name of the Python module in which the Python interface to the class is defined. For example, if the swig output file is shoofly.py in directory XYZ which is in the Python path, then modulename would be 'XYZ.shoofly'.

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

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 paramslist as they do in the Property's 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.

fields

This is a list of Field objects, indicating which Fields the Property depends upon. The Property will not be used unless all of the Fields in the list are defined on the mesh being solved.

fluxes

This is a list of Flux objects, indicating which Fluxes the Property contributes to. The Property will not be used unless some of the Fluxes in the list are used in the active Equations.

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

outputs

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

nonlinear

nonlinear should be set to 1 if nonlinear solvers will be needed to solve a mesh containing this Property. Generally, this means that the Property contains quantities that are Field dependent.

secret

secret should be set to 1 if the Property shouldn't appear in the GUI. This should not be used except by those who know what they're doing.

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. The manual will embed it inside a <refsect1> element.[63]

Since it's often inconvenient to include large blocks of text inside a PropertyRegistration, the text can be put into a separate file. The file name can be passed to the function loadFile from the oof2.common.IO.xmlmenudump module. Then discussion should be set to the return value from loadFile. (loadFile doesn't actually read the file unless the users manual is being generated, so there's no cpu or memory used when doing it this way, and the file often doesn't even have to be distributed with the code.) In any case, the discussion argument is optional. A generic message will be generated if it's absent.

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.

Table 8.3. Property Types

propertyType

Description

'ChargeDensity'

Spatial charge distribution

'DielectricPermittivity'

Dielectric permittivity

'Elasticity'

Elastic modulus

'ForceDensity'

Externally applied body force density

'Heat Source'

Heat sources and sinks

'HeatCapacity'

Heat capacity

'MassDensity'

Mass density, for dynamic equations

'Orientation'

Crystalline orientation

'PiezoElectricity'

Piezoelectric modulus

'Plasticity'

Plastic deformation rules

'ThermalConductivity'

Thermal conductivity

'ThermalExpansion'

Thermal expansion tensor and stress-free temperature




[63] The simplest legal discussion string has the form

<para>blah blah blah</para>