OOF2: The Manual

The first example returns Field values as OutputVal instances. It's copied^[49] from SRC/engine/IO/outputClones.py.

def _field(mesh, elements, coords, field): 
    ans = [] 
    for element, ecoords in zip(elements, coords): 
        ans += element.outputFields(mesh, field, ecoords) 
    return ans

FieldOutput = output.Output(
    name = "field", 
    callback = _field, 
    otype = outputval.OutputValPtr, 
    params = [meshparameters.FieldParameter("field", outofplane=1)], 
    ) 

To make the FieldOutput available in scripts and the GUI, SRC/engine/IO/outputDefs.py contains the following lines:

from oof2.common.IO import output
from oof2.engine.IO import outputClones
output.defineAggregateOutput('Field:Value', outputClones.FieldOutput) 

defineAggregateOutput states that this Output computes an aggregate object (such as all of the components of a Field or Flux), as opposed to a scalar object. 'Field:Value' categorizes the output — the GUI will refer to it as the Value item in the Field menu.

Note that the FieldOutput has no inputs! It reads its data from the mesh, not from any other Output. The next example, ComponentOutput, has both a parameter and an input, but doesn't read data from the mesh.

def _component(mesh, elements, coords, field, component): 
    if field: 
        comp = field[0].getIndex(component) 
        return [f[comp] for f in field] 
    return []
        
import types

ComponentOutput = output.Output(
    name = "component",
    callback = _component,
    otype = types.FloatType, 
	inputs = [outputval.OutputValParameter('field')], 
	params = [meshparameters.FieldIndexParameter('component')] 
    ) 

Note that despite the name of its input, 'field', the ComponentOutput can extract components from any kind of OutputVal, not only ones containing Fields. The built-in OOF2 outputs use ComponentOutput on Fields, Fluxes, and other multicomponent quantities.

The FieldOutput and ComponentOutput can be combined into a FieldCompOutput, which extracts a given component of a given Field, by using Output.connect. First, a copy of the ComponentOutput is made, giving it a new name at the same time:^[51]

FieldCompOutput = ComponentOutput.clone(name="field component") 

FieldOutput is connected to the input named 'field' of the FieldCompOutput:

FieldCompOutput.connect("field", FieldOutput) 

connect automatically makes a copy of its argument, so we don't have to worry about cloning FieldOutput here.

At this stage, FieldCompOutput has two parameters and no inputs. (The one input of the original ComponentOutput has been filled by the FieldOutput that was connected to it.) The original FieldOutput parameter, named 'field', and the ComponentOutput parameter, named 'component', still remain. 'component' is a direct parameter of FieldCompOutput. It can be accessed by the findParam method, e.g:

FieldCompOutput.findParam('component').value = 'x' 

Setting a parameter's value like this gives it a permanent value, as far as Outputs are concerned. The user will not be able to change the value, and the field-component Output has been changed into an field-x-component Output.

The 'field' parameter of the original FieldOutput can be accessed in a similar, but not identical way. The FieldCompOutput has no parameter called 'field', so we can't use FieldCompOutput.findParam('field'), and the original FieldOutput has been cloned, so its 'field' parameter isn't the same one that FieldCompOutput uses. The parameter can be accessed by specifying both the name of the input and the parameter in the call to findParam:

FieldCompOutput.findParam('field:field').value = Displacement 

Here the first field is the name of the input, and the second is the name of the parameter of that input.

Assuming that we want the user to be able to choose the Field and the component, we don't actually want to use findParam and set the parameter values. However, we don't want the user to see an ugly name like 'field:field'. For one thing, parameter names are used as Python variable names in scripts, and Python variable names can't contain colons. The function Output.aliasParam assigns a new name to an Output parameter, like this:

FieldCompOutput.aliasParam('field:field', 'field') 

Now FieldCompOutput has a parameter called 'field' instead of 'field:field'. Note that there's no conflict between the aliased parameter named 'field' and the input named 'field'. The confusion is always resolved by the context.

Output.findParam never considers aliases, so the call FieldCompOutput.findParam('field') will fail (it will raise a KeyError exception). To retrieve an aliased parameter, use Output.resolveAlias instead. If resolveAlias can't find an alias, it looks for a parameter, so the following three function calls are equivalent:

param = FieldCompOutput.resolveAlias('field')
param = FieldCompOutput.resolveAlias('field:field')
param = FieldCompOutput.findParam('field:field') 

Aliases are only known to the Outputs that create them. In the example above, the FieldOutput containing the original 'field' parameter doesn't know that it's been aliased. However, if FieldCompOutput were to be used as an input to another Output, like this:

SomeOtherOutput.connect('otherinput', FieldCompOutput) 

then the 'field' parameter could be accessed by

param = SomeOtherOutput.resolveAlias('otherinput:field') 

using the alias still stored in FieldCompOutput.

The examples above all use at most one parameter and one input. Outputs can have as many parameters and inputs as they like. The PointSumOutput from SRC/engine/IO/outputClones.py is used to add the Displacement to the original position of a node. It's actually a little more general than that — it takes two input streams which are lists of Coord or Point objects, multiplies them by scalar factors, and adds them together.

from oof2.SWIG.common import coord
from oof2.common import primitives
from oof2.common.IO import output
from oof2.common.IO import parameter

def _pointSum(mesh, elements, coords, point1, point2, a, b): 
    ans = [a*f+b*s for f,s in zip(point1, point2)] 
    return ans

PointSumOutput = output.Output(
    name="point sum",
    callback=_pointSum,
    otype=(coord.Coord, primitives.Point), 
    inputs=[coord.CoordParameter("point1"), coord.CoordParameter("point2")], 
    params=[parameter.FloatParameter("a", default=1.0), 
            parameter.FloatParameter("b", default=1.0)]
    ) 

The PointSumOutput is used in SRC/engine/IO/outputDefs.py to add the displacement to the node position. The displacement values come from displacementOutput and the position values come from posOutput, which won't be explicitly discussed here. The connection looks like this:

enhancedPosition = outputClones.PointSumOutput.clone(
    name='enhanced position',
    params=dict(b=1), 
    tip='Exaggerated displacement field.') 
enhancedPosition.connect('point1', displacementOutput) 
enhancedPosition.connect('point2', outputClones.posOutput) 
enhancedPosition.aliasParam('a', 'factor', default=1.0, 
                            tip='Displacement multiplier.') 

At this point, the enhancedPosition Output has one parameter, 'factor', and no inputs. It produces a list of node positions, with displacement exaggerated by the given amount. The actualPosition Output is now simply created by cloning enhancedPosition and setting the enhancement factor to 1.0:

actualPosition = enhancedPosition.clone(
    name='actual position',
    params=dict(factor=1.0),
    tip='Displaced position.') 

Finally, both enhancedPosition and actualPosition are made available in the GUI by calling definePositionOutput:

output.definePositionOutput('actual', actualPosition)
output.definePositionOutput('enhanced', enhancedPosition)