Metadata-Version: 2.1
Name: phyelds
Version: 7.6.5
Summary: A lightweight Python library to support aggregate computing!
Home-page: https://github.com/phyelds/phyelds
License: Apache-2.0
Author: Davide Domini
Author-email: davide.domini@unibo.it
Requires-Python: >=3.12,<3.14
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: jupyter
Requires-Dist: ipython (>=7.34.0,<8.0.0) ; extra == "jupyter"
Requires-Dist: matplotlib (>=3.10.1,<3.11.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: pydantic (==2.12.5)
Requires-Dist: wrapt (>=1.17.2,<1.18.0)
Project-URL: Changelog, https://github.com/phyelds/phyelds/blob/master/CHANGELOG.md
Project-URL: Repository, https://github.com/phyelds/phyelds
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/phyelds/phyelds/master/docs/assets/logo.png" alt="phyelds logo" width="96">

# Phyelds

Lightweight, pythonic aggregate computing & field calculus toolkit for building, simulating, and experimenting with large scale distributed systems.

[![PyPI version](https://img.shields.io/pypi/v/phyelds.svg)](https://pypi.org/project/phyelds/)
[![Python versions](https://img.shields.io/pypi/pyversions/phyelds.svg)](https://pypi.org/project/phyelds/)
[![Downloads](https://static.pepy.tech/badge/phyelds/month)](https://pepy.tech/project/phyelds)
[![Tests](https://github.com/phyelds/phyelds/actions/workflows/test.yml/badge.svg)](https://github.com/phyelds/phyelds/actions/workflows/test.yml)
[![Coverage](https://codecov.io/gh/phyelds/phyelds/graph/badge.svg)](https://codecov.io/gh/phyelds/phyelds)
[![Docs](https://github.com/phyelds/phyelds/actions/workflows/docs.yml/badge.svg)](https://phyelds.github.io/phyelds/)
<br>
[![License](https://img.shields.io/github/license/phyelds/phyelds.svg)](https://github.com/phyelds/phyelds/blob/master/LICENSE)
[![Last commit](https://img.shields.io/github/last-commit/phyelds/phyelds.svg)](https://github.com/phyelds/phyelds/commits/master)
[![semantic-release](https://img.shields.io/badge/semantic--release-conventionalcommits-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fe5196?logo=conventionalcommits&logoColor=white)](https://www.conventionalcommits.org/en/v1.0.0/)

**[Documentation](https://phyelds.github.io/phyelds/)** ·
**[Tutorial](https://phyelds.github.io/phyelds/tutorial/)** ·
**[Playground](https://phyelds.github.io/phyelds/playground/)** ·
**[API reference](https://phyelds.github.io/phyelds/reference/calculus/)**

</div>

---

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.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/phyelds/phyelds/master/docs/assets/channel-dark.gif">
    <img src="https://raw.githubusercontent.com/phyelds/phyelds/master/docs/assets/channel.gif" alt="A self-organizing channel between the bottom-left and top-right corners" width="480">
  </picture>
</p>

## Installation

```bash
pip install phyelds                # core library and simulator
pip install "phyelds[jupyter]"     # live rendering inside Jupyter
pip install phyelds-vmas           # VMAS integration
```

Requires Python 3.12+.

## A taste

A *channel* (or corridor): the devices within `WIDTH` of the shortest path between
a source and a target, as in the animation above. It is three building blocks of
the standard library, composed like ordinary Python functions:

```python
from phyelds.calculus import aggregate
from phyelds.libraries.collect import collect_or
from phyelds.libraries.device import sense
from phyelds.libraries.distances import neighbors_distances
from phyelds.libraries.spreading import distance_to

WIDTH = 0.8

@aggregate
def corridor() -> bool:
    distances = neighbors_distances()
    to_target = distance_to(sense("target"), distances)    # gradient towards the target
    on_path = collect_or(to_target, sense("source"))       # mark the path from the source
    return distance_to(on_path, distances) < WIDTH         # widen it into a corridor
```

Every device runs the same function, talking only to its neighbors, and the
corridor heals by itself when devices move or fail. The
[tutorial](https://phyelds.github.io/phyelds/tutorial/) builds it step by step from
`remember` and `neighbors`, and the
[playground](https://phyelds.github.io/phyelds/playground/#example=corridor) runs it
in your browser.

## What's inside

* **Core primitives**: `@aggregate`, `remember`, `neighbors`, `exchange`, `align`, and
  the `NeighborhoodField` abstraction 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**: a pluggable discrete-event simulator with live rendering, animation
  export, and [VMAS](https://github.com/proroklab/VectorizedMultiAgentSimulator)
  integration (`phyelds-vmas`).

Everything is explained in the [documentation](https://phyelds.github.io/phyelds/):
[thinking in fields](https://phyelds.github.io/phyelds/concepts/aggregate-programs/),
[core concepts](https://phyelds.github.io/phyelds/concepts/state/),
[libraries](https://phyelds.github.io/phyelds/concepts/libraries/),
[simulator](https://phyelds.github.io/phyelds/simulator/),
[integration with other runtimes](https://phyelds.github.io/phyelds/integration/),
and [common pitfalls](https://phyelds.github.io/phyelds/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](https://proto.bbn.com/)** & **[Protelis](https://protelis.github.io/)** ([GitHub](https://github.com/Protelis/Protelis)) — 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](https://scafi.github.io/)** ([GitHub](https://github.com/scafi/scafi)) — 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](https://fcpp.github.io/)** ([GitHub](https://github.com/fcpp/fcpp)) — The high-performance C++ field calculus library, from which Phyelds draws the `exchange` primitive (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](https://github.com/Collektive/collektive)** — The Kotlin Multiplatform aggregate computing DSL, which influenced Phyelds's ergonomic `NeighborhoodField` API and automatic alignment of standard language control flow (`if`/`else` AST rewriting via `@aggregate`).

For the ideas behind the paradigm, see the
[main paper on aggregate computing](https://www.sciencedirect.com/science/article/pii/S235222081930032X).

## Development

```bash
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](https://www.conventionalcommits.org/),
since releases are produced from the commit messages.

## Contributors & Acknowledgments

### Main Contributors

* **Gianluca Aguzzi** ([@cric96](https://github.com/cric96)) — [gianluca.aguzzi@unibo.it](mailto:gianluca.aguzzi@unibo.it)
* **Davide Domini** ([@davidedomini](https://github.com/davidedomini)) — [davide.domini@unibo.it](mailto: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](https://github.com/phyelds/phyelds/blob/master/LICENSE).

