Releases | Open Sustainable Technology

tsam - v.3.1.0

Added preserve_n_clusters option to ExtremeConfig. When set to True, extreme periods
count toward n_clusters instead of being added on top, giving exact control over the final
number of representative periods. Default behavior is unchanged.
Removed matplotlib dependency; all plotting and notebooks now use plotly
The tdqm test pipeline has been reduced due to the number of versions and the maturity of the library.
Renamed the examples for more clarity

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina about 2 months ago

Summary

New Features
- Redesigned API with functional aggregate() function and structured configuration objects (ClusterConfig, SegmentConfig, ExtremeConfig)
- New AggregationResult object providing:
  - cluster_representatives, cluster_weights, cluster_assignments properties
  - reconstruct() method for time series reconstruction
  - accuracy metrics (RMSE, MAE, etc.)
  - Built-in plotting via result.plot.*
- ClusteringResult for clustering transfer and persistence:
  - Save/load clustering with to_json() / from_json()
  - Apply saved clustering to new data with apply()
  - All clustering state bundled in one immutable object
- Interactive Plotly-based visualizations (tsam.plot.*): heatmaps, duration curves, time slices, comparisons
- New cluster_assignments() plot to visualize which cluster each period belongs to
- Hyperparameter tuning with find_optimal_combination():
  - Sparse Pareto frontier exploration (faster than exhaustive search)
  - Parallel execution with file-based data passing (memory safe)
- Segment transfer: ability to reuse segment configurations across aggregations
Documentation
- Comprehensive getting started guide with new API examples
- 10 example notebooks moved to docs/source/examples_notebooks/ for Sphinx integration
- New notebooks: tuning_example.ipynb, aggregation_method_showcase.ipynb
Chores
- Version bump to 3.0.0
- Made Matplotlib optional; added Plotly (>=5.0.0) as primary plotting backend
- Reorganized test fixtures to test/data/
- Added GitHub issue templates (bug report, feature request)
Breaking Changes
- The new API is additive - existing TimeSeriesAggregation class remains unchanged
- Notebooks moved from examples/ to docs/source/examples_notebooks/

New Modules

Module	Purpose
`src/tsam/api.py`	Functional `aggregate()` entry point
`src/tsam/config.py`	`ClusterConfig`, `SegmentConfig`, `ExtremeConfig`, `ClusteringResult` dataclasses
`src/tsam/result.py`	`AggregationResult` with reconstruction & metrics
`src/tsam/plot.py`	Plotly-based visualization functions
`src/tsam/tuning.py`	`find_optimal_combination()` with parallelization

New vs Old API Comparison

# Old API
aggregation = tsam.TimeSeriesAggregation(
    raw, noTypicalPeriods=8, hoursPerPeriod=24,
    clusterMethod='hierarchical',
    extremePeriodMethod='new_cluster',
    addPeakMin=['T'], addPeakMax=['Load']
)
aggregation.createTypicalPeriods()
typical = aggregation.typicalPeriods

# New API
result = tsam.aggregate(
    raw, n_clusters=8, period_duration=24,  # or '24h', '1d'
    cluster=ClusterConfig(method="hierarchical"),
    extremes=ExtremeConfig(
        method="new_cluster",
        min_value=["T"],
        max_value=["Load"]
    )
)
typical = result.cluster_representatives

Clustering Transfer

# Run aggregation on subset of data
result = tsam.aggregate(df_wind, n_clusters=8)

# Save clustering for later use
result.clustering.to_json("clustering.json")

# Load and apply to different data - all parameters come from the file
clustering = ClusteringResult.from_json("clustering.json")
result2 = clustering.apply(df_all)

# Visualize cluster assignments
result.plot.cluster_assignments()

API Naming Conventions

v2 → v3 Parameter Mapping

Old (v2)	New (v3)	Reason
`noTypicalPeriods`	`n_clusters`	Clearer terminology: we create clusters, each with one representative.
`hoursPerPeriod`	`period_duration`	Accepts int/float (hours) or pandas Timedelta strings (`'24h'`, `'1d'`).
`resolution`	`timestep_duration`	More explicit about what "resolution" refers to.
`typicalPeriods`	`cluster_representatives`	Renamed to reflect that each cluster has one representative period.
`clusterPeriodNoOccur`	`cluster_weights`	Clearer: weights indicate how often each cluster occurs.
`clusterOrder`	`cluster_assignments`	"Assignments" better describes mapping periods to clusters.

Naming Patterns

Pattern	Usage	Examples
`n_*`	Count parameters	`n_clusters`, `n_segments`, `n_timesteps_per_period`
`*_assignments`	Mapping arrays (which cluster/segment each item belongs to)	`cluster_assignments`, `segment_assignments`
`*_centers`	Representative indices	`cluster_centers`
`*_durations`	Duration/length arrays	`segment_durations`
`*_duration`	Time length parameters (accept int/float hours or pandas strings)	`period_duration`, `timestep_duration`
`find_*`	Search/optimization functions	`find_optimal_combination`, `find_pareto_front`
`*Config`	Configuration dataclasses	`ClusterConfig`, `SegmentConfig`, `ExtremeConfig`

Glossary

Note: The new API uses "cluster representative" instead of "typical period" to better reflect that each cluster is represented by one period.

Concept	Description
Period	A fixed-length time window (e.g., 24 hours = 1 day). The original time series is divided into periods for clustering.
Cluster	A group of similar periods. Each cluster has one representative period (`cluster_representatives`).
Segment	A subdivision within a period. Consecutive timesteps are grouped into segments to reduce temporal resolution.
Timestep	A single time point within a period (e.g., one hour in a 24-hour period).
Duration Curve	A sorted representation of values within a period (highest to lowest). Used with `use_duration_curves=True` or `representation="distribution"`.

Motivation and Context

The tsam API is quite complex and doesn't follow modern Python best practices (naming conventions like lower_case_with_underscores). The large number of parameters makes it hard to discover related options. I grouped parameters into small dataclasses (ClusterConfig, SegmentConfig, ExtremeConfig) for better discoverability and IDE autocomplete.

The same applies to results - I found it unintuitive to retrieve results and relevant metrics. The new AggregationResult object provides a clean interface with properties and methods.

I added Plotly-based plotting methods for quick interactive inspection.

The hyperparameter tuning was useful but unnecessarily slow. I added:

Sparse Pareto frontier search (explores promising configurations first)
Parallel execution with file-based data passing (avoids pickling large DataFrames)

I also was missing the option to predefine segments and transfer clustering results between datasets. The new ClusteringResult class with to_json()/from_json() and apply() methods addresses this.

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina about 2 months ago

tsam - v.2.3.9

Improve time series aggregation speed with segmentation, mentioned in issue https://github.com/FZJ-IEK3-VSA/tsam/issues/96 by @phil-fzj
Fix issue #99 reported by @adbuerger

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina 9 months ago

tsam - Improve time series aggregation speed with segmentation

Improve time series aggregation speed with segmentation, mentioned in issue #96 by @phil-fzj

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina 9 months ago

tsam - 2.3.7

Added Python 3.13 to the action matrix
Updated the Python requirement in the setup.py to incorporate 3.13
Updated ubuntu-20.4 to ubuntu-22.04 in workflow due to deprecation
Removed macos-12 due to slow runs
Solved issue invalid escape sequence '(' https://github.com/FZJ-IEK3-VSA/tsam/issues/90

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina 10 months ago

tsam - 2.3.6

I have transitioned from setup.py to pyproject.toml . https://github.com/FZJ-IEK3-VSA/tsam/issues/89
Changed the layout from flat to source. See here for advantages
Updated the installation description in the README.md
Fixed a couple of deprecation and future warnings, reported in https://github.com/FZJ-IEK3-VSA/tsam/issues/91

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina over 1 year ago

tsam - 2.3.5

Replaces 2.3.4 due to differences between github and pypi

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina over 1 year ago

tsam - 2.3.4

Extend the reporting if time series tolerances are exceeded and add the option to silence them with a tolerance value.
set default tolerance value to 1e-13

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina over 1 year ago

tsam - Version 2.3.3

Drop support for Python<3.9 and fix some depreciation warnings.

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur over 1 year ago

tsam - Version 2.3.2

The pandas version is limited to be less than 3.0 as, some commands will be deprecated in the requirements. a new release in the setup, 2.3.2, and warning silence. Deprecation warnings are silenced.

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina over 1 year ago

tsam - Version 2.3.1

accelerate rescale cluster periods
update documentation and include autodeployment

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur over 2 years ago

tsam - Version 2.3.0

Fix depreciated pandas functions
fix sum for distribution representation incl. min max vals - now mean value of representation equals mean value of original time series
add possibility to define segment representation
extend the default example
switch from travis to github workflow for ci

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur over 2 years ago

tsam - Version 2.2.2

Fix Hypertuning class
Set high as new default MILP solver
Rework README

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur over 3 years ago

tsam - Version 2.1.0

Following functionality was added:

a hyperparameter tuning meta class which is able to identify the optimal combination of typical periods and segments for a given time series dataset

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur over 3 years ago

tsam - Version 2.0.1

tsam release (2.0.1) includes the following new functionalities:

Changed dependency of scikit-learn to make tsam conda-forge runnable.

Energy Systems - Energy System Modeling Frameworks - Python
Published by OfficialCodexplosive almost 4 years ago

tsam - Version 2.0.0

In tsam’s latest release (2.0.0) the following functionalities were included:

A new comprehensive structure that allows for free cross-combination of clustering algorithms and cluster representations, e.g. centroids or medoids.
A novel cluster representation method that precisely replicates the original time series value distribution in the aggregated time series based on “Hoffmann, Kotzur and Stolten (2021): The Pareto-Optimal Temporal Aggregation of Energy System Models (https://arxiv.org/abs/2111.12072)”
Maxoids as representation algorithm which represents time series by outliers only based on “Sifa and Bauckhage (2017): Online k-Maxoids clustering”
K-medoids contiguity: An algorithm based on “Oehrlein and Hauner (2017): A cutting-plane method for adjacency-constrained spatial aggregation” that accounts for contiguity constraints to e.g. cluster only time series in neighboring regions

Energy Systems - Energy System Modeling Frameworks - Python
Published by OfficialCodexplosive over 4 years ago

tsam - Version 1.1.2

This tsam release (1.1.2) includes the following new functionalities

Added first version of the k-medoid contiguity algorithm

Energy Systems - Energy System Modeling Frameworks - Python
Published by OfficialCodexplosive over 4 years ago

tsam - Version 1.1.1

This tsam release (1.1.1) includes

Significantly increased test coverage
Separation between clustering and representation, i.e. for clustering algorithms like Ward’s hierarchical clustering algorithm the representation by medoids or centroids can now freely be chosen.

Energy Systems - Energy System Modeling Frameworks - Python
Published by OfficialCodexplosive over 4 years ago

tsam - Include build testing

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur about 7 years ago

tsam - First pypi release

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur almost 8 years ago

tsam - Clarify aggregation output structure

add second example which illustrates the output of the aggregation
add the second publication about storage modeling in readme
modify usable attributes to properties

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur almost 8 years ago

tsam -

Improvement of extreme periods
Move to MIT license

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur about 8 years ago

tsam - v0.9.3

Patch to first public version with minor bug fixes

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur over 8 years ago

tsam -

First public release

Features:

different aggregation methods implemented (averaging, k-mean, exact k-medoid, hierarchical), which are based on scikit-learn or pyomo
flexible integration of extreme periods as own cluster centers
weighting for the case of multidimensional time-series to represent their relevance

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur almost 9 years ago

tsam -

First public release of tsam

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur almost 9 years ago

Recent Releases of tsam

tsam - v.3.1.0

tsam - v3.0.0

Summary

New Modules

New vs Old API Comparison

Clustering Transfer

API Naming Conventions

v2 → v3 Parameter Mapping

Naming Patterns

Glossary

Motivation and Context

tsam - v.2.3.9

tsam - Improve time series aggregation speed with segmentation

tsam - 2.3.7

tsam - 2.3.6

tsam - 2.3.5

tsam - 2.3.4

tsam - Version 2.3.3

tsam - Version 2.3.2

tsam - Version 2.3.1

tsam - Version 2.3.0

tsam - Version 2.2.2

tsam - Version 2.1.0

tsam - Version 2.0.1

tsam - Version 2.0.0

tsam - Version 1.1.2

tsam - Version 1.1.1

tsam - Include build testing

tsam - First pypi release

tsam - Clarify aggregation output structure

tsam -

tsam - v0.9.3

tsam -

Features:

tsam -