Merge pull request #1154 from mlco2/docs/boamps

BoAmps output doc and example

Author: benoit-cty

codecarbon/__init__.py

@@ -8,6 +8,12 @@
     OfflineEmissionsTracker,
     track_emissions,
 )
+from .output import OutputMethod
 
-__all__ = ["EmissionsTracker", "OfflineEmissionsTracker", "track_emissions"]
+__all__ = [
+    "EmissionsTracker",
+    "OfflineEmissionsTracker",
+    "OutputMethod",
+    "track_emissions",
+]
 __app_name__ = "codecarbon"

codecarbon/emissions_tracker.py

@@ -2,7 +2,7 @@
 Provides functionality for persistence of data
 """
 
-from codecarbon.output_methods.base_output import BaseOutput  # noqa: F401
+from codecarbon.output_methods.base_output import BaseOutput, OutputMethod  # noqa: F401
 
 # Output to BoAmps format
 from codecarbon.output_methods.boamps import BoAmpsOutput  # noqa: F401

codecarbon/output.py

@@ -1,8 +1,35 @@
+from enum import Enum
 from typing import List
 
 from codecarbon.output_methods.emissions_data import EmissionsData, TaskEmissionsData
 
 
+class OutputMethod(str, Enum):
+    """
+    Enum listing the available output methods.
+
+    Usage::
+
+        tracker = EmissionsTracker(
+            output_methods=[OutputMethod.CSV, OutputMethod.API]
+        )
+
+    Available values: ``CSV``, ``API``, ``LOGGER``, ``PROMETHEUS``,
+    ``LOGFIRE``, ``BOAMPS``.
+
+    .. note::
+        HTTP output is not configured here; it is enabled by setting the
+        ``emissions_endpoint`` parameter.
+    """
+
+    CSV = "csv"
+    API = "api"
+    LOGGER = "logger"
+    PROMETHEUS = "prometheus"
+    LOGFIRE = "logfire"
+    BOAMPS = "boamps"
+
+
 class BaseOutput:
     """
     An abstract class defining possible contracts for an output strategy, a strategy implementation can save emissions

codecarbon/output_methods/base_output.py

@@ -61,6 +61,7 @@ The directory [examples/](https://github.com/mlco2/codecarbon/tree/master/exampl
 
 | Example | Type | Description |
 |---------|------|-------------|
+| [boamps_output.py](https://github.com/mlco2/codecarbon/blob/master/examples/boamps_output.py) | Python Script | Write the output in [BoAmps](https://github.com/Boavizta/BoAmps) format. |
 | [logging_to_file.py](https://github.com/mlco2/codecarbon/blob/master/examples/logging_to_file.py) | Python Script | Save emissions data to a local CSV file |
 | [logging_to_file_exclusive_run.py](https://github.com/mlco2/codecarbon/blob/master/examples/logging_to_file_exclusive_run.py) | Python Script | Long-running process with exclusive file logging |
 | [logging_to_google_cloud.py](https://github.com/mlco2/codecarbon/blob/master/examples/logging_to_google_cloud.py) | Python Script | Send emissions data to Google Cloud Logging |

docs/how-to/examples.md

@@ -1,5 +1,29 @@
 # Output
 
+## Choosing output methods
+
+Use the `output_methods` parameter to select where emissions data is sent. It takes
+a list of `OutputMethod` enum values:
+
+```python-skip
+from codecarbon import EmissionsTracker, OutputMethod
+
+tracker = EmissionsTracker(
+    output_methods=[OutputMethod.CSV, OutputMethod.API],
+)
+```
+
+Available values: `CSV`, `API`, `LOGGER`, `PROMETHEUS`, `LOGFIRE`, `BOAMPS`.
+It can also be set in the config file as a comma-separated string, e.g.
+`output_methods=csv,api`. HTTP output is enabled separately via the
+`emissions_endpoint` parameter.
+
+!!! warning "Deprecation"
+    The individual `save_to_file`, `save_to_api`, `save_to_logger`,
+    `save_to_prometheus` and `save_to_logfire` parameters are deprecated and will be
+    removed in a future version. Use `output_methods` instead. When `output_methods`
+    is provided, the `save_to_*` flags are ignored.
+
 ## CSV
 
 The package has an in-built logger that logs data into a CSV file named `emissions.csv` in the `output_dir`, provided as an input parameter (defaults to the current directory), for each experiment tracked across projects.
@@ -102,6 +126,80 @@ tracker.stop()
 
 The first time it will ask you to log in to Logfire. Once you log in and set the default Logfire project, the metrics will appear following the format `codecarbon_*`.
 
+## BoAmps
+
+[BoAmps](https://github.com/Boavizta/BoAmps) is a standardized JSON format for reporting AI and ML energy consumption.
+
+### How to use it
+
+Run your EmissionsTracker as usual, adding `OutputMethod.BOAMPS` to `output_methods`:
+
+```python-skip
+from codecarbon import OfflineEmissionsTracker, OutputMethod
+
+tracker = OfflineEmissionsTracker(
+    project_name="my_project",
+    country_iso_code="USA",
+    output_methods=[OutputMethod.CSV, OutputMethod.BOAMPS],
+)
+tracker.start()
+# Your code here
+tracker.stop()
+```
+
+CodeCarbon writes a final report named `boamps_report_<run_id>.json` in `output_dir`.
+
+If you need to enrich the report with task metadata, datasets, or publisher information, use `BoAmpsOutput` directly through `output_handlers` or start from [examples/boamps_output.py](https://github.com/mlco2/codecarbon/blob/master/examples/boamps_output.py).
+
+Sample output:
+```json
+{
+  "header": {
+    "formatVersion": "0.1",
+    "formatVersionSpecificationUri": "https://github.com/Boavizta/BoAmps/tree/main/model",
+    "reportId": "79e4408f-ec31-476f-a2c5-8ca7f53e6cc7",
+    "reportDatetime": "2026-04-09 23:07:42"
+  },
+  "measures": [
+    {
+      "measurementMethod": "codecarbon",
+      "version": "3.2.6",
+      "averageUtilizationCpu": 0.6,
+      "powerConsumption": 6.515418096322266e-05,
+      "measurementDuration": 7.052794550996623,
+      "measurementDateTime": "2026-04-09 23:07:42"
+    }
+  ],
+  "system": {
+    "os": "Linux-6.17.0-19-generic-x86_64-with-glibc2.42"
+  },
+  "software": {
+    "language": "python",
+    "version": "3.12.12"
+  },
+  "infrastructure": {
+    "infraType": "onPremise",
+    "components": [
+      {
+        "componentName": "Intel(R) Core(TM) Ultra 7 265H",
+        "componentType": "cpu",
+        "nbComponent": 8
+      },
+      {
+        "componentType": "ram",
+        "nbComponent": 1,
+        "memorySize": 30.052967071533203
+      }
+    ]
+  },
+  "environment": {
+    "country": "France",
+    "latitude": 48.6,
+    "longitude": 2.3
+  }
+}
+```
+
 ## HTTP Output
 
 The HTTP Output allows calling a webhook with emission data when the tracker is stopped. Use the `emissions_endpoint` parameter to specify your endpoint.

docs/reference/output.md

@@ -0,0 +1,28 @@
+import multiprocessing
+
+from codecarbon import EmissionsTracker, OutputMethod
+
+
+def cpu_load_task(number):
+    a = 0
+    for i in range(5):
+        for i in range(int(1e6)):
+            a = a + i**number
+
+
+tracker = EmissionsTracker(
+    measure_power_secs=10,
+    force_mode_cpu_load=False,
+    log_level="debug",
+    output_methods=[OutputMethod.BOAMPS],
+)
+try:
+    tracker.start()
+    with multiprocessing.Pool() as pool:
+        # call the function for each item in parallel
+        pool.map(cpu_load_task, [i for i in range(100)])
+finally:
+    emissions = tracker.stop()
+
+print(f"Emissions: {emissions} kg")
+print(f"BoAmps report written to ./boamps_report_{tracker.run_id}.json")

examples/boamps_output.py

@@ -18,6 +18,7 @@
     track_emissions,
 )
 from codecarbon.external.geography import CloudMetadata
+from codecarbon.output import BoAmpsOutput, CodeCarbonAPIOutput, OutputMethod
 from tests.fake_modules import pynvml as fake_pynvml
 from tests.testdata import (
     GEO_METADATA_CANADA,
@@ -212,6 +213,121 @@ def raise_exception(*args, **kwargs):
         tracker._measure_power = raise_exception
         tracker.stop()
 
+    def test_output_methods_boamps_adds_boamps_output_handler(
+        self,
+        mock_cli_setup,
+        mock_log_values,
+        mocked_get_gpu_details,
+        mocked_env_cloud_details,
+        mocked_is_gpu_details_available,
+        mocked_is_nvidia_system,
+    ):
+        tracker = EmissionsTracker(
+            output_dir=self.temp_path,
+            output_handlers=[],
+            output_methods=[OutputMethod.BOAMPS],
+        )
+
+        self.assertTrue(
+            any(
+                isinstance(handler, BoAmpsOutput)
+                for handler in tracker._output_handlers
+            )
+        )
+
+    def test_default_output_methods_is_csv(
+        self,
+        mock_cli_setup,
+        mock_log_values,
+        mocked_get_gpu_details,
+        mocked_env_cloud_details,
+        mocked_is_gpu_details_available,
+        mocked_is_nvidia_system,
+    ):
+        tracker = EmissionsTracker(
+            output_dir=self.temp_path,
+            output_handlers=[],
+        )
+
+        self.assertEqual(tracker._output_methods, [OutputMethod.CSV])
+
+    def test_save_to_flags_map_to_output_methods_and_warn(
+        self,
+        mock_cli_setup,
+        mock_log_values,
+        mocked_get_gpu_details,
+        mocked_env_cloud_details,
+        mocked_is_gpu_details_available,
+        mocked_is_nvidia_system,
+    ):
+        with self.assertWarns(DeprecationWarning):
+            tracker = EmissionsTracker(
+                output_dir=self.temp_path,
+                output_handlers=[],
+                save_to_file=True,
+                save_to_logger=True,
+            )
+
+        self.assertIn(OutputMethod.CSV, tracker._output_methods)
+        self.assertIn(OutputMethod.LOGGER, tracker._output_methods)
+        self.assertNotIn(OutputMethod.API, tracker._output_methods)
+        self.assertTrue(tracker._save_to_file)
+        self.assertTrue(tracker._save_to_logger)
+        self.assertFalse(tracker._save_to_api)
+
+    def test_output_methods_overrides_save_to_flags(
+        self,
+        mock_cli_setup,
+        mock_log_values,
+        mocked_get_gpu_details,
+        mocked_env_cloud_details,
+        mocked_is_gpu_details_available,
+        mocked_is_nvidia_system,
+    ):
+        with self.assertWarns(DeprecationWarning):
+            tracker = EmissionsTracker(
+                output_dir=self.temp_path,
+                output_handlers=[],
+                output_methods=[OutputMethod.CSV],
+                save_to_api=True,
+            )
+
+        self.assertEqual(tracker._output_methods, [OutputMethod.CSV])
+        self.assertFalse(tracker._save_to_api)
+        self.assertFalse(
+            any(
+                isinstance(handler, CodeCarbonAPIOutput)
+                for handler in tracker._output_handlers
+            )
+        )
+
+    def test_output_methods_parsed_from_config_string(
+        self,
+        mock_cli_setup,
+        mock_log_values,
+        mocked_get_gpu_details,
+        mocked_env_cloud_details,
+        mocked_is_gpu_details_available,
+        mocked_is_nvidia_system,
+    ):
+        tracker = EmissionsTracker(
+            output_dir=self.temp_path,
+            output_handlers=[],
+            output_methods="csv,boamps",
+        )
+
+        self.assertEqual(
+            tracker._output_methods,
+            [OutputMethod.CSV, OutputMethod.BOAMPS],
+        )
+        boamps_handlers = [
+            handler
+            for handler in tracker._output_handlers
+            if isinstance(handler, BoAmpsOutput)
+        ]
+        self.assertEqual(len(boamps_handlers), 1)
+        self.assertEqual(str(boamps_handlers[0]._output_dir), str(self.temp_path))
+
     @responses.activate
     def test_decorator_ONLINE_NO_ARGS(
         self,
@@ -268,6 +384,35 @@ def dummy_train_model():
         # THEN
         self.verify_output_file(self.emissions_file_path, 2)
 
+    def test_decorator_online_passes_output_methods(
+        self,
+        mock_cli_setup,
+        mock_log_values,
+        mocked_get_gpu_details,
+        mocked_env_cloud_details,
+        mocked_is_gpu_details_available,
+        mocked_is_nvidia_system,
+    ):
+        mocked_tracker = mock.Mock()
+
+        with mock.patch(
+            "codecarbon.emissions_tracker.EmissionsTracker",
+            return_value=mocked_tracker,
+        ) as mocked_tracker_cls:
+
+            @track_emissions(output_methods=[OutputMethod.BOAMPS])
+            def dummy_train_model():
+                return 42
+
+            self.assertEqual(dummy_train_model(), 42)
+
+        self.assertEqual(
+            mocked_tracker_cls.call_args.kwargs["output_methods"],
+            [OutputMethod.BOAMPS],
+        )
+        mocked_tracker.start.assert_called_once()
+        mocked_tracker.stop.assert_called_once()
+
     def test_decorator_OFFLINE_NO_COUNTRY(
         self,
         mock_cli_setup,