\section{OOMMF eXtensible Solver}\label{sec:oxs}%
\index{Oxs}\index{application!Oxs}%
The Oxs (OOMMF eXtensible Solver) is an extensible micromagnetic
computation engine capable of solving problems defined on
three-dimensional grids of rectangular cells holding three-dimensional
spins.  There are two interfaces provided to Oxs: the interactive
interface
\hyperrefhtml{Oxsii}{Oxsii (Sec.~}{)}{sec:oxsii}
intended to be controlled primarily through a graphical
user interface, and the batch mode
\hyperrefhtml{Boxsi}{Boxsi (Sec.~}{)}{sec:boxsi}, which has extended
command line controls making it suitable for use in shell scripts.

Problem definition for Oxs is accomplished using input files in the
\hyperrefhtml{\MIF~2 format}{\MIF~2 format (Sec.~}{)}{sec:mif2format}.
This is an extensible format; the standard OOMMF modules are
\hyperrefhtml{documented below}{documented in Sec.~}{ below}{sec:oxsext}.
Files in the \htmlref{\MIF~1.1}{sec:mif1format} and
\htmlref{\MIF~1.2}{sec:mif12format} formats are also accepted.  They are
passed to \hyperrefhtml{\app{mifconvert}}{\app{mifconvert}
(Sec.~}{)}{sec:mifconvert} for conversion to \MIF~2 format
``on-the-fly.''

Note on \Tk\ dependence: Some \MIF~2 problem descriptions rely on
external image files\index{file!mask}\index{file!bitmap}; examples
include those using the
\htmlonlyref{\cd{Oxs\_ImageAtlas} class}{html:oxsImageAtlas}%
\latex{ (Sec.~\ref{sec:oxsAtlases})}, or those using the \MIF~2
\htmlonlyref{\cd{ReadFile}}{html:ReadFile} command with the \cd{image}
translation specification\latex{ (Sec.~\ref{sec:mif2ExtensionCommands})}.
If the image file is not in the PPM P3 (text) format, then the
\app{any2ppm}\index{application!any2ppm} application may be
launched to read and convert the file.  Since \app{any2ppm}
requires\index{requirement!Tk}\index{requirement!display} \Tk, at the
time the image file is read a valid display must be available.  See the
{\hyperrefhtml{\app{any2ppm} documentation}{\app{any2ppm} documentation
(Sec.~}{)}{sec:any2ppm}} for details.

\subsection{OOMMF eXtensible Solver Interactive Interface:
Oxsii}\label{sec:oxsii}%
\index{simulation~3D!interactive}\index{application!Oxsii}

\begin{center}
\includepic{oxsii-ss}{Oxsii Screen Shot}
\end{center}

\ssechead{Overview}
The application \app{Oxsii} is the graphical, interactive user interface
to the Oxs micromagnetic computation engine.  Within the
\hyperrefhtml{\OOMMF\ architecture}{\OOMMF\ architecture (see
Sec.~}{)}{sec:arch}, \app{Oxsii} is both a server and a client
application. \app{Oxsii} is a client of data table display and storage
applications, and vector field display and storage applications.
\app{Oxsii} is the server of a solver control service for which the only
client is \hyperrefhtml{\app{mmLaunch}}{\app{mmLaunch}
(Sec.~}{)}{sec:mmlaunch}\index{application!mmLaunch}.  It is through
this service that \app{mmLaunch} provides a user interface window (shown
above) on behalf of \app{Oxsii}.

A micromagnetic problem is communicated to \app{Oxsii} via a
\htmlref{\MIF~2 file}{sec:mif2format},
which defines a collection of \htmlref{Oxs\_Ext objects}{sec:oxsext}
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 coarse grain simulation progress.  \app{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 \htmlref{\MIF~1.1}{sec:mif1format} and
\htmlref{\MIF~1.2}{sec:mif12format} formats can also be input.  They are
automatically passed to \hyperrefhtml{\app{mifconvert}}{\app{mifconvert}
(Sec.~}{)}{sec:mifconvert} for implicit conversion to \MIF~2 format.

\ssechead{Launching}
\app{Oxsii} may be started either by selecting the
\btn{Oxsii} button on \htmlref{mmLaunch}{sec:mmlaunch}, or from the
command line via
\begin{verbatim}
tclsh oommf.tcl oxsii [standard options] [-exitondone <0|1>] \
   [-logfile logname] [-loglevel level] [-nice <0|1>] [-nocrccheck <0|1>] \
   [-numanodes nodes] [-outdir dir] [-parameters params] [-pause <0|1>] \
   [-restart <0|1|2>] [-restartfiledir dir] [-threads count] [miffile]
\end{verbatim}
where
\begin{description}
\item[\optkey{-exitondone \boa 0\pipe 1\bca}]
  Whether to exit after solution of the problem is complete.
  Default is to simply await the interactive selection
  of another problem to be solved.
\item[\optkey{-logfile logname}]
  Write log and error messages to file \textit{logname}.  The default log
  file is \fn{oommf/oxsii.errors}.
\item[\optkey{-loglevel level}]
  Controls the detail level of log messages, with larger values of
  \textit{level} producing more output.  Default value is 1.
\item[\optkey{-nice \boa 0\pipe 1\bca}]
  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.
\item[\optkey{-nocrccheck \boa 0\pipe 1\bca}]
  On simulation restarts, the CRC
  \hyperrefhtml{CRC}{CRC (Sec.~}{)}{sec:crc32}
  of the \MIF\ file is normally compared against the CRC of the original
  \MIF\ file as recorded in the restart file.  If the CRCs don't match then
  an error is thrown to alert the user that the \MIF\ file has changed.  If
  this option is enabled (i.e., 1) then the check is disabled.
\item[\optkey{-numanodes \boa nodes\bca}]\index{NUMA|(}
  \index{parallelization}
  This option is available on
  \hyperrefhtml{NUMA-aware}{NUMA-aware (Sec.~}{)}{sec:parallel} builds of
  Oxs.  The \textit{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 insure there are no spaces in the list, or else protect the
  spaces with outlying quotes.  For example, \cd{-numanodes 2,4,6} or
  \cd{-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 \app{Oxsii} process, or may restrict \app{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
  \app{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 \app{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 \app{Oxsii}
   instance.  See also the discussion on \htmlonlyref{threading
  considerations}{html:threadconsider} in the Boxsi documentation.

  The default value for \textit{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 \app{Oxsii}, then \app{Oxsii} will
  likely run fastest if the thread count is set to the number of
  processing cores on the machine, and \textit{nodes} is set to
  ``auto''.  If you want to run multiple copies of \app{Oxsii}
  simultaneously, or run \app{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 \app{Oxsii} to some
  subset of the memory nodes with the \cd{-numanodes} option and an
  explicit nodes list.

  The default behavior is modified (in increasing order of priority) by the
  \cd{numanodes} setting in the active \fn{oommf/config/platform/} platform
  file, by the \cd {numanodes} setting in the \fn{oommf/config/options.tcl}
  or \fn{oommf/config/local/options.tcl} file, or by the environment variable
  \cd{OOMMF\_NUMANODES}\index{environment~variables!OOMMF\_NUMANODES}.  The
  \cd{-numanodes} command line option, if any, overrides all.\index{NUMA|)}
\item[\optkey{-outdir dir}]
  Specifies the directory where output files are written by
  \app{mmArchive}.  This option is useful when the default output
  directory is inaccessible or slow. The environment variable
  \cd{OOMMF\_OUTDIR}\index{environment~variables!OOMMF\_OUTDIR} sets the
  default output directory.  If \cd{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 \cd{OOMMF\_OUTDIR} is set, then the \app{Oxsii}
  \cd{File\pipe Load\ldots} dialog box includes a control to change
  the output directory.
\item[\optkey{-parameters params}]
  Sets \hyperrefhtml{\MIF~2}{\MIF~2 (Sec.~}{)}{sec:mif2format} file
  parameters.  The \textit{params} argument should be a list with an
  even number of arguments, corresponding to name + value pairs.  Each
  ``name'' must appear in a
  \htmlonlyref{\cd{Parameter}}{html:mif2parameter}
  statement\latex{ (Sec.~\ref{sec:mif2ExtensionCommands})} in the input
  \MIF\ file.  The entire name + value list must be quoted so it is
  presented to \app{Oxsii} as a single item on the command line.  For
  example, if \cd{A} and \cd{Ms} appeared in \cd{Parameter} statements
  in the \MIF\ file, then an option like
\begin{verbatim}
   -parameters "A 13e-12 Ms 800e3"
\end{verbatim}
  could be used to set \cd{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.
\item[\optkey{-pause \boa 0\pipe 1\bca}]
  If disabled (i.e., 0), then the program automatically shifts into
  ``Run'' mode after loading the specified \textit{miffile}. The default
  is 1, i.e., to ``Pause'' once the problem is loaded. This switch has
  no effect if miffile is not specified.
\item[\optkey{-restart \boa 0\pipe 1\bca\index{simulation~3D!restarting}}]
  Controls the initial setting of the restart flag, and thereby 
  the load restart behavior of any \cd{miffile} specified on the command
  line.  The restart flag is described in the
  \htmlonlyref{Controls section below}{html:oxsiirestartflag}.
  The default value is 0, i.e., no restart.
\item[\optkey{-restartfiledir dir}]
  Specifies the directory where restart files are written.
  The default is determined by the environment variable
  \cd{OOMMF\_RESTARTFILEDIR}\index{environment~variables!OOMMF\_RESTARTFILEDIR},
  or if this is not set then by
  \cd{OOMMF\_OUTDIR}\index{environment~variables!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.
\item[\optkey{-threads \boa count\bca}]
  \index{parallelization}
  The option is available on
  \hyperrefhtml{threaded}{threaded (Sec.~}{)}{sec:parallel} builds of Oxs.
  The \textit{count} parameter is the number of threads to run.  The
  default count value is set by the \cd{oommf\_thread\_count} value in
  the \fn{config/platforms/} file for your platform, but may be
  overridden by the
  \cd{OOMMF\_THREADS}\index{environment~variables!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
  \cd{tclsh oommf.tcl +platform}.
\item[\optkey{miffile}]
  Load and solve the problem found in \textit{miffile}, which must be
  either in the \MIF~2 format, or convertible to that format by 
  \htmlref{\app{mifconvert}}{sec:mifconvert}.  Optional.
\end{description}
All the above switches are optional.

Since \app{Oxsii}\index{mmLaunch~user~interface} does not present
any user interface window of its own, it depends on
\app{mmLaunch}\index{application!mmLaunch} to provide an interface on
its behalf.  The entry for an instance of \app{Oxsii} in the
\btn{Threads}\index{threads} column of any running copy of
\app{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 \app{Oxsii}.


\ssechead{Inputs}
Unlike \hyperrefhtml{\app{mmSolve2D}}{\app{mmSolve2D}
(Sec.~}{)}{sec:mmsolve2d},
\app{Oxsii} loads problem specifications
directly from disk (via the \cd{File\pipe Load\ldots} menu selection),
rather than through
\hyperrefhtml{\app{mmProbEd}}{\app{mmProbEd} (Sec.~}{)}{sec:mmprobed} or
\hyperrefhtml{\app{FileSource}}{\app{FileSource}
(Sec.~}{)}{sec:filesource}.  Input files for \app{Oxsii} must be either
in the \hyperrefhtml{\MIF~2}{\MIF~2 (Sec.~}{)}{sec:mif2format}
format, or convertible to that format by the command line tool
\hyperrefhtml{\app{mifconvert}}{\app{mifconvert}
(Sec.~}{)}{sec:mifconvert}.  There are sample \MIF~2 files in the
directory \cd{oommf/app/oxs/examples}.  \MIF\ files may be edited with
any plain text editor.

\ssechead{Outputs\label{html:oxsiioutputs}}
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 \cd{Oxs\_Ext} objects specified in the
input \MIF\ file.  Refer to the documentation for those objects for
\hyperrefhtml{specific details}{specific details (Sec.~}{)}{sec:oxsext}.
To send output from \app{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
\btn{Send} button.  The initial output configuration is set by
\htmlonlyref{\cd{Destination}}{html:destinationCmd} and
\htmlonlyref{\cd{Schedule}}{html:scheduleCmd} commands in the input
\MIF\ file\latex{ (Sec.~\ref{sec:mif2ExtensionCommands})}.

Outputs fall under two general categories: scalar (single-valued)
outputs and vector field outputs.  The scalar outputs are grouped
together as the \cd{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 \cd{DataTable} entry is selected, the Destination box will
list all \OOMMF\ applications accepting datatable-style input, i.e., all
currently running
\hyperrefhtml{\app{mmDataTable}}{\app{mmDataTable}
(Sec.~}{)}{sec:mmdatatable}\index{application!mmDataTable},
\hyperrefhtml{\app{mmGraph}}{\app{mmGraph}
(Sec.~}{)}{sec:mmgraph}\index{application!mmGraph}, and
\hyperrefhtml{\app{mmArchive}}{\app{mmArchive}
(Sec.~}{)}{sec:mmarchive}\index{application!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
\hyperrefhtml{\app{mmDisp}}{\app{mmDisp}
(Sec.~}{)}{sec:mmdisp}\index{application!mmDisp} and
\hyperrefhtml{\app{mmArchive}}{\app{mmArchive}
(Sec.~}{)}{sec:mmarchive}\index{application!mmArchive}.  Caution is
advised when scheduling vector field output, especially with large
problems, because the output may run many megabytes.

\ssechead{Controls}
The \btn{File} menu button holds five entries: Load, Show Console, Close
Interface, Clear Schedule and Exit Oxsii.  \btn{File\pipe Load\ldots}
launches a dialog box that allows the user to select an input \MIF\
problem description file.  \btn{File\pipe Show~Console} brings up a
\Tcl\ shell console running off the \app{Oxsii} interface \Tcl\
interpreter.  This console is intended primary for debugging purposes.
In particular, output from
\MIF\ \htmlonlyref{Report}{html:MifReport} commands%
\latex{ (Sec.~\ref{sec:mif2ExtensionCommands})}
may be viewed here.  \btn{File\pipe Close Interface} will remove the
interface window from the display, but leaves the solver running.  This
effect may also be obtained by deselecting the
\app{Oxsii} interface button in the \btn{Threads} list in
\htmlref{\app{mmLaunch}}{sec:mmlaunch}.
\btn{File\pipe 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,
\btn{File\pipe Exit Oxsii}, terminates the \app{Oxsii} solver and closes the
interface window.

\arblink{html:oxsiirestartflag}
The \btn{Options} menu holds two entries: Clear Schedule 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 \cd{Schedule} commands
in the MIF file.  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 restart (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 \cd{File\pipe Load} dialog box, or from the
command line.
\latex{See the Oxs\_Driver documentation, Sec.~\ref{sec:oxsDrivers}
page~\pageref{html:oxsdrivercheckpoint}, for information on checkpoint
files.}
\html{See the Oxs\_Driver documentation for information on
\htmlref{checkpoint files.}{html:oxsdrivercheckpoint}}

The \btn{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, \btn{Reload}, re-reads the most recent
problem \MIF\ input file, re-initializes the solver, and pauses.
\btn{Reset} is similar, except the file is not re-read.  The remaining
four buttons, \btn{Run},
\btn{Relax}, \btn{Step} and \btn{Pause} place the solver into one of
four \textit{run-states}.  In the Pause state, the solver sits idle
awaiting further instructions.  If \btn{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 \cd{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.

\ssechead{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
\hyperrefhtml{Oxs\_Ext classes}{Oxs\_Ext classes (Sec.~}{)}{sec:oxsext}.
Refer to the appropriate Oxs\_Ext class documentation for simulation and
computational details.

%\ssechead{Known Bugs}
%\index{platform!Windows!network socket bug|(}
%A bug in the network traffic handling code\index{network~socket} of
%\Tcl\ on \Windows~9X systems can sometimes interfere
%with communications between the control interface of \app{Oxsii} and
%the actual computation engine.  If \app{Oxsii} is sending out data
%to two or more data display services every iteration, the network
%traffic from that data can ``crowd out'' the receipt of
%control messages from the control interface.  You may observe this as a
%long delay between the time you click the \btn{Pause} button and the
%time the solver stops iterating.  This bug first appeared in \Tcl\
%release 8.0.3, and remained through \Tcl\ release 8.1.1.  It is fixed in
%\Tcl\ releases 8.2 and later, which we recommend for \OOMMF\ users on
%\Windows~9X systems.  Other platforms do not have this problem.
%\index{platform!Windows!network socket bug|)}

%If \Tcl\ version 7.5 is in use, and \app{Oxsii} processes
%a \cd{Destination} command in a \MIF\ file, and in response
%launches another application, then \app{Oxsii} will not be
%able to fully terminate until the launched application also
%terminates.  You might notice this in \app{mmLaunch} where
%an \app{Oxsii} will remain in the \btn{Threads}\index{threads} column
%long after it has apparently exited.  This glitch is due to a
%bug in Tcl's \cd{exec} command in version 7.5 that has long
%been fixed.  Use a more recent Tcl release to avoid the problem.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{OOMMF eXtensible Solver Batch Interface: boxsi}\label{sec:boxsi}%
\index{simulation~3D!batch}\index{application!boxsi}

\begin{center}
\includepic{boxsi-ss}{boxsi Screen Shot}
\end{center}

\ssechead{Overview}
The application \app{Boxsi} provides a batch mode interface to the Oxs
micromagnetic computation engine.  A restricted graphical interface is
provided, but \app{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 \hyperrefhtml{\OOMMF\ architecture}{\OOMMF\ architecture (see
Sec.~}{)}{sec:arch}, \app{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.
\app{Boxsi} is the server of a solver control service for which the only
client is \hyperrefhtml{\app{mmLaunch}}{\app{mmLaunch}
(Sec.~}{)}{sec:mmlaunch}\index{application!mmLaunch}.  It is through
this service that \app{mmLaunch} provides a user interface window (shown
above) on behalf of \app{Boxsi}.

A micromagnetic problem is communicated to \app{Boxsi} through a
\htmlref{\MIF~2 file}{sec:mif2format} specified on the command line
and loaded from disk.  The \MIF~1.x formats are also accepted; they are
converted to the \MIF~2 format by an automatic call to
\hyperrefhtml{\app{mifconvert}}{\app{mifconvert}
(Sec.~}{)}{sec:mifconvert}.

\ssechead{Launching}
\app{Boxsi} must be started from the command line.  The syntax is
\begin{verbatim}
tclsh oommf.tcl boxsi [standard options] [-exitondone <0|1>] [-kill tags] \
   [-logfile logname] [-loglevel level] [-nice <0|1>] [-nocrccheck <0|1>] \
   [-numanodes nodes] [-outdir dir] [-parameters params] [-pause <0|1>] \
   [-regression_test flag] [-regression_testname basename] \
   [-restart <0|1|2>] [-restartfiledir dir] [-threads count] miffile
\end{verbatim}
where
\begin{description}
\item[\optkey{-exitondone \boa 0\pipe 1\bca}]
  Whether to exit after solution of the problem is complete, or to
  await the interactive selection of the \btn{File\pipe Exit} command.
  The default is 1, i.e., automatically exit when done.
\item[\optkey{-kill tags}]
  On termination, sends requests to other applications to
  shutdown too.  The \textit{tags} argument should be either
  a list of destination tags (which are declared by
  \htmlonlyref{\cd{Destination} commands}{html:destinationCmd}\latex{,
  Sec.~\ref{sec:mif2ExtensionCommands}}) from the input \MIF\
  file, or else the keyword \cd{all}, which is interpreted to mean all
  the destination tags.
\item[\optkey{-logfile logname}]
  Write log and error messages to file \textit{logname}.  The default log
  file is \fn{oommf/boxsi.errors}.
\item[\optkey{-loglevel level}]
  Controls the detail level of log messages, with larger values of
  \textit{level} producing more output.  Default value is 1.
\item[\optkey{-nice \boa 0\pipe 1\bca}]
  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.
\item[\optkey{-nocrccheck \boa 0\pipe 1\bca}]
  On simulation restarts, the CRC
  \hyperrefhtml{CRC}{CRC (Sec.~}{)}{sec:crc32}
  of the \MIF\ file is normally compared against the CRC of the original
  \MIF\ file as recorded in the restart file.  If the CRCs don't match then
  an error is thrown to alert the user that the \MIF\ file has changed.  If
  this option is enabled (i.e., 1) then the check is disabled.
\item[\optkey{-numanodes \boa nodes\bca}]\index{NUMA|(}
  \index{parallelization}
  This option is available on
  \hyperrefhtml{NUMA-aware}{NUMA-aware (Sec.~}{)}{sec:parallel} builds of
  Oxs.  The \textit{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 insure there are no spaces in the list, or else protect the
  spaces with outlying quotes.  For example, \cd{-numanodes 2,4,6} or
  \cd{-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 \app{Boxsi} process, or may restrict \app{Boxsi}
  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
  \app{Boxsi}).  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 \app{Boxsi}, 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 \app{Boxsi}
  instance.  See also the discussion on \htmlonlyref{threading
  considerations}{html:threadconsider} below.

  The default value for \textit{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 \app{Boxsi}, then \app{Boxsi} will
  likely run fastest if the thread count is set to the number of
  processing cores on the machine, and \textit{nodes} is set to
  ``auto''.  If you want to run multiple copies of \app{Boxsi}
  simultaneously, or run \app{Boxsi} in parallel with some other
  application(s), then set the thread count to a number smaller than
  the number of processing cores and restrict \app{Boxsi} to some
  subset of the memory nodes with the \cd{-numanodes} option and an
  explicit nodes list.

  The default behavior is modified (in increasing order of priority) by the
  \cd{numanodes} setting in the active \fn{oommf/config/platform/} platform
  file, by the \cd {numanodes} setting in the \fn{oommf/config/options.tcl}
  or \fn{oommf/config/local/options.tcl} file, or by the environment variable
  \cd{OOMMF\_NUMANODES}\index{environment~variables!OOMMF\_NUMANODES}.  The
  \cd{-numanodes} command line option, if any, overrides all.\index{NUMA|)}
\item[\optkey{-outdir dir}]
  Specifies the directory where output files are written by
  \app{mmArchive}.  This option is useful when the default output
  directory is inaccessible or slow. The environment variable
  \cd{OOMMF\_OUTDIR}\index{environment~variables!OOMMF\_OUTDIR} sets the
  default output directory.  If \cd{OOMMF\_OUTDIR} is set to the empty
  string, or not set at all, then the default is the directory holding
  the \MIF\ file.
\item[\optkey{-parameters params}]
  Sets \hyperrefhtml{\MIF~2}{\MIF~2 (Sec.~}{)}{sec:mif2format} file
  parameters.  The \textit{params} argument should be a list with an
  even number of arguments, corresponding to name + value pairs.  Each
  ``name'' must appear in a
  \htmlonlyref{\cd{Parameter}}{html:mif2parameter}
  statement\latex{ (Sec.~\ref{sec:mif2ExtensionCommands})} in the input
  \MIF\ file.  The entire name + value list must be quoted so it is
  presented to \app{Boxsi} as a single item on the command line.  For
  example, if \cd{A} and \cd{Ms} appeared in \cd{Parameter} statements
  in the \MIF\ file, then an option like
\begin{verbatim}
   -parameters "A 13e-12 Ms 800e3"
\end{verbatim}
  could be used to set \cd{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.
\item[\optkey{-pause \boa 0\pipe 1\bca}]
  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.
\item[\optkey{-regression\_test flag}]
  This option is used internally by the 
  \hyperrefhtml{\app{oxsregression}}{\app{oxsregression} (Sec.~}{)}{sec:oxsregression}
  command line utility to run regression tests.  Default value is 0 (no
  test).
\item[\optkey{-regression\_testname basename}]
  This option is used internally by the 
  \hyperrefhtml{\app{oxsregression}}{\app{oxsregression} (Sec.~}{)}{sec:oxsregression}
  command line utility to control temporary file names during regression
  testing.
\item[\optkey{-restart \boa 0\pipe 1\pipe 2\bca\index{simulation~3D!restarting}}]
  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.
  \latex{See the Oxs\_Driver documentation, Sec.~\ref{sec:oxsDrivers}
  page~\pageref{html:oxsdrivercheckpoint}, for information on checkpoint
  files.}
  \html{See the Oxs\_Driver documentation for information on
  \htmlref{checkpoint files.}{html:oxsdrivercheckpoint}}
\item[\optkey{-restartfiledir dir}]
  Specifies the directory where restart files are written.
  The default is determined by the environment variable
  \cd{OOMMF\_RESTARTFILEDIR}\index{environment~variables!OOMMF\_RESTARTFILEDIR},
  or if this is not set then by
  \cd{OOMMF\_OUTDIR}\index{environment~variables!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.
\item[\optkey{-threads \boa count\bca}]
  \index{parallelization}
  The option is available on
  \hyperrefhtml{threaded}{threaded (Sec.~}{)}{sec:parallel} builds of Oxs.
  The \textit{count} parameter is the number of threads to run.  The
  default count value is set by the \cd{oommf\_thread\_count} value in
  the \fn{config/platforms/} file for your platform, but may be
  overridden by the
  \cd{OOMMF\_THREADS}\index{environment~variables!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 \cd{tclsh oommf.tcl +platform}.
\item[\optkey{miffile}]
  Load and solve the problem found in {\em miffile}, which must be
  either in the \MIF~2 format, or convertible to that format by 
  \htmlref{\app{mifconvert}}{sec:mifconvert}.  Required.
\end{description}

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

\ssechead{Inputs}
\app{Boxsi} loads problem specifications directly from disk as
requested on the command line.  The format for these files is
the \hyperrefhtml{\MIF~2}{\MIF~2 (Sec.~}{)}{sec:mif2format} format,
the same as used by the \app{Oxsii} interactive interface.  The
\htmlref{\MIF~1.1}{sec:mif1format} and
\htmlref{\MIF~1.2}{sec:mif12format}
formats used by the
2D solver \htmlonlyref{\app{mmSolve2D}}{sec:mmsolve2d} can also be input
to \app{Boxsi}, which will automatically call the command line tool
\hyperrefhtml{\app{mifconvert}}{\app{mifconvert}
(Sec.~}{)}{sec:mifconvert} to convert from the \MIF~1.x format to the
\MIF~2 format ``on-the-fly.''  Sample \MIF~2 files can be found in
the directory \cd{oommf/app/oxs/examples}.

\ssechead{Outputs}
The lower panel of the \app{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 \app{Oxsii}
user interface; refer to the
\htmlonlyref{\app{Oxsii} documentation}{html:oxsiioutputs}\latex{
(Sec.~\ref{sec:oxsii})} for details.
The only difference between \app{Boxsi} and \app{Oxsii} with
respect to outputs is that in practice \app{Boxsi} tends to rely
primarily on
\htmlonlyref{\cd{Destination}}{html:destinationCmd} and
\htmlonlyref{\cd{Schedule}}{html:scheduleCmd} commands in the input
\MIF\ file\latex{ (Sec.~\ref{sec:mif2ExtensionCommands})}
to setup the output configuration.  The interactive output interface is
used for incidental runtime monitoring of the job.

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

The \btn{File} menu holds 4 entries: Show Console, Close
Interface, Clear Schedule, and Exit Oxsii.  \btn{File\pipe Show~Console}
brings up a
\Tcl\ shell console running off the \app{Boxsi} interface \Tcl\
interpreter.  This console is intended primary for debugging purposes.
\btn{File\pipe Close Interface} will remove the interface window from
the display, but leaves the solver running.  This effect may also be
obtained by deselecting the
\app{Boxsi} interface button in the \btn{Threads} list in
\htmlref{\app{mmLaunch}}{sec:mmlaunch}.
\btn{File\pipe 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,
\btn{File\pipe Exit Boxsi}, terminates the \app{Boxsi} solver and closes the
interface window.  Note that there is no \btn{File\pipe Load\ldots}
menu item; the problem specification file must be declared on the
\app{Boxsi} command line.

The \btn{Help} menu provides the usual help facilities.

The row of buttons immediately below the menu bar provides simulation
progress control.  These buttons\emdash\btn{Run}, \btn{Relax},
\btn{Step} and \btn{Pause}\emdash 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 \btn{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 \cd{-exitondone} command line option.

Normally the solver progresses automatically from problem initialization
into Run mode, but this can be changed by the \cd{-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.

\ssechead{Details}
As with \app{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
\hyperrefhtml{Oxs\_Ext classes}{Oxs\_Ext classes (Sec.~}{)}{sec:oxsext}.
Refer to the appropriate Oxs\_Ext class documentation for simulation and
computational details.

\ssechead{Threading considerations\label{html:threadconsider}}
\index{parallelization|(}\index{NUMA|(}
As an example, suppose you are running on a four dual-core processor
box, where each of the four processors is connected to a separate memory
node.  In other words, there are eight cores in total, and each pair of
cores shares a memory node.  Further assume that the processors are
connected via point-to-point links such as AMD's HyperTransport or
Intel's QuickPath Interconnect.

If you want to run a single instance of \app{Boxsi} as quickly as
possible, you might use the \cd{-threads 8} option, which, assuming the
default value of \cd{-numanodes none} is in effect, would allow the
operating system to schedule the eight threads among the system's eight
cores as it sees fit.  Or, you might reduce the thread count to reserve
one or more cores for other applications.  If the job is long running,
however, you may find that the operating system tries to run multiple
threads on a single core\emdash perhaps in order to leave other cores idle so
that they can be shut down to save energy.  Or, the operating system may
move threads away from the memory node where they have allocated memory,
which effectively reduces memory bandwidth.  In such cases you might want
to launch \app{Boxsi} with the \cd{-numanodes auto} option.  This
overrides the operating systems preferences, and ties threads to
particular memory nodes for the lifetime of the process.  (On Linux
boxes, you should also check the ``cpu frequency governor'' and ``huge page
support'' selection and settings.)

If you want to run two instances of \app{Boxsi} concurrently, you might
launch each with the \cd{-threads 4} option, so that each job has four
threads for the operating system to schedule.  If you don't like the
default scheduling by the operating system, you can use the
\cd{-numanodes} option, but what you \textbf{don't} want to do is launch
two jobs with \cd{-numanodes auto}, because the ``auto'' option assigns
threads to memory nodes from a fixed sequence list, so both jobs will be
assigned to the same nodes.  Instead, you should manually assign the
nodes, with a different set to each job.  For example, you may launch
the first job with \cd{-numanodes 0,1} and the second job with
\cd{-numanodes 2,3}.  One point to keep in mind when assigning nodes is
that some node pairs are ``closer'' (with respect to memory latency and
bandwidth) than others.  For example, memory node 0 and memory node 1
may be directly connected via a point-to-point link, so that data can be
transferred in a single ``hop.''  But sending data from node 0 to node 2
may require two hops (from node 0 to node 1, and then from node 1 to
node 2).  In this case \cd{-numanodes 0,1} will probably run faster than
\cd{-numanodes 0,2}.

The \cd{-numanodes} option is only available on Linux boxes if the
``numactl'' and ``numactl-devel'' packages are installed.  The
\cd{numactl} command itself can be used to tie jobs to particular memory
nodes, similar to the \cd{boxsi -numanodes} option, except that
\cd{-numanodes} ties threads whereas \cd{numactl} ties jobs.  The
\cd{numactl --hardware} command will tell you how many memory nodes are
in the system, and also reports a measure of the (memory latency and
bandwidth) distance between nodes.  This information can be used in
selecting nodes for the \cd{boxsi -numanodes} option, but in
practice the distance information reported by \cd{numactl} is often not
reliable.  For best results one should experiment with different
settings, or run memory bandwidth tests with different node
pairs.\index{NUMA|)}\index{parallelization|)}

\ssechead{Batch Scheduling Systems}
\OOMMF\ jobs submitted to a batch queuing system (e.g., Condor, PBS,
NQS) can experience sporadic failures caused by interactions between
separate \OOMMF\ jobs running simultaneously on the same compute
node.  These problems can be prevented by using the \OOMMF\ command
line utility
\hyperrefhtml{\app{launchhost}}{\app{launchhost} (Sec.~}{)}{sec:launchhost}
to isolate each job.

%\ssechead{Known Bugs}
%\index{platform!Windows!network socket bug|(}
%\app{Boxsi} suffers from the same \Windows~9X \Tcl\ network traffic bug
%as \app{Oxsii}.  \OOMMF\ users on \Windows~9X systems are encouraged to
%upgrade to \Tcl~8.2 or later.
%\index{platform!Windows!network socket bug|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Standard Oxs\_Ext Child Classes}\label{sec:oxsext}%
\index{Oxs\_Ext~child~classes}
An Oxs simulation is built as a collection of \cd{Oxs\_Ext} (Oxs
Extension) objects.  These are defined via Specify blocks in the input
\hyperrefhtml{\MIF~2 file.}{\MIF~2 file (Sec.~}{).}{sec:mif2format}
The reader will find the information and
\hyperrefhtml{sample \MIF\ file}{sample \MIF\ file,
Fig.~}{,}{fig:mif2sample} provided in that section to be a helpful
adjunct to the material presented below.  Addition example \MIF~2
files can be found in the directory \fn{oommf/app/oxs/examples}.

This section describes the \cd{Oxs\_Ext} classes available in the
standard \OOMMF\ distribution, including documentation of their Specify
block initialization strings, and a list of some sample \MIF\ files from
the \fn{oommf/app/oxs/examples} directory that use the class.  The
standard \cd{Oxs\_Ext} objects, i.e., those that are distributed with
\OOMMF, can be identified by the \cd{Oxs\_} prefix in their names.
Additional \cd{Oxs\_Ext} classes may be available on your system.  Check
local documentation for details.

% NOTE: The html links hardcoded into the <PRE> sections below assume
% the anchors are on the same html page.  This will have to be reworked
% if (when?) we decide to break this section into multiple pages.
In the following presentation, the \cd{Oxs\_Ext} classes are organized
into 8 categories: atlases, meshes, energies, evolvers, drivers, scalar
field objects, vector field objects, and \MIF\ support classes.  The
following \cd{Oxs\_Ext} classes are currently available:
\begin{itemize}
%begin{latexonly}
\newlength{\tabcolwidth}
\settowidth{\tabcolwidth}{\tt Oxs\_AffineTransformVectorField}
\addtolength{\tabcolwidth}{3em}
\setlength{\parskip}{0pt}
\setlength{\topsep}{0pt}
%end{latexonly}
\item Atlases
  %begin{latexonly}
   {\tt\begin{tabbing}
   \hspace*{\tabcolwidth}\=\kill
      Oxs\_BoxAtlas    \>  Oxs\_ImageAtlas \\
      Oxs\_MultiAtlas  \>  Oxs\_ScriptAtlas \\
      Oxs\_EllipsoidAtlas
   \end{tabbing}}
  %end{latexonly}
  \begin{rawhtml}
<PRE>
   <A HREF="#BA">Oxs_BoxAtlas</A>                    <A HREF="#IA">Oxs_ImageAtlas</A>
   <A HREF="#MA">Oxs_MultiAtlas</A>                  <A HREF="#SA">Oxs_ScriptAtlas</A>
   <A HREF="#EA">Oxs_EllipsoidAtlas</A>
</PRE>
  \end{rawhtml}
\item Meshes
  %begin{latexonly}
  {\samepage\tt
   \begin{tabbing}
   \hspace*{\tabcolwidth}\=\kill
      Oxs\_RectangularMesh     \>    Oxs\_PeriodicRectangularMesh
   \end{tabbing}}
  %end{latexonly}
  \begin{rawhtml}
<PRE>
   <A HREF="#RM">Oxs_RectangularMesh</A>            <A HREF="#PRM">Oxs_PeriodicRectangularMesh</A>
</PRE>
  \end{rawhtml}
\item Energies
  %begin{latexonly}
   {\tt\begin{tabbing}
   \hspace*{\tabcolwidth}\=\kill
      Oxs\_CubicAnisotropy     \>    Oxs\_Demag              \\
      Oxs\_Exchange6Ngbr       \>    Oxs\_ExchangePtwise     \\
      Oxs\_FixedZeeman         \>    Oxs\_RandomSiteExchange \\
      Oxs\_ScriptUZeeman       \>    Oxs\_SimpleDemag        \\
      Oxs\_StageZeeman         \>    Oxs\_TransformZeeman    \\
      Oxs\_TwoSurfaceExchange  \>    Oxs\_UniaxialAnisotropy \\
      Oxs\_UniformExchange     \>    Oxs\_UZeeman
   \end{tabbing}}
  %end{latexonly}
  \begin{rawhtml}
<PRE>
   <A HREF="#CA">Oxs_CubicAnisotropy</A>             <A HREF="#DE">Oxs_Demag</A>
   <A HREF="#E6">Oxs_Exchange6Ngbr</A>               <A HREF="#EP">Oxs_ExchangePtwise</A>
   <A HREF="#FZ">Oxs_FixedZeeman</A>                 <A HREF="#SE">Oxs_RandomSiteExchange</A>
   <A HREF="#SU">Oxs_ScriptUZeeman</A>               <A HREF="#SD">Oxs_SimpleDemag</A>
   <A HREF="#SZ">Oxs_StageZeeman</A>                 <A HREF="#TZ">Oxs_TransformZeeman</A>
   <A HREF="#TS">Oxs_TwoSurfaceExchange</A>          <A HREF="#UA">Oxs_UniaxialAnisotropy</A>
   <A HREF="#UE">Oxs_UniformExchange</A>             <A HREF="#UZ">Oxs_UZeeman</A>
</PRE>
  \end{rawhtml}
\item Evolvers
  %begin{latexonly}
   {\tt\begin{tabbing}
   \hspace*{\tabcolwidth}\=\kill
      Oxs\_CGEvolve            \>    Oxs\_EulerEvolve  \\
      Oxs\_RungeKuttaEvolve    \>    Oxs\_SpinXferEvolve
   \end{tabbing}}
  %end{latexonly}
  \begin{rawhtml}
<PRE>
   <A HREF="#CG">Oxs_CGEvolve</A>                    <A HREF="#EE">Oxs_EulerEvolve</A>
   <A HREF="#RK">Oxs_RungeKuttaEvolve</A>            <A HREF="#SX">Oxs_SpinXferEvolve</A>
</PRE>
  \end{rawhtml}
\item Drivers
  %begin{latexonly}
   {\tt\begin{tabbing}
   \hspace*{\tabcolwidth}\=\kill
      Oxs\_MinDriver           \>    Oxs\_TimeDriver
   \end{tabbing}}
  %end{latexonly}
  \begin{rawhtml}
<PRE>
   <A HREF="#MD">Oxs_MinDriver</A>                  <A HREF="#TD">Oxs_TimeDriver</A>
</PRE>
  \end{rawhtml}
\item Scalar Field Objects
  %begin{latexonly}
   {\tt\begin{tabbing}
   \hspace*{\tabcolwidth}\=\kill
      Oxs\_AtlasScalarField          \>  Oxs\_LinearScalarField       \\
      Oxs\_RandomScalarField         \>  Oxs\_ScriptScalarField       \\
      Oxs\_UniformScalarField        \>  Oxs\_VecMagScalarField       \\
      Oxs\_ScriptOrientScalarField   \>  Oxs\_AffineOrientScalarField \\
      Oxs\_AffineTransformScalarField \> Oxs\_ImageScalarField
   \end{tabbing}}
  %end{latexonly}
  \begin{rawhtml}
<PRE>
   <A HREF="#ASF">Oxs_AtlasScalarField</A>           <A HREF="#LSF">Oxs_LinearScalarField</A>
   <A HREF="#RSF">Oxs_RandomScalarField</A>          <A HREF="#SSF">Oxs_ScriptScalarField</A>
   <A HREF="#USF">Oxs_UniformScalarField</A>         <A HREF="#VMSF">Oxs_VecMagScalarField</A>
   <A HREF="#SOSF">Oxs_ScriptOrientScalarField</A>    <A HREF="#AOSF">Oxs_AffineOrientScalarField</A>
   <A HREF="#ATSF">Oxs_AffineTransformScalarField</A> <A HREF="#ISF">Oxs_ImageScalarField</A>
</PRE>
  \end{rawhtml}
\item Vector Field Objects
  %begin{latexonly}
   {\tt\begin{tabbing}
   \hspace*{\tabcolwidth}\=\kill
   Oxs\_AtlasVectorField             \>  Oxs\_FileVectorField         \\
   Oxs\_PlaneRandomVectorField       \>  Oxs\_RandomVectorField       \\
   Oxs\_ScriptVectorField            \>  Oxs\_UniformVectorField      \\
   Oxs\_ScriptOrientVectorField      \>  Oxs\_AffineOrientVectorField \\
   Oxs\_AffineTransformVectorField   \>  Oxs\_MaskVectorField         \\
   Oxs\_ImageVectorField
   \end{tabbing}}
  %end{latexonly}
  \begin{rawhtml}
<PRE>
   <A HREF="#AVF">Oxs_AtlasVectorField</A>           <A HREF="#FVF">Oxs_FileVectorField</A>
   <A HREF="#PRVF">Oxs_PlaneRandomVectorField</A>     <A HREF="#RVF">Oxs_RandomVectorField</A>
   <A HREF="#SVF">Oxs_ScriptVectorField</A>          <A HREF="#UVF">Oxs_UniformVectorField</A>
   <A HREF="#SOVF">Oxs_ScriptOrientVectorField</A>    <A HREF="#AOVF">Oxs_AffineOrientVectorField</A>
   <A HREF="#ATVF">Oxs_AffineTransformVectorField</A> <A HREF="#MVF">Oxs_MaskVectorField</A>
   <A HREF="#IVF">Oxs_ImageVectorField</A>
</PRE>
  \end{rawhtml}
\item \MIF\ Support Classes
  %begin{latexonly}
   {\tt\begin{tabbing}
   \hspace*{\tabcolwidth}\=\kill
      Oxs\_LabelValue
   \end{tabbing}}
  %end{latexonly}
  \begin{rawhtml}
<PRE>
   <A HREF="#LV">Oxs_LabelValue</A>
</PRE>
  \end{rawhtml}
\end{itemize}

\subsubsection{Atlases\label{sec:oxsAtlases}}
Geometric volumes of spaces are specified in Oxs via \textit{atlases},
which divide their domain into one or more disjoint subsets called
\textit{regions}.  Included in each atlas definition is the atlas
\textit{bounding box}, which is an axes parallel rectangular
parallelepiped containing all the regions.  There is also the special
\textit{universe} region, which consists of all points outside the
regions specified in the atlas.  The universe region is not considered
to be part of any atlas, and the \cd{universe} keyword should not be
used to label any of the atlas regions.

The most commonly used atlas is the simple \cd{Oxs\_BoxAtlas}.  For
combining multiple atlases, use \cd{Oxs\_MultiAtlas}.

\begin{description}
\begin{rawhtml}<A NAME="BA"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_BoxAtlas}%
\item[Oxs\_BoxAtlas:]
An axes parallel rectangular parallelepiped,
containing a single region that is coterminous with the atlas itself.
The specify block has the form
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_BoxAtlas:\oxsval{atlasname} \ocb\\
\bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
\bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
\bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
\bi name \oxsval{regionname}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_BoxAtlas:</TT><I>atlasname</I> <TT>{</TT>
<DD><TT>xrange {</TT> <I>xmin</I><TT>&nbsp;</TT><I>xmax</I> <TT>}</TT>
<DD><TT>yrange {</TT> <I>ymin</I><TT>&nbsp;</TT><I>ymax</I> <TT>}</TT>
<DD><TT>zrange {</TT> <I>zmin</I><TT>&nbsp;</TT><I>zmax</I> <TT>}</TT>
<DD><TT>name </TT> <I>regionname</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
where \oxsval{xmin, xmax, \ldots} are coordinates in meters, specifying
the extents of the volume being defined.  The \oxsval{regionname} label
specifies the name assigned to the region contained in the atlas.  The
\oxslabel{name} entry is optional; if not specified then the
region name is taken from the object instance name, i.e.,
\oxsval{atlasname}.

\textbf{Examples:} \fn{sample.mif}, \fn{cgtest.mif}.

\begin{rawhtml}<A NAME="IA"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_ImageAtlas}%
\item[Oxs\_ImageAtlas:\label{html:oxsImageAtlas}]%
\index{file!mask|(}\index{file!bitmap|(}
This class is designed to allow an image file
to be used to define regions in terms of colors in the image.  It is
intended for use in conjunction with the \cd{Oxs\_AtlasScalarField} and
\cd{Oxs\_AtlasVectorField} classes in circumstances where a small
number of distinct species (materials) are being modeled.  This provides
a generalization of the \htmlonlyref{mask file}{sec:partgeometry}
functionality of the 2D solver\latexonly{
(Sec.~\ref{sec:partgeometry})}.

For situations requiring continuous variation in material parameters,
the script field classes should be used in conjunction with the
\cd{ReadFile} \MIF\ extension command.  See the
\cd{ColorField} sample proc in the \htmlonlyref{\cd{ReadFile}
documentation}{html:ReadFile} \latex{in
Sec.~\ref{sec:mif2ExtensionCommands}} for an example of this
technique.

The \cd{Oxs\_ImageAtlas} Specify block has the following form:
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_ImageAtlas:\oxsval{name} \ocb\\
\bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
\bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
\bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
\bi viewplane \oxsval{view}\\
\bi image \oxsval{pic}\\
\bi colormap \ocb\oxsval{\\
\bi \bi color-1 region\_name\\
\bi \bi color-2 region\_name\\
\bi \bi \ldots\\
\bi \bi color-n region\_name}\\
\bi\ccb\\
\bi matcherror \oxsval{max\_color\_distance}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_ImageAtlas:</TT><I>name</I> <TT>{</TT>
<DD><TT>xrange {</TT> <I>xmin</I><TT>&nbsp;</TT><I>xmax</I> <TT>}</TT>
<DD><TT>yrange {</TT> <I>ymin</I><TT>&nbsp;</TT><I>ymax</I> <TT>}</TT>
<DD><TT>zrange {</TT> <I>zmin</I><TT>&nbsp;</TT><I>zmax</I> <TT>}</TT>
<DD><TT>viewplane </TT> <I>view</I>
<DD><TT>image </TT> <I>pic</I>
<DD><TT>colormap {</TT><DL>
   <DD><I>color-1</I><TT>&nbsp;</TT><I>region_name</I>
   <DD><I>color-2</I><TT>&nbsp;</TT><I>region_name</I>
   <DD> ...
   <DD><I>color-n</I><TT>&nbsp;</TT><I>region_name</I>
</DL><TT>}</TT>
<DD><TT>matcherror </TT> <I>max_color_distance</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
The \oxslabel{xrange}, \oxslabel{yrange}, \oxslabel{zrange} entries
specify the extent of the atlas, in meters.  The \oxslabel{viewplane}
\oxsval{view} value should be one of the three two-letter codes \cd{xy},
\cd{zx} or \cd{yz}, which specify the mapping of the horizontal and
vertical axes of the image respectively to axes in the simulation.  The
image is scaled as necessary along each dimension to match the atlas
extents along the corresponding axes.  The image is overlaid through the
entire depth of the perpendicular dimension, i.e., along the axis absent
from the \cd{viewplane} specification.  The
\cd{Oxs\_ImageAtlas} class can be used inside a
\cd{Oxs\_MultiAtlas} object to specify regions in a multilayer
structure.

The \oxslabel{image} entry specifies the name of the image file to use.
If the file path is relative, then it will be taken with respect to the
directory containing the \MIF\ file.  The image format may be any of
those recognized by \hyperrefhtml{\cd{any2ppm}}{\cd{any2ppm}
(Sec.~}{)}{sec:any2ppm}.  The file will be read directly by Oxs if it is
in the P3 or P6 PPM formats, otherwise \cd{any2ppm} will be
automatically launched to perform the conversion.

The \oxslabel{colormap} value is an even length list of color + region
name pairs.  The colors may be specified in any of several ways.  The
most explicit is to use one of the \Tk\ numeric formats,
\lb rgb, \lb rrggbb, \lb rrrgggbbb or \lb rrrrggggbbbb, where
each r, g, and b is one hex digit (i.e., 0-9 or A-F) representing the
red, green and blue components of the color, respectively.  For example,
\lb F00 is bright (full-scale) red, \lb 800 would be a darker red, while
\lb FF0 and \lb FFFF00 would both be bright yellow.  Refer to the
\cd{Tk\_GetColor} documentation for details.  For shades of gray the
special notation \cd{grayD} or \cd{greyD} is available, where D is a
decimal value between 0 and 100, e.g., \cd{grey0} is black and
\cd{grey100} is white.  Alternatively, one may use any of the symbolic
names defined in the \fn{oommf/config/colors.config} file, such as
\cd{red}, \cd{white} and \cd{skyblue}.  When comparing symbolic names,
spaces and capitalization are ignored.  The list of symbolic names can
be extended by adding additional files to the \cd{Color filename} option
in the \fn{options.tcl} \hyperrefhtml{customization file}{customization
file (Sec.~}{)}{sec:custom}.  Finally, one \oxsval{color} in the
\cd{colormap} list may optionally be the special keyword ``default''.
All pixels that don't match any of the other specified colors (as
determined by the \cd{matcherror} option) are assigned to region
paired with \cd{default}.

Each of the specified colors should be distinct, but the region names
are allowed to be repeated as desired.  The region names may be chosen
arbitrarily, except the special keyword ``universe'' is reserved for
points not in any of the regions.  This includes all points outside the
atlas bounding box defined by the \cd{xrange}, \cd{yrange}, \cd{zrange}
entries, but may also include points inside that boundary.

Pixels in the image are assigned to regions by comparing the color of
the pixel to the list of colors specified in \cd{colormap}.  If the
pixel color is closer to a \cd{colormap} color than
\oxsval{max\_color\_distance}, then the colors are considered matched.
If a pixel color matches exactly one \cd{colormap} color, then the pixel
is assigned to the corresponding region.  If a pixel color matches more
than one \cd{colormap} color, the pixel is assigned to the region
corresponding to the closest match.  If a pixel color doesn't match any
of the \cd{colormap} colors, then it is assigned to the \textit{default
region}, which is the region paired with the ``default'' keyword.  If
\cd{default} does not explicitly appear in the \cd{colormap} colors
list, then \cd{universe} is made the default region.

To calculate the distance between two colors, each color is first
converted to a scaled triplet of floating point red, green, and blue
values, $(r,g,b)$, where each component lies in the interval $[0,1]$,
with $(0,0,0)$ representing black and $(1,1,1)$ representing white.  For
example, $(0,0,1)$ is bright blue.  Given two colors in this
representation, the distance is computed using the standard Euclidean
norm with uniform weights, i.e., the distance between $(r_1,g_1,b_1)$
and $(r_2,g_2,b_2)$ and is
\begin{displaymath}
\sqrt{(r_1-r_2)^2 + (g_1-g_2)^2 + (b_1-b_2)^2}.
\end{displaymath}
Since the difference in any one component is at most 1, the distance
between any two colors is at most \abovemath{\sqrt{3}}.

As explained above, two colors are considered to match if the distance
between them is less than the specified \oxslabel{matcherror} value.  If
\oxsval{max\_color\_distance} is sufficiently small, then it may easily
happen that a pixel's color does not match any of the specified region
colors, so the pixel would be assigned to the default region.  On the
other hand, if \oxsval{max\_color\_distance} is larger than
\abovemath{\sqrt{3}}, then all colors will match, and no pixels will be
assigned to the default region.  If \cd{matcherror} is not specified,
then the default value for \oxsval{max\_color\_distance} is 3, which
means all colors match.

The following example should help clarify these matters.
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_ImageAtlas:atlas {
    xrange { 0 400e-9 }
    yrange { 0 200e-9 }
    zrange { 0  20e-9 }
    image  mypic.gif
    viewplane "xy"
    colormap {
        blue   cobalt
        red    permalloy
        green  universe
        default cobalt
    }
    matcherror .1
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
Blue pixels get mapped to the ``cobalt'' region and red pixels
to the ``permalloy'' region.  Green pixels are mapped to the
``universe'' non-region, which means they are considered to be outside
the atlas entirely.  This is a fine point, but comes into
play when atlases with overlapping bounding boxes are brought together
inside an \cd{Oxs\_MultiAtlas}.  To which region would an orange pixel
be assigned?  The scaled triplet representation for orange is
$(1,0.647,0)$, so the distance to blue is $1.191$, the distance to red
is $0.647$, and the distance to green is $1.06$.  Thus the closest color
is red, but $0.647$ is outside the \cd{matcherror} setting of $0.1$, so
orange doesn't match any of the colors and is hence assigned to the
default region, which in this case is cobalt.  On the other hand, if
\cd{matcherror} had been set to say 1, then orange and red would match
and orange would be assigned to the permalloy region.

Pixels with colors that are equidistant to and match more than one color
in the colormap will be assigned to one of the closest color regions.
The user should not rely on any particular selection, that is to say,
the explicit matching procedure in this case is not defined.
\index{file!mask|)}\index{file!bitmap|)}

\textbf{Examples:} \fn{imageatlas.mif}, \fn{grill.mif}.

\begin{rawhtml}<A NAME="MA"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_MultiAtlas}%
\item[Oxs\_MultiAtlas:]
This atlas is built up as an ordered list of
other atlases.  The set of regions defined by the \cd{Oxs\_MultiAtlas}
is the union of the regions of all the atlases contained therein.  The
sub-atlases need not be disjoint, however each point is assigned to the
region in the first sub-atlas in the list that contains it, so the
regions defined by the \cd{Oxs\_MultiAtlas} are effectively disjoint.

The \cd{Oxs\_MultiAtlas} specify block has the form
\begin{latexonly}
{\samepage
\begin{quote}\tt
Specify Oxs\_MultiAtlas:\oxsval{name} \ocb\\
\bi atlas \ \ \oxsval{atlas\_1\_spec}\\
\bi atlas \ \ \oxsval{atlas\_2\_spec}\\
\bi\ldots\\
\bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
\bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
\bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
\ccb
\end{quote}}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_MultiAtlas:</TT><I>name</I> <TT>{</TT>
<DD> atlas &nbsp;&nbsp; <I>atlas_1_spec</I>
<DD> atlas &nbsp;&nbsp; <I>atlas_2_spec</I>
<DD> ...
<DD><TT>xrange {</TT> <I>xmin<TT>&nbsp;</TT>xmax</I> <TT>}</TT>
<DD><TT>yrange {</TT> <I>ymin<TT>&nbsp;</TT>ymax</I> <TT>}</TT>
<DD><TT>zrange {</TT> <I>zmin<TT>&nbsp;</TT>zmax</I> <TT>}</TT>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
Each \oxsval{atlas\_spec} may be either a reference to an atlas defined
earlier and outside the current Specify block, or else an inline,
embedded atlas definition.  The bounding box \oxslabel{xrange},
\oxslabel{yrange} and \oxslabel{zrange} specifications are each
optional.  If not specified the corresponding range for the atlas
bounding box is taken from the minimal bounding box containing all the
sub-atlases.

If the atlases are not disjoint, then the regions as defined by an
\cd{Oxs\_MultiAtlas} can be somewhat different from those of the
individual component atlases.  For example, suppose \cd{regionA} is a
rectangular region in \cd{atlasA} with corner points (5,5,0) and
(10,10,10), and \cd{regionB} is a rectangular region in \cd{atlasB} with
corner points (0,0,0) and (10,10,10).  When composed in the order
\cd{atlasA}, \cd{atlasB} inside an \cd{Oxs\_MultiAtlas}, \cd{regionA}
reported by the \cd{Oxs\_MultiAtlas} will be the same as \cd{regionA}
reported by \cd{atlasA}, but \cd{regionB} as reported by the
\cd{Oxs\_MultiAtlas} will be the ``L'' shaped volume of those points in
\cd{atlasB}'s \cd{regionB} not inside \cd{regionA}.  If the
\cd{Oxs\_MultiAtlas} is constructed with \cd{atlasB} first and
\cd{atlasA} second, then \cd{regionB} as reported by the
\cd{Oxs\_MultiAtlas} would agree with that reported by \cd{atlasB}, but
\cd{regionA} would be empty.

NOTE: The \htmlonlyref{\cd{attributes}}{par:specifyAttributes} key label
\latex{(cf.\ Sec.~\ref{par:specifyAttributes})} is not supported by this
class.

\textbf{Examples:} \fn{manyregions-multiatlas.mif}, \fn{spinvalve.mif},
\fn{spinvalve-af.mif}, \fn{yoyo.mif}.

\begin{rawhtml}<A NAME="SA"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_ScriptAtlas}%
\item[Oxs\_ScriptAtlas:]
An atlas where the regions are defined via a \Tcl\ script.  The specify
block has the form
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_ScriptAtlas:\oxsval{name} \ocb\\
\bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
\bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
\bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
\bi regions \ocb\oxsval{ rname\_1 rname\_2 \ldots\ rname\_n }\ccb\\
\bi script\_args \ocb\oxsval{ args\_request }\ccb\\
\bi script \oxsval{\Tcl\_script}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_ScriptAtlas:</TT><I>name</I> <TT>{</TT>
<DD><TT>xrange {</TT> <I>xmin<TT>&nbsp;</TT>xmax</I> <TT>}</TT>
<DD><TT>yrange {</TT> <I>ymin<TT>&nbsp;</TT>ymax</I> <TT>}</TT>
<DD><TT>zrange {</TT> <I>zmin<TT>&nbsp;</TT>zmax</I> <TT>}</TT>
<DD><TT>regions {</TT>
 <I>rname_1<TT>&nbsp;</TT>rname_2<TT>&nbsp;</TT>...<TT>&nbsp;</TT>rname_n</I>
 <TT>}</TT>
<DD><TT>script_args {</TT> <I>args_request</I> <TT>}</TT>
<DD><TT>script </TT> <I>Tcl_script</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
Here \oxsval{xmin, xmax, \ldots} are coordinates in meters, specifying
the extents of the axes-parallel rectangular parallelepiped enclosing
the total volume being identified.  This volume is subdivided
into \oxsval{n} sub-regions, using the names as given in the
\oxslabel{regions} list.  The \oxslabel{script} is used to assign
points to the various regions.  Appended to the script are the arguments
requested by \oxslabel{script\_args}, in the manner explained in the
\hyperrefhtml{User Defined Support Procedures}{User Defined Support
Procedures section (Sec.~}{)}{par:supportProcs}\html{ section} of the
\MIF~2 file format documentation.  The value \oxsval{args\_request}
should be a subset of \cd{\ocb relpt rawpt minpt maxpt span\ccb}.  If
\cd{script\_args} is not specified, the default value \cd{relpt} is
used.  When executed, the return value from the script should be an
integer in the range $1$ to $n$, indicating the user-defined region in
which the point lies, or else $0$ if the point is not in any
of the $n$ regions.  Region index $0$ is reserved for the implicit
``universe'' region, which is all-encompassing.  The following example
may help clarify the discussion:
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin{latexonly}
\begin{quote}
%end{latexonly}
\begin{verbatim}
proc Octs { cellsize x y z xmin ymin zmin xmax ymax zmax } {
    set xindex [expr {int(floor(($x-$xmin)/$cellsize))}]
    set yindex [expr {int(floor(($y-$ymin)/$cellsize))}]
    set zindex [expr {int(floor(($z-$zmin)/$cellsize))}]
    set octant [expr {1+$xindex+2*$yindex+4*$zindex}]
    if {$octant<1 || $octant>8} {
       return 0
    }
    return $octant
}

Specify Oxs_ScriptAtlas:octant {
    xrange {-20e-9 20e-9}
    yrange {-20e-9 20e-9}
    zrange {-20e-9 20e-9}
    regions { VIII V VII VI IV I III II }
    script_args { rawpt minpt maxpt }
    script { Octs 20e-9 }
}
\end{verbatim}
%begin{latexonly}
\end{quote}
%end{latexonly}
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
This atlas divides the rectangular volume between $(-20,-20,-20)$ and
$(20,20,20)$ (nm) into eight regions, corresponding to the standard
octants, I through VIII.  The \texttt{Octs} \Tcl\ procedure returns a
value between 1 and 8, with 1 corresponding to octant VIII and 8 to
octant II.  The canonical octant ordering starts with I as the
$+x,+y,+z$ space, proceeds counterclockwise in the $+z$ half-space, and
concludes in the $-z$ half-space with V directly beneath I, VI beneath
II, etc.  The ordering computed algorithmically in \texttt{Octs}
starts with 1 for the $-x,-y,-z$ space, 2 for the $+x,-y,-z$ space, 3
for the $-x,+y,-z$ space, etc.  The conversion between the two systems
is accomplished by the ordering of the \texttt{regions} list.

\textbf{Examples:} \fn{manyregions-scriptatlas.mif}, \fn{octant.mif},
\fn{tclshapes.mif}, \fn{diskarray.mif}, \fn{ellipsoid-atlasproc.mif}.

\begin{rawhtml}<A NAME="EA"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_EllipsoidAtlas}%
\item[Oxs\_EllipsoidAtlas:]
Defines an ellipsoidal region with axes parallel to the coordinate
axes.  This functionality can be obtained using the
\cd{Oxs\_ScriptAtlas} class with an appropriate \Tcl\ script, but this
class is somewhat easier to use and faster.  The Specify
block has the form
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_EllipsoidAtlas:\oxsval{atlasname} \ocb\\
\bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
\bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
\bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
\bi name \oxsval{regionname}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_EllipsoidAtlas:</TT><I>atlasname</I> <TT>{</TT>
<DD><TT>xrange {</TT> <I>xmin</I><TT>&nbsp;</TT><I>xmax</I> <TT>}</TT>
<DD><TT>yrange {</TT> <I>ymin</I><TT>&nbsp;</TT><I>ymax</I> <TT>}</TT>
<DD><TT>zrange {</TT> <I>zmin</I><TT>&nbsp;</TT><I>zmax</I> <TT>}</TT>
<DD><TT>name </TT> <I>regionname</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
Here \oxsval{xmin, xmax, \ldots} are coordinates in meters, specifying
the bounding box for the ellipsoid.  The layout of the Specify
block is exactly the same as for the \cd{Oxs\_BoxAtlas} class, except
that in this case the named region is not the whole bounding box but
rather that subvolume that is the interior of the ellipsoid inscribed
inside the bounding box.  Points exterior to that ellipsoid are
assigned to the ``universe'' region.

As in the \cd{Oxs\_BoxAtlas} case, the \oxsval{regionname} entry is
optional; if missing, the region name is taken from the object instance
name, i.e., \oxsval{atlasname}.

\begin{sloppypar}
\raggedright
\textbf{Example:} \fn{ellipsoid.mif}.  See also
\fn{ellipsoid-atlasproc.mif} and \fn{ellipsoid-fieldproc.mif} for
equivalent examples using \Tcl\ scripts.
\end{sloppypar}
\end{description}

\subsubsection{Meshes}\label{sec:Meshes}
Meshes define the discretization impressed on the simulation.  There
should be exactly one mesh declared in a \MIF~2 file.  The usual
(finite) mesh type is \cd{Oxs\_RectangularMesh}.  For simulations that
are periodic along one or more axes, use the
\cd{Oxs\_PeriodicRectangularMesh} type.

\begin{description}
\begin{rawhtml}<A NAME="RM"></A>\end{rawhtml}%
\label{html:oxsrectangularmesh}%
\index{Oxs\_Ext~child~classes!Oxs\_RectangularMesh}
\item[Oxs\_RectangularMesh:]
This mesh is comprised of a lattice of rectangular prisms.
The specify block has the form
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_RectangularMesh:\oxsval{name} \ocb \\
\bi cellsize \ocb\oxsval{ xstep ystep zstep }\ccb\\
\bi atlas \oxsval{atlas\_spec}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_RectangularMesh:</TT><I>name</I> <TT>{</TT>
<DD><TT>cellsize {</TT>
  <I>xstep<TT>&nbsp;</TT>ystep<TT>&nbsp;</TT>zstep</I>
  <TT>}</TT>
<DD><TT>atlas </TT> <I>atlas_spec</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
This creates an axes parallel rectangular mesh across the entire space
covered by \oxslabel{atlas}.  The mesh sample rates along each axis are
specified by \oxslabel{cellsize} (in meters).  The mesh is
cell-based, with the center of the first cell one half step in from the
minimal extremal point (xmin,ymin,ymax) for \oxsval{atlas\_spec}.
The \oxsval{name} is commonly set to ``mesh'', in which case the mesh
object may be referred to by other \cd{Oxs\_Ext} objects by the short
name \cd{:mesh}.

\textbf{Examples:} \fn{sample.mif}, \fn{stdprob3.mif}, \fn{stdprob4.mif}.

\begin{rawhtml}<A NAME="PRM"></A>\end{rawhtml}%
\label{html:oxsperiodicrectangularmesh}%
\index{Oxs\_Ext~child~classes!Oxs\_PeriodicRectangularMesh}
\item[Oxs\_PeriodicRectangularMesh:]
Like the \cd{Oxs\_RectangularMesh}, this mesh is also comprised of a
lattice of rectangular prisms.  However, in this case the
mesh is declared to be periodic along one or more of the axis
directions.  The specify block has the form
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_PeriodicRectangularMesh:\oxsval{name} \ocb \\
\bi cellsize \ocb\oxsval{ xstep ystep zstep }\ccb\\
\bi atlas \oxsval{atlas\_spec}\\
\bi periodic \oxsval{periodic\_axes}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_PeriodicRectangularMesh:</TT><I>name</I> <TT>{</TT>
<DD><TT>cellsize {</TT>
  <I>xstep<TT>&nbsp;</TT>ystep<TT>&nbsp;</TT>zstep</I>
  <TT>}</TT>
<DD><TT>atlas </TT> <I>atlas_spec</I>
<DD><TT>periodic </TT> <I>periodic_axes</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
The \oxslabel{atlas} and \oxslabel{cellsize} values are the same as
for the \cd{Oxs\_RectangularMesh} class.  The \oxsval{periodic\_axis}
value should be a string consisting of one or more of the letters
``x'', ``y'', or ``z'', denoting the periodic direction(s).
\cd{Oxs\_Ext} objects that are incompatible with
\cd{Oxs\_PeriodicRectangularMesh} will issue an error message at
runtime.  In particular, the
\htmlonlyref{\cd{Oxs\_Demag}}{html:oxsdemag} class supports
periodicity in none or one direction, but not more.  Also, some
third-party extensions provide independent periodicity support using
the older \cd{Oxs\_RectangularMesh} class rather than
\cd{Oxs\_PeriodicRectangularMesh}.

\textbf{Examples:} \fn{pbcbrick.mif}, \fn{pbcstripes.mif}.

\end{description}

\subsubsection{Energies}
The following subsections describe the available energy terms.  In
order to be included in the simulation energy and field calculations,
each energy term must be declared in its own, top-level Specify block,
i.e., energy terms should not be declared inline inside other
\cd{Oxs\_Ext} objects.  There is no limitation on the number of energy
terms that may be specified in the input \MIF\ file.  Many of these
terms have spatially varying parameters that are initialized via
\hyperrefhtml{\oxsval{field\_object\_spec}
entries}{\oxsval{field\_object\_spec} entries
(Sec.~}{)}{sec:oxsFieldObjects} in their
\hyperrefhtml{Specify initialization block}{Specify initialization block
(see Sec.~}{)}{par:oxsExtReferencing}.

\textbf{Outputs:} For each magnetization configuration, three standard
outputs are provided by all energy terms: the scalar output
``Energy,'' which is the total energy in joules contributed by this
energy term, the scalar field output ``Energy density,'' which is a
cell-by-cell map of the energy density in
\latexhtml{J/m${}^3$}{J/m\begin{rawhtml}<SUP>3</SUP>\end{rawhtml}},
and the three-component vector field output ``Field,'' which is the
pointwise field in A/m.  If the code was compiled with the macro
\cd{NDEBUG} not defined, then there will be an additional scalar
output, ``Calc count,'' which counts the number of times the term has
been calculated in the current simulation.  This is intended for
debugging purposes only; this number should agree with the ``Energy
calc count'' value provided by the evolver.

\begin{itemize}
\item{\textbf{Anisotropy Energy}}
\begin{description}
\begin{rawhtml}<A NAME="UA"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_UniaxialAnisotropy}%
\item[Oxs\_UniaxialAnisotropy:] Uniaxial magneto-crystalline
  anisotropy.  The Specify block has the form
   \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_UniaxialAnisotropy:\oxsval{name} \ocb\\
        \bi K1 \oxsval{K} \\
        \bi Ha \oxsval{H} \\
        \bi axis \oxsval{u} \\
      \ccb
      \end{quote}
   \end{latexonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_UniaxialAnisotropy:</TT><I>name</I> <TT>{</TT>
       <DD> <TT>K1 </TT><I>K</I>
       <DD> <TT>Ha </TT><I>H</I>
       <DD> <TT>axis </TT><I>u</I>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
  Exactly one of either \oxslabel{K1} or \oxslabel{Ha} should be
  specified, where \oxslabel{K1} is the crystalline anisotropy constant
  (in
  \latexhtml{J/m${}^3$}{J/m\begin{rawhtml}<sup>3</sup>\end{rawhtml}}),
  and \oxslabel{Ha} is the anistropy field (in A/m).  In either case,
  \oxslabel{axis} is the anisotropy direction.  \oxslabel{K1},
  \oxslabel{Ha}, and \oxslabel{axis} may each be varied cellwise across
  the mesh: \oxslabel{K1} and \oxslabel{Ha} are initialized with scalar
  field objects, while \oxslabel{axis} takes a vector field object.  (A
  constant value will be interpreted as a uniform field object having
  the stated value, as usual.)  The axis direction must be non-zero at
  each point, and will be normalized to unit magnitude before being
  used.

  The axis direction is an easy axis if \oxslabel{K1} (or \oxslabel{Ha})
  is $>$0, in which case the cellwise anisotropy energy density (in
  J/m${}^3$) is given by
   \begin{displaymath}
         E_i = K_i(1 - \vm_i\cdot\vu_i)^2 \qquad \mbox{or} \qquad
               \frac{1}{2}\, \mu_0 M_s H_i (1 - \vm_i\cdot\vu_i)^2,
   \end{displaymath}
  respectively.  (Here $m_i$ is the unit magnetization and $M_s$ the
  saturation magnetization in cell $i$.)  Otherwise, if \oxslabel{K1}
  (or \oxslabel{Ha}) is $<0$, the axis direction is the normal to the
  easy plane and the cellwise anisotropy energy density is given by
   \begin{displaymath}
         E_i = -K_i(\vm_i\cdot\vu_i)^2 \qquad \mbox{or} \qquad
               -\frac{1}{2}\, \mu_0 M_s H_i (\vm_i\cdot\vu_i)^2.
   \end{displaymath}
  The formulae in the two cases (easy axis vs.\ easy plane) differ by a
  constant offset, and in each case the energy is non-negative.

\textbf{Examples:} \fn{diskarray.mif}, \fn{stdprob3.mif}, \fn{grill.mif}.

\begin{rawhtml}<A NAME="CA"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_CubicAnisotropy}%
\item[Oxs\_CubicAnisotropy:] Cubic magneto-crystalline anisotropy.
  The Specify block has the form
   \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_CubicAnisotropy:\oxsval{name} \ocb\\
        \bi K1 \oxsval{K} \\
        \bi Ha \oxsval{H} \\
        \bi axis1 \oxsval{$u_1$} \\
        \bi axis2 \oxsval{$u_2$} \\
      \ccb
      \end{quote}
   \end{latexonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_CubicAnisotropy:</TT><I>name</I> <TT>{</TT>
       <DD> <TT>K1 </TT><I>K</I>
       <DD> <TT>Ha </TT><I>H</I>
       <DD> <TT>axis1 </TT><I>u<sub>1</sub></I>
       <DD> <TT>axis2 </TT><I>u<sub>2</sub></I>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
  Exactly one of either \oxslabel{K1} or \oxslabel{Ha} should be
  specified, where \oxslabel{K1} is the crystalline anisotropy constant
  (in
  \latexhtml{J/m${}^3$}{J/m\begin{rawhtml}<sup>3</sup>\end{rawhtml}}),
  and \oxslabel{Ha} is the anistropy field (in A/m).  In either case,
  \oxslabel{axis1} and \oxslabel{axis2} are two anisotropy directions;
  the third anisotropy axis $u_3$ is computed as the vector product,
  $u_1\times u_2$.  For each cell, the axis directions are easy axes if
  \oxslabel{K1} (or \oxslabel{Ha}) is $>$0, or hard axes if
  \oxslabel{K1} (or \oxslabel{Ha}) is $<$0.  All may be varied cellwise
  across the mesh.  \oxslabel{K1} or \oxslabel{Ha} is initialized with a
  scalar field object, and the axis directions are initialized with
  vector field objects.  (Constant values will be interpreted as uniform
  fields with the indicated value, as usual.)  The \oxslabel{axis1} and
  \oxslabel{axis2} directions must be mutually orthogonal and non-zero
  at each point ($u_1$ and $u_2$ are automatically scaled to unit
  magnitude before use).

  The anisotropy energy density (in J/m${}^3$) for cell $i$ is given by
   \begin{displaymath}
         E_i = K_i\left(a_1^2a_2^2 + a_2^2a_3^2 + a_3^2a_1^2\right),
   \end{displaymath}
   or
   \begin{displaymath}
         E_i = \frac{1}{2}\, \mu_0 M_s H_i 
         \left(a_1^2a_2^2 + a_2^2a_3^2 + a_3^2a_1^2\right),
   \end{displaymath}
  where $a_1 = \vm\cdot\vu_1$, $a_2 = \vm\cdot\vu_2$, $a_3 =
  \vm\cdot\vu_3$, for reduced (normalized) magnetization $m$ and
  orthonormal anisotropy axes $\vu_1$, $\vu_2$, and $\vu_3$ at cell $i$.
  In the second form, $M_s$ is the saturation magnetization in cell $i$.
  For each cell, if \oxslabel{K1} (resp.\ \oxslabel{Ha}) is $>$0 then
  the computed energy will be non-negative, otherwise for \oxslabel{K1}
  (resp.\ \oxslabel{Ha}) $<$0 the computed energy will be non-positive.

\textbf{Examples:} \fn{cgtest.mif}, \fn{sample2.mif}, \fn{grill.mif}.

\end{description}

\item{\textbf{Exchange Energy}}
\begin{description}
\begin{rawhtml}<A NAME="E6"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_Exchange6Ngbr}%
\item[Oxs\_Exchange6Ngbr:]
   Standard 6-neighbor exchange energy.  The
   exchange energy density contribution from cell $i$ is given by
   \begin{equation}
        E_i =  \sum_{j\in N_i} A_{ij}
         \frac{\vm_i\cdot\left(\vm_i - \vm_j\right)}{\Delta_{ij}^2}
   \label{eq:ExchangeEnergy}
   \end{equation}
   where $N_i$ is the set consisting of the 6 cells nearest to cell $i$,
   $A_{ij}$ is the exchange coefficient between cells $i$ and $j$ in J/m,
   and $\Delta_{ij}$ is the discretization step size between cell $i$ and
   cell $j$ (in meters).

   The Specify block for this term has the form
   \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_Exchange6Ngbr:\oxsval{name} \ocb\\
         \bi default\_A \oxsval{value}\\
         \bi atlas \oxsval{atlas\_spec}\\
         \bi A \ocb\\
         \bi  \bi \oxsval{ region-1 region-1 A${}_{11}$ }\\
         \bi  \bi \oxsval{ region-1 region-2 A${}_{12}$ }\\
         \bi  \bi \ldots\\
         \bi  \bi \oxsval{ region-m region-n A${}_{mn}$ }\\
         \bi \ccb\\
      \ccb
      \end{quote}
   \end{latexonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_Exchange6Ngbr:</TT><I>name</I> <TT>{</TT>
   <DD><TT>default_A </TT><I>value</I>
   <DD><TT>atlas </TT><I>atlas_spec</I>
   <DD><TT>A {</TT><DL>
       <DD>
        <I>region-1</I><TT>&nbsp;</TT>
          <I>region-1</I><TT>&nbsp;</TT><I>A<SUB>11</SUB></I>
       <DD>
        <I>region-1</I><TT>&nbsp;</TT>
          <I>region-2</I><TT>&nbsp;</TT><I>A<SUB>12</SUB></I>
       <DD> ...
       <DD>
        <I>region-m</I><TT>&nbsp;</TT>
          <I>region-n</I><TT>&nbsp;</TT><I>A<SUB>mn</SUB></I>
   </DL><TT>}</TT>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   or
   \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_Exchange6Ngbr:\oxsval{name} \ocb\\
         \bi default\_lex \oxsval{value}\\
         \bi atlas \oxsval{atlas\_spec}\\
         \bi lex \ocb\\
         \bi  \bi \oxsval{ region-1 region-1 lex${}_{11}$ }\\
         \bi  \bi \oxsval{ region-1 region-2 lex${}_{12}$ }\\
         \bi  \bi \ldots\\
         \bi  \bi \oxsval{ region-m region-n lex${}_{mn}$ }\\
         \bi \ccb\\
      \ccb
      \end{quote}
   \end{latexonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_Exchange6Ngbr:</TT><I>name</I> <TT>{</TT>
   <DD><TT>default_lex </TT><I>value</I>
   <DD><TT>atlas </TT><I>atlas_spec</I>
   <DD><TT>lex {</TT><DL>
       <DD>
        <I>region-1</I><TT>&nbsp;</TT>
          <I>region-1</I><TT>&nbsp;</TT><I>lex<SUB>11</SUB></I>
       <DD>
        <I>region-1</I><TT>&nbsp;</TT>
          <I>region-2</I><TT>&nbsp;</TT><I>lex<SUB>12</SUB></I>
       <DD> ...
       <DD>
        <I>region-m</I><TT>&nbsp;</TT>
          <I>region-n</I><TT>&nbsp;</TT><I>lex<SUB>mn</SUB></I>
   </DL><TT>}</TT>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   where \oxslabel{lex} specifies the magnetostatic-exchange length, in
   meters, defined by ${\rm lex} = \sqrt{2A/(\mu_0 M_s^2)}$.

   In the first case, the \oxslabel{A} block specifies $A_{ij}$ values
   on a region by region basis, where the regions are labels declared by
   \oxsval{atlas\_spec}.  This allows for specification of $A$ both
   inside a given region (e.g., $A_{ii}$) and along interfaces between
   regions (e.g., $A_{ij}$).  By symmetry, if $A_{ij}$ is specified,
   then the same value is automatically assigned to $A_{ji}$ as well.
   The \oxslabel{default\_A} value is applied to any otherwise
   unassigned $A_{ij}$.

   In the second case, one specifies the magnetostatic-exchange length
   instead of $A$, but the interpretation is otherwise analogous.

   Although one may specify $A_{ij}$ (resp.\ ${\rm lex}_{ij}$) for any
   pair of regions $i$ and $j$, it is only required and only active if
   the region pair are in contact.  If long-range exchange interaction
   is required, use \cd{Oxs\_TwoSurfaceExchange}.

   In addition to the standard energy and field outputs,
   \cd{Oxs\_Exchange6Ngbr} provides three scalar outputs involving the
   angle between spins at neighboring cells:
\begin{itemize}
\item \textbf{Max Spin Ang:} maximum angle, in degrees, between
  neigboring spins for the current magnetization state.
\item \textbf{Stage Max Spin Ang:} Maximum value of \cd{Max Spin Ang}
  for the current stage.
\item \textbf{Run Max Spin Ang:} Maximum value obtained by
  \cd{Max Spin Ang} during the simulation.
\end{itemize}

   \textbf{Examples:} \fn{grill.mif}, \fn{spinvalve.mif}, \fn{tclshapes.mif}.

\begin{rawhtml}<A NAME="UE"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_UniformExchange}%
\item[Oxs\_UniformExchange:]
   Similar to \cd{Oxs\_Exchange6Ngbr}, except the exchange constant $A$
   (or exchange length ${\rm lex}$) is uniform across all space.  The
   Specify block is very simple, consisting of either the label
   \oxslabel{A} with the desired exchange coefficient value in J/m, or
   the label \oxslabel{lex} with the desired magnetostatic-exchange
   length in meters.  Since \cd{A} (resp.\ \cd{lex}) is not spatially
   varying, it is initialized with a simple constant (as opposed to a
   scalar field object).

   In addition to the standard energy and field outputs,
   \cd{Oxs\_UniformExchange} provides the three scalar outputs
   \cd{Max Spin Ang}, \cd{Stage Max Spin Ang}, and
   \cd{Run Max Spin Ang} as described for \cd{Oxs\_Exchange6Ngbr}.

   \textbf{Examples:} \fn{sample.mif}, \fn{cgtest.mif}, \fn{stdprob3.mif}.

\begin{rawhtml}<A NAME="EP"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_ExchangePtwise}%
\item[Oxs\_ExchangePtwise:]
   The exchange coefficient $A_i$ is specified on
   a point-by-point (or cell-by-cell) basis, as opposed to the pairwise
   specification model used by \cd{Oxs\_Exchange6Ngbr}.  The exchange
   energy density at a cell $i$ is computed across its nearest 6 neighbors,
   $N_i$, using the formula
   \begin{displaymath}
        E_i =  \sum_{j\in N_i} A_{ij,{\rm eff}}
         \frac{\vm_i\cdot\left(\vm_i - \vm_j\right)}{\Delta_{ij}^2}
   \end{displaymath}
   where $\Delta_{ij}$ is the discretization step size from cell $i$ to
   cell $j$ in meters, and
   \begin{displaymath}
         A_{ij,{\rm eff}} = \frac{2A_iA_j}{A_i+A_j},
   \end{displaymath}
   with $A_{ij,{\rm eff}} = 0$ if $A_i$ and $A_j$ are 0.

   Note that $A_{ij,{\rm eff}}$ satisfies
   the following properties:
   \begin{eqnarray*}
        A_{ij,{\rm eff}} & = & A_{ji,{\rm eff}} \\
        A_{ij,{\rm eff}} & = & A_i \qquad \mbox{if $A_i=A_j$} \\
        \lim_{A_i\downarrow 0} A_{ij,{\rm eff}} & = & 0.
   \end{eqnarray*}
   Additionally, if $A_i$ and $A_j$ are non-negative,
   \begin{displaymath}
        \min(A_i,A_j) \leq  A_{ij,{\rm eff}}  \leq \max(A_i,A_j).
   \end{displaymath}
   Evaluating the exchange energy with this formulation of $A_{ij,{\rm
   eff}}$ is equivalent to finding the minimum possible exchange energy
   between cells $i$ and $j$ under the assumption that $A_i$ and $A_j$
   are constant in each of the two cells.  Similar considerations are
   made in computing the exchange energy for a \htmlonlyref{2D variable
   thickness model}{html:mifvariablethickness} \cite{porter01}.

   The Specify block for \cd{Oxs\_ExchangePtwise} has the form
   \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_ExchangePtwise:\oxsval{name} \ocb\\
        \bi A \oxsval{scalarfield\_spec}\\
      \ccb
      \end{quote}
   \end{latexonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_ExchangePtwise:</TT><I>name</I> <TT>{</TT>
       <DD> <TT>A </TT><I>scalarfield_spec</I>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   where \oxsval{scalarfield\_spec} is an arbitrary
   \hyperrefhtml{scalar field object}{scalar field object
   (Sec.~}{)}{sec:oxsFieldObjects} returning the desired exchange
   coefficient in J/m.

   In addition to the standard energy and field outputs,
   \cd{Oxs\_ExchangePtwise} provides the three scalar outputs
   \cd{Max Spin Ang}, \cd{Stage Max Spin Ang}, and
   \cd{Run Max Spin Ang} as described for \cd{Oxs\_Exchange6Ngbr}.

   \textbf{Example:} \fn{antidots-filled.mif}.

\begin{rawhtml}<A NAME="TS"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_TwoSurfaceExchange}%
\item[Oxs\_TwoSurfaceExchange:]
   Provides long-range bilinear and biquadratic exchange.  Typically
   used to simulate RKKY-style coupling across non-magnetic spacers in
   spinvalves.  The specify block has the form
   \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_TwoSurfaceExchange:\oxsval{name} \ocb\\
        \bi sigma \oxsval{value}\\
        \bi sigma2 \oxsval{value}\\
        \bi surface1 \ocb\\
        \bi \bi atlas  \oxsval{atlas\_spec}\\
        \bi \bi region \oxsval{region\_label}\\
        \bi \bi scalarfield \oxsval{scalarfield\_spec}\\
        \bi \bi scalarvalue \oxsval{fieldvalue}\\
        \bi \bi scalarside  \oxsval{sign}\\
        \bi \ccb\\
        \bi surface2 \ocb\\
        \bi \bi atlas  \oxsval{atlas\_spec}\\
        \bi \bi region \oxsval{region\_label}\\
        \bi \bi scalarfield \oxsval{scalarfield\_spec}\\
        \bi \bi scalarvalue \oxsval{fieldvalue}\\
        \bi \bi scalarside  \oxsval{sign}\\
        \bi \ccb\\
      \ccb
      \end{quote}
   \end{latexonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_TwoSurfaceExchange:</TT><I>name</I> <TT>{</TT>
   <DD><TT>sigma  </TT><I>value</I>
   <DD><TT>sigma2 </TT><I>value</I>
   <DD><TT>surface1 {</TT><DL>
       <DD> <TT>atlas </TT><I>atlas_spec</I>
       <DD> <TT>region </TT><I>region_label</I>
       <DD> <TT>scalarfield </TT><I>scalarfield_spec</I>
       <DD> <TT>scalarvalue </TT><I>fieldvalue</I>
       <DD> <TT>scalarside </TT><I>sign</I>
   </DL><TT>}</TT>
   <DD><TT>surface2 {</TT><DL>
       <DD> <TT>atlas </TT><I>atlas_spec</I>
       <DD> <TT>region </TT><I>region_label</I>
       <DD> <TT>scalarfield </TT><I>scalarfield_spec</I>
       <DD> <TT>scalarvalue </TT><I>fieldvalue</I>
       <DD> <TT>scalarside </TT><I>sign</I>
   </DL><TT>}</TT>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   Here \textbf{sigma} and \textbf{sigma2} are the bilinear and
   biquadratic surface (interfacial) exchange energies, in
   \latexhtml{J/m${}^2$}{J/m^2}.  Either is optional, with default value
   0.

   The \oxslabel{surface1} and \oxslabel{surface2} sub-blocks describe
   the two interacting surfaces.  Each description consists of 5
   name-values pairs, which must be listed in the order shown.  In each
   sub-block, \oxsval{atlas\_spec} specifies an atlas, and
   \oxsval{region\_label} specifies a region in that atlas.  These bound
   the extent of the desired surface.  The following
   \oxslabel{scalarfield}, \oxslabel{scalarvalue} and
   \oxslabel{scalarside} entries define a discretized surface inside the
   bounding region.  Here \oxsval{scalarfield\_spec} references a scalar
   field object, \oxsval{fieldvalue} should be a floating point value,
   and \oxsval{sign} should be a single character, either `$-$' or
   `$+$'.  If \oxsval{sign} is `$-$', then any point for which the
   scalar field object takes a value less than or equal to the
   \cd{scalarvalue} value is considered to be ``inside'' the surface.
   Conversely, if \oxsval{sign} is `$+$', then any point for which the
   scalar field object has value greater than or equal to the
   \cd{scalarvalue} value is considered to be ``inside'' the surface.
   The discretized surface determined is the set of all points on the
   problem mesh that are in the bounding region, are either on the
   surface or lie on the ``inside'' side of the surface, and have a
   (nearest-) neighbor that is on the ``outside'' side of the surface.
   A ``neighbor'' is determined by the mesh; in a typical rectangular
   mesh each cell has six neighbors.

   In this way, 2 discrete lists of cells representing the two
   surfaces are obtained.  Each cell from the first list (representing
   \cd{surface1}) is then matched with the closest cell from the
   second list (i.e., from \cd{surface2}).  Note the asymmetry in
   this matching process: each cell from the first list is included in
   exactly one match, but there may be cells in the second list that
   are included in many match pairs, or in none.  If the two surfaces
   are of different sizes, then in practice typically the smaller will
   be made the first surface, because this will usually lead to fewer
   multiply-matched cells, but this designation is not required.

   The resulting exchange energy density at cell $i$ on one surface
   from matching cell $j$ on the other is given by
   \begin{displaymath}
        E_{ij} =  \frac{\sigma\left[1-\vm_i\cdot\vm_j\right]
         +\sigma_2\left[1-\left(\vm_i\cdot\vm_j\right)^2\right]
        }{\Delta_{ij}}
   \end{displaymath}
   where $\sigma$ and $\sigma_2$, respectively, are the bilinear and
   biquadratic surface exchange coefficients between the two surfaces,
   in J/m${}^2$, $\vm_i$ and $\vm_j$ are the normalized, unit spins
   (i.e., magnetization directions) at cells $i$ and $j$, and
   $\Delta_{ij}$ is the discretization cell size in the direction from
   cell $i$ towards cell $j$, in meters.  Note that if $\sigma$ is
   negative, then the surfaces will be anti-ferromagnetically coupled.
   Likewise, if $\sigma_2$ is negative, then the biquadratic term will
   favor orthogonal alignment.

   The following example produces an antiferromagnetic exchange coupling
   between the lower surface of the ``top'' layer and the upper surface
   of the ``bottom'' layer, across a middle ``spacer'' layer.  The
   simple \cd{Oxs\_LinearScalarField} object is used here to provide
   level surfaces that are planes orthogonal to the $z$-axis.  In
   practice this example might represent a spinvalve, where the top and
   bottom layers would be composed of ferromagnetic material and the
   middle layer could be a copper spacer.
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin{latexonly}
\begin{quote}
%end{latexonly}
\begin{verbatim}
Specify Oxs_MultiAtlas:atlas {
    atlas { Oxs_BoxAtlas {
        name top
        xrange {0 500e-9}
        yrange {0 250e-9}
        zrange {6e-9 9e-9}
    } }
    atlas { Oxs_BoxAtlas {
        name spacer
        xrange {0 500e-9}
        yrange {0 250e-9}
        zrange {3e-9 6e-9}
    } }
    atlas { Oxs_BoxAtlas {
        name bottom
        xrange {0 500e-9}
        yrange {0 250e-9}
        zrange {0 3e-9}
    } }
}

Specify Oxs_LinearScalarField:zheight {
    vector {0 0 1}
    norm   1.0
}

Specify Oxs_TwoSurfaceExchange:AF {
    sigma -1e-4
    surface1 {
               atlas  :atlas
              region  bottom
         scalarfield  :zheight
         scalarvalue  3e-9
          scalarside  -
    }
    surface2 {
               atlas  :atlas
              region  top
         scalarfield  :zheight
         scalarvalue  6e-9
          scalarside  +
    }
}
\end{verbatim}
%begin{latexonly}
\end{quote}
%end{latexonly}
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}

   In addition to the standard energy and field outputs,
   \cd{Oxs\_TwoSurfaceExchange} provides the three scalar outputs
   \cd{Max Spin Ang}, \cd{Stage Max Spin Ang}, and
   \cd{Run Max Spin Ang} as described for \cd{Oxs\_Exchange6Ngbr}.

\textbf{Example:} \fn{spinvalve-af.mif}.


\begin{rawhtml}<A NAME="SE"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_RandomSiteExchange}%
\item[Oxs\_RandomSiteExchange:]
   A randomized exchange energy.  The Specify block has the form
   \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_RandomSiteExchange:\oxsval{name} \ocb\\
        \bi linkprob \oxsval{probability} \\
        \bi Amin \oxsval{A\_lower\_bound} \\
        \bi Amax \oxsval{A\_upper\_bound} \\
      \ccb
      \end{quote}
   \end{latexonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_RandomSiteExchange:</TT><I>name</I> <TT>{</TT>
       <DD> <TT>linkprob </TT><I>probability</I>
       <DD> <TT>Amin </TT><I>A_lower_bound</I>
       <DD> <TT>Amax </TT><I>A_upper_bound</I>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   Each adjacent pair of cells $i$, $j$, is given \oxslabel{linkprob}
   probability of having a non-zero exchange coefficient $A_{ij}$.  Here
   two cells are adjacent if they lie in each other's 6-neighborhood.
   If a pair is found to have a non-zero exchange coefficient, then
   $A_{ij}$ is drawn uniformly from the range $[\cd{Amin},\cd{Amax}]$.
   The exchange energy is computed using (\ref{eq:ExchangeEnergy}), the
   formula used by the \cd{Oxs\_Exchange6Ngbr} energy object.  The
   value $A_{ij}$ for each pair of cells is determined during problem
   initialization, and is held fixed thereafter.  The limits
   \oxsval{A\_lower\_bound} and \oxsval{A\_upper\_bound} may be any real
   numbers; negative values may be used to weaken the exchange
   interaction arising from other exchange energy terms.  The only
   restriction is that \oxsval{A\_lower\_bound} must not be greater than
   \oxsval{A\_upper\_bound}.  The \cd{linkprob} value \oxsval{probability}
   must lie in the range $[0,1]$.

   In addition to the standard energy and field outputs,
   \cd{Oxs\_RandomSiteExchange} provides the three scalar outputs
   \cd{Max Spin Ang}, \cd{Stage Max Spin Ang}, and
   \cd{Run Max Spin Ang} as described for \cd{Oxs\_Exchange6Ngbr}.

   \textbf{Example:} \fn{randexch.mif}.

\end{description}

\item{\textbf{Self-Magnetostatic Energy}}
\begin{description}
\begin{rawhtml}<A NAME="DE"></A>\end{rawhtml}%
\label{html:oxsdemag}%
\index{Oxs\_Ext~child~classes!Oxs\_Demag}%
\item[Oxs\_Demag:]
   Standard demagnetization energy term, built upon
   the assumption that the magnetization is constant in each cell.
   It computes the average demagnetization field in each cell using
   formulae from \cite{aharoni98,newell93} and convolution
   via the Fast Fourier Transform.  This class supports non-periodic
   simulations if the mesh object in the \MIF\ file is of the
   \htmlonlyref{\cd{Oxs\_RectangularMesh}}{html:oxsrectangularmesh}
   type; simulations periodic along one axis direction are also
   supported when using the
   \htmlonlyref{\cd{Oxs\_PeriodicRectangularMesh}}{html:oxsperiodicrectangularmesh}
   class.  Periodicity in more than one direction is not supported at
   this time.  The specify block has the form
   \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_Demag:\oxsval{name} \ocb\\
        \bi asymptotic\_radius \oxsval{radius}\\
      \ccb
      \end{quote}
   \end{latexonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_Demag:</TT><I>name</I> <TT>{</TT>
       <DD> <TT>asymptotic_radius </TT><I>radius</I>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   The analytic formulae used to compute the demag kernel are
   computationally expensive and inaccurate at large offsets.  At
   offsets larger than \oxsval{radius} (measured in cells) asymptotic
   approximations are used instead.  If \oxslabel{asymptotic\_radius} is
   not specified, then the default value 32 is used.  For non-periodic
   simulations, setting \oxsval{radius} to -1 causes the analytic
   formulae to be used at all offsets.  The example file
   \fn{demagtensor.mif} can be used to extract the computed
   demagnetization tensor coefficients for a specified cell geometry;
   see the description at the top of that file for usage details.

   \textbf{Examples:} \fn{sample.mif}, \fn{cgtest.mif}, \fn{pbcbrick.mif}, \fn{demagtensor.mif}.

\begin{rawhtml}<A NAME="SD"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_SimpleDemag}%
\item[Oxs\_SimpleDemag:]
   This is the same as the \cd{Oxs\_Demag} object, except that
   periodicity is not supported and asymptotic formulae are not used.
   The implementation does not use any of the symmetries
   inherent in the demagnetization kernel, or special properties of the
   Fourier Transform when applied to a real (non-complex) function.
   As a result, the source code is
   considerably simpler than for \cd{Oxs\_Demag}, but the run time
   performance and memory usage are poorer.  \cd{Oxs\_SimpleDemag} is
   included for validation checks, and as a base for user-defined
   demagnetization implementations.  The Specify initialization string
   for \cd{Oxs\_SimpleDemag} is an empty string, i.e., \ocb\ccb.

   \textbf{Example:} \fn{squarecubic.mif}.
\end{description}

\item{\textbf{Zeeman Energy}}
\begin{description}
\begin{rawhtml}<A NAME="UZ"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_UZeeman}%
\item[Oxs\_UZeeman:\label{html:UZeeman}]
   Uniform (homogeneous) applied field energy.  This class is frequently
   used for simulating hysteresis loops.  The specify block takes an
   optional \textbf{multiplier} entry, and a required field range list
   \textbf{Hrange}.  The field range list should be a compound list,
   with each sublist consisting of 7 elements: the first 3 denote the
   $x$, $y$, and $z$ components of the start field for the range, the
   next 3 denote the $x$, $y$, and $z$ components of the end field for
   the  range, and the last element specifies the number of (linear) steps
   through the range.  If the step count is 0, then the range consists
   of the start field only.  If the step count is bigger than 0, then
   the start field is skipped over if and only if it is the same field
   that ended the previous range (if any).

   The fields specified in the range entry are nominally in A/m, but
   these values are multiplied by \cd{multiplier}, which may be used to
   effectively change the units.  For example,
   \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_UZeeman \ocb \\
         \bi multiplier 795.77472\\
         \bi Hrange \ocb\\
         \bi\bi \ocb\ 0 0 0 10 0 0 2 \ccb\\
         \bi\bi \ocb\ 10 0 0 0 0 0 1 \ccb\\
         \bi\ccb\\
      \ccb
      \end{quote}
   \end{latexonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_UZeeman {</TT>
         <DD><TT> multiplier 795.77472</TT>
         <DD><TT> Hrange {</TT><DL>
              <DD><TT> { 0 0 0 10 0 0 2 }</TT>
              <DD><TT> { 10 0 0 0 0 0 1 }</TT>
         </DL><TT>}</TT>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   The applied field steps between 0~mT, 5~mT, 10~mT and back to 0~mT,
   for four stages in total.  If the first field in the second range
   sublist was different from the second field in the first range
   sublist, then a step would have been added between those field
   values, so five stages would have resulted.  In this example, note
   that 795.77472=0.001/\munaught.

   In addition to the standard energy and field outputs, the
   \cd{Oxs\_UZeeman} class provides these four scalar outputs:
   \begin{itemize}
   \item \textbf{B:} Magnitude of the applied field, in
   mT.  This is a non-negative quantity.
   \item \textbf{Bx:} Signed amplitude of the $x$-component
   of the applied field, in mT.
   \item \textbf{By:} Signed amplitude of the $y$-component
   of the applied field, in mT.
   \item \textbf{Bz:} Signed amplitude of the $z$-component
   of the applied field, in mT.
   \end{itemize}

   \textbf{Examples:} \fn{sample.mif}, \fn{cgtest.mif}, \fn{marble.mif}.

\begin{rawhtml}<A NAME="FZ"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_FixedZeeman}%
\item[Oxs\_FixedZeeman:]
   Non-uniform, non-time varying applied field.
   This can be used to simulate a biasing field.  The specify block
   takes one required parameter, which defines the field, and one
   optional parameter, which specifies a multiplication factor.
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_FixedZeeman:\oxsval{name} \ocb\\
       \bi field \oxsval{vector\_field\_spec}\\
       \bi multiplier \oxsval{multiplier}\\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_FixedZeeman:</TT><I>name</I> <TT>{</TT>
      <DD><TT> field </TT> <I>vector_field_spec</I>
      <DD><TT> multiplier </TT> <I>multiplier</I>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}
   The default value for \oxsval{multiplier} is 1.

   \textbf{Examples:} \fn{spinvalve.mif}, \fn{spinvalve-af.mif}, \fn{yoyo.mif}.

\begin{rawhtml}<A NAME="SU"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_ScriptUZeeman}%
\item[Oxs\_ScriptUZeeman:]
   Spatially uniform applied field,
   potentially varying as a function of time and stage, determined by a
   \Tcl\ script.  The Specify block has the form
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_ScriptUZeeman:\oxsval{name} \ocb\\
       \bi script\_args \ocb\oxsval{ args\_request }\ccb\\
       \bi script \oxsval{\Tcl\_script}\\
       \bi multiplier \oxsval{multiplier}\\
       \bi stage\_count \oxsval{number\_of\_stages} \\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_ScriptUZeeman:</TT><I>name</I> <TT>{</TT>
      <DD><TT>script_args {</TT> <I>args_request</I> <TT>}</TT>
      <DD><TT>script </TT> <I>Tcl_script</I>
      <DD><TT>multiplier </TT> <I>multiplier</I>
      <DD><TT>stage_count </TT> <I>number_of_stages</I>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}
   Here \oxslabel{script} indicates the \Tcl\ script to use.  The script
   is called once each iteration.  Appended to the script are the
   arguments requested by \oxslabel{script\_args}, in the manner
   explained in the \hyperrefhtml{User Defined Support Procedures}{User
   Defined Support Procedures section (Sec.~}{)}{par:supportProcs}
   \html{section} of the \MIF~2 file format documentation.  The value
   \oxsval{args\_request} should be a subset of \cd{\ocb stage
   stage\_time total\_time\ccb}.  If \cd{script\_args} is not specified,
   the default argument list is the complete list in the aforementioned
   order.  The units for the time arguments are seconds.

   The return value from the script should be a 6-tuple of numbers,
   \ocb\cd{Hx}, \cd{Hy}, \cd{Hz}, \cd{dHx}, \cd{dHy}, \cd{dHz}\ccb,
   representing the applied field and the time derivative of the applied
   field.  The field as a function of time must be differentiable for
   the duration of each stage.  Discontinuities are permitted between
   stages.  If a time evolver is being used, then it is very important
   that the time derivative values are correct; otherwise the evolver
   will not function properly.  This usual symptom of this problem is a
   collapse in the time evolution step size.

   The field and its time derivative are multiplied by the
   \oxslabel{multiplier} value before use.  The final field value should
   be in A/m; if the \Tcl\ script returns the field in T, then a
   \cd{multiplier} value of 1/\munaught\ (approx.\ 795774.72) should be
   applied to convert the \Tcl\ result into A/m.  The default value for
   \cd{multiplier} is 1.

   The \oxslabel{stage\_count} parameter informs the
   \hyperrefhtml{\cd{Oxs\_Driver}}{\cd{Oxs\_Driver}
   (Sec.~}{)}{sec:oxsDrivers} as to how many stages the
   \cd{Oxs\_ScriptUZeeman} object wants.  A value of 0 (the default)
   indicates that the object is prepared for any range of stages.  The
   \cd{stage\_count} value given here must be compatible with the
   \htmlonlyref{\cd{stage\_count} setting in the driver Specify
   block}{html:oxsdriverstagecount}\latex{\ (q.v.)}.

   The following example produces a sinusoidally varying field of
   frequency 1 GHz and amplitude 800 A/m, directed along the $x$-axis.
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
proc SineField { total_time } {
    set PI [expr {4*atan(1.)}]
    set Amp 800.0
    set Freq [expr {1e9*(2*$PI)}]
    set Hx [expr {$Amp*sin($Freq*$total_time)}]
    set dHx [expr {$Amp*$Freq*cos($Freq*$total_time)}]
    return [list $Hx 0 0 $dHx 0 0]
}

Specify Oxs_ScriptUZeeman {
   script_args total_time
   script SineField
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}

   In addition to the standard energy and field outputs, the
   \cd{Oxs\_ScriptUZeeman} class provides these four scalar outputs:
   \begin{itemize}
   \item \textbf{B:} Magnitude of the applied field, in
   mT.  This is a non-negative quantity.
   \item \textbf{Bx:} Signed amplitude of the $x$-component
   of the applied field, in mT.
   \item \textbf{By:} Signed amplitude of the $y$-component
   of the applied field, in mT.
   \item \textbf{Bz:} Signed amplitude of the $z$-component
   of the applied field, in mT.
   \end{itemize}

\textbf{Examples:} \fn{acsample.mif}, \fn{pulse.mif}, \fn{rotate.mif},
                   \fn{varalpha.mif}, \fn{yoyo.mif}.

\begin{rawhtml}<A NAME="TZ"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_TransformZeeman}%
\item[Oxs\_TransformZeeman:]
   Essentially a combination of the \cd{Oxs\_FixedZeeman} and
   \cd{Oxs\_ScriptUZeeman} classes, where an applied field is produced
   by applying a spatially uniform, but time and stage varying linear
   transform to a spatially varying but temporally static field.  The
   transform is specified by a \Tcl\ script.

   The Specify block has the form
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_TransformZeeman:\oxsval{name} \ocb\\
       \bi field \oxsval{vector\_field\_spec}\\
       \bi type \oxsval{transform\_type}\\
       \bi script \oxsval{\Tcl\_script}\\
       \bi script\_args \ocb\oxsval{ args\_request }\ccb\\
       \bi multiplier \oxsval{multiplier}\\
       \bi stage\_count \oxsval{number\_of\_stages} \\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_TransformZeeman:</TT><I>name</I> <TT>{</TT>
      <DD><TT>field </TT> <I>vector_field_spec</I>
      <DD><TT>type </TT> <I>transform_type</I>
      <DD><TT>script </TT> <I>Tcl_script</I>
      <DD><TT>script_args {</TT> <I>args_request</I> <TT>}</TT>
      <DD><TT>multiplier </TT> <I>multiplier</I>
      <DD><TT>stage_count </TT> <I>number_of_stages</I>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}
   The \oxslabel{field} specified by \oxsval{vector\_field\_spec} is
   evaluated during problem initialization and held throughout the life
   of the problem.  On each iteration, the specified \Tcl\
   \oxslabel{script} is called once.  Appended to the script are the
   arguments requested by \oxslabel{script\_args}, as explained in the
   \hyperrefhtml{User Defined Support Procedures}{User Defined Support
   Procedures section (Sec.~}{)}{par:supportProcs}\html{ section} of the
   \MIF~2 file format documentation.  The value for \cd{script\_args}
   should be a subset of \cd{\ocb stage stage\_time total\_time\ccb}.
   The default value for \cd{script\_args} is the complete list in the
   aforementioned order.  The time arguments are specified in seconds.

   The script return value should define a 3x3 linear transform and its
   time derivative.  The transform must be differentiable with respect
   to time throughout each stage, but is allowed to be discontinuous
   between stages.  As noted in the \cd{Oxs\_ScriptUZeeman}
   documentation, it is important that the derivative information be
   correct.  The transform is applied pointwise to the fixed
   field obtained from \oxsval{vector\_field\_spec}, which is
   additionally scaled by \oxsval{multiplier}.  The
   \oxslabel{multiplier} entry is optional, with default value 1.0.

   The \oxslabel{type} \oxsval{transform\_type} value declares the
   format of the result returned from the \Tcl\ script.  Recognized
   formats are \cd{identity}, \cd{diagonal}, \cd{symmetric} and
   \cd{general}.  The most flexible is \cd{general}, which indicates
   that the return from the \Tcl\ script is a list of 18 numbers,
   defining a general 3x3 matrix and its 3x3 matrix of time derivatives.
   The matrices are specified in row-major order, i.e., $M_{1,1}$,
   $M_{1,2}$, $M_{1,3}$, $M_{2,1}$, $M_{2,2}$, \ldots.  Of course, this
   is a long list to construct; if the desired transform is symmetric or
   diagonal, then the \cd{type} may be set accordingly to reduce the
   size of the \Tcl\ result string.  Scripts of the \cd{symmetric} type
   return 12 numbers, the 6 upper diagonal entries in row-major order,
   i.e., $M_{1,1}$, $M_{1,2}$, $M_{1,3}$, $M_{2,2}$, $M_{2,3}$,
   $M_{3,3}$, for both the transformation matrix and its time
   derivative.  Use the \cd{diagonal} type for diagonal matrices, in
   which case the \Tcl\ script result should be a list of 6 numbers.

   The simplest \oxsval{transform\_type} is \cd{identity}, which is the
   default.  This identifies the transform as the identity matrix, which
   means that effectively no transform is applied, aside from the
   \cd{multiplier} option which is still active.  For the \cd{identity}
   transform type, \cd{script} and \cd{script\_args} should not be
   specified, and \cd{Oxs\_TransformZeeman} becomes a clone of the
   \cd{Oxs\_FixedZeeman} class.

   The following example produces a 1000 A/m field that rotates in the
   $xy$-plane at a frequency of 1 GHz:
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
proc Rotate { freq stage stagetime totaltime } {
   global PI
   set w [expr {$freq*2*$PI}]
   set ct [expr {cos($w*$totaltime)}]
   set mct [expr {-1*$ct}]      ;# "mct" is "minus cosine (w)t"
   set st [expr {sin($w*$totaltime)}]
   set mst [expr {-1*$st}]      ;# "mst" is "minus sine (w)t"
   return [list  $ct $mst  0 \
                 $st $ct   0 \
                   0   0   1 \
                 [expr {$w*$mst}] [expr {$w*$mct}] 0 \
                 [expr {$w*$ct}]  [expr {$w*$mst}] 0 \
                        0                0         0]
}

Specify Oxs_TransformZeeman {
  type general
  script {Rotate 1e9}
  field {0 1000. 0}
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
This particular effect could be obtained using the
\cd{Oxs\_ScriptUZeeman} class, because the \cd{field} is uniform.
But the field was taken uniform only to simplify the example.  The
\oxsval{vector\_field\_spec} may be any \hyperrefhtml{Oxs vector field
object}{Oxs vector field object (Sec.~}{)}{sec:oxsFieldObjects}.  For
example, the base field could be large in the center of the sample, and
decay towards the edges.  In that case, the above example would generate
an applied rotating field that is concentrated in the center of the
sample.

The \oxslabel{stage\_count} parameter informs the
\hyperrefhtml{\cd{Oxs\_Driver}}{\cd{Oxs\_Driver}
(Sec.~}{)}{sec:oxsDrivers} as to how many stages the
\cd{Oxs\_TransformZeeman} object wants.  A value of 0 (the default)
indicates that the object is prepared for any range of stages.  The
\cd{stage\_count} value given here must be compatible with the
\htmlonlyref{\cd{stage\_count} setting in the driver Specify
block}{html:oxsdriverstagecount}\latex{\ (q.v.)}.

\textbf{Examples:} \fn{sample2.mif}, \fn{tickle.mif}, \fn{rotatecenter.mif}.

\begin{rawhtml}<A NAME="SZ"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_StageZeeman}%
\item[Oxs\_StageZeeman:]
   The \cd{Oxs\_StageZeeman} class provides spatially varying applied
   fields that are updated once per stage.  In its general form, the
   field at each stage is provided by an \hyperrefhtml{Oxs vector field
   object}{Oxs vector field object (Sec.~}{)}{sec:oxsFieldObjects}
   determined by a user supplied \Tcl\ script.  There is also a
   simplified interface that accepts a list of \hyperrefhtml{vector
   field files}{vector field files (Sec.~}{)}{sec:vfformats}, one per
   stage, that are used to specify the applied field.

   The Specify block takes the form
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_StageZeeman:\oxsval{name} \ocb\\
       \bi script \oxsval{Tcl\_script}\\
       \bi files \ocb\oxsval{ list\_of\_files }\ccb\\
       \bi stage\_count \oxsval{number\_of\_stages} \\
       \bi multiplier \oxsval{multiplier}\\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_StageZeeman:</TT><I>name</I> <TT>{</TT>
      <DD><TT>script </TT> <I>Tcl_script</I>
      <DD><TT>files </TT> <TT>{</TT> <I>list_of_files</I> <TT>}</TT>
      <DD><TT>stage_count </TT> <I>number_of_stages</I>
      <DD><TT>multiplier </TT> <I>multiplier</I>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}
   The initialization string should specify either \cd{script} or
   \cd{files}, but not both.  If a \oxslabel{script} is specified,
   then each time a new stage is started in the simulation, a \Tcl\
   command is formed by appending to \oxsval{Tcl\_script} the 0-based
   integer stage number.  This command should return a reference to an
   \cd{Oxs\_VectorField} object, as either the instance name of an
   object defined via a top-level Specify block elsewhere in the
   \MIF\ file, or as a two item list consisting of the name of an
   \cd{Oxs\_VectorField} class and an appropriate initialization string.
   In the latter case the \cd{Oxs\_VectorField} object will be created
   as a temporary object via an inlined Specify call.

   The following example should help clarify the use of the \cd{script}
   parameter.
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
proc SlidingField { xcutoff xrel yrel zrel } {
   if {$xrel>$xcutoff} { return [list 0. 0. 0.] }
   return [list 2e4 0. 0.]
}

proc SlidingFieldSpec { stage } {
  set xcutoff [expr {double($stage)/10.}]
  set spec Oxs_ScriptVectorField
  lappend spec [subst {
      atlas :atlas
      script {SlidingField $xcutoff}
   }]
   return $spec
}

Specify Oxs_StageZeeman {
  script SlidingFieldSpec
  stage_count 11
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}

   The \cd{SlidingFieldSpec} proc is used to generate the initialization
   string for an \cd{Oxs\_ScriptVectorField} vector field object, which
   in turn uses the \cd{SlidingField} proc to specify the applied field
   on a position-by-position basis.  The resulting field will be
   \latex{$2\times 10^4$}\html{2e4} A/m in the positive x-direction at
   all points with relative x-coordinate larger than \cd{\$stage/10.},
   and 0 otherwise.  \cd{\$stage} is the stage index, which here is
   one of 0, 1, \ldots, 10.  For example, if \cd{\$stage} is 5, then the
   left half of the sample will see a \latex{$2\times 10^4$}\html{2e4}
   A/m field directed to the right, and the right half of the sample
   will see none.  The return value from \cd{SlidingFieldSpec} in this
   case will be
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Oxs_ScriptVectorField {
   atlas :atlas
   script {SlidingField 0.5}
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
   The \verb+:atlas+ reference is to an \cd{Oxs\_Atlas} object defined
   elsewhere in the MIF file.

   The \oxslabel{stage\_count} parameter lets the
   \hyperrefhtml{\cd{Oxs\_Driver}}{\cd{Oxs\_Driver}
   (Sec.~}{)}{sec:oxsDrivers} know how many stages the
   \cd{Oxs\_StageZeeman} object wants.  A value of 0 indicates that the
   object is prepared for any range of stages.  Zero is the default
   value for \cd{stage\_count} when using the \oxsval{Tcl\_script}
   interface.  The \cd{stage\_count} value given here must be compatible
   with the \htmlonlyref{\cd{stage\_count} setting in the driver Specify
   block}{html:oxsdriverstagecount}\latex{\ (q.v.)}.

   The example above made use of two scripts, one to specify the
   \cd{Oxs\_VectorField} object, and one used internally by the
   \cd{Oxs\_ScriptVectorField} object.  But any \cd{Oxs\_VectorField}
   class may be used, as in the next example.
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
proc FileField { stage } {
  set filelist { field-a.ohf field-b.ohf field-c.ohf }
  set spec Oxs_FileVectorField
  lappend spec [subst {
      atlas :atlas
      file [lindex $filelist $stage]
   }]
   return $spec
}

Specify Oxs_StageZeeman {
  script FileField
  stage_count 3
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
   The \cd{FileField} proc yields a specification for an
   \cd{Oxs\_FileVectorField} object that loads one of three files,
   \cd{field-a.ohf}, \cd{field-b.ohf}, or \cd{field-c.ohf}, depending on
   the stage number.

   Specifying applied fields from a sequence of files is common enough
   to warrant a simplified interface.  This is the purpose of the
   \oxslabel{files} parameter:
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_StageZeeman {
  files { field-a.ohf field-b.ohf field-c.ohf }
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
   This is essentially equivalent to the preceding example, with two
   differences.  First, \cd{stage\_count} is not needed because
   \cd{Oxs\_StageZeeman} knows the length of the list of files.  You may
   specify \cd{stage\_count}, but the default value is the length of the
   \cd{files} list.  This is in contrast to the default value
   of 0 when using the \cd{script} interface.  If \cd{stage\_count} is
   set larger than the file list, then the last file is repeated as
   necessary to reach the specified size.

   The second difference is that no \cd{Oxs\_Atlas} is specified when
   using the \cd{files} interface.  The \cd{Oxs\_FileVectorField} object
   spatially scales the field read from the file to match a specified
   volume.  Typically a volume is specified by explicit reference to an
   atlas, but with the \cd{files} interface to \cd{Oxs\_StageZeeman} the
   file fields are implicitly scaled to match the whole of the meshed
   simulation volume.  This is the most common case; to obtain a
   different spatial scaling use the \cd{script} interface as
   illustrated above with a different atlas or an explicit x/y/z-range
   specification.

   The \oxsval{list\_of\_files} value is interpreted as a
   \htmlonlyref{\textit{grouped list}}{par:groupedLists}.  \latex{See
   the notes in Sec.~\ref{par:groupedLists} for details on grouped
   lists.}

   The remaining \cd{Oxs\_StageZeeman} parameter is
   \oxslabel{multiplier}.  The value of this parameter is applied as a
   scale factor to the field magnitude on a point-by-point basis.  For
   example, if the field returned by the \cd{Oxs\_VectorField} object
   were in Oe, instead of the required A/m, then \cd{multiplier} could
   be set to 79.5775 to perform the conversion.  The direction of the
   applied field can be reversed by supplying a negative \cd{multiplier}
   value.

   In addition to the standard energy and field outputs, the
   \cd{Oxs\_StageZeeman} class provides these four scalar outputs:
   \begin{itemize}
   \item \textbf{B max:} Pointwise maximum magnitude of the applied
     field, in mT.  This is a non-negative quantity;
     \begin{latexonly}
       $\textrm{B max} = \sqrt{(\textrm{Bx max})^2
                               +(\textrm{By max})^2+(\textrm{Bz max})^2}.$
     \end{latexonly}
     \begin{rawhtml}
B&nbsp;max&nbsp;=&nbsp;[(Bx&nbsp;max)<SUP>2</SUP>+(By&nbsp;max)<SUP>2</SUP>+(Bz&nbsp;max)<SUP>2</SUP>]<SUP>1/2</SUP>.
     \end{rawhtml}
   \item \textbf{Bx max:} Signed value of the $x$-component of the applied
     field at the point of maximum applied field magnitude, in mT.
   \item \textbf{By max:} Signed value of the $y$-component of the applied
     field at the point of maximum applied field magnitude, in mT.
   \item \textbf{Bz max:} Signed value of the $z$-component of the applied
     field at the point of maximum applied field magnitude, in mT.
   \end{itemize}

   \begin{sloppypar}
   \raggedright
   \textbf{Examples:} \fn{sliding.mif}, \fn{slidingproc.mif},
                      \fn{rotatestage.mif}, \fn{rotatecenterstage.mif}.
   \end{sloppypar}

\end{description}
\end{itemize}

\subsubsection{Evolvers\label{sec:oxsEvolvers}}
Evolvers are responsible for updating the magnetization configuration
from one step to the next.  There are two types of evolvers,
\textit{time evolvers}, which track Landau-Lifshitz-Gilbert dynamics,
and \textit{minimization evolvers}, which locate local minima in the
energy surface through direct minimization techniques.  Evolvers are
controlled by \hyperrefhtml{drivers}{\textit{drivers}
(Sec.~}{)}{sec:oxsDrivers}, and must be matched with the appropriate
driver type, i.e., time evolvers must be paired with
\htmlonlyref{time drivers}{item:TimeDriver}, and
minimization evolvers must be paired with \htmlonlyref{minimization
drivers}{html:MinDriver}.  The drivers hand a magnetization
configuration to the evolvers with a request to advance the
configuration by one \textit{step} (also called an \textit{iteration}).
It is the role of the drivers, not the evolvers, to determine when a
simulation stage or run is complete.  Specify blocks for evolvers
contain parameters to control all aspects of individual stepwise
evolution, but stopping criteria are communicated in the Specify block
of the driver, not the evolver.

There are currently three time evolvers and one minimization evolver in the
standard \OOMMF\ distribution.  The time evolvers are
\htmlonlyref{\cd{Oxs\_EulerEvolve}}{html:EulerEvolve},
\htmlonlyref{\cd{Oxs\_RungeKuttaEvolve}}{html:RungeKuttaEvolve}, and
\htmlonlyref{\cd{Oxs\_SpinXferEvolve}}{html:SpinXferEvolve}.
The minimization evolver is
\htmlonlyref{\cd{Oxs\_CGEvolve}}{html:CGEvolve}.
\begin{description}
\begin{rawhtml}<A NAME="EE"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_EulerEvolve}%
\item[Oxs\_EulerEvolve:\label{html:EulerEvolve}]
Time evolver implementing a simple first order forward Euler method with
step size control on the Landau-Lifshitz
ODE\index{ODE!Landau-Lifshitz}~\cite{gilbert55,landau35}:\\
\begin{equation}
\htmlimage{antialias}
  \frac{d\vM}{dt} = -|\bar{\gamma}|\,\vM\times\vH_{\rm eff}
   - \frac{|\bar{\gamma}|\alpha}{M_s}\,
     \vM\times\left(\vM\times\vH_{\rm eff}\right),
\label{eq:oxsllode}
\end{equation}
where $\vM$ is the magnetization, $\vH_{\rm eff}$ is the effective
field, \abovemath{\bar{\gamma}} is the Landau-Lifshitz gyromagnetic ratio, and
\abovemath{\alpha} is the damping constant. The Gilbert form
\begin{equation}
\htmlimage{antialias}
  \frac{d\vM}{dt} = -|\gamma|\,\vM\times\vH_{\rm eff}
   + \frac{\alpha}{M_s}
     \left(\vM\times\frac{d\vM}{dt}\right),
\label{eq:oxsllgode}
\end{equation}
where \abovemath{\gamma} is the Gilbert gyromagnetic ratio, is
mathematically equivalent to the Landau-Lifshitz form under the
relation \abovemath{\gamma = (1+\alpha^2)\,\bar{\gamma}}.

The Specify block has the form
   \begin{latexonly}
   \begin{quote}\tt
   Specify Oxs\_EulerEvolve:\oxsval{name} \ocb\\
    \bi alpha                  \oxsval{$\alpha$}\\
    \bi gamma\_LL              \oxsval{$\bar{\gamma}$}\\
    \bi gamma\_G               \oxsval{$\gamma$}\\
    \bi do\_precess            \oxsval{precess}\\
    \bi min\_timestep          \oxsval{minimum\_stepsize}\\
    \bi max\_timestep          \oxsval{maximum\_stepsize}\\
    \bi fixed\_spins \ocb\\
    \bi\bi \oxsval{atlas\_spec}\\
    \bi\bi \oxsval{region1 region2 \ldots}\\
    \bi\ccb\\
    \bi start\_dm              \oxsval{$\Delta \vm$}\\
    \bi error\_rate            \oxsval{rate}\\
    \bi absolute\_step\_error  \oxsval{abs\_error}\\
    \bi relative\_step\_error  \oxsval{rel\_error}\\
    \bi step\_headroom         \oxsval{headroom}\\
   \ccb
   \end{quote}
   \end{latexonly}%
   \begin{htmlonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_EulerEvolve:</TT><I>name</I> <TT>{</TT>
   <DD><TT> alpha </TT>
   \end{rawhtml}
   \abovemath{\alpha}
   \begin{rawhtml}
   <DD><TT> gamma_LL </TT>
   \end{rawhtml}
   \abovemath{\bar{\gamma}}
   \begin{rawhtml}
   <DD><TT> gamma_G </TT>
   \end{rawhtml}
   \abovemath{\gamma}
   \begin{rawhtml}
   <DD><TT> do_precess </TT> <I>precess</I>
   <DD><TT> min_timestep </TT> <I>minimum_stepsize</I>
   <DD><TT> max_timestep </TT> <I>maximum_stepsize</I>
   <DD><TT> fixed_spins {</TT><DL>
       <DD><I>atlas_spec</I>
       <DD><I>region1</I><TT>&nbsp;</TT><I>region2</I><TT> ...</TT>
       <DT><TT>}</TT></DL>
   <DD><TT> start_dm </TT>
   \end{rawhtml}
   $\Delta \vm$
   \begin{rawhtml}
   <DD><TT> error_rate </TT> <I>rate</I>
   <DD><TT> absolute_step_error </TT> <I>abs_error</I>
   <DD><TT> relative_step_error </TT> <I>rel_error</I>
   <DD><TT> step_headroom </TT> <I>headroom</I>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   \end{htmlonly}
All the entries have default values, but the ones most commonly adjusted
are listed first.

The options \oxslabel{alpha}, \oxslabel{gamma\_LL} and
\oxslabel{gamma\_G} are as in the Landau-Lifshitz-Gilbert ODE
(\ref{eq:oxsllode}), (\ref{eq:oxsllgode}), where the units on
\abovemath{\bar{\gamma}} and \abovemath{\gamma} are m/A$\cdot$s and
\abovemath{\alpha} is dimensionless.  At most one of
\abovemath{\bar{\gamma}} and \abovemath{\gamma} should be specified.  If
neither is specified, then the default is
\latex{$\gamma=2.211\times 10^5$.}%
\html{\abovemath{\gamma}$=2.211\times 10^5$.}
(Because of the absolute value convention adopted on
\abovemath{\bar{\gamma}} and \abovemath{\gamma} in
(\ref{eq:oxsllode}), (\ref{eq:oxsllgode}), the sign given to the value of
\texttt{gamma\_LL} or \texttt{gamma\_G} in the Specify block is
irrelevant.)  The default value for \abovemath{\alpha} is 0.5, which is
large compared to experimental values, but allows simulations to
converge to equilibria in a reasonable time.  However, for accurate
dynamic studies it is important to assign an appropriate value to
\abovemath{\alpha}.

The \oxslabel{do\_precess} value should be either 1 or 0, and determines
whether or not the precession term in the Landau-Lifshitz ODE (i.e., the
first term on the righthand side in (\ref{eq:oxsllode})) is used.  If
\oxsval{precess} is 0, then precession is disabled and the simulation
evolves towards equilibrium along a steepest descent path.  The default
value is 1.

The \oxslabel{min\_timestep} and \oxslabel{max\_timestep} parameters provide
soft limits on the size of steps taken by the evolver.  The minimum
value may be overridden by the driver if a smaller step is needed to
meet time based stopping criteria.  The maximum value will be ignored if
a step of that size would produce a magnetization state numerically
indistinguishable from the preceding state.  The units for
\texttt{min\_timestep} and \texttt{max\_timestep} are seconds.  Default
values are 0 and $10^{-10}$ respectively.

The optional \oxslabel{fixed\_spins} entry allows the magnetization in
selected regions of the simulation to be frozen in its initial
configuration.  The value portion of the entry should be a list, with
the first element of the list being either an inline atlas definition
(grouped as a single item), or else the name of a previously defined
atlas.  The remainder of the list are names of regions in that atlas for
which the magnetization is to be be fixed, i.e., $\vM(t)=\vM(0)$ for all
time $t$ for all points in the named regions.  Fields and energies are
computed and reported normally across these regions.  Although any atlas
may be used, it is frequently convenient to set up an atlas with special
regions defined expressly for this purpose.

The stepsize for the first candidate iteration in the problem run is
selected so that the maximum change in the normalized (i.e., unit)
magnetization $\vm$ is the value specified by \oxslabel{start\_dm}.  The
units are degrees, with default value 0.01.

The four remaining entries, \oxslabel{error\_rate},
\oxslabel{absolute\_step\_error}, \oxslabel{relative\_step\_error}, and
\oxslabel{step\_headroom}, control fine points of stepsize selection,
and are intended for advance use only.  Given normalized magnetization
$\vm_i(t)$ at time $t$ and position $i$, and candidate magnetization
$\vm_i(t+\Delta t)$ at time $t+\Delta t$, the error at position $i$ is
estimated to be
\begin{displaymath}
\htmlimage{antialias}
\mbox{Error}_i =
  \left|\dot{\vm}_i(t+\Delta t) - \dot{\vm}_i(t)\right|\Delta t
      \,/\,2,
\end{displaymath}
where the derivative with respect to time, $\dot{\vm}$, is computed
using the Landau-Lifshitz ODE (\ref{eq:oxsllode}).  First order methods
essentially assume that $\dot{\vm}$ is constant on the interval
$[t,t+\Delta t]$; the above formula uses the difference in $\dot{\vm}$
at the endpoints of the interval to estimate (guess) how untrue that
assumption is.

A candidate step is accepted if the maximum error across all positions
$i$ is smaller than \texttt{absolute\_step\_error},
\texttt{error\_rate}$\,\times\,\Delta t$, and
\texttt{relative\_step\_error}$\,\times\,|\dot{\vm}_{\rm
max}|\Delta t$, where $|\dot{\vm}_{\rm max}|$ is the maximum value of
$|\dot{\vm}_i|$ across all $i$ at time $t$.  If the step is rejected,
then a smaller stepsize is computed that appears to pass the above
tests, and a new candidate step is proposed using that smaller stepsize
times \texttt{step\_headroom}.  Alternatively, if the step is accepted,
then the error information is used to determine the stepsize for the
next step, modified in the same manner by \texttt{step\_headroom}.

The error calculated above is in terms of unit magnetizations, so the
natural units are radians or radians/second.  Inside the Specify block,
however, the \texttt{error\_rate} and \texttt{absolute\_step\_error} are
specified in degrees/nanosecond and degrees, respectively; they are
converted appropriately inside the code before use.  The
\texttt{relative\_step\_error} is a dimensionless quantity, representing a
proportion between 0 and 1.  The error check controlled by each of these
three quantities may be disabled by setting the quantity value to -1.
They are all optional, with default values of -1 for \texttt{error\_rate},
0.2 for \texttt{absolute\_step\_error}, and 0.2 for
\texttt{relative\_step\_error}.

The \cd{headroom} quantity should lie in the range $(0,1)$, and controls
how conservative the code will be in stepsize selection.  If \cd{headroom}
is too large, then much computation time will be lost computing
candidate steps that fail the error control tests.  If \cd{headroom} is
small, then most candidate steps will pass the error control tests, but
computation time may be wasted calculating more steps than are
necessary.  The default value for \cd{headroom} is 0.85.

In addition to the above error control tests, a candidate step will also
be rejected if the total energy, after adjusting for effects due to any
time varying external field, is found to increase.  In this case the
next candidate stepsize is set to one half the rejected stepsize.

The \cd{Oxs\_EulerEvolve} module provides five scalar, one scalar
field, and three vector field outputs.  The scalar outputs are
\begin{itemize}
\item \textbf{Max dm/dt:} maximum $|d\vm/dt|$, in degrees per
   nanosecond; $\vm$ is the unit magnetization direction.
\item \textbf{Total energy:} in joules.
\item \textbf{Delta E:} change in energy between last step and current
   step, in joules.
\item \textbf{dE/dt:} derivative of energy with respect to time, in
   joules per second.
\item \textbf{Energy calc count:} number of times total energy has been
   calculated.
\end{itemize}

The scalar field output is
\begin{itemize}
\item \textbf{Total energy density:} cellwise total energy density, in
\latexhtml{J/m${}^3$}{J/m\begin{rawhtml}<SUP>3</SUP>\end{rawhtml}}.
\end{itemize}

The vector field outputs are
\begin{itemize}
\item \textbf{Total field:} total effective field $\vH$ in A/m.
\item \textbf{mxH:} torque in A/m; $\vm$ is the unit magnetization
   direction, $\vH$ is the total effective field.
\item \textbf{dm/dt:} derivative of spin $\vm$ with respect to time, in
   radians per second.
\end{itemize}

\textbf{Example:} \fn{octant.mif}.

\begin{rawhtml}<A NAME="RK"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_RungeKuttaEvolve}%
\item[Oxs\_RungeKuttaEvolve:\label{html:RungeKuttaEvolve}]
Time evolver implementing several Runge-Kutta methods for integrating
the Landau-Lifshitz-Gilbert\index{ODE!Landau-Lifshitz} ODE
(\ref{eq:oxsllode}), (\ref{eq:oxsllgode}), with step size control.  In
most cases it will greatly outperform the \cd{Oxs\_EulerEvolve} class.
The Specify block has the form
   \begin{latexonly}
   \begin{quote}\tt
   Specify Oxs\_RungeKuttaEvolve:\oxsval{name} \ocb\\
    \bi alpha                  \oxsval{$\alpha$}\\
    \bi gamma\_LL              \oxsval{$\bar{\gamma}$}\\
    \bi gamma\_G               \oxsval{$\gamma$}\\
    \bi do\_precess            \oxsval{precess}\\
    \bi allow\_signed\_gamma \oxsval{signed\_gamma}\\
    \bi min\_timestep          \oxsval{minimum\_stepsize}\\
    \bi max\_timestep          \oxsval{maximum\_stepsize}\\
    \bi fixed\_spins \ocb\\
    \bi\bi \oxsval{atlas\_spec}\\
    \bi\bi  \oxsval{region1 region2 \ldots}\\
    \bi\ccb\\
    \bi start\_dm              \oxsval{$\Delta \vm$}\\
    \bi start\_dt              \oxsval{start\_timestep}\\
    \bi stage\_start           \oxsval{scontinuity}\\
    \bi error\_rate            \oxsval{rate}\\
    \bi absolute\_step\_error  \oxsval{abs\_error}\\
    \bi relative\_step\_error  \oxsval{rel\_error}\\
    \bi energy\_precision      \oxsval{eprecision}\\
    \bi min\_step\_headroom    \oxsval{min\_headroom}\\
    \bi max\_step\_headroom    \oxsval{max\_headroom}\\
    \bi reject\_goal           \oxsval{reject\_proportion}\\
    \bi method                 \oxsval{subtype}\\
   \ccb
   \end{quote}
   \end{latexonly}%
   \begin{htmlonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_RungeKuttaEvolve:</TT><I>name</I> <TT>{</TT>
   <DD><TT> alpha </TT>
   \end{rawhtml}
   \abovemath{\alpha}
   \begin{rawhtml}
   <DD><TT> gamma_LL </TT>
   \end{rawhtml}
   \abovemath{\bar{\gamma}}
   \begin{rawhtml}
   <DD><TT> gamma_G </TT>
   \end{rawhtml}
   \abovemath{\gamma}
   \begin{rawhtml}
   <DD><TT> do_precess </TT> <I>precess</I>
   <DD><TT> allow_signed_gamma </TT> <I>signed_gamma</I>
   <DD><TT> min_timestep </TT> <I>minimum_stepsize</I>
   <DD><TT> max_timestep </TT> <I>maximum_stepsize</I>
   <DD><TT> fixed_spins {</TT><DL>
       <DD><I>atlas_spec</I>
       <DD><I>region1</I><TT>&nbsp;</TT><I>region2</I><TT> ...</TT>
       <DT><TT>}</TT></DL>
   <DD><TT> start_dm </TT>
   \end{rawhtml}
   $\Delta \vm$
   \begin{rawhtml}
   <DD><TT> start_dt </TT> <I>start_timestep</I>
   <DD><TT> stage_start </TT> <I>scontinuity</I>
   <DD><TT> error_rate </TT> <I>rate</I>
   <DD><TT> absolute_step_error </TT> <I>abs_error</I>
   <DD><TT> relative_step_error </TT> <I>rel_error</I>
   <DD><TT> energy_precision </TT> <I>eprecision</I>
   <DD><TT> min_step_headroom </TT> <I>min_headroom</I>
   <DD><TT> max_step_headroom </TT> <I>max_headroom</I>
   <DD><TT> reject_goal </TT> <I>reject_proportion</I>
   <DD><TT> method </TT> <I>subtype</I>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   \end{htmlonly}
Most of these options appear also in the
\htmlonlyref{\cd{Oxs\_EulerEvolve}}{html:EulerEvolve} class.
The repeats have the same meaning as in that class, and the same
default values except for \texttt{relative\_step\_error} and
\texttt{error\_rate}, which for \cd{Oxs\_RungeKuttaEvolve} have the
default values of 0.01 and 1.0, respectively.  Additionally, the
\oxslabel{alpha}, \oxslabel{gamma\_LL} and \oxslabel{gamma\_G} options
may be initialized using scalar field objects, to allow these material
parameters to vary spatially.

The \oxslabel{allow\_signed\_gamma} parameter is for simulation testing
purposes, and is intended for advanced use only.  There is some lack of
consistency in the literature with respect to the sign of
\abovemath{\gamma}.  For this reason the Landau-Lifshitz-Gilbert
equations are presented above (\ref{eq:oxsllode}, \ref{eq:oxsllgode})
using the absolute value of \abovemath{\gamma}.  This is the
interpretation used if \cd{allow\_signed\_gamma} is 0 (the default).  If
instead \cd{allow\_signed\_gamma} is set to 1, then the
Landau-Lifshitz-Gilbert equations are interpreted without the absolute
values and with a sign change on the \abovemath{\gamma} terms, i.e., the
default value for \abovemath{\gamma} in this case is $-2.211 \times
10^5$ (units are m/A$\cdot$s).  In this setting, if \abovemath{\gamma}
is set positive then the spins will precess backwards about the
effective field, and the damping term will force the spins \textbf{away}
from the effective field and increase the total energy.  If you are
experimenting with \abovemath{\gamma>0}, you should either set
\abovemath{\alpha<=0} to force spins back towards the effective field,
or disable the energy precision control (discussed
\htmlonlyref{below}{html:oxsrkeprecision}).

The two controls \oxslabel{min\_step\_headroom} (default value 0.33) and
\oxslabel{max\_step\_headroom} (default value 0.95) replace the single
\cd{step\_headroom} option in \cd{Oxs\_EulerEvolve}.  The effective
\cd{step\_headroom} is automatically adjusted by the evolver between the
\oxsval{min\_headroom} and \oxsval{max\_headroom} limits to make the
observed reject proportion approach the \oxslabel{reject\_goal} (default
value 0.05).

The \oxslabel{method} entry selects a particular Runge-Kutta
implementation.  It should be set to one of \oxsval{rk2},
\oxsval{rk4}, \oxsval{rkf54}, \oxsval{rkf54m}, or \oxsval{rkf54s};
the default value is \oxsval{rkf54}.  The \oxsval{rk2} and
\oxsval{rk4} methods implement canonical second and fourth global order
Runge-Kutta methods\cite{stoer93}, respectively.  For \oxsval{rk2},
stepsize control is managed by comparing $\dot{\vm}$ at the middle and
final points of the interval, similar to what is done for stepsize
control for the \cd{Oxs\_EulerEvolve} class.  One step of the
\oxsval{rk2} method involves 2 evaluations of $\dot{\vm}$.

In the \oxsval{rk4} method, two successive steps are taken at half the
nominal step size, and the difference between that end point and that
obtained with one full size step are compared.  The error is estimated at
1/15th the maximum difference between these two states.  One step of the
\oxsval{rk4} method involves 11 evaluations of $\dot{\vm}$, but the
end result is that of the 2 half-sized steps.

The remaining methods, \oxsval{rkf54},  \oxsval{rkf54m},
and \oxsval{rkf54s}, are closely related Runge-Kutta-Fehlberg methods
derived by Dormand and Prince\cite{dormand80,dormand86}.  In the
nomenclature of these papers,
\oxsval{rkf54} implements RK5(4)7FC,
\oxsval{rkf54m} implements RK5(4)7FM, and
\oxsval{rkf54s} implements RK5(4)7FS.
All are 5th global order with an embedded 4th order method for stepsize
control.  Each step of these methods requires 6 evaluations of
$\dot{\vm}$ if the step is accepted, 7 if rejected.  The difference
between the methods involves tradeoffs between stability and error
minimization.  The RK5(4)7FS method has the best stability, RK5(4)7FM
the smallest error, and RK5(4)7FC represents a compromise between the
two.  The default method used by \cd{Oxs\_RungeKuttaEvolve} is
RK5(4)7FC.

\label{html:oxsrkeprecision}
The remaining undiscussed entry in the \cd{Oxs\_RungeKuttaEvolve}
Specify block is \oxslabel{energy\_precision}.  This should be set to an
estimate of the expected relative accuracy of the energy calculation.
After accounting for any change in the total energy arising from
time-varying applied fields, the energy remainder should decrease from
one step of the LLG ODE to the next.  \cd{Oxs\_RungeKuttaEvolve} will
reject a step if the energy remainder is found to increase by more than
that allowed by \oxsval{eprecision}.  The default value for
\oxsval{eprecision} is \latex{$10^{-10}$.}\html{1e-10.}  This control
may be disabled by setting \oxsval{eprecision} to -1.

The \cd{Oxs\_RungeKuttaEvolve} module provides the same scalar, scalar
field, and vector field outputs as \cd{Oxs\_EulerEvolve}.

\textbf{Examples:} \fn{sample.mif}, \fn{acsample.mif},
                   \fn{varalpha.mif}, \fn{yoyo.mif}.

\begin{rawhtml}<A NAME="SX"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_SpinXferEvolve}%
\item[Oxs\_SpinXferEvolve:\label{html:SpinXferEvolve}]
Time evolver that integrates an
Landau-Lifshitz-Gilbert\index{ODE!Landau-Lifshitz} ODE augmented with a
spin momentum term \cite{xiao04},
\begin{equation}
\htmlimage{antialias}
  \frac{d\vm}{dt} = -|\gamma|\,\vm\times\vH_{\rm eff}
   + \alpha
     \left(\vm\times\frac{d\vm}{dt}\right)
   + |\gamma|\beta\epsilon
     \left(\vm\times\vm_p\times\vm\right)
   - |\gamma|\beta\epsilon^\prime\,\vm\times\vm_p
\label{eq:oxsllgspinxfer}
\end{equation}
(compare to (\ref{eq:oxsllgode})), where
\begin{eqnarray*}
\vm & = & \mbox{reduced magnetization, $\vM/M_s$} \\
\gamma & = & \mbox{Gilbert gyromagnetic ratio} \\
\beta & = & \left|\frac{\hbar}{\mu_0 e}\right|\frac{J}{t M_s} \\
\vm_p & = & \mbox{(unit) electron polarization direction} \\
\epsilon & = &
\frac{P\Lambda^2}{(\Lambda^2+1)+(\Lambda^2-1)(\vm\cdot\vm_p)} \\
\epsilon^\prime & = & \mbox{secondary spin tranfer term}.
\end{eqnarray*}
In the definition of $\beta$, $e$ is the electron charge in C, $J$ is
current density in A/m${}^2$, $t$ is the free layer thickness in meters,
and $M_s$ is the saturation magnetization in A/m.

The various parameters are defined in the Specify block, which is an
extension of that for the
\htmlonlyref{\cd{Oxs\_RungeKuttaEvolve}}{html:RungeKuttaEvolve} class:
   \begin{latexonly}
   \begin{quote}\tt
   Specify Oxs\_SpinXferEvolve:\oxsval{name} \ocb\\
    \bi alpha                  \oxsval{$\alpha$}\\
    \bi gamma\_LL              \oxsval{$\bar{\gamma}$}\\
    \bi gamma\_G               \oxsval{$\gamma$}\\
    \bi do\_precess            \oxsval{precess}\\
    \bi allow\_signed\_gamma \oxsval{signed\_gamma}\\
    \bi min\_timestep          \oxsval{minimum\_stepsize}\\
    \bi max\_timestep          \oxsval{maximum\_stepsize}\\
    \bi fixed\_spins \ocb\\
    \bi\bi \oxsval{atlas\_spec}\\
    \bi\bi  \oxsval{region1 region2 \ldots}\\
    \bi\ccb\\
    \bi start\_dm              \oxsval{$\Delta \vm$}\\
    \bi stage\_start           \oxsval{scontinuity}\\
    \bi error\_rate            \oxsval{rate}\\
    \bi absolute\_step\_error  \oxsval{abs\_error}\\
    \bi relative\_step\_error  \oxsval{rel\_error}\\
    \bi energy\_precision      \oxsval{eprecision}\\
    \bi min\_step\_headroom    \oxsval{min\_headroom}\\
    \bi max\_step\_headroom    \oxsval{max\_headroom}\\
    \bi reject\_goal           \oxsval{reject\_proportion}\\
    \bi method                 \oxsval{subtype}\\
    \bi P                      \oxsval{polarization}\\
    \bi P\_fixed               \oxsval{p\_fixed\_layer}\\
    \bi P\_free                \oxsval{p\_free\_layer}\\
    \bi Lambda                 \oxsval{$\Lambda$}\\
    \bi Lambda\_fixed          \oxsval{$\Lambda$\_fixed\_layer}\\
    \bi Lambda\_free           \oxsval{$\Lambda$\_free\_layer}\\
    \bi eps\_prime             \oxsval{ep}\\
    \bi J                      \oxsval{current\_density}\\
    \bi J\_profile             \oxsval{Jprofile\_script}\\
    \bi J\_profile\_args       \oxsval{Jprofile\_script\_args}\\
    \bi mp                     \oxsval{p\_direction}\\
    \bi energy\_slack          \oxsval{eslack}\\
   \ccb
   \end{quote}
   \end{latexonly}%
   \begin{htmlonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_SpinXferEvolve:</TT><I>name</I> <TT>{</TT>
   <DD><TT> alpha </TT>
   \end{rawhtml}
   \abovemath{\alpha}
   \begin{rawhtml}
   <DD><TT> gamma_LL </TT>
   \end{rawhtml}
   \abovemath{\bar{\gamma}}
   \begin{rawhtml}
   <DD><TT> gamma_G </TT>
   \end{rawhtml}
   \abovemath{\gamma}
   \begin{rawhtml}
   <DD><TT> do_precess </TT> <I>precess</I>
   <DD><TT> allow_signed_gamma </TT> <I>signed_gamma</I>
   <DD><TT> min_timestep </TT> <I>minimum_stepsize</I>
   <DD><TT> max_timestep </TT> <I>maximum_stepsize</I>
   <DD><TT> fixed_spins {</TT><DL>
       <DD><I>atlas_spec</I>
       <DD><I>region1</I><TT>&nbsp;</TT><I>region2</I><TT> ...</TT>
       <DT><TT>}</TT></DL>
   <DD><TT> start_dm </TT>
   \end{rawhtml}
   $\Delta \vm$
   \begin{rawhtml}
   <DD><TT> stage_start </TT> <I>scontinuity</I>
   <DD><TT> error_rate </TT> <I>rate</I>
   <DD><TT> absolute_step_error </TT> <I>abs_error</I>
   <DD><TT> relative_step_error </TT> <I>rel_error</I>
   <DD><TT> energy_precision </TT> <I>eprecision</I>
   <DD><TT> min_step_headroom </TT> <I>min_headroom</I>
   <DD><TT> max_step_headroom </TT> <I>max_headroom</I>
   <DD><TT> reject_goal </TT> <I>reject_proportion</I>
   <DD><TT> method </TT> <I>subtype</I>
   <DD><TT> P </TT> <I>polarization</I>
   <DD><TT> P_fixed </TT> <I>p_fixed_layer</I>
   <DD><TT> P_free </TT> <I>p_free_layer</I>
   <DD><TT> Lambda </TT>
   \end{rawhtml}
   $\Lambda$
   \begin{rawhtml}
   <DD><TT> Lambda_fixed </TT>
   \end{rawhtml}
   $\Lambda$\_fixed\_layer
   \begin{rawhtml}
   <DD><TT> Lambda_free </TT>
   \end{rawhtml}
   $\Lambda$\_free\_layer
   \begin{rawhtml}
   <DD><TT> eps_prime </TT> <I>ep</I>
   <DD><TT> J </TT> <I>current_density</I>
   <DD><TT> J_profile </TT> <I>Jprofile_script</I>
   <DD><TT> J_profile_args </TT> <I>Jprofile_script_args</I>
   <DD><TT> mp </TT> <I>p_direction</I>
   <DD><TT> energy_slack </TT> <I>eslack</I>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   \end{htmlonly}
The options duplicated in the 
\htmlonlyref{\cd{Oxs\_RungeKuttaEvolve}}{html:RungeKuttaEvolve} class
Specify block have the same meaning and default values here, with the
exception of \texttt{error\_rate}, which for
\cd{Oxs\_SpinXferEvolve} has the default value of -1 (i.e., disabled).

The default values for \oxslabel{P} and \oxslabel{Lambda} are 0.4 and 2,
respectively.  If preferred, values for the fixed and free layers may be
instead specified separately, through \oxslabel{P\_fixed},
\oxslabel{P\_free}, \oxslabel{Lambda\_fixed}, and
\oxslabel{Lambda\_free}.  Otherwise P\_fixed = P\_free = P and
Lambda\_fixed = Lambda\_free = Lambda.  Lambda must be larger than or
equal to 1; set Lambda=1 to remove the dependence of
\abovemath{\epsilon} on $\vm\cdot\vm_p$.  If you want non-zero
\abovemath{\epsilon^\prime}, it is set directly as
\oxslabel{eps\_prime}.

Current density \oxslabel{J} and unit polarization direction
\oxslabel{mp} are required.  The units on J are A/m${}^2$.  Positive J
produces torque that tends to align \abovemath{\vm} towards
\abovemath{\vm_p}.

Parameters J, mp, P, Lambda, and eps\_prime may all be varied pointwise,
but are fixed with respect to time.  However, J can be multiplied by a
time varying ``profile,'' to model current rise times, pulses, etc.  Use
the \oxslabel{J\_profile} and \oxslabel{J\_profile\_args} options to
enable this feature.  The \oxsval{Jprofile\_script} should be a \Tcl\
script that returns a single scalar.  \oxsval{Jprofile\_script\_args}
should be a subset of \cd{\ocb stage stage\_time total\_time\ccb}, to
specify arguments appended to \oxsval{Jprofile\_script} on each time
step.  Default is the entire set, in the order as listed.

The \cd{Oxs\_SpinXferEvolve} module provides the same five scalar
outputs and three vector outputs as \cd{Oxs\_RungeKutta}, plus the
scalar output ``average J,'' and the vector field outputs ``Spin
torque'' (which is
$|\gamma|\beta\epsilon\left(\vm\times\vm_p\times\vm\right)$) and
``J*mp.''  (Development note: In the case \texttt{propagate\_mp} is
enabled, \texttt{mp} is actually $\Delta_x\partial\vm/\partial\vx$,
where $\vx$ is the flow direction and $\Delta_x$ is the cell dimension
in that direction.)

The \cd{Oxs\_SpinXferEvolve} class does \textbf{not} include any oersted
field arising from the current.  Of course, arbitrary fields simulating
the oersted field may be added separately as Zeeman energy terms.  An
example of this is contained in the \fn{spinxfer.mif} sample file.

There are no temperature effects in this evolver, i.e., it is a T = 0 K
code.

Note also that $\vm_p$ is fixed.

For basic usage, the Specify block can be as simple as
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_SpinXferEvolve:evolve {
  alpha 0.014
  J 7.5e12
  mp {1 0 0}
  P 0.4
  Lambda 2
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}

This class is still in early development; at this time the example files
are located in \fn{oommf/app/oxs/local} instead of
\fn{oommf/app/oxs/examples}.

\textbf{Examples:} \fn{spinxfer.mif}, \fn{spinxfer-miltat.mif},
\fn{spinxfer-onespin.mif}.

\begin{rawhtml}<A NAME="CG"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_CGEvolve}%
\item[Oxs\_CGEvolve:\label{html:CGEvolve}]
The minimization evolver is \cd{Oxs\_CGEvolve}, which is an
in-development conjugate gradient minimizer with no preconditioning. The
Specify block has the form
   \begin{latexonly}
   \begin{quote}\tt
   Specify Oxs\_CGEvolve:\oxsval{name} \ocb\\
    \bi gradient\_reset\_angle   \oxsval{reset\_angle}\\
    \bi gradient\_reset\_count   \oxsval{count}\\
    \bi minimum\_bracket\_step   \oxsval{minbrack}\\
    \bi maximum\_bracket\_step   \oxsval{maxbrack}\\
    \bi line\_minimum\_angle\_precision \oxsval{min\_prec\_angle}\\
    \bi line\_minimum\_relwidth  \oxsval{relwidth}\\
    \bi energy\_precision \oxsval{eprecision}\\
    \bi method \oxsval{cgmethod}\\
    \bi fixed\_spins \ocb\\
    \bi\bi \oxsval{atlas\_spec}\\
    \bi\bi  \oxsval{region1 region2 \ldots}\\
    \bi\ccb\\
   \ccb
   \end{quote}
   \end{latexonly}%
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
   <TT>Specify Oxs_CGEvolve:</TT><I>name</I> <TT>{</TT>
   <DD><TT> gradient_reset_angle </TT> <I>reset_angle</I>
   <DD><TT> gradient_reset_count </TT> <I>count</I>
   <DD><TT> minimum_bracket_step </TT> <I>minbrack</I>
   <DD><TT> maximum_bracket_step </TT> <I>maxbrack</I>
   <DD><TT> line_minimum_angle_precision </TT> <I>min_prec_angle</I>
   <DD><TT> line_minimum_relwidth </TT> <I>relwidth</I>
   <DD><TT> energy_precision </TT> <I>eprecision</I>
   <DD><TT> method </TT> <I>cgmethod</I>
   <DD><TT> fixed_spins {</TT><DL>
       <DD><I>atlas_spec</I>
       <DD><I>region1</I><TT>&nbsp;</TT><I>region2</I><TT> ...</TT>
       <DT><TT>}</TT></DL>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
All entries have default values.

The evolution to an energy minimum precedes by a sequence of line
minimizations.  Each line represents a one dimensional affine subspace
in the $3N$ dimensional space of possible magnetization configurations,
where $N$ is the number of spins in the simulation.  Once a minimum has
been found along a line, a new direction is chosen that is ideally
orthogonal to all preceding directions, but related to the gradient of
the energy taken with respect to the magnetization.  In practice the
line direction sequence cannot be extended indefinitely; the parameters
\oxslabel{gradient\_reset\_angle} and \oxslabel{gradient\_reset\_count}
control the gradient resetting process.  The first checks the angle
between the new direction and the gradient.  If that angle is larger
than \oxsval{reset\_angle} (expressed in degrees), then the selected
direction is thrown away, and the conjugate-gradient process is
re-initialized with the gradient direction as the new first direction.
In a similar vein, \oxsval{count} specifies the maximum number of line
directions selected before resetting the process.  Because the first
line in the sequence is selected along the gradient direction, setting
\oxsval{count} to 1 effectively turns the algorithm into a steepest
descent minimization method.  The default values for
\oxsval{reset\_angle} and \oxsval{count} are 80 degrees and 50,
respectively.

Once a minimization direction has been selected, the first stage of the
line minimization is to bracket the minimum energy on that line, i.e.,
given a start point on the line\emdash the location of the minimum from the
previous line minimization\emdash find another point on the line such that
the energy minimum lies between those two points.  As one moves along
the line, the spins in the simulation rotate, with one spin rotating
faster than (or at least as fast as) all the others.  If the start point
was not the result of a successful line minimization from the previous
stage, then the first bracket attempt step is sized so that the fastest
moving spin rotates through the angle specified by
\oxslabel{minimum\_bracket\_step}.  In the more usual case that the
start point is a minimum from the previous line minimization stage, the
initial bracket attempt step size is set to the distance between the
current start point and the start point of the previous line
minimization stage.

The energy and gradient of the energy are examined at the candidate
bracket point to test if an energy minimum lies in the interval.  If
not, the interval is extended, based on the size of the first bracket
attempt interval and the derivatives of the energy at the interval
endpoints.  This process is continued until either a minimum is
bracketed or the fastest moving spin rotates through the angle specified
by \oxslabel{maximum\_bracket\_step}.

If the bracketing process is successful, then a one dimensional
minimization is carried out in the interval, using both energy and
energy derivative information.  Each step in this process reduces the
width of the bracketing interval.  This process is continued until
the angle between the line direction and the computed energy
gradient is within \oxslabel{line\_minimum\_angle\_precision} degrees of
orthogonal, and the width of the interval relative to the distance of the
interval from the start point (i.e., the stop point from the previous
line minimization process) is less than
\oxslabel{line\_minimum\_relwidth}.  The stop point,
i.e., the effective minimum, is taken to be the endpoint of the final
interval having smaller energy.  The default value for
\oxsval{min\_prec\_angle} is 1 degree, and the default value for
\oxsval{relwidth} is 1.  This latter setting effectively disables the
\texttt{line\_minimum\_relwidth} control, which should generally be used
only as a secondary control.

If the bracketing process is unsuccessful, i.e., the check for bracketed
energy minimum failed at the maximum bracket interval size allowed by
\texttt{maximum\_bracket\_step}, then the maximum bracket endpoint is
accepted as the next point in the minimization iteration.

Once the line minimum stop point has been selected, the next iteration
begins with selection of a new line direction, as described above,
except in the case where the stop point was not obtained as an actual
minimum, but rather by virtue of satisfying the
\texttt{maximum\_bracket\_step} constraint.  In that case the orthogonal
line sequence is reset, in the same manner as when the
\texttt{gradient\_reset\_angle} or \texttt{gradient\_reset\_count}
controls are triggered, and the next line direction is taken directly
from the energy gradient.

There are several factors to bear in mind when selecting values for
the parameters \texttt{minimum\_bracket\_step},
\texttt{maximum\_bracket\_step}, and \texttt{line\_minimum\_relwidth}.
If \texttt{minimum\_bracket\_step} is too small, then it may take a
great many steps to obtain an interval large enough to bracket the
minimum.  If \texttt{minimum\_bracket\_step} is too large, then the
bracket interval will be unnecessarily generous, and many steps may be
required to locate the minimum inside the bracketing interval.  However,
this value only comes into play when resetting the line minimization
direction sequence, so the setting is seldom critical.  It is specified
in degrees, with default value 0.05.

If \texttt{maximum\_bracket\_step} is too small, then the minima will be
mostly not bracketed, and the minimization will degenerate into a type
of steepest descent method.  On the other hand, if
\texttt{maximum\_bracket\_step} is too large, then the line
minimizations may draw the magnetization far away from a local energy
minimum (i.e., one on the full $3N$ dimensional magnetization space),
eventually ending up in a different, more distant minimum.  The value
for \texttt{maximum\_bracket\_step} is specified in degrees, with
default value 10.

The \texttt{line\_minimum\_angle\_precision} and
\texttt{line\_minimum\_relwidth} values determine the precision of the
individual line minimizations, not the total minimization procedure,
which is governed by the stopping criteria specified in the driver's
Specify block.  However, these values are important because the
precision of the line minimizations affects the the line direction
sequence orthogonality.  If both are too coarse, then the selected line
directions will quickly drift away from mutual orthogonality.
Conversely, setting either too fine will
produce additional line minimization steps that do nothing to improve
convergence towards the energy minimum in the full $3N$ dimensional
magnetization space.

The \oxslabel{energy\_precision} parameter estimates the relative
precision of the energy computations.  This is used to introduce a slack
factor into the energy comparisons during the bracketing and line
minimization stages, that is, if the computed energy values at two
points have relative error difference smaller than
\oxsval{eprecision}, they are treated as having the same energy.  The
default value for \oxsval{eprecision} is 1e-10.  The true precision
will depend primarily on the number of spins in the simulation.  It may
be necessary for very large simulations to increase the
\oxsval{eprecision} value.

The \oxslabel{method} parameter can be set to either
\texttt{Fletcher-Reeves} or \texttt{Polak-Ribiere} to specify the
conjugate gradient direction selection algorithm.  The default is
Fletcher-Reeves, which has somewhat smaller memory requirements.

The last parameter, \oxslabel{fixed\_spins}, performs the same function
as for the \htmlonlyref{\cd{Oxs\_EulerEvolve}}{html:EulerEvolve} class.

The \cd{Oxs\_CGEvolve} module provides nine scalar, one scalar
 field, and two vector field outputs.  The scalar outputs are
\begin{itemize}
\item \textbf{Max mxHxm:} maximum $|\vm\times\vH\times\vm|$, in A/m;
   $\vm$ is the unit magnetization direction.
\item \textbf{Total energy:} in joules.
\item \textbf{Delta E:} change in energy between last step and current
   step, in joules.
\item \textbf{Energy calc count:} number of times total energy has been
   calculated.
\item \textbf{Bracket count:} total number of attempts required to
   bracket energy minimum during first phase of line minimization
   procedures.
\item \textbf{Line min count:} total number of minimization steps during
   second phase of line minimization procedures (i.e., steps after
   minimum has been bracketed).
\item \textbf{Cycle count:} number of line direction selections.
\item \textbf{Cycle sub count:} number of line direction selections
  since the last gradient direction reset.
\item \textbf{Conjugate cycle count:} number of times the conjugate gradient
   process has been reset to the gradient direction.
\end{itemize}

The scalar field output is
\begin{itemize}
\item \textbf{Total energy density:} cellwise total energy density, in
\latexhtml{J/m${}^3$}{J/m\begin{rawhtml}<SUP>3</SUP>\end{rawhtml}}.
\end{itemize}

The vector field outputs are
\begin{itemize}
\item \textbf{H:} total effective field in A/m.
\item \textbf{mxHxm:} in A/m; $\vm$ is the unit magnetization
   direction.
\end{itemize}

\textbf{Examples:} \fn{cgtest.mif}, \fn{stdprob3.mif}, \fn{yoyo.mif}.

\end{description}

\subsubsection{Drivers\label{sec:oxsDrivers}}
While \hyperrefhtml{evolvers}{evolvers (Sec.~}{)}{sec:oxsEvolvers} are
responsible for moving the simulation forward in individual steps,
\textit{drivers} coordinate the action of the evolver on the
simulation as a whole, by grouping steps into tasks, stages and runs.

Tasks are small groups of steps that can be completed without adversely
affecting user interface responsiveness.  Stages are larger units
specified by the MIF problem description; in particular, problem
parameters are not expected to change in a discontinuous manner inside a
stage.  The run is the complete sequence of stages, from problem start to
finish.  The driver detects when stages and runs are finished, using
criteria specified in the MIF problem description, and can enforce
constraints, such as making sure stage boundaries respect time stopping
criteria.

There are two drivers in Oxs,
\htmlonlyref{\cd{Oxs\_TimeDriver}}{item:TimeDriver}
for controlling time evolvers such as
\htmlonlyref{\cd{Oxs\_RungeKuttaEvolve}}{html:RungeKuttaEvolve},
and
\htmlonlyref{\cd{Oxs\_MinDriver}}{html:MinDriver}
for controlling minimization evolvers like
\htmlonlyref{\cd{Oxs\_CGEvolve}}{html:CGEvolve}.

\begin{description}
\begin{rawhtml}<A NAME="TD"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_TimeDriver}%
\item[Oxs\_TimeDriver:\label{item:TimeDriver}]
The Oxs time driver is \textbf{Oxs\_TimeDriver}.  The specify block has
the form
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_TimeDriver:\oxsval{name} \ocb\\
 \bi evolver \oxsval{evolver\_spec}\\
 \bi mesh \oxsval{mesh\_spec}\\
 \bi Ms \oxsval{scalar\_field\_spec}\\
 \bi m0 \oxsval{vector\_field\_spec}\\
 \bi stopping\_dm\_dt \oxsval{torque\_criteria}\\
 \bi stopping\_time \oxsval{time\_criteria}\\
 \bi stage\_iteration\_limit \oxsval{stage\_iteration\_count}\\
 \bi total\_iteration\_limit \oxsval{total\_iteration\_count}\\
 \bi stage\_count \oxsval{number\_of\_stages}\\
 \bi stage\_count\_check \oxsval{test}\\
 \bi checkpoint\_file \oxsval{restart\_file\_name}\\
 \bi checkpoint\_interval \oxsval{checkpoint\_minutes}\\
 \bi checkpoint\_disposal \oxsval{cleanup\_behavior}\\
 \bi start\_iteration \oxsval{iteration}\\
 \bi start\_stage \oxsval{stage}\\
 \bi start\_stage\_iteration \oxsval{stage\_iteration}\\
 \bi start\_stage\_start\_time \oxsval{stage\_time}\\
 \bi start\_stage\_elapsed\_time \oxsval{stage\_elapsed\_time}\\
 \bi start\_last\_timestep \oxsval{timestep}\\
 \bi normalize\_aveM\_output \oxsval{aveMflag}\\
 \bi report\_max\_spin\_angle \oxsval{report\_angle}\\
 \bi report\_wall\_time \oxsval{report\_time}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_TimeDriver:</TT><I>name</I> <TT>{</TT>
<DD><TT> evolver </TT><I>evolver_spec</I>
<DD><TT> mesh </TT><I>mesh_spec</I>
<DD><TT> Ms </TT> <I>scalar_field_spec</I>
<DD><TT> m0 </TT> <I>vector_field_spec</I>
<DD><TT> stopping_dm_dt </TT><I>torque_criteria</I>
<DD><TT> stopping_time </TT><I>time_criteria</I>
<DD><TT> stage_iteration_limit </TT><I>stage_iteration_count</I>
<DD><TT> total_iteration_limit </TT><I>total_iteration_count</I>
<DD><TT> stage_count </TT><I>number_of_stages</I>
<DD><TT> stage_count_check </TT><I>test</I>
<DD><TT> checkpoint_file </TT> <I>restart_file_name</I>
<DD><TT> checkpoint_interval </TT> <I>checkpoint_minutes</I>
<DD><TT> checkpoint_disposal </TT> <I>cleanup_behavior</I>
<DD><TT> start_iteration </TT> <I>iteration</I>
<DD><TT> start_stage </TT> <I>stage</I>
<DD><TT> start_stage_iteration </TT> <I>stage_iteration</I>
<DD><TT> start_stage_start_time </TT> <I>stage_time</I>
<DD><TT> start_stage_elapsed_time </TT> <I>stage_elapsed_time</I>
<DD><TT> start_last_timestep </TT> <I>timestep</I>
<DD><TT> normalize_aveM_output </TT> <I>aveMflag</I>
<DD><TT> report_max_spin_angle </TT> <I>report_angle</I>
<DD><TT> report_wall_time </TT> <I>report_time</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
The first four parameters, \oxslabel{evolver}, \oxslabel{mesh},
\oxslabel{Ms} and \oxslabel{m0} provide references to a time evolver, a
mesh, a scalar field and a vector field, respectively.  Here \cd{Ms} is
the pointwise saturation magnetization in A/m, and \cd{m0} is the
initial configuration for the magnetization unit spins, i.e., $|\vm|=1$
at each point.  These four parameters are required.

The next group of 3 parameters control stage stopping criteria.  The
\oxslabel{stopping\_dm\_dt} value, in degrees per nanosecond, specifies that a
stage should be considered complete when the maximum $|d\vm/dt|$ across
all spins drops below this value.  Similarly, the
\oxslabel{stopping\_time} value specifies the maximum ``Simulation
time,'' i.e., the Landau-Lifshitz-Gilbert ODE (\ref{eq:oxsllode}),
(\ref{eq:oxsllgode}) time, allowed per stage.  For example, if
\oxsval{time\_criteria} is
\latex{$10^{-9}$}\html{1e-9}, then no stage will evolve for more than
1~ns.  If there were a total of 5 stages in the simulation, then the
total simulation time would be not more than 5~ns.  The third way to
terminate a stage is with a \oxslabel{stage\_iteration\_limit}.  This is
a limit on the number of successful evolver steps allowed per stage.  A
stage is considered complete when any one of these three criteria are
met.  Each of the criteria may be either a single value, which is
applied to every stage, or else a
\htmlonlyref{\textit{grouped list}}{par:groupedLists}
\latex{(Sec.~\ref{par:groupedLists})} of values.  If the
simulation has more stages than a criteria list has entries, then the
last criteria value is applied to all additional stages.  These stopping
criteria all provide a default value of 0, meaning no constraint, but
usually at least one is specified since otherwise there is no automatic
stage termination control.  For quasi-static simulations, a
\cd{stopping\_dm\_dt} value in the range of 1.0 to 0.01 is reasonable;
the numerical precision of the energy calculations usually makes in not
possible to obtain $|d\vm/dt|$ much below 0.001 degree per nanosecond.


\arblink{html:oxsdriverstagecount}
The \oxslabel{total\_iteration\_limit}, \oxslabel{stage\_count} and
\oxslabel{stage\_count\_check} parameters involve simulation run
completion conditions.  The default value for the first is 0,
interpreted as no limit, but one may limit the total number of steps
performed in a simulation by specifying a positive integer value here.
The more usual run completion condition is based on the stage count.  If
a positive integer value is specified for \cd{stage\_count}, then the
run will be considered complete when the stage count reaches that value.
If \cd{stage\_count} is not specified, or is given the value 0, then the
effective \oxsval{number\_of\_stages} value is computed by examining the
length of the stopping criteria lists, and also any other \cd{Oxs\_Ext}
object that has stage length expectations, such as
\htmlonlyref{\cd{Oxs\_UZeeman}}{html:UZeeman}.  The longest of these is
taken to be the stage limit value.  Typically these lengths, along with
\cd{stage\_count} if specified, will all be the same, and any
differences indicate an error in the \MIF\ file.  Oxs will automatically
test this condition, provided \cd{stage\_count\_check} is set to 1,
which is the default value.  Stage length requests of 0 or 1 are ignored
in this test, since those lengths are commonly used to represent
sequences of arbitrary length.  At times a short sequence is
intentionally specified that is meant to be implicitly extended to match
the full simulation stage length.  In this case, the stage count check
can be disabled by setting \oxsval{test} to 0.

The checkpoint\arblink{html:oxsdrivercheckpoint}%
\index{simulation~3D!restarting}\index{file!checkpoint}
options are used to control the saving of solver state to disk; these
saves are used by the \app{oxsii} and \app{boxsi} restart feature.
The value of the \oxslabel{checkpoint\_file} option is the name to
use for the solver state file.  The default is
\textit{base\_file\_name}.restart.

Cleanup of the checkpoint file is determined by the setting of
\oxslabel{checkpoint\_disposal}, which should be one of
\textit{standard} (the default), \textit{done\_only}, or \textit{never}.
Under the standard setting, the checkpoint file is automatically deleted
upon normal program termination, either because the solver reached the end
of the problem, or because the user interactively terminated the problem
prematurely.  If \oxsval{cleanup\_behavior} is set to
\texttt{done\_only}, then the checkpoint file is only deleted if the
problem endpoint is reached.  If \oxsval{cleanup\_behavior} is
\texttt{never}, then OOMMF does not delete checkpoint file; the
user is responsible for deleting this file as she desires.

The \oxslabel{checkpoint\_interval} value is the time in minutes between
overwrites of the checkpoint file.  No checkpoint file is written until
\oxsval{checkpoint\_minutes} have elapsed.  Checkpoint writes occur
between solver iterations, so the actual interval time may be somewhat
longer than the specified time.  If \oxsval{checkpoint\_minutes} is 0,
then each step is saved.  Setting \oxsval{checkpoint\_minutes} to -1
disables checkpointing.  The default checkpoint interval is 15 minutes.

The six \oxslabel{start\_*} options control the problem run start point.
These are intended primarily for automatic use by the restart feature.
The default value for each is 0.

The \oxslabel{normalize\_aveM\_output} option is used to control the
scaling and units on the average magnetization components $M_x$, $M_y$
and $M_z$ sent as DataTable output (this includes output sent to
\hyperrefhtml{\app{mmDataTable}}{\app{mmDataTable}
(Sec.~}{)}{sec:mmdatatable}\index{application!mmDataTable},
\hyperrefhtml{\app{mmGraph}}{\app{mmGraph}
(Sec.~}{)}{sec:mmgraph}\index{application!mmGraph}, and
\hyperrefhtml{\app{mmArchive}}{\app{mmArchive}
(Sec.~}{)}{sec:mmarchive}\index{application!mmArchive}).  If
\oxsval{aveMflag} is true (1), then the output values are scaled to lie
in the range $[-1,1]$, where the extreme values are obtained only at
saturation (i.e., all the spins are aligned).  If \oxsval{aveMflag} is
false (0), then the output is in A/m.  The default setting is 1.

In the older \MIF~2.1 format, the driver Specify block supports three
additional values: \oxslabel{basename},
\oxslabel{scalar\_output\_format}, and
\oxslabel{vector\_field\_output\_format}.  In the \MIF~2.2 format
these output controls have been moved into the \cd{SetOptions} block.
See the \hyperrefhtml{\cd{SetOptions}}{\cd{SetOptions}
(Sec.~}{)}{html:mif2SetOptions}\index{SetOptions~command~(MIF)}
documentation for details.

\cd{Oxs\_TimeDriver} provides 12 scalar outputs and 2 vector field
outputs.  The scalar outputs are
\begin{itemize}
\item \textbf{Stage:} current stage number, counting from 0.
\item \textbf{Stage iteration:} number of successful evolver steps
in the current stage.
\item \textbf{Iteration:} number of successful evolver steps in the
current simulation.
\item \textbf{Simulation time:} Landau-Lifshitz-Gilbert evolution
time, in seconds.
\item \textbf{Last time step:} The size of the preceding time step, in
seconds.
\item \textbf{Mx/mx:} magnetization component in the $x$ direction,
averaged across the entire simulation, in A/m (Mx) or normalized units
(mx), depending on the setting of the \cd{normalize\_aveM\_output}
option.
\item \textbf{My/my:} magnetization component in the $y$ direction,
averaged across the entire simulation, in A/m (My) or normalized units
(my), depending on the setting of the \cd{normalize\_aveM\_output}
option.
\item \textbf{Mz/mz:} magnetization component in the $z$ direction,
averaged across the entire simulation, in A/m (Mz) or normalized units
(mz), depending on the setting of the \cd{normalize\_aveM\_output}
option.
\item \textbf{Max Spin Ang:} maximum angle between neighboring spins
having non-zero magnetization $M_s$, measured in degrees.  The definition
of ``neighbor'' depends on the mesh, but for \cd{Oxs\_RectangularMesh}
the neighborhood of a point consists of 6 points, those nearest
forward and backward along each of the 3 coordinate axis directions.
\item \textbf{Stage Max Spin Ang:} the largest value of ``Max Spin
Ang'' obtained across the current stage, in degrees.
\item \textbf{Run Max Spin Ang:} the largest value of ``Max Spin
Ang'' obtained across the current run, in degrees.
\item \textbf{Wall time:} Wall clock time, in seconds.
\end{itemize}
The three ``Max Spin Ang'' outputs are disabled by default.  In general
one should refer instead to the neighboring spin angle outputs provided
by the exchange energies.  However, for backward compatibility, or for
simulations without any exchange energy terms, the driver spin angle
outputs can be enabled by setting the
\oxslabel{report\_max\_spin\_angle} option to to 1.

The ``Wall time'' output is also disabled by default.  It can be enabled
by setting the \oxslabel{report\_wall\_time} option to to 1.  It reports
the wall clock time, in seconds, since a system-dependent zero-time.
This output may be useful for performance comparisions and
debugging. (Note: The timestamp for a magnetization state is recorded
when output is first requested for that state; the timestamp is not
directly tied to the processing of the state.)

The vector field outputs are
\begin{itemize}
\item \textbf{Magnetization:} magnetization vector $\vM$, in A/m.
\item \textbf{Spin:} unit magnetization $\vm$.  This output ignores the
\cd{vector\_field\_output\_format} \oxsval{precision} setting, instead
always exporting at full precision.
\end{itemize}

\textbf{Examples:} \fn{sample.mif}, \fn{pulse.mif}.

\begin{rawhtml}<A NAME="MD"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_MinDriver}%
\item[Oxs\_MinDriver:\label{html:MinDriver}]
The Oxs driver for controlling minimization evolvers is
\textbf{Oxs\_MinDriver}.  The specify block has the form
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_MinDriver:\oxsval{name} \ocb\\
 \bi evolver \oxsval{evolver\_spec}\\
 \bi mesh \oxsval{mesh\_spec}\\
 \bi Ms \oxsval{scalar\_field\_spec}\\
 \bi m0 \oxsval{vector\_field\_spec}\\
 \bi stopping\_mxHxm \oxsval{torque\_criteria}\\
 \bi stage\_iteration\_limit \oxsval{stage\_iteration\_count}\\
 \bi total\_iteration\_limit \oxsval{total\_iteration\_count}\\
 \bi stage\_count \oxsval{number\_of\_stages}\\
 \bi stage\_count\_check \oxsval{test}\\
 \bi checkpoint\_file \oxsval{restart\_file\_name}\\
 \bi checkpoint\_interval \oxsval{checkpoint\_minutes}\\
 \bi checkpoint\_disposal \oxsval{cleanup\_behavior}\\
 \bi start\_iteration \oxsval{iteration}\\
 \bi start\_stage \oxsval{stage}\\
 \bi start\_stage\_iteration \oxsval{stage\_iteration}\\
 \bi start\_stage\_start\_time \oxsval{stage\_time}\\
 \bi start\_stage\_elapsed\_time \oxsval{stage\_elapsed\_time}\\
 \bi start\_last\_timestep \oxsval{timestep}\\
 \bi normalize\_aveM\_output \oxsval{aveMflag}\\
 \bi report\_max\_spin\_angle \oxsval{report\_angle}\\
 \bi report\_wall\_time \oxsval{report\_time}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_MinDriver:</TT><I>name</I> <TT>{</TT>
<DD><TT> evolver </TT><I>evolver_spec</I>
<DD><TT> mesh </TT><I>mesh_spec</I>
<DD><TT> Ms </TT> <I>scalar_field_spec</I>
<DD><TT> m0 </TT> <I>vector_field_spec</I>
<DD><TT> stopping_mxHxm </TT><I>torque_criteria</I>
<DD><TT> stage_iteration_limit </TT><I>stage_iteration_count</I>
<DD><TT> total_iteration_limit </TT><I>total_iteration_count</I>
<DD><TT> stage_count </TT><I>number_of_stages</I>
<DD><TT> stage_count_check </TT><I>test</I>
<DD><TT> checkpoint_file </TT> <I>restart_file_name</I>
<DD><TT> checkpoint_interval </TT> <I>checkpoint_minutes</I>
<DD><TT> checkpoint_disposal </TT> <I>cleanup_behavior</I>
<DD><TT> start_iteration </TT> <I>iteration</I>
<DD><TT> start_stage </TT> <I>stage</I>
<DD><TT> start_stage_iteration </TT> <I>stage_iteration</I>
<DD><TT> start_stage_start_time </TT> <I>stage_time</I>
<DD><TT> start_stage_elapsed_time </TT> <I>stage_elapsed_time</I>
<DD><TT> start_last_timestep </TT> <I>timestep</I>
<DD><TT> normalize_aveM_output </TT> <I>aveMflag</I>
<DD><TT> report_max_spin_angle </TT> <I>report_angle</I>
<DD><TT> report_wall_time </TT> <I>report_time</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
These parameters are the same as those described for the
\htmlonlyref{\cd{Oxs\_TimeDriver}}{item:TimeDriver}
class\latex{ (page~\pageref{item:TimeDriver})}, except that
\oxslabel{stopping\_mxHxm} replaces \cd{stopping\_dm\_dt}, and there is no
analogue to \cd{stopping\_time}.  The value for \cd{stopping\_mxHxm} is
in A/m, and may be a
\htmlonlyref{\textit{grouped list}}{par:groupedLists}
\latex{(Sec.~\ref{par:groupedLists})}.
Choice depends on the particulars of the simulation, but typical values
are in the range 10 to 0.1.  Limits in the numerical precision of the
energy calculations usually makes it not possible to obtain
$|\vm\times\vH\times\vm|$ below about 0.01 A/m.  This control can be
disabled by setting it to 0.0.

As with \cd{Oxs\_TimeDriver}, in the older \MIF~2.1 format this Specify
block supports three additional values: \oxslabel{basename} to control
output filenames, and output format controls
\oxslabel{scalar\_output\_format} and
\oxslabel{vector\_field\_output\_format}.  In the \MIF~2.2 format these
output controls have been moved into the \cd{SetOptions} block.  See the
\hyperrefhtml{\cd{SetOptions}}{\cd{SetOptions}
(Sec.~}{)}{html:mif2SetOptions}\index{SetOptions~command~(MIF)}
documentation for details.

\cd{Oxs\_MinDriver} provides 10 scalar outputs and 2 vector
field outputs.  The scalar outputs are
\begin{itemize}
\item \textbf{Stage:} current stage number, counting from 0.
\item \textbf{Stage iteration:} number of successful evolver steps
in the current stage.
\item \textbf{Iteration:} number of successful evolver steps in the
current simulation.
\item \textbf{Mx/mx:} magnetization component in the $x$ direction,
averaged across the entire simulation, in A/m (Mx) or normalized units
(mx), depending on the setting of the \cd{normalize\_aveM\_output}
option.
\item \textbf{My/my:} magnetization component in the $y$ direction,
averaged across the entire simulation, in A/m (My) or normalized units
(my), depending on the setting of the \cd{normalize\_aveM\_output}
option.
\item \textbf{Mz/mz:} magnetization component in the $z$ direction,
averaged across the entire simulation, in A/m (Mz) or normalized units
(mz), depending on the setting of the \cd{normalize\_aveM\_output}
option.
\item \textbf{Max Spin Ang:} maximum angle between neighboring spins
having non-zero magnetization $M_s$, measured in degrees.  The definition
of ``neighbor'' depends on the mesh, but for \cd{Oxs\_RectangularMesh}
the neighborhood of a point consists of 6 points, those nearest
forward and backward along each of the 3 coordinate axis directions.
\item \textbf{Stage Max Spin Ang:} the largest value of ``Max Spin
Ang'' obtained across the current stage, in degrees.
\item \textbf{Run Max Spin Ang:} the largest value of ``Max Spin
Ang'' obtained across the current run, in degrees.
\item \textbf{Wall time:} Wall clock time, in seconds.
\end{itemize}
As is the case for the \cd{Oxs\_TimeDriver}, the three ``Max Spin Ang''
outputs and ``Wall time'' are disabled by default.  They angle outputs
are enabled by setting the \oxslabel{report\_max\_spin\_angle} option to
to 1, and the wall time output is enabled by setting the
\oxslabel{report\_wall\_time} option to to 1.

The vector field outputs are
\begin{itemize}
\item \textbf{Magnetization:} magnetization vector $\vM$, in A/m.
\item \textbf{Spin:} unit magnetization $\vm$.  This output ignores the
\cd{vector\_field\_output\_format} \oxsval{precision} setting, instead
always exporting at full precision.
\end{itemize}

\textbf{Examples:} \fn{cgtest.mif}, \fn{stdprob3.mif}.

\end{description}

\subsubsection{Field Objects\label{sec:oxsFieldObjects}}
Field objects return values (either scalar or vector) as a function of
position.  These are frequently used as embedded objects inside Specify
blocks of other \cd{Oxs\_Ext} objects to initialize spatially varying
quantities, such as material parameters or initial magnetization spin
configurations.  Units on the returned values will be dependent upon the
context in which they are used.

Scalar field objects are documented first.  Vector field objects are
considered farther below.
\begin{description}
\begin{rawhtml}<A NAME="USF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_UniformScalarField}%
\item[Oxs\_UniformScalarField:\label{item:UniformScalarField}]
   Returns the same constant value regardless of the import position.
   The Specify block takes one parameter, \textbf{value}, which is the
   returned constant value.  This class is frequently embedded inline to
   specify homogeneous material parameters.  For example, inside a driver
   Specify block we may have
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_TimeDriver {
    ...
    Ms { Oxs_UniformScalarField {
       value 8e5
    }}
    ...
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
As discussed in
\html{the section on \htmlonlyref{Oxs\_Ext
referencing}{par:oxsExtReferencing} in the \htmlonlyref{MIF
2}{sec:mif2format} documentation,}
\latex{the MIF 2 documentation (Sec.~\ref{par:oxsExtReferencing},
page~\pageref{par:oxsExtReferencing}),}
when embedding \cd{Oxs\_UniformScalarField}
or \htmlonlyref{\cd{Oxs\_UniformVectorField}}{item:UniformVectorField}
objects, a notational shorthand is allowed that lists only the value.
The previous example is exactly equivalent to
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_TimeDriver {
    ...
    Ms 8e5
    ...
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
where an implicit \cd{Oxs\_UniformScalarField} object is
created with \cd{value} set to \cd{8e5}.

\textbf{Examples:} \fn{sample.mif}, \fn{cgtest.mif}.


\begin{rawhtml}<A NAME="ASF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_AtlasScalarField}%
\item[Oxs\_AtlasScalarField:\label{item:AtlasScalarField}]
   Declares values that are defined across individual regions of an
   \cd{Oxs\_Atlas}.  The Specify block looks like
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_AtlasScalarField:\oxsval{value} \ocb\\
       \bi atlas \oxsval{atlas\_spec}\\
       \bi multiplier \oxsval{mult}\\
       \bi default\_value \oxsval{scalar\_field\_spec}\\
       \bi values \ocb\\
         \bi\bi\oxsval{ region1\_label scalar\_field\_spec1 }\\
         \bi\bi\oxsval{ region2\_label scalar\_field\_spec2 }\\
         \bi\bi \ldots\\
       \bi\ccb\\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_AtlasScalarField {</TT>
      <DD><TT> atlas </TT><I>atlas_spec</I>
      <DD><TT> multiplier </TT><I>mult</I>
      <DD><TT> default_value </TT><I>scalar_field_spec</I>
      <DD><TT> values {</TT><DL>
          <DD><I>region1_label</I><TT>&nbsp;</TT><I>scalar_field_spec1</I>
          <DD><I>region2_label</I><TT>&nbsp;</TT><I>scalar_field_spec2</I>
          <DD> ...
      </DL><TT>}</TT>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}

   The specified \oxslabel{atlas} is used to map cell locations to
   regions; the value at the cell location of the scalar field from the
   corresponding \oxslabel{values} sub-block is assigned to that cell.
   The \oxslabel{default\_value} entry is optional; if specified, and if
   a cell's region is not included in the \cd{values} sub-block, then
   the \cd{default\_value} scalar field is used.  If \cd{default\_value}
   is not specified, then missing regions will raise an error.

   The scalar field entries may specify any of the scalar field types
   described in this (Field Objects) section.  As usual, one may provide
   a single numeric value in any of the \cd{scalar\_field\_spec}
   positions; this will be interpreted as requesting a uniform (spatially
   homogeneous) field with the indicated value.

   If the optional \oxslabel{multiplier} value is provided, then each
   field value is scaled (multiplied) by the value \oxsval{mult}.

   The vector field analogue to this class is
   \htmlonlyref{\cd{Oxs\_AtlasVectorField}}{item:AtlasVectorField},
   which is described below in the vector fields portion of this
   section.

\textbf{Examples:} \fn{diskarray.mif}, \fn{ellipsoid.mif},
\fn{grill.mif}, \fn{spinvalve.mif}, \fn{tclshapes.mif}.

\begin{rawhtml}<A NAME="LSF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_LinearScalarField}%
\item[Oxs\_LinearScalarField:]
   Returns a value that varies linearly with position.  The Specify
   block has the form:
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_LinearScalarField:\oxsval{name} \ocb\\
       \bi norm \oxsval{value}\\
       \bi vector \ocb\oxsval{ $v_x$ $v_y$ $v_z$ }\ccb\\
       \bi offset \oxsval{off}\\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_LinearScalarField {</TT>
      <DD><TT> norm </TT><I>value</I>
      <DD><TT> vector {</TT>
         <I>v<sub>x</sub></I><TT>&nbsp;</TT>
         <I>v<sub>y</sub></I><TT>&nbsp;</TT>
         <I>v<sub>z</sub></I> <TT>}</TT>
      <DD><TT> offset </TT><I>off</I>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}
   If optional value \oxslabel{norm} is specified, then the given
   \oxslabel{vector} is first scaled to the requested size.  The
   \oxslabel{offset} entry is optional, with default value 0. For any
   given point $(x,y,z)$, the scalar value returned by this
   object will be $xv_x+yv_y+zv_z + off$.

\textbf{Example:} \fn{spinvalve-af.mif}.

\begin{rawhtml}<A NAME="RSF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_RandomScalarField}%
\item[Oxs\_RandomScalarField:]\label{item:RandomScalarField}
Defines a scalar field that varies spatially in a random fashion.
The Specify block has the form:
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_RandomScalarField:\oxsval{name} \ocb\\
       \bi range\_min \oxsval{minvalue}\\
       \bi range\_max \oxsval{maxvalue}\\
       \bi cache\_grid \oxsval{mesh\_spec}\\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_RandomScalarField {</TT>
      <DD><TT> range_min </TT><I>minvalue</I>
      <DD><TT> range_max </TT><I>maxvalue</I>
      <DD><TT> cache_grid </TT><I>mesh_spec</I>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}
The value at each position is drawn uniformly from the range declared by
the two required parameters, \oxslabel{range\_min} and
\oxslabel{range\_max}.  There is also an optional parameter,
\oxslabel{cache\_grid}, which takes a mesh specification that describes
the grid used for spatial discretization.  If
\oxslabel{cache\_grid} is not specified, then each call to
\cd{Oxs\_RandomScalarField} generates a different field.  If you want to
use the same random scalar field in two places (as a base for setting,
say anisotropy coefficients and saturation magnetization), then specify
\oxslabel{cache\_grid} with the appropriate (usually the base problem)
mesh.

\textbf{Examples:} \fn{randomshape.mif}, \fn{stdprob1.mif}.

\begin{rawhtml}<A NAME="SSF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_ScriptScalarField}%
\item[Oxs\_ScriptScalarField:\label{item:ScriptScalarField}]
Analogous to the parallel
\htmlonlyref{\cd{Oxs\_ScriptVectorField}}{item:ScriptVectorField} 
class, this class produces a scalar field dependent on a \Tcl\ script
and optionally other scalar and vector fields.  The Specify block has
the form
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_ScriptScalarField:\oxsval{name} \ocb\\
\bi script \oxsval{\Tcl\_script}\\
\bi script\_args \ocb\oxsval{ args\_request }\ccb\\
\bi scalar\_fields \ocb\oxsval{ scalar\_field\_spec \ldots }\ccb\\
\bi vector\_fields \ocb\oxsval{ vector\_field\_spec \ldots }\ccb\\
\bi atlas \oxsval{atlas\_spec}\\
\bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
\bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
\bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_ScriptScalarField:</TT><I>name</I> <TT>{</TT>
<DD><TT>script </TT> <I>Tcl_script</I>
<DD><TT>script_args {</TT> <I>args_request</I> <TT>}</TT>
<DD><TT>scalar_fields {</TT> <I>scalar_field_spec</I><TT> ...}</TT>
<DD><TT>vector_fields {</TT> <I>vector_field_spec</I><TT> ...}</TT>
<DD><TT>atlas </TT> <I>atlas_spec</I>
<DD><TT>xrange {</TT> <I>xmin<TT>&nbsp;</TT>xmax</I> <TT>}</TT>
<DD><TT>yrange {</TT> <I>ymin<TT>&nbsp;</TT>ymax</I> <TT>}</TT>
<DD><TT>zrange {</TT> <I>zmin<TT>&nbsp;</TT>zmax</I> <TT>}</TT>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
   For each point of interest, the specified \oxslabel{script} is
   called with the arguments requested by \oxslabel{script\_args}
   appended to the command, as explained in the \hyperrefhtml{User
   Defined Support Procedures}{User Defined Support Procedures section
   (Sec.~}{)}{par:supportProcs} \html{section} of the \MIF~2 file
   format documentation.  The value for \cd{script\_args} should be a
   subset of \cd{\ocb rawpt relpt minpt maxpt span scalars vectors\ccb}.

   If \cd{rawpt} is requested, then when the \Tcl\ proc is called, at
   the corresponding spot in the argument list the \cd{x}, \cd{y},
   \cd{z} values of point will be placed, in problem coordinates (in
   meters).  The points so passed will usually be node points in the
   simulation discretization (the \htmlonlyref{mesh}{sec:Meshes}), but
   this does not have to be the case in general.  The \cd{relpt},
   \cd{minpt}, \cd{maxpt}, and \cd{span} rely on a definition of a
   \textit{bounding box}, which is an axes parallel parallelepiped.  The
   bounding box must be specified by either referencing an
   \oxslabel{atlas}, or by explicitly stating the range via the three
   entries \oxslabel{xrange}, \oxslabel{yrange}, \oxslabel{zrange} (in
   meters).  The \cd{minpt} and \cd{maxpt} arguments list the minimum
   and maximum values of the bounding box (coordinate by coordinate),
   while \cd{span} provides the 3-vector resulting from $(\cd{maxpt} -
   \cd{minpt})$.  The \cd{relpt} selection provides \cd{x\_rel},
   \cd{y\_rel}, \cd{z\_rel}, where each element lies in the range
   $[0,1]$, indicating a relative position between \cd{minpt} and
   \cd{maxpt}, coordinate-wise.

   Each of the \cd{script\_args} discussed so far places exactly 3
   arguments onto the \Tcl\ proc argument list.  The last two,
   \cd{scalars} and \cd{vectors}, place arguments depending on the size
   of the \oxslabel{scalar\_fields} and \oxslabel{vector\_fields} lists.
   The \cd{scalar\_fields} value is a list of other scalar field
   objects.  Each scalar field is evaluated at the point in question,
   and the resulting scalar value is placed on the \Tcl\ proc argument
   list, in order.  The \cd{vector\_fields} option works similarly,
   except each vector field generates three points for the \Tcl\ proc
   argument list, since the output from vector field objects is a three
   vector.  Although the use of these entries appears complicated, this
   is a quite powerful facility that allows nearly unlimited control for
   the modification and combination of other field objects.  Both
   \cd{scalar\_fields} and \cd{vector\_fields} entries are optional.

   If \cd{script\_args} is not specified, the default value \cd{relpt}
   is used.

   Note that if \cd{script\_args} includes \cd{relpt}, \cd{minpt},
   \cd{maxpt}, or \cd{span}, then a bounding box must be specified, as
   discussed above.  The following example uses the explicit range
   method.  See the \htmlonlyref{\cd{Oxs\_ScriptVectorField}}{SVF}
   documentation\latex{ (page~\pageref{item:ScriptVectorField})}
   for an example using an atlas specification.
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
proc Ellipsoid { xrel yrel zrel } {
    set xrad [expr {$xrel - 0.5}]
    set yrad [expr {$yrel - 0.5}]
    set zrad [expr {$zrel - 0.5}]
    set test [expr {$xrad*$xrad+$yrad*$yrad+$zrad*$zrad}]
    if {$test>0.25} {return 0}
    return 8.6e5
}

Specify Oxs_ScriptScalarField {
    script Ellipsoid
    xrange { 0   1e-6 }
    yrange { 0 250e-9 }
    zrange { 0  50e-9 }
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
   This \cd{Oxs\_ScriptScalarField} object returns \latex{$8.6\times
   10^5$}\html{8.6e5} if the import (x,y,z) lies within the ellipsoid
   inscribed inside the axes parallel parallelepiped defined by (xmin=0,
   ymin=0, zmin=0) and (xmax=1e-6, ymax=250e-9, zmax=50e-9), and 0
   otherwise.
   See also the discussion of the
   \htmlonlyref{\cd{ReadFile}}{html:ReadFile} \MIF\ extension command
   \latex{in Sec.~\ref{sec:mif2ExtensionCommands}} for an example using
   an imported image file for similar purposes.

   Below is one more example, illustrating the use of the
   \cd{vector\_fields} option.
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
proc DotProduct { x1 y1 z1 x2 y2 z2 } {
    return [expr {$x1*$x2+$y1*$y2+$z1*$z2}]
}

Specify Oxs_FileVectorField:file1 {
    atlas :atlas
    file  file1.omf
}

Specify Oxs_UniformVectorField:dir111 {
    norm 1
    vector {1 1 1}
}

Specify Oxs_ScriptScalarField:project {
    script DotProduct
    script_args vectors
    vector_fields {:file1 :dir111}
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
The scalar field \cd{:project} yields at each point in space the
projection of the vector field \cd{:file1} onto the [1,1,1] direction.

\textbf{Examples:} \fn{antidots-filled.mif},
\fn{ellipsoid-fieldproc.mif}, \fn{manyregions-scriptfields.mif},
\fn{manyspheres.mif}, \fn{varalpha.mif}.

\begin{rawhtml}<A NAME="VMSF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_VecMagScalarField}%
\item[Oxs\_VecMagScalarField:]
The \cd{Oxs\_VecMagScalarField} class produces a scalar field
from a vector field by taking the norm of the vector field on a
point-by-point basis, i.e.,
\begin{displaymath}
   \|\mbox{\boldmath $v$}\| = \sqrt{v_x^2+v_y^2+v_z^2}.
\end{displaymath}
The Specify block has the form:
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_VecMagScalarField:\oxsval{name} \ocb\\
 \bi field \oxsval{vector\_field\_spec}\\
 \bi multiplier \oxsval{mult}\\
 \bi offset \oxsval{off}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_VecMagScalarField {</TT>
<DD><TT> field </TT><I>vector_field_spec</I>
<DD><TT> multiplier </TT><I>mult</I>
<DD><TT> offset </TT><I>off</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
The \oxslabel{multiplier} and \oxslabel{offset} entries are applied
after the vector norm, i.e., the resulting scalar field is
$\cd{mult}\ast\|\mbox{\boldmath $v$}\|+\cd{off}$.  The default values
for \cd{mult} and \cd{off} are 1 and 0, respectively.

The functionality of the \cd{Oxs\_VecMagScalarField} class may be achieved
with the \cd{Oxs\_ScriptScalarField} class by using the
\cd{vector\_fields} option and a \Tcl\ script to compute the vector
norm.  However, this particular functionality is needed frequently
enough that a specialized class is useful.  For example, this class can
be used in conjunction with a vector field object to set
both the saturation magnetization distribution ($M_s$) and the initial
magnetization:
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_FileVectorField:file1 {
    atlas :atlas
    file  file1.omf
}

Specify Oxs_TimeDriver {
    basename test
    evolver :evolve
    stopping_dm_dt 0.01
    mesh :mesh
    m0 :file1
    Ms { Oxs_VecMagScalarField {
       field :file1
    }}
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}

\textbf{Example:} \fn{sample-vecrotate.mif}.

\begin{rawhtml}<A NAME="SOSF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_ScriptOrientScalarField}%
\item[Oxs\_ScriptOrientScalarField:\label{item:ScriptOrientScalarField}]
Scalar fields provide scalar values as a function of position across
three-space.  The \cd{Oxs\_ScriptOrientScalarField} class is used to
compose a transformation on the input position before evaluation by
a scalar field.  The Specify block has the form:
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_ScriptOrientScalarField:\oxsval{name} \ocb\\
\bi field \oxsval{scalar\_field\_spec}\\
\bi script \oxsval{\Tcl\_script}\\
\bi script\_args \ocb\oxsval{ args\_request }\ccb\\
\bi atlas \oxsval{atlas\_spec}\\
\bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
\bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
\bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_ScriptOrientScalarField:</TT><I>name</I> <TT>{</TT>
<DD><TT>field </TT> <I>scalar_field_spec</I>
<DD><TT>script </TT> <I>Tcl_script</I>
<DD><TT>script_args {</TT> <I>args_request</I> <TT>}</TT>
<DD><TT>atlas </TT> <I>atlas_spec</I>
<DD><TT>xrange {</TT> <I>xmin</I><TT>&nbsp;</TT><I>xmax</I> <TT>}</TT>
<DD><TT>yrange {</TT> <I>ymin</I><TT>&nbsp;</TT><I>ymax</I> <TT>}</TT>
<DD><TT>zrange {</TT> <I>zmin</I><TT>&nbsp;</TT><I>zmax</I> <TT>}</TT>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
The \oxslabel{field} argument should refer to a scalar field object.
The \oxslabel{script} is a \Tcl\ script that should return a position
vector that will be sent on the \cd{field} object to ultimately
produce a scalar value.  The arguments to the \cd{\Tcl\_script} are
determined by \oxslabel{script\_args}, which should be a subset of
\cd{\ocb relpt rawpt minpt maxpt span\ccb}.  If any arguments other than
\cd{rawpt} are requested, then the bounding box must be specified by
either the \oxslabel{atlas} option, or else through the three \oxslabel{xrange},
\oxslabel{yrange}, \oxslabel{zrange} entries.  The default value for
\cd{script\_args} is \cd{relpt}.

The \cd{Oxs\_ScriptOrientScalarField} class can be used to change the
``orientation'' of a scalar field, as in the following simple example,
which reflects the \cd{:file1mag} scalar field across the yz-plane:
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_FileVectorField:file1 {
    atlas :atlas
    file  file1.omf
}

Specify Oxs_VecMagScalarField:file1mag {
   field :file1
}

proc Reflect { x y z xmin ymin zmin xmax ymax zmax} {
   return [list [expr {($xmax+$xmin-$x)}] $y $z]
}

Specify Oxs_ScriptOrientScalarField:reflect {
   field :file1mag
   script Reflect
   script_args {rawpt minpt maxpt}
   atlas :atlas
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
See also the
\htmlonlyref{\cd{Oxs\_ScriptOrientVectorField}}{item:ScriptOrientVectorField}
class\latex{ (page~\pageref{item:ScriptOrientVectorField})} for
analogous operations on vector fields.

\textbf{Example:} \fn{sample-reflect.mif}.

\begin{rawhtml}<A NAME="AOSF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_AffineOrientScalarField}%
\item[Oxs\_AffineOrientScalarField:\label{item:AffineOrientScalarField}]
The \cd{Oxs\_AffineOrientScalarField} class is similar to the
\cd{Oxs\_ScriptOrientScalarField} class, except that the transformation
on the import position is by an affine transformation defined in terms
of a \latex{$3\times 3$}\html{3x3} matrix and an offset instead of a
\Tcl\ script.  Although this functionality can be obtained by an
appropriate \Tcl\ script, the \cd{Oxs\_AffineOrientScalarField} is
easier to use and will run faster, as the underlying transformation is
performed by compiled C++ instead of \Tcl\ script.

The Specify block has the form:
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_AffineOrientScalarField:\oxsval{name} \ocb\\
 \bi field \oxsval{scalar\_field\_spec}\\
 \bi M \ocb\oxsval{ matrix\_entries \ldots }\ccb\\
 \bi offset \ocb\oxsval{ off${}_x$ off${}_y$ off${}_z$ }\ccb\\
 \bi inverse \oxsval{invert\_flag}\\
 \bi inverse\_slack \oxsval{slack}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_AffineOrientScalarField {</TT>
<DD><TT> field </TT><I>scalar_field_spec</I>
<DD><TT> M
  {</TT> <I>matrix_entries</I><TT>&nbsp;</TT><I>...</I> <TT>}</TT>
<DD><TT> offset {</TT>
   <I>off<sub>x</sub></I><TT>&nbsp;</TT>
   <I>off<sub>y</sub></I><TT>&nbsp;</TT>
   <I>off<sub>z</sub></I> <TT>}</TT>
<DD><TT> inverse </TT><I>invert_flag</I>
<DD><TT> inverse_slack </TT><I>slack</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
If $F(\mbox{\boldmath$x$})$ represents the scalar field specified by the
\oxslabel{field} value, then the resulting transformed scalar field is
$F(M\mbox{\boldmath$x$}+\textbf{off})$.  Here \oxslabel{M} is a
\latex{$3\times 3$}\html{3x3} matrix, which may be specified by a list
of 1, 3, 6 or 9 entries.  If the \cd{matrix\_entries} list consists of a
single value, then $M$ is taken to be that value times the identity
matrix, i.e., $M$ is a homogeneous scaling transformation.  If
\cd{matrix\_entries} consists of 3 values, then $M$ is taken to be the
diagonal matrix with those three values along the diagonal.
If \cd{matrix\_entries} is 6 elements long, then $M$ is assumed to be a
symmetric matrix, where the 6 elements specified correspond to $M_{11}$,
$M_{12}$, $M_{13}$, $M_{22}$, $M_{23}$, and $M_{33}$.  Finally, if
\cd{matrix\_entries} is 9 elements long, then the elements specify the
entire matrix, in the order $M_{11}$, $M_{12}$, $M_{13}$, $M_{21}$,
\ldots, $M_{33}$.  If $M$ is not specified, then it is taken to be
the identity matrix.

The \oxslabel{offset} entry is simply a 3-vector that is added to
$M\mbox{\boldmath$x$}$.  If \cd{offset} is not specified, then
it is set to the zero vector.

It is frequently the case that the transformation that one wants to
apply is not $M\mbox{\boldmath$x$}+\textbf{off}$, but rather the
inverse, i.e., $M^{-1}(\mbox{\boldmath$x$}-\textbf{off})$.  Provided $M$
is nonsingular, this can be accomplished by setting the
\oxslabel{inverse} option to 1.  In this case the matrix $M.M^{-1}$ is
compared to the identity matrix, to check the accuracy of the matrix
inversion.  If any entry in $M.M^{-1}$ differs from $I$ by more than the
8-byte float machine precision (typically
\latex{$2\times 10^{-16}$}\html{2e-16}) times the value of
\oxslabel{inverse\_slack}, then an error is raised. The default setting
for \cd{invert\_flag} is 0, meaning don't invert,
and the default setting for \cd{slack} is 128.

Here is an example using \cd{Oxs\_AffineOrientScalarField} to rotate a
field by \latex{$90^{\circ}$}\html{90 degrees} counterclockwise about the
$z$-axis.  Note that the specified atlas is square in $x$ and $y$, with
the origin of the atlas coordinates in the center of the atlas volume.
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_BoxAtlas:atlas {
  xrange {-250e-9 250e-9}
  yrange {-250e-9 250e-9}
  zrange { -15e-9  15e-9}
}

Specify Oxs_FileVectorField:file1 {
    atlas :atlas
    file  file1.omf
}

Specify Oxs_VecMagScalarField:file1mag {
   field :file1
}

Specify Oxs_AffineOrientScalarField:reflect {
   field :file1mag
   M { 0 1 0
      -1 0 0
       0 0 1 }
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}

See also the
\htmlonlyref{\cd{Oxs\_AffineOrientVectorField}}{item:AffineOrientVectorField}
class\latex{ (page~\pageref{item:AffineOrientVectorField})} for
analogous operations on vector fields.

\textbf{Example:} \fn{sample-rotate.mif}.

\begin{rawhtml}<A NAME="ATSF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_AffineTransformScalarField}%
\item[Oxs\_AffineTransformScalarField:\label{item:AffineTransformScalarField}]
Like the \cd{Oxs\_AffineOrientScalarField} class, this class composes
an affine transform with a separate scalar field, but in this case the
affine transform is applied \textit{after} the field evaluation.
The Specify block has the form:
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_AffineTransformScalarField:\oxsval{name} \ocb\\
 \bi field \oxsval{scalar\_field\_spec}\\
 \bi multiplier \oxsval{mult}\\
 \bi offset \oxsval{off}\\
 \bi inverse \oxsval{invert\_flag}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_AffineTransformScalarField {</TT>
<DD><TT> field </TT><I>scalar_field_spec</I>
<DD><TT> multiplier </TT><I>mult</I>
<DD><TT> offset </TT><I>off</I>
<DD><TT> inverse </TT><I>invert_flag</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
If $F(\mbox{\boldmath$x$})$ represents the scalar field specified by the
\oxslabel{field} value, then the resulting scalar field is
$\textrm{mult}*F(\mbox{\boldmath$x$})+\textrm{off}$.  Since the output
from $F$ is a scalar, both \oxslabel{multiplier} and \oxslabel{offset}
are scalars.  If \oxslabel{inverse} is 1, then the transform is changed
to $\left(F(\mbox{\boldmath$x$})-\textrm{off}\right)/\textrm{mult}$,
provided \cd{mult} is non-zero.

The default values for \oxsval{mult}, \oxsval{off}, and
\oxsval{invert\_flag} are 1, 0, and 0, respectively.  The \cd{field}
value is the only required entry.

The functionality provided by \cd{Oxs\_AffineTransformScalarField} can
also be produced by the
\htmlonlyref{\cd{Oxs\_ScriptScalarField}}{item:ScriptScalarField}
class\latex{ (page~\pageref{item:ScriptScalarField})} with the
\cd{scalar\_fields} entry, but the \cd{Oxs\_AffineTransformScalarField}
class is faster and has a simpler interface.  See also the
\htmlonlyref{\cd{Oxs\_AffineTransformVectorField}}{item:AffineTransformVectorField}
class\latex{ (page~\pageref{item:AffineTransformVectorField})} for analogous
operations on vector fields.

\textbf{Example:} \fn{sample-rotate.mif}.

\begin{rawhtml}<A NAME="ISF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_ImageScalarField}%
\item[Oxs\_ImageScalarField:\label{item:ImageScalarField}]
This class creates a scalar field using an image.  The Specify block has
the form
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_ImageScalarField:\oxsval{name} \ocb\\
 \bi image \oxsval{pic}\\
 \bi invert \oxsval{invert\_flag}\\
 \bi multiplier \oxsval{mult}\\
 \bi offset \oxsval{off}\\
 \bi viewplane \oxsval{view}\\
 \bi atlas \oxsval{atlas\_spec}\\
 \bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
 \bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
 \bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
 \bi exterior \oxsval{ext\_flag}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_ImageScalarField:</TT><I>name</I> <TT>{</TT>
<DD><TT>image </TT> <I>pic</I>
<DD><TT>invert </TT> <I>invert_flag</I>
<DD><TT>multiplier </TT><I>mult</I>
<DD><TT>offset </TT><I>off</I>
<DD><TT>viewplane </TT> <I>view</I>
<DD><TT>atlas </TT> <I>atlas_spec</I>
<DD><TT>xrange {</TT> <I>xmin</I><TT>&nbsp;</TT><I>xmax</I> <TT>}</TT>
<DD><TT>yrange {</TT> <I>ymin</I><TT>&nbsp;</TT><I>ymax</I> <TT>}</TT>
<DD><TT>zrange {</TT> <I>zmin</I><TT>&nbsp;</TT><I>zmax</I> <TT>}</TT>
<DD><TT>exterior </TT><I>ext_flag</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
The \oxslabel{image} is interpreted as a monochromatic map, yielding a
scalar field with black corresponding to zero and white to one if
\oxslabel{invert} is 0 (the default), or with black corresponding to 1
and white to 0 if \cd{invert} is 1.  Color images are converted to
grayscale by simply summing the red, green, and blue components.  A
\oxslabel{multiplier} option is available to change the range of values
from $[0,1]$ to $[0,\mbox{\texttt{mult}}]$, after which the
\oxslabel{offset} value, if any, is added.

The \oxslabel{viewplane} is treated in the same manner as the viewplane
option in the \htmlonlyref{\cd{Oxs\_ImageAtlas}}{IA} class, and should
likewise take one of the three two-letter codes \cd{xy} (default),
\cd{zx} or \cd{yz}.  The spatial scale is adjusted to fit the volume
specified by either the \oxslabel{atlas} or
\oxslabel{xrange/yrange/zrange} selections.  If the specified volume
does not fill the entire simulation volume, then points outside the
specified volume are handled as determined by the \oxslabel{exterior}
setting, which should be either a floating point value, or one of the
keywords \cd{boundary} or \cd{error}.  In the first case, the floating
point value is treated as a default value for points outside the image,
and should have a value in the range $[0,1]$.  The multiplier and offset
adjustments are made to this value in the same way as to points inside
the image.  If \oxsval{ext\_flag} is \cd{boundary}, then points outside the
image are filled with the value of the closest point on the boundary of
the image.  If \oxsval{ext} is \cd{error} (the default), then an error
is raised if a value is needed for any point outside the image.

\textbf{Examples:} \fn{rotatecenterstage.mif}, \fn{sample-reflect.mif}.

\end{description}

\noindent
The available vector field objects are:
\begin{description}
\begin{rawhtml}<A NAME="UVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_UniformVectorField}%
\item[Oxs\_UniformVectorField:\label{item:UniformVectorField}]
   Returns the same constant value regardless of the import position.
   The Specify block takes one required parameter, \oxslabel{vector},
   which is a 3-element list of the vector to return, and one optional
   parameter, \oxslabel{norm}, which if specified adjusts the size of
   export vector to the specified magnitude.  For example,
   \begin{latexonly}
   \begin{quote}\tt
      Specify Oxs\_UniformVectorField \ocb\\
      \bi norm 1\\
      \bi vector \ocb 1 1 1\ccb\\
      \ccb
   \end{quote}
   \end{latexonly}
   \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_UniformVectorField {</TT>
      <DD><TT> norm 1</TT>
      <DD><TT> vector {1 1 1}</TT>
   <DT><TT>}</TT></DL></BLOCKQUOTE><P>
   \end{rawhtml}
   This object returns the unit vector $(a,a,a)$, where
   \latexhtml{$a=1/\sqrt{3}$}{a=1/sqrt(3)}, regardless of the import
   position.

   This class is frequently embedded inline to specify spatially uniform
   quantities.  For example, inside a driver Specify block we may have

\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_TimeDriver {
    ...
    m0 { Oxs_UniformVectorField {
       vector {1 0 0}
    }}
    ...
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
As discussed in
\html{the section on \htmlonlyref{Oxs\_Ext
referencing}{par:oxsExtReferencing} in the \htmlonlyref{MIF
2}{sec:mif2format} documentation,}
\latex{the MIF 2 documentation (Sec.~\ref{par:oxsExtReferencing},
page~\pageref{par:oxsExtReferencing}),}
when embedding \cd{Oxs\_UniformVectorField}
or \htmlonlyref{\cd{Oxs\_UniformScalarField}}{item:UniformScalarField}
objects, a notational shorthand is allowed that lists only the required
value.  The previous example is exactly equivalent to
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_TimeDriver {
    ...
    m0 {1 0 0}
    ...
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
where an implicit \cd{Oxs\_UniformVectorField} object is
created with the value of \cd{vector} set to \cd{\ocb 1 0 0\ccb}.

\textbf{Examples:} \fn{sample.mif}, \fn{cgtest.mif}.

\begin{rawhtml}<A NAME="AVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_AtlasVectorField}%
\item[Oxs\_AtlasVectorField:\label{item:AtlasVectorField}]
   Declares vector values that are defined across individual regions of
   an \cd{Oxs\_Atlas}.  The Specify block has the form
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_AtlasVectorField:\oxsval{name} \ocb\\
       \bi atlas \oxsval{atlas\_spec}\\
       \bi norm \oxsval{magval}\\
       \bi multiplier \oxsval{mult}\\
       \bi default\_value \oxsval{vector\_field\_spec}\\
       \bi values \ocb\\
       \bi\bi\oxsval{ region1\_label vector\_field\_spec1 }\\
       \bi\bi\oxsval{ region2\_label vector\_field\_spec2 }\\
       \bi\bi \ldots\\
       \bi\ccb\\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_AtlasVectorField {</TT>
      <DD><TT> atlas </TT><I>atlas_spec</I>
      <DD><TT> norm </TT><I>magval</I>
      <DD><TT> multiplier </TT><I>mult</I>
      <DD><TT> default_value </TT><I>vector_field_spec</I>
      <DD><TT> values {</TT><DL>
          <DD><I>region1_label</I><TT>&nbsp;</TT><I>vector_field_spec1</I>
          <DD><I>region2_label</I><TT>&nbsp;</TT><I>vector_field_spec2</I>
          <DD> ...
      </DL><TT>}</TT>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}
   Interpretation is analogous to the
   \htmlonlyref{\cd{Oxs\_AtlasScalarField}}{item:AtlasScalarField}
   specify block, except here the output values are 3 dimensional
   vectors rather than scalars.  Thus the values associated with each
   region are vector fields rather than scalar fields.  Any of the
   vector field types described in this (Field Objects) section may be
   used.  As usual, one may provided a braced list of three numeric
   values to request a uniform (spatially homogeneous) vector field with
   the indicated value.

   The optional \oxslabel{norm} parameter causes each vector value to be
   scaled to have magnitude \oxsval{magval}.  The optional
   \oxslabel{multiplier} value scales the field values.  If both
   \cd{norm} and \cd{multiplier} are specified, then the field vectors
   are first normalized before being scaled by the multiplier value.

\textbf{Examples:} \fn{diskarray.mif}, \fn{exchspring.mif},
\fn{imageatlas.mif}, \fn{spinvalve.mif}.

\begin{rawhtml}<A NAME="SVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_ScriptVectorField}%
\item[Oxs\_ScriptVectorField:\label{item:ScriptVectorField}]
Conceptually similar to the
\htmlonlyref{\cd{Oxs\_ScriptScalarField}}{item:ScriptScalarField} scalar
field object\latex{ (page~\pageref{item:ScriptScalarField})},
except that the script should return a vector (as a 3 element list)
rather than a scalar.  In addition to the parameters accepted by
\cd{Oxs\_ScriptScalarField}, \cd{Oxs\_ScriptVectorField} also accepts
an optional parameter \oxslabel{norm}.  If specified, the return
values from the script are size adjusted to the specified magnitude.
If both \cd{norm} and \cd{multiplier} are specified, then
the field vectors are first normalized before being scaled by the
multiplier value.

The following example produces a vortex-like unit vector field, with
an interior core region pointing parallel to the $z$-axis.  Here the
scaling region is specified using an \cd{atlas} reference to an
object named ``:atlas'', which is presumed to be defined earlier in
the \MIF\ file.  See the \cd{Oxs\_ScriptScalarField} sample Specify
block for an example using the explicit range option.
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin{latexonly}
\begin{quote}
%end{latexonly}
\begin{verbatim}
proc Vortex { xrel yrel zrel } {
    set xrad [expr {$xrel-0.5}]
    set yrad [expr {$yrel-0.5}]
    set normsq [expr {$xrad*$xrad+$yrad*$yrad}]
    if {$normsq <= 0.025} {return "0 0 1"}
    return [list [expr {-1*$yrad}] $xrad 0]
}

Specify Oxs_ScriptVectorField {
    script Vortex
    norm  1
    atlas :atlas
}
\end{verbatim}
%begin{latexonly}
\end{quote}
%end{latexonly}
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
See also the
\htmlonlyref{\cd{Oxs\_MaskVectorField}}{item:MaskVectorField}
documentation and the discussion of the
\htmlonlyref{\cd{ReadFile}}{html:ReadFile} \MIF\ extension command
\latex{in Sec.~\ref{sec:mif2ExtensionCommands}}
for other example uses of the \cd{Oxs\_ScriptVectorField} class.

\textbf{Examples:} \fn{cgtest.mif}, \fn{ellipsoid.mif},
\fn{manyregions-scriptfields.mif}, \fn{sample-vecreflect.mif},
\fn{stdprob3.mif}, \fn{yoyo.mif}.

\begin{rawhtml}<A NAME="FVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_FileVectorField}%
\item[Oxs\_FileVectorField:\label{item:FileVectorField}]
   Provides a file-specified vector field.  The Specify block has the form
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_FileVectorField:\oxsval{name} \ocb\\
       \bi file  \oxsval{filename}\\
       \bi atlas \oxsval{atlas\_spec}\\
       \bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
       \bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
       \bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
       \bi spatial\_scaling \ocb\oxsval{ xscale yscale zscale }\ccb\\
       \bi spatial\_offset \ocb\oxsval{ xoff yoff zoff }\ccb\\
       \bi exterior \oxsval{ext\_flag}\\
       \bi norm  \oxsval{magnitude}\\
       \bi multiplier \oxsval{mult}\\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_FileVectorField {</TT>
      <DD><TT>file </TT><I>filename</I>

      <DD><TT>atlas </TT> <I>atlas_spec</I>
      <DD><TT>xrange {</TT> <I>xmin</I><TT>&nbsp;</TT><I>xmax</I> <TT>}</TT>
      <DD><TT>yrange {</TT> <I>ymin</I><TT>&nbsp;</TT><I>ymax</I> <TT>}</TT>
      <DD><TT>zrange {</TT> <I>zmin</I><TT>&nbsp;</TT><I>zmax</I> <TT>}</TT>
      <DD><TT>spatial_scaling {</TT>
        <I>xscale</I><TT>&nbsp;</TT><I>yscale</I><TT>&nbsp;</TT><I>zscale</I>
      <TT>}</TT>
      <DD><TT>spatial_offset {</TT>
        <I>xoff</I><TT>&nbsp;</TT><I>yoff</I><TT>&nbsp;</TT><I>zoff</I>
      <TT>}</TT>
      <DD><TT>exterior </TT><I>ext_flag</I>
      <DD><TT>norm </TT><I>magnitude</I>
      <DD><TT>multiplier </TT><I>mult</I>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}
   Required values in the Specify block are the name of the input vector
   field file and the desired scaling parameters.  The filename is
   specified via the \oxslabel{file} entry, which names a file
   containing a vector field in one of the formats recognized by
   \hyperrefhtml{\app{avf2ovf}}{\app{avf2ovf}
   (Sec.~}{)}{sec:avf2ovf}\index{application!avf2ovf}.  If
   \oxslabel{atlas} or \oxslabel{xrange/yrange/zrange} are specified,
   then the file will be scaled and translated as necessary to fit that
   scaling region, in the same manner as done, for example, by
   the \htmlonlyref{\cd{Oxs\_ScriptScalarField}}{SSF} and
   \htmlonlyref{\cd{Oxs\_ScriptVectorField}}{SVF} classes.
   Alternatively, one may specify \oxslabel{spatial\_scaling} and
   \oxslabel{spatial\_offset} directly.  In this case the vector spatial
   positions are taken as specified in the file, multiplied
   component-wise by \cd{(xscale,yscale,zscale)}, and then translated by
   \cd{(xoff,yoff,zoff)}.  If you want to use the spatial coordinates as
   directly specified in the file, use \cd{(1,1,1)} for spatial\_scaling
   and \cd{(0,0,0)} for spatial\_offset.

   In all cases, once the input field has been scaled and translated, it
   is then sub-sampled (zeroth-order fit) as necessary to match the
   simulation mesh.

   The \oxslabel{exterior} flag determines the behavior at ``exterior
   points'', i.e., locations (if any) in the simulation mesh that lie
   outside the extent of the scaled and translated vector field.  The
   \oxsval{ext\_flag} should be either a three-vector, or one of the
   keywords \cd{boundary} or \cd{error}.  If a three-vector is given,
   then that value is supplied at all exterior points.  If
   \oxsval{ext\_flag} is set to \cd{boundary}, then the value used is
   the point on the boundary of the input vector field that is closest
   to the exterior point.  The default setting for \oxsval{ext\_flag} is
   \cd{error}, which raises an error if there are any exterior points.

   The magnitude of the field can be modified by the optional
   \oxslabel{norm} and \oxslabel{multiplier} attributes.  If the norm
   parameter is given, then each vector in the field will be
   renormalized to the specified magnitude.  If the multiplier parameter
   is given, then each vector in the field will be multiplied by the
   given scalar value.  If the multiplier value is negative, the field
   direction will be reversed.  If both \cd{norm} and \cd{multiplier}
   are given, then the field vectors are renormalized before being
   scaled by the multiplier value.

\textbf{Examples:} \fn{stdprob3.mif}, \fn{yoyo.mif}.

\begin{rawhtml}<A NAME="RVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_RandomVectorField}%
\item[Oxs\_RandomVectorField:]
Similar to
\htmlonlyref{\cd{Oxs\_RandomScalarField}}{item:RandomScalarField}%
\latex{ (q.v.)}, but defines a vector field rather than a scalar field that
varies spatially in a random fashion.  The Specify block has the form:
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_RandomVectorField:\oxsval{name} \ocb\\
       \bi min\_norm \oxsval{minvalue}\\
       \bi max\_norm \oxsval{maxvalue}\\
       \bi cache\_grid \oxsval{mesh\_spec}\\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_RandomVectorField {</TT>
      <DD><TT> min_norm </TT><I>minvalue</I>
      <DD><TT> max_norm </TT><I>maxvalue</I>
      <DD><TT> cache_grid </TT><I>mesh_spec</I>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}
The Specify block takes two required parameters, \oxslabel{min\_norm}
and \oxslabel{max\_norm}.  The vectors produced will have magnitude
between these two specified values.  If \cd{min\_norm} = \cd{max\_norm},
then the samples are uniformly distributed on the sphere of that radius.
Otherwise, the samples are uniformly distributed in the hollow spherical
volume with inner radius \cd{min\_norm} and outer radius \cd{max\_norm}.
There is also an optional parameter, \oxslabel{cache\_grid}, which takes
a mesh specification that describes the grid used for cache spatial
discretization.  If \oxslabel{cache\_grid} is not specified, then each
call to \cd{Oxs\_RandomVectorField} generates a different field.  If you
want to use the same random vector field in two places (as a base for
setting, say anisotropy axes and initial magnetization), then specify
\oxslabel{cache\_grid} with the appropriate (usually the base problem)
mesh.

\textbf{Examples:} \fn{diskarray.mif}, \fn{sample2.mif},
\fn{randomshape.mif} \fn{stdprob1.mif}.

\begin{rawhtml}<A NAME="PRVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_PlaneRandomVectorField}%
\item[Oxs\_PlaneRandomVectorField:]
   Similar to \cd{Oxs\_RandomVectorField}, except that samples are
   drawn from 2D planes rather than 3-space.  The Specify block has the
   form
      \begin{latexonly}
      \begin{quote}\tt
      Specify Oxs\_RandomVectorField:\oxsval{name} \ocb\\
       \bi plane\_normal \oxsval{vector\_field\_spec}\\
       \bi min\_norm \oxsval{minvalue}\\
       \bi max\_norm \oxsval{maxvalue}\\
       \bi cache\_grid \oxsval{mesh\_spec}\\
      \ccb
      \end{quote}
      \end{latexonly}
      \begin{rawhtml}<BLOCKQUOTE><DL><DT>
      <TT>Specify Oxs_RandomVectorField {</TT>
      <DD><TT> plane_normal </TT><I>vector_field_spec</I>
      <DD><TT> min_norm </TT><I>minvalue</I>
      <DD><TT> max_norm </TT><I>maxvalue</I>
      <DD><TT> cache_grid </TT><I>mesh_spec</I>
      <DT><TT>}</TT></DL></BLOCKQUOTE><P>
      \end{rawhtml}
  The \oxslabel{min\_norm}, \oxslabel{max\_norm}, and
  \oxslabel{cache\_grid} parameters have the same meaning as for the
  \cd{Oxs\_RandomVectorField} class.  The additional parameter,
  \oxslabel{plane\_normal}, specifies a vector field that at each point
  provides a vector that is orthogonal to the plane from which the
  random vector at that point is to be drawn.  If the vector field is
  specified explicitly as three real values, then a spatially uniform
  vector field is produced and all the random vectors will lie in the
  same plane.  More generally, however, the normal vectors (and
  associated planes) may vary from point to point.  As a special case,
  if a normal vector at a point is the zero vector, then no planar
  restriction is made and the resulting random vector is drawn uniformly
  from a hollow ball in three space satisfying the minimum/maximum norm
  constraints.

\textbf{Example:} \fn{sample2.mif}.

\begin{rawhtml}<A NAME="SOVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_ScriptOrientVectorField}%
\item[Oxs\_ScriptOrientVectorField:\label{item:ScriptOrientVectorField}]
This class is analogous to the
\htmlonlyref{\cd{Oxs\_ScriptOrientScalarField}}{item:ScriptOrientScalarField}
class\latex{ (page~\pageref{item:ScriptOrientScalarField})}.
The Specify block has the form:
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_ScriptOrientVectorField:\oxsval{name} \ocb\\
\bi field \oxsval{vector\_field\_spec}\\
\bi script \oxsval{\Tcl\_script}\\
\bi script\_args \ocb\oxsval{ args\_request }\ccb\\
\bi atlas \oxsval{atlas\_spec}\\
\bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
\bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
\bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_ScriptOrientVectorField:</TT><I>name</I> <TT>{</TT>
<DD><TT>field </TT> <I>vector_field_spec</I>
<DD><TT>script </TT> <I>Tcl_script</I>
<DD><TT>script_args {</TT> <I>args_request</I> <TT>}</TT>
<DD><TT>atlas </TT> <I>atlas_spec</I>
<DD><TT>xrange {</TT> <I>xmin</I><TT>&nbsp;</TT><I>xmax</I> <TT>}</TT>
<DD><TT>yrange {</TT> <I>ymin</I><TT>&nbsp;</TT><I>ymax</I> <TT>}</TT>
<DD><TT>zrange {</TT> <I>zmin</I><TT>&nbsp;</TT><I>zmax</I> <TT>}</TT>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
The interpretation of the specify block and the operation of the \Tcl\
script is exactly the same as for the \cd{Oxs\_ScriptOrientScalarField}
class, except the input \oxslabel{field} and the resulting field are
vector fields instead of scalar fields.

Note that the ``orientation'' transformation is applied to the import
spatial coordinates only, not the output vector.  For example, if the
\cd{field} value represents a shaped vector field, and the \cd{script}
proc is a rotation transformation, then the resulting vector field shape
will be rotated as compared to the original vector field, but the output
vectors themselves will still point in their original directions.  In such
cases one may wish to compose the \cd{Oxs\_ScriptOrientVectorField} with
a \htmlonlyref{\cd{Oxs\_ScriptVectorField}}{item:ScriptVectorField}
object\latex{ (page~\pageref{item:ScriptVectorField})} to rotate the
output vectors as well.  This situation occurs also with the
\cd{Oxs\_AffineOrientVectorField} class.  See the
\htmlonlyref{\cd{Oxs\_AffineTransformVectorField}}{item:AffineTransformVectorField}
class documentation\latex{ (page~\pageref{item:AffineTransformVectorField})} for an
example illustrating the composition of an object of that class with a
\htmlonlyref{\cd{Oxs\_AffineOrientVectorField}}{item:AffineOrientVectorField}
object.

\textbf{Example:} \fn{sample-vecreflect.mif}.

\begin{rawhtml}<A NAME="AOVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_AffineOrientVectorField}%
\item[Oxs\_AffineOrientVectorField:\label{item:AffineOrientVectorField}]
This class is analogous to the
\htmlonlyref{\cd{Oxs\_AffineOrientScalarField}}{item:AffineOrientScalarField}
class\latex{ (page~\pageref{item:AffineOrientScalarField})}.
The Specify block has the form:
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_AffineOrientVectorField:\oxsval{name} \ocb\\
 \bi field \oxsval{vector\_field\_spec}\\
 \bi M \ocb\oxsval{ matrix\_entries \ldots }\ccb\\
 \bi offset \ocb\oxsval{ off${}_x$ off${}_y$ off${}_z$ }\ccb\\
 \bi inverse \oxsval{invert\_flag}\\
 \bi inverse\_slack \oxsval{slack}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_AffineOrientVectorField {</TT>
<DD><TT> field </TT><I>vector_field_spec</I>
<DD><TT> M
  {</TT> <I>matrix_entries</I><TT>&nbsp;</TT><I>...</I> <TT>}</TT>
<DD><TT> offset {</TT>
   <I>off<sub>x</sub></I><TT>&nbsp;</TT>
   <I>off<sub>y</sub></I><TT>&nbsp;</TT>
   <I>off<sub>z</sub></I> <TT>}</TT>
<DD><TT> inverse </TT><I>invert_flag</I>
<DD><TT> inverse_slack </TT><I>slack</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
The interpretation of the specify block and the affine transformation
is exactly the same as for the \cd{Oxs\_AffineOrientScalarField}
class, except the input \oxslabel{field} and the resulting field are
vector fields instead of scalar fields.

As explained in the 
\htmlonlyref{\cd{Oxs\_ScriptOrientVectorField}}{item:ScriptOrientVectorField}
documentation, the ``orientation'' transformation is applied to the
import spatial coordinates only, not the output vector.  If one wishes
to rotate the output vectors, then a
\htmlonlyref{\cd{Oxs\_AffineTransformVectorField}}{item:AffineTransformVectorField}
object may be applied with the opposite rotation.  See that section for
an example.

\textbf{Examples:} \fn{yoyo.mif}, \fn{sample-vecrotate.mif}.

\begin{rawhtml}<A NAME="ATVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_AffineTransformVectorField}%
\item[Oxs\_AffineTransformVectorField:\label{item:AffineTransformVectorField}]
This class applies an affine transform to the output of a vector field.
It is similar to the
\htmlonlyref{\cd{Oxs\_AffineTransformScalarField}}{item:AffineTransformScalarField}
class\latex{ (page~\pageref{item:AffineTransformScalarField})}, except
that in this case the affine transform is applied to a vector instead of
a scalar.  The Specify block has the form:
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_AffineTransformVectorField:\oxsval{name} \ocb\\
 \bi field \oxsval{vector\_field\_spec}\\
 \bi M \ocb\oxsval{ matrix\_entries \ldots }\ccb\\
 \bi offset \ocb\oxsval{ off${}_x$ off${}_y$ off${}_z$ }\ccb\\
 \bi inverse \oxsval{invert\_flag}\\
 \bi inverse\_slack \oxsval{slack}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_AffineTransformVectorField {</TT>
<DD><TT> field </TT><I>vector_field_spec</I>
<DD><TT> M
  {</TT> <I>matrix_entries</I><TT>&nbsp;</TT><I>...</I> <TT>}</TT>
<DD><TT> offset {</TT>
   <I>off<sub>x</sub></I><TT>&nbsp;</TT>
   <I>off<sub>y</sub></I><TT>&nbsp;</TT>
   <I>off<sub>z</sub></I> <TT>}</TT>
<DD><TT> inverse </TT><I>invert_flag</I>
<DD><TT> inverse_slack </TT><I>slack</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
Because the output from \oxslabel{field} is a 3-vector, the transform
defined by \oxslabel{M} and \oxslabel{offset} requires \cd{M} to be a 
\latex{$3\times 3$}\html{3x3} matrix and \cd{offset} to be a 3-vector.
Thus, if $\mbox{\boldmath$v$}(\mbox{\boldmath$x$})$ represents the
vector field specified by the \oxslabel{field} value, then the resulting
vector field is
$M.\mbox{\boldmath$v$}(\mbox{\boldmath$x$})+\textbf{off}$.

\cd{M} is described by a list of from one to nine entries, in exactly
the same manner as for the
\htmlonlyref{\cd{Oxs\_AffineOrientVectorField}}{item:AffineOrientVectorField}
and
\htmlonlyref{\cd{Oxs\_AffineOrientScalarField}}{item:AffineOrientScalarField}
classes\latex{ (page~\pageref{item:AffineTransformScalarField})}.  The
interpretation of \oxslabel{offset}, \oxslabel{inverse}, and
\oxslabel{inverse\_slack} is also the same.  In particular, if
\oxsval{invert\_flag} is 1, then the resulting vector field is
$M^{-1}.\left(\mbox{\boldmath$v$}(\mbox{\boldmath$x$})-\textbf{off}\right)$.

The following example illustrates combining a
\cd{Oxs\_AffineTransformVectorField} with a
\htmlonlyref{\cd{Oxs\_AffineOrientVectorField}}{item:AffineOrientVectorField}
to completely rotate a vector field.
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_BoxAtlas:atlas {
  xrange {-80e-9 80e-9}
  yrange {-80e-9 80e-9}
  zrange {0  40e-9}
}

proc Trap { x y z } {
     if {$y<=$x && $y<=0.5} {return [list 0 1 0]}
     return [list 0 0 0]
}

Specify Oxs_ScriptVectorField:trap {
   script Trap
   atlas :atlas
}

Specify Oxs_AffineOrientVectorField:orient {
   field :trap
   M { 0 -1 0
       1  0 0
       0  0 1 }
   offset { -20e-9 0 0 }
   inverse 1
}

Specify Oxs_AffineTransformVectorField:rot {
   field :orient
   M { 0 -1 0
       1  0 0
       0  0 1 }
}

proc Threshold { vx vy vz } {
   set magsq [expr {$vx*$vx+$vy*$vy+$vz*$vz}]
   if {$magsq>0} {return 8e5}
   return 0.0
}

Specify Oxs_ScriptScalarField:Ms {
  vector_fields :rot
  script Threshold
  script_args vectors  
}

Specify Oxs_TimeDriver {
 m0 :rot
 Ms :Ms
 stopping_dm_dt 0.01
 evolver :evolve
 mesh :mesh
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
The base field here is given by the \cd{Oxs\_ScriptVectorField:trap}
object, which produces a vector field having a trapezoidal shape with
the non-zero vectors pointing parallel to the $y$-axis.  The
\cd{:orient} and \cd{:rot} transformations rotate the shape and the
vectors counterclockwise \latex{$90^{\circ}$}\html{90 degrees}.
Additionally, the \cd{offset} option in \cd{:orient} translates the
shape 20~nm towards the left.  The original and transformed fields are
illustrated below.
\latex{
%  Usage: \includeimage{width}{height}{basename}{altstring}
\parbox{0.45\textwidth}{
\centerline{\includeimage{0.4\textwidth}{!}{trap-orig}{Original field}}
\centerline{Original field}
}
\parbox{0.45\textwidth}{
\centerline{\includeimage{0.4\textwidth}{!}{trap-rot}{Rotated field}}
\centerline{Rotated field}
}}%
\html{
% Latex2html doesn't handle above construction properly.
% So, instead just use figures with captions already
% pasted in.
\includeimage{1pt}{1pt}{trap-orig}{Original field}
\includeimage{1pt}{1pt}{trap-rot}{Rotate field}
}

\textbf{Example:} \fn{sample-vecrotate.mif}.

\begin{rawhtml}<A NAME="MVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_MaskVectorField}%
\item[Oxs\_MaskVectorField:\label{item:MaskVectorField}]
Multiplies a vector field pointwise by a scalar vector field (the mask)
to produce a new vector field.  The Specify block has the form:
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_MaskVectorField:\oxsval{name} \ocb\\
 \bi mask  \oxsval{scalar\_field\_spec}\\
 \bi field \oxsval{vector\_field\_spec}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_MaskVectorField {</TT>
<DD><TT> mask </TT><I>scalar_field_spec</I>
<DD><TT> field </TT><I>vector_field_spec</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
This functionality can be achieved, if in a somewhat more complicated
fashion, with the
\htmlonlyref{\cd{Oxs\_ScriptVectorField}}{item:ScriptVectorField}
class.  For example, given a scalar field \cd{:mask} and a vector field
\cd{:vfield}, this example using the \cd{Oxs\_MaskVectorField} class
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
Specify Oxs_MaskVectorField {
   mask :mask
   field :vfield
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
is equivalent to this example using the \cd{Oxs\_ScriptVectorField}
class
% The extra BLOCKQUOTE's here are a workaround for an apparent
% latex2html bug
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin<latexonly>
\begin{quote}
%end<latexonly>
\begin{verbatim}
proc MaskField { m vx vy vz } {
   return [list [expr {$m*$vx}] [expr {$m*$vy}] [expr {$m*$vz}]]
}

Specify Oxs_ScriptVectorField {
  script MaskField
  script_args {scalars vectors}
  scalar_fields { :mask }
  vector_fields { :vfield }
}
\end{verbatim}
%begin<latexonly>
\end{quote}
%end<latexonly>
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
Of course, the \cd{Oxs\_ScriptVectorField} approach is easily
generalized to much more complicated and arbitrary combinations of
scalar and vector fields.

\textbf{Example:} \fn{rotatecenterstage.mif}.

\begin{rawhtml}<A NAME="IVF"></A>\end{rawhtml}%
\index{Oxs\_Ext~child~classes!Oxs\_ImageVectorField}%
\item[Oxs\_ImageVectorField:\label{item:ImageVectorField}]
This class creates a vector field using an image.  The Specify block has
the form
\begin{latexonly}
\begin{quote}\tt
Specify Oxs\_ImageVectorField:\oxsval{name} \ocb\\
 \bi image \oxsval{pic}\\
 \bi multiplier \oxsval{mult}\\
 \bi vx\_multiplier \oxsval{xmult}\\
 \bi vy\_multiplier \oxsval{ymult}\\
 \bi vz\_multiplier \oxsval{zmult}\\
 \bi vx\_offset \oxsval{xoff}\\
 \bi vy\_offset \oxsval{yoff}\\
 \bi vz\_offset \oxsval{zoff}\\
 \bi norm \oxsval{norm\_magnitude}\\
 \bi viewplane \oxsval{view}\\
 \bi atlas \oxsval{atlas\_spec}\\
 \bi xrange \ocb\oxsval{ xmin xmax }\ccb\\
 \bi yrange \ocb\oxsval{ ymin ymax }\ccb\\
 \bi zrange \ocb\oxsval{ zmin zmax }\ccb\\
 \bi exterior \oxsval{ext\_flag}\\
\ccb
\end{quote}
\end{latexonly}
\begin{rawhtml}<BLOCKQUOTE><DL><DT>
<TT>Specify Oxs_ImageVectorField:</TT><I>name</I> <TT>{</TT>
<DD><TT>image </TT> <I>pic</I>
<DD><TT>multiplier </TT><I>mult</I>
<DD><TT>vx_multiplier </TT><I>xmult</I>
<DD><TT>vy_multiplier </TT><I>ymult</I>
<DD><TT>vz_multiplier </TT><I>zmult</I>
<DD><TT>vx_offset </TT><I>xoff</I>
<DD><TT>vy_offset </TT><I>yoff</I>
<DD><TT>vz_offset </TT><I>zoff</I>
<DD><TT>norm </TT> <I>norm_magnitude</I>
<DD><TT>viewplane </TT> <I>view</I>
<DD><TT>atlas </TT> <I>atlas_spec</I>
<DD><TT>xrange {</TT> <I>xmin</I><TT>&nbsp;</TT><I>xmax</I> <TT>}</TT>
<DD><TT>yrange {</TT> <I>ymin</I><TT>&nbsp;</TT><I>ymax</I> <TT>}</TT>
<DD><TT>zrange {</TT> <I>zmin</I><TT>&nbsp;</TT><I>zmax</I> <TT>}</TT>
<DD><TT>exterior </TT><I>ext_flag</I>
<DT><TT>}</TT></DL></BLOCKQUOTE><P>
\end{rawhtml}
The \oxslabel{image} is interpreted as a three-color map, yielding a
vector field where each (x,y,z) component is determined by the red,
green, and blue color components, respectively.\ldots

The \oxslabel{viewplane}, \oxslabel{atlas},
\oxslabel{xrange/yrange/zrange}, and \oxslabel{exterior} are treated
the same as for the
\htmlonlyref{\cd{Oxs\_ImageScalarField} class}{item:ImageScalarField}%
\latex{ (q.v.)}

\textbf{Examples:} \fn{NONE}.

\end{description}

\subsubsection{\MIF\ Support Classes}
\begin{rawhtml}<A NAME="LV"></A>\end{rawhtml}%
\begin{description}
\index{Oxs\_Ext~child~classes!Oxs\_LabelValue}%
\item[Oxs\_LabelValue:]
   A convenience object that holds label + value
   pairs.  \cd{Oxs\_LabelValue} objects may be referenced via the
   standard \cd{attributes} field in other Specify blocks, as in
   this example:
\begin{rawhtml}<BLOCKQUOTE>\end{rawhtml}
%begin{latexonly}
\begin{quote}
%end{latexonly}
\begin{verbatim}
Specify Oxs_LabelValue:probdata {
  alpha 0.5
  start_dm 0.01
}

Specify Oxs_EulerEvolve {
  attributes :probdata
}
\end{verbatim}
%begin{latexonly}
\end{quote}
%end{latexonly}
\begin{rawhtml}</BLOCKQUOTE>\end{rawhtml}
   The Specify block string for \cd{Oxs\_LabelValue} objects is an
   arbitrary \Tcl\ list with an even number of elements.  The first
   element in each pair is interpreted as a label, the second as the
   value.  The \cd{attribute} option causes this list to be dropped
   verbatim into the surrounding object.  This technique is most useful
   if the label + value pairs in the \cd{Oxs\_LabelValue} object are
   used in multiple Specify blocks, either inside the same \MIF\
   file, or across several \MIF\ files into which the
   \cd{Oxs\_LabelValue} block is imported using the \cd{ReadFile} \MIF\
   extension command.

\textbf{Examples:} The \MIF\ files \fn{sample-rotate.mif} and
   \fn{sample-reflect.mif} use the \cd{Oxs\_LabelValue} object
   stored in the \fn{sample-attributes.tcl} file.

\end{description}

%begin{latexonly}
Refer to Sec.~\ref{sec:mif2format} for details on the base \MIF~2
format specification.
%end{latexonly}
\begin{htmlonly}
Refer to the \MIF~2 documentation for details on the base format
specification.
\end{htmlonly}
