femwell
¶
gsim.femwell — femwell mode-solving adapter on the shared 2D mesh.
Loads the same native-2D cross-section mesh the Palace BoundaryMode pipeline generates into skfem/femwell, with piecewise-constant materials resolved from the stack database (cross-validation against Palace) or a continuous carrier-derived eps(x, y) projected per element (which Palace cannot express).
femwell/scikit-fem are optional: install the femwell extra
(pip install 'gsim[femwell]'). The epsilon-mapping helpers work
without them; only solve_modes needs the runtime.
Modules:
-
adapter–femwell adapter on the shared native-2D cross-section mesh.
-
runtime–femwell/skfem runtime resolution for the gsim.femwell adapter.
Functions:
-
boundary_field_ratio–How much of a solved Mode's field is left at the Window boundary.
-
electrode_current–Longitudinal current one conductor of a Mode carries.
-
elementwise_epsilon–Project scattered eps(x, y) samples onto per-element (P0) values.
-
epsilon_by_region–Resolve the complex permittivity of every 2D mesh region.
-
field_fraction_outside–How much of a solved Mode's power sits outside an interval.
-
line_reading–What an RF line solve asks of one selected Mode, in one reading.
-
require_femwell–Import and return the
femwellmodule. -
require_skfem–Import and return the
skfemmodule. -
solve_modes–Solve waveguide modes with femwell on the shared mesh.
-
z0_power_current–Marks-Williams power-current characteristic impedance of an RF mode.
boundary_field_ratio
¶
How much of a solved Mode's field is left at the Window boundary.
A mode solve is only as trustworthy as the box it was solved in: a domain too small for the Mode truncates the evanescent tail and returns a confident effective index for a field that was never allowed to decay. The ratio is the peak electric-field magnitude over the elements touching the outer boundary of the meshed domain, divided by the peak over the whole cross-section — a well-contained Mode gives a number orders of magnitude below one.
Only the outer boundary counts. Cut-outs inside the domain (a metal electrode is meshed as a void) are boundaries too, and the field peaks at their corners, but they are the structure rather than the edge of the Window.
Parameters:
-
mode(Any) –A femwell
Modefrom :func:solve_modes.
Returns:
-
float–Peak boundary field over peak field, in
[0, 1].
Raises:
-
ValueError–When the Mode carries no field, or when no facet of the mesh lies on the domain's bounding box.
electrode_current
¶
electrode_current(
mode: Any, *, frequency_hz: float, conductor: Conductor, mesh: Mesh | str | Path
) -> complex
Longitudinal current one conductor of a Mode carries.
The current definition :func:z0_power_current divides the power
by, on its own, so that a second conductor's current can be read the
same way and compared with the first's: the line Mode's signal and
return electrodes carry equal and opposite currents, the Mode
between both electrodes together and the shielding wall has them
alike (:func:gsim.common.modes.common_mode_fraction).
A "volume" conductor carries the conduction current
integral sigma E_z dA over the elements of its Region, with
sigma implied by the Mode's own epsilon; a "pec" conductor
left out of the meshed domain carries Ampere's contour integral of
H around the outline its extent locates
(:func:boundary_facets_within). Both land in the same scale, and
both sign conventions are consistent from one conductor to the
next — the conduction integral through E_z, the contour through
the boundary normal that points into every conductor alike — so two
conductors' currents read the same way are comparable.
Parameters:
-
mode(Any) –A femwell
Modefrom :func:solve_modes. -
frequency_hz(float) –RF frequency of the solve in Hz.
-
conductor(Conductor) –The conductor, named the way its current is read.
-
mesh(Mesh | str | Path) –The shared msh v2.2 mesh the Mode was solved on (path or loaded meshio mesh).
Returns:
-
complex–The complex current, in the um-coordinate scale
-
complex–func:
z0_power_currentdivides out.
Raises:
-
ValueError–When there is nothing to integrate over: a
"volume"conductor with no Region on the mesh, or a"pec"conductor that is not a hole in it.
elementwise_epsilon
¶
elementwise_epsilon(
mesh: Mesh | str | Path,
x_um: ArrayLike,
y_um: ArrayLike,
eps_values: ArrayLike,
*,
fill: complex | None = None,
) -> NDArray[complex128]
Project scattered eps(x, y) samples onto per-element (P0) values.
Each triangle of the mesh gets the value of the linear interpolant of
the samples at its centroid — the continuous-epsilon path Palace
cannot express. Centroids outside the convex hull of the samples fall
back to nearest-neighbour (or fill when given).
Parameters:
-
mesh(Mesh | str | Path) –The shared msh v2.2 mesh (path or loaded meshio mesh).
-
x_um(ArrayLike) –Sample x coordinates in um (e.g. charge-solve nodes).
-
y_um(ArrayLike) –Sample y coordinates in um.
-
eps_values(ArrayLike) –Complex permittivity samples at those points.
-
fill(complex | None, default:None) –Value for centroids outside the sample hull; defaults to nearest-neighbour extrapolation.
Returns:
-
NDArray[complex128]–Complex epsilon per triangle, in the mesh's triangle order.
epsilon_by_region
¶
epsilon_by_region(
mesh: Mesh | str | Path,
stack: LayerStack,
*,
wavelength_um: float | None = None,
frequency_hz: float | None = None,
overrides: dict[str, MaterialProperties] | None = None,
) -> dict[str, complex]
Resolve the complex permittivity of every 2D mesh region.
Materials come from the stack's materials (the same database the Palace config generator uses), evaluated at the target wavelength or frequency, so both solvers see identical piecewise-constant epsilon.
Parameters:
-
mesh(Mesh | str | Path) –The shared msh v2.2 mesh (path or loaded meshio mesh).
-
stack(LayerStack) –Layer stack the mesh was generated from (region-to-material mapping and material property source).
-
wavelength_um(float | None, default:None) –Target vacuum wavelength in um (optical).
-
frequency_hz(float | None, default:None) –Target frequency in Hz (RF). Exactly one of
wavelength_um/frequency_hzmust be given. -
overrides(dict[str, MaterialProperties] | None, default:None) –Optional material-property overrides by material name.
Returns:
field_fraction_outside
¶
How much of a solved Mode's power sits outside an interval.
A Staircase carries the carrier response only where its Strips are;
a Mode that mostly lives elsewhere is being solved on a
representation that cannot answer for it, however finely the Strips
are binned. The fraction here is the Mode's power — |E|^2
integrated over the elements — outside span along one axis, over
the power everywhere.
Parameters:
-
mode(Any) –A femwell
Modefrom :func:solve_modes. -
span(tuple[float, float]) –(min, max)interval in mesh units (um). -
axis(int, default:0) –Mesh axis the interval is on;
0is the in-plane one on a cross-section mesh,1the vertical one.
Returns:
Raises:
-
ValueError–When the interval is not ascending, or the Mode carries no field.
line_reading
¶
line_reading(
mode: Any,
*,
frequency_hz: float,
mesh: Mesh | str | Path,
signal: Conductor,
return_: Conductor | None = None,
) -> LineReading
What an RF line solve asks of one selected Mode, in one reading.
The index off the Mode, the impedance off its fields over the signal
conductor, and — given the return electrode — whether the Mode is
the wall Mode, from the balance of the two electrodes' currents
(:func:gsim.common.modes.wall_mode_from_currents). A line with no
single return electrode has no pair to compare, and is not checked.
Parameters:
-
mode(Any) –A femwell
Modefrom :func:solve_modes. -
frequency_hz(float) –RF frequency of the solve in Hz.
-
mesh(Mesh | str | Path) –The shared msh v2.2 mesh the Mode was solved on.
-
signal(Conductor) –The signal conductor.
-
return_(Conductor | None, default:None) –The return conductor, or
Nonewhen there is not exactly one.
Returns:
-
LineReading–The reading.
require_femwell
¶
require_femwell() -> ModuleType
Import and return the femwell module.
Raises:
-
ImportError–When femwell is not installed, with a message naming the
femwellpackaging extra.
require_skfem
¶
require_skfem() -> ModuleType
Import and return the skfem module.
Raises:
-
ImportError–When scikit-fem is not installed, with a message naming the
femwellpackaging extra.
solve_modes
¶
solve_modes(
msh_path: str | Path,
*,
epsilon: dict[str, complex] | ArrayLike,
wavelength_um: float,
num_modes: int = 1,
order: int = 2,
metallic_boundaries: bool = False,
n_guess: float | None = None,
) -> Any
Solve waveguide modes with femwell on the shared mesh.
Requires the femwell runtime (pip install 'gsim[femwell]').
Parameters:
-
msh_path(str | Path) –Path of the shared msh v2.2 mesh (um coordinates).
-
epsilon(dict[str, complex] | ArrayLike) –Either
{region_name: eps}(piecewise-constant, from :func:epsilon_by_region) or per-triangle values (continuous, from :func:elementwise_epsilon). -
wavelength_um(float) –Vacuum wavelength in um. For RF, pass the free-space wavelength of the target frequency (
c0 / fin um). -
num_modes(int, default:1) –Number of modes to compute.
-
order(int, default:2) –Finite element order of the mode solve. Order 2, the default, converges faster under mesh refinement than order 1 on optical and RF modes alike. Where the mesh is coarse away from the structure, refining the structure itself does not fix order 1: the series impedance of a lossy metal line (
gamma * Z0) comes out percent low that way, and order 2 brings it to a few 1e-3 or better. Order 2 does not remove the error left by the coarse far mesh; cap the element size there as well when the series impedance must be accurate to 1e-4. Order 2 costs more per solve, from about 2.5 times on a mesh of a hundred elements to about 10 times above a thousand; passorder=1for a cheaper solve where that accuracy is not needed. -
metallic_boundaries(bool, default:False) –Enforce PEC on the outer boundary.
-
n_guess(float | None, default:None) –Effective-index guess centering the eigenvalue search. femwell's default guess tracks the largest permittivity, which for RF materials with big conductive
|Im(eps)|can put the shift far from the physical quasi-TEM mode; pass an explicit guess (e.g. the expected slow-wave index) there.
Returns:
-
Any–The femwell
Modesresult (each mode carriesn_eff).
Raises:
-
ValueError–If the mesh has no triangles, if a region in
epsilonis not on the mesh, if a 2D region on the mesh is missing fromepsilon, or if per-element values do not match the element count.
z0_power_current
¶
z0_power_current(
mode: Any, *, frequency_hz: float, conductor: Conductor, mesh: Mesh | str | Path
) -> complex
Marks-Williams power-current characteristic impedance of an RF mode.
This Backend's two integrals — the complex Poynting flux
P = (1/2) integral (E_t x H_t*) . z dA over the whole
cross-section, and the longitudinal current I on the signal
conductor (:func:electrode_current) — divided through the shared
definition :func:gsim.common.modes.z0_power_current, which owns
Z_0 = 2 P / |I|^2 and the zero-current refusal. The ratio is
invariant to the mode's field normalization; the mesh coordinates
are in um and the unit conversion is internal.
Parameters:
-
mode(Any) –A femwell
Modefrom :func:solve_modes(fields solved with the complex permittivity that encodes the conductivity,exp(+i omega t):Im(eps) < 0). -
frequency_hz(float) –RF frequency of the solve in Hz.
-
conductor(Conductor) –The signal conductor, named the way its current is read.
-
mesh(Mesh | str | Path) –The shared msh v2.2 mesh the Mode was solved on (path or loaded meshio mesh), whose Region names a
"volume"conductor's elements are found by.
Returns:
-
complex–Complex characteristic impedance in ohms.
Raises:
-
ValueError–When the conductor has nothing to integrate over (from :func:
electrode_current), or the current comes out zero.