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.