\section{Command Line Utilities}\label{sec:cmdutils}

This section documents a few utilities distributed with \OOMMF\ that are
run from the command line (\Unix\ shell or \Windows\ \DOS\ prompt).
They are typically used in pre- or post-processing of data associated
with a micromagnetic simulation.

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

\subsection{Bitmap File Format Conversion:
          any2ppm}\label{sec:any2ppm}%
\index{file!bitmap}\index{file!ppm}\index{file!bmp}\index{file!gif}%
\index{application!any2ppm}\index{file!conversion}
The \app{any2ppm} program converts bitmap files from the Portable Pixmap
(PPM), Windows BMP, and GIF formats into the Portable Pixmap P3
(text) format or the uncompressed 24 bits-per-pixel BMP binary format.
Additional formats may be available if the \Tcl/\Tk\
\htmladdnormallinkfoot{\textit{Img}}{http://tkimg.sourceforge.net/}
package is installed on your system.  (Note: \OOMMF\ support for BMP
requires Tk 8.0\index{requirement!Tk~8.0+} or later.)

\sssechead{Launching}
The \app{any2ppm} launch command is:
\begin{verbatim}
tclsh oommf.tcl any2ppm [standard options] [-f] [-format fmt] \
   [-noinfo] [-o outfile] [infile ...]
\end{verbatim}
where
\begin{description}
\item[\optkey{-f}]
  Force output.  If the \cd{-o} option is not specified, then the output
  filename is automatically generated by stripping the extension, if
  any, off of each input filename, and appending a format-specific
  extension (e.g., \fn{.ppm}).  If \cd{-f} is specified, that generated
  filename is used for the output filename.  If \cd{-f} is not
  specified, then a check is made to see if the generated filename
  already exists.  If so, then an additional ``-000'' or ``-001''
  \ldots\ suffix is appended to create an unused filename.  If the input
  is coming from stdin, i.e., there is no input filename, then the
  default output is to stdout.
\item[\optkey{-format fmt}]
  Output file format.  The default is \cd{PPM}, which is the Portable
  Pixmap P3 (text) format.  Setting \texttt{fmt} to \cd{BMP} will
  produce files in the uncompressed Windows BMP\index{file!bmp} 24
  bits-per-pixel format.  If the \Tcl/\Tk\ Img package is installed,
  then additional formats, such as PNG, JPEG and TIFF, will be
  available.  The default output file extension depends on the format
  selected, e.g., \fn{.ppm} for PPM files and \fn{.bmp} for BMP files.
\item[\optkey{-noinfo}]
  Suppress writing of progress information to stderr.
\item[\optkey{-o outfile}]
  Write output to {\tt outfile}; use ``-'' to pipe output to stdout.
  Note that if {\tt outfile} is specified, then all output will go to
  this one file; in this case it is unlikely that one wants to specify
  more than one input file.
\item[\optkey{infile \ldots}]
  List of input files to process.  If none, or if an infile is the empty
  string, then read from stdin.
\end{description}

\textbf{Note:} If the output is to stdout, and the selected output
format is anything other than \cd{PPM}, then the output is first written
to a temporary file before being copied to stdout.  Under normal
operation the temporary file will be automatically deleted, but this is
not guaranteed if the program terminates abnormally.

\textbf{\Tk\ Requirement:}\index{requirement!Tk} \app{any2ppm} uses the
\Tk\ \cd{image} command in its processing.  This requires that \Tk\ be
properly initialized, which in particular means that a valid display
must be available.  This is not a problem on \Windows, where a desktop
is always present, but on \Unix\ this means that an \X\ server must be
running.  The
\htmladdnormallinkfoot{\textit{Xvfb}}{%
http://www.x.org/archive/X11R7.6/doc/man/man1/Xvfb.1.xhtml}\index{application!Xvfb}
virtual framebuffer can be used if desired.  (Xvfb is an X server
distributed with X11R6 that requires no display hardware or physical
input devices.)

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

\subsection{Making Data Tables from Vector Fields:
          avf2odt}\label{sec:avf2odt}%
\index{file!vector~field}\index{file!data~table}\index{file!vio}%
\index{application!avf2odt}\index{file!conversion}
The \app{avf2odt} program converts \textit{rectangularly} meshed vector field
files in any of the \latexhtml{recognized formats (\OVF, \VIO; see
Sec.~\ref{sec:vfformats})}{\htmlref{recognized formats}{sec:vfformats}
(\OVF, \VIO)} into the \hyperrefhtml{\ODT~1.0}{\ODT~1.0
(Sec.~}{)}{sec:odtformat} data table format.  (Irregular meshes are
not supported by this command.  Note that any \OVF\ file using the
``irregular'' meshtype is considered to be using an irregular mesh, even
if the mesh nodes do in fact lie on a rectangular grid.)

\sssechead{Launching}
The \app{avf2odt} launch command is:
\begin{verbatim}
tclsh oommf.tcl avf2odt [standard options] \
   [-average <space|plane|line|point|ball>] [-axis <x|y|z>] \
   [-ball_radius brad] [-defaultpos <0|1>] [-defaultvals <0|1>] \
   [-extravals flag] [-filesort method] [-headers <full|collapse|none>] \
   [-index label units valexpr] [-ipat pattern] [-normalize <0|1>] \
   [-numfmt fmt] [-onefile outfile] [-opatexp regexp] [-opatsub sub] \
   [-region xmin ymin zmin xmax ymax zmax] \
   [-rregion rxmin rymin rzmin rxmax rymax rzmax] \
   [-truncate <0|1>] [-v level] [-valfunc label units fcnexpr] \
   [infile ...]
\end{verbatim}
where
\begin{description}
\item[\optkey{-average \boa space\pipe plane\pipe line\pipe point\pipe
    ball\bca}]
  Specify type of averaging.  Selection of \cd{Space} averaging
  results in the output of one data line (per input file) consisting
  of the average $v_x$, $v_y$ and $v_z$ field values in the selected
  region (see \cd{-region} option below).  For example, in
  magnetization files, $v_x$, $v_y$ and $v_z$ correspond to $M_x$,
  $M_y$ and $M_z$.  If \cd{plane} or \cd{line} is selected, then the
  output data table consists of multiple lines with 4 or 5 columns per
  line, respectively.  The last 3 columns in both cases are the $v_x$,
  $v_y$ and $v_z$ averaged over the specified axes-parallel affine
  subspace (i.e., plane or line).  In the \cd{plane} case, the first
  column specifies the averaging plane offset along the coordinate
  axis normal to the plane (see \cd{-axis} option below).  In the
  \cd{line} case, the first 2 columns specify the offset of the
  averaging line in the coordinate plane perpendicular to the line.
  If the averaging type is \cd{point}, then no averaging is done, and
  the output consists of lines of 6 column data, one line for each
  point in the selected region, where the first 3 columns are the
  point coordinates, and the last 3 are the $v_x$, $v_y$ and $v_z$
  values at the point.  If the type is \cd{ball}, then one line is
  output for each sample point for which a ball of radius \cd{brad}
  (see \cd{-ball\_radius} option) centered about that point lies
  entirely inside the selected region.  The output values consist of 6
  columns: the ball center point location and the $v_x$, $v_y$ and
  $v_z$ values averaged across the ball.  As a special case, if the
  spatial extent of the selected region is two-dimensional (e.g., all
  the sample locations have the same $z$-coordinate), then the
  averaging region is taken to be a disk instead of a ball.
  Similarly, if the spatial extent of the selected region is
  one-dimensional, then the averaging region is reduced to a
  one-dimensional line segment.  (Note: The output columns described
  above may be suppressed by the \cd{-defaultpos} and
  \cd{-defaultvals} options.  Additional columns may be introduced by
  the \cd{-index} and \cd{-valfunc} options.)  The default averaging
  type is \cd{space}.
\item[\optkey{-axis \boa x\pipe y\pipe z\bca}]
  For the \cd{-average plane} and \cd{-average line} averaging types,
  selects which subset of affine subspaces the averaging will be
  performed over.  In the \cd{plane} case, the \cd{-axis} represents
  the normal direction to the planes, while for \cd{line} it is the
  direction parallel to the lines.  This parameter is ignored if
  \cd{-average} is not either \cd{plane} or \cd{line}.  Default value
  is \cd{x}.
\item[\optkey{-ball\_radius brad}]
  This option is required if \cd{-average} is \cd{ball}, in which case
  \cd{brad} specifies the radius of the averaging ball in problem
  units (e.g., meters).  If  \cd{-average} is not \cd{ball}, then this
  option is ignored.
\item[\optkey{-defaultpos \boa 0\pipe 1\bca}]
  By default, the output data columns are as described in the
  description of the \cd{-average} option above.  However,
  \cd{-defaultpos 0} may be used to omit the columns indicating the
  averaging position.
\item[\optkey{-defaultvals \boa 0\pipe 1\bca}]
  By default, the output data columns are as described in the
  description of the \cd{-average} option above.  However,
  \cd{-defaultvals 0} may be used to omit the columns containing the
  averaged $v_x$, $v_y$ and $v_z$ values.  In particular, this may be
  useful in conjunction with the \cd{-valfunc} option.
\item[\optkey{-extravals \boa 0\pipe 1\bca}]
  Specify \cd{-extravals 1} to augment the output with columns
  for the average $L^1$ norm
  $\sum\left(|v_x| + |v_y| + |v_z|\right)/N$, the normalized $L^2$
  norm $\sqrt{\sum v^2/N}$, the minimum component absolute value,
  and the maximum component absolute value.
\item[\optkey{-filesort method}]
  Specifies the sorting order to apply to the input file list.  This
  order is important when using the \cd{-onefile} option, since it
  controls the order in which the rows from the various input files
  are concatenated.  Method should be either the keyword ``none'', or
  else a valid option string for the \Tcl\ command \cd{lsort}, e.g.,
  ``-ascii -decreasing''.  Note that the \cd{lsort} sort options all
  begin with a hyphen, ``-'', and that if you want to use multiple
  options they must be grouped as one element to \cd{filesort} (by,
  for example, placing quotes around the list).  The default value is
  ``-dictionary'' if the \cd{-ipat} option is specified, or ``none''
  otherwise.
\item[\optkey{-headers \boa full\pipe collapse\pipe none\bca}]
  Determines the style of headers written to the output \ODT\ file(s).
  The full style (default) provides the standard headers, as described
  in the \hyperrefhtml{\ODT\ documentation}{\ODT\ documentation
  (Sec.~}{)}{sec:odtformat}.  Specifying ``none'' produces raw data
  lines without any headers.  The collapse style is used with multiple
  input files and the \cd{-onefile} output option to concatenate
  output with no \ODT\ header information between the segments.
\item[\optkey{-index label units valexpr}]
  Adds an input file based index column to the output, where label is
  the column header, units is a string displayed as the column units
  header, and valexpr is a \Tcl\ \cd{expr} expression that may include
  the special variables \cd{\$i}, \cd{\$f1}, \cd{\$f2}, \ldots, \cd{\$d1},
  \cd{\$d2}, \ldots; here \cd{\$i} is the 0-based index of
  the file in the list of input files, \cd{\$f1} is the first number
  appearing in the input filename, \cd{\$f2} is the second number
  appearing in the input filename, \cd{\$d1} is the first number
  appearing in the ``Desc'' fields in the header of the input file,
  etc.  For example, if there are two input files named
  \fn{foo-100.ovf} and and \fn{foo-101.ovf}, then setting valexpr to
  \cd{abs(\$f1)+1} would yield a column with the value 101 for all lines
  coming from \fn{foo-100.ovf}, and the value 102 for all lines coming
  from  \fn{foo-101.ovf}.  (We use the \Tcl\ \cd{expr} function
  \cd{abs} because the leading hyphen in \fn{foo-100.ovf} gets
  interpreted as a minus sign, so \cd{\$f1} is extracted as -100.)
  On \Unix\ systems, the valexpr string should be surrounding by single
  quotes in order to forestall interpolation of the special variables
  by the shell.  On Windows, the valexpr string should be surrounded
  by double quotes as usual to protect embedded spaces.
  Multiple instances of the \cd{-index} option on the command line
  will result in multiple columns in the output file, in the order
  specified.  The index columns, if any, will be the first columns in
  the output file.
\item[\optkey{-ipat pattern}]
  Specify input files using a pattern with ``glob-style'' wildcards.
  Especially useful in \DOS.  Files must meet the \cd{infile}
  requirements (see below).
\item[\optkey{-normalize \boa 0\pipe 1\bca}]
  If 1, then the default averaged output values $v_x$, $v_y$ and $v_z$
  are divided by the maximum magnitude that would occur if all the
  vectors in the averaging manifold are aligned.  (In particular, the
  maximum magnitude of the output vector is 1.)  This option should
  be used carefully because the normalization is done independently for
  each output row.  For \cd{-normalize 0}
  (the default), averaged output values are in file units.
\item[\optkey{-numfmt fmt}]
  C-style output format for numeric data in the body of the output
  table.  Default value is ``\verb+%- #20.15g+''.
\item[\optkey{-onefile outfile}]
  Generally a \app{avf2odt} writes its output to a collection of files
  with names generated using the \cd{-opatexp} and \cd{-opatsub}
  specifications.  This option overrides that behavior and sends all
  output to one place.  If outfile is ``-'', then the output is sent
  to standard output, otherwise outfile is the name of the output file.
\item[\optkey{-opatexp regexp}]
  Specify the ``regular expression'' applied to input filenames to
  determine portion to be replaced in generation of output filenames.
  The default regular expression is: {\verb!(\.[^.]?[^.]?[^.]?$|$)!}
\item[\optkey{-opatsub sub}]
  The string with which to replace the portion of input filenames
  matched by the {\tt -opatexp regexp} during output filename
  generation.  The default is {\verb!.odt!}.
\item[\optkey{-region xmin ymin zmin xmax ymax zmax}]
  Axes-parallel rectangular box denoting region in the vector field
  file over which data is to be collected.  The locations are in
  problem units (typically meters).  A single hyphen, ``-'', may be
  specified for any of the box corner coordinates, in which case the
  corresponding extremal value from the input file is used.  Optional;
  the default, \cd{-region - - - - - -}, selects the entire input file.
\item[\optkey{-rregion rxmin rymin rzmin rxmax rymax rzmax}]
  This option is the same as \cd{-region}, except that the locations
  are specified in relative units, between 0 and 1.
\item[\optkey{-truncate \boa 0\pipe 1\bca}]
  When opening an existing file for output, the new output can either be
  appended to the file (\cd{-truncate 0}), or else the existing data
  can be discarded (\cd{-truncate 1}).  The default is \cd{-truncate 0}.
\item[\optkey{-v level}]
  Verbosity (informational message) level, with 0 generating only
  error messages, and larger numbers generating additional information.
  The {\tt level} value is an integer, defaulting to 1.
\item[\optkey{-valfunc label units fcnexpr}]
  Similar to the \cd{-index} option, \cd{-valfunc} adds an additional
  column to the output with label and units as the column header, and
  fcnexpr is a \Tcl\ \cd{expr} expression that may include special
  variables.  Here, however, the allowed special variables are
  \cd{\$x}, \cd{\$y}, \cd{\$z}, \cd{\$r},
  \cd{\$vx}, \cd{\$vy}, \cd{\$vz}, \cd{\$vmag}, where
  \cd{\$x}, \cd{\$y}, \cd{\$z}, and \cd{\$r} are sample location and
  magnitude, respectively ($r = \sqrt{x^2+y^2+z^2}$), and
  \cd{\$vx}, \cd{\$vy}, \cd{\$vz} and \cd{\$vmag} are vector component
  values and magnitude.  The output is the value of fcnexpr averaged
  across the manifold selected by the \cd{-average} option.  A couple
  of examples are
\begin{verbatim}
   -valfunc Ms   A/m '$vmag'
   -valfunc M110 A/m '($vx+$vy)/sqrt(2.)'
\end{verbatim}
  As with the valexpr string for \cd{-index}, the fcnexpr string
  should be surrounding by single quotes on \Unix\ in order to
  forestall interpolation of the special variables by the shell.  On
  Windows, the fcnexpr string should be surrounded by double quotes as
  usual to protect embedded spaces.
  The output value is not affected by the \cd{-normalize} option.
  Multiple instances of the
  \cd{-valfunc} option on the command line will result in multiple
  columns in the output file, in the order specified.  These
  additional columns will be append to the right of all other columns in
  the output file.
\item[\optkey{infile \ldots}]
  Input file list.  Files must be one of the recognized
  formats,  \OVF\ 1.0 or \VIO, in a rectangular mesh subformat.
\end{description}

The file specification options require some explanation.  Input files
may be specified either by an explicit list (\cd{infile ...}),
or by giving a wildcard pattern, e.g., \cd{-ipat *.omf}, which is
expanded in the usual way by \app{avf2odt} (using the \Tcl\ command
\cd{glob}).   \Unix\ shells (sh, csh, etc.) automatically expand
wildcards before handing control over to the invoked application, so the
\cd{-ipat} option is not usually needed---although it is useful in case of a
``command-line too long'' error.  \DOS\ does not do this expansion, so
you must use \cd{-ipat} to get wildcard
expansion\index{platform!Windows!wildcard~expansion} in \Windows.
The resulting file list is sorted  based on the \cd{-filesort}
specification as described above.

If \cd{-onefile} is not requested, then as each input file is
processed, a name for the corresponding output file is produced from
the input filename by rules determined by handing the \cd{-opatexp}
and \cd{-opatsub} expressions to the \Tcl\ \cd{regsub} command.  Refer
to the \Tcl\ \cd{regsub} documentation for details, but essentially
whatever portion of the input filename is matched by the \cd{-opatexp}
expression is removed and replaced by the \cd{-opatsub} string.  The
default \cd{-opatexp} expression matches against any filename
extension of up to 3 characters, and the default \cd{-opatsub} string
replaces this with the extension \fn{.odt}.

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

\subsection{Vector Field File Format Conversion:
          avf2ovf}\label{sec:avf2ovf}%
\index{file!vector~field}\index{file!vio}%
\index{application!avf2ovf}\index{file!conversion}
The \app{avf2ovf} program converts vector field files from any of the
\latexhtml{recognized formats (\OVF, \VIO; see
Sec.~\ref{sec:vfformats})}{\htmlref{recognized formats}{sec:vfformats}
(\OVF, \VIO)} into the \OVF\ format.

\sssechead{Launching}
The \app{avf2ovf} launch command is:
\begin{verbatim}
tclsh oommf.tcl avf2ovf [standard options] \
   [-clip xmin ymin zmin xmax ymax zmax] [-flip flipstr] \
   [-format <text|b4|b8>] [-grid <rect|irreg>] [-info] [-keepbb] \
   [-mag] [-ovfversion version] [-pertran xoff yoff zoff] [-q] \
   [-resample xstep ystep zstep order] [-rpertran rxoff ryoff rzoff] \
   [-subsample period] [infile [outfile]]
\end{verbatim}
where
\begin{description}
\item[\optkey{-clip xmin ymin zmin xmax ymax zmax}]
  The 6 arguments specify the vertices of a bounding clip box.  Only mesh
  points inside the clip box are brought over into the output file.  Any
  of the arguments may be set to ``-'' to use the corresponding value
  from the input file, i.e., to not clip along that box face.
\item[\optkey{-flip flipstr}]
  Provides an axis coordinate transformation.  Flipstr has the form
  A:B:C, where A, B, C is a permutation of $x$, $y$, $z$, with an
  optional minus sign on each entry.  The first component A denotes the
  axis to which $x$ is mapped, B where $y$ is mapped, and $C$ where $z$
  is mapped.  The default is the identity map, {\tt x:y:z}.  To rotate
  $90^\circ$ about the $z$-axis, use ``-flip y:-x:z'', which sends $x$
  to the $+y$ axis, $y$ to the -$x$ axis, and leaves $z$ unchanged.
\item[\optkey{-format \boa text\pipe b4\pipe b8\bca}]
  Specify output data format.  The default is ASCII \cd{text}; \cd{b4} selects
  4-byte binary, \cd{b8} selects 8-byte binary.  (The OVF format has an
  ASCII text header in all cases.)
\item[\optkey{-grid \boa rect\pipe irreg\bca}]
  Specify output grid\index{grid} structure.  The default is \cd{rect},
  which will output a regular rectangular grid if the input is recognized
  as a regular rectangular grid.  The option ``-grid irreg'' forces
  irregular mesh style output.
\item[\optkey{-info}]
  Instead of converting the file, print information about the file, such
  as size, range, and descriptive text from the file header.
\item[\optkey{-keepbb}]
  If the \cd{-clip} option is used, then normally the spatial extent,
  i.e., the boundary, of the output is clipped to the specified clip
  box.  If \cd{-keepbb} (keep bounding box) is given, then the spatial
  extent of the output file is taken directly from the input file.
  Clipping is still applied to the data vectors; \cd{-keepbb} affects
  only the action of the clip box on the boundary.
\item[\optkey{-mag}]
  Write out a scalar valued field instead of a vector value field, where
  the scalar values are the magnitude $|v(r)|$ of the vector values at
  each point $r$.
\item[\optkey{-ovfversion version}]
  Specify the output \OVF\ version, either 1 (default) or 2.
\item[\optkey{-pertran xoff yoff zoff}]
  Translates field with respect to location coordiates, by amount
  $(\mathit{xoff},\mathit{yoff},\mathit{zoff})$, in a periodic
  fashion.  For example, if
  $(\mathit{xoff},\mathit{yoff},\mathit{zoff})$ is $(\mbox{50e-9},0,0)$,
  then a vector $v$ at position
  $(\mathit{rx},\mathit{ry},\mathit{rz})$
  in the original file is positioned instead at
  $(\mathit{rx} + \mbox{50e-9},\mathit{ry},\mathit{rz})$
  in the output file.  If the spatial extent of the
  $x$ coordinate in the input file runs from $\mathit{xmin}$ to
  $\mathit{xmax}$, and if
  $\mathit{rx} +\mbox{50e-9}$ is larger than $\mathit{xmax}$, then $v$
  will be placed at
  $\mathit{rx} + \mbox{50e-9} - \mathit{xmax} + \mathit{xmin}$
  instead.  Translations are rounded to the
  nearest full step; aside from any clipping, the output file has the
  exact same spatial extent and sample locations as the original file.
  If both translation and clipping are requested, then the clipping is
  applied after the translation.
\item[\optkey{-q}]
  Quiet operation --- don't print informational messages.
\item[\optkey{-resample xstep ystep zstep \boa 0\pipe 1\pipe 3\bca}]
  Resample grid using specified step sizes.  Each step size must exactly
  divide the grid extent in the corresponding direction, after any
  clipping.  (That is, the export mesh consists of full cells only.)
  The last argument specifies the polynomial interpolation order: 0 for
  nearest value, 1 for trilinear interpolation, or 3 for fitting with
  tricubic Catmull-Rom splines.  This control is only available for
  input files having a rectangular grid structure.  Default is no
  resampling.
\item[\optkey{-rpertran rxoff ryoff rzoff}]
  Similar to -pertran, except the offsets
  $(\mathit{rxoff},\mathit{ryoff},\mathit{rzoff})$ are
  interpreted as offsets in the range $[0,1]$ taken relative to the
  spatial extents of the $x$, $y$, and $z$ coordinates.  For example, if
  $\mathit{xmax} - \mathit{xmin} = \mbox{500e-9}$, then an
  $\mathit{rxoff}$ value of 0.1 is equivalent
  to an $\mathit{xoff}$ value of 50e-9.
\item[\optkey{-subsample period}]
  Reduce point density in output by subsampling input with specified
  period along $x$, $y$, and $z$ axes.  For example, if period is 2,
  then the output will have only 1/8th as many points as the input.
  This control is only available for input files having a rectangular
  grid structure.  Default value is 1, i.e., no subsampling.
\item[\optkey{infile}]
  Name of input file to process.  Must be one of the recognized
  formats, \OVF\ 0.0, \OVF\ 1.0, \OVF\ 2.0, or \VIO.  If no file is
  specified, reads from stdin.
\item[\optkey{outfile}]
  Name of output file.  If no file is specified, writes to stdout.
\end{description}

The \cd{-clip} option is useful when one needs to do analysis on a
small piece of a large simulation.  The \cd{-info} option is helpful
here to discover the extents of the original mesh.  The \cd{-clip}
option can also be used with \cd{-resample} to enlarge the mesh.

The \cd{-flip} option can be used to align different simulations
to the same orientation.  It can also be used to change a file into its
mirror image; for example, ``-flip~-x:y:z'' reflects the mesh through
the $yz$-plane.

If multiple operations are specified, then the operation order is
clip, resample, subsample, flip, and translate.

The \cd{-format text} and \cd{-grid irreg} options are handy for
preparing files for import into non-\OOMMF\ applications, since all
non-data lines are readily identified by a leading ``\verb+#+,'' and
each data line is a 6-tuple consisting of the node location and vector
value.  Pay attention, however, to the scaling of the vector value as
specified by ``\verb+# valueunit+'' and ``\verb+# valuemultiplier+''
header lines.

For output format details, see the \hyperrefhtml{OVF file
description}{OVF file description (Sec.~}{,
page~\pageref{sec:ovfformat})}{sec:ovfformat}.


\sssechead{Known Bugs}
If the input file contains an explicit boundary polygon (cf.\ the
\cd{boundary} entry in the \htmlref{Segment Header
block}{sec:ovfsegmentheader} subsection of the {\hyperrefhtml{OVF file
description}{OVF file description, Sec.~}{}{sec:ovfformat}}) then the
output file will also contain an explicit boundary polygon.  If clipping
is active, then the output boundary polygon is formed by moving the
vertices from the input boundary polygon as necessary to bring them into
the clipping region.  This is arguably not correct, in particular for
boundary edges that don't run parallel to a coordinate axis.


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

\subsection{Making Bitmaps from Vector Fields:
            avf2ppm}\label{sec:avf2ppm}%
\index{file!bitmap}\index{file!vector~field}\index{file!conversion}%
\index{animations}

The \app{avf2ppm}\index{application!avf2ppm} utility converts a
collection of vector field files (e.g., \fn{.omf}, \fn{.ovf}) into color
bitmaps suitable for inclusion into documents or collating into movies.
The command line arguments control filename and format selection, while
plain-text configuration files, modeled after the
{\hyperrefhtml{\app{mmDisp}}{\app{mmDisp}
(Sec.~}{)}{sec:mmdisp}\index{application!mmDisp}} configuration dialog
box, specify display parameters.

\sssechead{Launching}
The \app{avf2ppm} launch command is:
\begin{verbatim}
tclsh oommf.tcl avf2ppm [standard options] [-config file] [-f] \
   [-filter program] [-format <P3|P6|B24>] [-ipat pattern] \
   [-opatexp regexp] [-opatsub sub] [-v level] [infile ...]
\end{verbatim}
where
\begin{description}
\item[\optkey{-config file}]
  User configuration file that specifies image display parameters.  This
  file is discussed in \htmlref{detail below}{sec:avf2ppmconfig}.
\item[\optkey{-f}]
  Force overwriting of existing (output) files.  By default, if
  \app{avf2ppm} tries to create a file, say \fn{foo.ppm}, that already
  exists, it generates instead a new name of the form \fn{foo.ppm-000},
  or \fn{foo.ppm-001}, \ldots, or \fn{foo.ppm-999}, that doesn't exist
  and writes to that instead.  The {\tt -f} flag disallows alternate
  filename generation, and overwrites \fn{foo.ppm} instead.
\item[\optkey{-filter program}]
  Post-processing application to run on each \app{avf2ppm} output
  file.  May be a pipeline of several programs.
\item[\optkey{-format \boa P3\pipe P6\pipe B24\bca}]
  Specify the output image file format.  Currently supported formats are
  the true color {\em Portable Pixmap} (PPM)\index{file!ppm} formats P3
  (ASCII text) and P6 (binary), and the uncompressed Windows
  BMP\index{file!bmp} 24 bits-per-pixel format.  The default is P6.
\item[\optkey{-ipat pattern}]
  Specify input files using a pattern with ``glob-style'' wildcards.
  Mostly useful in \DOS.
\item[\optkey{-opatexp regexp}]
  Specify the ``regular expression'' applied to input filenames to
  determine portion to be replaced in generation of output filenames.
  The default regular expression is: {\verb!(\.[^.]?[^.]?[^.]?$|$)!}
\item[\optkey{-opatsub sub}]
  The string with which to replace the portion of input filenames
  matched by the {\tt -opatexp regexp} during output filename
  generation.  The default is {\verb!.ppm!} for type P3 and P6 file
  output, {\verb!.bmp!} for B24 file output.
\item[\optkey{-v level}]
  Verbosity (informational message) level, with 0 generating only
  error messages, and larger numbers generating additional information.
  The {\tt level} value is an integer, defaulting to 1.
\item[\optkey{infile \ldots}]
  List of input files to process.
\end{description}

The file specification options require some explanation.  Input files
may be specified either by an explicit list (\cd{infile ...}),
or by giving a wildcard pattern, e.g., \cd{-ipat *.omf}, which is
expanded in the usual way by \app{avf2ppm} (using the \Tcl\ command
\cd{glob}).   \Unix\ shells (sh, csh, etc.) automatically expand
wildcards before handing control over to the invoked application, so the
\cd{-ipat} option is not needed (although it is useful in case of a
``command-line too long'' error).  \DOS\ does not do this expansion, so
you must use \cd{-ipat} to get
wildcard expansion\index{platform!Windows!wildcard~expansion} in \Windows.

As each input file is processed, a name for the output file is produced
from the input filename by rules determined by handing the
\cd{-opatexp} and \cd{-opatsub} expressions to the \Tcl\
\cd{regsub} command.  Refer to the \Tcl\ \cd{regsub} documentation for
details, but essentially whatever portion of the input filename is
matched by the \cd{-opatexp} expression is removed and replaced by
the \cd{-opatsub} string.  The default \cd{-opatexp} expression
matches against any filename extension of up to 3 characters, and the
default \cd{-opatsub} string replaces this with the extension
\fn{.ppm} or \fn{.bmp}.

If you have command line image processing ``filter'' programs, e.g.,
\app{ppmtogif}\index{application!ppmtogif} (part of the
NetPBM\index{NetPBM} package), then you can use the \cd{-filter}
option to pipe the output of \app{avf2ppm} through that filter before it
is written to the output file specified by the \cd{-opat*}
expressions.  If the processing changes the format of the file, (e.g.,
\app{ppmtogif} converts from PPM\index{file!ppm} to
GIF\index{file!gif}), then you will likely want to specify a
\cd{-opatsub} different from the default.

Here is an example that processes all files with the \fn{.omf}
extension, sending the output through \app{ppmtogif} before saving the
results in files with the extension \fn{.gif}:
\begin{verbatim}
tclsh oommf.tcl avf2ppm -ipat *.omf -opatsub .gif -filter ppmtogif
\end{verbatim}
(On \Unix, either drop the \cd{-ipat} flag, or use quotes to protect
the input file specification string from expansion by the shell, as in
\cd{-ipat '*.omf'}.)  You may also pipe together multiple filters, e.g.,
\cd{-filter "ppmquant 256 | ppmtogif"}\index{application!ppmquant}.

\begin{rawhtml}
<A NAME="pt:avf2ppm.config"></A>
\end{rawhtml}
\sssechead{Configuration
files\label{sec:avf2ppmconfig}}\index{file!configuration}
The details of the conversion process are specified by plain-text
configuration files, in the same format as the
\html{\htmlref{\app{mmDisp} configuration
files}{sec:mmdispconfig}.}\latex{\app{mmDisp} configuration file
(Sec.~\ref{sec:mmdispconfig}, page~\pageref{sec:mmdispconfig}).}

Each of the configurable parameters is an element in an array named
\cd{plot\_config}.  The default values for this array are read first
from the main configuration file
\begin{quote}
\fn{oommf/app/mmdisp/scripts/avf2ppm.config}
\end{quote}
followed by the local customization file
\begin{quote}
\fn{oommf/app/mmdisp/scripts/local/avf2ppm.config}
\end{quote}
if it exists.  Lastly, any files passed as \cd{-config} options on the
command line are input.  Each of these parameters is interpreted as
explained in the \htmlref{\app{mmDisp}}{sec:mmdispconfig}
documentation\latex{ (q.v.)}, except that \app{avf2ppm} ignores the
\cd{misc,defaultwindowwidth} and \cd{misc,defaultwindowheight}
parameters, and the following additional parameters are available:
\begin{description}
\item[\optkey{arrow,antialias}]
 If 1\index{antialias}, then each pixel along the edge of an arrow is
 drawn not with the color of the arrow, but with a mixture of the arrow
 color and the background color.  This makes arrow boundaries appear
 less jagged, but increases computation time.  Also, the colors used in
 the anti-aliased pixels are not drawn from the arrow or pixel colormap
 discretizations, so color allocation in the output bitmap may increase
 dramatically.
\item[\optkey{arrow,outlinewidth}]
 Width of a colored outline around each arrow; this can improve
 visibility of an arrow when it is overlayed against a background with
 color similar to that of the arrow.  Default value is zero, meaning no
 outline.  A value of 1 produces an outline with a recommended width,
 and other positive values are scaled relative to this.
\item[\optkey{arrow,outlinecolor}]
 If \cd{arrow,outlinewidth} is positive, then this is the color of the
 arrow outline.
\item[\optkey{misc,boundarypos}]
 Placement of the bounding polygon, either \cd{back} or \cd{front},
 i.e., either behind or in front of the rendered arrows and pixel
 elements.
\item[\optkey{misc,matwidth}]
 Specifies the width, in pixels, of a mat (frame) around the outer edge
 of the image.  The mat is drawn in front of all other objects.  To
 disable, set matwidth to 0.
\item[\optkey{misc,matcolor}]
 Color of the mat.
\item[\optkey{misc,width}, \optkey{misc,height}]
 Maximum width and height of the output bitmap, in pixels.  If
 \cd{misc,crop} is enabled, then one or both of these dimensions may be
 shortened.
\item[\optkey{misc,crop}]
 If disabled (0), then any leftover space in the bitmap (of dimensions
 \cd{misc,width} by \cd{misc,height}) after packing the image are filled
 with the background color.  If enabled (1), then the bitmap is cropped
 to just include the image (with the margin specified by
 \cd{misc,margin}).  {\bf NOTE:} Some movie formats require that
 bitmap dimensions be multiples of 8 or 16.  For such purposes, you
 should disable \cd{misc,crop} and specify appropriate dimensions
 directly with \cd{misc,width} and \cd{misc,height}.
\end{description}

The \hyperrefhtml{default configuration file}{default configuration file
shown in Fig.~}{}{fig:avf2ppm.config}\latex{
(page~\pageref{fig:avf2ppm.config})} can be used as a starting point for
user configuration files.  You may also use configuration files produced
by the \btn{File\pipe Write config\ldots} command in
\htmlref{\app{mmDisp}}{sec:mmdisp}, although any of the above
\app{avf2ppm}-specific parameters that you wish to use will have to be
added manually, using a plain text editor.  You may omit any entries
that you do not want to change from the default.  You may ``layer''
configuration files by specifying multiple user configuration files on
the command line.  These are processed from left to right, with the last
value set for each entry taking precedence.

\begin{codelisting}{f}{fig:avf2ppm.config}{Contents of default configuration
file \fn{avf2ppm.config}.}{pt:avf2ppm.config}
\begin{verbatim}
array set plot_config {
    arrow,status       1                misc,background    #FFFFFF
    arrow,antialias    1                misc,drawboundary  1
    arrow,outlinewidth 0.0              misc,boundarywidth 1
    arrow,outlinecolor #000000          misc,boundarycolor #000000
    arrow,colormap     Red-Black-Blue   misc,boundarypos   front
    arrow,colorcount   100              misc,matwidth      0
    arrow,quantity     z                misc,matcolor      #FFFFFF
    arrow,colorphase   0                misc,margin        10
    arrow,colorreverse 0                misc,width         640
    arrow,autosample   1                misc,height        480
    arrow,subsample    10               misc,crop          1
    arrow,size         1                misc,zoom          0
                                        misc,rotation      0
    pixel,status       1                misc,datascale     0
    pixel,colormap     Teal-White-Red   misc,relcenterpt   {0.5 0.5 0.5}
    pixel,colorcount   100
    pixel,opaque       1                viewaxis            +z
    pixel,quantity     x                viewaxis,xarrowspan {}
    pixel,colorphase   0                viewaxis,xpixelspan {}
    pixel,colorreverse 0                viewaxis,yarrowspan {}
    pixel,autosample   1                viewaxis,ypixelspan {}
    pixel,subsample    0                viewaxis,zarrowspan {}
    pixel,size         1                viewaxis,zpixelspan {}
}
\end{verbatim}
\end{codelisting}

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

\subsection{Making \postscript\ from Vector Fields:
            avf2ps}\label{sec:avf2ps}%
\index{file!PostScript}\index{file!vector~field}\index{file!conversion}

The \app{avf2ps}\index{application!avf2ps} utility creates a
collection of color \eps\ files from a collection of
vector field files (e.g., \fn{.omf}, \fn{.ovf}), which can be embedded
into larger \postscript\ documents or printed directly on a \postscript\
printer.  Operation of the \app{avf2ps} command is modeled after the
{\hyperrefhtml{\app{avf2ppm} command}{\app{avf2ppm} command
(Sec.~}{)}{sec:avf2ppm}\index{application!avf2ppm}} and the print
dialog box in {\hyperrefhtml{\app{mmDisp}}{\app{mmDisp}
(Sec.~}{)}{sec:mmdisp}\index{application!mmDisp}}.

\sssechead{Launching}
The \app{avf2ps} launch command is:
\begin{verbatim}
tclsh oommf.tcl avf2ps [standard options] [-config file] [-f] \
   [-filter program] [-ipat pattern] [-opatexp regexp] [-opatsub sub] \
   [-v level] [infile ...]
\end{verbatim}
where
\begin{description}
\item[\optkey{-config file}]
  User configuration file that specifies image display parameters.  This
  file is discussed in \htmlref{detail below}{sec:avf2psconfig}.
\item[\optkey{-f}]
  Force overwriting of existing (output) files.  By default, if
  \app{avf2ps} tries to create a file, say \fn{foo.ps}, that already
  exists, it generates instead a new name of the form \fn{foo.ps-000},
  or \fn{foo.ps-001}, \ldots, or \fn{foo.ps-999}, that doesn't exist
  and writes to that instead.  The {\tt -f} flag disallows alternate
  filename generation, and overwrites \fn{foo.ps} instead.
\item[\optkey{-filter program}]
  Post-processing application to run on each \app{avf2ps} output
  file.  May be a pipeline of several programs.
\item[\optkey{-ipat pattern}]
  Specify input files using a pattern with ``glob-style'' wildcards.
  Mostly useful in \DOS.
\item[\optkey{-opatexp regexp}]
  Specify the ``regular expression'' applied to input filenames to
  determine portion to be replaced in generation of output filenames.
  The default regular expression is: {\verb!(\.[^.]?[^.]?[^.]?$|$)!}
\item[\optkey{-opatsub sub}]
  The string with which to replace the portion of input filenames
  matched by the {\tt -opatexp regexp} during output filename
  generation.  The default is {\verb!.eps!}.
\item[\optkey{-v level}]
  Verbosity (informational message) level, with 0 generating only
  error messages, and larger numbers generating additional information.
  The {\tt level} value is an integer, defaulting to 1.
\item[\optkey{infile \ldots}]
  List of input files to process.
\end{description}

The file specification options, \cd{-ipat}, \cd{-opatexp}, and
\cd{-opatsub}, are interpreted in the same manner as for the
\htmlref{\app{avf2ppm} application}{sec:avf2ppm}.

If you have command line \postscript\ processing ``filter'' programs,
e.g., \app{ghostscript}\index{application!ghostscript}, then you can
use the \cd{-filter} option to pipe the output of \app{avf2ps} through
that filter before it is written to the output file specified by the
\cd{-opat*} expressions.  If the processing changes the format of the
file, (e.g., from \postscript\ to PDF\index{file!pdf}), then you will
likely want to specify a \cd{-opatsub} different from the default.

Here is an example that processes all files with the \fn{.ovf}
extension, sending the output through \app{ps2pdf} (part of the
ghostscript package) before saving the results in files with the
extension \fn{.pdf}:
\begin{verbatim}
tclsh oommf.tcl avf2ps -ipat *.ovf -opatsub .pdf -filter "ps2pdf - -"
\end{verbatim}
On \Unix, either drop the \cd{-ipat} flag, or use quotes to protect
the input file specification string from expansion by the shell, as in
\cd{-ipat '*.ovf'}.

\begin{rawhtml}
<A NAME="pt:avf2ps.config"></A>
\end{rawhtml}
\sssechead{Configuration
files\label{sec:avf2psconfig}}\index{file!configuration}
The details of the conversion process are specified by plain-text
configuration files, in the same format as the
\html{\htmlref{\app{mmDisp} configuration
files}{sec:mmdispconfig}.}\latex{\app{mmDisp} configuration file
(Sec.~\ref{sec:mmdispconfig}, page~\pageref{sec:mmdispconfig}).}

The arrays \cd{plot\_config} and \cd{print\_config} hold the
configurable parameters.  The default values for these arrays are read
first from the main configuration file
\begin{quote}
\fn{oommf/app/mmdisp/scripts/avf2ps.config}
\end{quote}
followed by the local customization file
\begin{quote}
\fn{oommf/app/mmdisp/scripts/local/avf2ps.config}
\end{quote}
if it exists.  Lastly, any files passed as \cd{-config} options on the
command line are input.  Each of these parameters is interpreted as
explained in the \htmlref{\app{mmDisp}}{sec:mmdispconfig}
documentation\latex{ (q.v.)}, except that \app{avf2ps} ignores the
\cd{misc,defaultwindowwidth} and \cd{misc,defaultwindowheight}
parameters, and the following additional parameters are available:
\begin{description}
\item[\optkey{arrow,outlinewidth}]
 Width of a colored outline around each arrow; this can improve
 visibility of an arrow when it is overlayed against a background with
 color similar to that of the arrow.  Default value is zero, meaning no
 outline.  A value of 1 produces an outline with a recommended width,
 and other positive values are scaled relative to this.
\item[\optkey{arrow,outlinecolor}]
 If \cd{arrow,outlinewidth} is positive, then this is the color of the
 arrow outline.
\item[\optkey{misc,boundarypos}]
 Placement of the bounding polygon, either \cd{back} or \cd{front},
 i.e., either behind or in front of the rendered arrows and pixel
 elements.
\item[\optkey{misc,matwidth}]
 Specifies the width, in pixels, of a mat (frame) around the outer edge
 of the image.  The mat is drawn in front of all other objects.  To
 disable, set matwidth to 0.
\item[\optkey{misc,matcolor}]
 Color of the mat.
\item[\optkey{misc,width}, \optkey{misc,height}]
 Maximum width and height of the output bitmap, in pixels.  If
 \cd{misc,crop} is enabled, then one or both of these dimensions may be
 shortened.
\item[\optkey{misc,crop}]
 If disabled (0), then any leftover space in the bitmap (of dimensions
 \cd{misc,width} by \cd{misc,height}) after packing the image are filled
 with the background color.  If enabled (1), then the bitmap is cropped
 to just include the image (with the margin specified by
 \cd{misc,margin}).  {\bf NOTE:} Some movie formats require that
 bitmap dimensions be multiples of 8 or 16.  For such purposes, you
 should disable \cd{misc,crop} and specify appropriate dimensions
 directly with \cd{misc,width} and \cd{misc,height}.
\end{description}

The \hyperrefhtml{default configuration file}{default configuration file
shown in Fig.~}{}{fig:avf2ps.config}\latex{
(page~\pageref{fig:avf2ps.config})} can be used as a starting point for
user configuration files.  You may also use configuration files produced
by the \btn{File\pipe Write config\ldots} command in
\htmlref{\app{mmDisp}}{sec:mmdisp}, although any of the above
\app{avf2ps}-specific parameters that you wish to use will have to be
added manually, using a plain text editor.  You may omit any entries
that you do not want to change from the default.  You may ``layer''
configuration files by specifying multiple user configuration files on
the command line.  These are processed from left to right, with the last
value set for each entry taking precedence.

\begin{codelisting}{f}{fig:avf2ps.config}{Contents of default configuration
file \fn{avf2ps.config}.}{pt:avf2ps.config}
\begin{verbatim}
array set plot_config {
  arrow,status       1                  misc,background     #FFFFFF
  arrow,colormap     Black-Gray-White   misc,drawboundary   1
  arrow,colorcount   0                  misc,boundarywidth  1
  arrow,quantity     z                  misc,boundarycolor  #000000
  arrow,colorphase   0.                 misc,boundarypos    front
  arrow,colorinvert  0                  misc,matwidth       0
  arrow,autosample   1                  misc,matcolor       #FFFFFF
  arrow,subsample    10                 misc,margin         10
  arrow,size         1                  misc,width          640
  arrow,antialias    1                  misc,height         480
                                        misc,crop           1
  pixel,status       1                  misc,zoom           0
  pixel,colormap     Teal-White-Red     misc,rotation       0
  pixel,colorcount   225                misc,datascale      0
  pixel,opaque       1                  misc,relcenterpt {0.5 0.5 0.5}
  pixel,quantity     x
  pixel,colorphase   0.                 viewaxis            +z
  pixel,colorinvert  0                  viewaxis,xarrowspan {}
  pixel,autosample   1                  viewaxis,xpixelspan {}
  pixel,subsample    0                  viewaxis,yarrowspan {}
  pixel,size         1                  viewaxis,ypixelspan {}
                                        viewaxis,zarrowspan {}
                                        viewaxis,zpixelspan {}
}
array set print_config {
  orient   landscape                    tmargin   1.0
  paper    letter                       lmargin   1.0
  hpos     center                       pwidth    6.0
  vpos     center                       pheight   6.0
  units    in                           croptoview 1
}
\end{verbatim}
\end{codelisting}

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

\subsection{Vector Field File Difference:
          avfdiff}\label{sec:avfdiff}%
\index{file!vector~field}\index{file!vector~field}\index{file!vio}%
\index{application!avfdiff}\index{file!difference}
The \app{avfdiff} program computes differences between vector field files
in any of the \latexhtml{recognized formats (\OVF, \VIO; see
Sec.~\ref{sec:vfformats})}{\htmlref{recognized formats}{sec:vfformats}
(\OVF, \VIO)}.  The input data must lie on rectangular meshes with
identical dimensions.

\sssechead{Launching}
The \app{avfdiff} launch command is:
\begin{verbatim}
tclsh oommf.tcl avfdiff [standard options] [-cross] [-filesort method] \
   [-info] [-numfmt fmt] [-odt label units valexpr] \
   [-resample fileselect interp_order] file-0 file-1 [... file-n]
\end{verbatim}
where
\begin{description}
\item[\optkey{-cross}]
  Compute the pointwise vector cross product
  of each \cd{file-k} against \cd{file-0} instead of subtraction.
\item[\optkey{-filesort method}]
  Specifies the sorting order to apply to the target file list,
  \cd{file-1} through \cd{file-n}.  The order is important when using
  the \cd{-odt} option, because it controls the order of the rows in the
  output.  Parameter \cd{method} should be a valid option string for the
  \Tcl\ command \cd{lsort}, e.g., ``-ascii -decreasing''.  Note that the
  \cd{lsort} sort options all begin with a hyphen, ``-'', and that if
  you want to use multiple options they must be grouped as one element
  to \cd{-filesort} (by, for example, placing quotes around the list).
  If this option is not specified then the order is as presented on the
  command line (or as produced by wildcard expansion).
\item[\optkey{-info}]
  Prints statistics on file differences.  If this option is selected
  then no output files are created.
\item[\optkey{-numfmt fmt}]
  Parameter \cd{fmt} specifies a C-style output format for numeric data if
  \cd{-info} or \cd{-odt} is selected.  Default value is
  ``\verb+%- #20.15g+''.
\item[\optkey{-odt label units valexpr}]
  Computes the file differences, but instead of writing difference files
  to disk this option writes \OOMMF\ Data Table
  \hyperrefhtml{(\ODT)}{(\ODT\ format, Sec.~}{)}{sec:odtformat} output to
  stdout.  The \ODT\ output consists of eight columns.  The first column
  is an index column identifying the target file (\cd{file-1} through
  \cd{file-n}).  The \cd{label} parameter is a string specifying the
  label for this column, and likewise the \cd{units} parameter is a
  string specifying the units for the column.  The third parameter,
  \cd{valexpr}, is any valid \Tcl\ \cd{expr} expression that may
  include the special variables \cd{\$i}, \cd{\$f1}, \cd{\$f2}, \ldots,
  \cd{\$d1}, \cd{\$d2}, \ldots; here \cd{\$i} is the 0-based index of
  the file in the target file list (\cd{file-1} is index 0, \cd{file-2}
  is index 1, etc.), \cd{\$f1} is the first number appearing in the
  target filename, \cd{\$f2} is the second number appearing in the target
  filename, \cd{\$d1} is the first number appearing in the ``Desc''
  fields in the header of the target file, etc.  This control is
  analogous to the \cd{-index} option to 
  \hyperrefhtml{\cd{avf2odt}}{\cd{avf2odt} (Sec.~}{)}{sec:avf2odt}.
  The next three columns are the sum of each of the vector components in
  the difference.  The last four columns are the averaged $L^1$ norm,
  the normalized $L^2$ norm, minimum component absolute value, and
  maximum component absolute value of the difference; these columns
  correspond to those produced by the \cd{-extravals} option to
  \htmlonlyref{\cd{avf2odt}}{sec:avf2odt}.
\item[\optkey{-resample \boa 0\pipe n\bca\  \boa 0\pipe 1\pipe 3\bca}]
  Resample either the base file (\cd{file-0}) to match the resolutions of
  the target files (\cd{file-1} through \cd{file-n}), or resample each
  target file to match the resolution of the base file.  Set
  \cd{fileselect} to 0 for the former, to n for the latter.  The second
  argument specifies the polynomial interpolation order: 0 for
  nearest value, 1 for trilinear interpolation, or 3 for fitting with
  tricubic Catmull-Rom splines.  Default is no resampling.
\item[\optkey{file-0}]
  Name of input file to subtract from other files.  Must be either
  an \OVF\ 1.0 file in the rectangular mesh subformat, or an \VIO\
  file.  Required.
\item[\optkey{file-1}]
  Name of first input file from which \cd{file-0} is to be subtracted.
  Must also be either an \OVF\ 1.0 file in the rectangular mesh
  subformat, or an \VIO\ file, and must have the same dimensions as
  \cd{file-0}.  Required.
\item[\optkey{\ldots\ file-n}]
  Optional additional files from which \cd{file-0} is to be
  subtracted, with the same requirements as \cd{file-1}.
\end{description}

If neither \cd{-info} nor \cd{-odt} are specified, then for each target
file \cd{file-1} through \cd{file-n} a separate output file is
generated, in the \OVF\ 1.0 format.  Each output file has a name based
on the name of corresponding input file, with a \cd{-diff} suffix.  If a
file with the same name already exists, it will be overwritten.

For output file format details, see the \hyperrefhtml{OVF file
description}{OVF file description (Sec.~}{)}{sec:ovfformat}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Cyclic Redundancy Check: crc32\label{sec:crc32}}%
\index{application!crc32}\index{CRC-32}

The \app{crc32} application computes 32-bit cyclic redundancy checksums
(CRC-32) on files.

\sssechead{Launching}
The \app{crc32} command line is:
\begin{verbatim}
tclsh oommf.tcl crc32 [standard options] [-binary|-text] \
   [-decimal|-hex] [-v level] [file ...]
\end{verbatim}
where
\begin{description}
\item[\optkey{-binary\textmd{\pipe}-text}]
 Select binary (default) or text input mode.
\item[\optkey{-decimal\textmd{\pipe}-hex}]
 Output CRC value in decimal (default) or hexadecimal format.
\item[\optkey{-v level}]
  Verbosity (informational message) level, with 0 generating only error
  messages and minimal CRC output, and larger numbers generating
  additional information.  The {\tt level} value is an integer,
  defaulting to 1.
\item[\optkey{file \ldots}]
 List of files to process.  If no files are listed, then input is read
 from stdin.
\end{description}
For each file in the input file list, the CRC-32 is computed and output.
By default, the computation is on the raw byte stream (binary mode).
However, if text mode is selected, then text mode translations, e.g.,
carriage return + newline $\rightarrow$ newline conversion, is performed
before the CRC-32 computation.  Text mode translations usually have no
effect on \Unix\ systems.  For additional information on text mode, see
the \Tcl\ documentation for \cd{fconfigure}, specifically ``-translation
auto.''

If the verbosity level is 1 or greater, then the length of the byte
stream as processed by the CRC-32 computation is also reported.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Killing \OOMMF\ Processes: killoommf\label{sec:killoommf}}%
\index{application!killoommf}\index{processes!killing}

The \app{killoommf} application terminates running \OOMMF\ processes.

\sssechead{Launching}
The \app{killoommf} command line is:
\begin{verbatim}
tclsh oommf.tcl killoommf [standard options] [-account name] \
   [-hostport port] [-pid] [-q] [-show] [-shownames] [-test] \
   [-timeout secs] oid [...]
\end{verbatim}
where
\begin{description}
\item[\optkey{-account name}]
 Specify the account name.  The default is the same used by
 \hyperrefhtml{\app{mmLaunch}}{\app{mmLaunch} (Sec.~}{)}{sec:mmlaunch}:
 the current user login name, except on \Windows~9X, where the dummy
 account ID  ``oommf''\index{platform!Windows!dummy~user~ID} may be used
 instead.
\item[\optkey{-hostport port}]
 Use the host server listening on \cd{port}.  Default is set by the
 \cd{Net\_Host~port} setting in \fn{oommf/config/options.tcl}, or by
 the environment variable \cd{OOMMF\_HOSTPORT} (which, if set,
 overrides the former).  The standard setting is 15136.
\item[\optkey{-pid}]
 Select processes by system pid rather than OOMMF oid.
\item[\optkey{-q}]
 Quiet; don't print informational messages.
\item[\optkey{-show}]
 Don't kill anything, just print matching targets.
\item[\optkey{-shownames}]
 Don't kill anything, just print nicknames of matching targets, where
 nicknames are as set by the \MIF\ 2.1
 \htmlonlyref{\cd{Destination}}{html:destinationCmd}
 command\latex{ (Sec.~\ref{sec:mif2ExtensionCommands})}.
\item[\optkey{-test}]
 Don't kill anything, just test that targets are responding.
\item[\optkey{-timeout secs}]
 Maximum time to wait for response from servers, in seconds.  Default
 is five seconds.
\item[\optkey{oid \ldots}]
 List of one or more oids (\OOMMF\ ID's), application names,
 nicknames, or the keyword ``all''.  Glob-style wildcards may also be
 used.  This field is required (there are no default kill targets).  If
 the \cd{-pid} option is specified then numbers are interpreted as
 referring to system process ID's rather than \OOMMF\ ID's.
\end{description}
The \app{killoommf} command affects processes that listen to \OOMMF\
message traffic.  These are the same applications that are listed in
the ``Threads'' list of \hyperrefhtml{\app{mmLaunch}}{\app{mmLaunch}
(Sec.~}{)}{sec:mmlaunch}.  The command
\begin{verbatim}
tclsh oommf.tcl killoommf all
\end{verbatim}
is essentially equivalent to the ``\cd{File\pipe Exit All OOMMF}''
menu option in \app{mmLaunch}, except that \app{killoommf} does not
shut down any \app{mmLaunch} processes.

An \OOMMF\ application that does not respond to \app{killoommf} can be
killed by using the \OOMMF\ command line program
\hyperrefhtml{\app{pidinfo}}{\app{pidinfo} (Sec.~}{)}{sec:pidinfo} to
determine its PID (process identification) as used by the operating
system, and then using the system facilities for terminating processes
(e.g., \cd{kill} on \Unix, or the \cd{Windows Task Manager} on
\Windows).

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

\subsection{Last Oxsii/Boxsi run:
            lastjob\label{sec:lastjob}}%
\index{application!lastjob}

The \app{lastjob} command reads through
\hyperrefhtml{Oxs}{Oxs (Sec.~}{)}{sec:oxs}\index{application!Oxs}
log files and identifies
the last simulation run.  From information in the log file,
\app{lastjob} constructs a command equivalent to that used to launch
the last simulation and prints that command to stdout.  If that
simulation is not recorded as complete in the log file, and a restart is
requested, then the simulation will be restarted with the
\cd{-restart 1} comand line option.  If a restart
(checkpoint) file exists for the simulation, then the command will
restart the simulation at the checkpoint state.  If a restart file
cannot be found, then the job restart will fail.
(By default, \app{oxsii} and \app{boxsi} write
\latex{checkpoint files (Sec.~\ref{sec:oxsDrivers},
page~\pageref{html:oxsdrivercheckpoint})}%
\html{\htmlref{checkpoint files}{html:oxsdrivercheckpoint}}
to disk every fifteen minutes.  If a simulation is aborted, for example
by a system crash, then the checkpoint file can be used to restart the
simulation.)

\sssechead{Launching}
The \app{lastjob} launch command is:
\begin{verbatim}
tclsh oommf.tcl lastjob [-logfile logname] [-unfinished] [-v] <show|restart> \
   <oxsii|boxsi> [hostname] [username]
\end{verbatim}
where
\begin{description}
\item[\optkey{-logfile logname}]
The name of the file to look in to determine the last job.  Optional.
The default is to look in the \OOMMF\ root directory for either
\fn{oxsii.errors} or \fn{boxsi.errors}, corresponding to whether
\app{oxsii} or \app{boxsi} jobs are selected.
\item[\optkey{-unfinished}]
Restrict search to unfinished jobs.  Optional.
\item[\optkey{-v}]
Request verbose output.  Optional.
\item[\optkey{show\pipe restart}]
Selects whether to simply show the command or to attempt a restart.
Required.
\item[\optkey{oxsii\pipe boxsi}]
Selects \app{oxsii} or \app{boxsi} jobs.  Required.
\item[\optkey{hostname}]
The name of the host machine to look for jobs for.  This is optional,
with the default being the name of the current machine.  This option is
useful if the log file is on a shared drive used by multiple hosts.
This field is interpreted as a regular expression, so for example
``\cd{.*}'' can be used to find the last job for all hosts.
\item[\optkey{username}]
The name of the user to look for jobs for.  This is optional,
with the default being the name of the current user.  This option is
useful if the same log file is shared by multiple users.
This field is interpreted as a regular expression, so for example
``\cd{.*}'' can be used to find the last job by any user.
\end{description}
Note: If your command shell expands wildcards, as is common on Unix
systems, then you may need to escape or quote regular expressions to
protect them from expansion by the shell.


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

\subsection{Launching the \OOMMF\ host server:
   launchhost\label{sec:launchhost}}%
\index{application!launchhost}\index{processes!host~server}\index{ports}

Under normal circumstances, the \OOMMF\ host server (also known as the
host service directory) is automatically launched in the background as
needed by client applications.  However, it can be useful, primarily in
batch compute environments, to launch the host server explicitly in
order to control the host server port address.

\sssechead{Launching}
The \app{launchhost} command line is:
\begin{verbatim}
tclsh oommf.tcl launchhost [standard options] port
\end{verbatim}
where
\begin{description}
\item[\optkey{port}]
Requested port number for host server to listen on.  For
non-privileged users, this usually has to be larger than 1024, or the
special value 0 which signals the host server to open on a random,
unused port.  On success, \app{launchhost} writes the host port number
actually used to stdout.
\end{description}
As described in the \hyperrefhtml{\OOMMF\ architecture
documentation}{\OOMMF\ architecture documentation
(Sec.~}{)}{sec:arch}, the host server (host service directory) plays a
vital role in allowing various \OOMMF\ applications to communicate
with one another.  To work, the host server port number must be known
to all \OOMMF\ applications.  Typically this port number is determined
by the \cd{Net\_Host~port} setting in the file
\fn{oommf/config/options.tcl}, although this
setting may be overridden by the environment variable
\cd{OOMMF\_HOSTPORT}.

In batch-mode settings, however, it can occur that one wants to run
multiple concurrent but independent \OOMMF\ sessions on a single
machine.  One way to accomplish this is to set the environment
variable \cd{OOMMF\_HOSTPORT} to distinct values in each session.
A difficulty here is the bookkeeping necessary to insure that each
session really gets a distinct value.  Using \app{launchhost} with
\cd{port} set to zero provides a straightforward solution to this
problem.  For example, consider the Bourne shell script:
\begin{verbatim}
   #!/bin/sh
   OOMMF_HOSTPORT=`tclsh oommf.tcl launchhost 0`
   export OOMMF_HOSTPORT
   tclsh oommf.tcl mmArchive
   tclsh oommf.tcl boxsi sample.mif
   tclsh oommf.tcl killoommf all
\end{verbatim}
The second line (\cd{OOMMF\_HOSTPORT=\ldots}) launches the host server
on a random port; the port selected is printed to stdout by
\app{launchhost} and sets the environment variable
\cd{OOMMF\_HOSTPORT}.  (Note in particular the backticks around the
\app{launchhost} command, which invoke command execution.)  The
subsequent commands launch an instance of \app{mmArchive} in the
background, and run \app{boxsi} on the problem described by
\fn{sample.mif}.  (By default, \app{boxsi} runs in the foreground.)
When \app{boxsi} returns, the \app{killoommf} command is used to
terminate all \OOMMF\ processes in this session.  (Alternatively, the
\app{boxsi} command option \cd{-kill} may be used to the same effect
as \app{killoommf}.)  For \app{csh} and derivatives, use
\begin{verbatim}
   setenv OOMMF_HOSTPORT `tclsh oommf.tcl launchhost 0`
\end{verbatim}
in place of the two \cd{OOMMF\_HOSTPORT} commands in the above
example.


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

\subsection{Calculating \vH\ Fields from Magnetization:
            mag2hfield}\label{sec:mag2hfield}%
\index{file!magnetization}\index{file!vector~field}\index{file!conversion}

The \app{mag2hfield}\index{application!mag2hfield} utility takes a
\MIF~1.1 micromagnetic problem specification file
(\hyperrefhtml{\fn{.mif}}{\fn{.mif}, see Sec.~}{}{sec:mif1format}) and a
magnetization file (\hyperrefhtml{\fn{.omf}}{\fn{.omf}, see
Sec.~}{}{sec:vfformats}) and uses the \hyperrefhtml{mmSolve2D}{mmSolve2D
(Sec.~}{)}{sec:mmsolve2d} computation engine to calculate the resulting
component (self-magnetostatic, exchange, crystalline anisotropy, Zeeman)
and total energy and/or \vH\ fields.  The main use of this utility to study
the fields in a simulation using magnetization files generated by an
earlier
\app{mmSolve2D} run.

\sssechead{Launching}
The \app{mag2hfield} launch command is:
\begin{verbatim}
tclsh oommf.tcl mag2hfield [standard options]
   [-component [all,][anisotropy,][demag,][exchange,][total,][zeeman] \
   [-data [energy,][field]] [-energyfmt fmt] [-fieldstep #] \
   mif_file omf_file [omf_file2 ...]
\end{verbatim}
where
\begin{description}
\item[\optkey{-component
  [all,][anisotropy,][demag,][exchange,][total,][zeeman]}]
  Specify all energy/field components that are desired.  Optional;
  default is {\tt total}, which is the sum of the crystalline
  anisotropy, demagnetization (self-magnetostatic), exchange, and Zeeman
  (applied field) terms.
\item[\optkey{-data [energy,][field]}]
  Calculate energies, \vH\ fields, or both.  Energy values are printed
  to stdout, \vH\ fields are written to files as described below.
  Optional; the default is {\tt energy,field}.
\item[\optkey{-energyfmt fmt}]
  Output C printf-style format string for energy data.  Optional.  The
  default format string is \verb+"%s"+.
\item[\optkey{-fieldstep \lb}]
  Applied field step index, following the schedule specified in the
  input \MIF\ file (0 denotes the initial field).  Optional; default is
  0.
\item[\optkey{mif\_file}]
  \MIF\ micromagnetic problem specification file (.mif).  Required.
\item[\optkey{omf\_file}]
  Magnetization state file.  This can be in any of the formats accepted
  by the \cd{avfFile} record of the input \MIF\ file.  Required.
\item[\optkey{omf\_file2 \ldots}]
  Optional additional magnetization state files.
\end{description}

The \vH\ field output file format is determined by the
\latexhtml{\cd{Total Field Output Format} record of the input \MIF~1.1 file
(Sec.~\ref{sec:mif1format}).}{\htmlref{Total Field Output
Format}{sec:mif1outspec} record of the input \MIF~1.1 file.}  The output
file names are constructed using the form \fn{{\em
basename}-hanisotropy.ohf}, \fn{{\em basename}-hzeeman.ohf}, etc., where
{\em basename} is the input \fn{.omf} magnetization file name, stripped
of any trailing \fn{.omf} or
\fn{.ovf} extension.

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

\subsection{\MIF\ Format Conversion: mifconvert}\label{sec:mifconvert}%
\index{file!MIF}\index{file!conversion}

The \app{mifconvert}\index{application!mifconvert} utility converts any
of the
\hyperrefhtml{\MIF}{\MIF\ (Sec.~}{,
page~\pageref{sec:mifformat})}{sec:mifformat} formats into the
\MIF~2.1 format used by the
\hyperrefhtml{Oxs 3D solvers}{Oxs 3D solvers (Sec.~}{)}{sec:oxs}.
It can also convert between
the  \MIF~1.1 and \MIF~1.2
formats generated by micromagnetic problem editor,
\hyperrefhtml{mmProbEd}{mmProbEd (Sec.~}{)}{sec:mmprobed}.

As a migration aid, \app{mifconvert} will convert most files from the
obsolete \MIF~2.0 format used by \OOMMF\ 1.2a2 into the newer
\MIF~2.1 format.

\sssechead{Launching}
The \app{mifconvert} launch command is:
\begin{verbatim}
tclsh oommf.tcl mifconvert [-f|--force] [--format fmt]
   [-h|--help] [--nostagecheck] [-q|--quiet] [--unsafe]
   [-v|--version] input_file output_file
\end{verbatim}
where
\begin{description}
\item[\optkey{-f} or \optkey{--force}]
  Force overwrite of output file.  Optional.
\item[\optkey{--format fmt}]
  Specify output format, where \cd{fmt} is one of 1.1, 1.2, or 2.1.  The
  1.1 and 1.2 formats are available only if the input file is also in
  the 1.x format.  Conversion from the 2.1 format to the 1.x formats is
  not supported.  Optional; default setting is 2.1.
\item[\optkey{-h} or \optkey{--help}]
  Print help information and stop.
\item[\optkey{--nostagecheck}]
  Sets the \cd{stage\_count\_check} parameter in the output
 \hyperrefhtml{Oxs\_Driver
 Specify block}{Oxs\_Driver Specify block (Sec.~}{,
 page~\pageref{sec:oxsDrivers})}{sec:oxsDrivers} to 0;
 this disables stage count consistency checks inside the Oxs
 solver. Optional.
 This option is only active when the output \MIF\ format is 2.1.
\item[\optkey{-q} or \optkey{--quiet}]
  Suppress normal informational and warning messages.  Optional.
\item[\optkey{--unsafe}]
  Runs embedded Tcl scripts, if any, in unsafe interpreter.  Optional.
\item[\optkey{-v} or \optkey{--version}]
  Print version string and stop.
\item[\optkey{input\_file}]
  Name of the import micromagnetic problem specification file, in
  \MIF~1.1, \MIF~1.2, or \MIF~2.0 format.  Use ``-'' to read from stdin.
  Required.
\item[\optkey{output\_file}]
  Name of the export micromagnetic problem specification file. Use ``-''
  to write to stdout.  Required.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Process Nicknames: nickname\label{sec:nickname}}%
\index{application!pidinfo}\index{PID's}\index{OID's}\index{nicknames}

The \app{nickname} command associates nicknames to running instances
of \OOMMF\ applications.  These names are used by the \MIF\ 2.x
\htmlonlyref{\cd{Destination}}{html:destinationCmd} command\latex{
(Sec.~\ref{sec:mif2ExtensionCommands})}.

\sssechead{Launching}
The \app{nickname} command line is:
\begin{verbatim}
tclsh oommf.tcl nickname [standard options] [-account name] \
   [-hostport port] [-pid] [-timeout secs] oid nickname [nickname2 ...]
\end{verbatim}
where
\begin{description}
\item[\optkey{-account name}]
 Specify the account name.  The default is the same used by
 \hyperrefhtml{\app{mmLaunch}}{\app{mmLaunch} (Sec.~}{)}{sec:mmlaunch}:
 the current user login name, except on \Windows~9X, where the dummy
 account ID  ``oommf''\index{platform!Windows!dummy~user~ID} may be used
 instead.
\item[\optkey{-hostport port}]
 Use the host server listening on \cd{port}.  Default is set by the
 \cd{Net\_Host~port} setting in \fn{oommf/config/options.tcl}, or by
 the environment variable \cd{OOMMF\_HOSTPORT} (which, if set,
 overrides the former).  The standard setting is 15136.
\item[\optkey{-pid}]
 Specify application instance to nickname by system PID
 (process identifier) rather than OID (\OOMMF\ identifier).
\item[\optkey{-timeout secs}]
 Maximum time to wait for response from servers, in seconds.  Default
 is five seconds.
\item[\optkey{oid}]
 The \OOMMF\ ID of the running application instance to nickname, unless
 the \cd{-pid} option is specified, in which case the system PID is
 specified instead.
\item[\optkey{nickname}]
 One or more nicknames to associate with the specified application
 instance.  Each nickname must include at least one non-numeric
 character.
\end{description}
This command is used to associate nicknames with running instances of
\OOMMF\ applications.  The \MIF\ 2
\htmlonlyref{\cd{Destination}}{html:destinationCmd} command can then
use the nickname to link Oxs output to a given OOMMF application
instance at problem load time.  Nicknames for GUI applications can be
viewed in the application \cd{About} dialog box, or can be seen for
any application via the \cd{-names} option to the command line
application \htmlonlyref{\app{pidinfo}}{sec:pidinfo}.

Note that nicknames can also be associated with \OOMMF\ applications
when they are started via the standard \cd{-nickname} command line
option, or by using the \cd{application:nickname} syntax for
applications launched by the \MIF\ \cd{Destination} command.

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

\subsection{\ODT\ Derived Quantity Calculator: odtcalc}\label{sec:odtcalc}%
\index{file!data~table}

The \app{odtcalc}\index{application!odtcalc} utility reads an
\hyperrefhtml{\ODT}{\ODT\ (Sec.~}{)}{sec:odtformat} file on stdin
that contains one or more tables, and prints to stdout an \ODT\ file
consisting of the same tables augmented by additional columns as
controlled by command line arguments.  This utility enables the calculation
and recording of new data table columns that can be computed from
existing columns.

\sssechead{Launching}
The \app{odtcalc} launch command is:
\begin{verbatim}
tclsh oommf.tcl odtcalc [standard options] [var expr unit ...] \
    <infile >outfile
\end{verbatim}
where
\begin{description}
\item[\optkey{var expr unit \ldots}]
  Each triplet of command line arguments determines the calculation
  to make for the production of a new column in the output data table.
  Each {\tt var} value becomes the new {\tt Columns:} entry in the
  data table header, labeling the new column of data.
  Each {\tt unit} value becomes the new {\tt Units:} entry in the
  data table header, reporting the measurement unit for the new
  column of data.
  Each {\tt expr} value is a Tcl expression to be evaluated to
  compute each new data value to be stored in the new column of data.
  See below for more details.
\item[\optkey{\boa infile}]
  \app{odtcalc} reads its input from stdin.  Use the redirection operator
  ``\boa'' to read input from a file.
\item[\optkey{\bca outfile}]
  \app{odtcalc} writes its output to stdout.  Use the redirection operator
  ``\bca'' to send output to a file.
\end{description}

The computation of a new data value for each row of each new column
of data is performed by passing the corresponding {\tt expr} command
line argument to Tcl's {\bf expr} command.  The standard collection
of operators and functions are available.  The value of other columns
in the same row may be accessed by use of the column label as a variable
name.  For example, the value of the {\tt Iteration} column can be used
in {\tt expr} by including the variable substitution {\tt \$Iteration}.
When column labels include colons, the {\tt expr} has the option of using
just the portion of the column label after the last colon as the variable
name.  For example, the value of the {\tt Oxs\_UZeeman::Bx} column can
be used in {\tt expr} by including the variable substitution {\tt \$Bx}.
When multiple triples specifying new data columns are provided, the
values of earlier new columns may be used to compute the values of later
new columns.  The order of command line arguments controls the order of
the new columns that are added to the right side of the data table.

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

\subsection{\ODT\ Table Concatenation: odtcat}\label{sec:odtcat}%
\index{file!data~table}

The \app{odtcat}\index{application!odtcat} utility reads an
\hyperrefhtml{\ODT}{\ODT\ (Sec.~}{)}{sec:odtformat} file on stdin that
contains one or more tables, and concatenates them together into a
single table, creating a new \ODT\ file consisting of a single table.
When successive tables are joined, the tail of the first is truncated as
necessary so that the specified control column is monotonic across the
seam.

This tool is useful for fixing up \ODT\ output from a simulation that
was interrupted and restarted from checkpoint data one or more times.

\sssechead{Launching}
The \app{odtcat} launch command is:
\begin{verbatim}
tclsh oommf.tcl odtcat [standard options] [-b overlap_lines] \
   [-c control_column] [-o order] [-q] <infile >outfile
\end{verbatim}
where
\begin{description}
\item[\optkey{-b overlap\_lines}]
  Overlap window size.  This is the maximum number of lines to retain
  when looking for overlap between two adjacent tables.  This is also
  the upper limit on the number of lines that may be removed when
  two tables are joined.  The default value is 100.
\item[\optkey{-c control\_column}]
  Specifies control column, either by number or glob-string.  Default
  is the glob string
  \cd{\ocb Oxs\_TimeDriver:*:Simulation time\ccb\ Oxs\_MinDriver:*:Iteration}.
\item[\optkey{-o order}]
  Order selection: one of \cd{increase}, \cd{decrease}, \cd{auto}
  (default), or \cd{none}.
\item[\optkey{-q}]
  Quiet; don't write informational messages to stderr.
\item[\optkey{\boa infile}]
  \app{odtcat} reads its input from stdin.  Use the redirection operator
  ``\boa'' to read input from a file.
\item[\optkey{\bca outfile}]
  \app{odtcat} writes its output to stdout.  Use the redirection operator
  ``\bca'' to send output to a file.
\end{description}
The first table header is examined and compared against the control
column specification to identify the control column.  If multiple
columns match the control column specification, then an error is
reported and the process exits.  The \OOMMF\ command line utility
{\hyperrefhtml{\app{odtcols}}{\app{odtcols} (Sec.~}{)}{sec:odtcols}}
with the \texttt{\textbf{-s}} command line switch can be used to view
column headers before running \app{odtcat}.

Each table in the input stream is assumed to have the same layout as
the first; header information between tables is summarily eliminated.
As each table is encountered, a check is made that the new table has
the same number of columns as the first.  If not, an error is reported
and processing is halted.

When subsequent table headers are encountered, the values in the
control column in the tail of the preceding table and the head of the
succeeding table are compared.  The order selection is used to
determine the position of the start of the latter table inside the
tail of the former.  If the data are not compatible with the specified
ordering, then an error is reported an the program aborts.  If
identical values are discovered, then the matching lines in the
earlier table are excluded from the output stream.

If the \texttt{\textbf{-q}} flag is not specified, then after
processing is complete a report is written to stderr detailing the
number of tables merged and the number of data lines eliminated.

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

\subsection{\ODT\ Column Extraction: odtcols}\label{sec:odtcols}%
\index{file!data~table}

The \app{odtcols}\index{application!odtcols} utility extracts column
subsets from \hyperrefhtml{\ODT}{\ODT\ (Sec.~}{)}{sec:odtformat} data
table files.

\sssechead{Launching}
The \app{odtcols} launch command is:
\begin{verbatim}
tclsh oommf.tcl odtcols [standard options] [-f format] \
   [-m missing] [-q] [-s] [-S] [-t output_type] \
   [-table select] [-no-table deselect] [-w colwidth] \
   [col ...] <infile >outfile
\end{verbatim}
where
\begin{description}
\item[\optkey{-f format}]
  C printf-style format string for each output item.  Optional.  The
  default format string is \verb+"%-${colwidth}s"+.
\item[\optkey{-m missing}]
  String used on output to designate a missing value.  Default
  is the two character open-close curly brace pair, \ocb\ccb, as
  specified by the \hyperrefhtml{\ODT\ file format}{\ODT\ file format
  (Sec.~}{)}{sec:odtformat}.
\item[\optkey{-q}]
  Silences some meaningless error messages, such as "broken pipe" when
  using the \Unix\ head or tail utilities.
\item[\optkey{-s}]
  Produces a file summary instead of column extraction.  Output includes
  table titles, column and row counts, and the header for each specified
  column.  If no columns are specified, then the headers for all the
  columns are listed.
\item[\optkey{-S}]
  Same as  \texttt{-s} option, except the column list is ignored;
  headers for all columns are reported.
\item[\optkey{-t output\_type}]
  Specify the output format.  Here output\_type should be one of the
  strings \cd{odt}, \cd{csv}, or \cd{bare}.  The default is \cd{odt},
  the \hyperrefhtml{\ODT\ file format}{\ODT\ file format
  (Sec.~}{)}{sec:odtformat}.  Selecting \cd{csv} will yield a
  ``Comma-Separated Values'' (CSV) file, which can be read by many
  spreadsheet programs.  The \cd{bare} selection produces space separated
  numeric output, with no \ODT\ header, trailer, or comment lines.  The
  latter two options are intended as aids for transferring data to third
  party programs; in particular, such output is not in \ODT\ format, and
  there is no support in OOMMF for translating back from CSV or bare
  format to \ODT\ format.
\item[\optkey{-table select}]
  Select tables to include in output.  Tables are selected by index
  number; the first table in the file has index 0.  The select string
  consists of one or more selections separated by commas, where each
  selection is either an individual index number or a range with
  inclusive endpoints separated by a colon.  Example select string:
  \cd{0:3,7,9:12}.  Default is all tables.
\item[\optkey{-no-table deselect}]
  Specify tables to exclude from output.  The deselect string has the
  same format at the \cd{-table select} string.  Default is to print all
  tables, so the effective default deselect string is the empty set.
\item[\optkey{-w colwidth}]
  Minimum horizontal spacing to provide for each column on output.
  Optional.  Default value is 15.
\item[\optkey{col \ldots}]
  Output column selections.  These may either be integers representing
  the position of the column in the input data (with the first column
  numbered as 0), or else arbitrary strings used for case-insensitive
  glob-style matching against the column headers.  The columns are
  output in match order, obtained by processing the column selections
  from left to right.  If no columns are specified then by default all
  columns are selected.
\item[\optkey{\boa infile}]
  \app{odtcols} reads its input from stdin.  Use the redirection operator
  ``\boa'' to read input from a file.
\item[\optkey{\bca outfile}]
  \app{odtcols} writes its output to stdout.  Use the redirection operator
  ``\bca'' to send output to a file.
\end{description}
Commonly the \texttt{\textbf{-s}} switch is used in a first pass, to
reveal the column headers; specific column selections may then be made
in a second, separate invocation.  If no options or columns are
specified, then the help message is displayed.

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

\subsection{Oxs package management:
            oxspkg\label{sec:oxspkg}}%
\index{application!oxspkg}

The \app{oxspkg} command is used to manage optional Oxs extension
packages.  Each package is stored in a separate directory under
\fn{oommf/app/oxs/contrib/}.  These packages can be ``installed'' and
``uninstalled'' to and from the \fn{oommf/app/oxs/local/} directory by
the \app{oxspkg} command.  The install is a simple copy that does not
automatically build the package or link it into the Oxs executable---a
separate invocation of
\hyperrefhtml{\app{pimake}}{\app{pimake} (Sec.~}{)}{sec:pimake}
is needed for that.

\sssechead{Launching}
The \app{oxspkg} launch command is:
\begin{description}
\addtolength{\itemsep}{-0.9\baselineskip}
\item[\latex{\hphantom{\textbf{or}}\hspace{1ex}}]\hspace*{1ex}\latex{\\[-\baselineskip]}
\verb+tclsh oommf.tcl oxspkg list+
\item[\textbf{or}\hspace{1ex}]\hspace*{1ex}\latex{\\[-0.4\baselineskip]}
\verb+tclsh oommf.tcl oxspkg listfiles pkg [pkg ...]+
\item[\textbf{or}\hspace{1ex}]\hspace*{1ex}\latex{\\[-0.4\baselineskip]}
\verb+tclsh oommf.tcl oxspkg install [-v] [-nopatch] pkg [pkg ...]+
\item[\textbf{or}\hspace{1ex}]\hspace*{1ex}\latex{\\[-0.4\baselineskip]}
\verb+tclsh oommf.tcl oxspkg uninstall pkg [pkg ...]+
\item[\textbf{or}\hspace{1ex}]\hspace*{1ex}\latex{\\[-0.4\baselineskip]}
\verb+tclsh oommf.tcl oxspkg copyout pkg [pkg ...] destination+
\end{description}
Glob-style wildcards (*, ?) or the keyword \cd{all} are accepted in
package specifications.  (If your command shell expands wildcards, as
is common on \Unix\ systems, then you may need to escape or quote the
wildcards so that they are passed unadulterated to the \app{oxspkg}
program.)  The first argument following the \app{oxspkg}
keyword is one of the sub-commands \cd{list}, \cd{listfiles},
\cd{install}, \cd{uninstall}, or \cd{copyout}:
\begin{description}
\item[\optkey{list}]
  Lists all the packges available under
  \fn{oommf/app/oxs/contrib/}, how many (installable) files are in
  each package, and the package install status.
\item[\optkey{listfiles pkg [pkg \ldots]}]
  List each of the ``installable'' files for the selected package.
  (There may be additional files for the package, e.g.\ \fn{README} or
  files with versioning information, included in the
  \fn{oommf/app/oxs/contrib/\oab pkg\cab/} directory.  However, those
  files are ignored by the \app{oxspkg install} command.)
\item[\optkey{install [-v] [-nopatch] pkg [pkg \ldots]}]
  Install (copies) the installable files for the selected package
  from \fn{oommf/app/oxs/contrib/} to \fn{oommf/app/oxs/local/}.
  This command \textbf{does not} to compile the files or link them
  into the Oxs executable.  The user is responsible for making a
  separate call to \htmlonlyref{\app{pimake}}{sec:pimake}
  to build and link the package.

  For third-party packages, the contents of the
  \fn{oommf/app/oxs/contrib/\oab pkg\cab/} directory will mirror some
  release of the package from the official maintainer of the package.
  If those files don't compile cleanly against the current
  \OOMMF\ distribution, then a patch file will be included in the
  parent \fn{oommf/app/oxs/contrib/} directory.  Normally that patch
  file (if any) is automatically applied as part of the installation
  procedure.  The \cd{-nopatch} option skips the patch step.  Note:
  The patch step requires that a \app{patch} command exists on the
  system executable search path.  \app{patch} is a standard system
  utility on \Unix\ systems.  Versions of \app{patch} for \Windows\ are
  available, such as the one from the GnuWin project.  If there are no
  patches for a particular package, then the message \cd{No patches
    found} will be reported during the install process.

  The \cd{-v} option requests more verbose output.
\item[\optkey{uninstall pkg [pkg \ldots]}]
 Deletes all files in \fn{oommf/app/oxs/local/} associated with the
 selected package.  Here ``associated'' means a file name match with a
 file in the package directory \fn{oommf/app/oxs/contrib/\oab pkg\cab/}.
 There is no checking of contents or timestamps between the files.
\item[\optkey{copyout pkg [pkg \ldots] destination}]
  Selects files in the same manner as the \cd{uninstall} command, but
  rather than deleting the files instead copies them to the
  \fn{destination} directory.  This is intended as a development aid
  for creating patches for packages.
\end{description}

Most of the optional packages controlled by \app{oxspkg} are from
third-party contributors.  However, some may originate with the
\OOMMF\ core development team, but are made optional because they
require third-party libraries or are considered too experimental to be
included among the standard \OOMMF\ packages.  See the \fn{README} file
in the various \fn{oommf/app/oxs/contrib/\oab pkg\cab/} directories
for details.

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

\subsection{Oxs regression tests:
            oxsregression\label{sec:oxsregression}}%
\index{application!regression}

The \app{oxsregression} runs a test suite for the Oxs solver.  For
each test, an instance of
\hyperrefhtml{\app{boxsi}}{\app{boxsi} (Sec.~}{)}{sec:boxsi}\index{application!boxsi}
is run and the results are compared against reference results stored
in subdirectories under \fn{oommf/app/oxs/regression\_tests/}.

\sssechead{Launching}
The \app{oxsregression} launch command is:
\begin{verbatim}
tclsh oommf.tcl runtests [-autoadd] [-ignoreextra] [-keepfail] [-listtests]
       [-loglevel level] [-noexcludes] [-resultsfile stemname] [-showoutput]
       [-sigfigs digits] [-threads count] [-timeout seconds]
       [-updaterefdata] [-v] [testa testb ...]
\end{verbatim}
where
\begin{description}
\item[\optkey{-autoadd}]
 Automatically adds new tests from \MIF\ files found in the examples
 directory \fn{oommf/app/oxs/examples/}.
\item[\optkey{-ignoreextra}]
 Ignore extra columns, if any, in test results as compared to
 reference results.  This is useful in developement work when
 changes to a \MIF\ file introduce additional data table output.
\item[\optkey{-keepfail}]
  Keep results from failed tests.  Normally test results are
  automatically deleted.
\item[\optkey{-listtests}]
  List all selected tests and exit without running any tests.
\item[\optkey{-loglevel level}]
  Controls amount of log information written to \fn{boxsi.errors}
  (default 0).
\item[\optkey{-noexcludes}]
  Some tests suffer from various numerical problems.  These are
  excluded from testing, unless this option is specified.
\item[\optkey{-resultsfile stemname}]
  Test results are written to temporary files; by default these files
  have the stem \cd{regression-test-output}.  If \app{oxsregression}
  is run simultaneously, perhaps on different machines on a shared
  file system, then overwriting of files from one process can
  interfere with the processing by another.  The \cd{-resultsfile}
  option can be used to cordon off results between simultaneous runs.
\item[\optkey{-showoutput}]
  If this switch is not specified, then \fn{stdout} and \fn{stderr}
  output from \app{boxsi} is swallowed by \app{oxsregression}.
\item[\optkey{-sigfigs digits}]
 Number of significant (decimal) digits to use in comparing test to
 reference results; the default setting is eight.
\item[\optkey{-threads count}]
 Number of threads to run \app{boxsi} with.  This option is available
 for threaded builds only.  The default is the default thread count
 for \app{boxsi}.
\item[\optkey{-timeout seconds}]
 Maximum number of seconds to wait for one test to finish; any
 individual test that fails to complete within this time span is summarily
 terminated.  The default time is 150 seconds; use 0 to indicate no timeout.
\item[\optkey{-updaterefdata}]
 For developer use only; this option causes the reference results to
 be replaced (overwritten) with new test results.
\item[\optkey{-v}]
 Enable verbose output.
\item[\optkey{testa testb \ldots}]
 Tests to run, with glob-style wildcards (*, ?) accepted.  If no tests
 are specified then all (non-excluded) tests are selected.  Subtest
 selection must be quoted with the test to appear as a single
 argument, e.g., \verb+"exch6ngbr 1,7,9"+.  If no subtests are
 specified then all subtests are run.
\end{description}

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

\subsection{OOMMF and Process ID Information: pidinfo\label{sec:pidinfo}}%
\index{application!pidinfo}\index{PID's}\index{OID's}

The \app{pidinfo} command prints a table mapping OOMMF ID's (OID's)
to system process ID's (PID's) and application names.

\sssechead{Launching}
The \app{pidinfo} command line is:
\begin{verbatim}
tclsh oommf.tcl pidinfo [standard options] [-account name] \
   [-hostport port] [-names] [-noheader] [-pid] [-ports] \
   [-timeout secs] [-wait secs] [-v] [oid ...]
\end{verbatim}
where
\begin{description}
\item[\optkey{-account name}]
 Specify the account name.  The default is the same used by
 \hyperrefhtml{\app{mmLaunch}}{\app{mmLaunch} (Sec.~}{)}{sec:mmlaunch}:
 the current user login name, except on \Windows~9X, where the dummy
 account ID  ``oommf''\index{platform!Windows!dummy~user~ID} may be used
 instead.
\item[\optkey{-hostport port}]
 Use the host server listening on \cd{port}.  Default is set by the
 \cd{Net\_Host~port} setting in \fn{oommf/config/options.tcl}, or by
 the environment variable \cd{OOMMF\_HOSTPORT} (which, if set,
 overrides the former).  The standard setting is 15136.
\item[\optkey{-names}]\index{nicknames}
 Display application nicknames, which are used by the \MIF\ 2.1
 \htmlonlyref{\cd{Destination}}{html:destinationCmd}
 command\latex{ (Sec.~\ref{sec:mif2ExtensionCommands})}.
\item[\optkey{-noheader}]
 Don't print column headers.
\item[\optkey{-pid}]
 Select processes by system pid rather than OOMMF oid.
\item[\optkey{-ports}]
 Display active server ports for each application.
\item[\optkey{-timeout secs}]
 Maximum time to wait for response from servers, in seconds.  Default
 is five seconds.
\item[\optkey{-v}]
 Display information about the host and account servers.
\item[\optkey{-wait secs}]
 If no match is found, then retry for up to \cd{secs} seconds.  Default
 is zero seconds, i.e., try once.
\item[\optkey{oid \ldots}]
 List of OOMMF ID's to display information about.  Default is all
 current applications.  If the \cd{-pid} option is specified then this
 selection is by system process ID's rather than \OOMMF\ ID's.
\end{description}
The title bar of running OOMMF applications typically displays the
application OID, which are used by OOMMF applications to identify one
another.  These ID's start at 0 and are incremented each time a newly
launched application registers with the account server.  The OID's are
independent of the operating system PID's.  The PID is needed to obtain
information, e.g., resource use, about a running process using system
utilities.  The PID may also be needed to invoke the operating system
``kill'' facility to terminate a rogue OOMMF application.  The
\app{pidinfo} application can be used to correspond OID's or \OOMMF\
application names to PID's for such purposes.

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

\subsection{Platform-Independent Make:
            pimake\label{sec:pimake}}%
\index{application!pimake}

The application \app{pimake}\index{application!pimake}
is similar in operation to the
\Unix\ utility program \fn{make}\index{application!make},
but it is written entirely in
\Tcl\ so that it will run anywhere \Tcl\ is installed.
Like \fn{make}, \fn{pimake} controls the building of one
file, the {\em target}, from other files.
Just as \fn{make} is controlled by rules in
files named \fn{Makefile} or \fn{makefile}, \fn{pimake} is controlled
by rules in files named \fn{makerules.tcl}.

\sssechead{Launching}
The \app{pimake} launch command is:
\begin{verbatim}
tclsh oommf.tcl pimake [standard options] \
   [-d] [-i] [-k] [-out file] [target]
\end{verbatim}
where
\begin{description}
\item[\optkey{-d}]
  Print verbose information about dependencies.
\item[\optkey{-i}]
  Normally an error halts operation.  When \cd{-i} is specified,
  ignore errors and try to continue updating all dependencies
  of target.
\item[\optkey{-k}]
  Normally an error halts operation.
  When \cd{-k} is specified, and an error is encountered, stop
  processing dependencies which depend on the error, but continue
  updating other dependencies of target.
\item[\optkey{-out file}]
  Write output to named file instead of to the standard output.
\item[\optkey{target}]
  The file to build.  May also be (and usually is) a symbolic
  target name.  See below for standard symbolic targets.  By default,
  the first target in \fn{makerules.tcl} is built.
\end{description}

There are several targets which may be used as arguments to
\app{pimake} to achieve different tasks.
Each target builds in the current directory
and all subdirectories.  The standard targets are:
\begin{description}
\item[\optkey{upgrade}]
Used immediately after unpacking a distribution, it removes
any files which were part of a previous release, but are not
part of the unpacked distribution.
\item[\optkey{all}]
Creates all files created by the \fn{configure} target (see below).
Compiles and links all the executables and libraries.
Constructs all index files.
\item[\optkey{configure}]
Creates subdirectories with the same name as the platform type.
Constructs a \fn{ocport.h} file which includes C++ header information
specific to the platform.
\item[\optkey{objclean}]
Removes the intermediate object files created by the compile and
link steps.  Leaves working executables in place.  Leaves
\OOMMF\ in the state of its distribution with pre-compiled
executables.
\item[\optkey{clean}]
Removes the files removed by the \fn{objclean} target.
Also removes the executables and libraries created by the \fn{all}
target.  Leaves the files generated by the \fn{configure} target.
\item[\optkey{distclean}]
Removes the files removed by the \fn{clean} target.
Also removes all files and directories generated by
\fn{configure} target.  Leaves only the files which
are part of the source code distribution.
\item[\optkey{maintainer-clean}]
Remove all files which can possibly be generated from other files.
The generation might require specialized developer tools.  This
target is not recommended for end-users, but may be helpful for
developers.
\item[\optkey{help}]
Print a summary of the standard targets.
\end{description}

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