v1.0.0

Version 1.0.0

Listed in the following are changes since the last beta-release v0.15.1. A full list of all features of ReSiE as of v1.0.0 can be found in the documentation.

Package renaming

• The julia package has been renamed to ResieQuasi. This name was chosen to avoid naming conflicts with existing packages in the General registry. The preferred name and spelling is ReSiE, as part of the QuaSi project. You can find an explanation of these two names in the online documentation.
  • If the package name is used extensively in code, a handy trick is to use import ResieQuasi as Resie

Grid connections

• The two component models GridInput and GridOutput have been renamed to GridSupply and GridSink. These names were chosen to be in line with the names of other supply/sink components and because "input" and "output" where deemed confusing as they relate to the whole energy system, not the invidiual component. The models work exactly the same as before, only the name has changed.

Minor changes

• Updates to the scenario reference files
• Set compat entries in file Project.toml. This is mostly a requirement for the General registry, but also helps to specificy a known working set of dependencies, which should reduce a source of errors caused by new versions of dependencies.

v0.15.0

Version 0.15.0

Major feature: Parameter studies, optimisation and sensitivity analysis

• Add a parameter_study section for repeatedly simulating an energy system with different input parameters

  • Define variable parameters using optimisation bounds, starting values, explicit values or generated ranges
  • Run Cartesian-product, zipped or random parameter variations
  • Define objectives from simulation, economic and emissions results and combine them using sum, weighted linear functions or separate multi-objective outputs

• Add single- and multi-objective optimisation using algorithms from Optim, BlackBoxOptim, Metaheuristics, NLopt and NOMAD

  • Add run, time and tolerance limits, objective-specific minimisation or maximisation and an optional refinement stage
  • Normalise parameters internally while retaining physical values in project files and outputs

• Add global and local sensitivity analyses

  • Calculate first- and total-order Sobol indices using polynomial chaos expansion
  • Evaluate one-at-a-time local parameter changes around starting values or the best available result
  • Reuse matching results from preceding parameter-study calculations

• Add threaded execution, interruption handling and dedicated parameter-study logging

  • Preserve available results when studies are interrupted with Ctrl+C

• Add CSV and interactive HTML outputs

  • Include complete result tables, continuous CSV writing, optimisation and parameter-relation plots, interactive 3D plots and global- and local-sensitivity outputs

• Add disable_all_simulation_outputs, enabled by default, to suppress regular outputs from individual parameter-study simulations

• Add parameter-study examples and scenarios for multi-family-house parameter variation, component-size optimisation and sensitivity analysis

Breaking changes

• Rename general output-path parameters for consistency

  • csv_output_file → csv_output_file_path
  • output_plot_file → output_plot_file_path
  • sankey_plot_file → sankey_plot_file_path

• Rename CSV-related parameters to consistently use lowercase csv

  • write_summary_CSV → write_summary_csv
  • output_economic_CSV → output_economic_csv
  • economic_CSV_file_path → economic_csv_file_path
  • output_emissions_CSV → output_emissions_csv
  • emissions_CSV_file_path → emissions_csv_file_path

• Change fixed output precision to use significant digits instead of decimal digits

  • Update scenario reference outputs to reflect the changed rounding behaviour

Minor changes / fixes

• Add multi-family-house and district examples and scenarios with economic and GHG emissions calculations
• Add summary CSV generation with automatic aggregation of means, sums, minima and maxima
• Add capex_specific_scale and the economic result annuity_opex_including_energies
• Improve validation and error messages for invalid profile values, unknown component types, empty interfaces and missing scenarios
• Extend the storage_driven control module with control_mode for storages used as sources
• Fix heat-pump temperature calculations, secondary-interface behaviour, slice splitting and storage transfer handling
• Fix transformer order-of-operations handling for active part-load operation on middle busses
• Fix an incorrect conditional in GeothermalHeatCollector
• Fix profile handling, geothermal plotting, file-only plotting and logger shutdown
• Clarify heat-pump COP warnings, installation instructions and file-path formatting
• Add and update missing scenario reference outputs

Internal changes

• Add BlackBoxOptim, Metaheuristics, NLopt, NOMAD and PolyChaos
• Separate parameter-study execution and output generation into dedicated modules
• Rename file_output.jl to simulation_output.jl and generalise simulation-result extraction
• Add the GlobalInfo log level for messages applying to complete parameter studies
• Cache reusable profiles and the order of operations across repeated simulation runs
• Improve scenario tooling and update examples, inputs and reference files

v0.14.0

Major feature: Costs and emissions

• Add optional economic and GHG emissions calculations
  • Includes component-specific investment costs, operating costs, energy prices, subsidies, embodied emissions, emission factors, emissions credits and unmet-energy costs
  • Add CSV and plot outputs for economic and GHG emissions results
  • Add different repetition methods of price and emission profiles using the parameter repeat_method

Breaking changes

• Rework IO settings for CSV output, output plots and Sankey plots by splitting output mode and custom output specification
  • This changes the project file syntax for custom output definitions. Please check the documentation for how the new format works.
  • Update default Sankey colours and improve handling of incomplete custom colour specifications. Unknown media are now assigned random colours, but these colours are consistent between runs.
• Change handling of unmet demands and surplus supplies so they are assigned to sinks and sources and no longer to busses
  • Improve handling of unmet energies in single and connected busses
  • Change output of balance warnings to a new format: Balance warnings are now separated into interface balance warnings and component balance errors; proxy busses no longer create duplicate balance warnings
  • Update Sankey plotting to display unmet energies more reliably and consistently
• Remove legacy component type GridConnection
  • Please use GridInput and GridOutput instead, which function the same, except they do not require setting the parameter is_source.

Minor changes / fixes

• Fix multiple issues in profile repetition, profile trimming, output paths, line plot ordering, optional parameter validation and unit descriptions
• Add IO setting fixed_output_precision to make CSV, plot, Sankey, economic and emissions outputs perfectly reproducible. This is mostly used for testing.

Internal changes

• Refactor simulation parameters, IO settings, economic parameters, emissions parameters, control parameters and control modules to use SSOT parameter definitions
• Improve scenario tooling and update scenario reference files
  • The scenario command compare_ooo is replaced by compare, which compares all relevant output files. This includes automatically ignoring expected differences in execution time and timestamps.
  • The new compare tool can be used to quickly check all scenarios for any difference at all.

v0.13.0

Key Features

General simulation model

• Renamed the system functions bounded_source and bounded_sink to flexible_source and flexible_sink
• Clarify some terms in the code, doc blocks and comments in regard to the use of "order of operations" and "step"
• Implemented control callbacks that can modifiy the order of operations for a timestep as well as reordering the priorities and energy flow matrix on busses (as both are necessary to ensure correct calculation)
• Changed the option to specifiy a custom order of operations in the project file. To input a custom order via field order_of_operation in the project file, the UAC must now be separated from the operation by a : instead of an empty space in order to allow UACs to contain empty spaces
• Added the option to start the output of simulation results later than the beginning of the simulation, which is for example useful to pre-heat large storage components that would otherwise start in a physically unrealistic state. To use this feature, set the simulation parameter start_output to a DateTime after the simulation start. All timesteps prio to this second start date are calculated as normal, but will not create any output.

Control modules

• Added control module economic_control making use of the new callbacks to implement an operational strategy assigning different priorities and allowed flows depending on a given price profile and a threshold value
• Removed control module economical_discharge as it was only used for examplatory purposes and is no longer required. Please note that this requires you to remove this control module from your project files if you have used it before.

General components

• Renamed BoundedSupply to FlexibleSupply and BoundedSink to FlexibleSink. Please note that this requires you change the names of the components in your project files.

Geothermal collector

• Model improvements for the geothermal collector component: Changed explicit Euler formulation to implicit Euler for the calculation of heat transfer in the soil around the geothermal collector due to massive computational speed improvements. The results are very close to the former implementation.

New component: UTIR

• Added component UTIR as a unified implementation of electric transformers, inverters and rectifiers (UTIR).

Bus component

• The energy flow matrix of a bus can now be used to specify a custom order of each input-output connection using consecutive numbers starting from 1 in the energy flow matrix (or 0 for denied connections). This only works for single busses that are not interconnected to other busses.

Profiles

• Added the possibility to repeat profiles using the parameter "repeat_profile" in the profile header
• Add optional simulation parameter force_profiles_to_repeat to force profiles to repeat, even if repeat_profile is not set in the profile header

v0.12.0

Key Features

Extended Outputs
Energy and temperature flows between components connected via busses can now be included in CSV and plot outputs. This makes it possible to directly analyse inter-component exchanges, not just component-level results. Options are available to export nothing, all excluding flows, all including flows, or a custom set (with preserved order).

New Component Models

• Solar thermal collector (STC) for solar heat supply, including a solar radiation model that computes sun position and irradiance in a plane, with improved interpolation conserving energy and correctly handling sunrise and sunset.
• Seasonal thermal energy storage (STES) with detailed stratification and loss behaviour.

Heat Pump Enhancements

• New model_type with three modes:
  • simplified (constant efficiency),
  • inverter (optimised for partial load operation),
  • on-off (captures cycling losses).
• Added standby electricity consumption and a minimum usage fraction to avoid unrealistic operation at very low loads.
• Bypass behaviour now respects the actually demanded temperature.

Control Modules

• negotiate_temperature: dynamically sets operating temperatures between components with flexible temperatues.
• limit_cooling_input_temperature: restricts input temperature for electrolysers with STES.
• check_src_to_snk and forbid_src_to_snk: new mechanisms to explicitly allow or block energy flows between specific source–sink pairs.
• Control module loading refactored so new modules can be added without modifying core code.

Temperature Handling Rework

• Minimum and maximum temperatures are now tracked in the MaxEnergy struct rather than interfaces.
• Bus distribution and balancing functions revised to handle temperature-dependent flows more accurately.
• Added a recalculation method for energy limits when conditions change.
• Control-step order adjusted so components like STES and STC can determine temperatures correctly during control.
• Electrolyser extended to properly handle temperature constraints of usable available capacities (UACs).

Other Changes

• Output references: output_refs can now be dictionaries for multi-output components (ensures unique connections); list syntax still works but raises warnings when ambiguous.
• Input syntax: separator for specific input/output channels changed to :, enabling spaces in medium names.
• Losses/Gains: outputs now report losses as negative and gains as positive.
• Order of operation: improved to cover circle-transformers (input and output on the same bus) and busses with minimum PLR set.
• CLI: more graceful handling of Ctrl+c.
• Profiles: better error reporting (including line numbers), robustness improvements, and bugfixes.
• Scenarios: new stc_2_demands and p2h_stes_stc; updated multisector district example with STES.
• Simulation parameters: new parameter epsilon added.
• Storages: made more robust against different process/load orders; redundant functions removed.
• General: all tests and scenarios adapted to the new syntax; documentation updated; multiple bugfixes across components.

v0.11.0

Key Features

New CLI

The CLI of ReSiE, and how simulations are performed with it, has been restructured. Instead of a single call to the CLI script, that runs the simulation and then returns to the shell, it now puts the user into an interactive CLI that keeps prompting for commands until exited. This has the advantage that performing multiple runs without changing the code results in a significant performance boost for runs after the first one, as the code does not have be compiled again and is reused.

The interactive part can be circumvented by adding the command and associated arguments to the call starting the CLI. An optional argument --exit-after-run will exit the CLI after the simulation is done. Additional output during a simulation has also been added to make it clearer in what state the simulation currently is in.

Note: This is a breaking change, as the previous command to run a simulation, e.g. julia --project=. src/resie-cli.jl examples/simple_heat_pump.json, no longer works. With the new CLI a single simulation run with no interactive part now looks like this: julia --project=. src/resie-cli.jl run --exit-after-run examples/simple_heat_pump.json. Please update any scripts or automated processes to reflect these changes.

More detailed component models

The models for energy system components of several types have been extended in more detail, as described in the documentation.

Heat Pump

The model has been extended to include several effects that affect how the heat pump operates:

• Calculation of the COP as a customisable function of the source and sink temperatures
• Customisable temperature-dependent minimum/maximum power functions
• Part load ratio (PLR) dependent efficiency as customisable function modifying the COP depending on the PLR
• Optimisation of the PLR if the heat pump is not working under full load. This is a useful feature for inverter heat pumps, that typically work most efficiently at a PLR of less than 100%. Note: this optimisation could be improved and does not always calculate the true optimum. There also known problems where activating this feature will lead to energy balances not quite working out. Hopefully this will be fixed in future updates.
• Handling multiple combinations of input and output (so-called "slices") in each timestep. For example a heat pump can supply both room heating and domestic hot water (DHW) demands at the same time, calculating each with a different COP and power
• Losses of power and heat input that are not included in the heat output as these represent true losses to the environment, as compared to losses of efficiency, which are included in the COP function.
• More output channels to make it easier to understand how the heat pump works

Buffer tank / STTES

Three different models have been made available, each with and without losses:

• ideally stratified: Supplies energy consistently at "high_temperature". Losses reduce energy but do not affect temperature.
• ideally mixed: Fully mixed model, with temperature output depending on the current load. Losses decrease both energy and temperature.
• balanced: Combines both models. A full tank behaves as ideally stratified, transitioning to ideally mixed as the tank empties.

Geothermal collector

Finalisation of the model, successfully validated agains TRNSYS and DELPHIN:

• Revision of the entire model, including bug fixed and improvements
• Add automatic generation of the numerical grid
• Add time-shiftable plot of the temperature distribution (requires GLMakie package, activate with auxiliary_plots)
• Add scenario using the geothermal collector

Profiles and interpolation/segmentation

Especially for weather profiles and other externally given data, new functionality has been implemented for profiles:

• Add the possibility to output the weather data from EPW and dat-files to the lineplot and CSV output
• Add two more interpolation methods for segmentation of data: "stepwise", "linear_classic", "linear_time_preserving", "linear_solar_radiation"
• The time zone can now be specified in the simulation_parameters to overwrite the time zone provided by the weather file

Other changes

• New control module "temperature_sorting", which enables sorting the inputs or outputs of a heat pump by temperature. This can be used to override a static order, derived from priorities on a bus, with an order that chooses the highest or lowest temperature first.
• Add workaround for storage_driven control module not recognizing a full storage if losses are activated. This can be done cleaner in the future.
• Add the possibility to create optional figures at the end of the simulation period
• Update installation instructions for ReSiE
• Bugfix for order of operation not determining middle busses with grids correctly
• Bugfix in grid (sink) setting wrong min/max temperature in control

v0.10.0

Key Features:

• Datetime Indexes for Profiles and Simulations: Introduced datetime handling for profiles and internal processes. Simulation start and end times are now datetime-based, and time steps can be provided in seconds, minutes, or hours. Profiles must cover the full simulation period and can be defined with various formats (start date & timestep, start date & timestamp or custom date format). Multi-year weather data is now supported. Added extensive/intensive data types in profiles, replacing "is_power." Improved segmentation and aggregation algorithms with support for linear or stepwise interpolation.

• Temperature Layer Integration: Temperature layers are now handled in input/output interfaces for correct calculation of COP. Enhanced the heat pump component to manage temperature layers, and implemented a method to handle unknown energies during the potential step to avoid balance errors.

Additional Improvements:

• Improved Time Definition: Data is now defined as the mean/sum of the following time step. Weather data is converted accordingly were required. Internally, local standard time is used. Profiles with daylight saving time (DST) are converted. Leap days are omitted in both input and output.
• Coordinate Support: Added input for coordinates and automatic conversion for coordinates provided in weather data files.
• New Parameters: Introduced "time_shift_seconds" to manually shift profile data and "use_linear_segmentation" for linear interpolation. Simulation parameters are defined completely new. Added long-wave irradiation from weather files to be used by components.

Other Changes:

• Removed deprecated internal parameters like "is_first_timestep."
• Improved geothermal probe interpolation and added custom g-function import, temperature limits, and bypass functionality in the heat pump for temperature management.
• Enhanced tests to cover profile conversions and added default simulation parameters for tests.
• Introduced support for timezones beyond 2038.

Code and Documentation:

• Applied autoformat to non-formatted files, added YAS code style configuration using JuliaFormatter, and introduced pre-commit hooks for automatic formatting. Extended README to cover code style guidelines.

Scenarios:

• Added new scenarios: "transformer_chain" and "hp_temperature_layer," along with new scenario references due to heat pump bypass, correct COP calculation for multiple heat layers and for line plots using dates as x-axis.

v0.9.0

• Implement functionality of control modules, that can be added to components and that control the operation of the components via defined callback functions. This replaces the previous implementation of "strategies", as this was too limiting. The currently implemented control module types are:
  • economical_discharge: Handles the discharging of a battery to only be allowed if sufficient charge is available and a linked PV plant has available power below a given threshold. Mostly used for examplatory purposes.
  • profile_limited: Sets the maximum PLR of a component to values from a profile. Used to set the operation of a component to a fixed schedule while allowing circumstances to override the schedule in favour of lower values (e.g. the produced energy could not be used up completely).
  • storage_driven: Controls a component to only operate when the charge of a linked storage component falls below a certain threshold and keep operation until a certain higher threshold is reached. This is often used to avoid components switching on and off rapdily to keep a storage topped up, as realised systems often operate with this kind of hysteresis behaviour.
• Restructure how the operational strategy is defined in the input file. In particular:
  • Remove entry "strategy"
  • Remove entry "control_refs"
  • Add entry "control_modules" that holds the definitions of control modules active for this component
  • Add entry "control_parameters" as container for miscellaneous parameters of the control behaviour as well as parameters to configure the storage un-/loading flags and special flags to modify the potential step of transformers to not consider given interfaces in during calculation.
• Add scenario "chpp_two_hyst" to highlight the operation of a transformer with two storage_driven control modules

v0.8.0

• Standardise storage un-/loading control parameters for all components and make them customisable to the input/output media
• Remove operational strategy extended_storage_loading_control
• Update line plot & sankey outputs to better show missing demands
• Rework internal energy distribution calculations on busses:
  • If two or more busses are connected in a chain (necessarily of the same medium), a so-called proxy bus is created, which handles the calculations for any energy transfer from components on any of the principal/original busses
  • Remove the distinction of maximum potential energy utilisation () and storage un-/loading potential, as the calculation on a bus considers storages according to the energy flow matrix as well as storage loading flags and thus does not require a distinction anymore. Direct 1-to-1 connections do not require this either, hence the removal.
  • Add automatically generated output channels for busses in a chain, where each bus tracks how much energy is transfered to other busses in the input->output direction
  • Some slight changes the generated order of operations, as this now makes use of the input and output order on proxy busses. This should not have an impact on results, but might change the order of operations compared to versions before v0.8.0.

v0.7.0

Input and output

• Rename parameters and output variables across several components:
  • Load --> Demand in output channel of FixedSink
  • static_load --> constant_demand for parameters of sinks
  • static_* --> constant_* for parameters where * in (power, temperature, demand, supply)
  • fixed_cop --> constant_cop for HeatPump
  • draw sum --> output_sum in output channel of GridConnection
  • load sum --> input_sum in output channel of GridConnection
  • power --> power_* for parameters of all transformers, where * in (el, th)
  • medium --> consider_medium for control strategy parameters of all transformers
• Add output channel "Losses" to all components and to Sankey output. "Losses" are total losses, while "Losses_XX" are medium-wise break downs
• Constant values for fixed sources and sinks are now given as power instead of work/energy to be consistent with bounded sources and sinks
• Add global logging functionalities with the following categories: Debug, Info, BalanceWarn, Warn, Error and redirected all println() to logger (console and/or logging files, separately for general logs and Balancewarn)
• Update configuration options for busses:
  • Rename "connection_matrix" to "connections"
  • Rename "storage_loading" to "energy_flow"
  • Make "connections" a required part of the config for a bus, including items "input_order" and "output_order", however "energy_flow" remains optional
  • Remove "output_refs" item as "output_order" contains the same information and is now required

Functionality

• Sankey diagrams now display the difference of requested and delivered energy in fixed sinks and sources
• Remove condition "would overfill thermal buffer" in storage_driven strategy as this is now handled implicitly
• Add profile aggregation and segmentation with testcases
• Add import of weather files in EPW format and .dat format (DWD)
• Add functionality to map profiles from weather file to component profiles, like ambient temperature from the weather file to a geothermal collector

Fixes

• Fix generic storage implementation not being available due to the module not being included
• Fix the profile scaling factor of some components being required despite profiles being optional
• Add missing output channels to Electrolyser

Refactorings

• Change the input and output interfaces of busses such that the order matches the input and output priorities
• Rename helper function highest_temperature to highest and add types to inputs
• Provide docstrings for some structs and functions that were missing them
• Rename internal variables to match changes in the input and output variables mentioned above
• Remove last potential() step of transformer chains as this is not needed
• Add required Julia packages: Colors, Interpolations, Dates, Logging
• Rename argument "parameters" for simulation parameters to "sim_params" and add them to all components and profiles
• Rework communication of balances, energy/storage potentials and temperatures via busses. This is an extensive rework that touches almost all components and how the process and potential simulation steps work. Please note that the rework is not finished with v0.7.0 and will continue to support more energy systems and component configurations that might be of interest to users. However no compatability is knowingly broken with examples that worked in previous versions.