meow

MEOW: Modeling of Eigenmodes and Overlaps in Waveguides.

Modules:

Name	Description
`arrays`	MEOW array tools for pydantic models.
`base_model`	The pydantic base model all other models are based on.
`cell`	an EME Cell.
`cross_section`	A CrossSection.
`eme`	SAX EME.
`environment`	One place to gather your environment settings.
`fde`	FDE Implementations & Backends.
`gds_structures`	GDS Extrusions.
`geometries`	MEOW geometries.
`materials`	Meow Materials.
`mesh`	A 2D Mesh.
`mode`	An EigenMode.
`structures`	A Structure is a combination of a Geometry with a material.
`visualization`	Visualizations for common meow-datatypes.

Classes:

Name	Description
`BaseModel`	Base model class for all models.
`Box`	A Box is a simple rectangular cuboid.
`Cell`	An EME Cell.
`CrossSection`	A `CrossSection` is built from a `Cell` with an `Environment`.
`Environment`	An environment contains all variables that don't depend on the structure.
`GdsExtrusionRule`	A `GdsExtrusionRule` describes a single extrusion rule.
`Geometry2DBase`	Base class for 2D geometries.
`Geometry3DBase`	Base class for 3D geometries.
`IndexMaterial`	A material with a constant refractive index.
`MaterialBase`	a `Material` defines the index of a `Structure3D` in an `Environment`.
`Mesh2D`	A `Mesh2D` describes how a `Structure3D` is discritized into a `Cell`.
`Mode`	A `Mode` contains the field information for a given `CrossSection`.
`ModelMetaclass`	Metaclass for all models.
`Polygon2D`	A 2D polygon defined by a list of vertices.
`Prism`	A prism is a 2D Polygon extruded along a axis direction ('x', 'y', 'z').
`Rectangle`	A Rectangle.
`SampledMaterial`	A material with a sampled refractive index.
`SerializedArray`	A serialized representation of a numpy array.
`Structure2D`	A `Structure2D` is an association between a `Geometry2D` and a `Material`.
`Structure3D`	A `Structure3D` is an association between a `Geometry3D` and a `Material`.
`TidyMaterial`	A material from the Tidy3D material library.

Functions:

Name	Description
`DType`	Validator to ensure the array has a specific dtype.
`Dim`	Validator to ensure the array has a specific number of dimensions.
`Shape`	Validator to ensure the array has a specific shape.
`Structure`	Create a Structure from a Material and Geometry.
`cache`	Decorator to cache the result of a property method.
`cached_property`	Decorator to cache the result of a property method.
`compute_interface_s_matrices`	Compute interface S-matrices for each adjacent pair of mode sets.
`compute_interface_s_matrix`	Compute the interface S-matrix between two modal bases.
`compute_mode_amplitudes`	Solve for the forward and backward modal amplitudes in one cell.
`compute_modes_lumerical`	Compute `Modes` for a given `CrossSection` (Lumerical backend).
`compute_modes_tidy3d`	Compute `Modes` for a given `CrossSection`.
`compute_propagation_s_matrices`	Return the propagation S-matrix for every cell in a stack.
`compute_propagation_s_matrix`	Return the diagonal propagation S-matrix for one cell.
`compute_s_matrix_sax`	Calculate the S-matrix for given sets of modes.
`create_cells`	Create multiple `Cell` objects with a `Mesh` and a collection of cell lengths.
`create_lumerical_geometries`	Create Lumerical geometries from a list of structures.
`downselect_s`	Downselect the S-matrix to the given ports.
`electric_energy`	Get the electric energy contained in a `Mode`.
`electric_energy_density`	Get the electric energy density contained in a `Mode`.
`energy`	Get the energy contained in a `Mode`.
`energy_density`	Get the energy density contained in a `Mode`.
`enforce_passivity`	Project singular values onto a passive interval.
`extrude_gds`	Extrude a gds cell given a dictionary of extrusion rules.
`filter_modes`	Filter a set of modes according to certain criteria.
`get_sim`	Get the Lumerical simulation object.
`inner_product`	The modal inner product for z-normal mode planes.
`invert_mode`	Invert a `Mode`.
`is_lossy_mode`	Check whether a mode can be considered lossy.
`is_pml_mode`	Check whether a mode can be considered a PML mode.
`l2r_matrices`	Return cumulative left-to-right S-matrices.
`magnetic_energy`	Get the magnetic energy contained in a `Mode`.
`magnetic_energy_density`	Get the magnetic energy density contained in a `Mode`.
`normalize`	Normalize a `Mode` according to the `inner_product` with itself.
`normalize_energy`	Normalize a mode according to the energy it contains.
`normalize_modes`	Self-normalize a set of modes.
`orthonormalize_modes`	Gram-Schmidt orthonormalization with drop tolerance.
`overlap_matrix`	Build the modal overlap matrix between two mode sets.
`pi_pairs`	Return propagation-interface pairs for a full stack.
`plot_fields`	Reconstruct an `Ex(x, z)` field slice from propagated modal amplitudes.
`pml_fraction`	Fraction of energy density in the PML region.
`post_process_modes`	Default post-processing pipeline after FDE.
`propagate`	Propagate boundary excitations through cumulative S-matrices.
`propagate_modes`	Propagate modal excitations through a stack of cells.
`r2l_matrices`	Return cumulative right-to-left S-matrices.
`select_ports`	Keep a subset of ports from an S-matrix.
`sort_structures`	Sort structures by mesh order, then by order of definition.
`split_square_matrix`	Split a square matrix into its four block submatrices.
`te_fraction`	The TE polarization fraction of the `Mode`.
`track_modes`	Track modal order and phase continuously across a cell stack.
`tsvd_solve`	Solve `A X = B` with a truncated-SVD pseudoinverse.
`visualize`	Visualize any meow object.
`zero_phase`	Normalize (zero out) the phase of a `Mode`.

Attributes:

Name	Type	Description
`AxisDirection`	`TypeAlias`	Axis direction: `"x"`, `"y"`, or `"z"`.
`BoolArray1D`	`TypeAlias`	1D boolean numpy array.
`BoolArray2D`	`TypeAlias`	2D boolean numpy array.
`Complex`	`TypeAlias`	0D (scalar) complex128 numpy array.
`ComplexArray1D`	`TypeAlias`	1D complex128 numpy array.
`ComplexArray2D`	`TypeAlias`	2D complex128 numpy array.
`FloatArray1D`	`TypeAlias`	1D float64 numpy array.
`FloatArray2D`	`TypeAlias`	2D float64 numpy array.
`Geometry`	`TypeAlias`	Any 2D or 3D geometry.
`Geometry2D`	`TypeAlias`	A 2D geometry: either a `Rectangle` or a `Polygon2D`.
`Geometry3D`	`TypeAlias`	A 3D geometry: either a `Box` or a `Prism`.
`IntArray1D`	`TypeAlias`	1D int64 numpy array.
`IntArray2D`	`TypeAlias`	2D int64 numpy array.
`Material`	`TypeAlias`	A material: `IndexMaterial`, `SampledMaterial`, or `TidyMaterial`.
`Materials`	`TypeAlias`	A list of `Material` objects.
`Modes`	`TypeAlias`	A list of `Mode` objects.
`NDArray`	`TypeAlias`	A numpy ndarray with pydantic serialization support.
`PassivityMethod`	`TypeAlias`	Method for enforcing S-matrix passivity.
`Sim`	`TypeAlias`	A lumerical simulation object.

AxisDirection `module-attribute`

AxisDirection: TypeAlias = Literal['x', 'y', 'z']

Axis direction: "x", "y", or "z".

BoolArray1D `module-attribute`

BoolArray1D: TypeAlias = Annotated[
    NDArray, Dim(1), DType("bool")
]

1D boolean numpy array.

BoolArray2D `module-attribute`

BoolArray2D: TypeAlias = Annotated[
    NDArray, Dim(2), DType("bool")
]

2D boolean numpy array.

Complex `module-attribute`

Complex: TypeAlias = Annotated[
    NDArray, Dim(0), DType("complex128")
]

0D (scalar) complex128 numpy array.

ComplexArray1D `module-attribute`

ComplexArray1D: TypeAlias = Annotated[
    NDArray, Dim(1), DType("complex128")
]

1D complex128 numpy array.

ComplexArray2D `module-attribute`

ComplexArray2D: TypeAlias = Annotated[
    NDArray, Dim(2), DType("complex128")
]

2D complex128 numpy array.

FloatArray1D `module-attribute`

FloatArray1D: TypeAlias = Annotated[
    NDArray, Dim(1), DType("float64")
]

1D float64 numpy array.

FloatArray2D `module-attribute`

FloatArray2D: TypeAlias = Annotated[
    NDArray, Dim(2), DType("float64")
]

2D float64 numpy array.

Geometry `module-attribute`

Geometry: TypeAlias = Geometry2D | Geometry3D

Any 2D or 3D geometry.

Geometry2D `module-attribute`

Geometry2D: TypeAlias = Rectangle | Polygon2D

A 2D geometry: either a Rectangle or a Polygon2D.

Geometry3D `module-attribute`

Geometry3D: TypeAlias = Box | Prism

A 3D geometry: either a Box or a Prism.

IntArray1D `module-attribute`

IntArray1D: TypeAlias = Annotated[
    NDArray, Dim(1), DType("int64")
]

1D int64 numpy array.

IntArray2D `module-attribute`

IntArray2D: TypeAlias = Annotated[
    NDArray, Dim(2), DType("int64")
]

2D int64 numpy array.

Material `module-attribute`

Material: TypeAlias = (
    IndexMaterial | SampledMaterial | TidyMaterial
)

A material: IndexMaterial, SampledMaterial, or TidyMaterial.

Materials `module-attribute`

Materials: TypeAlias = list[Material]

A list of Material objects.

Modes `module-attribute`

Modes: TypeAlias = list[Mode]

A list of Mode objects.

NDArray `module-attribute`

NDArray: TypeAlias = Annotated[
    ndarray,
    ArraySchema,
    PlainSerializer(_serialize_ndarray),
    BeforeValidator(_validate_ndarray),
    AfterValidator(_coerce_immutable),
]

A numpy ndarray with pydantic serialization support.

PassivityMethod `module-attribute`

PassivityMethod: TypeAlias = Literal[
    "none", "clip", "invert", "subtract"
]

Method for enforcing S-matrix passivity.

Sim `module-attribute`

Sim: TypeAlias = Any

A lumerical simulation object.

BaseModel

Bases: BaseModel

Base model class for all models.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

Box

Bases: Geometry3DBase

A Box is a simple rectangular cuboid.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

Cell

Bases: BaseModel

An EME Cell.

This defines an interval in z (the direction of propagation) within the simulation domain. The intersecting Structure3Ds are discretized by a given mesh at the center of the Cell

Methods:

Name	Description
`m_full`	The full material mask for the cell.
`materials`	A mapping of the materials in the cell to their indices.
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.
`structures_2d`	The 2D structures in the cell.

Attributes:

Name	Type	Description
`length`	`float`	The length of the cell.
`z`	`float`	The z-position of the center of the cell.

length `property`

length: float

The length of the cell.

z `property`

z: float

The z-position of the center of the cell.

m_full

m_full() -> IntArray2D

The full material mask for the cell.

Source code in src/meow/cell.py

@cached_property
def m_full(self) -> IntArray2D:
    """The full material mask for the cell."""
    return _create_full_material_array(
        mesh=self.mesh,
        structures=self.structures_2d,
        materials=self.materials,
    )

materials

materials() -> dict[Material, int]

A mapping of the materials in the cell to their indices.

Source code in src/meow/cell.py

@cached_property
def materials(self) -> dict[Material, int]:
    """A mapping of the materials in the cell to their indices."""
    materials = {}
    for i, structure in enumerate(sort_structures(self.structures), start=1):
        if structure.material not in materials:
            materials[structure.material] = i
    return materials

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

structures_2d

structures_2d() -> list[Structure2D]

The 2D structures in the cell.

Source code in src/meow/cell.py

@cached_property
def structures_2d(self) -> list[Structure2D]:
    """The 2D structures in the cell."""
    z = 0.5 * (self.z_min + self.z_max)
    list_of_list = [s._project(z) for s in self.structures]
    structures = [s for ss in list_of_list for s in ss]
    return structures

CrossSection

Bases: BaseModel

A CrossSection is built from a Cell with an Environment.

This uniquely defines the refractive index everywhere.

Methods:

Name	Description
`from_cell`	Create a CrossSection from a Cell and Environment.
`materials`	Return a dictionary mapping materials to their indices.
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.
`n_full`	Return the refractive index array for the full mesh.
`nx`	Return the smoothed refractive index on the Ex positions.
`ny`	Return the smoothed refractive index on the Ey positions.
`nz`	Return the smoothed refractive index on the Ez positions.

from_cell `classmethod`

from_cell(
    *,
    cell: Cell,
    env: Environment,
    subpixel_smoothing: bool = True,
) -> Self

Create a CrossSection from a Cell and Environment.

Source code in src/meow/cross_section.py

@classmethod
def from_cell(
    cls,
    *,
    cell: Cell,
    env: Environment,
    subpixel_smoothing: bool = True,
) -> Self:
    """Create a CrossSection from a Cell and Environment."""
    return cls(
        structures=cell.structures_2d,
        mesh=cell.mesh,
        env=env,
        subpixel_smoothing=subpixel_smoothing,
        _cell=cell,
    )

materials

materials() -> dict[Material, int]

Return a dictionary mapping materials to their indices.

Source code in src/meow/cross_section.py

@cached_property
def materials(self) -> dict[Material, int]:
    """Return a dictionary mapping materials to their indices."""
    materials: dict[Material, int] = {}
    for i, structure in enumerate(sort_structures(self.structures), start=1):
        if structure.material not in materials:
            materials[structure.material] = i
    return materials

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

n_full

n_full() -> ComplexArray2D

Return the refractive index array for the full mesh.

Source code in src/meow/cross_section.py

@cached_property
def n_full(self) -> ComplexArray2D:
    """Return the refractive index array for the full mesh."""
    n_full = np.ones_like(self.mesh.X_full, dtype=np.complex128)
    for material, idx in self.materials.items():
        n_full = np.where(self._m_full == idx, material(self.env), n_full)
    return n_full

nx

nx() -> ComplexArray2D

Return the smoothed refractive index on the Ex positions.

Source code in src/meow/cross_section.py

@cached_property
def nx(self) -> ComplexArray2D:
    """Return the smoothed refractive index on the Ex positions."""
    if self.subpixel_smoothing:
        return _compute_smoothed_n(
            self.mesh, self._m_full, self.materials, self.env, self.structures, "x"
        )
    return _compute_winner_takes_all_n(
        self.mesh, self._m_full, self.materials, self.env, self.structures, "x"
    )

ny

ny() -> ComplexArray2D

Return the smoothed refractive index on the Ey positions.

Source code in src/meow/cross_section.py

@cached_property
def ny(self) -> ComplexArray2D:
    """Return the smoothed refractive index on the Ey positions."""
    if self.subpixel_smoothing:
        return _compute_smoothed_n(
            self.mesh, self._m_full, self.materials, self.env, self.structures, "y"
        )
    return _compute_winner_takes_all_n(
        self.mesh, self._m_full, self.materials, self.env, self.structures, "y"
    )

nz

nz() -> ComplexArray2D

Return the smoothed refractive index on the Ez positions.

Source code in src/meow/cross_section.py

@cached_property
def nz(self) -> ComplexArray2D:
    """Return the smoothed refractive index on the Ez positions."""
    if self.subpixel_smoothing:
        return _compute_smoothed_n(
            self.mesh, self._m_full, self.materials, self.env, self.structures, "z"
        )
    return _compute_winner_takes_all_n(
        self.mesh, self._m_full, self.materials, self.env, self.structures, "z"
    )

Environment

Bases: BaseModel

An environment contains all variables that don't depend on the structure.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

GdsExtrusionRule

Bases: BaseModel

A GdsExtrusionRule describes a single extrusion rule.

Multiple of such rules can later be associated with a gds layer tuple.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

Geometry2DBase

Bases: BaseModel

Base class for 2D geometries.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

Geometry3DBase

Bases: BaseModel

Base class for 3D geometries.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

IndexMaterial

Bases: MaterialBase

A material with a constant refractive index.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

MaterialBase

Bases: BaseModel

a Material defines the index of a Structure3D in an Environment.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

Mesh2D

Bases: BaseModel

A Mesh2D describes how a Structure3D is discritized into a Cell.

Methods:

Name	Description
`XY_full`	X and Y at half-integer locations.
`dx`	dx at Hz locations, i.e. center of the 2D cell.
`dy`	dy at Hz locations, i.e. center of the 2D cell.
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.
`x_`	x at Hz locations, i.e. center of the 2D cell.
`x_full`	x at half-integer locations.
`y_`	y at Hz locations, i.e. center of the 2D cell.
`y_full`	y at half-integer locations.

Attributes:

Name	Type	Description
`X_full`	`FloatArray2D`	X at half-integer locations.
`Xx`	`FloatArray2D`	X at Ex locations.
`Xy`	`FloatArray2D`	X at Ey locations.
`Xz`	`FloatArray2D`	X at Ez locations.
`Xz_`	`FloatArray2D`	X at Hz locations.
`Y_full`	`FloatArray2D`	Y at half-integer locations.
`Yx`	`FloatArray2D`	Y at Ex locations.
`Yy`	`FloatArray2D`	Y at Ey locations.
`Yz`	`FloatArray2D`	Y at Ez locations.
`Yz_`	`FloatArray2D`	Y at Hz locations.

X_full `property`

X_full: FloatArray2D

X at half-integer locations.

Xx `property`

Xx: FloatArray2D

X at Ex locations.

Xy `property`

Xy: FloatArray2D

X at Ey locations.

Xz `property`

Xz: FloatArray2D

X at Ez locations.

Xz_ `property`

Xz_: FloatArray2D

X at Hz locations.

Y_full `property`

Y_full: FloatArray2D

Y at half-integer locations.

Yx `property`

Yx: FloatArray2D

Y at Ex locations.

Yy `property`

Yy: FloatArray2D

Y at Ey locations.

Yz `property`

Yz: FloatArray2D

Y at Ez locations.

Yz_ `property`

Yz_: FloatArray2D

Y at Hz locations.

XY_full

XY_full() -> tuple[FloatArray2D, FloatArray2D]

X and Y at half-integer locations.

Source code in src/meow/mesh.py

@cached_property
def XY_full(self) -> tuple[FloatArray2D, FloatArray2D]:
    """X and Y at half-integer locations."""
    Y_full, X_full = np.meshgrid(self.y_full, self.x_full)
    return X_full, Y_full

dx

dx() -> FloatArray1D

dx at Hz locations, i.e. center of the 2D cell.

Source code in src/meow/mesh.py

@cached_property
def dx(self) -> FloatArray1D:
    """dx at Hz locations, i.e. center of the 2D cell."""
    return self.x[1:] - self.x[:-1]

dy

dy() -> FloatArray1D

dy at Hz locations, i.e. center of the 2D cell.

Source code in src/meow/mesh.py

@cached_property
def dy(self) -> FloatArray1D:
    """dy at Hz locations, i.e. center of the 2D cell."""
    return self.y[1:] - self.y[:-1]

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

x_

x_() -> FloatArray1D

x at Hz locations, i.e. center of the 2D cell.

Source code in src/meow/mesh.py

@cached_property
def x_(self) -> FloatArray1D:
    """x at Hz locations, i.e. center of the 2D cell."""
    return 0.5 * (self.x[1:] + self.x[:-1])

x_full

x_full() -> FloatArray1D

x at half-integer locations.

Source code in src/meow/mesh.py

@cached_property
def x_full(self) -> FloatArray1D:
    """x at half-integer locations."""
    return np.stack([self.x[:-1], self.x[:-1] + self.dx / 2], 1).ravel()

y_

y_() -> FloatArray1D

y at Hz locations, i.e. center of the 2D cell.

Source code in src/meow/mesh.py

@cached_property
def y_(self) -> FloatArray1D:
    """y at Hz locations, i.e. center of the 2D cell."""
    return 0.5 * (self.y[1:] + self.y[:-1])

y_full

y_full() -> FloatArray1D

y at half-integer locations.

Source code in src/meow/mesh.py

@cached_property
def y_full(self) -> FloatArray1D:
    """y at half-integer locations."""
    return np.stack([self.y[:-1], self.y[:-1] + self.dy / 2], 1).ravel()

Mode

Bases: BaseModel

A Mode contains the field information for a given CrossSection.

Methods:

Name	Description
`interpolate`	Interpolate the mode to the given location.
`load`	Load a mode from a file.
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.
`save`	Save the mode to a file.

Attributes:

Name	Type	Description
`Px`	`ComplexArray2D`	The x-component of the Poynting vector.
`Py`	`ComplexArray2D`	The y-component of the Poynting vector.
`Pz`	`ComplexArray2D`	The z-component of the Poynting vector.
`env`	`Environment`	The environment of the mode.
`mesh`	`Mesh2D`	The mesh of the mode.
`te_fraction`	`float`	The TE polarization fraction of the mode.

Px `property`

Px: ComplexArray2D

The x-component of the Poynting vector.

Py `property`

Py: ComplexArray2D

The y-component of the Poynting vector.

Pz `property`

Pz: ComplexArray2D

The z-component of the Poynting vector.

env `property`

env: Environment

The environment of the mode.

mesh `property`

mesh: Mesh2D

The mesh of the mode.

te_fraction `property`

te_fraction: float

The TE polarization fraction of the mode.

interpolate

interpolate(
    location: Literal["Ex", "Ey", "Ez", "Hx", "Hy", "Hz"]
    | None,
) -> Mode

Interpolate the mode to the given location.

Source code in src/meow/mode.py

def interpolate(
    self,
    location: Literal["Ex", "Ey", "Ez", "Hx", "Hy", "Hz"] | None,
) -> Mode:
    """Interpolate the mode to the given location."""
    if location is None or location == self.interpolation:
        return self
    if self.interpolation != "":
        msg = "Cannot interpolate from already interpolated mode!"
        raise RuntimeError(msg)
    interpolate_funcs = {
        "EX": _interpolate_Ex,
        "EY": _interpolate_Ey,
        "EZ": _interpolate_Ez,
        "HX": _interpolate_Ey,
        "HY": _interpolate_Ex,
        "HZ": _interpolate_Hz,
    }
    interpolate_func = interpolate_funcs[location.upper()]
    return interpolate_func(self)

load `classmethod`

load(filename: str | Path) -> Mode

Load a mode from a file.

Source code in src/meow/mode.py

@classmethod
def load(cls, filename: str | Path) -> Mode:
    """Load a mode from a file."""
    return cast(Mode, pickle.loads(Path(filename).read_bytes()))

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

save

save(filename: str | Path) -> None

Save the mode to a file.

Source code in src/meow/mode.py

def save(self, filename: str | Path) -> None:
    """Save the mode to a file."""
    path = Path(filename)
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_bytes(pickle.dumps(self))

ModelMetaclass

Bases: ModelMetaclass

Metaclass for all models.

Polygon2D

Bases: Geometry2DBase

A 2D polygon defined by a list of vertices.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

Prism

Bases: Geometry3DBase

A prism is a 2D Polygon extruded along a axis direction ('x', 'y', 'z').

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

Rectangle

Bases: Geometry2DBase

A Rectangle.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

SampledMaterial

Bases: MaterialBase

A material with a sampled refractive index.

Methods:

Name	Description
`from_df`	Create a SampledMaterial from a DataFrame.
`from_path`	Create a SampledMaterial from a CSV file.
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

from_df `classmethod`

from_df(
    name: str, df: DataFrame, meta: dict | None = None
) -> Self

Create a SampledMaterial from a DataFrame.

Source code in src/meow/materials.py

@classmethod
def from_df(cls, name: str, df: pd.DataFrame, meta: dict | None = None) -> Self:
    """Create a SampledMaterial from a DataFrame."""
    meta = meta or {}

    nr = df["nr"].to_numpy()
    ni = np.zeros_like(nr) if "ni" not in df else df["ni"].to_numpy()
    n = nr + 1j * ni

    columns = [c for c in df.columns if c not in ["nr", "ni"]]
    params = {c: np.asarray(df[c].values, dtype=np.float64) for c in columns}

    return cls(name=name, params=params, n=n, meta=meta)

from_path `classmethod`

from_path(path: str, meta: dict | None = None) -> Self

Create a SampledMaterial from a CSV file.

Source code in src/meow/materials.py

@classmethod
def from_path(cls, path: str, meta: dict | None = None) -> Self:
    """Create a SampledMaterial from a CSV file."""
    path = _validate_path(path)
    name = re.sub(r"\.csv$", "", os.path.split(path)[-1])
    df = pd.read_csv(path)
    return cls.from_df(name, df, meta=meta)

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

SerializedArray

Bases: BaseModel

A serialized representation of a numpy array.

Methods:

Name	Description
`from_array`	Create a SerializedArray from a numpy array.
`to_array`	Convert the SerializedArray back to a numpy array.

from_array `classmethod`

from_array(x: ndarray) -> Self

Create a SerializedArray from a numpy array.

Source code in src/meow/arrays.py

@classmethod
def from_array(cls, x: np.ndarray) -> Self:
    """Create a SerializedArray from a numpy array."""
    x = np.asarray(x)
    shape = x.shape
    dtype = str(x.dtype)
    if dtype == "complex64":
        _x = x.ravel().view("float32")
    elif dtype == "complex128":
        _x = x.ravel().view("float64")
    else:
        _x = x.ravel()
    return cls(shape=shape, dtype=dtype, values=_x.tolist())

to_array

to_array() -> ndarray

Convert the SerializedArray back to a numpy array.

Source code in src/meow/arrays.py

def to_array(self) -> np.ndarray:
    """Convert the SerializedArray back to a numpy array."""
    if self.dtype == "complex128":
        arr = np.asarray(self.values, dtype="float64").view("complex128")
    elif self.dtype == "complex64":
        arr = np.asarray(self.values, dtype="float32").view("complex64")
    else:
        arr = np.asarray(self.values, dtype=self.dtype)

    if not self.shape:
        return arr
    return arr.reshape(*self.shape)

Structure2D

Bases: BaseModel

A Structure2D is an association between a Geometry2D and a Material.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

Structure3D

Bases: BaseModel

A Structure3D is an association between a Geometry3D and a Material.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

TidyMaterial

TidyMaterial(**kwargs: Any)

Bases: MaterialBase

A material from the Tidy3D material library.

Methods:

Name	Description
`model_validate`	Validate a pydantic model instance.
`model_validate_json`	Validate a pydantic model instance.

Source code in src/meow/materials.py

def __init__(self, **kwargs: Any) -> None:
    """Initialize the TidyMaterial."""
    super().__init__(**kwargs)

    if self.name not in material_library:
        msg = (
            "Specified material name is invalid. "
            f"Use one of {material_library.keys()}"
        )
        raise ValueError(msg)
    _material = material_library[self.name]
    _variants = getattr(_material, "variants", {})
    if not _variants:
        msg = f"Tidy3D material '{self.name}' not supported."
        raise ValueError(msg)
    if self.variant not in _variants:
        _variant_options = list(_variants.keys())
        msg = f"Specified variant is invalid. Use one of {_variant_options}."
        raise ValueError(msg)

model_validate `classmethod`

model_validate(
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`	`bool \| None`	Whether to extract data from object attributes.	`None`
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    obj: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        obj: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    __tracebackhide__ = True

    if isinstance(obj, cls):
        return obj

    if isinstance(obj, dict):
        cls = MODELS.get(obj.get("type", cls.__name__), cls)  # noqa: PLW0642

    return cls.__pydantic_validator__.validate_python(
        obj, strict=strict, from_attributes=from_attributes, context=context
    )

model_validate_json `classmethod`

model_validate_json(
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self

Validate a pydantic model instance.

Parameters:

Name	Type	Description	Default
`json_data`	`str \| bytes \| bytearray`	The object to validate.	required
`strict`	`bool \| None`	Whether to enforce types strictly.	`None`
`from_attributes`		Whether to extract data from object attributes.	required
`context`	`dict[str, Any] \| None`	Additional context to pass to the validator.	`None`

Raises:

Type	Description
`ValidationError`	If the object could not be validated.

Returns:

Type	Description
`Self`	The validated model instance.

Source code in src/meow/base_model.py

@classmethod
def model_validate_json(  # type: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]
    cls,
    json_data: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> Self:
    """Validate a pydantic model instance.

    Args:
        json_data: The object to validate.
        strict: Whether to enforce types strictly.
        from_attributes: Whether to extract data from object attributes.
        context: Additional context to pass to the validator.

    Raises:
        ValidationError: If the object could not be validated.

    Returns:
        The validated model instance.
    """
    if isinstance(json_data, str):
        json_data = json_data.encode()
    dct = orjson.loads(json_data)
    return cls.model_validate(dct, strict=strict, context=context)

DType

DType(dtype: str, *, coerce: bool = True) -> AfterValidator

Validator to ensure the array has a specific dtype.

Parameters:

Name	Type	Description	Default
`dtype`	`str`	the required data type as a string (e.g. "float64").	required
`coerce`	`bool`	if True, cast the array to the dtype; if False, raise on mismatch.	`True`

Returns:

Type	Description
`AfterValidator`	A pydantic AfterValidator that checks or coerces the array dtype.

Source code in src/meow/arrays.py

def DType(dtype: str, *, coerce: bool = True) -> AfterValidator:  # noqa: N802
    """Validator to ensure the array has a specific dtype.

    Args:
        dtype: the required data type as a string (e.g. "float64").
        coerce: if True, cast the array to the dtype; if False, raise on mismatch.

    Returns:
        A pydantic AfterValidator that checks or coerces the array dtype.
    """
    f = _coerce_dtype if coerce else _assert_dtype
    return AfterValidator(partial(f, dtype=dtype))

Dim

Dim(ndim: int, *, coerce: bool = True) -> AfterValidator

Validator to ensure the array has a specific number of dimensions.

Parameters:

Name	Type	Description	Default
`ndim`	`int`	the required number of dimensions.	required
`coerce`	`bool`	if True, reshape the array to match; if False, raise on mismatch.	`True`

Returns:

Type	Description
`AfterValidator`	A pydantic AfterValidator that checks or coerces the array dimensions.

Source code in src/meow/arrays.py

def Dim(ndim: int, *, coerce: bool = True) -> AfterValidator:  # noqa: N802
    """Validator to ensure the array has a specific number of dimensions.

    Args:
        ndim: the required number of dimensions.
        coerce: if True, reshape the array to match; if False, raise on mismatch.

    Returns:
        A pydantic AfterValidator that checks or coerces the array dimensions.
    """
    f = _coerce_dim if coerce else _assert_dim
    return AfterValidator(partial(f, ndim=ndim))

Shape

Shape(*shape: int, coerce: bool = True) -> AfterValidator

Validator to ensure the array has a specific shape.

Parameters:

Name	Type	Description	Default
`*shape`	`int`	the required dimensions of the array.	`()`
`coerce`	`bool`	if True, reshape the array to match; if False, raise on mismatch.	`True`

Returns:

Type	Description
`AfterValidator`	A pydantic AfterValidator that checks or coerces the array shape.

Source code in src/meow/arrays.py

def Shape(*shape: int, coerce: bool = True) -> AfterValidator:  # noqa: N802
    """Validator to ensure the array has a specific shape.

    Args:
        *shape: the required dimensions of the array.
        coerce: if True, reshape the array to match; if False, raise on mismatch.

    Returns:
        A pydantic AfterValidator that checks or coerces the array shape.
    """
    f = _coerce_shape if coerce else _assert_shape
    return AfterValidator(partial(f, shape=shape))

Structure

Structure(
    *,
    material: Material,
    geometry: Geometry2D,
    mesh_order: int = DEFAULT_MESH_ORDER,
) -> Structure2D

Structure(
    *,
    material: Material,
    geometry: Geometry3D,
    mesh_order: int = DEFAULT_MESH_ORDER,
) -> Structure3D

Structure(
    *,
    material: Material,
    geometry: Geometry2D | Geometry3D,
    mesh_order: int = DEFAULT_MESH_ORDER,
) -> Structure2D | Structure3D

Create a Structure from a Material and Geometry.

Parameters:

Name	Type	Description	Default
`material`	`Material`	the material of the structure.	required
`geometry`	`Geometry2D \| Geometry3D`	a 2D or 3D geometry for the structure.	required
`mesh_order`	`int`	the mesh order used for rasterization priority.	`DEFAULT_MESH_ORDER`

Returns:

Type	Description
`Structure2D \| Structure3D`	A Structure2D if geometry is 2D, otherwise a Structure3D.

Source code in src/meow/structures.py

def Structure(  # noqa: N802
    *,
    material: Material,
    geometry: Geometry2D | Geometry3D,
    mesh_order: int = DEFAULT_MESH_ORDER,
) -> Structure2D | Structure3D:
    """Create a Structure from a Material and Geometry.

    Args:
        material: the material of the structure.
        geometry: a 2D or 3D geometry for the structure.
        mesh_order: the mesh order used for rasterization priority.

    Returns:
        A Structure2D if geometry is 2D, otherwise a Structure3D.
    """
    kwargs = {
        "material": material,
        "geometry": geometry,
        "mesh_order": mesh_order,
    }
    if isinstance(geometry, Geometry2D):
        return Structure2D(**kwargs)
    return Structure3D(**kwargs)

cache

cache(prop: Callable) -> Callable

Decorator to cache the result of a property method.

Parameters:

Name	Type	Description	Default
`prop`	`Callable`	the property method whose result should be cached.	required

Returns:

Type	Description
`Callable`	A wrapped callable that caches and returns the computed value.

Source code in src/meow/base_model.py

def cache(prop: Callable) -> Callable:
    """Decorator to cache the result of a property method.

    Args:
        prop: the property method whose result should be cached.

    Returns:
        A wrapped callable that caches and returns the computed value.
    """
    prop_name = getattr(prop, "__name__", "")
    if not prop_name:
        return prop

    @wraps(prop)
    def getter(self):  # noqa: ANN001,ANN202
        stored_value = self._cache.get(prop_name)

        if stored_value is not None:
            return stored_value

        computed = prop(self)
        self._cache[prop_name] = computed
        return computed

    return getter

cached_property

cached_property(method: Callable)

Decorator to cache the result of a property method.

Parameters:

Name	Type	Description	Default
`method`	`Callable`	the method to wrap as a cached property.	required

Returns:

Type	Description
	A property descriptor that caches the method's return value.

Source code in src/meow/base_model.py

def cached_property(method: Callable):  # noqa: ANN201
    """Decorator to cache the result of a property method.

    Args:
        method: the method to wrap as a cached property.

    Returns:
        A property descriptor that caches the method's return value.
    """
    return property(cache(method))

compute_interface_s_matrices

compute_interface_s_matrices(
    modes: list[Modes],
    *,
    inner_product: Callable = inner_product,
    conjugate: bool | None = None,
    tsvd_rcond: float = 0.001,
    passivity_method: PassivityMethod = "invert",
    enforce_reciprocity: bool = True,
    ignore_warnings: bool = True,
) -> dict[str, SDenseMM]

Compute interface S-matrices for each adjacent pair of mode sets.

This is a thin wrapper around :func:compute_interface_s_matrix applied to every neighboring pair in modes.

The same sharp edges apply here as for the single-interface solve: orthonormalization, inner-product choice, TSVD cutoff, and passivity method must all be interpreted consistently across the full stack.

Parameters:

Name	Type	Description	Default
`modes`	`list[Modes]`	Ordered list of modal bases across the stack.	required
`inner_product`	`Callable`	Inner-product callable for forming overlap matrices.	`inner_product`
`conjugate`	`bool \| None`	Whether to use the conjugated formulation. Inferred from inner_product if None.	`None`
`tsvd_rcond`	`float`	Relative singular-value cutoff for the TSVD solve.	`0.001`
`passivity_method`	`PassivityMethod`	Method for enforcing S-matrix passivity.	`'invert'`
`enforce_reciprocity`	`bool`	Whether to symmetrize each interface S-matrix.	`True`
`ignore_warnings`	`bool`	Whether to suppress numerical warnings.	`True`

Returns:

Type	Description
`dict[str, SDenseMM]`	Dict mapping interface names (e.g. `"i_0_1"`) to SAX dense
`dict[str, SDenseMM]`	multimode S-matrix tuples.

Source code in src/meow/eme/interface.py

def compute_interface_s_matrices(
    modes: list[Modes],
    *,
    inner_product: Callable = inner_product,
    conjugate: bool | None = None,
    tsvd_rcond: float = 1e-3,
    passivity_method: PassivityMethod = "invert",
    enforce_reciprocity: bool = True,
    ignore_warnings: bool = True,
) -> dict[str, sax.SDenseMM]:
    """Compute interface S-matrices for each adjacent pair of mode sets.

    This is a thin wrapper around :func:`compute_interface_s_matrix` applied to
    every neighboring pair in ``modes``.

    The same sharp edges apply here as for the single-interface solve:
    orthonormalization, inner-product choice, TSVD cutoff, and passivity method
    must all be interpreted consistently across the full stack.

    Args:
        modes: Ordered list of modal bases across the stack.
        inner_product: Inner-product callable for forming overlap matrices.
        conjugate: Whether to use the conjugated formulation. Inferred from
            inner_product if None.
        tsvd_rcond: Relative singular-value cutoff for the TSVD solve.
        passivity_method: Method for enforcing S-matrix passivity.
        enforce_reciprocity: Whether to symmetrize each interface S-matrix.
        ignore_warnings: Whether to suppress numerical warnings.

    Returns:
        Dict mapping interface names (e.g. ``"i_0_1"``) to SAX dense
        multimode S-matrix tuples.
    """
    return {
        f"i_{i}_{i + 1}": compute_interface_s_matrix(
            modes1=modes1,
            modes2=modes2,
            inner_product=inner_product,
            conjugate=conjugate,
            tsvd_rcond=tsvd_rcond,
            passivity_method=passivity_method,
            enforce_reciprocity=enforce_reciprocity,
            ignore_warnings=ignore_warnings,
        )
        for i, (modes1, modes2) in enumerate(pairwise(modes))
    }

compute_interface_s_matrix

compute_interface_s_matrix(
    modes1: Modes,
    modes2: Modes,
    *,
    inner_product: Callable = inner_product,
    conjugate: bool | None = None,
    tsvd_rcond: float = 0.001,
    passivity_method: PassivityMethod = "invert",
    enforce_reciprocity: bool = True,
    ignore_warnings: bool = True,
) -> SDenseMM

Compute the interface S-matrix between two modal bases.

This implements the overlap-based EME interface solve for a step discontinuity. The transmission blocks are obtained from a TSVD-regularized solve, then the reflection blocks are reconstructed from the two continuity equations and averaged:

R_LL = 0.5 * ((O_RL^adj @ T_LR - I) + (I - O_LR @ T_LR))
R_RR = 0.5 * ((O_LR^adj @ T_RL - I) + (I - O_RL @ T_RL))

High-level assumptions

the supplied mode sets are already orthonormalized in the same metric used by inner_product;
the interface formulas are therefore used in their simplified G = I form;
any remaining non-passivity is treated as a numerical/truncation issue and corrected afterwards via singular-value processing.

Sharp edges

If modes were orthonormalized with a different inner product than the one passed here, the result is not physically meaningful.
conjugate must match the intended overlap convention. If omitted, it is inferred from inner_product.
tsvd_rcond controls a stability/accuracy tradeoff. Too small can amplify ill-conditioned directions; too large can discard physically relevant channels.
passivity correction modifies the raw interface solve. This is often necessary for truncated bases, but it is still a model correction, not a proof that the original solve was complete.

Parameters:

Name	Type	Description	Default
`modes1`	`Modes`	Modes on the left side of the interface.	required
`modes2`	`Modes`	Modes on the right side of the interface.	required
`inner_product`	`Callable`	Inner-product callable used to form the overlap matrices. This must be consistent with how the modes were orthonormalized.	`inner_product`
`conjugate`	`bool \| None`	Whether to use the conjugated (power-conserving) formulation. If None, inferred from the inner_product callable. Must match the conjugate setting used in inner_product for physical consistency: - conjugate=True: uses O_RL.conj().T (Hermitian transpose) - conjugate=False: uses O_RL.T (transpose)	`None`
`tsvd_rcond`	`float`	Relative singular-value cutoff for the TSVD solve used to build the transmission blocks.	`0.001`
`passivity_method`	`PassivityMethod`	Method for enforcing passivity ("none", "clip", "invert", "subtract").	`'invert'`
`enforce_reciprocity`	`bool`	Whether to symmetrize the final S-matrix as `0.5 * (S + S.T)`.	`True`
`ignore_warnings`	`bool`	Whether to suppress numerical warnings.	`True`

Returns:

Type	Description
`SDenseMM`	A tuple `(S, port_map)` in SAX dense-matrix format.

Notes

The default path is internally consistent because the default meow.mode.inner_product is the asymmetric, unconjugated overlap and the default mode post-processing uses that same callable. If you change the interface inner product, you should generally use the same callable during mode post-processing.

Source code in src/meow/eme/interface.py

def compute_interface_s_matrix(
    modes1: Modes,
    modes2: Modes,
    *,
    inner_product: Callable = inner_product,
    conjugate: bool | None = None,
    tsvd_rcond: float = 1e-3,
    passivity_method: PassivityMethod = "invert",
    enforce_reciprocity: bool = True,
    ignore_warnings: bool = True,
) -> sax.SDenseMM:
    """Compute the interface S-matrix between two modal bases.

    This implements the overlap-based EME interface solve for a step
    discontinuity. The transmission blocks are obtained from a TSVD-regularized
    solve, then the reflection blocks are reconstructed from the two continuity
    equations and averaged:

    - ``R_LL = 0.5 * ((O_RL^adj @ T_LR - I) + (I - O_LR @ T_LR))``
    - ``R_RR = 0.5 * ((O_LR^adj @ T_RL - I) + (I - O_RL @ T_RL))``

    High-level assumptions:
        - the supplied mode sets are already orthonormalized in the same metric
          used by ``inner_product``;
        - the interface formulas are therefore used in their simplified
          ``G = I`` form;
        - any remaining non-passivity is treated as a numerical/truncation
          issue and corrected afterwards via singular-value processing.

    Sharp edges:
        - If modes were orthonormalized with a different inner product than the
          one passed here, the result is not physically meaningful.
        - ``conjugate`` must match the intended overlap convention. If omitted,
          it is inferred from ``inner_product``.
        - ``tsvd_rcond`` controls a stability/accuracy tradeoff. Too small can
          amplify ill-conditioned directions; too large can discard physically
          relevant channels.
        - passivity correction modifies the raw interface solve. This is often
          necessary for truncated bases, but it is still a model correction, not
          a proof that the original solve was complete.

    Args:
        modes1: Modes on the left side of the interface.
        modes2: Modes on the right side of the interface.
        inner_product: Inner-product callable used to form the overlap matrices.
            This must be consistent with how the modes were orthonormalized.
        conjugate: Whether to use the conjugated (power-conserving) formulation.
            If None, inferred from the inner_product callable. Must match the
            conjugate setting used in inner_product for physical consistency:
            - conjugate=True: uses O_RL.conj().T (Hermitian transpose)
            - conjugate=False: uses O_RL.T (transpose)
        tsvd_rcond: Relative singular-value cutoff for the TSVD solve used to
            build the transmission blocks.
        passivity_method: Method for enforcing passivity
            ("none", "clip", "invert", "subtract").
        enforce_reciprocity: Whether to symmetrize the final S-matrix as
            ``0.5 * (S + S.T)``.
        ignore_warnings: Whether to suppress numerical warnings.

    Returns:
        A tuple ``(S, port_map)`` in SAX dense-matrix format.

    Notes:
        The default path is internally consistent because the default
        ``meow.mode.inner_product`` is the asymmetric, unconjugated overlap and
        the default mode post-processing uses that same callable. If you change
        the interface inner product, you should generally use the same callable
        during mode post-processing.
    """
    if ignore_warnings:
        with warnings.catch_warnings():
            warnings.filterwarnings("ignore", message=".*divide by zero.*")
            warnings.filterwarnings("ignore", message=".*overflow encountered.*")
            warnings.filterwarnings("ignore", message=".*invalid value.*")
            return compute_interface_s_matrix(
                modes1=modes1,
                modes2=modes2,
                inner_product=inner_product,
                conjugate=conjugate,
                tsvd_rcond=tsvd_rcond,
                passivity_method=passivity_method,
                enforce_reciprocity=enforce_reciprocity,
                ignore_warnings=False,
            )

    # Infer conjugate from inner_product if not explicitly provided
    if conjugate is None:
        conjugate = _infer_conjugate(inner_product)

    # Supports unequal number of modes on left and right
    N_L, N_R = len(modes1), len(modes2)

    # Overlap matrices: O_LR is (N_L, N_R), O_RL is (N_R, N_L)
    O_LR = overlap_matrix(modes1, modes2, inner_product)
    O_RL = overlap_matrix(modes2, modes1, inner_product)

    I_L = np.eye(N_L)
    I_R = np.eye(N_R)

    # Use Hermitian transpose (.conj().T) for conjugated inner product,
    # plain transpose (.T) for unconjugated inner product.
    # This matches the Lorentz reciprocity relation for each formulation.
    O_RL_adj = O_RL.conj().T if conjugate else O_RL.T
    O_LR_adj = O_LR.conj().T if conjugate else O_LR.T

    # T_LR: (N_R, N_L) — maps N_L left inputs to N_R right outputs
    # Solve: A_LR @ T_LR = 2 * I_L, where A_LR is (N_L, N_R)
    # tsvd_solve(A, B) returns pinv(A) @ B
    # pinv(A_LR) is (N_R, N_L), so result is (N_R, N_L) @ (N_L, N_L) = (N_R, N_L)
    A_LR = O_LR + O_RL_adj  # (N_L, N_R)
    T_LR, *_ = tsvd_solve(A_LR, 2.0 * I_L, rcond=tsvd_rcond)  # (N_R, N_L)

    # T_RL: (N_L, N_R) — maps N_R right inputs to N_L left outputs
    # pinv(A_RL) is (N_L, N_R), so result is (N_L, N_R) @ (N_R, N_R) = (N_L, N_R)
    A_RL = O_RL + O_LR_adj  # (N_R, N_L)
    T_RL, *_ = tsvd_solve(A_RL, 2.0 * I_R, rcond=tsvd_rcond)  # (N_L, N_R)

    # Compute R from both continuity equations and average; this reduces sensitivity
    # to cancellation relative to directly forming (O_RL^adj - O_LR).
    # R_LL: (N_L, N_L)
    R_LL_e = O_RL_adj @ T_LR - I_L  # (N_L, N_R) @ (N_R, N_L) = (N_L, N_L)
    R_LL_h = I_L - O_LR @ T_LR  # (N_L, N_R) @ (N_R, N_L) = (N_L, N_L)
    R_LL = 0.5 * (R_LL_e + R_LL_h)

    # R_RR: (N_R, N_R)
    R_RR_e = O_LR_adj @ T_RL - I_R  # (N_R, N_L) @ (N_L, N_R) = (N_R, N_R)
    R_RR_h = I_R - O_RL @ T_RL  # (N_R, N_L) @ (N_L, N_R) = (N_R, N_R)
    R_RR = 0.5 * (R_RR_e + R_RR_h)

    # Full S-matrix: [a-; b+] = S [a+; b-]
    # Shape: (N_L + N_R, N_L + N_R)
    # Block structure:
    #   [[R_LL (N_L, N_L),  T_RL (N_L, N_R)],
    #    [T_LR (N_R, N_L),  R_RR (N_R, N_R)]]
    S = np.block(
        [
            [R_LL, T_RL],
            [T_LR, R_RR],
        ]
    )

    # Passivity enforcement via SVD
    U, sigma, Vh = np.linalg.svd(S, full_matrices=False)
    sigma_corrected = enforce_passivity(sigma, method=passivity_method)
    S = (U * sigma_corrected) @ Vh

    if enforce_reciprocity:
        S = 0.5 * (S + S.T)

    in_ports = [f"left@{i}" for i in range(N_L)]
    out_ports = [f"right@{i}" for i in range(N_R)]
    port_map = {p: i for i, p in enumerate(in_ports + out_ports)}
    return jnp.asarray(S), port_map

compute_mode_amplitudes

compute_mode_amplitudes(
    u: ComplexArray2D,
    v: ComplexArray2D,
    m: int,
    excitation_l: ComplexArray1D,
    excitation_r: ComplexArray1D,
) -> tuple[ComplexArray1D, ComplexArray1D]

Solve for the forward and backward modal amplitudes in one cell.

Parameters:

Name	Type	Description	Default
`u`	`ComplexArray2D`	Cumulative left-to-right S-matrix (dense array).	required
`v`	`ComplexArray2D`	Cumulative right-to-left S-matrix (dense array).	required
`m`	`int`	Number of right-side (forward) modes.	required
`excitation_l`	`ComplexArray1D`	Left boundary excitation vector.	required
`excitation_r`	`ComplexArray1D`	Right boundary excitation vector.	required

Returns:

Type	Description
`tuple[ComplexArray1D, ComplexArray1D]`	Tuple `(forward, backward)` of complex amplitude vectors.

Source code in src/meow/eme/propagation.py

def compute_mode_amplitudes(
    u: ComplexArray2D,
    v: ComplexArray2D,
    m: int,
    excitation_l: ComplexArray1D,
    excitation_r: ComplexArray1D,
) -> tuple[ComplexArray1D, ComplexArray1D]:
    """Solve for the forward and backward modal amplitudes in one cell.

    Args:
        u: Cumulative left-to-right S-matrix (dense array).
        v: Cumulative right-to-left S-matrix (dense array).
        m: Number of right-side (forward) modes.
        excitation_l: Left boundary excitation vector.
        excitation_r: Right boundary excitation vector.

    Returns:
        Tuple ``(forward, backward)`` of complex amplitude vectors.
    """
    n = u.shape[0] - m
    _, [u21, u22] = split_square_matrix(u, n)
    [v11, v12], _ = split_square_matrix(v, m)

    rhs = u21 @ excitation_l + u22 @ v12 @ excitation_r
    lhs = np.eye(m, dtype=complex) - u22 @ v11
    forward = np.linalg.solve(lhs, rhs)
    backward = v12 @ excitation_r + v11 @ forward
    return forward, backward

compute_modes_lumerical

compute_modes_lumerical(
    cs: CrossSection,
    num_modes: PositiveInt = 10,
    unit: float = 1e-06,
    post_process: Callable = post_process_modes,
    sim: Sim | None = None,
) -> list[Mode]

Compute Modes for a given CrossSection (Lumerical backend).

Parameters:

Name	Type	Description	Default
`cs`	`CrossSection`	the cross-section to solve modes for.	required
`num_modes`	`PositiveInt`	number of modes to compute.	`10`
`unit`	`float`	unit scaling factor (default 1e-6 for micrometres).	`1e-06`
`post_process`	`Callable`	callable applied to the raw mode list before returning.	`post_process_modes`
`sim`	`Sim \| None`	optional Lumerical simulation object; uses the global one if None.	`None`

Returns:

Type	Description
`list[Mode]`	The computed and post-processed list of modes.

Source code in src/meow/fde/lumerical.py

def compute_modes_lumerical(
    cs: CrossSection,
    num_modes: PositiveInt = 10,
    unit: float = 1e-6,
    post_process: Callable = post_process_modes,
    sim: Sim | None = None,
) -> list[Mode]:
    """Compute ``Modes`` for a given ``CrossSection`` (Lumerical backend).

    Args:
        cs: the cross-section to solve modes for.
        num_modes: number of modes to compute.
        unit: unit scaling factor (default 1e-6 for micrometres).
        post_process: callable applied to the raw mode list before returning.
        sim: optional Lumerical simulation object; uses the global one if None.

    Returns:
        The computed and post-processed list of modes.
    """
    from lumapi import (  # ty: ignore[unresolved-import]
        LumApiError,  # type: ignore[reportMissingImports]
    )

    sim = get_sim(sim=sim)

    if sim is None:
        msg = "Lumerical simulation object not given or found."
        raise RuntimeError(msg)

    cell = cs._cell

    if cell is None:
        msg = (
            "The cross-section does not have a cell defined. "
            "Please define a cell before computing modes."
        )
        raise ValueError(msg)

    _assert_default_mesh_setting(cell.mesh.angle_phi == 0, "angle_phi")
    _assert_default_mesh_setting(cell.mesh.angle_theta == 0, "angle_theta")
    _assert_default_mesh_setting(cell.mesh.bend_radius is None, "bend_radius")

    create_lumerical_geometries(sim, cell.structures, cs.env, unit)

    sim.select("FDE")
    sim.delete()
    pml_settings = {}
    num_pml_y, num_pml_z = 0, 0
    if cell.mesh.num_pml[0] > 0:
        pml_settings.update(
            {
                "y_min_bc": "PML",
                "y_max_bc": "PML",
            }
        )
        num_pml_y = 22  # TODO: allow adjusting these values
    if cell.mesh.num_pml[1] > 0:
        pml_settings.update(
            {
                "z_min_bc": "PML",
                "z_max_bc": "PML",
            }
        )
        num_pml_z = 22  # TODO: allow adjusting these values
    sim.addfde(
        background_index=1.0,
        solver_type="2D X normal",
        x=float(cell.z * unit),
        y_min=float(cell.mesh.x.min() * unit),
        y_max=float(cell.mesh.x.max() * unit),
        z_min=float(cell.mesh.y.min() * unit),
        z_max=float(cell.mesh.y.max() * unit),
        define_y_mesh_by="number of mesh cells",
        define_z_mesh_by="number of mesh cells",
        mesh_cells_y=cell.mesh.x_.shape[0],
        mesh_cells_z=cell.mesh.y_.shape[0],
        **pml_settings,
    )
    # set mesh size again, because PML messes with it:
    if cell.mesh.num_pml[0] > 0:
        sim.setnamed("FDE", "mesh cells y", cell.mesh.x_.shape[0] - num_pml_y)
    if cell.mesh.num_pml[1] > 0:
        sim.setnamed("FDE", "mesh cells z", cell.mesh.y_.shape[0] - num_pml_z)
    sim.setanalysis("number of trial modes", int(num_modes))
    sim.setanalysis("search", "near n")
    sim.setanalysis("use max index", True)  # noqa: FBT003
    sim.setanalysis("wavelength", float(cs.env.wl * unit))
    sim.findmodes()
    modes = []
    for j in range(1, num_modes + 1):
        try:
            mode = _lumerical_fields_to_mode(
                cs=cs,
                lneff=sim.getdata(f"mode{j}", "neff"),
                lEx=sim.getdata(f"mode{j}", "Ex"),
                lEy=sim.getdata(f"mode{j}", "Ey"),
                lEz=sim.getdata(f"mode{j}", "Ez"),
                lHx=sim.getdata(f"mode{j}", "Hx"),
                lHy=sim.getdata(f"mode{j}", "Hy"),
                lHz=sim.getdata(f"mode{j}", "Hz"),
            )
        except LumApiError:
            break
        modes.append(mode)

    modes = sorted(modes, key=lambda m: np.real(m.neff), reverse=True)
    return post_process(modes)

compute_modes_tidy3d

compute_modes_tidy3d(
    cs: CrossSection,
    num_modes: PositiveInt = 10,
    target_neff: PositiveFloat | None = None,
    precision: Literal["single", "double"] = "double",
    post_process: Callable = post_process_modes,
) -> Modes

Compute Modes for a given CrossSection.

Parameters:

Name	Type	Description	Default
`cs`	`CrossSection`	the cross-section to solve modes for.	required
`num_modes`	`PositiveInt`	number of modes to compute.	`10`
`target_neff`	`PositiveFloat \| None`	effective index near which to search for modes.	`None`
`precision`	`Literal['single', 'double']`	floating-point precision, `"single"` or `"double"`.	`'double'`
`post_process`	`Callable`	callable applied to the raw mode list before returning.	`post_process_modes`

Returns:

Type	Description
`Modes`	The computed and post-processed collection of modes.

Source code in src/meow/fde/tidy3d.py

def compute_modes_tidy3d(
    cs: CrossSection,
    num_modes: PositiveInt = 10,
    target_neff: PositiveFloat | None = None,
    precision: Literal["single", "double"] = "double",
    post_process: Callable = post_process_modes,
) -> Modes:
    """Compute ``Modes`` for a given ``CrossSection``.

    Args:
        cs: the cross-section to solve modes for.
        num_modes: number of modes to compute.
        target_neff: effective index near which to search for modes.
        precision: floating-point precision, ``"single"`` or ``"double"``.
        post_process: callable applied to the raw mode list before returning.

    Returns:
        The computed and post-processed collection of modes.
    """
    if num_modes < 1:
        msg = "You need to request at least 1 mode."
        raise ValueError(msg)

    od = np.zeros_like(cs.nx)  # off diagonal entry
    eps_cross = [cs.nx**2, od, od, od, cs.ny**2, od, od, od, cs.nz**2]

    if np.isinf(cs.mesh.bend_radius) or np.isnan(cs.mesh.bend_radius):
        bend_radius = None
        bend_axis = None
    else:
        bend_radius = cs.mesh.bend_radius
        bend_axis = cs.mesh.bend_axis

    mode_spec = SimpleNamespace(  # tidy3d.ModeSpec alternative (prevents type checking)
        num_modes=num_modes,
        target_neff=target_neff,
        num_pml=cs.mesh.num_pml,
        filter_pol=None,
        angle_theta=cs.mesh.angle_theta,
        angle_phi=cs.mesh.angle_phi,
        bend_radius=bend_radius,
        precision=precision,
        bend_axis=bend_axis,
        track_freq="central",
        group_index_step=False,
    )

    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", message=".*Input has data type int64.*")
        warnings.filterwarnings("ignore", message=".*divide by zero.*")
        warnings.filterwarnings("ignore", message=".*overflow encountered.*")
        warnings.filterwarnings("ignore", message=".*invalid value.*")
        ((Ex, Ey, Ez), (Hx, Hy, Hz)), neffs = (
            x.squeeze()
            for x in _compute_modes(
                eps_cross=eps_cross,
                coords=[cs.mesh.x, cs.mesh.y],
                freq=c / (cs.env.wl * 1e-6),
                mode_spec=mode_spec,
                precision=precision,
                plane_center=cs.mesh.plane_center,
            )[:2]
        )

    if num_modes == 1:
        modes = [
            Mode(
                cs=cs,
                Ex=Ex,
                Ey=Ey,
                Ez=Ez,
                Hx=Hx,
                Hy=Hy,
                Hz=Hz,
                neff=np.asarray(neffs, dtype=np.complex128).item(),
            )
            for _ in range(num_modes)
        ]
    else:  # num_modes > 1
        modes = [
            Mode(
                cs=cs,
                Ex=Ex[..., i],
                Ey=Ey[..., i],
                Ez=Ez[..., i],
                Hx=Hx[..., i],
                Hy=Hy[..., i],
                Hz=Hz[..., i],
                neff=neffs[i],
            )
            for i in range(num_modes)
        ]

    modes = sorted(modes, key=lambda m: float(np.real(m.neff)), reverse=True)
    return post_process(modes)

compute_propagation_s_matrices

compute_propagation_s_matrices(
    modes: list[Modes],
    cells: list[Cell],
    *,
    cell_lengths: list[float] | None = None,
) -> dict[str, SDictMM]

Return the propagation S-matrix for every cell in a stack.

Parameters:

Name	Type	Description	Default
`modes`	`list[Modes]`	Modal basis for each cell.	required
`cells`	`list[Cell]`	Cells through which the modes propagate.	required
`cell_lengths`	`list[float] \| None`	Optional explicit lengths. If omitted, they are derived from `cell.length`.	`None`

Source code in src/meow/eme/propagation.py

def compute_propagation_s_matrices(
    modes: list[Modes],
    cells: list[Cell],
    *,
    cell_lengths: list[float] | None = None,
) -> dict[str, sax.SDictMM]:
    """Return the propagation S-matrix for every cell in a stack.

    Args:
        modes: Modal basis for each cell.
        cells: Cells through which the modes propagate.
        cell_lengths: Optional explicit lengths. If omitted, they are derived
            from ``cell.length``.
    """
    if cell_lengths is None:
        if cells is None:
            msg = "Either cells or cell_lengths must be provided."
            raise ValueError(msg)
        if len(cells) != len(modes):
            msg = f"len(cells) != len(modes): {len(cells)} != {len(modes)}"
            raise ValueError(msg)
        cell_lengths = [cell.length for cell in cells]

    if len(cell_lengths) != len(modes):
        msg = f"len(cell_lengths) != len(modes): {len(cell_lengths)} != {len(modes)}"
        raise ValueError(msg)

    return {
        f"p_{i}": compute_propagation_s_matrix(modes_, cell_length=cell_length)
        for i, (modes_, cell_length) in enumerate(zip(modes, cell_lengths, strict=True))
    }

compute_propagation_s_matrix

compute_propagation_s_matrix(
    modes: Modes, cell_length: float
) -> SDictMM

Return the diagonal propagation S-matrix for one cell.

Each mode acquires a phase exp(2j * pi * neff / wl * cell_length) while propagating through the cell. Backward propagation is mirrored by the bidirectional port mapping in the returned SAX dictionary.

Parameters:

Name	Type	Description	Default
`modes`	`Modes`	Modal basis for the cell.	required
`cell_length`	`float`	Physical length of the cell.	required

Returns:

Type	Description
`SDictMM`	SAX dictionary mapping port pairs to complex transmission values.

Source code in src/meow/eme/propagation.py

def compute_propagation_s_matrix(modes: Modes, cell_length: float) -> sax.SDictMM:
    """Return the diagonal propagation S-matrix for one cell.

    Each mode acquires a phase ``exp(2j * pi * neff / wl * cell_length)`` while
    propagating through the cell. Backward propagation is mirrored by the
    bidirectional port mapping in the returned SAX dictionary.

    Args:
        modes: Modal basis for the cell.
        cell_length: Physical length of the cell.

    Returns:
        SAX dictionary mapping port pairs to complex transmission values.
    """
    s_dict = {
        (f"left@{i}", f"right@{i}"): jnp.exp(
            2j * jnp.pi * mode.neff / mode.env.wl * cell_length
        )
        for i, mode in enumerate(modes)
    }
    return {**s_dict, **{(p2, p1): v for (p1, p2), v in s_dict.items()}}

compute_s_matrix_sax

compute_s_matrix_sax(
    modes: list[Modes],
    *,
    cells: list[Cell] | None = None,
    cell_lengths: list[float] | None = None,
    sax_backend: Backend = "klu",
    interfaces_fn: Callable = compute_interface_s_matrices,
    propagations_fn: Callable = compute_propagation_s_matrices,
    **_: Any,
) -> SDenseMM

Calculate the S-matrix for given sets of modes.

Parameters:

Name	Type	Description	Default
`modes`	`list[Modes]`	Modal basis for each cell in the stack.	required
`cells`	`list[Cell] \| None`	Cells from which to derive propagation lengths. Either cells or cell_lengths must be provided.	`None`
`cell_lengths`	`list[float] \| None`	Optional explicit propagation lengths per cell.	`None`
`sax_backend`	`Backend`	SAX backend used for circuit evaluation.	`'klu'`
`interfaces_fn`	`Callable`	Callable that computes interface S-matrices.	`compute_interface_s_matrices`
`propagations_fn`	`Callable`	Callable that computes propagation S-matrices.	`compute_propagation_s_matrices`

Returns:

Type	Description
`SDenseMM`	A tuple `(S, port_map)` in SAX dense multimode format.

Source code in src/meow/eme/cascade.py

def compute_s_matrix_sax(
    modes: list[Modes],
    *,
    cells: list[Cell] | None = None,
    cell_lengths: list[float] | None = None,
    sax_backend: sax.Backend = "klu",
    interfaces_fn: Callable = compute_interface_s_matrices,
    propagations_fn: Callable = compute_propagation_s_matrices,
    **_: Any,
) -> sax.SDenseMM:
    """Calculate the S-matrix for given sets of modes.

    Args:
        modes: Modal basis for each cell in the stack.
        cells: Cells from which to derive propagation lengths. Either cells
            or cell_lengths must be provided.
        cell_lengths: Optional explicit propagation lengths per cell.
        sax_backend: SAX backend used for circuit evaluation.
        interfaces_fn: Callable that computes interface S-matrices.
        propagations_fn: Callable that computes propagation S-matrices.

    Returns:
        A tuple ``(S, port_map)`` in SAX dense multimode format.
    """
    propagations = propagations_fn(modes, cells, cell_lengths=cell_lengths)
    interfaces = interfaces_fn(modes)
    net = _get_netlist(propagations, interfaces)
    _, analyze_fn, evaluate_fn = circuit_backends[sax_backend]  # type: ignore[reportArgumentType]  # ty: ignore[invalid-assignment]
    # TODO: use analyze_instances instead of manually converting to scoo ?
    net["instances"] = {k: sax.scoo(v) for k, v in net["instances"].items()}
    analyzed = analyze_fn(net["instances"], net["nets"], net["ports"])
    S, port_map = sax.sdense(
        evaluate_fn(
            analyzed,
            instances=net["instances"],
        )
    )
    S = np.asarray(S)

    # final sorting of result:
    current_port_map = {
        (p, int(i)): j
        for (p, i), j in {
            tuple(pm.split("@")): idx for pm, idx in port_map.items()
        }.items()
    }
    desired_port_map = {pm: i for i, pm in enumerate(sorted(current_port_map))}
    idxs = [current_port_map[pm] for pm in desired_port_map]
    S = S[idxs, :][:, idxs]
    port_map = {f"{p}@{m}": v for (p, m), v in desired_port_map.items()}

    return cast(sax.SDenseMM, (S, port_map))

create_cells

create_cells(
    structures: list[Structure3D],
    mesh: Mesh2D | list[Mesh2D],
    Ls: Annotated[NDArray, Dim(1), DType("float64")],
    z_min: float = 0.0,
) -> list[Cell]

Create multiple Cell objects with a Mesh and a collection of cell lengths.

Parameters:

Name	Type	Description	Default
`structures`	`list[Structure3D]`	the 3D structures shared by all cells.	required
`mesh`	`Mesh2D \| list[Mesh2D]`	a single mesh or a list of meshes, one per cell.	required
`Ls`	`Annotated[NDArray, Dim(1), DType('float64')]`	a 1D array of cell lengths.	required
`z_min`	`float`	the starting z-coordinate for the first cell.	`0.0`

Returns:

Type	Description
`list[Cell]`	A list of Cell objects spanning the given lengths.

Source code in src/meow/cell.py

def create_cells(
    structures: list[Structure3D],
    mesh: Mesh2D | list[Mesh2D],
    Ls: Annotated[NDArray, Dim(1), DType("float64")],
    z_min: float = 0.0,
) -> list[Cell]:
    """Create multiple `Cell` objects with a `Mesh` and a collection of cell lengths.

    Args:
        structures: the 3D structures shared by all cells.
        mesh: a single mesh or a list of meshes, one per cell.
        Ls: a 1D array of cell lengths.
        z_min: the starting z-coordinate for the first cell.

    Returns:
        A list of Cell objects spanning the given lengths.
    """
    Ls = np.asarray(Ls, float)
    if Ls.ndim != 1:
        msg = f"Ls should be 1D. Got shape: {Ls.shape}."
        raise ValueError(msg)
    if Ls.shape[0] < 0:
        msg = f"length of Ls array should be nonzero. Got: {Ls}."
        raise ValueError(msg)

    meshes = [mesh] * Ls.shape[0] if isinstance(mesh, Mesh2D) else mesh
    if len(Ls) != len(meshes):
        msg = (
            "Number of meshes should correspond to number of lengths (length of Ls). "
            f"Got {len(meshes)} != {len(Ls)}."
        )
        raise ValueError(msg)

    z = np.cumsum(np.concatenate([np.asarray([z_min], float), Ls]))
    cells = [
        Cell(
            structures=structures,
            mesh=mesh,
            z_min=z_min,
            z_max=z_max,
        )
        for mesh, (z_min, z_max) in zip(meshes, pairwise(z), strict=False)
    ]

    return cells

create_lumerical_geometries

create_lumerical_geometries(
    sim: Sim,
    structures: list[Structure3D],
    env: Environment,
    unit: float,
) -> None

Create Lumerical geometries from a list of structures.

Parameters:

Name	Type	Description	Default
`sim`	`Sim`	the Lumerical simulation object.	required
`structures`	`list[Structure3D]`	3-D structures to add to the simulation.	required
`env`	`Environment`	the environment containing material/wavelength info.	required
`unit`	`float`	unit scaling factor.	required

Source code in src/meow/fde/lumerical.py

def create_lumerical_geometries(
    sim: Sim,
    structures: list[Structure3D],
    env: Environment,
    unit: float,
) -> None:
    """Create Lumerical geometries from a list of structures.

    Args:
        sim: the Lumerical simulation object.
        structures: 3-D structures to add to the simulation.
        env: the environment containing material/wavelength info.
        unit: unit scaling factor.
    """
    sim = get_sim(sim=sim)
    sim.switchtolayout()
    sim.deleteall()
    for s in structures:
        s._lumadd(sim, env, unit, "yzx")

downselect_s

downselect_s(S: SDenseMM, ports: list[str]) -> SDenseMM

Downselect the S-matrix to the given ports.

Parameters:

Name	Type	Description	Default
`S`	`SDenseMM`	A tuple `(S_matrix, port_map)` in SAX dense multimode format.	required
`ports`	`list[str]`	Port names to keep.	required

Returns:

Type	Description
`SDenseMM`	A new `(S_matrix, port_map)` tuple containing only the selected ports.

Source code in src/meow/eme/cascade.py

def downselect_s(S: sax.SDenseMM, ports: list[str]) -> sax.SDenseMM:
    """Downselect the S-matrix to the given ports.

    Args:
        S: A tuple ``(S_matrix, port_map)`` in SAX dense multimode format.
        ports: Port names to keep.

    Returns:
        A new ``(S_matrix, port_map)`` tuple containing only the selected ports.
    """
    S_matrix, port_map = S
    idxs = [port_map[port] for port in ports]
    S_matrix = S_matrix[idxs, :][:, idxs]
    port_map = {port: i for i, port in enumerate(ports)}
    return S_matrix, port_map

electric_energy

electric_energy(mode: Mode) -> float

Get the electric energy contained in a Mode.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to compute the electric energy of.	required

Returns:

Type	Description
`float`	The total electric energy summed over the cross section.

Source code in src/meow/mode.py

def electric_energy(mode: Mode) -> float:
    """Get the electric energy contained in a `Mode`.

    Args:
        mode: the mode to compute the electric energy of.

    Returns:
        The total electric energy summed over the cross section.
    """
    return electric_energy_density(mode).sum()

electric_energy_density

electric_energy_density(
    mode: Mode,
) -> ndarray[tuple[int, int], dtype[float64]]

Get the electric energy density contained in a Mode.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to compute the electric energy density of.	required

Returns:

Type	Description
`ndarray[tuple[int, int], dtype[float64]]`	A 2D array of electric energy density values.

Source code in src/meow/mode.py

def electric_energy_density(
    mode: Mode,
) -> np.ndarray[tuple[int, int], np.dtype[np.float64]]:
    """Get the electric energy density contained in a `Mode`.

    Args:
        mode: the mode to compute the electric energy density of.

    Returns:
        A 2D array of electric energy density values.
    """
    epsx, epsy, epsz = mode.cs.nx**2, mode.cs.ny**2, mode.cs.nz**2
    return np.real(
        0.5
        * eps0
        * (
            epsx * np.abs(mode.Ex) ** 2
            + epsy * np.abs(mode.Ey) ** 2
            + epsz * np.abs(mode.Ez) ** 2
        )
    )

energy

energy(mode: Mode) -> float

Get the energy contained in a Mode.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to compute the energy of.	required

Returns:

Type	Description
`float`	The total energy summed over the cross section.

Source code in src/meow/mode.py

def energy(mode: Mode) -> float:
    """Get the energy contained in a `Mode`.

    Args:
        mode: the mode to compute the energy of.

    Returns:
        The total energy summed over the cross section.
    """
    return energy_density(mode).sum()

energy_density

energy_density(
    mode: Mode,
) -> ndarray[tuple[int, int], dtype[float64]]

Get the energy density contained in a Mode.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to compute the energy density of.	required

Returns:

Type	Description
`ndarray[tuple[int, int], dtype[float64]]`	A 2D array of total (electric + magnetic) energy density values.

Source code in src/meow/mode.py

def energy_density(mode: Mode) -> np.ndarray[tuple[int, int], np.dtype[np.float64]]:
    """Get the energy density contained in a `Mode`.

    Args:
        mode: the mode to compute the energy density of.

    Returns:
        A 2D array of total (electric + magnetic) energy density values.
    """
    return electric_energy_density(mode) + magnetic_energy_density(mode)

enforce_passivity

enforce_passivity(
    singular_values: ndarray,
    *,
    method: PassivityMethod = "invert",
) -> ndarray

Project singular values onto a passive interval.

This function post-processes the singular values of an S-matrix so that the resulting matrix has singular values no larger than one.

Available methods

"none": leave the singular values unchanged.
"clip": replace values larger than one by exactly one.
"invert": replace sigma by 1 / sigma when sigma > 1.
"subtract": replace sigma by max(0, 2 - sigma) when sigma > 1.

High-level interpretation

clip is the most conservative algebraic projection. invert and subtract both map modest gain above one to modest loss below one, which can be useful when the excess gain is interpreted as missing radiation channels in a truncated basis.

Sharp edge

These are heuristic corrections on top of a truncated modal solve. They are often useful, but they are not substitutes for a converged basis.

Parameters:

Name	Type	Description	Default
`singular_values`	`ndarray`	Singular values to correct.	required
`method`	`PassivityMethod`	Passivity enforcement strategy.	`'invert'`

Returns:

Type	Description
`ndarray`	Corrected singular values.

Raises:

Type	Description
`ValueError`	If `method` is unknown.

Source code in src/meow/eme/interface.py

def enforce_passivity(
    singular_values: np.ndarray, *, method: PassivityMethod = "invert"
) -> np.ndarray:
    """Project singular values onto a passive interval.

    This function post-processes the singular values of an S-matrix so that the
    resulting matrix has singular values no larger than one.

    Available methods:
        - ``"none"``: leave the singular values unchanged.
        - ``"clip"``: replace values larger than one by exactly one.
        - ``"invert"``: replace ``sigma`` by ``1 / sigma`` when ``sigma > 1``.
        - ``"subtract"``: replace ``sigma`` by ``max(0, 2 - sigma)`` when
          ``sigma > 1``.

    High-level interpretation:
        ``clip`` is the most conservative algebraic projection. ``invert`` and
        ``subtract`` both map modest gain above one to modest loss below one,
        which can be useful when the excess gain is interpreted as missing
        radiation channels in a truncated basis.

    Sharp edge:
        These are heuristic corrections on top of a truncated modal solve. They
        are often useful, but they are not substitutes for a converged basis.

    Args:
        singular_values: Singular values to correct.
        method: Passivity enforcement strategy.

    Returns:
        Corrected singular values.

    Raises:
        ValueError: If ``method`` is unknown.
    """
    match method:
        case "none":
            return singular_values
        case "clip":
            return np.where(singular_values > 1.0, 1.0, singular_values)
        case "invert":
            return np.where(singular_values > 1.0, 1 / singular_values, singular_values)
        case "subtract":
            singular_values = np.where(
                singular_values > 1.0, 2.0 - singular_values, singular_values
            )
            return np.where(singular_values < 0.0, 0.0, singular_values)
        case _:
            msg = f"Unknown passivity enforcement method {method}."
            raise ValueError(msg)

extrude_gds

extrude_gds(
    cell: Any,
    extrusions: dict[
        tuple[int, int], list[GdsExtrusionRule]
    ],
) -> list[Structure3D]

Extrude a gds cell given a dictionary of extrusion rules.

Parameters:

Name	Type	Description	Default
`cell`	`Any`	a gdspy or gdstk Cell to extrude.	required
`extrusions`	`dict[tuple[int, int], list[GdsExtrusionRule]]`	the extrusion rules to use (if not given, the example extrusions will be used).	required

Returns:

Type	Description
`list[Structure3D]`	A list of Structure3D objects created from the extruded polygons.

Source code in src/meow/gds_structures.py

def extrude_gds(
    cell: Any,  # gf.Component | gdspy.Cell | gdstk.Cell
    extrusions: dict[tuple[int, int], list[GdsExtrusionRule]],
) -> list[Structure3D]:
    """Extrude a gds cell given a dictionary of extrusion rules.

    Args:
        cell: a gdspy or gdstk Cell to extrude.
        extrusions: the extrusion rules to use
            (if not given, the example extrusions will be used).

    Returns:
        A list of Structure3D objects created from the extruded polygons.
    """
    structs = []
    for layer, polys in _get_polygons(cell).items():
        for poly in polys:
            if layer not in extrusions:
                continue
            structs.extend(extrusion(poly) for extrusion in extrusions[layer])
    return structs

filter_modes

filter_modes(
    modes: Modes,
    conditions: Iterable[Callable] = (
        is_pml_mode,
        is_lossy_mode,
    ),
) -> Modes

Filter a set of modes according to certain criteria.

Parameters:

Name	Type	Description	Default
`modes`	`Modes`	the list of modes to filter	required
`conditions`	`Iterable[Callable]`	the conditions to filter the modes with	`(is_pml_mode, is_lossy_mode)`

Returns:

Type	Description
`Modes`	the filtered modes

Source code in src/meow/fde/post_process.py

def filter_modes(
    modes: Modes,
    conditions: Iterable[Callable] = (is_pml_mode, is_lossy_mode),
) -> Modes:
    """Filter a set of modes according to certain criteria.

    Args:
        modes: the list of modes to filter
        conditions: the conditions to filter the modes with

    Returns:
        the filtered modes
    """
    kept = []
    for mode in modes:
        for condition_fn in conditions:
            if condition_fn(mode):
                break
        else:
            kept.append(mode)
    return kept

get_sim

get_sim(**kwargs: Any) -> Sim

Get the Lumerical simulation object.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	keyword arguments; pass `sim` to set and return a specific simulation object.	`{}`

Returns:

Type	Description
`Sim`	The active Lumerical simulation object.

Source code in src/meow/fde/lumerical.py

def get_sim(**kwargs: Any) -> Sim:
    """Get the Lumerical simulation object.

    Args:
        **kwargs: keyword arguments; pass ``sim`` to set and return a specific
            simulation object.

    Returns:
        The active Lumerical simulation object.
    """
    global _sim  # noqa: PLW0603
    sim = kwargs.get("sim", None)
    if sim is not None:
        _sim = sim
        return sim
    sim = _sim
    if sim is None:
        msg = (
            "Could not start Lumerical simulation. Please either pass the "
            "`lumapi.MODE` simulation object as an argument to "
            "`compute_modes_lumerical` to globally "
            "set the lumapi.MODE simulation object."
        )
        raise ValueError(msg)
    return sim

inner_product

inner_product(
    mode1: Mode,
    mode2: Mode,
    *,
    symmetric: bool = False,
    conjugate: bool = False,
    ignore_pml: bool = True,
    interpolation: Literal[
        "Ex", "Ey", "Ez", "Hx", "Hy", "Hz"
    ]
    | None = None,
) -> complex

The modal inner product for z-normal mode planes.

Parameters:

Name	Type	Description	Default
`mode1`	`Mode`	the left mode	required
`mode2`	`Mode`	the right mode	required
`symmetric`	`bool`	use the symmetric inner product definition	`False`
`conjugate`	`bool`	use the conjugage inner product definition (power normalization)	`False`
`ignore_pml`	`bool`	ignore PML region while taking the inner product	`True`
`interpolation`	`Literal['Ex', 'Ey', 'Ez', 'Hx', 'Hy', 'Hz'] \| None`	interpolate both modes to a certain field-grid position before taking the inner product.	`None`

Returns:

Type	Description
`complex`	the inner product

Source code in src/meow/mode.py

def inner_product(
    mode1: Mode,
    mode2: Mode,
    *,
    symmetric: bool = False,
    conjugate: bool = False,
    ignore_pml: bool = True,
    interpolation: Literal["Ex", "Ey", "Ez", "Hx", "Hy", "Hz"] | None = None,
) -> complex:
    """The modal inner product for z-normal mode planes.

    Args:
        mode1: the left mode
        mode2: the right mode
        symmetric: use the symmetric inner product definition
        conjugate: use the conjugage inner product definition (power normalization)
        ignore_pml: ignore PML region while taking the inner product
        interpolation: interpolate both modes to a certain field-grid position
            before taking the inner product.

    Returns:
        the inner product
    """
    mode1 = mode1.interpolate(interpolation)
    mode2 = mode2.interpolate(interpolation)

    mesh = mode1.mesh
    x = np.asarray(mesh.x_)
    y = np.asarray(mesh.y_)

    if conjugate:
        ex1, ey1 = mode1.Ex.conj(), mode1.Ey.conj()
        hx1, hy1 = mode1.Hx.conj(), mode1.Hy.conj()
    else:
        ex1, ey1 = mode1.Ex, mode1.Ey
        hx1, hy1 = mode1.Hx, mode1.Hy

    e1_cross_h2 = ex1 * mode2.Hy - ey1 * mode2.Hx
    if symmetric:
        h1_cross_e2 = hx1 * mode2.Ey - hy1 * mode2.Ex
        integrand = 0.25 * (e1_cross_h2 - h1_cross_e2)
    else:
        integrand = 0.5 * e1_cross_h2

    if ignore_pml:
        integrand, x, y = _crop_non_pml(mesh, integrand, x, y)

    arr = np.trapezoid(np.trapezoid(integrand, y), x)
    return float(np.real(arr)) + float(np.imag(arr)) * 1j

invert_mode

invert_mode(mode: Mode) -> Mode

Invert a Mode.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to invert.	required

Returns:

Type	Description
`Mode`	A new mode with all field components negated.

Source code in src/meow/mode.py

def invert_mode(mode: Mode) -> Mode:
    """Invert a `Mode`.

    Args:
        mode: the mode to invert.

    Returns:
        A new mode with all field components negated.
    """
    return Mode(
        neff=mode.neff,
        cs=mode.cs,
        Ex=-mode.Ex,
        Ey=-mode.Ey,
        Ez=-mode.Ez,
        Hx=-mode.Hx,
        Hy=-mode.Hy,
        Hz=-mode.Hz,
    )

is_lossy_mode

is_lossy_mode(
    mode: Mode, *, threshold: float = 1.0
) -> bool

Check whether a mode can be considered lossy.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to check.	required
`threshold`	`float`	imaginary neff value above which the mode is considered lossy.	`1.0`

Returns:

Type	Description
`bool`	True if the absolute imaginary part of neff exceeds the threshold.

Source code in src/meow/mode.py

def is_lossy_mode(mode: Mode, *, threshold: float = 1.0) -> bool:
    """Check whether a mode can be considered lossy.

    Args:
        mode: the mode to check.
        threshold: imaginary neff value above which the mode is considered lossy.

    Returns:
        True if the absolute imaginary part of neff exceeds the threshold.
    """
    return bool(abs(np.imag(mode.neff)) > threshold)

is_pml_mode

is_pml_mode(mode: Mode, *, threshold: float = 0.1) -> bool

Check whether a mode can be considered a PML mode.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to check.	required
`threshold`	`float`	PML energy fraction above which the mode is considered a PML mode.	`0.1`

Returns:

Type	Description
`bool`	True if the PML energy fraction exceeds the threshold.

Source code in src/meow/mode.py

def is_pml_mode(mode: Mode, *, threshold: float = 0.1) -> bool:
    """Check whether a mode can be considered a PML mode.

    Args:
        mode: the mode to check.
        threshold: PML energy fraction above which the mode is considered a PML mode.

    Returns:
        True if the PML energy fraction exceeds the threshold.
    """
    threshold = min(max(float(threshold), 0.0), 1.0)
    if threshold > 0.999:
        return False
    return abs(pml_fraction(mode)) > threshold

l2r_matrices

l2r_matrices(
    pairs: list[STypeMM],
    identity: SDenseMM,
    sax_backend: Backend,
) -> list[STypeMM]

Return cumulative left-to-right S-matrices.

Parameters:

Name	Type	Description	Default
`pairs`	`list[STypeMM]`	Propagation-interface pair S-matrices from `pi_pairs`.	required
`identity`	`SDenseMM`	Identity-like S-matrix used as the initial accumulator.	required
`sax_backend`	`Backend`	SAX backend used for cascading.	required

Returns:

Type	Description
`list[STypeMM]`	List of cumulative S-matrices from the left boundary up to each cell.

Source code in src/meow/eme/propagation.py

def l2r_matrices(
    pairs: list[sax.STypeMM], identity: sax.SDenseMM, sax_backend: sax.Backend
) -> list[sax.STypeMM]:
    """Return cumulative left-to-right S-matrices.

    Args:
        pairs: Propagation-interface pair S-matrices from ``pi_pairs``.
        identity: Identity-like S-matrix used as the initial accumulator.
        sax_backend: SAX backend used for cascading.

    Returns:
        List of cumulative S-matrices from the left boundary up to each cell.
    """
    matrices: list[sax.STypeMM] = [identity]
    for pair in pairs[:-1]:
        matrices.append(_connect_two(matrices[-1], pair, sax_backend))
    return matrices

magnetic_energy

magnetic_energy(mode: Mode) -> float

Get the magnetic energy contained in a Mode.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to compute the magnetic energy of.	required

Returns:

Type	Description
`float`	The total magnetic energy summed over the cross section.

Source code in src/meow/mode.py

def magnetic_energy(mode: Mode) -> float:
    """Get the magnetic energy contained in a `Mode`.

    Args:
        mode: the mode to compute the magnetic energy of.

    Returns:
        The total magnetic energy summed over the cross section.
    """
    return magnetic_energy_density(mode).sum()

magnetic_energy_density

magnetic_energy_density(
    mode: Mode,
) -> ndarray[tuple[int, int], dtype[float64]]

Get the magnetic energy density contained in a Mode.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to compute the magnetic energy density of.	required

Returns:

Type	Description
`ndarray[tuple[int, int], dtype[float64]]`	A 2D array of magnetic energy density values.

Source code in src/meow/mode.py

def magnetic_energy_density(
    mode: Mode,
) -> np.ndarray[tuple[int, int], np.dtype[np.float64]]:
    """Get the magnetic energy density contained in a `Mode`.

    Args:
        mode: the mode to compute the magnetic energy density of.

    Returns:
        A 2D array of magnetic energy density values.
    """
    return np.real(
        0.5 * mu0 * (np.abs(mode.Hx) ** 2 + np.abs(mode.Hy) ** 2 + np.abs(mode.Hz) ** 2)
    )

normalize

normalize(mode: Mode, inner_product: Callable) -> Mode

Normalize a Mode according to the inner_product with itself.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to normalize.	required
`inner_product`	`Callable`	a callable computing the inner product of two modes.	required

Returns:

Type	Description
`Mode`	A new mode normalized such that its self-inner-product is unity.

Source code in src/meow/mode.py

def normalize(mode: Mode, inner_product: Callable) -> Mode:
    """Normalize a `Mode` according to the `inner_product` with itself.

    Args:
        mode: the mode to normalize.
        inner_product: a callable computing the inner product of two modes.

    Returns:
        A new mode normalized such that its self-inner-product is unity.
    """
    factor = np.sqrt(inner_product(mode, mode))
    return Mode(
        neff=mode.neff,
        cs=mode.cs,
        Ex=mode.Ex / factor,
        Ey=mode.Ey / factor,
        Ez=mode.Ez / factor,
        Hx=mode.Hx / factor,
        Hy=mode.Hy / factor,
        Hz=mode.Hz / factor,
    )

normalize_energy

normalize_energy(mode: Mode) -> Mode

Normalize a mode according to the energy it contains.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to normalize.	required

Returns:

Type	Description
`Mode`	A new mode with fields scaled so that electric and magnetic energies are 0.5.

Source code in src/meow/mode.py

def normalize_energy(mode: Mode) -> Mode:
    """Normalize a mode according to the energy it contains.

    Args:
        mode: the mode to normalize.

    Returns:
        A new mode with fields scaled so that electric and magnetic energies are 0.5.
    """
    e = np.sqrt(2 * electric_energy(mode))
    h = np.sqrt(2 * magnetic_energy(mode))

    return Mode(
        neff=mode.neff,
        cs=mode.cs,
        Ex=mode.Ex / e,
        Ey=mode.Ey / e,
        Ez=mode.Ez / e,
        Hx=mode.Hx / h,
        Hy=mode.Hy / h,
        Hz=mode.Hz / h,
    )

normalize_modes

normalize_modes(
    modes: Modes, inner_product: Callable
) -> Modes

Self-normalize a set of modes.

This only fixes the norm of each mode individually. It does not make the mode set mutually orthogonal. For overlap-based interface formulas, use :func:orthonormalize_modes if you need the simplified G = I metric.

Parameters:

Name	Type	Description	Default
`modes`	`Modes`	the modes to normalize.	required
`inner_product`	`Callable`	callable computing the inner product between two modes.	required

Returns:

Type	Description
`Modes`	The normalized (and zero-phased) modes.

Source code in src/meow/fde/post_process.py

def normalize_modes(modes: Modes, inner_product: Callable) -> Modes:
    """Self-normalize a set of modes.

    This only fixes the norm of each mode individually. It does not make the
    mode set mutually orthogonal. For overlap-based interface formulas, use
    :func:`orthonormalize_modes` if you need the simplified ``G = I`` metric.

    Args:
        modes: the modes to normalize.
        inner_product: callable computing the inner product between two modes.

    Returns:
        The normalized (and zero-phased) modes.
    """
    return [zero_phase(normalize(m, inner_product)) for m in modes]

orthonormalize_modes

orthonormalize_modes(
    modes: Modes,
    inner_product: Callable,
    *,
    tolerance: float = 0.01,
) -> Modes

Gram-Schmidt orthonormalization with drop tolerance.

Parameters:

Name	Type	Description	Default
`modes`	`Modes`	the modes to orthonormalize	required
`inner_product`	`Callable`	the inner product to orthonormalize them under	required
`tolerance`	`float`	any mode that can't expand the basis beyond this tolerance will be dropped.	`0.01`

Returns:

Type	Description
`Modes`	Orthonormalized mode basis.

Notes

This routine first self-normalizes each mode and then applies Gram-Schmidt. The inner_product passed here should generally be the same one used later to build interface overlaps; otherwise the final basis is orthonormal in the wrong metric.

Source code in src/meow/fde/post_process.py

def orthonormalize_modes(
    modes: Modes,
    inner_product: Callable,
    *,
    tolerance: float = 0.01,
) -> Modes:
    """Gram-Schmidt orthonormalization with drop tolerance.

    Args:
        modes: the modes to orthonormalize
        inner_product: the inner product to orthonormalize them under
        tolerance: any mode that can't expand the basis beyond this tolerance
            will be dropped.

    Returns:
        Orthonormalized mode basis.

    Notes:
        This routine first self-normalizes each mode and then applies
        Gram-Schmidt. The ``inner_product`` passed here should generally be the
        same one used later to build interface overlaps; otherwise the final
        basis is orthonormal in the wrong metric.
    """
    if not modes:
        return []
    modes = normalize_modes(modes, inner_product)
    basis = []
    n_dropped = 0
    for mode in modes:
        current = mode
        for b in basis:
            current = current - (inner_product(b, current) / inner_product(b, b)) * b
        norm_sq = inner_product(current, current)
        if abs(norm_sq) < tolerance:
            n_dropped += 1
            continue
        basis.append(current / np.sqrt(norm_sq))
    return basis

overlap_matrix

overlap_matrix(
    modes1: Modes, modes2: Modes, inner_product: Callable
) -> ndarray[tuple[int, int], dtype[complex128]]

Build the modal overlap matrix between two mode sets.

The entry M[i, j] is inner_product(modes1[i], modes2[j]). In the interface derivation this is used both for self-overlaps (the metric G) and cross-overlaps between the left and right waveguide bases.

Sharp edge

The meaning of the overlap matrix is entirely determined by the inner_product callable. If modes were orthonormalized with one inner product but overlaps are formed with another, the simplified G = I interface formulas are no longer valid.

Parameters:

Name	Type	Description	Default
`modes1`	`Modes`	Left/test mode set.	required
`modes2`	`Modes`	Right/expansion mode set.	required
`inner_product`	`Callable`	Modal inner-product callable.	required

Returns:

Type	Description
`ndarray[tuple[int, int], dtype[complex128]]`	Complex overlap matrix of shape `(len(modes1), len(modes2))`.

Source code in src/meow/eme/interface.py

def overlap_matrix(
    modes1: Modes, modes2: Modes, inner_product: Callable
) -> np.ndarray[tuple[int, int], np.dtype[np.complex128]]:
    """Build the modal overlap matrix between two mode sets.

    The entry ``M[i, j]`` is ``inner_product(modes1[i], modes2[j])``. In the
    interface derivation this is used both for self-overlaps (the metric ``G``)
    and cross-overlaps between the left and right waveguide bases.

    Sharp edge:
        The meaning of the overlap matrix is entirely determined by the
        ``inner_product`` callable. If modes were orthonormalized with one
        inner product but overlaps are formed with another, the simplified
        ``G = I`` interface formulas are no longer valid.

    Args:
        modes1: Left/test mode set.
        modes2: Right/expansion mode set.
        inner_product: Modal inner-product callable.

    Returns:
        Complex overlap matrix of shape ``(len(modes1), len(modes2))``.
    """
    M = np.zeros((len(modes1), len(modes2)), dtype=np.complex128)
    for i, ma in enumerate(modes1):
        for j, mb in enumerate(modes2):
            M[i, j] = inner_product(ma, mb)
    return M

pi_pairs

pi_pairs(
    propagations: dict[str, SDictMM],
    interfaces: dict[str, SDenseMM],
    sax_backend: Backend,
) -> list[STypeMM]

Return propagation-interface pairs for a full stack.

Parameters:

Name	Type	Description	Default
`propagations`	`dict[str, SDictMM]`	Propagation S-matrices keyed by cell index.	required
`interfaces`	`dict[str, SDenseMM]`	Interface S-matrices keyed by adjacent cell pairs.	required
`sax_backend`	`Backend`	SAX backend used for cascading.	required

Returns:

Type	Description
`list[STypeMM]`	List of cascaded propagation-interface S-matrices, one per cell.

Source code in src/meow/eme/propagation.py

def pi_pairs(
    propagations: dict[str, sax.SDictMM],
    interfaces: dict[str, sax.SDenseMM],
    sax_backend: sax.Backend,
) -> list[sax.STypeMM]:
    """Return propagation-interface pairs for a full stack.

    Args:
        propagations: Propagation S-matrices keyed by cell index.
        interfaces: Interface S-matrices keyed by adjacent cell pairs.
        sax_backend: SAX backend used for cascading.

    Returns:
        List of cascaded propagation-interface S-matrices, one per cell.
    """
    pairs: list[sax.STypeMM] = []
    for i in range(len(propagations)):
        propagation = propagations[f"p_{i}"]
        if i == len(interfaces):
            pairs.append(propagation)
        else:
            pairs.append(
                _connect_two(propagation, interfaces[f"i_{i}_{i + 1}"], sax_backend)
            )
    return pairs

plot_fields

plot_fields(
    modes: list[list[Mode]],
    cells: list[Cell],
    forwards: list[ComplexArray1D],
    backwards: list[ComplexArray1D],
    y: float,
    z: FloatArray1D,
) -> tuple[ComplexArray2D, FloatArray1D]

Reconstruct an Ex(x, z) field slice from propagated modal amplitudes.

Parameters:

Name	Type	Description	Default
`modes`	`list[list[Mode]]`	Mode sets for each cell.	required
`cells`	`list[Cell]`	Cells defining the geometry and mesh.	required
`forwards`	`list[ComplexArray1D]`	Forward amplitude vectors per cell.	required
`backwards`	`list[ComplexArray1D]`	Backward amplitude vectors per cell.	required
`y`	`float`	Transverse y-coordinate at which to sample the field.	required
`z`	`FloatArray1D`	Global z-grid on which to reconstruct the field.	required

Returns:

Type	Description
`ComplexArray2D`	Tuple `(field, x)` where `field` is the complex `Ex(z, x)`
`FloatArray1D`	array and `x` is the transverse sampling grid.

Source code in src/meow/eme/propagation.py

def plot_fields(
    modes: list[list[Mode]],
    cells: list[Cell],
    forwards: list[ComplexArray1D],
    backwards: list[ComplexArray1D],
    y: float,
    z: FloatArray1D,
) -> tuple[ComplexArray2D, FloatArray1D]:
    """Reconstruct an ``Ex(x, z)`` field slice from propagated modal amplitudes.

    Args:
        modes: Mode sets for each cell.
        cells: Cells defining the geometry and mesh.
        forwards: Forward amplitude vectors per cell.
        backwards: Backward amplitude vectors per cell.
        y: Transverse y-coordinate at which to sample the field.
        z: Global z-grid on which to reconstruct the field.

    Returns:
        Tuple ``(field, x)`` where ``field`` is the complex ``Ex(z, x)``
        array and ``x`` is the transverse sampling grid.
    """
    mesh_y = cells[0].mesh.y
    mesh_x = cells[0].mesh.x
    mesh_x = mesh_x[:-1] + np.diff(mesh_x) / 2
    i_y = np.argmin(np.abs(mesh_y - y))

    e_tot = np.zeros((len(z), len(mesh_x)), dtype=complex)
    for mode_set, forward, backward, cell in zip(
        modes, forwards, backwards, cells, strict=False
    ):
        ex = np.array(0 + 0j)
        i_min = np.argmax(z >= cell.z_min)
        i_max = np.argmax(z > cell.z_max)
        z_ = z[i_min:] if i_max == 0 else z[i_min:i_max]
        z_local = z_ - cell.z_min
        for mode, fwd, bwd in zip(mode_set, forward, backward, strict=False):
            e_slice = mode.Ex[:, i_y]
            ex += jnp.outer(
                fwd * e_slice.T, jnp.exp(2j * np.pi * mode.neff / mode.env.wl * z_local)
            )
            ex += jnp.outer(
                bwd * e_slice.T,
                jnp.exp(-2j * np.pi * mode.neff / mode.env.wl * z_local),
            )

        if i_max == 0:
            e_tot[i_min:] = ex.T
        else:
            e_tot[i_min:i_max] = ex.T

    return e_tot, mesh_x

pml_fraction

pml_fraction(mode: Mode) -> float

Fraction of energy density in the PML region.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to evaluate.	required

Returns:

Type	Description
`float`	The fraction of total energy density located in the PML region (0.0 to 1.0).

Source code in src/meow/mode.py

def pml_fraction(mode: Mode) -> float:
    """Fraction of energy density in the PML region.

    Args:
        mode: the mode to evaluate.

    Returns:
        The fraction of total energy density located in the PML region (0.0 to 1.0).
    """
    numx, numy = mode.mesh.num_pml
    if numx == numy == 0:
        return 0.0
    ed = energy_density(mode)
    m, n = ed.shape
    lft = ed[:numx, :]
    rgt = ed[m - numx :, :]
    top = ed[numx : m - numx, :numy]
    btm = ed[numx : m - numx, n - numy :]
    rest = ed[numx : m - numx, numy : n - numy]
    pml_sum = lft.sum() + rgt.sum() + top.sum() + btm.sum()
    total = pml_sum + rest.sum()
    # probably propper integration considering
    # the size of the mesh cells would be better here
    return float(pml_sum / total) if total > 0 else 1.0

post_process_modes

post_process_modes(
    modes: Modes,
    inner_product: Callable = inner_product,
    gm_tolerance: float = 0.01,
) -> Modes

Default post-processing pipeline after FDE.

Parameters:

Name	Type	Description	Default
`modes`	`Modes`	the modes to post process	required
`inner_product`	`Callable`	the inner product with which to post-process the modes	`inner_product`
`gm_tolerance`	`float`	Gramm-Schmidt orthonormalization tolerance	`0.01`

Returns:

Type	Description
`Modes`	Filtered and orthonormalized modes.

Notes

This is the default post_process used by compute_modes. The choice of inner_product here matters downstream: if interface overlaps are later built with a different inner product, the resulting mode basis is no longer orthonormal in the interface metric.

Source code in src/meow/fde/post_process.py

def post_process_modes(
    modes: Modes,
    inner_product: Callable = inner_product,
    gm_tolerance: float = 0.01,
) -> Modes:
    """Default post-processing pipeline after FDE.

    Args:
        modes: the modes to post process
        inner_product: the inner product with which to post-process the modes
        gm_tolerance: Gramm-Schmidt orthonormalization tolerance

    Returns:
        Filtered and orthonormalized modes.

    Notes:
        This is the default ``post_process`` used by ``compute_modes``. The
        choice of ``inner_product`` here matters downstream: if interface
        overlaps are later built with a different inner product, the resulting
        mode basis is no longer orthonormal in the interface metric.
    """
    return orthonormalize_modes(
        filter_modes(modes),
        inner_product,
        tolerance=gm_tolerance,
    )

propagate

propagate(
    l2rs: list[STypeMM],
    r2ls: list[STypeMM],
    excitation_l: ComplexArray1D,
    excitation_r: ComplexArray1D,
) -> tuple[list[ComplexArray1D], list[ComplexArray1D]]

Propagate boundary excitations through cumulative S-matrices.

Parameters:

Name	Type	Description	Default
`l2rs`	`list[STypeMM]`	Cumulative left-to-right S-matrices for each cell.	required
`r2ls`	`list[STypeMM]`	Cumulative right-to-left S-matrices for each cell.	required
`excitation_l`	`ComplexArray1D`	Left boundary excitation vector.	required
`excitation_r`	`ComplexArray1D`	Right boundary excitation vector.	required

Returns:

Type	Description
`list[ComplexArray1D]`	Tuple `(forwards, backwards)` where each element is a list of
`list[ComplexArray1D]`	complex amplitude vectors, one per cell.

Source code in src/meow/eme/propagation.py

def propagate(
    l2rs: list[sax.STypeMM],
    r2ls: list[sax.STypeMM],
    excitation_l: ComplexArray1D,
    excitation_r: ComplexArray1D,
) -> tuple[list[ComplexArray1D], list[ComplexArray1D]]:
    """Propagate boundary excitations through cumulative S-matrices.

    Args:
        l2rs: Cumulative left-to-right S-matrices for each cell.
        r2ls: Cumulative right-to-left S-matrices for each cell.
        excitation_l: Left boundary excitation vector.
        excitation_r: Right boundary excitation vector.

    Returns:
        Tuple ``(forwards, backwards)`` where each element is a list of
        complex amplitude vectors, one per cell.
    """
    forwards = []
    backwards = []
    for l2r, r2l in zip(l2rs, r2ls, strict=False):
        s_l2r, pm_l2r = sax.sdense(l2r)
        s_r2l, pm_r2l = sax.sdense(r2l)
        ports_l2r = _sorted_ports(pm_l2r)
        ports_r2l = _sorted_ports(pm_r2l)
        s_l2r, _ = select_ports((s_l2r, pm_l2r), ports_l2r)
        s_r2l, _ = select_ports((s_r2l, pm_r2l), ports_r2l)
        n_right = len([key for key in ports_l2r if "right" in key])
        fwd, bwd = compute_mode_amplitudes(
            np.asarray(s_l2r), np.asarray(s_r2l), n_right, excitation_l, excitation_r
        )
        forwards.append(fwd)
        backwards.append(bwd)
    return forwards, backwards

propagate_modes

propagate_modes(
    modes: list[list[Mode]],
    cells: list[Cell],
    *,
    excitation_l: ComplexArray1D | None = None,
    excitation_r: ComplexArray1D | None = None,
    excite_mode_l: int = 0,
    excite_mode_r: int | None = None,
    y: float | None = None,
    z: FloatArray1D | None = None,
    num_z: int = 1000,
    sax_backend: BackendLike = "default",
    interface_kwargs: dict[str, Any] | None = None,
    track: bool = True,
    tracking_inner_product: Callable = inner_product,
    interfaces_fn: Callable = compute_interface_s_matrices,
    interface_fn: Callable = compute_interface_s_matrix,
) -> tuple[ComplexArray2D, FloatArray1D]

Propagate modal excitations through a stack of cells.

This is a convenience wrapper around the propagation and interface S-matrix machinery. The only required positional inputs are the modal bases and the cells. Everything else has defaults that are inferred from the stack:

by default the left boundary excites mode 0 with unit amplitude;
by default there is no right-side excitation;
by default y is the center of the transverse mesh;
by default z spans the full device with num_z samples.

Parameters:

Name	Type	Description	Default
`modes`	`list[list[Mode]]`	Mode set for each cell.	required
`cells`	`list[Cell]`	Cells associated with `modes`.	required
`excitation_l`	`ComplexArray1D \| None`	Optional explicit left excitation vector.	`None`
`excitation_r`	`ComplexArray1D \| None`	Optional explicit right excitation vector.	`None`
`excite_mode_l`	`int`	Left mode to excite if `excitation_l` is omitted.	`0`
`excite_mode_r`	`int \| None`	Right mode to excite if `excitation_r` is omitted. If omitted, no right-side excitation is applied.	`None`
`y`	`float \| None`	Transverse y-coordinate at which to reconstruct `Ex`.	`None`
`z`	`FloatArray1D \| None`	Global z-grid on which to reconstruct the field.	`None`
`num_z`	`int`	Number of z samples if `z` is omitted.	`1000`
`sax_backend`	`BackendLike`	SAX backend used for cascading.	`'default'`
`interface_kwargs`	`dict[str, Any] \| None`	Optional keyword arguments forwarded to both `interfaces_fn` and `interface_fn`.	`None`
`track`	`bool`	Whether to reorder and phase-align modes between neighboring cells before propagation.	`True`
`tracking_inner_product`	`Callable`	Inner product used for mode tracking.	`inner_product`
`interfaces_fn`	`Callable`	Factory for interface S-matrices across the stack.	`compute_interface_s_matrices`
`interface_fn`	`Callable`	Factory for the identity-like same-basis interface used to seed the left-to-right accumulation.	`compute_interface_s_matrix`

Returns:

Type	Description
`ComplexArray2D`	`(field, x)` where `field` is the reconstructed `Ex(z, x)` slice
`FloatArray1D`	and `x` is the transverse sampling grid.

Source code in src/meow/eme/propagation.py

def propagate_modes(
    modes: list[list[Mode]],
    cells: list[Cell],
    *,
    excitation_l: ComplexArray1D | None = None,
    excitation_r: ComplexArray1D | None = None,
    excite_mode_l: int = 0,
    excite_mode_r: int | None = None,
    y: float | None = None,
    z: FloatArray1D | None = None,
    num_z: int = 1000,
    sax_backend: sax.BackendLike = "default",
    interface_kwargs: dict[str, Any] | None = None,
    track: bool = True,
    tracking_inner_product: Callable = inner_product,
    interfaces_fn: Callable = compute_interface_s_matrices,
    interface_fn: Callable = compute_interface_s_matrix,
) -> tuple[ComplexArray2D, FloatArray1D]:
    """Propagate modal excitations through a stack of cells.

    This is a convenience wrapper around the propagation and interface S-matrix
    machinery. The only required positional inputs are the modal bases and the
    cells. Everything else has defaults that are inferred from the stack:

    - by default the left boundary excites mode 0 with unit amplitude;
    - by default there is no right-side excitation;
    - by default ``y`` is the center of the transverse mesh;
    - by default ``z`` spans the full device with ``num_z`` samples.

    Args:
        modes: Mode set for each cell.
        cells: Cells associated with ``modes``.
        excitation_l: Optional explicit left excitation vector.
        excitation_r: Optional explicit right excitation vector.
        excite_mode_l: Left mode to excite if ``excitation_l`` is omitted.
        excite_mode_r: Right mode to excite if ``excitation_r`` is omitted. If
            omitted, no right-side excitation is applied.
        y: Transverse y-coordinate at which to reconstruct ``Ex``.
        z: Global z-grid on which to reconstruct the field.
        num_z: Number of z samples if ``z`` is omitted.
        sax_backend: SAX backend used for cascading.
        interface_kwargs: Optional keyword arguments forwarded to both
            ``interfaces_fn`` and ``interface_fn``.
        track: Whether to reorder and phase-align modes between neighboring
            cells before propagation.
        tracking_inner_product: Inner product used for mode tracking.
        interfaces_fn: Factory for interface S-matrices across the stack.
        interface_fn: Factory for the identity-like same-basis interface used to
            seed the left-to-right accumulation.

    Returns:
        ``(field, x)`` where ``field`` is the reconstructed ``Ex(z, x)`` slice
        and ``x`` is the transverse sampling grid.
    """
    if len(cells) != len(modes):
        msg = f"len(cells) != len(modes): {len(cells)} != {len(modes)}"
        raise ValueError(msg)
    if not cells:
        msg = "At least one cell is required."
        raise ValueError(msg)

    actual_sax_backend = sax.into[sax.Backend](sax_backend)
    interface_kwargs = dict(interface_kwargs or {})
    interface_kwargs.setdefault("enforce_reciprocity", False)

    if excitation_l is None:
        excitation_l = _default_excitation(len(modes[0]), excite_mode_l)
    if excitation_r is None:
        if excite_mode_r is None:
            excitation_r = np.zeros(len(modes[-1]), dtype=complex)
        else:
            excitation_r = _default_excitation(len(modes[-1]), excite_mode_r)

    if y is None:
        y = float(0.5 * (cells[0].mesh.y.min() + cells[0].mesh.y.max()))
    if z is None:
        z = _default_z(cells, num_z)

    tracked_modes = (
        track_modes(modes, inner_product_fn=tracking_inner_product) if track else modes
    )

    propagations = compute_propagation_s_matrices(tracked_modes, cells)
    interfaces = interfaces_fn(tracked_modes, **interface_kwargs)
    identity = interface_fn(tracked_modes[0], tracked_modes[0], **interface_kwargs)

    pairs = pi_pairs(propagations, interfaces, actual_sax_backend)
    l2rs = l2r_matrices(pairs, identity, actual_sax_backend)
    r2ls = r2l_matrices(pairs, actual_sax_backend)

    forwards, backwards = propagate(l2rs, r2ls, excitation_l, excitation_r)
    return plot_fields(tracked_modes, cells, forwards, backwards, y, z)

r2l_matrices

r2l_matrices(
    pairs: list[STypeMM], sax_backend: Backend
) -> list[STypeMM]

Return cumulative right-to-left S-matrices.

Parameters:

Name	Type	Description	Default
`pairs`	`list[STypeMM]`	Propagation-interface pair S-matrices from `pi_pairs`.	required
`sax_backend`	`Backend`	SAX backend used for cascading.	required

Returns:

Type	Description
`list[STypeMM]`	List of cumulative S-matrices from each cell to the right boundary.

Source code in src/meow/eme/propagation.py

def r2l_matrices(
    pairs: list[sax.STypeMM], sax_backend: sax.Backend
) -> list[sax.STypeMM]:
    """Return cumulative right-to-left S-matrices.

    Args:
        pairs: Propagation-interface pair S-matrices from ``pi_pairs``.
        sax_backend: SAX backend used for cascading.

    Returns:
        List of cumulative S-matrices from each cell to the right boundary.
    """
    matrices = [pairs[-1]]
    for pair in pairs[-2::-1]:
        matrices.append(_connect_two(pair, matrices[-1], sax_backend))
    return matrices[::-1]

select_ports

select_ports(S: SDenseMM, ports: list[str]) -> SDenseMM

Keep a subset of ports from an S-matrix.

Parameters:

Name	Type	Description	Default
`S`	`SDenseMM`	A tuple `(s_matrix, port_map)` in SAX dense multimode format.	required
`ports`	`list[str]`	Port names to retain.	required

Returns:

Type	Description
`SDenseMM`	A new `(s_matrix, port_map)` tuple with only the selected ports.

Source code in src/meow/eme/propagation.py

def select_ports(S: sax.SDenseMM, ports: list[str]) -> sax.SDenseMM:
    """Keep a subset of ports from an S-matrix.

    Args:
        S: A tuple ``(s_matrix, port_map)`` in SAX dense multimode format.
        ports: Port names to retain.

    Returns:
        A new ``(s_matrix, port_map)`` tuple with only the selected ports.
    """
    s, pm = S
    idxs = jnp.array([pm[port] for port in ports], dtype=jnp.int32)
    s = s[idxs, :][:, idxs]
    new_port_map = {p: i for i, p in enumerate(ports)}
    return s, new_port_map

sort_structures

sort_structures(
    structures: list[Structure3D],
) -> list[Structure3D]

sort_structures(
    structures: list[Structure2D],
) -> list[Structure2D]

sort_structures(
    structures: list[Structure3D] | list[Structure2D],
) -> list[Structure2D] | list[Structure3D]

Sort structures by mesh order, then by order of definition.

Parameters:

Name	Type	Description	Default
`structures`	`list[Structure3D] \| list[Structure2D]`	the list of structures to sort.	required

Returns:

Type	Description
`list[Structure2D] \| list[Structure3D]`	A new list of structures sorted by descending mesh order.

Source code in src/meow/structures.py

def sort_structures(
    structures: list[Structure3D] | list[Structure2D],
) -> list[Structure2D] | list[Structure3D]:
    """Sort structures by mesh order, then by order of definition.

    Args:
        structures: the list of structures to sort.

    Returns:
        A new list of structures sorted by descending mesh order.
    """
    struct_info = [(s.mesh_order, -i, s) for i, s in enumerate(structures)]
    sorted_struct_info = sorted(struct_info, key=lambda I: (I[0], I[1]), reverse=True)
    return cast(
        list[Structure2D] | list[Structure3D], [s for _, _, s in sorted_struct_info]
    )

split_square_matrix

split_square_matrix(
    matrix: ComplexArray2D, idx: int
) -> tuple[
    tuple[ComplexArray2D, ComplexArray2D],
    tuple[ComplexArray2D, ComplexArray2D],
]

Split a square matrix into its four block submatrices.

Parameters:

Name	Type	Description	Default
`matrix`	`ComplexArray2D`	Square matrix to split.	required
`idx`	`int`	Row/column index at which to split.	required

Returns:

Type	Description
`tuple[tuple[ComplexArray2D, ComplexArray2D], tuple[ComplexArray2D, ComplexArray2D]]`	Nested tuple `((top_left, top_right), (bottom_left, bottom_right))`.

Source code in src/meow/eme/propagation.py

def split_square_matrix(
    matrix: ComplexArray2D, idx: int
) -> tuple[
    tuple[ComplexArray2D, ComplexArray2D], tuple[ComplexArray2D, ComplexArray2D]
]:
    """Split a square matrix into its four block submatrices.

    Args:
        matrix: Square matrix to split.
        idx: Row/column index at which to split.

    Returns:
        Nested tuple ``((top_left, top_right), (bottom_left, bottom_right))``.
    """
    if matrix.shape[0] != matrix.shape[1]:
        msg = "Matrix has to be square."
        raise ValueError(msg)
    return (matrix[:idx, :idx], matrix[:idx, idx:]), (
        matrix[idx:, :idx],
        matrix[idx:, idx:],
    )

te_fraction

te_fraction(mode: Mode) -> float

The TE polarization fraction of the Mode.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to compute the TE fraction of.	required

Returns:

Type	Description
`float`	The TE fraction (0.0 for pure TM, 1.0 for pure TE).

Source code in src/meow/mode.py

def te_fraction(mode: Mode) -> float:
    """The TE polarization fraction of the `Mode`.

    Args:
        mode: the mode to compute the TE fraction of.

    Returns:
        The TE fraction (0.0 for pure TM, 1.0 for pure TE).
    """
    epsx = np.real(mode.cs.nx**2)
    e = np.sum(0.5 * eps0 * epsx * np.abs(mode.Ex) ** 2)
    h = np.sum(0.5 * mu0 * np.abs(mode.Hx) ** 2)
    return float(e / (e + h))

track_modes

track_modes(
    modes: list[Modes],
    *,
    inner_product_fn: Callable = inner_product,
) -> list[Modes]

Track modal order and phase continuously across a cell stack.

Modes are solved independently in each cell, so neighboring cells may differ by permutation and arbitrary complex phase. This helper reorders each mode set by maximum overlap with the previous cell and phase-aligns matched modes so that the tracking overlap is real-positive.

Unmatched modes are appended after the matched subset in their original order. This function does not change the physics of the interface solve; it only makes the local basis more continuous for reconstruction and plotting.

Parameters:

Name	Type	Description	Default
`modes`	`list[Modes]`	Ordered list of modal bases across the stack.	required
`inner_product_fn`	`Callable`	Inner-product callable used to compute overlaps between neighboring mode sets.	`inner_product`

Returns:

Type	Description
`list[Modes]`	Reordered and phase-aligned list of modal bases.

Source code in src/meow/eme/propagation.py

def track_modes(
    modes: list[Modes],
    *,
    inner_product_fn: Callable = inner_product,
) -> list[Modes]:
    """Track modal order and phase continuously across a cell stack.

    Modes are solved independently in each cell, so neighboring cells may differ
    by permutation and arbitrary complex phase. This helper reorders each mode
    set by maximum overlap with the previous cell and phase-aligns matched modes
    so that the tracking overlap is real-positive.

    Unmatched modes are appended after the matched subset in their original
    order. This function does not change the physics of the interface solve; it
    only makes the local basis more continuous for reconstruction and plotting.

    Args:
        modes: Ordered list of modal bases across the stack.
        inner_product_fn: Inner-product callable used to compute overlaps
            between neighboring mode sets.

    Returns:
        Reordered and phase-aligned list of modal bases.
    """
    if not modes:
        return []

    tracked: list[Modes] = [list(modes[0])]
    for current in modes[1:]:
        previous = tracked[-1]
        n_prev = len(previous)
        n_curr = len(current)
        if n_prev == 0 or n_curr == 0:
            tracked.append(list(current))
            continue

        overlaps = np.zeros((n_prev, n_curr), dtype=np.complex128)
        for i, mode_prev in enumerate(previous):
            for j, mode_curr in enumerate(current):
                overlaps[i, j] = inner_product_fn(mode_prev, mode_curr)

        row_ind, col_ind = linear_sum_assignment(-np.abs(overlaps))
        matched_cols = set(col_ind.tolist())

        reordered: list[Mode] = []
        for i, j in sorted(
            zip(row_ind, col_ind, strict=True), key=lambda pair: pair[0]
        ):
            overlap = overlaps[i, j]
            if np.abs(overlap) > 0:
                phase = np.exp(-1j * np.angle(overlap))
                reordered.append(current[j] * phase)
            else:
                reordered.append(current[j])

        reordered.extend(
            mode for j, mode in enumerate(current) if j not in matched_cols
        )
        tracked.append(reordered)

    return tracked

tsvd_solve

tsvd_solve(
    A: ndarray, B: ndarray, rcond: float = 0.001
) -> tuple[ndarray, ndarray, float, float]

Solve A X = B with a truncated-SVD pseudoinverse.

This is the regularized solve used by the EME interface construction. The smallest singular directions of A are the first place where truncated mode sets become numerically unstable, so the solve is performed as

X = pinv_tsvd(A) @ B

with a relative cutoff

s_cut = rcond * s_max.

Singular values below s_cut are discarded entirely.

High-level behavior

small rcond keeps more singular directions and is closer to the exact inverse, but is more sensitive to ill-conditioning;
large rcond drops more singular directions and is more stable, but biases the result towards a lower-rank approximation.

This routine does not enforce passivity by itself. It only stabilizes the linear inversion. Passivity is handled afterwards on the assembled interface S-matrix.

Parameters:

Name	Type	Description	Default
`A`	`ndarray`	System matrix to invert approximately.	required
`B`	`ndarray`	Right-hand side.	required
`rcond`	`float`	Relative singular-value cutoff. Singular values smaller than `rcond * max(s)` are discarded.	`0.001`

Returns:

Type	Description
`ndarray`	A tuple `(X, s, s_cut, rank_kept)` containing the solved result,
`ndarray`	the singular values of `A`, the absolute cutoff, and the number of
`float`	retained singular directions.

Raises:

Type	Description
`RuntimeError`	If all singular values are rejected.

Source code in src/meow/eme/solve.py

def tsvd_solve(
    A: np.ndarray, B: np.ndarray, rcond: float = 1e-3
) -> tuple[np.ndarray, np.ndarray, float, float]:
    """Solve ``A X = B`` with a truncated-SVD pseudoinverse.

    This is the regularized solve used by the EME interface construction. The
    smallest singular directions of ``A`` are the first place where truncated
    mode sets become numerically unstable, so the solve is performed as

    ``X = pinv_tsvd(A) @ B``

    with a relative cutoff

    ``s_cut = rcond * s_max``.

    Singular values below ``s_cut`` are discarded entirely.

    High-level behavior:
        - small ``rcond`` keeps more singular directions and is closer to the
          exact inverse, but is more sensitive to ill-conditioning;
        - large ``rcond`` drops more singular directions and is more stable,
          but biases the result towards a lower-rank approximation.

    This routine does not enforce passivity by itself. It only stabilizes the
    linear inversion. Passivity is handled afterwards on the assembled
    interface S-matrix.

    Args:
        A: System matrix to invert approximately.
        B: Right-hand side.
        rcond: Relative singular-value cutoff. Singular values smaller than
            ``rcond * max(s)`` are discarded.

    Returns:
        A tuple ``(X, s, s_cut, rank_kept)`` containing the solved result,
        the singular values of ``A``, the absolute cutoff, and the number of
        retained singular directions.

    Raises:
        RuntimeError: If all singular values are rejected.
    """
    U, s, Vh = np.linalg.svd(A, full_matrices=False)
    s_cut = rcond * float(s[0]) if s.size else 0.0
    keep = s >= s_cut
    if not np.any(keep):
        msg = "TSVD rejected all singular values; lower rcond."
        raise RuntimeError(msg)
    A_pinv = (Vh.conj().T[:, keep] * (1.0 / s[keep])) @ U.conj().T[keep, :]
    X = A_pinv @ B
    return X, s, s_cut, int(np.count_nonzero(keep))

visualize

visualize(obj: Any, **kwargs: Any) -> Any

Visualize any meow object.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	the meow object to visualize	required
`**kwargs`	`Any`	extra configuration to visualize the object	`{}`

Returns:

Type	Description
`Any`	The result of the visualization function for the given object.

Note

Most meow objects have a ._visualize method. Check out its help to see which kwargs are accepted.

Source code in src/meow/visualization.py

def visualize(obj: Any, **kwargs: Any) -> Any:
    """Visualize any meow object.

    Args:
        obj: the meow object to visualize
        **kwargs: extra configuration to visualize the object

    Returns:
        The result of the visualization function for the given object.

    Note:
        Most meow objects have a `._visualize` method.
        Check out its help to see which kwargs are accepted.
    """
    try:
        is_empty = bool(not obj)
    except ValueError:
        is_empty = isinstance(obj, np.ndarray) and obj.size == 0

    if is_empty:
        msg = "Nothing to visualize!"
        raise ValueError(msg)

    vis_func = _get_vis_func(obj)
    vis_func(obj, **kwargs)

zero_phase

zero_phase(mode: Mode) -> Mode

Normalize (zero out) the phase of a Mode.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	the mode to normalize the phase of.	required

Returns:

Type	Description
`Mode`	A new mode with zeroed-out phase.

Source code in src/meow/mode.py

def zero_phase(mode: Mode) -> Mode:
    """Normalize (zero out) the phase of a `Mode`.

    Args:
        mode: the mode to normalize the phase of.

    Returns:
        A new mode with zeroed-out phase.
    """
    e = np.abs(energy_density(mode))
    m, n = np.array(np.where(e == e.max()))[:, 0]
    phase = np.exp(-1j * np.angle(np.array(mode.Hx))[m][n])
    new_mode = Mode(
        neff=mode.neff,
        cs=mode.cs,
        Ex=mode.Ex * phase,
        Ey=mode.Ey * phase,
        Ez=mode.Ez * phase,
        Hx=mode.Hx * phase,
        Hy=mode.Hy * phase,
        Hz=mode.Hz * phase,
    )
    if _sum_around(np.real(new_mode.Hx), int(m), int(n)) < 0:
        new_mode = invert_mode(new_mode)
    return new_mode

algorithm changelog

On This Page

api

meow

AxisDirection module-attribute

BoolArray1D module-attribute

BoolArray2D module-attribute

Complex module-attribute

ComplexArray1D module-attribute

ComplexArray2D module-attribute

FloatArray1D module-attribute

FloatArray2D module-attribute

Geometry module-attribute

Geometry2D module-attribute

Geometry3D module-attribute

IntArray1D module-attribute

IntArray2D module-attribute

Material module-attribute

Materials module-attribute

Modes module-attribute

NDArray module-attribute

PassivityMethod module-attribute

Sim module-attribute

BaseModel

model_validate classmethod

model_validate_json classmethod

Box

model_validate classmethod

model_validate_json classmethod

Cell

length property

z property

m_full

materials

model_validate classmethod

model_validate_json classmethod

structures_2d

CrossSection

from_cell classmethod

materials

model_validate classmethod

model_validate_json classmethod

n_full

nx

ny

nz

Environment

model_validate classmethod

model_validate_json classmethod

GdsExtrusionRule

model_validate classmethod

model_validate_json classmethod

Geometry2DBase

model_validate classmethod

model_validate_json classmethod

Geometry3DBase

model_validate classmethod

model_validate_json classmethod

IndexMaterial

model_validate classmethod

model_validate_json classmethod

MaterialBase

model_validate classmethod

model_validate_json classmethod

Mesh2D

X_full property

Xx property

Xy property

Xz property

Xz_ property

Y_full property

Yx property

Yy property

Yz property

Yz_ property

XY_full

dx

dy

model_validate classmethod

model_validate_json classmethod

x_

x_full

AxisDirection `module-attribute`

BoolArray1D `module-attribute`

BoolArray2D `module-attribute`

Complex `module-attribute`

ComplexArray1D `module-attribute`

ComplexArray2D `module-attribute`

FloatArray1D `module-attribute`

FloatArray2D `module-attribute`

Geometry `module-attribute`

Geometry2D `module-attribute`

Geometry3D `module-attribute`

IntArray1D `module-attribute`

IntArray2D `module-attribute`

Material `module-attribute`

Materials `module-attribute`

Modes `module-attribute`

NDArray `module-attribute`

PassivityMethod `module-attribute`

Sim `module-attribute`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

length `property`

z `property`

model_validate `classmethod`

model_validate_json `classmethod`

from_cell `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

X_full `property`

Xx `property`

Xy `property`

Xz `property`

Xz_ `property`

Y_full `property`

Yx `property`

Yy `property`

Yz `property`

Yz_ `property`

model_validate `classmethod`

model_validate_json `classmethod`

Px `property`

Py `property`

Pz `property`

env `property`

mesh `property`

te_fraction `property`

load `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

from_df `classmethod`

from_path `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

from_array `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`

model_validate `classmethod`

model_validate_json `classmethod`