specsolve 0.1.0__tar.gz

specsolve-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+*.so
+.env
+.venv/
+venv/
+.idea/
+.pixi/
+pixi.lock
+
+bench/.cache/
+.benchmarks/
+
+scratch/relational_spike/*_data/
+scratch/relational_spike/bench_out/
+scratch/relational_spike/*.lp
+.DS_Store
+
+site/
+.cache/
+
+docs/*.html
+docs/*.pdf
+# The chart page is a source: it carries its numbers inline.
+!docs/benchmarks-scaling.html
+
+bench/results/.inflight

specsolve-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felix Bumann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

specsolve-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: specsolve
+Version: 0.1.0
+Summary: Self-documenting optimisation models: declarative LP/MILP, built relationally and handed straight to the solver
+Project-URL: Documentation, https://specsolve.readthedocs.io
+Project-URL: Repository, https://github.com/fluxopt/specsolve
+Project-URL: Issues, https://github.com/fluxopt/specsolve/issues
+Project-URL: Changelog, https://github.com/fluxopt/specsolve/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: declarative,highs,linear-programming,mixed-integer,operations-research,optimisation,optimization,polars,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: highspy>=1.13
+Requires-Dist: mathspec>=0.2.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: polars>=1.30
+Provides-Extra: gurobi
+Requires-Dist: gurobipy>=11; extra == 'gurobi'
+Requires-Dist: scipy>=1.11; extra == 'gurobi'
+Provides-Extra: xpress
+Requires-Dist: xpress>=9.5; extra == 'xpress'
+Description-Content-Type: text/markdown
+
+# specsolve
+
+<!-- --8<-- [start:badges] -->
+
+[![CI](https://img.shields.io/github/actions/workflow/status/fluxopt/specsolve/ci.yml?style=flat-square&branch=main)](https://github.com/fluxopt/specsolve/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/specsolve.svg?logo=pypi&logoColor=white&style=flat-square)](https://pypi.org/project/specsolve/)
+[![Python](https://img.shields.io/pypi/pyversions/specsolve?logo=python&logoColor=white&style=flat-square)](https://pypi.org/project/specsolve/)
+[![Docs](https://readthedocs.org/projects/specsolve/badge/?version=latest&style=flat-square)](https://specsolve.readthedocs.io)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg?style=flat-square)](https://github.com/fluxopt/specsolve/blob/main/LICENSE)
+
+<!-- --8<-- [end:badges] -->
+
+**Solve an optimisation problem written in YAML. Attach your data as tables, and
+keep the solver loaded for quick updates and warm starts.**
+
+<!-- --8<-- [start:intro] -->
+
+specsolve solves [mathspec](https://github.com/energy-models/mathspec) specs.
+A spec states the math, and mathspec checks it before any data exists.
+specsolve attaches your tables to the spec, builds the resulting model on
+polars, and hands it to HiGHS, Gurobi or Xpress.
+
+<!-- --8<-- [end:intro] -->
+
+<!-- --8<-- [start:benefits] -->
+
+- **Tables in, tables out.** Pass any Arrow table, such as polars, pandas or
+  DuckDB, or a parquet path. Results come back as tables, and an archive keeps
+  the spec, its data and its results as parquet, ready for queries, plots or
+  BI. [Tables in, tables out →](https://specsolve.readthedocs.io/en/latest/tables/)
+- **Sweeps and rolling horizons built in.** One call runs scenario sweeps,
+  rolling horizons and myopic pathways over the same spec. Each window is
+  checked against how the model couples before it runs. [Sweep a model →](https://specsolve.readthedocs.io/en/latest/sweep/)
+- **Fast, and hard to get wrong.** Tables hold only the rows that exist, so a
+  model's topology does not change its cost. The solver stays loaded:
+  `update()` puts new numbers on it, and `keep='progress'` warm-starts from the
+  last run. The API is a handful of verbs, with nothing to tune.
+  [Benchmarks →](https://specsolve.readthedocs.io/en/latest/about/benchmarks-scaling.html)
+- **Validated against PyPSA.** PyPSA's model is one file here, grown rung by
+  rung through storage, unit commitment, multi-period and stochastic runs. All
+  16 rungs match PyPSA's objective, and 12 match its duals row for row.
+  [The PyPSA ladder →](https://specsolve.readthedocs.io/en/latest/examples/pypsa_ladder/)
+
+<!-- --8<-- [end:benefits] -->
+
+## Example
+
+<!-- --8<-- [start:model] -->
+```yaml
+# dispatch.yaml
+dimensions:
+  snapshot: {dtype: int}
+  generator: {dtype: str}
+parameters:
+  p_max: {dims: [generator]}
+  load:  {dims: [snapshot]}
+  cost:  {dims: [generator]}
+variables:
+  p:
+    dims: [snapshot, generator]
+    where: "p_max > 0"
+    bounds: {lower: 0, upper: p_max}
+constraints:
+  power_balance:
+    dims: [snapshot]
+    expression: sum(p, over=generator) == load
+objective:
+  sense: minimize
+  expression: sum(p * cost)
+```
+<!-- --8<-- [end:model] -->
+
+<!-- --8<-- [start:solve] -->
+
+```python
+import specsolve as sps, polars as pl
+
+generators = ['wind', 'solar', 'gas']
+sources = {  # (1)!
+    'p_max': pl.DataFrame({'generator': generators, 'value': [100.0, 60.0, 200.0]}),
+    'cost': pl.DataFrame({'generator': generators, 'value': [1.0, 2.0, 50.0]}),
+    'load': pl.DataFrame({'snapshot': range(6), 'value': [80.0, 120.0, 150.0, 180.0, 140.0, 100.0]}),
+    'snapshot': range(6),
+    'generator': generators,
+}
+
+result = sps.solve('dispatch.yaml', sources, archive='runs/base/')  # (2)!
+print(result.objective)  # 1920.0
+print(result.primal('p'))  # (3)!
+print(result.dual('power_balance'))
+
+base = sps.scan_archive('runs/base/')  # (4)!
+print(base.answer.primal('p').group_by('generator').agg(pl.col('value').sum()))
+```
+
+1. A source is any table: polars, pandas, pyarrow or DuckDB. It can also be a
+   parquet path, such as `'load': 'load.parquet'`.
+2. `archive=` writes the spec, the data and the answer to `runs/base/` as
+   parquet files.
+3. A tidy table, with one row per snapshot and generator.
+4. `scan_archive` reads the archive where it lies. `base.sources` are parquet
+   paths, so `sps.solve(base.spec, base.sources)` asks the same question again.
+
+<!-- --8<-- [end:solve] -->
+
+## Documentation
+
+The documentation is at <https://specsolve.readthedocs.io>. What a file may
+contain is mathspec's
+[language reference](https://mathspec.readthedocs.io/en/latest/reference/language/).
+
+## Installation
+
+```bash
+pip install specsolve
+```
+
+That brings polars, HiGHS and the language. Add the `[gurobi]` or `[xpress]`
+extra for those solvers. The bridges out of a result, `to_pandas` and
+`to_dataarray`, need pandas and xarray, which you install yourself. To work on
+specsolve, see
+[CONTRIBUTING.md](https://github.com/fluxopt/specsolve/blob/main/CONTRIBUTING.md).
+
+## Prior art
+
+The YAML surface comes from [Calliope](https://github.com/calliope-project/calliope),
+and [linopy](https://github.com/PyPSA/linopy) supplies the vocabulary, the
+oracle and every benchmark denominator.
+[Prior art and credit](https://specsolve.readthedocs.io/en/latest/about/prior-art/)
+says what came from each.
+
+## Status
+
+Alpha, pre-1.0.
+
+<!-- --8<-- [start:status] -->
+
+**Breaking changes land without a deprecation cycle.** Pin an exact version if
+you depend on this, and read the
+[changelog](https://github.com/fluxopt/specsolve/blob/main/CHANGELOG.md) before
+upgrading. A retired spelling fails at load and names its rewrite. Real models
+round-trip through solve and are tested against linopy. The accepted surface
+is not yet frozen.
+
+<!-- --8<-- [end:status] -->
+
+## Licence
+
+[MIT](LICENSE).

specsolve-0.1.0/README.md

@@ -0,0 +1,149 @@
+# specsolve
+
+<!-- --8<-- [start:badges] -->
+
+[![CI](https://img.shields.io/github/actions/workflow/status/fluxopt/specsolve/ci.yml?style=flat-square&branch=main)](https://github.com/fluxopt/specsolve/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/specsolve.svg?logo=pypi&logoColor=white&style=flat-square)](https://pypi.org/project/specsolve/)
+[![Python](https://img.shields.io/pypi/pyversions/specsolve?logo=python&logoColor=white&style=flat-square)](https://pypi.org/project/specsolve/)
+[![Docs](https://readthedocs.org/projects/specsolve/badge/?version=latest&style=flat-square)](https://specsolve.readthedocs.io)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg?style=flat-square)](https://github.com/fluxopt/specsolve/blob/main/LICENSE)
+
+<!-- --8<-- [end:badges] -->
+
+**Solve an optimisation problem written in YAML. Attach your data as tables, and
+keep the solver loaded for quick updates and warm starts.**
+
+<!-- --8<-- [start:intro] -->
+
+specsolve solves [mathspec](https://github.com/energy-models/mathspec) specs.
+A spec states the math, and mathspec checks it before any data exists.
+specsolve attaches your tables to the spec, builds the resulting model on
+polars, and hands it to HiGHS, Gurobi or Xpress.
+
+<!-- --8<-- [end:intro] -->
+
+<!-- --8<-- [start:benefits] -->
+
+- **Tables in, tables out.** Pass any Arrow table, such as polars, pandas or
+  DuckDB, or a parquet path. Results come back as tables, and an archive keeps
+  the spec, its data and its results as parquet, ready for queries, plots or
+  BI. [Tables in, tables out →](https://specsolve.readthedocs.io/en/latest/tables/)
+- **Sweeps and rolling horizons built in.** One call runs scenario sweeps,
+  rolling horizons and myopic pathways over the same spec. Each window is
+  checked against how the model couples before it runs. [Sweep a model →](https://specsolve.readthedocs.io/en/latest/sweep/)
+- **Fast, and hard to get wrong.** Tables hold only the rows that exist, so a
+  model's topology does not change its cost. The solver stays loaded:
+  `update()` puts new numbers on it, and `keep='progress'` warm-starts from the
+  last run. The API is a handful of verbs, with nothing to tune.
+  [Benchmarks →](https://specsolve.readthedocs.io/en/latest/about/benchmarks-scaling.html)
+- **Validated against PyPSA.** PyPSA's model is one file here, grown rung by
+  rung through storage, unit commitment, multi-period and stochastic runs. All
+  16 rungs match PyPSA's objective, and 12 match its duals row for row.
+  [The PyPSA ladder →](https://specsolve.readthedocs.io/en/latest/examples/pypsa_ladder/)
+
+<!-- --8<-- [end:benefits] -->
+
+## Example
+
+<!-- --8<-- [start:model] -->
+```yaml
+# dispatch.yaml
+dimensions:
+  snapshot: {dtype: int}
+  generator: {dtype: str}
+parameters:
+  p_max: {dims: [generator]}
+  load:  {dims: [snapshot]}
+  cost:  {dims: [generator]}
+variables:
+  p:
+    dims: [snapshot, generator]
+    where: "p_max > 0"
+    bounds: {lower: 0, upper: p_max}
+constraints:
+  power_balance:
+    dims: [snapshot]
+    expression: sum(p, over=generator) == load
+objective:
+  sense: minimize
+  expression: sum(p * cost)
+```
+<!-- --8<-- [end:model] -->
+
+<!-- --8<-- [start:solve] -->
+
+```python
+import specsolve as sps, polars as pl
+
+generators = ['wind', 'solar', 'gas']
+sources = {  # (1)!
+    'p_max': pl.DataFrame({'generator': generators, 'value': [100.0, 60.0, 200.0]}),
+    'cost': pl.DataFrame({'generator': generators, 'value': [1.0, 2.0, 50.0]}),
+    'load': pl.DataFrame({'snapshot': range(6), 'value': [80.0, 120.0, 150.0, 180.0, 140.0, 100.0]}),
+    'snapshot': range(6),
+    'generator': generators,
+}
+
+result = sps.solve('dispatch.yaml', sources, archive='runs/base/')  # (2)!
+print(result.objective)  # 1920.0
+print(result.primal('p'))  # (3)!
+print(result.dual('power_balance'))
+
+base = sps.scan_archive('runs/base/')  # (4)!
+print(base.answer.primal('p').group_by('generator').agg(pl.col('value').sum()))
+```
+
+1. A source is any table: polars, pandas, pyarrow or DuckDB. It can also be a
+   parquet path, such as `'load': 'load.parquet'`.
+2. `archive=` writes the spec, the data and the answer to `runs/base/` as
+   parquet files.
+3. A tidy table, with one row per snapshot and generator.
+4. `scan_archive` reads the archive where it lies. `base.sources` are parquet
+   paths, so `sps.solve(base.spec, base.sources)` asks the same question again.
+
+<!-- --8<-- [end:solve] -->
+
+## Documentation
+
+The documentation is at <https://specsolve.readthedocs.io>. What a file may
+contain is mathspec's
+[language reference](https://mathspec.readthedocs.io/en/latest/reference/language/).
+
+## Installation
+
+```bash
+pip install specsolve
+```
+
+That brings polars, HiGHS and the language. Add the `[gurobi]` or `[xpress]`
+extra for those solvers. The bridges out of a result, `to_pandas` and
+`to_dataarray`, need pandas and xarray, which you install yourself. To work on
+specsolve, see
+[CONTRIBUTING.md](https://github.com/fluxopt/specsolve/blob/main/CONTRIBUTING.md).
+
+## Prior art
+
+The YAML surface comes from [Calliope](https://github.com/calliope-project/calliope),
+and [linopy](https://github.com/PyPSA/linopy) supplies the vocabulary, the
+oracle and every benchmark denominator.
+[Prior art and credit](https://specsolve.readthedocs.io/en/latest/about/prior-art/)
+says what came from each.
+
+## Status
+
+Alpha, pre-1.0.
+
+<!-- --8<-- [start:status] -->
+
+**Breaking changes land without a deprecation cycle.** Pin an exact version if
+you depend on this, and read the
+[changelog](https://github.com/fluxopt/specsolve/blob/main/CHANGELOG.md) before
+upgrading. A retired spelling fails at load and names its rewrite. Real models
+round-trip through solve and are tested against linopy. The accepted surface
+is not yet frozen.
+
+<!-- --8<-- [end:status] -->
+
+## Licence
+
+[MIT](LICENSE).