Math Expression Documentation

OpenVCAD uses math expression strings in several nodes, most notably the FGrade and Function nodes. These expressions define how material volume fractions or scalar fields vary across space.

Note

OpenVCAD uses the ExprTk library for parsing math strings. It follows syntax common on most graphing calculators and supports many advanced features. See the ExprTk documentation for the full specification.

Coordinate Systems

The following variables may be used in any math expression to grade based on spatial position. You can combine multiple coordinate systems in a single expression.

Name	Form	Variable Names
Cartesian	f(x, y, z)	x, y, z
Cylindrical	f(rho, phic, z)	rho, phic, z
Spherical	f(r, theta, phis)	r, theta, phis
Signed Distance	f(d)	d

Note

phic corresponds to phi in cylindrical coordinates and phis to phi in spherical coordinates.

Note

d is the signed distance to the surface of the object. Zero is the surface, negative values are inside, and positive values are outside. This can be used to create conformal gradients.

Arithmetic & Assignment Operators

Operator	Definition
+	Addition between x and y. (e.g., x + y)
-	Subtraction between x and y. (e.g., x - y)
*	Multiplication between x and y. (e.g., x * y)
/	Division between x and y. (e.g., x / y)
%	Modulus of x with respect to y. (e.g., x % y)
^	x to the power of y. (e.g., x ^ y)
:=	Assign the value of x to y. (e.g., y := x)
+=	Increment x by the value of the expression on the right-hand side.
-=	Decrement x by the value of the expression on the right-hand side.
*=	Assign the multiplication of x by the value of the expression to x.
/=	Assign the division of x by the value of the expression to x.
%=	Assign x modulo the value of the expression on the right-hand side to x.

Equalities & Inequalities

Operator	Definition
== or =	True only if x is strictly equal to y. (e.g., x == y)
<> or !=	True only if x does not equal y. (e.g., x != y)
<	True only if x is less than y. (e.g., x < y)
<=	True only if x is less than or equal to y. (e.g., x <= y)
>	True only if x is greater than y. (e.g., x > y)
>=	True only if x is greater than or equal to y. (e.g., x >= y)

Boolean Operations

Operator	Definition
true	True state or any value other than zero (typically 1).
false	False state, value of exactly zero.
and	Logical AND, True only if x and y are both true. (e.g., x and y)
or	Logical OR, True if either x or y is true. (e.g., x or y)
not	Logical NOT, negates the logical sense of the input. (e.g., not x)
xor	Logical XOR, True only if the logical states of x and y differ.
nand	Logical NAND, True only if either x or y is false.
nor	Logical NOR, True only if both x and y are false.
mand	Multi-input logical AND, True only if all inputs are true.
mor	Multi-input logical OR, True if at least one input is true.

General Purpose Functions

Function	Definition
abs	Absolute value of x. (e.g., abs(x))
avg	Average of all inputs. (e.g., avg(x, y, z))
ceil	Smallest integer greater than or equal to x.
floor	Largest integer less than or equal to x.
sqrt	Square root of x, where x >= 0. (e.g., sqrt(x))
log	Natural logarithm of x. (e.g., log(x))
exp	e to the power of x. (e.g., exp(x))
pow	x to the power of y. (e.g., pow(x, y))
max	Largest value of all inputs. (e.g., max(x, y, z))
min	Smallest value of all inputs. (e.g., min(x, y, z))
clamp	Clamp x between low and high. (e.g., clamp(low, x, high))

Trigonometry Functions

Function	Definition
sin	Sine of x. (e.g., sin(x))
cos	Cosine of x. (e.g., cos(x))
tan	Tangent of x. (e.g., tan(x))
asin	Arc sine of x, in radians.
acos	Arc cosine of x, in radians.
atan	Arc tangent of x, in radians.
deg2rad	Convert x from degrees to radians. (e.g., deg2rad(x))
rad2deg	Convert x from radians to degrees. (e.g., rad2deg(x))

Constants

Constant	Value
pi	3.14159…
e	2.71828…

Examples

Linear gradient along X

A bar that transitions from 100% red at x = -50 to 100% blue at x = 50:

root = pv.FGrade(
    ["x/100 + 0.5", "-x/100 + 0.5"],
    [materials.id("red"), materials.id("blue")],
    False
)

Radial gradient

A sphere that is one material at the center and another at the surface:

root = pv.FGrade(
    ["clamp(0, 1 - r/5, 1)", "clamp(0, r/5, 1)"],
    [materials.id("red"), materials.id("blue")],
    False
)

Angular gradient (cylindrical)

A gradient that varies with angle around the Z-axis:

root = pv.FGrade(
    ["(phic + pi) / (2*pi)", "1 - (phic + pi) / (2*pi)"],
    [materials.id("red"), materials.id("blue")],
    False
)

Conformal gradient (signed distance)

A gradient that follows the surface contour of the object:

root = pv.FGrade(
    ["clamp(0, -d/2 + 0.5, 1)", "clamp(0, d/2 + 0.5, 1)"],
    [materials.id("red"), materials.id("blue")],
    False
)

Important

All PDFs at any spatial location must sum to 1. If they don’t, OpenVCAD will normalize them, but this may produce unexpected results.