Merge pull request #162 from nextmv-io/mooneyc/adds-simpy-example

sebastian-quintero · web-flow · commit 683f2108a90e · 2025-12-18T18:14:30.000-05:00
diff --git a/.nextmv/readme/python-simpy-carwash-simulation/0.sh b/.nextmv/readme/python-simpy-carwash-simulation/0.sh
@@ -0,0 +1 @@
+pip3 install -r requirements.txt
diff --git a/.nextmv/readme/python-simpy-carwash-simulation/0.sh.golden b/.nextmv/readme/python-simpy-carwash-simulation/0.sh.golden
diff --git a/.nextmv/readme/python-simpy-carwash-simulation/1.sh b/.nextmv/readme/python-simpy-carwash-simulation/1.sh
@@ -0,0 +1 @@
+python3 main.py -input input.json -output output.json -random_seed -1 -sim_time 20
diff --git a/.nextmv/readme/python-simpy-carwash-simulation/1.sh.golden b/.nextmv/readme/python-simpy-carwash-simulation/1.sh.golden
diff --git a/.nextmv/readme/python-simpy-carwash-simulation/2.sh b/.nextmv/readme/python-simpy-carwash-simulation/2.sh
@@ -0,0 +1 @@
+python3 app.py -action local -input_file input.json
diff --git a/.nextmv/readme/python-simpy-carwash-simulation/2.sh.golden b/.nextmv/readme/python-simpy-carwash-simulation/2.sh.golden
diff --git a/.nextmv/readme/python-simpy-carwash-simulation/3.sh b/.nextmv/readme/python-simpy-carwash-simulation/3.sh
@@ -0,0 +1 @@
+export NEXTMV_API_KEY="<YOUR_API_KEY>"
diff --git a/.nextmv/readme/python-simpy-carwash-simulation/3.sh.golden b/.nextmv/readme/python-simpy-carwash-simulation/3.sh.golden
diff --git a/.nextmv/readme/python-simpy-carwash-simulation/4.sh b/.nextmv/readme/python-simpy-carwash-simulation/4.sh
@@ -0,0 +1 @@
+python3 app.py -action sync -app_id carwash-sim -app_name "Carwash Simulation"
diff --git a/.nextmv/readme/python-simpy-carwash-simulation/4.sh.golden b/.nextmv/readme/python-simpy-carwash-simulation/4.sh.golden
diff --git a/.nextmv/readme/workflow-configuration.yml b/.nextmv/readme/workflow-configuration.yml
@@ -304,6 +304,18 @@ apps:
         silent: true
       - name: 1.sh
         stderr: true
+  - name: python-simpy-carwash-simulation
+    scripts:
+      - name: 0.sh
+        silent: true
+      - name: 1.sh
+        silent: true
+      - name: 2.sh
+        silent: true
+      - name: 3.sh
+        silent: true
+      - name: 4.sh
+        skip: true
   - name: python-tr-ortools-region-allocation
     scripts:
       - name: 0.sh
diff --git a/.nextmv/workflow-configuration.yml b/.nextmv/workflow-configuration.yml
@@ -251,6 +251,12 @@ apps:
     marketplace_app_id:
     marketplace_major_version:
     description: Use Python and SCIP - knapsack.
+  - name: python-simpy-carwash-simulation
+    type: python
+    app_id:
+    marketplace_app_id:
+    marketplace_major_version:
+    description: Use Python and Simpy - carwash simulation.
   - name: python-tr-ortools-region-allocation
     type: python
     app_id:
diff --git a/python-simpy-carwash-simulation/.gitignore b/python-simpy-carwash-simulation/.gitignore
@@ -0,0 +1 @@
+.nextmv
diff --git a/python-simpy-carwash-simulation/README.md b/python-simpy-carwash-simulation/README.md
@@ -0,0 +1,49 @@
+# Nextmv Python Simpy Carwash Simulation
+
+Example for running a Python application on the Nextmv Platform using the Simpy
+library. We simulate a carwash with limited washing machines and random car
+arrivals.
+
+<!-- markdownlint-disable MD013 -->
+
+1. Install packages.
+
+    ```bash
+    pip3 install -r requirements.txt
+    ```
+
+1. Run the app.
+
+    ```bash
+    python3 main.py -input input.json -output output.json -random_seed -1 -sim_time 20
+    ```
+
+1. Create local runs of the app.
+
+    ```bash
+    python3 app.py -action local -input_file input.json
+    ```
+
+1. Export your Nextmv API key as an environment variable.
+
+    ```bash
+    export NEXTMV_API_KEY="<YOUR_API_KEY>"
+    ```
+
+1. Sync the local app with the cloud.
+
+    ```bash
+    python3 app.py -action sync -app_id carwash-sim -app_name "Carwash Simulation"
+    ```
+
+<!-- markdownlint-enable MD013 -->
+
+## Next steps
+
+* Open `main.py` and modify the model.
+* Visit our [docs][docs] and [blog][blog]. Need more assistance?
+  [Contact][contact] us!
+
+[docs]: https://docs.nextmv.io
+[blog]: https://www.nextmv.io/blog
+[contact]: https://www.nextmv.io/contact
diff --git a/python-simpy-carwash-simulation/app.py b/python-simpy-carwash-simulation/app.py
@@ -0,0 +1,45 @@
+import os
+
+import nextmv
+from nextmv import cloud, local
+
+# Initialize the executable code as a local application.
+local_app = local.Application(src=".")  # An app manifest will be created if not provided.
+
+# Use options to choose an action when running this script.
+options = nextmv.Options(
+    nextmv.Option(name="app_id", option_type=str, default="carwash-sim"),
+    nextmv.Option(name="app_name", option_type=str, default="Carwash Simulation"),
+    nextmv.Option(name="action", option_type=str),
+    nextmv.Option(name="input_file", option_type=str, default="input.json"),
+)
+
+if options.action == "sync" or options.action == "push":
+    # Initialize the cloud application.
+    api_key = os.environ.get("NEXTMV_API_KEY")
+    if api_key is None:
+        raise Exception("Please set NEXTMV_API_KEY environment variable")
+
+    client = cloud.Client(api_key=api_key)
+
+    # Create or get the cloud application.
+    cloud_app = cloud.Application.new(
+        client=client,
+        id=options.app_id,
+        name=options.app_name,
+        exist_ok=True,
+    )
+
+# Do a local run.
+if options.action == "local":
+    input = nextmv.load(path=options.input_file)
+    run_1 = local_app.new_run(input=input.data)
+    print(run_1)
+
+# Sync local application with cloud application.
+if options.action == "sync":
+    local_app.sync(target=cloud_app, verbose=True)
+
+# Push to cloud application.
+if options.action == "push":
+    cloud_app.push(app_dir=".", verbose=True)
diff --git a/python-simpy-carwash-simulation/app.yaml b/python-simpy-carwash-simulation/app.yaml
@@ -0,0 +1,50 @@
+# This manifest holds the information the app needs to run on the Nextmv Cloud.
+type: python
+runtime: ghcr.io/nextmv-io/runtime/python:3.11
+python:
+  # All listed packages will get bundled with the app.
+  pip-requirements: requirements.txt
+
+# List all files/directories that should be included in the app. Globbing
+# (e.g.: configs/*.json) is supported.
+files:
+  - main.py
+
+# Configuration options for the application.
+configuration:
+  content:
+    format: json
+  options:
+    items:
+      - name: random_seed
+        description: Seed for random number generator. Use -1 for a random seed.
+        option_type: int
+        default: -1
+        required: false
+        ui:
+          control_type: input
+          display_name: Random Seed
+      - name: sim_time
+        description: Total time to run the simulation (in minutes).
+        option_type: int
+        default: 20
+        required: false
+        ui:
+          control_type: input
+          display_name: Simulation Time
+      - name: input
+        description: Path to input data file, default is stdin.
+        option_type: string
+        default: ""
+        required: false
+        ui:
+          control_type: input
+          display_name: Input Path
+      - name: output
+        description: Path to output data file, default is stdout.
+        option_type: string
+        default: ""
+        required: false
+        ui:
+          control_type: input
+          display_name: Output Path
diff --git a/python-simpy-carwash-simulation/input.json b/python-simpy-carwash-simulation/input.json
@@ -0,0 +1,5 @@
+{
+  "NUM_MACHINES": 2,
+  "WASHTIME": 5,
+  "T_INTER": 7
+}
diff --git a/python-simpy-carwash-simulation/main.py b/python-simpy-carwash-simulation/main.py
@@ -0,0 +1,170 @@
+"""
+Carwash example. https://simpy.readthedocs.io/en/latest/examples/carwash.html
+
+Covers:
+
+- Waiting for other processes
+- Resources: Resource
+
+Scenario:
+  A carwash has a limited number of washing machines and defines
+  a washing processes that takes some (random) time.
+
+  Car processes arrive at the carwash at a random time. If one washing
+  machine is available, they start the washing process and wait for it
+  to finish. If not, they wait until they can use one.
+
+"""
+
+import itertools
+import random
+
+import nextmv
+import simpy
+
+# List to collect all simulation events
+simulation_events = []
+
+# Load the input data and options.
+manifest = nextmv.Manifest.from_yaml(".")
+options = manifest.extract_options()
+input = nextmv.load(options=options, path=options.input)
+data = input.data
+
+
+class Carwash:
+    """A carwash has a limited number of machines (``NUM_MACHINES``) to
+    clean cars in parallel.
+
+    Cars have to request one of the machines. When they got one, they
+    can start the washing processes and wait for it to finish (which
+    takes ``washtime`` minutes).
+
+    """
+
+    def __init__(self, env, num_machines, washtime):
+        self.env = env
+        self.machine = simpy.Resource(env, num_machines)
+        self.washtime = washtime
+
+    def wash(self, car):
+        """The washing processes. It takes a ``car`` processes and tries
+        to clean it."""
+        yield self.env.timeout(self.washtime)
+        pct_dirt = random.randint(50, 99)
+        nextmv.log(f"Carwash removed {pct_dirt}% of {car}'s dirt.")
+        simulation_events.append(
+            {"event": "wash_complete", "car": car, "time": self.env.now, "dirt_removed_pct": pct_dirt}
+        )
+
+
+def car(env, name, cw):
+    """The car process (each car has a ``name``) arrives at the carwash
+    (``cw``) and requests a cleaning machine.
+
+    It then starts the washing process, waits for it to finish and
+    leaves to never come back ...
+
+    """
+    arrival_time = env.now
+    nextmv.log(f"{name} arrives at the carwash at {arrival_time:.2f}.")
+    simulation_events.append({"event": "car_arrival", "car": name, "time": arrival_time})
+
+    with cw.machine.request() as request:
+        yield request
+
+        start_time = env.now
+        wait_time = start_time - arrival_time
+        nextmv.log(f"{name} enters the carwash at {start_time:.2f}.")
+        simulation_events.append({"event": "wash_start", "car": name, "time": start_time, "wait_time": wait_time})
+
+        yield env.process(cw.wash(name))
+
+        departure_time = env.now
+        nextmv.log(f"{name} leaves the carwash at {departure_time:.2f}.")
+        simulation_events.append(
+            {"event": "car_departure", "car": name, "time": departure_time, "total_time": departure_time - arrival_time}
+        )
+
+
+def setup(env, num_machines, washtime, t_inter):
+    """Create a carwash, a number of initial cars and keep creating cars
+    approx. every ``t_inter`` minutes."""
+    # Create the carwash
+    carwash = Carwash(env, num_machines, washtime)
+
+    car_count = itertools.count()
+
+    # Create 4 initial cars
+    for _ in range(4):
+        env.process(car(env, f"Car {next(car_count)}", carwash))
+
+    # Create more cars while the simulation is running
+    while True:
+        yield env.timeout(random.randint(t_inter - 2, t_inter + 2))
+        env.process(car(env, f"Car {next(car_count)}", carwash))
+
+
+# Setup and start the simulation
+nextmv.log("Carwash simulation starting...")
+# Generate random seed if RANDOM_SEED is -1, otherwise use the provided value
+seed = random.randint(0, 1000) if options.random_seed == -1 else options.random_seed
+random.seed(seed)  # This helps to reproduce the results
+nextmv.log(f"Using random seed: {seed}")
+
+# Create an environment and start the setup process
+env = simpy.Environment()
+env.process(
+    setup(
+        env,
+        num_machines=input.data.get("NUM_MACHINES"),
+        washtime=input.data.get("WASHTIME"),
+        t_inter=input.data.get("T_INTER"),
+    )
+)
+
+# Execute!
+env.run(until=options.sim_time)
+nextmv.log("Carwash simulation completed.")
+
+# Calculate summary statistics
+total_cars = len([e for e in simulation_events if e["event"] == "car_arrival"])
+completed_cars = len([e for e in simulation_events if e["event"] == "car_departure"])
+wait_times = [e["wait_time"] for e in simulation_events if e["event"] == "wash_start"]
+total_times = [e["total_time"] for e in simulation_events if e["event"] == "car_departure"]
+
+# Write statistics to statistics.json
+statistics = nextmv.Statistics(
+    result=nextmv.ResultStatistics(
+        value=completed_cars,  # Using completed cars as the objective value
+        custom={
+            "total_cars": total_cars,
+            "completed_cars": completed_cars,
+            "average_wait_time": round(sum(wait_times) / len(wait_times), 2) if wait_times else 0,
+            "average_total_time": round(sum(total_times) / len(total_times), 2) if total_times else 0,
+            "random_seed": seed,
+        },
+    ),
+)
+
+# Restructure events by car
+cars_dict = {}
+for event in simulation_events:
+    car_name = event["car"]
+    if car_name not in cars_dict:
+        cars_dict[car_name] = {"car": car_name, "events": []}
+    cars_dict[car_name]["events"].append(
+        {
+            "event": event["event"],
+            "time": event["time"],
+            **{k: v for k, v in event.items() if k not in ["car", "event", "time"]},
+        }
+    )
+
+# Create output structured by car
+output = nextmv.Output(
+    options=options,
+    solution={"cars": list(cars_dict.values())},
+    statistics=statistics,
+)
+nextmv.write(output, path=options.output)
diff --git a/python-simpy-carwash-simulation/requirements.txt b/python-simpy-carwash-simulation/requirements.txt
@@ -0,0 +1,2 @@
+simpy==4.1.1
+nextmv[all]==0.37.2

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+python3 main.py -input input.json -output output.json -random_seed -1 -sim_time 20`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+python3 app.py -action local -input_file input.json`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+python3 app.py -action sync -app_id carwash-sim -app_name "Carwash Simulation"`