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 an if must be assigned in every branch, including an else.

  • return <expression>: returns one value. It must be the last statement of the program, and it can’t be inside an if.

  • 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

2, 1.5e-3, Q.PRESSURE, cell_volume, Q.VELOCITY.x

vec3

Q.VELOCITY, position, normal, vec3(1, 0, 0)

bool

True, False, p > 0, isnan(p)

  • A number is written as in Python: 3, 0.5, .5, 2e5, 1.2E-3.

  • A vec3’s components are .x, .y and .z. Indexing such as v[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

a if c else b

a where c is true, b elsewhere; a and b must have the same type

or

logical or

and

logical and

not

logical not

< <= > >= == !=

comparisons of scalars; they chain, so 0 < x < 1 works

+ -

add and subtract

* /

multiply and divide

unary - +

negate

**

power

f(...), .x

calls and components

Arithmetic on vec3s works by component:

  • v + w and v - w need two vec3s; a vec3 plus a scalar is an error.

  • v * s, s * v and v / s scale a vec3 by a scalar.

  • v * w of two vec3s is an error; use dot(v, w) or cross(v, w).

  • ** and comparisons take scalars only.

  • and, or, not and the condition of if take bools, such as comparisons.

Fields

Read a solution field in any of these ways:

Form

Example

Notes

Q.<QUANTITY>

Q.PRESSURE, Q.VELOCITY, Q.DENSITY, Q.TEMPERATURE

Any quantity type name. VisQuantity.<QUANTITY> is the same. Recommended.

A bare name

Pressure

A field name that is also a valid name, without its unit.

A quoted name

"Pressure", "Pressure (Pa)", "Velocity - X", "Velocity-Magnitude"

- X, - Y, - Z and - Magnitude pick a component or the magnitude of a vector field. Case and spaces around the dash don’t matter.

field("...")

field("Pressure (Pa)")

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

x, y, z

scalar

points

the point’s coordinates

position

vec3

points

the point’s position

centroid

vec3

cells

the cell’s center; centroid.x etc. for one coordinate

normal

vec3

cells

the unit normal of a surface cell

cell_volume

scalar

cells

the volume of a volume cell

cell_area

scalar

cells

the area of a surface cell

  • Point values (x, y, z, position) need centering=POINTS, and cell values need centering=CELLS. Queries on solutions from simulations run in Luminary Cloud use centering=CELLS, so use centroid.x in place of x and centroid in place of position.

  • cell_volume needs volume cells, such as volumes=. cell_area and normal need surface cells, such as surfaces= or a Slice.

  • normal also 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 read normal on a Slice.

  • On a boundary, normal points out of the fluid. On a Slice, it is the slice’s plane normal.

Constants:

Name

Value

pi, PI

π

p_ref, v_ref, t_ref

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

sqrt, cbrt, log, exp, abs

one scalar

scalar; log is the natural log

sin, cos, tan, asin, acos, atan

one scalar

scalar, in radians

pow(a, b)

two scalars

a to the power b, the same as a ** b

hypot(a, b)

two scalars

√(a² + b²)

atan2(y, x)

two scalars

the angle of (x, y), in radians

max(a, b), min(a, b)

two scalars

the larger or smaller at each point

isnan(a), isfinite(a)

one scalar

bool

norm(v)

one vec3

its length; for a scalar use abs

dot(v, w)

two vec3s

scalar

cross(v, w)

two vec3s

vec3

vec3(a, b, c)

three scalars

vec3

field("name")

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

integrate_surface(f, ...)

scalar or vec3

∫ f dA over surfaces

integrate_volume(f, ...)

scalar or vec3

∫ f dV over volumes

mean_surface(f, ...)

scalar or vec3

area-weighted mean over surfaces

mean_volume(f, ...)

scalar or vec3

volume-weighted mean over volumes

mass_avg(f, ...)

scalar or vec3

mean of f over surfaces, weighted by mass flux ρ|u·n| dA

sum(f, ...)

scalar or vec3

the plain sum over points or cells, unweighted

max(f, ...), min(f, ...)

scalar

the largest or smallest value

max_location(f, ...), min_location(f, ...)

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=CELLS or centering=POINTS (required): read cell values or point values. Integrals, means and mass_avg need CELLS. Queries on solutions from simulations run in Luminary Cloud use CELLS.

  • What to read, one of:

    • on=<port>: the output of a filter added with Query.add_input(), written as a bare name. With one input, on= can be left out.

    • surfaces=["id", ...] or surfaces=ALL_SURFACES: surfaces of the solution, by the IDs that vis.list_surfaces() returns.

    • volumes=["id", ...] or volumes=ALL_VOLUMES: volumes of the solution, by the IDs that vis.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

def, lambda, for, while, import and other statements

assignments, if and return

x += 1 and other augmented assignment

assign a new name

a, b = ...

one name per assignment

a ^ b

a ** b or pow(a, b)

a // b

a / b

a % b, |, &, <<, >>

none

a @ b

dot(a, b)

~a

not a

v[0]

v.x

in, is, None

comparisons

lists, tuples, dicts, sets, comprehensions

none; lists appear only in surfaces= and volumes=

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.