symop.modes.transfer.base¶

Base classes for spectral transfer functions.

This module provides small implementation-oriented base classes for transfer functions used in the modes package.

The design separates two concerns:

Generic transfer identity and evaluation contract.
Optional analytic capabilities layered on top of the generic transfer.

The primary class exported here is TransferBase, which provides shared logic for stable signatures and approximate signatures. Concrete transfer functions typically inherit from this class and implement only their spectral evaluation rule.

Notes

The base class is intentionally lightweight. It does not impose any particular analytic formalism and does not assume that a transfer supports closed-form application to specific envelope families.

For dataclass-based transfers, the default implementation derives signature parameters from dataclass fields in declaration order. This keeps concrete transfer implementations compact and uniform.

Subclasses may override _signature_params() when the identity of a transfer should differ from its raw dataclass field tuple.

Examples

A simple constant phase transfer can inherit from TransferBase and only implement three things:

the class attribute _signature_tag
the spectral call operator __call__
optional constructor-time validation

Then the exact and approximate signatures are inherited automatically.

Classes

TransferBase()

Common implementation base for spectral transfer functions.

class TransferBase¶

Bases: ABC

Common implementation base for spectral transfer functions.

This base class centralizes signature generation for concrete transfer-function implementations.

A transfer function \(H(\omega)\) is identified by a stable signature used for caching, comparison, and expression reuse. In many cases the identity is fully determined by the transfer type together with a tuple of scalar parameters. For frozen dataclass-based transfers, this class derives those parameters automatically.

Subclasses are expected to provide:

a class attribute _signature_tag
an implementation of __call__()

They may optionally override _signature_params() if their logical identity differs from their raw stored parameters.

Notes

This class does not enforce a specific numerical representation for the returned samples beyond what is required by the public transfer protocol used elsewhere in the package.

The approximate signature is constructed by recursively rounding floating-point values contained in the exact parameter structure.

_signature_tag¶

Stable symbolic tag identifying the concrete transfer type.

Type:: ClassVar[str]

_abc_impl = <_abc._abc_data object>¶

_dataclass_field_values() → tuple[Any, ...]¶

Return dataclass field values in declaration order.

Returns:: Tuple of stored dataclass field values.
Return type:: tuple[Any, …]
Raises:: TypeError – If the instance is not a dataclass instance and the subclass did not override _signature_params().

Notes

This helper supports the common case where transfer functions are implemented as frozen dataclasses with scalar parameters.

classmethod _round_for_signature(value: Any, *, decimals: int) → Any¶

Recursively round numeric values for approximate signatures.

Parameters:

value (Any) – Arbitrary nested value appearing inside a signature parameter structure.
decimals (int) – Number of decimal places used for rounding.

Returns:

Value with floating-point leaves rounded recursively.

Return type:

Any

Notes

The transformation preserves the container shape for tuples and lists. Complex numbers are rounded componentwise as

\[z = x + i y \mapsto \operatorname{round}(x) + i \operatorname{round}(y).\]

Booleans are preserved unchanged.

_signature_params(*, ignore_global_phase: bool = False) → tuple[Any, ...]¶

Return the logical parameter tuple used in signatures.

Parameters:: ignore_global_phase (bool) – Whether a physically irrelevant global phase should be excluded or canonicalized by subclasses that support that behavior.
Returns:: Parameter tuple describing the transfer.
Return type:: tuple[Any, …]

Notes

The default implementation derives parameters from dataclass fields in declaration order. This is appropriate for most simple immutable transfer classes.

Subclasses can override this method if their signature should depend on a transformed, reduced, or reordered set of values.

_signature_tag: ClassVar[str]¶

approx_signature(*, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]¶

Return an approximate signature with rounded numeric values.

This method is useful for grouping or caching transfer functions whose parameters differ only by negligible floating-point noise.

Parameters:

decimals (int) – Number of decimal places used when rounding floating-point values.
ignore_global_phase (bool) – Whether subclasses should omit or normalize parameters representing a physically irrelevant global phase.

Returns:

Approximate signature tuple with recursively rounded numeric parameters.

Return type:

Signature

Notes

The exact meaning of ignore_global_phase depends on the subclass. For transfers without a global-phase degree of freedom, the flag usually has no effect.

property signature: tuple[object, ...]¶

Return the exact stable signature of the transfer.

The exact signature is a tuple beginning with the subclass tag followed by the exact signature parameter structure.

Returns:: Exact signature tuple used for caching and structural comparison.
Return type:: Signature

Notes

The default implementation uses _signature_params() with ignore_global_phase=False.