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

gradientCast

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

Computes a fast, self-healing gradient broadcast of local values from all source nodes, always retaining the data from the nearest source.

Starting from every device where source is true, this function propagates data of type Value along multiple overlapping spanning trees. At each device:

  • If source is true, initializes its own local value at distance bottom.

  • Otherwise, gathers neighbor-propagated GradientPath<ID, Value, Distance>? values, filters out nulls, loops (via maxDiameter and hop sets), and paths invalidated by inconsistent neighbor distances, then selects the minimal-distance, path-coherent route.

  • Uses accumulateDistance to sum edge distances and accumulateData to update the data payload.

  • Falls back to local if no valid source path exists.

This algorithm employs fast repair and is not subject to the rising-value problem, but it incurs larger message sizes and more computation than bellmanFordGradientCast. To limit work and prevent infinite loops, supply an estimate of the network diameter via maxDiameter.

Return

The Value associated with the nearest source node, following a minimal-distance, loop-free path, or local if no source paths are found.

Parameters

source

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

local

The local data value for this device, or the default if no source path exists.

bottom

The zero-distance value at a source. Must be ≤ top.

top

The maximum allowed distance; incoming distances are clamped into [bottom, top].

metric

A Field<ID, Distance> providing edge weights to each neighbor.

maxDiameter

Upper bound on path hop count; paths longer than this are discarded. Defaults to Int.MAX_VALUE.

accumulateData

Function to update neighbor data when traversing an edge. Receives the neighbor’s distance from source, the edge distance, and the neighbor’s data, returning a new Value. Defaults to identity.

accumulateDistance

A reducer to sum two Distance values; used for accumulating path lengths.

ID

The type used for neighbor identifiers.

Value

The type of data being propagated.

Distance

The type representing path lengths; must be comparable.

See also

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

Broadcasts a fast-repair gradient of local values from all source nodes, always retaining the data from the nearest source.

This overload delegates to the full gradientCast(...) implementation using a default distance range of [0.0, +∞) and the standard addition reducer.

Return

The data associated with the nearest source node, following a minimal-distance, loop-free path, or local if no source is reachable.

Parameters

source

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

local

The local data value or the fallback if no source path exists.

metric

A Field<ID, Double> that provides the edge weight (distance) to each neighbor.

maxDiameter

Upper limit on path hop count; any path exceeding this is discarded. Defaults to Int.MAX_VALUE.

accumulateData

Function to update neighbor data when traversing an edge. Receives the neighbor’s distance from source, the edge distance, and the neighbor’s data, returning a new data value. Defaults to the identity function.

accumulateDistance

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

See also