Headless mode: batch runs and console kernels

A calculation is usually started from the program window. Often, though, another way is more convenient: to calculate a dozen tasks one after another, to run a long calculation on a server, or to include the calculation in your own processing script. The package offers two ways of working without a person at the keyboard.

The calculation is the same in both cases, and the output files are identical.

1. Batch mode

The program is given the -Ar switch and the path to the task. It opens the task, calculates every step and closes itself.

Windows

"C:\\Program Files\\TMC Suite\\bin\\tmc_rth.exe" /Ar "C:\\work\\task.tpl"

The switch may be written with a hyphen (-Ar) or a slash (/Ar) — both are equivalent. The /Arb form is also accepted: historically it meant “batch”, and today it behaves exactly like /Ar.

Linux

planarrt_h -Arb /home/user/work/task.tpl

macOS

The executable lives inside the .app bundle, and that is what is called:

/Applications/PlanarRT_H.app/Contents/MacOS/PlanarRT_H -Arb /Users/user/work/task.tpl

What the program does

1. Opens the task file.
2. Calculates the steps from the first to the last (#STEP … #END_STEP).
3. Writes the output files next to the task — the names come from the #OUTPUT section.
4. Closes.

Always give the full path to the task. The program derives from it the directory that holds the included task files (#include) and the .eps distributions. Given a bare file name, it looks for them elsewhere.

For the X-mode everything is the same; the program is called tmc_rtx (Windows) or planarrt_x (Linux, macOS).

2. Console kernels for Linux

These are separate programs — tmc_rth (H-mode) and tmc_rtx (X-mode). They have no windows at all and need no desktop on the machine: they are installed on a server that has only a terminal.

tmc_rth /home/user/work/task.tpl
tmc_rtx /home/user/work/task.tpl

The kernel takes the output file name from the task itself, from the #OUTPUT section — no second argument is needed.

Exit codes

The exit code makes it easy to stop a script when a task fails to calculate:

tmc_rth /path/task.tpl || { echo "calculation failed"; exit 1; }

What is printed

The progress of parsing and calculating goes to the standard output, error messages to the error stream. Useful lines:

Step:1;Error:no                                 the task was read, no errors
Set block 55; points:1057041; eps = {...}       a distribution file was read
Step:1;Can't open diel.data file {...}          the distribution file is missing

3. Several tasks in a row

Linux and macOS

for f in /home/user/work/*.tpl; do
    echo "== $f"
    tmc_rth "$f" || echo "  failed, skipping"
done

Windows

for %%f in (C:\\work\\*.tpl) do (
    echo == %%f
    "C:\\Program Files\\TMC Suite\\bin\\tmc_rth.exe" /Ar "%%f"
)

4. What affects the speed

• Field and topology output. With FIELDS and TOPOLOGY switched off in the #OUTPUT section the calculation is noticeably faster: the whole grid does not have to be written to disk on every time step.
• Where the task is stored. Keep the task and its results on a local disk. Working from a network share, or from a partition belonging to another system (a Windows partition mounted under Linux, for example), makes every write take the long way round and slows the calculation down several times over.
• Synchronisation with FieldView. The menu item Config → Synchronization enables a mode in which the kernel waits after each field frame until FieldView has read it. It is of no use without windows: there is nobody to wait for, and every frame costs extra seconds. Switch this mode off before a batch run.

5. Common questions

The program closed immediately and there are no files. Most likely the task or an included file was not found: check that the path is complete and that the files the task refers to (#include, .eps distributions) are next to it.

It calculates, but no output files appear. Look at the #OUTPUT section: the line FILE <name>; is mandatory, must come first, and the name must not contain a dot.

How to look at the result. The output files are the same on all three systems. The viewers of the package open them: .t — TMCROS, .s — TMCGROUT, .DAT — TMC_DN, fields (.ex, .AMP, .FAZ) — FieldView. A file calculated on Linux opens in the Windows version and the other way round.

Can one system calculate and another display. Yes — that is exactly why the file formats were kept unchanged. Tasks and results move between Windows, Linux and macOS as they are.