refactor: Add off-the-shelf update policies

.github/workflows/upload_coverage.yaml

@@ -20,16 +20,20 @@ on:
 
 jobs:
   test:
-    name: Run tests and collect coverage
+    name: Run tests on Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
     steps:
       - name: Checkout Source Code
         uses: actions/checkout@v6
 
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: 3.12
+          python-version: ${{ matrix.python-version }}
 
       - name: Install Dependencies
         run: make setup-test
@@ -38,6 +42,7 @@ jobs:
         run: pytest
 
       - name: Upload results to Codecov
+        if: matrix.python-version == '3.11'
         uses: codecov/codecov-action@v6
         with:
           files: ./coverage.xml

.ruff.toml

@@ -1,4 +1,4 @@
-target-version = "py312"
+target-version = "py311"
 
 include = ["eclypse/**/*.py", "tests/**/*.py"]
 line-length = 88
@@ -40,7 +40,7 @@ select = [
     "D",
 ]
 
-ignore = ["D203", "D213", "D100", "D104", "E501", "PLC0415", "UP008"]
+ignore = ["D203", "D213", "D100", "D104", "E501", "PLC0415", "UP008", "UP040"]
 
 fixable = ["ALL"]
 

docs/source/api/index.rst

@@ -10,6 +10,7 @@ Reference
     builders
     graph
     placement
+    policies
     remote
     report
     simulation

docs/source/overview/concepts/topology.rst

@@ -15,12 +15,20 @@ The two classes share many structural similarities, but differ in purpose and in
 
       .. code-block:: python
 
+         from eclypse import policies
          from eclypse.graph.infrastructure import Infrastructure
 
          infrastructure = Infrastructure(
              infrastructure_id="infra",
-             node_update_policy=[...],
-             edge_update_policy=[...],
+             update_policies=[
+                 policies.failure.availability_flap(0.01, up_probability=0.2),
+                 policies.distribution.uniform(
+                     node_assets=["cpu", "ram"],
+                     edge_assets=["latency", "bandwidth"],
+                     node_distribution=(0.95, 1.05),
+                     edge_distribution=(0.95, 1.05),
+                 ),
+             ],
              node_assets=[...],
              edge_assets=[...],
              resource_init="min",
@@ -33,7 +41,7 @@ The two classes share many structural similarities, but differ in purpose and in
       **Key parameters:**
 
       - ``infrastructure_id``: identifier of the infrastructure
-      - ``node_update_policy`` / ``edge_update_policy``: list of :doc:`update policies <update-policy>` for infrastructure resources
+      - ``update_policies``: list of :doc:`update policies <update-policy>` for infrastructure resources
       - ``node_assets`` / ``edge_assets``: available capabilities (:doc:`asset <assets>` values) of nodes and links
       - ``resource_init``: initialisation of resources (*min* or *max*)
       - ``seed``: random seed for reproducibility
@@ -46,12 +54,30 @@ The two classes share many structural similarities, but differ in purpose and in
 
       .. code-block:: python
 
+         from eclypse import policies
          from eclypse.graph.application import Application
 
          application = Application(
              application_id="app",
-             node_update_policy=[...],
-             edge_update_policy=[...],
+             update_policies=[
+                 policies.after(
+                     50,
+                     policies.degrade.reduce(
+                         factor=0.6,
+                         epochs=200,
+                         node_assets=["cpu", "ram"],
+                         edge_assets=["bandwidth"],
+                     ),
+                 ),
+                 policies.after(
+                     50,
+                     policies.degrade.increase(
+                         factor=1.6667,
+                         epochs=200,
+                         edge_assets=["latency"],
+                     ),
+                 ),
+             ],
              node_assets=[...],
              edge_assets=[...],
              requirement_init="min",
@@ -62,7 +88,7 @@ The two classes share many structural similarities, but differ in purpose and in
       **Key parameters:**
 
       - ``application_id``: identifier of the application
-      - ``node_update_policy`` / ``edge_update_policy``: list of :doc:`update policies <update-policy>` for application requirements
+      - ``update_policies``: list of :doc:`update policies <update-policy>` for application requirements
       - ``node_assets`` / ``edge_assets``: resource requirements (:doc:`asset <assets>` values) of services and links
       - ``requirement_init``: initialisation of resources (*min* or *max*)
       - ``seed``: random seed for reproducibility

docs/source/overview/concepts/update-policy.rst

@@ -5,53 +5,188 @@ In ECLYPSE, an update policy is a function that defines how the state of the
 infrastructure or application evolves over time. It enables dynamic
 simulations by modifying node or edge assets at each simulation step.
 
-Unlike assets, update policies are not classes. Instead, they are simple functions with a fixed signature, depending on whether they operate on nodes or edges.
+Unlike assets, update policies are not tied to separate node- or edge-specific
+interfaces. They are simple graph-oriented callables that receive the graph
+being updated.
 
 Function Signature
 ------------------
 
-There are two kinds of update policies:
+.. code-block:: python
+
+   from eclypse.graph import AssetGraph
+
+   def my_policy(graph: AssetGraph):
+       ...
+
+The graph exposes the standard `networkx` views through ``graph.nodes`` and
+``graph.edges``. Each node or edge has an associated data dictionary containing
+its current asset values.
+
+Built-in Policies
+-----------------
+
+ECLYPSE also provides a catalogue of off-the-shelf policies in
+:mod:`eclypse.policies`. The module groups reusable policies into a few common
+families:
 
-- **Node update policies**:
+- **failure**: availability flapping, node failures, and latency spikes
+- **noise**: bounded random walks, momentum walks, and impulse shocks
+- **distribution**: uniform, normal, lognormal, triangular, beta, gamma,
+  truncated-normal, and categorical multiplicative perturbations
+- **degrade**: progressive increase or reduction of selected assets through
+  explicit ``increase()`` and ``reduce()`` policies
+- **replay**: replay of node or edge values from records, dataframes, or parquet files
+- **schedule**: wrappers such as ``every()``, ``after()``, ``between()``, and ``once_at()``
 
-  .. code-block:: python
+For most simulations, the easiest workflow is to compose a few built-in
+policies and only fall back to a custom callable when the behaviour is
+scenario-specific.
 
-     def my_node_policy(nodes: NodeView):
-         ...
+Using Built-in Policies
+-----------------------
+
+Built-in policies are regular graph callables, so you use them exactly like any
+custom update policy.
+
+.. code-block:: python
+    :caption: **Example:** Infrastructure policies composed from ``eclypse.policies``
+
+    from eclypse import policies
+    from eclypse.graph import Infrastructure
+
+    infrastructure = Infrastructure(
+        "edge-cloud",
+        update_policies=[
+            policies.failure.availability_flap(
+                down_probability=0.02,
+                up_probability=0.5,
+                node_filter=lambda _, data: data["availability"] > 0,
+            ),
+            policies.distribution.uniform(
+                node_assets=["cpu", "ram", "storage"],
+                edge_assets=["latency", "bandwidth"],
+                node_asset_distributions={
+                    "cpu": (0.95, 1.05),
+                    "ram": (0.9, 1.1),
+                    "storage": (0.98, 1.02),
+                },
+                edge_asset_distributions={
+                    "latency": (0.95, 1.05),
+                    "bandwidth": (0.98, 1.02),
+                },
+            ),
+        ],
+    )
+
+Selectors and Assets
+--------------------
+
+Most built-in policies separate **what** to change from **where** to change it.
+
+- ``node_assets`` / ``edge_assets`` select which graph assets are updated
+- ``node_ids`` / ``edge_ids`` target specific nodes or links
+- ``node_filter`` / ``edge_filter`` let you target assets dynamically
+
+.. code-block:: python
+    :caption: **Example:** Apply noise only to edge nodes and WAN links
 
-- **Edge update policies**:
+    from eclypse import policies
 
-  .. code-block:: python
+    policy = policies.distribution.uniform(
+        node_assets=["cpu", "ram"],
+        edge_assets=["latency"],
+        node_filter=lambda node_id, data: data.get("tier") == "edge",
+        edge_filter=lambda source, target, data: data.get("kind") == "wan",
+    )
 
-     def my_edge_policy(edges: EdgeView):
-         ...
+Scheduling Policies
+-------------------
 
-Both `NodeView` and `EdgeView` are provided by the `networkx` library and behave like dictionaries over the graph structure. Each node or edge has an associated data dictionary containing asset instances.
-In particular a node is a tuple of the form ``(node_id, node_data)``, where `node_id` is the node identifier and `node_data` is a dictionary containing the asset instances.
-On the other hand, an edge is a tuple of the form ``(source_node_id, target_node_id, edge_data)``, where `source_node_id` and `target_node_id` are the identifiers of the source and target nodes, respectively, and `edge_data` is a dictionary containing the asset instances.
+Scheduling wrappers let you activate a policy only during part of the run.
+
+.. code-block:: python
+    :caption: **Example:** Start value adjustments after step 100
+
+    from eclypse import policies
+
+    update_policies = [
+        policies.after(
+            100,
+            policies.degrade.reduce(
+                factor=0.5,
+                epochs=200,
+                node_assets=["cpu", "ram", "storage"],
+                edge_assets=["bandwidth"],
+            ),
+        ),
+        policies.after(
+            100,
+            policies.degrade.increase(
+                factor=2.0,
+                epochs=200,
+                edge_assets=["latency"],
+            ),
+        ),
+    ]
+
+Replay Policies
+---------------
+
+Replay helpers are useful when you want the simulation to follow observed
+or synthetic measurements over time.
+
+.. code-block:: python
+    :caption: **Example:** Replay node load from a parquet trace
+
+    from eclypse import policies
+
+    replay_users = policies.replay.from_parquet(
+        "examples/user_distribution/dataset.parquet",
+        target="nodes",
+        node_id_column="node_id",
+        time_column="time",
+        value_columns=["user_count"],
+        start_step=0,
+    )
 
 Writing Custom Policies
 -----------------------
 
-You can define your own update policies by modifying the relevant asset values within each node or edge.
+You can define your own update policies by modifying the relevant asset values
+within the graph.
 
 .. code-block:: python
     :caption: **Example:** A node policy that caps CPU to a fixed maximum
 
-    def cap_cpu(nodes: NodeView):
-        for _, data in nodes.items():
+    from eclypse.graph import AssetGraph
+
+    def cap_cpu(graph: AssetGraph):
+        for _, data in graph.nodes.items():
             if "cpu" in data:
-                data["cpu"].value = min(data["cpu"].value, 2.0)
+                data["cpu"] = min(data["cpu"], 2.0)
 
 .. code-block:: python
     :caption: **Example:** An edge policy that increases latency:
 
-    def increase_latency(edges: EdgeView):
-        for _, _, data in edges:
+    from eclypse.graph import AssetGraph
+
+    def add_latency(graph: AssetGraph):
+        for _, _, data in graph.edges.data():
             if "latency" in data:
-                data["latency"].value += 1.0
+                data["latency"] += 1.0
+
+Custom vs built-in
+------------------
+
+Built-in policies are ideal for common patterns such as failures, distributions,
+explicit value adjustments, and replay from traces. When an example or scenario couples
+multiple effects in a very specific way, keeping a custom callable is still the
+right choice. Several examples in the repository intentionally do that to
+preserve their original behaviour.
 
 .. important::
 
    Update policies must always ensure that modified asset values remain consistent.
-   Use the asset's :py:meth:`~eclypse.graph.assets.asset.Asset.is_consistent()` method if needed. Otherwise, placement and simulation logic may occur on inconsistent data.
+   Use the asset's :py:meth:`~eclypse.graph.assets.asset.Asset.is_consistent()` method if needed.
+   Otherwise, placement and simulation logic may occur on inconsistent data.

docs/source/overview/examples/echo.rst

@@ -58,8 +58,9 @@ nodes connected through links with different latency and bandwidth values.
     .. literalinclude:: ../../../../examples/echo/infrastructure.py
         :language: python
 
-The infrastructure is also updated at each iteration through random node and
-edge update policies, which simulate changing runtime conditions.
+The infrastructure is also updated at each iteration through a graph update
+policy that mutates both nodes and links to simulate changing runtime
+conditions.
 
 .. dropdown:: Update policy code
 

docs/source/overview/examples/index.rst

@@ -7,6 +7,7 @@ Examples
    :hidden:
 
    echo
+   off_the_shelf
    sock_shop
 
 The examples section complements the getting-started guides with runnable
@@ -29,6 +30,16 @@ subdirectory of the repository.
          communication patterns.
 
 
+   .. grid-item::
+
+      .. card:: :octicon:`tools;1em;info` **Off-the-shelf**
+         :link-type: doc
+         :link: off_the_shelf
+
+         A local simulation composed only from built-in builders, policies,
+         and placement logic.
+
+
    .. grid-item::
 
       .. card:: :octicon:`package-dependents;1em;info` **SockShop**