Debian Codegraph @

texmf-dist/source/latex/paramcalc/paramcalc.dtx

raw
1 %% \CheckSum{145}
2 % \iffalse
3 % File: paramcalc.dtx
4 % Copyright (C) 2026 Miguel V. S. Frasson ([email protected])
5 %
6 % This package may be distributed under the terms of the LaTeX
7 % Project Public License, as described in lppl.txt in the base
8 % LaTeX distribution, either version 1.3 or (at your option)
9 % any later version.
10 %
11 %<*driver>
12 \documentclass{ltxdoc}
13 \usepackage[T1]{fontenc}
14 \usepackage[lining]{ebgaramond}
15 \usepackage{ebgaramond-maths,textcomp}
16 \usepackage[cmintegrals,cmbraces]{newtxmath}
17 \let\epsilon\varepsilon
18 \usepackage{xcolor,microtype,amsmath,amstext,tikz,centerlastline}
19 \usepackage{paramcalc}
20 % \usepackage[margin=1in]{geometry}
21 \newcommand{\var}[1]{\texttt{\expandafter\string\csname #1\endcsname}}
22 \RecordChanges
23 \begin{document}
24 \DocInput{paramcalc.dtx}
25 \end{document}
26 %</driver>
27 % \fi
28 %
29 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
30 %
31 % \StopEventually
32 %
33 % \changes{1.0}{2026/01/27}{Initial version}
34 %
35 % \title{\textsc{paramcalc}: compute parameters to fit condition}
36 % \author{Miguel V.\ S.\ Frasson\\(\texttt{[email protected]})}
37 % \date{2026, jan. 27}
38 %
39 % \maketitle
40 %
41 % \begin{abstract}\centerlastline\noindent
42 % Sometimes one wants to get font size or letter spacing so that
43 % text fits a desired length, or some unit length so that a picture
44 % fits some desired size, for instance. This package implements
45 % macros to compute such parameters to fit a condition.
46 % \end{abstract}
47 %
48 % \section{The purpose of this package}
49
50 % Suppose that one wants to create a nice logo with two lines of same
51 % size, first line “AWESOME” and second line “example of use for
52 % \texttt{paramcalc}”. We look for font size of first line, so that
53 % the lines have the same width. This is the desired result:
54 %
55 % \newlength{\lineIwd}
56 % \newlength{\lineIIwd}
57 % \newcommand{\mytext}{\Large example of use for paramcalc}
58 % \settowidth{\lineIIwd}{\mytext}
59 %
60 % \paramcalc{12}{50}{\lineIIwd}[\lineIwd]{
61 % \settowidth{\lineIwd}{\fontsize{\x}{\x}\selectfont \textls*{AWESOME}}
62 % }
63 %
64 % \begin{center}
65 % {\fontsize{\x}{\x}\selectfont \textls*{AWESOME}\par}
66 % \mytext \vspace*{\bigskipamount}
67 % \end{center}
68 %
69 % Instead of setting font size by hand\footnote{As width is
70 % proportional to font size, one could also compute font size by
71 % proportion, measuring texts of both lines.} and visually trying to get the
72 % desired condition, we want to compute such font size for line 1.
73 %
74 % This can be acomplished with \texttt{paramcalc} with the following
75 % code (make sure you use scalable fonts\footnote{Computer Modern are
76 % not scalable, but Latin Modern (package \texttt{lmodern}), EB
77 % Garamond (package \texttt{ebgaramond}) and many others are.}):
78 %
79 % \enlargethispage{\baselineskip}
80 % \begin{verbatim}
81 %\newcommand{\mytext}{\Large example of use for paramcalc}
82 %\newlength{\lineIIwd}
83 %\settowidth{\lineIIwd}{\mytext}
84 %
85 %\newlength{\lineIwd}
86 %\paramcalc{12}{50}{\lineIIwd}[\lineIwd]{
87 % % compute \lineIwd as function of fontsize \x
88 % \settowidth{\lineIwd}{\fontsize{\x}{\x}\selectfont \textls*{AWESOME}}
89 %}
90 %
91 %Showing the result.
92 %\begin{center}
93 % {\fontsize{\x}{\x}\selectfont \textls*{AWESOME}\par}
94 % \mytext
95 %\end{center}
96 %\end{verbatim}
97 %
98 % It you use \texttt{\string\x} in the document, you get the computed
99 % value \x.
100 %
101 % \section{Usage}
102 %
103 % To compute a desired parameter, the situation can be reduced to find
104 % a zero of a real function. In the example above, we wanted that the
105 % length $y(x)$ of first line as function of its font size $x$ should
106 % match the length $y_0$ of second line, so that we need to find the
107 % zero of the function $f(x) = y(x) - y_0$.
108 %
109 % The computation is done by \texttt{\string\paramcalc} macro.\medskip
110 %
111 % \DescribeMacro{\paramcalc}^^A
112 % \newcommand{\varp}[1]{\textlangle\makebox{\textit{#1}}\textrangle}^^A
113 % \newcommand{\varm}[1]{\texttt{\{}\varp{#1}\texttt{\}}}^^A
114 % \newcommand{\varopt}[1]{\texttt{[}\varp{#1}\texttt{]}}
115 % \noindent\texttt{\string \paramcalc}\varopt{x macro}^^A
116 % \varm{x initial}\varm{x final}\varopt{$\epsilon$}^^A
117 % \varm{y desired}\varopt{y macro}\varm{body}\medskip
118 %
119 % The optional \varp{x macro} defaults to \texttt{\string\x}, the
120 % optional \varp{y macro} defaults to \texttt{\string\y} and both
121 % should be control sequences. \varp{y macro} and \varp{y desited}
122 % could be lengths, converted to numbers as pt.
123 %
124 % \varp{body} should be code that computes \varp{y macro} for an
125 % arbitrary value of \varp{x macro}, supposed to expand to a decimal
126 % value. The result is stored in \varp{x macro} after its
127 % computation. If its value is in between \varp{x initial} and
128 % \varp{x final}, convergence is ensured. Often\footnote{I could not
129 % figure out any real life example where the function was not affine.}
130 % the functions involved are affine (for instance, a width is
131 % proportional a font size), and in this case convergence is achieved
132 % after just one step.
133 %
134 % The convergence is achieved when
135 % $\vert \text{\varp{y macro}} - \text{\varp{y desired}}\vert <
136 % \epsilon$.
137 % The value of $\epsilon$, where $\epsilon$ is given in optional arg
138 % \varp{epsilon} and defaults to 0.05. If it doesn't happen after a
139 % maximum number of steps, an error is signaled. Then, probably de
140 % desired $x$ is outside initial interval.
141 %
142 % There are situations where only integer values of $x$ are suitable,
143 % like in the optional parameter \textit{n} for
144 % \texttt{\string\textls}\varopt{n}\varm{text}. In such cases, use
145 % \texttt{\string\intparamcalc}, with same arguments. The only
146 % difference is that \varp{x macro} only assume integer values, but
147 % \varp{y macro} still are supposed to assume real values.\medskip
148 %
149 % \DescribeMacro{\intparamcalc}^^A
150 % \noindent\texttt{\string \intparamcalc}\varopt{x macro}^^A
151 % \varm{x initial}\varm{x final}\varopt{$\epsilon$}^^A
152 % \varm{y desired}\varopt{y macro}\varm{body}\medskip
153 %
154 % \textit{Attention}: The numerical method implemented in this package
155 % is not suitable when $y$ assumes (too) discrete values or isn't a
156 % continuous function of $x$ (it its where real-valued) like when $y$
157 % counts lines, for instance.
158 %
159 % \subsection{Package options}
160 %
161 % \begin{itemize}
162 % \item \texttt{maxsteps} = \varp{n} : sets maximum number of steps
163 % before giving up. Defaults to 20.
164 % \item \texttt{epsilon} = \varp{epsilon} : sets the convegence
165 % criterium $\epsilon$ to \varp{epsilon}. Defaults to 0.05.
166 % \end{itemize}
167 %
168 % \section{Examples}
169 %
170 % Creating a logo for the book “História Geral do Brasil”, in three
171 % lines.
172 % \begin{itemize}
173 % \item The first two lines in font size 20pt of size;
174 % \item For the first line we compute letter spacing to fit size of 2nd line;
175 % \item For the third line, we compute font size, keeping same size.
176 % \end{itemize}
177 %
178 %\begin{center}
179 % \fontsize{20}{22}\bfseries
180 %
181 % \newlength{\lIIwd} \newlength{\auxwd}
182 % \settowidth{\lIIwd}{\textls*{GERAL \,DO}}
183 %
184 % \intparamcalc[\lIls]{0}{200}{\lIIwd}[\auxwd]{
185 % \settowidth{\auxwd}{\textls*[\lIls]{HISTÓRIA}}}
186 %
187 % \paramcalc[\lIIIfs]{20}{50}{\lIIwd}[\auxwd]{
188 % \settowidth{\auxwd}{\fontsize{\lIIIfs}{\lIIIfs}\selectfont \textls*{BRASIL}}}
189 %
190 % \textls*[\lIls]{HISTÓRIA} \\ \textls*{GERAL \,DO} \\
191 % \fontsize{\lIIIfs}{\lIIIfs}\selectfont \textls*{BRASIL}
192 % \end{center}
193 %
194 % This is achieved with the code:
195 % \begin{verbatim}
196 %\begin{center}
197 % \fontsize{20}{22}\bfseries
198 %
199 % % base length \lIIwd: line 2 with \textls* and \bfseries
200 % \newlength{\lIIwd} \newlength{\auxwd}
201 % \settowidth{\lIIwd}{\textls*{GERAL \,DO}}
202 %
203 % % compute letter spacing \lIls for 1st line: body compute \auxwd
204 % \intparamcalc[\lIls]{0}{200}{\lIIwd}[\auxwd]{
205 % \settowidth{\auxwd}{\textls*[\lIls]{HISTÓRIA}}}
206 %
207 % % compute font size \lIIIfs for 3rd line: body compute \auxwd
208 % \paramcalc[\lIIIfs]{20}{50}{\lIIwd}[\auxwd]{
209 % \settowidth{\auxwd}{\fontsize{\lIIIfs}{\lIIIfs}\selectfont \textls*{BRASIL}}}
210 %
211 % % typesetting the logo
212 % \textls*[\lIls]{HISTÓRIA} \\ \textls*{GERAL \,DO} \\
213 % \fontsize{\lIIIfs}{\lIIIfs}\selectfont \textls*{BRASIL}
214 %\end{center}
215 % \end{verbatim}
216 %
217 % \section{Numerical method implemented}
218 %
219 % To ensure convergense (with a root in $[a,b]$), we implement Illinois
220 % algorithm\footnote{Dowell, M., Jarratt, P. A modified regula falsi
221 % method for computing the root of an equation. \textit{BIT Numerical
222 % mathematics} \textbf{11}, 168–174
223 % (1971). \url{https://doi.org/10.1007/BF01934364}}, an improvement
224 % over False Position method (\textit{regula falsi}):
225 %
226 % Assuming that $f:I\to \mathbb{R}$ is a continuous function,
227 % end-points $a, b \in I$, $f(a)\cdot f(b) < 0$, so $f$ has a root in $[a,b]$.
228 %
229 % Let $c$ be the root of the secant line that connects $(a,f(a))$ and
230 % $(b,f(b))$.
231 %
232 % \begin{center}
233 % \begin{tikzpicture}
234 % \draw[->] (-0.5,0) -- (2.5,0); \draw[->] (0,-1.5) -- (0,1.5);
235 % \draw[thick] (0.5,-1) coordinate (a)
236 % (a|-0,0) node[above] {$a$}
237 % (1.8,1.5) coordinate (b)
238 % (b|-0,0) node[below right] {$b$}
239 % (a) -- (b)
240 % (1.02,0) coordinate (x) node[below right] {$c$};
241 % \draw[dashed] (a|-0,0) -- (a) -- (a-|b) -- (b);
242 % \fill (a) circle[radius=1pt] (b)
243 % circle[radius=1pt] (x) circle[radius=1pt];
244 % \end{tikzpicture}
245 % \end{center}
246 % so, by similarity of triangles,
247 % \begin{equation}\label{eq:c}
248 % \Delta = \frac{b-a}{f(b)-f(a)} = \frac{b-c}{f(b)} \implies
249 % c = b - f(b)\Delta.
250 % \end{equation}
251 %
252 % The Illinois algorithm for False Position puts the following iteraction:
253 % \begin{align}
254 % (a,f(a)) & =
255 % \begin{cases}
256 % \bigl(c,f(c)\bigr), & \text{if } f(b)f(c)< 0,\\
257 % \bigl(a,\frac{f(a)}{2}\bigr), & \text{otherwise}
258 % \end{cases}\label{eq:iter1} \\
259 % (b,f(b)) & = (c,f(c)) \label{eq:iter2}
260 % \end{align}
261 %
262 % \section{Code}
263 %
264 % Identidication of the package.
265 % \begin{macrocode}
266 \NeedsTeXFormat{LaTeX2e}
267 \ProvidesPackage{paramcalc}[2026/01/27 v1.0 compute params to fit conditions]
268 % \end{macrocode}
269 %
270 % We use \LaTeX3 codebase.
271 % \begin{macrocode}
272 \ExplSyntaxOn
273 % \end{macrocode}
274 %
275 % There are two versions of the solving macros: real roots are
276 % admitted or only integer roots (like parameters for
277 % \texttt{\string\textls[\string\x]\{\textit{text}\}}). We do a
278 % single implementation and the cases are regulated by a boolen.
279 % \begin{macrocode}
280 \bool_new:N \g_PARC_int_bool
281 % \end{macrocode}
282 %
283 % The iteraction will end when $|f(c)|<\epsilon$.
284 %
285 % Floating point variables for $a$, $b$, $f(a)$, $f(b)$, $c$, $f(c)$
286 % and $\Delta$:
287 % \begin{macrocode}
288 \fp_new:N \l_PARC_a_fp
289 \fp_new:N \l_PARC_b_fp
290 \fp_new:N \l_PARC_fa_fp
291 \fp_new:N \l_PARC_fb_fp
292 \fp_new:N \l_PARC_x_fp
293 \fp_new:N \l_PARC_fx_fp
294 \fp_new:N \l_PARC_delta_fp
295 % \end{macrocode}
296 % Also, a counter for steps taken, in case of divergence.
297 % \begin{macrocode}
298 \int_new:N \l_PARC_steps_int
299 % \end{macrocode}
300 %
301 % Defining package option for maximum number of steps.
302 % \begin{macrocode}
303 \int_new:N \l_PARC_maxsteps_int
304 \int_set:Nn \l_PARC_maxsteps_int { 20 }
305 \keys_define:nn {paramcalc} { maxsteps .int_set:N = \l_PARC_maxsteps_int }
306 % \end{macrocode}
307 %
308 % Defining package option for default epsilon (stop criterium).
309 % \begin{macrocode}
310 \fp_new:N \l_PARC_epsilon_fp
311 \fp_set:Nn \l_PARC_epsilon_fp { 0.05 }
312 \keys_define:nn {paramcalc} { epsilon .fp_set:N = \l_PARC_epsilon_fp }
313 % \end{macrocode}
314 %
315 % Passing options to package.
316 % \begin{macrocode}
317 \DeclareOption*{ \keys_set:ne { paramcalc } { \CurrentOption } }
318 \ProcessOptions
319 % \end{macrocode}
320 %
321 % \DescribeMacro{\PARC\_paramcalc:NnnnnNn}
322 % The arguments of $\mathtt{\string\PARC\_paramcalc:NnnnnNn}$
323 % are\\
324 % \texttt{\#1} = macro that holds value for $x$ (default to
325 % \texttt{\string\x} later on)\\
326 % \texttt{\#2} = $a$\\
327 % \texttt{\#3} = $b$\\
328 % \texttt{\#4} = $\epsilon$\\
329 % \texttt{\#5} = $y_0$\\
330 % \texttt{\#6} = macro that stores computed $y(x)$ (default to
331 % \texttt{\string\y} later on)\\
332 % \texttt{\#7} = body of code that computes $y(x)$ and stores value in
333 % \texttt{\#6}.
334 % \begin{macrocode}
335 \cs_new:Nn \PARC_paramcalc:NnnnnNn
336 {
337 % \end{macrocode}
338 % Store $a$ from \texttt{\#2} in \var{l_PARC_a_fp} and set
339 % \texttt{\#1} as the decimal representation of $a$, taking care if
340 % integer values must be used.
341 % \begin{macrocode}
342 \fp_set:Nn \l_PARC_a_fp { #2 }
343 \bool_if:NTF \g_PARC_int_bool
344 { \tl_set:Ne #1 { \fp_to_int:n { #2 } } }
345 { \tl_set:Ne #1 { \fp_to_decimal:n { #2 } } }
346 % \end{macrocode}
347 % Call body to get $y(x)$ in \texttt{\#6}
348 % \begin{macrocode}
349 #7
350 % \end{macrocode}
351 % Save $f(x) = y(x) - y_0$ in \var{l_PARC_fa_fp}
352 % \begin{macrocode}
353 \fp_set:Nn \l_PARC_fa_fp { #6 - (#5) }
354 % \end{macrocode}
355 %
356 % Do as before, now for $b$ stored in \texttt{\#3}:
357 % \begin{macrocode}
358 \fp_set:Nn \l_PARC_b_fp { #3 }
359 \bool_if:NTF \g_PARC_int_bool
360 { \tl_set:Ne #1 { \fp_to_int:n { #3 } } }
361 { \tl_set:Ne #1 { \fp_to_decimal:n { #3 } } }
362 #7
363 \fp_set:Nn \l_PARC_fb_fp { #6 - (#5) }
364 % \end{macrocode}
365 %
366 % In many situations, the function $f(x)$ is affine and the secant
367 % method converges after the first iteration, so it really doesn't
368 % matter if $f(a)f(b)<0$, so we trigger just a warning if signs of
369 % $f(a)$ and $f(b)$ are the same.
370 % \begin{macrocode}
371 \fp_compare:nNnT { (\l_PARC_fa_fp) * (\l_PARC_fb_fp) } > { 0 }
372 {
373 \msg_warning:nn {paramcalc}
374 {
375 The ~values ~of ~\string#6 ~are
376 ~{\fp_to_decimal:N \l_PARC_fa_fp} ~and
377 ~{\fp_to_decimal:N \l_PARC_fa_fp}, ~both
378 \fp_compare:nNnTF { \l_PARC_fa_fp } > 0 { ~above } { ~below }
379 ~{\fp_to_decimal:n {#5}} ~so ~convergence ~is ~not ~ensured.\\
380 Try ~to ~set ~initial ~values ~that ~surround ~the ~root.
381 }
382 }
383 % \end{macrocode}
384 % \bigskip
385 %
386 % Now the loop. Last iteraction is supposed to be stored in
387 % \var{l_PARC_fb_fp}. Stop condition is $|f(b)|< \epsilon$, with
388 % $\epsilon$ stored in \texttt{\#4}.
389 % \begin{macrocode}
390 \fp_while_do:nNnn { abs(\l_PARC_fb_fp) } > { #4 }
391 {
392 % \end{macrocode}
393 % Computing $\Delta$ and $c$ as in \eqref{eq:c}.
394 % \begin{macrocode}
395 \fp_set:Nn \l_PARC_delta_fp
396 { (\l_PARC_b_fp - \l_PARC_a_fp) / (\l_PARC_fb_fp - \l_PARC_fa_fp) }
397 \fp_set:Nn \l_PARC_c_fp
398 { \l_PARC_b_fp - (\l_PARC_fb_fp) * (\l_PARC_delta_fp) }
399 % \end{macrocode}
400 % Compute $f(c)$ and store it in \var{l_PARC_fc_fp}.
401 % \begin{macrocode}
402 \bool_if:NTF \g_PARC_int_bool
403 { \tl_set:Ne #1 { \fp_to_int:N \l_PARC_c_fp } }
404 { \tl_set:Ne #1 { \fp_to_decimal:N \l_PARC_c_fp } }
405 #7
406 \fp_set:Nn \l_PARC_fc_fp { #6 - (#5) }
407 % \end{macrocode}
408 % Now implement Illinois iteraction from \eqref{eq:iter1}
409 % \begin{macrocode}
410 \fp_compare:nNnTF { (\l_PARC_fc_fp) * (\l_PARC_fc_fp) } < { 0 }
411 {
412 \fp_set:Nn \l_PARC_a_fp { \l_PARC_b_fp }
413 \fp_set:Nn \l_PARC_fa_fp { \l_PARC_fb_fp }
414 }
415 {
416 \fp_set:Nn \l_PARC_fa_fp { 0.5 * (\l_PARC_fa_fp) }
417 }
418 % \end{macrocode}
419 % and \eqref{eq:iter2}.
420 % \begin{macrocode}
421 \fp_set:Nn \l_PARC_b_fp { \l_PARC_c_fp }
422 \fp_set:Nn \l_PARC_fb_fp { \l_PARC_fc_fp }
423 }
424 % \end{macrocode}
425 %
426 % Handling possible divergence if $f(a)f(b)>0$. If it doesn't converge
427 % after \texttt{\string\l\_PARC\_maxsteps\_int} steps, an error is
428 % signaled.
429 % \begin{macrocode}
430 \int_incr:N \l_PARC_steps_int
431 \int_compare:nNnT { \l_PARC_steps_int } > { \l_PARC_maxsteps_int }
432 {
433 \msg_error:nn {paramcalc}
434 {
435 Failed ~to ~converge ~after ~\int_use:N \l_PARC_steps_int ~steps.\\
436 Try ~to ~narrow ~initial ~values ~around ~the ~zero.
437 }
438 }
439 }
440 % \end{macrocode}
441 % Recall that the user access the computed value from \texttt{\#1}.
442 %
443 % Now we define user functions that set \var{g_PARC_int_bool} and
444 % call previous function.
445 %
446 % Define \texttt{\string\paramcalc}.
447 % \begin{macrocode}
448 \NewDocumentCommand{\paramcalc}{ O{\x} m m O{0.05} m O{\y} m}
449 {
450 \bool_set:Nn \g_PARC_int_bool { \c_false_bool }
451 \PARC_paramcalc:NnnnnNn #1 { #2 } { #3 } { #4 } { #5 } #6 { #7 }
452 }
453 %
454 % Define \texttt{\string\intparamcalc}.
455 % \begin{macrocode}
456 \NewDocumentCommand{\intparamcalc}{ O{\x} m m O{0.05} m O{\y} m}
457 {
458 \bool_set:Nn \g_PARC_int_bool { \c_true_bool }
459 \PARC_paramcalc:NnnnnNn #1 { #2 } { #3 } { #4 } { #5 } #6 { #7 }
460 }
461 % \end{macrocode}
462 %
463 % Finish \LaTeX3 syntax.
464 % \begin{macrocode}
465 \ExplSyntaxOff
466 % \end{macrocode}
467 %
468 % \Finale
469 %
470 \endinput
471 %
472 %% \CharacterTable
473 %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
474 %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
475 %% Digits \0\1\2\3\4\5\6\7\8\9
476 %% Exclamation \! Double quote \" Hash (number) \#
477 %% Dollar \$ Percent \% Ampersand \&
478 %% Acute accent \' Left paren \( Right paren \)
479 %% Asterisk \* Plus \+ Comma \,
480 %% Minus \- Point \. Solidus \/
481 %% Colon \: Semicolon \; Less than \<
482 %% Equals \= Greater than \> Question mark \?
483 %% Commercial at \@ Left bracket \[ Backslash \\
484 %% Right bracket \] Circumflex \^ Underscore \_
485 %% Grave accent \` Left brace \{ Vertical bar \|
486 %% Right brace \} Tilde \~}