In addition to the commands available in MIF 2.1 files, MIF 2.2 introduces the following new commands: GetMifFilename, GetMifParameters, GetOptions, SetOptions, DefaultFieldFilename, EvalScalarField, EvalVectorField, GetAtlasRegions, and GetAtlasRegionByPosition.
In MIF 2.1 files, the output basename and output file formats are specified inside the driver’s Specify block. In MIF 2.2 these specifications are moved to a separate SetOptions block. This block can be placed anywhere in the MIF file, but is typically placed near the start of the file so that it affects all output initializations. The SetOptions command takes a single argument, which is a list of label + value pairs. The supported labels are:
basename
scalar_output_format
scalar_field_output_format
scalar_field_output_meshtype
scalar_field_output_filename_script
vector_field_output_format
vector_field_output_meshtype
vector_field_output_filename_script
Multiple SetOptions blocks are allowed. Values specified in one SetOption block will be superseded if reset by later SetOption blocks. Judicious placement of SetOptions blocks allows formats and filenames to be varied across different outputs in one MIF file.
The basename value is used as a prefix for output filename construction by the data output routines. If basename is not specified, then the default value is the filename of the input MIF file minus its extension (.mif). The scalar_output_format value is a C-style printf string specifying the output format for DataTable output. This is optional, with default value “%.17g”. The scalar(vector)_field_output_format value should be a two element list that specifies the style and precision for output sent to mmDisp and mmArchive. The first element in the list should be one of binary or text, specifying the output style. If binary output is selected, then the second element specifying precision should be either 4 or 8, denoting component binary output length in bytes. For text output, the second element should be a C-style printf string like that used by scalar_output_format. Be forewarned that for large field files text-style output may be many times slower that binary; if you require text format for post-processing, it may be better to save from Oxsii/Boxsi in binary format and convert afterwards to text using avf2ovf. The default value for scalar(vector)_field_output_format is “binary 8”. For scalar(vector)_field_output_meshtype the value should be either “rectangular” (default) or “irregular”, specifying the grid type for the corresponding field output files. The “scalar(vector)_field_output_filename_script” value is a Tcl script used to construct filenames for the respective output type.
Typically SetOptions is declared near the top of the MIF file, before any Specify blocks, so that the options apply to all Oxs_Ext objects. However, multiple SetOptions blocks are allowed. Values specified in one SetOption block will be replaced if reset by later SetOption blocks. Judicious placement of SetOptions blocks allows formats and filenames to be varied across different outputs in one MIF file.
The filename for DataTable output written through mmArchive has the form
<basename>.odt
If an mmArchive instance is associated with a Destination tag, then basename is the setting active at the point of the Destination command in the MIF file. For mmArchive instances not associated with a Destination tag, including ones launched interactively after problem initialization, the basename used is the value active at the end of the MIF file.
Output formats and filename scripts for a given output are set during the processing of the Specify block for the enclosing Oxs_Ext object. For the field outputs, the default filename format is
<basename>-<outputname>-<stage>-<iteration>.<ext>
where the stage and iteration are two and seven digit integers, with leading zeros as needed. (If the total number of stages in a simulation is larger than 99, then the stage format width is expanded to fit. The extension is determined by the type of output: .omf for magnetization, .ohf for H fields, .obf for B fields, .oef for energy density fields, and and .ovf for everything else. The filename format can be altered using a filename script. This script should be a Tcl proc that takes one argument and returns the desired filename. The import argument is a Tcl dict structure that includes the following fields:
The active SetOption basename, extended to an absolute pathname
Generating event: Step, Stage, Done, or Interactive
Iteration count
Suggested iteration format; defaults to “%07d”
The output name, e.g. Oxs_RungeKuttaEvolve::Total field
The protocol type; either scalarField or vectorField
File-system friendly “sanitized” version of the output name, e.g., Oxs_RungeKuttaEvolve-Total_field
Stage number
Suggested stage format; “%02d” unless stage count is larger than 99
Internal state number
Output units, e.g., “A/m”; this will be an empty string if the output is unitless
Inside the filename proc use the Tcl dict get command to retrieve items from the params dict as needed. You can also call
DefaultFieldFilename $params
to get the default scalar or vector field filename as described above.
The following MIF fragment illustrates SetOptions usage including a vector field filename script that truncates the iteration count on stage events:
proc ShortStageVF { params } {
set filename [DefaultFieldFilename $params]
set event [dict get $params event]
if {[string compare Stage $event] == 0} {
# Strip trailing iteration count (but retaining extension)
regsub -- {-[0-9]+(\.[a-zA-Z]+)$} $filename {\1} filename
}
return $filename
}
SetOptions {
basename fubar
scalar_output_format %.12g
scalar_field_output_format {text %.4g}
scalar_field_output_meshtype irregular
vector_field_output_format {binary 4}
vector_field_output_filename_script ShortStageVF
}
Can be called from inside an output filename script with the $params import to retrieve the MIF default filename. See the SetOptions section for details and an example.
This command allows access in a MIF file to values from a scalar field defined in a preceding Specify block. For example,
Oxs_AtlasScalarField:Ms {
atlas :atlas
default_value 0
values {
Adisks 520e3
Bdisks 520e3
}
}}
set Ms_a [EvalScalarField :Ms 50e-9 20e-9 2e-9]
The four arguments to EvalScalarField are a reference to the scalar field (here :Ms), and the three coordinates of the point where you want the field evaluated. The coordinates are in the problem coordinate space, i.e., in meters.
This command takes one argument, which is a reference to an atlas, and returns an ordered list of all the regions in that atlas. The first item on the returned list will always be “universe”, which includes all points not in any of the other regions, including in particular any points outside the nominal bounds of the atlas. Sample usage:
set regions_list [GetAtlasRegions :atlas]
This command takes four arguments: a reference to atlas, followed by the x, y, and z coordinates of a point using problem coordinates (i.e., meters). The return value is the name of the region containing the specified point. This name will match exactly one of the names on the list returned by the GetAtlasRegions command for the given atlas. Note that the return value might be the “universe” region. Sample usage:
set rogue_region [GetAtlasRegionByPosition :atlas 350e-9 120e-9 7.5e-9]