OOF2: The Manual
Name
Output — Compute output data on a Mesh
Python Synopis
import oof2.common.IO.outputclass 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)
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 thisOutput
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. Ifotype
is a Python class or an instance of a class, then the objects must be instances of that class. Ifotype
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 ofParameter
objects, describing the inputs to thisOutput
, if any. Only the name and subclass of eachParameter
are important. The name is used to identify the input, and the subclass determines its type. When oneOutput
is connected to an input of another, theotype
of the firstOutput
must be compatible with theParameter
type of the secondOutput
'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 inputFloatParameter('xyz')
will cause a list of floats namedxyz
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 ofParameter
objects, specifying parameters that govern theOutput
'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 theparams
list, then the callback argumentx
will always have the value 3. To set an initial value that can be changed by the user, usedefault
, as inFloatParameter('x', default=3)
. tip
-
tip
is a character string that describes the role of theOutput
. It appears in GUI tooltips and in the documentation. discussion
-
discussion
is a more verbose description of theOutput
, meant for inclusion in the OOF2 user manual. It can either be a string or a reference to a file via thexmlmenudump.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. Ifparams
is omitted, only those parameters that are set in the originalOutput
will be set in the clone. tip
-
A
tip
provided in theclone
command will replace the originaltip
provided in the constructor. discussion
-
A
discussion
provided in theclone
command will replace the originaldiscussion
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.
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 theElements
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 theelements
list, in order. The sublists contain eitherPoint
or Coord objects, which specify positions in theElement
's master space. (UseElement.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.