OOMMF Home next up previous contents index
Next: Standard Oxs_Ext Child Classes Up: OOMMF eXtensible Solver Previous: OOMMF eXtensible Solver Interactive


OOMMF eXtensible Solver Batch Interface: boxsi

boxsi Screen Shot

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. The MIF 1.x formats are also accepted; they are converted to the MIF 2.1 format by an automatic call to mifconvert.

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

tclsh oommf.tcl boxsi [standard options] [-exitondone <0|1>] \
   [-kill tags] [-nice <0|1>] [-parameters params] \
   [-pause <0|1>] [-restart <0|1|2>] miffile
where
-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.
-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.
-parameters params
Sets MIF 2.1 file parameters. The params argument should be a list with an even number of arguments, corresponding to name + value pairs. Each ``name'' must appear in a Parameter statement in the input MIF file. The entire name + value list must be quoted so it is presented to Boxsi as a single item on the command line. For example, if A and Ms appeared in Parameter statements in the MIF file, then an option like
   -parameters "A 13e-12 Ms 800e3"
could be used to set A to 13e-12 and Ms to 800e3. The quoting mechanism is shell/operating system specific; refer to your system documentation for details.
-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.
-restart <0|1|2>
If the restart option is 0 (the default), then the problem loads and runs from the beginning. If set to 1, then when loading the problem a check is made for a pre-existing restart (checkpoint) file. If one is found, then the problem resumes from the state saved in that file. If no checkpoint file is found, then an error is raised. If the restart option is set to 2, then a checkpoint file is used if one can be found, but if not then the problem loads and runs from the beginning without raising an error. See the Oxs_Driver documentation for information on checkpoint files.
miffile
Load and solve the problem found in miffile, which must be either in the MIF 2.1 format, or convertible to that format by mifconvert. 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 MIF 1.1 and MIF 1.2 formats used by the 2D solver mmSolve2D can also be input to Boxsi, which will automatically call the command line tool mifconvert to convert from the MIF 1.x format to the MIF 2.1 format ``on-the-fly.'' 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 Home next up previous Contents index

OOMMF Documentation Team
May 24, 2006