Periodic boundary conditions¶
Last changes: Documentation changelog
1. Physical problem and solver family¶
fm.PeriodicBC configures strict zero-phase translational periodicity across paired master/slave cell boundaries (pair_ids) for equilibrium relaxation, time-domain LLG dynamics, spin-wave eigenmode (Eigenmodes at \(\Gamma\)), and steady-state frequency-response (FrequencyResponse) stages.
Unlike fm.FloquetBC, fm.PeriodicBC enforces direct equality of boundary degrees of freedom across the lattice vector \(\Delta\mathbf{r}\) without real/imaginary Bloch phase mixing (PeriodicPhasePolicyIR::ZeroPhase).
2. Governing equations¶
Across each paired master/slave boundary \((\partial\Omega_-, \partial\Omega_+)\) separated by lattice translation vector \(\Delta\mathbf{r} = \mathbf{r}_+ - \mathbf{r}_-\), zero-phase translational periodicity enforces:
For linearized tangent-plane perturbations \(\delta\mathbf{m}(\mathbf{r})\) and dynamic magnetostatic scalar potential \(\delta\phi(\mathbf{r})\), the real and imaginary parts remain uncoupled across the periodic seam:
3. Symbols and SI units¶
Symbol |
Meaning |
SI unit |
|---|---|---|
\(\mathbf{m}\) |
unit magnetization field |
\(\mathrm{1}\) |
\(\phi\) |
magnetostatic scalar potential |
\(\mathrm{A}\) |
\(\delta\mathbf{m}\) |
linearized dynamic magnetization amplitude |
\(\mathrm{1}\) |
\(\delta\phi\) |
linearized dynamic magnetostatic scalar potential amplitude |
\(\mathrm{A}\) |
\(\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}\) |
4. Assumptions, boundary meaning, and validity limits¶
Choice |
Mathematical meaning |
What it does not mean |
|---|---|---|
|
Identifies slave boundary nodes on \(\partial\Omega_+\) with master boundary nodes on \(\partial\Omega_-\) with zero phase twist ( |
Does not apply a nonzero Bloch wave-vector phase \(\mathrm{e}^{-\mathrm{i}\,\mathbf{k}\cdot\Delta\mathbf{r}}\) (use |
|
Enforces periodic wrap on the lateral faces of the shared magnetostatic airbox while retaining Dirichlet truncation on the non-periodic outer faces. |
Not supported on FDM FFT demag when combined with FEM-only airbox boundary options ( |
5. Python API and complete parameter reference¶
Constructor signature¶
fm.PeriodicBC(pair_ids)
Stage-first example: periodic unit-cell relaxation and \(\Gamma\)-point modes¶
# %%
import fullmag as fm
study = fm.study("periodic_unit_cell_modes")
study.objects.mesh.defaults(maximum_element_size=5.0e-9)
film = study.geometry(fm.Box(size=(100.0e-9, 20.0e-9, 5.0e-9)), name="film")
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.exchange()
study.demag(model="airbox", variant="robin")
# %%
# Configure zero-phase periodic boundary conditions along x
periodic_bc = fm.PeriodicBC(pair_ids=("x_minus_x_plus",))
study.stages.add_relax(stage_id="relax_eq", dt=5.0e-13, max_steps=100)
study.stages.add_eigenmodes(
stage_id="gamma_modes",
equilibrium_source="relax",
count=4,
operator="linearized_llg",
damping_policy="ignore",
k_vector=(0.0, 0.0, 0.0),
bc=periodic_bc,
magnetostatic_bc="periodic_airbox_k0",
)
canonical_ir = periodic_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 |
paired boundary identifiers |
FEM/FDM CPU/GPU: IR; resolved support required |
|
6. ProblemIR, normalization, and provenance¶
PeriodicBC.to_ir() emits the canonical kind="periodic" record, which the planner lowers into PeriodicConstraintSetIR entries with PeriodicPhasePolicyIR::ZeroPhase:
{
"spin_wave_bc": {
"kind": "periodic",
"pair_ids": ["x_minus_x_plus"]
},
"periodic_constraint_sets": [
{
"unknown_family": "magnetization_dynamic",
"domain_scope": "magnetic_domain",
"pair_ids": ["x_minus_x_plus"],
"phase_policy": {
"kind": "zero_phase"
}
}
]
}
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("PeriodicBC requires at least one pair_id").Combining FEM-only
periodic_airbox_k0magnetostatic boundary conditions with an FDM solver target fails closed at the IR/planner boundary (test_problem_to_ir_rejects_periodic_airbox_demag_for_fdm).
8. Discrete realization and execution sequence¶
8.1 Master/slave DOF identification¶
In FEM, conformal periodic face pairs on pair_ids identify slave vertices with master vertices (\(u_+ = u_-\)) before or during operator assembly. In FDM, periodic axes wrap finite-difference exchange stencils and use periodic dipole-tensor / FFT image summation along the periodic directions.
8.2 FEM CPU¶
FEM CPU enforces ZeroPhase master/slave elimination on both the magnetic space and (for periodic_airbox_k0) the shared magnetostatic airbox mesh.
8.3 FEM GPU¶
FEM GPU uses the same planner-validated periodic DOF mapping across device and host-assisted operators.
9. Implementation mapping¶
Python DSL class:
packages/fullmag-py/src/fullmag/model/study.py(class PeriodicBC).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 |
Solver legality check |
|
Confirms incompatible periodic airbox + FDM combinations fail closed. |
11. Limitations and failure modes¶
Non-conformal opposite boundary meshes that lack paired vertex correspondence cannot form direct periodic master/slave constraints without conformal periodic meshing.
Nonzero wave-vector dispersion (\(\mathbf{k}\neq\mathbf{0}\)) requires
fm.FloquetBCrather thanfm.PeriodicBC.
12. Scientific bibliography¶
C. Geuzaine and J.-F. Remacle, Gmsh: a three-dimensional finite element mesh generator with built-in pre- and post-processing facilities, Int. J. Numer. Meth. Eng. 79, 1309–1331 (2009), DOI: 10.1002/nme.2579.
13. Source-code index¶
Source path |
Symbol |
Responsibility |
|---|---|---|
|
public constructor and IR lowering for zero-phase periodic 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 periodic and Floquet boundary conditions into planner constraint sets |