
                               VisIt expressions
                                Mon Aug 27, 2001

I. General information

We separated out the concept of expressions into two parts: The definition
of the expression, and its execution.

A. Defining expressions

The definition of the expression involves the assignment of a mathematical
definition of a variable (defined later) to a name.  This name can now be
used just like a variable name found in a file.  This is identical to how
MeshTV thinks of "defvars" and variable names.  An example of defining an
expression is assigning the expression "-sin(u)" to the name "sin_u".  No
file access is necessarily required to define an expression.  A discussion
of the mathematical language of expressions is found below.

B. Execution

The execution (or evaluation) of an expression involves setting up the AVT
database, AVT network, and a geometry generator (discussed below) that
properly represents the expression's definition.  An example of executing
an expression is creating a pseudocolor plot of the previously-defined
expression "sin_u".

Execution might not include variables from files.  We envision expressions
that create new geometry (data sources) that do not rely on existing
geometry or data.  Example: createSphere(4,{0,0,0},10,10,10) might create a
mesh that is a sphere with radius 4, centered at the origin, sampled with
10 points in each of r, theta, and phi.

C. Expression results

Variables fetched from files may have one of many types:
    + meshes
    + scalars over meshes (pressure)
    + vectors over meshes (velocity)
    + materials over meshes
    + material species over meshes
    + individual scalars and vectors with no associated mesh. (time)

Expressions may have any of these types as well.  Every expression has one
type, chosen from this list of types.


II. Language

The language used for defining expressions has yet to be designed.
However, we expect that it will use a "standard" mathematical notation for
infix operators, prefix operators, and functions (e.g. "-sin(u+v)").
Special syntax will be required for the composition of vectors (maybe {}
brackets).  Since datasets can span a range of time, users may also wish to
reference particular points in time or a range of times.  Additional syntax
will be required to refer to this information.

In addition to "standard" mathematics operations, expressions will provide
access to every plugin operator.  This means that an expression syntax must
be defined for every one.  We envision something similar to MeshTV's
language for accessing operators.  The language for accessing a plugin will
be automatically generated by our plugin creation tools from the .def
files.  The information in the .def files may have to be extended to
provide this.


III. Code modification

Definition and evaluation of expressions will require modification to the
the network construction logic of the engine and the viewer.

Since plugin operators are executed in the networks that the engine
creates, the engine will have to include "evaluators" for expressions.  An
example of this would be the expression "1+onion(v,{0,0,0},2)".  This
expression is meant to describe an onion-peel operation of the mesh
associated with variable "v", with the value "1" added to all resulting
values of "v".  Since the addition happens after the onion-peel operation,
this "downstream" execution must be directed by the engine.  These
evaluators will have to be able to accept new symbols to the language
dynamically to support plugins.

Geometry creation will be a separate module, at the same level in the
engine as the database is.  It will be called upon as a data source,
generating geometry and data as required by expressions, just as the
database is called upon to act as a data source for geometry and data
stored in external files.

To fully support binary operators, as well as general operators that take
more than two arguments, multiple inputs are required in the engine.  As an
example, imagine a "map" operator that takes a variable defined over one
mesh and does the interpolation required to have it lie on another mesh.
This operator requires two mesh inputs, something the engine does not
currently handle.

The viewer will be the storage location of the "master list" of variables.
This list will be the union of the list of variables that the metadata
servers report and the list of defined expression names.  Each entry in
that master list will contain at least the following information:

    1) The name of the variable
    2) The data type (see above)
    3) Whether it's a raw variable or an expression.
    4) For expressions: The mathematical definition


IV. Planning: Short-term vs. Long term

There are two major classes of variable types defined above: those that
have an associated mesh, and those that do not.

There are plenty of advantages to having expressions that evaluate to
simple scalars and vectors with no associated mesh.  For instance, imagine
a "max" operator that returned the maximum value of a mesh variable over a
range of time.  The result of such an expression could be fed into the
pseudocolor plot attributes, and thus automatically calculated from plot to
plot.  Another example would be an operator that calculated the centroid of
a mesh and returned a vector.  That vector could be used to steer the
rendering camera so that problem was always drawn centered in a window.

The more advanced ability of expressions to return scalars and other
variables that are not associated with a mesh has the potential to provide
a lot of power to the VisIt infrastructure.  Potentially, these scalars
could be associated with any member of an attribute group, controlling
virtually any aspect of VisIt.  In this way, the VisIt pipeline
architecture would have much in comon with other visualization tools such
as AVS, DX, and Khoros.
    
However, there are important design issues with this that have yet to be
mapped out.  There are issues with the interface, attribute subjects, and
connecting the expressions in addition to AVT issues.  These will have be
addressed when we put general expressions into VisIt.
    
Considering all of these issues, and the fact that most of our users' needs
for visualization can be handled through the use of expressions that have
an associated mesh, the design and implementation of this advanced ability
of expressions will be done some time after VisIt version 1.0.


V. Appendix: Sean Ahern's expression notes

Things I'd like to do with expressions:

1. Normal mathematics:
   a. Unary operators: -sin(a)
   b. Binary operators: u^v*e
2. Types of data:
   a. Scalars over mesh
   c. Scalars u+4
   d. Vectors over mesh curl(v)*mag({x,y,z})
   e. Vectors displace(mesh,{1,0,0})
3. Ways of referencing:
   a. unqualified means current file at current time: u
   b. File qualification: globe.silo:/dir/u
   c. Time qualification: u@0004
   d. Both file and time probably don't make sense.
   e. Might want spans of time: max(x, mesh@[0002..0010])
4. Custom operations: foo(a+b)+g
   a. Specified as a plugin
   b. Python for rapid turnaround?
5. Non-numeric operations: createSphere(4,{0,0,0}), displace, resample
   mesh/var.
