a field-theory motivated approach to computer algebra

## Installation

### The Jupyter kernel does not start.

In order for Jupyter to start the Cadabra kernel, it has to be able to find the cadabra2 and cadabra2_jupyter modules. If you are using a binary package, these things will be installed in a path searched by the system python, but if you built from source, they may not be.

Typically, if you configure with cmake .. with no further options, the installation will be into /usr/local/lib/python3.7/site-packages (possibly with a different python version number). You need to add this to your PYTHONPATH, e.g. using

export PYTHONPATH=\${PYTHONPATH}:/usr/local/lib/python3.7/site-packages
in the terminal, before starting jupyter notebook from there. You can stick this into the ~/.bashrc file to make it automatic at every terminal start.

### I get a 'Generic LaTeX error' when evaluating a cell.

This is typically caused by a missing LaTeX package. The error dialog may give you a hint, but if you want to see the full LaTeX error, take note of the file name in the error dialog, and try to run that file through latex by hand.

The most common missing package is ytableau, which you can get on Debian/Ubuntu systems by installing the texlive-science package (or on older versions, the texlive-math-extra package) and on Fedora by installing texlive-ytableau.

## How to...

### What is the difference between free, fixed and independent indices?

When you declare an index set, you can give it a position property, which takes one of three values free, fixed or independent. Indices which are free can be raised or lowered at will, and pairs can be at the same position; these are typically used in case there is no metric associated to them. Indices which have a different meaning when they are in subscript or superscript position should, instead, be declared fixed; this is what you would typically do in special/general relativity, where the difference between an upper or lower index is a factor of the metric. Cadabra can still swap the position of pairs of indices in e.g. the canonicalise function. If you want Cadabra to never touch the position of indices in a set, declare them independent.

## Error messages

### RuntimeError: Dependencies on derivatives are not yet handled in the sympy bridge.

This error occurs when you try to use the evaluate algorithm on an expression with derivatives, and the expression contains objects which were declared with a property ::Depends(\partial{#}) or something to that extent. To avoid the issue, there are two ways out. Either declare the dependence of that object directly on the coordinate. So instead do something like
x::Coordinate;
A::Depends(x);
The other alternative is to simply switch off automatic simplification, by using the simplify=False argument to the evaluate function.

## Design and philosophy

### Why not build the tensor functionality into Sympy, and wedge into Sympy's expression parser?

Cadabra uses the philosophy that expressions should be represented in their own language, not Python. However, one can do something like that in Sympy, by only feeding expressions in string form to the logic in sympy.parsing.sympy_parser. So in a sense Sympy supports this Cadabraesque mode of working, even though the tutorials and examples do not emphasise it. The reason why Cadabra nevertheless uses its own parser, and its own tree representation of expressions, is simply that an enormous amount of work would have to be done to rewrite the lot so that it fits into the Sympy framework. Moreover, little would be gained by doing this: almost all functionality which is in Sympy and which would make sense when applied to tensors (think of taking derivatives, or pattern matching) would require a lot of extra Sympy code to extend it beyond scalars. The way things are now the separation is clean, localised, and relatively easy to maintain. If you would ever rewrite Cadabra+Sympy from scratch you might take a different approach, but that's not going to happen soon.

### Why an independent notebook interface instead of building on IPython?

There are a number of reasons for this. For starters, Cadabra's notebook interface predates IPython (that is, a publically available version of it) by quite a few years. That by itself is of course not a very good reason to keep developing the Cadabra notebook interface, but it does play a certain role.

A more important reason has to do with the fact that there are, despite what one might think at first inspection, quite a few differences between IPython/Jupyter and the Cadabra interface. The most obvious one is that Cadabra is a native application, which does not rely on a web browser to display its results. I still think that native applications have their place, as they tend to look and feel much better than web apps.

IPython/Jupyter tend to be focussed a lot on data-centric problems, and less so on being a nice front-end for symbolic mathematics. These two do differ.

Another reason to keep developing the Cadabra notebook interface is that it allows me much more flexibility in trying new features and ideas. As a consequence, Cadabra for instance has a way to open multiple views on the same notebook.