PyPhi¶

IIT 3.0 Paper (2014)¶

This section is meant to serve as a companion to the paper From the Phenomenology to the Mechanisms of Consciousness: Integrated Information Theory 3.0 by Oizumi, Albantakis, and Tononi, and as a demonstration of how to use PyPhi. Readers are encouraged to follow along and analyze the systems shown in the figures, hopefully becoming more familiar with both the theory and the software in the process.

First, start a Python 3 REPL by running python3 on the command line. Then import PyPhi and NumPy:

>>> import pyphi
>>> import numpy as np

>>> tpm = np.array([
...     [0, 0, 0, 0, 0, 0],
...     [0, 0, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 0, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 1, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 1, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 0, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 0, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 1, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 1, 0, 0, 1, 0],
...     [0, 0, 0, 0, 0, 0],
...     [0, 0, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 0, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 1, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 1, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 0, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 0, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 1, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 1, 0, 0, 1, 0],
...     [0, 0, 0, 0, 0, 0],
...     [0, 0, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 0, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 1, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 1, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 0, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 0, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 1, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 1, 0, 0, 1, 0],
...     [0, 0, 0, 0, 0, 0],
...     [0, 0, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 0, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 1, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 1, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 0, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 0, 0, 0, 1, 0],
...     [1, 0, 0, 0, 0, 0],
...     [1, 1, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 1, 0, 0, 1, 0]
... ])

>>> cm = np.array([
...     [0, 1, 1, 0, 0, 0],
...     [1, 0, 1, 0, 1, 0],
...     [1, 1, 0, 0, 0, 0],
...     [1, 0, 0, 0, 0, 0],
...     [0, 0, 0, 0, 0, 0],
...     [0, 0, 0, 0, 0, 0]
... ])

>>> network = pyphi.Network(tpm, connectivity_matrix=cm)

>>> state = (1, 0, 0, 0, 1, 0)
>>> ABC = pyphi.Subsystem(network, state, [0, 1, 2])

>>> network = pyphi.examples.fig3a()
>>> state = (1, 0, 0, 0)
>>> subsystem = pyphi.Subsystem(network, state, range(network.size))
>>> A, B, C, D = subsystem.node_indices

>>> subsystem.cause_repertoire((A,), (B, C, D))
array([[[[ 0.125,  0.125],
         [ 0.125,  0.125]],

        [[ 0.125,  0.125],
         [ 0.125,  0.125]]]])

>>> subsystem.cause_info((A,), (B, C, D))
0.0

>>> network = pyphi.examples.fig3b()
>>> subsystem = pyphi.Subsystem(network, state, range(network.size))
>>> A, B, C, D = subsystem.node_indices

>>> cr = subsystem.cause_repertoire((A,), (B, C, D))
>>> cr
array([[[[ 0.,  0.],
         [ 0.,  0.]],

        [[ 0.,  0.],
         [ 0.,  1.]]]])

>>> cr = cr.squeeze()

>>> cr[(1, 1, 1)]
1.0

>>> subsystem.cause_info((A,), (B, C, D))
1.5

>>> state = (0, 0, 0, 0)
>>> subsystem = pyphi.Subsystem(network, state, range(network.size))
>>> A, B, C, D = subsystem.node_indices

>>> subsystem.cause_repertoire((A,), (B, C, D))
array([[[[ 0.14285714,  0.14285714],
         [ 0.14285714,  0.14285714]],

        [[ 0.14285714,  0.14285714],
         [ 0.14285714,  0.        ]]]])

>>> subsystem.cause_info((A,), (B, C, D))
0.214284

>>> network = pyphi.examples.fig4()
>>> state = (1, 0, 0)
>>> subsystem = pyphi.Subsystem(network, state, range(network.size))
>>> A, B, C = subsystem.node_indices

>>> subsystem.cause_repertoire((A,), (A, B, C))
array([[[ 0.        ,  0.16666667],
        [ 0.16666667,  0.16666667]],

       [[ 0.        ,  0.16666667],
        [ 0.16666667,  0.16666667]]])
>>> subsystem.effect_repertoire((A,), (A, B, C))
array([[[ 0.0625,  0.0625],
        [ 0.0625,  0.0625]],

       [[ 0.1875,  0.1875],
        [ 0.1875,  0.1875]]])

>>> subsystem.unconstrained_cause_repertoire((A, B, C))
array([[[ 0.125,  0.125],
        [ 0.125,  0.125]],

       [[ 0.125,  0.125],
        [ 0.125,  0.125]]])
>>> subsystem.unconstrained_effect_repertoire((A, B, C))
array([[[ 0.09375,  0.09375],
        [ 0.03125,  0.03125]],

       [[ 0.28125,  0.28125],
        [ 0.09375,  0.09375]]])

>>> subsystem.cause_info((A,), (A, B, C))
0.333332
>>> subsystem.effect_info((A,), (A, B, C))
0.25

>>> subsystem.cause_effect_info((A,), (A, B, C))
0.25

>>> network = pyphi.examples.fig5a()
>>> state = (1, 1, 1)
>>> subsystem = pyphi.Subsystem(network, state, range(network.size))
>>> A, B, C = subsystem.node_indices

>>> subsystem.cause_repertoire((A,), (A, B, C))
array([[[ 0. ,  0. ],
        [ 0. ,  0.5]],

       [[ 0. ,  0. ],
        [ 0. ,  0.5]]])
>>> subsystem.cause_info((A,), (A, B, C))
1.0

>>> np.array_equal(subsystem.effect_repertoire((A,), (A, B, C)),
...                subsystem.unconstrained_effect_repertoire((A, B, C)))
True
>>> subsystem.effect_info((A,), (A, B, C))
0.0

>>> subsystem.cause_effect_info((A,), (A, B, C))
0.0

>>> network = pyphi.examples.fig5b()
>>> state = (1, 0, 0)
>>> subsystem = pyphi.Subsystem(network, state, range(network.size))
>>> A, B, C = subsystem.node_indices

>>> subsystem.effect_repertoire((A,), (A, B, C))
array([[[ 0.,  0.],
        [ 0.,  0.]],

       [[ 0.,  0.],
        [ 0.,  1.]]])
>>> subsystem.effect_info((A,), (A, B, C))
0.5

>>> np.array_equal(subsystem.cause_repertoire((A,), (A, B, C)),
...                subsystem.unconstrained_cause_repertoire((A, B, C)))
True
>>> subsystem.cause_info((A,), (A, B, C))
0.0

>>> subsystem.cause_effect_info((A,), (A, B, C))
0.0

>>> network = pyphi.examples.fig6()
>>> state = (1, 0, 0)
>>> subsystem = pyphi.Subsystem(network, state, range(network.size))
>>> ABC = subsystem.node_indices

>>> mip_c = subsystem.mip_past(ABC, ABC)
>>> mip_e = subsystem.mip_future(ABC, ABC)

>>> mip_c.phi
0.499999
>>> mip_c.partition
(Part(mechanism=(0,), purview=()), Part(mechanism=(1, 2), purview=(0, 1, 2)))
>>> mip_e.phi
0.25
>>> mip_e.partition
(Part(mechanism=(), purview=(1,)), Part(mechanism=(0, 1, 2), purview=(0, 2)))

import json
with open('path/to/network.json') as json_file:
    network_dictionary = json.load(json_file)

tpm = network_dictionary['tpm']
cm = network_dictionary['cm']

>>> network = pyphi.examples.fig8()
>>> state = (1, 0, 0)
>>> subsystem = pyphi.Subsystem(network, state, range(network.size))
>>> A, B, C = subsystem.node_indices

>>> core_cause = subsystem.core_cause((B, C))
>>> core_cause.phi
0.333334

>>> concept_A = subsystem.concept((A,))
>>> concept_A.phi
0.166667

>>> constellation = pyphi.compute.constellation(subsystem)

>>> [round(concept.phi, 2) for concept in constellation]
[0.17, 0.17, 0.25, 0.25, 0.33, 0.5]

>>> subsystem.null_concept.phi
0

>>> pyphi.compute.conceptual_information(subsystem)
2.111109

>>> big_mip = pyphi.compute.big_mip(subsystem)

>>> big_mip.phi
1.916665
>>> big_mip.cut
Cut (0, 1) --//--> (2,)

>>> network = pyphi.examples.fig14()
>>> state = (1, 0, 0, 0, 1, 0)

>>> main_complex = pyphi.compute.main_complex(network, state)

>>> main_complex.subsystem.nodes
(n0, n1, n2)

>>> network = pyphi.examples.fig16()
>>> state = (1, 0, 0, 1, 1, 1, 0)

>>> condensed = pyphi.compute.condensed(network, state)

>>> len(condensed)
2
>>> ABC, FG = condensed
>>> (ABC.subsystem.nodes, ABC.phi)
((n0, n1, n2), 1.916665)
>>> (FG.subsystem.nodes, FG.phi)
((n5, n6), 0.069445)

Basic Usage¶

• pyphi.examples.basic_network()
• pyphi.examples.basic_subsystem()

Let’s make a simple 3-node network and compute its \(\Phi\).

To make a network, we need a TPM and (optionally) a connectivity matrix. The TPM can be in more than one form; see the documentation for pyphi.network. Here we’ll use the 2-dimensional state-by-node form.

>>> import pyphi
>>> import numpy as np
>>> tpm = np.array([
...     [0, 0, 0],
...     [0, 0, 1],
...     [1, 0, 1],
...     [1, 0, 0],
...     [1, 1, 0],
...     [1, 1, 1],
...     [1, 1, 1],
...     [1, 1, 0]
... ])

The connectivity matrix is a square matrix such that the \(i,j^{\textrm{th}}\) entry is 1 if there is a connection from node \(i\) to node \(j\), and 0 otherwise.

>>> cm = np.array([
...     [0, 0, 1],
...     [1, 0, 1],
...     [1, 1, 0]
... ])

Now we construct the network itself with the arguments we just created:

>>> network = pyphi.Network(tpm, connectivity_matrix=cm)

The next step is to define a subsystem for which we want to evaluate \(\Phi\). To make a subsystem, we need the network that it belongs to, the state of that network, and the indices of the subset of nodes which should be included.

The state should be an \(n\)-tuple, where \(n\) is the number of nodes in the network, and where the \(i^{\textrm{th}}\) element is the state of the \(i^{\textrm{th}}\) node in the network.

>>> state = (1, 0, 0)

In this case, we want the \(\Phi\) of the entire network, so we simply include every node in the network in our subsystem:

>>> subsystem = pyphi.Subsystem(network, state, range(network.size))

Now we use pyphi.compute.big_phi() function to compute the \(\Phi\) of our subsystem:

>>> phi = pyphi.compute.big_phi(subsystem)
>>> phi
2.3125

If we want to take a deeper look at the integrated-information-theoretic properties of our network, we can access all the intermediate quantities and structures that are calculated in the course of arriving at a final \(\Phi\) value by using pyphi.compute.big_mip(). This returns a deeply nested object, BigMip, that contains data about the subsystem’s constellation of concepts, cause and effect repertoires, etc.

>>> mip = pyphi.compute.big_mip(subsystem)

For instance, we can see that this network has 4 concepts:

>>> len(mip.unpartitioned_constellation)
4

The documentation for pyphi.models contains description of these structures.

Conditional Independence¶

• pyphi.examples.cond_depend_tpm()
• pyphi.examples.cond_independ_tpm()

This example explores the assumption of conditional independence, and the behaviour of the program when it is not satisfied.

Every state-by-node TPM corresponds to a unique state-by-state TPM which satisfies the conditional independence assumption. If a state-by-node TPM is given as input for a network, the program assumes that it is from a system with the corresponding conditionally independent state-by-state TPM.

When a state-by-state TPM is given as input for a network, the state-by-state TPM is first converted to a state-by-node TPM. The program then assumes that the system corresponds to the unique conditionally independent representation of the state-by-node TPM. If a non-conditionally independent TPM is given, the analyzed system will not correspond to the original TPM. Note that every deterministic state-by-state TPM will automatically satisfy the conditional independence assumption.

Consider a system of two binary nodes(\(A\) and \(B\)) which do not change if they have the same value, but flip with probability 50% if they have different values.

We’ll load the state-by-state TPM for such a system from the examples module:

>>> import pyphi
>>> tpm = pyphi.examples.cond_depend_tpm()
>>> print(tpm)
[[ 1.   0.   0.   0. ]
 [ 0.   0.5  0.5  0. ]
 [ 0.   0.5  0.5  0. ]
 [ 0.   0.   0.   1. ]]

This system does not satisfy the conditional independence assumption; given a past state of (1, 0), the current state of node \(A\) depends on whether or not \(B\) has flipped.

When creating a network, the program will convert this state-by-state TPM to a state-by-node form, and issue a warning if it does not satisfy the assumption:

>>> sbn_tpm = pyphi.convert.state_by_state2state_by_node(tpm)

“The TPM is not conditionally independent. See the conditional independence example in the documentation for more information on how this is handled.”

>>> print(sbn_tpm)
[[[ 0.   0. ]
  [ 0.5  0.5]]

 [[ 0.5  0.5]
  [ 1.   1. ]]]

The program will continue with the state-by-node TPM, but since it assumes conditional independence, the network will not correspond to the original system.

To see the corresponding conditionally independent TPM, convert the state-by-node TPM back to state-by-state form:

>>> sbs_tpm = pyphi.convert.state_by_node2state_by_state(sbn_tpm)
>>> print(sbs_tpm)
[[ 1.    0.    0.    0.  ]
 [ 0.25  0.25  0.25  0.25]
 [ 0.25  0.25  0.25  0.25]
 [ 0.    0.    0.    1.  ]]

A system which does not satisfy the conditional independence assumption shows “instantaneous causality.” In such situations, there must be additional exogenous variable(s) which explain the dependence.

Consider the above example, but with the addition of a third node (\(C\)) which is equally likely to be ON or OFF, and such that when nodes \(A\) and \(B\) are in different states, they will flip when \(C\) is ON, but stay the same when \(C\) is OFF.

>>> tpm2 = pyphi.examples.cond_independ_tpm()
>>> print(tpm2)
[[ 0.5  0.   0.   0.   0.5  0.   0.   0. ]
 [ 0.   0.5  0.   0.   0.   0.5  0.   0. ]
 [ 0.   0.   0.5  0.   0.   0.   0.5  0. ]
 [ 0.   0.   0.   0.5  0.   0.   0.   0.5]
 [ 0.5  0.   0.   0.   0.5  0.   0.   0. ]
 [ 0.   0.   0.5  0.   0.   0.   0.5  0. ]
 [ 0.   0.5  0.   0.   0.   0.5  0.   0. ]
 [ 0.   0.   0.   0.5  0.   0.   0.   0.5]]

The resulting state-by-state TPM now satisfies the conditional independence assumption.

>>> sbn_tpm2 = pyphi.convert.state_by_state2state_by_node(tpm2)
>>> print(sbn_tpm2)
[[[[ 0.   0.   0.5]
   [ 0.   0.   0.5]]

  [[ 0.   1.   0.5]
   [ 1.   0.   0.5]]]


 [[[ 1.   0.   0.5]
   [ 0.   1.   0.5]]

  [[ 1.   1.   0.5]
   [ 1.   1.   0.5]]]]

The node indices are 0 and 1 for \(A\) and \(B\), and 2 for \(C\):

>>> AB = [0, 1]
>>> C = 2

From here, if we marginalize out the node \(C\);

>>> tpm2_marginalizeC = pyphi.utils.marginalize_out(C, sbn_tpm2)

And then restrict the purview to only nodes \(A\) and \(B\);

>>> import numpy as np
>>> tpm2_purviewAB = np.squeeze(tpm2_marginalizeC[:,:,:,AB])

We get back the original state-by-node TPM from the system with just \(A\) and \(B\).

>>> np.all(tpm2_purviewAB == sbn_tpm)
True

Emergence (Macro/Micro)¶

• pyphi.examples.macro_network()

For this example, we will use the pprint module to display lists in a way which makes them easer to read.

>>> from pprint import pprint

We’ll use the macro module to explore alternate spatial scales of a network. The network under consideration is a 4-node non-deterministic network, available from the examples module.

>>> import pyphi
>>> network = pyphi.examples.macro_network()

The connectivity matrix is all-to-all:

>>> network.connectivity_matrix
array([[ 1.,  1.,  1.,  1.],
       [ 1.,  1.,  1.,  1.],
       [ 1.,  1.,  1.,  1.],
       [ 1.,  1.,  1.,  1.]])

We’ll set the state so that nodes are OFF.

>>> state = (0, 0, 0, 0)

At the “micro” spatial scale, we can compute the main complex, and determine the \(\Phi\) value:

>>> main_complex = pyphi.compute.main_complex(network, state)
>>> main_complex.phi
0.113889

The question is whether there are other spatial scales which have greater values of \(\Phi\). This is accomplished by considering all possible coarse-graining of micro-elements to form macro-elements. A coarse-graining of nodes is any partition of the elements of the micro system. First we’ll get a list of all possible partitions:

>>> partitions = pyphi.macro.list_all_partitions(network)
>>> pprint(partitions)
[[[0, 1, 2], [3]],
 [[0, 1, 3], [2]],
 [[0, 1], [2, 3]],
 [[0, 1], [2], [3]],
 [[0, 2, 3], [1]],
 [[0, 2], [1, 3]],
 [[0, 2], [1], [3]],
 [[0, 3], [1, 2]],
 [[0], [1, 2, 3]],
 [[0], [1, 2], [3]],
 [[0, 3], [1], [2]],
 [[0], [1, 3], [2]],
 [[0], [1], [2, 3]],
 [[0, 1, 2, 3]]]

Lets start by considering the partition [[0, 1, 2], [3]]:

>>> partition = partitions[0]
>>> partition
[[0, 1, 2], [3]]

For this partition there are two macro-elements, one consisting of micro-elements (0, 1, 2) and the other is simply micro-element 3.

We must then determine the relationship between micro-elements and macro-elements. An assumption when coarse-graining the system, is that the resulting macro-elements do not differentiate the different micro-elements. Thus any correspondence between states must be stated soley in terms of the number of micro-elements which are on, and not depend on which micro-element are on.

For example, consider the macro-element (0, 1, 2). We may say that the macro-element is ON if at least one micro-element is on, or if all micro-elements are on; however, we may not say that the macro-element is ON if micro-element 1 is on, because this relationship involves identifying specific micro-elements.

To see a list of all possible groupings of micro-states into macro-states:

>>> groupings = pyphi.macro.list_all_groupings(partition)
>>> pprint(groupings)
[[[[0, 1, 2], [3]], [[0], [1]]],
 [[[0, 1, 3], [2]], [[0], [1]]],
 [[[0, 1], [2, 3]], [[0], [1]]],
 [[[0, 2, 3], [1]], [[0], [1]]],
 [[[0, 2], [1, 3]], [[0], [1]]],
 [[[0, 3], [1, 2]], [[0], [1]]],
 [[[0], [1, 2, 3]], [[0], [1]]]]

We will focus on the first grouping in the list.

>>> grouping = groupings[0]
>>> grouping
[[[0, 1, 2], [3]], [[0], [1]]]

The grouping contains two lists, one for each macro-element.

>>> grouping[0]
[[0, 1, 2], [3]]

For the first macro-element, this grouping means that the element will be OFF if zero, one or two of its micro-elements are ON, and will be ON if all three micro-elements are ON.

>>> grouping[1]
[[0], [1]]

For the second macro-element, the grouping means that the element will be OFF if its micro-element is OFF, and ON if its micro-element is ON.

One we have selected a partition and grouping for analysis, we can create a mapping between micro-states and macro-states:

>>> mapping = pyphi.macro.make_mapping(partition, grouping)
>>> mapping
array([ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  1.,  2.,  2.,  2.,  2.,  2.,
        2.,  2.,  3.])

The interpretation of the mapping uses the LOLI convention of indexing (see LOLI: Low-Order bits correspond to Low-Index nodes).

>>> mapping[7]
1.0

This says that micro-state 7 corresponds to macro-state 1:

>>> pyphi.convert.loli_index2state(7, 4)
(1, 1, 1, 0)

>>> pyphi.convert.loli_index2state(1, 2)
(1, 0)

In micro-state 7, all three elements corresponding to the first macro-element are ON, so that macro-element is ON. The micro-element corresponding to the second macro-element is OFF, so that macro-element is OFF.

Using the mapping, we can then create a state-by-state TPM for the macro-system corresponding to the selected partition and grouping:

>>> macro_tpm = pyphi.macro.make_macro_tpm(network.tpm, mapping)
>>> macro_tpm
array([[ 0.5838,  0.0162,  0.3802,  0.0198],
       [ 0.    ,  0.    ,  0.91  ,  0.09  ],
       [ 0.5019,  0.0981,  0.3451,  0.0549],
       [ 0.    ,  0.    ,  0.    ,  1.    ]])

This macro-TPM does not satisfy the conditional independence assumption, so this particular partition and grouping combination is not a valid coarse-graining of the system:

>>> pyphi.validate.conditionally_independent(macro_tpm)
False

In these cases, the object returned make_macro_network() function will have a boolean value of False:

>>> (macro_network, macro_state) = pyphi.macro.make_macro_network(network, state, mapping)
>>> bool(macro_network)
False

Lets consider a different partition instead.

>>> partition = partitions[2]
>>> partition
[[0, 1], [2, 3]]

>>> groupings = pyphi.macro.list_all_groupings(partition)
>>> grouping = groupings[0]
>>> grouping
[[[0, 1], [2]], [[0, 1], [2]]]

>>> mapping = pyphi.macro.make_mapping(partition, grouping)
>>> mapping
array([ 0.,  0.,  0.,  1.,  0.,  0.,  0.,  1.,  0.,  0.,  0.,  1.,  2.,
        2.,  2.,  3.])

>>> (macro_network, macro_state) = pyphi.macro.make_macro_network(network, state, mapping)
>>> bool(macro_network)
True

We can then consider the integrated information of this macro-network and compare it to the micro-network.

>>> macro_main_complex = pyphi.compute.main_complex(macro_network, macro_state)
>>> macro_main_complex.phi
0.86905

The integrated information of the macro system (\(\Phi = 0.86905\)) is greater than the integrated information of the micro system (\(\Phi = 0.113889\)). We can conclude that a macro-scale is appropriate for this system, but to determine which one, we must check all possible partitions and all possible groupings to find the maximum of integrated information across all scales.

>>> M = pyphi.macro.emergence(network, state)
>>> M.partition
[[0, 1], [2, 3]]
>>> M.grouping
[[[0, 1], [2]], [[0, 1], [2]]]
>>> M.emergence
0.755161

The analysis determines the partition and grouping which results in the maximum value of integrated information, as well as the emergence (increase in \(\Phi\)) from the micro-scale to the macro-scale.

Magic Cuts¶

• pyphi.examples.rule110_network()
• pyphi.examples.rule154_network()

This example explores a system of three fully connected elements \(A\), \(B\) and \(C\), which follow the logic of the Rule 110 cellular automaton. The point of this example is to highlight an unexpected behaviour of system cuts, that the minimum information partition of a system can result in new concepts being created.

First let’s create the the Rule 110 network, with all nodes OFF in the current state.

>>> import pyphi
>>> network = pyphi.examples.rule110_network()
>>> state = (0, 0, 0)

Next, we want to identify the spatial scale and main complex of the network:

>>> macro = pyphi.macro.emergence(network, state)
>>> macro.emergence
-1.35708

Since the emergence value is negative, there is no macro scale which has greater integrated information than the original micro scale. We can now analyze the micro scale to determine the main complex of the system:

>>> main_complex = pyphi.compute.main_complex(network, state)
>>> subsystem = main_complex.subsystem
>>> subsystem
Subsystem((n0, n1, n2))
>>> main_complex.phi
1.35708

The main complex of the system contains all three nodes of the system, and it has integrated information \(\Phi = 1.35708\). Now that we have identified the main complex of the system, we can explore its conceptual structure and the effect of the MIP.

>>> constellation = main_complex.unpartitioned_constellation

There two equalivalent cuts for this system; for concreteness we sever all connections from elements \(A\) and \(B\) to \(C\).

>>> cut = pyphi.models.Cut(severed = (0, 1), intact = (2,))
>>> cut_subsystem = pyphi.Subsystem(network, state, range(network.size), cut)
>>> cut_constellation = pyphi.compute.constellation(cut_subsystem)

Lets investigate the concepts in the unpartitioned constellation,

>>> [concept.mechanism for concept in constellation]
[(0,), (1,), (2,), (0, 1), (0, 2), (1, 2)]
>>> [concept.phi for concept in constellation]
[0.125, 0.125, 0.125, 0.499999, 0.499999, 0.499999]
>>> sum(_)
1.8749970000000002

and also the concepts of the partitioned constellation.

>>> [concept.mechanism for concept in cut_constellation]
[(0,), (1,), (2,), (0, 1), (1, 2), (0, 1, 2)]
>>> [concept.phi for concept in cut_constellation]
[0.125, 0.125, 0.125, 0.499999, 0.266666, 0.333333]
>>> sum(_)
1.4749980000000003

The unpartitioned constellation includes all possible first and second order concepts, but there is no third order concept. After applying the cut, and severing the connections from \(A\) and \(B\) to \(C\), a third order concept is created in the partitioned constellation. A new concept is created as a result of the cut, but there is also a concept destroyed |A,B| and the overall amount of \(\varphi\) in the system decreases from \(1.875\) to \(1.475\).

Lets explore the concept which was created to determine why it does not exist in the unpartitioned constellation and what changed in the partitioned constellation.

>>> subsystem = main_complex.subsystem
>>> ABC = subsystem.node_indices
>>> subsystem.cause_info(ABC, ABC)
0.749999
>>> subsystem.effect_info(ABC, ABC)
1.875

The mechanism has cause and effect power over the system, so it must be that this power is reducible.

>>> mice_cause = subsystem.core_cause(ABC)
>>> mice_cause.phi
0.0
>>> mice_effect = subsystem.core_effect(ABC)
>>> mice_effect.phi
0.624999

The reason ABC does not exist as a concept is that its cause is reducible. Looking at the TPM of the system, there are no possible states with two of the elements set to OFF. This means that knowing two elements are OFF is enough to know that the third element must also be OFF, and thus the third element can always be cut from the concept without a loss of information. This will be true for any purview, so the cause information is reducible.

>>> BC = (1, 2)
>>> A = (0,)
>>> repertoire = subsystem.cause_repertoire(ABC, ABC)
>>> cut_repertoire = subsystem.cause_repertoire(BC, ABC) * subsystem.cause_repertoire(A, ())
>>> pyphi.utils.hamming_emd(repertoire, cut_repertoire)
0.0

Next, lets look at the cut subsystem to understand how the new concept comes into existence.

>>> ABC = (0, 1, 2)
>>> C = (2,)
>>> AB = (0, 1)

The cut applied to the subsystem severs the connections from \(A\) and \(B\) to \(C\). In this circumstance, knowing \(A\) and \(B\) do not tell us anything about the state of \(C\), only the past state of \(C\) can tell us about the future state of \(C\). Here, past_tpm[1] gives us the probability of C being ON in the next state, while past_tpm[0] would give us the probability of C being OFF.

>>> C_node = cut_subsystem.indices2nodes(C)[0]
>>> C_node.tpm[1].flatten()
array([ 0.5 ,  0.75])

This states that A has a 50% chance of being ON in the next state if it currently OFF, but a 75% chance of being ON in the next state if it is currently ON. Thus unlike the unpartitioned case, knowing the current state of C gives us additional information over and above knowing A and B.

>>> repertoire = cut_subsystem.cause_repertoire(ABC, ABC)
>>> cut_repertoire = cut_subsystem.cause_repertoire(AB, ABC) * cut_subsystem.cause_repertoire(C, ())
>>> pyphi.utils.hamming_emd(repertoire, cut_repertoire)
0.500001

With this partition, the integrated information is \(\varphi = 0.5\), but we must check all possible partitions to find the MIP.

>>> cut_subsystem.core_cause(ABC).purview
(0, 1, 2)
>>> cut_subsystem.core_cause(ABC).phi
0.333333

It turns out that the MIP is

and the integrated information of ABC is \(\varphi = 1/3\).

Note: In order for a new concept to be created by a cut, there must be a within mechanism connection severed by the cut.

In the previous example, the MIP created a new concept, but the amount of \(\varphi\) in the constellation still decreased. This is not always the case. Next we will look at an example of system whoes MIP increases the amount of \(\varphi\). This example is based on a five node network which follows the logic of the Rule 154 cellular automaton. Lets first load the network,

>>> network = pyphi.examples.rule154_network()
>>> state = (1, 0, 0, 0, 0)

For this example, it is the subsystem consisting of |n0, n1, n4| that we explore. This is not the main concept of the system, but it serves as a proof of principle regardless.

>>> subsystem = pyphi.Subsystem(network, state, (0, 1, 4))

Calculating the MIP of the system,

>>> mip = pyphi.compute.big_mip(subsystem)
>>> mip.phi
0.217829
>>> mip.cut
Cut (0, 4) --//--> (1,)

This subsystem has a \(\Phi\) value of 0.15533, and the MIP cuts the connections from |n0, n4| to \(n_{1}\). Investigating the concepts in both the partitioned and unpartitioned constellations,

>>> unpartitioned_constellation = mip.unpartitioned_constellation
>>> [concept.mechanism for concept in unpartitioned_constellation]
[(0,), (1,), (0, 1)]
>>> [concept.phi for concept in unpartitioned_constellation]
[0.25, 0.166667, 0.178572]
>>> sum([concept.phi for concept in unpartitioned_constellation])
0.5952390000000001

The unpartitioned constellation has mechanisms \(n_{0}\), \(n_{1}\) and \(n_{0}n_{1}\) with \(\sum\varphi = 0.595239\).

>>> partitioned_constellation = mip.partitioned_constellation
>>> [concept.mechanism for concept in partitioned_constellation]
[(0, 1), (0,), (1,)]
>>> [concept.phi for concept in partitioned_constellation]
[0.214286, 0.25, 0.166667]
>>> sum([concept.phi for concept in partitioned_constellation])
0.630953

The unpartitioned constellation has mechanisms \(n_{0}\), \(n_{1}\) and \(n_{0}n_{1}\) with \(\sum\varphi = 0.630953\). There are the same number of concepts in both constellations, over the same mechanisms; however, the partitioned constellation has a greater \(\varphi\) value for the concept \(n_{0}n_{1}\), resulting in an overall greater \(\sum\varphi\) for the MIP constellation.

Although situations described above are rare, they do occur, so one must be careful when analyzing the integrated information of physical systems not to dismiss the possibility of partitions creating new concepts or increasing the amount of \(\varphi\); otherwise, an incorrect main complex may be identified.

Residue¶

• pyphi.examples.residue_network()
• pyphi.examples.residue_subsystem()

This example describes a system containing two AND nodes, \(A\) and \(B\), with a single overlapping input node.

First let’s create the subsystem corresponding to the residue network, with all nodes off in the current and past states.

>>> import pyphi
>>> subsystem = pyphi.examples.residue_subsystem()

Next, we can define the mechanisms of interest. Mechanisms and purviews are represented by tuples of node indices in the network:

>>> A = (0,)
>>> B = (1,)
>>> AB = (0, 1)

And the possible past purviews that we’re interested in:

>>> CD = (2, 3)
>>> DE = (3, 4)
>>> CDE = (2, 3, 4)

We can then evaluate the cause information for each of the mechanisms over the past purview \(CDE\).

>>> subsystem.cause_info(A, CDE)
0.333332

>>> subsystem.cause_info(B, CDE)
0.333332

>>> subsystem.cause_info(AB, CDE)
0.5

The composite mechanism \(AB\) has greater cause information than either of the individual mechanisms. This contradicts the idea that \(AB\) should exist minimally in this system.

Instead, we can quantify existence as the irreducible cause information of a mechanism. The MIP of a mechanism is the partition of mechanism and purview which makes the least difference to the cause repertoire (see the documentation for the Mip object). The irreducible cause information is the distance between the unpartitioned and partitioned repertoires.

To calculate the MIP structure of mechanism \(AB\):

>>> mip_AB = subsystem.mip_past(AB, CDE)

We can then determine what the specific partition is.

>>> mip_AB.partition
(Part(mechanism=(), purview=(2,)), Part(mechanism=(0, 1), purview=(3, 4)))

The labels (n0, n1, n2, n3, n4) correspond to nodes \(A, B, C, D, E\) respectively. Thus the MIP is \(\frac{AB}{DE} \times \frac{\left[\;\right]}{C}\), where \([\,]\) denotes the empty mechanism.

The partitioned repertoire of the MIP can also be retrieved:

>>> mip_AB.partitioned_repertoire
array([[[[[ 0.2,  0.2],
          [ 0.1,  0. ]],

         [[ 0.2,  0.2],
          [ 0.1,  0. ]]]]])

And we can then calculate the irreducible cause information as the difference between partitioned and unpartitioned repertoires.

>>> mip_AB.phi
0.1

One counterintuitive result that merits discussion is that since irreducible cause information is what defines existence, we must also evaluate the irreducible cause information of the mechanisms \(A\) and \(B\).

The mechanism \(A\) over the purview \(CDE\) is completely reducible to \(\frac{A}{CD} \times \frac{\left[\;\right]}{E}\) because \(E\) has no effect on \(A\), so it has zero \(\varphi\).

>>> subsystem.mip_past(A, CDE).phi
0.0
>>> subsystem.mip_past(A, CDE).partition
(Part(mechanism=(), purview=(4,)), Part(mechanism=(0,), purview=(2, 3)))

Instead, we should evaluate \(A\) over the purview \(CD\).

>>> mip_A = subsystem.mip_past(A, CD)

In this case, there is a well defined MIP

>>> mip_A.partition
(Part(mechanism=(), purview=(2,)), Part(mechanism=(0,), purview=(3,)))

which is \(\frac{\left[\;\right]}{C} \times \frac{A}{D}\). It has partitioned repertoire

>>> mip_A.partitioned_repertoire
array([[[[[ 0.33333333],
          [ 0.16666667]],

         [[ 0.33333333],
          [ 0.16666667]]]]])

and irreducible cause information

>>> mip_A.phi
0.166667

A similar result holds for \(B\). Thus the mechanisms \(A\) and \(B\) exist at levels of \(\varphi = \frac{1}{6}\), while the higher-order mechanism \(AB\) exists only as the residual of causes, at a level of \(\varphi = \frac{1}{10}\).

XOR Network¶

• pyphi.examples.xor_network()
• pyphi.examples.xor_subsystem()

This example describes a system of three fully connected XOR nodes, \(n_{0}\), \(n_{1}\) and \(n_{2}\) (no self-connections).

First let’s create the XOR network:

>>> import pyphi
>>> network = pyphi.examples.xor_network()

We’ll consider the state with all nodes OFF.

>>> state = (0, 0, 0)

Existence is a top-down process; the whole is more important than its parts. The first step is to confirm the existence of the whole, by finding the main complex of the network:

>>> main_complex = pyphi.compute.main_complex(network, state)

The main complex exists (\(\Phi > 0\)),

>>> main_complex.phi
1.874999

and it consists of the entire network:

>>> main_complex.subsystem
Subsystem((n0, n1, n2))

Knowing what exists at the system level, we can now investigate the existence of concepts within the complex.

>>> constellation = main_complex.unpartitioned_constellation
>>> len(constellation)
3
>>> [concept.mechanism for concept in constellation]
[(0, 1), (0, 2), (1, 2)]

There are three concepts in the constellation. They are all the possible second order mechanisms: \(n_{0}n_{1}\), \(n_{0}n_{2}\) and \(n_{1}n_{2}\).

Focusing on the concept specified by mechanism \(n_{0}n_{1}\), we investigate existence, and the irreducible cause and effect. Based on the symmetry of the network, the results will be similar for the other second order mechanisms.

>>> concept = constellation[0]
>>> concept.mechanism
(0, 1)
>>> concept.phi
0.5

The concept has \(\varphi = \frac{1}{2}\).

>>> concept.cause.purview
(0, 1, 2)
>>> concept.cause.repertoire
array([[[ 0.5,  0. ],
        [ 0. ,  0. ]],

       [[ 0. ,  0. ],
        [ 0. ,  0.5]]])

So we see that the cause purview of this mechanism is the whole system \(n_{0}n_{1}n_{2}\), and that the repertoire shows a \(0.5\) of probability the past state being (0, 0, 0) and the same for (1, 1, 1):

>>> concept.cause.repertoire[(0, 0, 0)]
0.5
>>> concept.cause.repertoire[(1, 1, 1)]
0.5

This tells us that knowing both \(n_{0}\) and \(n_{1}\) are currently OFF means that the past state of the system was either all OFF or all ON with equal probability.

For any reduced purview, we would still have the same information about the elements in the purview (either all ON or all OFF), but we would lose the information about the elements outside the purview.

>>> concept.effect.purview
(2,)
>>> concept.effect.repertoire
array([[[ 1.,  0.]]])

The effect purview of this concept is the node \(n_{2}\). The mechanism \(n_{0}n_{1}\) is able to completely specify the next state of \(n_{2}\). Since both nodes are OFF, the next state of \(n_{2}\) will be OFF.

The mechanism \(n_{0}n_{1}\) does not provide any information about the next state of either \(n_{0}\) or \(n_{1}\), because the relationship depends on the value of \(n_{2}\). That is, the next state of \(n_{0}\) (or \(n_{1}\)) may be either ON or OFF, depending on the value of \(n_{2}\). Any purview larger than \(n_{2}\) would be reducible by pruning away the additional elements.

An analysis of the intrinsic existence of this system reveals that the main complex of the system is the entire network of XOR nodes. Furthermore, the concepts which exist within the complex are those specified by the second-order mechanisms \(n_{0}n_{1}\), \(n_{0}n_{2}\), and \(n_{1}n_{2}\).

To understand the notion of intrinsic existence, in addition to determining what exists for the system, it is useful to consider also what does not exist.

Specifically, it may be surprising that none of the first order mechanisms \(n_{0}\), \(n_{1}\) or \(n_{2}\) exist. This physical system of XOR gates is sitting on the table in front of me; I can touch the individual elements of the system, so how can it be that they do not exist?

That sort of existence is what we term extrinsic existence. The XOR gates exist for me as an observer, external to the system. I am able to manipulate them, and observe their causes and effects, but the question that matters for intrinsic existence is, do they have irreducible causes and effects within the system? There are two reasons a mechanism may have no irreducible cause-effect power: either the cause-effect power is completely reducible, or there was no cause-effect power to begin with. In the case of elementary mechanisms, it must be the latter.

To see this, again due to symmetry of the system, we will focus only on the mechanism \(n_{0}\).

>>> subsystem = pyphi.examples.xor_subsystem()
>>> n0 = (0,)
>>> n0n1n2 = (0, 1, 2)

In order to exist, a mechanism must have irreducible cause and effect power within the system.

>>> subsystem.cause_info(n0, n0n1n2)
0.5
>>> subsystem.effect_info(n0, n0n1n2)
0.0

The mechanism has no effect power over the entire subsystem, so it cannot have effect power over any purview within the subsystem. Furthermore, if a mechanism has no effect power, it certainly has no irreducible effect power. The first-order mechanisms of this system do not exist intrinsically, because they have no effect power (having causal power is not enough).

To see why this is true, consider the effect of \(n_{0}\). There is no self-loop, so \(n_{0}\) can have no effect on itself. Without knowing the current state of \(n_{0}\), in the next state \(n_{1}\) could be either ON or OFF. If we know that the current state of \(n_{0}\) is ON, then \(n_{1}\) could still be either ON or OFF, depending on the state of \(n_{2}\). Thus, on its own, the current state of \(n_{0}\) does not provide any information about the next state of \(n_{1}\). A similar result holds for the effect of \(n_{0}\) on \(n_{2}\). Since \(n_{0}\) has no effect power over any element of the system, it does not exist from the intrinsic perspective.

To complete the discussion, we can also investigate the potential third order mechanism \(n_{0}n_{1}n_{2}\). Consider the cause information over the purview \(n_{0}n_{1}n_{2}\):

>>> subsystem.cause_info(n0n1n2, n0n1n2)
0.749999

Since the mechanism has nonzero cause information, it has causal power over the system—but is it irreducible?

>>> mip = subsystem.mip_past(n0n1n2, n0n1n2)
>>> mip.phi
0.0
>>> mip.partition
(Part(mechanism=(0,), purview=()), Part(mechanism=(1, 2), purview=(0, 1, 2)))

The mechanism has \(ci = 0.75\), but it is completely reducible (\(\varphi = 0\)) to the partition

This result can be understood as follows: knowing that \(n_{1}\) and \(n_{2}\) are OFF in the current state is sufficient to know that \(n_{0}\), \(n_{1}\), and \(n_{2}\) were all OFF in the past state; there is no additional information gained by knowing that \(n_{0}\) is currently OFF.

Similarly for any other potential purview, the current state of \(n_{1}\) and \(n_{2}\) being (0, 0) is always enough to fully specify the previous state, so the mechanism is reducible for all possible purviews, and hence does not exist.

compute¶

Maintains backwards compatability with the old compute API.

concept_caching¶

Objects and functions for managing the normalization, caching, and retrieval of concepts.

class pyphi.concept_caching.NormalizedMechanism(mechanism, subsystem, normalize_tpms=True)¶

A mechanism rendered into a normal form, suitable for use as a cache key in concept memoization.

The broad outline for the normalization procedure is as follows:

• Get the set of all nodes that input to (output from) at least one mechanism node.
• Sort the Marbls in a stable way (this is done by marbl-python, when the MarblSet is initialized).
• Iterate over the sorted Marbls; for each one, iterate over its corresponding mechanism node’s inputs (outputs).
• Label each input (output) with a unique integer. These are the “normalized indices” of the inputs (outputs).
• Record the inverse mapping, which sends a normalized index to a real index.
• Record the state of the mechanism and all input/ouptut nodes.

Then two normalized mechanisms are the same if they have the same MarblSets, inputs, outputs, state, and input/output state.

marblset¶

MarblSet – A dictionary where keys are directions, and values are MarblSets containing Marbls generated from the TPMs of the mechanism nodes’ corresponding to the direction.

normalized_indices¶

dict – A dictionary where keys are directions, and values are dictionaries mapping mechanism node indices to their normalized indices for that direction.

unnormalized_indices¶

dict – The inverse of normalized_indices.

inputs¶

tuple(tuple(int – A tuple where the \(i^{\textrm{th}}\) element contains a tuple of the normalized indices of the \(i^{\textrm{th}}\) node, where \(i\) is a normalized index.

outputs¶

tuple(tuple(int – The same as inputs, but the elements contain normalized indices of the outputs.

permutation¶

dict( – A dictionary where the keys are directions and the values are the permutations that maps mechanism nodes to the position of their marbl in the marblset for that direction.

class pyphi.concept_caching.NormalizedMice¶

A lightweight container for MICE data.

See documentation for Mice for its unnormalized counterpart.

phi¶

float – The difference between the mechanism’s unpartitioned and partitioned repertoires.

direction¶

str – Either ‘past’ or ‘future’. If ‘past’ (‘future’), this represents a maximally irreducible cause (effect).

mechanism¶

tuple(int – The normalized indices of the MICE’s mechanism.

purview¶

tuple(int – A normalized purview. This is a tuple of the normalized indices of its nodes.

repertoire¶

np.ndarray – The normalized unpartitioned repertoire of the mechanism over the purview. A repertoire is normalized by squeezing and then reordering its dimensions so they correspond to the normalized purview.

class pyphi.concept_caching.NormalizedConcept(normalized_mechanism, concept)¶

A precomputed concept in a form suitable for memoization.

Upon initialization, the normal form of the concept to be cached is computed, and data relating its cause and effect purviews are stored, which the concept to be reconstituted in a different subsystem.

mechanism¶

NormalizedMechanism – The mechanism the concept consists of.

phi¶

float – The \(\varphi\) value of the concept.

cause¶

NormalizedMice – The concept’s normalized core cause.

effect¶

NormalizedMice – The concept’s normalized core effect.

pyphi.concept_caching.concept(subsystem, mechanism)¶

Find the concept specified by a mechanism, returning a cached value if one is found and computing and caching it otherwise.

config¶

The configuration is loaded upon import from a YAML file in the directory where PyPhi is run: pyphi_config.yml. If no file is found, the default configuration is used.

The various options are listed here with their defaults

>>> import pyphi
>>> defaults = pyphi.config.DEFAULTS

It is also possible to manually load a YAML configuration file within your script:

>>> pyphi.config.load_config_file('pyphi_config.yml')

Or load a dictionary of configuration values:

>>> pyphi.config.load_config_dict({'SOME_CONFIG': 'value'})

convert¶

Conversion functions.

pyphi.convert.nodes2indices(nodes)¶

pyphi.convert.nodes2state(nodes)¶

pyphi.convert.state2holi_index(state)¶

Convert a PyPhi state-tuple to a decimal index according to the HOLI convention.

Parameters:	state (tuple(int) – A state-tuple where the \(i^{\textrm{th}}\) element of the tuple gives the state of the \(i^{\textrm{th}}\) node.
Returns:	holi_index – A decimal integer corresponding to a network state under the HOLI convention.
Return type:	int

Examples

>>> from pyphi.convert import state2loli_index
>>> state2holi_index((1, 0, 0, 0, 0))
16
>>> state2holi_index((1, 1, 1, 0, 0, 0, 0, 0))
224

pyphi.convert.state2loli_index(state)¶

Convert a PyPhi state-tuple to a decimal index according to the LOLI convention.

Parameters:	state (tuple(int) – A state-tuple where the \(i^{\textrm{th}}\) element of the tuple gives the state of the \(i^{\textrm{th}}\) node.
Returns:	loli_index – A decimal integer corresponding to a network state under the LOLI convention.
Return type:	int

Examples

>>> from pyphi.convert import state2loli_index
>>> state2loli_index((1, 0, 0, 0, 0))
1
>>> state2loli_index((1, 1, 1, 0, 0, 0, 0, 0))
7

pyphi.convert.loli_index2state(i, number_of_nodes)¶

Convert a decimal integer to a PyPhi state tuple with the LOLI convention.

The output is the reverse of holi_index2state.

Parameters:	i (int) – A decimal integer corresponding to a network state under the LOLI convention.
Returns:	state – A state-tuple where the \(i^{\textrm{th}}\) element of the tuple gives the state of the \(i^{\textrm{th}}\) node.
Return type:	``tuple(int

Examples

>>> from pyphi.convert import loli_index2state
>>> number_of_nodes = 5
>>> loli_index2state(1, number_of_nodes)
(1, 0, 0, 0, 0)
>>> number_of_nodes = 8
>>> loli_index2state(7, number_of_nodes)
(1, 1, 1, 0, 0, 0, 0, 0)

pyphi.convert.holi_index2state(i, number_of_nodes)¶

Convert a decimal integer to a PyPhi state tuple using the HOLI convention that high-order bits correspond to low-index nodes.

The output is the reverse of loli_index2state.

Parameters:	i (int) – A decimal integer corresponding to a network state under the HOLI convention.
Returns:	state – A state-tuple where the \(i^{\textrm{th}}\) element of the tuple gives the state of the \(i^{\textrm{th}}\) node.
Return type:	``tuple(int

Examples

>>> from pyphi.convert import holi_index2state
>>> number_of_nodes = 5
>>> holi_index2state(1, number_of_nodes)
(0, 0, 0, 0, 1)
>>> number_of_nodes = 8
>>> holi_index2state(7, number_of_nodes)
(0, 0, 0, 0, 0, 1, 1, 1)

pyphi.convert.to_n_dimensional(tpm)¶

Reshape a state-by-node TPM to the N-D form.

See documentation for the Network object for more information on TPM formats.

pyphi.convert.state_by_state2state_by_node(tpm)¶

Convert a state-by-state TPM to a state-by-node TPM.

Note

The indices of the rows and columns of the state-by-state TPM are assumed to follow the LOLI convention. The indices of the rows of the resulting state-by-node TPM also follow the LOLI convention. See the documentation for the examples module for more info on these conventions.

Parameters:	tpm (list(list) – A square state-by-state TPM with row and column indices following the LOLI convention.
Returns:	state_by_node_tpm – A state-by-node TPM, with row indices following the LOLI convention.
Return type:	np.ndarray

Examples

>>> from pyphi.convert import state_by_state2state_by_node
>>> tpm = np.array([[0.5, 0.5, 0.0, 0.0],
...                 [0.0, 1.0, 0.0, 0.0],
...                 [0.0, 0.2, 0.0, 0.8],
...                 [0.0, 0.3, 0.7, 0.0]])
>>> state_by_state2state_by_node(tpm)
array([[[ 0.5,  0. ],
        [ 1. ,  0.8]],

       [[ 1. ,  0. ],
        [ 0.3,  0.7]]])

pyphi.convert.state_by_node2state_by_state(tpm)¶

Convert a state-by-node TPM to a state-by-state TPM.

Note

A nondeterministic state-by-node TPM can have more than one representation as a state-by-state TPM. However, the mapping can be made to be one-to-one if we assume the TPMs to be conditionally independent. Therefore, given a nondeterministic state-by-node TPM, this function returns the corresponding conditionally independent state-by-state.

Note

The indices of the rows of the state-by-node TPM are assumed to follow the LOLI convention, while the indices of the columns follow the HOLI convention. The indices of the rows and columns of the resulting state-by-state TPM both follow the HOLI convention.

Parameters:	tpm (list(list) – A state-by-node TPM with row indices following the LOLI convention and column indices following the HOLI convention.
Returns:	state_by_state_tpm – A state-by-state TPM, with both row and column indices following the HOLI convention.
Return type:	np.ndarray

>>> from pyphi.convert import state_by_node2state_by_state
>>> tpm = np.array([[1, 1, 0],
...                 [0, 0, 1],
...                 [0, 1, 1],
...                 [1, 0, 0],
...                 [0, 0, 1],
...                 [1, 0, 0],
...                 [1, 1, 1],
...                 [1, 0, 1]])
>>> state_by_node2state_by_state(tpm)
array([[ 0.,  0.,  0.,  1.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  1.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  1.,  0.],
       [ 0.,  1.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  1.,  0.,  0.,  0.],
       [ 0.,  1.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  1.],
       [ 0.,  0.,  0.,  0.,  0.,  1.,  0.,  0.]])

db¶

Interface to MongoDB that exposes it as a key-value store.

pyphi.db.find(key)¶

Return the value associated with a key.

If there is no value with the given key, returns None.

pyphi.db.insert(key, value)¶

Store a value with a key.

If the key is already present in the database, this does nothing.

pyphi.db.generate_key(filtered_args)¶

Get a key from some input.

This function should be used whenever a key is needed, to keep keys consistent.

examples¶

Example networks and subsystems to go along with the documentation.

pyphi.examples.basic_network(cm=False)¶

A simple 3-node network with roughly two bits of \(\Phi\).

Diagram:

        +~~~~~~~~+
  +~~~~>|   A    |<~~~~+
  |     |  (OR)  +~~~+ |
  |     +~~~~~~~~+   | |
  |                  | |
  |                  v |
+~+~~~~~~+       +~~~~~+~+
|   B    |<~~~~~~+   C   |
| (COPY) +~~~~~~>| (XOR) |
+~~~~~~~~+       +~~~~~~~+

TPM:

Past state	Current state
A, B, C	A, B, C
0, 0, 0	0, 0, 0
1, 0, 0	0, 0, 1
0, 1, 0	1, 0, 1
1, 1, 0	1, 0, 0
0, 0, 1	1, 1, 0
1, 0, 1	1, 1, 1
0, 1, 1	1, 1, 1
1, 1, 1	1, 1, 0

Connectivity matrix:

.	A	B	C
A	0	0	1
B	1	0	1
C	1	1	0

Note

\(CM_{i,j} = 1\) means that node \(i\) is connected to node \(j\).

pyphi.examples.basic_subsystem()¶

A subsystem containing all the nodes of the basic_network().

pyphi.examples.residue_network()¶

The network for the residue example.

Current and past state are all nodes off.

Diagram:

        +~~~~~~~+         +~~~~~~~+
        |   A   |         |   B   |
    +~~>| (AND) |         | (AND) |<~~+
    |   +~~~~~~~+         +~~~~~~~+   |
    |        ^               ^        |
    |        |               |        |
    |        +~~~~~+   +~~~~~+        |
    |              |   |              |
+~~~+~~~+        +~+~~~+~+        +~~~+~~~+
|   C   |        |   D   |        |   E   |
|       |        |       |        |       |
+~~~~~~~+        +~~~~~~~+        +~~~~~~~+

Connectivity matrix:

.	A	B	C	D	E
A	0	0	0	0	0
B	0	0	0	0	0
C	1	0	0	0	0
D	1	1	0	0	0
E	0	1	0	0	0

pyphi.examples.residue_subsystem()¶

The subsystem containing all the nodes of the residue_network().

pyphi.examples.xor_network()¶

A fully connected system of three XOR gates. In the state (0, 0, 0), none of the elementary mechanisms exist.

Diagram:

+~~~~~~~+       +~~~~~~~+
|   A   +<~~~~~~+   B   |
| (XOR) +~~~~~~>| (XOR) |
+~+~~~~~+       +~~~~~+~+
  | ^               ^ |
  | |   +~~~~~~~+   | |
  | +~~~+   C   +~~~+ |
  +~~~~>| (XOR) +<~~~~+
        +~~~~~~~+

Connectivity matrix:

.	A	B	C
A	0	1	1
B	1	0	1
C	1	1	0

pyphi.examples.xor_subsystem()¶

The subsystem containing all the nodes of the xor_network().

pyphi.examples.cond_depend_tpm()¶

A system of two general logic gates A and B such if they are in the same state they stay the same, but if they are in different states, they flip with probability 50%.

Diagram:

+~~~~~+         +~~~~~+
|  A  |<~~~~~~~~+  B  |
|     +~~~~~~~~>|     |
+~~~~~+         +~~~~~+

TPM:

	(0, 0)	(1, 0)	(0, 1)	(1, 1)
(0, 0)	1.0	0.0	0.0	0.0
(1, 0)	0.0	0.5	0.5	0.0
(0, 1)	0.0	0.5	0.5	0.0
(1, 1)	0.0	0.0	0.0	1.0

Connectivity matrix:

.	A	B
A	0	1
B	1	0

pyphi.examples.cond_independ_tpm()¶

A system of three general logic gates A, B and C such that: if A and B are in the same state then they stay the same; if they are in different states, they flip if C is ON and stay the same if C is OFF; and C is ON 50% of the time, independent of the previous state.

Diagram:

+~~~~~+         +~~~~~+
|  A  +~~~~~~~~>|  B  |
|     |<~~~~~~~~+     |
+~+~~~+         +~~~+~+
  | ^             ^ |
  | |   +~~~~~+   | |
  | ~~~~+  C  +~~~+ |
  +~~~~>|     |<~~~~+
        +~~~~~+

TPM:

	(0, 0, 0)	(1, 0, 0)	(0, 1, 0)	(1, 1, 0)	(0, 0, 1)	(1, 0, 1)	(0, 1, 1)	(1, 1, 1)
(0, 0, 0)	0.5	0.0	0.0	0.0	0.5	0.0	0.0	0.0
(1, 0, 0)	0.0	0.5	0.0	0.0	0.0	0.5	0.0	0.0
(0, 1, 0)	0.0	0.0	0.5	0.0	0.0	0.0	0.5	0.0
(1, 1, 0)	0.0	0.0	0.0	0.5	0.0	0.0	0.0	0.5
(0, 0, 1)	0.5	0.0	0.0	0.0	0.5	0.0	0.0	0.0
(1, 0, 1)	0.0	0.0	0.5	0.0	0.0	0.0	0.5	0.0
(0, 1, 1)	0.0	0.5	0.0	0.0	0.0	0.5	0.0	0.0
(1, 1, 1)	0.0	0.0	0.0	0.5	0.0	0.0	0.0	0.5

Connectivity matrix:

.	A	B	C
A	0	1	0
B	1	0	0
C	1	1	0