calibrax.profiling.carbon

Carbon emissions tracking for benchmark workloads via CodeCarbon. Measures energy consumption and CO2 emissions during training or inference runs.

Optional Dependency

Requires codecarbon: uv pip install "calibrax[codecarbon]"

Carbon emissions tracking via CodeCarbon integration.

Wraps the codecarbon.EmissionsTracker as a context manager, exposing emissions data as a frozen CarbonResult dataclass. Requires the optional codecarbon dependency (uv pip install "calibrax[codecarbon]").

CarbonResult(*, emissions_kg_co2, energy_consumed_kwh, duration_sec, country_iso_code=None) dataclass

Result of carbon emissions measurement.

Attributes:

Name	Type	Description
emissions_kg_co2	float	Total CO2 emissions in kilograms.
energy_consumed_kwh	float	Total energy consumed in kilowatt-hours.
duration_sec	float	Duration of the tracked period in seconds.
country_iso_code	str | None	ISO code of the country used for carbon intensity.

to_dict()

Serialize to a JSON-compatible dictionary.

from_dict(data) classmethod

Deserialize from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Dictionary with carbon result fields.	required

Returns:

Type	Description
CarbonResult	Reconstructed CarbonResult instance.

CarbonTracker(country_iso_code=None, log_level='warning')

Context manager for tracking carbon emissions via CodeCarbon.

Requires the codecarbon package. Install with:

uv pip install "calibrax[codecarbon]"

Usage:

with CarbonTracker() as tracker:
    # ... run workload ...
result = tracker.result()
print(f"Emissions: {result.emissions_kg_co2:.6f} kg CO2")

Parameters:

Name	Type	Description	Default
country_iso_code	str | None	Optional ISO country code for regional carbon intensity.	None
log_level	str	Logging level for CodeCarbon (default: "warning").	'warning'

Raises:

Type	Description
ImportError	If codecarbon is not installed.

Initialize the carbon tracker.

Parameters:

Name	Type	Description	Default
country_iso_code	str | None	Optional ISO country code.	None
log_level	str	CodeCarbon logging level.	'warning'

Raises:

Type	Description
ImportError	If codecarbon is not installed.

__enter__()

Start emissions tracking.

__exit__(*args)

Stop emissions tracking and record results.

result()

Get the carbon emissions result.

Call this after exiting the context manager.

Returns:

Type	Description
CarbonResult	CarbonResult with emissions, energy, and duration data.