Skip to content

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

boundary_field_ratio(mode: Any) -> float

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 Mode from :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 Mode from :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_current divides 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_hz must be given.

  • overrides (dict[str, MaterialProperties] | None, default: None ) –

    Optional material-property overrides by material name.

Returns:

  • dict[str, complex] –

    {region_name: complex_relative_permittivity} for every dim-2

  • dict[str, complex] –

    physical group (exp(+i omega t): lossy means Im < 0).

field_fraction_outside

field_fraction_outside(mode: Any, span: tuple[float, float], *, axis: int = 0) -> float

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 Mode from :func:solve_modes.

  • span (tuple[float, float]) –

    (min, max) interval in mesh units (um).

  • axis (int, default: 0 ) –

    Mesh axis the interval is on; 0 is the in-plane one on a cross-section mesh, 1 the vertical one.

Returns:

  • float –

    The fraction in [0, 1]; 0 when every element centroid

  • float –

    falls inside the interval.

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 Mode from :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 None when there is not exactly one.

Returns:

require_femwell

require_femwell() -> ModuleType

Import and return the femwell module.

Raises:

  • ImportError –

    When femwell is not installed, with a message naming the femwell packaging 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 femwell packaging 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 / f in 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; pass order=1 for 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 Modes result (each mode carries n_eff).

Raises:

  • ValueError –

    If the mesh has no triangles, if a region in epsilon is not on the mesh, if a 2D region on the mesh is missing from epsilon, 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 Mode from :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.