ThrottlePoint

Energy Optimization Governor for HPC systems.

ThrottlePoint caps CPU frequency (and NVIDIA GPU power) based on grid carbon intensity, electricity price, or temperature. The shipped configuration throttles the CPU only while the Wattnet CO₂ intensity is above a threshold (430 gCO₂/kWh by default). Which signals drive the decision is configurable, and you can plug in your own steps.

It runs from cron as root, with no daemon and no batch-system integration. Each run reads its signal (Wattnet CO₂ against the threshold by default, or a price/CO₂ rating or a temperature band) and sets the CPU's maximum scaling frequency accordingly. Running jobs are never signalled, paused, or killed; they run under a lower clock ceiling while conditions are bad.

---

Documentation

docs/install.md	Start here. Prerequisites, building the RPM or DEB.
docs/deployment.md	Configure, first run, verify, tune: one node, either mode.
docs/cluster-rollout.md	Many nodes, upgrades, uninstall.
docs/configuration.md	Every key of /etc/hpc_eff/config.ini.
docs/regulation-modes.md	What each mode does with its input: the rating maths, the thermal bands.
docs/plugins.md	The score/action pipeline: built-in plugins, writing your own, the JSON contract.
docs/monitoring.md	Database schema, state.json, useful queries.
docs/troubleshooting.md	Symptom-first fault finding.

---

Use cases

• Driver: carbon intensity of electricity
  • Primary GreenDIGIT scenario
  • Lowering carbon impact
• Driver: electricity cost or consumption profile
  • Lowering operational costs
• Driver: datacenter temperature
  • Optimize datacenter usage
  • Continuity of services
• Driver: power-grid or local heating signals
  • Lowering operational costs, carbon impact

---

Quick start

git clone git@github.com:CESNET/hpc_eff.git
cd hpc_eff

RHEL / AlmaLinux / Rocky

sudo dnf install -y ipmitool make kernel-tools rpm-build rpmdevtools
make                                   # build + install the RPM

Debian / Ubuntu

sudo apt install -y build-essential devscripts debhelper dh-python \
                    python3-all python3-setuptools fakeroot
sudo apt install -y ipmitool cpufrequtils python3-numpy python3-requests
make deb
sudo dpkg -i ../hpc-eff_*.deb          # does not enable cron; see below

Then configure and start:

sudo vi /etc/hpc_eff/config.ini        # set WATTNET_EMAIL and WATTNET_PASSWORD
sudo hpc-eff                           # one real run: applies a cap immediately
sudo hpc-eff --enable                  # install /etc/cron.d/hpc-eff (every 10 min)

With the shipped config, the only required edit is the Wattnet login in [CO2_API]; check [frequency_tables] for your CPU. The temperature mode needs [TEMPERATURE_SOURCE] and [CPU_THERMO] instead and calls no external API.

Full prerequisites and build detail: docs/install.md. Configuration and verification: docs/deployment.md. Fleet rollout and uninstall: docs/cluster-rollout.md.

---

Regulation modes

The shipped config uses a [PIPELINE] section: CO₂ from Wattnet against [CO2_API] THRESHOLD. Without [PIPELINE], [MODE] control_mode selects a preset and is then required.

Setup	CPU	GPU	Inputs
CO₂ threshold (shipped)	full speed, or the lowest table frequency above the threshold	untouched	Wattnet carbon intensity
control_mode=co2	rating 1–10 → max-frequency cap	untouched	spot price + grid carbon intensity
control_mode=temperature	hysteresis thermal bands	NVIDIA power limiting	one temperature sensor

CPU regulation is mutually exclusive: a node is driven either by carbon/price or by temperature, never both. Details: docs/regulation-modes.md.

Plugins

Every evaluation is a pipeline of plugins: read → score → act → record. Without extra config it behaves exactly as above. To change it, add a [PIPELINE] section, for example CO₂ alone (no price) driving the CPU cap:

[PIPELINE]
score = co2
act   = cpu_freq

Your own score or action is any executable that reads JSON on stdin and prints JSON on stdout. Contract, built-in plugins, security rules and starter files: docs/plugins.md.

---

Data sources

Signal	Source	Notes
Electricity price	spotovaelektrina.cz (Czech OTE spot market)	Current price via API; the 12-month baseline is scraped from HTML
Carbon intensity	Wattnet	Needs a login (email + password, register at api.wattnet.eu/token-request)
Temperature	IPMI sensor, HTTP API, or your own Python module	"Bring your own reader": see docs/configuration.md

---

Logging

Every run writes one row to /var/lib/hpc_eff/history.db (SQLite) and rewrites /var/lib/hpc_eff/state.json with the current evaluation plus a rolling history. Schema and queries: docs/monitoring.md.

---

License

BSD-3-Clause. See LICENSE.