tsam-xarray 0.6.4__tar.gz → 0.6.6__tar.gz

tsam_xarray-0.6.6/.github/workflows/benchmarks.yaml

@@ -0,0 +1,126 @@
+name: Benchmarks
+
+# Informational performance report on every PR: run the pytest-benchmem suite
+# on the PR head and on the base branch in the same job (same runner, same
+# pinned benchmem version), then keep one sticky comment with the delta table
+# and upload an interactive plot artifact. Never blocks a merge — GitHub
+# runners are noisy, so treat the walltime deltas as a hint, not a gate.
+# Fork PRs run too (read-only token) and get the step summary and artifact;
+# only the sticky comment needs a writable token and is skipped for them.
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  BENCHMEM: pytest-benchmem[plot]==0.4.10
+  BENCH_ARGS: >-
+    -o addopts= -p no:xdist -q --benchmark-only --benchmark-memory
+    --benchmark-disable-gc
+
+jobs:
+  report:
+    name: Head vs base
+    runs-on: ubuntu-24.04
+    continue-on-error: true # informational, never blocks a merge
+    permissions:
+      contents: read
+      pull-requests: write # no-op on fork PRs (read-only token); comment step is guarded
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # hatch-vcs + checkout of the base revision
+          persist-credentials: false # benchmarks execute PR code; keep the token out of .git/config
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Benchmark head
+        run: |
+          uv run --with "$BENCHMEM" pytest benchmarks/ $BENCH_ARGS \
+            --benchmark-json "$RUNNER_TEMP/head.json"
+          uv run --no-sync python -c "import tsam; print('head tsam:', tsam.__version__)"
+
+      - name: Benchmark base (${{ github.event.pull_request.base.ref }})
+        if: github.event_name == 'pull_request'
+        # Base src with the head's benchmark suite overlaid, so test IDs match
+        # and suite edits in the PR still compare against the same cases.
+        # Drop the head run's uv.lock (untracked — the repo commits none):
+        # uv keeps a satisfying lock as-is, so without this a head that
+        # changes dependencies leaks its resolution into the base run.
+        run: |
+          git checkout --detach ${{ github.event.pull_request.base.sha }}
+          git checkout ${{ github.sha }} -- benchmarks/
+          rm -f uv.lock
+          uv run --exact --with "$BENCHMEM" pytest benchmarks/ $BENCH_ARGS \
+            --benchmark-json "$RUNNER_TEMP/base.json"
+          uv run --no-sync python -c "import tsam; print('base tsam:', tsam.__version__)"
+
+      - name: Render report and plot
+        run: |
+          if [ -f "$RUNNER_TEMP/base.json" ]; then
+            uv run --with "$BENCHMEM" benchmem compare \
+              "$RUNNER_TEMP/base.json" "$RUNNER_TEMP/head.json" \
+              --diff --group-by module --sort change --format md > "$RUNNER_TEMP/table.md"
+            uv run --with "$BENCHMEM" benchmem plot \
+              "$RUNNER_TEMP/base.json" "$RUNNER_TEMP/head.json" \
+              --view compare -o benchmark-plot.html
+            {
+              echo 'Δ% vs base, one table sorted by biggest change first'
+              echo '(`min` walltime and memray `peak`). Peak memory is'
+              echo 'deterministic — any delta there is real; walltime on GitHub'
+              echo 'runners is noisy, so only large time deltas are meaningful.'
+            } > "$RUNNER_TEMP/intro.md"
+          else
+            uv run --with "$BENCHMEM" benchmem compare \
+              "$RUNNER_TEMP/head.json" --format md > "$RUNNER_TEMP/table.md"
+            uv run --with "$BENCHMEM" benchmem plot \
+              "$RUNNER_TEMP/head.json" --x n_cols -o benchmark-plot.html
+            echo 'Standalone run — no base revision to compare against.' \
+              > "$RUNNER_TEMP/intro.md"
+          fi
+          {
+            echo '<!-- benchmarks-report -->'
+            echo '## Benchmarks'
+            echo
+            cat "$RUNNER_TEMP/intro.md"
+            echo 'The interactive plot is attached as the `benchmark-plot` artifact.'
+            echo
+            echo '<details><summary>Full table</summary>'
+            echo
+            cat "$RUNNER_TEMP/table.md"
+            echo
+            echo '</details>'
+          } > "$RUNNER_TEMP/comment.md"
+          cat "$RUNNER_TEMP/comment.md" >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-plot
+          path: benchmark-plot.html
+
+      - name: Post or update the sticky comment
+        # Commenting needs a writable token; fork PRs only get a read-only one,
+        # so they keep the step summary and artifact but skip the comment.
+        if: >-
+          ${{ github.event_name == 'pull_request' &&
+              github.event.pull_request.head.repo.full_name == github.repository }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          marker='<!-- benchmarks-report -->'
+          existing=$(gh api --paginate "repos/${{ github.repository }}/issues/$PR/comments" \
+            --jq ".[] | select(.body | startswith(\"$marker\")) | .id" | head -n1)
+          if [ -n "$existing" ]; then
+            gh api -X PATCH "repos/${{ github.repository }}/issues/comments/$existing" \
+              -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
+          else
+            gh pr comment "$PR" --body-file "$RUNNER_TEMP/comment.md"
+          fi

{tsam_xarray-0.6.4 → tsam_xarray-0.6.6}/.gitignore

@@ -37,3 +37,4 @@ site/
 # OS
 .DS_Store
 docs/examples/clustering.json
+.benchmarks/

tsam_xarray-0.6.6/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.6.6"
+}

{tsam_xarray-0.6.4 → tsam_xarray-0.6.6}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.6.6](https://github.com/FBumann/tsam_xarray/compare/v0.6.5...v0.6.6) (2026-07-27)
+
+
+### Performance Improvements
+
+* compute accuracy and reconstructed on first access ([#113](https://github.com/FBumann/tsam_xarray/issues/113)) ([69443aa](https://github.com/FBumann/tsam_xarray/commit/69443aa78a7e4cef5551a1010e65bc3e99210af7))
+* disaggregate segmented clusterings with a scatter ([#117](https://github.com/FBumann/tsam_xarray/issues/117)) ([02c569f](https://github.com/FBumann/tsam_xarray/commit/02c569f44a2c937841a10db343be1c5a2daf70e3))
+* gather from the payload's final layout instead of a strided view ([#119](https://github.com/FBumann/tsam_xarray/issues/119)) ([0a455bf](https://github.com/FBumann/tsam_xarray/commit/0a455bf81792b2654cd644bcce24fbc6a92f32cb))
+
+## [0.6.5](https://github.com/FBumann/tsam_xarray/compare/v0.6.4...v0.6.5) (2026-07-27)
+
+
+### Features
+
+* support tsam v4 (cluster_counts rename, ClusterConfig.weights removal) ([#105](https://github.com/FBumann/tsam_xarray/issues/105)) ([6cd9f5d](https://github.com/FBumann/tsam_xarray/commit/6cd9f5d41057eb7ec9e3a29f811d7ee52a80a9c0))
+
+
+### Bug Fixes
+
+* reset uv.lock before the base benchmark run ([#111](https://github.com/FBumann/tsam_xarray/issues/111)) ([3d7d8b7](https://github.com/FBumann/tsam_xarray/commit/3d7d8b7ed0f5b435e9d1eda17080bbaa4a79d158))
+
+
+### Performance Improvements
+
+* disaggregate unsegmented clusterings with a numpy gather ([#116](https://github.com/FBumann/tsam_xarray/issues/116)) ([0fc2de6](https://github.com/FBumann/tsam_xarray/commit/0fc2de6676b2322f0d0a0512c88a13ecc47ae160))
+
 ## [0.6.4](https://github.com/FBumann/tsam_xarray/compare/v0.6.3...v0.6.4) (2026-07-22)
 
 

{tsam_xarray-0.6.4 → tsam_xarray-0.6.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsam_xarray
-Version: 0.6.4
+Version: 0.6.6
 Summary: Lightweight xarray wrapper for tsam time series aggregation
 License-Expression: MIT
 License-File: LICENSE
@@ -44,9 +44,9 @@ tsam works on flat DataFrames. With multi-dimensional data, you end up writing b
 import tsam_xarray
 
 result = tsam_xarray.aggregate(
-    da,                                    # (time, variable, region, scenario)
+    da,  # (time, variable, region, scenario)
     time_dim="time",
-    cluster_dim=["variable", "region"],    # clustered together
+    cluster_dim=["variable", "region"],  # clustered together
     n_clusters=4,
 )
 # scenario is sliced independently — each gets its own clustering
@@ -55,9 +55,9 @@ result = tsam_xarray.aggregate(
 Everything comes back as labeled xarray objects:
 
 ```python
-result.cluster_representatives   # (scenario, cluster, timestep, variable, region)
-result.reconstructed             # same shape as input
-result.cluster_assignments       # (scenario, period)
+result.cluster_representatives  # (scenario, cluster, timestep, variable, region)
+result.reconstructed  # same shape as input
+result.cluster_assignments  # (scenario, period)
 ```
 
 Accuracy metrics preserve all dimensions — see exactly where the approximation is good or bad:
@@ -65,8 +65,8 @@ Accuracy metrics preserve all dimensions — see exactly where the approximation
 ![Per-column RMSE across all dimensions](docs/assets/multi-dim-metrics.png)
 
 ```python
-result.accuracy.rmse             # DataArray (scenario, variable, region)
-result.accuracy.weighted_rmse    # DataArray (scenario,) — per-slice summary
+result.accuracy.rmse  # DataArray (scenario, variable, region)
+result.accuracy.weighted_rmse  # DataArray (scenario,) — per-slice summary
 ```
 
 ## Save, load, reuse
@@ -77,9 +77,9 @@ result.clustering.to_json("clustering.json")
 
 # Load and inspect — no original data needed
 clustering = tsam_xarray.load_clustering("clustering.json")
-clustering.n_clusters              # 4
-clustering.cluster_assignments     # DataArray (scenario, period)
-clustering.cluster_occurrences     # DataArray (scenario, cluster)
+clustering.n_clusters  # 4
+clustering.cluster_assignments  # DataArray (scenario, period)
+clustering.cluster_occurrences  # DataArray (scenario, cluster)
 
 # Apply to new data or disaggregate optimization results
 new_result = clustering.apply(new_da)
@@ -97,8 +97,8 @@ grid = tsam_xarray.grid_search(
     cluster_dim=["variable", "region"],
     timesteps=np.geomspace(2, 48, num=12, dtype=int),  # sparse search
 )
-grid.summary_matrix["rmse"]        # heatmap-ready (n_clusters, n_segments)
-grid.accuracy["weighted_rmse"]     # per-slice weighted RMSE for every config
+grid.summary_matrix["rmse"]  # heatmap-ready (n_clusters, n_segments)
+grid.accuracy["weighted_rmse"]  # per-slice weighted RMSE for every config
 ```
 
 ## Installation

{tsam_xarray-0.6.4 → tsam_xarray-0.6.6}/README.md

@@ -23,9 +23,9 @@ tsam works on flat DataFrames. With multi-dimensional data, you end up writing b
 import tsam_xarray
 
 result = tsam_xarray.aggregate(
-    da,                                    # (time, variable, region, scenario)
+    da,  # (time, variable, region, scenario)
     time_dim="time",
-    cluster_dim=["variable", "region"],    # clustered together
+    cluster_dim=["variable", "region"],  # clustered together
     n_clusters=4,
 )
 # scenario is sliced independently — each gets its own clustering
@@ -34,9 +34,9 @@ result = tsam_xarray.aggregate(
 Everything comes back as labeled xarray objects:
 
 ```python
-result.cluster_representatives   # (scenario, cluster, timestep, variable, region)
-result.reconstructed             # same shape as input
-result.cluster_assignments       # (scenario, period)
+result.cluster_representatives  # (scenario, cluster, timestep, variable, region)
+result.reconstructed  # same shape as input
+result.cluster_assignments  # (scenario, period)
 ```
 
 Accuracy metrics preserve all dimensions — see exactly where the approximation is good or bad:
@@ -44,8 +44,8 @@ Accuracy metrics preserve all dimensions — see exactly where the approximation
 ![Per-column RMSE across all dimensions](docs/assets/multi-dim-metrics.png)
 
 ```python
-result.accuracy.rmse             # DataArray (scenario, variable, region)
-result.accuracy.weighted_rmse    # DataArray (scenario,) — per-slice summary
+result.accuracy.rmse  # DataArray (scenario, variable, region)
+result.accuracy.weighted_rmse  # DataArray (scenario,) — per-slice summary
 ```
 
 ## Save, load, reuse
@@ -56,9 +56,9 @@ result.clustering.to_json("clustering.json")
 
 # Load and inspect — no original data needed
 clustering = tsam_xarray.load_clustering("clustering.json")
-clustering.n_clusters              # 4
-clustering.cluster_assignments     # DataArray (scenario, period)
-clustering.cluster_occurrences     # DataArray (scenario, cluster)
+clustering.n_clusters  # 4
+clustering.cluster_assignments  # DataArray (scenario, period)
+clustering.cluster_occurrences  # DataArray (scenario, cluster)
 
 # Apply to new data or disaggregate optimization results
 new_result = clustering.apply(new_da)
@@ -76,8 +76,8 @@ grid = tsam_xarray.grid_search(
     cluster_dim=["variable", "region"],
     timesteps=np.geomspace(2, 48, num=12, dtype=int),  # sparse search
 )
-grid.summary_matrix["rmse"]        # heatmap-ready (n_clusters, n_segments)
-grid.accuracy["weighted_rmse"]     # per-slice weighted RMSE for every config
+grid.summary_matrix["rmse"]  # heatmap-ready (n_clusters, n_segments)
+grid.accuracy["weighted_rmse"]  # per-slice weighted RMSE for every config
 ```
 
 ## Installation

tsam_xarray-0.6.6/benchmarks/README.md

@@ -0,0 +1,60 @@
+# Benchmarks
+
+Performance suite for `aggregate()`, built on
+[pytest-benchmem](https://github.com/fluxopt/pytest-benchmem) (pytest-benchmark
+plus memray peak-memory columns). Not part of the regular test suite — CI runs
+it via `.github/workflows/benchmarks.yaml`, which posts a head-vs-base delta
+table on every PR and uploads an interactive plot artifact.
+
+Three layers (see the module docstring in `test_bench_aggregate.py`):
+wrapper-stage micro-benchmarks with many rounds (the only code this repo's
+PRs can regress — ~90% of an end-to-end run is inside tsam), config cost
+ratios at reduced size, and a few full-pipeline sentinels at production
+size. Cases are a deterministic grid, not random: `benchmem compare`
+matches runs by test ID, so IDs must be stable across runs for baselines
+to work.
+
+## Run locally
+
+```bash
+uv run --with "pytest-benchmem[plot]" pytest benchmarks/ \
+    -o addopts="" -p no:xdist --benchmark-only --benchmark-memory
+```
+
+(`-o addopts="" -p no:xdist` because the project's xdist config auto-disables
+benchmarks.)
+
+## Large tier
+
+Production-sized cases (`test_large_*`, several seconds and hundreds of MiB
+peak each) are skipped by default — in CI too. Run them locally before
+dependency bumps or performance work:
+
+```bash
+uv run --with "pytest-benchmem[plot]" pytest benchmarks/ --large -k large \
+    -o addopts="" -p no:xdist --benchmark-only --benchmark-memory
+```
+
+## Baselines
+
+Save a named baseline (stored in `.benchmarks/`, gitignored — machine-specific):
+
+```bash
+... --benchmark-save=baseline
+```
+
+Compare a later run against it, failing on >10% mean regressions:
+
+```bash
+... --benchmark-compare=0001 --benchmark-compare-fail=mean:10%
+```
+
+## Reports and plots
+
+```bash
+uv run --with "pytest-benchmem[plot]" benchmem compare a.json b.json --diff
+uv run --with "pytest-benchmem[plot]" benchmem plot a.json b.json -o plot.html --open
+```
+
+`benchmem flamegraph <test-id>` renders a memory flamegraph when the run was
+saved with `--benchmark-memory-profile`.

tsam_xarray-0.6.6/benchmarks/conftest.py

@@ -0,0 +1,25 @@
+import pytest
+
+
+def pytest_addoption(parser):
+    parser.addoption(
+        "--large",
+        action="store_true",
+        default=False,
+        help="run large-scale benchmarks (production-sized data, minutes)",
+    )
+
+
+def pytest_configure(config):
+    config.addinivalue_line(
+        "markers", "large: large-scale benchmark, runs only with --large"
+    )
+
+
+def pytest_collection_modifyitems(config, items):
+    if config.getoption("--large"):
+        return
+    skip = pytest.mark.skip(reason="large benchmark: pass --large to run")
+    for item in items:
+        if "large" in item.keywords:
+            item.add_marker(skip)

tsam_xarray-0.6.6/benchmarks/test_bench_aggregate.py

@@ -0,0 +1,279 @@
+"""Benchmarks for tsam_xarray: wrapper micro-benchmarks + end-to-end sentinels.
+
+Run with:
+    uv run --with pytest-benchmem pytest benchmarks/ -o addopts= -p no:xdist \
+        --benchmark-only --benchmark-memory
+
+Three layers, cheapest statistics where the repo's own code lives:
+
+- ``test_wrapper_*`` — micro-benchmarks of the wrapper's conversion stages
+  (DataFrame in, result out, slice concat). Profiling showed ~90% of an
+  end-to-end run is inside tsam, which this repo cannot regress — its PRs
+  can only regress these stages, so they get many rounds and wide inputs.
+- ``test_config_*`` — cost ratios of tsam config options at a reduced size
+  (90 days); every measured config effect is multiplicative, so ratios at
+  90 days match 365 days at a quarter of the cost.
+- ``test_e2e_*`` — few full-pipeline sentinels at production size for
+  integration surprises (tsam version bumps, config plumbing), the
+  representation-by-width interaction, and the multi-``cluster_dim``
+  MultiIndex path.
+- ``test_large_*`` — production-sized cases (hundreds of MiB peak) that
+  guard the memory-amplification regime. Opt-in via ``--large`` (skipped
+  otherwise, including in CI) — run locally before dependency bumps or
+  performance work.
+- ``test_user_*`` — post-aggregation operations users run on results:
+  reusing a stored clustering on new data (``clustering.apply``) and
+  expanding cluster-level data back to the full time axis
+  (``disaggregate``). Accuracy metrics and ``reconstructed`` need no
+  extra cases — tsam computes them eagerly inside ``aggregate()``, so
+  every e2e case and the result-conversion micro already include them.
+
+Cases are a deterministic grid (data seeded per call) because benchmem
+matches runs by test ID — IDs and data must be stable across runs.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import pytest
+import tsam
+import xarray as xr
+
+from tsam_xarray import aggregate
+from tsam_xarray._core import (
+    _aggregate_single,
+    _concat_results,
+    _result_from_tsam,
+    _to_dataframe,
+)
+from tsam_xarray._dim_names import DimNames
+
+
+def make_data(n_days: int, n_cols: int, n_slices: int) -> xr.DataArray:
+    rng = np.random.default_rng(42)
+    n_t = n_days * 24
+    time_idx = pd.date_range("2023-01-01", periods=n_t, freq="h")
+    t = np.arange(n_t)
+    daily = np.sin(2 * np.pi * t / 24)
+    yearly = np.sin(2 * np.pi * t / 8760)
+    base = (
+        daily[None, :] * rng.uniform(0.5, 2, (n_cols, 1))
+        + yearly[None, :] * rng.uniform(0.5, 2, (n_cols, 1))
+        + rng.normal(0, 0.3, (n_cols, n_t))
+    )
+    dims = ["variable", "time"]
+    coords: dict[str, object] = {
+        "variable": [f"var{i:03d}" for i in range(n_cols)],
+        "time": time_idx,
+    }
+    data = base
+    if n_slices > 1:
+        scale = rng.uniform(0.8, 1.2, (n_slices, 1, 1))
+        data = base[None, :, :] * scale
+        dims = ["scenario", *dims]
+        coords["scenario"] = [f"s{i}" for i in range(n_slices)]
+    return xr.DataArray(data, dims=dims, coords=coords, name="load")
+
+
+def cluster_config(representation: object | None = None) -> tsam.ClusterConfig:
+    return tsam.ClusterConfig(
+        method="hierarchical",
+        representation=representation,
+        include_period_sums=False,
+    )
+
+
+def extremes_config(method: str = "replace") -> tsam.ExtremeConfig:
+    return tsam.ExtremeConfig(method=method, max_value=["var000"], min_value=["var001"])
+
+
+FULL_CONFIG: dict[str, object] = {
+    "cluster": cluster_config(tsam.Distribution(scope="global")),
+    "extremes": extremes_config(),
+}
+
+REPRESENTATIONS: dict[str, object | None] = {
+    "medoid": None,
+    "mean": "mean",
+    "dist_cluster": tsam.Distribution(scope="cluster"),
+    "dist_global": tsam.Distribution(scope="global"),
+    "dist_global_minmax": tsam.Distribution(scope="global", preserve_minmax=True),
+}
+
+
+def run_aggregate(
+    da: xr.DataArray,
+    config: dict[str, object],
+    cluster_dim: list[str] | str = "variable",
+) -> None:
+    aggregate(da, time_dim="time", cluster_dim=cluster_dim, n_clusters=12, **config)
+
+
+MICRO_OPTS = dict(rounds=10, iterations=10, warmup_rounds=1)
+CONFIG_OPTS = dict(rounds=5, iterations=1, warmup_rounds=1)
+E2E_OPTS = dict(rounds=3, iterations=1, warmup_rounds=1)
+
+
+# --- wrapper micro-benchmarks -------------------------------------------------
+
+
+@pytest.fixture(scope="module")
+def wide_tsam_result():
+    da = make_data(365, 128, 1)
+    df = _to_dataframe(da, "time", ["variable"])
+    return tsam.aggregate(df, 12), da, df
+
+
+@pytest.fixture(scope="module")
+def slice_results():
+    da = make_data(365, 8, 8)
+    scenarios = da.coords["scenario"].values
+    results = [
+        _aggregate_single(
+            da.sel(scenario=s), 12, "time", ["variable"], None, None, {}, DimNames()
+        )
+        for s in scenarios
+    ]
+    return results, {"scenario": scenarios}, [(s,) for s in scenarios]
+
+
+def test_wrapper_to_dataframe(benchmark):
+    da = make_data(365, 128, 1)
+    benchmark.pedantic(_to_dataframe, args=(da, "time", ["variable"]), **MICRO_OPTS)
+
+
+def test_wrapper_result_conversion(benchmark, wide_tsam_result):
+    res, da, df = wide_tsam_result
+    benchmark.pedantic(
+        _result_from_tsam,
+        args=(res, da, df, "time", ["variable"], DimNames()),
+        **MICRO_OPTS,
+    )
+
+
+def test_wrapper_concat_results(benchmark, slice_results):
+    results, slice_coords, slice_keys = slice_results
+    benchmark.pedantic(
+        _concat_results,
+        args=(results, ["scenario"], slice_coords, slice_keys),
+        **MICRO_OPTS,
+    )
+
+
+# --- config cost ratios (reduced size) ----------------------------------------
+
+
+@pytest.mark.parametrize("representation", list(REPRESENTATIONS))
+def test_config_representation(benchmark, representation):
+    da = make_data(90, n_cols=8, n_slices=1)
+    config = {"cluster": cluster_config(REPRESENTATIONS[representation])}
+    benchmark.pedantic(run_aggregate, args=(da, config), **CONFIG_OPTS)
+
+
+@pytest.mark.parametrize("extremes", ["replace", "append"])
+def test_config_extremes(benchmark, extremes):
+    da = make_data(90, n_cols=8, n_slices=1)
+    config = {"cluster": cluster_config(), "extremes": extremes_config(extremes)}
+    benchmark.pedantic(run_aggregate, args=(da, config), **CONFIG_OPTS)
+
+
+# --- end-to-end sentinels -----------------------------------------------------
+
+
+def test_e2e_default(benchmark):
+    da = make_data(365, n_cols=8, n_slices=1)
+    benchmark.pedantic(run_aggregate, args=(da, {}), **E2E_OPTS)
+
+
+def test_e2e_full(benchmark):
+    da = make_data(365, n_cols=8, n_slices=1)
+    benchmark.pedantic(run_aggregate, args=(da, FULL_CONFIG), **E2E_OPTS)
+
+
+@pytest.mark.parametrize("representation", ["medoid", "dist_global"])
+def test_e2e_wide(benchmark, representation):
+    da = make_data(365, n_cols=128, n_slices=1)
+    config = {"cluster": cluster_config(REPRESENTATIONS[representation])}
+    benchmark.pedantic(run_aggregate, args=(da, config), **E2E_OPTS)
+
+
+def test_e2e_slices(benchmark):
+    da = make_data(365, n_cols=8, n_slices=8)
+    benchmark.pedantic(run_aggregate, args=(da, FULL_CONFIG), **E2E_OPTS)
+
+
+def test_e2e_multidim(benchmark):
+    da = make_data(365, n_cols=8, n_slices=4).rename(scenario="region")
+    benchmark.pedantic(run_aggregate, args=(da, {}, ["variable", "region"]), **E2E_OPTS)
+
+
+# --- user post-aggregation operations -----------------------------------------
+
+
+@pytest.fixture(scope="module")
+def wide_result():
+    da = make_data(365, 128, 1)
+    result = aggregate(da, time_dim="time", cluster_dim="variable", n_clusters=12)
+    return result, da
+
+
+def test_user_apply(benchmark, wide_result):
+    result, da = wide_result
+    benchmark.pedantic(result.clustering.apply, args=(da * 1.1,), **CONFIG_OPTS)
+
+
+def test_user_disaggregate(benchmark, wide_result):
+    result, _da = wide_result
+    benchmark.pedantic(
+        result.clustering.disaggregate,
+        args=(result.cluster_representatives,),
+        **CONFIG_OPTS,
+    )
+
+
+@pytest.fixture(scope="module")
+def sliced_result():
+    da = make_data(365, 32, 12)
+    return aggregate(da, time_dim="time", cluster_dim="variable", n_clusters=12)
+
+
+def test_user_disaggregate_sliced(benchmark, sliced_result):
+    benchmark.pedantic(
+        sliced_result.clustering.disaggregate,
+        args=(sliced_result.cluster_representatives,),
+        **CONFIG_OPTS,
+    )
+
+
+def test_user_disaggregate_segmented(benchmark):
+    da = make_data(365, 32, 1)
+    result = aggregate(
+        da,
+        time_dim="time",
+        cluster_dim="variable",
+        n_clusters=12,
+        segments=tsam.SegmentConfig(n_segments=6),
+    )
+    benchmark.pedantic(
+        result.clustering.disaggregate,
+        args=(result.cluster_representatives,),
+        **CONFIG_OPTS,
+    )
+
+
+# --- large tier (production-sized, opt-in via --large) -------------------------
+
+LARGE_OPTS = dict(rounds=2, iterations=1, warmup_rounds=0)
+
+
+@pytest.mark.large
+def test_large_wide(benchmark):
+    da = make_data(730, n_cols=256, n_slices=1)
+    benchmark.pedantic(run_aggregate, args=(da, FULL_CONFIG), **LARGE_OPTS)
+
+
+@pytest.mark.large
+def test_large_scenarios(benchmark):
+    da = make_data(365, n_cols=64, n_slices=8)
+    benchmark.pedantic(run_aggregate, args=(da, FULL_CONFIG), **LARGE_OPTS)

{tsam_xarray-0.6.4 → tsam_xarray-0.6.6}/docs/data-model.md

@@ -32,7 +32,7 @@ graph LR
     D --- F1[".cluster_representatives<br/><i>cluster, timestep, *cluster_dims, *slice_dims</i>"]
     D --- F2[".reconstructed<br/><i>same shape as input</i>"]
     D --- F3[".cluster_assignments<br/><i>period, *slice_dims</i>"]
-    D --- F4[".cluster_weights<br/><i>cluster, *slice_dims</i>"]
+    D --- F4[".cluster_counts<br/><i>cluster, *slice_dims</i>"]
     D --- F5[".segment_durations<br/><i>cluster, timestep, *slice_dims | None</i>"]
 
     Meta --- A[".accuracy<br/><b>→ AccuracyMetrics</b>"]

{tsam_xarray-0.6.4 → tsam_xarray-0.6.6}/docs/examples/getting-started.ipynb

@@ -107,8 +107,8 @@
    "source": [
     "print(f\"Clusters: {result.n_clusters}\")\n",
     "print(f\"Timesteps per period: {result.n_timesteps_per_period}\")\n",
-    "print(\"Cluster weights (days each represents):\")\n",
-    "result.cluster_weights.to_dataframe(\"weight\")"
+    "print(\"Cluster counts (days each represents):\")\n",
+    "result.cluster_counts.to_dataframe(\"count\")"
    ]
   },
   {