-
Notifications
You must be signed in to change notification settings - Fork 4
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add first introduction part (Aggregate Programming) #548
base: master
Are you sure you want to change the base?
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #548 +/- ##
=======================================
Coverage 69.51% 69.51%
=======================================
Files 21 21
Lines 561 561
Branches 100 100
=======================================
Hits 390 390
Misses 134 134
Partials 37 37 ☔ View full report in Codecov by Sentry. |
…ate Programming paragraph) and minor changes
@Danix002 I suggest not to close PRs, just leave it open and when you'll add a commit on your branch it will refresh automatically. |
There is no reason, i made a mistake. Thank you." |
I would suggest organizing the docs with the DIVIO framework |
aea439d
to
b20931f
Compare
I've structured the documentation in that way, following: https://docs.divio.com/documentation-system/ |
bd6f037
to
3375d8e
Compare
…ate Programming paragraph) and minor changes
|
||
## Aggregate Programming as a Relevant Approach | ||
|
||
In this context, **aggregate programming**[<sup>1</sup>](#bibliography) (AP) emerges as a **relevant macroprogramming approach**. It is based on the **functional composition** of **reusable collective behavior blocks**, with the goal of efficiently achieving **complex** and **resilient behaviors** in **dynamic networks**. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In this context, **aggregate programming**[<sup>1</sup>](#bibliography) (AP) emerges as a **relevant macroprogramming approach**. It is based on the **functional composition** of **reusable collective behavior blocks**, with the goal of efficiently achieving **complex** and **resilient behaviors** in **dynamic networks**. | |
In this context, **Aggregate Programming**[<sup>1</sup>](#bibliography) (AP) emerges as a **relevant macroprogramming approach**. It is based on the **functional composition** of **reusable collective behavior blocks**, with the goal of efficiently achieving **complex** and **resilient behaviors** in **dynamic networks**. |
|
||
- **Environmental Monitoring**: sensor networks employing AP can collectively estimate parameters like pollution levels, temperature gradients, or wildfire spread by aggregating local measurements efficiently. | ||
|
||
- **Vascular Morphogenesis**[<sup>2</sup>](#bibliography): an early application of AP was demonstrated in the context of vascular morphogenesis, where Collektive was used to model self-organizing biological patterns. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The cited paper is not the correct reference to the Vascular Morphogenesis work, this is the correct one.
|
||
### Field Calculus Constructs | ||
|
||
This layer, depicted as the second layer in the figure, represents the interface where aggregate programming interacts with the external environment, composed of device infrastructure and non-aggregated software services, which together form the system's lowest layer. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this sentence doesn't seem appropriate in this position. Please clarify the concepts written here and put it at the end of this paragraph.
Also, it is not clear about which layer you're writing about, the second from the top or the bottom?
|
||
This layer, depicted as the second layer in the figure, represents the interface where aggregate programming interacts with the external environment, composed of device infrastructure and non-aggregated software services, which together form the system's lowest layer. | ||
|
||
A key abstraction provided by **Field Calculus** is the notion of a *field*, inspired by physical phenomena. In this abstraction, each networked device contributes a local value, forming a distributed structure over the system. For example, temperature sensors might define a field of ambient temperature values, while smartphones might contribute fields of movement directions or displayed notifications. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A key abstraction provided by **Field Calculus** is the notion of a *field*, inspired by physical phenomena. In this abstraction, each networked device contributes a local value, forming a distributed structure over the system. For example, temperature sensors might define a field of ambient temperature values, while smartphones might contribute fields of movement directions or displayed notifications. | |
A key abstraction provided by **Field Calculus** is the notion of a *field*, inspired by physical phenomena. | |
In this abstraction, each networked device contributes a local value, forming a distributed data structure over the system. This data structure represents a mapping from devices to values, enabling decentralized computations that produce globally coordinated behaviors. | |
For example, temperature sensors might define a field representing ambient temperature values, while smartphones might contribute fields representing movement directions or displayed notifications. |
|
||
- **Conditional branching in the network**: conditional mechanisms allow devices to behave differently based on local or global conditions, effectively partitioning the network into distinct regions that execute different operations. | ||
|
||
These constructs together form the building blocks for creating robust and flexible aggregate behaviors. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These constructs together form the building blocks for creating robust and flexible aggregate behaviors. | |
Together, these constructs enable the creation of robust and flexible behaviors that emerge from the aggregation of local device interactions and computations. |
<img src="/img/basic-usage-first-example-4.png" style={{ maxWidth: '70%' }} /> | ||
</div> | ||
|
||
In the third step of the code from the first example, the computed values are assigned to molecules. These molecules can be inspected within the data of a selected device, thereby simplifying the debugging process and enabling a more effective analysis of the system's behavior. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Molecules and relative concentrations are strictly related to the Alchemist Simulator.
In the Collektive first-steps documentation, try to avoid them as much as possible because the tool should potentially run also outside the Alchemist environment.
```kotlin | ||
package it.unibo.collektive.examples.maxID | ||
|
||
import it.unibo.collektive.aggregate.api.Aggregate | ||
import it.unibo.collektive.aggregate.api.operators.neighboringViaExchange | ||
import it.unibo.collektive.field.operations.max | ||
import it.unibo.collektive.alchemist.device.sensors.EnvironmentVariables | ||
|
||
/** | ||
* First example - Tutorial: | ||
* 1. Identify the maximum value among the neighboring nodes. | ||
* 2. Assign a distinct color to the nodes with the identified maximum values. | ||
* Second example - Tutorial: | ||
* 3. Identify the maximum value in the network. | ||
* 4. Assign a distinct color to the nodes with the identified maximum values. | ||
*/ | ||
|
||
fun Aggregate<Int>.maxID(environment: EnvironmentVariables) = | ||
when (environment.get<Boolean>("isMaxID")) { | ||
true -> searchMaxNetworkIDValue(environment) | ||
false -> environment.get<Int>("maxNetworkID") | ||
} | ||
|
||
fun Aggregate<Int>.searchMaxNeighborIDValue(environment: EnvironmentVariables): Int { | ||
// Step 1: Exchange the localId with neighbors and obtain a field of values | ||
val neighborValues = neighboringViaExchange(local = localId) | ||
|
||
// Step 2: Find the maximum value among neighbors (including self) | ||
val maxValue = neighborValues.max(base = localId) | ||
|
||
// Step 3: Assign the result to a molecule | ||
environment.set<Boolean>("isMaxLocalID", localId == maxValue) | ||
environment.set<Int>("maxNeighborID", maxValue) | ||
|
||
return maxValue | ||
} | ||
|
||
fun Aggregate<Int>.searchMaxNetworkIDValue(environment: EnvironmentVariables): Int { | ||
environment.set<Int>("localID", localId) | ||
|
||
when (environment.get<Boolean>("isMaxLocalID")) { | ||
true -> searchMaxNeighborIDValue(environment) | ||
false -> environment.get<Int>("maxNeighborID") | ||
} | ||
|
||
// Step 1: Exchange the maxNeighborID with neighbors and obtain a field of values | ||
val neighborValues = neighboringViaExchange(local = environment.get<Int>("maxNeighborID")) | ||
|
||
// Step 2: Find the maximum value among neighbors (including self) | ||
val maxValue = neighborValues.max(base = environment.get<Int>("maxNeighborID")) | ||
|
||
// Step 3: Assign the result to a molecule | ||
environment.set<Boolean>("isMaxID", localId == maxValue) | ||
environment.set<Int>("maxNetworkID", maxValue) | ||
|
||
return maxValue | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Use the suggestions above to fix this code.
<img src="/img/basic-usage-second-example-2.png" style={{ maxWidth: '70%' }} /> | ||
</div> | ||
|
||
This second example represents a highly simplified demonstration of leader election using the Collektive library. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Explain better what can be observed by the image.
The network remains unchanged from the first example, except for the interconnection radius between devices. A poorly connected network would result in the presence of multiple global maxima within the network. | ||
|
||
<div style={{ textAlign: 'center' }}> | ||
<img src="/img/basic-usage-second-example-2.png" style={{ maxWidth: '70%' }} /> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The network is too dense and displaying the connections in such a network is hard to understand.
It would be better to reduce its density first and then show the connections.
<summary>Click to view images</summary> | ||
<div style={{ textAlign: 'center' }}> | ||
<img src="/img/basic-usage-first-example-1.png" style={{ maxWidth: '70%' }} /> | ||
</div> | ||
|
||
<div style={{ textAlign: 'center' }}> | ||
<img src="/img/basic-usage-first-example-2.png" style={{ maxWidth: '70%' }} /> | ||
</div> | ||
|
||
<div style={{ textAlign: 'center' }}> | ||
<img src="/img/basic-usage-first-example-3.png" style={{ maxWidth: '70%' }} /> | ||
</div> | ||
|
||
<div style={{ textAlign: 'center' }}> | ||
<img src="/img/basic-usage-first-example-4.png" style={{ maxWidth: '70%' }} /> | ||
</div> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When displaying example images, provide a brief description of what can be seen in them.
Site introduction implementation