Merge branch 'master' into driver-n5245a

.gitignore

@@ -89,4 +89,12 @@ docs/examples/data/*
 .DS_Store
 
 # qcodes related
-experiments.db
+experiments.db
+
+# Do not ignore asv configuration
+!benchmarking/asv.conf.json
+
+# Ignore files generated by asv benchmarking
+benchmarking/env/
+benchmarking/html/
+benchmarking/results/

.travis.yml

@@ -31,13 +31,18 @@ before_script: # configure a headless display to test plot generation
     - sleep 3 # give xvfb some time to start
 
 script:
-    - cd qcodes
-    - py.test --cov=qcodes --cov-report xml --cov-config=.coveragerc
-    # build docs with warnings as errors
     - |
-      cd ..
-      mypy qcodes
-
+      cd qcodes
+      py.test --cov=qcodes --cov-report xml --cov-config=.coveragerc
+    - cd ..
+    - mypy qcodes
+    # run benchmarks to make sure they are correct
+    - |
+      cd benchmarking
+      asv machine --machine travis
+      asv dev --machine travis
+    - cd ..
+    # build docs with warnings as errors
     - |
       cd docs
       make SPHINXOPTS="-W" html-api

benchmarking/README.rst

@@ -0,0 +1,121 @@
+Benchmarking QCoDeS
+===================
+
+This directory contains benchmarks implemented for usage with airspeed
+velocity ``asv`` benchmarking package. Refer to `asv documentation`_ for
+information on how to use it.
+
+.. _asv documentation: https://asv.readthedocs.io/en/stable/index.html
+
+The ``asv.conf.json`` file in this directory configures ``asv`` to work
+correctly with QCoDeS.
+
+Usage
+-----
+
+Run benchmarking
+````````````````
+
+If you already have a python environment set up for QCoDeS, then run the
+following command from this directory:
+
+.. code:: bash
+
+  asv run python=same
+
+If you do not have an environment set, then ``asv`` can set it up
+automatically. The benchmarks are executed in the same way:
+
+.. code:: bash
+
+  asv run
+
+Either of the commands above will execute benchmarking for the latest commit
+of the master branch.
+
+If you want to run benchmarking for a particular commit, use the same syntax
+as there is used for ``git log`` (commit id with ``^!`` at the end; note that in
+some terminals you will need to type ``^`` two times like this ``^^!``):
+
+.. code:: bash
+
+  asv run ed9b6fe8^!
+
+Use the ``--bench`` option with a regular expression to tell ``asv`` which
+benchmarks you would like to execute. For example, use the following syntax
+to execute a benchmark called ``saving`` in ``data.py`` benchmark module:
+
+.. code:: bash
+
+  asv run --bench data.saving
+
+Refer to `asv documentation`_ for more information on the various ways the
+benchmarking can be executed (for example, how to run a particular
+benchmark, how to compare results between commits, etc).
+
+Display benchmarking results
+````````````````````````````
+
+In order to view the benchmarking results, execute the following command
+to generate a convenient website
+
+.. code:: bash
+
+  asv publish
+
+and the following command to start a simple server that could host the
+website locally (the generated website is not static, hence the server is
+needed)
+
+.. code:: bash
+
+  asv preview -b
+
+The ``-b`` option opens the website automatically in your default browser
+(the URL that it opens automatically is also printed to the terminal). In
+order to stop the server, press ``Ctrl+C`` in the terminal where you've
+started it.
+
+Note that the benchmarking results are created locally on your machine, and
+they get accumulated.
+
+In order to compare benchmarking results of two commits, use the following
+command (note that the benchmarking results for these two commits should
+already exist):
+
+.. code:: bash
+
+  asv compare ed859c0a 8984aefb
+
+
+Profile during benchmarking
+```````````````````````````
+
+If you would like to also profile while benchmarking in order to get more
+insights on the performance of the code, use either
+
+.. code:: bash
+
+  asv run --profile
+
+command or
+
+.. code:: bash
+
+  asv profile
+
+command.
+
+In case you would like to use a visualization tool for the profile results,
+you can install one, for example, ``snakeviz``, and run benchmarking with
+profiling as follows:
+
+.. code:: bash
+
+  asv profile --gui=snakeviz
+
+
+ToDo for QCoDeS/core
+--------------------
+
+- host results and their html representation (GitHub pages?)

benchmarking/asv.conf.json

@@ -0,0 +1,141 @@
+{
+    // The version of the config file format.  Do not change, unless
+    // you know what you are doing.
+    "version": 1,
+
+    // The name of the project being benchmarked
+    "project": "Qcodes",
+
+    // The project's homepage
+    "project_url": "http://github.com/QCoDeS/Qcodes",
+
+    // The URL or local path of the source code repository for the
+    // project being benchmarked
+    "repo": "..",
+
+    // List of branches to benchmark. If not provided, defaults to "master"
+    // (for git) or "default" (for mercurial).
+    // "branches": ["master"], // for git
+    // "branches": ["default"],    // for mercurial
+
+    // The DVCS being used.  If not set, it will be automatically
+    // determined from "repo" by looking at the protocol in the URL
+    // (if remote), or by looking for special directories, such as
+    // ".git" (if local).
+    "dvcs": "git",
+
+    // The tool to use to create environments.  May be "conda",
+    // "virtualenv" or other value depending on the plugins in use.
+    // If missing or the empty string, the tool will be automatically
+    // determined by looking for tools on the PATH environment
+    // variable.
+    "environment_type": "conda",
+
+    // timeout in seconds for installing any dependencies in environment
+    // defaults to 10 min
+    //"install_timeout": 600,
+
+    // the base URL to show a commit for the project.
+    "show_commit_url": "https://github.com/QCoDeS/Qcodes/commit/",
+
+    // The Pythons you'd like to test against.  If not provided, defaults
+    // to the current version of Python used to run `asv`.
+    // "pythons": ["2.7", "3.3"],
+
+    // The matrix of dependencies to test.  Each key is the name of a
+    // package (in PyPI) and the values are version numbers.  An empty
+    // list or empty string indicates to just test against the default
+    // (latest) version. null indicates that the package is to not be
+    // installed. If the package to be tested is only available from
+    // PyPi, and the 'environment_type' is conda, then you can preface
+    // the package name by 'pip+', and the package will be installed via
+    // pip (with all the conda available packages installed first,
+    // followed by the pip installed packages).
+    //
+    // "matrix": {
+    //     "numpy": ["1.6", "1.7"],
+    //     "six": ["", null],        // test with and without six installed
+    //     "pip+emcee": [""],   // emcee is only available for install with pip.
+    // },
+
+    // Combinations of libraries/python versions can be excluded/included
+    // from the set to test. Each entry is a dictionary containing additional
+    // key-value pairs to include/exclude.
+    //
+    // An exclude entry excludes entries where all values match. The
+    // values are regexps that should match the whole string.
+    //
+    // An include entry adds an environment. Only the packages listed
+    // are installed. The 'python' key is required. The exclude rules
+    // do not apply to includes.
+    //
+    // In addition to package names, the following keys are available:
+    //
+    // - python
+    //     Python version, as in the *pythons* variable above.
+    // - environment_type
+    //     Environment type, as above.
+    // - sys_platform
+    //     Platform, as in sys.platform. Possible values for the common
+    //     cases: 'linux2', 'win32', 'cygwin', 'darwin'.
+    //
+    // "exclude": [
+    //     {"python": "3.2", "sys_platform": "win32"}, // skip py3.2 on windows
+    //     {"environment_type": "conda", "six": null}, // don't run without six on conda
+    // ],
+    //
+    // "include": [
+    //     // additional env for python2.7
+    //     {"python": "2.7", "numpy": "1.8"},
+    //     // additional env if run on windows+conda
+    //     {"platform": "win32", "environment_type": "conda", "python": "2.7", "libpython": ""},
+    // ],
+
+    // The directory (relative to the current directory) that benchmarks are
+    // stored in.  If not provided, defaults to "benchmarks"
+    "benchmark_dir": "benchmarks",
+
+    // The directory (relative to the current directory) to cache the Python
+    // environments in.  If not provided, defaults to "env"
+    "env_dir": "env",
+
+    // The directory (relative to the current directory) that raw benchmark
+    // results are stored in.  If not provided, defaults to "results".
+    "results_dir": "results",
+
+    // The directory (relative to the current directory) that the html tree
+    // should be written to.  If not provided, defaults to "html".
+    "html_dir": "html",
+
+    // The number of characters to retain in the commit hashes.
+    // "hash_length": 8,
+
+    // `asv` will cache wheels of the recent builds in each
+    // environment, making them faster to install next time.  This is
+    // number of builds to keep, per environment.
+    // "wheel_cache_size": 0
+
+    // The commits after which the regression search in `asv publish`
+    // should start looking for regressions. Dictionary whose keys are
+    // regexps matching to benchmark names, and values corresponding to
+    // the commit (exclusive) after which to start looking for
+    // regressions.  The default is to start from the first commit
+    // with results. If the commit is `null`, regression detection is
+    // skipped for the matching benchmark.
+    //
+    // "regressions_first_commits": {
+    //    "some_benchmark": "352cdf",  // Consider regressions only after this commit
+    //    "another_benchmark": null,   // Skip regression detection altogether
+    // }
+
+    // The thresholds for relative change in results, after which `asv
+    // publish` starts reporting regressions. Dictionary of the same
+    // form as in ``regressions_first_commits``, with values
+    // indicating the thresholds.  If multiple entries match, the
+    // maximum is taken. If no entry matches, the default is 5%.
+    //
+    // "regressions_thresholds": {
+    //    "some_benchmark": 0.01,     // Threshold of 1%
+    //    "another_benchmark": 0.5,   // Threshold of 50%
+    // }
+}

benchmarking/benchmarks/__init__.py

@@ -0,0 +1,4 @@
+"""
+This module contains benchmarks for QCoDeS. These benchmarks shall be executed
+by the `asv` (airspeed velocity) package.
+"""