MIF 2.2
Keywords: userguide

Next: Data Table File Format Up: Problem Specification File Formats Previous: MIF 2.1
Subsections

- Differences between MIF 2.2 and MIF 2.1 Formats
- MIF 2.2 New Extension Commands
- Sample MIF 2.2 File

##
MIF 2.2

The MIF 2.2 format, introduced with OOMMF 1.2a4, is a minor modification to the MIF 2.1 format. MIF 2.2 provides a few additional commands, and is mostly backwards compatible with MIF 2.1, except as detailed below.

###
Differences between MIF 2.2 and MIF 2.1 Formats

1. The first line of a MIF 2.2 file must be ```#` MIF 2.2''.
2. The `basename`, `scalar_output_format` and `vector_field_output_format` options to the `Oxs_TimeDriver` and `Oxs_MinDriver` objects are no longer supported. Instead, there is a new top-level extension command, `SetOptions`, where these options are declared. The `SetOptions` block also supports new options for controlling output vector field mesh type (rectangular or irregular) and scalar field output format.
3. In the MIF 2.1 format, MIF files are processed in a two pass mode. During the first pass, `Specify` commands simply store the contents of the `Specify` blocks without creating any `Oxs_Ext` objects. The `Oxs_Ext` objects associated with each `Specify` block are created in the second pass from the data stored in the first pass. In the MIF 2.2 format, this is replaced with a one pass mode, where `Oxs_Ext` objects are created at the time that the `Specify` commands are parsed. This processing model is more intuitive for MIF file authors, but has two main consequences. The first is that in MIF 2.1 format files, Tcl procs that are used only inside `Specify` commands can be placed anywhere inside the MIF file (for example, commonly at the end), because they won't be called during the first pass. As long as they are defined at any point during the first pass, they will be available for use in the second pass. In contrast, in the MIF 2.2 format, Tcl procs definitions must generally be moved forward, before any references in `Specify` blocks. The second consequence is that `Oxs_Ext` objects defined by `Specify` commands are available for use inside the MIF file. This allows support for the new commands discussed next.

###
MIF 2.2 New Extension Commands

In addition to the commands available in MIF 2.1 files, MIF 2.2 introduces the following new commands: `GetMifFilename`, `GetMifParameters`, `GetOptions`, `SetOptions`, `EvalScalarField`, `EvalVectorField`, `GetAtlasRegions`, and `GetAtlasRegionByPosition`.

GetMifFilename
  The `GetMifFilename` command returns the full (absolute) name of the MIF file being read. This command takes no parameters.

GetMifParameters
  This command takes no parameters, and returns an even numbered list of ``Parameter'' label + value pairs as set on the command line or in the Load Problem dialog box. If no parameters were specified, then the return will be an empty list.

GetOptions
  The `GetOptions` command takes no parameters. It returns the accumulated contents of all preceding `SetOptions` blocks, as an even numbered list of label + value pairs.

SetOptions
  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 default labels are:
  - `basename`
  - `scalar_output_format`
  - `scalar_field_output_format`
  - `scalar_field_output_meshtype`
  - `vector_field_output_format`
  - `vector_field_output_meshtype`
  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 taken from the filename of the input MIF file. 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 values associated with `scalar_field_output_format` and `vector_field_output_format` should be two element lists that specify the style and precision for scalar and vector field 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`. The default value for both `scalar_field_output_format` and `vector_field_output_format` is ```binary 8`''. The values for `scalar_field_output_meshtype` and `vector_field_output_meshtype` should be either ``rectangular'' (default) or ``irregular'', specifying the grid type for the corresponding field output files.

  Multiple `SetOptions` blocks are allowed. Label values specified in one `SetOption` block may be overwritten by a later `SetOption` block. Output formats for a given output are set during the processing of the `Specify` block for the enclosing `Oxs_Ext` object. Therefore, one can specify different formats for outputs in different `Oxs_Ext` objects by strategic placement of `SetOptions` blocks.

  Additional label names may be added in the future, and may be `Oxs_Ext` class dependent. At present there is no checking for unknown label names, but that policy is subject to change.

  An example `SetOptions` block:

  >     SetOptions {
  >      basename fubar
  >      scalar_output_format %.12g
  >      scalar_field_output_format {text %.4g}
  >      scalar_field_output_meshtype irregular
  >      vector_field_output_format {binary 4}
  >     }

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

EvalVectorField
  This command is the same as the `EvalScalarField` command, except that the field reference is to a vector field, and the return value is a three item list representing the three components of the vector field at the specified point.

GetAtlasRegions
  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]

GetAtlasRegionByPosition
  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]

###
Sample MIF 2.2 File

    # MIF 2.2

    ###############
    # Constants
    set pi [expr 4*atan(1.0)]
    set mu0 [expr 4*$pi*1e-7]

    ###############
    # Command-line controls
    Parameter seed 1
    Parameter thickness 6e-9
    Parameter stop 1e-2

    # Texturing angle, phideg, in degrees, from 0 to 90; 0 is all z.
    Parameter phideg 10;

    ###############
    # Output options
    SetOptions [subst {
       basename "polyuniaxial_phi_$phideg"
       scalar_output_format %.12g
       scalar_field_output_format {text %.4g}
       scalar_field_output_meshtype irregular
       vector_field_output_format {binary 4}
    }]

    ###############
    # Rogue grain:
    # If RoguePt is an empty string, then no rogue grain is selected.  OTOH,
    # If RoguePt is set to a three item list consisting of x, y, and z coords
    #   in the problem coordinate system (i.e., in meters), then the grain
    #   containing that point is individually set as specified below.
    Parameter RoguePt {263.5e-9 174.5e-9 3e-9}

    ###############
    # Support procs:
    proc Ellipse { Ms x y z} {
       set x [expr {2*$x-1.}]
       set y [expr {2*$y-1.}]
       if {$x*$x+$y*$y<=1.0} {
          return $Ms
       }
       return 0.0
    }

    ###############
    # Material constants
    set Ms 1.40e6
    set Ku 530e3
    set A  8.1e-12

    ###############
    # Atlas and mesh
    set xsize 400e-9
    set ysize 400e-9
    set xycellsize 1.0e-9
    set zcellsize  3.0e-9

    set grain_count 260
    set grain_map polycrystal-map-mif.ppm

    set colormap {}
    for {set i 0} {$i<$grain_count} {incr i} {
       lappend colormap [format "#%06x" $i]
       lappend colormap $i
    }

    Specify Oxs_ImageAtlas:world [subst {
       xrange {0 $xsize}
       yrange {0 $ysize}
       zrange {0 $thickness}
       viewplane xy
       image $grain_map
       colormap {
          $colormap
       }
       matcherror 0.0
    }]

    Specify Oxs_RectangularMesh:mesh [subst {
       cellsize {$xycellsize $xycellsize $zcellsize}
       atlas :world
    }]

    #################################
    # Uniaxial Anisotropy

    # Generate TEXTURED random unit vector
    set phirange [expr {1-cos($phideg*$pi/180.)}]
    proc Texture {} {
       global pi phirange

       set theta [expr {(2.*rand()-1.)*$pi}]
       set costheta [expr {cos($theta)}]
       set sintheta [expr {sin($theta)}]

       set cosphi [expr {1.-$phirange*rand()}]
       set sinphi [expr {1.0-$cosphi*$cosphi}]
       if {$sinphi>0.0} { set sinphi [expr {sqrt($sinphi)}] }

       set x [expr {$sinphi*$costheta}]
       set y [expr {$sinphi*$sintheta}]
       set z [expr {$cosphi}]

       return [list $x $y $z]
    }

    # Set a random unit vector for each grain region
    set axes {}
    for {set i 0} {$i<$grain_count} {incr i} {
       lappend axes $i
       lappend axes [Texture]
    }

    # Sets the rogue grain ($Rogue < $grain_count)
    if {[llength $RoguePt] == 3} {
       # The :Regions field maps region name (which is a number)
       # to the corresponding number.
       set regionmap {}
       for {set i 0} {$i<$grain_count} {incr i} {lappend regionmap $i $i }
       Specify Oxs_AtlasScalarField:Regions [subst {
          atlas :world
          values [list $regionmap]
       }]
       foreach {x y z} $RoguePt { break }
       set Rogue [EvalScalarField :Regions $x $y $z]
       set item_number [expr 2*$Rogue+1]
       set axes [lreplace $axes $item_number $item_number {1 0 0}]
    }

    Specify Oxs_AtlasVectorField:axes [subst {
       atlas :world
       norm 1.0
       values [list $axes]
    }]

    Specify Oxs_UniaxialAnisotropy [subst {
       K1 $Ku
       axis :axes
    }]

    #################################
    # Exchange
    set A_list {}
    for {set i 0} {$i<$grain_count} {incr i} {
       lappend A_list $i $i $A
    }

    Specify Oxs_Exchange6Ngbr [subst {
       default_A $A
       atlas world
       A   [list $A_list]
    }]

    #################################
    # Zeeman (applied) field
    set field 10000		;# Maximum field (in Oe)
    Specify Oxs_UZeeman [subst {
       multiplier [expr (1./($mu0*1e4))*$field]
       Hrange  {
          { 0 0 0   0 0 1   10}
       }
    }]

    #################################
    # Driver and Evolver

    Specify Oxs_CGEvolve:evolve {}

    Specify Oxs_MinDriver [subst {
       evolver evolve
       stopping_mxHxm $stop
       mesh :mesh
       Ms { Oxs_ScriptScalarField {
          atlas :world
          script_args {relpt}
          script {Ellipse $Ms}
       } }
       m0 { 0 0 -1 }
    }]

Figure 9: Example MIF 2.2 file. (Description.)

OOMMF Documentation Team
September 29, 2018