Why this package?
Energy system models, capacity expansion studies, and other time-series-heavy applications often need to reduce a full year of hourly data to a small set of representative periods — days, weeks, or months — without losing what matters.
The literature offers many methods (k-means, k-medoids, MILP-based selection, genetic algorithms, etc.), but the landscape is dense and tangled: each method bundles multiple decisions — how to represent data, what to optimize, how to search — into a single procedure, making it hard to see which choices matter, compare approaches on equal footing, or adapt a method to your specific problem.
A Unified Framework
Decomposes any time-series aggregation method into five interchangeable components. Every established methodology is a specific instantiation of this structure. The framework provides a common language for describing, comparing, and assembling methods.
Read the framework paperA Modular Python Package
Implements this framework as a library of composable, protocol-based modules. You pick one implementation per component, wire them together, and run. Adding a new algorithm or score metric means implementing a single protocol — everything else stays the same.
Browse all modulesThe Five Components
Any time-series aggregation method decomposes into these five pillars. Mix and match implementations to build the exact workflow you need.
Feature Space
How raw time-series are transformed into comparable representations
Objective
How candidate selections are scored for quality
Selection Space
What is being selected (historical subsets, synthetic archetypes, etc.)
Representation Model
How selected periods represent the full dataset
Search Algorithm
The engine that finds optimal selections
How It Works
Define your problem, pick one implementation per component, wire them into a workflow, and run. The result contains the selected periods, their weights, and all objective scores.
Implemented Modules
A growing library of composable components. Each implements a protocol — swap any module without touching the rest of your pipeline.
Feature Engineering
StandardStatsFeatureEngineer
PCAFeatureEngineer
FeaturePipeline
Transform raw time-series into statistical summaries, PCA projections, or chained multi-step feature pipelines.
Score Components
WassersteinFidelity
CorrelationFidelity
DurationCurveFidelity
DiversityReward
...
Evaluate candidate selections on distribution similarity, correlation preservation, diversity, and more. 10 components and counting.
Combination Generators
ExhaustiveCombiGen
GroupQuotaCombiGen
HierarchicalCombiGen
Define the selection space: enumerate all k-of-n combinations, enforce group quotas (e.g. one per season), or compose hierarchically.
Representation Models
UniformRepresentationModel
KMedoidsClustersizeRepresentation
BlendedRepresentationModel
Assign responsibility weights: equal 1/k, cluster-membership proportional, or soft blended assignment where every period contributes.
Search Algorithms
ObjectiveDrivenCombinatorialSearchAlgorithm
WeightedSumPolicy
ParetoMaxMinStrategy
Generate-and-test search with pluggable selection policies: weighted sum, Pareto front, or custom strategies.
Explore hands-on examples
Worked examples showcasing different configurations — from a minimal "hello world" to multi-objective optimization and hierarchical seasonal workflows.
Browse all examplesEx 1: Getting Started
Minimal end-to-end workflow — single objective, uniform weights, 4 representative months.
Ex 2: Feature Space Exploration
PCA features, Pareto selection, cluster-size weights, and the full suite of diagnostics.
Ex 3: Hierarchical Selection
Seasonal constraints via hierarchical combination generation — one month per season.
Ex 4: Representation Models
Same selection, three weight models compared: uniform, cluster-size, and blended.
Ex 5: Multi-Objective
Four objectives, Pareto vs. weighted-sum policies — exploring the trade-off frontier.
Part of the MESQUAL Family
energy-repset is a standalone library within the MESQUAL family — a collection of open-source tools for energy system analysis, scenario comparison, and modeling support.
mesqual
The Pythonic framework for energy scenario comparison and quantitative analysis.
mesqual-ai
Coming soonAn extension for AI context, agents and MCPs within the MESQUAL framework.
captain-arro
Create beautiful, customizable, animated SVG arrows for web interfaces with just a few lines of code.