omnibias.core.transfer
Coefficient recurrences, activation contracts, jet algebra, and verified arithmetic shared by the numerical backends.
import omnibias.core.transferModule 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.
BandGapCertificate
omnibias.core.transfer.BandGapCertificateSource ↗class BandGapCertificateDataclass 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
| Name | Type & default | Contract |
|---|---|---|
omega_lodataclass field | floatRequired | See the operation contract and implementation below. |
omega_hidataclass field | floatRequired | See the operation contract and implementation below. |
trace_half_lodataclass field | floatRequired | See the operation contract and implementation below. |
trace_half_hidataclass field | floatRequired | See the operation contract and implementation below. |
is_gapdataclass field | boolRequired | See the operation contract and implementation below. |
continuum_claimdataclass field | boolDefault: False | See the operation contract and implementation below. |
Fields & methods
omega_lofield
omega_lo: floatDeclared 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: floatDeclared 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: floatDeclared 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: floatDeclared 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: boolDeclared 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 = FalseDeclared bool field on BandGapCertificate. Default expression: False.
is_soundproperty
is_sound(self) -> boolSee the class contract above and the exact method implementation below.
Returns: bool
Method implementation
def is_sound(self) -> bool:
return TrueRead 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 TrueLayer
omnibias.core.LayerSource ↗class LayerDataclass 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
| Name | Type & default | Contract |
|---|---|---|
indexdataclass field | complexRequired | See the operation contract and implementation below. |
thicknessdataclass field | floatRequired | See 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.0python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -qRegression 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 -qFields & methods
indexfield
index: complexDeclared complex field on Layer. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.
View source ↗thicknessfield
thickness: floatDeclared 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) -> NoneSee the class contract above and the exact method implementation below.
Returns: None
Validation & failure cases
- When
self.thickness < 0.0, raisesValueError('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.0python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -qMethod implementation
def __post_init__(self) -> None:
if self.thickness < 0.0:
raise ValueError("thickness must be >= 0")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.Layeromnibias.core.transfer.Layer
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]]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
| Name | Type & default | Contract |
|---|---|---|
cellpositional-or-keyword | Sequence[Layer]Required | See the operation contract and implementation below. |
omegapositional-or-keyword | floatRequired | See the operation contract and implementation below. |
floatExecuted 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.0python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -qRegression 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 -qRead 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]).realcertified_band_gap
omnibias.core.certified_band_gapSource ↗certified_band_gap(cell: Sequence[Layer], *, omega_range: tuple[float, float], n_grid: int=64) -> BandGapCertificateInterval 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
| Name | Type & default | Contract |
|---|---|---|
cellpositional-or-keyword | Sequence[Layer]Required | See the operation contract and implementation below. |
omega_rangekeyword-only | tuple[float, float]Required | See the operation contract and implementation below. |
n_gridkeyword-only | intDefault: 64 | See the operation contract and implementation below. |
BandGapCertificateExplicit validation & failure cases
- When
hi <= lo, raisesValueError('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" -qRead 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_gapomnibias.core.transfer.certified_band_gap
interface_matrix
omnibias.core.transfer.interface_matrixSource ↗interface_matrix(n_lo: complex, n_hi: complex) -> Matrix2Continuity of E and H at a dielectric interface (normal incidence).
Parameters
| Name | Type & default | Contract |
|---|---|---|
n_lopositional-or-keyword | complexRequired | See the operation contract and implementation below. |
n_hipositional-or-keyword | complexRequired | See the operation contract and implementation below. |
Matrix2Read 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))layer_matrix
omnibias.core.transfer.layer_matrixSource ↗layer_matrix(layer: Layer, omega: float) -> Matrix2Characteristic matrix of a homogeneous slab (det = 1 when lossless).
Parameters
| Name | Type & default | Contract |
|---|---|---|
layerpositional-or-keyword | LayerRequired | See the operation contract and implementation below. |
omegapositional-or-keyword | floatRequired | See the operation contract and implementation below. |
Matrix2Executed 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.0python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -qRead 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))propagation_matrix
omnibias.core.transfer.propagation_matrixSource ↗propagation_matrix(n: complex, thickness: float, omega: float) -> Matrix2Phase accumulation diag(e^{i n omega d}, e^{-i n omega d}) (c=1).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | complexRequired | See the operation contract and implementation below. |
thicknesspositional-or-keyword | floatRequired | See the operation contract and implementation below. |
omegapositional-or-keyword | floatRequired | See the operation contract and implementation below. |
Matrix2Read 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))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
| Name | Type & default | Contract |
|---|---|---|
n_hipositional-or-keyword | floatRequired | See the operation contract and implementation below. |
n_lopositional-or-keyword | floatRequired | See the operation contract and implementation below. |
n_periodskeyword-only | intRequired | See the operation contract and implementation below. |
omega0keyword-only | floatDefault: 1.0 | See the operation contract and implementation below. |
tuple[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.0python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -qRegression 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 -qRead 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)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
| Name | Type & default | Contract |
|---|---|---|
mpositional-or-keyword | Matrix2Required | See the operation contract and implementation below. |
n_inkeyword-only | complexDefault: 1.0 | See the operation contract and implementation below. |
n_outkeyword-only | complexDefault: 1.0 | See the operation contract and implementation below. |
tuple[complex, complex]Explicit validation & failure cases
- When
denom == 0, raisesZeroDivisionError('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-13python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g1_structural_identities" -qRead 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, tstack_matrix
omnibias.core.transfer.stack_matrixSource ↗stack_matrix(layers: Sequence[Layer], omega: float, *, n_in: complex=1.0) -> Matrix2Product of characteristic matrices. n_in is unused (ambient is 1).
Parameters
| Name | Type & default | Contract |
|---|---|---|
layerspositional-or-keyword | Sequence[Layer]Required | See the operation contract and implementation below. |
omegapositional-or-keyword | floatRequired | See the operation contract and implementation below. |
n_inkeyword-only | complexDefault: 1.0 | See the operation contract and implementation below. |
Matrix2Executed 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.0python -m pytest "packages/omnibias-core/tests/test_transfer.py::test_g2_quarter_wave_midgap" -qRegression 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 -qRead 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 munitarity_residual
omnibias.core.transfer.unitarity_residualSource ↗unitarity_residual(m: Matrix2, *, lossless: bool=True) -> float|det M - 1|. Refused unless lossless (reciprocal linear media).
Parameters
| Name | Type & default | Contract |
|---|---|---|
mpositional-or-keyword | Matrix2Required | See the operation contract and implementation below. |
losslesskeyword-only | boolDefault: True | See the operation contract and implementation below. |
floatExplicit validation & failure cases
- When
not lossless, raisesValueError('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" -qRegression 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-13python -m pytest packages/omnibias-core/tests/test_transfer.py -k test_g1_structural_identities -qRead 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)