API Reference

This is a reference covering the Python modules and objects across the CATS codebase. For the interface for the command-line, which is likely to be more relevant to users (rather than developers) of CATS, please see Command-line (CLI) reference.

Modules

cats

class cats.CATSOutput(carbonIntensityNow: CarbonIntensityAverageEstimate, carbonIntensityOptimal: CarbonIntensityAverageEstimate, location: str, countryISO3: str, emmissionEstimate: Estimates | None = None)

Carbon Aware Task Scheduler output

cats.parse_arguments()

Parse command line arguments :return: [dict] parsed arguments

cats.schedule_at(output: CATSOutput, args: list[str], at_command: str = 'at') str | None

Schedule job with optimal start time using at(1)

Returns:

Error as a string, or None if successful

cats.configure

This module exports a function configure that processes both command line arguments and configuration file. This function returns a runtime configuration for cats to make a request to a carcon intensity forecast provider. A runtime configuration consits of:

  • location (postcode)

  • job duration

  • Interface to carbon intensity forecast provider (See TODO)

cats.configure.get_runtime_config(args) tuple[cats.CI_api_interface.APIInterface, str, int, Optional[list[tuple[int, float]]], Optional[float]]

Return the runtime cats configuration from list of command line arguments and content of configuration file.

Returns a tuple containing an instance of APIInterface, the location as a string, the duration in minutes as an integer, as well as information on the number of cpus/gpus used by the job and their power consumption.

Parameters:

args – Command line arguments

Returns:

Runtime cats configuration

Return type:

tuple[APIInterface, str, int, list[tuple[int, float]]]

Raises:

ValueError – If job duration cannot be interpreted as a positive integer.

cats.CI_api_interface

class cats.CI_api_interface.APIInterface(get_request_url, parse_response_data, max_duration)
get_request_url

Alias for field number 0

max_duration

Alias for field number 2

parse_response_data

Alias for field number 1

exception cats.CI_api_interface.InvalidLocationError
cats.CI_api_interface.ciuk_parse_response_data(response: dict)

This wraps the API from carbonintensity.org.uk and is set up to cache data from call to call even accross different processes within the same half hour window. The returned prediction data is in half hour blocks starting from the half hour containing the current time and extending for 48 hours into the future.

Parameters:

response

Returns:

cats.CI_api_query

cats.CI_api_query.get_CI_forecast(location: str, CI_API_interface) list[cats.forecast.CarbonIntensityPointEstimate]

Get carbon intensity from an API

Given the location and an API interface, return a list of predictions of the future carbon intensity.

param location: [str] Depends on country. UK postcode (just the first section), e.g. M15. returns: a list of CarbonIntensityPointEstimate

cats.carbonFootprint

class cats.carbonFootprint.Estimates(now, best, savings)
best

Alias for field number 1

now

Alias for field number 0

savings

Alias for field number 2

cats.forecast

class cats.forecast.CarbonIntensityAverageEstimate(value: float, start: datetime, end: datetime)

Represents a single data point within an integrated carbon intensity timeseries. Use order=True in order to enable comparison of class instance based on the first attribute. See https://peps.python.org/pep-0557

class cats.forecast.CarbonIntensityPointEstimate(value: float, datetime: datetime)

Represents a single data point within an intensity timeseries. Use order=True in order to enable comparison of class instance based on the first attribute. See https://peps.python.org/pep-0557

cats.optimise_starttime

cats.optimise_starttime.get_avg_estimates(data, duration=None)

Get lowest carbon intensity in data depending on user method return dict of timestamp and carbon intensity

duration is in minutes