Metadata-Version: 2.4
Name: ecofx
Version: 0.2.0
Summary: Estimate the energy use and carbon emissions of Python programs
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: X11 Applications
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: psutil>=5.9
Requires-Dist: rich>=13.0

# EcoFX

EcoFX estimates the energy use and associated carbon emissions of Python
programs. Track a script or function, inspect and compare runs, export history,
or browse it in a desktop dashboard.

> **Estimates, not meter readings:** EcoFX estimates CPU-related power from
> configurable assumptions. By default it assumes 5 W idle power, a 45 W CPU
> contribution at full load, and 436 gCO2e/kWh. Process CPU is the default
> measurement mode. These are rough estimates and are not suitable for audited
> carbon accounting or precise comparisons across different hardware.

## Feature list

- Track Python scripts and modules from the command line; forward arguments to
  the target program.
- Track functions with a decorator or code block with a context manager.
- Configure sampling interval, project name, tags, idle and CPU power, carbon
  intensity, CPU measurement mode, database, and summary output.
- Choose process CPU (default) or system-wide CPU sampling.
- Get estimated energy in joules and kWh, carbon emissions, average/peak CPU
  use, sample count, and smartphone-charge equivalent in summaries.
- Produce readable terminal output or JSON; suppress summaries for quiet runs.
- Persist runs locally in SQLite with timestamps, tags, CPU estimates, carbon
  assumptions, Python version, and machine name.
- Browse searchable run history in a Tkinter desktop dashboard; auto-refresh,
  sort columns, export displayed rows to CSV, and clear history.
- Filter command-line history by project or date range and limit/order results.
- Export all or filtered runs to CSV or JSON.
- Compare project totals and average duration; view overall or per-project
  aggregate statistics.
- Delete individual records or clear all history (or history before a date),
  with confirmation safeguards.
- Estimate energy/carbon from a supplied wattage and duration without running
  a workload.
- Choose a custom SQLite database path or `ECOFX_DB` environment variable.
- Migrate an existing `.ecotrace/history.db` into `.ecofx/history.db` without
  modifying the old file.
- Diagnose the installation with `ecofx doctor` and inspect active defaults
  with `ecofx config`.

## Installation

Once published to PyPI:

```console
python -m pip install ecofx
```

Requires Python 3.9 or newer. EcoFX depends on psutil and Rich. The optional GUI
uses Tkinter from the Python standard library; some operating-system packages
provide Tkinter separately.

## Track a script

```console
ecofx path/to/script.py
```

EcoFX accepts the explicit `track` subcommand too:

```console
ecofx track --project image-training --poll-interval 0.25 path/to/train.py -- --epochs 5
```

Arguments after `--` are forwarded to the target script. EcoFX options go
before the script path. The short form also accepts script arguments:

```console
ecofx path/to/train.py --epochs 5 --dataset samples.csv
```

The target executes in the current Python process using `runpy`. Its summary
and run-history record are produced when it exits, including when it raises an
exception. The exception is not swallowed.

Run an importable Python module instead of a file:

```console
ecofx track --module --project nightly-job my_package.worker -- --date 2026-10-04
```

Equivalent module invocation:

```console
python -m ecofx path/to/script.py
```

## Tracking options

Use `ecofx track --help` for the complete live help. Common options:

| Option | Description | Default |
| --- | --- | --- |
| `--project NAME` | Friendly name stored with the run | Script or module name |
| `--poll-interval SECONDS` | CPU sampling interval; must be positive | `0.2` |
| `--idle-watts WATTS` | Assumed idle power | `5` |
| `--max-cpu-watts WATTS` | CPU power added at 100% whole-machine load | `45` |
| `--carbon-intensity G_PER_KWH` | Carbon intensity used for the estimate | `436` |
| `--cpu-mode process\|system` | Sample this process or the whole system | `process` |
| `--tag TAG` | Attach a searchable tag; repeat as needed | None |
| `--db PATH` | SQLite database file | `.ecofx/history.db` |
| `--output text\|json\|none` | Summary output format | `text` |
| `--no-save` | Do not write this run to history | Save |
| `--module` | Interpret target as an importable module | Script |

Examples:

```console
ecofx track --project api-benchmark --tag staging --tag release --cpu-mode system --poll-interval 0.1 --output json benchmark.py
ecofx track --no-save --output none scratch.py
ecofx track --db C:\data\experiments.sqlite --idle-watts 8 --max-cpu-watts 65 --carbon-intensity 210 job.py
```

EcoFX process mode samples the current Python process and normalizes its CPU
use against the machine's logical CPU count. System mode measures system-wide
CPU load, which can include unrelated applications. Both modes use an idle
power baseline, so results are approximate and short runs have proportionally
higher uncertainty.

## Track Python functions

Decorator:

```python
from ecofx import track_emissions


@track_emissions(
    project_name="data-cleaning",
    poll_interval=0.1,
    carbon_intensity_g_per_kwh=210,
    tags=["batch", "nightly"],
)
def clean_data():
    # Your workload goes here.
    ...


clean_data()
```

Context manager:

```python
from ecofx import EcoFXTracker

with EcoFXTracker(
    project_name="model-training",
    poll_interval=0.2,
    cpu_mode="process",
    tags=("experiment-7",),
):
    train_model()
```

`EcoTracker` remains available as an alias for `EcoFXTracker`.

## Run-history commands

Show newest runs, filter by project, and choose ordering or a limit:

```console
ecofx history
ecofx history --project training --since 2026-01-01 --until 2026-01-31 --limit 20
ecofx history --order oldest --db C:\data\experiments.sqlite
```

Date filters accept `YYYY-MM-DD` or ISO 8601 date/time values. A date-only
`--until` includes that whole day.

Export history:

```console
ecofx export --format csv --output runs.csv
ecofx export --format json --project training -o training.json
ecofx export --format csv > runs.csv
```

The default output path `-` writes to standard output. Export supports the
same `--project`, `--since`, `--until`, and `--db` filters.

Aggregate and compare:

```console
ecofx stats
ecofx stats --by-project
ecofx compare baseline optimized
```

`compare` accepts exact project names saved in run history. Its percentage
change is calculated from total estimated energy for the two projects.

Manage saved runs:

```console
ecofx delete 14
ecofx delete 14 --yes
ecofx clear --before 2026-01-01 --yes
ecofx clear --yes
```

Deletion prompts before changing history unless `--yes` is provided.

## One-off estimate

Calculate energy and carbon from a known average wattage and runtime:

```console
ecofx estimate --watts 60 --duration 1200
ecofx estimate --watts 60 --duration 1200 --carbon-intensity 210 --output json
```

This command does not run code or save a history entry.

## Desktop dashboard

```console
ecofx dashboard
ecofx-gui
ecofx dashboard --db C:\data\experiments.sqlite --refresh-seconds 10
```

The dashboard filters projects/tags as you type, refreshes on a timer, sorts
columns when their headings are clicked, shows run-level CPU and energy
estimates, exports the displayed records as CSV, and can clear the history
after confirmation. It opens history for the current working directory unless
you supply `--db`.

## Configuration and troubleshooting

```console
ecofx --help
ecofx track --help
ecofx config
ecofx doctor
ecofx --version
```

Set `ECOFX_DB` to use a default database file without repeating `--db`:

```console
set ECOFX_DB=C:\data\experiments.sqlite
ecofx history
```

On PowerShell, set it for the current shell with:

```powershell
$env:ECOFX_DB = 'C:\data\experiments.sqlite'
```

## Estimation and data notes

The simplified estimate is:

```text
estimated watts = idle watts + (CPU utilization / 100 × max CPU watts)
energy (kWh) = accumulated joules / 3,600,000
carbon (gCO2e) = energy (kWh) × carbon intensity (gCO2e/kWh)
```

The default `.ecofx/history.db` is local to the current working directory. No
account or network service is required. A detected legacy
`.ecotrace/history.db` is copied on first initialization; EcoFX leaves the
legacy file intact.

## License

No license has been declared for this project yet.
