Debian Codegraph @

texmf-dist/doc/metapost/mp-neuralnetwork/mp-neuralnetwork-doc-en.tex

raw
1
2 % LTeX: language=en
3
4 % huffman : draw binary huffman trees with MetaPost/MetaObj
5 %
6 % Originally written by Maxime Chupin <[email protected]>,
7 % 2023.
8 %
9 % Distributed under the terms of the GNU free documentation licence:
10 % http://www.gnu.org/licenses/fdl.html
11 % without any invariant section or cover text.
12
13 \documentclass[english]{ltxdoc}
14
15 \input{mp-neuralnetwork-preamble.tex}
16
17 \usepackage[english]{babel}
18
19 \makeindex[title=Command Index, columns=2]
20
21
22
23 %\lstset{moredelim=*[s][\color{red}\rmfamily\itshape]{<}{>}}
24 %\lstset{moredelim=*[s][\color{blue}\rmfamily\itshape]{<<}{>>}}
25
26 \begin{document}
27
28 \title{{\mpneural} : drawing artificial neural networks with \MP and \MO/}
29 \author{Maxime Chupin, \url{[email protected]}}
30 \date{\today}
31
32 %% === Page de garde ===================================================
33 \thispagestyle{empty}
34 \begin{tikzpicture}[remember picture, overlay]
35 \node[below right, shift={(-4pt,4pt)}] at (current page.north west) {%
36 \includegraphics{fond.pdf}%
37 };
38 \end{tikzpicture}%
39
40 \noindent
41 {\Huge \mpneural}\par\bigskip
42 \noindent
43 {\Large drawing artificial neural networks \\[0.2cm]with \hologo{METAPOST} and \MO/}\\[1cm]
44 \parbox{0.6\textwidth}{
45 \begin{mplibcode}[mpneural]
46 input mp-neuralnetwork;
47
48
49 beginfig(1);
50 framed_output(false);
51 framed_input(false);
52 drawANN("x","n","a","p","b","q","y","m") "circmargin(3pt)";
53 endfig;
54 \end{mplibcode}
55 }\hfill
56 \parbox{0.5\textwidth}{\Large\raggedleft
57 \textbf{Contributor}\\
58 Maxime \textsc{Chupin}\\
59 \url{[email protected]}
60 }
61 \vfill
62 \begin{center}
63 Version 0.1, 2025, January, 27th \\
64 \url{https://gitlab.gutenberg-asso.fr/mchupin/mp-neuralnetwork}
65 \end{center}
66 %% == Page de garde ====================================================
67 \newpage
68
69 %\maketitle
70
71 \begin{abstract}
72 This \hologo{METAPOST} package allows to draw artificial neural networks.
73 It is based on the \MO/ package which
74 provides many tools to draw and arrange nodes.
75 \end{abstract}
76
77
78 \begin{center}
79 \url{https://gitlab.gutenberg-asso.fr/mchupin/mp-neuralnetwork}
80 \end{center}
81
82 \tableofcontents
83
84
85
86 \bigskip
87
88 \begin{tcolorbox}[ arc=0pt,outer arc=0pt,
89 colback=darkred!3,
90 colframe=darkred,
91 breakable,
92 boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
93 3pt, toptitle=3pt,
94 boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
95 0pt, bottomrule at break = 0pt,]
96 \itshape
97 This package is in beta version---do not hesitate to report bugs, as well as requests for improvement.
98 \end{tcolorbox}
99
100 \section{Installation}
101
102 \mpneural is on \ctan{} and can also be installed via the package manager of your
103 distribution.
104
105 \begin{center}
106 \url{https://www.ctan.org/pkg/mp-neuralnetwork}
107 \end{center}
108
109
110 \subsection{With \TeX live under Linux or macOS}
111
112 To install \mpneural with \TeX Live, you will have to create the directory
113 \lstinline+texmf+ in your \lstinline+home+.
114
115 \begin{commandshell}
116 mkdir ~/texmf
117 \end{commandshell}
118
119 Then, you will have to place the \lstinline+neuralnetwork.mp+ and
120 \lstinline+metaobj-patch.mp+\footnote{Thanks to Denis Roegel, this file define a
121 \texttt{Group} object to group different \MO/ objects.
122 } files in
123 \begin{center}
124 \lstinline+~/texmf/metapost/mp-neuralnetwork/+
125 \end{center}
126
127
128 Once this is done, \mpneural will be loaded with the classic \MP{}
129 input code
130 \begin{mpcode}
131 input mp-neuralnetwork
132 \end{mpcode}
133
134 \subsection{With Mik\TeX{} and Windows}
135
136 These two systems are unknown to the author of \mpneural, so we
137 refer you to the Mik\TeX documentation concerning the addition of local packages:
138 \begin{center}
139 \url{http://docs.miktex.org/manual/localadditions.html}
140 \end{center}
141
142
143
144 \subsection{Dependencies}
145
146
147 \mpneural depends:
148 \begin{itemize}
149 \item of course on \MP~\cite{ctan-metapost};
150 \item on the package\package{metaobj}~\cite{ctan-metaobj};
151 \item if \mpneural is not used with
152 \hologo{LuaLaTeX} and the \package{luamplib} package, on the \package{latexmp}
153 package\cite{ctan-latexmp};
154 \item and on the package \package{colorbrewer-rgb}~\cite{ctan-metapost-colorbrewer}.
155 \end{itemize}
156 \section{Main Command}
157
158 The package \mpneural provides one principal command that has two possible
159 invocations.
160
161 \subsection{Finite network}
162
163 \commande|drawANN(«name1»,«size1»,«name2»,«size2», etc.)|\smallskip\index{drawANN@\lstinline+drawANN+}
164
165 Each layer of the network is described by a couple \meta{name} and \meta{size}, where:
166 \begin{description}
167 \item[\meta{name}:] is the names of the layers. It a
168 string, and this is the prefix of each node (for instance \lstinline+"x"+ will
169 produce nodes $x_i$).
170 \item[\meta{size}:] is the size (integer) of the layer (for instance if
171 \meta{size}$=4$, the layer will be composed by nodes $x_1$, $x_2$, $x_3$ and $x_4$).
172 \end{description}
173 Here, a simple example.
174 \begin{ExempleMP}
175 input mp-neuralnetwork
176
177 beginfig(1);
178 drawANN("x",4,"y",5,"z",1);
179 endfig;
180 \end{ExempleMP}
181
182
183 \subsection{Abstract network}
184
185 You can set variables for the size of each layers with the same command using
186 the string notation for the size instead of an integer.
187
188 \commande|drawANN(«name1»,«size1»,«name2»,«size2», etc.)|\smallskip\index{drawANN@\lstinline+drawANN+}
189
190 Each layer of the network is described by a couple \meta{name} and \meta{size}, where:
191 \begin{description}
192 \item[\meta{name}:] is the names of the layers. It a
193 string, and this is the prefix of each node (for instance \lstinline+"x"+ will
194 produce nodes $x_i$).
195 \item[\meta{size}:] is the notation for size (string) of the layer (for instance
196 \lstinline+"p"+, the layer will be composed by nodes $x_1$, $x_2$, $\dots$ and $x_p$).
197 \end{description}
198 Here, a simple example.
199 \begin{ExempleMP}
200 input mp-neuralnetwork
201
202 beginfig(1);
203 drawANN("x","m","y","n","z","p");
204 endfig;
205 \end{ExempleMP}
206
207 The first and the last layers are composed with four nodes, and intern layers
208 with five nodes.
209
210 \section{Options}
211
212 \mpneural allows to customize the network representation. If you want to restore
213 default behaviour, you can use the following command.
214 \commande|mpneural_init_values|\smallskip\index{mpneural_init_values@\lstinline+mpneural_init_values+}
215
216
217 \subsection{Colors}
218
219 We can see, in the previous examples, that the nodes are colored. If you do not
220 want them to be colored, use the following command.
221
222 \commande|colored_layers(«boolean»)|\smallskip\index{colored_layers@\lstinline+colored_layers+}
223
224 \begin{description}
225 \item[\meta{boolean}:] is a \MP{} boolean (true by default) to choose if we
226 want or not colored layers.
227 \end{description}
228
229 If the layers are colored, \mpneural{} uses \lstinline+Spectral+ colors defined
230 in \package{colorbrewer-rgb}\footnote{Up to 11 colors. If there are more layers,
231 the colors cycle.}.
232
233 You can also define colors for each layer using the following command.
234
235
236 \commande|set_layer_colors(«layer number1»,«color1»,«layer number 1»,«color1»,etc.)|\smallskip\index{set_layer_colors@\lstinline+set_layer_colors+}
237
238 \begin{description}
239 \item[\meta{layer number 1}, \meta{color1}:] is a couple with the integer of
240 the layer we want to color with \meta{color1}.
241 \end{description}
242
243 The rest of layers are set to white by default.
244
245 For example:
246 \begin{ExempleMP}
247 input mp-neuralnetwork
248
249 colored_layers(false);
250 beginfig(1);
251 drawANN("x",5,"y",1);
252 endfig;
253 \end{ExempleMP}
254
255 and
256 \begin{ExempleMP}
257 input mp-neuralnetwork
258
259 colored_layers(true);
260 set_layer_colors(1,red,3,(0.7,0.7,0.7));
261
262 beginfig(1);
263 drawANN("x",5,"y",1,"z",4);
264 endfig;
265 \end{ExempleMP}
266
267 Connections are colored. The default color is gray (\lstinline+0.4*white+) but
268 you can modify that with the following command.
269
270 \commande|set_connection_color(«color»)|\smallskip\index{set_connection_color@\lstinline+set_connection_color+}
271
272 \begin{description}
273 \item[\meta{color}:] is the color for drawing the connections between layers
274 (default \lstinline+0.4*white+).
275 \end{description}
276
277
278 \subsection{Annotations}
279
280 \mpneural provides some tools to annotate the network. However, because we use
281 \MO/ behind the scene, you can always use \MO/ tools to draw above the graph
282 build with \mpneural (see section~\ref{sec:mo}).
283
284 \subsubsection{Frames}
285
286 You can add frames around three different blocks: input, output and hidden
287 layers.
288
289 To draw a frame around these three types of layers (or stop the drawing of theses frames), you
290 can use the following commands.
291
292
293 \commande|framed_input(«boolean»)|\smallskip\index{framed_input@\lstinline+framed_input+}
294
295
296 \commande|framed_output(«boolean»)|\smallskip\index{framed_output@\lstinline+framed_output+}
297
298
299 \commande|framed_hidden(«boolean»)|\smallskip\index{framed_hidden@\lstinline+framed_hidden+}
300 \begin{description}
301 \item[\meta{boolean}:] true or false (default).
302 \end{description}
303
304 \subsubsection{Positioning nodes}
305
306 We can adjust the vertical and horizontal distance between nodes with the
307 following commands.
308
309 \commande|set_vspace(«distance»)|\smallskip\index{set_vspace@\lstinline+set_vspace+}
310
311 \begin{description}
312 \item[\meta{distance}:] is a numeric (default \lstinline+1.5cm+).
313 \end{description}
314
315
316 \commande|set_hspace(«distance»)|\smallskip\index{set_hspace@\lstinline+set_hspace+}
317
318 \begin{description}
319 \item[\meta{distance}:] is a numeric (default \lstinline+2.2cm+).
320 \end{description}
321
322 \begin{ExempleMP}
323 input mp-neuralnetwork
324
325 beginfig(1);
326 set_vspace(2cm);
327 set_hspace(3cm);
328 drawANN("x",5,"u",6,"v",3,"y",2);
329 endfig;
330 \end{ExempleMP}
331
332 \subsubsection{Labels and sections}
333
334
335 First, if you do not want to label the nodes, use the following command to
336 deactivate the function.
337
338 \commande|show_node_labels(«boolean»)|\smallskip\index{show_node_labels@\lstinline+show_node_labels+}
339
340 You can also add legends to these part of the network (independently of the
341 frame draw). For that, you can use the following command.
342
343 \commande|print_legends(«boolean»)|\smallskip\index{print_legends@\lstinline+print_legends+}
344 \begin{description}
345 \item[\meta{boolean}:] true or false (default).
346 \end{description}
347
348 The default value for the legends of the three parts (input, output, and
349 hidden), are \lstinline+"Input layer"+, \lstinline+"Output layer"+, and
350 \lstinline+"Hidden layer(s)"+. You can modify these string with the following
351 commands.
352
353
354 \commande|set_input_legend(«string»)|\smallskip\index{set_input_legend@\lstinline+set_input_legend+}
355
356 \commande|set_output_legend(«string»)|\smallskip\index{set_output_legend@\lstinline+set_output_legend+}
357
358 \commande|set_hidden_legend(«string»)|\smallskip\index{set_hidden_legend@\lstinline+set_hidden_legend+}
359
360
361 \begin{description}
362 \item[\meta{string}:] is a string for the legend (default are \lstinline+"Input layer"+, \lstinline+"Output layer"+, and
363 \lstinline+"Hidden layer(s)"+).
364 \end{description}
365
366
367 \begin{ExempleMP}
368 input mp-neuralnetwork
369
370 colored_layers(false);
371 beginfig(1);
372 print_legends(true);
373 set_input_legend("Entrées");
374 set_output_legend("Sortie");
375 framed_hidden(true);
376 drawANN("x",5,"u",6,"v",8,"y",2);
377 endfig;
378 \end{ExempleMP}
379
380 You may also want to print the \emph{weights} on the network. To do that, use
381 the following commands.
382 \commande|print_weights(«boolean»)|\smallskip\index{print_weights@\lstinline+print_weights+}
383
384 By default, weights are denoted by $w$, but you can change that with the
385 following command.
386
387
388 \commande|set_weights_notation(«string»)|\smallskip\index{set_weights_notation@\lstinline+set_weights_notation+}
389 \begin{description}
390 \item[\meta{string}:] is a string for the weights (default is
391 \lstinline+"w"+).
392 This is a prefix: for instance, with the default value, the weights are, in
393 math mode, $w_{ij}^{(k)}$ for the $k$-th layer.
394 \end{description}
395
396
397
398 \begin{ExempleMP}
399 input mp-neuralnetwork
400
401 colored_layers(false);
402 beginfig(1);
403 print_legends(false);
404 print_weights(true);
405 drawANN("x",4,"u",6,"v",5,"y",2);
406 endfig;
407 \end{ExempleMP}
408
409 You can add labels positioning them with relative coordinates that is $(0,0)$ at
410 bottom left of the bounding box of the complete graph and $(1,1)$ at top right.
411 For that, you can use the following command.
412
413 \commande|labelANN(«string»)(«xpart»,«ypart») «\MO/ options»|\smallskip\index{labelANN@\lstinline+labelANN+}
414 \begin{description}
415 \item[\meta{string}:] is a string for the label (process by
416 \lstinline+textext+ command).
417 \item[\meta{xpart},\meta{ypart}:] are numeric in the relative coordinates (but
418 can be lower or greater than 0 and 1.).
419 \end{description}
420
421 This command build a \MO/ box. It is the center of the box that is put at the
422 relative coordinate. Moreover, you can add the \MO/ options at the end to
423 customize the box.
424
425 \begin{ExempleMP}
426 input mp-neuralnetwork
427
428 colored_layers(false);
429 beginfig(1);
430 print_legends(false);
431 print_weights(true);
432 drawANN("x",4,"u",6,"v",5,"y",2);
433 labelANN("My fabulous network")(0.5,-0.2) "filled(true)","fillcolor((0.8,0.5,0.5))";
434 endfig;
435 \end{ExempleMP}
436
437
438
439
440 \section{With MetaObj}\label{sec:mo}
441
442 Because \mpneural is built above \MO/~\cite{ctan-metaobj}, the tools of the
443 incredible package are available.
444
445 The nodes of the network are \MO/ boxes, with names:
446 \begin{itemize}
447 \item with the prefix \texttt{ANN};
448 \item the instance number of the network (useful if you draw
449 multiple networks);
450 \item an underscore \texttt{\_};
451 \item the identifier of the layer (specified in the \lstinline+drawANN+ command);
452 \item the number of the node in the layer.
453 \end{itemize}
454
455 The boxes of weights are named as follows:
456 \begin{itemize}
457 \item with the prefix \texttt{ANN};
458 \item the instance number of the network (useful if you draw
459 multiple networks);
460 \item an underscore \texttt{\_};
461 \item \texttt{weights};
462 \item the number of the left layer.
463 \end{itemize}
464
465 The boxes of label for input, output and hidden layers are named as follows:
466 \begin{itemize}
467 \item with the prefix \texttt{ANN};
468 \item the instance number of the network (useful if you draw
469 multiple networks);
470 \item an underscore \texttt{\_};
471 \item \texttt{input}, \texttt{output} or \texttt{hidden}.
472 \end{itemize}
473
474
475
476
477 Labels generated by \lstinline+labelANN+ are also \MO/ boxes named as follows:
478 \begin{itemize}
479 \item with the prefix \texttt{ANN};
480 \item the instance number of the network (useful if you draw
481 multiple networks);
482 \item an underscore \texttt{\_};
483 \item \texttt{label};
484 \item then the number of the label.
485 \end{itemize}
486
487 For example, if you draw the following network:
488 \begin{mpcode}
489 input mp-neuralnetwork
490
491 beginfig(1);
492 drawANN("x",3,"y",2);
493 endfig;
494 \end{mpcode}
495
496 The nodes will be named \texttt{ANN1\_x1}, \texttt{ANN1\_x2}, \texttt{ANN1\_x3},
497 \texttt{ANN1\_y1}, and \texttt{ANN1\_y2}. The weights will be named
498 \texttt{ANN1\_weights1}.
499
500 Here is a real example (this is the 10th instance of a network drawing in this
501 document). \lstinline+ncline+ is a \MO/ command.
502 \begin{ExempleMP}
503 input mp-neuralnetwork;
504
505 beginfig(1);
506 print_legends(true);
507 show_node_labels(true);
508 drawANN("x","n","a","p","b","q","y","m") "circmargin(3pt)";
509 labelANN("Test")(1.3,0.4);
510 labelANN("Test")(0.5,1.1) "framed(false)";
511 ncline(ANN10_label2)(ANN10_x2)"doubleline(true)","coilwidth(2mm)",
512 "angleA(0)",
513 "linewidth(1pt)";
514 endfig;
515 \end{ExempleMP}
516
517
518 \printbibliography
519 \printindex
520 \end{document}