API REFERENCE/omnibias-torch

omnibias.torch.architectures.ftc_net

0.5.0rc1Release candidatePython >=3.10Apache-2.0

PyTorch activation derivatives, trainable operator layers, network jets, and direct differential-operator contractions.

import omnibias.torch.architectures.ftc_net

Module contract & mathematical conventions

FTC-Net + dual-FTC loss (torch; theory 09-03 / 09-17).

The cell is the integral role. The derivative head is FTC of the same window. The founding bias collapse (delta -> 0) is the collapse head I / delta. Temperature collapse (beta -> inf, feasibility) does not appear. Do not conflate the two.

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.

Module source ↗Source revision 9a2d73df0573Running reference examples →

Imports & aliases

These names share a definition with another public module. Follow a name for its full contract, parameters, and examples.

Import from this module	Canonical reference
DISCLAIMER	omnibias.core.ftc.DISCLAIMER
DualFTCConfig	omnibias.core.ftc.DualFTCConfig
FTCNetConfig	omnibias.core.ftc.FTCNetConfig
honesty_payload	omnibias.core.ftc.honesty_payload
worked_example	omnibias.core.ftc.worked_example

CLASS

FTCNet

omnibias.torch.architectures.FTCNetSource ↗

class FTCNet

Config holder; evaluation is the closed-form pack sum in omnibias.core.ftc.

Parameters

Name	Type & default	Contract
configpositional-or-keyword	FTCNetConfig | NoneDefault: None	See the operation contract and implementation below.

Executed regression · g1 and g4 matches core

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.

Full file, imports & fixtures ↗

def test_g1_and_g4_matches_core() -> None:
    torch.set_default_dtype(torch.float64)
    x = torch.tensor(0.0)
    w = torch.tensor(1.0)
    lo = torch.tensor(-0.1)
    hi = torch.tensor(0.1)
    integral, deriv, collapse = ftc_block(x, w, lo, hi)
    ex = worked_example()
    assert float(integral) == ex["I"]
    assert float(deriv) == ex["dI"]
    assert float(collapse) == ex["collapse"]
    net = FTCNet(FTCNetConfig())
    assert net.config.width == 12
    loss = dual_ftc_loss([float(integral)], [float(deriv)], [float(deriv)], [0.0], I_a=float(integral))
    assert loss.max_r_D < 1e-12

python -m pytest "packages/omnibias-torch/tests/test_ftc_net.py::test_g1_and_g4_matches_core" -q

Fields & methods

__init__method

__init__(self, config: FTCNetConfig | None=None) -> None

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

Parameters

Name	Type & default	Contract
configpositional-or-keyword	FTCNetConfig | NoneDefault: None	See the operation contract and implementation below.

Returns: None

Executed regression · g1 and g4 matches core

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.

Full file, imports & fixtures ↗

def test_g1_and_g4_matches_core() -> None:
    torch.set_default_dtype(torch.float64)
    x = torch.tensor(0.0)
    w = torch.tensor(1.0)
    lo = torch.tensor(-0.1)
    hi = torch.tensor(0.1)
    integral, deriv, collapse = ftc_block(x, w, lo, hi)
    ex = worked_example()
    assert float(integral) == ex["I"]
    assert float(deriv) == ex["dI"]
    assert float(collapse) == ex["collapse"]
    net = FTCNet(FTCNetConfig())
    assert net.config.width == 12
    loss = dual_ftc_loss([float(integral)], [float(deriv)], [float(deriv)], [0.0], I_a=float(integral))
    assert loss.max_r_D < 1e-12

python -m pytest "packages/omnibias-torch/tests/test_ftc_net.py::test_g1_and_g4_matches_core" -q

Method implementation

    def __init__(self, config: FTCNetConfig | None = None) -> None:
        self.config = FTCNetConfig() if config is None else config

View source ↗

configattribute

config = FTCNetConfig() if config is None else config

Public instance attribute assigned by __init__. The source assignment is config = FTCNetConfig() if config is None else config; it describes instance state, not a literal constructor default.

Regression example · g1 and g4 matches core

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.

Full file, imports & fixtures ↗

def test_g1_and_g4_matches_core() -> None:
    torch.set_default_dtype(torch.float64)
    x = torch.tensor(0.0)
    w = torch.tensor(1.0)
    lo = torch.tensor(-0.1)
    hi = torch.tensor(0.1)
    integral, deriv, collapse = ftc_block(x, w, lo, hi)
    ex = worked_example()
    assert float(integral) == ex["I"]
    assert float(deriv) == ex["dI"]
    assert float(collapse) == ex["collapse"]
    net = FTCNet(FTCNetConfig())
    assert net.config.width == 12
    loss = dual_ftc_loss([float(integral)], [float(deriv)], [float(deriv)], [0.0], I_a=float(integral))
    assert loss.max_r_D < 1e-12

python -m pytest packages/omnibias-torch/tests/test_ftc_net.py -k test_g1_and_g4_matches_core -q

View source ↗

Read the implementation

class FTCNet:
    """Config holder; evaluation is the closed-form pack sum in ``omnibias.core.ftc``."""

    def __init__(self, config: FTCNetConfig | None = None) -> None:
        self.config = FTCNetConfig() if config is None else config

Related APIsomnibias.core.ftc.FTCNetConfig↗

Other public import paths

• omnibias.torch.architectures.FTCNet
• omnibias.torch.architectures.ftc_net.FTCNet

FUNCTION

dual_ftc_loss

omnibias.torch.architectures.dual_ftc_lossSource ↗

dual_ftc_loss(I_vals: Sequence[float] | Tensor, dI_vals: Sequence[float] | Tensor, f_vals: Sequence[float] | Tensor, F_vals: Sequence[float] | Tensor, *, config: DualFTCConfig | None=None, I_a: float | None=None) -> core_ftc.DualFTCResult

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
I_valspositional-or-keyword	Sequence[float] | TensorRequired	See the operation contract and implementation below.
dI_valspositional-or-keyword	Sequence[float] | TensorRequired	See the operation contract and implementation below.
f_valspositional-or-keyword	Sequence[float] | TensorRequired	See the operation contract and implementation below.
F_valspositional-or-keyword	Sequence[float] | TensorRequired	See the operation contract and implementation below.
configkeyword-only	DualFTCConfig | NoneDefault: None	See the operation contract and implementation below.
I_akeyword-only	float | NoneDefault: None	See the operation contract and implementation below.

Returnscore_ftc.DualFTCResult

Executed regression · g1 and g4 matches core

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.

Full file, imports & fixtures ↗

def test_g1_and_g4_matches_core() -> None:
    torch.set_default_dtype(torch.float64)
    x = torch.tensor(0.0)
    w = torch.tensor(1.0)
    lo = torch.tensor(-0.1)
    hi = torch.tensor(0.1)
    integral, deriv, collapse = ftc_block(x, w, lo, hi)
    ex = worked_example()
    assert float(integral) == ex["I"]
    assert float(deriv) == ex["dI"]
    assert float(collapse) == ex["collapse"]
    net = FTCNet(FTCNetConfig())
    assert net.config.width == 12
    loss = dual_ftc_loss([float(integral)], [float(deriv)], [float(deriv)], [0.0], I_a=float(integral))
    assert loss.max_r_D < 1e-12

python -m pytest "packages/omnibias-torch/tests/test_ftc_net.py::test_g1_and_g4_matches_core" -q

Read the implementation

def dual_ftc_loss(
    I_vals: Sequence[float] | Tensor,
    dI_vals: Sequence[float] | Tensor,
    f_vals: Sequence[float] | Tensor,
    F_vals: Sequence[float] | Tensor,
    *,
    config: DualFTCConfig | None = None,
    I_a: float | None = None,
) -> core_ftc.DualFTCResult:
    def _as_list(v: Sequence[float] | Tensor) -> list[float]:
        if isinstance(v, Tensor):
            return [float(x) for x in v.detach().reshape(-1).tolist()]
        return [float(x) for x in v]

    return core_ftc.dual_ftc_loss(
        _as_list(I_vals),
        _as_list(dI_vals),
        _as_list(f_vals),
        _as_list(F_vals),
        config=core_ftc.DEFAULT_DUAL if config is None else config,
        I_a=I_a,
    )

Related APIsomnibias.core.ftc.dual_ftc_loss↗

Other public import paths

• omnibias.torch.architectures.dual_ftc_loss
• omnibias.torch.architectures.ftc_net.dual_ftc_loss

FUNCTION

ftc_block

omnibias.torch.architectures.ftc_blockSource ↗

ftc_block(x: Tensor, w: Tensor, b_lo: Tensor, b_hi: Tensor, *, activation: str='sigmoid') -> tuple[Tensor, Tensor, Tensor]

mathematically equivalent to omnibias.core.ftc.ftc_block on scalars.

Backend scope: this identifies the corresponding mathematical construction. It does not guarantee bitwise-equal floating-point results across devices, compilers, dtypes, or backend versions. Validate the selected path with an appropriate absolute and relative tolerance.

Parameters

Name	Type & default	Contract
xpositional-or-keyword	TensorRequired	See the operation contract and implementation below.
wpositional-or-keyword	TensorRequired	See the operation contract and implementation below.
b_lopositional-or-keyword	TensorRequired	See the operation contract and implementation below.
b_hipositional-or-keyword	TensorRequired	See the operation contract and implementation below.
activationkeyword-only	strDefault: 'sigmoid'	See the operation contract and implementation below.

Returnstuple[Tensor, Tensor, Tensor]

Executed regression · g1 and g4 matches core

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.

Full file, imports & fixtures ↗

def test_g1_and_g4_matches_core() -> None:
    torch.set_default_dtype(torch.float64)
    x = torch.tensor(0.0)
    w = torch.tensor(1.0)
    lo = torch.tensor(-0.1)
    hi = torch.tensor(0.1)
    integral, deriv, collapse = ftc_block(x, w, lo, hi)
    ex = worked_example()
    assert float(integral) == ex["I"]
    assert float(deriv) == ex["dI"]
    assert float(collapse) == ex["collapse"]
    net = FTCNet(FTCNetConfig())
    assert net.config.width == 12
    loss = dual_ftc_loss([float(integral)], [float(deriv)], [float(deriv)], [0.0], I_a=float(integral))
    assert loss.max_r_D < 1e-12

python -m pytest "packages/omnibias-torch/tests/test_ftc_net.py::test_g1_and_g4_matches_core" -q

Regression example · g4 worked example bit identical

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.

Full file, imports & fixtures ↗

def test_g4_worked_example_bit_identical() -> None:
    torch.set_default_dtype(torch.float64)
    ti, td, tc = torch_ftc_block(
        torch.tensor(0.0), torch.tensor(1.0), torch.tensor(-0.1), torch.tensor(0.1)
    )
    ji, jd, jc = jax_ftc_block(
        jnp.asarray(0.0), jnp.asarray(1.0), jnp.asarray(-0.1), jnp.asarray(0.1)
    )
    assert float(ti) == float(ji)
    assert float(td) == float(jd)
    assert float(tc) == float(jc)

python -m pytest tests/test_ftc_net_parity.py -k test_g4_worked_example_bit_identical -q

Read the implementation

def ftc_block(
    x: Tensor,
    w: Tensor,
    b_lo: Tensor,
    b_hi: Tensor,
    *,
    activation: str = "sigmoid",
) -> tuple[Tensor, Tensor, Tensor]:
    """Bit-identical to :func:`omnibias.core.ftc.ftc_block` on scalars."""
    _ = activation
    xs = x.detach().reshape(-1).tolist()
    ws = w.detach().reshape(-1).tolist()
    los = b_lo.detach().reshape(-1).tolist()
    his = b_hi.detach().reshape(-1).tolist()
    n = max(len(xs), len(ws), len(los), len(his))

    def _at(vals: list[float], i: int) -> float:
        return vals[0] if len(vals) == 1 else vals[i]

    integrals: list[float] = []
    derivs: list[float] = []
    collapses: list[float] = []
    for i in range(n):
        integral, deriv, collapse = core_ftc.ftc_block(
            _at(xs, i), _at(ws, i), _at(los, i), _at(his, i), activation=activation
        )
        integrals.append(integral)
        derivs.append(deriv)
        collapses.append(collapse)
    dtype = x.dtype
    if x.ndim == 0:
        return (
            torch.tensor(integrals[0], dtype=dtype, device=x.device),
            torch.tensor(derivs[0], dtype=dtype, device=x.device),
            torch.tensor(collapses[0], dtype=dtype, device=x.device),
        )
    return (
        torch.tensor(integrals, dtype=dtype, device=x.device).reshape(x.shape),
        torch.tensor(derivs, dtype=dtype, device=x.device).reshape(x.shape),
        torch.tensor(collapses, dtype=dtype, device=x.device).reshape(x.shape),
    )

Related APIsomnibias.core.ftc.ftc_block↗

Other public import paths

• omnibias.torch.architectures.ftc_block
• omnibias.torch.architectures.ftc_net.ftc_block

← Package overviewRunnable learning examples →