Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

fluxopt

Energy system optimization with linopy — detailed dispatch, scaled to multi period planning.
https://github.com/fluxopt/fluxopt

Category: Energy Systems
Sub Category: Energy System Modeling Frameworks

Last synced: about 15 hours ago
JSON representation

Repository metadata

Successor of flixopt with a new datamodel

README.md

fluxopt

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

PyPI
Downloads
License: MIT
Python 3.12+
Ruff

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

# A gas boiler covers a heat demand, minimizing fuel cost
from datetime import datetime
from fluxopt import Carrier, Converter, Effect, Flow, Port, optimize

result = optimize(
    timesteps=[datetime(2024, 1, 1, h) for h in range(4)],
    carriers=[Carrier('gas'), Carrier('heat')],
    effects=[Effect('cost')],
    ports=[
        Port('grid', imports=[
            Flow('gas', size=500, effects_per_flow_hour={'cost': 0.04})
        ]),
        Port('demand', exports=[
            Flow('heat', size=100, fixed_relative_profile=[0.4, 0.7, 0.5, 0.6])
        ])
    ],
    converters=[
        Converter.boiler(
            'boiler',
            thermal_efficiency=0.9,
            fuel_flow=Flow('gas', size=300),
            thermal_flow=Flow('heat', size=200)
        )
    ],
    objective_effects='cost',
)

print(f"Total cost: {result.objective:.2f}")
print(result.flow_rates)

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  fluxopt-marimo  (examples)
   plotting      YAML+CSV    time series    interactive     cross-package
   (plotly)       loader     aggregation       apps          notebooks

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

Companion packages

Package Role Versioning · Tier fluxopt pin Status
fluxopt-plot Result visualization (Plotly) Semver · Experimental — method signatures may change Tight (>=A.B,<A.C), validated per release Scaffolded — docs · #51
fluxopt-yaml Declarative model loader (YAML + CSV → Elements) Semver · Experimental — YAML schema may change Tight (>=A.B,<A.C), validated per release Scaffolded — docs · #52
fluxopt-tsam Time series aggregation — input pre-processing, possibly result disaggregation Semver · Experimental — round-trip schema may evolve Undecided — depends on whether representative-period primitives live in core (→ loose) or in this package (→ tight) Planned
fluxopt-marimo Interactive exploration & dashboards (marimo apps) CalVer (YYYY.MM.PATCH) · Experimental — apps are templates Tight (>=A.B,<A.C), validated per release Planned

Tight-pinned companions release on every fluxopt minor; validation is
automated via scheduled CI. fluxopt-tsam's pin policy is blocked on an
architectural decision — if representative-period primitives live in core, tsam stays
a thin adapter (loose pin); if they live in tsam, the package owns deep
round-trip behavior (tight pin).

Milestones

Cross-cutting work not tied to a single companion package:

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
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.

Companion packages have their own stability policies — see the table above.

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

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: 7 days ago

Total Commits: 142
Total Committers: 5
Avg Commits per committer: 28.4
Development Distribution Score (DDS): 0.204

Commits in past year: 142
Committers in past year: 5
Avg Commits per committer in past year: 28.4
Development Distribution Score (DDS) in past year: 0.204

Name Email Commits
FBumann 1****n 113
dependabot[bot] 4****] 21
fluxopt-release[bot] 2****] 6
Shaan Satsangi 1****a 1
GitButler g****r@g****m 1

Committer domains:

Issue and Pull Request metadata

Last synced: 4 days ago

Total issues: 23
Total pull requests: 68
Average time to close issues: 2 months
Average time to close pull requests: 5 days
Total issue authors: 1
Total pull request authors: 3
Average comments per issue: 0.09
Average comments per pull request: 1.31
Merged pull request: 51
Bot issues: 0
Bot pull requests: 20

Past year issues: 23
Past year pull requests: 68
Past year average time to close issues: 2 months
Past year average time to close pull requests: 5 days
Past year issue authors: 1
Past year pull request authors: 3
Past year average comments per issue: 0.09
Past year average comments per pull request: 1.31
Past year merged pull request: 51
Past year bot issues: 0
Past year bot pull requests: 20

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/fluxopt/fluxopt

Top Issue Authors

  • FBumann (23)

Top Pull Request Authors

  • FBumann (48)
  • dependabot[bot] (19)
  • fluxopt-release[bot] (1)

Top Issue Labels

  • type:feat (17)
  • area:effects (7)
  • area:flow (5)
  • area:storage (4)
  • area:multi-period (4)
  • area:status (3)
  • area:sizing (3)
  • area:new (2)
  • type:fix (2)
  • area:api (2)
  • area:io (1)
  • type:perf (1)

Top Pull Request Labels

  • dependencies (19)
  • type:feat (15)
  • type:docs (10)
  • area:effects (8)
  • type:fix (8)
  • area:status (3)
  • area:sizing (3)
  • area:converter (2)
  • area:storage (1)
  • area:multi-period (1)
  • area:api (1)
  • autorelease: tagged (1)
  • type:perf (1)

Dependencies

pyproject.toml pypi
  • highspy >=1.13.1
  • linopy @ git+https://github.com/PyPSA/linopy.git@f53d1968e53d70962eb208b01c3f938f693f0083
  • netcdf4 >=1.6.0
  • numpy >=1.26
  • pandas >=2.1
  • xarray >=2024.1.0
.github/workflows/dependabot-auto-merge.yaml actions
  • actions/create-github-app-token v3 composite
  • dependabot/fetch-metadata v2 composite
.github/workflows/ci.yaml actions
  • actions/checkout v6 composite
  • actions/setup-python v6 composite
  • astral-sh/ruff-action v3 composite
  • astral-sh/setup-uv v7 composite
  • codecov/codecov-action v5 composite
.github/workflows/pr-title.yaml actions
  • amannn/action-semantic-pull-request v6 composite
.github/workflows/release.yaml actions
  • actions/create-github-app-token v3 composite
  • googleapis/release-please-action v4 composite
.github/workflows/publish.yaml actions
  • actions/checkout v6 composite
  • actions/setup-python v6 composite
  • astral-sh/setup-uv v7 composite
  • pypa/gh-action-pypi-publish release/v1 composite
.github/workflows/label-from-title.yaml actions

Score: 5.298317366548036