# Math and equations

There are several ways to make writing math in your documents as familiar as possible.
Math can either be (1) inline or (2) displayed as an equation block; which are roles and directives specifically.
In addition to the usual MyST syntax, you can also use "dollar math", which is derived from $\LaTeX$
and surrounds inline math with single dollar signs (`$`

), and equation blocks with two dollar signs (`$$`

).
The details of using inline math and equations are below.

For example, here is an example of a cross-product, which we reference in the docs below!

## #Inline Math

There are two ways to write inline math; (1) with a `math`

role or (2) by wrapping it in single dollar signs.

The output of these is the same (which you can see by looking at the AST and $\LaTeX$ outputs in the demo above).
Using a `math`

role is much less likely to collide with your writing if it includes dollars (e.g. $2.99).

Ocassionally, dollar signs that you do not intend to wrap math need to be escaped.
These can be preceded by a backslash, that is `\$2.99`

, and the `\`

will not be displayed in your output.
If using $\LaTeX$ as an output, these dollarsigns will also be properly escaped again!

## #Equations

You can also include math directives to create an equation block in your document.
Equations are great for complex or longer equations and can be referenced throughout your document.
There are three ways to create an equation:
(1) a `math`

directive (rather than a role for inline math);
(2) wrap the equation in two dollar-signs, `$$`

; or
(3) use a `\begin{equation}`

statement directly (i.e. using AMS math).

### #Math directives

The math directive takes no arugments and the body of the directive is the $\LaTeX$ style math.
You can have an optional `label`

parameter, which will label this equation for later cross-referencing, see Referencing Equations below for more on that!

### #Dollar math equations

You can also create equations by wrapping content with two dollar signs (`$$`

).
In this syntax, you can follow the equation with a label in brackets `(label)`

.
This can be quite convinient if your equations are small, the entire syntax can fit on a single line.

### #AMS Math

In addition to a `math`

directive and dollar-math syntax, you can also use AMS math, which is specifically using AMS Version 2.1.

You can label your equation with the standard `\label{my-equation}`

that you would do in $\LaTeX$.
The equation cross-referencing and numbering will work with the rest of your content.

## #Referencing Equations

As you have seen above, each of the ways to create equations can also label them and then cross-reference these in other parts of your document. For example, the start of this document had Equation 1, which can be referenced here with a link and inline-preview. There are a few different ways to reference equations, with more details in Cross-references.

### #Labelling equations

The examples above all show how to label an equation in the interactive demos.
With a directive, you can use the `label`

option;
with dollar-math, follow the closing `$$`

with a space and a `(label)`

; and
in AMS math you can use the `\label{}`

syntax that is native to $\LaTeX$.

For example, a directive can be labelled as follows:

```
```{math}
:label: my_label
my_math
```
```

To reference equations you can use a markdown link with the target, for example:`[](#cross)`

will create: (1)

### #Disabling Numbering

TODO!

### #Customizing Numbering

To change the reference format, you can use the frontmatter under the `xxx`

field.

TODO!

## #Adding Macros

Macros allow you to create reusable math elements that can simplify the writing of a document.
These marcos can be defined for a single document through the frontmatter, or shared in project frontmatter.
These macros are used throughout HTML and $\LaTeX$ exports and are written declaratively so that they can be easily parsed. Macros are the same as `\newcommand`

or `\renewcommand`

in $\LaTeX$, and use the `math`

object in the frontmatter.

The `math`

macros are parsed as `yaml`

in the frontmatter and can easily be shared or inherited through project to page frontmatter. These are also inserted into any $\LaTeX$ outputs for creating professional PDF documents.

The `key`

is the command that you are defining, in the demo above `\dobs`

or `\dpred`

, the command should include the `\`

. The value of the entry should be the macro definition, if the definition contains `#1`

then there will be one required argument for the macro that should be supplied in braces when you use it (e.g. `\dpred{m}`

). The macros can be nested as in the example where `\dobs{\mref}`

uses two macros.

In the macro in the example above, `\mathbf{d}_\text{pred}\left( #1 \right)`

, the `#1`

is the first and only required argument, and is placed inbetween left and right brackets. The numbering for arguments starts at one, and other arguments can be added with `#2`

, `#3`

, etc. and then input in a command using `\command{arg1}{arg2}`

.