Manual for Package pgfplots
2D/3D Plots in LATeX, Version 1.18.1
http://sourceforge.net/projects/pgfplots

If lua backend is active and the document is processed by means of lualatex, pgfplots activates scalability and performance improvements which result in the same output as without it, but with less time and with a smarter memory management.

The feature relies on a partial reimplementation of pgfplots in the fast scripting language lua. In order to benefit from it, you need to

• 1. write compat=1.12 (or newer) into your preamble and

• 2. use lualatex to translate your .tex files (or at least those which contain pgfplots figures).

The time to generate surface plots with this feature can be reduced to 25%–50% of the time required by the pure TeX implementation (i.e. pdflatex). Other plot types will also benefit from the feature.

The lua backend works in two ways: first, it substitutes isolated routines by faster lua pendants. This is relatively generic. Second, it replaces entire processing steps by an equivalent lua implementation.¹¹⁴ pgfplots 1.12 comes with lua implementations for important and long-running operations. This implementation will be used whenever possible. However, it only covers parts of the feature set: some features of pgfplots are unsupported by the lua backend. In this case, it will be switched off automatically and the TeX implementation will be used as fallback.

The lua backend will be extended in order to gain more performance improvements and in order to cover more features. Please take a look at lua debug if you want to see if lua backend has been (de)activated for your figure.

Note that the lua backend uses a different math engine with a higher accuracy. As a consequence, the appearance of a plot might have insignificant pixel differences compared to the output generated by pdflatex. It is generally recommended to stick with one way to generate a document, i.e. to use either lualatex or pdflatex. Migrating from one to another might change the appearance of your document due to lua backend.

Eventually, pgfplots might add computationally expensive features which can be implemented as part of lua backend and which will be unavailable without it.

Note that lua backend requires a TeX distribution which supports at least lua 5.2 (like TeXLive 2014). It will be deactivated automatically if your version of lualatex is shipped with an older lua interpreter.

Here are some guidelines how to benefit from lua backend:

• • Math expressions which involve macro definitions are unavailable in lua backend. Best practice: prefer declare function over macro constants:

  

  copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ small, title=Do, samples=2, ] \addplot+ [ declare function={C=4;} ] {C*x}; \end{axis} \end{tikzpicture}

  

  copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ small, title=Don't, samples=2, ] \def\constantC{4} \addplot {\constantC*x}; \end{axis} \end{tikzpicture}

  Both are semantically equivalent, but since lua cannot interpret TeX macros, it refuses to process the “Don’t” case. The “Don’t” case results in a log message

  Package pgfplots info on input line 16: Deactivating LUA version of
  plot expression for plot 0 (type 'pgfplothandlerlineto'):
  y expression '\constantC *x' contains a TeX macro.
  

• • Any operation which requires “native” TeX code is unavailable in lua backend. This includes x filter/.code={...} since /.code cannot be mapped to lua. Best practice: prefer x filter/.expression over x filter/.code:

  

  copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[small,grid=major,title=Do] \addplot+ [ unbounded coords=jump, y filter/.expression={y==3 ? nan : y}, ] table { x y 1 2 1.5 2.5 2 3 2.5 3.5 3 4 }; \end{axis} \end{tikzpicture}

• • Plot expression can be processed entirely in lua, all other input coordinate types use TeX to read the value and hand-over to lua.

• • There are a couple of operations for which the lua backend is planned for future releases.

Typically, the lua backend works silently: pgfplots decides if it is active and if it supports the current operation and proceeds accordingly. If both conditions are satisfied, it will transfer control to the lua backend. If one of them is not met, it will automatically fall back to the old TeX implementation. As a consequence, it cannot be sensed right away, only the time to compile pictures will vary.

This key controls how pgfplots handles the case where the lua backend is active, but cannot be used because some encountered feature is unsupported.

The choices false and off deactivate lua debugging. In this case, pgfplots will only write log messages if it used the TeX implementation instead of the lua backend. In addition, it will only write the messages into the .log file (but not into the console output).

The choice off and silent writes neither information messages nor debug messages: it is the same as off but without the log message if the TeX implementation has been used. It is the least verbose choice.

The choice verbose will also write success messages into the .log file (not into the console).

The choice compileerror will abort compilation if the lua backend is active but does not support the current figure or plot.

Note that pgfplots might come with limited expensive operations which are only available in the lua backend. These items will result in compile errors if the lua backend cannot be used for some reason.