Vis Expression Language¶
NOTE: Vis expressions are experimental. They may change or be removed in the future.
The visualization expression language is designed as a subset of python, and as with python, indentation matters. This language supports a number of built-in functions and constants that let you access fields, math functions, and conditionals. Each output of a vis query is a program in this language. A program reads fields and mesh geometry at each point or cell, does arithmetic on them, and reduces them to one result. Here is a high-level example of the types of expressions used to compute mass flow through a user defined slice.
# Mass flow through a slice, and the mean pressure over it.
mdot = Q.DENSITY * dot(Q.VELOCITY, normal)
flow = integrate_surface(mdot, on=s, centering=CELLS)
p = mean_surface(Q.PRESSURE, on=s, centering=CELLS)
return flow * p
Custom fields and this language¶
Custom fields use a subset of this language today, the subset the solver
supports, and a query can’t read a custom field by name. To use a custom field in a query, write
its expression in the program instead. For example, "Pressure" * 2 becomes:
p2 = "Pressure" * 2
return mean_surface(p2, on=s, centering=CELLS)
Custom fields will soon support the full language; see Custom Fields.
Programs and statements¶
A program is one expression, or a sequence of statements that ends in return.
integrate_surface(Q.PRESSURE * normal, surfaces=ALL_SURFACES, centering=CELLS)
speed = norm(Q.VELOCITY)
return max(speed, volumes=ALL_VOLUMES, centering=CELLS)
Assignment:
name = <expression>. One name per statement. Each name is assigned once; to change a value, assign a new name.if/elif/else: the bodies are indented, as in Python. A name assigned in anifmust be assigned in every branch, including anelse.return <expression>: returns one value. It must be the last statement of the program, and it can’t be inside anif.Comments: start with
#and run to the end of the line.Line continuation: inside
( )or[ ]a new line continues the statement. Elsewhere, end the line with\.
p = Q.PRESSURE
if p > 0:
gauge = p
else:
gauge = 0
return mean_surface(gauge, on=s, centering=CELLS)
A name assigned anywhere in the program is that variable everywhere in it, so reading it before it is assigned is an error, even when a field of the same name exists.
Values and types¶
Every value has one of three types:
Type |
Examples |
|---|---|
scalar |
|
vec3 |
|
bool |
|
A number is written as in Python:
3,0.5,.5,2e5,1.2E-3.A vec3’s components are
.x,.yand.z. Indexing such asv[0]isn’t supported.A bool can’t be used as a number. Write
1 if c else 0.Text in quotes,
"..."or'...', names a field (see Fields, below).
Operators¶
From lowest to highest precedence:
Operator |
Meaning |
|---|---|
|
|
|
logical or |
|
logical and |
|
logical not |
|
comparisons of scalars; they chain, so |
|
add and subtract |
|
multiply and divide |
unary |
negate |
|
power |
|
calls and components |
Arithmetic on vec3s works by component:
v + wandv - wneed two vec3s; a vec3 plus a scalar is an error.v * s,s * vandv / sscale a vec3 by a scalar.v * wof two vec3s is an error; usedot(v, w)orcross(v, w).**and comparisons take scalars only.and,or,notand the condition ofiftake bools, such as comparisons.
Fields¶
Read a solution field in any of these ways:
Form |
Example |
Notes |
|---|---|---|
|
|
Any quantity type name. |
A bare name |
|
A field name that is also a valid name, without its unit. |
A quoted name |
|
|
|
|
The exact field name, with no component or unit matching. |
Vector fields, such as Q.VELOCITY, are vec3s and components can be accessed
through Q.VELOCITY.x notation. A program reads at most 20 fields.
Field values are in the project’s units. A field missing from the data a reduction reads is an
error, with one exception (see Reductions, below): ALL_SURFACES, ALL_VOLUMES and ports skip
blocks without the field, and fail only when no block has it.
Built-in variables¶
Geometry of the mesh, read at each point or cell:
Name |
Type |
At |
Value |
|---|---|---|---|
|
scalar |
points |
the point’s coordinates |
|
vec3 |
points |
the point’s position |
|
vec3 |
cells |
the cell’s center; |
|
vec3 |
cells |
the unit normal of a surface cell |
|
scalar |
cells |
the volume of a volume cell |
|
scalar |
cells |
the area of a surface cell |
Point values (
x,y,z,position) needcentering=POINTS, and cell values needcentering=CELLS. Queries on solutions from simulations run in Luminary Cloud usecentering=CELLS, so usecentroid.xin place ofxandcentroidin place ofposition.cell_volumeneeds volume cells, such asvolumes=.cell_areaandnormalneed surface cells, such assurfaces=or a Slice.normalalso needs oriented normals. A Slice has them, and a Clip doesn’t.surfaces=has them only when the mesh records global face IDs on every boundary; otherwise readnormalon a Slice.On a boundary,
normalpoints out of the fluid. On a Slice, it is the slice’s plane normal.
Constants:
Name |
Value |
|---|---|
|
π |
|
the simulation’s reference pressure, velocity and temperature, in project units |
named variables |
each of the simulation’s named variables that has a value, by its name |
A named variable with a quantity type is converted to project units. A field with the same name as a named variable wins, with a warning.
Functions¶
Functions take positional arguments only.
Function |
Arguments |
Result |
|---|---|---|
|
one scalar |
scalar; |
|
one scalar |
scalar, in radians |
|
two scalars |
|
|
two scalars |
√(a² + b²) |
|
two scalars |
the angle of (x, y), in radians |
|
two scalars |
the larger or smaller at each point |
|
one scalar |
bool |
|
one vec3 |
its length; for a scalar use |
|
two vec3s |
scalar |
|
two vec3s |
vec3 |
|
three scalars |
vec3 |
|
a quoted field name |
the field (see Fields, above) |
max and min with one argument are reductions, below.
Reductions¶
A reduction turns a value at every point or cell into one value. A program returns a reduction, or
an expression of reductions, such as m_up - m_down.
Reduction |
Argument |
Result |
|---|---|---|
|
scalar or vec3 |
∫ f dA over surfaces |
|
scalar or vec3 |
∫ f dV over volumes |
|
scalar or vec3 |
area-weighted mean over surfaces |
|
scalar or vec3 |
volume-weighted mean over volumes |
|
scalar or vec3 |
mean of |
|
scalar or vec3 |
the plain sum over points or cells, unweighted |
|
scalar |
the largest or smallest value |
|
scalar |
the position of the largest or smallest value |
For example, integrate_surface(1, ...) is the area and sum(1, ...) is the cell count.
Each reduction takes keywords:
centering=CELLSorcentering=POINTS(required): read cell values or point values. Integrals, means andmass_avgneedCELLS. Queries on solutions from simulations run in Luminary Cloud useCELLS.What to read, one of:
on=<port>: the output of a filter added withQuery.add_input(), written as a bare name. With one input,on=can be left out.surfaces=["id", ...]orsurfaces=ALL_SURFACES: surfaces of the solution, by the IDs thatvis.list_surfaces()returns.volumes=["id", ...]orvolumes=ALL_VOLUMES: volumes of the solution, by the IDs thatvis.list_volumes()returns.
A surface or volume listed by ID must have every field the reduction reads, or the query fails
with an error such as “surface ‘wing’ has no field ‘Pressure (Pa)’”. With ALL_SURFACES,
ALL_VOLUMES or on=, blocks without the field are skipped, so the result covers only the blocks
that have it. Those fail only when no block has the field: “no block has field ‘…’”.
integrate_surface, mean_surface and mass_avg read surfaces, and integrate_volume and
mean_volume read volumes. They skip cells of the other dimension.
A value computed from fields or geometry varies per point, so it can only be used inside a reduction. A reduction’s result is the same everywhere, so it can be used anywhere, including inside another reduction:
p = Q.PRESSURE
p_mean = mean_surface(p, on=s, centering=CELLS)
return mean_surface((p - p_mean) ** 2, on=s, centering=CELLS) # the variance of p
A variable is computed on the data of each reduction that uses it, so mdot in the first
example is evaluated on the cells of s.
Not supported¶
These parts of Python give an error that says what to use instead:
Python |
Use instead |
|---|---|
|
assignments, |
|
assign a new name |
|
one name per assignment |
|
|
|
|
|
none |
|
|
|
|
|
|
|
comparisons |
lists, tuples, dicts, sets, comprehensions |
none; lists appear only in |
calling anything other than a built-in function |
built-in functions |
keyword arguments to functions |
positional arguments; only reductions take keywords |
Python’s keywords, such as class or with, can’t be used as variable names.
Errors¶
The server reports errors as INVALID_ARGUMENT with the message
<output>:<line>:<column>: error: <message>, where <output> is the name given to
Query.add_output(). Errors from reductions are listed in
Vis Queries, under Errors.