EnergyModelsX · JulStraus · Sep 25, 2025 · Sep 24, 2025 · Sep 24, 2025 · Sep 24, 2025
diff --git a/NEWS.md b/NEWS.md
@@ -1,12 +1,13 @@
 # Release notes
 
-## Unversioned
+## Version 0.5.16 (2025-09-24)
 
 ### Enhancement
 
 * Enable reading model results from files by enabling `model::String` being the directory to the saved files instead of `model::JuMP.Model`. Note that the files can be generated by `EnergyModelsGUI.save_results(model::JuMP.model)`.
 * Enhance the descriptive names for nodes having dictionaries with keys of type Resource as in the `MultipleBuildingTypes`-node in `EnergyModelsLanguageInterfaces.jl`.
-* Enhance visualization of plots over OperationalPeriods having a constant non-zero value.
+* Enhance visualization of plots over `OperationalPeriod`s having a constant non-zero value.
+* Improved the cross references in the documentation and added how to show results from a model run.
 
 ### Adjustment
 

diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "EnergyModelsGUI"
 uuid = "737a7361-d3b7-40e9-b1ac-59bee4c5ea2d"
 authors = ["Jon Vegard Venås <JonVegard.Venas@sintef.no>", "Magnus Askeland <Magnus.Askeland@sintef.no>", "Shweta Tiwari <Shweta.Tiwari@sintef.no>"]
-version = "0.5.15"
+version = "0.5.16"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

diff --git a/docs/src/figures/EMI_geography_Oslo.png b/docs/src/figures/EMI_geography_Oslo.png
diff --git a/docs/src/how-to/customize-colors.md b/docs/src/how-to/customize-colors.md
@@ -1,4 +1,4 @@
-# [Customize colors](@id customize_colors)
+# [Customize colors](@id how_to-cust_colors)
 
 EnergyModelsGUI provides a set of colors for a set of frequently used `Resource`-`id`s.
 These can be found in `src/colors.yml` and are visualized below

diff --git a/docs/src/how-to/customize-descriptive_names.md b/docs/src/how-to/customize-descriptive_names.md
@@ -1,33 +1,35 @@
-# [Customize descriptive_names](@id customize_descriptive_names)
+# [Customize descriptive_names](@id how_to-cust_desc_names)
 
-EnergyModelsGUI provides a set of descriptive names for case input structures and assosiated JuMP variables.
-These can be found in `src/descriptive_names.yml`. These descriptions are extended/overwritten with EMX 
+`EnergyModelsGUI` provides a set of descriptive names for case input structures and assosiated JuMP variables.
+These can be found in `src/descriptive_names.yml`. These descriptions are extended/overwritten with EMX
 packages having a `descriptive_names.yml` file in a `ext/EMGUIExt` folder of its repository. That is,
-if you want to provide descriptive names for your EMX package, add a `.yml` file in this location, with the 
+if you want to provide descriptive names for your EMX package, add a `.yml` file in this location, with the
 same structure as `src/descriptive_names.yml`.
 
-It can be convenient to provide a user defined file in addition. If you have this file located at 
-`path_to_descriptive_names`, simply add it using
+It can be convenient to provide a user defined file in addition.
+If you have this file located at `path_to_descriptive_names`, simply add it using
+
 ```julia
 gui = GUI(case; path_to_descriptive_names=path_to_descriptive_names)
 ```
 
 If you instead (or in addition) want to provide descriptive names through a `Dict`, this can be done as follows
+
 ```julia
 descriptive_names_dict = Dict(
     :structures => Dict( # Input parameter from the case Dict
         :RefStatic => Dict(
-            :trans_cap => "New description for trans_cap",
-            :opex_fixed => "New description for opex_fixed",
+            :trans_cap => "New description for `trans_cap`",
+            :opex_fixed => "New description for `opex_fixed`",
         ),
         :RefDynamic => Dict(
-            :opex_var => "New description for opex_var",
-            :directions => "New description for directions",
+            :opex_var => "New description for `opex_var`",
+            :directions => "New description for `directions`",
         ),
     ),
     :variables => Dict( # variables from the JuMP model
-        :stor_discharge_use => "New description for stor_discharge_use",
-        :trans_cap_rem => "New description for trans_cap_rem",
+        :stor_discharge_use => "New description for `stor_discharge_use`",
+        :trans_cap_rem => "New description for `trans_cap_rem`",
     ),
 )
 gui = GUI(
@@ -36,9 +38,12 @@ gui = GUI(
     descriptive_names_dict=descriptive_names_dict,
 )
 ```
+
 The variables for `total` quantities (and their descriptions) can be customized in the same manner (see structure in the `src/descriptive_names.yml` file).
 
-It is also possible to ignore certain `JuMP` variables. *E.g.*, ignoring `cap_use` and `flow_in` (in addition to the variable `con_em_tot` which is ignored by default) can be done as follows
+It is also possible to ignore certain `JuMP` variables.
+As an example, `cap_use` and `flow_in` (in addition to the variable `con_em_tot` which is ignored by default) can be ignored through:
+
 ```julia
 gui = GUI(
     case;
@@ -47,11 +52,12 @@ gui = GUI(
     descriptive_names_dict=Dict(:ignore => ["con_em_tot", "cap_use", "flow_in"]),
 )
 ```
-You can similarly customize variables that indicates an investment has occured `investment_indicators` the default variables are
-```
-  - cap_add
-  - trans_cap_add
-  - stor_level_add
-  - stor_charge_add
-  - stor_discharge_add
-```
+
+You can similarly customize variables that indicate an investment has occured through the values of the key `:investment_indicators` in the keyword argument `descriptive_names_dict`.
+The default variables are which indicate investments are
+
+- ``\texttt{cap\_add}`` for all nodes except for [`Storage`](@extref EnergyModelsBase.Storage),
+- ``\texttt{stor\_level\_add}`` for all  [`Storage`](@extref EnergyModelsBase.Storage) nodes,
+- ``\texttt{stor\_charge_\_add}`` for all  [`Storage`](@extref EnergyModelsBase.Storage) nodes with charge capacity,
+- ``\texttt{stor\_discharge\_add}`` for all  [`Storage`](@extref EnergyModelsBase.Storage) nodes with discharge capacity, and
+- ``\texttt{trans\_cap\_add}`` for all transmission modes.
diff --git a/docs/src/how-to/customize-icons.md b/docs/src/how-to/customize-icons.md
@@ -1,8 +1,9 @@
-# [Customize icons](@id customize_icons)
+# [Customize icons](@id how_to-cust_icons)
 
 EnergyModelsGUI provides default icon generation for `Node`s and `Area`s, but these "icons" can be customized by the users.
 You can define an icon based on a `Node` `id` or by types.
 To do this you need to specify the `id_to_icon_map` option in the `GUI` function.
+
 Say that you want to specify default icons for the types `Source`, `NetworkNode` and `Sink`, and you want to have a special icon for the `Node` with `id` `7`, then simply do the following
 
 ```julia
@@ -23,4 +24,4 @@ gui = GUI(case; id_to_icon_map=id_to_icon_map);
 If the string provided is a full path to a .png file, the GUI will use this file.
 If the string is simply the name of the file (without the .png ending) as above, the GUI will first look for a file in a folder `../icons`.
 If it is not provided here, it will look in the `ext/EMGUIExt/icons/` folder in the EMX repositories.
-If the icon is not found here either, it will fall back to the default icon generation mention earlier (based on simple shapes like circle for `Sink`s and squares for `Source`s and colored by input/output colors).
+If the icon is not found here either, it will fall back to the default icon generation mentioned earlier (based on simple shapes like circle for `Sink`s and squares for `Source`s and colored by input/output colors).
diff --git a/docs/src/how-to/export-results.md b/docs/src/how-to/export-results.md
@@ -1,7 +1,7 @@
-# [Export results](@id export_results)
+# [Export results](@id how_to-export_res)
 
 The GUI enables simple printing of the results to the REPL, but one can also export to file.
-In order to do this, you needs to provide the path to which the files can be exported.
+In order to do this, you need to provide the path to which the files can be exported.
 This is done with the keyword input argument `path_to_results` as follows
 
 ```julia

diff --git a/docs/src/how-to/save-design.md b/docs/src/how-to/save-design.md
@@ -1,7 +1,7 @@
-# [Save design to file](@id save_design)
+# [Save design to file](@id how_to-save_design)
 
 EnergyModelsGUI enables an interactive framework for moving nodes in a topology which can be saved to file.
-To save the coordinates to file the `design_path` argument must be provided as follows
+To save the coordinates to file, the `design_path` argument must be provided as
 
 ```julia
 gui = GUI(case; design_path);

diff --git a/docs/src/library/internals/reference.md b/docs/src/library/internals/reference.md
@@ -1,20 +1,20 @@
-# Internals
+# [Internals](@id lib-int)
 
-## Index
+## [Index](@id lib-int-idx)
 
 ```@index
 Pages = ["reference.md"]
 ```
 
-## Types
+## [Types](@id lib-int-types)
 
 ```@autodocs
 Modules = [EnergyModelsGUI]
 Public = false
 Order = [:type]
 ```
 
-## Methods
+## [Functions](@id lib-int-fun)
 
 ```@autodocs
 Modules = [EnergyModelsGUI]

diff --git a/docs/src/library/public.md b/docs/src/library/public.md
@@ -1,30 +1,23 @@
-# [Public interface](@id sec_lib_public)
+# [Public interface](@id lib-pub)
 
-## GUI constructor
+## [Constructor](@id lib-pub-const)
 
 ```@docs
-EnergyModelsGUI.GUI(case::Case; kwargs...)
+GUI(case::Case; kwargs...)
+EnergySystemDesign(system::EnergyModelsGUI.AbstractSystem)
 ```
 
-## EnergySystemDesign constructor
+## [Types](@id lib-pub-types)
 
 ```@docs
-EnergyModelsGUI.EnergySystemDesign(system::EnergyModelsGUI.AbstractSystem)
+EnergySystemDesign
+GUI
 ```
 
-## Structures
+## [Utilities](@id lib-pub-utils)
 
 ```@docs
-EnergyModelsGUI.EnergySystemDesign
-EnergyModelsGUI.GUI
-```
-
-## Utilities
-
-```@docs
-EnergyModelsGUI.set_colors
-```
-
-```@docs
-EnergyModelsGUI.set_icons
+save_results
+set_colors
+set_icons
 ```
diff --git a/docs/src/manual/philosophy.md b/docs/src/manual/philosophy.md
@@ -1,18 +1,18 @@
-# Philosophy
+# [Philosophy](@id man-phil)
 
-## General design philosophy
+## [General design philosophy](@id man-phil-gen)
 
 One key aim in the development of `EnergyModelsGUI` was to create a graphical user interface that
 
 1. visualizes the topology and result from `EnergyModelsX`,
-2. draws inspiration from the [integrate](https://www.sintef.no/programvare/integrate/) framework for visualization of energy systems, and
+2. draws inspiration from the *[Integrate](https://www.sintef.no/programvare/integrate/)* framework for visualization of energy systems, and
 3. has a simple architecture that minimizes dependencies on major packages.
 
 `EnergyModelsGUI` is hence focusing of providing the user with a simple interface to both visualize the created energy system and the results, if a `JuMP.model` is added.
 Its aim is not to provide the user with an input processing routine or a method for generating figures that can be directly used in publications.
 
-## Incorporation of `EnergyModelsGUI` to your `EMX` extension package
+## [Incorporation of `EnergyModelsGUI` to your `EMX` extension package](@id man-phil-ext)
 
 `EnergyModelsGUI` should by default be able to work with potential extension packages as it is only dependent on the case dictionary description and the variable names.
 However, you can provide an extension to `EnergyModelsGUI` in your `EMX` package with, *e.g.*, specific icons for the developed nodes.
-In addition, if your package introduces new variables, you can provide a description of the variables in your package.
+In addition, if your package introduces new variables, you can provide a description of the variables in your package.
diff --git a/docs/src/manual/quick-start.md b/docs/src/manual/quick-start.md
@@ -1,21 +1,61 @@
-# Quick Start
+# [Quick Start](@id man-quick)
 
->  1. Install the most recent version of [Julia], preferably using the Juliaup version multiplexer (https://github.com/JuliaLang/juliaup)
->  2. Install the package [`EnergyModelsGUI`](https://energymodelsx.github.io/EnergyModelsGUI.jl/) by running:
->     ```
->     ] add EnergyModelsGUI
->     ```
+## [Installation](@id man-quick-install)
+
+> 1. Install the most recent version of [Julia], preferably using the Juliaup version multiplexer (<https://github.com/JuliaLang/juliaup>)
+> 2. Install the package [`EnergyModelsGUI`](https://energymodelsx.github.io/EnergyModelsGUI.jl/) by running:
+>
+>    ```
+>    ] add EnergyModelsGUI
+>    ```
+
+## [Use](@id man-quick-use)
 
 !!! note
-    Utilizing `EnergyModelsGUI` requires the declaration of cases in `EnergyModelsX`.
+    `EnergyModelsGUI` extends `EnergyModelsBase` with a graphical user interface.
+    As a consequence, it requires the declaration of a [`Case`](@extref EnergyModelsBase.Case) in `EnergyModelsX`.
+
     To this end, you also have to add the packages [`EnergyModelsBase`](https://energymodelsx.github.io/EnergyModelsBase.jl/stable/) and potentially [`EnergyModelsGeography`](https://energymodelsx.github.io/EnergyModelsGeography.jl/stable/) and [`EnergyModelsInvestments`](https://energymodelsx.github.io/EnergyModelsInvestments.jl/stable/) to create your energy model cases first.
 
-If you already have constructed a `case` in EMX you can view this case with
+If you already have constructed a [`Case`](@extref EnergyModelsBase.Case) in `EMX` you can view this case with
 
 ```julia
 using EnergyModelsGUI
 
 GUI(case)
 ```
 
-A complete overview of the keyword arguments available for the `GUI` functions is available [`here`](@ref GUI(::Dict)). The GUI and its functionality is described through an example [`here`](@ref simple-example).
+This allows you to investigate all provided parameters, but does not show you the results from the analysis.
+The results from a `JuMP` model can be visualized through the keyword argument `model` for a given `JuMP` model `m`:
+
+```julia
+GUI(case; model=m)
+```
+
+It is furthermore possible to visualize results from a saved model run.
+This however requires you to first save the results from a model run through the function [`save_results`](@ref).
+You can then visualize the results from a saved model run, again with the keyword argument `model`.
+
+For a given `JuMP` model `m`, this approach is given by
+
+```julia
+# Specify the directory for saving the results and save the results
+dir_save = `path-to-results`
+save_results(m; directory = dir_save)
+
+# Load the results from the saved directory
+GUI(case; model = dir_save)
+```
+
+!!! warning "Requirements for loading from file"
+
+    1. You **must** always provide a [`Case`](@extref EnergyModelsBase.Case) in `EnergyModelsX` corresponding to the model results when reading input data.
+       This case can be created anew from corresponding functions.
+       It **cannot** be a saved `Case` as the pointers to specific instances of, *e.g.*, `Link`s are not recreated when loading a `Case`.
+    2. You **must** use the function `save_results` for saving your results as we require the meta data when reading the CSV files for translating the data into the correct format.
+
+A complete overview of the keyword arguments available for the `GUI` functions is available *[in its docstring](@ref GUI(case::Case; kwargs...))*.
+
+!!! tip "Example"
+    The GUI and its functionality is described through *[an example](@ref man-exampl)*.
+    You can also load different examples from the folder, if desired