Input format

General structure

Cadabra uses LaTeX for the input of mathematical expressions, and Python to write out actions and algorithms which act on these expressions. In order to make it simpler to mix LaTeX and Python code, the cadabra2 command-line client and the cadabra2-gtk notebook interface use a pre-processor which accepts this mixture and converts it to pure Python. This happens under the hood and most people will not need to know more about this, other than that it works.

Expressions are entered by using the ':=' operator, as in

ex:=A+B+C_{m} C^{m};

$\displaystyle{}A+B+C_{m} C^{m}$

A + B + C_{m} C^{m}

The ex identifier is a Python variable, and the above line assigns it the mathematical expression which follows the ':=' operator. Internally, objects like ex are ordinary Python objects (of type cadabra2.Ex), and their names can thus only contain normal alphanumeric symbols.

type(ex);

<class 'cadabra2.Ex'>

Lines containing mathematical expressions like the above always have to be terminated with either a ';' or a ':' (or a '.', which acts in the same way as ':'). These delimiting symbols act in the same way as in Maple: the second form suppresses the output of the entered expression. Long expressions can, because of these delimiters, be spread over many subsequent input lines. As in ordinary Python, any line starting with a "\#" sign is considered to be a comment (even when it appears within a multi-line expression).

When entering maths as above (using the ':=' assignment operator) you do not need to indicate that the right-hand side is mathematics. There are situations, however, when you do need to give Cadabra a hint that what you type is maths, not Python, namely when you want to write maths without assigning it to a Python variable. In this case, you add dollar symbols, just as in LaTeX:

substitute($A + B + C$, $C -> D$);

$\displaystyle{}A+B+D$

A + B + D

As you can see, this uses an 'inline' definition of a mathematical expression, without giving it a name.

Algorithms acting on mathematical expressions

Mathematical expressions are manipulated by using ordinary Python functions, which act on cadabra2.Ex objects. You have already seen an example of this above: when we wrote substitute(...), this is a normal Python function, and it acts on the cadabra2.Ex object which contains the mathematical expression $A+B+C$. It also gets passed a second argument, which is the substitution rule, in the example above given by $C \rightarrow D$. In both cases we have in-lined this expression using the LaTeX dollar notation. An alternative way to write the above is to first define the two expressions, and then feed those (as Python objects) to the substitute algorithm. This looks as follows:

ex := A+B+C; rule := C -> D; substitute(ex, rule);

$\displaystyle{}A +B +C$

A + B + C

$\displaystyle{}C \rightarrow D$

C -> D

$\displaystyle{}A +B +D$

A + B + D

Observe how we do not put dollar signs around the ex and rule arguments of the substitute function call: these things are Python objects, and therefore that last line above is just a standard Python function acting on Python objects. The only non-standard thing is the semi-colon at the end: it ensures that when we execute the cell, the result of that function call gets displayed.

Function calls inside mathematical expressions

Many computer algebra systems do not make a distinction between the language used to write the mathematical expressions and the language used to write the actions and algorithms acting on them. If you prefer that notation, you can instruct Cadabra to allow in-line Python code in mathematical expressions, by using a particular kernel option:

__cdbkernel__.call_embedded_python_functions=True

You can now write the above example in an even more compact form, as

ex:= substitute( A+B+C, C->D );

$\displaystyle{}A +B +D$

A + B + D

Note that the entire line after the ':=' operator is considered a mathematical expression, but Cadabra has automatically applied the substitute Python function on the two sub-expressions. The result is stored in the Python object ex. Note that with this option turned on, any function with a name two or more characters long will be treated as a Python function and Cadabra will attempt to run it. If your mathematical expressions contain such functions as mathematics (not Python), then you will need to keep this functionality turned off.

__cdbkernel__.call_embedded_python_functions=False

Similarity and difference with LaTeX

Inside mathematical expressions you can use most of the standard LaTeX notation. You can write mathematical functions acting on variables, use special functions, and things like integrals. In some cases this deviates slightly from what you are used to, mostly in order to remove ambiguities in the LaTeX notation, as the example below shows:

ex:= f(x) \sin(x) \int{ \cos(y) }{y, 0, x};

$\displaystyle{}f\left(x\right) \sin{x} \int_{0}^{x} \cos{y}\,\,{\rm d}y$

f(x) \sin(x) \int{\cos(y)}{{y, 0, x}}

Cadabra always uses standard sub- and super-script notation for vector, spinor and other tensor indices,

ex:= R^m_{n p q} v^p v^q;

$\displaystyle{}R^{m} _{n p q} v^{p} v^{q}$

R^{m} _{n p q} v^{p} v^{q}

Be careful that you will in general may need to be a little bit more generous in providing curly braces to group these sub- and superscripts; sometimes it is best to be on the cautious side. Also be aware that while Cadabra tries hard to figure out products of symbols even when you do not write a multiplication sign, you need to give it some hints by using spaces appropriately. If you write 'mn' this is treated as one symbol, not the product of 'm' and 'n'. If you want the latter, put a space inbetween.