OOMMF eXtensible Solver Interactive Interface: Oxsii

Oxsii Screen Shot

Overview
The application Oxsii is the graphical, interactive user interface to the Oxs micromagnetic computation engine. Within the OOMMF architecture, Oxsii is both a server and a client application. Oxsii is a client of data table display and storage applications, and vector field display and storage applications. Oxsii 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 Oxsii.

A micromagnetic problem is communicated to Oxsii via a MIF 2 file, which defines a collection of Oxs_Ext objects that comprise the problem model. The problem description includes a segmentation of the lifetime of the simulation into stages. Stages mark discontinuous changes in model attributes, such as applied fields, and also serve to mark overall simulation progress. Oxsii provides controls to advance the simulation, stopping between iterations, between stages, or only when the run is complete. Throughout the simulation, the user may save and display intermediate results, either interactively or via scheduling based on iteration and stage counts.

Problem descriptions in the MIF 1.1 and MIF 1.2 formats can also be input. They are automatically passed to mifconvert for implicit conversion to MIF 2 format. MIF 2 files are actually Tcl scripts with a handful of extra commands. This makes them extremely flexible, but they can also be difficult to compose from scratch. In many cases it may be easier to first use mmProbEd set to MIF 1.2 mode to create a draft problem. Use the File|Save as menu option in mmProbEd to write the problem to disk. If MIF 1.2 provides all the needed functionality, then one can keep the problem in that format, loading it directly into Oxsii and Boxsi, and continue to edit it in mmProbEd as necessary. If and when some more advanced functionality available only in MIF 2.x is needed, the mifconvert command line application can be run manually to create a MIF 2.x file from the MIF 1.2 version. The MIF 2.x file can then be hand edited to suit. Do note, however, that there is no MIF 2.x to MIF 1.2 back conversion support.

See MIF 2.x tips for additional recommendations on writing MIF 2.x files.

Launching
Oxsii may be started either by selecting the Oxsii button on mmLaunch, or from the command line via

tclsh oommf.tcl oxsii [standard options] [-exitondone <0|1>] \
   [-logfile logname] [-loglevel level] [-nice <0|1>] [-nocrccheck <0|1>] \
   [-nologfile] [-numanodes nodes] [-outdir dir] [-parameters params] \
   [-pause <0|1>] [-quiet level] [-restart <0|1|2>] [-restartfiledir dir] \
   [-threads count] [miffile]
where
-exitondone <0|1>
Whether to exit after solution of the problem is complete. Default is to simply await the interactive selection of another problem to be solved.
-logfile logname
Write log and error messages to file logname. The default log file is oommf/oxsii.log (formerly oxsii.errors).
-loglevel level
Controls the detail level of log messages, with larger values of level producing more output. Default value is 1.
-nice <0|1>
If enabled (i.e., 1), then the program will drop its scheduling priority after startup. The default is 1, i.e., to yield scheduling priority to other applications.
-nocrccheck <0|1>
On simulation restarts the CRC of the MIF file and the run parameters are normally compared against the CRC of the original MIF file and parameters as recorded in the restart file. If the CRCs or parameters don't match then an error is thrown to alert the user that the run state is changed. If this option is enabled (i.e., 1) then those checks are disabled.
-nologfile
If this option is set then logging information is not written to disk but is instead written to (only) stderr (regardless of -quiet level).
-numanodes <nodes>
This option is available on NUMA-aware builds of Oxs. The nodes parameter must be either a comma separated list of 0-based node numbers, the keyword “auto”, or the keyword “none”. In the first case, the numbers refer to memory nodes. These must be passed on the command line as a single parameter, so either ensure there are no spaces in the list, or else protect the spaces with outlying quotes. For example, -numanodes 2,4,6 or -numanodes "2, 4, 6". Threads are assigned to the nodes in order, in round-robin fashion. The user can either assign all the system nodes to the Oxsii process, or may restrict Oxsii to run on a subset of the nodes. In this way the user may reserve specific processing cores for other processes (or other instances of Oxsii). Although it varies by system, typically there are multiple processing cores associated with each memory node. If the keyword “auto” is selected, then the threads are assigned to a fixed node sequence that spans the entire list of memory nodes. If the keyword “none” is selected, then threads are not tied to nodes by Oxsii, but are instead assigned by the operating system. In this last case, over time the operating system is free to move the threads among processors. In the other two cases, each thread is tied to a particular node for the lifetime of the Oxsii instance. See also the discussion on threading considerations in the Boxsi documentation.

The default value for nodes is “none”, which allows the operating system to assign and move threads based on overall system usage. This is also the behavior obtained when the Oxs build is not NUMA-aware. On the other hand, if a machine is dedicated primarily to running one instance of Oxsii, then Oxsii will likely run fastest if the thread count is set to the number of processing cores on the machine, and nodes is set to “auto”. If you want to run multiple copies of Oxsii simultaneously, or run Oxsii in parallel with some other application(s), then set the thread count to a number smaller than the number of processing cores and restrict Oxsii to some subset of the memory nodes with the -numanodes option and an explicit nodes list.

The default behavior is modified (in increasing order of priority) by the numanodes setting in the active oommf/config/platform/ platform file, by the numanodes setting in the oommf/config/options.tcl or oommf/config/local/options.tcl file, or by the environment variable OOMMF_NUMANODES. The -numanodes command line option, if any, overrides all.

-outdir dir
Specifies the directory where output files are written by mmArchive. This option is useful when the default output directory is inaccessible or slow. The environment variable OOMMF_OUTDIR sets the default output directory. If OOMMF_OUTDIR is set to the empty string, or not set at all, then the default is the directory holding the MIF file. If this option is specified on the command line, or if OOMMF_OUTDIR is set, then the Oxsii File|Load dialog box includes a control to change the output directory.
-parameters params
Sets MIF 2 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 Oxsii 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 specific to the shell/operating system; refer to your system documentation for details.
-pause <0|1>
If disabled (i.e., 0), then the program automatically shifts into “Run” mode after loading the specified miffile. The default is 1, i.e., to “Pause” once the problem is loaded. This switch has no effect if miffile is not specified.
-quiet level
Controls amount of output written to stdout and stderr. If level is 0 then log messages are echoed to stderr. The default setting is 1.
-restart <0|1>
Controls the initial setting of the restart flag, and thereby the load restart behavior of any miffile specified on the command line. The restart flag is described in the Controls section below. The default value is 0, i.e., no restart.
-restartfiledir dir
Specifies the directory where restart files are written. The default is determined by the environment variable OOMMF_RESTARTFILEDIR, or if this is not set then by OOMMF_OUTDIR. If neither environment variable is set then the default is the directory holding the MIF file. Write access is required to the restart file directory. Also, you may want to consider whether the restart files should be written to a local temporary directory or a network mount.
-threads <count>
The option is available on threaded builds of Oxs. The count parameter is the number of threads to run. The default count value is set by the oommf_thread_count value in the config/platforms/ file for your platform, but may be overridden by the OOMMF_THREADS environment variable or this command line option. In most cases the default count value will equal the number of processing cores on the system; this can be checked via the command tclsh oommf.tcl +platform.
miffile
Load and solve the problem found in miffile, which must be either in the MIF 2 format, or convertible to that format by mifconvert. Optional.
All the above switches are optional.

Since Oxsii does not present any user interface window of its own, it depends on mmLaunch to provide an interface on its behalf. The entry for an instance of Oxsii in the Running Applications column of any running copy of mmLaunch has a checkbutton next to it. This button toggles the presence of a user interface window through which the user may control that instance of Oxsii.

Inputs
Unlike mmSolve2D, Oxsii loads problem specifications directly from disk (via the File|Load menu selection), rather than through mmProbEd or FileSource. Input files for Oxsii must be either in the MIF 2 format, or convertible to that format by the command line tool mifconvert. There are sample MIF 2 files in the directory oommf/app/oxs/examples. MIF files may be edited with any plain text editor.

Outputs
Once a problem has been loaded, the scroll box under the Output heading will fill with a list of available outputs. The contents of this list will depend upon the Oxs_Ext objects specified in the input MIF file. Refer to the documentation for those objects for specific details. To send output from Oxsii to another OOMMF application, highlight the desired selection under the Output heading, make the corresponding selection under the Destination heading, and then specify the output timing under the Schedule heading. Outputs may be scheduled by the step or stage, and may be sent out interactively by pressing the Send button. The initial output configuration is set by Destination and Schedule commands in the input MIF file.

Outputs fall under two general categories: scalar (single-valued) outputs and vector field outputs. The scalar outputs are grouped together as the DataTable entry in the Output scroll box. Scalar outputs include such items as total and component energies, average magnetization, stage and iteration counts, max torque values. When the DataTable entry is selected, the Destination box will list all OOMMF applications accepting datatable-style input, i.e., all currently running mmDataTable, mmGraph, and mmArchive processes.

The vector field outputs include pointwise magnetization, various total and partial magnetic fields, and torques. Unlike the scalar outputs, the vector field outputs are listed individually in the Output scroll box. Allowed destinations for vector field output are running instances of mmDisp and mmArchive. Caution is advised when scheduling vector field output, especially with large problems, because the output may run many megabytes.

Controls
The File menu button holds five entries: Load, Show Console, Close Interface, Suspend Oxsii and Exit Oxsii. File|Load launches a dialog box that allows the user to select an input MIF problem description file. File|Show Console brings up a Tcl shell console running off the Oxsii interface Tcl interpreter. This console is intended primary for debugging purposes. In particular, output from MIF Report commands may be viewed here. 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 Oxsii interface button in the Running Applications list in mmLaunch. File|Suspend Oxsii causes the Oxsii solver to write the current simulation state into a checkpoint (.restart) file and exit. The checkpoint file may be used to resume the simulation at a later time using the command line -restart or File|Load dialog Restart checkbutton controls. The final entry, File|Exit Oxsii, terminates the Oxsii solver and closes the interface window.

Options menu holds three entries: Clear Schedule, Checkpoint Control and Restart Flag. The first clears all Step and Stage selections from the 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. This control can be used after loading a problem to override the effect of any Schedule commands in the MIF file. (In contrast, the Clr Sched button in the File|Load dialog clears the existing schedule before loading the MIF file.) The Checkpoint Control option opens a dialog box that reports the name of the checkpoint (.restart) file and allows interactive setting of the checkpoint interval and checkpoint file disposal. The restart flag controls problem load behavior. In normal usage, the restart flag is not set and the selected problem loads and runs from the beginning. Conversely, if the restart flag is set, then when a problem is loaded a check is made for a checkpoint file. If the checkpoint file is not found, then an error is raised. Otherwise, the information in the checkpoint file is used to resume the problem from the state saved in that file. The restart flag can be set from the Options menu, the File|Load dialog box, or from the command line. See the Oxs_Driver documentation for information on checkpoint files.

The Help menu provides the usual help facilities.

The row of buttons immediately below the menu bar provides simulation progress control. These buttons become active once a problem has been loaded. The first button, Reload, re-reads the most recent problem MIF input file, re-initializes the solver, and pauses. Reset is similar, except the file is not re-read. The remaining four buttons, Run, Relax, Step and Pause place the solver into one of four run-states. 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. Interactive output is available in all modes; the scheduled outputs occur appropriately as the step and stage counts advance.

Directly below the progress control buttons are two display lines, showing the name of the input MIF file and the current run-state. Below the run-state Status line is the stage display and control bar. The simulation stage may be changed at any time by dragging the scroll bar or by typing the desired stage number into the text display box to the left of the scroll bar. Valid stage numbers are integers from 0 to $N-1$, where $N$ is the number of stages specified by the MIF input file.

Details
The simulation model construction is governed by the Specify blocks in the input MIF file. Therefore, 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.

Error and status messages are written to the log file (default oommf/oxsii.log). This is a plain text file where each record is prefixed with a timestamp and source identification. The start of each simulation is recorded with a Start: record, and an End record marks successful completion of the simulation. If you have multiple simulations running simultaneously, either on the same machine or on different machines but logging to the same (networked) file, then records from the different simulations will be intermingled. The OOMMF command line application logreview can be used as an aid for reading Oxsii log files. See also the command line application lastjob, which relies on the log file to determine the last simulation run and optionally restart interrupted simulations.


OOMMF Documentation Team
September 30, 2025