state_sparsity#

Decay-aware sparsity policies for persisted recurrent state.

Classes

`DASCCalibrationMeasurement`	Caller-supplied measurements for one candidate recovery window.
`DASCConfig`	Configuration for GDN decay-aware state checkpoint sparsity.
`DASCLayerPolicy`	Serializable whole-head policy for one GDN layer.
`DASCPolicy`	Standalone JSON-safe DASC deployment policy.
`DASCQualityMeasurement`	Quality and lifecycle measurements for one calibration slice.

Functions

`analyze_gdn_decay`	Return deterministic per-head horizons for every GDN module in a model.
`calibrate`	Calibrate and attach a DASC policy without changing model execution.
`compute_gdn_decay_horizons`	Compute one static retention horizon per GDN head in CPU float64.
`export_policy`	Export a JSON-safe DASC policy after validating model structure and decay parameters.

class DASCCalibrationMeasurement#

Bases: ModeloptBaseConfig

Caller-supplied measurements for one candidate recovery window.

checkpoint_savings: float#

model_config = {'extra': 'forbid', 'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

quality: list[DASCQualityMeasurement]#

retained_heads: int#

total_heads: int#

classmethod validate_unique_slices(quality)#

Require one result per named calibration slice.

Parameters:: quality (list[DASCQualityMeasurement])
Return type:: list[DASCQualityMeasurement]

variant: Literal['dasc_nr', 'dasc_wr']#

wmax: int#

class DASCConfig#

Bases: ModeloptBaseConfig

Configuration for GDN decay-aware state checkpoint sparsity.

calibration_data_id: str#

epsilon: float#

granularity: Literal['gdn_head']#

min_checkpoint_savings: float#

min_perplexity_retention: float#

min_top1_agreement: float#

model_config = {'extra': 'forbid', 'protected_namespaces': (), 'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_config_id: str#

model_id: str#

model_revision: str#

preserve_convolution_state: Literal[True]#

static_gate_input: float#

classmethod validate_epsilon(epsilon)#

Require a finite decay threshold strictly between zero and one.

Parameters:: epsilon (float)
Return type:: float

classmethod validate_perplexity_gate(value)#

Require a finite retention gate in (0, 1].

Parameters:: value (float)
Return type:: float

classmethod validate_provenance(value)#

Require explicit immutable provenance instead of inferred defaults.

Parameters:: value (str)
Return type:: str

classmethod validate_savings_gate(value)#

Require a finite physical checkpoint-savings gate in [0, 1).

Parameters:: value (float)
Return type:: float

classmethod validate_static_gate_input(value)#

Require a finite representative gate input.

Parameters:: value (float)
Return type:: float

classmethod validate_top1_gate(value)#

Require a finite agreement gate in [0, 1].

Parameters:: value (float)
Return type:: float

classmethod validate_wmax_candidates(candidates)#

Require unique positive integer windows without power-of-two restrictions.

Parameters:: candidates (object)
Return type:: object

variant: Literal['dasc_nr', 'dasc_wr']#

wmax_candidates: list[int]#

class DASCLayerPolicy#

Bases: ModeloptBaseConfig

Serializable whole-head policy for one GDN layer.

model_config = {'extra': 'forbid', 'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

num_heads: int#

omitted_heads: list[int]#

retained_heads: list[int]#

static_horizons: list[float]#

validate_partition()#

Validate that retained and omitted indices partition every GDN head.

Return type:: DASCLayerPolicy

class DASCPolicy#

Bases: ModeloptBaseConfig

Standalone JSON-safe DASC deployment policy.

active_runtime_state: Literal['dense']#

calibration_data_id: str#

decay_parameters_sha256: str#

epsilon: float#

format_version: Literal[1]#

granularity: Literal['gdn_head']#

layers: dict[str, DASCLayerPolicy]#

measurements: list[DASCCalibrationMeasurement]#

model_config = {'extra': 'forbid', 'protected_namespaces': (), 'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_config_id: str#

model_id: str#

model_revision: str#

model_structure_sha256: str#

preserve_convolution_state: Literal[True]#

quality_gates: dict[str, float]#

recovery: Literal['zero', 'suffix_replay']#

selected_wmax: int#

static_gate_input: float#

validate_policy()#

Reject inconsistent variant, candidate, measurement, or mask metadata.

Return type:: DASCPolicy

variant: Literal['dasc_nr', 'dasc_wr']#

wmax_candidates: list[int]#

class DASCQualityMeasurement#

Bases: ModeloptBaseConfig

Quality and lifecycle measurements for one calibration slice.

convolution_state_exact: bool#

finite_continuation_logits: bool#

model_config = {'extra': 'forbid', 'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

omitted_state_matches_recovery: bool#

perplexity_retention: float#

retained_state_exact: bool#

slice_id: str#

top1_agreement: float#

analyze_gdn_decay(model, *, epsilon=0.001, static_gate_input=-0.3)#

Return deterministic per-head horizons for every GDN module in a model.

Parameters:

model (Module)
epsilon (float)
static_gate_input (float)

Return type:

dict[str, list[float]]

calibrate(model, config, measurements)#

Calibrate and attach a DASC policy without changing model execution.

measurements must contain exactly one entry for every configured Wmax candidate. The largest candidate passing every quality, lifecycle, and storage gate is selected.

Example:

import modelopt.torch.sparsity.state_sparsity as mtss

model = mtss.calibrate(model, config, measurements)
deployment_policy = mtss.export_policy(model)

Parameters:

model (Module) – Model containing GatedDeltaNet modules with one-dimensional A_log and dt_bias tensors.
config (dict[str, Any] | DASCConfig) – Checkpoint provenance, candidate windows, and quality gates.
measurements (Iterable[DASCCalibrationMeasurement | dict]) – Quality and checkpoint-storage results produced by the caller’s paired dense-versus-DASC calibration workflow.

Returns:

The input model with a serializable DASC policy attached through ModelOpt state.

Return type:

Module

compute_gdn_decay_horizons(a_log, dt_bias, *, epsilon=0.001, static_gate_input=-0.3)#

Compute one static retention horizon per GDN head in CPU float64.

Parameters:

a_log (Tensor)
dt_bias (Tensor)
epsilon (float)
static_gate_input (float)

Return type:

Tensor

export_policy(model)#

Export a JSON-safe DASC policy after validating model structure and decay parameters.

This policy does not implement checkpoint packing or recovery. A serving backend must preserve convolution state, store retained complete GDN heads, recover omitted heads according to the declared variant, and materialize the ordinary dense runtime state before continuation.

Parameters:: model (Module)
Return type:: dict[str, Any]