CI Python 3.13 only; Dockerfile fix and docs; README tests section; PID plot; utils docstrings and imports

Made-with: Cursor

Author: GaetanoCarlucci

.github/workflows/ci.yml

@@ -11,25 +11,21 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-    
-    strategy:
-      matrix:
-        python-version: ["3.9", "3.13"]
 
     steps:
       - name: Check out the repository
         uses: actions/checkout@v4
-        
-      - name: Set up Python ${{ matrix.python-version }}
+
+      - name: Set up Python 3.13
         uses: actions/setup-python@v4
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.13"
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt
-      
+
       - name: Run tests
         run: |
           python tests/PID.py

Dockerfile

@@ -1,3 +1,6 @@
+# Image to run the CPU load generator in a container.
+# Build: docker build -t cpuloadgen .
+# Run:   docker run --rm cpuloadgen -c 0 -l 0.2 -d 10
 FROM python:3.13
 LABEL maintainer="GaetanoCarlucci <gaetano.carlucci@gmail.com>"
 
@@ -6,5 +9,5 @@ RUN cd / && git clone https://github.com/GaetanoCarlucci/CPULoadGenerator.git /C
 RUN pip install -r /CPULoadGenerator/requirements.txt
 
 WORKDIR /CPULoadGenerator
-ENTRYPOINT ["./cpu_load_generator.py"]
+ENTRYPOINT ["python", "cpu_load_generator.py"]
 CMD ["--help"]

README.md

@@ -72,3 +72,9 @@ Or make the script executable and run: `chmod +x cpu_load_generator.py` then `./
 5. **Example graph of CPU load (50% target on core 0):**
 
    ![Example - 50% load on CPU core 0](https://raw.githubusercontent.com/molguin92/CPULoadGenerator/python3_port_stable/50%25-Target-Load.png)
+
+## Tests
+
+Test and identification scripts live in `tests/` (see `tests/README.md`). Expected output from the PID script after CPU identification:
+
+![Expected output from the PID script after CPU identification](tests/PID_Actuation.png)

cpu_load_generator.py

@@ -4,13 +4,12 @@
 # Authors: Gaetano Carlucci
 #         Giuseppe Cofano
 # Python3 port: Manuel Olguín
+import argparse
 import itertools
 import multiprocessing
 import os
 import signal
-from typing import cast, Callable
-
-import click
+import sys
 import psutil
 
 from utils.ClosedLoopActuator import ClosedLoopActuator, \
@@ -99,71 +98,59 @@ def load_core(target_core, target_load,
         control.join()
 
 
-def __validate_cpu_load(_ctx, _param, value):
-    for v in value:
+def _parse_args():
+    """Parse command-line arguments. Exits on validation errors."""
+    available = _available_cores()
+    p = argparse.ArgumentParser(
+        description='Generate a fixed CPU load on one or more cores (PI controller).'
+    )
+    p.add_argument(
+        '--core', '-c', type=int, nargs='*', default=available,
+        metavar='N',
+        help=f'CPU core(s) to load (default: all: {available})'
+    )
+    p.add_argument(
+        '--cpu_load', '-l', type=float, nargs='*', default=[0.2],
+        metavar='L',
+        help='Target load per core in [0, 1]; one value for all cores (default: 0.2)'
+    )
+    p.add_argument(
+        '--duration', '-d', type=float, default=-1,
+        help='Duration in seconds; negative = until SIGINT/SIGTERM (default: -1)'
+    )
+    p.add_argument(
+        '--plot', '-p', action='store_true',
+        help='Plot CPU load and save a PNG (single core, fixed duration only)'
+    )
+    p.add_argument(
+        '--sampling_interval', '-s', type=float, default=0.1,
+        help='PI controller sampling interval in seconds (default: 0.1)'
+    )
+    args = p.parse_args()
+
+    core = args.core if args.core else available
+    cpu_load = args.cpu_load if args.cpu_load else [0.2]
+
+    for v in core:
+        if v not in available:
+            sys.exit(f'Target core {v} is not in available cores: {available}')
+    for v in cpu_load:
         if not 0. <= v <= 1.:
-            msg = f'CPU load {v} out of range [0, 1]'
-            raise click.BadOptionUsage(message=msg, option_name='cpu_load')
-    return value
-
-
-def __validate_cpu_core(_ctx, _param, value):
-    available_cores = _available_cores()
-
-    for v in value:
-        if v not in available_cores:
-            msg = (f'Target core ({v}) is not one of the available cores: '
-                   f'{available_cores}')
-            raise click.BadOptionUsage(message=msg, option_name='core')
-    return value
-
-
-def __validate_sampling_interval(_ctx, _param, value):
-    if value < 0:
-        msg = f'Sampling interval cannot be negative ({value}).'
-        raise click.BadOptionUsage(message=msg, option_name='sampling_interval')
-    return value
-
-
-@click.command()
-@click.option('--core', '-c',
-              type=int, callback=__validate_cpu_core,
-              required=True, multiple=True,
-              help='CPU core to artificially load. '
-                   'Can be specified multiple times to load multiple cores, '
-                   'default is all cores.',
-              default=_available_cores(),
-              show_default=True)
-@click.option('--cpu_load', '-l',
-              type=float, multiple=True,
-              help='Target CPU load. If only one value is provided, '
-                   'it is applied to all affected cores, otherwise specifies '
-                   'load per affected core.',
-              default=[0.2], show_default=True, callback=__validate_cpu_load)
-@click.option('--duration', '-d',
-              type=float, default=-1, show_default=True,
-              help='Duration in seconds. If omitted or negative, '
-                   'program will run until a SIGINT or SIGTERM is received.')
-@click.option('--plot', '-p',
-              is_flag=True, default=False, show_default=True,
-              help='Plot the resulting CPU load (and save a PNG at the end). '
-                   'Can only be used with a fixed duration.')
-@click.option('--sampling_interval', '-s',
-              type=float, default=0.1, show_default=True,
-              help='Sampling interval, in seconds, '
-                   'for the internal PI controller. '
-                   'Changing this value is strongly discouraged!',
-              callback=__validate_sampling_interval)
-
-def __main(core, cpu_load, duration, plot, sampling_interval):
-    if plot and duration < 0:
-        msg = 'Plot option can only be used with a fixed duration.'
-        raise click.BadOptionUsage(message=msg, option_name='plot')
-
+            sys.exit(f'CPU load {v} out of range [0, 1]')
+    if args.sampling_interval < 0:
+        sys.exit(f'Sampling interval cannot be negative ({args.sampling_interval})')
+    if args.plot and args.duration < 0:
+        sys.exit('Plot option requires a fixed duration (use -d SECONDS).')
     if len(cpu_load) > 1 and len(cpu_load) != len(core):
-        msg = 'Number of cores and loads does not match.'
-        raise click.BadOptionUsage(message=msg, option_name='cpu_load')
-    elif len(cpu_load) == 1:
+        sys.exit('Number of cores and loads must match when specifying multiple loads.')
+
+    return core, cpu_load, args.duration, args.plot, args.sampling_interval
+
+
+def _main() -> None:
+    """Entry point: parse CLI, then run load on selected core(s)."""
+    core, cpu_load, duration, plot, sampling_interval = _parse_args()
+    if len(cpu_load) == 1:
         cpu_load = itertools.repeat(cpu_load[0], len(core))
 
     # filter out repeated core indexes
@@ -195,4 +182,4 @@ def __main(core, cpu_load, duration, plot, sampling_interval):
 
 
 if __name__ == '__main__':
-    cast(Callable[[], None], __main)()
+    _main()

requirements.txt

@@ -1,3 +1,2 @@
-matplotlib
-psutil
-click
+matplotlib>=3.5,<5
+psutil>=5.9,<7

tests/PID.py

@@ -15,7 +15,7 @@
 from cpu_load_generator import _available_cores
 from utils.Monitor import MonitorThread
 from utils.Controller import ControllerThread
-from utils.ClosedLoopActuator import ClosedLoopActuator
+from utils.ClosedLoopActuator import ClosedLoopActuator, PlottingClosedLoopActuator
 
 if __name__ == "__main__":
 
@@ -36,8 +36,10 @@
 
         control = ControllerThread(0.1)
         monitor = MonitorThread(core, 0.1)
-        actuator = ClosedLoopActuator(control, monitor, len(cpuSequence) *
-                                      stepPeriod, 1)
+        # Use PlottingClosedLoopActuator to see real-time plot; use ClosedLoopActuator for no plot
+        actuator_cls = PlottingClosedLoopActuator if dynamics_plot_online else ClosedLoopActuator
+        actuator = actuator_cls(control, monitor, len(cpuSequence) *
+                                stepPeriod, core)
 
         monitor.start()
         control.start()

tests/PID_Actuation.png

@@ -1,94 +1,33 @@
-# Review: tests in the `tests/` folder
+# Tests
 
-## Overview
+## What runs in CI
 
-| File | Purpose | CI |
-|------|--------|-----|
-| **PID.py** | PI controller closed-loop test: CPU target sequence, save dynamics, PNG plots | ✅ run |
-| **feedForward.py** | Open-loop test: sleep time sequence (CPU model), comparison with monitor | ✅ run |
-| **Identification.py** | Identification: for each sleep time estimates mean CPU load, scatter plot sleep vs load | ❌ not in CI |
-| **Identification2.py** | Alternative identification: sleep time sequence, dynamics plot and PNG | ❌ not in CI |
+On every push and pull request to `master`, the [CI workflow](../.github/workflows/ci.yml) runs:
 
----
+- **Python 3.13** on Ubuntu
+- After `pip install -r requirements.txt`:
+  - `python tests/PID.py`
+  - `python tests/feedForward.py`
 
-## Strengths
+If both scripts complete without errors, the build passes. They produce data files and PNGs in the current working directory (repo root when run from CI).
 
-- **Component reuse:** Monitor, Controller, ClosedLoopActuator, OpenLoopActuator used consistently.
-- **Reproducibility:** `testing = 1` runs the experiment, `testing = 0` loads data from JSON files (useful to regenerate plots without re-running).
-- **CI:** PID and feedForward are run on push/PR (Python 3.9 and 3.13).
+## Scripts
 
----
+| Script | Run in CI | Description |
+|--------|-----------|-------------|
+| **PID.py** | Yes | Closed-loop (PI) test: runs a sequence of CPU targets, records dynamics, saves `pid_data` and PNGs (e.g. `PID.png`, `PID Actuation.png`). |
+| **feedForward.py** | Yes | Open-loop test: runs a sequence of sleep times, records dynamics, saves `feed_forward_data` and `FeedForward.png`. |
+| **Identification.py** | No | Identification script: sweep sleep times, estimate CPU load, scatter plots. Run manually from project root if needed. |
+| **Identification2.py** | No | Alternative identification: sleep-time sequence and dynamics plot. Run manually from project root if needed. |
 
-## Issues and risks
-
-### 1. ~~**macOS / cross-platform compatibility**~~ (fixed)
-
-- **PID.py** and **feedForward.py** import `_available_cores` from `cpu_load_generator` (same logic as main script) → they work on macOS too.
-
-### 2. ~~**Use of `monitor.running` (bug)**~~ (fixed)
-
-- In **Identification.py** and **Identification2.py**, `monitor.running = 0` was replaced with **`monitor.stop()`** before `monitor.join()`.
-
-### 3. ~~**Duplicate `monitor.join()` in Identification.py**~~ (fixed)
-
-- Removed the redundant second `monitor.join()`; a single `monitor.stop()` + `monitor.join()`.
-
-### 4. **Path and imports**
-
-- All tests use `sys.path.insert(0, ...)` to import from the parent. This works when run from repo root; from `tests/` it may depend on cwd.
-- CI runs from repo root (`python tests/PID.py`), so it is fine. Running from `tests/` might not find `utils`.
-- Optional: use `python -m tests.PID` from root, or document “run from project root”.
-
-### 5. **Files and figures written to cwd**
-
-- Tests write `pid_data`, `feed_forward_data`, `identification_data`, `scatter_plot_data`, and PNGs (`PID.png`, `FeedForward.png`, `Identification.png`, etc.) to the **current working directory**.
-- In CI the cwd is the repo root → these files end up in the repo and could be committed by mistake (though `.gitignore` has `*.png`).
-- **Suggestion:** write to a subfolder (e.g. `tests/output/` or `tests/artifacts/`) and add it to `.gitignore`, or use `tempfile.gettempdir()`.
-
-### 6. **No assertions**
-
-- The tests do **not** use `assert` or a framework (pytest/unittest). They only check that the run does not crash and produce data/plots.
-- Useful as characterization/identification scripts; less so as automated tests (e.g. “controller reaches target within X seconds”).
-- Optional: add minimal checks (e.g. `assert len(dynamics['cpu']) > 0`, or thresholds on mean error) to make CI tests more robust.
-
-### 7. **Identification and Identification2 not in CI**
-
-- **Identification.py** and **Identification2.py** are not run by the CI workflow. If something breaks in Monitor/OpenLoopActuator, CI won’t catch it for these two.
-- **Suggestion:** include them in CI (at least as “run without crash”) or document that they are manual identification scripts.
-
-### 8. **Unused variables**
-
-- `dynamics_plot_online` is defined but not clearly used to change behaviour (in some places it is only passed to OpenLoopActuator as `plot`). It can be removed or used explicitly.
-
-### 9. **Axis labels and titles**
-
-- In several places the x-axis is labeled "Time [ms]" while the dynamics use `time.time()` (seconds). It should be "Time [s]" for consistency.
-
----
-
-## Recommended actions summary
-
-| Priority | Action |
-|----------|--------|
-| ~~High~~ | ~~Make PID.py and feedForward.py macOS-compatible~~ (done: `_available_cores` from `cpu_load_generator`). |
-| ~~High~~ | ~~Replace `monitor.running = 0` with `monitor.stop()`~~ (done in Identification and Identification2). |
-| Medium | Write data and PNGs to `tests/output/` (or similar) and add to `.gitignore`. |
-| Medium | Fix "Time [ms]" → "Time [s]" where data are in seconds. |
-| Low | Add Identification.py and Identification2.py to CI (at least as smoke). |
-| Low | Add some asserts or pytest to turn them into proper automated tests. |
-
----
-
-## How to run the tests
+## How to run (same as CI)
 
 From the **project root**:
 
 ```bash
 pip install -r requirements.txt
 python tests/PID.py
 python tests/feedForward.py
-python tests/Identification.py   # optional, may open windows
-python tests/Identification2.py
 ```
 
-The tests are aligned with the main script changes (`cpu_load_generator.py`, cross-platform cores, monitor stop).
+Run from the project root so imports (`utils`, `cpu_load_generator`) resolve correctly.