first version of the toy scheduling tutorial

documentation/dev/data.rst

@@ -1,6 +1,6 @@
 .. _dev-data:
 
-Handling data
+Handling databases
 =============================
 
 This document describes how to get the postgres database ready to use and maintain it (do migrations / changes to the structure).
@@ -210,17 +210,18 @@ You can create some pre-determined asset types and data sources with this comman
 
 .. code-block:: bash
 
-   flexmeasures add structure
+   flexmeasures add initial-structure
 
+You can also create assets in the FlexMeasures UI.
 
-.. todo:: We should instead offer CLI commands to be able to create asset types as needed.
+On the command line, you can add many things. Check what data you can add yourself:
 
-You can create assets in the FlexMeasures UI.
+.. code-block:: bash
+
+   flexmeasures add --help
 
-.. todo:: Maybe a CLI command would help to script all data creation.
-.. todo:: We still need a decent way to load in metering data, e.g. from CSV - often, a custom loading script will be necessary anyways.
 
-You can create forecasts for your existing metered data with this command:
+For instance, you can create forecasts for your existing metered data with this command:
 
 .. code-block:: bash
 
@@ -230,13 +231,11 @@ You can create forecasts for your existing metered data with this command:
 Check out it's ``--help`` content to learn more. You can set which assets and which time window you want to forecast. Of course, making forecasts takes a while for a larger dataset.
 You can also simply queue a job with this command (and run a worker to process the :ref:`redis-queue`).
 
-Just to note, there are also commands to get rid of data, such as:
+Just to note, there are also commands to get rid of data. Check:
 
 .. code-block:: bash
 
-   flexmeasures delete structure
-   flexmeasures delete measurements
-   flexmeasures delete forecasts
+   flexmeasures delete --help
 
 Check out the :ref:`cli` documentation for more details.
 

documentation/getting-started.rst

@@ -6,9 +6,9 @@ Getting started
 Quickstart
 ----------
 
-This section walks you through getting FlexMeasures to run with the least effort. We'll cover making a secret key, connecting a database and creating one user & one asset.
+This section walks you through getting FlexMeasures to run. For an example with the least effort, see :ref:`tut_toy_schedule`. Here, we'll cover getting started with an installation you run continuously ― making a secret key, connecting a database and creating one user & one asset.
 
-.. note:: Are you not hosting FlexMeasures, but want to learn how to use it? Head over to our tutorials, starting with :ref:`tut_posting_data`.
+.. note:: Are you not hosting FlexMeasures, but want to learn how to interact with it? Start with :ref:`tut_posting_data`.
 
 .. warning:: Are you implementing code based on FlexMeasures, please read :ref:`note_on_datamodel_transition`.
 
@@ -127,7 +127,7 @@ Populate the database with some standard asset types, user roles etc.:
 
 .. code-block::
 
-   flexmeasures add structure
+   flexmeasures add initial-structure
 
 
 Add your first asset

documentation/index.rst

@@ -1,46 +1,77 @@
 Welcome to the FlexMeasures documentation!
 ===================================================================
 
-In a world with renewable energy, flexibility is crucial and valuable.
+*FlexMeasures is the intelligent & developer-friendly backend to support real-time energy flexibility apps, rapidly and scalable.*
+
+In a world with renewable energy, flexibility is crucial and valuable, e.g. for demand response.
 Planning ahead allows flexible assets to serve the whole system with their flexibility,
 e.g. by shifting or curtailing energy use.
-This can also be profitable for their owners.
 
-The *FlexMeasures Platform* is the intelligent backend to support real-time energy flexibility apps, rapidly and scalable. 
+Developing energy flexibility services is expensive work. FlexMeasures is designed to be developer-friendly, which helps you to go to market quickly, while keeping the costs of software development at bay. FlexMeasures delivers:
+
+- Real-time data intelligence & integration
+- Uncertainty models
+- App-building (API/UI/CLI & plugin support)
+
+
+A quick glance at usage
+------------------------
+
+A tiny, but complete example: Let's install FlexMeasures from scratch. Then, using only the terminal, load hourly prices and optimize a 12h-schedule for a battery that is half full at the beginning.
+
+.. code-block:: bash
+
+    pip install flexmeasures
+    docker pull postgres; docker run --name pg-docker -e POSTGRES_PASSWORD=docker -e POSTGRES_DB=flexmeasures-db -d -p 5433:5432 postgres:latest 
+    export SQLALCHEMY_DATABASE_URI="postgresql://postgres:docker@127.0.0.1:5433/flexmeasures-db" && export SECRET_KEY=notsecret 
+    flexmeasures db upgrade  # create tables
+    flexmeasures add toy-account --kind battery  # setup account & a user, a battery (Id 2) and a market (Id 3)
+    flexmeasures add beliefs --sensor-id 3 --source toy-user prices-tomorrow.csv  # load prices, also possible per API
+    flexmeasures add schedule --sensor-id 2 --factor-id 3 \
+        --from ${TOMORROW}T07:00+01:00 --duration PT12H \
+        --soc-at-start 50 --roundtrip-efficiency 90  # this is also possible per API
+    flexmeasures show beliefs --sensor-id 2 --from ${TOMORROW}T07:00:00+01:00 --duration PT12H  # also visible per UI, of course
+
+We discuss this in more depth at :ref:`tut_toy_schedule`.
+
+
+Use cases
+-----------
 
-- Developing energy flexibility services (e.g. to enable demand response) is crucial, but expensive.
-- FlexMeasures reduces development costs with real-time data integrations, uncertainty models and API/UI support.
+As possible users, we see energy service companies (ESCOs) who want to build real-time apps & services around energy flexibility for their customers, or medium/large industrials who are looking for support in their internal digital tooling.
 
-As possible users, we see energy service companies (ESCOs) who want to build real-time apps & services around energy flexibility for their customers, or medium/large industrials who are looking for support in their internal digital tooling. However, even small companies and hobby projects might find FlexMeasures useful! 
+However, even small companies and hobby projects might find FlexMeasures useful! 
 
-Let's take a closer look at the three core values:
 
+The three ways in which FlexMeasures supports developers:
+---------------------------------------------------------
 
 Real-time data intelligence & integration
------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Energy flexibility services need to interact multiple times per day or hour. We equipped FlexMeasures with:
 
 - Support for real-time updates
 - Forecasting for the upcoming hours
 - Schedule optimization
+- Extensions for integrating data, e.g. from `ENTSO-E <https://github.com/SeitaBV/flexmeasures-entsoe>`_ or `OpenWeatherMap <https://github.com/SeitaBV/flexmeasures-openweathermap>`_
 
 
 Uncertainty models
------------------------
+^^^^^^^^^^^^^^^^^^^^
 
 Dealing with uncertain forecasts and outcomes is crucial.
 
 FlexMeasures is therefore built on the `timely-beliefs framework <https://github.com/SeitaBV/timely-beliefs>`_, so we model this real-world aspect accurately.
 
 
-Service building
------------------------
-Building customer-facing services is where developers make impact. We make their work easy.
+App building
+^^^^^^^^^^^^^^^^^^
+Building customer-facing apps & services is where developers make impact. We make their work easy.
 
-- Well-documented API
-- Plugin support
-- Plotting support
+- Well-documented API and CLI
+- Plugin support (add your own logic)
+- Backend UI and support for plotting
 - Multi-tenancy
 
 
@@ -80,6 +111,7 @@ The platform operator of FlexMeasures can be an Aggregator.
     :caption: Tutorials
     :maxdepth: 1
 
+    tut/toy-example-from-scratch
     tut/posting_data
     tut/forecasting_scheduling
     tut/building_uis