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_avgweights 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=CELLSorcentering=POINTS. Queries on solutions from simulations run in Luminary Cloud usecentering=CELLS.A reduction reads one input. Either name a port with
on=(a bare name, such ason=up), or select blocks of the solution withsurfaces=orvolumes=. Pass a list of IDs, orALL_SURFACES/ALL_VOLUMES. IDs come fromvis.list_surfaces()andvis.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, andvolumes=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_VOLUMESor 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 aSlice,PlaneClip, orBoxClip. A filter’sset_parentchain 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_locationandmin_locationreturn the lowest index in the first block.normalon surfaces needs a mesh with global face IDs on every boundary. Otherwise anormalquery is rejected with “normalneeds oriented normals, and no block in the input has them”. Readnormalon 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; ‘ |
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 ‘ |
|
Rename the port |
the query already has an input named ‘ |
|
Use a different name |
output name ‘ |
|
Rename the output |
the query already has an output named ‘ |
|
Use a different name |
the query has no outputs; add one with add_output() |
|
Add an output |
the parent chain of ‘ |
A |
Break the cycle |
Raised by the server¶
Message |
Cause |
Fix |
|---|---|---|
|
An integral, mean, or |
Use |
use |
|
Pick a component or the magnitude |
|
The query returns a per-point value |
Return a reduction |
reductions on the source must say which blocks: |
Reduction with no selector and no input |
Add a selector |
|
|
Keep one of them |
queries can read through Slice and Clip; |
A filter not on the allow-list upstream |
Query before that filter |
|
Reduction without |
Add it |
|
Integral, mean, or |
Use the matching reduction |
|
Constant passed to the wrong selector |
Swap the selector |
unknown |
Selector names a block the source lacks |
Fix the name |
unknown |
Selector names neither a block nor a tag of the simulation |
Fix the name or tag ID |
tag ‘ |
A tag in |
Use a tag that holds only surfaces, or list the surfaces |
tag ‘ |
A tag member is not a block of this solution |
List the blocks by ID |
tag ‘ |
The tag is empty |
Use another tag |
|
Reduction selects a block without normals |
Remove that block from the selector |
|
|
Read |
‘ |
|
Use |
‘ |
|
Use |
no block has field ‘ |
No surface (for |
Fix the name |
surface ‘ |
A surface listed in |
Remove that ID, or read the field on |
no block has field ‘ |
Field missing from a port’s output; also |
Fix the name, or read it on another input |
solver data stores cell values; use |
|
Use |
|
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 |
A reduction without |
Add |
unknown port ‘ |
|
Fix the name |
unknown port ‘ |
|
Add the input, or select blocks of the source |
input ‘ |
A port no output reads |
Remove the input or use it |
inputs |
One filter added with |
Add the filter once and use its one port |
|
Single string, empty list, or non-string items as a selector |
Give a non-empty list of names, or |
‘ |
The same ID twice in one selector (also |
List each ID once |
|
A reduction with another keyword (such as |
Remove it |
|
A reduction with zero or several positional arguments (two-argument |
Pass one value |
|
|
Write the port as a bare name |
a reduction reads one input; use |
Both selectors on one reduction |
Keep one; use two reductions for both |
|
|
Swap the selector |
|
|
Pass it as a selector |
|
|
Use the cell center |
|
|
Use the point position |
|
|
Use |
|
A per-point value returned by a query with no inputs |
Return a reduction |
|
A volume integral, mean, or |
Use the matching selector or reduction |