OOF2: The Manual

Output
Prev  8.6.5. Output-related Classes  Next

Name

Output — Compute output data on a Mesh

Python Synopis

import oof2.common.IO.output
	
class Output:
  def __init__(self, name, otype, callback, inputs=[], params=[], tip=parameter.emptyTipString, discussion=parameter.emptyTipString, parent=None)
  def clone(self, name=None, params={}, tip=None, discussion=None)
  def connect(self, iname, input)
  def findParam(self, path)
  def aliasParam(self, paramname, alias, default=None, tip=None)
  def resolveAlias(self, alias)

Source Files

  • SRC/common/IO/output.py: Output class definition
  • SRC/engine/IO/outputClones.py: generic Output instances
  • SRC/engine/IO/outputDefs.py: fully constructed Output instances

Description

OOF2 Output objects perform simple operations on data derived from a finite element Mesh. Simple Output objects may be combined to perform more complicated operations. An overview and examples may be found in Section 8.5.

The Output class is only available in Python.

Methods

Output.__init__(self, ...)

Only the first three arguments to the constructor are required. The arguments are:

name

name is a string, used to identify this Output in error messages. It's not used otherwise.

otype

The output from an Output is always a list of objects. otype specifies the data type of the objects in the list. If otype is a Python class or an instance of a class, then the objects must be instances of that class. If otype is a Python type object (e.g, types.FloatType) or an instance of that type (e.g, 3.14) then the output must be instances of that type.

If an Output can produce values of different types, otype should be a list or tuple of type specifications (e.g, (types.IntType, coord.Coord)).

callback

callback is a function that will be called to process the data. See the section called “The callback function” for the details.

inputs

inputs is a list of Parameter objects, describing the inputs to this Output, if any. Only the name and subclass of each Parameter are important. The name is used to identify the input, and the subclass determines its type. When one Output is connected to an input of another, the otype of the first Output must be compatible with the Parameter type of the second Output's input.

Each input in the list corresponds to an argument of the callback function. The argument's value will be a list of objects whose type is given by the input's Parameter type. For example, an input FloatParameter('xyz') will cause a list of floats named xyz to be sent to the callback.

The names of all of the inputs must be unique.

Some Outputs don't require any inputs, in which case this constructor argument can be omitted. Its default value is an empty list, [].

params

params is a list of Parameter objects, specifying parameters that govern the Output's behavior. The value of each parameter will be passed to the callback function.

The names of the parameters must be unique, and must also not conflict with the names of any of the inputs.

Parameters that are to be set by the user must not have values. That is, if FloatParameter('x', value=3) appears in the params list, then the callback argument x will always have the value 3. To set an initial value that can be changed by the user, use default, as in FloatParameter('x', default=3).

tip

tip is a character string that describes the role of the Output. It appears in GUI tooltips and in the documentation.

discussion

discussion is a more verbose description of the Output, meant for inclusion in the OOF2 user manual. It can either be a string or a reference to a file via the xmlmenudump.loadFile function. The string or the contents of the file must be docbook xml code suitable for the contents of a refsection.

clone(name, params, tip, discussion)

clone makes a copy of an Output, including all of its parameters and any connected inputs.

All of of the arguments to clone are optional. The arguments are:

name

The name of the copied Output. This name is only used in error messages. If omitted, the name of the clone is the same as the name of its parent.

params

params is a dictionary whose keys are parameter names or aliases. The clone's parameters that are specified by the keys in the dictionary will be set to the values in the dictionary. Parameters set in this way are set permanently — they will not be available to the user. If params is omitted, only those parameters that are set in the original Output will be set in the clone.

tip

A tip provided in the clone command will replace the original tip provided in the constructor.

discussion

A discussion provided in the clone command will replace the original discussion provided in the constructor.

connect(iname, input)

connect directs the data computed from one Output into the input of another. The otype of the connected Output must agree with the Parameter type of the input slot.

The arguments are:

iname

The name of the input slot to which the data should be directed.

input

The Output object which should be connected to the input slot. The object will be cloned automatically before it's connected.

For example, if an Output were created like this: 

downstream = Output(..., inputs=[FloatParameter('x')], ...)

and a second one were created like this: 

upstream = Output(..., otype=FloatType, ...)

then they could be connected like this: 

downstream.connect('x', upstream)

findParam(path)

findParam returns the Output parameter specified by the path argument. path must be a colon separated string, where the last segment is the name of a parameter, and the preceding segments (if any) are names of inputs. For example, given these two Outputs: 

out1 = Output(..., params=[FloatParameter('x')], ...)
out2 = Output(..., inputs=[FloatParameter('y')], ...)

connected like this: 

out2.connect('y', out1)

the parameter named 'x' can be retrieved from out1 like this: 

param1 = out1.findParam('x')

or from out2 like this: 

param2 = out2.findParam('y:x')

Note that in this example param1 and param2 are different objects! The parameters of out1 were cloned when it was connected to out2. param2 is a reference to the clone.

If findParam can't find a parameter with the given name, it raises a KeyError.

aliasParam(paramname, alias, default, tip)

aliasParam assigns a new name to an Output parameter. This is useful when a generic Output is being used in a specific context, and a generic parameter name can be replaced by a more descriptive one. It is required when a parameter in an input is to be set by the user, since the colon separated string that identifies input parameters is not a legal Python variable name.

The arguments to findParam are:

paramname

This is the name, path, or pre-existing alias of the parameter. See findParam for a discussion of parameter paths.

alias

This is the new name for the parameter. It must be a legal Python variable name.

default

This argument is optional. If the parameter is being aliased because its role is changing, it may be useful to change its default value.

tip

This argument is optional. It provides a new descriptive tip string for the parameter.

resolveAlias(alias)

resolveAlias is just like findParam, except that it first looks for a parameter with the given alias. If the alias can't be found, it returns findParam(alias). If that doesn't work, a KeyError will be raised.

The callback function

The callback function specified in the Output constructor does all of the computational work for the Output. The arguments to the callback depend upon the params and inputs arguments to the constructor, but all callbacks have these three arguments, at least:

mesh

The FEMesh object on which the data is to be computed.

elements

A list of the Elements of the mesh on which the data is to be computed. It is possible, even likely, that this list doesn't contain all of the Elements in the mesh.

coords

A list of lists of positions at which the data is to be computed. The list contains one sublist for each Element in the elements list, in order. The sublists contain either Point or Coord objects, which specify positions in the Element's master space. (Use Element.from_master to convert master space coordinates to physical coordinates, if necessary.)

In addition to these three arguments, the callback function must have one argument for each entry in its constructor's params and inputs lists. The name of the argument is the same as the name of the Parameter object in the list. The value of arguments from the params list is simply the value that was assigned to the Parameter. Arguments from the inputs list are lists of values that were computed by the Outputs that were connected to the inputs. These lists are flat — they contain one entry for each point in the coords list, but the input lists do not contain sublists.

Callback functions are invoked with keyword arguments, so the order of the arguments in the function definition is unimportant. The names of the arguments are crucial, though. They must match the names in the params and inputs lists.

The callback function must return a flat list of values, whose type is determined by the otype constructor argument. The list contains one value for each point in the coords list, in the same order.

Prev  Up  Next
Parameter  Home  PropertyOutput