Merge pull request #163 from NOWUM/add-parameters

Add new features and endpoints for excel files

docs/source/conf.py

@@ -14,13 +14,13 @@
 import pathlib
 import sys
 
+sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
+
 from fastapi.openapi.utils import get_openapi
 
 import ensysmod
 from ensysmod.app import app
 
-sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
-
 # If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # import os

docs/source/datamodel/dataset.rst

@@ -18,4 +18,4 @@ Dataset
     dataset/energy_conversion.rst
     dataset/energy_storage.rst
     dataset/energy_transmission.rst
-    dataset/time_series_data.rst
+    dataset/excel_data.rst

docs/source/datamodel/dataset/excel_data.rst

@@ -0,0 +1,80 @@
+**********
+Excel data
+**********
+
+All components
+==============
+For all energy components, these data can be provided via the REST API, or as excel files for easy access.
+If provided as excel files, the number and the name of the columns must correspond to the regions defined in the dataset. For capacities and full load hours, there should be exactly one row. For operation rates, the number of rows must correspond to the number of time steps defined in the dataset.
+
+Examples can be found `here <https://github.com/NOWUM/EnSysMod/tree/main/examples>`_.
+
+Fix Capacity
+------------
+The following attributes are available for fix capacities:
+
+.. autopydantic_model:: ensysmod.schemas.CapacityFixCreate
+   :inherited-members: BaseModel
+
+Max Capacity
+------------
+The following attributes are available for maximum capacities:
+
+.. autopydantic_model:: ensysmod.schemas.CapacityMaxCreate
+   :inherited-members: BaseModel
+
+Min Capacity
+------------
+The following attributes are available for minimum capacities:
+
+.. autopydantic_model:: ensysmod.schemas.CapacityMinCreate
+   :inherited-members: BaseModel
+
+Fix Operation Rate
+------------------
+The following attributes are available for fix operation rate:
+
+.. autopydantic_model:: ensysmod.schemas.OperationRateFixCreate
+   :inherited-members: BaseModel
+
+Max Operation Rate
+------------------
+The following attributes are available for maximum operation rate:
+
+.. autopydantic_model:: ensysmod.schemas.OperationRateMaxCreate
+   :inherited-members: BaseModel
+
+Max Yearly Full Load Hours
+--------------------------
+The following attributes are available for maximum yearly full load hours:
+
+.. autopydantic_model:: ensysmod.schemas.YearlyFullLoadHoursMaxCreate
+   :inherited-members: BaseModel
+
+Min Yearly Full Load Hours
+--------------------------
+The following attributes are available for minimum yearly full load hours:
+
+.. autopydantic_model:: ensysmod.schemas.YearlyFullLoadHoursMinCreate
+   :inherited-members: BaseModel
+
+Transmission components
+=======================
+Additionaly, transmission distances and losses can also be provided for transmission components, via REST API or as excel files.
+If provided as excel files, the number and the name of rows and columns must correspond to the regions defined in the dataset.
+
+Examples can be found `here <https://github.com/NOWUM/EnSysMod/tree/main/examples>`_.
+
+Transmission Distance
+---------------------
+The following attributes are available for transmission distances:
+
+.. autopydantic_model:: ensysmod.schemas.TransmissionDistanceCreate
+   :inherited-members: BaseModel
+
+Transmission Loss
+-----------------
+The following attributes are available for transmission losses:
+
+.. autopydantic_model:: ensysmod.schemas.TransmissionLossCreate
+   :inherited-members: BaseModel

docs/source/userguide/dataset.rst

@@ -149,7 +149,7 @@ Here is an part of such an excel file which contains a time series for a region.
 The parameter that are needed for each object are documented :ref:`here. <dataset_description>`.
 All of the parameters can be set, but not all of them have to.
 
-To show the structure of the zip file, we have created an example. This can be found `here <https://github.com/NOWUM/EnSysMod/tree/main/examples/data/dataset-1/>`_.
+To show the structure of the zip file, we have created an example. This can be found `here <https://github.com/NOWUM/EnSysMod/tree/main/examples>`_.
 
 Upload data per REST API interfaces individually
 ------------------------------------------------
@@ -187,8 +187,8 @@ The zip archive contains files and folders in which the regions, commodities and
 You can modify the data inside the zip archive locally and use the zip upload (again) to commit your changes.
 
 To show the structure of the zip file, we have created an example.
-This can be found `here <https://github.com/NOWUM/EnSysMod/tree/main/examples/data/dataset-2/>`_.
+This can be found `here <https://github.com/NOWUM/EnSysMod/tree/main/examples>`_.
 
 Access data per REST API interfaces individually
 ------------------------------------------------
-Another way is to access the data in small pieces via the individual REST interfaces. A list of the interfaces can be found :ref:`here. <rest_endpoints>`
+Another way is to access the data in small pieces via the individual REST interfaces. A list of the interfaces can be found :ref:`here. <rest_endpoints>`

ensysmod/api/api.py

@@ -2,6 +2,9 @@
 
 from .endpoints import (
     authentication,
+    capacity_fix,
+    capacity_max,
+    capacity_min,
     datasets,
     datasets_permissions,
     energy_commodities,
@@ -10,15 +13,15 @@
     energy_sinks,
     energy_sources,
     energy_storages,
-    energy_transmission_distances,
-    energy_transmission_losses,
     energy_transmissions,
+    operation_rate_fix,
+    operation_rate_max,
     regions,
-    ts_capacity_fix,
-    ts_capacity_max,
-    ts_operation_rate_fix,
-    ts_operation_rate_max,
+    transmission_distances,
+    transmission_losses,
     users,
+    yearly_full_load_hours_max,
+    yearly_full_load_hours_min,
 )
 
 api_router = APIRouter()
@@ -33,11 +36,14 @@
 api_router.include_router(energy_sources.router, prefix="/sources", tags=["Energy Sources"])
 api_router.include_router(energy_storages.router, prefix="/storages", tags=["Energy Storages"])
 api_router.include_router(energy_transmissions.router, prefix="/transmissions", tags=["Energy Transmissions"])
-api_router.include_router(energy_transmission_distances.router, prefix="/distances", tags=["Energy Transmission Distances"])
-api_router.include_router(energy_transmission_losses.router, prefix="/losses", tags=["Energy Transmission Losses"])
+api_router.include_router(transmission_distances.router, prefix="/transmission-distances", tags=["Transmission Distances"])
+api_router.include_router(transmission_losses.router, prefix="/transmission-losses", tags=["Transmission Losses"])
 api_router.include_router(energy_models.router, prefix="/models", tags=["Energy Models"])
 
-api_router.include_router(ts_capacity_fix.router, prefix="/fix-capacities", tags=["Fix Capacities"])
-api_router.include_router(ts_capacity_max.router, prefix="/max-capacities", tags=["Max Capacities"])
-api_router.include_router(ts_operation_rate_fix.router, prefix="/fix-operation-rates", tags=["Fix Operation Rates"])
-api_router.include_router(ts_operation_rate_max.router, prefix="/max-operation-rates", tags=["Max Operation Rates"])
+api_router.include_router(capacity_fix.router, prefix="/fix-capacities", tags=["Fix Capacities"])
+api_router.include_router(capacity_max.router, prefix="/max-capacities", tags=["Max Capacities"])
+api_router.include_router(capacity_min.router, prefix="/min-capacities", tags=["Min Capacities"])
+api_router.include_router(operation_rate_fix.router, prefix="/fix-operation-rates", tags=["Fix Operation Rates"])
+api_router.include_router(operation_rate_max.router, prefix="/max-operation-rates", tags=["Max Operation Rates"])
+api_router.include_router(yearly_full_load_hours_max.router, prefix="/max-yearly-full-load-hours", tags=["Max Yearly Full Load Hours"])
+api_router.include_router(yearly_full_load_hours_min.router, prefix="/min-yearly-full-load-hours", tags=["Min Yearly Full Load Hours"])