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.