Floquet boundary conditions¶
Last changes: Documentation changelog
1. Physical problem and solver family¶
fm.FloquetBC configures Bloch/Floquet phase-twisted periodic boundary constraints across paired opposite cell boundaries for wave-vector-resolved spin-wave eigenmode (Eigenmodes) and steady-state frequency-response (FrequencyResponse) stages.
Unlike strict zero-phase periodic boundaries (fm.PeriodicBC), fm.FloquetBC couples the real and imaginary parts of the dynamic magnetization \(\delta\mathbf{m}(\mathbf{r})\) and dynamic magnetostatic scalar potential \(\delta\phi(\mathbf{r})\) across the unit-cell translation vector \(\Delta\mathbf{r}\) via a wave-vector-dependent complex phase factor \(\exp(-\mathrm{i}\,\mathbf{k}\cdot\Delta\mathbf{r})\).
2. Governing equations¶
Across any master/slave boundary pair \((\partial\Omega_-, \partial\Omega_+)\) separated by lattice translation vector \(\Delta\mathbf{r} = \mathbf{r}_+ - \mathbf{r}_-\), the Bloch-periodic boundary condition under the canonical exp_minus_i_k_dot_delta_r convention enforces:
In the real-split two-component tangent-plane and Poisson-airbox representation \((\Re,\Im)\), the complex phase factor \(\mathrm{e}^{-\mathrm{i}\theta}\) with \(\theta = \mathbf{k}\cdot\Delta\mathbf{r}\) acts as an orthogonal \(2\times 2\) rotation matrix mixing the real and imaginary sub-blocks (real_imag_mixing = true):
When the wave-vector norm satisfies the planner \(\Gamma\)-point threshold \(\|\mathbf{k}\|_2 \le \varepsilon_\Gamma = 10^{-12}\,\mathrm{rad\,m^{-1}}\), the off-diagonal \(\sin(\mathbf{k}\cdot\Delta\mathbf{r})\) terms vanish and the constraint reduces to zero-phase periodicity.
3. Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(\delta\mathbf{m}\) |
complex dynamic magnetization amplitude |
\(\mathrm{1}\) |
\(\delta\phi\) |
complex dynamic magnetostatic scalar potential amplitude |
\(\mathrm{A}\) |
\(\delta u\) |
generic complex dynamic field component (\(\delta\mathbf{m}\) or \(\delta\phi\)) |
\(\mathrm{1}\) |
\(\mathbf{r}_-, \mathbf{r}_+\) |
paired master and slave boundary coordinates |
\(\mathrm{m}\) |
\(\Delta\mathbf{r}\) |
periodic lattice translation vector \(\mathbf{r}_+ - \mathbf{r}_-\) |
\(\mathrm{m}\) |
\(\mathbf{k}\) |
Bloch wave vector |
\(\mathrm{rad\,m^{-1}}\) |
\(\theta\) |
Bloch phase angle \(\mathbf{k}\cdot\Delta\mathbf{r}\) across the boundary pair |
\(\mathrm{rad}\) |
\(\varepsilon_\Gamma\) |
planner \(\Gamma\)-point classification threshold (\(10^{-12}\)) |
\(\mathrm{rad\,m^{-1}}\) |
4. Assumptions, boundary meaning, and validity limits¶
Choice |
Mathematical meaning |
What it does not mean |
|---|---|---|
|
Enforces Bloch phase twist \(\mathrm{e}^{-\mathrm{i}\,\mathbf{k}\cdot\Delta\mathbf{r}}\) on paired boundaries in the 3D unit-cell formulation ( |
Does not eliminate the propagation axis into a 2D cross-section mesh (use |
|
Uses \(\psi(\mathbf{r}+\Delta\mathbf{r}) = \mathrm{e}^{-\mathrm{i}\,\mathbf{k}\cdot\Delta\mathbf{r}}\psi(\mathbf{r})\) consistent with \(\mathrm{e}^{\mathrm{i}(\omega t - \mathbf{k}\cdot\mathbf{r})}\). |
Does not flip the sign of \(\omega\) without corresponding adjustment in the real-split operator. |
|
Applies the same Bloch phase constraint ( |
Does not apply open Dirichlet truncation on the periodic lateral faces. |
5. Python API and complete parameter reference¶
Constructor signature¶
fm.FloquetBC(
pair_ids,
phase_convention="exp_minus_i_k_dot_delta_r",
)
Stage-first example: 3D unit-cell Floquet dispersion¶
# %%
import fullmag as fm
study = fm.study("unit_cell_floquet_dispersion")
study.objects.mesh.defaults(maximum_element_size=5.0e-9)
cell = study.geometry(fm.Box(size=(50.0e-9, 50.0e-9, 10.0e-9)), name="magnonic_cell")
cell.Ms = 800.0e3
cell.Aex = 13.0e-12
cell.alpha = 0.01
cell.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.exchange()
study.demag(model="airbox", variant="robin")
# %%
# Configure 3D unit-cell Floquet boundary conditions along x
floquet_bc = fm.FloquetBC(
pair_ids=("x_minus_x_plus",),
phase_convention="exp_minus_i_k_dot_delta_r",
)
study.stages.add_relax(stage_id="relax_eq", dt=5.0e-13, max_steps=100)
study.stages.add_eigenmodes(
stage_id="floquet_bands",
equilibrium_source="relax",
count=6,
operator="linearized_llg",
damping_policy="include",
k_sampling=fm.KPath(
points=[
fm.KPoint("Gamma", (0.0, 0.0, 0.0)),
fm.KPoint("X", (6.283185307e7, 0.0, 0.0)),
],
samples_per_segment=[8],
),
bc=floquet_bc,
magnetostatic_bc="floquet_airbox",
)
canonical_ir = floquet_bc.to_ir()
Parameter reference¶
Python name |
Type |
Default |
SI unit |
Validation |
Meaning |
FEM/FDM CPU/GPU support |
ProblemIR destination |
|---|---|---|---|---|---|---|---|
|
|
|
|
non-empty sequence; IDs non-empty |
boundary pairs carrying the Bloch phase |
FEM/FDM CPU/GPU: IR; resolved support required |
|
|
|
|
|
non-empty string |
phase sign convention |
FEM/FDM CPU/GPU: IR; resolved support required |
|
6. ProblemIR, normalization, and provenance¶
FloquetBC.to_ir() emits the canonical SpinWaveBoundaryConditionIR::Config record, which the FEM planner lowers into PeriodicConstraintSetIR entries for both dynamic magnetization and dynamic magnetostatic scalar potential:
{
"spin_wave_bc": {
"kind": "floquet",
"pair_ids": ["x_minus_x_plus"],
"phase_convention": "exp_minus_i_k_dot_delta_r"
},
"periodic_constraint_sets": [
{
"unknown_family": "magnetization_dynamic",
"domain_scope": "magnetic_domain",
"pair_ids": ["x_minus_x_plus"],
"phase_policy": {
"kind": "bloch_phase",
"phase_convention": "exp_minus_i_k_dot_delta_r",
"k_vector_rad_per_m": [62831853.07, 0.0, 0.0],
"real_imag_mixing": true
}
}
]
}
7. Round-trip and failure semantics¶
The requested intent is preserved in ProblemIR before resolved execution, while validation errors identify invalid inputs and unsupported combinations are rejected explicitly:
Empty
pair_idsor blank pair identifier strings raiseValueError("FloquetBC requires at least one pair_id").Blank
phase_conventionstrings fail closed inFloquetBC.__post_init__.Closed phase loops around intersecting periodic pairs are checked by planner phase-loop diagnostics (
frequency_response_phase_loop_diagnostics).
8. Discrete realization and execution sequence¶
8.1 Constraint assembly¶
For each paired master/slave node set on pair_ids, the backend constructs the complex Bloch phase constraint \(\mathrm{e}^{-\mathrm{i}\,\mathbf{k}\cdot\Delta\mathbf{r}}\) and eliminates slave degrees of freedom into master degrees of freedom via the \(2\times 2\) real-split orthogonal rotation block.
8.2 FEM CPU¶
FEM CPU applies the real-split Bloch constraint to both the tangent-plane magnetic subspace and (when magnetostatic_bc="floquet_airbox") the \(H^1(\Omega_{\mathrm{ms}})\) scalar potential space.
8.3 FEM GPU¶
FEM GPU uses the same planner-validated PeriodicConstraintSetIR contract when assembling device or host-transferred Floquet operators.
9. Implementation mapping¶
Python DSL class:
packages/fullmag-py/src/fullmag/model/study.py(class FloquetBC).IR types:
crates/fullmag-ir/src/execution.rs(SpinWaveBoundaryConditionIR),crates/fullmag-ir/src/plan.rs(PeriodicPhasePolicyIR,PeriodicConstraintSetIR).Planner constraint lowering:
crates/fullmag-plan/src/fem.rs(frequency_response_periodic_constraint_sets).
10. Validation and qualification¶
Validation layer |
Required check |
Evidence required |
|---|---|---|
Python \(\to\) IR serialization |
|
Verifies |
Planner constraint lowering |
|
Confirms |
11. Limitations and failure modes¶
Requiring
FloquetBCwithout paired periodic mesh faces on the specifiedpair_idsfails during mesh/planner constraint validation.Using
FloquetBCwithout a wave-vector specification (k_sampling) leaves the Bloch phase vector unresolved in frequency-response or modal stages.
12. Scientific bibliography¶
F. Bloch, Über die Quantenmechanik der Elektronen in Kristallgittern, Z. Physik 52, 555–600 (1929), DOI: 10.1007/BF01339455.
M. Krawczyk and D. Grundler, Review and prospects of magnonic crystals and devices with reprogrammable band structure, J. Phys.: Condens. Matter 26, 123202 (2014), DOI: 10.1088/0953-8984/26/12/123202.
13. Source-code index¶
Source path |
Symbol |
Responsibility |
|---|---|---|
|
public constructor and IR lowering for Bloch/Floquet boundary pairs |
|
|
canonical IR enum for spin-wave boundary conditions |
|
|
planner IR representation of zero-phase vs Bloch-phase boundary policies |
|
|
resolved periodic/Floquet constraint set for magnetic and magnetostatic domains |
|
|
lowers Floquet and periodic boundary conditions into planner constraint sets |