extended documentation (#229)

* extended overview section

* typos

* typos

* further enhancement of overview

* added glossary

* moved things from readme to glossary

* mention notebooks

README.rst

@@ -3,12 +3,12 @@
 RidePy
 ======
 
-Simulates a dispatching algorithm serving exogenous transportation
-requests with a fleet of vehicles. Does not simulate the universe,
-unlike MATSim. Batteries are included.
+Simulates a dispatching algorithm serving exogenous transportation requests with a fleet of vehicles. Does not simulate the universe, unlike MATSim. Batteries are included.
+
+The extensive documentation is available at `ridepy.org <https://ridepy.org/>`__. This includes a high-level `overview <https://ridepy.org/overview>`__, as well as a `glossary <https://ridepy.org/glossary>`__ and a detailed `reference <https://ridepy.org/reference>`__.
+
+The source code is hosted on `GitHub <https://github.com/PhysicsOfMobility/ridepy>`__.
 
-The documentation is available at `ridepy.org <https://ridepy.org/>`__,
-the source code is hosted on `GitHub <https://github.com/PhysicsOfMobility/ridepy>`__.
 
 Instructions
 ------------
@@ -71,6 +71,7 @@ Developer Installation
 
 The built documentation can be found in ``doc/_build/html/index.html``.
 
+.. _first_steps:
 
 First Steps
 -----------
@@ -131,32 +132,6 @@ Testing
    innocent-looking files named ``conftest.py``. See docs on
    `conftest <https://docs.pytest.org/en/2.7.3/plugins.html>`__.
 
-Principles
-----------
-
-Jargon
-~~~~~~
-
--  **estimated arrival time**, also Cached Predicted Arrival Time CPAT
--  **time window min**, also Earliest Allowed Service Time EAST
--  **time window max**, also Latest Allowed Service Time LAST
--  **stoplist**, a sequence of scheduled stops that a transporter must
-   *service*, i.e. perform the action defined in the respective stop's
-   ``Stop.action``
--  The dummy stop **current position element CPE** always must be the first
-   entry of each stoplist. It is used to denote the current location of the
-   transporter.
--  Transporter, the same as vehicle, bus, or car
-
-General Things
-~~~~~~~~~~~~~~
-
--  The **dispatcher** is responsible for keeping the state of the stoplists
-   valid. This includes recomputing the estimated arrival times and
-   making sure that the order of the stops in the stoplist follows the
-   order of the estimated arrival times. It also means managing the
-   CPE.
-
 
 .. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black

doc/glossary.rst

@@ -0,0 +1,38 @@
+Glossary
+========
+
+.. glossary::
+    :sorted:
+
+    estimated arrival time
+        Property of each stop. It is the time at which the vehicle was expected to reach the stop at the latest insertion of any stop (at which point the times are updated by the dispatcher).
+
+        Legacy synonym: Cached Predicted Arrival Time (``CPAT``).
+
+    time window min
+        The earliest time at which a stop can be served.
+
+        Legacy synonym: Earliest Allowed Service Time (``EAST``).
+
+    time window max
+        The maximum service time beyond which a stop may not be delayed.
+
+        Legacy synonym: Latest Allowed Service Time (``LAST``).
+
+    current position element
+        ``CPE``, dummy stop. It must always be the first entry of each valid stoplist. It denotes the current position of the vehicle.
+
+    vehicle
+        A transporter. In reality, this could be a transit bus or a passenger car. The primary representation of a vehicle in the framework is a stoplist.
+
+    fleet
+        A set of transporters.
+
+    dispatcher
+        Algorithm that schedules the stops. In essence, the dispatcher is a mapping of an existing stoplist and a transportation request onto a modified stoplist and a cost of insertion/service.
+
+        Note that the dispatcher is responsible for keeping the state of the stoplists valid. This includes recomputing the estimated arrival times and making sure that the order of the stops in the stoplist follows the order of the estimated arrival times. It also means managing the CPE.
+
+    stoplist
+        Ordered list of stops that define the route of a vehicle. The first element is the current position element (``CPE``), the other stops represent pick-up or drop-off of requests (passengers).
+

doc/index.rst

@@ -14,6 +14,7 @@ Welcome to ridepy's documentation!
 
    overview
    reference
+   glossary
 
 Indices and tables
 ==================

doc/overview.rst

@@ -3,34 +3,26 @@ Overview
 
 .. highlight:: python
 
-Here we describe the design of ridepy, and how to get started with using
-it to run simulations. We also describe how to specify new dispatching
-algorithms and new transport spaces.
+RidePy is a Python library that performs mobility simulations; in particular, it is able to simulate on-demand transit services such as ride hailing (taxicab-like operations) and ridepooling (trips of similar origin, destination, and time are served by the same vehicle). RidePy provides an interface that allows researchers to replicate the operation of such transport systems and thus study their properties and behavior without actually transporting passengers in the real world.
 
+Getting started with RidePy is easy: The user just has to choose a way of generating the virtual customers' requests for transportation and set up a transportation service by specifying its characteristics (e.g., number of vehicles, dispatching algorithm, additional constraints). RidePy will simulate the operation of the service and log all events, e.g., the pick-up of a customer or the submission of a new request. After the simulation has finished, RidePy can additionally provide structured information about the details of the simulation run. These data can then be analyzed further by the user to gain insights into the behavior of the simulated service.
+
+In this chapter, we describe the design of RidePy, and how to get started using it to run simulations. We also describe how to specify new dispatching algorithms and new transport spaces.
 
 
 The setting
 -----------
-ridepy does *not* do agent-based simulations. Rather, it starts with a set of
-*transportation requests* (denoting the desire of an individual to be transported from A
-to B within specified time windows), and a *dispatcher* (an algorithm that determines
-which vehicle should service which requests and in which order). Then it simply
-simulates these requests arriving in the system, being picked up and delivered. Requests
-that cannot be delivered within the specified time windows are *rejected*.
-
-ridepy makes it easy to experiment with different dispatching algorithms,
-spatiotemporal request densities, fleet sizes and transport spaces (2-D plane, different
-graphs). It comes with an `analytics` module that computes from the simulation output
-various metrics like the statistical distributions of occupancies, waiting times and
-detours.
-
-Since the ability to simulate many *requests* and many *vehicles* is important for any
-quantitative study, we include two powerful ways of speeding up the simulation:
+
+Rather than explicitly modeling the behavior of individuals (classic agent-based simulations), RidePy instead starts with a set of *transportation requests* (denoting the desire of an individual to be transported from A to B within a specified time window), and a *dispatcher* (an algorithm that determines which vehicle should service which requests and in which order). Then it simply simulates these requests arriving in the system, being picked up, and being delivered. Requests that cannot be delivered within the specified time windows are *rejected*.
+
+RidePy makes it easy to experiment with different dispatching algorithms, spatio-temporal request densities, fleet sizes and transport spaces (2-D plane, different graphs). It comes with an `analytics` module that computes from the simulation output various metrics like the statistical distributions of occupancies, waiting times, and detours.
+
+Since the ability to simulate many *requests* and many *vehicles* is important for any quantitative study, we include two powerful ways of speeding up the simulation:
 
 Using parallelism:
    The dispatcher interface prescribes computing a *cost* for serving a request with a
    certain vehicle. Then the vehicle with the minimum cost is chosen. Since this is an
-   "embarassingly parallelizable" operation, ridepy provides two parallel ways of
+   "embarassingly parallelizable" operation, RidePy provides two parallel ways of
    computing it, out of the box:
 
    - ``multiprocessing``,
@@ -44,12 +36,17 @@ Using `cython <https://cython.readthedocs.io/en/latest/>`_:
 
 Quickstart
 ----------
+
 Here we will demonstrate how to run a simple simulation.
 
+Note that several introductory notebooks for easy experimentation are available in the ``notebooks`` directory in the git repository, see also :ref:`first steps <first_steps>`.
+
 Generate requests
 ^^^^^^^^^^^^^^^^^
+
 First we need to generate a sequence of :class:`TransportationRequest
 <data_structures.TransportationRequest>`. Each ``TransportationRequest`` consists of:
+
   - ``origin``,
   - ``destination``,
   - ``pickup_timewindow_min``,
@@ -86,6 +83,7 @@ will be run.
 
 Create a ``FleetState`` with a single vehicle
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 We will now create a :class:`FleetState <fleet_state.FleetState>` with the
 desired number of vehicles, the initial positions of the vehicles, and a
 ``dispatcher`` that matches a request to a vehicle.
@@ -109,6 +107,7 @@ own.
 
 Now, simulate
 ^^^^^^^^^^^^^
+
 ...by calling the :meth:`FleetState.simulate <fleet_state.FleetState.simulate>` method.
 The output of the simulation run is an :any:`Iterator <python:collections.abc.Iterator>`
 of ``Event`` objects, describing when which ``TransportationRequest`` was picked up and
@@ -131,7 +130,8 @@ delivered.
 
 Using parallelism
 -----------------
-Running ridepy in a multi-node OpenMPI cluster is as simple as replacing
+
+Running RidePy in a multi-node OpenMPI cluster is as simple as replacing
 :class:`SlowSimpleFleetState <fleet_state.SlowSimpleFleetState>` with
 :class:`MPIFuturesFleetState <fleet_state.MPIFuturesFleetState>`:
 
@@ -154,6 +154,7 @@ Running ridepy in a multi-node OpenMPI cluster is as simple as replacing
 
 Using cythonized data structures and algorithms
 -----------------------------------------------
+
 The simulation we saw can be sped up considerably by using a cythonized version of the
 dispatcher, with the core logic implemented in C++. We will also need to use cythonized
 versions of ``TransportationRequest``, ``Stop``, ``VehicleState`` and a
@@ -203,13 +204,15 @@ versions of ``TransportationRequest``, ``Stop``, ``VehicleState`` and a
    print(events)
 
 
-How to write your own dispatcher
----------------------------------
+..
+   How to write your own dispatcher
+   ---------------------------------
 
 
 
-How to write your own ``TransportSpace``
------------------------------------------
+..
+   How to write your own ``TransportSpace``
+   -----------------------------------------