GradNet (class)

The core differentiable adjacency parameterization exposed at the top level of gradnet.

class gradnet.GradNet(num_nodes, budget, mask=None, adj0=None, delta_sign='nonnegative', final_sign='free', directed=False, rand_init_weights=True, strict_budget=True, cost_matrix=None, cost_aggr_norm=1, *, device=None, dtype=None)

Bases: Module

User-facing GradNet: learn a constrained delta over a base adjacency.

This thin wrapper owns the mask, cost matrix, and base adjacency adj0, and delegates the trainable parameters to either a dense or sparse parameterization depending on mask layout.

Construct a GradNet instance.

Parameters:

• num_nodes (int) – Number of nodes (matrix dimension).

• budget (float | None) – Target cost-weighted p-norm of the perturbation. If None, no budget normalization is enforced.

• mask (torch.Tensor | None, optional) – Active-entry mask. Dense masks result in a dense parameterization; sparse COO masks use the sparse backend. If None, defaults to all-ones off-diagonal.

• adj0 (torch.Tensor | None, optional) – Base adjacency. If None, uses a zero matrix matching the selected backend layout.

• delta_sign (str, optional) – Sign constraint for delta. One of {"free", "nonnegative", "nonpositive"}.

• final_sign (str, optional) – Sign constraint applied to the returned adjacency. One of {"free", "nonnegative", "nonpositive"}.

• directed (bool, optional) – If False, symmetrize delta and expect a symmetric cost matrix.

• rand_init_weights (bool | float, optional) – Initialization mix coefficient a. Cast to float and clamped to [0,1]. a = 1.0 or True yields fully random U(0,1); a = 0.0 or False yields uniform ones. Intermediate values yield interpolation.

• strict_budget (bool, optional) – If True, always scale up/down to the exact budget. If False, scale down only.

• cost_matrix (torch.Tensor | None, optional) – Per-entry costs for normalization; defaults to ones. In sparse backend mode, omitted costs remain implicit (unit costs) and no dense default matrix is materialized.

• cost_aggr_norm (int, optional) – Aggregation norm p for the cost-weighted p-norm.

• device (torch.device | str | None, optional) – Target device for buffers/parameters. If None, inferred from input tensors or defaults to CPU.

• dtype (torch.dtype | str | None, optional) – Target dtype for buffers/parameters. If None, inferred from input tensors or from PyTorch defaults.

extra_repr()

Return the extra representation of the module.

To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.

export_config()

Return a CPU-side configuration snapshot for later reconstruction.

classmethod from_config(config)

Rebuild a GradNet from export_config() output.

set_initial_state(delta_adj_raw_0)

Forward to the parameterization’s set_initial_state and renormalize.

renorm_params()

Renormalize internal parameters using the backend’s strategy.

should_renorm_after_step()

Return whether post-update parameter renormalization is advised.

This is True only when the model enforces a budget and strict budget scaling is enabled.

get_delta_adj(noise_amplitude=0.0)

Return the normalized perturbation matrix delta from the backend.

Parameters:

noise_amplitude (float, optional) – Standardized magnitude for the stochastic perturbation applied to the raw parameters before constraints. Defaults to 0 (deterministic).

forward(noise_amplitude=0.0)

Return the full adjacency A = adj0 + delta.

Handles dense/sparse combinations between adj0 and delta and returns either a dense or a sparse tensor accordingly. When noise_amplitude > 0 the same stochastic perturbation as get_delta_adj() is injected before constraints.

Parameters:

noise_amplitude (float, optional) – Magnitude of the Gaussian noise applied to delta_adj_raw prior to constraint handling.

to_numpy()

Return the full adjacency as a NumPy array on CPU.

classmethod from_checkpoint(checkpoint_path, *, map_location='cpu')

Load a GradNet from a PyTorch Lightning checkpoint. Checkpoints are stored by fit.

Note

Additional convenience methods (for example to or eval) are inherited directly from torch.nn.Module. Refer to the PyTorch module documentation for their full API.