Preset Textures¶

Backend support and qualification¶

preset_version=2 is the current public Python default. A serialized ProblemIR payload that omits preset_version still defaults to version 1 so that old studies are not silently reinterpreted.

Coordinate, mapping, plane, and transform pipeline¶

For each active sample, the planner first selects \(\mathbf x_\mathrm s\) from the object-space or world-space point according to mapping.space. Version 2 then applies the inverse texture transform:

Here translation and pivot are lengths, scale is dimensionless and component-wise, and the quaternion is normalized before use. Every scale component and the quaternion norm must exceed \(10^{-14}\) in the canonical Rust v2 evaluator. The planner validates the descriptor once and materializes a prepared transform containing the normalized forward/inverse quaternion and reciprocal scale. FDM cells and FEM nodes therefore use the same affine map without repeating normalization for every sample. After the local profile has been evaluated, the magnetization vector is embedded in the selected plane and rotated forward by \(\mathcal R_q\). Translation, pivot, and scale affect coordinates; only the quaternion rotates spin components.

The implemented right-handed frames are:

For the planar presets, the local coordinates are

An explicit preset plane and a planar mapping projection must identify the same plane; version 2 rejects a conflict. In the canonical Rust v2 sampler, planar projection is currently applied only to vortex, antivortex, the skyrmion family, skyrmionium, bimeron, domain_wall, and two_domain. uniform, random, helical, and conical retain transformed Cartesian coordinates. hopfion is intrinsically three-dimensional and rejects planar projection.

Inactive FDM cells are written as [0, 0, 0]. Version-2 parameters and transforms are validated before iterating over samples, so malformed input is rejected even for an empty or entirely inactive sample set.

Uniform¶

After validation, the authored direction is normalized once:

The detailed public parameter contract is owned by the Uniform Texture page.

Deterministic random texture¶

Version 2 hashes the seed and the exact IEEE-754 bit patterns of the three local coordinates with SplitMix64. Two 53-bit uniform variates are converted to a point uniformly distributed on the unit sphere:

The public factories require seed. A hand-authored version-2 parameter map that omits it is interpreted with the backend default seed=1. The result is deterministic for the same seed, coordinates, version, and floating-point bit pattern. A mesh change changes the sampled coordinates and therefore changes the random field.

Vortex and antivortex¶

For vortex, \(Q_\mathrm v=+1\); for antivortex, \(Q_\mathrm v=-1\). Version 2 uses a Gaussian normal core:

The square-root argument is evaluated as max(0, 1 - g*g) to suppress a negative value caused by roundoff at the core. circulation is \(c\in\{-1,+1\}\), core_polarity is \(p\in\{-1,+1\}\), and an omitted core_radius is evaluated as \(r_\mathrm c=10^{-9}\,\mathrm{m}\) by the version-2 backend. The factory omits this default from preset_params; consequently the evaluator default is part of the versioned contract.

Bloch and Neel skyrmions¶

The overflow-resistant version-2 radial profile is equivalent to

The implementation returns \(\theta=\pi\) directly for \(r\le 10^{-14}\,\mathrm{m}\), evaluates the hyperbolic-sine ratio in logarithmic form elsewhere, and saturates the logarithmic ratio outside \([-40,40]\). The chirality convention is now explicit: Bloch walls use \(\gamma=c\pi/2\), while Neel walls use \(\gamma=0\) for \(c=+1\) and \(\gamma=\pi\) for \(c=-1\). Consequently chirality reverses the radial Neel-wall direction instead of being a no-op. In version 2, core_polarity=p is the actual sign of the normal component at \(r=0\).

Bimeron: implemented field, topology, and exact core geometry¶

A bimeron is commonly interpreted as an in-plane skyrmion analogue composed of two merons. Fullmag uses that physical interpretation but implements a specific analytic initializer; it is not claimed to be an exact minimizer for a particular Hamiltonian.

With \(Q_\mathrm v\in\{-1,+1\}\), helicity \(\eta\), and \(s_\mathrm{bg}\in\{-1,+1\}\), the exact version-2 local field is

This field is analytically normalized because \(\cos^2\theta+\sin^2\theta(\sin^2\chi+\cos^2\chi)=1\). At the origin, \(\theta(0)=0\); as \(r\rightarrow\infty\), \(\theta\rightarrow\pi\). Therefore

• at the centre: \(\mathbf m=-s_\mathrm{bg}\mathbf e_u\);

• in the far field: \(\mathbf m=+s_\mathrm{bg}\mathbf e_u\);

• changing helicity_rad rotates the meron pair without changing its continuum charge;

• changing vorticity reverses the winding;

• changing background_sign globally reverses the field.

For the documented right-handed \((u,v)\) orientation and the convention

provided that the continuum plane reaches the uniform far field. On a finite or coarsely discretized sample, a numerically integrated charge need not be exactly integer.

A crucial implementation detail is that radius=R is a nominal profile scale, not generally the exact radius of the two points with \(|m_n|=1\). Those points satisfy \(\theta=\pi/2\), hence

The result follows by rewriting each profile term as \(\arcsin[\tanh((r\pm R)/\Delta)]=2\arctan\{\exp[(r\pm R)/\Delta]\}-\pi/2\). Setting \(\theta=\pi/2\) then reduces the profile equation to \(\sinh(r_\mathrm{core}/\Delta)=\cosh(R/\Delta)\). For \(R/\Delta\gg1\), \(r_\mathrm{core}\simeq R\); otherwise the difference is material:

At \(r=r_\mathrm{core}\), the negative-normal core lies where \(Q_\mathrm v\phi+\eta=0\pmod{2\pi}\), and the positive-normal core lies at the antipodal phase \(Q_\mathrm v\phi+\eta=\pi\pmod{2\pi}\). Their normal components are \(-s_\mathrm{bg}\) and \(+s_\mathrm{bg}\), respectively.

The implementation uses only tanh and asin for this profile, so it avoids a direct exponential overflow for very small wall_width. It still requires a positive finite width.

Smooth Bloch or Neel domain wall¶

Let \(s\) be the coordinate selected by normal_axis, \(s_0\) the centre offset, and \(\xi=(s-s_0)/w\). Version 2 requires the normalized right domain to be antiparallel to the normalized left domain and uses

Thus \(\mathbf m\rightarrow\mathbf m_\mathrm L\) for \(\xi\rightarrow-\infty\) and \(\mathbf m\rightarrow\mathbf m_\mathrm R=-\mathbf m_\mathrm L\) for \(\xi\rightarrow+\infty\). wall_center_direction is either explicit or deterministically derived. For a Neel wall the first candidate is the wall-normal axis projected orthogonally to \(\mathbf m_\mathrm L\); for a Bloch wall it is the cross product of the wall-normal axis and \(\mathbf m_\mathrm L\). A deterministic Cartesian helper supplies a tangent when that candidate degenerates. The final direction is normalized and must be orthogonal to the domain direction within \(10^{-10}\). For numerical stability, the Rust evaluator sets sech(xi)=0 when \(|\xi|>350\).

Two-domain initializer¶

In sharp mode, the implementation returns \(\mathbf m_\mathrm L\) for \(s<0\), \(\mathbf m_\mathrm R\) for \(s>0\), and \(\mathbf m_\mathrm W\) exactly at \(s=0\). In smooth mode,

When sharp=None, the factory chooses sharp mode if wall_width is None, otherwise smooth mode. There is currently no center_offset parameter for this preset.

Helical texture¶

Version 2 preserves the magnitude and SI unit of the authored wavevector:

The evaluator normalizes \(\mathbf e_1\) and \(\mathbf e_2\) separately and requires \(|\mathbf e_1\cdot\mathbf e_2|\le 10^{-12}\). Consequently the period along \(\mathbf q\) is \(2\pi/\lVert\mathbf q\rVert\).

Conical texture¶

For a normalized cone axis \(\mathbf a\), the implementation selects \(+\hat{\mathbf x}\) as helper when \(|a_x|<0.9\) and \(+\hat{\mathbf y}\) otherwise. It normalizes the cross product of \(\mathbf a\) with that selected helper to obtain \(\mathbf e_1\), then sets \(\mathbf e_2=\mathbf a\times\mathbf e_1\). It evaluates

The cone angle must lie in \([0,\pi]\). The authored cone_axis is normalized and the physical wavevector magnitude is retained.

Antiskyrmion¶

fm.texture.antiskyrmion(...) uses the same overflow-resistant radial profile as the skyrmion, but reverses the azimuthal winding:

[ \psi=-\phi+\gamma_c,\qquad \mathbf m_\mathrm{local}= (\sin\theta\cos\psi,\ \sin\theta\sin\psi,\ -p\cos\theta). ]

The implemented v2 preset is a Neel-type antiskyrmion ansatz. chirality=+1 gives \(\gamma_c=0\) and chirality=-1 gives \(\gamma_c=\pi\). It is sampled identically on FDM cell centres and FEM magnetic nodes.

Skyrmionium¶

fm.texture.skyrmionium(...) is a normalized two-wall, 2-pi target-state initializer. Defining

[ a(s)=\arccos[-\tanh(s)],\qquad \theta(r)=a!\left(\frac{r-R_\mathrm{in}}{\Delta}\right) +a!\left(\frac{r-R_\mathrm{out}}{\Delta}\right), ]

the local field is

[ \mathbf m_\mathrm{local}= (\sin\theta\cos\psi,\ \sin\theta\sin\psi,\ s_\mathrm{bg}\cos\theta). ]

The centre and far field have the same background orientation; the annulus between the two walls is reversed. The continuum target has zero net skyrmion number when the full far field is included.

Hopfion¶

fm.texture.hopfion(...) is a three-dimensional Hopf-map initializer. With normalized coordinates \(X=x/R\), \(Y=qy/R\), \(Z=z/(R a_z)\), \(\rho^2=X^2+Y^2+Z^2\), and \(d=1+\rho^2\),

[ z_1=\frac{2(X+iY)}{d},\qquad z_2=\frac{2Z+i(\rho^2-1)}{d}, ]

[ \mathbf h= \left(2\operatorname{Re}(z_1\overline{z_2}), 2\operatorname{Im}(z_1\overline{z_2}), |z_1|^2-|z_2|^2\right),\qquad \mathbf m=-s_\mathrm{bg},\mathcal R_z(\varphi_0)\mathbf h. ]

The field is normalized analytically and renormalized once numerically to suppress roundoff. hopf_charge=-1 reflects the second stereographic coordinate and reverses the texture orientation. The profile requires mapping.projection="object_local"; orient it in space with the texture quaternion transform.

Version 1 compatibility¶

Version 1 remains executable only to reproduce historical studies. It is not a less strict spelling of version 2.

Complete factory parameter inventory¶

The table below is generated against the public signatures and is owned by this page. The uniform factory has a separate canonical parameter table on the Uniform Texture page.

Mapping and transform methods¶

The Python transform helpers use a \(10^{-30}\) fallback when constructing degenerate quaternions, whereas the canonical Rust v2 evaluator rejects a final quaternion norm at or below \(10^{-14}\). Therefore successful object construction does not imply successful planner validation.

Complete stage-first bimeron example¶

# %% Imports and units
import fullmag as fm

nm = 1.0e-9

# %% Study, grid, geometry, and material
study = fm.study("bimeron_initial_state")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 2 * nm))

film = study.geometry(fm.Box(300 * nm, 160 * nm, 4 * nm), name="film")
film.Ms = 8.0e5
film.Aex = 13.0e-12
film.alpha = 0.05

# %% Versioned analytic initial condition
film.m = fm.texture.bimeron(
    radius=45 * nm,
    wall_width=8 * nm,
    vorticity=1,
    helicity_rad=0.0,
    background_sign=1,
    plane="xy",
    preset_version=2,
)

# %% Physics and ordered stage
study.exchange()
study.demag()
study.tableautosave(
    1.0e-12,
    quantities=["t", "step", "mx", "my", "mz", "E_total"],
)
study.stages.add_minimize(
    method="bb",
    max_steps=4000,
    tolA=1.0e-5,
)

This example materializes and minimizes the authored field; it does not claim that this material and geometry stabilize a bimeron.

Inspecting the exact serialized descriptor¶

# %% Object-level ProblemIR fragment
import json
from fullmag import texture

nm = 1.0e-9
initial = texture.bimeron(
    radius=45 * nm,
    wall_width=8 * nm,
    vorticity=-1,
    helicity_rad=0.25,
    background_sign=1,
    plane="xy",
    preset_version=2,
).with_mapping(
    space="object",
    projection="planar_xy",
)

print(json.dumps(initial.to_ir(), indent=2))

FDM¶

The planner enumerates cell centres in z, y, x loops with flat index x + nx * (y + ny * z). World coordinates are origin + (index + 0.5) * cell_size. Object coordinates are formed by subtracting the owning top-level geometry translation. The active geometry mask is passed to the versioned sampler; inactive cells receive zero vectors.

The base magnet texture is sampled once on the resolved grid. Enabled region texture overrides are sampled on the same point array and replace base vectors only where the resolved numeric region mask wins. CPU and GPU FDM lanes consume this planner-materialized initial vector.

FEM¶

The mesh path samples the versioned preset at magnetic nodes. Shared-domain air nodes are not magnetization degrees of freedom and are excluded. The planner receives world coordinates and, when available, corresponding object coordinates; the current helper falls back to world coordinates if an object-coordinate array is absent. CPU and GPU FEM lanes consume the same planner-materialized initial vector.

Region-owned texture realization and clipping¶

Object-region textures use the same analytic descriptor and transform pipeline as object-level textures, but ownership is resolved before the sampled vectors are merged. For every FDM cell or FEM magnetic node, Fullmag first determines the unique winning enabled region using the declared priority. Equal highest priorities fail closed. The writable selection is

The texture transform is evaluated only as a coordinate map inside this selection. Translation, rotation, pivot, and scale can move or reshape the visible analytic profile, but they cannot move the region boundary and cannot write outside \Omega_{\mathrm{write}}. A profile translated partly or completely beyond its region is therefore clipped at the region boundary; cells or nodes outside the region retain the object-level initial state or the winning texture of another region.

FDM uses the final active-cell mask and numeric winning-region mask in both single-grid and multilayer plans. FEM evaluates region predicates on the final magnetic P1 nodes of the merged or shared-domain mesh and applies the same priority rule. At a shared FEM interface node there is one global nodal degree of freedom, so overlapping region claims are resolved globally by priority rather than by silently duplicating the node.

Numerical resolution¶

Analytic normalization does not remove discretization error in gradients, energy, or topological charge. For a profile width \(\ell\), compare at least two substantially finer discretizations and monitor the relaxed energy, charge, core position, and maximum torque. For bimerons, resolve \(\Delta\) and use the exact \(r_\mathrm{core}\) above rather than assuming that the cores lie at \(r=R\).