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