16.2 Making Data Tables from Vector Fields: avf2odt

Launching
The avf2odt launch command is:

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] \
   [-wgtfunc fcnexpr exclude_zeros] [infile ...]

where

-average space|plane|line|point|ball$\mathbf{>}$

Specify type of averaging. Selection of 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 -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 plane or 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 plane case, the first column specifies the averaging plane offset along the coordinate axis normal to the plane (see -axis option below). In the 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 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 ball, then one line is output for each sample point for which a ball of radius brad (see -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 -defaultpos and -defaultvals options. Additional columns may be introduced by the -index and -valfunc options.) The default averaging type is space.

-axis x|y|z$\mathbf{>}$

For the -average plane and -average line averaging types, selects which subset of affine subspaces the averaging will be performed over. In the plane case, the -axis represents the normal direction to the planes, while for line it is the direction parallel to the lines. This parameter is ignored if -average is not either plane or line. Default value is x.

-ball_radius brad

This option is required if -average is ball, in which case brad specifies the radius of the averaging ball in problem units (e.g., meters). If -average is not ball, then this option is ignored.

-defaultpos 0|1$\mathbf{>}$

By default, the output data columns are as described in the description of the -average option above. However, -defaultpos 0 may be used to omit the columns indicating the averaging position.

-defaultvals 0|1$\mathbf{>}$

By default, the output data columns are as described in the description of the -average option above. However, -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 -valfunc option.

-extravals 0|1$\mathbf{>}$

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

-filesort method

Specifies the sorting order to apply to the input file list. This order is important when using the -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 lsort, e.g., “-ascii -decreasing”. Note that the 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 filesort (by, for example, placing quotes around the list). The default value is “-dictionary” if the -ipat option is specified, or “none” otherwise.

-headers full|collapse|none$\mathbf{>}$

Determines the style of headers written to the output ODT file(s). The full style (default) provides the standard headers, as described in the ODT documentation. Specifying “none” produces raw data lines without any headers. The collapse style is used with multiple input files and the -onefile output option to concatenate output with no ODT header information between the segments.

-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 expr expression that may include the special variables $i, $f1, $f2, …, $d1, $d2, …; here $i is the 0-based index of the file in the list of input files, $f1 is the first number appearing in the input filename, $f2 is the second number appearing in the input filename, $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 foo-100.ovf and and foo-101.ovf, then setting valexpr to abs($f1)+1 would yield a column with the value 101 for all lines coming from foo-100.ovf, and the value 102 for all lines coming from foo-101.ovf. (We use the Tcl expr function abs because the leading hyphen in foo-100.ovf gets interpreted as a minus sign, so $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 -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.

-ipat pattern

Specify input files using a pattern with “glob-style” wildcards. Especially useful in DOS. Files must meet the infile requirements (see below).

-normalize 0|1$\mathbf{>}$

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 -normalize 0 (the default), averaged output values are in file units.

-numfmt fmt

C-style output format for numeric data in the body of the output table. Default value is “%- #20.15g”.

-onefile outfile

Generally a avf2odt writes its output to a collection of files with names generated using the -opatexp and -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.

-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: (\.[^.]?[^.]?[^.]?$|$)

-opatsub sub

The string with which to replace the portion of input filenames matched by the -opatexp regexp during output filename generation. The default is .odt.

-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, -region - - - - - -, selects the entire input file.

-rregion rxmin rymin rzmin rxmax rymax rzmax

This option is the same as -region, except that the locations are specified in relative units, between 0 and 1.

-truncate 0|1$\mathbf{>}$

When opening an existing file for output, the new output can either be appended to the file (-truncate 0), or else the existing data can be discarded (-truncate 1). The default is -truncate 0.

-v level

Verbosity (informational message) level, with 0 generating only error messages, and larger numbers generating additional information. The level value is an integer, defaulting to 1.

-valfunc label units fcnexpr

Similar to the -index option, -valfunc adds an additional column to the output with label and units as the column header, and fcnexpr is a Tcl expr expression that may include special variables. Here, however, the allowed special variables are $x, $y, $z, $r, $vx, $vy, $vz, $vmag, where $x, $y, $z, and $r are sample location and magnitude, respectively ($r=\sqrt{x^2+y^2+z^2}$), and $vx, $vy, $vz and $vmag are vector component values and magnitude. The output is the value of fcnexpr averaged across the manifold selected by the -average option. A couple of examples are

   -valfunc Ms   A/m '$vmag'
   -valfunc M110 A/m '($vx+$vy)/sqrt(2.)'

As with the valexpr string for -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 -normalize option. Multiple instances of the -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.

-wgtfunc fcnexpr exclude_zeros

The -wgtfunc option provides a pointwise weighting to the file field values. The fcnexpr is a Tcl expr expression of the same form as used in the valfunc option, and supports the same special variables. At each spatial location the expression is evaluated (the weight) and is multiplied against the field value there. If exclude_zeros is non-zero then points with zero weight are excluded from the average. Multiple instances of this option are stacked; in this case a point is excluded from the average if any of the instances with exclude_zeros set true have weight = 0. For the plane, line, and ball manifold types, if exclude_zeros>1 then an additional column is included in the output reporting the number of points in the averaging manifold.

One use of the -wgtfunc option with exclude_zeros > 0 is to average across irregular subsets of the full volume. (As compared to the -region and -rregion options which create only axis-parallel rectangular subregions.) For example, to take averages across a full-height cylindrical volume of radius 15 nm centered about $(x,y)=(400\times {10}^{-9},200\times {10}^{-9})$, use

   -wgtfunc 'pow($x-400e-9,2)+pow($y-200e-9,2)<pow(15e-9,2) ? 1 : 0' 1

(On Windows replace the single quotes with double quotes.) As another example, given a magnetization file (.omf) for a magnetic part with an irregular boundary, find the magnetization averaged across the magnetically active portion (i.e., the part with $\text{𝐌}\ne 0$) with

   -wgtfunc '$vmag == 0 ? 0 : 1' 1

(If exclude_zeros here were 0 instead of 1, then the average would be across the full volume, yielding a smaller result because of the averaged-in zeros.)

infile …

Input file list. Files must be one of the recognized formats, OVF 1.0 or VIO, in a rectangular mesh subformat.