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 per-head horizons, optionally canonicalized to a checkpoint storage dtype.
`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#

decay_parameter_storage_dtype: Literal['float16', 'bfloat16', 'float32']#

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 positive retention gate.

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_parameter_storage_dtype: Literal['float16', 'bfloat16', 'float32']#

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, decay_parameter_storage_dtype=None)#

Return per-head horizons, optionally canonicalized to a checkpoint storage dtype.

Parameters:

model (Module)
epsilon (float)
static_gate_input (float)
decay_parameter_storage_dtype (Literal['float16', 'bfloat16', 'float32'] | None)

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. Recalibrating replaces the existing DASC mode-state entry in place.

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]