Merge branch 'docs/refactoring-scheduling' of github.com:FlexMeasures…

…/flexmeasures into docs/refactoring-scheduling

documentation/concepts/data-model.rst

@@ -21,7 +21,7 @@ Assets can represent physical objects (e.g. a car battery or an industrial machi
 In essence, an asset is anything on which you collect data.
 
 Assets can also have a parent-child relationship with other assets.
-So, you could model a building, which contains assets like solar panels, a heat pump and EV chargers.
+So, you could model a building that contains assets like solar panels, a heat pump and EV chargers.
 
 
 Sensors

documentation/features/forecasting.rst

@@ -41,7 +41,7 @@ Here are more details:
 A use case: automating solar production prediction
 -----------------------------------------------------
 
-We'll consider an example which FlexMeasures supports ― forecasting an asset that represents solar panels.
+We'll consider an example that FlexMeasures supports ― forecasting an asset that represents solar panels.
 Here is how you can ask for forecasts to be made in the CLI:
 
 .. code-block:: bash
@@ -50,7 +50,7 @@ Here is how you can ask for forecasts to be made in the CLI:
 
 Sensor 12 would represent the power readings of your solar power, and here you ask for forecasts for one day (2 February, 2024), with a forecast of 6 hours.
 
-The ``--as-job`` parameter is optional, if given the computation becomes a job which a worker needs to pick up. There is some more information at :ref:`how_queue_forecasting`.
+The ``--as-job`` parameter is optional. If given, the computation becomes a job which a worker needs to pick up. There is some more information at :ref:`how_queue_forecasting`.
 
 
 Rolling vs fixed-point

documentation/features/reporting.rst

@@ -7,8 +7,8 @@ FlexMeasures feeds upon raw measurement data (e.g. solar generation) and data fr
 
 However, there are use cases for enriching these raw data by combining them:
 
-- Pre-calculations: E.g. from a tariff and some tax rules we compute the real financial impact of price data.
-- Post-calculations: To be able to show the customer value, we regularly want to compute things like money or CO2 saved.
+- Pre-calculations: For example, from a tariff and some tax rules we compute the real financial impact of price data.
+- Post-calculations: To be able to show the customer value, we regularly want to compute things like money or CO₂ saved.
 
 These calculations can be done with code, but there'll be many repetitions. 
 
@@ -29,7 +29,7 @@ Example: solar feed-in / self-consumption delta
 
 So here is a glimpse into a reporter we made - it is based on the ``AggregatorReporter`` (which is for the combination of any two sensors).
 This simplified example reporter basically calculates ``pv - consumption`` at grid connection point.
-This tells us how much solar power we fed back to the grid (positive values) and/or the amount of grid power within the overall consumption which did not come from local solar panels (negative values).
+This tells us how much solar power we fed back to the grid (positive values) and/or the amount of grid power within the overall consumption that did not come from local solar panels (negative values).
 
 This is the configuration of how the computation works:
 

documentation/features/scheduling.rst

@@ -32,7 +32,7 @@ Let's dive into the details ― what can you tell FlexMeasures about your optimi
 The flex-context
 -----------------
 
-The ``flex-context`` is independent of the type of flexible device which is optimized.
+The ``flex-context`` is independent of the type of flexible device that is optimized.
 With the flexibility context, we aim to describe the system in which the flexible assets operate:
 
 
@@ -48,10 +48,10 @@ With the flexibility context, we aim to describe the system in which the flexibl
      - 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. * Note:* For now, the inflexible-device-sensors need to have MW units. 
    * - ``consumption-price-sensor``
      - ``5``
-     - The sensor which defines the price of consuming energy. This sensor can be recording market prices, but also CO2 - whatever fits your optimization problem. 
+     - The sensor that defines the price of consuming energy. This sensor can be recording market prices, but also CO₂ - whatever fits your optimization problem.
    * - ``production-price-sensor``
      - ``6``
-     - The sensor which defines the price of producing energy.
+     - The sensor that defines the price of producing energy.
    * - ``site-power-capacity``
      - ``"45kW"``
      - Maximum/minimum achievable power at the grid connection point [#asymmetric]_. Defaults to the Asset attribute ``capacity_in_mw``
@@ -84,7 +84,7 @@ You can do a lot with this ― examples for storage devices are:
 - hot water storage ("heat batteries", where the SoC relates to the water temperature)
 - pumped hydro storage (SoC is the water level)
 - water basins (here, SoC is supposed to be low, as water is being pumped out)
-- buffers of energy-intensive chemicals which are needed in other industry processes
+- buffers of energy-intensive chemicals that are needed in other industry processes
 
 
 The ``flex-model`` for storage describes to the scheduler what the flexible asset's state is,
@@ -102,7 +102,7 @@ and what constraints or preferences should be taken into account.
      - The (estimated) state of charge at the beginning of the schedule (defaults to 0).
    * - ``soc-unit``
      - ``"kWh"`` or ``"MWh"``
-     - The unit which all SoC related flex-model values are to be interpreted as.
+     - The unit in which all SoC related flex-model values are to be interpreted.
    * - ``soc-min``
      - ``"2.5"``
      - A constant lower boundary for all values in the schedule (defaults to 0).
@@ -117,7 +117,7 @@ and what constraints or preferences should be taken into account.
      - Set point(s) that form upper boundaries at certain times. Can be single values or a range (defaults to NaN values).
    * - ``soc-targets``
      - ``[{"datetime": "2024-02-05T08:00:00+01:00", value: 3.2}]``
-     - Exact set point(s) which the scheduler needs to realize (defaults to NaN values).
+     - Exact set point(s) that the scheduler needs to realize (defaults to NaN values).
    * - ``soc-gain``
      - ``.1kWh`` 
      - Encode SoC gain per time step. A constant gain every time step, or see [#sensor_field]_.
@@ -149,15 +149,15 @@ and what constraints or preferences should be taken into account.
      - ``0kW`` (only consumption)
      - Device-level power constraint on production. How much power can be supplied by this asset. A constant limit, or see [#sensor_field]_.
 
-.. [#sensor_field] For some fields, it is possible to supply a sensor instead of one fixed value (``{"sensor": 51}``), which allows for more dynamic contexts, for instance power limits which change over time.
+.. [#sensor_field] For some fields, it is possible to supply a sensor instead of one fixed value (``{"sensor": 51}``), which allows for more dynamic contexts, for instance power limits that change over time.
 
 .. [#storage_efficiency] 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`.
 
 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.
 
 You can add new storage schedules with the CLI command ``flexmeasures add schedule for-storage``.
 
-If you model devices which *buffer* energy (e.g. thermal energy storage systems connected to heat pumps), we can use the same flexibility parameters described above for storage devices.
+If you model devices that *buffer* energy (e.g. thermal energy storage systems connected to heat pumps), we can use the same flexibility parameters described above for storage devices.
 However, here are some tips to model a buffer correctly:
 
    - Describe the thermal energy content in kWh or MWh.
@@ -181,7 +181,7 @@ You can also review the current flex-model for storage in the code, at ``flexmea
 Shiftable loads (processes)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-For *processes*, which can be shifted or interrupted, but have to happen at a constant rate (of consumption), FlexMeasures provides the ``ShiftabeLoad`` scheduler.
+For *processes* that can be shifted or interrupted, but have to happen at a constant rate (of consumption), FlexMeasures provides the ``ShiftableLoad`` scheduler.
 Some examples from practice (usually industry) could be:
 
 - A centrifuge's daily work of combing through sludge water. Depends on amount of sludge present.
@@ -223,5 +223,5 @@ We believe the two schedulers (and their flex-models) we describe here are cover
 Here are some thoughts on further innovation:
 
 - Writing your own scheduler. You can always write your own scheduler(see :ref:`plugin_customization`). You then might want to add your own flex model, as well. FlexMeasures will let the scheduler decide which flexibility model is relevant and how it should be validated. 
-- We also aim to model situations with more than one flexible asset, and which have different types of flexibility (e.g. EV charging and smart heating in the same site). This is ongoing architecture design work, and therefore happens in development settings, until we are happy with the outcomes. Thoughts welcome :) 
+- We also aim to model situations with more than one flexible asset, and that have different types of flexibility (e.g. EV charging and smart heating in the same site). This is ongoing architecture design work, and therefore happens in development settings, until we are happy with the outcomes. Thoughts welcome :)
 - Aggregating flexibility of a group of assets (e.g. a neighborhood) and optimizing its aggregated usage (e.g. for grid congestion support) is also an exciting direction for expansion.

documentation/host/deployment.rst

@@ -29,7 +29,7 @@ Often, that requires a WSGI script. Below is a minimal example.
    from flexmeasures.app import create as create_app
    application = create_app()
 
-The web server is told about the WSGI script, but also about the object which represents the application.
+The web server is told about the WSGI script, but also about the object that represents the application.
 For instance, if this script is called wsgi.py, then the relevant argument to the gunicorn server is `wsgi:application`.
 
 A more nuanced one from our practice is this:

documentation/host/installation.rst

@@ -7,7 +7,7 @@ Installation & First steps
 This section walks you through the basics of installing FlexMeasures on a computer and running it continuously.
 
 We'll cover the most crucial settings you need to run FlexMeasures step-by-step, both for `pip`-based installation, as well as running via Docker.
-In addition, we'll explain some basics which you'll need:
+In addition, we'll explain some basics that you'll need:
 
 .. contents:: Table of contents
     :local:
@@ -50,7 +50,8 @@ We'll need to add a few minimal preparations before running will work, see below
 Make a secret key for sessions and password salts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Set a secret key which is used to sign user sessions and re-salt their passwords. The quickest way is with an environment variable, like this:
+Set a secret key, which is used to sign user sessions and re-salt their passwords.
+The quickest way is with an environment variable, like this:
 
 .. tabs::
 
@@ -326,7 +327,7 @@ This obviously depends on some conditions (like the right underlying data) being
 Set mail settings
 ^^^^^^^^^^^^^^^^^
 
-For FlexMeasures to be able to send email to users (e.g. for resetting passwords), you need an email service which can do that (e.g. GMail). Set the MAIL_* settings in your configuration, see :ref:`mail-config`.
+For FlexMeasures to be able to send email to users (e.g. for resetting passwords), you need an email service that can do that (e.g. GMail). Set the MAIL_* settings in your configuration, see :ref:`mail-config`.
 
 .. _install-lp-solver:
 

documentation/index.rst

@@ -3,7 +3,7 @@ Welcome to the FlexMeasures documentation!
 
 FlexMeasures is the intelligent & developer-friendly EMS to support real-time energy flexibility apps, rapidly and scalable.
 
-The problem it helps you to solve is: **What are the best times to run flexible assets, like batteries or heat pumps?**
+The problem it helps you to solve is: **What are the best times to run flexible assets, such as batteries or heat pumps?**
 
 In a nutshell, FlexMeasures turns data into optimized schedules for flexible assets.
 *Why?* Planning ahead allows flexible assets to serve the whole system with their flexibility, e.g. by shifting energy consumption to more optimal times. For the asset owners, this creates CO₂ savings but also monetary value (e.g. through self-consumption, dynamic tariffs and grid incentives).
@@ -13,7 +13,9 @@ In a nutshell, FlexMeasures turns data into optimized schedules for flexible ass
     :align: center
 ..    :scale: 40%
 
-FlexMeasures is written in Python, and runs on Flask and Postgres. We aim to create developer-friendly technology which saves time in developing complex services. Read more on this in :ref:`dev_why`. 
+FlexMeasures is written in Python, and runs on Flask and Postgres.
+We aim to create developer-friendly technology that saves time in developing complex services.
+Read more on this in :ref:`dev_why`.
 
 FlexMeasures proudly is an incubation project at `the Linux Energy Foundation <https://www.lfenergy.org/>`_.
 
@@ -25,7 +27,7 @@ A quick glance
 
     .. tab:: Schedules
 
-        The main purpose of FlexMeasures is to create optimized schedules. Let's have a quick glance how that looks like in the UI:
+        The main purpose of FlexMeasures is to create optimized schedules. Let's have a quick glance at what that looks like in the UI:
 
         .. tabs::
 
@@ -43,7 +45,7 @@ A quick glance
                     :align: center
                 ..    :scale: 40%
 
-        A short explanation: This battery is optimized to buy power cheaply and sell it at expensive times - the red-dotted line is what FlexMeasures computed to be the best schedule, given all knowledge (in this case, the prices shown in blue). However, in the example on the right the battery has to store local solar power as well (orange line), which contrains how much it can do with its capacity (that's why the schedule is limited in capacity and thus cycling less energy overall than on the left).
+        A short explanation: This battery is optimized to buy power cheaply and sell it at expensive times - the red-dotted line is what FlexMeasures computed to be the best schedule, given all knowledge (in this case, the prices shown in blue). However, in the example on the right the battery has to store local solar power as well (orange line), which constrains how much it can do with its capacity (that's why the schedule is limited in capacity and thus cycling less energy overall than on the left).
 
     .. tab:: Example code
 
@@ -81,7 +83,7 @@ What FlexMeasures does
     - Forecasting
         Optimizing the future (by scheduling) requires some predictions.  or consumption. Several predictions can be gotten from third parties (e.g. weather conditions, for which we wrote `a plugin <https://github.com/SeitaBV/flexmeasures-openweathermap>`_), others need to be done manually. FlexMeasures provides some support for this (read more at :ref:`tut_forecasting_scheduling`), but you can also create predictions with one of the many excellent tools out there and feed them into FlexMeasures.
     - Monitoring
-        As FlexMeasures is a real-time platform, processing data and computing new schedules continuously, hosting it requires to be notified when things go wrong. There is in-built :ref:`host_error_monitoring` for tracking connection problems and tasks which did not finish correctly. Also, you can connect to Sentry. We have `further plans to monitor data quality <https://github.com/FlexMeasures/flexmeasures/projects/12>`_.  
+        As FlexMeasures is a real-time platform, processing data and computing new schedules continuously, hosting it requires to be notified when things go wrong. There is in-built :ref:`host_error_monitoring` for tracking connection problems and tasks that did not finish correctly. Also, you can connect to Sentry. We have `further plans to monitor data quality <https://github.com/FlexMeasures/flexmeasures/projects/12>`_.
 
   .. tab:: Interfacing with FlexMeasures
 

documentation/tut/toy-example-process.rst

@@ -18,7 +18,7 @@ Examples of flexible processes are:
 
 
 For consumers under :abbr:`ToU (Time of Use)` tariffs, FlexMeasures `ProcessScheduler` can plan the start time of the process to minimize the overall cost of energy.
-Alternatively, it can create a consumption plan to minimize the CO2 emissions. 
+Alternatively, it can create a consumption plan to minimize the CO₂ emissions.
 
 
 In this tutorial, you'll learn how to schedule processes using three different policies: INFLEXIBLE, BREAKABLE and SHIFTABLE.