7.3.6 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. This class is frequently embedded inline to specify homogeneous material parameters. For example, inside a driver Specify block we may have

Specify Oxs_TimeDriver {
    ...
    Ms { Oxs_UniformScalarField {
       value 8e5
    }}
    ...
}

As discussed in the MIF 2 documentation (Sec. 17.3.3, page 17.3.3), when embedding Oxs_UniformScalarField or Oxs_UniformVectorField objects, a notational shorthand is allowed that lists only the value. The previous example is exactly equivalent to

Specify Oxs_TimeDriver {
    ...
    Ms 8e5
    ...
}

where an implicit Oxs_UniformScalarField object is created with value set to 8e5.

Examples: sample.mif, cgtest.mif.

Oxs_AtlasScalarField:

Declares values that are defined across individual regions of an Oxs_Atlas. The Specify block looks like

Specify Oxs_AtlasScalarField:value {
      atlas atlas_spec
      multiplier mult
      default_value scalar_field_spec
      values {
             region1_label scalar_field_spec1
             region2_label scalar_field_spec2
            …
      }
}

The specified atlas is used to map cell locations to regions; the value at the cell location of the scalar field from the corresponding 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 scalar field is used. If default_value is not specified, then missing regions will raise an error.

The scalar field entries may specify any of the scalar field types described in this (Field Objects) section. As usual, one may provide a single numeric value in any of the scalar_field_spec positions; this will be interpreted as requesting a uniform (spatially homogeneous) field with the indicated value.

If the optional multiplier value is provided, then each field value is scaled (multiplied) by the value mult.

The vector field analogue to this class is Oxs_AtlasVectorField, which is described below in the vector fields portion of this section.

Examples: diskarray.mif, ellipsoid.mif, grill.mif, spinvalve.mif, tclshapes.mif.

Oxs_LinearScalarField:

Returns a value that varies linearly with position. The Specify block has the form:

Specify Oxs_LinearScalarField:name {
      norm value
      vector { $v_x$ $v_y$ $v_z$ }
      offset off
}

If optional value norm is specified, then the given vector is first scaled to the requested size. The offset entry is optional, with default value 0. For any given point $(x,y,z)$, the scalar value returned by this object will be $x{v}_x+y{v}_y+z{v}_z+off$.

Example: spinvalve-af.mif.

Oxs_RandomScalarField:

Defines a scalar field that varies spatially in a random fashion. The Specify block has the form:

Specify Oxs_RandomScalarField:name {
      range_min minvalue
      range_max maxvalue
      cache_grid mesh_spec
}

The value at each position is drawn uniformly from the range declared by the two required parameters, range_min and range_max. There is also an optional parameter, cache_grid, which takes a mesh specification that describes the grid used for spatial discretization. If cache_grid is not specified, then each call to Oxs_RandomScalarField generates a different field. If you want to use the same random scalar field in two places (as a base for setting, say anisotropy coefficients and saturation magnetization), then specify cache_grid with the appropriate (usually the base problem) mesh.

Examples: randomshape.mif, stdprob1.mif.

Oxs_ScriptScalarField:

Analogous to the parallel Oxs_ScriptVectorField class, this class produces a scalar field dependent on a Tcl script and optionally other scalar and vector fields. The Specify block has the form

Specify Oxs_ScriptScalarField:name {
      script Tcl_script
      script_args { args_request }
      scalar_fields { scalar_field_spec …}
      vector_fields { vector_field_spec …}
      atlas atlas_spec
      xrange { xmin xmax }
      yrange { ymin ymax }
      zrange { zmin zmax }
}

For each point of interest, the specified script is called with the arguments requested by script_args appended to the command, as explained in the User Defined Support Procedures of the MIF 2 file format documentation. The value for script_args should be a subset of {rawpt relpt minpt maxpt span scalars vectors}.

If rawpt is requested, then when the Tcl proc is called, at the corresponding spot in the argument list the x, y, z values of point will be placed, in problem coordinates (in meters). The points so passed will usually be node points in the simulation discretization (the mesh), but this does not have to be the case in general. The relpt, minpt, maxpt, and span rely on a definition of a bounding box, which is an axes parallel parallelepiped. The bounding box must be specified by either referencing an atlas, or by explicitly stating the range via the three entries xrange, yrange, zrange (in meters). The minpt and maxpt arguments list the minimum and maximum values of the bounding box (coordinate by coordinate), while span provides the 3-vector resulting from $(\text{𝚖𝚊𝚡𝚙𝚝}-\text{𝚖𝚒𝚗𝚙𝚝})$. The relpt selection provides x_rel, y_rel, z_rel, where each element lies in the range $[0,1]$, indicating a relative position between minpt and maxpt, coordinate-wise.

Each of the script_args discussed so far places exactly 3 arguments onto the Tcl proc argument list. The last two, scalars and vectors, place arguments depending on the size of the scalar_fields and vector_fields lists. The scalar_fields value is a list of other scalar field objects. Each scalar field is evaluated at the point in question, and the resulting scalar value is placed on the Tcl proc argument list, in order. The vector_fields option works similarly, except each vector field generates three points for the Tcl proc argument list, since the output from vector field objects is a three vector. Although the use of these entries appears complicated, this is a quite powerful facility that allows nearly unlimited control for the modification and combination of other field objects. Both scalar_fields and vector_fields entries are optional.

If script_args is not specified, the default value relpt is used.

Note that if script_args includes relpt, minpt, maxpt, or span, then a bounding box must be specified, as discussed above. The following example uses the explicit range method. See the Oxs_ScriptVectorField documentation (page 7.3.6) 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.6\times {10}^5$ 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 in Sec. 17.3.2 for an example using an imported image file for similar purposes.

Below is one more example, illustrating the use of the vector_fields option.

proc DotProduct { x1 y1 z1 x2 y2 z2 } {
    return [expr {$x1*$x2+$y1*$y2+$z1*$z2}]
}

Specify Oxs_FileVectorField:file1 {
    atlas :atlas
    file  file1.omf
}

Specify Oxs_UniformVectorField:dir111 {
    norm 1
    vector {1 1 1}
}

Specify Oxs_ScriptScalarField:project {
    script DotProduct
    script_args vectors
    vector_fields {:file1 :dir111}
}

The scalar field :project yields at each point in space the projection of the vector field :file1 onto the [1,1,1] direction.

Examples: antidots-filled.mif, ellipsoid-fieldproc.mif, manyregions-scriptfields.mif, manyspheres.mif, varalpha.mif.

Oxs_VecMagScalarField:

The Oxs_VecMagScalarField class produces a scalar field from a vector field by taking the norm of the vector field on a point-by-point basis, i.e.,

$$\parallel 𝒗\parallel =\sqrt{v_x^2+v_y^2+v_z^2}.$$

The Specify block has the form:

Specify Oxs_VecMagScalarField:name {
      field vector_field_spec
      multiplier mult
      offset off
}

The multiplier and offset entries are applied after the vector norm, i.e., the resulting scalar field is $\text{𝚖𝚞𝚕𝚝}\ast \parallel 𝒗\parallel +\text{𝚘𝚏𝚏}$. The default values for mult and off are 1 and 0, respectively.

The functionality of the Oxs_VecMagScalarField class may be achieved with the Oxs_ScriptScalarField class by using the vector_fields option and a Tcl script to compute the vector norm. However, this particular functionality is needed frequently enough that a specialized class is useful. For example, this class can be used in conjunction with a vector field object to set both the saturation magnetization distribution ($M_s$) and the initial magnetization:

Specify Oxs_FileVectorField:file1 {
    atlas :atlas
    file  file1.omf
}

Specify Oxs_TimeDriver {
    basename test
    evolver :evolve
    stopping_dm_dt 0.01
    mesh :mesh
    m0 :file1
    Ms { Oxs_VecMagScalarField {
       field :file1
    }}
}

Example: sample-vecrotate.mif.

Oxs_ScriptOrientScalarField:

Scalar fields provide scalar values as a function of position across three-space. The Oxs_ScriptOrientScalarField class is used to compose a transformation on the input position before evaluation by a scalar field. The Specify block has the form:

Specify Oxs_ScriptOrientScalarField:name {
      field scalar_field_spec
      script Tcl_script
      script_args { args_request }
      atlas atlas_spec
      xrange { xmin xmax }
      yrange { ymin ymax }
      zrange { zmin zmax }
}

The field argument should refer to a scalar field object. The script is a Tcl script that should return a position vector that will be sent on the field object to ultimately produce a scalar value. The arguments to the Tcl_script are determined by script_args, which should be a subset of {relpt rawpt minpt maxpt span}. If any arguments other than rawpt are requested, then the bounding box must be specified by either the atlas option, or else through the three xrange, yrange, zrange entries. The default value for script_args is relpt.

The Oxs_ScriptOrientScalarField class can be used to change the “orientation” of a scalar field, as in the following simple example, which reflects the :file1mag scalar field across the yz-plane:

Specify Oxs_FileVectorField:file1 {
    atlas :atlas
    file  file1.omf
}

Specify Oxs_VecMagScalarField:file1mag {
   field :file1
}

proc Reflect { x y z xmin ymin zmin xmax ymax zmax} {
   return [list [expr {($xmax+$xmin-$x)}] $y $z]
}

Specify Oxs_ScriptOrientScalarField:reflect {
   field :file1mag
   script Reflect
   script_args {rawpt minpt maxpt}
   atlas :atlas
}

See also the Oxs_ScriptOrientVectorField class (page 7.3.6) for analogous operations on vector fields.

Example: sample-reflect.mif.

Oxs_AffineOrientScalarField:

The Oxs_AffineOrientScalarField class is similar to the Oxs_ScriptOrientScalarField class, except that the transformation on the import position is by an affine transformation defined in terms of a $3\times 3$ matrix and an offset instead of a Tcl script. Although this functionality can be obtained by an appropriate Tcl script, the Oxs_AffineOrientScalarField is easier to use and will run faster, as the underlying transformation is performed by compiled C++ instead of Tcl script.

The Specify block has the form:

Specify Oxs_AffineOrientScalarField:name {
      field scalar_field_spec
      M { matrix_entries …}
      offset { off${}_x$ off${}_y$ off${}_z$ }
      inverse invert_flag
      inverse_slack slack
}

If $F(𝒙)$ represents the scalar field specified by the field value, then the resulting transformed scalar field is $F(M𝒙+\text{𝐨𝐟𝐟})$. Here M is a $3\times 3$ matrix, which may be specified by a list of 1, 3, 6 or 9 entries. If the matrix_entries list consists of a single value, then $M$ is taken to be that value times the identity matrix, i.e., $M$ is a homogeneous scaling transformation. If matrix_entries consists of 3 values, then $M$ is taken to be the diagonal matrix with those three values along the diagonal. If matrix_entries is 6 elements long, then $M$ is assumed to be a symmetric matrix, where the 6 elements specified correspond to $M_{11}$, $M_{12}$, $M_{13}$, $M_{22}$, $M_{23}$, and $M_{33}$. Finally, if matrix_entries is 9 elements long, then the elements specify the entire matrix, in the order $M_{11}$, $M_{12}$, $M_{13}$, $M_{21}$, …, $M_{33}$. If $M$ is not specified, then it is taken to be the identity matrix.

The offset entry is simply a 3-vector that is added to $M𝒙$. If offset is not specified, then it is set to the zero vector.

It is frequently the case that the transformation that one wants to apply is not $M𝒙+\text{𝐨𝐟𝐟}$, but rather the inverse, i.e., $M^{-1}(𝒙-\text{𝐨𝐟𝐟})$. Provided $M$ is nonsingular, this can be accomplished by setting the inverse option to 1. In this case the matrix $M.M^{-1}$ is compared to the identity matrix, to check the accuracy of the matrix inversion. If any entry in $M.M^{-1}$ differs from $I$ by more than the 8-byte float machine precision (typically $2\times {10}^{-16}$) times the value of inverse_slack, then an error is raised. The default setting for invert_flag is 0, meaning don’t invert, and the default setting for slack is 128.

Here is an example using Oxs_AffineOrientScalarField to rotate a field by ${90}^{\circ }$ counterclockwise about the $z$-axis. Note that the specified atlas is square in $x$ and $y$, with the origin of the atlas coordinates in the center of the atlas volume.

Specify Oxs_BoxAtlas:atlas {
  xrange {-250e-9 250e-9}
  yrange {-250e-9 250e-9}
  zrange { -15e-9  15e-9}
}

Specify Oxs_FileVectorField:file1 {
    atlas :atlas
    file  file1.omf
}

Specify Oxs_VecMagScalarField:file1mag {
   field :file1
}

Specify Oxs_AffineOrientScalarField:reflect {
   field :file1mag
   M { 0 1 0
      -1 0 0
       0 0 1 }
}

See also the Oxs_AffineOrientVectorField class (page 7.3.6) for analogous operations on vector fields.

Example: sample-rotate.mif.

Oxs_AffineTransformScalarField:

Like the Oxs_AffineOrientScalarField class, this class composes an affine transform with a separate scalar field, but in this case the affine transform is applied after the field evaluation. The Specify block has the form:

Specify Oxs_AffineTransformScalarField:name {
      field scalar_field_spec
      multiplier mult
      offset off
      inverse invert_flag
}

If $F(𝒙)$ represents the scalar field specified by the field value, then the resulting scalar field is $\text{mult}*F(𝒙)+\text{off}$. Since the output from $F$ is a scalar, both multiplier and offset are scalars. If inverse is 1, then the transform is changed to $\left(F(𝒙)-\text{off}\right)/\text{mult}$, provided mult is non-zero.

The default values for mult, off, and invert_flag are 1, 0, and 0, respectively. The field value is the only required entry.

The functionality provided by Oxs_AffineTransformScalarField can also be produced by the Oxs_ScriptScalarField class (page 7.3.6) with the scalar_fields entry, but the Oxs_AffineTransformScalarField class is faster and has a simpler interface. See also the Oxs_AffineTransformVectorField class (page 7.3.6) for analogous operations on vector fields.

Example: sample-rotate.mif.

Oxs_ImageScalarField:

This class creates a scalar field using an image. The Specify block has the form

Specify Oxs_ImageScalarField:name {
      image pic
      invert invert_flag
      multiplier mult
      offset off
      viewplane view
      atlas atlas_spec
      xrange { xmin xmax }
      yrange { ymin ymax }
      zrange { zmin zmax }
      exterior ext_flag
}

The image is interpreted as a monochromatic map, yielding a scalar field with black corresponding to zero and white to one if invert is 0 (the default), or with black corresponding to 1 and white to 0 if invert is 1. Color images are converted to grayscale by simply summing the red, green, and blue components. A multiplier option is available to change the range of values from $[0,1]$ to $[0,\text{𝚖𝚞𝚕𝚝}]$, after which the offset value, if any, is added.

The viewplane is treated in the same manner as the Oxs_ImageAtlas viewplane option, and should likewise take one of the three two-letter codes xy (default), zx or yz. The spatial scale is adjusted to fit the volume specified by either the atlas or xrange/yrange/zrange selections. If the specified volume does not fill the entire simulation volume, then points outside the specified volume are handled as determined by the exterior setting, which should be either a floating point value, or one of the keywords boundary or error. In the first case, the floating point value is treated as a default value for points outside the image, and should have a value in the range $[0,1]$. The multiplier and offset adjustments are made to this value in the same way as to points inside the image. If ext_flag is boundary, then points outside the image are filled with the value of the closest point on the boundary of the image. If ext is error (the default), then an error is raised if a value is needed for any point outside the image.

Examples: rotatecenterstage.mif, sample-reflect.mif.