Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-math-algorithms.tex

raw
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}