collektive-stdlib/it.unibo.collektive.stdlib.spreading/bellmanFordGradientCast

bellmanFordGradientCast

@JvmOverloads
inline fun <ID : Any, Value, Distance : Comparable<Distance>> Aggregate<ID>.bellmanFordGradientCast(source: Boolean, local: Value, bottom: Distance, top: Distance, noinline accumulateData: (fromSource: Distance, toNeighbor: Distance, data: Value) -> Value = { _, _, data -> data }, crossinline accumulateDistance: Reducer<Distance>, metric: Field<ID, Distance>): Value

Computes a gradient-based broadcast of local values over the network using a Bellman–Ford–style algorithm.

Starting from the nearest source node(s), this function propagates values of type Value along a spanning tree defined by a distance metric. At each device:

  • If source is true, returns the local value at minimal distance bottom.

  • Otherwise, selects the neighbor path yielding the minimal total distance (accumulated via accumulateDistance) and applies accumulateData to combine neighbor data.

  • In the absence of any source or neighbors, returns the local value.

Return

The aggregated Value at this device, chosen from the minimal-distance path.

This function uses incremental repair to self-heal the gradient and may suffer from the rising value problem. See Fast self-healing gradients for details.

Parameters

source

true if this device is a source; false otherwise.

local

The local value to propagate from a source or to use as a default.

bottom

The minimum distance (distance at a source). Must be ≤ top.

top

The maximum distance threshold; values outside [bottom, top] are clamped.

accumulateData

A function to combine data when forwarding from a neighbor. Receives the neighbor's distance from source, the edge distance to this device, and the neighbor's data. Defaults to the identity function.

accumulateDistance

A reducer that sums two distances; used to accumulate path lengths.

metric

A Field<ID, Distance> providing the distance to each neighbor.

@JvmOverloads
inline fun <ID : Any, Value> Aggregate<ID>.bellmanFordGradientCast(source: Boolean, local: Value, noinline accumulateData: (fromSource: Double, toNeighbor: Double, data: Value) -> Value = { _, _, data -> data }, crossinline accumulateDistance: (fromSource: Double, toNeighbor: Double) -> Double = Double::plus, metric: Field<ID, Double>): Value

Propagates local values across the network using a Bellman–Ford gradient.

Starting from the nearest source node(s), this function builds a spanning tree and distributes data of type Value along minimal-distance paths. At each device:

  • If source is true, returns the local value at distance 0.0.

  • Otherwise, examines each neighbor’s propagated pair (distance, data), adds the edge weight via accumulateDistance, applies accumulateData to the data, and selects the path with the smallest total distance.

  • If there are no sources and no neighbors, returns the local value.

This overload uses a default distance range of [0.0, +∞) and the standard addition operator for distance accumulation.

Return

The propagated Value at this device, chosen along the shortest-distance path.

This function uses incremental repair to self-heal the gradient and may suffer from the rising value problem. See Fast self-healing gradients for details.

Parameters

source

true if this device is a source node; false otherwise.

local

The local value to propagate or to use as a default.

accumulateData

Function to combine neighbor data: receives the neighbor’s distance from source, the edge distance to this device, and the neighbor’s data. Defaults to the identity function.

accumulateDistance

Function to sum two distances; defaults to Double::plus.

metric

A Field<ID, Double> providing the edge weight to each neighbor.