Ecoclient Simvue Python API Extension

[kzscisoft]

Ecoclient

Issue: #751

Python Version(s) Tested: 3.13

Operating System(s): Ubuntu 24.10

Documentation PR: https://github.com/simvue-io/docs/pull/61

📝 Summary

Replaces CodeCarbon as the source of emission metrics giving measures for CO2 emissions and energy consumption.

🔄 Changes

• Removed CodeCarbon based EmissionsTracker from simvue.Run.
• Created eco submodule containing:
  • APIClient: Class for connecting to CO2 Signal API.
  • CO2Monitor: Class for calculating values based on CPU usage and current CO2 intensity.
• Integrated CO2Monitor into simvue.Run and attached metric gathering to heartbeat (similar to resource metrics).

✔️ Checklist

• Unit and integration tests passing.
• Pre-commit hooks passing.
• Quality checks passing.
• Updated the documentation.

[wk9874]

Initial comments:

• Unit test is failing, please correct
• I think you should raise a docs MR which contains updated information on how EcoClient works, a warning that it is an early version and the values aren't asbolute, etc

[AbyAbraham21]

Calculations look right. Some comments to address regarding offline mode.

[wk9874]

I think it should probably not require this, and should do the same as CC where Simvue comes with some default file which it can read from (that we make sure to update each PyPI release). That way the user just needs to provide a ISO code, not a value.

We could also make it so that the sender makes a call to the carbon intensity data every (eg) hour, and records it in the same file which online mode produces.

[kzscisoft]

I would argue in doing this we are then held accountable for this value.

[wk9874]

Why?

[kzscisoft]

Actually this is a remnant of CC when this was not possible due to CC starting a server of sorts.

[kzscisoft]

Cannot disable because once the loop is running you cannot modify it

[wk9874]

Final general comment - I strongly think that we should be adding in contributions from GPUs into this initial version of this if not too much work. Other stuff like RAM etc doesnt matter so much as it'd be roughly constant between runs, but if you did a run on a GPU cluster and a run on a CPU cluster, our emissions metrics comparison between the two would basically just be lies :/

[wk9874]

Would suggest making emissions and resource metrics interval the same, and then doing something like:

In run.py, in _heartbeat:

                with self._configuration_lock:
                    if (
                        self._resources_metrics_interval
                        and (res_time := time.time()) - last_res_metric_call
                        > self._resources_metrics_interval
                    ):
                        # Set join on fail to false as if an error is thrown
                        # join would be called on this thread and a thread cannot
                        # join itself!
                        _sysinfo = self._get_sysinfo()
                        self._add_metrics_to_dispatch(
                            _sysinfo, join_on_fail=False, step=res_step
                        )
                        if emissions:
                            <calculate emissions based on _sysinfo["cpu"]>
                        last_res_metric_call = res_time
                        res_step += 1

[wk9874]

I would call this 'system_metrics_interval' as it now applies to both resources and emissions metrics

[wk9874]

change to 130