Struct TotalVariationPenalty 

pub struct TotalVariationPenalty {
    pub weight: f64,
    pub n_eff: usize,
    pub difference_op: DifferenceOpKind,
    pub smoothing_eps: f64,
    pub learnable_weight: bool,
    pub rho_index: usize,
    pub weight_schedule: Option<ScalarWeightSchedule>,
}

Coordinatewise/anisotropic smoothed-L¹ total variation on a row-major (n_eff, d) latent block.

Uses the differentiable Huber-style kernel φ(x)=sqrt(x²+ε²)-ε separately for each edge and latent axis. This is not vector-norm/isotropic edge TV: the Hessian intentionally has no cross-axis terms. The difference operator defines the prior shape: forward 1-D differences for ordered context windows, or graph edges for adjacency-structured atoms. Pair TV with Orthogonality when piecewise-constant atoms need a gauge-fixed basis.

Fields

weight: f64

Base strength. If learnable_weight is true, the resolved strength is weight * exp(rho[rho_index]); otherwise it is fixed at weight.

n_eff: usize

Number of rows in the row-major latent coefficient block.

difference_op: DifferenceOpKind

smoothing_eps: f64

learnable_weight: bool

rho_index: usize

weight_schedule: Option<ScalarWeightSchedule>

Implementations

impl TotalVariationPenalty

pub fn new( weight: f64, n_eff: usize, difference_op: DifferenceOpKind, smoothing_eps: f64, learnable_weight: bool, ) -> Result<Self, String>

pub fn with_weight_schedule(self, schedule: ScalarWeightSchedule) -> Self

Attach a scalar weight schedule, seeding the current weight from the schedule’s stored iteration counter.

pub fn diag_target( &self, target: ArrayView1<'_, f64>, rho: ArrayView1<'_, f64>, ) -> Array1<f64>

pub fn as_dense( &self, target: ArrayView1<'_, f64>, rho: ArrayView1<'_, f64>, ) -> Array2<f64>

Materialize Dᵀ diag(φ''(D T)) D for diagnostics and small graph cases.

pub fn log_det_plus_lambda_i_forward_1d( &self, target: ArrayView1<'_, f64>, rho: ArrayView1<'_, f64>, lambda: f64, ) -> Result<f64, String>

Trait Implementations

impl AnalyticPenalty for TotalVariationPenalty

fn tier(&self) -> PenaltyTier

Tier the target lives in (β or ext-coord).

fn value(&self, target: ArrayView1<'_, f64>, rho: ArrayView1<'_, f64>) -> f64

Scalar penalty contribution P(target; ρ). The strength factor exp(ρ) (or whatever parameterization the penalty uses) is folded in.

fn grad_target( &self, target: ArrayView1<'_, f64>, rho: ArrayView1<'_, f64>, ) -> Array1<f64>

Gradient ∂P/∂target, same length as target.

fn hvp( &self, target: ArrayView1<'_, f64>, rho: ArrayView1<'_, f64>, v: ArrayView1<'_, f64>, ) -> Array1<f64>

Hessian-vector product H v = (∂²P/∂target²) v, in closed form.

fn grad_rho( &self, target: ArrayView1<'_, f64>, rho: ArrayView1<'_, f64>, ) -> Array1<f64>

Gradient of the penalty value w.r.t. each owned ρ-axis. Length equals Self::rho_count.

fn rho_count(&self) -> usize

Number of REML-selectable hyperparameter axes this penalty contributes to the outer ρ vector.

fn name(&self) -> &str

Human-readable identifier for diagnostics / logging.

fn apply_schedule(&mut self, iter: usize)

Update any attached scalar weight schedule at the given REML outer iteration. Penalties without schedules keep their stored weight.

fn hessian_diag( &self, target: ArrayView1<'_, f64>, rho: ArrayView1<'_, f64>, ) -> Option<Array1<f64>>

Diagonal of the Hessian diag(∂²P/∂target²) when the Hessian is block-diagonal. Returns None for penalties whose Hessian is dense (Isometry); those implement Self::hvp instead. The default signals “no closed-form diagonal” by returning None for any non-empty target — concrete penalties either override with their own analytic diagonal or rely on the matrix-free hvp path.

fn psd_majorizer_diag( &self, target: ArrayView1<'_, f64>, rho: ArrayView1<'_, f64>, ) -> Option<Array1<f64>>

Diagonal of a PSD majorizer of the Hessian — the positive re-weighted-ℓ₂ / MM surrogate diag(B(target; ρ)) with B ⪰ ∂²P/∂target² everywhere and B ⪰ 0. This is a different operator from Self::hessian_diag: for nonconvex penalties (log sparsity, JumpReLU) the exact Hessian is indefinite, but the inner Newton / PIRLS solve and the log-det / preconditioner pipeline require a PSD curvature block. For convex penalties the majorizer coincides with the exact Hessian, so the default simply delegates to Self::hessian_diag; nonconvex penalties override.

fn psd_majorizer_hvp( &self, target: ArrayView1<'_, f64>, rho: ArrayView1<'_, f64>, v: ArrayView1<'_, f64>, ) -> Array1<f64>

Matrix-vector product against the PSD majorizer B(target; ρ) v (see Self::psd_majorizer_diag). For convex penalties this is the exact Hessian-vector product, so the default delegates to Self::hvp; nonconvex penalties override to return their PSD surrogate instead of the indefinite true Hessian.

impl Clone for TotalVariationPenalty

fn clone(&self) -> TotalVariationPenalty

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TotalVariationPenalty

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PenaltyManifest for TotalVariationPenalty

const KIND_TAG: &'static str = "total_variation"

const PYTHON_WRAPPER: &'static str = "TotalVariationPenalty"

const ROW_BLOCK_DIAGONAL: bool = false

fn dispatch_tier(&self) -> PenaltyTier