* org-contrib/babel/languages/ob-doc-mathomatic.org: Added a logo.
[worg.git] / org-contrib / babel / languages / ob-doc-mathomatic.org
1 #+TITLE:Org-babel-mathomatic
2 #+AUTHOR: Luis Anaya
3 #+EMAIL:  papoanaya[at]hotmail[dot]com
4 #+LINK_UP:    ../languages.html
5 #+LINK_HOME:  http://orgmode.org/worg/
6 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
7 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
8 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
9 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
10 #+LANGUAGE:   en
11 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
12
13 #+begin_html
14   <div id="subtitle" style="float: center; text-align: center;">
15   <p>
16   Org-babel support for
17   <a href="http://www.mathomatic.org/">Mathomatic</a>
18   </p>
19   <p>
20   <a href="http://www.mathomatic.org/">
21   <img src="http://www.mathomatic.org/math/png/mathomatic192x195.png"/>
22   </a>
23   </p>
24   </div>
25 #+end_html
26 * Introduction
27 =org-babel-mathomatic= allows Mathomatic statements to be executed directly
28 within embedded code blocks in Org-mode documents. These code blocks and
29 its results can be included as the document is exported to documentation
30 formats. 
31
32 The following provides instructions and some examples of Mathomatic
33 usage. Since babel is simply allowing native code to run inside of
34 Org-mode, all Mathomatic documentation is applicable and valid.
35 * Requirements and Setup
36 Mathomatic is a small Computer Algebra System (CAS) written in C. The
37 program is quite portable and useful, and quite suitable for small
38 systems. 
39
40 To get Mathomatic up and running, you need the =mathomatic= program
41 installed in your system. You can obtain and compile =mathomatic= from [[
42 www.mathomatic.org]]
43
44 To enable support for Mathomatic, it must be enabled as part of your
45 initialization script. For example: 
46
47 #+begin_example
48 ;; set up babel support
49 (require 'org-install)
50 (require 'ob-mathomatic)
51 ;; add additional languages with (require 'ob-language)
52 #+end_example
53
54 Babel block headers are used to pass various arguments to control the
55 results of the executed code. The complete list of header arguments
56 is covered in the Org-mode manual; for now, some options frequently used for
57 tclsh are:
58 - =:exports {code, results, both, none}=
59   - When the code is run and the document exported (e.g. to HTML or
60     \LaTeX PDF), what should appear? Just the code block itself? Only
61     the produced output (in this case a plot of some sort)? Both the
62     code and the accompanying results? Or nothing?
63 - =:results {value, output}=
64   - Controls the results of the output. Only two alternatives are
65     allowed: 
66   - /value/ :: Returns the value of the last =return= statement in the
67                code. and places in =#+RESULTS:=. 
68   - /output/ :: Returns the value of the =puts= or =write= statement and
69                 places those in =#+RESULTS:=. 
70 - =:file foo.{png,eps,etc.}=
71   - Mathomatic uses gnuplot as its plotting engine. Using the =:file=
72     option specifies where the resulting output should be put. If
73     no option is given, a Gnuplot window will open with the
74     resultant plot. 
75     *NOTE:* Certain plot options may /not/ output
76     properly to Gnuplot directly and thus /must/ have the =:file
77     filename= option in the header. If the error "Code block produced
78     no output" recurs, try outputting to a file. 
79
80 * Overview
81 Mathomatic is a comprehensive CAS that includes many options and
82 features. 
83 Describing these are beyond the scope of this
84 manual. However, the examples provided in this guide should 
85 be easy enough to follow to
86 those that have used similar programs in the past. 
87 interested in learning about Mathomatic, please refer to the official documents
88 or books on the subject. [fn:1]
89
90 Through this overview, Any of the commands
91 typed in =code= font below should be assumed to reside in a babel
92 code block (between =#+begin_src mathomatic= and =#+end_src=).
93
94 To run a Mathomatic block  and produce a result from the babel block
95 move the cursor anywhere in the code
96 block and press =C-c C-c= (Ctrl+C followed by Ctrl+C) and type "yes"
97 in the minibuffer when asked about executing the code.
98
99 ** Basic Use
100 An example of a Mathomatic  block in Org-babel is as follows:
101
102 #+begin_example
103 #+begin_src mathomatic :results output
104 x + 2
105 eliminate x
106 #+end_src
107
108 #+RESULTS: mathotest
109 : #1: x = 0
110 : #2: x + 2
111 : Eliminating variable x using solved equation #1...
112 : #2: 2
113 #+end_example 
114
115 Using =:results output= describes all the steps executed in the
116 code. using =:results value= will write the results in a table. For
117 example:
118
119 #+begin_example
120 #+begin_src mathomatic :results value
121 x = 0
122 x + 2
123 eliminate x
124 ans = x
125 #+end_src
126
127 #+RESULTS:
128 | #1:         | x        | = |     0 |        |          |       |
129 | #2:         | x        | + |     2 |        |          |       |
130 | Eliminating | variable | x | using | solved | equation | #1... |
131 | #2:         | 2        |   |       |        |          |       |
132 | #3:         | ans      | = |     x |        |          |       |
133 #+end_example
134
135
136 ** Graphical output
137 Graphical output is supported in Mathomatic which can be stored using
138 the =:file= header option. The following output formats are supported
139 within Mathomatic: [fn:2]
140 - Encapsulated Postscript =.eps=
141 - Portable Network Graphics =.png=
142 - Postscript =.ps=
143 - Groff PIC =.pic=
144
145 #+begin_example
146 #+begin_src mathomatic :results graphics :file sine.png
147 plot sin(x)
148 #+end_src
149
150 #+RESULTS:
151 [[file:sine.png]]
152 #+end_example 
153
154 In order to get graphical output during evaluation use the Mathomatic =plot=
155 command within Mathomatic. The file suffix will configure Gnuplot to
156 write the right file format. 
157
158 ** Named Procedures
159 The Babel Mathomatic plugin supports the use of named procedures and calls
160 operations. The use of these are detailed in the /Org Manual/.  This
161 manual will describe how they are used within the context of a Mathomatic
162 script.
163
164 A variable can be passed to a Mathomatic script which can be used to call the
165 aforementioned program later on in your org document.  The following
166 example is a program that evaluates X+2. 
167
168 #+begin_example
169 #+name: mathotest(x=0)
170 #+begin_src mathomatic :results output
171 x + 2
172 eliminate x
173 #+end_src
174
175 #+RESULTS: mathotest
176 : #1: x = 0
177 : #2: x + 2
178 : Eliminating variable x using solved equation #1...
179 : #2: 2
180 #+end_example
181
182 Calling the named script with a different value will result in a
183 different execution. For example: 
184
185 #+begin_example
186 #+call: mathotest(x=30)
187
188 #+RESULTS: mathotest(x=30)
189 : #1: x = 30
190 : #2: x + 2
191 : Eliminating variable x using solved equation #1...
192 : #2: 32
193 #+end_example
194
195 Note that table processing is not supported. This is because Mathomatic
196 does not have support for matrixes. However there are 
197 plans to provide this in the future through the use of simulated
198 arrays.  A simulated array is a syntactic sugar in Mathomatic to enclose
199 indexes in square brackets (/[]/). 
200
201 * Footnotes
202
203 [fn:1] Mathomatic manual downloads and further information can be obtained
204 from: [[http://www.mathomatic.org/math/doc/index.html]]
205
206 [fn:2] Mathomatic uses Gnuplot as its plot engine. All plot modes are
207 supported in Mathomatic. However, for convenience, only these are
208 supported in the =:file= option.