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.0 file. The reader will find the sample file presented in that section to be a helpful adjuct 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. Standard Oxs_Ext objects can be identified by the Oxs_ prefix in their names. Additional Oxs_Ext objects may be available on your system. Check local documentation for details.

For presentation purposes, the Oxs_Ext classes are organized into 6 categories: regions, meshes, energies, evolvers, drivers, and field initializers.

Regions
Regions describe geometric volumes of space. OXS recognizes ``sections,'' which define single regions of space, and ``atlases,'' which are conceptually collections of sections. At present only one type of each is supported:

Oxs_RectangularSection:

An axes parallel rectangular parallelepiped. The specify block has the form

Specify Oxs_RectangularSection:name {

xrange { xmin xmax }

yrange { ymin ymax }

zrange { zmin zmax }

}

where xmin, xmax, ... are coordinates in meters.

Oxs_SectionAtlas:

An ordered list of sections. The specify block has the form

Specify Oxs_SectionAtlas:name {

section-1-name { section-type {

section-initialize-block

} }

section-2-name { section-type {

section-initialize-block

} }

...

final-section-name { section-type {

section-initialize-block

} }

}

At present there is only one section type, so all the section-type fields above will be Oxs_RectangularSection.

Given a point, Oxs_SectionAtlas returns the name of the first section in its list that contains that point. The final section in the list must be sized so as to contain all the preceding sections. For this reason, it is common to set final-section-name to world, though this is not required.

Meshes
Meshes define the discretization impressed on the simulation. There should be exactly one mesh declared in a MIF 2.0 file. The only standard mesh available at present is

Specify Oxs_RectangularMesh:name {

cellsize { xstep ystep zstep }

atlas { atlas_reference }

}

This creates an axes parallel rectangular mesh across the entire space covered by atlas_reference (i.e., the final or ``world'' section of the atlas). The mesh sample rates along each axis are specified by xstep, ystep, and zstep. The mesh is cell-based, with the center of the first cell one half step in from the minimal extremal point (xmin,ymin,ymax) specified by atlas_reference. The name is commonly set to ``mesh'', so the mesh object can be referred to by other Oxs_Ext objects by the short name ``:mesh''.

Energies
The following energy terms are available. There is no limitation on the number of each specified in the input MIF file. Many of these terms have spatially varying parameters that are initialized via Field Initializer objects embedded in their Specify initialization block.

Oxs_UniaxialAnisotropy:

Uniaxial magneto-crystalline anisotropy. Specify block takes 2 parameters, crystalline anisotropy constant K1 (in J/m^3) and anisotropy direction axis. The axis direction is an easy axis if K1>0, or is the normal to the easy plane if K1 < 0. Both may be varied cellwise across the mesh. The first is initialized with an embedded Scalar Field Initializer, and the second with an embedded Vector Field Initializer. The axis directions should be unit vectors. The energy computed by this term is non-negative in all cases.

Oxs_CubicAnisotropy:

Cubic magneto-crystalline anisotropy. Specify block takes 3 parameters, crystalline anisotropy constant K1 (in J/m^3) and anisotropy directions axis1 and axis2. The axis directions are easy axes if K1>0, or hard axes if K1<0. All may be varied cellwise across the mesh. K1 is initialized with an embedded Scalar Field Initializer, and the axis directions embedded Vector Field Initializers. The axis directions should be unit vectors. The second axis, axis2, will be adjusted if necessary to be orthogonal to axis1. For each cell, if K1>0 then the computed energy will be non-negative, else if K1<0 then the computed energy will be non-positive.

Oxs_Exchange6Ngbr:

Standard 6-neighbor exchange energy. The exchange energy density contribution from cell i is given by

E_i = $$\sum_{j\in N_i}^{}$$A_ij$${\frac{\textbf{m}_i\cdot\left(\textbf{m}_i - \textbf{m}_j\right)}{\Delta_{ij}^2}}$$

where N_i is the set consisting of the 6 cells nearest to cell i, A_ij is the exchange coefficient between cells i and j in J/m, and $\Delta_{ij}^{}$ is the discretization step size from cell i to cell j (in meters).

The Specify block for this term has the form

Specify Oxs_Exchange6Ngbr:name {

default_A value

atlas atlas_reference

A {

{ region-1 region-1 A₁₁ }

{ region-1 region-2 A₁₂ }

...

{ region-m region-n A_mn }

}

}

The A block specifies A_ij values on a region by region basis, where the regions are those declared by atlas_reference. This allows for specification of A both inside a given region (e.g., A_ii) and along interfaces between regions (e.g., A_ij). By symmetry, if A_ij is specified, then the same value is automatically assigned to A_ji as well. The default_A value is applied to any otherwise unassigned A_ij.

Oxs_UniformExchange:

Similar to Oxs_Exchange6Ngbr, except the exchange constant A is uniform across all space. The Specify block is very simple, consisting of the label A and the desired exchange coefficient value in J/m. Since A is not spatially varying, it is initialized with a simple constant, as opposed to an embedded Field Initializer object.

Oxs_UZeeman:

Uniform (homogeneous) applied field energy. The specify block for this term takes an optional Hscale entry, and a required field range list Hrange. The field range list should be a compound list, with each sublist consisting of 7 elements: the first 3 denote the start field for the range, the next 3 denote the end field for the range, and the last element specifies the number of (linear) steps through the range. If the step count is 0, then the range consists of the start field only. If the step count is bigger than 0, then the start field is skipped over if and only if it is the same field that ended the previous range (if any).

The fields specified in the range entry are nominally in A/m, but these values are multiplied by Hscale, which may be used to effectively change the units. For example,

Specify Oxs_UZeeman {

Hscale 795.77472

Hrange {

{ 0 0 0 10 0 0 2 }

{ 10 0 0 0 0 0 1 }

}

}

The applied field steps between 0 mT, 5 mT, 10 mT and back to 0 mT. (Note that 795.77472=0.001/$\mu_{0}^{}$.)

Oxs_FixedZeeman:

Non-uniform, non-time varying applied field. This can be used to simulate a biasing field. The specify block holds one parameter, which defines the field:

Specify Oxs_FixedZeeman:name {

field { vector_field_initializer }

}

Oxs_Demag:

Standard demagnetization energy term, which is built on the assumption that the magnetization is constant in each cell, and computes the average demagnetization field through the cell using formulae from [2,12] and convolution via the Fast Fourier Transform. The Specify initialization string should be an empty string, typically denoted by { }.

Oxs_SimpleDemag:

This is the same as the Oxs_Demag object, except that the implementation does not use any of the of the symmetries inherent in the demagnetization kernel, or special properties of the Fourier Transform when applied to a real (non-complex) function. As a result, the source code for this implementation is considerably simpler than for Oxs_Demag, but the run time performance and memory usage are poorer. Oxs_SimpleDemag is included for validation checks, and as a base for user-defined demagnetization implementations. The Specify initialization string for Oxs_SimpleDemag is the same as for Oxs_Demag.

Evolvers
Evolvers are responsible for updating the magnetization configuration from one step to the next. There is currently one evolver in the standard distribution, Oxs_EulerEvolve. This implements a simple first order forward Euler method with step size control to the Landau-Lifshitz ODE [7,9]:

$$\frac{d\textbf{M}}{dt} = -\gamma\,\textbf{M}\times\textbf{H... ...tbf{M}\times\left(\textbf{M}\times\textbf{H}_{\rm eff}\right).$$ (2)

The Specify block takes one required parameter, alpha, which is the Landau-Lifshitz damping parameter above. There are also three optional parameters, gamma, which is the gyromagnetic ratio in m/(A.s), start_dm, which is the size of the maximal initial step in reduced magnetization units, i.e., radians, and do_precess, which is 1 or 0 depending on whether precession is enabled or not (respectively). The default value for gamma is 2.21e5, for start_dm is 0.01, and for do_precess is 1.

Drivers
The driver is responsible for coordinating the action of the evolver on the simulation as a whole. The only driver at present is Oxs_StandardDriver. The specify block has the form

Specify Oxs_StandardDriver:name {

evolver evolver_reference

mesh mesh_reference

min_timestep minimum_time_step

max_timestep maximum_time_step

stopping_dm_dt stopping_criterion

number_of_stages stage_count

stage_iteration_limit stage_iteration_count

total_iteration_limit total_iteration_count

Ms { scalar_field_initializer }

m0 { vector_field_initializer }

}

evolver should be a reference to a previously declared evolver, and mesh should be a reference to a previously declared mesh. min_timestep and max_timestep are the minimum and maximum time step size allowed during Landau-Lifshitz ODE evolution, in seconds. A stage is considered complete when |$\dot{\textbf{M}}$/M_s| drops below stopping_dm_dt (in degrees/nanosecond), or when the number of steps taken on the current problem reaches stage_iteration_limit. stage_iteration_limit is an optional integer parameter, with default value of 0, which is interpreted to mean no iteration limit. Similarly, a simulation as a whole is considered complete when either the stage count reaches number_of_stages or the total number of steps taken reaches total_iteration_limit. Both of these are optional parameters with default value 0, meaning no limit. Ms specifies the saturation magnetization distribution, in A/m. m0 is the initial spin configuration. These should be unit vectors, specified using an embedded vector field initializer object.

Field Initializers
Field initializers are objects that produce output (either scalar or vector) as a function of position. These are typically 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 initializer objects are documented first. Vector field initializers are considered farther below.

Oxs_UniformScalarFieldInit:

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

Oxs_AtlasScalarFieldInit:

Defines values that are constant across individual regions of a previously defined Oxs_Atlas. The Specify block looks like

Specify Oxs_AtlasScalarFieldInit {

atlas atlas_reference

default_value value

values {

{ region1_reference value1 }

{ region2_reference value2 }

...

}

}

The specified atlas is used to map cell locations to regions, and the corresponding value from the values subblock is assigned to that cell. If a cell's region is not included in the values subblock, then the default_value is used.

Oxs_ScriptScalarFieldInit:

Returns a value dependent on a Tcl script, which should be defined elsewhere in the MIF file. The one Specify initialization string parameter is script, which is the name of the associated Tcl procedure. That procedure should be coded to take 9 arguments, the 3 coordinates of the current query position, followed by the 3 coordinates of bounding box minimum corner point, and lastly the 3 coordinates of bounding box maximum corner point. For example,

proc Ellipsoid { x y z xmin ymin zmin xmax ymax zmax } {
    set xcenter [expr ($xmax-$xmin)/2.]
    set ycenter [expr ($ymax-$ymin)/2.]
    set zcenter [expr ($zmax-$zmin)/2.]
    set xrad [expr $x/$xcenter -1 ]
    set yrad [expr $y/$ycenter -1 ]
    set zrad [expr $z/$zcenter -1 ]
    set test [expr $xrad*$xrad+$yrad*$yrad+$zrad*$zrad]
    if {$test>1.0} {return 0}
    return 8.6e5
}

Specify Oxs_ScriptScalarFieldInit {
    script Ellipsoid
}

This Oxs_ScriptScalarFieldInit returns 8.6e5 if the import (x,y,z) lies inside the ellipsoid inscribed inside the axes parallel parallelepiped defined by (xmin,ymin,zmin) and (xmax,ymax,zmax), and 0 otherwise.

The available vector field initializers are:

Oxs_UniformVectorFieldInit:

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 be of the specified magnitude. For example,

Specify Oxs_UniformVectorFieldInit {

norm 1

vector { 1 1 1 }

}

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

Oxs_AtlasVectorFieldInit:

Defines vector values that are constant across individual regions of a previously defined Oxs_Atlas. The Specify block looks like

Specify Oxs_AtlasVectorFieldInit {

atlas atlas_reference

default_value { v_x v_y v_z }

values {

{ region1_reference v1_x v1_y v1_z }

{ region2_reference v2_x v2_y v2_z }

...

}

}

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

Oxs_ScriptVectorFieldInit:

This is conceptually similar to the scalar field initializer object, Oxs_ScriptScalarFieldInit, except that the script should return a vector (as a 3 element list) rather than a scalar. In addition to the script parameter, the Specify string for Oxs_ScriptVectorFieldInit also accepts an optional parameter norm. If specified, then 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.

proc Vortex { x y z xmin ymin zmin xmax ymax zmax } {
    set xcenter [expr ($xmax-$xmin)/2.]
    set ycenter [expr ($ymax-$ymin)/2.]
    set xrad [expr $x-$xcenter]
    set yrad [expr $y-$ycenter]
    set normsq [expr $xrad*$xrad+$yrad*$yrad]
    if {$normsq <= $xcenter*$ycenter*0.05} {return "0 0 1"}
    return [list [expr -1*$yrad] $xrad 0]
}

Specify Oxs_ScriptVectorFieldInit {
    script Vortex
    norm  1
}

Oxs_FileVectorFieldInit:

Initializes a vector field from a file. The Specify block takes one required parameter file, and one optional parameter norm. The file should contain a vector field in one of the formats recognized by avf2ovf. The file will be scaled and sub-sampled as necessary to match the current mesh. If the norm parameter is given, then each vector will be renormalized to the specified magnitude.

Oxs_RandomVectorFieldInit:

Initializes a vector field which 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_PlaneRandomVectorFieldInit:

Similar to Oxs_RandomVectorFieldInit, 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_PlaneRandomVectorFieldInit 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.

OOMMF Documentation Team
January 22, 2001