The (non-exported) Cartesian module provides macros that facilitate writing multidimensional algorithms. It is hoped that Cartesian will not, in the long term, be necessary; however, at present it is one of the few ways to write compact and performant multidimensional code.
Principles of usage¶
A simple example of usage is:
which generates the following code:
In general, Cartesian allows you to write generic code that contains
repetitive elements, like the nested loops in this example. Other
applications include repeated expressions (e.g., loop unwinding) or
creating function calls with variable numbers of arguments without using
the “splat” construct (
The (basic) syntax of
@nloops is as follows:
- The first argument must be an integer (not a variable) specifying the number of loops.
- The second argument is the symbol-prefix used for the iterator
variable. Here we used
i, and variables
- The third argument specifies the range for each iterator variable. If
you use a variable (symbol) here, it’s taken as
1:size(A,dim). More flexibly, you can use the anonymous-function expression syntax described below.
- The last argument is the body of the loop. Here, that’s what appears
There are some additional features of
@nloops described in the
@nref follows a similar pattern, generating
@nref3Ai. The general practice is to read from left to right,
which is why
@nloops3iAexpr (as in
i_2 is to the left and the range is
to the right) whereas
@nref3Ai (as in
A[i_1,i_2,i_3], where the array comes first).
If you’re developing code with Cartesian, you may find that debugging is
easier when you examine the generated code, using
Supplying the number of expressions¶
The first argument to both of these macros is the number of
expressions, which must be an integer. When you’re writing a function
that you intend to work in multiple dimensions, this may not be
something you want to hard-code. If you’re writing code that
you need to work with older Julia versions, currently you
should use the
@ngenerate macro described in an older version of this documentation.
Starting in Julia 0.4-pre, the recommended approach is to use
@generatedfunction. Here’s an example:
Naturally, you can also prepare expressions or perform calculations
Anonymous-function expressions as macro arguments¶
Perhaps the single most powerful feature in
Cartesian is the
ability to supply anonymous-function expressions that get evaluated at
parsing time. Let’s consider a simple example:
n expressions that follow a pattern. This
code would generate the following statements:
In each generated statement, an “isolated”
j (the variable of the
anonymous function) gets replaced by values in the range
Generally speaking, Cartesian employs a LaTeX-like syntax. This
allows you to do math on the index
j. Here’s an example computing
the strides of an array:
would generate expressions
Anonymous-function expressions have many uses in practice.
@nloops N itersym rangeexpr bodyexpr
@nloops N itersym rangeexpr preexpr bodyexpr
@nloops N itersym rangeexpr preexpr postexpr bodyexpr
Nnested loops, using
itersymas the prefix for the iteration variables.
rangeexprmay be an anonymous-function expression, or a simple symbol
varin which case the range is
Optionally, you can provide “pre” and “post” expressions. These get executed first and last, respectively, in the body of each loop. For example, :
would generate :
If you want just a post-expression, supply
nothingfor the pre-expression. Using parenthesis and semicolons, you can supply multi-statement expressions.
@nref N A indexexpr
Generate expressions like
indexexprcan either be an iteration-symbol prefix, or an anonymous-function expression.
@nexprs N expr
exprshould be an anonymous-function expression.
@ntuple N expr
@nall N expr
@nall3d->(i_d>1)would generate the expression
(i_1>1&&i_2>1&&i_3>1). This can be convenient for bounds-checking.
@nif N conditionexpr expr
@nif N conditionexpr expr elseexpr
Generates a sequence of
if...elseif...else...endstatements. For example:
@nif3d->(i_d>=size(A,d))d->(error("Dimension ",d," too big"))d->println("All OK")
ifi_1>size(A,1)error("Dimension ",1," too big")elseifi_2>size(A,2)error("Dimension ",2," too big")elseprintln("All OK")end