| 1 |
% Copyright 2019 by Mark Wibrow |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Customizing the Mathematical Engine} |
| 12 |
\label{pgfmath-reimplement} |
| 13 |
|
| 14 |
Perhaps you have a desire for some function that \pgfname\ does not provide. |
| 15 |
Perhaps you are not happy with the accuracy or efficiency of some of the |
| 16 |
algorithms that are implemented in \pgfname. In these cases you will want to |
| 17 |
add a function to the parser or replace the current implementations of the |
| 18 |
algorithms with your own code. |
| 19 |
|
| 20 |
The mathematical engine was designed with such customization in mind. It is |
| 21 |
possible to add new functions, or modify the code for existing functions. Note, |
| 22 |
however, that whilst adding new operators is possible, it can be a rather |
| 23 |
tricky business and is only recommended for adventurous users. |
| 24 |
|
| 25 |
To add a new function to the math engine the following command can be used: |
| 26 |
|
| 27 |
\begin{command}{\pgfmathdeclarefunction\opt{|*|}\marg{function name}\marg{number of arguments}\marg{code}} |
| 28 |
This will set up the parser to recognize a function called \meta{name}. The |
| 29 |
name of the function can consist of, uppercase or lowercase letters, |
| 30 |
numbers or the underscore |_|. In line with many programming languages, a |
| 31 |
function name cannot begin with a number or contain any spaces. The |
| 32 |
function may not have been declared earlier, unless the optional star (|*|) |
| 33 |
is provided, which forces an ``overwriting'' of the function by the new |
| 34 |
function. Note that you \emph{should never change the arity of standard |
| 35 |
functions} and you should normally use |\pgfmathredeclarefunction|, |
| 36 |
which does not allow you to do anything wrong here. |
| 37 |
|
| 38 |
The \meta{number of arguments} can be any positive integer, zero, or the |
| 39 |
value |...|, which indicates a variable number of arguments. \pgfname{} |
| 40 |
treats constants, such as |pi| and |e|, as functions with zero arguments. |
| 41 |
Functions with more than nine arguments or with a variable number of |
| 42 |
arguments are a ``bit special'' and are discussed below. |
| 43 |
|
| 44 |
The effect of \meta{code} should be to set the macro |\pgfmathresult| to |
| 45 |
the correct value (namely to the result of the computation without units). |
| 46 |
Furthermore, the function should have no other side effects, that is, it |
| 47 |
should not change any global values. As an example, consider the creation |
| 48 |
of a new function |double|, which takes one argument, and returns the value |
| 49 |
of that argument times two. |
| 50 |
% |
| 51 |
\begin{codeexample}[] |
| 52 |
\makeatletter |
| 53 |
\pgfmathdeclarefunction{double}{1}{ |
| 54 |
\begingroup |
| 55 |
\pgf@x=#1pt\relax |
| 56 |
\multiply\pgf@x by2\relax |
| 57 |
\pgfmathreturn\pgf@x |
| 58 |
\endgroup |
| 59 |
} |
| 60 |
\makeatother |
| 61 |
\pgfmathparse{double(44.3)}\pgfmathresult |
| 62 |
\end{codeexample} |
| 63 |
|
| 64 |
The macro |\pgfmathreturn|\meta{tokens} must be |
| 65 |
directly followed by an |\endgroup| and will save the result of the |
| 66 |
computation, by defining |\pgfmathresult| as the expansion of |
| 67 |
\meta{tokens} (without units) outside the group, so \meta{tokens} |
| 68 |
must be something that can be assigned to a dimension register. |
| 69 |
|
| 70 |
Alternatively, the |\pgfmathsmuggle|\meta{macro} can be used. This must |
| 71 |
also be directly followed by an |\endgroup| and will simply ``smuggle'' the |
| 72 |
definition of \meta{macro} outside the \TeX-group. |
| 73 |
|
| 74 |
By performing computations within a \TeX-group, \pgfname{} registers such |
| 75 |
as |\pgf@x|, |\pgf@y| and |\c@pgf@counta|, |\c@pgfcountb|, and so forth, |
| 76 |
can be used at will. |
| 77 |
|
| 78 |
Beyond setting up the parser, this command also defines two macros which |
| 79 |
provide access to the function independently of the parser: |
| 80 |
% |
| 81 |
\begin{itemize} |
| 82 |
\item |\pgfmath|\meta{function name} |
| 83 |
|
| 84 |
This macro will provide a ``public'' interface for the function |
| 85 |
\meta{function name} allowing the function to be called |
| 86 |
independently of the parser. All arguments passed to this macro are |
| 87 |
evaluated using |\pgfmathparse| and then passed on to the following |
| 88 |
macro: |
| 89 |
\item |\pgfmath|\meta{function name}|@| |
| 90 |
|
| 91 |
This macro is the ``private'' implementation of the function's |
| 92 |
algorithm (but note that, for speed, the parser calls this macro |
| 93 |
rather than the ``public'' one). Arguments passed to this macro are |
| 94 |
expected to be numbers without units. It is defined using |
| 95 |
\meta{code}, but need not be self-contained. |
| 96 |
\end{itemize} |
| 97 |
|
| 98 |
For functions that are declared with less than ten arguments, the public |
| 99 |
macro is defined in the same way as normal \TeX{} macros using, for |
| 100 |
example, |\def\pgfmathNoArgs{|\meta{code}|}| for a function with no |
| 101 |
arguments, or |\def\pgfmathThreeArgs#1#2#3{|\meta{code}|}| for a function |
| 102 |
with three arguments. The private macro is defined in the same way, and |
| 103 |
each argument can therefore be accessed in \meta{code} using |#1|, |#2| and |
| 104 |
so on. |
| 105 |
|
| 106 |
For functions with more than nine arguments, or functions with a variable |
| 107 |
number of arguments, these macros are only defined as taking \emph{one} |
| 108 |
argument. The public macro expects its arguments to be comma separated, for |
| 109 |
example, |\pgfmathVariableArgs{1.1,3.5,-1.5,2.6}|. Each argument is parsed |
| 110 |
and passed on to the private macro as follows: |
| 111 |
|\pgfmathVariableArgs@{{1.1}{3.5}{-1.5}{2.6}}|. This means that some |
| 112 |
``extra work'' will be required to access each argument (although it is a |
| 113 |
fairly simple task). |
| 114 |
|
| 115 |
Note that there are two exceptions to this arrangement: the public versions |
| 116 |
of the |min| and |max| functions still take two arguments for compatibility |
| 117 |
with older versions, but each of these arguments can take several comma |
| 118 |
separated values. |
| 119 |
\end{command} |
| 120 |
|
| 121 |
To redefine a function use the following command: |
| 122 |
|
| 123 |
\begin{command}{\pgfmathredeclarefunction\marg{function name}\marg{code}} |
| 124 |
This command redefines the |\pgfmath|\meta{function name}|@| macro with the |
| 125 |
new \meta{code}. See the description of the |
| 126 |
|\pgfmathdeclarefunction| for details. You cannot change the number of |
| 127 |
arguments for an existing function. |
| 128 |
% |
| 129 |
\begin{codeexample}[] |
| 130 |
\makeatletter |
| 131 |
\pgfmathdeclarefunction{foo}{1}{ |
| 132 |
\begingroup |
| 133 |
\pgf@x=#1pt\relax |
| 134 |
\multiply\pgf@x by2\relax |
| 135 |
\pgfmathreturn\pgf@x |
| 136 |
\endgroup |
| 137 |
} |
| 138 |
\pgfmathparse{foo(42)}\pgfmathresult |
| 139 |
\pgfmathredeclarefunction{foo}{ |
| 140 |
\begingroup |
| 141 |
\pgf@x=#1pt\relax |
| 142 |
\multiply\pgf@x by3\relax |
| 143 |
\pgfmathreturn\pgf@x |
| 144 |
\endgroup |
| 145 |
} |
| 146 |
\pgfmathparse{foo(42)}\pgfmathresult |
| 147 |
\makeatother |
| 148 |
\end{codeexample} |
| 149 |
% |
| 150 |
\end{command} |
| 151 |
|
| 152 |
\pgfname{} uses the last known definition of a function within the |
| 153 |
prevailing scope, so it is possible for a function to be redefined locally. |
| 154 |
You should also remember that any |.sty| or |.tex| file containing any |
| 155 |
re-implementations should be loaded after |pgfmath|. |
| 156 |
|
| 157 |
In addition to the above commands, the following key is provided to quickly |
| 158 |
create simple ad hoc functions which can greatly improve the readability of |
| 159 |
code, and is particularly useful in \tikzname{}: |
| 160 |
|
| 161 |
\begin{key}{/pgf/declare function=\meta{function definitions}} |
| 162 |
This key allows simple functions to be created locally. Its use is perhaps |
| 163 |
best illustrated by an example: |
| 164 |
% |
| 165 |
\begin{codeexample}[] |
| 166 |
\begin{tikzpicture} |
| 167 |
\draw [help lines] (0,0) grid (3,2); |
| 168 |
\draw [blue, thick, x=0.0085cm, y=1cm, |
| 169 |
declare function={ |
| 170 |
sines(\t,\a,\b)=1 + 0.5*(sin(\t)+sin(\t*\a)+sin(\t*\b)); |
| 171 |
}] |
| 172 |
plot [domain=0:360, samples=144, smooth] (\x,{sines(\x,3,5)}); |
| 173 |
\end{tikzpicture} |
| 174 |
\end{codeexample} |
| 175 |
|
| 176 |
Each definition in \meta{function definitions} takes the form |
| 177 |
\meta{name}|(|\meta{arguments}|)=|\meta{definition}|;| (note the semicolon |
| 178 |
at the end, this is very important). If multiple functions are being |
| 179 |
defined, the semicolon is used to separate them (\emph{not} a comma). The |
| 180 |
function \meta{name} can be any name that is not already a function name in |
| 181 |
the current scope. The list of \meta{arguments} are commands such as |\x|, |
| 182 |
or |\y| (it is not possible to declare functions that take variable numbers |
| 183 |
of arguments using this key). If the function takes no arguments, then the |
| 184 |
parentheses need not be used. The \meta{definition} should be an expression |
| 185 |
that can be parsed by the mathematical engine and should use the commands |
| 186 |
specified in \meta{arguments}. |
| 187 |
|
| 188 |
When specifying multiple functions, functions that appear later on in |
| 189 |
\meta{function definitions} can refer to earlier functions: |
| 190 |
% |
| 191 |
\begin{codeexample}[pre={\pgfmathsetseed{1}}] |
| 192 |
\begin{tikzpicture}[ |
| 193 |
declare function={ |
| 194 |
excitation(\t,\w) = sin(\t*\w); |
| 195 |
noise = rnd - 0.5; |
| 196 |
source(\t) = excitation(\t,20) + noise; |
| 197 |
filter(\t) = 1 - abs(sin(mod(\t, 90))); |
| 198 |
speech(\t) = 1 + source(\t)*filter(\t); |
| 199 |
} |
| 200 |
] |
| 201 |
\draw [help lines] (0,0) grid (3,2); |
| 202 |
\draw [blue, thick, x=0.0085cm, y=1cm] (0,1) -- |
| 203 |
plot [domain=0:360, samples=144, smooth] (\x,{speech(\x)}); |
| 204 |
\end{tikzpicture} |
| 205 |
\end{codeexample} |
| 206 |
% |
| 207 |
\end{key} |
| 208 |
|
| 209 |
\begin{key}{/pgf/declare function/execute at begin function=\meta{tokens}} |
| 210 |
These \meta{tokens} are inserted just before |\pgfmathdeclarefunction| |
| 211 |
scans the body of the function definition. This is a rather low-level |
| 212 |
option, so you should read the implementation to figure out where the |
| 213 |
\meta{tokens} are inserted. |
| 214 |
\end{key} |
| 215 |
|
| 216 |
\begin{key}{/pgf/declare function/execute at end function=\meta{tokens}} |
| 217 |
These \meta{tokens} are inserted just after |\pgfmathdeclarefunction| has |
| 218 |
finished scanning the body of the function definition. This is a rather |
| 219 |
low-level option, so you should read the implementation to figure out where |
| 220 |
the \meta{tokens} are inserted. |
| 221 |
\end{key} |
| 222 |
|
| 223 |
\begin{key}{/pgf/declare function/ignore spaces=\meta{boolean}} |
| 224 |
Uses the two previously described keys |/pgf/declare function/execute at begin function| and |
| 225 |
|/pgf/declare function/execute at end function| to install catcodes such |
| 226 |
that spaces inside the body of the function definition of |
| 227 |
|\pgfmathdeclarefunction| are ignored. The usual \TeX\ tokenization rules |
| 228 |
apply, so if the body of the function had already been tokenized by other |
| 229 |
means this will become ineffective. If you want to use a space you can use |
| 230 |
|~| in the function body which has its catcode set to 10 (space). |
| 231 |
\end{key} |