gradnet.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)[source]

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.

Methods

export_config()

Return a CPU-side configuration snapshot for later reconstruction.

extra_repr()

Return the extra representation of the module.

forward([noise_amplitude])

Return the full adjacency A = adj0 + delta.

from_checkpoint(checkpoint_path, *[, ...])

Load a GradNet from a PyTorch Lightning checkpoint.

from_config(config)

Rebuild a GradNet from export_config() output.

get_delta_adj([noise_amplitude])

Return the normalized perturbation matrix delta from the backend.

renorm_params()

Renormalize internal parameters using the backend's strategy.

set_initial_state(delta_adj_raw_0)

Forward to the parameterization's set_initial_state and renormalize.

to_numpy()

Return the full adjacency as a NumPy array on CPU.

Attributes

device

dtype

training