Updating documentation to ensure running examples.

Author: rcschrg

Project.toml

@@ -7,27 +7,24 @@ version = "0.1.0"
 [deps]
 AutoHashEquals = "15f4f7f2-30c1-5605-9d31-71845cf9641f"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
-ECOS = "e2685f51-7e38-5353-a97d-a921fd2c8199"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Mango = "5e49fdec-d473-4d14-b295-7bff2fcf1925"
 OSQP = "ab2f91bb-94b4-55e3-9ba0-7f65df51de79"
-Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
 
 [compat]
 AutoHashEquals = "2.2.0"
 Distributions = "0.25.115"
-ECOS = "1.1.3"
 JuMP = "1.25.0"
 LinearAlgebra = "^1.9"
 Mango = "^0.5"
 OSQP = "0.8.1"
-Revise = "3.6.4"
 julia = "^1.9"
 
 [extras]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]

docs/make.jl

@@ -44,5 +44,5 @@ end
 deploydocs(
     repo="github.com/Digitalized-Energy-Systems/DistributedResourceOptimization.jl.git",
     push_preview=true,
-    devbranch="main"
+    devbranch="development"
 )

docs/src/algorithms/admm.md

@@ -128,9 +128,6 @@ The generic ADMM coordinator ([`ADMMGenericCoordinator`](@ref)) exposes several
 | `max_iters` | `1000` | Maximum number of ADMM iterations |
 | `abs_tol` | `1e-4` | Absolute primal/dual residual tolerance |
 | `rel_tol` | `1e-3` | Relative primal/dual residual tolerance |
-| `μ` | `10` | Residual ratio threshold for ρ adaptation |
-| `τ` | `2` | Multiplicative factor for ρ adaptation |
-| `slack_penalty` | `100` | Penalty for infeasibility slack variables |
 
 ## Complete Example — ADMM Sharing
 
@@ -179,7 +176,7 @@ println(result(actor2))
     - Reducing `ρ` when primal residuals dominate
     - Increasing `ρ` when dual residuals dominate
     - Tightening `abs_tol` / `rel_tol` for higher precision
-    - Increasing `max_iters` for complex problems
+    - Increasing `max_iters` if the warning "reached max iterations" appears
 
 ## See Also
 

src/algorithm/admm/core.jl

@@ -1,4 +1,4 @@
-export ADMMStart, ADMMAnswer, ADMMAnswer, ADMMGlobalActor, ADMMGlobalObjective, ADMMGenericCoordinator, create_admm_start
+export ADMMStart, ADMMAnswer, ADMMGlobalActor, ADMMGlobalObjective, ADMMGenericCoordinator, create_admm_start
 
 struct ADMMStart
     data::Any
@@ -52,13 +52,10 @@ end
 
 @kwdef struct ADMMGenericCoordinator <: Coordinator
     global_actor::ADMMGlobalActor
-    ρ::Float64 = 1.0 
+    ρ::Float64 = 1.0
     max_iters::Int64 = 1000
-    slack_penalty::Int64 = 100
     abs_tol::Float64 = 1e-4
     rel_tol::Float64 = 1e-3
-    μ::Real = 10
-    τ::Real = 2
 end
 
 # ADMM solver
@@ -68,8 +65,6 @@ function _start_coordinator(admm::ADMMGenericCoordinator, carrier::Carrier, inpu
     abs_tol = admm.abs_tol
     rel_tol = admm.rel_tol
     n = length(others(carrier, "coordinator"))
-    μ = admm.μ
-    τ = admm.τ
 
     # Initialize
     x = [zeros(m) for i in 1:n]
@@ -80,7 +75,7 @@ function _start_coordinator(admm::ADMMGenericCoordinator, carrier::Carrier, inpu
         # 1. Local x-updates (in parallel)
         awaitables = []
         # send all async and get awaitable
-        for (i,addr) in enumerate(others(carrier, "c"))
+        for (i,addr) in enumerate(others(carrier, "coordinator"))
             push!(awaitables, send_awaitable(carrier, ADMMMessage(actor_correction(admm.global_actor, x, z, u, i), ρ), addr))
         end
         # await all awaitables and update x
@@ -103,21 +98,12 @@ function _start_coordinator(admm::ADMMGenericCoordinator, carrier::Carrier, inpu
         ϵ_pri = sqrt(m*n)*abs_tol + rel_tol*max(maximum(norm.(x)), maximum(norm.(z)))
         ϵ_dual = sqrt(m*n)*abs_tol + rel_tol*maximum(norm.(u))
         if r_norm < ϵ_pri && s_norm < ϵ_dual
-            @warn "Converged in $k iterations."
+            @debug "ADMM converged in $k iterations."
             break
         end
-        
-        # Varying penalty paramter according to B. S. He, H. Yang, and S. L. Wang, “Alternating direction method with self
-        # adaptive penalty parameters for monotone variational inequalities,”
-        # if r_norm > μ * s_norm
-        #     ρ = ρ * τ
-        # elseif s_norm > μ * r_norm
-        #     ρ = ρ / τ
-        # end
-        
+
         if k == max_iters
-            @warn "Reached max iterations ($max_iters) without full convergence."
-            throw("ADMM not converged $x, $u")
+            @warn "ADMM reached max iterations ($max_iters) without full convergence (r=$r_norm, s=$s_norm)."
         end
     end
     return x, z, u

src/algorithm/consensus/averaging.jl

@@ -1,5 +1,5 @@
 
-export ConsensusActor, NoConsensusActor, AveragingConsensusAlgorithm, AveragingConsensusMessage, create_averaging_consensus_participant, gradient_term
+export ConsensusActor, NoConsensusActor, AveragingConsensusAlgorithm, AveragingConsensusMessage, create_averaging_consensus_participant, create_averaging_consensus_start, gradient_term
 
 abstract type ConsensusActor end
 
@@ -78,8 +78,19 @@ function on_exchange_message(algorithm_data::AveragingConsensusAlgorithm, carrie
     end
 end
 
-function create_averaging_consensus_participant(finish_callback::Function, consensus_actor::ConsensusActor; initial_λ::Real=10, α::Real=0.3, max_iter::Int=50) 
+function create_averaging_consensus_participant(finish_callback::Function, consensus_actor::ConsensusActor; initial_λ::Real=10, α::Real=0.3, max_iter::Int=50)
     appl_consensus_actor = isnothing(consensus_actor) ? NoConsensusActor() : consensus_actor
-    
+
     return AveragingConsensusAlgorithm(finish_callback=finish_callback, initial_λ=initial_λ, α=α, actor=appl_consensus_actor, max_iter=max_iter)
+end
+
+"""
+    create_averaging_consensus_start(initial_λ::Real, data::Any=nothing) -> AveragingConsensusMessage
+
+Create the initial start message for averaging consensus. `initial_λ` sets the starting
+price/signal value (scalar, broadcast to all dimensions), and `data` is any auxiliary
+payload forwarded unchanged to each participant's `gradient_term`.
+"""
+function create_averaging_consensus_start(initial_λ::Real, data::Any=nothing)
+    return AveragingConsensusMessage([initial_λ], 0, data, true)
 end

src/algorithm/heuristic/cohda/core.jl

@@ -1,5 +1,5 @@
 export on_exchange_message, ScheduleSelection, SystemConfig, SolutionCandidate, TargetParams,
-    WorkingMemory, COHDAAlgorithmData, create_cohda_start_message, create_cohda_participant
+    WorkingMemory, COHDAAlgorithmData, create_cohda_start_message, create_cohda_participant, result
 
 using AutoHashEquals
 
@@ -56,15 +56,15 @@ end
 end
 
 function initial_schedule(local_decider::DefaultLocalDecider, memory::WorkingMemory)
-    return local_decider.schedule_provider(memory)[0]
+    return local_decider.schedule_provider(memory)[1]
 end
 
 @kwdef mutable struct COHDAAlgorithmData <: DistributedAlgorithm
     participant_id::Int
     counter::Int = 0
     memory::WorkingMemory = WorkingMemory(nothing, SystemConfig(Dict()), nothing)
     performance_function::Function = cohda_default_performance
-    decider::LocalDecider = DefaultLocalDecider()
+    decider::Union{LocalDecider,Nothing} = nothing
 end
 
 function decide(cohda_data::COHDAAlgorithmData, decider::LocalDecider, sysconfig::SystemConfig, candidate::SolutionCandidate)
@@ -211,7 +211,7 @@ function create_from_updated_sysconf(participant_id::Int, sysconfig::SystemConfi
         base_mat[id, :] = choice.schedule
     end
     base_mat[participant_id, :] = new_schedule
-    return SolutionCandidate(participant_id, base_mat, nothing, keys(sysconfig.schedule_choices))
+    return SolutionCandidate(participant_id, base_mat, nothing, Set{Int}(keys(sysconfig.schedule_choices)))
 end
 
 function decide(cohda_data::COHDAAlgorithmData, decider::DefaultLocalDecider, sysconfig::SystemConfig, candidate::SolutionCandidate)
@@ -313,4 +313,14 @@ function create_cohda_participant_with_decider(participant_id::Int,
         decider=decider)
 end
 
+"""
+    result(actor::COHDAAlgorithmData) -> Vector{Float64}
+
+Return the aggregate schedule chosen by the COHDA optimization — the column-wise sum of
+all participants' schedules in the best solution candidate known to this actor.
+"""
+function result(actor::COHDAAlgorithmData)
+    return vec(sum(actor.memory.solution_candidate.schedules, dims=1))
+end
+
 

src/algorithm/heuristic/cohda/decider.jl

@@ -3,10 +3,10 @@ using Distributions
 
 @kwdef struct LocalSearchDecider <: LocalDecider
     initial_schedule::Vector{Float64}
-    corridors::Vector{Tuple{Float64}}
+    corridors::Vector{Tuple{Float64,Float64}}
     local_performance::Function
     convergence_force_factor::Float64 = 0.1
-    max_iterations = 10
+    max_iterations::Int = 10
     sample_size_per_value::Int = 10
     distribution::Function = (low, up) -> Uniform(low, up)
 end
@@ -20,18 +20,19 @@ function local_performance_with_global_share(decider::LocalSearchDecider, schedu
 end
 
 function find_new_value(decider::LocalSearchDecider, current_index::Int, current_best_schedule::Vector{Float64}, delta_to_target::Float64)
-    possible_values = rand(decider.distribution, decider.sample_size_per_value)
+    corridor = decider.corridors[current_index]
+    possible_values = rand(decider.distribution(corridor[1], corridor[2]), decider.sample_size_per_value)
     current_value = current_best_schedule[current_index]
     new_value_performance_tuples::Vector{Tuple{Float64,Float64}} = []
     new_value = nothing
     iteration = 1
-    while length(possible_values) > 0 || iteration > decider.max_iterations
+    while length(possible_values) > 0 && iteration <= decider.max_iterations
         copy_bs = copy(current_best_schedule)
         random_index = ceil(Int, rand() * length(possible_values))
         new_value = possible_values[random_index]
         copy_bs[current_index] = new_value
 
-        # we calculate the performance with a variable local performance share and a adaptive global performance share 
+        # we calculate the performance with a variable local performance share and a adaptive global performance share
         performance = local_performance_with_global_share(decider, copy_bs, new_value, current_value, delta_to_target)
 
         push!(new_value_performance_tuples, (new_value, performance))
@@ -41,7 +42,7 @@ function find_new_value(decider::LocalSearchDecider, current_index::Int, current
             sort!(new_value_performance_tuples)
             first = new_value_performance_tuples[1][1]
             second = new_value_performance_tuples[2][1]
-            third = new_value_performance_tuples[2][1]
+            third = new_value_performance_tuples[3][1]
 
             # cut out undesirable parts of the whole vector
             if first > second > third

test/runtests.jl

@@ -12,7 +12,7 @@ function DistributedResourceOptimization.send_to_other(carrier::TestCarrier, con
     push!(message_buffer, content)
 end
 
-function DistributedResourceOptimization.schedule_using(to_be_scheduled::Function, carrier::TestCarrier, delay_s::Float64)
+function DistributedResourceOptimization.schedule_using(carrier::TestCarrier, to_be_scheduled::Function, ::Float64)
     to_be_scheduled()
 end