From 76763f8d34159cb110fb8f5871bb118ede9c5bd9 Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Thu, 27 Aug 2026 18:19:54 +0100 Subject: [PATCH 1/2] First draft for user guide on Time in MUSE --- docs/SUMMARY.md | 1 + docs/glossary.md | 4 +- docs/model/README.md | 2 + docs/model/time.md | 90 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 95 insertions(+), 2 deletions(-) create mode 100644 docs/model/time.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 45e724747..f091cb82a 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -10,6 +10,7 @@ - [Input Files](file_formats/input_files.md) - [Output Files](file_formats/output_files.md) - [Model Description](model/README.md) + - [Time](model/time.md) - [Units and Dimensions](model/units_and_dimensions.md) - [Dispatch Optimisation](model/dispatch_optimisation.md) - [Investment Appraisal](model/investment.md) diff --git a/docs/glossary.md b/docs/glossary.md index b93e52a1e..3c9e9d470 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -194,8 +194,8 @@ which trade and other regional interactions are modelled. for a particular *Commodity*, *Region*, and *Year*. It determines which *Candidate Assets* are available during investment appraisal. -**Season:** A subdivision of a *Year* that groups related *Time Slices*. For example, summer, -winter, or other. +**Season:** A user-defined subdivision of a representative *Year* that groups related *Time Slices*. +For example, summer, winter or other. **Sector:** Models are often broken down into sectors, each of which is associated with specific *Service Demands* or specific *Commodity* production. For example, the residential sector, the power diff --git a/docs/model/README.md b/docs/model/README.md index 01dcf8c9c..2a68b9f08 100644 --- a/docs/model/README.md +++ b/docs/model/README.md @@ -48,6 +48,8 @@ At a high level, the user defines: rules. Portions of demand for each commodity must be assigned to an agent, and the sum of these portions must be one. +The temporal arrangements described above are explained in more detail in [Time](time.md). + ## Framework Overview The model operates sequentially across a series of milestone years (MSYs). For the base year, diff --git a/docs/model/time.md b/docs/model/time.md new file mode 100644 index 000000000..91faa78ed --- /dev/null +++ b/docs/model/time.md @@ -0,0 +1,90 @@ +# Time + +MUSE2 represents time in two related ways: over the long-term model horizon and within each +milestone year. + +```text +Time horizon +└── Milestone years + └── Seasons + └── Time slices +``` + +Milestone years describe when the model makes long-term investment decisions and records results. +Time slices describe how operation is represented within each of those years. + +## Time horizon and milestone years + +The time horizon is the overall period covered by a model run. It is represented by the ordered list +of `milestone_years` in `model.toml`, for example: + +```toml +milestone_years = [2020, 2030, 2040] +``` + +Milestone years must be positive, sorted and unique. MUSE2 evaluates the system at each milestone +year. The first milestone year is the base year: existing assets and base-year demand describe the +system being calibrated. Subsequent milestone years are investment and reporting points, at which +assets, demand, dispatch and prices are evaluated. + +Milestone years need not cover every calendar year in the horizon. Use additional milestone years +when technology, demand or policy changes need to be represented at a finer long-term resolution. + +## Seasons and time slices + +Each milestone year is divided into user-defined seasons and times of day. A *time slice* combines +one season and one time of day, and is written as `season.time_of_day`, for example `winter.day` or +`summer.peak`. + +The names are labels supplied by the modeller. MUSE2 does not attach a built-in meaning to names +such as `winter`, `day` or `peak`. + +Time slices are defined in `time_slices.csv`, for example: + +```csv +season,time_of_day,fraction +winter,night,0.25 +winter,day,0.25 +summer,night,0.25 +summer,day,0.25 +``` + +The `fraction` is the share of the year represented by a time slice. Every fraction must be +positive, and the fractions for all slices must sum to one. If `time_slices.csv` is omitted, MUSE2 +uses one `all-year.all-day` slice covering the whole year. + +The input-file reference contains the complete [time-slice format](../file_formats/input_files.md#time-slices). + +## Time-slice selections + +A time-slice selection is the period over which MUSE2 applies a balance or limit. It can cover the +whole year (`annual`), a season (`winter`), or one time slice (`winter.day`). The granularity of a +selection comes from the thing it applies to: commodity balances use the commodity's +`time_slice_level`, while explicitly provided constraints use the level of their `time_slice`. +These two granularities are independent. + +- **SED balance:** Supply and demand for an SED commodity are balanced at the commodity's + `time_slice_level`. `annual` creates one balance for the whole year, `season` creates one balance + per season, and `daynight` creates one balance per time slice. +- **SVD demand:** Annual service demand is distributed using `demand_slicing.csv`. Demand slicing + data should be provided at the granularity of the SVD commodity's `time_slice_level`. +- **Commodity constraints:** A production or consumption limit uses the level of its own + `time_slice` entry, which may differ from the commodity's balance level. For example, an `annual` + commodity can have a production limit that applies only to `winter`. +- **Availability constraints:** A process activity limit uses the level of its own `time_slice` + entry. It can apply to one time slice, a season, or the whole year, independently of the balance + level of the commodities produced or consumed by the process. + +## Choosing a resolution + +- **Define the time slices for the most detailed requirement:** The shared time-slice definition + must support the most detailed commodity balance or operational constraint in the model. +- **Choose each commodity's balance level separately:** Set `time_slice_level` to `annual`, `season`, + or `daynight` according to the resolution needed for that commodity. Demand-slicing data should + use the same granularity. +- **Keep explicit constraints in mind:** Availability limits and commodity constraints specify their + own time-slice selection, which can be more detailed than the balance level of the commodities + involved. + +More time slices provide more detail but increase the size of the optimisation problem, so use only +the temporal resolution needed by the model. From 0c42ecbd8a82a7d855d74e48733da957f62a2cfa Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Thu, 27 Aug 2026 18:21:46 +0100 Subject: [PATCH 2/2] Revert glossary change --- docs/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index 3c9e9d470..b93e52a1e 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -194,8 +194,8 @@ which trade and other regional interactions are modelled. for a particular *Commodity*, *Region*, and *Year*. It determines which *Candidate Assets* are available during investment appraisal. -**Season:** A user-defined subdivision of a representative *Year* that groups related *Time Slices*. -For example, summer, winter or other. +**Season:** A subdivision of a *Year* that groups related *Time Slices*. For example, summer, +winter, or other. **Sector:** Models are often broken down into sectors, each of which is associated with specific *Service Demands* or specific *Commodity* production. For example, the residential sector, the power