Merge pull request #7 from ait-energy/dev

Integrate IESoptLib, add more cleaned up structure to the docs
ait-energy · Jun 7, 2024 · a3eec3d · a3eec3d
2 parents ec9acdb + 6baa045
commit a3eec3d
Show file tree

Hide file tree

Showing 17 changed files with 563 additions and 34 deletions.
diff --git a/Project.toml b/Project.toml
@@ -8,6 +8,7 @@ CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
+IESoptLib = "b98f706d-40ec-4ce6-a66c-1c6e71d3cef6"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
@@ -53,6 +54,7 @@ Dates = "<0.0.1,1"
 GLPK = "1.2.1"
 Gurobi = "1.3.0"
 HiGHS = "1.9"
+IESoptLib = "0.1.0"
 Ipopt = "1.6.2"
 JLD2 = "0.4"
 JSON = "0.21"

diff --git a/README.md b/README.md
@@ -10,11 +10,19 @@
 [![Coverage](https://codecov.io/gh/ait-energy/IESopt.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/ait-energy/IESopt.jl)
 [![Aqua](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 
+> Note: We are currently moving from our internal version control to GitHub. Missing contents will be added during the
+> upcoming days ...
+
 **IESopt** (_Integrated Energy System Optimization_) is a modeling and optimization framework for integrated energy
 systems.
 
-> Note: We are currently moving from our internal version control to GitHub. Missing contents will be added during the
-> upcoming days ...
+It is developed and maintained at the **Center for Energy** at
+[AIT Austrian Institute of Technology GmbH](https://www.ait.ac.at/). The framework is designed to support the
+optimization of energy systems that are characterized by a high degree of integration between different energy carriers
+and sectors. It focuses on offering a modular and adaptable tool for modelers, that does not compromise on performance,
+while still being user-friendly. This is enabled by reducing energy system assets to abstract building blocks, that are
+supported by specialized implementation, and can be combined into complex systems without the need of a detailed
+understanding of mathematical modeling or proficiency in any coding-language.
 
 ## Table of Contents
 
@@ -28,13 +36,20 @@ systems.
 ## Background
 
 IESopt has been in development at AIT since 2021, and was moved to GitHub in June, 2024, based on a cleaned version with
-slightly more than 1000 commits. Check out the [references](https://ait-energy.github.io/IESopt.jl/dev/pages/references/publications/)
-for a more detailed overview about publications and projects, where IESopt has been used.
+slightly more than 1000 commits. IESopt has been applied in a variety of projects, ranging from small-scale energy
+system optimization, to large-scale models spanning multiple sectors and regions. Check out the
+[list of references](https://ait-energy.github.io/IESopt.jl/dev/pages/references/) for more information.
 
 ## Install
 
-Make sure to check out the detailed [installation guides](https://ait-energy.github.io/IESopt.jl/dev/pages/tutorials/setup/)
-in the documentation, both for Python and Julia.
+Make sure to check out the detailed [installation guides](https://ait-energy.github.io/IESopt.jl/dev/#Installation)
+in the documentation, both for Python and Julia. Depending on your use-case, and choice of programming language / setup,
+there are different ways to get started. If you are experienced with Julia, and want to interact with the core model
+itself, then using `IESopt.jl` directly will suit you best. If you are looking for a more user-friendly interaction, or
+are new to energy system modeling and/or coding at all, you might want to check out the Python wrapper
+[iesopt-py](https://github.com/ait-energy/iesopt-py).
+
+> If you are not 110% sure where to start... start here: [iesopt](https://github.com/ait-energy/iesopt-py)
 
 ### Quick setup for Julia
 
@@ -91,7 +106,8 @@ df_results = model.results.to_pandas()
 ## API
 
 Check out the full [API reference](https://ait-energy.github.io/IESopt.jl/dev/pages/manual/api/) in the
-documentation.
+documentation, and most importantly the [YAML reference](https://ait-energy.github.io/IESopt.jl/dev/pages/manual/yaml/),
+that documents how the required model configuration files should be structured.
 
 ### Basic API
 

diff --git a/docs/generate.jl b/docs/generate.jl
@@ -19,15 +19,18 @@ append!(
     _PAGES,
     _build_page_paths(
         [
-            "Tutorials" => ["setup", "first_model", "next_steps", "results"],
+            "Tutorials" => [
+                "setup", "first_model", "next_steps", "results",
+                "Creating new components" => ["index", "templates_1", "templates_2"],
+            ],
             "User Guide" => [
                 "general",
                 "Sectors" => ["electricity", "heat", "gas"],
                 "solvers",
-                "Custom Functionality" => ["templates", "addons"],
+                "Custom functionality" => ["templates", "addons"],
                 "Examples" => [], # TODO: examples_files,
             ],
-            "Manual" => ["yaml", "core_components", "templates", "api"],
+            "Manual / Reference" => ["yaml", "core_components", "templates", "api"],
             "References" => "references",
             "Developer Documentation" => "dev_docs",
             "Changelog" => "changelog",

diff --git a/docs/liveserver.jl b/docs/liveserver.jl
@@ -8,7 +8,10 @@ const LS_PATH_DOCS = joinpath(LS_PATH_ROOT, "docs")
 
 # Make sure `docs` environment is set up properly.
 import Pkg
+Pkg.resolve()
+Pkg.instantiate()
 Pkg.activate(@__DIR__)
+Pkg.resolve()
 Pkg.instantiate()
 
 # Communicate with `make.jl` that we are running in live mode, so that we can load `Revise` there.

diff --git a/docs/src/pages/manual/api.md → docs/src/pages/manual___reference/api.md b/docs/src/pages/manual/api.md → docs/src/pages/manual___reference/api.md
@@ -1,4 +1,4 @@
-# API Reference
+# API
 
 This contains the following raw documentation entries:
 

diff --git a/docs/src/pages/manual/core_components.md → ...ges/manual___reference/core_components.md b/docs/src/pages/manual/core_components.md → ...ges/manual___reference/core_components.md
@@ -1,6 +1,6 @@
-# Model Reference
+# Model formulation
 
-This page collects all information about the core components of IESopt, their properties (and default values), their internal mathematical formulations, and some examples of how to use them. See the [API Reference](@ref) for a complete list of all available functions and types.
+This page collects all information about the core components of IESopt, their properties (and default values), their internal mathematical formulations, and some examples of how to use them. See the [API](@ref) for a complete list of all available functions and types.
 
 ```@meta
 CurrentModule       = IESopt

diff --git a/docs/src/pages/manual/templates.md → ...src/pages/manual___reference/templates.md b/docs/src/pages/manual/templates.md → ...src/pages/manual___reference/templates.md
@@ -1,3 +1,3 @@
-# Template Reference
+# Templates
 
 To be added (explanation).
diff --git a/docs/src/pages/manual/yaml.md → docs/src/pages/manual___reference/yaml.md b/docs/src/pages/manual/yaml.md → docs/src/pages/manual___reference/yaml.md
@@ -1,3 +1,3 @@
-# YAML Reference
+# YAML
 
 To be added (based on docstrings from, e.g., the configs).
diff --git a/docs/src/pages/tutorials/creating_new_components/index.md b/docs/src/pages/tutorials/creating_new_components/index.md
@@ -0,0 +1,3 @@
+# Custom Components
+
+To be added.