How to Use Mathematica Kernel

  It is possible to run Mathematica kernel without notebook interface. Sometimes we are required to use the kernel, particularly when no graphical interface is installed in CPU clusters [1].

1. General tips

There are general tips for making the computation by Mathematica faster.

• This article [2] is useful to write a faster mathematica code.
• Do not use Simplify[] or FullSimplify[]. When a code mysteriously gets too slow at certain parameter values, then this may be because Simplify[] works poorly for a big (and complicated) data.
• Use Hold[_] to create dummy variables. Objects such as Cycles[_] contain extra properties. Mathematica has to check these extra properties for any operations such as Simplify[_] or Coefficient[_].
• Try to parallelize the computation. The outermost loop can be most efficiently parallelized. Adjusting the order of indices (e.g. ParallelTable[Table[comp[i,j],{i,10}],{j,100}]) may enhance the speed by an O(1) factor or more.
• Let your computer run overnight. Use

     NotebookSave[EvaluationNotebook[]]

  to save the current notebook. Record the time by

     DateList[]

• Try a remote login to special servers, rather than computing locally.
• Use a larger number of CPUs (a workstation cluster). Usually one cannot open a notebook, so s/he needs to send jobs to the Mathematica kernel. For this purpose, a notebook should be rewritten a batch file; see instructions in Wolfram, EIS Lab and DAMTP.
• To clear all memories in the kernel and keep evaluating the cells, use
  

     SetOptions[$FrontEnd, "ClearEvaluationQueueOnKernelQuit" -> False]; Quit[]

  See this post.

2. Shell setup

Mathematica kernel can be invoked by using Command Prompt (Windows) or Terminal (Mac OS X, Unix), and carries the name math (in Windows or Unix) or MathKernel (in Mac OS X). In Mac OS X before Catalina (10.5), create

~/.bash_profile

and add a line

alias math="/Applications/Mathematica.app/Contents/MacOS/MathKernel"

then

$ math

invokes the MathKernel. The OS X Catalina uses zsh, and loads .zprofile or .zshrc; See this post.

3. Batch mode

A basic usage is

$ math < test.m > out.txt

This gives the text version of the standard output. The output file out.txt can have other extensions like out.m. Here < > is not a bracket, but they specify input and output; A < B is "input B to A" and B > C is "output B to C". Notebook files like test.nb cannot be executed in this mode. Unlike the notebook interface, there is no waring like "Output exceeds size limits".

  The file test.m should be wrapped as

AppendTo[$Echo, "stdout"]

Expand[(x+y)^2]

Exit[ ]

The first line says the output file should contain the input lines, which is omitted in the batch mode by default. The final line quit the kernel when all computation has been done.

$ math -noprompt < test.m > out.txt

removes the prompts, In[1]:= and Out[1]:= .

  Textual messages are shown on the terminal in the batch mode, but graphical outputs like Plot[ ] cause some problem [3].

4. Script mode

A basic usage is

$ math -script test.m

The script mode does not produce any output by itself. You need to write appropriate expressions directly in the Mathematica file, like

res = Simplify[1+1];

StandardForm["res="] >> "~/Desktop/output.txt";

res >>> "~/Desktop/output.txt";

Notebook files cannot be executed in the script mode. Compared to the batch mode, the script mode works much faster when you handle large data (e.g. more than 10000 lines).

5. Tips and Options

Creating a script file

First, clear the output cells by choosing "Cells -> Delete all output cells" in the menu, and delete the prompts (In[1]:= and Out[1]:= ) by restart.

Use "Save as -> text (.txt)" and change the extension to .m by hand. Do not use "Save as -> package (.m)" since it may produce a crap [4].

Numerical precision

Keep in mind that Simplify[] may truncate the precision of numerical calculation down to MachinePrecision. A workaround is to use SetPrecision[] inside Simplify[].

Debugging

Unfortunately, Mathematica complains a lot more in the script mode. The Package scripts should follow a strict grammar, if we want to execute it at command prompt.

Greek letters (σ, π, ...) can cause troubles if you share the same file in different operating systems. They should be replaced by textual notation (\[Sigma], \[Pi], ...).

Do not forget to put the semicolon (;) at the end of each sentence, because CR may be totally neglected in the script mode.

In Windows, a MathKernel session terminates immediately after Exit[] or Quit[]. It is better to use Interrupt[] for debugging. It is useless to try cmd /k MathKernel.exe -script file.m because it stops Command Prompt, not MathKernel.

Reading data

A simple example is to use

SetDirectory["~/mydocuments"];

<< "mydata.txt";

FilePrint[ ] just writes out the data, but does not load them. Reading an external file in this way is much faster than making copy-and-paste particularly when the data is large.

If you want to define the name and location of the data as a variable, you need to create an input stream.

SetDirectory["~/mydocuments"];

instream = OpenRead["mydata.txt"];

Get[instream];

Close[instream];

Get[ ] loads the entire data in the file, while Read[ ] just reads one line. ReadList[ ] reads the entire file and returns the data as a list (or a list of NULL if the file is made out of substitutions). Sometimes Get[ ] does not work properly in different platforms.

Writing results

Create an output stream in order to specify the location and the name of output file in a flexible way, like

filename = "~/Desktop/myfile.txt";

outstream = OpenWrite[filename, PageWidth -> 100];

Write[outstream, Table[f[i], {i,1,9}], StandardForm["="]];

Write[outstream, Table[i^2, {i,1,9}], StandardForm[";"]];

Close[outstream];

where each of Write[ ] automatically inserts a new line. Other methods like

1+1 >> filename;

1+1 >> ToString[filename];

just create a new file named "filename".

Measuring the execution time

To measure the time needed for computation, use

$ time math < test.m > out.txt

If you log in to a remote server e.g. by ssh, you can continue the calculation after logout by adding nohup as

$ nohup math < test.m > out.txt

Nohup and time can be combined as

$ nohup bash -c "(time math -script MMd2.1.m) &> timelog.out" &

We need to specify two outputs (two &'s) for the following reasons. Nohup invokes a background process where all standard output is sent to nohup.out, whereas time writes the duration of process onto the standard error output [5].

6. Remote login guide

One can open a Mathematica notebook in a remote server and show it on the display of your local computer by using SSH X11-forwarding. X-server should be installed and launched to enable the X11-forwarding. In practice, you need to install e.g. PUTTY and X-ming in Windows. XQuartz is needed in Mac OS X [6].

After launching the X-server, use

ssh -X myaccount@server

If this does not work, check the file

/private/etc/sshd_config

and rewrite

X11Forwarding yes

X-term setup

   In Mac OS X, XQuartz launches X-term as well. The X-term uses small fonts by default, so I prefer to use the following setup. Note that this small task is not necessary because Xterm is interchangeable with Terminal.

To change the font, create the file

~/.Xresources

as follows and restart XQuartz.

! XTerm

XTerm*visualBell: false

XTerm*utf-8: 1

XTerm*jumpScroll: true

XTerm*saveLines: 2000

XTerm*scrollBar: true

XTerm*rightScrollBar: true

XTerm.VT100.geometry:100x40+50+20

Xterm*colorMode: true

Xterm*cursorColor: grey

Xterm*pointerColor: blue

XTerm*background: white

XTerm*foreground: black

XTerm*faceName: Mono

XTerm*faceSize: 12

XTerm*VT100*cursorBlink: true

Footnotes

[1] An example is the sushiki server in Yukawa Institute

[2] 10 Tips for Writing Fast Mathematica Code

[3] Running Mathematica without the Notebook interface to export plots or graphics.

[4] How to Run Mathematica Batch-files in Background?

[5] how can I use nohup to run process as a background process in linux

[6] X11 is replaced by XQuartz as announced by Apple.