Skip to main content

omnibias.core.transfer

0.5.0rc1Release candidatePython >=3.10Apache-2.0

Coefficient recurrences, activation contracts, jet algebra, and verified arithmetic shared by the numerical backends.

import omnibias.core.transfer
Module contract & mathematical conventions

1-D layered transfer matrices (theory 02-11).

One-dimensional layered propagation only. unitarity_residual is refused outside lossless reciprocal linear media. Certified gaps set continuum_claim=False.

Shared formulas do not imply universal floating-point identity. Verify dtype, shape, derivative-order support, and the stated numerical assumptions for the path you use.

CLASS

BandGapCertificate​

omnibias.core.transfer.BandGapCertificateSource ↗
class BandGapCertificate

Dataclass constructor fields; inherited fields, if any, are declared by the base class. A field(...) expression describes a default factory or field options, not a literal argument default.

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

NameType & defaultContract
omega_lodataclass fieldfloatRequiredSee the operation contract and implementation below.
omega_hidataclass fieldfloatRequiredSee the operation contract and implementation below.
trace_half_lodataclass fieldfloatRequiredSee the operation contract and implementation below.
trace_half_hidataclass fieldfloatRequiredSee the operation contract and implementation below.
is_gapdataclass fieldboolRequiredSee the operation contract and implementation below.
continuum_claimdataclass fieldboolDefault: FalseSee the operation contract and implementation below.

Fields & methods

omega_lofield
omega_lo: float

Declared float field on BandGapCertificate. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗
omega_hifield
omega_hi: float

Declared float field on BandGapCertificate. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗
trace_half_lofield
trace_half_lo: float

Declared float field on BandGapCertificate. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗
trace_half_hifield
trace_half_hi: float

Declared float field on BandGapCertificate. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗
is_gapfield
is_gap: bool

Declared bool field on BandGapCertificate. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗
continuum_claimfield
continuum_claim: bool = False

Declared bool field on BandGapCertificate. Default expression: False.

View source ↗
is_soundproperty
is_sound(self) -> bool

See the class contract above and the exact method implementation below.

Returns: bool

Method implementation
    def is_sound(self) -> bool:
        return True
View source ↗
Read the implementation
class BandGapCertificate:
    omega_lo: float
    omega_hi: float
    trace_half_lo: float
    trace_half_hi: float
    is_gap: bool
    continuum_claim: bool = False

    @property
    def is_sound(self) -> bool:
        return True
CLASS

Layer​

omnibias.core.LayerSource ↗
class Layer

Dataclass constructor fields; inherited fields, if any, are declared by the base class. A field(...) expression describes a default factory or field options, not a literal argument default.

A homogeneous slab. index is refractive index (or wave speed inverse).

Parameters

NameType & defaultContract
indexdataclass fieldcomplexRequiredSee the operation contract and implementation below.
thicknessdataclass fieldfloatRequiredSee the operation contract and implementation below.
Executed regression · g2 quarter wave midgap

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g2_quarter_wave_midgap() -> None:
    cell = quarter_wave_stack(2.0, 1.0, n_periods=1, omega0=1.0)
    mid = abs(bloch_dispersion(cell, 1.0))
    assert mid > 1.0
python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -q
Regression example · unitarity refused when lossy

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_unitarity_refused_when_lossy() -> None:
    with pytest.raises(ValueError, match="lossless"):
        unitarity_residual(stack_matrix((Layer(1.5 + 0.1j, 0.2),), 1.0), lossless=False)
python -m pytest packages/omnibias-core/tests/test_transfer.py -k test_unitarity_refused_when_lossy -q

Fields & methods

indexfield
index: complex

Declared complex field on Layer. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗
thicknessfield
thickness: float

Declared float field on Layer. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗
__post_init__method
__post_init__(self) -> None

See the class contract above and the exact method implementation below.

Returns: None

Validation & failure cases
  • When self.thickness < 0.0, raises ValueError('thickness must be >= 0').
Executed regression · g2 quarter wave midgap

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g2_quarter_wave_midgap() -> None:
    cell = quarter_wave_stack(2.0, 1.0, n_periods=1, omega0=1.0)
    mid = abs(bloch_dispersion(cell, 1.0))
    assert mid > 1.0
python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -q
Method implementation
    def __post_init__(self) -> None:
        if self.thickness < 0.0:
            raise ValueError("thickness must be >= 0")
View source ↗
Read the implementation
class Layer:
    """A homogeneous slab. ``index`` is refractive index (or wave speed inverse)."""

    index: complex
    thickness: float

    def __post_init__(self) -> None:
        if self.thickness < 0.0:
            raise ValueError("thickness must be >= 0")
Other public import paths
  • omnibias.core.Layer
  • omnibias.core.transfer.Layer
CONSTANT

Matrix2​

omnibias.core.transfer.Matrix2Source ↗
Matrix2 = tuple[tuple[complex, complex], tuple[complex, complex]]

This exported constant is defined by the expression above. Its exact value and annotation come from the pinned source; use it with the module contract.

Read the implementation
Matrix2 = tuple[tuple[complex, complex], tuple[complex, complex]]
FUNCTION

bloch_dispersion​

omnibias.core.transfer.bloch_dispersionSource ↗
bloch_dispersion(cell: Sequence[Layer], omega: float) -> float

(1/2) Re tr M_cell; |value| <= 1 is a pass band of the infinite stack.

Parameters

NameType & defaultContract
cellpositional-or-keywordSequence[Layer]RequiredSee the operation contract and implementation below.
omegapositional-or-keywordfloatRequiredSee the operation contract and implementation below.
Returnsfloat
Executed regression · g2 quarter wave midgap

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g2_quarter_wave_midgap() -> None:
    cell = quarter_wave_stack(2.0, 1.0, n_periods=1, omega0=1.0)
    mid = abs(bloch_dispersion(cell, 1.0))
    assert mid > 1.0
python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -q
Regression example · g3 certified gap sound

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g3_certified_gap_sound() -> None:
    cell = quarter_wave_stack(2.3, 1.0, n_periods=1, omega0=1.0)
    cert = certified_band_gap(cell, omega_range=(0.85, 1.15), n_grid=48)
    assert cert.continuum_claim is False
    xs = [0.85 + (1.15 - 0.85) * i / 80 for i in range(81)]
    vals = [abs(bloch_dispersion(cell, w)) for w in xs]
    if cert.is_gap:
        assert min(vals) >= 1.0 - 1e-9
    assert cert.trace_half_lo <= min(vals) + 1e-9
    assert cert.trace_half_hi + 1e-9 >= max(vals)
python -m pytest packages/omnibias-core/tests/test_transfer.py -k test_g3_certified_gap_sound -q
Read the implementation
def bloch_dispersion(cell: Sequence[Layer], omega: float) -> float:
    """``(1/2) Re tr M_cell``; ``|value| <= 1`` is a pass band of the infinite stack."""
    m = stack_matrix(cell, omega)
    return 0.5 * (m[0][0] + m[1][1]).real
FUNCTION

certified_band_gap​

omnibias.core.certified_band_gapSource ↗
certified_band_gap(cell: Sequence[Layer], *, omega_range: tuple[float, float], n_grid: int=64) -> BandGapCertificate

Interval enclosure of |tr M|/2 over omega_range.

continuum_claim is always False: this is a finite stack / finite frequency sample, not an infinite-crystal theorem.

Parameters

NameType & defaultContract
cellpositional-or-keywordSequence[Layer]RequiredSee the operation contract and implementation below.
omega_rangekeyword-onlytuple[float, float]RequiredSee the operation contract and implementation below.
n_gridkeyword-onlyintDefault: 64See the operation contract and implementation below.
ReturnsBandGapCertificate
Explicit validation & failure cases
  • When hi <= lo, raises ValueError('omega_range must be an ordered interval').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · g3 certified gap sound

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g3_certified_gap_sound() -> None:
    cell = quarter_wave_stack(2.3, 1.0, n_periods=1, omega0=1.0)
    cert = certified_band_gap(cell, omega_range=(0.85, 1.15), n_grid=48)
    assert cert.continuum_claim is False
    xs = [0.85 + (1.15 - 0.85) * i / 80 for i in range(81)]
    vals = [abs(bloch_dispersion(cell, w)) for w in xs]
    if cert.is_gap:
        assert min(vals) >= 1.0 - 1e-9
    assert cert.trace_half_lo <= min(vals) + 1e-9
    assert cert.trace_half_hi + 1e-9 >= max(vals)
python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g3_certified_gap_sound" -q
Read the implementation
def certified_band_gap(
    cell: Sequence[Layer],
    *,
    omega_range: tuple[float, float],
    n_grid: int = 64,
) -> BandGapCertificate:
    """Interval enclosure of ``|tr M|/2`` over ``omega_range``.

    ``continuum_claim`` is always ``False``: this is a finite stack / finite
    frequency sample, not an infinite-crystal theorem.
    """
    lo, hi = float(omega_range[0]), float(omega_range[1])
    if hi <= lo:
        raise ValueError("omega_range must be an ordered interval")
    samples = [lo + (hi - lo) * i / (n_grid - 1) for i in range(n_grid)]
    vals = [abs(bloch_dispersion(cell, w)) for w in samples]
    # Crude variation: neighbour difference as an interval padding.
    pad = 0.0
    for a, b in zip(vals, vals[1:], strict=False):
        pad = max(pad, abs(a - b))
    iv = Interval(min(vals) - pad, max(vals) + pad)
    return BandGapCertificate(
        omega_lo=lo,
        omega_hi=hi,
        trace_half_lo=float(iv.lo),
        trace_half_hi=float(iv.hi),
        is_gap=bool(iv.lo > 1.0),
        continuum_claim=False,
    )
Other public import paths
  • omnibias.core.certified_band_gap
  • omnibias.core.transfer.certified_band_gap
FUNCTION

interface_matrix​

omnibias.core.transfer.interface_matrixSource ↗
interface_matrix(n_lo: complex, n_hi: complex) -> Matrix2

Continuity of E and H at a dielectric interface (normal incidence).

Parameters

NameType & defaultContract
n_lopositional-or-keywordcomplexRequiredSee the operation contract and implementation below.
n_hipositional-or-keywordcomplexRequiredSee the operation contract and implementation below.
ReturnsMatrix2
Read the implementation
def interface_matrix(n_lo: complex, n_hi: complex) -> Matrix2:
    """Continuity of E and H at a dielectric interface (normal incidence)."""
    # Maps amplitude basis (E+, E-) through the interface.
    # E, H continuous: E+ + E- and n(E+ - E-).
    a = (n_hi + n_lo) / (2.0 * n_hi)
    b = (n_hi - n_lo) / (2.0 * n_hi)
    return ((a, b), (b, a))
FUNCTION

layer_matrix​

omnibias.core.transfer.layer_matrixSource ↗
layer_matrix(layer: Layer, omega: float) -> Matrix2

Characteristic matrix of a homogeneous slab (det = 1 when lossless).

Parameters

NameType & defaultContract
layerpositional-or-keywordLayerRequiredSee the operation contract and implementation below.
omegapositional-or-keywordfloatRequiredSee the operation contract and implementation below.
ReturnsMatrix2
Executed regression · g2 quarter wave midgap

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g2_quarter_wave_midgap() -> None:
    cell = quarter_wave_stack(2.0, 1.0, n_periods=1, omega0=1.0)
    mid = abs(bloch_dispersion(cell, 1.0))
    assert mid > 1.0
python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -q
Read the implementation
def layer_matrix(layer: Layer, omega: float) -> Matrix2:
    """Characteristic matrix of a homogeneous slab (``det = 1`` when lossless)."""
    n = layer.index
    delta = n * omega * layer.thickness
    c = cmath.cos(delta)
    s = cmath.sin(delta)
    return ((c, 1.0j * s / n), (1.0j * n * s, c))
FUNCTION

propagation_matrix​

omnibias.core.transfer.propagation_matrixSource ↗
propagation_matrix(n: complex, thickness: float, omega: float) -> Matrix2

Phase accumulation diag(e^{i n omega d}, e^{-i n omega d}) (c=1).

Parameters

NameType & defaultContract
npositional-or-keywordcomplexRequiredSee the operation contract and implementation below.
thicknesspositional-or-keywordfloatRequiredSee the operation contract and implementation below.
omegapositional-or-keywordfloatRequiredSee the operation contract and implementation below.
ReturnsMatrix2
Read the implementation
def propagation_matrix(n: complex, thickness: float, omega: float) -> Matrix2:
    """Phase accumulation ``diag(e^{i n omega d}, e^{-i n omega d})`` (c=1)."""
    phase = n * omega * thickness
    ep = cmath.exp(1.0j * phase)
    em = cmath.exp(-1.0j * phase)
    return ((ep, 0.0j), (0.0j, em))
FUNCTION

quarter_wave_stack​

omnibias.core.transfer.quarter_wave_stackSource ↗
quarter_wave_stack(n_hi: float, n_lo: float, *, n_periods: int, omega0: float=1.0) -> tuple[Layer, ...]

Quarter-wave Bragg stack: n d = pi / (2 omega0) per layer.

Parameters

NameType & defaultContract
n_hipositional-or-keywordfloatRequiredSee the operation contract and implementation below.
n_lopositional-or-keywordfloatRequiredSee the operation contract and implementation below.
n_periodskeyword-onlyintRequiredSee the operation contract and implementation below.
omega0keyword-onlyfloatDefault: 1.0See the operation contract and implementation below.
Returnstuple[Layer, ...]
Executed regression · g2 quarter wave midgap

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g2_quarter_wave_midgap() -> None:
    cell = quarter_wave_stack(2.0, 1.0, n_periods=1, omega0=1.0)
    mid = abs(bloch_dispersion(cell, 1.0))
    assert mid > 1.0
python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -q
Regression example · g3 certified gap sound

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g3_certified_gap_sound() -> None:
    cell = quarter_wave_stack(2.3, 1.0, n_periods=1, omega0=1.0)
    cert = certified_band_gap(cell, omega_range=(0.85, 1.15), n_grid=48)
    assert cert.continuum_claim is False
    xs = [0.85 + (1.15 - 0.85) * i / 80 for i in range(81)]
    vals = [abs(bloch_dispersion(cell, w)) for w in xs]
    if cert.is_gap:
        assert min(vals) >= 1.0 - 1e-9
    assert cert.trace_half_lo <= min(vals) + 1e-9
    assert cert.trace_half_hi + 1e-9 >= max(vals)
python -m pytest packages/omnibias-core/tests/test_transfer.py -k test_g3_certified_gap_sound -q
Read the implementation
def quarter_wave_stack(
    n_hi: float, n_lo: float, *, n_periods: int, omega0: float = 1.0
) -> tuple[Layer, ...]:
    """Quarter-wave Bragg stack: ``n d = pi / (2 omega0)`` per layer."""
    layers: list[Layer] = []
    for _ in range(n_periods):
        layers.append(Layer(n_hi, math.pi / (2.0 * omega0 * n_hi)))
        layers.append(Layer(n_lo, math.pi / (2.0 * omega0 * n_lo)))
    return tuple(layers)
FUNCTION

reflection_transmission​

omnibias.core.transfer.reflection_transmissionSource ↗
reflection_transmission(m: Matrix2, *, n_in: complex=1.0, n_out: complex=1.0) -> tuple[complex, complex]

r, t from an ABCD characteristic matrix into n_out.

Parameters

NameType & defaultContract
mpositional-or-keywordMatrix2RequiredSee the operation contract and implementation below.
n_inkeyword-onlycomplexDefault: 1.0See the operation contract and implementation below.
n_outkeyword-onlycomplexDefault: 1.0See the operation contract and implementation below.
Returnstuple[complex, complex]
Explicit validation & failure cases
  • When denom == 0, raises ZeroDivisionError('transfer matrix is singular').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · g1 structural identities

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g1_structural_identities() -> None:
    layers = (
        Layer(1.5 + 0.0j, 0.3),
        Layer(2.3 + 0.0j, 0.2),
        Layer(1.2 + 0.0j, 0.4),
    )
    for omega in (0.4, 1.0, 2.2):
        m = stack_matrix(layers, omega)
        assert unitarity_residual(m) <= 1e-12
        r, t = reflection_transmission(m)
        cons = abs(r) ** 2 + abs(t) ** 2
        assert abs(cons - 1.0) <= 1e-13
python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g1_structural_identities" -q
Read the implementation
def reflection_transmission(m: Matrix2, *, n_in: complex = 1.0, n_out: complex = 1.0) -> tuple[complex, complex]:
    """``r, t`` from an ABCD characteristic matrix into ``n_out``."""
    a, b = m[0]
    c, d = m[1]
    denom = a * n_out + b * n_in * n_out + c + d * n_in
    if denom == 0:
        raise ZeroDivisionError("transfer matrix is singular")
    r = (a * n_out + b * n_in * n_out - c - d * n_in) / denom
    t = (2.0 * n_in) / denom
    return r, t
FUNCTION

stack_matrix​

omnibias.core.transfer.stack_matrixSource ↗
stack_matrix(layers: Sequence[Layer], omega: float, *, n_in: complex=1.0) -> Matrix2

Product of characteristic matrices. n_in is unused (ambient is 1).

Parameters

NameType & defaultContract
layerspositional-or-keywordSequence[Layer]RequiredSee the operation contract and implementation below.
omegapositional-or-keywordfloatRequiredSee the operation contract and implementation below.
n_inkeyword-onlycomplexDefault: 1.0See the operation contract and implementation below.
ReturnsMatrix2
Executed regression · g2 quarter wave midgap

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g2_quarter_wave_midgap() -> None:
    cell = quarter_wave_stack(2.0, 1.0, n_periods=1, omega0=1.0)
    mid = abs(bloch_dispersion(cell, 1.0))
    assert mid > 1.0
python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -q
Regression example · unitarity refused when lossy

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_unitarity_refused_when_lossy() -> None:
    with pytest.raises(ValueError, match="lossless"):
        unitarity_residual(stack_matrix((Layer(1.5 + 0.1j, 0.2),), 1.0), lossless=False)
python -m pytest packages/omnibias-core/tests/test_transfer.py -k test_unitarity_refused_when_lossy -q
Read the implementation
def stack_matrix(layers: Sequence[Layer], omega: float, *, n_in: complex = 1.0) -> Matrix2:
    """Product of characteristic matrices. ``n_in`` is unused (ambient is 1)."""
    _ = n_in
    m = _eye()
    for layer in layers:
        m = _mul(layer_matrix(layer, omega), m)
    return m
FUNCTION

unitarity_residual​

omnibias.core.transfer.unitarity_residualSource ↗
unitarity_residual(m: Matrix2, *, lossless: bool=True) -> float

|det M - 1|. Refused unless lossless (reciprocal linear media).

Parameters

NameType & defaultContract
mpositional-or-keywordMatrix2RequiredSee the operation contract and implementation below.
losslesskeyword-onlyboolDefault: TrueSee the operation contract and implementation below.
Returnsfloat
Explicit validation & failure cases
  • When not lossless, raises ValueError('unitarity_residual is refused outside lossless reciprocal linear media').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · unitarity refused when lossy

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_unitarity_refused_when_lossy() -> None:
    with pytest.raises(ValueError, match="lossless"):
        unitarity_residual(stack_matrix((Layer(1.5 + 0.1j, 0.2),), 1.0), lossless=False)
python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_unitarity_refused_when_lossy" -q
Regression example · g1 structural identities

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

def test_g1_structural_identities() -> None:
    layers = (
        Layer(1.5 + 0.0j, 0.3),
        Layer(2.3 + 0.0j, 0.2),
        Layer(1.2 + 0.0j, 0.4),
    )
    for omega in (0.4, 1.0, 2.2):
        m = stack_matrix(layers, omega)
        assert unitarity_residual(m) <= 1e-12
        r, t = reflection_transmission(m)
        cons = abs(r) ** 2 + abs(t) ** 2
        assert abs(cons - 1.0) <= 1e-13
python -m pytest packages/omnibias-core/tests/test_transfer.py -k test_g1_structural_identities -q
Read the implementation
def unitarity_residual(m: Matrix2, *, lossless: bool = True) -> float:
    """``|det M - 1|``. Refused unless ``lossless`` (reciprocal linear media)."""
    if not lossless:
        raise ValueError(
            "unitarity_residual is refused outside lossless reciprocal linear media"
        )
    return abs(_det(m) - 1.0)