update docs

README.rst

@@ -22,7 +22,9 @@ Examples
 ---------
 
 `Using Huang auction <examples/Huang.ipynb>`_
+
 `Using P2P trading <examples/P2P.ipynb>`_
+
 `Using MUDA auction <examples/MUDA.ipynb>`_
 
 Features

docs/conf.py

@@ -85,7 +85,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'classic'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the

docs/index.rst

@@ -1,12 +1,27 @@
-Welcome to pymarket's documentation!
+Welcome to PyMarket's documentation!
 ======================================
 
+PyMarket is a python library designed to ease the simulation and
+comparison of different market mechanisms.
+
+Marketplaces can be proposed to solve a diverse array of problems. They
+are used to sell ads online, bandwith spectrum, energy, etc.
+PyMarket provides a simple environment to try, simulate and compare different
+market mechanisms, a task that is inherent to the process of establishing a new
+market.
+
+As an example, Local Energy Markets (LEMs) have been proposed to syncronize energy consumption
+with surplus of renewable generation. Several mechanisms have been proposed for such a market:
+from double sided auctions to p2p trading. 
+
+This library aims to provide a simple interface for such process, making results reproducible.
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
-   readme
    installation
+   quickstart
    usage
    modules
    contributing

docs/installation.rst

@@ -22,6 +22,8 @@ you through the process.
 .. _pip: https://pip.pypa.io
 .. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
 
+.. warning::
+    Python `3.6 >=` is required. PyMarket won't run on Python 2.
 
 From sources
 ------------

docs/pymarket.datasets.rst

@@ -0,0 +1,22 @@
+pymarket.datasets package
+=========================
+
+Submodules
+----------
+
+pymarket.datasets.uniform\_bidders module
+-----------------------------------------
+
+.. automodule:: pymarket.datasets.uniform_bidders
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: pymarket.datasets
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/pymarket.rst

@@ -7,6 +7,7 @@ Subpackages
 .. toctree::
 
     pymarket.bids
+    pymarket.datasets
     pymarket.mechanisms
     pymarket.plot
     pymarket.statistics

docs/quickstart.rst

@@ -0,0 +1,21 @@
+=====
+Quickstart
+=====
+
+A minimal example
+------------------
+
+.. code:: python
+
+    import pymarket as pm
+
+    mar = pm.Market() # Creates a new market
+
+    mar.accept_bid(1, 2, 0, True) # User 0 want to buy (True) 1 unit at price 2 
+    mar.accept_bid(2, 1, 1, False) # User 1 wants to sell (False) 2 units at price 2
+
+    transactions, extras = mar.run('p2p') # run the p2p mechanism with the 2 bids
+
+    df = transactions.get_df() # obtain a dataframe with the summary of all transactions
+
+

examples/Huang.ipynb

@@ -2,43 +2,32 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 4,
    "metadata": {},
-   "outputs": [
-    {
-     "ename": "NameError",
-     "evalue": "name '__file__' is not defined",
-     "output_type": "error",
-     "traceback": [
-      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
-      "\u001b[0;31mNameError\u001b[0m                                 Traceback (most recent call last)",
-      "\u001b[0;32m<ipython-input-8-186417d02eaa>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m      2\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mos\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mpath\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      3\u001b[0m sys.path.append(\n\u001b[0;32m----> 4\u001b[0;31m     os.path.abspath(os.path.join(os.path.dirname(__file__), os.path.pardir)))\n\u001b[0m",
-      "\u001b[0;31mNameError\u001b[0m: name '__file__' is not defined"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
+    "import os\n",
     "import sys\n",
-    "import os.path\n",
-    "sys.path.append(\n",
-    "    os.path.abspath(os.path.join(os.path.dirname(__file__), os.path.pardir)))"
+    "module_path = os.path.abspath(os.path.join('..'))\n",
+    "if module_path not in sys.path:\n",
+    "    sys.path.append(module_path)"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [
     {
-     "ename": "ModuleNotFoundError",
-     "evalue": "No module named 'pymarket.bids'",
+     "ename": "ImportError",
+     "evalue": "cannot import name 'bids'",
      "output_type": "error",
      "traceback": [
       "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
-      "\u001b[0;31mModuleNotFoundError\u001b[0m                       Traceback (most recent call last)",
-      "\u001b[0;32m<ipython-input-7-a081262fc3c3>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m      4\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mmatplotlib\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mpyplot\u001b[0m \u001b[0;32mas\u001b[0m \u001b[0mplt\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      5\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mnetworkx\u001b[0m \u001b[0;32mas\u001b[0m \u001b[0mnx\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 6\u001b[0;31m \u001b[0;32mfrom\u001b[0m \u001b[0mpymarket\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mMarket\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      7\u001b[0m \u001b[0;32mfrom\u001b[0m \u001b[0mpymarket\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mbids\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mdemand_curves\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mdemand_curve_from_bids\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0msupply_curve_from_bids\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      8\u001b[0m \u001b[0;32mfrom\u001b[0m \u001b[0mpymarket\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mplot\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mplot_demand_curves\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
-      "\u001b[0;32m~/anaconda3/lib/python3.6/site-packages/pymarket-0.5.5-py3.6.egg/pymarket/__init__.py\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0;31m# -*- coding: utf-8 -*-\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      2\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 3\u001b[0;31m \u001b[0;32mimport\u001b[0m \u001b[0mpymarket\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mbids\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      4\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mpymarket\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mmechanisms\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      5\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mpymarket\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mstatistics\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
-      "\u001b[0;31mModuleNotFoundError\u001b[0m: No module named 'pymarket.bids'"
+      "\u001b[0;31mImportError\u001b[0m                               Traceback (most recent call last)",
+      "\u001b[0;32m<ipython-input-2-c61d1654b14e>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m      4\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mmatplotlib\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mpyplot\u001b[0m \u001b[0;32mas\u001b[0m \u001b[0mplt\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      5\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mnetworkx\u001b[0m \u001b[0;32mas\u001b[0m \u001b[0mnx\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 6\u001b[0;31m \u001b[0;32mimport\u001b[0m \u001b[0mpymarket\u001b[0m \u001b[0;32mas\u001b[0m \u001b[0mpm\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      7\u001b[0m \u001b[0;31m#from pymarket import Market\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      8\u001b[0m \u001b[0;31m#from pymarket.bids.demand_curves import demand_curve_from_bids, supply_curve_from_bids\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
+      "\u001b[0;32m~/anaconda3/lib/python3.6/site-packages/pymarket-0.5.5-py3.6.egg/pymarket/__init__.py\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m      2\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      3\u001b[0m \u001b[0;31m#import pymarket.bids\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 4\u001b[0;31m \u001b[0;32mfrom\u001b[0m \u001b[0;34m.\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mbids\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      5\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mpymarket\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mmechanisms\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      6\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mpymarket\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mstatistics\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
+      "\u001b[0;31mImportError\u001b[0m: cannot import name 'bids'"
      ]
     }
    ],
@@ -48,9 +37,10 @@
     "import pandas as pd\n",
     "import matplotlib.pyplot as plt\n",
     "import networkx as nx\n",
-    "from pymarket import Market\n",
-    "from pymarket.bids.demand_curves import demand_curve_from_bids, supply_curve_from_bids\n",
-    "from pymarket.plot import plot_demand_curves"
+    "import pymarket as pm\n",
+    "#from pymarket import Market\n",
+    "#from pymarket.bids.demand_curves import demand_curve_from_bids, supply_curve_from_bids\n",
+    "#from pymarket.plot import plot_demand_curves"
    ]
   },
   {

examples/MUDA.ipynb

@@ -11,9 +11,7 @@
     "import pandas as pd\n",
     "import matplotlib.pyplot as plt\n",
     "import networkx as nx\n",
-    "from pymarket import Market\n",
-    "from pymarket.bids.demand_curves import demand_curve_from_bids, supply_curve_from_bids\n",
-    "from pymarket.plot import plot_demand_curves"
+    "import pymarket as pm"
    ]
   },
   {
@@ -30,7 +28,7 @@
    "outputs": [],
    "source": [
     "r = np.random.RandomState(1234)\n",
-    "mar = Market()\n",
+    "mar = pm.Market()\n",
     "    \n",
     "mar.accept_bid(1, 6.7, 0, True, 0)\n",
     "mar.accept_bid(1, 6.6, 1, True, 0)\n",
@@ -88,7 +86,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {
@@ -162,7 +160,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 5,
    "metadata": {},
    "outputs": [
     {
@@ -178,7 +176,7 @@
        "0.6666666666659999"
       ]
      },
-     "execution_count": 6,
+     "execution_count": 5,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -190,7 +188,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 6,
    "metadata": {},
    "outputs": [
     {
@@ -206,7 +204,7 @@
        "0.7906976744186046"
       ]
      },
-     "execution_count": 7,
+     "execution_count": 6,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -218,7 +216,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 7,
    "metadata": {},
    "outputs": [
     {
@@ -248,7 +246,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [
     {