.. _parameters: Parameters ================ A set of parameters are supported by API to help users provide additional details per project. Input Parameters ----------------- .. list-table:: Input Parameters :widths: 20 80 :align: center :header-rows: 1 * - Parameter - Description * - project_name - Name of the project, defaults to ``codecarbon`` * - experiment_id - Id of the experiment * - measure_power_secs - Interval (in seconds) to measure hardware power usage, defaults to ``15`` * - tracking_mode - | ``machine`` measure the power consumptions of the entire machine (default) | ``process`` try and isolate the tracked processes in isolation * - gpu_ids - | Comma-separated list of GPU ids to track, defaults to ``None`` | These can either be integer indexes of GPUs on the system, or prefixes | to match against GPU identifiers as described `here `_ * - log_level - | Global codecarbon log level (by order of verbosity): "debug", "info" (default), | "warning", "error", or "critical" * - electricitymaps_api_token - | API token for electricitymaps.com (formerly co2signal.com) * - pue - | PUE (Power Usage Effectiveness) of the data center | where the experiment is being run. * - wue - | WUE (Water Usage Effectiveness) of the data center | where the experiment is being run. | Units of *L/kWh* - how many litres of water are consumed per kilowatt-hour | of electricity consumed. * - force_cpu_power - | Force the CPU max power consumption in watts, | use this if you know the TDP of your machine. | *(POWER_CONSTANT x CONSUMPTION_PERCENTAGE)* * - force_ram_power - | Force the RAM power consumption in watts, | use this if you know the power consumption of your RAM. | Estimate it with ``sudo lshw -C memory -short | grep DIMM`` | to get the number of RAM slots used, then do | *RAM power in W = Number of RAM Slots * 5 Watts* * - rapl_include_dram - | Boolean variable indicating if DRAM (memory) power should be included | in RAPL measurements on Linux systems, defaults to ``False``. | When ``True``, measures complete hardware power (CPU package + DRAM). | Set to ``False`` to measure only CPU package power. | Note: Only affects systems where RAPL exposes separate DRAM domains. | In a future version DRAM power will probably be included in RAM. * - rapl_prefer_psys - | Boolean variable indicating if psys (platform/system) RAPL domain should be | preferred over package domains on Linux systems, defaults to ``False``. | When ``True``, uses psys domain for total platform power (CPU + chipset + PCIe). | When ``False`` (default), uses package domains which are more reliable and | consistent with CPU TDP specifications. | Note: psys can report higher values than CPU TDP and may be unreliable on older systems. * - allow_multiple_runs - | Boolean variable indicating if multiple instance of CodeCarbon | on the same machine is allowed, | defaults to ``True`` since v3. Used to be ``False`` in v2. PUE is a multiplication factor provided by the user, so it is up to the user to get it from their cloud provider. Old data-centers have a PUE up to 2.2, where new greener ones could be as low as 1.1. If you, or your provider, use ``CUDA_VISIBLE_DEVICES`` to set the GPUs you want to use, CodeCarbon will automaticly populate this value into ``gpu_ids``. If you set ``gpu_ids`` manually, it will override the ``CUDA_VISIBLE_DEVICES`` for CodeCarbon measures. Output parameters ----------------- .. list-table:: Output Parameters :widths: 20 80 :align: center :header-rows: 1 * - Parameter - Description * - **save_to_file** - | Boolean variable indicating if the emission artifacts should be logged | to a CSV file, defaults to ``True`` * - output_dir - | Directory path to which the experiment details are logged | defaults to current directory * - output_file - | Name of output CSV file | defaults to ``emissions.csv`` * - on_csv_write - | When calling ``tracker.flush()`` manually choose if | - ``update`` the existing ``run_id`` row (erasing former data) | - ``append`` add a new row to CSV file (defaults) * - **save_to_api** - | Boolean variable indicating if emissions artifacts should be logged | to the CodeCarbon API, defaults to ``False`` * - api_endpoint: - | Optional URL of CodeCarbon API endpoint for sending emissions data | defaults to "https://api.codecarbon.io" * - api_key - API key for the CodeCarbon API (mandatory to use this API!) * - api_call_interval - | Number of measurements between API calls (defaults to 8): | -1 : call API on flush() and at the end | 1 : at every measure | 2 : at every 2 measure, and so on * - **save_to_logger** - | Boolean variable indicating if the emission artifacts should be written | to a dedicated logger, defaults to ``False`` * - logging_logger - LoggerOutput object encapsulating a logging.Logger or a Google Cloud logger * - logger_preamble - String to systematically include in the logger's messages (defaults to "") * - save_to_prometheus - | Boolean variable indicating if the emission artifacts should be written | to a Prometheus server, defaults to ``False`` * - prometheus_url - | URL of the Prometheus server * - save_to_logfire - | Boolean variable indicating if the emission artifacts should be written | to a LogFire server, defaults to ``False`` * - output_handlers - | List of output handlers to use for saving the emissions data | defaults to ``[]`` Specific parameters for offline mode ------------------------------------ .. list-table:: Input Parameters to OfflineEmissionsTracker :widths: 20 80 :align: center :header-rows: 1 * - Parameter - Description * - country_iso_code - | 3-letter ISO Code of the country | where the experiment is being run. | Available countries are listed in `global_energy_mix.json `__ * - region - | Optional name of the Province/State/City, where the infrastructure is hosted | Currently, supported only for US States and Canada | for example - California or New York, from the `list `_ * - cloud_provider - | The cloud provider specified for estimating emissions intensity, | defaults to ``None``. See `impact.csv `_ for a list of cloud providers * - cloud_region - | The region of the cloud data center, defaults to ``None`` | See `impact.csv `_ for a list of cloud regions. * - country_2letter_iso_code - | For use with the Electricity Maps emissions API. | See `Electricity Maps zones `_ for a list of codes and their locations. @track_emissions ---------------- Decorator ``track_emissions`` in addition to standard arguments, requires the following parameters: .. list-table:: Input Parameters to @track_emissions :widths: 20 80 :align: center :header-rows: 1 * - Parameter - Description * - fn - function to be decorated * - offline - | Boolean variable indicating if the tracker should be run in offline mode | defaults to ``False`` * - country_iso_code - | 3 letter ISO Code of the country where the experiment is being run. | Available countries are listed in `global_energy_mix.json `__ * - region - | Optional Name of the Province/State/City, where the infrastructure is hosted | Currently, supported only for US States | for example - California or New York, from the `list `_ * - cloud_provider - | The cloud provider specified for estimating emissions intensity, | defaults to ``None``. See `impact.csv `_ for a list of cloud providers * - cloud_region - | The region of the cloud data center, defaults to ``None`` | See `impact.csv `_ for a list of cloud regions.