Review of the documentation

.readthedocs.yml

@@ -0,0 +1,25 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+# Optionally set the version of Python and requirements required to build your docs
+python:
+   install:
+      - requirements: docs/requirements.txt

README.md

@@ -1,7 +1,11 @@
-Welcome to the open_plan gui repository
+[![Documentation Status](https://readthedocs.org/projects/open-plan-documentation/badge/?version=latest)](https://open-plan-documentation.readthedocs.io/en/latest/?badge=latest)
 
-Here will the code of the gui be available after we clear licensing and proof setting files before publishing. If you want to get notified when the code gets uploaded you can send an email to ...
+Welcome to the open-plan-tool documentation repository,
+
+Here the code of the documentation will be available. If you want to get notified when the code gets uploaded you can send an email to [email protected].
 
 The open_plan team
 
-Learn more about the open_plan project on our [website](https://open-plan-tool.org/)
+![open_plan_logo (10X1)](https://user-images.githubusercontent.com/70587431/144256918-974fcefd-29f5-4b2f-b68b-6468327ef50b.png)
+
+Learn more about the open_plan project on our [website](https://open-plan-tool.org/).

docs/MVS_kpi_categories.csv

@@ -0,0 +1,4 @@
+ref,category,description
+technical_kpi,technical,"Technical KPI are calculated to assess the performance of a simulated energy system, ie. represent the technical system configuration and operation. They are calculated based on the asset capacities and asset dispatch. They should allow the comparision of different energy system topologies and different project sites with each other."
+economic_kpi,economic,"Economic KPI are calculated to assess the costs of a simulated energy system. They include the costs per asset as well as the system's overall costs. Relative values like the levelized costs of supply allow a comparision to other investment options."
+environmental_kpi,environmental,"Environmental KPI are calculated to assess the impact of a simulated energy system on the environment."

docs/MVS_kpis_list.csv

@@ -0,0 +1,46 @@
+ref,label,:Unit:,:Valid Interval:,:Type:,category,see_also,:Definition:
+annual_total_flow,Aggregated flow,kWh,>=0,Numeric,technical,"average_flow, peak_flow","Dispatch of the asset over a year, aggregated generation, demand or throughput."
+annuity_om,"Annual operation, maintenance and dispatch expenses",currency/a,>=0,Numeric,economic,"annuity_total, costs_om_total","Annuity of the operation, maintenance and dispatch costs of the asset or energy system, i.e. ballpark number of the annual expenses for asset or system operation."
+annuity_total,Annuity,currency/a,>=0,Numeric,economic,"annuity_om, costs_total",Annuity of the assets costs over the project lifetime or the energy system's :ref:`net present costs (NPC) <costs_total>` .
+attributed_costs,Costs attributed to a specific sector,currency,>=0,Numeric,economic,costs_total,"Costs attributed to supplying the demand of a specific sector, based on the :ref:`net present costs (NPC) <costs_total>` of the energy system and the share of the sector demand compared to the overall system demand."
+automatic_report,Simulation report,None,None,html or pdf,files,,"Automatically generated simulation report, including the most important input data as well as all output data. The `html` can be browsed interactively, while the `pdf` can be shared with partners."
+average_flow,Average flow,kWh,>=0,Numeric,technical,"annual_total_flow, peak_flow",Average value of the assets dispatch. The ratio of average dispatch to peak dispatch indicates how much the asset is used in comparison to its actual installed capacity.
+bar_chart_optimizedAddCap,Bar chart of optimal capacities,"kWh, kWp, kW, ...",None,Figure,files,optimizedAddCap,A bar chart to compare the optimized additional capacities for each asset to be installed in the energy system. Please be aware that the units of the capacities may different.
+costs_cost_om,Operation and maintenance costs,currency,>=0,Numeric,economic,"costs_dispatch, costs_investment_over_lifetime, costs_om_total, costs_total, costs_upfront_in_year_zero","Costs for fix annual operation and maintenance costs over the whole project lifetime, which do not depend on the assets dispatch but solely on installed capacity. An example would be the maintenance costs for cleaning the installed PV capacity."
+costs_dispatch,Dispatch costs,currency,>=0,Numeric,economic,"costs_cost_om, costs_investment_over_lifetime, costs_om_total, costs_total, costs_upfront_in_year_zero","Dispatch costs over the whole project lifetime including all expenditures that depend on the dispatch of assets (e.g. fuel costs, electricity consumption from the external grid, costs for operation and maintainance that depend on the throughput of an asset)"
+costs_investment_over_lifetime,Investment costs,currency,>=0,Numeric,economic,"costs_cost_om, costs_dispatch, costs_om_total, costs_total, costs_upfront_in_year_zero, replacement_costs_during_project_lifetime","Investment costs over the whole project lifetime, including all replacement costs."
+costs_om_total,"Operation, maintenance and dispatch costs",currency,>=0,Numeric,economic,"costs_cost_om, costs_dispatch, costs_investment_over_lifetime, costs_total, costs_upfront_in_year_zero","Costs for annual operation and maintenance costs as well as dispatch of all assets of the energy system, for the whole project duration."
+costs_total,Net Present Costs (NPC),currency,>=0,Numeric,economic,"costs_cost_om, costs_dispatch, costs_investment_over_lifetime, costs_om_total, costs_upfront_in_year_zero","Net present costs of the system for the whole project duration, includes all operation, maintainance and dispatch costs as well as the investment costs (including replacements). Applied to a single asset, the costs can also be called present costs of the asset."
+costs_upfront_in_year_zero,Upfront investment costs,currency,>=0,Numeric,economic,"costs_cost_om, costs_dispatch, costs_investment_over_lifetime, costs_om_total, costs_total","The costs which will have to be paid upfront when project begins, ie. In year 0. These are the investment and fix project costs into the chosen  configuration."
+degree_of_autonomy,Degree of Autonomy,Factor,"[0,1]",Numeric,technical,total_demand,"A degree of autonomy close to zero shows high dependence on the energy provider, while a degree of autonomy of 1 represents an autonomous or net-energy system and a degree of autonomy higher 1 a surplus-energy system."
+degree_of_nze,Degree of Net Zero Energy,Factor,>=0,Numeric,technical,"total_feedin, total_consumption_from_energy_provider",The degree of net zero energy describes the ability of an energy system to provide its aggregated annual demand through local sources.
+excel_scalar_kpi,Excel file with all KPI,None,None,Excel file,files,,"Excel sheet with all calculated KPI, both for the individual assets, the sectors and the overall energy system."
+excel_timeseries,Excel file with dispatch timeseries,None,None,Excel file,files,"flow, plot_dispatch",Excel sheet with the dispatch of all assets of the energy system. Each tab represents one energy bus.
+flow,Dispatch of an asset,"kW,kgH2,...",None,Time series (with time stamps and values),technical,"plot_dispatch, peak_flow, annual_total_flow, average_flow","Optimized dispatch of an asset in the optimized energy system, ie. its generation or thoughput."
+json_input_processed,Simulation data after pre-processing (JSON),None,None,JSON,files,,"This file includes all data that is used to setup the energy system model, including all the pre-processing performed within :ref:`the module C0 <module_C0>`. It is mostly used by developers."
+json_with_results,Simulation data and results (JSON),None,None,JSON,files,,"This file includes all simulation data and also results of the energy system optimization. With :code:`mvs_report` this file can be used to create a report without re-simulating the energy system. This file is also only used by developers, and also the file used to provide the EPA with the simulation results."
+levelized_cost_of_energy_of_asset,Levelized cost of throughput,currency/kWh,>=0,Numeric,economic,"annuity_total, annual_total_flow","Cost per kWh throughput through an asset, based on the assets costs during the project lifetime as well as the total throughput through the asset in the project lifetime. For generation assets, equivalent to the levelized cost of generation."
+levelized_costs_of_electricity_equivalent,Levelized costs of electricity equivalent,currency/kWheleq,>=0,Numeric,economic,"costs_total, total_demand","Levelized cost of energy of the sector-coupled energy system, calculated from the systems annuity and the total system demand in electricity equivalent."
+logfile,MVS logfile,None,None,Logfile,files,,"Logfile of the MVS simulation including a number of log entries: Debug, information, warning and error messages. Helpful to debug the energy system simulation."
+network_graph,Energy system model visualization,None,None,Figure,files,,"Plot of the energy system model in oemof-solph topology. This graph also includes the automatically generated components, ie. the sub-assets of energy providers and an energy excess sink on each energy bus. The model therefore appears different than in the Energy Planning Application (EPA)."
+onsite_energy_fraction,Onsite energy fraction,Factor,"[0,1]",Numeric,technical,onsite_energy_matching,Onsite energy fraction is also referred to as self-consumption. It describes the fraction of all locally generated energy that is consumed by the system itself.
+onsite_energy_matching,Onsite energy matching,Factor,"[0,1]",Numeric,technical,"onsite_energy_fraction, total_feedin",The onsite energy matching is also referred to as self-sufficiency. It describes the fraction of the total demand that can be covered by the locally generated energy.
+optimizedAddCap,Optimal additional capacity,"kW, kWh, kWp, ...",>=0,Numeric,technical,peak_flow,Capacity added to installed capacity for optimal economic system performance.
+peak_flow,Peak flow,kW,>=0,Numeric,technical,"average_flow, annual_total_flow",Peak of the dispatch of an asset.
+pie_chart_costs,Pie charts of cost parameters,Percentages,None,Figure,files,"costs_total, costs_om_total, annuity_total",Displays the share of individual asset costs on different economical parameters of the overall system
+plot_dispatch,Dispatch of all assets on a bus,"kW, kgH2, ...",None,Figure,files,flow,"Visualization of the dispatch of all assets of a specific energy bus, ie. all inflows and outflows of a specific bus. Generated for every single energy bus in the energy system. If relevant, a plot of the state of charge is also displayed."
+plot_input_timeseries,Input timeseries,"kW, kgH2, ...",None,Figure,files,,"Vizualization of timeseries provided as input data, eg. PV generation timeseries."
+renewable_factor,Renewable factor,Factor,"[0,1]",Numeric,technical,"renewable_share_of_local_generation, onsite_energy_fraction, onsite_energy_matching",Describes the share of the energy influx to the local energy system that is provided from renewable sources. This includes both local generation as well as consumption from energy providers.
+renewable_share_of_local_generation,Renewable share of local generation,Factor,"[0,1]",Numeric,technical,renewable_factor,The renewable share of local generation describes how much of the energy generated locally is produced from renewable sources. It does not take into account the consumption from energy providers.
+replacement_costs_during_project_lifetime,Replacement costs,currency,>=0,Numeric,economic,costs_investment_over_lifetime,Costs for replacement of assets which occur over the project lifetime.
+specific_emissions_per_electricity_equivalent,Specific GHG per electricity equivalent,kg GHGeq/kWh,>=0,Numeric,environmental,total_emissions,Specific GHG emissions per supplied electricity equivalent.
+total_consumption_from_energy_provider,Energy import,"kWh, kWheleq, ...",>=0,Numeric,technical,,Aggregated energy imports into the local energy system from the provider.
+total_demand,Energy demand,"kWh, kWheleq, ...",>=0,Numeric,technical,,Demand of energy in local energy system over a the project lifetime.
+total_emissions,Total GHG emissions,kg GHGeq,>=0,Numeric,environmental,"renewable_factor, specific_emissions_per_electricity_equivalent",Total greenhouse gas emissions in kg.
+total_excess,Energy excess,"kWh, kWheleq, ...",>=0,Numeric,technical,,"Excess of energy, ie. unused energy in local energy system."
+total_feedin,Energy export,"kWh, kWheleq, ...",>=0,Numeric,technical,onsite_energy_fraction,Feed-in of energy into external grid.
+total_internal_generation,Total local generation,kWheleq,>=0,Numeric,technical,"total_internal_non-renewable_generation, total_internal_renewable_generation",Aggregated amount of energy generated within the energy system.
+total_internal_non-renewable_generation,Total non-renewable local generation,kWheleq,>=0,Numeric,technical,"total_internal_generation, total_internal_renewable_generation",Aggregated amount of non-renewable energy generated within the energy system.
+total_internal_renewable_generation,Total renewable local generation,kWheleq,>=0,Numeric,technical,"total_internal_generation, total_internal_non-renewable_generation",Aggregated amount of renewable energy generated within the energy system.
+total_non-renewable_energy_use,Total non-renewable energy use,kWheleq,>=0,Numeric,technical,total_renewable_energy_use,Aggregated amount of non-renewable energy used within the energy system (ie. Including local generation and external supply).
+total_renewable_energy_use,Total renewable energy use,kWheleq,>=0,Numeric,technical,total_non-renewable_energy_use,Aggregated amount of renewable energy used within the energy system (ie. Including local generation and external supply).

docs/MVS_parameters_categories.csv

@@ -0,0 +1,13 @@
+ref,csv_file_name,description
+constraints,constraints,"The file `constraints.csv` includes the following parameter(s):"
+economic_data,economic_data,"The file `economic_data.csv` includes all economic data that the simulation will use. This includes the following parameters:"
+busses,energyBusses,"The file `energyBusses.csv` defines all busses required to build the energy system. It includes following parameters:"
+consumption,energyConsumption,"The file `energyConsumption.csv` defines all energy demands that should be included in the energy system. It includes the following parameters:"
+conversion,energyConversion,"The file `energyConversion.csv` defines the assets that convert one energy carrier into another one, eg. inverters or generators. Following parameters define them:"
+production,energyProduction,"The file `energyProduction.csv` defines the assets that serve as energy sources, eg. fuel sources or PV plants. They include the following parameters:"
+providers,energyProviders,"The file `energyProviders.csv` defines the energy providers of the energy system. They include the following parameters:"
+storage,energyStorage,"The file `energyStorage.csv` defines the storage assets included in the energy system. It does not hold all needed parameters, but requires `storage_xx.csv` to be defined as well. The file `energyStorage.csv` includes the following parameters:"
+fixcost,fixcost,"The parameters must be filled for all three columns/components namely: *distribution_grid*, *engineering* and *operation*.\nThe file `fixcost.csv` includes the following parameters:"
+project_data,project_data,"The file `project_data.csv` includes the following parameters:"
+simulation_settings,simulation_settings,"The file `simulation_settings.csv` includes the following parameters:"
+storage_csv,storage_*,"The `*` in the storage filename is the number identifying the storage. It depends on the number of storage components (such as batteries, etc.) present in the system. For e.g., there should be two storage files named storage_01.csv and storage_02.csv if the system contains two storage components.The file `storage_xx.csv` contains the following parameters:"