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.__init__
- class cats.__init__.CATSOutput(carbonIntensityNow: CarbonIntensityAverageEstimate, carbonIntensityOptimal: CarbonIntensityAverageEstimate, location: str, countryISO3: str, emmissionEstimate: Estimates | None = None)
Carbon Aware Task Scheduler output
- cats.__init__.parse_arguments()
Parse command line arguments :return: [dict] parsed arguments
- cats.__init__.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.__main__
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[APIInterface, str, int, list[tuple[int, float]] | None, float | None]
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[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
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