Problem definition

The bilevel problem is a single Problem dataclass that carries the datafit + penalty + design + target. The hyperparameter α is not stored — that’s what the outer search tunes.

The Datafit and Penalty families are tagged unions of frozen dataclasses. Algorithms dispatch on them via match statements with typing.assert_never exhaustiveness; mypy will flag any missing case.

class sparho.Problem

Bases: object

A bilevel inner problem argmin_β  L(Xβ, y) + R(β; α).

The hyperparameter α is not stored here — it is what the outer search tunes. The problem captures the fixed structure: which loss, which regularizer family, which design matrix, which target vector.

datafit: SquaredLoss | LogisticLoss

penalty: L1 | ElasticNet | WeightedL1 | GroupL1

design: ndarray[tuple[Any, ...], dtype[floating]] | csc_matrix | csc_array

target: ndarray[tuple[Any, ...], dtype[floating]]

property n_samples: int

Number of observations (X.shape[0]).

__init__(datafit, penalty, design, target)

Parameters:

• datafit (SquaredLoss | LogisticLoss)

• penalty (L1 | ElasticNet | WeightedL1 | GroupL1)

• design (ndarray[tuple[Any, ...], dtype[floating]] | csc_matrix | csc_array)

• target (ndarray[tuple[Any, ...], dtype[floating]])

Return type:

None

property n_features: int

Number of features (X.shape[1]).

Datafits

class sparho.SquaredLoss

Bases: object

L(Xβ, y) = 0.5 · ‖Xβ − y‖².

__init__()

Return type:

None

class sparho.LogisticLoss

Bases: object

L(Xβ, y) = Σᵢ log(1 + exp(−yᵢ (Xβ)ᵢ)) with yᵢ ∈ {−1, +1}.

__init__()

Return type:

None

sparho.Datafit = SquaredLoss | LogisticLoss

Represent a PEP 604 union type

E.g. for int | str

Penalties

class sparho.L1

Bases: object

R(β; α) = α · ‖β‖₁ with scalar hyperparameter α > 0.

__init__()

Return type:

None

class sparho.ElasticNet

Bases: object

R(β; α) = α · (ρ · ‖β‖₁ + (1 − ρ)/2 · ‖β‖²).

The mixing weight ρ ∈ (0, 1] is structural (carried here, not tuned). The hyperparameter optimized by grad_search is the scalar α.

rho: float

__init__(rho)

Parameters:

rho (float)

Return type:

None

class sparho.WeightedL1

Bases: object

R(β; α) = Σⱼ αⱼ · |βⱼ| with per-feature hyperparameter vector α.

__init__()

Return type:

None

sparho.Penalty = L1 | ElasticNet | WeightedL1

Represent a PEP 604 union type

E.g. for int | str