Command-line (CLI) reference

The Climate-Aware Task Scheduler (cats) command line program helps you run your calculations in a way that minimises their impact on the climate by delaying computation until a time when the ammount of CO2 produced to generate the power you will use is predicted to be minimised.

By default, the command simply returns information about when the calculation should be undertaken and compares the carbon intensity (gCO2/kWh) of running the calculation now with the carbon intensity at that time in the future. To undertake this calculation, cats needs to know the predicted duration of the calculation (which you must supply, see -d) and your location, either inferred from your IP address, or passed using -l. If additional information about the power consumption of your computer is available and passed to CATS via the –config option, the predicted CO2 usage will be reported.

To make use of this information, you will need to couple cats with a task scheduler of some kind. The command to schedule is specified with the -c or –command parameter, and the scheduler can be selected using the –scheduler option.

Example:

cats -d 1 –loc RG1 –scheduler=at –command=’ls’

usage: cats [-h] -d DURATION [-s {at}] [-a API] [-c COMMAND]
            [--dateformat DATEFORMAT] [-l LOCATION] [--config CONFIG]
            [--profile PROFILE] [--format {json}] [-f] [--cpu CPU] [--gpu GPU]
            [--memory MEMORY]

Named Arguments

-d, --duration

[required] Expected duration of the job in minutes.

-s, --scheduler

Possible choices: at

Pass command using -c to scheduler. Currently, the only supported scheduler is at

-a, --api

API to use to obtain carbon intensity forecasts. Overrides config.yml. For now, only choice is carbonintensity.org.uk (hence UK only forecasts). Default: carbonintensity.org.uk.

-c, --command

Command to schedule, requires –scheduler to be set

--dateformat

Output date format in strftime(3) format or one of the supported schedulers (‘at’).

-l, --location

Location of the computing facility. For the UK, first half of a postcode (e.g. M15), for other APIs, see documentation for exact format. Overrides config.yml. Default: if absent, location based in IP address is used.

--config

Path to a configuration file. The file is required to obtain carbon footprint estimates. Default: config.yml in current directory.Template found at https://github.com/GreenScheduler/cats/blob/main/config.yml.

--profile

Hardware profile, specified in configuration file

--format

Possible choices: json

Format to output optimal start time and carbon emmissionestimate savings in. Currently only JSON is supported.

-f, --footprint

Default: False

--cpu

Number of cpus used by the job

--gpu

Number of cpus used by the job

--memory

Amount of memory used by the job, in GB

CATS can be used to report information on the best time to run a calculation and the amount of CO2. Information about a 90 minute calculation in centeral Oxford can be found by running:

cats -d 90 –loc OX1

The at scheduler is available from the command line on most Linux and MacOS computers, and can be the easest way to use cats to minimise the carbon intensity of calculations on smaller computers. For example, the above calculation can be scheduled by running:

cats -d 90 –loc OX1 -s at -c ‘mycommand’

To report carbon footprint, pass the –config option to select a configuration file and the –profile option to select a profile. An example config file is given below:

profiles:

my_cpu_only_profile:

cpu:

model: “Xeon Gold 6142” power: 9.4 # in W, per core nunits: 2

my_gpu_profile:

gpu:

model: “NVIDIA A100-SXM-80GB GPUs” power: 300 nunits: 2

cpu:

model: “AMD EPYC 7763” power: 4.4 nunits: 1

The configuration file is documented in the Quickstart section of the online documentation.