Macro language
To plot a function of the magnetic field calculated by a given probe, open the edit window for the probe, enter the macro-language function on the Macro tab, and on the Plot tell the probe to plot the macro result.
The macro language is governed by a few simple rules:
- There is no operator precedence; all operators have equal precedence. Operations group right to left within parenthesized groups (examples below will make this clear).
- There is one statement per line.
- The value of the last statement is the macro result which can be plotted.
The macro language operates on a workspace that contains a few predefined variables determined by the probe:
| variable | meaning |
| x | x coordinate of probe point in laboratory frame |
| y | y coordinate of probe point in laboratory frame |
| z | z coordinate of probe point in laboratory frame |
| Bx | x component of magnetic flux density in laboratory frame |
| By | y component of magnetic flux density in laboratory frame |
| Bz | z component of magnetic flux density in laboratory frame |
| B | magnitude of magnetic flux density |
| Ax | x component of magnetic vector potential in laboratory frame |
| Ay | y component of magnetic vector potential in laboratory frame |
| Az | z component of magnetic vector potential |
| A | magnitude of magnetic vector potential |
| dBxdx, dBxdy, etc. | components of magnetic field gradient tensor |
These variables are arrays whose length is the number of field points. For example, if the probe samples the field at 100 points, then Bx will be an array of length 100. Arithmetic operations are performed in parallel on all elements of arrays, so the expression
w=Bx^2
makes a new variable w which is a 100 element array each element of which is the square of the corresponding element in Bx.
A few examples will clarify (and hopefully motivate) the absence of operator precedence:
| mathematics | macro language |
 |
B*sin 2*pi*x |
 |
(x+y)/sqrt 2*log B |
 |
B^pi/3 |
Finally, here is an example of a macro sequence to let you plot the potential energy in micro-Kelvin of an Cs-133 atom in a magnetic trap, including gravity:
m=132.905*1.67e-27 g=9.81 mu=9.27e-24 k=1.38e-23 1e6*((mu*B)-m*g*z)/k
Constants
Special constants
The macro language has constants pi and e built in.
Scalars
Scalar (single-element) numbers are the typical floating point numbers recognizable by most programming languages. Scientific notation is indicated as usual, with an e or E separating the mantissa and the exponent. Examples of valid scalars:
5 -7.002 3.24 -45.3e-12
Vectors
A vector of numbers is specified by listing the elements in sequence. The extent of the vector is determined by context. For example, the statement
12e-3+4 5 6
adds the scalar 12e-3 to each element of the three element vector 4 5 6, to give a three-element vector.
Negative numbers and vectors
A minus sign immediately before the first digit of a number indicates that the number is negative if permitted by context. Otherwise the minus sign will be interpreted as the minus operator. This rule determines how we interpret - in vectors. For example, the macro expression
-5 4 -3
produces the vector of three elements, with the first and last element negative, whereas
- 5 4 -3
is the minus operator acting on the entire vector which follows, to produce the vector
-5 -4 3
The macro statement
-5 4-3
interprets the first minus sign as negative and the second minus sign as an operator, and the expression evaluation gives
-8 1
This context senstivity of the minus sign eliminates the need for a special "negative number" sign.
Variables
Variables are any string of alphanumeric characters starting with an alpha (upper or lower case a thru z). The macro language is case sensitive, so x and X are distinct variables. To create a variable, just assign a value to it, as in the statement
t=4*pi
Subscripting
To access a particular element of an array, use square brackets. The first element is index 0, as in the statement
B=B/B[0]
which scales the vector of field values B so that its first element is unity.
Operators
Unary
Unary operators are those which have a right argument only. Unary and binary operators are distinguished by context. For example in the statement x*-y the operator - is unary and the operator * is binary, because there is no left argument for the - to act upon.
| +x | identity (this operator has no effect) |
| -x | negation |
| *x | signum (1, 0, or -1 with the same sign as the argument) |
| /x | reciprocal |
| ^x | e to the power of x |
| |x | absolute value of x |
| log x | natural logarithm of x |
| sin x | trigonometric function (argument in radians) |
| cos x | " |
| tan x | " |
| sinh x | hyperbolic trigonometric function |
| cosh x | " |
| tanh x | " |
Binary
Binary operators are those which have a left argument and a right argument.
| a=b | assignment |
| a+b | addition |
| a-b | subtraction |
| a*b | multiplication |
| a/b | division |
| a^b | a to the power b |
| a log b | log of b to the base a |