Off-the-shelf

This example shows a complete local simulation built only from reusable ECLYPSE components:

• the get_hotel_reservation() application builder

• an infrastructure builder from eclypse.builders.infrastructure

• built-in update policies from eclypse.policies

• a built-in placement strategy

Use it when you want a minimal reference for composing existing building blocks without writing custom services, topologies, or policy callables.

The full code lives in the examples/off_the_shelf directory.

Run it from the repository root with:

uv run off-the-shelf

Application

The application is the built-in hotel reservation graph, paired with built-in uniform-distribution and degradation policies that progressively make placement harder.

ECLYPSE also provides several other ready-made application builders collected in eclypse.builders.application.

Application code

"""Application built entirely from off-the-shelf ECLYPSE components."""

from __future__ import annotations

from eclypse import policies
from eclypse.builders.application import get_hotel_reservation


def get_application(seed: int = 7):
    """Create a hotel reservation application using built-in policies only."""
    return get_hotel_reservation(
        application_id="HotelReservationBuiltins",
        include_default_assets=True,
        seed=seed,
        update_policies=[
            policies.every(
                2,
                policies.distribution.uniform(
                    node_assets=["cpu", "ram"],
                    edge_assets=["latency", "bandwidth"],
                    node_distribution=(1.02, 1.18),
                    edge_distribution=(0.98, 1.08),
                ),
                start=2,
            ),
            policies.after(
                6,
                policies.degrade.reduce(
                    factor=0.8,
                    epochs=14,
                    node_assets=["cpu", "ram"],
                    edge_assets=["bandwidth"],
                ),
            ),
            policies.after(
                6,
                policies.degrade.increase(
                    factor=1.25,
                    epochs=14,
                    edge_assets=["latency"],
                ),
            )
        ],
    )

Infrastructure

The infrastructure is a generated hierarchical topology using the default assets and a built-in policy mix for flapping availability, uniform perturbations, periodic latency spikes, and scheduled degradation. ECLYPSE also provides several other off-the-shelf infrastructure builders collected in eclypse.builders.infrastructure. Together with BestFitStrategy, this example exercises repeated placement under a changing environment.

Infrastructure code

"""Infrastructure built entirely from off-the-shelf ECLYPSE components."""

from __future__ import annotations

from eclypse import policies
from eclypse.builders.infrastructure import get_hierarchical


def get_infrastructure(seed: int = 7):
    """Create a generated infrastructure with built-in update policies."""
    return get_hierarchical(
        n=64,
        infrastructure_id="BuiltinsInfrastructure",
        symmetric=True,
        update_policies=[
            policies.failure.availability_flap(
                down_probability=0.04,
                up_probability=0.15,
            ),
            policies.distribution.uniform(
                node_asset_distributions={
                    "cpu": (0.85, 1.12),
                    "ram": (0.8, 1.15),
                    "storage": (0.92, 1.08),
                },
                edge_asset_distributions={
                    "latency": (0.95, 1.2),
                    "bandwidth": (0.82, 1.08),
                },
            ),
            policies.every(
                2,
                policies.failure.latency_spike(
                    probability=0.35,
                    min_increase=122.0,
                    max_increase=126.0,
                ),
                start=2,
            ),
            policies.after(
                5,
                policies.degrade.reduce(
                    factor=0.82,
                    epochs=12,
                    node_assets=["cpu", "ram", "storage"],
                    edge_assets=["bandwidth"],
                ),
            ),
            policies.after(
                5,
                policies.degrade.increase(
                    factor=1.22,
                    epochs=12,
                    edge_assets=["latency"],
                ),
            ),
        ],
        include_default_assets=True,
        resource_init="max",
        seed=seed,
    )

Simulation

The simulation registers the built-in application on the generated infrastructure with a built-in placement strategy and runs it locally.

Simulation code

"""Local simulation showcasing off-the-shelf ECLYPSE building blocks."""

from __future__ import annotations

from eclypse.placement.strategies import BestFitStrategy
from eclypse.simulation import (
    Simulation,
    SimulationConfig,
)
from eclypse.utils.defaults import get_default_sim_path

from .application import get_application
from .events import get_events
from .infrastructure import get_infrastructure


def main() -> None:
    """Run the off-the-shelf example."""
    SEED = 42
    MAX_STEPS = 50
    simulation = Simulation(
        get_infrastructure(seed=SEED),
        simulation_config=SimulationConfig(
            seed=SEED,
            max_steps=MAX_STEPS,
            step_every_ms="auto",
            include_default_metrics=True,
            events=get_events(),
            log_to_file=True,
            path=get_default_sim_path() / "OffTheShelf",
            log_level="TRACE",
        ),
    )

    simulation.register(get_application(seed=SEED), BestFitStrategy())
    simulation.run()
    print(simulation.report.application())


if __name__ == "__main__":
    main()