Debian Codegraph @

texmf-dist/doc/latex/tkz-elements/TKZdoc-elements-classes-fct.tex

raw
1 %--------------------------------------------------------------------
2 \newpage
3 \section{Class \tkzClass{fct}}
4 \label{sec:class_fct}
5
6 The \tkzClass{fct} class represents a real-valued function
7 \[
8 x \longmapsto f(x)
9 \]
10 defined and evaluated in Lua. A \tkzClass{fct} object encapsulates either
11 (i) a numerical expression (given as a string in the variable \texttt{x}),
12 or (ii) a callable Lua function, together with methods for evaluation,
13 sampling, and geometric construction.
14
15 By convention, function objects are stored in a Lua table named
16 \tkzVar{fct}{F}. Although this name is not mandatory, using \texttt{F} is
17 strongly recommended for consistency across examples and documentation.
18 Each entry of \texttt{F} associates a symbolic name (such as \texttt{fa})
19 with an object of class \tkzClass{fct}. If a custom table name is used, it
20 must be initialized manually. The \tkzFct{tkz-elements}{init\_elements()}
21 function will reset the \texttt{F} table if it has already been defined.
22
23 \paragraph{Mathematical expressions.}
24 All expressions defining a \tkzClass{fct} object are evaluated using standard
25 Lua rules. A \tkzClass{fct} object can be evaluated at a real number, sampled on an
26 interval, converted into a \tkzClass{path} (for drawing with TikZ), or exported
27 to a data file.
28
29 \paragraph{Important.}
30 In function and parametric function definitions
31 (\tkzClass{fct} and \tkzClass{pfct}),
32 expressions must be written using standard mathematical notation.
33 The Lua prefix \texttt{math.} must \emph{not} be used.
34
35 In contrast, in all other methods and Lua code fragments of
36 \tkzNamePack{tkz-elements},
37 standard Lua syntax applies, and the use of the prefix \texttt{math.}
38 is required whenever a Lua mathematical function is called. For convenience, users may define local aliases in their Lua code, such as
39 \code{local sin, cos, pi = math.sin, math.cos, math.pi}.
40
41
42 \medskip
43 Correct:
44 \begin{verbatim}
45 sin(x), exp(-x^2)
46 \end{verbatim}
47
48 Incorrect (in \tkzClass{fct} and \tkzClass{pfct}):
49 \begin{verbatim}
50 math.sin(x), math.exp(-x^2)
51 \end{verbatim}
52
53 \subsection{Methods of the class fct}
54 The \tkzClass{fct} class offers a compact set of methods, centered around:
55 \emph{(i)} creating a function object, \emph{(ii)} evaluating it, and
56 \emph{(iii)} producing a \tkzClass{path} or a data file.
57
58 \vspace{1em}
59
60 \bgroup
61 \catcode`_=12
62 \small
63 \captionof{table}{fct methods.}\label{fct:methods}
64 \begin{tabular}{ll}
65 \toprule
66 \texttt{Methods} & \texttt{Reference} \\
67 \midrule
68 \texttt{Creation} & \\
69 \midrule
70 \tkzFct{fct}{new(expr\_or\_fn)} & [\ref{ssub:method_fct_new}] \\
71 \tkzFct{fct}{compile(expr)} & [\ref{ssub:method_fct_compile}] \\
72 \midrule
73 \texttt{Reals / evaluation} & \\
74 \midrule
75 \tkzMeth{fct}{eval(x)} & [\ref{ssub:method_fct_value}] \\
76 \midrule
77 \texttt{Points / Paths} & \\
78 \midrule
79 \tkzMeth{fct}{set\_scale(x)} & [\ref{ssub:method_fct_set_scale}] \\
80 \tkzMeth{fct}{point(x)} & [\ref{ssub:method_fct_point}] \\
81 \tkzMeth{fct}{path(xmin,xmax,n)} & [\ref{ssub:method_fct_path}] \\
82 \bottomrule
83 \end{tabular}
84 \egroup
85 %-------------------- details ---------------------------------------
86 \subsubsection{Constructor \tkzFct{fct}{new(expr\_or\_fn)}}
87 \label{ssub:method_fct_new}
88
89 \texttt{Description: }Creates a function object from either a Lua expression
90 (string) or a callable Lua function. When a string is provided, it represents
91 an expression in the variable \texttt{x}, evaluated using standard Lua rules
92 (therefore requiring \texttt{math.} prefixes).
93
94 \medskip
95 \texttt{Arguments: }\par
96 \begin{itemize}
97 \item \code{expr\_or\_fn}: either
98 \begin{itemize}
99 \item a string representing an expression in \texttt{x}, or
100 \item a callable Lua function \texttt{f(x)}.
101 \end{itemize}
102 \end{itemize}
103
104 \medskip
105 \texttt{Returns: } a \tkzClass{fct} object.
106
107 \medskip
108 \texttt{Example: }
109 \begin{verbatim}
110 \directlua{
111 init_elements()
112 F.f = fct:new("x*math.exp(-x^2)+1")
113 tex.print(F.f:value(0))
114 }
115 \end{verbatim}
116
117
118
119 \subsubsection{Function \tkzFct{fct}{compile(expr)}}
120 \label{ssub:method_fct_compile}
121
122 \texttt{Description: }Compiles an expression and returns a callable Lua function
123 (or wraps it into a \tkzClass{fct}, depending on the implementation). This is a
124 low-level helper mainly intended for internal use.
125
126 \medskip
127 \texttt{Argument: } \code{expr} (string, expression in variable \texttt{x}). \qquad
128
129 \medskip
130 \texttt{Returns: } a callable function or a \tkzClass{fct} object (depending on implementation).
131
132 \subsubsection{Method \tkzMeth{fct}{eval(x)}}
133 \label{ssub:method_fct_value}
134
135 \texttt{Description: }Evaluates the function at the real number \code{x}.
136
137 \medskip
138 \texttt{Returns: } a number (which may be \texttt{nan} or infinite if the expression is not defined).
139
140 \begin{verbatim}
141 init_elements()
142 F.fa = fct("sin(x) + x")
143 PA.curve = F.fa:path(-2, 5, 200)
144 z.A = F.fa:point(1.3)
145 tex.print(F.fa:eval(math.pi/2))
146 \end{verbatim}
147
148
149 \subsubsection{Method \tkzMeth{fct}{point(x)}}
150 \label{ssub:method_fct_point}
151
152 \texttt{Description: }Constructs the point $(x,f(x))$ associated with the function.
153 This method provides a direct bridge between numerical evaluation and geometric
154 construction.
155
156 \medskip
157 \texttt{Returns: } a \tkzClass{point}.
158
159 \medskip
160 \texttt{Example: }
161 \begin{verbatim}
162 init_elements()
163 F.fa = fct("sin(x)+x")
164 PA.curve = F.fa:path(-2, 5, 200)
165 z.A = F.fa:point(1.5)
166 % or z.A = point(1.3, F.fa:eval(1.3) )
167 \end{verbatim}
168
169 \subsubsection{Method \tkzMeth{fct}{path(xmin,xmax,n)}}
170 \label{ssub:method_fct_path}
171
172 \texttt{Description: }Samples the function on $[xmin,xmax]$ using \code{n}
173 subdivisions and returns a \tkzClass{path}. Invalid values are skipped (depending
174 on the internal policy).
175
176 \medskip
177 \texttt{Returns: } a \tkzClass{path}.
178
179 \medskip
180 \texttt{Example: }
181
182 \begin{tkzexample}[latex=.5\textwidth]
183 \directlua{
184 init_elements()
185 F.fa = fct("sin(x) + x")
186 PA.curve = F.fa:path(-1, 5, 200)
187 z.A = F.fa:point(math.pi/2)
188 }
189 \begin{tikzpicture}[scale=.75,gridded]
190 \tkzInit[xmin=-1,xmax=5,ymin=-1,ymax=2]
191 \tkzDrawX\tkzDrawY
192 \tkzGetNodes
193 \tkzDrawCoordinates[smooth,blue,
194 thick](PA.curve)
195 \tkzDrawPoint[red](A)
196 % \tkzDrawPointsOnGraph[blue]{0,1,2}{fa}
197 % \tkzDrawPointOnGraph[red]{-1}{fa}
198 \end{tikzpicture}
199 \end{tkzexample}
200
201 %
202
203 % ------------------------------------------------------------
204 % fct : set_scale
205 % ------------------------------------------------------------
206
207 \subsubsection{Method \tkzMeth{fct}{set\_scale}}
208 \label{ssub:method_fct_set_scale}
209
210 This method applies an anisotropic scaling to the function graph.
211
212 \medskip
213 \texttt{Syntax: }
214 \begin{quote}
215 F:set\_scale(sx, sy)
216 \end{quote}
217
218 \medskip
219 \texttt{Arguments: }
220 \begin{itemize}
221 \item \texttt{sx}: scaling factor applied to the $x$-coordinate.
222 \item \texttt{sy}: scaling factor applied to the $y$-coordinate.
223 \end{itemize}
224
225 \medskip
226 \texttt{Description: }
227
228 Let $f(x)$ be the original function.
229 After applying \texttt{set\_scale(sx, sy)}, a generated point
230
231 \[
232 (x, f(x))
233 \]
234
235 becomes
236
237 \[
238 (s_x x,\; s_y f(x)).
239 \]
240
241 The scaling affects the geometric output produced by
242 \texttt{point(x)} and \texttt{path(xmin, xmax, n)}.
243
244 The analytic expression of the function remains unchanged.
245
246 \medskip
247 \texttt{Example: }
248
249 \begin{tkzexample}[vbox]
250 \directlua{
251 init_elements()
252 F.f73 = fct("(1./90000)*x*x*x-(1./100)*x*x+(113./36)*x")
253 :set_scale(1/100, 1/400)
254 PA.scaled = F.f73:path(0, 800, 200)
255 z.A = F.f73:point(600)
256 z.Pl, z.Pr = F.f73:tangent(600)
257 }
258 \begin{center}
259 \begin{tikzpicture}[scale=1.75]
260 \tkzGetNodes
261 \tkzInit[xmin=0,xmax=800,xstep=100,
262 ymin=0,ymax=2000,ystep=400]
263 \tkzGrid
264 \tkzAxeXY
265 \tkzDrawCoordinates[smooth,red](PA.scaled)
266 \tkzDrawPoint[red,size=4](A)
267 \tkzDrawLine[blue,add = .5 and .5](Pl,Pr)
268 \end{tikzpicture}
269 \end{center}
270 \end{tkzexample}
271
272
273
274
275 \subsubsection{Method \tkzMeth{fct}{tangent(x0,<h>,<tol>)}}
276 \label{ssub:fct_tangent}
277
278 This method returns two points defining the tangent at abscissa \texttt{x0}.
279 If the curve behaves regularly at \texttt{x0}, a single tangent is returned.
280 If the curve has a corner (left and right slopes significantly different),
281 the method returns the two half-tangent points.
282
283 \medskip
284
285 \texttt{Arguments: }
286 \begin{itemize}
287 \item \texttt{x0}: abscissa where the tangent is evaluated.
288 \item \texttt{h} (optional): finite difference step passed to \texttt{half\_tangents}.
289 \item \texttt{tol} (optional): tolerance used to decide whether left/right slopes
290 define a unique tangent. Default: \texttt{1e-3}.
291 \end{itemize}
292
293 \medskip
294
295 \texttt{Returns: }
296 Two points \texttt{P1}, \texttt{P2} that define a tangent direction.
297 They are constructed at unit distance from the point $P=(x0,f(x0))$.
298
299 \medskip
300
301 \texttt{Behaviour: }
302
303 \begin{itemize}
304 \item If the function is locally smooth at $x_0$
305 (i.e.\ the left and right slopes are sufficiently close),
306 a single tangent direction is computed using a centered derivative.
307 \item If the slopes differ significantly (e.g.\ cusp or angle),
308 the two half-tangents are returned.
309 \end{itemize}
310
311 \medskip
312
313 \texttt{Example: }
314
315 \begin{tkzexample}[vbox]
316 \directlua{
317 init_elements()
318 F.f691 = fct("x*exp(x)")
319 PA.curve = F.f691:path(-5, 1, 200)
320 PA.from = path:new()
321 PA.to = path:new()
322 for x=-4, 1, 0.5 do
323 local Pl, Pr = F.f691:tangent(x)
324 PA.from:add_point(Pl)
325 PA.to:add_point(Pr)
326 end}
327
328 \begin{center}
329 \begin{tikzpicture}[scale=2]
330 \tkzGetNodes
331 \tikzstyle{tan style}=[-]
332 \tkzInit[xmin=-5,xmax=2,ymin=-1,ymax=3]
333 \tkzDrawXY
334 \tkzDrawCoordinates[smooth,red](PA.curve)
335 \tkzText[draw,color = red,
336 fill = orange!20](1.5,1.5){$y = xe^x$}
337 \tkzDrawSegmentsFromPaths[draw,color=blue,
338 line width=.4pt,add=.5 and .5](PA.from,PA.to)
339 \end{tikzpicture}
340 \end{center}
341
342 \end{tkzexample}
343
344
345 % ------------------------------------------------------------
346 % fct : half_tangents
347 % ------------------------------------------------------------
348
349 \subsubsection{Method \tkzMeth{fct}{half\_tangents}}
350 \label{ssub:method_fct_half_tangents}
351
352 This method computes two half-tangent directions at abscissa \texttt{x0}
353 using a finite difference approximation.
354 It is mainly intended to provide two points defining the two possible tangent
355 directions when the curve has a corner or a cusp.
356
357 \texttt{Syntax: }
358 \begin{quote}
359 Pl, Pr, ml, mr = F:half\_tangents(x0, h)
360 \end{quote}
361
362 \texttt{Arguments: }
363 \begin{itemize}
364 \item \texttt{x0}: abscissa where the tangent directions are evaluated.
365 \item \texttt{h} (optional): finite difference step. If omitted, a default value
366 is chosen (relative to \texttt{x0}).
367 \end{itemize}
368
369 \texttt{Returns: }
370 \begin{itemize}
371 \item \texttt{Pl}, \texttt{Pr}: two points on the left and right tangent directions.
372 They are constructed at unit distance from the point $P=(x0,f(x0))$.
373 \item \texttt{ml}, \texttt{mr}: the corresponding left and right slopes.
374 \end{itemize}
375
376 \texttt{Description: }
377
378 Let $P=(x_0,f(x_0))$. The method evaluates
379 $P_+=(x_0+h,f(x_0+h))$ and $P_-=(x_0-h,f(x_0-h))$ and computes the slopes
380
381 \[
382 m_r=\frac{f(x_0+h)-f(x_0)}{(x_0+h)-x_0}, \qquad
383 m_l=\frac{f(x_0)-f(x_0-h)}{x_0-(x_0-h)}.
384 \]
385
386 Then it returns two points on the corresponding directions (left/right),
387 normalized so that $\overline{PPl}=\overline{PPr}=1$.
388
389 \texttt{Example: }
390
391 \begin{tkzexample}[vbox]
392 \directlua{
393 init_elements()
394 F.f67 = fct("(exp(x)-1)/(exp(1)-1)"):set_scale(10, 10)
395 PA.scaled = F.f67:path(0, 1, 200)
396 z.P0l, z.P0r = F.f67:half_tangents(0)
397 z.P1l, z.P1r = F.f67:half_tangents(1)
398 z.P0 = F.f67:point(0)
399 z.P1 = F.f67:point(1)
400 }
401
402 \begin{center}
403 \begin{tikzpicture}[scale=1.20]
404 \tkzGetNodes
405 \tkzInit[xmax=1,ymax=1,xstep=0.1,ystep=0.1]
406 \tkzGrid(0,0)(1,1)
407 \tkzAxeXY
408 \tkzDrawCoordinates[smooth,red,thick](PA.scaled)
409 \tkzText[draw,color = red,fill = orange!20](0.5,0.6)%
410 {$f(x)=\dfrac{\text{e}^x-1}{\text{e}-1}$}
411 \tkzDrawSegments[>=stealth,->,cyan, thick, add = 0 and 4](P0,P0r P1,P1l)
412 \end{tikzpicture}
413 \end{center}
414 \end{tkzexample}[vbox]
415 \endinput