Algebraic operators#

BOUT++ provides a wide variety of algebraic operators acting on fields.

Most of these operators can participate in the lazy field-expression system described in Field Expressions. In practice this means you can usually write ordinary algebraic code and let BOUT++ delay evaluation until assignment or reduction.

For a completely up-to-date list, see the Non-member functions part of field2d.hxx, field3d.hxx, and fieldperp.hxx.

Common operators#

Table 11 Algebraic operators#

Name

Description

min(f, allpe=true, region)

Minimum (optionally over all processes)

max(f, allpe=true, region)

Maximum (optionally over all processes)

mean(f, allpe=true, region)

Mean (optionally over all processes)

pow(lhs, rhs[, region])

\(\mathtt{lhs}^\mathtt{rhs}\)

SQ(f, region)

Square of f

sqrt(f, region)

\(\sqrt{(f)}\)

abs(f, region)

\(|f|\)

exp(f, region)

\(e^f\)

log(f, region)

\(\log(f)\)

sin(f, region)

\(\sin(f)\)

cos(f, region)

\(\cos(f)\)

tan(f, region)

\(\tan(f)\)

sinh(f, region)

\(\sinh(f)\)

cosh(f, region)

\(\cosh(f)\)

tanh(f, region)

\(\tanh(f)\)

floor(f, floor_value[, region])

Returns a field where values below floor_value are replaced by floor_value

filter(f, n, region)

Calculate the amplitude of the Fourier mode in the z-direction with mode number n

lowpass(f, nmax, region)

Remove Fourier modes (in the z-direction) with mode number higher than zmax

lowpass(f, nmax, nmin, region)

Remove Fourier modes (in the z-direction) with mode number higher than zmax or lower than zmin

shiftZ(f, angle, region)

Rotate f by angle in the z-direction. \(\mathtt{angle}/2\pi\) is the fraction of the domain multiplied by \(2\pi\) so angle is in radians if the total size of the domain is \(2\pi\)

DC(f, region)

The average in the z-direction of f (DC stands for direct current, i.e. the constant part of f as opposed to the AC, alternating current, or fluctuating part)

if_else(cond, lhs, rhs)

Select between two algebraic branches

if_else_zero(cond, expr)

Select either expr or zero

These operators can usually be combined directly in expressions:

Field3D rhs = sqrt(SQ(n) + SQ(T));
Field3D profile = pow(n + n0, 1.5);
Field3D masked = if_else(use_drive, source * profile, sink * profile);
BoutReal max_error = max(abs(lhs - rhs), true);

Reductions such as min, max, and mean can operate directly on an expression, so an intermediate field is often unnecessary.

pow also participates in lazy field expressions, including mixed Field2D/Field3D cases where the Field2D operand is broadcast in z. FieldPerp also has pow overloads for FieldPerp with FieldPerp or a scalar.

Region arguments#

These operators take a region argument. Common values are [1] (see Iterating over fields):

  • RGN_ALL, which is the whole mesh

  • RGN_NOBNDRY, which skips all boundaries

  • RGN_NOX, which skips the x boundaries

  • RGN_NOY, which skips the y boundaries

The default is usually RGN_ALL. Restricting the region can improve performance when guard-cell values will not be used.

When a region-limited expression is materialized into a field, only the selected region is guaranteed to contain valid values. This is the same performance-oriented convention used by other field operators.

Field3DParallel follows the same rule for the main field data. On FCI meshes, materializing a lazy expression into Field3DParallel also preserves the forward and backward parallel slices when those slices are available on the expression operands. Materializing the same expression into plain Field3D does not preserve those slices.

Further reading#