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