decent_bench.metrics.metric_utils

decent_bench.metrics.metric_utils.single(values: Sequence[float]) → float

Assert that values contain exactly one element and return it.

Raises:

ValueError – if there isn’t exactly one element in values

decent_bench.metrics.metric_utils.mean_x(agents: tuple[AgentMetricsView, ...], iteration: int = -1) → ndarray[tuple[Any, ...], dtype[float64]]

Calculate the mean x at iteration (or using the agents’ final x if iteration is -1).

Agents that did not reach iteration are disregarded.

Raises:

ValueError – if no agent reached iteration

decent_bench.metrics.metric_utils.global_cost_error_at_iter(agents: list[AgentMetricsView], problem: BenchmarkProblem, iteration: int = -1) → float

Calculate the global cost error at iteration (or using the agents’ final x if iteration is -1).

Global cost error is defined as:

\[| \sum_i (f_i(\mathbf{\bar{x}}) - f_i(\mathbf{x}^\star)) |\]

where \(f_i\) is agent i’s local cost function, \(\mathbf{\bar{x}}\) is the mean x across all agents, and \(\mathbf{x}^\star\) is the optimal x defined in the problem.

decent_bench.metrics.metric_utils.global_gradient_optimality_at_iter(agents: list[AgentMetricsView], iteration: int = -1) → float

Calculate the global gradient optimality at iteration (or using the agents’ final x if iteration is -1).

Global gradient optimality is defined as:

\[\| \frac{1}{N} \sum_i \nabla f_i(\mathbf{\bar{x}}) \|^2\]

where N is the number of agents, \(f_i\) is agent i’s local cost function, and \(\mathbf{\bar{x}}\) is the mean x across all agents.

decent_bench.metrics.metric_utils.x_error_per_iteration(agent: AgentMetricsView, problem: BenchmarkProblem) → ndarray[tuple[Any, ...], dtype[float64]]

Calculate the x error per iteration as defined below.

\[\{ \|\mathbf{x}_0 - \mathbf{x}^\star\|, \|\mathbf{x}_1 - \mathbf{x}^\star\|, ... \}\]

where \(\mathbf{x}_k\) is the agent’s local x at iteration k, and \(\mathbf{x}^\star\) is the optimal x defined in the problem.

decent_bench.metrics.metric_utils.asymptotic_convergence_rate_and_order(agent: AgentMetricsView, problem: BenchmarkProblem) → tuple[float, float]

Estimate the asymptotic convergence rate and order as defined below.

\[\lim_{k \to \infty} \frac{\| \mathbf{x}_{k+1} - \mathbf{x}^\star \|}{\| \mathbf{x}_{k} - \mathbf{x}^\star\|^q} = \mu\]

where \(\mathbf{x}_k\) is the agent’s local x at iteration k, \(\mathbf{x}^\star\) is the optimal x defined in the problem, \(q\) is the asymptotic convergence order, and \(\mu\) is the asymptotic convergence rate.

decent_bench.metrics.metric_utils.iterative_convergence_rate_and_order(agent: AgentMetricsView, problem: BenchmarkProblem) → tuple[float, float]

Estimate the iterative convergence rate and order as defined below.

\[k = \frac{\mu}{\|\mathbf{x}_k - \mathbf{x}^\star\|^q}\]

where k is the iteration, \(\mu\) is the iterative convergence rate, \(\mathbf{x}_k\) is the agent’s local x at iteration k, \(\mathbf{x}^\star\) is the optimal x defined in the problem, and \(q\) is the iterative convergence order.

As per the definition, iterative convergence is a measure of how many iterations are needed to reach a certain error. This makes iterative convergence order and rate suitable metrics for sublinear algorithms; a sublinear algorithm with iterative convergence order 0.5 generally converges significantly faster than one with order 1.