OOMMF eXtensible Solver Batch Interface: boxsi

Overview
The application Boxsi provides a batch mode interface to the Oxs micromagnetic computation engine. A restricted graphical interface is provided, but Boxsi is primarily intended to be controlled by command line arguments, and launched by the user either directly from the shell prompt or from inside a batch file.

Within the OOMMF architecture, Boxsi is both a server and a client application. It is a client of data table display and storage applications, and vector field display and storage applications. Boxsi is the server of a solver control service for which the only client is mmLaunch. It is through this service that mmLaunch provides a user interface window (shown above) on behalf of Boxsi.

A micromagnetic problem is communicated to Boxsi through a MIF 2.1 file specified on the command line and loaded from disk.

Launching
Boxsi must be started from the command line. The syntax is

tclsh oommf.tcl boxsi [standard options] [-parameters params] \
   [-pause <0|1>] [-nice <0|1>] [-exitondone <0|1>] [-kill tags] miffile

where

-parameters params

Sets MIF 2.1 format file parameters. The params argument should be a list with an even number of arguments, corresponding to name + value pairs. This list must be quoted so it is presented to Boxsi as a single item on the command line. The quoting mechanism is shell/operating system specific. Refer to your system documentation for details.

-nice <0|1>

If enabled (i.e., 1), then the program will drop its scheduling priority after startup. The default is 0, i.e., to retain its original scheduling priority.

-pause <0|1>

If enabled (i.e., 1), then the program automatically pauses after loading the specified problem file. The default is 0, i.e., to automatically move into ``Run'' mode once the problem is loaded.

-exitondone <0|1>

Whether to exit after solution of the problem is complete, or to await the interactive selection of the File|Exit command. The default is 1, i.e., automatically exit when done.

-kill tags

On termination, sends requests to other applications to shutdown too. The tags argument should be either a list of destination tags (which are declared by Destination commands) from the input MIF file, or else the keyword all, which is interpreted to mean all the destination tags.

miffile

Load and solve the problem found in miffile, which must be in the MIF 2.1 format. Required.

Although Boxsi cannot be launched by mmLaunch, nonetheless a limited graphical interactive interface for Boxsi is provided through mmLaunch, in the same manner as is done for Oxsii. Each running instance of Boxsi is included in the Threads list of mmLaunch, along with a checkbutton. This button toggles the presence of a user interface window.

Inputs
Boxsi loads problem specifications directly from disk as requested on the command line. The format for these files is the MIF 2.1 format, the same as used by the Oxsii interactive interface. The older MIF 1.1 used by the 2D solver mmSolve2D cannot be read by Boxsi, but the command line tool mifconvert can be used as an aid for converting MIF 1.1 files to the MIF 2.1 format. Sample MIF 2.1 files can be found in the directory oommf/app/oxs/examples.

Outputs
The lower panel of the Boxsi interactive interface presents Output, Destination, and Schedule sub-windows that display the current output configuration and allow interactive modification of that configuration. These controls are identical to those in the Oxsii user interface; refer to the Oxsii documentation for details. The only difference between Boxsi and Oxsii with respect to outputs is that in practice Boxsi tends to rely primarily on Destination and Schedule commands in the input MIF file to setup the output configuration. The interactive output interface is used for incidental runtime monitoring of the job.

Controls
The runtime controls provided by the Boxsi interactive interface are a restricted subset of those available in the Oxsii interface. If the runtime controls provided by Boxsi are found to be insufficient for a given task, consider using Oxsii instead.

The File menu holds 4 entries: Show Console, Close Interface, Clear Schedule, and Exit Oxsii. File|Show Console brings up a Tcl shell console running off the Boxsi interface Tcl interpreter. This console is intended primary for debugging purposes. File|Close Interface will remove the interface window from the display, but leaves the solver running. This effect may also be obtained by deselecting the Boxsi interface button in the Threads list in mmLaunch. File|Clear Schedule will disable all currently active output schedules, exactly as if the user clicked through the interactive schedule interface one output and destination at a time and disabled each schedule-enabling checkbutton. The final entry, File|Exit Boxsi, terminates the Boxsi solver and closes the interface window. Note that there is no File|Load... menu item; the problem specification file must be declared on the Boxsi command line.

The Help menu provides the usual help facilities.

The row of buttons immediately below the menu bar provides simulation progress control. These buttons--Run, Relax, Step and Pause--become active once the micromagnetic problem has been initialized. These buttons allow the user to change the run state of the solver. In the Pause state, the solver sits idle awaiting further instructions. If Step is selected, then the solver will move forward one iteration and then Pause. In Relax mode, the solver takes at least one step, and then runs until it reaches a stage boundary, at which point the solver is paused. In Run mode, the solver runs until the end of the problem is reached. When the problem end is reached, the solver will either pause or exit, depending upon the setting of the -exitondone command line option.

Normally the solver progresses automatically from problem initialization into Run mode, but this can be changed by the -pause command line switch. Interactive output is available in all modes; the scheduled outputs occur appropriately as the step and stage counts advance.

Directly below the run state control buttons are three display lines, showing the name of the input MIF file, the current run-state, and the current stage number/maximum stage number. Both stage numbers are 0-indexed.

Details
As with Oxsii, the simulation model construction is governed by the Specify blocks in the input MIF file, and all aspects of the simulation are determined by the specified Oxs_Ext classes. Refer to the appropriate Oxs_Ext class documentation for simulation and computational details.

Known Bugs
Boxsi suffers from the same Windows 9X Tcl network traffic bug as Oxsii. OOMMF users on Windows 9X systems are encouraged to upgrade to Tcl 8.2 or later.

OOMMF Documentation Team
October 30, 2002