magnelio.boundaries#

Boundary-condition components. BoundaryConditions (the per-face closure declaration) lives in the core magnelio namespace; this component holds the concrete boundary classes for custom setups.

class magnelio.boundaries.CPMLBoundary(face, grid, thickness_cells=8, m=3, R_target=1e-08, kappa_max=7.0, alpha_max=0.02)#

CFS-PML absorbing boundary on one face of the domain.

Parameters:

  • face (str) – 'xmin' | 'xmax' | 'ymin' | 'ymax' | 'zmin' | 'zmax'

  • grid (GridLines) – Simulation grid.

  • thickness_cells (int) – Number of PML cells (default 8).

  • m (int) – Polynomial grading order (default 3).

  • R_target (float) – Target reflection coefficient (default 1e-8).

  • kappa_max (float) – Maximum coordinate stretching factor (default 7). κ = 1 means no stretching (classic CPML).

  • alpha_max (float) – Maximum frequency-shift parameter (default 0.02). Improves low-frequency absorption and late-time stability.

apply(fields)#

Enforce PEC (E_tangential = 0) at the outer face of the PML.

Every CPML is backed by a PEC wall at its outermost grid boundary. Without this, the tangential E-fields at the domain edge are not constrained and cause spurious reflections.

Return type:

None

initialize(dt, xp=None, dtype=None)#

Pre-compute CPML coefficients and allocate ψ arrays.

Must be called once before the time-stepping loop. xp is the solver’s array backend (NumPy or CuPy); None falls back to the module-global get_xp() for standalone use. dtype is the field scalar precision (WP1b) — the ψ recursion state and the device-side b/c/ck coefficients follow it so the CPML correction β·ψ stays a same-dtype op (no float64 penalty on a float32 GPU run); None keeps float64.

Parameters:

dt (float)

Return type:

None

load_state_dict(sd)#

Restore ψ fields written by state_dict() (in place).

Parameters:

sd (dict)

Return type:

None

set_pec_mask(pec_mask_E, Nx, Ny, Nz, material_id=None, material_library=None, xp=None)#

Extract air-edge masks for the PML region from a PEC mask.

Prevents ψ auxiliary fields from accumulating at PEC edges/faces, which would otherwise cause late-time instability when PEC material exists inside the PML region (e.g. waveguide walls at port faces).

Parameters:

  • pec_mask_E (np.ndarray) – Flat boolean PEC mask for all E-field edges.

  • Nx (int) – Grid cell counts.

  • Ny (int) – Grid cell counts.

  • Nz (int) – Grid cell counts.

  • material_id (np.ndarray, optional) – Cell material IDs, shape (Nx, Ny, Nz). Used to derive H-field masks.

  • material_library (dict, optional) – Maps material ID to Material objects.

Return type:

None

state_dict()#

Checkpoint the ψ auxiliary convolution fields.

Serialises every _psi_* array — the exact subset depends on the boundary face axis. All other CPML data are constant stretching coefficients, re-derived at construction.

Return type:

dict

update_E(fields, beta_E)#

Update ψ_E and apply additive correction to E-field (PML region only).

beta_E is the flat array dt / M_eps_eff of length n_E (as produced by FITTimeDomainSolver). The correction Δ E = β_E[edge] · ψ is applied in-place.

All operations are vectorised over the PML slab to minimise kernel-launch overhead on GPU.

Parameters:

beta_E (ndarray)

Return type:

None

update_H(fields, beta_H)#

Update ψ_H and apply additive correction to H-field (PML region only).

beta_H is the flat array dt / M_mu of length n_H (as produced by FITTimeDomainSolver).

Forward E differences rely on PEC being enforced at the outer face before this method is called (tangential E = 0 at PEC boundary).

Parameters:

beta_H (ndarray)

Return type:

None

property pml_axis_indices: list[int]#

Global cell indices along the PML normal axis.

Requires initialize() to have been called first.

property sigma_per_cell: ndarray#

Conductivity σ [S/m] for each PML cell along the normal axis.

The array has length thickness_cells and follows the grading profile from the interface (index 0) inward. Requires initialize() to have been called first.

class magnelio.boundaries.PECBoundary(face, wall_sigma=None, wall_mu=1.0, wall_roughness=None)#

PEC boundary on one face of the simulation domain.

Parameters:

  • face (str) – One of 'xmin', 'xmax', 'ymin', 'ymax', 'zmin', 'zmax'.

  • wall_sigma (float, optional) – Conductivity [S/m] of THIS face’s wall for the wall-loss models. None (default) falls back to the analysis-level wall_sigma. The boundary condition carries the wall material, following large-suite convention; the field update itself stays ideal PEC either way (losses enter through wall_model).

  • wall_mu (float) – Relative permeability accompanying wall_sigma (default 1.0; only consulted when wall_sigma is set).

  • wall_roughness (SurfaceRoughness, optional) – Surface-roughness model for this face’s wall (only consulted when wall_sigma is set).

apply(E)#

Zero tangential E-field on this PEC face.

Parameters:

E (FieldState) – FieldState to modify in place.

Return type:

None

class magnelio.boundaries.PMCBoundary(face, grid)#

PMC boundary on one face of the simulation domain.

The magnetic wall is realised by the natural boundary condition of the free FIT operators (see module docstring); it sits Δ/2 outside the outermost primal grid line of this face. apply_E / apply_H are therefore no-ops — the instance only marks the face as closed.

Parameters:

  • face (str) – One of 'xmin', 'xmax', 'ymin', 'ymax', 'zmin', 'zmax'.

  • grid (GridLines) – The simulation grid.

class magnelio.boundaries.PeriodicBoundary(axis, grid)#

Periodic boundary along one axis pair.

Parameters:

  • axis (str) – 'x', 'y', or 'z' — the periodic axis.

  • grid (GridLines) – The simulation grid.

apply_E(E)#

Apply periodic BC to E field (copy from opposite face).

Parameters:

E (FieldState)

Return type:

None

apply_H(H)#

Apply periodic BC to H field (copy from opposite face).

Parameters:

H (FieldState)

Return type:

None