Merge branch 'release/0.1.5'

Conflicts:
	README.rst

INSTALLATION.md

@@ -0,0 +1,129 @@
+Detailed installation guide for Mac OS X
+========================================
+
+This is a step-by-step guide intended for those unfamiliar with Python or the
+command-line (*a.k.a.* the “shell”).
+
+A shell can be opened by opening a new tab in the Terminal app (located in
+Utilities). Text that is `formatted like code` is meant to be copied and pasted
+into the terminal (hit the Enter key to run the command).
+
+The fist step is to install the versions of Python that we need. The most
+convenient way of doing this is to use the OS X package manager
+[Homebrew](http://brew.sh/). Install Homebrew by running this command:
+
+```bash
+ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+```
+
+Now you should have access to the `brew` command. First, we need to install
+Python 2 and 3. Using these so-called “brewed” Python versions, rather than the
+version of Python that comes with your computer, will protect your computer's
+Python version from unwanted changes that could interfere with other
+applications.
+
+```bash
+brew install python python3
+```
+
+Then we need to ensure that the terminal “knows about” the newly-installed
+Python versions:
+
+```bash
+brew link --overwrite python
+brew link --overwrite python3
+```
+
+Now that we're using our shiny new Python versions, it is highly recommended to
+set up a **virtual environment** in which to install PyPhi. Virtual
+environments allow different projects to isolate their dependencies from one
+another, so that they don't interact in unexpected ways. Please see [this
+guide](http://docs.python-guide.org/en/latest/dev/virtualenvs/) for more
+information.
+
+To do this, you must install `virtualenv` and `virtualenvwrapper`, a [tool for
+manipulating virtual
+environments](http://virtualenvwrapper.readthedocs.org/en/latest/). Both of
+those tools are available on [PyPI](https://pypi.python.org/pypi), the Python
+package index, and can be installed with `pip`, the command-line utility for
+installing and managing Python packages (`pip` was installed automatically with
+the brewed Python):
+
+```bash
+pip install virtualenvwrapper
+```
+
+Now we need to edit your shell startup file. This is a file that runs
+automatically every time you open a new shell (a new window or tab in the
+Terminal app). This file should be in your home directory, though it will be
+invisible in the Finder because the filename is preceded by a period. On most
+Macs it is called `.bash_profile`. You can open this in a text editor by
+running this command:
+
+```bash
+open -a TextEdit ~/.bash_profile
+```
+
+If this doesn't work because the file doesn't exist, then run `touch
+~/.bash_profile` first.
+
+Now, you'll add three lines to the shell startup file. These lines will set the
+location where the virtual environments will live, the location of your
+development project directories, and the location of the script installed with
+this package, respectively. **Note:** The location of the script can be found
+by running `which virtualenvwrapper.sh`.
+
+The filepath after the equals sign on second line will different for everyone,
+but here is an example:
+
+```bash
+export WORKON_HOME=$HOME/.virtualenvs
+export PROJECT_HOME=$HOME/dev
+source /usr/local/bin/virtualenvwrapper.sh
+```
+
+After editing the startup file and saving it, open a new terminal shell by
+opening a new tab or window (or just reload the startup file by running `source
+~/.bash_profile`).
+
+Now that `virtualenvwrapper` is fully installed, use it to create a Python 3
+virtual environment, like so:
+
+```bash
+mkvirtualenv -p `which python3` <name_of_your_project>
+```
+
+The `` -p `which python3 ``\` option ensures that when the virtual environment
+is activated, the commands `python` and `pip` will refer to their Python 3
+counterparts.
+
+The virtual environment should have been activated automatically after creating
+it. It can be manually activated with `workon <name_of_your_project>`, and
+deactivated with `deactivate`.
+
+**Important:** Remember to activate the virtual environment *every time* you
+begin working on your project. Also, note that the currently active virtual
+environment is *not* associated with any particular folder; it is associated
+with a terminal shell.
+
+Finally, you can install PyPhi into your new virtual environment:
+
+```bash
+pip install pyphi
+```
+
+Congratulations, you've just installed PyPhi!
+
+To play around with the software, ensure that you've activated the virtual
+environment with `workon <name_of_your_project>`. Then run `python` to start a
+Python 3 interpreter. Then, in the interpreter's command-line (which is
+preceded by the `>>>` prompt), run
+
+```python
+import pyphi
+```
+
+Please see the documentation for some
+[examples](http://pythonhosted.org/pyphi/#usage-and-examples) and information
+on how to [configure](http://pythonhosted.org/pyphi/#configuration-optional)
+it.

README.rst

@@ -37,66 +37,29 @@ The documentation is also available within the Python interpreter with the
 Installation
 ~~~~~~~~~~~~
 
-Set up a Python 3 virtual environment and install using ``pip install pyphi``.
-
-
-Detailed guide for those unfamiliar with Python
-```````````````````````````````````````````````
-
-This is a Python 3 project, so in order to use it you must install `Python
-3 <https://www.python.org/downloads/>`_.
-
-Once you've installed Python 3, it is highly recommended to set up a **virtual
-environment** in which to install PyPhi. Virtual environments allow different
-projects to isolate their dependencies from one another, so that they don't
-interact in unexpected ways. They also protect your system's version of Python
-from unwanted changes. Please see `this guide
-<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_ for more
-information.
-
-To do this, you must install ``virtualenv`` and ``virtualenvwrapper``, a `tool
-for manipulating virtual environments
-<http://virtualenvwrapper.readthedocs.org/en/latest/>`_. Both of those tools
-are available on `PyPI <https://pypi.python.org/pypi>`_, the Python package
-index, and can be installed with ``pip``, the command-line utility for
-installing and managing Python packages (``pip`` is installed automatically
-with Python):
+Set up a Python 3 virtual environment and install with
 
 .. code:: bash
 
-    pip install virtualenv virtualenvwrapper
+    pip install pyphi
 
-Then use ``virtualenvwrapper`` to create a Python 3 virtual environment, like
-so:
+To install the latest development version, which is a work in progress and may
+have bugs, instead run:
 
 .. code:: bash
 
-    mkvirtualenv -p `which python3` <name_of_your_project>
-
-The ``-p `which python3``` option ensures that when the virtual environment is
-activated, the commands ``python`` and ``pip`` will refer to their Python 3
-counterparts.
-
-The virtual environment should have been activated automatically after creating
-it. It can be manually activated with ``workon <name_of_your_project>``, and
-deactivated with ``deactivate``.
-
-Remember to activate the virtual environment *every time* you begin working on
-your project. Also, note that the currently active virtual environment is *not*
-associated with any particular folder; it is associated with a terminal shell.
-
-Finally, you can install PyPhi into your new virtual environment:
-
-.. code:: bash
+    pip install "git+https://github.com/wmayner/pyphi@develop#egg=pyphi"
 
-    pip install pyphi
+**Note:** this software has only been tested on the Mac OS X and Linux
+operating systems. Windows is not supported, though it might work on with minor
+modifications. If you do get it to work, a writeup of the steps would be much
+appreciated!
 
-To install the latest development version (which is a work in progress and may
-have bugs):
 
-.. code:: bash
+Detailed installation guide for Mac OS X
+````````````````````````````````````````
 
-    pip install "git+https://github.com/wmayner/pyphi@develop#egg=pyphi"
+`See here <https://github.com/wmayner/pyphi/blob/develop/INSTALLATION.md>`_.
 
 
 Optional: caching with a database

conftest.py

@@ -15,16 +15,20 @@
 ]
 
 
-# Run slow tests separately with command-line option
-# ==================================================
+# Run slow tests separately with command-line option, filter tests
+# ================================================================
 
 def pytest_addoption(parser):
+    parser.addoption("--filter", action="store_true",
+                     help="run only tests marked with 'filter'")
     parser.addoption("--slow", action="store_true", help="run slow tests")
     parser.addoption("--veryslow", action="store_true",
                      help="run very slow tests")
 
 
 def pytest_runtest_setup(item):
+    if 'filter' not in item.keywords and item.config.getoption("--filter"):
+        pytest.skip("only running tests with 'filter' mark")
     if 'slow' in item.keywords and not item.config.getoption("--slow"):
         pytest.skip("need --slow option to run")
     if 'veryslow' in item.keywords and not item.config.getoption("--veryslow"):

pyphi/__init__.py

@@ -42,7 +42,7 @@
 """
 
 __title__ = 'pyphi'
-__version__ = '0.1.4'
+__version__ = '0.1.5'
 __description__ = 'Python library for computing integrated information.',
 __author__ = 'Will Mayner'
 __author_email__ = 'wmayner@gmail.com'

pyphi/compute.py

@@ -238,6 +238,9 @@ def _evaluate_partition(uncut_subsystem, partition,
         partitioned_constellation=forward_constellation,
         subsystem=uncut_subsystem,
         cut_subsystem=forward_cut_subsystem)
+    # Short-circuit if the forward MIP has no Phi.
+    if utils.phi_eq(forward_mip.phi, 0):
+        return forward_mip
     # Compute backward mip.
     backward_cut = Cut(partition[1], partition[0])
     backward_cut_subsystem = Subsystem(uncut_subsystem.node_indices,

pyphi/examples.py

@@ -5,10 +5,10 @@
 Usage and Examples
 ~~~~~~~~~~~~~~~~~~
 
-The :class:`pyphi.Network` object is the main object on which computations are
+The :class:`pyphi.network` object is the main object on which computations are
 performed. It represents the network of interest.
 
-The :class:`pyphi.Subsystem` object is the secondary object; it represents a
+The :class:`pyphi.subsystem` object is the secondary object; it represents a
 subsystem of a network. |big_phi| is defined on subsystems.
 
 The :mod:`pyphi.compute` module is the main entry-point for the library. It
@@ -21,7 +21,7 @@
 
 To make a network, we need a TPM, current state, past state, and optionally a
 connectivity matrix. The TPM can be in more than one form; see the
-documentation for :class:`pyphi.Network`. Here we'll use the 2-dimensional
+documentation for :class:`pyphi.network`. Here we'll use the 2-dimensional
 state-by-node form.
 
     >>> import pyphi
@@ -112,7 +112,7 @@ def network():
     +--------------+---------------+
     | Past state   | Current state |
     +--------------+---------------+
-    |   A, B, C    |    C, B, A    |
+    |   C, B, A    |    A, B, C    |
     +==============+===============+
     |  {0, 0, 0}   |   {0, 0, 0}   |
     +--------------+---------------+

pyphi/network.py

@@ -45,19 +45,18 @@ class Network:
         tpm (np.ndarray):
             The transition probability matrix that encodes the network's
             mechanism. It can be provided in either state-by-node or
-            state-by-state form. In state-by-state form, decimal indices must
-            correspond to states so that lower-order bits of the binary
-            representation of the index give the state of low-index nodes. See
-            :func:`utils.state_by_state2state_by_node` for more info. If given
-            in state-by-node form, it can be either 2-dimensional, so that
-            ``tpm[i]`` gives the probabilities of each node being on if the
-            past state is given by the binary representation of |i|, or in N-D
-            form, so that ``tpm[0][1][0]`` gives the probabilities of each node
-            being on if the past state is |0,1,0|. The shape of the
+            state-by-state form. In state-by-state form, row *and* column
+            indices must follow the **HOLI** convention (see note below). If
+            given in state-by-node form, it can be either 2-dimensional, so
+            that ``tpm[i]`` gives the probabilities of each node being on if
+            the past state is given by the binary representation of |i|, where
+            ``i`` represents a state according to the **LOLI** convention, or
+            in N-D form, so that ``tpm[0][1][0]`` gives the probabilities of
+            each node being on if the past state is |0,1,0|. The shape of the
             2-dimensional form of the TPM must be ``(S, N)``, and the shape of
-            the N-D form of the TPM must be ``[2]
-            * N + [N]``, where ``S`` is the number of states and ``N`` is the
-            number of nodes in the network.
+            the N-D form of the TPM must be ``[2] * N + [N]``, where ``S`` is
+            the number of states and ``N`` is the number of nodes in the
+            network.
         current_state (tuple):
             The current state of the network. ``current_state[i]`` gives the
             current state of node |i|.
@@ -71,6 +70,20 @@ class Network:
             The number of nodes in the network.
         num_states (int):
             The number of possible states of the network.
+
+    .. note::
+        Throughout PyPhi, when decimal indices of state-by-node TPM **rows**
+        are used to represent the state of a set of binary nodes, the indices
+        follow the **LOLI** convention: low-order bits of the binary
+        representation of the index correspond to low-index nodes. The
+        rationale is that this low-order to low-index mapping is stable under
+        changes in the number of nodes, in the sense that the same bit always
+        corresponds to the same node index.
+
+    .. note::
+        Column indices still use the more intuitive **HOLI** convention, so that
+        when the row is read as a state-tuple, the index of the node gives the
+        state of that node.
     """
 
     def __init__(self, tpm, current_state, past_state,