1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
|
\documentclass{article}
\usepackage[comments,3x,jpg]{mgltex}
\usepackage{hyperref}
\title{\mglTeX*{} usage sample}
\author{Diego Sejas Viscarra \and Alexey Balakin}
\date{\today}
\begin{mglsetupscript}
define gravity 9.81 # [m/s^2]
\end{mglsetupscript}
\begin{document}
\maketitle
\begin{abstract}
\noindent \mglTeX{} is a \LaTeX{} package that allows the creation of graphics directly from MGL scripts of the MathGL library (by Alexey Balakin) inside documents. The MGL code is extracted, executed (if shell escape is activated), and the resulting graphics are automatically included.
This document is intended as a sample of the capabilities of \mglTeX{}, as well as a brief introduction to the package, for those who want to start right away to use it, without diving into the a little bit more technical documentation.
\end{abstract}
\section{Basics on environments}
\begin{description}
\item[mgl] The easiest way to embed MGL code is the \verb|mgl| environment. It extracts its contents to a main script associated to the document.\footnote{Generally, the main script has the same name as the document being compiled. In order to rename it or create a new one, the \texttt{\textbackslash mglname} command can be used.} If shell escape is activated, \LaTeX{} will take care of calling \verb|mglconv| (the MathGL compiler) with the appropriate settings, and the resulting image will be automatically included.
For example, you could write:
\begin{verbatim}
\begin{figure}[!ht]
\centering
\begin{mgl}[width=0.95\textwidth,height=6cm]
call 'prepare1d'
subplot 2 1 0 '<_' : title 'Standard data plot'
box : axis : grid 'xy' ';k'
plot y ’rGb’
subplot 2 1 1 '<_' : title 'Region plot'
ranges -1 1 -1 1 : origin 0 0
new y1 200 'x^3-x' : new y2 200 'x'
axis : grid 'xy' 'W'
region y1 y2 'ry'
plot y1 '2k' : plot y2 '2k'
text -0.75 -0.35 '\i{A}_1' 'k' : text 0.75 0.25 '\i{A}_2' 'k'
\end{mgl}
caption{A simple plot created by \mglTeX's \texttt{mgl} environment}
\end{figure}
\end{verbatim}
This will produce the following image:
\begin{figure}[!ht]
\centering
\begin{mgl}[width=0.95\textwidth,height=5.5cm]
call 'prepare1d'
subplot 2 1 0 '<_' : title 'Standard data plot'
box : axis : grid 'xy' ';k'
plot y '2'
subplot 2 1 1 '<_' : title 'Region plot'
ranges -1 1 -1 1 : origin 0 0
new y1 200 'x^3-x' : new y2 200 'x'
axis 'AKDTVISO' : grid 'xy' ';W'
region y1 y2 'ry'
plot y1 '2k' : plot y2 '2k'
text -0.75 -0.35 '\i{A}_1' 'k' -2 : text 0.75 0.25 '\i{A}_2' 'k' -2
\end{mgl}
\caption{A simple plot create by \mglTeX's \texttt{mgl} environment}
\end{figure}
Two important aspects of \mglTeX{} can be noted from this example: First, the \verb|mgl| environment accepts the same optional argument as the \verb|\includegraphics| command from the \verb|graphicx| package. Actually, it also accepts other optional arguments, called \verb|gray| (to activate/deactivate gray-scale mode), \verb|mglscale| (to set the factor for scaling the image file), \verb|quality| (to set the quality of the image), \verb|variant| (to chose the variant of the arguments of MGL commands in the script), \verb|imgext| (to specify the extension of the resulting graphic file), and \verb|label| (to specify a name to save the image). Most of these options are available to every \mglTeX{} environment or command to create graphics.
The second aspect to be noted about the example is that this script calls a MGL function, \verb|prepare1d|, which hasn't been defined yet. \mglTeX{} provides the \verb|mglfunc| environment for this purpose (see below).
\item[mglfunc] This environment can be used in any part of the \LaTeX{} document; \mglTeX{} takes care of placing the corresponding code at the end of the main script, as has to be done in the MGL language.
For example, the function \verb|prepare1d| that is called in the script above is defined like this
\begin{verbatim}
\begin{mglfunc}{prepare1d}
new y 50 3
modify y '0.7*sin(2*pi*x)+0.5*cos(3*pi*x)+0.2*sin(pi*x)'
modify y 'sin(2*pi*x)' 1
modify y 'cos(2*pi*x)' 2
\end{mglfunc}
\end{verbatim}
\begin{mglfunc}{prepare1d}
new y 50 3
modify y '0.7*sin(2*pi*x)+0.5*cos(3*pi*x)+0.2*sin(pi*x)'
modify y 'sin(2*pi*x)' 1
modify y 'cos(2*pi*x)' 2
\end{mglfunc}
As you can see, only the body of the function has to be written. The number of arguments of the function can be passed to \verb|mglfunc| as optional argument, like in the code \verb|\begin{mglfunc}[3]{func_with_three_args}|.
\item[mgladdon] This environment just adds its contents to the main script, without producing any image. It is useful to load dynamic libraries, define constants, etc.
\item[mglcode] The \verb|mglcode| environment is similar to \verb|mgl|, but it creates its own script, whose name is passed as mandatory argument. The same optional arguments are accepted, except \verb|label| (for obvious reasons).
\begin{verbatim}
\begin{figure}[!ht]
\begin{mglcode}[height=5cm,width=8cm]{vectorial_flow}
new a 20 30 'sin(pi*x)*sin(pi*y)+cos(2*pi*x*y)'
new b 20 30 'cos(pi*x)*cos(pi*y)+cos(2*pi*x*y)'
subplot 1 1 0 '' : title 'Flow of vector field' : box
flow a b 'v'; value 20
\end{mglcode}
\end{figure}
\end{verbatim}
\begin{figure}[!ht]
\centering
\begin{mglcode}[height=5cm,width=8cm]{vectorial_flow}
new a 20 30 'sin(pi*x)*sin(pi*y)+cos(2*pi*x*y)'
new b 20 30 'cos(pi*x)*cos(pi*y)+cos(2*pi*x*y)'
subplot 1 1 0 '' : title 'Flow of a vector field' : box
flow a b '2v'; value 10
\end{mglcode}
\end{figure}
\item[mglscript] This environment just creates a script, whose name is specified as mandatory argument. It is useful, for example, to create MGL scripts which can later be post-processed by another package, like \verb|listings| or \verb|pygments|.
For example, the following won't produce any image, just a script:
\begin{verbatim}
\begin{mglscript}{Gaston_Neiza}
clf 'k'
attachlight on
subplot 1 1 0 '' : title 'Gaston\utf0x0027{}s Surface'
ranges -13 13 -40 40
new a 200 200 '-x+(2*0.84*cosh(0.4*x)*sinh(0.4*x))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+(0.4*sin(sqrt(0.84)*y))))+0.5*sin(pi/2*x)'
new b 200 200 '(2*sqrt(0.84)*cosh(0.45*x)*(-(sqrt(0.84)*sin(y)*cos(sqrt(0.84)*y))+cos(y)*sin(sqrt(0.84)*y)))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+2*(0.4*sin(sqrt(0.84)*x))^2))'
new c 200 200 '(2*sqrt(0.84)*cosh(0.45*x)*(-(sqrt(0.84)*cos(y)*cos(sqrt(0.84)*y))-sin(y)*sin(sqrt(0.84)*y)))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+2*(0.4*sin(sqrt(0.84)*x))^2))'
rotate 60 60
light on : light 0 1 1 0
xrange c : yrange b : zrange a : crange c
surf c b a '#'; meshnum 100
subplot 2 1 1 ''
title 'Neiza\utf0x0027{}s Rose'
ranges -13 13 -40 40
new a 700 700 '-x+(1.5*cos(x^2))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+(0.4*sin(sqrt(0.84)*y))))+0.5*cos(pi/2*x)'
new b 700 700 '(sqrt(0.5)*cos(0.25*x)*((sqrt(0.84)*sin(y)*cos(0.75*y))+cos(y)*sin(sqrt(0.84)*y)))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+2*(0.4*sin(sqrt(0.84)*x))^2))'
new c 700 700 '(sqrt(0.5)*cos(0.25*x)*((sqrt(0.84)*cos(y)*sin(0.75*y))-sin(y)*sin(sqrt(0.84)*y)))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+2*(0.4*sin(sqrt(0.84)*x))^2))'
rotate 75 130
light on : light 0 0 0 1 'w' 0.5 : light 1 -1 0 0 'r' 0.85 : light 2 -1 0 0 'w' 0.75
xrange c : yrange b : zrange a : crange c
surf c b a 'r'
\end{mglscript}
\end{verbatim}
\begin{mglscript}{Gaston_Neiza}
clf 'k'
attachlight on
subplot 2 1 0 ''
ranges -13 13 -40 40
new a 200 200 '-x+(2*0.84*cosh(0.4*x)*sinh(0.4*x))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+(0.4*sin(sqrt(0.84)*y))))+0.5*sin(pi/2*x)'
new b 200 200 '(2*sqrt(0.84)*cosh(0.45*x)*(-(sqrt(0.84)*sin(y)*cos(sqrt(0.84)*y))+cos(y)*sin(sqrt(0.84)*y)))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+2*(0.4*sin(sqrt(0.84)*x))^2))'
new c 200 200 '(2*sqrt(0.84)*cosh(0.45*x)*(-(sqrt(0.84)*cos(y)*cos(sqrt(0.84)*y))-sin(y)*sin(sqrt(0.84)*y)))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+2*(0.4*sin(sqrt(0.84)*x))^2))'
rotate 60 60
light on : light 0 1 1 0
xrange c : yrange b : zrange a : crange c
surf c b a '#'; meshnum 100
title 'Gaston\utf0x0027{}s Surface'
subplot 2 1 1 ''
title 'Neiza\utf0x0027{}s Rose'
ranges -13 13 -40 40
new a 700 700 '-x+(1.5*cos(x^2))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+(0.4*sin(sqrt(0.84)*y))))+0.5*cos(pi/2*x)'
new b 700 700 '(sqrt(0.5)*cos(0.25*x)*((sqrt(0.84)*sin(y)*cos(0.75*y))+cos(y)*sin(sqrt(0.84)*y)))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+2*(0.4*sin(sqrt(0.84)*x))^2))'
new c 700 700 '(sqrt(0.5)*cos(0.25*x)*((sqrt(0.84)*cos(y)*sin(0.75*y))-sin(y)*sin(sqrt(0.84)*y)))/(0.4*((sqrt(0.84)*cosh(0.4*x))^2+2*(0.4*sin(sqrt(0.84)*x))^2))'
rotate 75 130
light on : light 0 0 0 1 'w' 0.5 : light 1 -1 0 0 'r' 0.85 : light 2 -1 0 0 'w' 0.75
xrange c : yrange b : zrange a : crange c
surf c b a 'r'
\end{mglscript}
\item[mglblock] It writes its contents verbatim to a file, specified as mandatory argument, and to the \LaTeX{} document.
For example:
\begin{verbatim}
\begin{mglblock}{fractal}
list A [0,0,0,.16,0,0,.01] [.85,.04,-.04,.85,0,1.6,.85] [.2,-.26,.23,.22,0,1.6,.07] [-.15,.28,.26,.24,0,.44,.07]
ifs2d f A 100000
subplot 2 1 0 '<_' : title 'A fractal fern'
ranges f(0) f(1) : axis
plot f(0) f(1) 'G#o '; size 0.05
subplot 2 1 1 '<_' : title 'Bifurcation plot'
ranges 0 4 0 1 : axis
bifurcation 0.005 'x*y*(1-y)' 'R'
\end{mglblock}
\end{verbatim}
\begin{mglblock}{fractal}
list A [0,0,0,.16,0,0,.01] [.85,.04,-.04,.85,0,1.6,.85] [.2,-.26,.23,.22,0,1.6,.07] [-.15,.28,.26,.24,0,.44,.07]
ifs2d f A 100000
subplot 2 1 0 '<_' : title 'A fractal fern'
ranges f(0) f(1) : axis
plot f(0) f(1) 'G#o '; size 0.05
subplot 2 1 1 '<_' : title 'Bifurcation plot'
ranges 0 4 0 1 : axis
bifurcation 0.005 'x*y*(1-y)' 'R'
\end{mglblock}
As you can see, although this is a verbatim-like environment, very long lines of code are split to fit the paragraph. Each line of code is numbered, this can be disabled with the \verb|lineno| option, like \verb|\begin{mglblock}[lineno=false]{fractal}|.
\item[mglverbatim] This is like \verb|mglblock| environment, but it doesn't produce any script, just typesets the code to the \LaTeX{} document. It accepts the \verb|lineno| option, plus the \verb|label| option, in case you want to associate a name to the code.
\item[mglcomment] This environment is used to embed comments in the document. You can control whether the contents of this environment are displayed or not, using the \verb|comments| and \verb|nocomments| package options, or the \verb|\mglcomments{on}| and \verb|mglcomments{off}| commands.
An example of this would be:
\begin{verbatim}
\begin{mglcomments}
This comment will be shown because we used the "comments" package option for mglTeX
\end{mglcomments}
\end{verbatim}
\begin{mglcomment}
This comment will be shown because we used the "comments" package option for mglTeX
\end{mglcomment}
Once again, long lines are broke down to fit the paragraph.
\end{description}
\section{Basics on commands}
\begin{description}
\item[\textbackslash mglgraphics] This command takes the name of an external MGL script, compiles it, and includes the resulting image. It accespt the same optional arguments as the \verb|mgl| environment, except for \verb|label|, plus a \verb|path| option, which can be used to specify the location of the script. This is useful when you have a script outside of the \LaTeX{} document (sent by a colleague for example), but you don't want to transcript it to your document.
For example, in order to display the image of the script we created with \verb|mglscript| environment, we write:
\begin{verbatim}
\begin{figure}[!ht]
\centering
\mglgraphics[height=9cm,width=18cm]{Gaston_Neiza}
\caption{``Gaston's Surface'' and ``Neiza's Rose'' are named after Diego Sejas' parents}
\end{figure}
\end{verbatim}
\begin{figure}[!ht]
\centering
\mglgraphics[height=8cm,width=14cm]{Gaston_Neiza}
\caption{``Gaston's Surface'' and ``Neiza's Rose'' are named after Diego Sejas' parents}
\end{figure}
We could also could compile the script we created with the \verb|mglblock| environment:
\begin{verbatim}
\begin{figure}[!ht]
\centering
\mglgraphics[height=7cm,width=10cm]{fractal}
\caption{Examples of fractal behavior}
\end{figure}
\end{verbatim}
\begin{figure}[!ht]
\centering
\mglgraphics[height=7cm,width=10cm]{fractal}
\caption{Examples of fractal behavior}
\end{figure}
\item[\textbackslash mglinclude] This is equivalent to the \verb|mglblock| environment, but works for external scripts.
\item[\textbackslash mglplot] This command allows the fast creation of plots. It takes one mandatory argument, which is a block of MGL code to produce the plot. Accepts the same optional arguments as the \verb|mgl| environment, plus an additional one, \verb|setup|, that can be used to specify a block of code to append, defined inside a \verb|mglsetup| environment (see the example below).
The \verb|mglsetup| environment can be used if many plots will have the same settings (background color, etc.). Instead of writing the same code over and over again, it can be introduced in that environment, and used with the \verb|\mglplot| command.
An example of use of the \verb|mglsetup| environment and the \verb|\mglplot| command would be:
\begin{verbatim}
\begin{mglsetup}{3d}
clf 'W'
rotate 50 60
light on
box : axis : grid 'xyz' ';k'
\end{mglsetup}
\begin{figure}[!ht]
\centering
\mglplot[setup=3d,height=5cm,width=8cm]{fsurf 'cos(4*pi*hypot(x,y))*exp(-abs(x+y))'}
\end{figure}
\begin{figure}[!ht]
\centering
\mglplot[setup=3d,height=5cm,width=8cm]{fsurf 'sin(pi*(x+y))'}
\end{figure}
\end{verbatim}
\begin{mglsetup}{3d}
clf 'W'
rotate 50 60
light on : light 0 0 1 0 'w' 0.25
box : axis : grid 'xyz' ';k'
\end{mglsetup}
\begin{figure}[!ht]
\centering
\mglplot[setup=3d,height=5cm,width=8cm]{fsurf 'cos(4*pi*hypot(x,y))*exp(-abs(x+y))'}
\end{figure}
\begin{figure}[!ht]
\centering
\mglplot[setup=3d,height=5cm,width=8cm]{fsurf 'sin(pi*(x+y))'}
\end{figure}
\end{description}
There are more environments and commands defined by \mglTeX{}. The ones presented here are the most basic. More on this topic can be found in the documentation.
\end{document}
|
