Skip to content

Commit b134ddf

Browse files
JulStrausJulStraus
authored
Improvement of the documentation (#30)
* Unified approach for documentation with the other packages * Exported `save_results` for simpler usage
1 parent 8b49d80 commit b134ddf

17 files changed

Lines changed: 155 additions & 104 deletions

‎NEWS.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
# Release notes
22

3-
## Unversioned
3+
## Version 0.5.16 (2025-09-24)
44

55
### Enhancement
66

77
* 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)`.
88
* Enhance the descriptive names for nodes having dictionaries with keys of type Resource as in the `MultipleBuildingTypes`-node in `EnergyModelsLanguageInterfaces.jl`.
9-
* Enhance visualization of plots over OperationalPeriods having a constant non-zero value.
9+
* Enhance visualization of plots over `OperationalPeriod`s having a constant non-zero value.
10+
* Improved the cross references in the documentation and added how to show results from a model run.
1011

1112
### Adjustment
1213

‎Project.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name = "EnergyModelsGUI"
22
uuid = "737a7361-d3b7-40e9-b1ac-59bee4c5ea2d"
33
authors = ["Jon Vegard Venås <JonVegard.Venas@sintef.no>", "Magnus Askeland <Magnus.Askeland@sintef.no>", "Shweta Tiwari <Shweta.Tiwari@sintef.no>"]
4-
version = "0.5.15"
4+
version = "0.5.16"
55

66
[deps]
77
CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

‎docs/src/figures/EMI_geography_Oslo.png‎

19 Bytes
Loading

‎docs/src/how-to/customize-colors.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# [Customize colors](@id customize_colors)
1+
# [Customize colors](@id how_to-cust_colors)
22

33
EnergyModelsGUI provides a set of colors for a set of frequently used `Resource`-`id`s.
44
These can be found in `src/colors.yml` and are visualized below

‎docs/src/how-to/customize-descriptive_names.md‎

Lines changed: 27 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,35 @@
1-
# [Customize descriptive_names](@id customize_descriptive_names)
1+
# [Customize descriptive_names](@id how_to-cust_desc_names)
22

3-
EnergyModelsGUI provides a set of descriptive names for case input structures and assosiated JuMP variables.
4-
These can be found in `src/descriptive_names.yml`. These descriptions are extended/overwritten with EMX
3+
`EnergyModelsGUI` provides a set of descriptive names for case input structures and assosiated JuMP variables.
4+
These can be found in `src/descriptive_names.yml`. These descriptions are extended/overwritten with EMX
55
packages having a `descriptive_names.yml` file in a `ext/EMGUIExt` folder of its repository. That is,
6-
if you want to provide descriptive names for your EMX package, add a `.yml` file in this location, with the
6+
if you want to provide descriptive names for your EMX package, add a `.yml` file in this location, with the
77
same structure as `src/descriptive_names.yml`.
88

9-
It can be convenient to provide a user defined file in addition. If you have this file located at
10-
`path_to_descriptive_names`, simply add it using
9+
It can be convenient to provide a user defined file in addition.
10+
If you have this file located at `path_to_descriptive_names`, simply add it using
11+
1112
```julia
1213
gui = GUI(case; path_to_descriptive_names=path_to_descriptive_names)
1314
```
1415

1516
If you instead (or in addition) want to provide descriptive names through a `Dict`, this can be done as follows
17+
1618
```julia
1719
descriptive_names_dict = Dict(
1820
:structures => Dict( # Input parameter from the case Dict
1921
:RefStatic => Dict(
20-
:trans_cap => "New description for trans_cap",
21-
:opex_fixed => "New description for opex_fixed",
22+
:trans_cap => "New description for `trans_cap`",
23+
:opex_fixed => "New description for `opex_fixed`",
2224
),
2325
:RefDynamic => Dict(
24-
:opex_var => "New description for opex_var",
25-
:directions => "New description for directions",
26+
:opex_var => "New description for `opex_var`",
27+
:directions => "New description for `directions`",
2628
),
2729
),
2830
:variables => Dict( # variables from the JuMP model
29-
:stor_discharge_use => "New description for stor_discharge_use",
30-
:trans_cap_rem => "New description for trans_cap_rem",
31+
:stor_discharge_use => "New description for `stor_discharge_use`",
32+
:trans_cap_rem => "New description for `trans_cap_rem`",
3133
),
3234
)
3335
gui = GUI(
@@ -36,9 +38,12 @@ gui = GUI(
3638
descriptive_names_dict=descriptive_names_dict,
3739
)
3840
```
41+
3942
The variables for `total` quantities (and their descriptions) can be customized in the same manner (see structure in the `src/descriptive_names.yml` file).
4043

41-
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
44+
It is also possible to ignore certain `JuMP` variables.
45+
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:
46+
4247
```julia
4348
gui = GUI(
4449
case;
@@ -47,11 +52,12 @@ gui = GUI(
4752
descriptive_names_dict=Dict(:ignore => ["con_em_tot", "cap_use", "flow_in"]),
4853
)
4954
```
50-
You can similarly customize variables that indicates an investment has occured `investment_indicators` the default variables are
51-
```
52-
- cap_add
53-
- trans_cap_add
54-
- stor_level_add
55-
- stor_charge_add
56-
- stor_discharge_add
57-
```
55+
56+
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`.
57+
The default variables are which indicate investments are
58+
59+
- ``\texttt{cap\_add}`` for all nodes except for [`Storage`](@extref EnergyModelsBase.Storage),
60+
- ``\texttt{stor\_level\_add}`` for all [`Storage`](@extref EnergyModelsBase.Storage) nodes,
61+
- ``\texttt{stor\_charge_\_add}`` for all [`Storage`](@extref EnergyModelsBase.Storage) nodes with charge capacity,
62+
- ``\texttt{stor\_discharge\_add}`` for all [`Storage`](@extref EnergyModelsBase.Storage) nodes with discharge capacity, and
63+
- ``\texttt{trans\_cap\_add}`` for all transmission modes.

‎docs/src/how-to/customize-icons.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
# [Customize icons](@id customize_icons)
1+
# [Customize icons](@id how_to-cust_icons)
22

33
EnergyModelsGUI provides default icon generation for `Node`s and `Area`s, but these "icons" can be customized by the users.
44
You can define an icon based on a `Node` `id` or by types.
55
To do this you need to specify the `id_to_icon_map` option in the `GUI` function.
6+
67
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
78

89
```julia
@@ -23,4 +24,4 @@ gui = GUI(case; id_to_icon_map=id_to_icon_map);
2324
If the string provided is a full path to a .png file, the GUI will use this file.
2425
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`.
2526
If it is not provided here, it will look in the `ext/EMGUIExt/icons/` folder in the EMX repositories.
26-
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).
27+
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).

‎docs/src/how-to/export-results.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
# [Export results](@id export_results)
1+
# [Export results](@id how_to-export_res)
22

33
The GUI enables simple printing of the results to the REPL, but one can also export to file.
4-
In order to do this, you needs to provide the path to which the files can be exported.
4+
In order to do this, you need to provide the path to which the files can be exported.
55
This is done with the keyword input argument `path_to_results` as follows
66

77
```julia

‎docs/src/how-to/save-design.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
# [Save design to file](@id save_design)
1+
# [Save design to file](@id how_to-save_design)
22

33
EnergyModelsGUI enables an interactive framework for moving nodes in a topology which can be saved to file.
4-
To save the coordinates to file the `design_path` argument must be provided as follows
4+
To save the coordinates to file, the `design_path` argument must be provided as
55

66
```julia
77
gui = GUI(case; design_path);

‎docs/src/library/internals/reference.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
# Internals
1+
# [Internals](@id lib-int)
22

3-
## Index
3+
## [Index](@id lib-int-idx)
44

55
```@index
66
Pages = ["reference.md"]
77
```
88

9-
## Types
9+
## [Types](@id lib-int-types)
1010

1111
```@autodocs
1212
Modules = [EnergyModelsGUI]
1313
Public = false
1414
Order = [:type]
1515
```
1616

17-
## Methods
17+
## [Functions](@id lib-int-fun)
1818

1919
```@autodocs
2020
Modules = [EnergyModelsGUI]

‎docs/src/library/public.md‎

Lines changed: 11 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,23 @@
1-
# [Public interface](@id sec_lib_public)
1+
# [Public interface](@id lib-pub)
22

3-
## GUI constructor
3+
## [Constructor](@id lib-pub-const)
44

55
```@docs
6-
EnergyModelsGUI.GUI(case::Case; kwargs...)
6+
GUI(case::Case; kwargs...)
7+
EnergySystemDesign(system::EnergyModelsGUI.AbstractSystem)
78
```
89

9-
## EnergySystemDesign constructor
10+
## [Types](@id lib-pub-types)
1011

1112
```@docs
12-
EnergyModelsGUI.EnergySystemDesign(system::EnergyModelsGUI.AbstractSystem)
13+
EnergySystemDesign
14+
GUI
1315
```
1416

15-
## Structures
17+
## [Utilities](@id lib-pub-utils)
1618

1719
```@docs
18-
EnergyModelsGUI.EnergySystemDesign
19-
EnergyModelsGUI.GUI
20-
```
21-
22-
## Utilities
23-
24-
```@docs
25-
EnergyModelsGUI.set_colors
26-
```
27-
28-
```@docs
29-
EnergyModelsGUI.set_icons
20+
save_results
21+
set_colors
22+
set_icons
3023
```

0 commit comments

Comments
 (0)