refactoring: removing content which now lives in feature pages, move …

…V2G/flex-model illustration to tutorials

Signed-off-by: Nicolas Höning <nicolas@seita.nl>

.vscode/spellright.dict

@@ -266,3 +266,5 @@ UNPROCESSABLE_ENTITY
 Prosumers
 customizable
 backend
+amongst
+―

documentation/api/notation.rst

@@ -153,104 +153,6 @@ In all current versions of the FlexMeasures API, only equidistant timeseries dat
 - "duration" should also be a multiple of the sensor resolution.
 
 
-.. _describing_flexibility:
-
-Describing flexibility
-^^^^^^^^^^^^^^^^^^^^^^^
-
-FlexMeasures computes schedules for energy systems that consist of multiple devices that consume and/or produce electricity.
-We model a device as an asset with a power sensor, and compute schedules only for flexible devices, while taking into account inflexible devices.
-
-To compute a schedule, FlexMeasures first needs to assess the flexibility state of the system.
-This is described by the `flex model` (information about the state and possible actions of the flexible device) and the `flex-context`
-(information about the system as a whole, in order to assess the value of activating flexibility).
-
-This information goes beyond the usual time series recorded by an asset's sensors. It's being sent through the API when triggering schedule computation.
-Some parts of it can be persisted on the asset & sensor model as attributes (that's design work in progress). 
-
-We distinguish the information with two groups:
-
-Flex model
-""""""""""""
-
-The flexibility model describes to the scheduler what the flexible asset's state is,
-and what constraints or preferences should be taken into account.
-Which type of flexibility model is relevant to a scheduler usually relates to the type of device.
-
-Usually, not the whole flexibility model is needed.
-FlexMeasures can infer missing values in the flex model, and even get them (as default) from the sensor's attributes.
-This means that API and CLI users don't have to send the whole flex model every time.
-
-Here are the three types of flexibility models you can expect to be built-in:
-
-1) For **storage devices** (e.g. batteries, and :abbr:`EV (electric vehicle)` batteries connected to charge points), the schedule deals with the state of charge (SOC).
-
-   The possible flexibility parameters are:
-
-   - ``soc-at-start`` (defaults to 0)
-   - ``soc-unit`` (kWh or MWh)
-   - ``soc-min`` (defaults to 0)
-   - ``soc-max`` (defaults to max soc target)
-   - ``soc-minima`` (defaults to NaN values)
-   - ``soc-maxima`` (defaults to NaN values)
-   - ``soc-targets`` (defaults to NaN values)
-   - ``roundtrip-efficiency`` (defaults to 100%)
-   - ``charging-efficiency`` (defaults to 100%)
-   - ``discharging-efficiency`` (defaults to 100%)
-   - ``storage-efficiency`` (defaults to 100%) [#]_
-   - ``prefer-charging-sooner`` (defaults to True, also signals a preference to discharge later)
-   - ``power-capacity`` (defaults to the Sensor attribute ``capacity_in_mw``)
-
-    .. [#] The storage efficiency (e.g. 95% or 0.95) to use for the schedule is applied over each time step equal to the sensor resolution. For example, a storage efficiency of 95 percent per (absolute) day, for scheduling a 1-hour resolution sensor, should be passed as a storage efficiency of :math:`0.95^{1/24} = 0.997865`.
-
-   For some examples, see the :ref:`v2g` use case and `the API documentation for triggering schedules <../api/v3_0.html#post--api-v3_0-sensors-(id)-schedules-trigger>`_.
-
-2) For **processes**
-
-    - ``power``: nominal power of the load.
-    - ``duration``: time that the load last.
-    - ``optimization_sense``: objective of the scheduler, to maximize or minimize.
-    - ``time_restrictions``: time periods in which the load cannot be schedule to.
-    - ``process_type``: INFLEXIBLE, BREAKABLE or SHIFTABLE.
-
-
-3) For **buffer devices** (e.g. thermal energy storage systems connected to heat pumps), use the same flexibility parameters described above for storage devices. Here are some tips to model a buffer with these parameters:
-
-   - Describe the thermal energy content in kWh or MWh.
-   - Set ``soc-minima`` to the accumulative usage forecast.
-   - Set ``charging-efficiency`` to the sensor describing the :abbr:`COP (coefficient of performance)` values.
-   - Set ``storage-efficiency`` to a value below 100% to model (heat) loss.
-
-
-In addition, folks who write their own custom scheduler (see :ref:`plugin_customization`) might also require their custom flexibility model.
-That's no problem, FlexMeasures will let the scheduler decide which flexibility model is relevant and how it should be validated. 
-
-.. note:: We also aim to model situations with more than one flexible asset, with different types of flexibility.
-     This is ongoing architecture design work, and therefore happens in development settings, until we are happy 
-     with the outcomes. Thoughts welcome :) 
-
-
-Flex context
-"""""""""""""
-
-With the flexibility context, we aim to describe the system in which the flexible assets operates:
-
-- ``inflexible-device-sensors`` ― power sensors that are relevant, but not flexible, such as a sensor recording rooftop solar power connected behind the main meter, whose production falls under the same contract as the flexible device(s) being scheduled
-- ``consumption-price-sensor`` ― the sensor which defines costs/revenues of consuming energy
-- ``production-price-sensor`` ― the sensor which defines cost/revenues of producing energy
-- ``site-power-capacity`` ― defaults to the Asset attribute ``capacity_in_mw`` ― maximum/minimum achievable power at the grid connection point [#asymmetric]_.
-- ``site-consumption-capacity`` ― defaults to the Asset attribute ``consumption_capacity_in_mw`` ― maximum consumption power at the grid connection point [#consumption]_. If ``site-power-capacity`` is defined, the minimum between the ``site-power-capacity`` and ``site-consumption-capacity`` will be used.
-- ``site-production-capacity`` ― defaults to the Asset attribute ``production_capacity_in_mw`` ― maximum production power at the grid connection point [#production]_.  If ``site-power-capacity`` is defined, the minimum between the ``site-power-capacity`` and ``site-production-capacity`` will be used.
-
-These should be independent on the asset type and consequently also do not depend on which scheduling algorithm is being used.
-
-.. [#asymmetric] ``site-consumption-capacity`` and ``site-production-capacity`` allow defining asymmetric contracted transport capacities for each direction (i.e. production and consumption).
-.. [#production] Example: with a connection capacity (``site-power-capacity``) of 1 MVA (apparent power) and a production capacity (``site-production-capacity``) of 400 kW (active power), the scheduler will make sure that the grid outflow doesn't exceed 400 kW.
-.. [#consumption] Example: with a connection capacity (``site-power-capacity``) of 1 MVA (apparent power) and a consumption capacity (``site-consumption-capacity``) of 800 kW (active power), the scheduler will make sure that the grid inflow doesn't exceed 800 kW.
-
-.. warning:: If no (symmetric, consumption and production) site capacity is defined (also not as defaults), the scheduler will not enforce any bound on the site power.
-
-
 .. _beliefs:
 
 Tracking the recording time of beliefs

documentation/concepts/device_scheduler.rst

@@ -1,16 +1,16 @@
-.. _device_scheduler:
+.. _storage_device_scheduler:
 
-Device scheduler
-===========
+Storage device scheduler: Linear model
+=======================================
 
 Introduction
 --------------
-This generic device scheduler is able to handle an EMS with multiple devices, with various types of constraints on the EMS level and on the device level,
+This generic storage device scheduler is able to handle an EMS with multiple devices, with various types of constraints on the EMS level and on the device level,
 and with multiple market commitments on the EMS level.
 
 A typical example is a house with many devices. The commitments are assumed to be with regard to the flow of energy to the device (positive for consumption, negative for production). In practice, this generic scheduler is used in the **StorageScheduler** to schedule a storage device.
 
-The solver minimises the costs of deviating from the commitments.
+The solver minimizes the costs of deviating from the commitments.
 
 
 

documentation/concepts/benefits_of_flex.rst → documentation/concepts/flexibility.rst

@@ -3,7 +3,7 @@
 Energy flexibility
 =====================
 
-FlexMeasures was created so that the value of energy flexibility can be realised.
+FlexMeasures was created so that the value of energy flexibility can be realized.
 This will make energy cheaper to use, and can also reduce CO₂ emissions.
 Here, we define a few terms around this idea, which come up in other parts of this documentation.
 
@@ -104,27 +104,27 @@ This volume is a multiplication of the energy volume being shifted and the durat
 Profits of flexibility activation
 ---------------------------------
 
-The realised value from activating flexibility has to be computed and accounted for.
-Both of these activities depend on the context in which FlexMeasures is being used, and we expect that it will often have to be implemented in a custom manner (much as the actual scheduling optimisation).
+The realized value from activating flexibility has to be computed and accounted for.
+Both of these activities depend on the context in which FlexMeasures is being used, and we expect that it will often have to be implemented in a custom manner (much as the actual scheduling optimization).
 
 .. todo:: Making it possible to configure custom scheduling and value accounting is on the roadmap for FlexMeasures.
 
 Computing value
 ^^^^^^^^^^^^^^^^
 
-The computation of the value is what drives the scheduling optimisation.
+The computation of the value is what drives the scheduling optimization.
 This value is usually monetary, and in that case there should be some form of market configured.
 This can be a constant or time-of-use tariff, or a real market.
-However, there are other possibilities, for instance if the optimisation goal is to minimise CO₂ emissions.
-Then, the realised value is avoided CO₂, which nowadays has an assumed value, e.g. in `the EU ETS carbon market <https://ember-climate.org/data/carbon-price-viewer/>`_.
+However, there are other possibilities, for instance if the optimization goal is to minimize CO₂ emissions.
+Then, the realized value is avoided CO₂, which nowadays has an assumed value, e.g. in `the EU ETS carbon market <https://ember-climate.org/data/carbon-price-viewer/>`_.
 
 
 Accounting / Sharing value
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The realisation of payments is outside of the scope of FlexMeasures, but it can provide the accounting to enable them (as was said above, this is usually a part of the optimisation problem formulation).
+The realization of payments is outside of the scope of FlexMeasures, but it can provide the accounting to enable them (as was said above, this is usually a part of the optimization problem formulation).
 
-However, next to fueling algorithmic optimisation, the way that the value of energy flexibility is shared among the stakeholders will also be an important driver for project participation. Accounting plays an important role here.
+However, next to fueling algorithmic optimization, the way that the value of energy flexibility is shared among the stakeholders will also be an important driver for project participation. Accounting plays an important role here.
 
 There are different roles in a modern smart energy system (e.g. "Prosumer", "DSO", Aggregator", "ESCo"),
 and they all enjoy the benefits of flexibility  in different ways
@@ -136,9 +136,9 @@ can support well are the following relationships:
 
 * between Aggregator and Prosumer, where the Aggregator sells the balancing power to a third party and shares the profits with the Prosumer according to some contracted method for profit sharing. In this case the stated costs and revenues for the Prosumer may be after deducting the Aggregator fee (which typically include price components per flex activation and price components per unit of time, but may include arbitrarily complex price components).
 
-* between ESCo and Prosumer, where the ESCo advises the Prosumer to optimise against e.g. dynamic prices. Likewise, stated numbers may be after deducting the ESCo fee.
+* between ESCo and Prosumer, where the ESCo advises the Prosumer to optimize against e.g. dynamic prices. Likewise, stated numbers may be after deducting the ESCo fee.
 
-FlexMeasures can take these intricacies into account if a custom optimisation algorithm is plugged in to model them.
+FlexMeasures can take these intricacies into account if a custom optimization algorithm is plugged in to model them.
 
 Alternatively, we can assume that all profit from activating flexibility goes to the Prosumer, or simply report the profits before sharing (and before deducting any service fees).
 

documentation/features/scheduling.rst

@@ -27,6 +27,7 @@ This is described by:
 This information goes beyond the usual time series recorded by an asset's sensors. It's being sent through the API when triggering schedule computation.
 Some parts of it can be persisted on the asset & sensor model as attributes (that's design work in progress). 
 
+Let's dive into the details ― what can you tell FlexMeasures about your optimization problem?
 
 The flex-context
 -----------------
@@ -170,7 +171,7 @@ depending on the first target state of charge and the capabilities of the asset.
 
 Of course, we also log a failure in the scheduling job, so it's important to take note of these failures. Often, mis-configured flex models are the reason.
 
-For some examples, see the :ref:`v2g` use case and `the API documentation for triggering schedules <../api/v3_0.html#post--api-v3_0-sensors-(id)-schedules-trigger>`_.
+For a hands-on tutorial on using some of the storage flex-model fields, head over to :ref:`tut_v2g` use case and `the API documentation for triggering schedules <../api/v3_0.html#post--api-v3_0-sensors-(id)-schedules-trigger>`_.
 
 Finally, are you interested in the linear programming details behind the storage scheduler? Then head over to :ref:`storage_device_scheduler`!
 You can also review the current flex-model for storage in the code, at ``flexmeasures.data.schemas.scheduling.storage.StorageFlexModelSchema``.

documentation/getting-started.rst

@@ -3,8 +3,13 @@
 Getting started
 =================================
 
-For a direct dive into running FlexMeasures, go to :ref:`installation`. However, FlexMeasures is useful from different perspectives.
-Below, we added helpful pointers to start reading the right sections of this documentation first, to start engaging with this technology in a way that makes sense to you personally.
+For a direct intro on running FlexMeasures, go to :ref:`installation`. However, FlexMeasures is useful from different perspectives.
+Below, we added helpful pointers to start reading.
+
+.. contents::
+    :local:
+    :depth: 2
+
 
 .. _start_using_flexmeasures_in_your_organization:
 

documentation/index.rst

@@ -157,14 +157,12 @@ In :ref:`getting_started`, we have some helpful tips how to dive into this docum
 
 
 .. toctree::
-    :caption: Concepts
+    :caption: Features
     :maxdepth: 1
-
-    concepts/data-model
-    concepts/algorithms
-    concepts/security_auth
-    concepts/device_scheduler
-
+
+    features/scheduling
+    features/forecasting
+    features/reporting
 
 .. toctree::
     :caption: Tutorials
@@ -173,12 +171,24 @@ In :ref:`getting_started`, we have some helpful tips how to dive into this docum
     tut/toy-example-setup
     tut/toy-example-from-scratch
     tut/toy-example-expanded
+    tut/flex-model-v2g
     tut/toy-example-process
     tut/toy-example-reporter
     tut/posting_data
     tut/forecasting_scheduling
     tut/building_uis
 
+
+.. toctree::
+    :caption: Concepts
+    :maxdepth: 1
+
+    concepts/flexibility
+    concepts/data-model
+    concepts/security_auth
+    concepts/device_scheduler
+
+
 .. toctree::
     :caption: The in-built UI
     :maxdepth: 1
@@ -193,7 +203,6 @@ In :ref:`getting_started`, we have some helpful tips how to dive into this docum
 
     api/introduction
     api/notation
-    api/v2g
     api/v3_0
     api/dev
     api/change_log

documentation/api/v2g.rst → documentation/tut/flex-model-v2g.rst

@@ -1,10 +1,13 @@
-.. _v2g:
+.. _tut_v2g:
 
-Vehicle-to-grid
----------------
+A storage flex-model tutorial: Vehicle-to-grid
+-----------------------------------------------
+
+The most powerful concept of FlexMeasures is the flex-model. We feel it is time to pay more attention to it and illustrate its effects.
+
+As a demonstration of how to construct a suitable flex model for a given use case, let us for a moment consider a use case where FlexMeasures is asked (throough API calls) to compute :abbr:`V2G (vehicle-to-grid)` schedules.
+(For a more general introduction to flex modeling, see :ref:`describing_flexibility`.)
 
-As a demonstration of how to construct a suitable flex model for a given use case, we consider a client using FlexMeasures to compute :abbr:`V2G (vehicle-to-grid)` schedules.
-For a more general introduction to flex modelling, see :ref:`describing_flexibility`.
 In this example, the client is interested in the following:
 
 1. :ref:`battery_protection`: Protect the battery from degradation by constraining any cycling between 25% and 85% of its available storage capacity.
@@ -117,3 +120,7 @@ To provide an incentive for cycling the battery in response to market prices, th
             "production-price-sensor": 42
         }
     }
+
+
+We hope this demonstration helped to illustrate the flex-model of the storage scheduler. Until now, optimizing storage (like batteries) has been the sole focus of these tutorial series.
+In :ref:`tut_toy_schedule_process`, we'll turn to something different: the optimal timing of processes with fixed energy work and duration.