Expressions

Expressions in Quanscient Allsolve

Quanscient Allsolve uses the power of expressions all around the application. You can define and use them for most inputs, wherever you see an icon in the graphical user interface (GUI). An expression can consist of numbers, matrices, simple arithmetics and predefined variables and functions among other things.

Expression language

The expression language of Allsolve is a subset of Octave. In expressions, everything is a matrix of doubles. Even scalars are considered 1 x 1 matrices.

The supported features are listed below.

Numbers

Double precision number in any format, such as 41, 8.91, -0.91233, +4.655e-23.

Constants

Basic mathematical constants are predefined: pi, mu0 and epsilon0. Constants can be used in place of numbers, like 2 * pow(pi,2).

Expression API

Expression API in Allsolve provides access to many useful variables and functions that can be used to define an expression in the GUI. Some of them are

• mathematical constants (pi, mu0, …),
• trigonometric functions (sin, cos, …),
• logarithmic, exponential and power functions (log, log10, …),
• space-time variables (t, x, y, z),
• integration and interpolation functions,
• functions for finding maximum and minimum value of a field in a region and many more.

Note that the simulation setup in Allsolve generates python scripts wherein the variables/functions of the GUI Expression API are translated into an equivalent Script API functions. They are equivalent in the sense that they have the same functionality but differ slightly in the syntax. For example, take the interpolation function which is interpolate(..) in Expression API while in Script API it is qs.allinterpolate(..) in Script API which are used in the python scripting interface of Allsolve. For ease of use in the GUI, the variables/functions in the Expression API have a much lighter syntax in comparison to their equivalent function in Script API.

To briefly summarize on the distinction,

• the variables/functions in the Expression API are for definining expressions in the GUI.
• the functions in the Script API are for the python scripting interface.
• Many variables/functions in the Expression API have an equivalent function in the Script API - same functionality but different syntax.

Expression API also gives access to both primary and derived field variables (if any) associated with the physics added during the simulation setup.

Physics	Primary field variable(s)	Derived field variable(s)
Solid mechanics	u	-
Current flow	v	j, E
Electrostatics	v	E
Magnetism $\varphi$	phi	H, B
Magnetism A	A	H, B
Magnetism H	H	j, E, B
Heat solid	T	-
Heat fluid	T	-
Acoustic waves	p	-
Elastic waves	u	-
Electromagnetic waves	E	-
Laminar flow	p, V	-

All the available variables and functions in the Expression API are listed below and wherever applicable the syntax of its equivalent function in Sript API is also provided.

Basic math constants

pi

The constant $\pi$.

Script API equivalent: qs.getpi()

mu0

Vacuum magnetic permeability, $\mu_0 = 1.2566370621219 \times 10^{-6} \text{ } N/A^2$.

Script API equivalent: qs.getmu0()

epsilon0

Vacuum electric permittivity, $\varepsilon_0 = 8.854187812813 \times 10^{-12} \text{ } F/m$.

Script API equivalent: qs.getepsilon0()

c0

Speed of light in vacuum, $c_0 = \dfrac{1}{\sqrt{\mu_0 \varepsilon_0}} = 2.99792458 \times 10^8 \text{ } m/s$.

Script API equivalent: qs.c0()

Quanscient variables

t

The time variable.

Script API equivalent: qs.t()

x

The x-coordinate of the geometry.

Script API equivalent: qs.getx()

y

The y-coordinate of the geometry.

Script API equivalent: qs.gety()

z

The z-coordinate of the geometry.

Script API equivalent: qs.getz()

Basic math functions

sin

• input: expression

The sine function.

The input expression must be in radians. For example sin(pi/4).

Script API equivalent: qs.sin(qs.getpi()/4)

cos

• input: expression

The cosine function.

The input expression must be in radians. For example cos(pi/4).

Script API equivalent: qs.cos(qs.getpi()/4)

tan

• input: expression

The tangent function.

The input expression must be in radians. For example tan(pi/4).

Script API equivalent: qs.tan(qs.getpi()/4)

asin

• input: expression

The inverse sine function

The output is in radians. For example asin(sqrt(0.5)).

Script API equivalent: qs.asin(qs.sqrt(0.5))

acos

• input: expression

The inverse cosine function

The output is in radians. For example acos(sqrt(0.5)).

Script API equivalent: qs.acos(qs.sqrt(0.5))

atan

• input: expression

The inverse tangent function

The output is in radians. For example atan(1).

Script API equivalent: qs.atan(1)

abs

• input: expression

The absolute value function.

Returns the absolute value of the input expression. For example abs(-2.5).

Script API equivalent: qs.abs(-2.5)

sqrt

• input: expression

The square root function.

Returns the square root of the input expression. For example sqrt(2).

Script API equivalent: qs.sqrt(2)

log

• input: expression

The log function.

Returns the natural logarithm of the input expression. For example log(2.71828182846).

Script API equivalent: qs.log(2.71828182846)

log10

• input: expression

The log10 function.

Returns the base 10 logarithm of the input expression. For example log10(100).

Script API equivalent: qs.log10(100)

exp

• input: expression

The exponential function.

Returns an expression equal to the $e^{input}$. For example exp(2).

Script API equivalent: qs.exp(2)

pow

• base: expression

• exponent: expression

The power function.

Returns an expression equal to $base^{exponent}$. For example pow(2, 5).

Script API equivalent: qs.pow(2, 5)

mod

• input: expression

• modval: float - divisor value

The modulo function.

Returns an expression whose output is equal to the remainder resulting from the division of input by modval. For example mod(10,9).

Script API equivalent: qs.mod(10, 9)

Quanscient functions

dx

• input: expression

The dx function

Returns the $x$ space derivative expression. For example the $x$-space derivative of the electric potential field is dx(v).

Script API equivalent: qs.dx(fld.v)

dy

• input: expression

The dy function

Returns the $y$ space derivative expression. For example the $y$-space derivative of the electric potential field is dy(v).

Script API equivalent: qs.dy(fld.v)

dz

• input: expression

The dz function

Returns the $z$ space derivative expression. For example the $z$-space derivative of the electric potential field is dz(v).

Script API equivalent: qs.dz(fld.v)

dt

• input: expression

The dt function

Returns the first-order time derivative expression. For example the first-order time derivative of the displacement field is dt(u).

Script API equivalent: qs.dt(fld.u)

dtdt

• input: expression

The dtdt function

Returns the second-order time derivative expression. For example the second-order time derivative of the displacement field is dtdt(u).

Script API equivalent: qs.dtdt(fld.u)

dtdtdt

• input: expression

The dtdtdt function

Returns the third-order time derivative expression. For example the third-order time derivative of the displacement field is dtdtdt(u).

Script API equivalent: qs.dtdtdt(fld.u)

dtdtdtdt

• input: expression

The dtdtdtdt function

Returns the fourth-order time derivative expression. For example the fourth-order time derivative of the displacement field is dtdtdtdt(u).

Script API equivalent: qs.dtdtdtdt(fld.u)

max

• a: expression

• b: expression

The max function.

Returns the maximum of the two input arguments. Can be used with 2 expressions, fields or parameters. For example max(x, y).

Script API equivalent: qs.max(qs.getx(), qs.gety()

min

• a: expression

• b: expression

The min function.

Returns the minimum of the two input arguments. Can be used with 2 expressions, fields or parameters. For example max(x, y).

Script API equivalent: qs.min(qs.getx(), qs.gety()

maxvalue

• region: Region

• expression: expression

• refinement: int

The expression max function.

Returns the maximum value of a scalar expression on a region. For example maxvalue(reg.surface, compx(u), 5). Vector expressions needs to be converted to scalar with eg. norm or comp functions. The accuracy of the value of an expression can be improved by providing a higher refinement value.

Script API equivalent: qs.allmax(reg.surface, qs.compx(fld.u), 5)

minvalue

• region: Region

• expression: expression

• refinement: int

The expression min function.

Returns the minimum value of a scalar expression on a region. For example minvalue(reg.surface, compx(u), 5). Vector expressions need to be converted to scalar with eg. norm or comp functions. The accuracy of the value of an expression can be improved by providing a higher refinement value.

Script API equivalent: qs.allmin(reg.surface, qs.compx(fld.u), 5)

probe

• reg: Region - A point region

• expr: expression - Expression to evaluate at point.

Probe the value of a scalar expression on a point region.

For example probe(reg.pointongeometry, norm(B).

Script API equivalent: qs.allprobe(reg.pointongeometry, qs.norm(fld.B)

integrate

• region: Region

• expr: expression

• order: int

Integrates an expression over the physical region.

Examples

• Calculate volume/area/length: integrate(region, 1, 3).

• Get the total current (flux) through a surface: integrate(reg.integration_surf, on(reg.integration_vol, transpose(j)) * normal(reg.integration_vol), 5)

Script API equivalent: qs.integrate(reg.integration_surf, qs.on(reg.integration_vol, qs.transpose(df.j)) * qs.normal(reg.integration_vol), 5)

interpolate

• region: Region

• expression: expression - Expression to evaluate at point.

• coords: [float, float, float]

Interpolate a scalar expression on a region at a point whose xyz coordinates are provided.

The expression must be scalar. Vector expressions needs to be converted to scalar with eg. norm or compx functions. For example interpolate(reg.surface, norm(B), [0,0,0.5e-3])

Script API equivalent: qs.allinterpolate(reg.surface, qs.norm(fld.B), [0,0,0.5e-3]

ifpositive

• condExpr: expression

• trueExpr: expression

• falseExpr: expression

Returns a conditional expression.

The condExpr specifies the logical condition. The returned value is trueExpr for all evaluation points where condExpr is larger or equal to zero. Otherwise, its value is falseExpr.

Example

ifpositive(x + y, 1, -1) returns a value of $1$ at points where $x + y \geq 0$ otherwise returns $-1$.

Script API equivalent: qs.ifpositive(qs.getx() + qs.gety(), 1, -1)

comp

• component: int

• input: expression

The component function.

Get the $n^{th}$ component of a column vector expression or the $n^{th}$ row of a matrix expression. For example comp(0, u)

Script API equivalent: qs.comp(0, fld.u)

compx

• input: expression

The compx function.

Get the x component of a column vector or the first row of a matrix expression. Equivalent to comp(0, input). For example compx(u).

Script API equivalent: qs.compx(fld.u)

compy

• input: expression

The compy function.

Get the y component of a column vector or the second row of a matrix expression. Equivalent to comp(1, input). For example compy(u).

Script API equivalent: qs.compy(fld.u)

compz

• input: expression

The compz function.

Get the z component of a column vector or the third row of a matrix expression. Equivalent to comp(2, input). For example compz(u).

Script API equivalent: qs.compz(fld.u)

transpose

• input: expression

The transpose function.

Returns an expression that is the transpose of the input vector or matrix expression. For example transpose(E)

Script API equivalent: qs.transpose(fld.E)

inverse

• input: expression

The matrix inverse function.

Returns the inverse of a square matrix. For example inverse([1,2;3,4])

Script API equivalent: qs.inverse(qs.array2x2(1,2,3,4))

determinant

• input: expression

The matrix determinant function.

Returns the determinant of a square matrix. For example determinant([1,2;3,4])

Script API equivalent: qs.determinant(qs.array2x2(1,2,3,4))

grad

• input: expression

The gradient function.

For a scalar input expression, this is mathematically treated as the gradient of a scalar ($\nabla{v}$) and the output is a column vector with one entry per space derivative. For a vector input expression, this is mathematically treated as the gradient of a vector ($\nabla{\boldsymbol{u}}$) and the output has one row per component of the input and one column per space derivative. For example grad(u).

Script API equivalent: qs.grad(fld.u)

div

• input: expression

The divergence function.

Computes the divergence of a vector expression ($\nabla \cdot \boldsymbol{u}$). The returned expression is a scalar. For example div(u).

Script API equivalent: qs.div(fld.u)

curl

• input: expression

The curl function

Computes the curl of a vector expression ($\nabla \times \boldsymbol{H}$). The returned expression is a vector. For example curl(H).

Script API equivalent: qs.curl(fld.H)

norm

• input: expression

The norm function.

This retruns the $L2$ norm of an expression input. For example norm(B).

Script API equivalent: qs.norm(fld.B)

crossproduct

• a: expression

• b: expression

The cross product function.

Computes the cross-product of two vector expressions ($\boldsymbol{a} \times \boldsymbol{b}$). The returned expression is a vector. For example crossproduct(E, normal(reg.vol))

Script API equivalent: qs.crossproduct(fld.E, qs.normal(reg.vol))

doubledotproduct

• a: expression

• b: expression

The double dot product function.

Computes the double-dot product of two matrix expressions. The returned expression is a scalar. $\boldsymbol{A:B} = \sum_{i,j} A_{ij} B_{ij}$. For example doubledotproduct([1, 2; 3, 4], [11, 12; 13, 14]) is resolved to 130.

Script API equivalent: doubledotproduct(qs.array2x2(1, 2, 3, 4), qs.array2x2(11, 12, 13, 14))

cn

• n: float - fundamental frequency multiplier

cn(n) is a shortcut for cos(2 * pi * f * n * t). For example cn(2).

Script API equivalent: qs.cn(2)

sn

• n: float - fundamental frequency multiplier

sn(n) is a shortcut for sin(2 * pi * f * n * t). For example sn(2).

Script API equivalent: qs.sn(2)

getharmonic

• harmonicnumber: int

• input: expression

Returns the harmonicnumber harmonic of the input expression. For example getharmonic(2, u).

Script API equivalent: qs.getharmonic(2, fld.u)

harm

• harmonicnumber: int

• input: expression

Returns the harmonicnumber harmonic of the input expression. For example harm(2, u).

Script API equivalent: qs.harm(2, fld.u)

makeharmonic

• harmonicnumbers: List[int]

• expr: expression

The makeharmonic function creates a harmonic expression for the input expression with the given harmonic indices. For example makeharmonic([1,2,4], [11, harm(2,v), 14)

Script API equivalent: qs.makeharmonic([1,2,4], [11, v.harmonic(2), 14])

harmonicnorm

• harmonicnumbers: List[int]

• expr: expression

The harmonicnorm function evaluates the norm of the input expression considering only the harmonic indices provided. For example harmonicnorm([2,3], u).

Script API equivalent: qs.norm([2, 3], fld.u, 7)

on

• physreg: Region

• expr: expression

The on function.

This function allows to use fields, unknown dof fields or general expressions across physical regions with possibly non-matching meshes by evaluating the expression argument using a (x, y, z) coordinate interpolation. For example to get the total current (flux) through a surface: integrate(reg.integration_surf, on(reg.integration_vol, transpose(j)) * normal(reg.integration_vol), 5).

Script API equivalent: qs.integrate(reg.integration_surf, qs.on(reg.integration_vol, qs.transpose(df.j)) * qs.normal(reg.integration_vol), 5)

normal

• physreg: Region - region with project dimension

Returns the unit normal vector pointing out of the physical region. For example normal(reg.volume).

Script API equivalent: qs.normal(reg.volume)

linspace

• start: float

• end: float

• numValues: int

The linspace function produces a row vector of length numValues with linearly spaced values from start to end.

It can be used to create override vectors for sweeps.

For example linspace(1, 3, 5) is resolved to [1, 1.5, 2, 2.5, 3].

Script API equivalent: qs.linspace(1, 3, 5)

logspace

• start: float

• end: float

• numValues: int

• base: int = 10

The logspace function produces a row vector of length numValues with logarithmically spaced values from $base^{start}$ to $base^{end}$, with default $base=10$

It can be used to create override vectors for sweeps.

For example logspace(1, 3, 3) is resolved to [10, 100, 1000].

Script API equivalent: qs.logspace(1, 3, 3)

repelem

• vec: vector

• numRepeat: int

Repeats the elements of a vector numRepeat times.

This is typically used to create override vectors for multivariate sweeps so that numRepeat varies based on other vector lengths. For example repelem([1, 2, 3], 3) is resolved to [1, 1, 1, 2, 2, 2, 3, 3, 3].

Script API equivalent: Not applicable

repmat

• mat: matrix

• rowRepeat: int

• colRepeat: int

Repeats the matrix rowRepeat times in row direction and colRepeat times in column direction

This is typically used to create override vectors for multivariate sweeps so that rowRepeat is always 1 and colRepeat varies based on other vector lengths. For example repmat([1, 2, 3], 1, 3) is resolved to [1, 2, 3, 1, 2, 3, 1, 2, 3].

Script API equivalent: Not applicable

getcoords

• region: Region - A point region

Get a coordinate vector of a given point region. For example getcoords(reg.point_region).

Script API equivalent: qs.getcoords(reg.point_region)

getcoordscomp

• region: Region - A point region

• comp: int - The coordinate component. 0 for x, 1 for y and 2 for z component

Get a coordinate component of a given point region.

For example to get y-coordinate of a point region: getcoordscomp(reg.point_region, 1).

Script API equivalent: qs.getcoordscomp(reg.point_region, 1)

wavelet

• frequency: expression

• delay: expression

This function creates a Ricker wavelet with given frequency and delay. Note that the delay is not directly in time but rather it represents the amount of time period (T=1/f) by which the wavelet is delayed. The time period corresponds to that of the frequency. For example wavelet(freq, 0.5).

Script API equivalent: qs.wavelet(freq, 0.5)

ramp

• rampuptime: expression - The time to transition linearly from value 0 to 1

• holdtime: expression - The time the value stays at 1

• rampdowntime: expression - The time to transition linearly from value 1 to 0

• delay: expression - The time at which the rampup starts

Create a ramp signal.

It is a signal that starts initially at value 0. Then at 0 + delay in seconds it starts to transition from value 0 to 1 in a linear increase. That transition happens in rampuptime seconds. This is followed by a flat value 1 that is held for holdtime seconds. This is followed by a linear decrease from value 1 to 0 that happens in rampdowntime seconds. The value is then forever 0 after that. For example ramp(3, 5, 3, 0).

Script API equivalent: qs.ramp(3, 5, 3, 0)

vonmises

• stress: expression

The von Mises function.

This returns the von Mises stress expression corresponding to the 3D stress tensor provided as argument. The stress tensor should be provided in Voigt form $(\sigma_{xx},\sigma_{yy},\sigma_{zz},\sigma_{yz},\sigma_{xz},\sigma_{xy})$. For example vonmises(par.H() * strain(u))

Script API equivalent: qs.vonmises(par.H() * qs.strain(fld.u))

neumann

• bndreg: Region

• calcreg: Region

• fld: field

The neumann function.

Returns the Neumann term on the boundary bndreg associated with the domain calcreg and the field fld. The term can be integrated over the boundary, e.g. integrate(reg.boundary, neumann(reg.boundary, reg.volume, T), 5). If bndreg is at an interface region, the calcreg and fld together define the correct term to return. For more information, see allneumann

Script API equivalent: qs.allneumann(reg.bnd, reg.vol, fld.T)

lineinterpolate

• region: Region

• expression: expression

• firstCoords: [float, float, float]

• lastCoords: [float, float, float]

• numSamples: int

Interpolates the expression at a series of points along a line inside a region.

The line for interpolation is defined by a starting and an end point whose [x,y,z] coordinates are provided in the firstCoords and lastCoords arguments. The numSamples argument determines the number of sample points considered along the line. For example lineinterpolate(reg.box, [0, 0, 0], [0, 100, 0], 11). If the start and end points are geometric points, then their coordinates can be obtained using getcoords(reg.point). If a requested interpolation point along the line cannot be found (because it is outside of region or because the interpolation algorithm fails to converge, as can happen on curved 3D elements) then an error occurs.

Script API equivalent: qs.alllineinterpolate(reg.box, [0, 0, 0], [0, 100, 0], 11)

absZ

• V: expression - Voltage

• I: expression - Current

Returns the magnitude of the complex impedance $Z = V/I$. For example with a lumped port lump: absZ(lump.V, lump.I).

Script API equivalent: qs.absZ(lump.V, lump.I)

realZ

• V: expression - Voltage

• I: expression - Current

Returns the real part of the complex impedance $Z = V/I$. For example with a lumped port lump: realZ(lump.V, lump.I)

Script API equivalent: qs.realZ(lump.V, lump.I)

imagZ

• V: expression - Voltage

• I: expression - Current

Returns the imaginary part of the complex impedance $Z = V/I$. For example with a lumped port lump: imagZ(lump.V, lump.I)

Script API equivalent: qs.imagZ(lump.V, lump.I)

argZ

• V: expression - Voltage

• I: expression - Current

Returns the phase of the of the complex impedance $Z = V/I$. For example with a lumped port lump: argZ(lump.V, lump.I)

Script API equivalent: qs.argZ(lump,V, lump.I)