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].

evaluate

evaluate(X: ArrayLike, *, weights: ArrayLike | None = None, execution: ExecutionConfig | None = None) -> LinearProblem

Create a reusable evaluated problem.

Parameters:

• X (ArrayLike) –

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

• weights (ArrayLike | None, default: None ) –

  Optional finite, nonnegative integration weights with shape [N].

Returns:

• LinearProblem –

  Validated components, coefficients, weights, and metadata.

to_dict

to_dict() -> dict[str, JsonValue]

Return serializable model metadata; callables are intentionally omitted.

LinearProblem dataclass

LinearProblem(components: ArrayLike, coefficients: ArrayLike, weights: ArrayLike | None = None, component_names: Sequence[str] | None = None, variables: Sequence[str] | None = None, execution: ExecutionConfig | None = None)

Represent an evaluated linear intensity on an integration sample.

Parameters:

• components (ArrayLike) –

  Component matrix with shape [N, M].

• coefficients (ArrayLike) –

  Reference coefficient vector with shape [M].

• weights (ArrayLike | None, default: None ) –

  Optional finite, nonnegative integration weights with shape [N].

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

  Optional unique component names. Stable generated names are used when omitted.

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

  Optional physical-variable names retained as metadata.

Validate arrays and freeze their normalized representations.

density property

density: ndarray

Reference intensity evaluated on every integration point.

scores property

scores: ndarray

Inference score representation derived from the components.

to_dict

to_dict() -> dict[str, JsonValue]

Return the evaluated problem as JSON-compatible data.

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:

• ValueError –

  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.