Vector Field File Format Conversion: avf2ovf

The avf2ovf program converts vector field files from any of the recognized formats (OVF, VIO) into the OOMMF OVF or the Python NumPy NPY format.

Launching
The avf2ovf launch command is:

tclsh oommf.tcl avf2ovf [standard options] \
   [-clip xmin ymin zmin xmax ymax zmax] [-dataformat <text|b4|b8>] \
   [-fileformat <ovf|npy> version] [-flip flipstr] [-grid <rect|irreg>] \
   [-info] [-keepbb] [-mag] [-pertran xoff yoff zoff] [-q] \
   [-resample xstep ystep zstep order] [-resetbasept] \
   [-rpertran rxoff ryoff rzoff]  [-shiftbasept xbase ybase ybase] \
   [-subsample period] [infile [outfile]]

where

-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.

-dataformat <text|b4|b8>

Specify output data format, either ASCII text (text), 4-byte binary (b4), or 8-byte binary (b8). For OOMMF OVF output files, the default is text (note that the OVF format has an ASCII text header in all cases). For Python NumPy NPY output files the default is 8-byte binary. For OOMMF OVF version 2 output, the text option can additionally include a C-style printf format string, e.g., -dataformat "text %16.12e" (note the quotes to keep this a single argument to -dataformat).

-fileformat <ovf|npy> version

Specify the output file format and version, either OOMMF OVF version 1 (default) or 2, or the Python NumPy array file format version 1.

-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, 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.

-grid <rect|irreg>

Specify output grid structure. The default is 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.

-info

Instead of converting the file, print information about the file, such as size, range, and descriptive text from the file header.

-keepbb

If the -clip option is used, then normally the spatial extent, i.e., the boundary, of the output is clipped to the specified clip box. If -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; -keepbb affects only the action of the clip box on the boundary.

-mag

Write out a scalar valued field instead of a vector value field, where the scalar values are the magnitude $\vert v(r)\vert$ of the vector values at each point $r$. This option is only supported for OOMMF OVF version 2 output.

-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 $($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} +$   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} +$50e-9 is larger than $\mathit{xmax}$, then $v$ will be placed at $\mathit{rx} +$   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.

-q

Quiet operation — don't print informational messages.

-resample xstep ystep zstep <0|1|3>

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.

-resetbasept

Adjusts the mesh base point (x/y/zbase) and reorders the mesh data so that all node steps (x/y/zstepsize) are non-negative. This changes the mesh internal data structure but does not affect the mesh location or extent. Rectangular grids only.

-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} =$   500e-9, then an $\mathit{rxoff}$ value of 0.1 is equivalent to an $\mathit{xoff}$ value of 50e-9.

-shiftbasept xbase ybase zbase

Shifts the mesh base point to the specified position, effectively translating the full mesh. Rectangular grids only. If multiple options are selected, then -shiftbasept is applied last.

-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.

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.

outfile

Name of output file. If no file is specified, writes to stdout.

There are also two recognized but deprecated options, -format and -ovf. The former is replaced by -dataformat and the latter superceded by -fileformat.

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

The -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 -dataformat text and -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 “#,” 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 “# valueunit” and “# valuemultiplier” header lines (OVF version 1 only).

The avf2ovf command processes only one file at at time. To convert a large collection of files use the looping facilities in your command shell. For example, if you are running a Bourne shell derivative such bash (common on Linux) or zsh (macOS), you can convert all .omf files in the current directory to NumPy NPY format with the command

 for i in *.omf ; do \
   tclsh oommf.tcl avf2ovf -fileformat npy 1 $i ${i%.omf}.npy ; \
 done

Here the shell variable i is set in turn to the name of each .omf file, and fed as the infile to avf2ovf. For the outfile, the syntax ${i%.omf}.npy replaces the .omf extension with .npy.

The equivalent on Windows is

 for %i in (*.omf) do tclsh oommf.tcl avf2ovf -fileformat npy 1 %i %~ni.npy

In this case %~ni.npy replaces the filename extension.

For file format details, see the OVF file description.

Known Bugs
If the input file contains an explicit boundary polygon (cf. the boundary entry in the Segment Header block subsection of the OVF file description) 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.

OOMMF Documentation Team
September 27, 2024