Getting started#

Download this page as a Jupyter notebook Open in Colab

This page installs PyPhi and then walks through a complete computation end to end: build a small substrate from the IIT 4.0 paper, analyze it in a chosen state, read off the integrated information \(\varphi_s\) and the associated \(\Phi\)-structure, and save the result to disk. After installing, the walkthrough takes about ten minutes.

Installation#

Using pip#

pip install "pyphi>=2.0.0rc1"                             # 2.0 release candidate
pip install "git+https://github.com/wmayner/pyphi@main"   # latest development version

Your first computation#

Start by importing the package. Turning off the progress bars keeps the output readable here; leave them on for real computations, where they are helpful.

import pyphi

pyphi.config.progress_bars = False

Build a substrate#

A Substrate is a set of interacting units defined by a transition probability matrix and a connectivity matrix. PyPhi ships the example systems used in the IIT literature; we will use the three-unit network the IIT 4.0 paper introduces the theory with (Albantakis et al. 2023, Fig 1A) — three units A, B, and C, each a noisy logistic function of its inputs.

substrate = pyphi.examples.iit4_2023_fig1a_substrate()
substrate
Substrate3 units · A, B, C
UnitsA, B, C
State spacebinary
Connectivity
ABC
A111
B11·
C·11
TPM
stateABC
(0,0,0)0.1192030.768525 0.167982
(1,0,0)0.0265970.998887 0.5
(0,1,0)0.9734030.401312 0.167982
(1,1,0)0.8807970.994514 0.5
(0,0,1)0.1192030.0054863 0.5
(1,0,1)0.0265970.598688 0.832018
(0,1,1)0.9734030.001112540.5
(1,1,1)0.8807970.231475 0.832018

The connectivity matrix shows which units influence which, and the transition probability matrix gives the probability that each unit turns on given the current state of the system. Note the probabilities are strictly between 0 and 1: the network is probabilistic, not deterministic.

Analyze a state#

Integrated information is a property of a substrate in a particular state. We use the state analyzed in the paper — A off, B and C on — ordered (A, B, C), and hand it, together with the substrate, to analyze().

state = (0, 1, 1)
analysis = pyphi.analyze(substrate, state)
analysis
Analysis
Φ4.36567
φs0.133873
Distinctions6
Σφd1.448
Relations45
Σφr2.91768
Distinctions
MechanismφdCause purviewEffect purview
a0.42835 BBC
B0.523043 Ca
aB0.193358 BaB
aC0.0902052aB
BC0.141602 aB
aBC0.0714404aBaB
System
UnitsA,B,C
Current state(0, 1, 1)
Specified cause state(1, 0, 0)
Specified effect state(1, 0, 0)
MIP2 parts: {AB,C}
ii(s)0.718749

That single call runs the whole analysis of the three-unit system: it measures the system’s irreducibility, finds its distinctions, and computes their relations.

Read the results#

The scalar analysis.phi is \(\varphi_s\), the system integrated information — how much the system, as a whole, is irreducible to its parts.

round(analysis.phi, 4)

0.1339

The value is positive: the three units hang together as one system. (It reproduces the value published in the paper’s Fig 1E for this system, 0.13.)

Find the complexes#

Not every subset of units exists as a whole of its own. Subsets compete: among overlapping candidates, only the one with maximal \(\varphi_s\) exists. Such a subset is called a complex. complexes() runs that competition over every subset:

for complex_ in substrate.complexes(state):
    print(complex_.node_indices, round(float(complex_.phi), 4))

(2,) 0.2122
(0, 1) 0.0405

The substrate condenses into two complexes: the single unit C, and the pair {A, B} — the complex the paper features in Fig 1E, written “aB”. (Its \(\varphi_s\) here differs from the published value; see the worked example.) Every other candidate, including the full three-unit system we just analyzed, is excluded by one of these two. This is IIT’s exclusion postulate in action: \(\varphi_s > 0\) makes a candidate eligible; the competition then proceeds recursively — the strongest candidate claims its units first, and the remaining candidates compete over what is left, which is how aB can be a complex even though the full system’s \(\varphi_s\) is larger.

The Φ-structure#

The richer object is the \(\Phi\)-structure, available as analysis.ces (a CauseEffectStructure). It is the collection of distinctions — the irreducible mechanisms the system specifies — together with the relations among them.

ces = analysis.ces
print("distinctions:", len(ces.distinctions))
print("relations:   ", ces.relations.num_relations())

distinctions: 6
relations:    45

Its big_phi attribute is the structure integrated information \(\Phi\), the summed \(\varphi\) of the distinctions and relations.

round(float(ces.big_phi), 4)

4.3657

Every row of the card that analysis prints is explained in Read a result.

Save the result#

Analyses can be expensive, so it is worth saving them. save() writes any PyPhi result object to JSON, and load() reads it back.

pyphi.save(ces, "ces.json")

Where to go next#

That is a full PyPhi computation. From here:

  • To analyze a network of your own, build a substrate from a transition probability matrix, a weight matrix, or a function per unit.

  • The worked example follows this same network through the paper’s Figures 1, 2, and 4, reproducing the published numbers.

  • The theory page What IIT computes explains what these quantities mean and how they are defined.

  • Deterministic networks have \(\varphi_s = 0\), because they provide themselves no alternatives; The intrinsic-information requirement explains why.