Phyelds
Lightweight, pythonic aggregate computing & field calculus toolkit for building, simulating, and experimenting with large scale distributed systems.
You write one function for a whole collective (a swarm of robots, a sensor network, a fleet of devices) and every device runs it in rounds, exchanging values only with its neighbors. Global behaviour emerges from local state and local communication, and the library stays small enough to read in an afternoon.
Installation
pip install phyelds # core: the calculus and the libraries
pip install phyelds-simulator # the simulator, with a compatible phyelds
pip install "phyelds-simulator[jupyter]" # live rendering inside Jupyter
pip install phyelds-vmas # VMAS integration
pip install phyelds-mesa # Mesa integration
pip install phyelds-webots # Webots integration
Requires Python 3.12+.
A taste
A channel: the devices on a route from a source to a target at most width longer
than the shortest one. A device is on such a route when its distance from the source
plus its distance from the target is close to the distance between the two, so the
channel is three gradients of the standard library, composed like ordinary Python
functions:
from phyelds.calculus import aggregate
from phyelds.libraries.distances import neighbors_distances
from phyelds.libraries.spreading import distance_between, distance_to
@aggregate
def channel(source: bool, target: bool, width: float) -> bool:
distances = neighbors_distances()
to_source = distance_to(source, distances)
to_target = distance_to(target, distances)
between = distance_between(source, target, distances)
return to_source + to_target <= between + width
Every device runs the same function, talking only to its neighbors, and the
channel heals by itself when devices move or fail. The
playground runs it
in your browser, and the tutorial
builds the gradient beneath it step by step from remember and neighbors.
What's inside
- Core primitives:
@aggregate,remember,neighbors,exchange,align, and theNeighborhoodFieldabstraction with element-wise arithmetic. - Standard libraries: spreading, collection, gossip, leader election, time &
reactive state, aggregate processes (
@process/spawn), and spatial/temporal logic (SLCS & Past-CTL). - Simulator (
phyelds-simulator): a pluggable discrete-event simulator with live rendering, animation export, and VMAS integration (phyelds-vmas). - Mesa (
phyelds-mesa): phyelds programs on the agents of a Mesa model. - Webots (
phyelds-webots): phyelds programs on the robots of a Webots simulation, talking over their simulated radios. - MicroPython: the same programs run on microcontrollers such as the ESP32
(
python -m phyelds.micropython), and talk with devices running CPython. - Experimental (
phyelds.experimental): studies in progress, whose API will probably change, such as collective state machines and swarm behaviours.
Everything is explained in the documentation: thinking in fields, core concepts, libraries, simulator, integration with other runtimes, MicroPython and the ESP32, experimental studies, and common pitfalls.
Heritage & Related Projects
Phyelds stands on the shoulders of over a decade of research and open-source tools in spatial and aggregate computing, bringing their ideas into a lightweight, Python-native library designed to integrate naturally with Python's scientific, simulation, and machine-learning ecosystem:
- Proto & Protelis (GitHub) — The pioneering spatial computing and aggregate programming languages that established the computational field abstraction, the
rep/nbr(remember/neighbors) round-based execution model, and the self-organizing coordination building blocks. - ScaFi (GitHub) — The Scala toolkit for aggregate programming, which inspired Phyelds's internal-DSL approach, standard coordination blocks (
G/C/S,summarize,channel, reactive state and time operators), and spatially/temporally scoped aggregate processes (@process/spawn). - FCPP (GitHub) — The high-performance C++ field calculus library, from which Phyelds draws the
exchangeprimitive (from Exchange Calculus), resilient coordination strategies (path-coherent gradients, multi-path and point-to-point collection, bounded leader election), and spatial/temporal logic operators (SLCS and Past-CTL). - Collektive — The Kotlin Multiplatform aggregate computing DSL, which influenced Phyelds's ergonomic
NeighborhoodFieldAPI and automatic alignment of standard language control flow (if/elseAST rewriting via@aggregate).
For the ideas behind the paradigm, see the main paper on aggregate computing.
Development
git clone https://github.com/phyelds/phyelds.git
cd phyelds
poetry install
poetry run pytest
poetry run pylint src/
poetry run flake8
Contributions are welcome: open an issue for non-trivial changes, keep PRs focused and tested, and use Conventional Commits, since releases are produced from the commit messages.
Contributors & Acknowledgments
Main Contributors
- Gianluca Aguzzi (@cric96) — gianluca.aguzzi@unibo.it
- Davide Domini (@davidedomini) — davide.domini@unibo.it
Acknowledgments
Special thanks to Mirko Viroli, Ferruccio Damiani, Danilo Pianini, Roberto Casadei, and Giorgio Audrito for the insightful discussions, foundational ideas, and continuous feedback that made this project possible.
License
Apache License 2.0 – see LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for phyelds 8.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| phyelds-8.5.0.tar.gz | 76.1 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| phyelds-8.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 170.6 kB
Release files / phyelds-8.5.0.tar.gz
| Download URL | phyelds-8.5.0.tar.gz |
|---|---|
| Size | 76.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dd737e9ca457946c81a549e2e9e07520565c3265f5e8d698d2e00a50dea8bdf0
|
|
BLAKE2b-256 checksum How to use checksums |
ca3ff267140822d9fdfd7a67a2926664c1ba5bc8b4f6cce9d3c10fb29cc46ce9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.0 CPython/3.13.16 Linux/7.0.0-1017-azure
|
Release files / phyelds-8.5.0-py3-none-any.whl
| Download URL | phyelds-8.5.0-py3-none-any.whl |
|---|---|
| Size | 94.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6e625b5bd997796f11210ca497dd5b20224cd34d686112b32f36dca95ef5ee51
|
|
BLAKE2b-256 checksum How to use checksums |
3589df24c4fc068f7daa7790912b392b9fccc8d5d93b6d3025950cf7b374cdf5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.0 CPython/3.13.16 Linux/7.0.0-1017-azure
|
Security for phyelds 8.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
