Adding some docs.

Author: rcschrg

docs/make.jl

@@ -11,6 +11,14 @@ with_logger(logger) do
         sitename="DistributedResourceOptimization.jl Documentation",
         pages=Any["Home"=>"index.md",
             "Getting Started"=>"getting_started.md",
+            "Algorithms" => [
+                "ADMM"=>"algorithms/admm.md",
+                "COHDA"=>"algorithms/cohda.md",
+            ],
+            "Carrier" => [
+                "Simple"=>"carrier/simple.md",
+                "Mango"=>"carrier/mango.md",
+            ],
             "API"=>"api.md"],
         repo="https://github.com/Digitalized-Energy-Systems/DistributedResourceOptimization.jl",
     )

docs/src/algorithms/admm.md

@@ -0,0 +1,91 @@
+In DRO.jl every ADMM optimization consists of two components, the ADMM problem form itself, and the local model, which determines local constraints and objectives.
+
+# Problem Form
+
+## Consensus
+
+The single global variable consensus form can be written as
+
+```math
+\begin{equation}
+\begin{split}
+\min_{\{x_i\},\,z}\;\; \sum_{i=1}^N f_i(x_i) \\
+\quad\text{s.t.}\quad x_i = z,\;\; i=1,\dots,N,
+\end{split}
+\end{equation}
+```
+
+where ``f_i`` is the local objective of agent ``i``, ``x_i`` the decision variable of this agent.
+
+With the dual variable ``u`` and the penalty ``\rho`` the update iteration reads.
+
+```math
+\begin{align}
+x_i^{k+1} 
+&= \arg\min_{x_i} \;
+f_i(x_i) 
++ \frac{\rho}{2}\big\| x_i - \big(z^k - u_i^k \big) \big\|_2^2
+\\
+z^{k+1} 
+&= \arg\min_{z} \;
+g(z) + \frac{N \rho}{2}\left\| 
+z - \Big( \bar{x}^{k+1} + \bar{u}^k \Big) 
+\right\|_2^2 \\
+u_i^{k+1} 
+&= u_i^k + x_i^{k+1} - z^{k+1}
+\end{align}
+```
+
+To instantiate a coordinator for the sharing form, use [`create_consensus_target_reach_admm_coordinator`](@ref). To start the neotiation you need to use [`create_admm_start_consensus`](@ref).
+
+
+## Sharing
+
+Take the sharing problem:
+
+```math
+\begin{equation}
+\begin{split}
+\min_{\{x_i\},\,z}\;\; \sum_{i=1}^N f_i(x_i) \;+\; g(z)\\
+\quad\text{s.t.}\quad \sum_{i=1}^N x_i = z,\;\; i=1,\dots,N,
+\end{split}
+\end{equation}
+```
+
+where ``f_i`` is the local objective of agent ``i``, ``x_i`` the decision variable of this agent, and ``g`` the global objective.
+
+With the dual variable ``u`` and the penalty ``\rho`` the generic update iteration reads.
+
+```math
+\begin{align}
+x_i^{k+1} 
+  &= \arg\min_{x_i}\;
+     f_i(x_i) + \tfrac{\rho}{2}\,\big\lVert x_i - (z^k - u^k) \big\rVert_2^2,
+    \\
+     &i=1,\dots,N, 
+     \\[6pt]
+z^{k+1} 
+  &= \arg\min_{z}\;
+     g(N\cdot z) + \tfrac{N\rho}{2}\,\big\lVert z - \bar{x}^{\,k+1} - u^k \big\rVert_2^2,
+     \\
+\bar{x}^{\,k+1} 
+  &= \tfrac{1}{N}\sum_{i=1}^N x_i^{k+1},
+     \\[6pt]
+u^{k+1} 
+  &= u^k + \bar{x}^{\,k+1} - z^{k+1}. 
+     
+\end{align}
+```
+
+To instantiate a coordinator for the sharing form, use [`create_sharing_admm_coordinator`](@ref). To start the negotiation you can use [`create_admm_start`](@ref).
+
+# Local Models
+
+## Flexibility Actor
+
+Each local actor `ì`` has some flexibility of ``m`` resources and a decision on the provided flexibility ``x_i``. The decision is constrained by
+* lower and upper bounds ``l_i \leq x_i \leq u_i``
+* coupling constraints ``C_i x_i\leq d_i``
+* linear penalites ``S_i`` for priorization
+
+To instantiate a flexibility actor use [`create_admm_flex_actor_one_to_many`](@ref).

docs/src/algorithms/cohda.md

@@ -0,0 +1,15 @@
+COHDA is a distributed optimization heuristic, which solves MC-COP (Multiple Choice Combinatorial Optimization Problem). 
+
+COHDA minimizes the distance of the sum of a set of schedules (distributedly chosen) to a target vector.
+
+```math
+\begin{equation}
+  \begin{split}
+      &\underset{x_{\rm i,j}}{\text{max}}~\left(-\lVert T - \sum_{i=1}^{N}\sum_{j=1}^{M} (U_{\rm i,j}\cdot x_{\rm i,j})\rVert_1\right)\\
+      &\text{with } \sum_{j=1}^{M}x_{{\rm i,j}} = 1\\
+      &x_{{\rm i,j}}\in\left\{0,\,1\right\},~i=1,\,\dots,\,N,~j=1,\,\dots,\,M.
+  \end{split}
+\end{equation}
+```
+
+To use COHDA [`create_cohda_participant`](@ref) and [`create_cohda_start_message`](@ref) can be used.

docs/src/api.md

@@ -46,5 +46,5 @@ Pages = ["algorithm/admm/consensus_admm.jl"]
 ```@autodocs
 Modules = [DistributedResourceOptimization]
 Private = false
-Pages = ["algorithm/admm/conflex_actor.jl"]
+Pages = ["algorithm/admm/flex_actor.jl"]
 ```

docs/src/carrier/mango.md

@@ -0,0 +1,3 @@
+To use the distributed algorithms, the role [`DistributedOptimizationRole`](@ref) can be used to integrate an algorithm. 
+
+Some Distributed Algorithms require a coordinator, in this case another role can be used additionally [`CoordinatorRole`](@ref).

docs/src/carrier/simple.md

@@ -0,0 +1 @@
+TBD

src/algorithm/admm/flex_actor.jl

@@ -44,6 +44,22 @@ function _create_C_and_d(u::Vector{<:Real})
     return C, d
 end
 
+"""
+    create_admm_flex_actor_one_to_many(in_capacity::Real, η::Vector{Float64}, P::Union{Nothing,Vector{<:Real}}=nothing)
+
+Creates an ADMM flex actor for a one-to-many resource allocation scenario.
+
+# Arguments
+- `in_capacity::Real`: The input capacity of the resource.
+- `η::Vector{Float64}`: Vector of efficiency parameters for the ADMM algorithm.
+- `P::Union{Nothing,Vector{<:Real}}`: Optional vector of priorities. If not provided, defaults to `nothing`.
+
+# Returns
+A flex actor object configured for one-to-many ADMM optimization.
+
+# Notes
+This function is typically used in distributed resource optimization problems where a single resource is allocated to multiple consumers using the ADMM algorithm.
+"""
 function create_admm_flex_actor_one_to_many(in_capacity::Real, η::Vector{Float64}, P::Union{Nothing,Vector{<:Real}}=nothing)
     tech_capacity = in_capacity .* η
 

src/algorithm/admm/sharing_admm.jl

@@ -1,4 +1,4 @@
-export create_sharing_target_distance_admm_coordinator, ADMMSharingGlobalActor, ADMMTargetDistanceObjective, create_admm_sharing_data
+export create_sharing_target_distance_admm_coordinator, ADMMSharingGlobalActor, ADMMTargetDistanceObjective, create_admm_sharing_data, create_sharing_admm_coordinator
 
 using JuMP
 using OSQP
@@ -85,3 +85,13 @@ end
 function create_sharing_target_distance_admm_coordinator()
     return ADMMGenericCoordinator(global_actor=ADMMSharingGlobalActor(ADMMTargetDistanceObjective()))
 end
+
+"""
+    create_sharing_admm_coordinator(objective::ADMMGlobalObjective)
+
+# Arguments
+- `objective::ADMMGlobalObjective`: The global objective function to be used in the AD
+"""
+function create_sharing_admm_coordinator(objective::ADMMGlobalObjective)
+    return ADMMGenericCoordinator(global_actor=ADMMSharingGlobalActor(objective))
+end