ecal.api

Public API for eCAL energy estimation.

Functions

estimate(model_type[, model_params, ...])

Estimate the total energy cost of an AI model lifecycle.
ecal.api.estimate(model_type, model_params=None, num_samples=1000, sample_size=10, num_epochs=50, batch_size=64, num_inferences=10000, float_precision=64, hardware=None, processor_flops_per_second=None, processor_max_power=None, preprocessing_type='normalization', evaluation_strategy='cross_validation', k_folds=5, split_ratio=0.8, transmission_hops=None, virtualization_overhead=0.0)[source]

Estimate the total energy cost of an AI model lifecycle.

Parameters:

  • model_type (str) – Model architecture (“MLP”, “CNN”, “KAN”, “Transformer”)

  • model_params (Dict[str, Any] | None) – Architecture-specific parameters. Keys depend on model_type: MLP needs num_layers, din, dout; CNN needs num_cnv_layers, num_pool_layers, i_r, i_c, k_r, k_c, c_in; KAN needs num_layers, grid_size, din, dout; Transformer needs context_length, embedding_size, num_heads, num_decoder_blocks, feed_forward_size, vocab_size.

  • num_samples (int) – Number of training samples

  • sample_size (int) – Size of each sample (e.g., number of features)

  • num_epochs (int) – Number of training epochs

  • batch_size (int) – Training batch size

  • num_inferences (int) – Number of inference runs

  • float_precision (int) – Bits per float (default 64)

  • hardware (str | None) – Hardware profile name (e.g., “generic_cpu”, “apple_m2”)

  • processor_flops_per_second (float | None) – Override FLOPS (used if hardware is None)

  • processor_max_power (float | None) – Override power in watts (used if hardware is None)

  • preprocessing_type (str) – “normalization”, “min_max_scaling”, or “GADF”

  • evaluation_strategy (str) – “cross_validation” or “train_test_split”

  • k_folds (int) – Number of folds for cross-validation

  • split_ratio (float) – Train/test split ratio

  • transmission_hops (list | None) – List of dicts with protocol/failure_rate config per hop. Each dict may contain keys: application, presentation, session, transport, network, datalink, physical, failure_rate. Defaults to a single hop with generic protocols and 0% failure.

  • virtualization_overhead (float) – Energy overhead fraction [0, 1]

Returns:

Dictionary with energy breakdown (Joules) and eCAL metric (J/bit). Keys: “transmission”, “preprocessing”, “training”, “evaluation”, “inference”, “inference_process”, “total” (all in Joules), “ecal_j_per_bit” (J/bit), and bit counts “Ed bits”, “inf_proc_bits”, “total_bits”.

Return type:

Dict[str, Any]