+++
title = "Matplotlib configuration"
weight = 183
+++

## Matplotlib configuration

Images in BornAgain examples are generated using the Python library
[Matplotlib](https://matplotlib.org).

Default settings can be overridden
by function arguments, Matplotlib ressources, or environment variables.

### Plot invocation

In the BornAgain example scripts, Matplotlib is invoked through the following functions:

##### plot_simulation_result

`plot_simulation_result(result, **plotargs)` plots one 1D or 2D simulation result.

The argument `result` is of type {{% ref-class "Device/Data" "Datafield" %}},
as returned by the function `Simulation.simulate()`.

The optional `plotargs` arguments are discussed below.

##### plot_multicurve

`plot_multicurve(results, **plotargs)` plots several 1D simulation results into one frame.

The argument `results` is a list of {{% ref-class "Device/Data" "Datafield" %}}s.

The optional `plotargs` arguments are discussed below.

##### make_plot

`make_plot(results, ncol, **plotargs)` plots several simulation results into as many different frames.

The argument `results` is a list of {{% ref-class "Device/Data" "Datafield" %}}s.

The argument `ncol` is the number of columns of the grid that holds the plot frames.

The optional `plotargs` arguments are discussed below.

### Optional plot arguments

In the functions documented above, `**plotargs` stands for optional keyword arguments.
These are supplied either directly like in
```
    result = simulation.simulate()
    bp.plot_simulation_result(result, cmap='viridis', legendloc='lower right')
    bp.plt.show()
```
or through a dictionary variable like in
```
    result = simulation.simulate()
    plotargs = {}
    plotargs['aspect'] = 'auto'
    plotargs['intensity_min'] = 1e-12
    plotargs['intensity_max'] = 1e2
    bp.plot_simulation_result(result, **plotargs)
    bp.plt.show()
```

Support keyword arguments include

* `intensity_min`,
* `intensity_max`,
* `xlabel`,
* `ylabel`,
* `zlabel`,
* `legendloc`: where a legend is placed.
* `aspect`: [aspect ratio](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html), default is 'auto', other possible values are 'equal', or a number,
* `cmap`: heat map, see below.

For other optional arguments that may or may not be respected, see
the [Matplotlib customizing tutorial](https://matplotlib.org/stable/tutorials/introductory/customizing.html).

### Code location

The above documented functions are implemented in the Python module
[`ba_plot`]({{% url-src %}}/Wrap/Python/src/bornagain/ba_plot.py)
that is typically imported with the line
```
from bornagain import ba_plot as bp
```

### Heat map

Matplotlib supports various color schemes for plotting color-coded pixel values in 2d:
[Matplotlib color schemes tutorial](https://matplotlib.org/stable/tutorials/colors/colormaps.html).
It is generally recommended to use one of the five "perceptually uniform sequential" color schemes:
![Matplotlib perceptually uniform sequential color schemes](/img/matplotlib_pus_colormaps.png "Perceptually uniform sequential color schemes from Matplotlib.")

When plotting through `ba_plot`, then the color scheme is determined in this order:
* from the optional `plotargs` arguments if there is one with keyword `cmap`, like `cmap='jet'`;
* otherwise from the environment variable `CMAP`, if defined;
* otherwise from the hard-coded default "inferno".

Note that the variable `image.cmap` from
[matplotlib.pyplot.rcParams](https://matplotlib.org/stable/users/explain/customizing.html)
is ignored.
This is a concious choice - we expect an environment variable to be more convenient for
users that are not Matplotlib experts.

## LaTeX markup

Text enclosed between dollar signs `$...$` is interpreted as LaTeX markup.
It allows us to plot greek letters (`$\alpha$`), superscripts (`$F^2$`),
subscripts (`$\phi_{\rm i}`$), and special symbols (`$90^\circ$`).

By default, it is processed by Matplotlib's own LaTeX processor.
However, if _usetex mode_ is activated, then the original LaTeX text
processor is used, and labels are typeset in LaTeX's computer modern fonts.
For _usetex mode_ to work, it may be necessary to install extra software.
Under Debian, the required packages are `texlive-latex-extra` (and
dependencies), `dvipng` and `cm-super-minimal`. We have no clue how
to support _usetex mode_ under Windows.

Original LaTeX fonts differ in many respects from Matplotlib's default
Helvetica fonts.  Fonts from these different families should not be mixed.
Therefore, in _usetex mode_ it is important that *all* plot labels and titles
be enclosed in `$...$`, or for upright text `${\rm ...}$`.

To activate _usetex mode_, do one of the following:
* set environment variable `USETEX` to `True`, or
* set [matplotlib.pyplot.rcParams](https://matplotlib.org/stable/users/explain/customizing.html)
  entry `rc['text.usetex']` to `True`.
