PGF/TikZ Manual

The TikZ and PGF Packages
Manual for version 3.1.10

Mathematical and Object-Oriented Engines

93 Design Principles

pgf needs to perform many computations while typesetting a picture. For this, pgf relies on a mathematical engine, which can also be used independently of pgf, but which is distributed as part of the pgf package nevertheless. Basically, the engine provides a parsing mechanism similar to the calc package so that expressions like 2*3cm+5cm can be parsed; but the pgf engine is more powerful and can be extended and enhanced.

pgf provides enhanced functionality, which permits the parsing of mathematical operations involving integers and non-integers with or without units. Furthermore, various functions, including trigonometric functions and random number generators can also be parsed (see Section 94.1). The calc macros \setlength and friends have pgf versions which can parse these operations and functions (see Section 94.1). Additionally, each operation and function has an independent pgf command associated with it (see Section 95), and can be accessed outside the parser.

The mathematical engine of pgf is implicitly used whenever you specify a number or dimension in a higher-level macro. For instance, you can write \pgfpoint{2cm+4cm/2}{3cm*sin(30)} or suchlike. However, the mathematical engine can also be used independently of the pgf core, that is, you can also just load it to get access to a mathematical parser.

93.1 Loading the Mathematical Engine

The mathematical engine of pgf is loaded automatically by pgf, but if you wish to use the mathematical engine but you do not need pgf itself, you can load the following package:

  • \usepackage{pgfmath} %

  • \input pgfmath.tex % plain

  • \usemodule[pgfmath] % Cont

  • This command will load the mathematical engine of pgf, but not pgf itself. It defines commands like \pgfmathparse.

93.2 Layers of the Mathematical Engine

Like pgf itself, the mathematical engine is also structured into different layers:

  • 1. The top layer, which you will typically use directly, provides the command \pgfmathparse. This command parses a mathematical expression and evaluates it.

    Additionally, the top layer also defines some additional functions similar to the macros of the calc package for setting dimensions and counters. These macros are just wrappers around the \pgfmathparse macro.

  • 2. The calculation layer provides macros for performing one specific computation like computing a reciprocal or a multiplication. The parser uses these macros for the actual computation.

  • 3. The implementation layer provides the actual implementations of the computations. These can be changed (and possibly be made more efficient) without affecting the higher layers.

93.3 Efficiency and Accuracy of the Mathematical Engine

Currently, the mathematical algorithms are all implemented in . This poses some intriguing programming challenges as is a language for typesetting, rather than for general mathematics, and as with any programming language, there is a trade-off between accuracy and efficiency. If you find the level of accuracy insufficient for your purposes, you will have to replace the algorithms in the implementation layer.

All the fancy mathematical “bells-and-whistles” that the parser provides, come with an additional processing cost, and in some instances, such as simply setting a length to 1cm, with no other operations involved, the additional processing time is undesirable. To overcome this, the following feature is implemented: when no mathematical operations are required, an expression can be preceded by +. This will bypass the parsing process and the assignment will be orders of magnitude faster. This feature only works with the macros for setting registers described in Section 94.1.


\pgfmathsetlength\mydimen{1cm} % parsed : slower.
\pgfmathsetlength\mydimen{+1cm} % not parsed : much faster.