API Reference

This section contains the comprehensive API documentation for FLOPpy.

Core Tracker

class floppy.tracker.FLOPpyTracker(run_name: str | None = None)

Bases: object

Tracker for monitoring FLOPs and BOPs in machine learning and deep learning models. for models, optimizers, loss functions and tokenizers during training or inference. It supports integration with Weights & Biases for logging and can export reports.

Supported usage patterns: 1) Immediate-start mode:

tracker = FLOPpyTracker(…) tracker.run(model=model, optimizer=optimizer, loss_fn=loss_fn) … tracker.batch() tracker.epoch() print(tracker.report())

2. Context-manager mode:

   with FLOPpyTracker(…) as tracker:

   tracker.start(model=model, optimizer=optimizer, loss_fn=loss_fn) … tracker.batch() tracker.epoch() tracker.stop()

run(...)

Configure and immediately start monitoring.

start(...)

Start monitoring.

stop()

Stop monitoring and generate the report.

report()

Get the final report.

batch()

Log a batch snapshot.

epoch()

Log an epoch snapshot.

batch() → dict

Log and returns the current FLOP/BOP counters as a batch snapshot. Each call increments the internal batch counter by 1.

epoch() → dict

Log and returns the current FLOP/BOP counters as an epoch snapshot. Each call increments the internal epoch counter by 1.

report() → FLOPpyReport

Returns a report.

run(model, optimizer: Optimizer | None = None, loss_fn: Any | None = None, tokenizer: Any | None = None, export_path: str | None = None, wandb_config: WandbConfiguration | None = None) → FLOPpyTracker

Configure and immediately start monitoring.

Parameters:

• model – The model to monitor.

• optimizer (Optional[Optimizer]) – The optimizer to monitor.

• loss_fn (Optional[Any]) – The loss function to monitor.

• tokenizer (Optional[Any]) – The tokenizer to monitor.

• export_path (Optional[str]) – Local path to export the report.

• wandb_config (Optional[WandbConfiguration]) – Weights & Biases configuration containing project name and token.

Returns:

The tracker instance.

Return type:

FLOPpyTracker

start(model=None, optimizer: Optimizer | None = None, loss_fn: Any | None = None, tokenizer: Any | None = None, export_path: str | None = None, wandb_config: WandbConfiguration | None = None) → FLOPpyTracker

Start monitoring. It can be used directly inside a context manager:

with FLOPpyTracker(…) as tracker:

tracker.start(model=…, optimizer=…, loss_fn=…, tokenizer=…) … tracker.stop()

stop(print_summary=False) → FLOPpyTracker

Stop monitoring. Safe to call multiple times.

property tokenizer: TokenizerWithOps

Returns the wrapped tokenizer connected to the internal Tracker. Available only after start/run if a tokenizer was provided.

wrap_tokenizer(base_tokenizer, cost_model: str = 'chars+tokens') → TokenizerWithOps

Optional helper for manual tokenizer wrapping. Requires an active internal Tracker.

Reporting and Metrics

class floppy.utils.floppy_report.FLOPpyReport(run_name: str | None, model_architecture: str | None, model_device: str | None, loss_type: str | None, optimizer_type: str | None, backend: str, model_forward_flop: int, model_backward_flop: int, model_forward_bop: int, model_backward_bop: int, optimizer_flop: int, optimizer_bop: int, loss_forward_flop: int, loss_forward_bop: int, loss_backward_flop: int, loss_backward_bop: int, preproc_ops: int, overall_flop: int, overall_bop: int, export_path: str | None, wandb_config: WandbConfiguration | None, system: SystemInfo)

A comprehensive report containing the aggregated computational workload and hardware statistics of a monitored machine learning run.

backend: str

The specific FLOPpy backend utilized (e.g., ‘pytorch’, ‘sklearn’).

export_path: str | None

The file system path where the CSV report is saved, if applicable.

loss_backward_bop: int

The BOPs consumed during the loss gradient computation.

loss_backward_flop: int

The FLOPs consumed during the loss gradient computation.

loss_forward_bop: int

The BOPs consumed during the loss function evaluation.

loss_forward_flop: int

The FLOPs consumed during the loss function evaluation.

loss_type: str | None

The name of the loss function used during training.

model_architecture: str | None

The structural class name of the monitored model (e.g., ‘ResNet’, ‘RandomForest’)

model_backward_bop: int

The total Bit-Operations consumed by the model’s structural layers (in backward).

model_backward_flop: int

The total Floating Point Operations consumed by the model’s structural layers (in backward).

model_device: str | None

The hardware device where the model is allocated (e.g., ‘cpu’, ‘cuda’).

model_forward_bop: int

The total Bit-Operations consumed by the model’s structural layers (in forward).

model_forward_flop: int

The total Floating Point Operations consumed by the model’s structural layers (in forward).

optimizer_bop: int

The computational overhead (in BOPs) introduced by the optimizer step.

optimizer_flop: int

The computational overhead (in FLOPs) introduced by the optimizer step.

optimizer_type: str | None

The name of the optimizer used for weight updates.

overall_bop: int

The total aggregated BOPs across the entire tracked pipeline.

overall_flop: int

The total aggregated FLOPs across the entire tracked pipeline.

preproc_ops: int

The operations workload for input preparation (e.g., tokenization steps).

run_name: str | None

The custom name assigned to this tracking session.

system: SystemInfo

A snapshot of the execution environment’s specifications.

wandb_config: WandbConfiguration | None

The Weights & Biases configuration used for real-time logging.

class floppy.utils.system_info.SystemInfo(os: str, os_version: str, machine: str, processor: str, python_version: str, cpu_name: str | None, cpu_cores_logical: int | None, cpu_cores_physical: int | None, ram_total_gb: float | None, cuda_available: bool | None, gpu_name: str | None, gpu_count: int | None, torch_version: str | None, sklearn_version: str | None)

A snapshot of the hardware and software environment where the model is executed.

cpu_cores_logical: int | None

The number of logical CPU cores (including hyperthreading).

cpu_cores_physical: int | None

The number of physical CPU cores.

cpu_name: str | None

The specific model name of the CPU (e.g., ‘Intel Core i9’).

cuda_available: bool | None

Indicates whether a CUDA-enabled GPU is accessible to PyTorch.

gpu_count: int | None

The total number of GPUs available on the system.

gpu_name: str | None

The model name of the primary GPU detected (e.g., ‘NVIDIA RTX 4090’).

machine: str

The hardware architecture of the machine (e.g., ‘x86_64’, ‘AMD64’).

os: str

The name of the operating system (e.g., ‘Linux’, ‘Windows’).

os_version: str

The specific release version of the operating system.

processor: str

The processor family or detailed name provided by the system.

python_version: str

The version of Python currently running the tracker.

ram_total_gb: float | None

The total amount of system RAM available, expressed in Gigabytes.

sklearn_version: str | None

The installed version of the Scikit-learn library.

torch_version: str | None

The installed version of the PyTorch library.

Configuration

class floppy.utils.wandb_configuration.WandbConfiguration(project_name: str, group_name: str, reporter_key: str)

Configuration settings for Weights & Biases (WandB) integration. Used to synchronize real-time tracking of computational workloads.

group_name: str

The group name to organize multiple runs together in the W&B dashboard.

project_name: str

The name of the WandB project where the runs will be logged.

reporter_key: str

The API key used for authenticating with the WandB server.