fluxopt

Energy system optimization with linopy — detailed dispatch, scaled to multi period planning.

Early development — the API may change between releases. Planned features and progress are tracked in Issues.

Installation

pip install fluxopt

Includes the HiGHS solver out of the box.

Quick Start

from datetime import datetime, timedelta

import fluxopt as fx

timesteps = [datetime(2024, 1, 1) + timedelta(hours=i) for i in range(4)]

result = fx.optimize(
    timesteps=timesteps,
    carriers=[fx.Carrier('electricity')],
    effects=[fx.Effect('cost', is_objective=True)],
    ports=[
        fx.Port('grid', imports=[
            fx.Flow('electricity', size=200, effects_per_flow_hour={'cost': 0.04}),
        ]),
        fx.Port('demand', exports=[
            fx.Flow('electricity', size=100, fixed_relative_profile=[0.5, 0.8, 1.0, 0.6]),
        ]),
    ],
)

Roadmap

fluxopt is evolving into a family of packages with a lean core and optional companions:

                  ┌──────────────┐
                  │   fluxopt    │  core: model building, solving, results, IO
                  └──────┬───────┘
          ┌───────────┬──┴──────────┬────────────────┐
          │           │             │                 │
   fluxopt-plot  fluxopt-yaml  fluxopt-tsam     (examples)
    plotting      YAML+CSV      time series     cross-package
   (plotly)       loader       aggregation       notebooks

Companion packages depend on core — core has no knowledge of companions.

Milestones

Milestone	Description	Status	Issue
Result.stats accessor	Cached xarray properties for post-processing	Planned	#49
.plot stub on Result	Discoverable property, helpful error if plot package absent	Planned	#50
fluxopt-plot package	Interactive plotly visualization as companion package	Scaffolded	#51
fluxopt-yaml package	Declarative model definition via YAML + CSV	Scaffolded	#52
fluxopt-tsam package	Time series aggregation preprocessing	Planned	—
ReadTheDocs migration	Automatic versioned docs from git tags	Planned	#53
Remove plotly from core	Keep core lean — plotting deps in fluxopt-plot only	Planned	#54

Stability Tiers

Component	Tier	Policy
Core modeling API	Stable	Semver. Deprecation warnings before removal.
Stats accessor	Semi-stable	Breaking changes allowed between minor versions with changelog entry.
fluxopt-yaml	Experimental	Own versioning. YAML schema may change.
fluxopt-plot	Experimental	Own versioning. Method signatures may change.
fluxopt-tsam	Independent	Fully independent semver.

See #47 for the full architecture discussion.

Development

Requires uv and Python >= 3.12.

uv sync --group dev      # Install deps
uv run pytest -v         # Run tests
uv run ruff check .      # Lint
uv run ruff format .     # Format

License

MIT