17.3.3 Specify Conventions

The Specify blocks in the input MIF file determine the collection of Oxs_Ext objects defining the Oxs simulation. As explained above, the Specify command takes two arguments, the name of the Oxs_Ext object to create, and an initialization string. The format of the initialization string can be arbitrary, as determined by the author of the Oxs_Ext class. This section presents a number of recommended conventions which Oxs_Ext class authors are encouraged to follow. Any Oxs_Ext classes that don’t follow these conventions should make that fact explicitly clear in their documentation. Details on the standard Oxs_Ext classes included with OOMMF can be found in the Oxs section.

Sometimes the value portion of a label + value pair will itself be a list, as in this next example:

Specify Oxs_BoxAtlas:myatlas {
            …
}

Specify Oxs_RectangularMesh:mymesh {
      cellsize { 5e-9 5e-9 5e-9 }
      atlas Oxs_BoxAtlas:myatlas
}

Here the value associated with “cellsize” is a list of 3 elements, which declare the sampling rate along each of the coordinate axes, in meters. (Oxs_BoxAtlas is a particular type of Oxs_Atlas, and “…” mark the location of the Oxs_BoxAtlas initialization string, which is omitted because it is not pertinent to the present discussion.)

Alternatively, the Oxs_RectangularMesh object could define an Oxs_BoxAtlas object inline:

Specify Oxs_RectangularMesh:mymesh {
      atlas {
            Oxs_BoxAtlas {
                  …
            }
      }
      cellsize { 5e-9 5e-9 5e-9 }
}

In place of the name of an external atlas object, a two item list is provided consisting of the type of object (here Oxs_BoxAtlas) and the corresponding initialization string. The initialization string is provided as a sublist, with the same format that would be used if that object were initialized via a separate Specify block.

More commonly, embedded Oxs_Ext objects are used to initialize spatially varying quantities. For example,

Specify Oxs_UniaxialAnisotropy {
  axis { Oxs_RandomVectorField {
           min_norm 1
           max_norm 1
  }}
  K1  { Oxs_UniformScalarField { value 530e3 } }
}

The magneto-crystalline anisotropy class Oxs_UniaxialAnisotropy supports cellwise varying K1 and anisotropy axis directions. In this example, the anisotropy axis directions are randomly distributed. To initialize its internal data structure, Oxs_UniaxialAnisotropy creates a local Oxs_RandomVectorField object. This object is also a child of the Oxs_Ext hierarchy, which allows it to be constructed using the same machinery invoked by the Specify command. However, it is known only to the enclosing Oxs_UniaxialAnisotropy object, and no references to it are possible, either from other Specify blocks or even elsewhere inside the same initialization string. Because it cannot be referenced, the object does not need an instance name. It does need an initialization string, however, which is given here as the 4-tuple “min_norm 1 max_norm 1”. Notice how the curly braces are nested so that this 4-tuple is presented to the Oxs_RandomVectorField initializer as a single item, while “Oxs_RandomVectorField” and the associated initialization string are wrapped up in another Tcl list, so that the value associated with “axis” is parsed at that level as a single item.

The value associated with “K1” is another embedded Oxs_Ext object. In this particular example, K1 is desired uniform (homogeneous) throughout the simulation region, so the trivial Oxs_UniformScalarField class is used for initialization (to the value $530\times {10}^3$ J/m${}^3$). In the case of uniform fields, scalar or vector, a shorthand notation is available that implicitly supplies a uniform Oxs_Ext field class:

Specify Oxs_UniaxialAnisotropy {
  axis { 1 0 0 }
  K1  530e3
}

which is equivalent to

Specify Oxs_UniaxialAnisotropy {
  axis { Oxs_UniformVectorField {
           vector { 1 0 0 }
  }}
  K1  { Oxs_UniformScalarField { value 530e3 } }
}

While embedding Oxs_Ext objects inside Specify blocks can be convenient, it is important to remember that such objects are not available to any other Oxs_Ext object—only objects declared via top-level Specify blocks may be referenced from inside other Specify blocks. Also, embedded Oxs_Ext objects cannot directly provide user output. Furthermore, the only Oxs_Energy energy objects included in energy and field calculations are those declared via top-level Specify blocks. For this reason Oxs_Energy terms are invariably created via top-level Specify blocks, and not as embedded objects.

As a matter of nomenclature, standard (i.e., flat) lists and single values are also considered grouped lists, albeit trivial ones. Any Oxs object that accepts grouped lists in its Specify block should explicitly state so in its documentation.

Here is an example proc that may be used to set the initial magnetization configuration into an approximate vortex state, with a central core in the positive $z$ direction:

proc Vortex { x_rel y_rel z_rel } {
   set xrad [expr {$x_rel-0.5}]
   set yrad [expr {$y_rel-0.5}]
   set normsq [expr {$xrad*$xrad+$yrad*$yrad}]
   if {$normsq <= 0.0125} {return "0 0 1"}
   return [list [expr {-1*$yrad}] $xrad 0]
}

The return value in this case is a 3D vector representing the spin direction at the point (x_rel,y_rel,z_rel). Procs that are used to set scalar properties, such as saturation magnetization $M_s$, return a scalar value instead. But in both cases, the import argument list specifies a point in the simulation mesh.

In the above example, the import point is specified relative to the extents of the simulation mesh. For example, if x_rel were 0.1, then the $x$-coordinate of the point is one tenth of the way between the minimum $x$ value in the simulation and the maximum $x$ value. In all cases x_rel will have a value between 0 and 1.

In most support proc examples, relative coordinates are the most flexible and easiest representation to work with. However, by convention, scripting Oxs_Ext classes also support absolute coordinate representations. The representation used is selected in the Oxs_Ext object Specify block by the optional script_args entry. The Tcl proc itself is specified by the script entry, as seen in this example:

proc SatMag { x y z } {
   if {$z < 20e-9} {return 8e5}
   return 5e5
}

Specify ScriptScalarField:Ms {
   atlas :atlas
   script_args { rawpt }
   script SatMag
}

The value associated with the label script_args should in this case be a subset of {relpt rawpt minpt maxpt span scalars vectors}, as explained in the Oxs_ScriptScalarField documentation (page 7.3.6). Here rawpt provides the point representation in problem coordinates, i.e., in meters. Other Oxs_Ext objects support a different list of allowed script_args values. Check the documentation of the Oxs_Ext object in question for details. Please note that the names used in the proc argument lists above are for exposition purposes only. You may use other names as you wish. It is the order of the arguments that is important, not their names. Also, MIF 2.1 files are parsed first in toto before the Specify blocks are evaluated, so the support procs may be placed anywhere in a MIF 2.1 file, regardless of the location of the referencing Specify blocks. Conversely, MIF 2.2 files are parsed in a single pass, with Specify blocks evaluated as they are read. Therefore for MIF 2.2 files it is generally best to place proc definitions ahead of Specify blocks in which they are referenced.

The command call to the Tcl support proc is actually built up by appending to the script value the arguments as specified by the script_args value. This allows additional arguments to the Tcl proc to be specified in the script value, in which case they will appear in the argument list in front of the script_args values. The following is equivalent to the preceding example:

proc SatMag { zheight Ms1 Ms2 x y z } {
   if {$z < $zheight} {return $Ms1}
   return $Ms2
}

Specify ScriptScalarField:Ms {
   script_args { rawpt }
   script {SatMag 20e-9 8e5 5e5}
}

Notice in this case that the script value is wrapped in curly braces so that the string SatMag 20e-9 8e5 5e5 will be treated as the single value associated with the label script.

As seen in the earlier example using the Vortex Tcl proc, support procedures in MIF 2.1 files will frequently make use of the Tcl expr command. If you are using Tcl version 8.0 or later, then the cpu time required by the potentially large number of calls to such procedures can be greatly reduced by grouping the arguments to expr commands in curly braces, as illustrated in the Vortex example. The braces aid the operation of the Tcl byte code compiler, although there are a few rare situations involving multiple substitution where such bracing cannot be applied. See the Tcl documentation for the expr command for details.

Sometimes externally defined data can be put to good use inside a Tcl support proc, as in this example:

# Lay out a 6 x 16 mask, at global scope.
set mask {
   1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
   1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
   1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
   1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1
   1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1
   1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1
}

proc MyShape { xrel yrel znotused } {
   global mask  ;# Make mask accessible inside proc
   set Ms 8e5   ;# Saturation magnetization of element
   set xindex [expr {int(floor($xrel*16))}]
   set yindex [expr {5 - int(floor($yrel*6))}]
   set index [expr {$yindex*16+$xindex}]
   # index references point in mask corresponding
   # to (xrel,yrel)
   return [expr {[lindex $mask $index]*$Ms}]
}

The variable mask holds a Tcl list of 0’s and 1’s defining a part shape. The mask is brought into the scope of the MyShape proc via the Tcl global command. The relative $x$ and $y$ coordinates are converted into an index into the list, and the proc return value is either 0 or 8e5 depending on whether the corresponding point in the mask is 0 or 1. This is essentially the same technique used in the ColorField proc example presented in the ReadFile MIF extension command documented above (Sec. 17.3.2), except that there the data structure values are built from a separate image file rather than from data embedded inside the MIF file.

The second parameter, source_field, specifies the vector field output that the output is derived from. The source value should match the label for the source field output as displayed in the “Output” pane of the Oxsii or Boxsi interactive interface; this can also be found in the documentation for the source field Oxs_Ext class. If the source field is from the same class as the user output, then source can use the short form of the name (i.e., the component following the last “:”); otherwise the full name must be used.

The third parameter, select_field, references a field that is used to weight the source field to create the scalar output. The output is computed according to

where the sums are across all cells in the simulation, $W_{\mathrm{select}}[i]$ is the value of the select field at cell $i$, $V_{\mathrm{source}}[i]$ is the value of the source field at cell $i$, and “$\cdot$” indicates the scalar (dot) product.

The first three parameters are required, the remaining parameters are optional. The first of the optional parameters, normalize, affects the denominator in (17.1). If norm_request is 1 (the default), then the output is computed as shown in (17.1). If norm_request is 0, then instead the denominator is replaced with the number of cells in the simulation, i.e., ${\sum }_{i}1$.

The second optional parameter, exclude_0_Ms, is a convenience operator; if novacuum is 1, then the select field is reset so that it is the zero vector at all cells in the simulation where the saturation magnetization is zero. This is especially useful when you want to compute the average magnetization of a shaped part. The change to the select field is made before the denominator in (17.1) is computed, so setting exclude_0_Ms to 1 is equivalent to defining the select field as being zero where $M_s$ is zero in the first place. The default value for this parameter is 0, which results in the select field being used exactly as defined.

The user_scaling parameter (default value 1.0) allows the user to define a constant factor that is multiplied against the result of (17.1). This can be used, for example, in conjuction with the units parameter to implement unit conversion. The units value is an arbitrary string (for example, A/m) that is placed in the DataTable output. This label must follow the rules for ODT unit labels; in particular, embedded newlines and carriage returns are not allowed. If units is not set, then the units string is copied from the units for the source field.

The following is a simple example showing two user outputs based off the demagnetization field:

Specify Oxs_BoxAtlas:atlas [subst {
  xrange {0 $cube_edge}
  yrange {0 $cube_edge}
  zrange {0 $cube_edge}
}]

Specify Oxs_BoxAtlas:octant [subst {
  xrange {0 [expr {$cube_edge/2.}]}
  yrange {0 [expr {$cube_edge/2.}]}
  zrange {0 [expr {$cube_edge/2.}]}
}]

Specify Oxs_AtlasVectorField:octant_field_y {
   atlas :octant
   default_value {0 0 0}
   values {
      octant {0 1 0}
   }
}

Specify Oxs_Demag {
  user_output {
     name "Hdemag_x"
     source_field Field
     select_field {1 0 0}
  }
  user_output {
     name "octant Hdemag_y"
     source_field Field
     select_field :octant_field_y
  }
}

The first user output, “Hdemag_x,” returns the $x$-component of the demagnetization field, averaged across the entire simulation volume. This output will appear in DataTable output with the label “Oxs_Demag::Hdemag_x.” The source_field parameter “Field” refers to the “Field” output of the surrounding Oxs_Ext object, which here means Oxs_Demag::Field. The select field is $(1,0,0)$, uniform across the simulation volume. The second output, “octant Hdemag_y,” is similar, but the average is of the $y$ component of the demagnetization field, and is averaged across only the first octant of the simulation volume. The averaging volume and component selection are defined by the :octant_field_y field object, which is $(0,1,0)$ in the first octant and $(0,0,0)$ everywhere else.

The source code for user defined scalar outputs can be found in the files ext.h and ext.cc in the directory oommf/app/oxs/base/. Example MIF files include cube.mif, pbcbrick.mif, spinvalve.mif, and stdprob2.mif in oommf/app/oxs/examples/.