Linear models

LinearComponents dataclass

LinearComponents(
    components: Mapping[str, ComponentFunction]
    | Sequence[ComponentFunction],
    coefficients: Mapping[str, float] | Sequence[float],
    *,
    variables: Sequence[str] | None = None,
)

Define vectorized linear-intensity components on physical variables.

Parameters:

• components (Mapping[str, ComponentFunction] | Sequence[ComponentFunction]) –

  Either an insertion-ordered mapping from names to callables or a sequence of callables. Each callable receives X with shape [N, K] and returns one finite value per row.

• coefficients (Mapping[str, float] | Sequence[float]) –

  A mapping with exactly the component keys or a coefficient sequence aligned with sequence components.

• variables (Sequence[str] | None, default: None ) –

  Optional unique physical-variable names used to validate K.

Validate and freeze component order, coefficients, and metadata.

evaluate_components

evaluate_components(
    X: ArrayLike,
    *,
    execution: ExecutionConfig | None = None,
) -> ndarray

Evaluate every component function.

Parameters:

• X (ArrayLike) –

  Finite numeric physical-variable matrix with shape [N, K].

Returns:

• ndarray –

  Evaluated component matrix with shape [N, M].

to_dict

to_dict() -> dict[str, JsonValue]

Return serializable model metadata; callables are intentionally omitted.

scores_from_components

scores_from_components(
    components: ArrayLike,
    coefficients: ArrayLike,
    *,
    execution: ExecutionConfig | None = None,
) -> ndarray

Construct scores for a linear intensity model.

Parameters:

• components (ArrayLike) –

  Finite component matrix with shape [N, M].

• coefficients (ArrayLike) –

  Finite reference coefficients with shape [M].

Returns:

• ndarray –

  Score matrix components / (components @ coefficients)[:, None] with shape [N, M].

Raises:

• ContractError –

  If shapes are incompatible, values are non-finite, or the reference intensity is not strictly positive at every row.

Notes

Components and coefficients may be signed and need not be normalized. They must be finite, and their resulting reference intensity must be strictly positive at every supplied integration point.

The map is invariant under a common event-wise rescaling of a row: for any positive c(x), replacing components[i, :] by c(x_i) * components[i, :] leaves the scores unchanged. Component densities and component density ratios in any gauge therefore produce identical scores; absolute normalization is never required.