Improving and updating docs regarding carrier usage.

Author: rcschrg

README.md

@@ -10,83 +10,57 @@ Currently there are three tested algorithms:
 * ADMM sharing variant on flexibility providing resources
 * COHDA, Combinatorial Optimization Heuristic for Distributed Agents, which minimizes the distance of schedule sums to a given target schedule
 
-There is one carrier implemented:
+There are two carrier implemented:
+* A lightweight built-in carrier
 * Mango.jl, agent framework for the simulation of distributed systems, DO provides roles to which the specific algorithms can be assigned to
 
-Note that the package is highly work in progress.
+Note that the package is still work in progress.
 
-### Using the sharing ADMM with flex actors (e.g. for resource optimization) with Mango.jl
+## Examples
 
-```julia
-using Mango
-using DistributedResourceOptimization
+### Using the sharing ADMM with flex actors (e.g. for energy resource optimization) 
 
-@role struct HandleOptimizationResultRole
-    got_it::Bool = false
-end
+You can use DRO in two different ways, using the express style, just executing the distributed optimization routine without embedding it into a larger system. For that two different ways are available, distributed and coordinated optimization.
 
-function Mango.handle_message(role::HandleOptimizationResultRole, message::OptimizationFinishedMessage, meta::Any)
-    role.got_it = true
-end
+#### Coordinated (ADMM Sharing with resource actors)
 
-container = create_tcp_container("127.0.0.1", 5555)
+```julia
+using DistributedResourceOptimization
 
-# create participant models
 flex_actor = create_admm_flex_actor_one_to_many(10, [0.1, 0.5, -1])
 flex_actor2 = create_admm_flex_actor_one_to_many(15, [0.1, 0.5, -1])
-flex_actor3 = create_admm_flex_actor_one_to_many(10, [0.1, 0.5, -1])
+flex_actor3 = create_admm_flex_actor_one_to_many(10, [-1.0, 0.0, 1.0])
 
-# create coordinator with objective
 coordinator = create_sharing_target_distance_admm_coordinator()
 
-# create roles to integrate admm in Mango.jl
-dor = DistributedOptimizationRole(flex_actor, tid=:custom)
-dor2 = DistributedOptimizationRole(flex_actor2, tid=:custom)
-dor3 = DistributedOptimizationRole(flex_actor3, tid=:custom)
-coord_role = CoordinatorRole(coordinator, tid=:custom, include_self=true)
-
-# role to handle a result
-handle = HandleOptimizationResultRole()
-handle2 = HandleOptimizationResultRole()
-handle3 = HandleOptimizationResultRole()
-
-# create agents
-add_agent_composed_of(container, dor, handle)
-c = add_agent_composed_of(container, dor2, handle2)
-ca = add_agent_composed_of(container, coord_role, dor3, handle3)
-
-# create a topology of the agents
-auto_assign!(complete_topology(3, tid=:custom), container)
-
-# run the simulation with start message and wait for result
-activate(container) do
-    wait(send_message(c, StartCoordinatedDistributedOptimization(create_admm_start(create_admm_sharing_data([0.2, 1, -2]))), address(ca)))
-    wait(coord_role.task)
-end
+admm_start = create_admm_start(create_admm_sharing_data([-4, 0, 6], [5,1,1]))
+
+start_coordinated_optimization([flex_actor, flex_actor2, flex_actor3], coordinator, admm_start)
 ```
 
-### Using COHDA with Mango.jl
+#### Distributed (COHDA)
 
 ```julia
-using Mango
 using DistributedResourceOptimization
 
-container = create_tcp_container("127.0.0.1", 5555)
-
-# create agents with local model wrapped in the general distributed optimization role
-agent_one = add_agent_composed_of(container, DistributedOptimizationRole(
-    create_cohda_participant(1, [[0.0, 1, 2], [1, 2, 3]])))
-agent_two = add_agent_composed_of(container, DistributedOptimizationRole(
-    create_cohda_participant(2, [[0.0, 1, 2], [1, 2, 3]])))
+actor_one = create_cohda_participant(1, [[0.0, 1, 2], [1, 2, 3]])
+actor_two = create_cohda_participant(2, [[0.0, 1, 2], [1, 2, 3]])
 
-# create start message
 initial_message = create_cohda_start_message([1.2, 2, 3])
 
-# create topology
-auto_assign!(complete_topology(2), container)
+wait(start_distributed_optimization([actor_one, actor_two], initial_message))
+```
+
+If you need more control, e.g. when integrate the optimization into a larger system we recommend using the carrier system directly, e.g with the built-in carrier:
+
+```julia
+using DistributedResourceOptimization
+
+container = ActorContainer()
+actor_one = SimpleCarrier(container, create_cohda_participant(1, [[0.0, 1, 2], [1, 2, 3]]))
+actor_two = SimpleCarrier(container, create_cohda_participant(2, [[0.0, 1, 2], [1, 2, 3]]))
+
+initial_message = create_cohda_start_message([1.2, 2, 3])
 
-# run simulation
-activate(container) do
-    send_message(agent_one, initial_message, address(agent_two))
-end
+wait(send_to_other(actor_one, initial_message, cid(actor_two))) 
 ```

docs/src/api.md

@@ -16,15 +16,15 @@ Private = false
 Pages = ["carrier/core.jl"]
 ```
 
-## Simple
+### Simple
 
 ```@autodocs
 Modules = [DistributedResourceOptimization]
 Private = false
 Pages = ["carrier/simple.jl"]
 ```
 
-## Mango
+### Mango
 
 ```@autodocs
 Modules = [DistributedResourceOptimization]
@@ -33,23 +33,24 @@ Pages = ["carrier/mango.jl"]
 ```
 
 # ADMM
-## ADMM Sharing
+
+### Sharing
 
 ```@autodocs
 Modules = [DistributedResourceOptimization]
 Private = false
 Pages = ["algorithm/admm/sharing_admm.jl"]
 ```
 
-## ADMM Consensus
+### Consensus
 
 ```@autodocs
 Modules = [DistributedResourceOptimization]
 Private = false
 Pages = ["algorithm/admm/consensus_admm.jl"]
 ```
 
-## ADMM Flex
+### Actors
 
 ```@autodocs
 Modules = [DistributedResourceOptimization]

docs/src/getting_started.md

@@ -1,75 +1,48 @@
-### Using the sharing ADMM with flex actors (e.g. for resource optimization) with Mango.jl
+## Getting Started
 
-```julia
-using Mango
-using DistributedResourceOptimization
+### Using the sharing ADMM with flex actors (e.g. for energy resource optimization) 
 
-@role struct HandleOptimizationResultRole
-    got_it::Bool = false
-end
+You can use DRO in two different ways, using the express style, just executing the distributed optimization routine without embedding it into a larger system. For that two different ways are available, distributed and coordinated optimization.
 
-function Mango.handle_message(role::HandleOptimizationResultRole, message::OptimizationFinishedMessage, meta::Any)
-    role.got_it = true
-end
+#### Coordinated (ADMM Sharing with resource actors)
 
-container = create_tcp_container("127.0.0.1", 5555)
+```julia
+using DistributedResourceOptimization
 
-# create participant models
 flex_actor = create_admm_flex_actor_one_to_many(10, [0.1, 0.5, -1])
 flex_actor2 = create_admm_flex_actor_one_to_many(15, [0.1, 0.5, -1])
-flex_actor3 = create_admm_flex_actor_one_to_many(10, [0.1, 0.5, -1])
+flex_actor3 = create_admm_flex_actor_one_to_many(10, [-1.0, 0.0, 1.0])
 
-# create coordinator with objective
 coordinator = create_sharing_target_distance_admm_coordinator()
 
-# create roles to integrate admm in Mango.jl
-dor = DistributedOptimizationRole(flex_actor, tid=:custom)
-dor2 = DistributedOptimizationRole(flex_actor2, tid=:custom)
-dor3 = DistributedOptimizationRole(flex_actor3, tid=:custom)
-coord_role = CoordinatorRole(coordinator, tid=:custom, include_self=true)
-
-# role to handle a result
-handle = HandleOptimizationResultRole()
-handle2 = HandleOptimizationResultRole()
-handle3 = HandleOptimizationResultRole()
-
-# create agents
-add_agent_composed_of(container, dor, handle)
-c = add_agent_composed_of(container, dor2, handle2)
-ca = add_agent_composed_of(container, coord_role, dor3, handle3)
-
-# create a topology of the agents
-auto_assign!(complete_topology(3, tid=:custom), container)
-
-# run the simulation with start message and wait for result
-activate(container) do
-    wait(send_message(c, StartCoordinatedDistributedOptimization(create_admm_start(create_admm_sharing_data([0.2, 1, -2]))), address(ca)))
-    wait(coord_role.task)
-end
+admm_start = create_admm_start(create_admm_sharing_data([-4, 0, 6], [5,1,1]))
+
+start_coordinated_optimization([flex_actor, flex_actor2, flex_actor3], coordinator, admm_start)
 ```
 
-### Using COHDA with Mango.jl
+#### Distributed (COHDA)
 
 ```julia
-using Mango
 using DistributedResourceOptimization
 
-container = create_tcp_container("127.0.0.1", 5555)
-
-# create agents with local model wrapped in the general distributed optimization role
-agent_one = add_agent_composed_of(container, DistributedOptimizationRole(
-    create_cohda_participant(1, [[0.0, 1, 2], [1, 2, 3]])))
-agent_two = add_agent_composed_of(container, DistributedOptimizationRole(
-    create_cohda_participant(2, [[0.0, 1, 2], [1, 2, 3]])))
+actor_one = create_cohda_participant(1, [[0.0, 1, 2], [1, 2, 3]])
+actor_two = create_cohda_participant(2, [[0.0, 1, 2], [1, 2, 3]])
 
-# create start message
 initial_message = create_cohda_start_message([1.2, 2, 3])
 
-# create topology
-auto_assign!(complete_topology(2), container)
+wait(start_distributed_optimization([actor_one, actor_two], initial_message))
+```
+
+If you need more control, e.g. when integrate the optimization into a larger system we recommend using the carrier system directly, e.g with the built-in carrier:
+
+```julia
+using DistributedResourceOptimization
+
+container = ActorContainer()
+actor_one = SimpleCarrier(container, create_cohda_participant(1, [[0.0, 1, 2], [1, 2, 3]]))
+actor_two = SimpleCarrier(container, create_cohda_participant(2, [[0.0, 1, 2], [1, 2, 3]]))
+
+initial_message = create_cohda_start_message([1.2, 2, 3])
 
-# run simulation
-activate(container) do
-    send_message(agent_one, initial_message, address(agent_two))
-end
+wait(send_to_other(actor_one, initial_message, cid(actor_two))) 
 ```

docs/src/index.md

@@ -7,9 +7,8 @@ Currently there are three tested algorithms:
 * ADMM sharing variant on flexibility providing resources
 * COHDA, Combinatorial Optimization Heuristic for Distributed Agents, which minimizes the distance of schedule sums to a given target schedule
 
-There is one carrier implemented:
+There are two carrier implemented:
+* A lightweight built-in carrier
 * Mango.jl, agent framework for the simulation of distributed systems, DO provides roles to which the specific algorithms can be assigned to
 
-Note that the package is highly work in progress. 
-
-However, DRO is available on the general Julia registry, and can therfore be installed calling `]add DistributedResourceOptimization`.
+Note that the package is still work in progress.

src/algorithm/admm/consensus_admm.jl

@@ -42,6 +42,11 @@ function create_consensus_target_reach_admm_coordinator()
     return ADMMGenericCoordinator(global_actor=ADMMConsensusGlobalActor())
 end
 
+"""
+    create_admm_start_consensus(target::Vector{<:Real})
+
+    Create an `ADMMStart` message for consensus ADMM with the specified target vector.
+"""
 function create_admm_start_consensus(target::Vector{<:Real})
     return ADMMStart(target, length(target))
 end