Asynchronous Sheaf Diffusion

Module for simulating asynchronous cellular sheaf diffusion.

Agents communicate over a sheaf's underlying graph using a gossip-like protocol: each agent maintains a local estimate of the global cochain, periodically applies a gradient descent step on its own component, and periodically broadcasts its local state to neighboring agents.

Scheduling models

Three scheduling models govern when each agent updates and broadcasts:

• Probabilistic (ProbabilisticModelParams): each agent independently decides to update or broadcast at each iteration with random probabilities.
• Deterministic (period vectors): each agent i updates every update_periods[i] iterations and broadcasts every broadcast_periods[i] iterations, with a random phase offset.
• Mixture (MixtureModelParams): periods are sampled from a Gaussian mixture at the start of the simulation and held fixed thereafter.

Key functions

• compute_trajectory — synchronous gradient descent baseline.
• compute_trajectory_asynch — asynchronous diffusion (all scheduling variants; single-run and batch forms).

Utilities

• random_psd, random_pd, random_semi_orthogonal_matrix — random matrix generators for constructing test sheaves.
• matrix_weighted_rm, matrix_weighted_edge_generator — helpers for building matrix-weighted sheaves.
• save_trajectory, save_trajectories, load_trajectory — CSV I/O for trajectory data.
• empty_experiment_plot, plot_loss_curve!, plot_log_loss_curve! — plotting helpers (requires using Plots).

MixtureModelParams(dists, weights)

Parameters for a Gaussian mixture distribution over agent periods.

Each agent's update or broadcast period is sampled by:

1. Selecting component k with probability weights[k].
2. Drawing from dists[k] (a Normal), rounding up to the nearest integer.
3. Clamping to [1, B].

Construct with:

using Distributions: Normal
d1 = Normal(5.0, 0.5)
d2 = Normal(50.0, 5.0)
params = MixtureModelParams([d1, d2], [0.5, 0.5])

ProbabilisticModelParams(update_prob_upper_bound, broadcast_prob_upper_bound)

Parameters for coin-flip-based update and broadcast scheduling.

At each iteration, agent i updates with probability pᵢ drawn uniformly from [0, update_prob_upper_bound], and broadcasts with probability qᵢ drawn from [0, broadcast_prob_upper_bound]. These probabilities are sampled once at the start of the simulation.

compute_trajectory(sheaf, x0, γ; max_iters=1000, tol=1e-8) -> Vector

Run synchronous gradient descent on sheaf_laplacian_matrix(sheaf) from initial cochain x0 with step size γ.

Returns a vector of cochains (one per iteration, including x0). Stops early when energy drops below tol.

compute_trajectory_asynch(sheaf, x0, γs::AbstractVector{<:Real},
                           update_model, broadcast_model;
                           max_iters=1000, tol=1e-8, B=50) -> Vector{Vector}

Batch asynchronous diffusion over multiple step sizes.

A single schedule (periods and phases) is sampled once and reused across all step sizes in γs. This isolates the effect of the step size from the effect of the schedule.

Returns a vector of trajectories, one per element of γs.

compute_trajectory_asynch(sheaf, x0, γ,
                           update_periods::Vector{Int},
                           broadcast_periods::Vector{Int};
                           max_iters=1000, tol=1e-8, B=50) -> Vector

Asynchronous sheaf diffusion with deterministic periodic scheduling.

Agent i updates every update_periods[i] iterations and broadcasts every broadcast_periods[i] iterations, starting from a random phase in [0, period-1].

Returns a vector of global cochains (one per iteration).

compute_trajectory_asynch(sheaf, x0, γ,
                           update_model::MixtureModelParams,
                           broadcast_model::MixtureModelParams;
                           max_iters=1000, tol=1e-8, B=50) -> Vector

Asynchronous sheaf diffusion with mixture-model period scheduling.

Agent periods are sampled once at the start from update_model and broadcast_model (Gaussian mixture distributions), then clamped to [1, B]. Each agent starts at a random phase within its period.

Returns a vector of global cochains (one per iteration).

compute_trajectory_asynch(sheaf, x0, γ, params::ProbabilisticModelParams;
                           max_iters=1000, tol=1e-8, B=50) -> Vector

Asynchronous sheaf diffusion with coin-flip scheduling.

At the start of the simulation each agent i is assigned update probability pᵢ ∈ [0, params.update_prob_upper_bound] and broadcast probability qᵢ ∈ [0, params.broadcast_prob_upper_bound], drawn uniformly at random. At each iteration, agent i independently flips these coins.

Returns a vector of global cochains (one per iteration).

compute_trajectory_asynch(sheaf, x0s::Vector{<:AbstractVector}, γ,
                           update_model, broadcast_model;
                           max_iters=1000, tol=1e-8, B=50) -> Vector{Vector}

Batch asynchronous diffusion over multiple initial cochains.

A single schedule (periods and phases) is sampled once and reused across all initial conditions in x0s. This isolates the effect of initialization from the effect of the schedule.

Returns a vector of trajectories, one per element of x0s.

empty_experiment_plot(; kwargs...) -> Plot

Create a blank plot with standard experiment styling. Requires using Plots before calling.

load_trajectory(filename) -> Matrix

Read a trajectory from a CSV file at filename. Returns a matrix (rows are iterations, columns are state components).

matrix_weighted_edge_generator(; pd_prob=0.5) -> Function

Return a function stalk_dim -> Matrix that generates restriction maps from either a random PD or PSD matrix with probability pd_prob and 1-pd_prob respectively.

Useful as an rm_generator argument to sheaf_from_graph.

matrix_weighted_rm(A) -> Matrix{Float64}

Extract a restriction map from A via QR factorization (returns the R factor).

plot_log_loss_curve!(plt, losses, label; kwargs...)

Add a log₁₀-scale loss curve to plt. Requires using Plots before calling.

plot_loss_curve!(plt, losses, label; kwargs...)

Add a linear-scale loss curve to plt. Requires using Plots before calling.

random_pd(dim) -> Matrix{Float64}

Return a random dim × dim positive definite matrix.

random_psd(dim) -> Matrix{Float64}

Return a random dim × dim positive semidefinite matrix.

random_semi_orthogonal_matrix(n, m) -> Matrix{Float64}

Return a random n × m semi-orthogonal matrix (columns are orthonormal when n ≥ m, rows are orthonormal when m > n).

save_trajectories(path, experiment_name, trajectories)

Write each trajectory in trajectories to a separate CSV file under path, named <experiment_name>_traj1.csv, <experiment_name>_traj2.csv, etc.

save_trajectory(filename, trajectory)

Write a trajectory (vector of scalars or vectors) to a CSV file at filename.