Skip to content
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

Open
wants to merge 23 commits into
base: master
Choose a base branch
from

Conversation

Danix002
Copy link

@Danix002 Danix002 commented Nov 7, 2024

Site introduction implementation

@nicolasfara nicolasfara changed the title Added first introduction part (Aggragate Programming paragraph) docs: add first introduction part (Aggragate Programming paragraph) Nov 7, 2024
site/docs/introduction/Aggregate Programming.md Outdated Show resolved Hide resolved
site/yarn.lock Outdated Show resolved Hide resolved
Copy link

codecov bot commented Nov 7, 2024

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 69.51%. Comparing base (fcb0da7) to head (72e9dd6).

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.
📢 Have feedback on the report? Share it here.

@Danix002 Danix002 closed this Nov 7, 2024
@Danix002 Danix002 reopened this Nov 7, 2024
@Danix002 Danix002 closed this Nov 7, 2024
@angelacorte angelacorte reopened this Nov 7, 2024
@angelacorte
Copy link
Collaborator

@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.
Or were there other motivations to close it?

@Danix002
Copy link
Author

Danix002 commented Nov 7, 2024

There is no reason, i made a mistake. Thank you."

@DanySK
Copy link
Contributor

DanySK commented Nov 7, 2024

I would suggest organizing the docs with the DIVIO framework

@DanySK DanySK force-pushed the gh-pages branch 2 times, most recently from aea439d to b20931f Compare November 7, 2024 16:09
@nicolasfara
Copy link
Contributor

I would suggest organizing the docs with the DIVIO framework

I've structured the documentation in that way, following: https://docs.divio.com/documentation-system/

@DanySK DanySK force-pushed the gh-pages branch 4 times, most recently from bd6f037 to 3375d8e Compare November 8, 2024 14:37
site/docs/introduction/_category_.json Outdated Show resolved Hide resolved
site/docs/introduction/aggregate-programming.md Outdated Show resolved Hide resolved
site/docs/introduction/aggregate-programming.md Outdated Show resolved Hide resolved
site/docs/introduction/aggregate-programming.md Outdated Show resolved Hide resolved
site/docs/introduction/aggregate-programming.md Outdated Show resolved Hide resolved
site/docs/introduction/aggregate-programming.md Outdated Show resolved Hide resolved
site/docs/introduction/aggregate-programming.md Outdated Show resolved Hide resolved
site/docs/introduction/aggregate-programming.md Outdated Show resolved Hide resolved
site/docs/introduction/aggregate-programming.md Outdated Show resolved Hide resolved
@DanySK DanySK changed the title docs: add first introduction part (Aggragate Programming paragraph) docs: add first introduction part (Aggregate Programming) Dec 19, 2024

## 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**.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Copy link
Collaborator

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.
Copy link
Collaborator

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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Copy link
Collaborator

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.

Comment on lines +88 to +144
```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
}
Copy link
Collaborator

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.
Copy link
Collaborator

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%' }} />
Copy link
Collaborator

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.

Comment on lines +60 to +75
<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>
Copy link
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants