Vis Queries

NOTE: Vis queries are experimental. They may change or be removed in the future.

A query computes named values from reductions over a simulation solution. Build one with vis.Query, add each value with Query.add_output(), and run it with vis.run_query(). Each output is a program that returns one value: a float or a Vector3. run_query returns a dict from output name to value. All outputs of a query read the same inputs and one load of the solution, so computing several values in one query is faster than one query per value. The programs are written in the vis expression language, which lists every operator, function and built-in variable.

All examples use these imports, and solution is a Solution, for example simulation.list_solutions()[-1]:

import luminarycloud.vis as vis
from luminarycloud.vis import Plane

Writing a program

  • A reduction (integrate_surface, integrate_volume, mean_surface, mean_volume, mass_avg, sum, max, min, max_location, min_location) takes one value and keywords.

  • mass_avg weights each cell by its mass flux, ρ|u·n| times its area. An incompressible fluid has no density field; its density is constant and cancels, so the weight is |u·n| times the area.

  • Every reduction needs centering=CELLS or centering=POINTS. Queries on solutions from simulations run in Luminary Cloud use centering=CELLS.

  • A reduction reads one input. Either name a port with on= (a bare name, such as on=up), or select blocks of the solution with surfaces= or volumes=. Pass a list of IDs, or ALL_SURFACES / ALL_VOLUMES. IDs come from vis.list_surfaces() and vis.list_volumes(), for example "0/bound/airfoil".

  • A list can also hold tag IDs (Tag.id). A tag selects its members. surfaces= takes only tags whose members are all surfaces, and volumes= only tags whose members are all volumes. A block in several listed tags, or in a tag and listed by its own ID, is read once.

  • With one input, on= can be left out. With two or more, every reduction names its port.

  • Each input must be read by at least one output.

  • A surface or volume listed by ID or in a listed tag must have every field the reduction reads. With ALL_SURFACES, ALL_VOLUMES or a port, blocks without the field are skipped, so the result covers only the blocks that have it. The reduction fails only when no block has the field.

  • A port is bound with Query.add_input() to a Slice, PlaneClip, or BoxClip. A filter’s set_parent chain is sent with it and may only hold Slices and Clips.

  • The program returns a reduction, or an expression of reductions, such as a difference of two.

Mass flow through a slice

s = vis.Slice("x = 2")
s.plane = Plane(origin=[2, 0, 0], normal=[1, 0, 0])

q = vis.Query("slice mass flow")
q.add_input("s", s)
q.add_output("mdot", "integrate_surface(Q.DENSITY * dot(Q.VELOCITY, normal), centering=CELLS)")
mdot = vis.run_query(solution, q)["mdot"]  # float

Positive means flow along the plane normal as given.

Mass flow difference between two slices

up = vis.Slice("upstream")
up.plane = Plane(origin=[0, 0, 0], normal=[1, 0, 0])
down = vis.Slice("downstream")
down.plane = Plane(origin=[2, 0, 0], normal=[1, 0, 0])

DIFFERENCE = """
mdot = Q.DENSITY * dot(Q.VELOCITY, normal)
m_up = integrate_surface(mdot, on=up, centering=CELLS)
m_down = integrate_surface(mdot, on=down, centering=CELLS)
return m_up - m_down
"""
q = vis.Query("mass flow difference")
q.add_input("up", up)
q.add_input("down", down)
q.add_output("dm", DIFFERENCE)
dm = vis.run_query(solution, q)["dm"]      # float

up and down in the program are the port names given to add_input, written as bare names. mdot is evaluated on each slice’s own cells.

To restrict the downstream slice to one leg, clip it and make the clip read the slice:

leg = vis.BoxClip("downstream leg")
leg.box.center = [2, 0.5, 0]
leg.box.lengths = [1, 1, 2]
leg.set_parent(down)

q = vis.Query("mass flow difference, one leg")
q.add_input("up", up)
q.add_input("down", leg)
q.add_output("dm", DIFFERENCE)

A clip on a slice runs smooth whatever BoxClip.smooth says.

A vector: force on a surface

q = vis.Query("airfoil pressure force")
q.add_output("force",
    'integrate_surface(Q.PRESSURE * normal, surfaces=["0/bound/airfoil"], centering=CELLS)')
f = vis.run_query(solution, q)["force"]    # Vector3: f.x, f.y, f.z

Boundary normals point out of the fluid, so this is the force the fluid’s pressure puts on the airfoil.

A location: the hottest cell

q = vis.Query("hottest point")
q.add_output("where", "max_location(Q.TEMPERATURE, volumes=ALL_VOLUMES, centering=CELLS)")
loc = vis.run_query(solution, q)["where"]  # Vector3: cell center of the max cell

Under centering=POINTS the location is a mesh point.

Mixing the solution and an input

q = vis.Query("inlet boundary minus slice")
q.add_input("s", s)
q.add_output("dp", """
p_bc = mean_surface(Q.PRESSURE, surfaces=["0/bound/inlet"], centering=CELLS)
p_s = mean_surface(Q.PRESSURE, on=s, centering=CELLS)
return p_bc - p_s
""")

Several values from one query

q = vis.Query("slice stats")
q.add_input("s", s)
q.add_output("mdot", "integrate_surface(Q.DENSITY * dot(Q.VELOCITY, normal), centering=CELLS)")
q.add_output("p_mean", "mean_surface(Q.PRESSURE, centering=CELLS)")
q.add_output("p_max", 'max(Q.PRESSURE, surfaces=["0/bound/airfoil"], centering=CELLS)')
results = vis.run_query(solution, q)      # {"mdot": ..., "p_mean": ..., "p_max": ...}

The solution loads once and the slice runs once for all three. An output need not read every input; p_max reads only the solution.

Notes

  • Results are in project units.

  • A query can’t read a custom field by name yet. Write the custom field’s expression in the program instead; see Custom fields and this language.

  • Surface integrals such as mass flow integrate rho (u . n) A from cell values, while the solver reports its numerical face flux, so the two differ slightly.

  • On a tie, max_location and min_location return the lowest index in the first block.

  • normal on surfaces needs a mesh with global face IDs on every boundary. Otherwise a normal query is rejected with “normal needs oriented normals, and no block in the input has them”. Read normal on a Slice instead.

Errors

The SDK checks port names and filter types when you call add_input, and output names when you call add_output. The server checks the programs and reports problems as INVALID_ARGUMENT with the message <output>:<line>:<column>: error: <message>, or <output>: <message> for problems found while the query runs.

Raised by the SDK

Message

Cause

Fix

a query can read through Slice, PlaneClip, and BoxClip; ‘<filter>’ is a <type>

A filter of another type, such as a Threshold, added to a query, or as a parent of one

Use a Slice or Clip

port name ‘<name>’ must be a Python identifier (ASCII letters, digits, _; not starting with a digit)

add_input with a name the program can’t write as a bare name

Rename the port

the query already has an input named ‘<name>’

add_input twice with one port name

Use a different name

output name ‘<name>’ must be a Python identifier (ASCII letters, digits, _; not starting with a digit)

add_output with a name that isn’t an identifier

Rename the output

the query already has an output named ‘<name>’

add_output twice with one name

Use a different name

the query has no outputs; add one with add_output()

run_query on a query with no outputs

Add an output

the parent chain of ‘<filter>’ has a cycle

A set_parent chain that loops back on itself

Break the cycle

Raised by the server

Message

Cause

Fix

<name> with centering=POINTS isn’t available yet; use centering=CELLS, or max/min.

An integral, mean, or mass_avg with POINTS

Use CELLS

use Q.VELOCITY.x or norm(Q.VELOCITY)

max/min/locations on a vec3

Pick a component or the magnitude

mdot varies per point; a query returns reductions, e.g. integrate_surface(mdot, on=inlet, centering=CELLS)

The query returns a per-point value

Return a reduction

reductions on the source must say which blocks: volumes= or surfaces= (e.g. volumes=ALL_VOLUMES)

Reduction with no selector and no input

Add a selector

on=<port> reads all of <filter>’s output; remove surfaces=/volumes=, or remove on= to select blocks of the source.

on= and a selector on one reduction

Keep one of them

queries can read through Slice and Clip; <filter> is upstream of this query.

A filter not on the allow-list upstream

Query before that filter

<name> needs centering=CELLS or centering=POINTS

Reduction without centering=

Add it

<name> integrates over <surfaces/volumes>, but its input is <a volume/a surface/a line> (<filter>)

Integral, mean, or mass_avg on input of another dimension

Use the matching reduction

ALL_SURFACES selects surfaces; use it with surfaces= (and ALL_VOLUMES with volumes=)

Constant passed to the wrong selector

Swap the selector

unknown <surface/volume> ‘<name>’; the source has: <names>

Selector names a block the source lacks

Fix the name

unknown <surface/volume> or tag ‘<name>’; the source has: <names>

Selector names neither a block nor a tag of the simulation

Fix the name or tag ID

tag ‘<id>’ contains volume ‘<name>’; surfaces= takes only surfaces

A tag in surfaces= holds a volume (contains surface ... for a tag in volumes=)

Use a tag that holds only surfaces, or list the surfaces

tag ‘<id>’ contains ‘<name>’, which the source doesn’t have

A tag member is not a block of this solution

List the blocks by ID

tag ‘<id>’ has no members

The tag is empty

Use another tag

normal isn’t available on block ‘<name>’ (no oriented normals)

Reduction selects a block without normals

Remove that block from the selector

normal needs oriented normals, and no block in the input has them

normal on an input without oriented normals, such as surfaces= on a solution whose mesh doesn’t record face IDs on every boundary

Read normal on a Slice instead, or drop it

‘<field>’ is stored only at points; use centering=POINTS

CELLS on a point-only field

Use POINTS

‘<field>’ is stored only at cells; use centering=CELLS

POINTS on a cell-only field

Use CELLS

no block has field ‘<field>’

No surface (for surfaces=) or volume (for volumes=) of the solution has the field

Fix the name

surface ‘<id>’ has no field ‘<field>’

A surface listed in surfaces= lacks the field (volume ... for volumes=)

Remove that ID, or read the field on ALL_SURFACES to skip blocks without it

no block has field ‘<field>’ on input <port>

Field missing from a port’s output; also mass_avg’s density or velocity on a port

Fix the name, or read it on another input

solver data stores cell values; use centering=CELLS.

POINTS in a query on a solution

Use CELLS

<reduction> on <port> uses a result from <other port>, which isn’t upstream of it; a reduction can use results from its own input, an input upstream of it, or from any reduction when it reads the source

A reduction needs a result that isn’t ready when its input is processed

Reorder the filters so the other input is upstream, or read the source

this query has inputs <ports>; name one with on=

A reduction without on= in a query with two or more inputs

Add on=

unknown port ‘<name>’; the query’s inputs are: <ports>

on= names a port the query doesn’t have

Fix the name

unknown port ‘<name>’; the query has no inputs

on= in a query with no inputs

Add the input, or select blocks of the source

input ‘<port>’ isn’t used by any program

A port no output reads

Remove the input or use it

inputs <port> and <port> both read filter ‘<filter id>’; add each filter once

One filter added with add_input under two port names

Add the filter once and use its one port

surfaces= takes a list of names, e.g. surfaces=["inlet"], or ALL_SURFACES (same for volumes=)

Single string, empty list, or non-string items as a selector

Give a non-empty list of names, or ALL_SURFACES

‘<name>’ is listed twice in surfaces=

The same ID twice in one selector (also volumes=)

List each ID once

<name> has no keyword <keyword>=; use centering=, on=, surfaces= or volumes=

A reduction with another keyword (such as per=)

Remove it

<name> takes 1 argument, got <n>

A reduction with zero or several positional arguments (two-argument max/min stay per-point)

Pass one value

on= takes a port name, like on=inlet

on= given a string, number or expression

Write the port as a bare name

a reduction reads one input; use surfaces= or volumes=, not both

Both selectors on one reduction

Keep one; use two reductions for both

ALL_VOLUMES selects volumes; use it with volumes= (and ALL_SURFACES with surfaces=)

ALL_VOLUMES passed to surfaces=

Swap the selector

ALL_SURFACES is only a value for a reduction’s surfaces= or volumes=

ALL_SURFACES/ALL_VOLUMES used as a value

Pass it as a selector

<x> is a point coordinate and centering=CELLS reads cells; use centroid.x

x, y, z or position in a CELLS reduction

Use the cell center

centroid is a cell center and centering=POINTS reads points; use position

centroid in a POINTS reduction

Use the point position

<name> is a cell value and centering=POINTS reads points; use centering=CELLS

normal, cell_volume or cell_area in a POINTS reduction

Use CELLS

<text> varies per point; a query returns reductions, e.g. integrate_surface(<text>, surfaces=ALL_SURFACES, centering=CELLS)

A per-point value returned by a query with no inputs

Return a reduction

<name> integrates over volumes, but its input is a surface (surfaces=["wing"])

A volume integral, mean, or mass_avg of surface blocks

Use the matching selector or reduction