/**
 * Port of the AI-Carbon-Footprint-Calculator data and formulas
 * (`upstream/AI-Carbon-Footprint-Calculator/src/ai_carbon_footprint/data.py`
 * + `core.py` + `comparisons.py`, commit d8d52b5, Apache-2.0): GPU TDP table,
 * regional grid carbon intensity (kg CO2e/kWh), PUE constants, the
 * GPU-hours → energy → CO2 formula, and the equivalence comparisons.
 *
 * The plugin bridges LLM tokens onto this model through
 * {@link tokenCarbon}: IT energy = tokens × kWh/token, total energy = IT × PUE,
 * CO2 = total energy × regional intensity. `energyKwhPerToken` is configurable
 * (`config.carbon.energyKwhPerToken`); its default derivation is documented in
 * cordis.patch.yml.
 *
 * @module dsh-budget/estimate/carbon
 */
/** GPU TDP specifications, verbatim from upstream data.py. */
export interface GpuSpec {
    /** Thermal design power in watts. */
    tdp: number;
    /** Display name. */
    name: string;
    /** Upstream category tag. */
    category: string;
}
/** The upstream GPU table (17 entries), verbatim. */
export declare const GPU_SPECS: Readonly<Record<string, GpuSpec>>;
/** Regional grid carbon intensity in kg CO2e per kWh, verbatim from upstream. */
export declare const CARBON_INTENSITY: Readonly<Record<string, number>>;
/** Upstream default power usage effectiveness. */
export declare const DEFAULT_PUE = 1.58;
/** Upstream "efficient" PUE reference. */
export declare const EFFICIENT_PUE = 1.2;
/** Upstream "hyperscale" PUE reference. */
export declare const HYPERSCALE_PUE = 1.1;
/** One GPU-hours workload's carbon result. */
export interface CarbonResult {
    /** GPU display name. */
    gpuName: string;
    /** GPU table key. */
    gpuModel: string;
    /** GPU count. */
    numGpus: number;
    /** Runtime in hours. */
    hours: number;
    /** Utilization factor (0..1]. */
    utilization: number;
    /** Effective PUE. */
    pue: number;
    /** Electricity region key. */
    region: string;
    /** IT energy in kWh (before PUE). */
    energyKwh: number;
    /** Total energy in kWh (after PUE). */
    totalEnergyKwh: number;
    /** Emissions in kg CO2e. */
    co2Kg: number;
    /** Regional intensity used, kg CO2e/kWh. */
    carbonIntensity: number;
}
/**
 * Compute the carbon footprint of a GPU-hours workload.
 *
 * @param gpuModel - GPU table key.
 * @param hours - runtime in hours.
 * @param numGpus - GPU count (default 1).
 * @param pue - power usage effectiveness (default {@link DEFAULT_PUE}).
 * @param region - electricity region key (default `global`).
 * @param utilization - GPU utilization in (0, 1] (default 1).
 * @returns the calculation result.
 * @throws on an unknown GPU, an unknown region, or an out-of-range utilization.
 */
export declare function calculateCarbonFootprint(gpuModel: string, hours: number, numGpus?: number, pue?: number, region?: string, utilization?: number): CarbonResult;
/** One real-world equivalence reference (upstream `co2_kg` comparison table). */
export interface CarbonComparison {
    /** Human-readable name. */
    name: string;
    /** Emoji marker from the upstream table. */
    emoji: string;
    /** Reference emissions in kg CO2e. */
    co2Kg: number;
}
/** The upstream comparison references, verbatim from comparisons.py. */
export declare const COMPARISONS: Readonly<Record<string, CarbonComparison>>;
/** One computed equivalence: how many reference units a CO2 amount equals. */
export interface CarbonEquivalence {
    /** Reference name. */
    name: string;
    /** Reference emoji. */
    emoji: string;
    /** `co2Kg / reference`. */
    equivalent: number;
    /** Reference emissions in kg CO2e. */
    unitCo2: number;
}
/**
 * Pick the top-3 most relevant real-world equivalences for an emissions
 * amount, upstream style: only references within 0.1×–10× qualify, sorted by
 * closeness to 1×.
 *
 * @param co2Kg - emissions in kg CO2e.
 * @returns up to three equivalences, closest first.
 */
export declare function getComparisons(co2Kg: number): CarbonEquivalence[];
/** Token-bridge carbon result for one token volume. */
export interface TokenCarbonResult {
    /** IT energy in kWh (tokens × kWh/token). */
    energyKwh: number;
    /** Total energy in kWh (IT × PUE). */
    totalEnergyKwh: number;
    /** Emissions in kg CO2e. */
    co2Kg: number;
    /** Regional intensity used, kg CO2e/kWh. */
    carbonIntensity: number;
}
/**
 * Estimate the carbon footprint of a token volume (the plugin's token→carbon
 * bridge): energy = tokens × kWh/token, total = energy × PUE,
 * CO2 = total × regional intensity.
 *
 * @param tokens - total tokens processed (all buckets).
 * @param energyKwhPerToken - IT energy per token in kWh.
 * @param pue - power usage effectiveness.
 * @param region - electricity region key.
 * @returns the estimation result.
 * @throws on an unknown region.
 */
export declare function tokenCarbon(tokens: number, energyKwhPerToken: number, pue: number, region: string): TokenCarbonResult;
//# sourceMappingURL=carbon.d.ts.map