OOMMF Home next up previous contents index
Next: Micromagnetic Problem Editor: mmProbEd Up: OOMMF eXtensible Solver Previous: OOMMF eXtensible Solver Batch

Subsections


Standard Oxs_Ext Child Classes

An Oxs simulation is built as a collection of Oxs_Ext (Oxs Extension) objects. These are defined via Specify blocks in the input MIF 2.1 file. The reader will find the information and sample MIF file provided in that section to be a helpful adjunct to the material presented below.

This section describes the Oxs_Ext classes available in the standard OOMMF distribution, including documentation of their Specify block initialization strings. The standard Oxs_Ext objects, i.e., those that are distributed with OOMMF, can be identified by the Oxs_ prefix in their names. Additional Oxs_Ext classes may be available on your system. Check local documentation for details.

In the following presentation, the Oxs_Ext classes are organized into 8 categories: atlases, meshes, energies, evolvers, drivers, scalar field objects, vector field objects, and MIF support classes. The following Oxs_Ext classes are currently available:


Atlases

Geometric volumes of spaces are specified in Oxs via atlases, which divide their domain into one or more disjoint subsets called regions. Each atlas definition also specifies a bounding box, i.e., an axes parallel rectangular parallelepiped that contains all the regions. The most commonly used atlases are the simple Oxs_BoxAtlas and the compound Oxs_MultiAltas.
Oxs_BoxAtlas:
An axes parallel rectangular parallelepiped, containing a single region that is coterminous with the atlas itself. The specify block has the form
Specify Oxs_BoxAtlas:atlasname {
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
name regionname
}

where xmin, xmax, ... are coordinates in meters, specifying the extents of the volume being defined. The regionname label specifies the name assigned to the region contained in the atlas. The name entry is optional; if not specified then the region name is taken from the object instance name, i.e., atlasname.

Oxs_ImageAtlas:
This class is designed to allow an image file to be used to define regions in terms of colors in the image. It is intended for use in conjunction with the Oxs_AtlasScalarField and Oxs_AtlasVectorField classes in circumstances where a small number of distinct species (materials) are being modeled. This is a generalization of the mask file functionality of the 2D solver (Sec. 17.2.3).

For situations requiring continuous variation in material parameters, the script field classes should be used in conjunction with the ReadFile MIF extension command. See the ColorField sample proc in the ReadFile documentation for an example of this technique.

The Oxs_ImageAtlas Specify block has the following form:

Specify Oxs_ImageAtlas:name {
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
viewplane view
image pic
colormap {
color-1 region_name
color-2 region_name
...
color-n region_name
}
matcherror max_color_distance
}

The xrange, yrange, zrange entries specify the extent of the atlas, in meters. The viewplane view value should be one of the 3 two-letter codes xy, zx or yz, which specify the mapping of the horizontal and vertical axes of the image respectively to axes in the simulation. The image is scaled as necessary along each dimension to match the atlas extents along the corresponding axes. The image is overlaid through the entire depth of the perpendicular dimension, i.e., along the axis absent from the viewplane specification. The Oxs_ImageAtlas class can be used inside a Oxs_MultiAtlas object to specify regions in a multilayer structure.

The image entry specifies the name of the image file to use. If the file path is relative, then it will be taken with respect to the directory containing the MIF file. The image format may be any of those recognized by any2ppm. The file will be read directly by Oxs if it is in the P3 or P6 PPM formats, otherwise any2ppm will be automatically launched to perform the conversion.

The colormap value is an even length list of color + region name pairs. The colors may be specified in any of several ways. The most explicit is to use one of the Tk numeric formats, #rgb, #rrggbb, #rrrgggbbb or #rrrrggggbbbb, where each r, g, and b is one hex digit (i.e., 0-9 or A-F) representing the red, green and blue components of the color, respectively. For example, #F00 is bright (full-scale) red, #800 would be a darker red, while #FF0 and #FFFF00 would both be bright yellow. Refer to the Tk_GetColor documentation for details. For shades of gray the special notation grayD or greyD is available, where D is a decimal value between 0 and 100, e.g., grey0 is black and grey100 is white. Alternatively, one may use any of the symbolic names defined in the oommf/config/colors.def file, such as red, white and skyblue. When comparing symbolic names, spaces and capitalization are ignored. The list of symbolic names can be extended by adding additional files to the Color filename option in the options.tcl customization file. Finally, one color in the colormap list may optionally be the special keyword ``default,'' which essentially represents all colors not in the colormap list.

Each of the specified colors should be distinct, but the region names are allowed to be repeated as desired. The region names may be chosen arbitrarily, except the special keyword ``universe'' is reserved for points not in any of the regions. This includes all points outside the atlas bounding box defined by the xrange, yrange, zrange entries, but may also include points inside that boundary.

Pixels in the image are assigned to regions by comparing the color of the pixel to the list of colors specified in colormap. If the pixel color is closer to a colormap color than max_color_distance, then the colors are considered matched. If a pixel color matches exactly one colormap color, then the pixel is assigned to the corresponding region. If a pixel color matches more than one colormap color, the pixel is assigned to the region corresponding to the closest match. If a pixel color doesn't match any of the colormap colors, then it is assigned to the default region, which is the region paired with the ``default'' keyword. If default does not explicitly appear in the colormap colors list, then universe is made the default region.

To calculate the distance between two colors, each color is first converted to a scaled triplet of floating point red, green, and blue values, (r, g, b), where each component lies in the interval [0, 1], with (0, 0, 0) representing black and (1, 1, 1) representing white. For example, (0, 0, 1) is bright blue. Given two colors in this representation, the distance is computed using the standard Euclidean norm with uniform weights, i.e., the distance between (r1, g1, b1) and (r2, g2, b2) and is

$\displaystyle \sqrt{{(r_1-r_2)^2 + (g_1-g_2)^2 + (b_1-b_2)^2}}$.

Since the difference in any one component is at most 1, the distance between any two colors is at most $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\sqrt{3}\\ \rule{1pt}{0pt}\end{array}$}$.

As explained above, two colors are considered to match if the distance between them is less than the specified matcherror value. If max_color_distance is sufficiently small, then it may easily happen that a pixel's color does not match any of the specified region colors, so the pixel would be assigned to the default region. On the other hand, if max_color_distance is larger than $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\sqrt{3}\\ \rule{1pt}{0pt}\end{array}$}$, then all colors will match, and no pixels will be assigned to the default region. If matcherror is not specified, then the default value for max_color_distance is 3, which means all colors match.

The following example should help clarify these matters. 

Specify Oxs_ImageAtlas:atlas {
    xrange { 0 400e-9 }
    yrange { 0 200e-9 }
    zrange { 0  20e-9 }
    image  mypic.gif
    viewplane "xy"
    colormap {
        blue   cobalt
        red    permalloy
        green  universe
        default cobalt
    }
    matcherror .1
}
Blue pixels get mapped to the ``cobalt'' region and red pixels to the ``permalloy'' region. Green pixels are mapped to the ``universe'' non-region, which means they are considered to be outside the atlas entirely. This is a fine point, but comes into play when atlases with overlapping bounding boxes are brought together inside an Oxs_MultiAtlas. To which region would an orange pixel be assigned? The scaled triplet representation for orange is (1, 0.647, 0), so the distance to blue is 1.191, the distance to red is 0.647, and the distance to green is 1.06. Thus the closest color is red, but 0.647 is outside the matcherror setting of 0.1, so orange doesn't match any of the colors and is hence assigned to the default region, which in this case is cobalt. On the other hand, if matcherror had been set to say 1, then orange and red would match and orange would be assigned to the permalloy region.

Pixels with colors that are equidistant to and match more than one color in the colormap will be assigned to one of the closest color regions. The user should not rely on any particular selection, that is to say, the explicit matching procedure in this case is not defined.

Oxs_MultiAtlas:
This atlas is built up as an ordered list of other atlases. The set of regions defined by the Oxs_MultiAtlas is the union of the regions of all the atlases contained therein. The sub-atlases need not be disjoint, however each point is assigned to the region in the first sub-atlas in the list that contains it, so the regions defined by the Oxs_MultiAtlas are effectively disjoint.

The Oxs_MultiAtlas specify block has the form

Specify Oxs_MultiAtlas:name {
atlas    atlas_1_spec
atlas    atlas_2_spec
...
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
}

Each atlas_spec may be either a reference to an atlas defined earlier and outside the current Specify block, or else an inline, embedded atlas definition. The bounding box xrange, yrange and zrange specifications are each optional. If not specified the corresponding range for the atlas bounding box is taken from the minimal bounding box containing all the sub-atlases.

If the atlases are not disjoint, then the regions as defined by an Oxs_MultiAtlas can be somewhat different from those of the individual component atlases. For example, suppose regionA is a rectangular region in atlasA with corner points (5,5,0) and (10,10,10), and regionB is a rectangular region in atlasB with corner points (0,0,0) and (10,10,10). When composed in the order atlasA, atlasB inside an Oxs_MultiAtlas, regionA reported by the Oxs_MultiAtlas will be the same as regionA reported by atlasA, but regionB as reported by the Oxs_MultiAtlas will be the ``L'' shaped volume of those points in atlasB's regionB not inside regionA. If the Oxs_MultiAtlas is constructed with atlasB first and atlasA second, then regionB as reported by the Oxs_MultiAtlas would agree with that reported by atlasB, but regionA would be empty.

NOTE: The attributes key label is not supported by this class.

Oxs_ScriptAtlas:
An atlas where the regions are defined via a Tcl script. The specify block has the form
Specify Oxs_ScriptAtlas:name {
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
regions { rname_1 rname_2 ... rname_n }
script_args { args_request }
script Tcl_script
}

Here xmin, xmax, ... are coordinates in meters, specifying the extents of the axes-parallel rectangular parallelepiped enclosing the total volume being identified. This volume is subdivided into n sub-regions, using the names as given in the regions list. The script is used to assign points to the various regions. Appended to the script are the arguments requested by script_args, in the manner explained in the User Defined Support Procedures section of the MIF 2.1 file format documentation. The value args_request should be a subset of {relpt rawpt minpt maxpt span }. If script_args is not specified, the default value relpt is used. When executed, the return value from the script should be an integer in the range 1 to n, indicating the user-defined region in which the point lies, or else 0 if the point is not in any of the n regions. Region index 0 is reserved for the implicit ``universe'' region, which is all-encompassing. The following example may help clarify the discussion: 

proc Octs { cellsize x y z xmin ymin zmin xmax ymax zmax } {
    global RegionArray
    set xindex [expr {int(floor(($x-$xmin)/$cellsize))}]
    set yindex [expr {int(floor(($y-$ymin)/$cellsize))}]
    set zindex [expr {int(floor(($z-$zmin)/$cellsize))}]
    set octant [expr {1+$xindex+2*$yindex+4*$zindex}]
    if {$octant<1 || $octant>8} {
       return 0
    }
    return $octant
}
Specify Oxs_ScriptAtlas:octant {
    xrange {-20e-9 20e-9}
    yrange {-20e-9 20e-9}
    zrange {-20e-9 20e-9}
    regions { VIII V VII VI IV I III II }
    script_args { rawpt minpt maxpt }
    script { Octs 20e-9 }
}
This atlas divides the rectangular volume between (- 20, - 20, - 20) and (20, 20, 20) (nm) into eight regions, corresponding to the standard octants, I through VIII. The Octs Tcl procedure returns a value between 1 and 8, with 1 corresponding to octant VIII and 8 to octant II. The canonical octant ordering starts with I as the + x, + y, + z space, proceeds counterclockwise in the + z half-space, and concludes in the - z half-space with V directly beneath I, VI beneath II, etc. The ordering computed algorithmically in Octs starts with 1 for the - x, - y, - z space, 2 for the + x, - y, - z space, 3 for the - x, + y, - z space, etc. The conversion between the two systems is accomplished by the ordering of the regions list.

Meshes

Meshes define the discretization impressed on the simulation. There should be exactly one mesh declared in a MIF 2.1 file. The only standard mesh available at present is
Specify Oxs_RectangularMesh:name {
cellsize { xstep ystep zstep }
atlas atlas_spec
}

This creates an axes parallel rectangular mesh across the entire space covered by atlas. The mesh sample rates along each axis are specified by cellsize (in meters). The mesh is cell-based, with the center of the first cell one half step in from the minimal extremal point (xmin,ymin,ymax) for atlas_spec. The name is commonly set to ``mesh'', in which case the mesh object may be referred to by other Oxs_Ext objects by the short name :mesh.

Energies

The following subsections describe the available energy terms. In order to be included in the simulation energy and field calculations, each energy term must be declared in its own, top-level Specify block, i.e., energy terms should not be declared inline inside other Oxs_Ext objects. There is no limitation on the number of energy terms that may be specified in the input MIF file. Many of these terms have spatially varying parameters that are initialized via field_object_spec entries in their Specify initialization block.

Outputs: For each magnetization configuration, two standard outputs are provided by all energy terms: the scalar output ``Energy,'' which is the total energy in joules contributed by this energy term, and the vector field output ``Field,'' which is the pointwise field in A/m. If the code was compiled with the macro NDEBUG not defined, then there will be an additional scalar output, ``Calc count,'' which counts the number of times the term has been calculated in the current simulation. This is intended for debugging purposes only; this number should agree with the ``Energy calc count'' value provided by the evolver.


Evolvers

Evolvers are responsible for updating the magnetization configuration from one step to the next. There are two types of evolvers, time evolvers, which track Landau-Lifshitz-Gilbert dynamics, and minimization evolvers, which locate local minima in the energy surface through direct minimization techniques. Evolvers are controlled by drivers, and must be matched with the appropriate driver type, i.e., time evolvers must be paired with time drivers, and minimization evolvers must be paired with minimization drivers. The drivers hand a magnetization configuration to the evolvers with a request to advance the configuration by one step (also called an iteration). It is the role of the drivers, not the evolvers, to determine when a simulation stage or run is complete. Specify blocks for evolvers contain parameters to control all aspects of individual stepwise evolution, but stopping criteria are communicated in the Specify block of the driver, not the evolver.

There is currently one representative of each type of evolver in the standard OOMMF distribution, time evolver Oxs_EulerEvolve and minimization evolver Oxs_CGEvolve.

Oxs_EulerEvolve:
Time evolver implementing a simple first order forward Euler method with step size control on the Landau-Lifshitz ODE [7,9]:

\begin{displaymath} \frac{d\textbf{M}}{dt} = -\vert\bar{\gamma}\vert\,\textbf{M... ...tbf{M}\times\left(\textbf{M}\times\textbf{H}_{\rm eff}\right), \end{displaymath} (2)
where M is the magnetization, Heff is the effective field, $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\bar{\gamma}\\ \rule{1pt}{0pt}\end{array}$}$ is the Landau-Lifshitz gyromagnetic ratio, and $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\alpha\\ \rule{1pt}{0pt}\end{array}$}$ is the damping constant. The Gilbert form

\begin{displaymath} \frac{d\textbf{M}}{dt} = -\vert\gamma\vert\,\textbf{M}\time... ...ha}{M_s} \left(\textbf{M}\times\frac{d\textbf{M}}{dt}\right), \end{displaymath} (3)
where $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\gamma\\ \rule{1pt}{0pt}\end{array}$}$ is the Gilbert gyromagnetic ratio, is mathematically equivalent to the Landau-Lifshitz form under the relation $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\gamma = (1+\alpha^2)\,\bar{\gamma}\\ \rule{1pt}{0pt}\end{array}$}$.

The Specify block has the form

Specify Oxs_EulerEvolve:name {
alpha $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\alpha\\ \rule{1pt}{0pt}\end{array}$}$
gamma_LL $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\bar{\gamma}\\ \rule{1pt}{0pt}\end{array}$}$
gamma_G $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\gamma\\ \rule{1pt}{0pt}\end{array}$}$
do_precess precess
min_timestep minimum_stepsize
max_timestep maximum_stepsize
fixed_spins {
atlas_spec
region1 region2 ...
}
start_dm $ \Delta$m
error_rate rate
absolute_step_error abs_error
relative_step_error rel_error
step_headroom headroom
}

All the entries have default values, but the ones most commonly adjusted are listed first.

The options alpha, gamma_LL and gamma_G are as in the Landau-Lifshitz-Gilbert ODE (2,3), where the units on $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\bar{\gamma}\\ \rule{1pt}{0pt}\end{array}$}$ and $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\gamma\\ \rule{1pt}{0pt}\end{array}$}$ are m/A . s and $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\alpha\\ \rule{1pt}{0pt}\end{array}$}$ is dimensionless. At most one of $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\bar{\gamma}\\ \rule{1pt}{0pt}\end{array}$}$ and $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\gamma\\ \rule{1pt}{0pt}\end{array}$}$ should be specified. If neither is specified, then the default is $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\gamma\\ \rule{1pt}{0pt}\end{array}$}$ = 2.211×105. (Because of the absolute value convention adopted on $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\bar{\gamma}\\ \rule{1pt}{0pt}\end{array}$}$ and $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\gamma\\ \rule{1pt}{0pt}\end{array}$}$ in (2,3), the sign given to the value of gamma_LL or gamma_G in the Specify block is irrelevant.) The default value for $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\alpha\\ \rule{1pt}{0pt}\end{array}$}$ is 0.5, which is large compared to experimental values, but allows simulations to converge to equilibria in a reasonable time. However, for accurate dynamic studies it is important to assign an appropriate value to $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\alpha\\ \rule{1pt}{0pt}\end{array}$}$.

The do_precess value should be either 1 or 0, and determines whether or not the precession term in the Landau-Lifshitz ODE (i.e., the first term on the righthand side in (2)) is used. If precess is 0, then precession is disabled and the simulation evolves towards equilibrium along a steepest descent path. The default value is 1.

The min_timestep and max_timestep parameters provide soft limits on the size of steps taken by the evolver. The minimum value may be overridden by the driver if a smaller step is needed to meet time based stopping criteria. The maximum value will be ignored if a step of that size would produce a magnetization state numerically indistinguishable from the preceding state. The units for min_timestep and max_timestep are seconds. Default values are 0 and 10-10 respectively.

The optional fixed_spins entry allows the magnetization in selected regions of the simulation to be frozen in its initial configuration. The value portion of the entry should be a list, with the first element of the list being either an inline atlas definition (grouped as a single item), or else the name of a previously defined atlas. The remainder of the list are names of regions in that atlas for which the magnetization is to be be fixed, i.e., M(t) = M(0) for all time t for all points in the named regions. Fields and energies are computed and reported normally across these regions. Although any atlas may be used, it is frequently convenient to set up an atlas with special regions defined expressly for this purpose.

The stepsize for the first candidate iteration in the problem run is selected so that the maximum change in the normalized (i.e., unit) magnetization m is the value specified by start_dm. The units are degrees, with default value 0.01.

The four remaining entries, error_rate, absolute_step_error, relative_step_error, and step_headroom, control fine points of stepsize selection, and are intended for advance use only. Given normalized magnetization mi(t) at time t and position i, and candidate magnetization mi(t + $ \Delta$t) at time t + $ \Delta$t, the error at position i is estimated to be

Errori = $\displaystyle \left\vert\vphantom{\dot{\textbf{m}}_i(t+\Delta t) - \dot{\textbf{m}}_i(t)}\right.$$\displaystyle \dot{{\textbf{m}}}_{i}^{}$(t + $\displaystyle \Delta$t) - $\displaystyle \dot{{\textbf{m}}}_{i}^{}$(t)$\displaystyle \left.\vphantom{\dot{\textbf{m}}_i(t+\Delta t) - \dot{\textbf{m}}_i(t)}\right\vert$$\displaystyle \Delta$t / 2,

where the derivative with respect to time, $ \dot{{\textbf{m}}}$, is computed using the Landau-Lifshitz ODE (2). First order methods essentially assume that $ \dot{{\textbf{m}}}$ is constant on the interval [t, t + $ \Delta$t]; the above formula uses the difference in $ \dot{{\textbf{m}}}$ at the endpoints of the interval to estimate (guess) how untrue that assumption is.

A candidate step is accepted if the maximum error across all positions i is smaller than absolute_step_error, error_rate  × $ \Delta$t, and relative_step_error  × |$ \dot{{\textbf{m}}}_{{\rm max}}^{}$|$ \Delta$t, where |$ \dot{{\textbf{m}}}_{{\rm max}}^{}$| is the maximum value of |$ \dot{{\textbf{m}}}_{i}^{}$| across all i at time t. If the step is rejected, then a smaller stepsize is computed that appears to pass the above tests, and a new candidate step is proposed using that smaller stepsize times step_headroom. Alternatively, if the step is accepted, then the error information is used to determine the stepsize for the next step, modified in the same manner by step_headroom.

The error calculated above is in terms of unit magnetizations, so the natural units are radians or radians/second. Inside the Specify block, however, the error_rate and absolute_step_error are specified in degrees/nanosecond and degrees, respectively; they are converted appropriately inside the code before use. The relative_step_error is a dimensionless quantity, representing a proportion between 0 and 1. The error check controlled by each of these three quantities may be disabled by setting the quantity value to -1. They are all optional, with default values of -1 for error_rate, 0.2 for absolute_step_error, and 0.2 for relative_step_error.

The headroom quantity should lie in the range (0, 1), and controls how conservative the code will be in stepsize selection. If headroom is too large, then much computation time will be lost computing candidate steps that fail the error control tests. If headroom is small, then most candidate steps will pass the error control tests, but computation time may be wasted calculating more steps than are necessary. The default value for headroom is 0.85.

In addition to the above error control tests, a candidate step will also be rejected if the total energy, after adjusting for effects due to any time varying external field, is found to increase. In this case the next candidate stepsize is set to one half the rejected stepsize.

The Oxs_EulerEvolve module provides five scalar outputs and three vector field outputs. The scalar outputs are

The vector field outputs are

Oxs_CGEvolve:
The minimization evolver is Oxs_CGEvolve, which is an in-development conjugate gradient minimizer with no preconditioning. The Specify block has the form
Specify Oxs_CGEvolve:name {
gradient_reset_count count
minimum_bracket_step minbrack
maximum_bracket_step maxbrack
line_minimum_relwidth relwidth
fixed_spins {
atlas_spec
region1 region2 ...
}
}

All entries have default values.

The evolution to an energy minimum precedes by a sequence of line minimizations. Each line represents a one dimensional affine subspace in the 3N dimensional space of possible magnetization configurations, where N is the number of spins in the simulation. Once a minimum has been found along a line, a new direction is chosen that is ideally orthogonal to all preceding directions, but related to the gradient of the energy taken with respect to the magnetization. In practice the line direction sequence cannot be extended indefinitely; the parameter gradient_reset_count controls the maximum number of line directions selected before resetting the process. The default value for count is 42. Because the first line in the sequence is selected along the gradient direction, setting count to 1 effectively turns the algorithm into a steepest descent minimization method.

Once a minimization direction has been selected, the first stage of the line minimization is to bracket the minimum energy on that line, i.e., given a start point on the line--the location of the minimum from the previous line minimization--find another point on the line such that the energy minimum lies between those two points. As one moves along the line, the spins in the simulation rotate, with one spin rotating faster than (or at least as fast as) all the others. If the start point was not the result of a successful line minimization from the previous stage, then the first bracket attempt step is sized so that the fastest moving spin rotates through the angle specified by minimum_bracket_step. In the more usual case that the start point is a minimum from the previous line minimization stage, the initial bracket attempt step size is set to the distance between the current start point and the start point of the previous line minimization stage.

The energy and gradient of the energy are examined at the candidate bracket point to test if an energy minimum lies in the interval. If not, the interval is extended, based on the size of the first bracket attempt interval and the derivatives of the energy at the interval endpoints. This process is continued until either a minimum is bracketed or the fastest moving spin rotates through the angle specified by maximum_bracket_step.

If the bracketing process is successful, then a one dimensional minimization is carried out in the interval, using both energy and energy derivative information. Each step in this process reduces the width of the bracketing interval. This process is continued until the width of the interval relative to the distance of the interval from the start point (i.e., the stop point from the previous line minimization process) is less than line_minimum_relwidth. The stop point, i.e., the effective minimum, is then taken to be the endpoint of the final interval with smallest energy. If the bracketing process is unsuccessful, i.e., the check for bracketed energy minimum failed at the maximum bracket interval size allowed by maximum_bracket_step, then the maximum bracket endpoint is accepted as the next point in the minimization iteration.

Once the line minimum stop point has been selected, the next iteration begins with selection of a new line direction, as described above, except in the case where the stop point was not obtained as an actual minimum, but rather by virtue of satisfying the maximum_bracket_step constraint. In that case the orthogonal line sequence is reset, in the same manner as when the gradient_reset_count switch is triggered, and the next line direction is taken directly from the energy gradient.

There are several factors to bear in mind when selecting values for the parameters minimum_bracket_step, maximum_bracket_step, and line_minimum_relwidth. If minimum_bracket_step is too small, then it may take a great many steps to obtain an interval large enough to bracket the minimum. If minimum_bracket_step is too large, then the bracket interval will be unnecessarily generous, and many steps may be required to locate the minimum inside the bracketing interval. However, this value only comes into play when resetting the line minimization direction sequence, so the setting is seldom critical. It is specified in degrees, with default value 0.05.

If maximum_bracket_step is too small, then the minima will be mostly not bracketed, and the minimization will degenerate into a type of steepest descent method. On the other hand, if maximum_bracket_step is too large, then the line minimizations may draw the magnetization far away from a local energy minimum (i.e., one on the full 3N dimensional magnetization space), eventually ending up in a different, more distant minimum. The value for maximum_bracket_step is specified in degrees, with default value 10.

The line_minimum_relwidth value determines the precision of the individual line minimizations, not the total minimization procedure, which is governed by the stopping criteria specified in the driver's Specify block. However, the line_minimum_relwidth value is important because the precision of the line minimizations affects the the line direction sequence orthogonality. If line_minimum_relwidth is too coarse, then the selected line directions will quickly drift away from mutual orthogonality. Conversely, selecting line_minimum_relwidth too fine will produce additional line minimization steps that do nothing to improve convergence towards the energy minimum in the full 3N dimensional magnetization space. The default value for line_minimum_relwidth is 1e-6.

Referring back to the Oxs_CGEvolve Specify block, the fixed_spins entry performs the same function as for the Oxs_EulerEvolve class.

The Oxs_CGEvolve module provides seven scalar outputs and two vector field outputs. The scalar outputs are

The vector field outputs are


Drivers

While evolvers are responsible for moving the simulation forward in individual steps, drivers coordinate the action of the evolver on the simulation as a whole, by grouping steps into tasks, stages and runs.

Tasks are small groups of steps that can be completed without adversely affecting user interface responsiveness. Stages are larger units specified by the MIF problem description; in particular, problem parameters are not expected to change in a discontinuous manner inside a stage. The run is the complete sequence of stages, from problem start to finish. The driver detects when stages and runs are finished, using criteria specified in the MIF problem description, and can enforce constraints, such as making sure stage boundaries respect time stopping criteria.

There are two drivers in Oxs, Oxs_TimeDriver for controlling time evolvers such as Oxs_EulerEvolve, and Oxs_MinDriver for controlling minimization evolvers like Oxs_CGEvolve.

Oxs_TimeDriver:
The Oxs time driver is Oxs_TimeDriver. The specify block has the form
Specify Oxs_TimeDriver:name {
evolver evolver_spec
mesh mesh_spec
Ms scalar_field_spec
m0 vector_field_spec
stopping_dm_dt torque_criteria
stopping_time time_criteria
stage_iteration_limit stage_iteration_count
total_iteration_limit total_iteration_count
stage_count number_of_stages
stage_count_check test
basename base_file_name
scalar_output_format format
vector_field_output_format { style precision }
}

The first four parameters, evolver, mesh, Ms and m0 provide references to a time evolver, a mesh, a scalar field and a vector field, respectively. Here Ms is the pointwise saturation magnetization in A/m, and m0 is the initial configuration for the magnetization unit spins, i.e., |m| = 1 at each point. These four parameters are required.

The next group of 3 parameters control stage stopping criteria. The stopping_dm_dt value, in degrees per nanosecond, specifies that a stage should be considered complete when the maximum | dm/dt| across all spins drops below this value. Similarly, the stopping_time value specifies the maximum ``Simulation time,'' i.e., the Landau-Lifshitz-Gilbert ODE (2,3) time, allowed per stage. For example, if time_criteria is 1e-9, then no stage will evolve for more than 1 ns. If there were a total of 5 stages in the simulation, then the total simulation time would be not more than 5 ns. The third way to terminate a stage is with a stage_iteration_limit. This is a limit on the number of successful evolver steps allowed per stage. A stage is considered complete when any one of these three criteria are met. Each of the criteria may be either a single value, which is applied to every stage, or else a grouped list of values. If the simulation has more stages than a criteria list has entries, then the last criteria value is applied to all additional stages. These stopping criteria all provide a default value of 0, meaning no constraint, but usually at least one is specified since otherwise there is no automatic stage termination control. For quasi-static simulations, a stopping_dm_dt value in the range of 1.0 to 0.01 is reasonable; the numerical precision of the energy calculations usually makes in not possible to obtain | dm/dt| much below 0.001 degree per nanosecond.

The total_iteration_limit, stage_count and stage_count_check parameters involve simulation run completion conditions. The default value for the first is 0, interpreted as no limit, but one may limit the total number of steps performed in a simulation by specifying a positive integer value here. The more usual run completion condition is based on the stage count. If a positive integer value is specified for stage_count, then the run will be considered complete when the stage count reaches that value. If stage_count is not specified, or is given the value 0, then the effective number_of_stages value is computed by examining the length of the stopping criteria lists, and also any other Oxs_Ext object that has stage length expectations, such as Oxs_UZeeman. The longest of these is taken to be the stage limit value. Typically these lengths, along with stage_count if specified, will all be the same, and any differences indicate an error in the MIF file. Oxs will automatically test this condition, provided stage_count_check is set to 1, which is the default value. Stage length requests of 0 or 1 are ignored in this test, since those lengths are commonly used to represent sequences of arbitrary length. At times a short sequence is intentionally specified that is meant to be implicitly extended to match the full simulation stage length. In this case, the stage count check can be disabled by setting test to 0.

The value associated with basename is used as a prefix for output filename construction by some of the data output routines. It may represent either an absolute path (i.e., one with a leading ``/''), or else a relative path taken with respect to the directory containing the MIF file. This an optional field with default value oxs. The value assigned to scalar_output_format should be a C-style printf string specifying the output format for DataTable output (this includes output sent to mmDataTable, mmGraph, and mmArchive). This is optional, with default value ``%.17g''. The value associated with vector_field_output_format should be a two element list, specifying the style and precision for 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 the individual field 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 vector_field_output_format is ``binary 8''.

Oxs_TimeDriver provides seven scalar outputs and two vector field outputs. The scalar outputs are

The vector field outputs are

Oxs_MinDriver:
The Oxs driver for controlling minimization evolvers is Oxs_MinDriver. The specify block has the form
Specify Oxs_TimeDriver:name {
evolver evolver_spec
mesh mesh_spec
Ms scalar_field_spec
m0 vector_field_spec
stopping_mxHxm torque_criteria
stage_iteration_limit stage_iteration_count
total_iteration_limit total_iteration_count
stage_count number_of_stages
stage_count_check test
basename base_file_name
scalar_output_format format
vector_field_output_format { style precision }
}

These parameters are the same as those described for the Oxs_TimeDriver, except that stopping_mxHxm replaces stopping_dm_dt, and there is no analogue to stopping_time. The value for stopping_mxHxm is in A/m, and may be a grouped list . This is a required value. Choice depends on the particulars of the simulation, but typical values are in the range 10 to 0.1. Limits in the numerical precision of the energy calculations usually makes it not possible to obtain |m×H×m| below about 0.01 A/m.

Oxs_MinDriver provides six scalar outputs and two vector field outputs. The scalar outputs are

The vector field outputs are


Field Objects

Field objects return values (either scalar or vector) as a function of position. These are frequently used as embedded objects inside Specify blocks of other Oxs_Ext objects to initialize spatially varying quantities, such as material parameters or initial magnetization spin configurations. Units on the returned values will be dependent upon the context in which they are used.

Scalar field objects are documented first. Vector field objects are considered farther below.

Oxs_UniformScalarField:
Returns the same constant value regardless of the import position. The Specify block takes one parameter, value, which is the returned constant value.

Oxs_AtlasScalarField:
Defines values that are constant across individual regions of an Oxs_Atlas. The Specify block looks like
Specify Oxs_AtlasScalarField {
atlas atlas_spec
default_value value
values {
region1_label value1
region2_label value2
...
}
}

The specified atlas is used to map cell locations to regions, and the corresponding value from the values sub-block is assigned to that cell. The default_value entry is optional; if specified, and if a cell's region is not included in the values sub-block, then the default_value value is used. If default_value is not specified, then missing regions will raise an error.

Oxs_LinearScalarField:
Returns a value that varies linearly with position. The Specify block has the form:
Specify Oxs_LinearScalarField {
vector { vx  vy  vz }
norm value
}

If optional value norm is specified, then the given vector is first scaled to the requested size. For any given point (x, y, z), the scalar function value returned by this object will be xvx + yvy + zvz.

Oxs_RandomScalarField:
Defines a scalar field that varies spatially in a random fashion. The value at each position is drawn uniformly from the range declared by the two Specify block required parameters, range_min and range_max.

Oxs_ScriptScalarField:
Produces a field dependent on a Tcl script. The Specify block has the form
Specify Oxs_ScriptScalarField:name {
script Tcl_script
script_args { args_request }
atlas atlas_spec
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
}

For each position in the mesh, the specified script is called with the arguments requested by script_args appended to the command, as explained in the User Defined Support Procedures section of the MIF 2.1 file format documentation. The value for script_args should be a subset of {relpt rawpt minpt maxpt span }. If script_args is not specified, the default value relpt is used.

A bounding box must also be specified, by either referencing an atlas specification, or by explicitly stating the range via the three entries xrange, yrange, zrange (in meters). The following example uses the explicit range method. See the Oxs_ScriptVectorField documentation below for an example using an atlas specification. 

proc Ellipsoid { xrel yrel zrel } {
    set xrad [expr {$xrel - 0.5}]
    set yrad [expr {$yrel - 0.5}]
    set zrad [expr {$zrel - 0.5}]
    set test [expr {$xrad*$xrad+$yrad*$yrad+$zrad*$zrad}]
    if {$test>0.25} {return 0}
    return 8.6e5
}

Specify Oxs_ScriptScalarField {
    script Ellipsoid
    xrange { 0   1e-6 }
    yrange { 0 250e-9 }
    zrange { 0  50e-9 }

}
This Oxs_ScriptScalarField object returns 8.6e5 if the import (x,y,z) lies within the ellipsoid inscribed inside the axes parallel parallelepiped defined by (xmin=0, ymin=0, zmin=0) and (xmax=1e-6, ymax=250e-9, zmax=50e-9), and 0 otherwise. See also the discussion of the ReadFile MIF extension command for an example using an imported image file for similar purposes.

The available vector field objects are:

Oxs_UniformVectorField:
Returns the same constant value regardless of the import position. The Specify block takes one required parameter, vector, which is a 3-element list of the vector to return, and one optional parameter, norm, which if specified adjusts the size of export vector to the specified magnitude. For example,
Specify Oxs_UniformVectorField {
norm 1
vector { 1 1 1 }
}

This object returns the unit vector (a, a, a), where a=1/sqrt(3), regardless of the import position.

Oxs_AtlasVectorField:
Defines vector values that are constant across individual regions of an Oxs_Atlas. The Specify block has the form
Specify Oxs_AtlasVectorField {
atlas atlas_spec
default_value { vx  vy  vz }
values {
region1_label { v1x  v1y  v1z }
region2_label { v2x  v2y  v2z }
...
}
}

Interpretation is analogous to the Oxs_AtlasScalarField specify block, except here the output values are 3 dimensional vectors rather than scalars.

Oxs_ScriptVectorField:
Conceptually similar to the Oxs_ScriptScalarField scalar field object, except that the script should return a vector (as a 3 element list) rather than a scalar. In addition to the script, script_args, and xrange/yrange/zrange or atlas parameters, the Specify string for Oxs_ScriptVectorField also accepts an optional parameter norm. If specified, the return values from the script are size adjusted to the specified magnitude. The following example produces a vortex-like unit vector field, with an interior core region pointing parallel to the z-axis. Here the scaling region is specified using an atlas reference to an object named ``:atlas'', which is presumed to be defined earlier in the MIF file. See the Oxs_ScriptScalarField sample Specify block for an example using the explicit range option. 
proc Vortex { xrel yrel zrel } {
    set xrad [expr {$xrel-0.5}]
    set yrad [expr {$yrel-0.5}]
    set normsq [expr {$xrad*$xrad+$yrad*$yrad}]
    if {$normsq <= 0.025} {return "0 0 1"}
    return [list [expr {-1*$yrad}] $xrad 0]
}

Specify Oxs_ScriptVectorField {
    script Vortex
    norm  1
    atlas :atlas
}
See also the discussion of the ReadFile MIF extension command for an example using an imported image file for similar purposes.

Oxs_FileVectorField:
Provides a file-specified vector field. Required values in the Specify block are the name of the input vector field file and the desired scaling parameters. The filename is specified via the file entry, which names a file containing a vector field in one of the formats recognized by avf2ovf. The file will be scaled and sub-sampled as necessary to fit the scaling region. The scaling region is specified in the same manner as for the Oxs_ScriptScalarField and Oxs_ScriptVectorField classes, by either an explicit range specification or an atlas reference.

The magnitude of the field can be modified by the optional norm and multiplier options. If the norm parameter is given, then each vector in the field will be renormalized to the specified magnitude. If the multiplier parameter is given, then each vector in the field will be multiplied by the given scalar value. If the multiplier value is negative, the field direction will be reversed. If both norm and multiplier are given, then the field vectors are renormalized before being scaled by the multiplier value.

Oxs_RandomVectorField:
Defines a vector field that varies spatially in a random fashion. The Specify block takes two required parameters, min_norm and max_norm. The vectors produced will have magnitude between these two specified values. If min_norm = max_norm, then the samples are uniformly distributed on the sphere of radius = min_norm. Otherwise, first a uniformly distributed sample is chosen on the unit sphere, and then the magnitude is adjusted to a size drawn uniformly from the interval [min_norm,max_norm].

Oxs_PlaneRandomVectorField:
Similar to Oxs_RandomVectorField, except that all samples are drawn from a plane rather than 3-space. In addition to min_norm and max_norm, the Specify block for Oxs_PlaneRandomVectorField also requires the parameter plane_normal. This parameter takes as its value a list of 3 elements, representing a vector orthogonal to the plane from which the random vectors are to be drawn.

MIF Support Classes

Oxs_LabelValue:
A convenience object that holds label + value pairs. Oxs_LabelValue objects may be referenced via the standard attributes field in other Specify blocks, as in this example: 
Specify Oxs_LabelValue:probdata {
  alpha 0.5
  start_dm 0.01
}
Specify Oxs_EulerEvolve {
  attributes :probdata
}
The Specify block string for Oxs_LabelValue objects is an arbitrary Tcl list with an even number of elements. The first element in each pair is interpreted as a label, the second as the value. The attribute option causes this list to be dropped verbatim into the surrounding object. This technique is most useful if the label + value pairs in the Oxs_LabelValue object are used in multiple Specify blocks, either inside the same MIF file, or across several MIF files into which the Oxs_LabelValue block is imported using the ReadFile MIF extension command.

Refer to the MIF 2.1 documentation for details on the base format specification.

OOMMF Home next up previous Contents index

OOMMF Documentation Team
October 30, 2002