Floquet/Bloch frequency response

Last changes: Documentation changelog

Scope and purpose

Floquet response imposes a phase relation between corresponding periodic boundary faces. It is a boundary-value condition on the dynamic magnetization, not merely a nonzero k_vector field. The pair IDs, translation vectors, phase convention, k sampling, demagnetization policy and solver lane must all be resolved before a response is executable.

Scientific and numerical model

For a periodic pair separated by \(\Delta\mathbf r\), the dynamic field satisfies

(1)\[\widehat{\mathbf m}(\mathbf r+\Delta\mathbf r)= e^{-\mathrm i\mathbf k\cdot\Delta\mathbf r} \widehat{\mathbf m}(\mathbf r).\]

The same phase relation is applied to the response operator constraints. A driven response at a prescribed frequency therefore solves

(2)\[\left(\mathsf K(\mathbf k)+\mathrm i\omega\mathsf G(\mathbf k)\right) \widehat{\mathbf q}(\omega,\mathbf k)=\widehat{\mathbf b}(\omega,\mathbf k).\]

The current native FEM production slice supports a narrow projected Floquet response, including a no-dynamic-demag path. Nonzero-k dynamic demagnetization is rejected until its coupled \(\delta\mathbf m/\delta\phi\) operator is qualified.

Symbols and SI units

Symbol

Meaning

SI unit

\(\widehat{\mathbf m}\)

complex dynamic magnetization amplitude

\(1\)

\(\mathbf r\)

position

\(\mathrm{m}\)

\(\Delta\mathbf r\)

periodic face translation

\(\mathrm{m}\)

\(\mathbf k\)

Bloch wave vector

\(\mathrm{m^{-1}}\)

\(\mathsf K(\mathbf k)\)

k-dependent tangent operator

problem-dependent

\(\mathsf G(\mathbf k)\)

k-dependent gyrotropic/damping operator

problem-dependent

\(\omega\)

angular drive frequency

\(\mathrm{rad\,s^{-1}}\)

\(\widehat{\mathbf q}\)

tangent response amplitude

\(1\)

\(\widehat{\mathbf b}\)

harmonic right-hand side

problem-dependent

Assumptions and validity

  • FloquetBC.pair_ids must refer to periodic mesh pairs with finite translations and complete node correspondence. A k vector without pair metadata is not a Floquet boundary condition.

  • The documented phase convention is exp_minus_i_k_dot_delta_r; changing convention changes the sign of the phase and must be recorded.

  • Nonzero-k dynamic demagnetization is not available in the current native FEM contract. A request combining it with Floquet response is a validation error, not permission to drop demag silently.

  • CPU and GPU projected slices are separate qualifications. A CPU result does not prove GPU support.

Python API

# %% Stage-first projected Floquet response without dynamic demagnetization
import fullmag as fm

nm = 1.0e-9
study = fm.study("floquet_response")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(mode="manual", size=(700 * nm, 250 * nm, 250 * nm))
film = study.geometry(fm.Box(size=(500 * nm, 125 * nm, 3 * nm), name="film"), name="film")
film.Ms = 8.0e5
film.Aex = 1.3e-11
film.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
study.stages.add_frequency_response(
    frequencies_hz=(1.0e9, 2.0e9),
    include_demag=False,
    bc=fm.FloquetBC(pair_ids=("x_faces",), phase_convention="exp_minus_i_k_dot_delta_r"),
    k_vector=(1.0e6, 0.0, 0.0),
    magnetostatic_bc="open",
    observable="susceptibility_tensor",
)

Parameters

Python parameter

Type

Default

SI unit

Validation

Meaning

Backend support

ProblemIR

FloquetBC.pair_ids

Sequence[str]

required

\(1\)

at least one nonempty pair ID

periodic face pair identities

FEM mesh/planner

study.spin_wave_bc.pair_ids

FloquetBC.phase_convention

str

exp_minus_i_k_dot_delta_r

\(1\)

nonempty supported convention

sign convention for phase

FEM Floquet

study.spin_wave_bc.phase_convention

FrequencyResponseStageSpec.k_vector

`tuple[float,float,float]

None`

None

\(\mathrm{m^{-1}}\)

finite three-vector

legacy Bloch vector

FEM Floquet

FrequencyResponseStageSpec.k_sampling

`object

None`

None

\(1\)

valid k sampling schema

Bloch sampling

FEM Floquet

FrequencyResponseStageSpec.include_demag

bool

True

\(1\)

Boolean

include dynamic demag

narrow gated slice

study.operator.include_demag

FrequencyResponseStageSpec.magnetostatic_bc

str

open

\(1\)

open, periodic_airbox_k0, or floquet_airbox

magnetostatic closure

FEM

study.magnetostatic_bc

ProblemIR and provenance

The IR keeps Floquet pair IDs and phase convention separate from k sampling and magnetostatic policy. Resolved provenance records periodic mesh certificate, translation vectors, k vector, phase loop diagnostics, dynamic-demag status, solver lane, precision and rejection/qualification reason.

Diagnostics and failure semantics

Script export preserves pair IDs, phase convention and k sampling. Validation errors include missing pair metadata, invalid phase convention, nonzero-k Floquet requests without periodic mesh pairs and dynamic demagnetization without a qualified demag-k operator. Unsupported combinations are explicit; they cannot silently become free boundaries or open demagnetization. Requested intent and resolved execution are recorded separately.

Discrete realization by lane

Solver

Device

Status

Realization

FEM

CPU

partial/source-backed

projected Floquet driven-response slice; dynamic demag gated

FEM

GPU

partial/qualification-dependent

separate projected response slice and runtime dependency gate

FDM

CPU

unsupported

no native FDM Floquet response lane

FDM

GPU

unsupported

no public FDM CUDA Floquet response lane

Where this is implemented

Claim

Repository path

Stable symbol

Responsibility

Lane

Floquet boundary schema

packages/fullmag-py/src/fullmag/model/study.py

class FloquetBC

pair IDs and phase convention

Python

Request validation

backends/fem/src/frequency_domain/operator_contract.cpp

validate_driven_frequency_response_request

Floquet legality checks

FEM

Response contract

backends/fem/src/frequency_domain/modal_eigen_solver.cpp

solve_driven_response_contract

projected response diagnostics

FEM

Validation

Validate periodic pair completeness, translation vectors, phase-loop closure, k-vector units, field continuity, response residuals and CPU/GPU parity at identical k, phase, operator and precision. Validate dynamic-demag rejection explicitly; an unavailable coupled operator is a scientifically important result, not a passing response.

Limitations

The native nonzero-k dynamic-demag operator is not production-qualified. This page documents the projected response slice and its rejection boundary; it does not claim a general periodic magnetostatic response solver.

Scientific bibliography

  • C. Kittel, Introduction to Solid State Physics, magnetic spin-wave boundary conventions.

  • I. A. Kalinikos and A. N. Slavin, Journal of Physics C 19 (1986), periodic spin-wave theory.

  • Canonical boundary owner: Boundary conditions.

Control Room workflow

Use Model Explorer -> Stages -> Add stage -> <stage kind> for stage-level controls when the terminal page identifies a matching field. The current editor is partial: only fields surfaced by the stage draft are authorable. Numerical parameters without a matching control are not implemented in the frontend. Do not infer frontend support from Python or backend availability. See {doc}/frontend/capability-register for the current register and exact source owner.

Source-code index

Claim

Repository path

Stable symbol

Responsibility

Evidence

Floquet schema

packages/fullmag-py/src/fullmag/model/study.py

class FloquetBC

pair IDs and phase

Python source

Native validation

backends/fem/src/frequency_domain/operator_contract.cpp

validate_driven_frequency_response_request

legality

native source

Native response

backends/fem/src/frequency_domain/modal_eigen_solver.cpp

solve_driven_response_contract

response contract

native source