decent_bench.algorithms.utils#

Utilities for algorithm initialization and general helpers.

decent_bench.algorithms.utils.initial_states(x0: InitialStates, network: Network) → dict[Agent, Array][source]#

Build per-agent initial states, for use in initialize().

Parameters:

  • x0 (InitialStates) –

    • None: initialize all agents to zeros, using each agent’s native shape/framework/device.

    • Array: apply the same state to all agents.

    • dict[Agent, Array]: explicit per-agent states.

  • network (Network) – network instance containing the target agents.

Returns:

mapping from each network agent to its initial state.

Return type:

dict[Agent, Array]

Raises:

  • ValueError – if x0 is missing required agent entries.

  • TypeError – if x0 has an invalid type.

Notes

For FedNetwork, explicit x0 dictionaries must provide client entries. If the server entry is missing, it is inferred as the average of client initial states. Keys in x0 not referring to agents in the network are silently ignored.

decent_bench.algorithms.utils.normal_initialization(network: Network, mean: float = 0.0, std: float = 1.0) → dict[Agent, Array][source]#

Build per-agent initial states sampled from a normal distribution.

Parameters:

  • network (Network) – network instance containing the target agents.

  • mean (float) – mean of the normal distribution used to sample each state entry.

  • std (float) – standard deviation of the normal distribution used to sample each state entry.

Returns:

mapping from each agent to an independently sampled random initial state.

Return type:

dict[Agent, Array]

Notes

The states are created using each agent’s own cost.shape, cost.framework, and cost.device.

decent_bench.algorithms.utils.pytorch_initialization(network: Network, all_same: bool = False) → dict[Agent, Array] | Array[source]#

Build per-agent initial states using PyTorchCost.model initialization routine.

Gets the initialized parameter tensor for every agent from PyTorchCost.model (via torch.nn.Module.parameters()), and flattens it. The returned dict is compatible with initial_states() and can be passed directly as x0 to any algorithm.

Parameters:

  • network (Network) – network instance containing the target agents. All agents must have a PyTorchCost.

  • all_same (bool) – if True, use the first agent’s initialized state for all agents.

Returns:

mapping from each network agent to its initial state, as a flattened parameter vector extracted from the initialized model.

Return type:

dict[Agent, Array] | Array

Raises:

TypeError – if any agent’s cost is not a PyTorchCost.

decent_bench.algorithms.utils.uniform_initialization(network: Network, low: float = 0.0, high: float = 1.0) → dict[Agent, Array][source]#

Build per-agent initial states sampled from a uniform distribution.

Parameters:

  • network (Network) – network instance containing the target agents.

  • low (float) – inclusive lower bound of the uniform distribution.

  • high (float) – exclusive upper bound of the uniform distribution.

Returns:

mapping from each agent to an independently sampled random initial state.

Return type:

dict[Agent, Array]

Raises:

ValueError – if high is not greater than low.

Notes

The states are created using each agent’s own cost.shape, cost.framework, and cost.device.