codegreen.queries

codegreen.queries.get_data(submission_type, dump=False, experiment_name=None)

Retrieve the data submitted to the server. There are currently three options: the codecarbon logs, the nextflow logs and the request log for all the requests made to the server.

Parameters:

  • submission_type (str) – One of [‘codecarbon’, ‘nextflow’, ‘requests’]

  • dump (bool, optional) – Dump all data, can only be used in combination with an admin API key, defaults to False

  • experiment_name (str, optional) – Name of the experiment to identify the configuration file by., defaults to None

Raises:

UnauthorizedException – raised when no valid API key is submitted.

Returns:

Returns the data as a Dataframe

Return type:

pd.DataFrame

codegreen.queries.get_location_prediction(estimated_runtime_hours=1, estimated_run_time_in_minutes=12, percent_renewable=40, hard_finish_time=1732575600.075279, area_code=['DE', 'FR'], log_request=True, process_id=None, experiment_name=None)

Get a preddiction for the optimal location to perform the computation within the given time frame using the specified percentage of renewable energy.

Parameters:

  • estimated_runtime_hours (int, optional) – Run time of the code in hours, defaults to 1

  • estimated_run_time_in_minutes (int, optional) – additional run time of the code in minutes, defaults to 12

  • percent_renewable (int, optional) – required percentage of renewable energy in the grid at the time of computation, defaults to 40

  • hard_finish_time (datetime.timestamp, optional) – Deadline for the termination of the code, defaults to datetime.utcnow().replace(hour=24, minute=0, second=0).timestamp() which is 24 ahead.

  • area_code (list[str], optional) – list of potential area codes for the computation, defaults to [‘DE’,’FR’]

  • log_request (bool, optional) – allow logging the request at the server side, defaults to True

  • process_id (str, optional) – process id to scope the project, defaults to None

  • experiment_name (str, optional) – Name of the experiment to load the correct configuration, defaults to None

Raises:

UnauthorizedException – Raised if no correct API key is submitted with the request.

Returns:

A response in for the request with the content in json format.

Return type:

requests.Response

codegreen.queries.get_prediction(estimated_runtime_hours=1, estimated_run_time_in_minutes=12, percent_renewable=40, hard_finish_time=1732557600.075263, area_code=['DE'], log_request=True, process_id=None, experiment_name=None)

Get a prediction for an optimal time given the specified parameters.

Parameters:

  • estimated_runtime_hours (int, optional) – Estimated run time in hours, defaults to 1

  • estimated_run_time_in_minutes (int, optional) – Estimated additional minutes of runtime, defaults to 12

  • percent_renewable (int, optional) – Required percentage of renewable energy available in the grid at the time of computation, defaults to 40

  • hard_finish_time (datetime.timestamp, optional) – deadline for when the computation needs to be finished, defaults to datetime.utcnow().replace(hour=18, minute=0, second=0).timestamp()

  • area_code (list[str], optional) – list of area codes with a two letter country code and an optional postal code separated by a dash. Postal codes can be given as 1-5 digit areas. [‘CC-PPPPP’, ‘CC’, ‘CC-P’], defaults to [‘DE’]

  • log_request (bool, optional) – allow logging the request server side, this is required to compute the carbon offset, defaults to True

  • process_id (str, optional) – An string to identify the experiment, defaults to None

  • experiment_name (str, optional) – Name of the experiment used to load the configuration. If none it will try to load a default configuration, defaults to None

Raises:

UnauthorizedException – raised when the API key is invalid

Returns:

A response object representing the the prediction in the form of a json object, Example: {‘optimal_start’: 1689703307, ‘message’: ‘No data available’, ‘avg_percentage_renewable’: 0}

Return type:

requests.Response

codegreen.queries.submit_cc_resource_usage(trace_file, process_id, task_name, postal_code='DE-791', experiment_name=None)

Upload the codecarbon report in the file specified. Process id needs to be provided. The experiment name can be used to use a specific experiment configuration. Otherwise the experiment will be reported under the default settings.

Parameters:

  • trace_file (str) – Name of the nextflow trace file to upload.

  • process_id (str) – The process id to upload the nextflow report under. Can be used for scoped reporting within an API key scope.

  • task_name (str) – The name of the task to upload the nextflow report under

  • experiment_name (str, optional) – Name of the experiment to report under, defaults to None

  • postal_code (str) – Can be used to obfuscate the exact location.

Raises:

UnauthorizedException – will be raised if the API key is invalid or does not exist.

Returns:

The response of the server.

Return type:

requests.Response

codegreen.queries.submit_nf_resource_usage(trace_file, process_id, experiment_name=None)

Upload the nextflow report in the trace file. Process id needs to be provided. The experiment name can be used to use a specific experiment configuration. Otherwise the experiment will be reported under the default settings.

Parameters:

  • trace_file (str) – Name of the nextflow trace file to upload.

  • process_id (str) – The process id to upload the nextflow report under. Can be used for scoped reporting within an API key scope.

  • experiment_name (str, optional) – Name of the experiment to report under, defaults to None

Raises:

UnauthorizedException – will be raised if the API key is invalid or does not exist.

Returns:

The response of the server.

Return type:

requests.Response