Skip to content

IIT 3.0

iitx.measures.iit3

IIT 3.0: concepts, cause-effect structures, and big Φ (Oizumi et al. 2014).

The 3.0 pipeline: freeze the background at the current state; for every mechanism and purview compute cause and effect repertoires (Text S2, Eqs. S2-S9); small φ is the earth mover's distance to the minimum-information bipartition (Eqs. 6-8), maximized over purviews into the maximally irreducible cause and effect (MICE, Eq. 9); mechanisms with φ > 0 are concepts, and together they form the cause-effect structure. Big Φ (Eq. 11) is the extended EMD between the cause-effect structure and the structure recomputed under the minimal unidirectional cut, transporting φ mass between concepts at concept-distance cost, with destroyed mass absorbed by the null concept (Text S2).

The exact EMDs are host linear programs (:func:iitx.distances.emd), so this measure composes with jit and vmap but not with grad — by design, and loudly (docs/design.md §8). Two oracle conventions matter: cause-side φ uses the full Hamming EMD while effect-side φ uses the analytic per-unit form (they differ on correlated repertoires), and every distance is rounded to the measure's precision (1e-6) before any comparison, exactly as PyPhi rounds.

PRECISION = 1e-06 module-attribute

Quantization applied to every distance before comparison (PyPhi's 3.0 PRECISION).

Concepts dataclass

A cause-effect structure: the concepts of a candidate system, as stacked arrays.

Row k describes the mechanism whose mask is row k of iitx.enumeration.subsets(n, nonempty=True); mechanisms with φ = 0 (or outside the candidate) have exists false.

Attributes:

Name Type Description
exists Array

Which mechanisms are concepts (φ > 0 at precision), shape (D,).
phi Array

Concept φ, min(phi_cause, phi_effect), shape (D,).
mechanism Array

Mechanism masks, shape (D, n).
cause_purview Array

Core cause purview masks, shape (D, n).
effect_purview Array

Core effect purview masks, shape (D, n).
cause_repertoire Array

Maximally irreducible cause repertoires, expanded over the full state space (uniform filler), shape (D, *shape).
effect_repertoire Array

Maximally irreducible effect repertoires, expanded over the full state space (unconstrained-product filler), shape (D, *shape).
phi_cause Array

Cause-side φ maxima, shape (D,).
phi_effect Array

Effect-side φ maxima, shape (D,).
Source code in src/iitx/measures/iit3.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@jax.tree_util.register_dataclass
@dataclasses.dataclass(frozen=True)
class Concepts:
	"""A cause-effect structure: the concepts of a candidate system, as stacked arrays.

	Row ``k`` describes the mechanism whose mask is row ``k`` of
	``iitx.enumeration.subsets(n, nonempty=True)``; mechanisms with φ = 0 (or outside
	the candidate) have ``exists`` false.

	Attributes:
		exists: Which mechanisms are concepts (φ > 0 at precision), shape ``(D,)``.
		phi: Concept φ, ``min(phi_cause, phi_effect)``, shape ``(D,)``.
		mechanism: Mechanism masks, shape ``(D, n)``.
		cause_purview: Core cause purview masks, shape ``(D, n)``.
		effect_purview: Core effect purview masks, shape ``(D, n)``.
		cause_repertoire: Maximally irreducible cause repertoires, expanded over the
			full state space (uniform filler), shape ``(D, *shape)``.
		effect_repertoire: Maximally irreducible effect repertoires, expanded over the
			full state space (unconstrained-product filler), shape ``(D, *shape)``.
		phi_cause: Cause-side φ maxima, shape ``(D,)``.
		phi_effect: Effect-side φ maxima, shape ``(D,)``.

	"""

	exists: jax.Array
	phi: jax.Array
	mechanism: jax.Array
	cause_purview: jax.Array
	effect_purview: jax.Array
	cause_repertoire: jax.Array
	effect_repertoire: jax.Array
	phi_cause: jax.Array
	phi_effect: jax.Array

SystemPhi dataclass

Big Φ and its minimal cut (Eq. 11).

Attributes:

Name Type Description
phi Array

Integrated conceptual information Φ at the minimal unidirectional cut, rounded to the measure's precision (as the oracle reports it).
cut_index Array

Index of the minimal cut in the canonical table (:func:iitx.enumeration.directed_bipartitions). Where the oracle's own tied-cut identity is nondeterministic under its parallel evaluation, iitx reports the first tied cut in canonical order.
ces Concepts

The (uncut) cause-effect structure.
Source code in src/iitx/measures/iit3.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
@jax.tree_util.register_dataclass
@dataclasses.dataclass(frozen=True)
class SystemPhi:
	"""Big Φ and its minimal cut (Eq. 11).

	Attributes:
		phi: Integrated conceptual information Φ at the minimal unidirectional cut,
			rounded to the measure's precision (as the oracle reports it).
		cut_index: Index of the minimal cut in the canonical table
			(:func:`iitx.enumeration.directed_bipartitions`). Where the oracle's own
			tied-cut identity is nondeterministic under its parallel evaluation, iitx
			reports the first tied cut in canonical order.
		ces: The (uncut) cause-effect structure.

	"""

	phi: jax.Array
	cut_index: jax.Array
	ces: Concepts

Complex dataclass

One candidate system with its Φ analysis.

Attributes:

Name Type Description
units tuple[int, ...]

The candidate's units.
analysis SystemPhi

Its Φ analysis.
Source code in src/iitx/measures/iit3.py 
520
521
522
523
524
525
526
527
528
529
530
531
@dataclasses.dataclass(frozen=True)
class Complex:
	"""One candidate system with its Φ analysis.

	Attributes:
		units: The candidate's units.
		analysis: Its Φ analysis.

	"""

	units: tuple[int, ...]
	analysis: SystemPhi

ces(system, state, candidate=None)

Compute the cause-effect structure of a candidate system.

Parameters:

Name Type Description Default
system System

The system.

 required
state Array

Current state of the whole system, shape (n,).

 required
candidate tuple[int, ...] | None

Units of the candidate system (static); None means all units.

 None

Returns:

Type Description
Concepts

The concepts, stacked over the nonempty mechanisms of the candidate.
Source code in src/iitx/measures/iit3.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def ces(
	system: System,
	state: jax.Array,
	candidate: tuple[int, ...] | None = None,
) -> Concepts:
	"""Compute the cause-effect structure of a candidate system.

	Args:
		system: The system.
		state: Current state of the whole system, shape ``(n,)``.
		candidate: Units of the candidate system (static); ``None`` means all units.

	Returns:
		The concepts, stacked over the nonempty mechanisms of the candidate.

	"""
	units = tuple(range(system.n)) if candidate is None else tuple(sorted(candidate))
	candidate_mask = _mask(system.n, units)
	factors = condition(
		node_tpms(system, check_independence=False), state, jnp.asarray(candidate_mask)
	)
	return _ces(factors, state, candidate_mask, system.shape)

system_phi(system, state, candidate=None)

Compute big Φ of a candidate system.

Evaluates every unidirectional cut: the cause-effect structure is recomputed under the cut and compared to the whole structure by the extended EMD; Φ is the minimum.

Parameters:

Name Type Description Default
system System

The system.

 required
state Array

Current state of the whole system, shape (n,).

 required
candidate tuple[int, ...] | None

Units of the candidate system (static); None means all units.

 None

Returns:

Type Description
SystemPhi

The Φ analysis at the minimal cut, with the uncut cause-effect structure.
Source code in src/iitx/measures/iit3.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def system_phi(
	system: System,
	state: jax.Array,
	candidate: tuple[int, ...] | None = None,
) -> SystemPhi:
	"""Compute big Φ of a candidate system.

	Evaluates every unidirectional cut: the cause-effect structure is recomputed under
	the cut and compared to the whole structure by the extended EMD; Φ is the minimum.

	Args:
		system: The system.
		state: Current state of the whole system, shape ``(n,)``.
		candidate: Units of the candidate system (static); ``None`` means all units.

	Returns:
		The Φ analysis at the minimal cut, with the uncut cause-effect structure.

	"""
	units = tuple(range(system.n)) if candidate is None else tuple(sorted(candidate))
	n, shape = system.n, system.shape
	candidate_mask = _mask(n, units)
	factors = condition(
		node_tpms(system, check_independence=False), state, jnp.asarray(candidate_mask)
	)

	whole = _ces(factors, state, candidate_mask, shape)
	null_cause, null_effect = _null_repertoires(factors, shape)

	cuts = jnp.asarray(_candidate_cuts(n, units))

	def cut_distance(cut: jax.Array) -> jax.Array:
		partitioned = _ces(sever(factors, cut), state, candidate_mask, shape)
		return _ces_distance(whole, partitioned, null_cause, null_effect, shape)

	distances = quantize(jax.vmap(cut_distance)(cuts), PRECISION)
	index = jnp.argmin(distances)

	# A candidate that is not strongly connected is null by definition (its analysis,
	# including the cause-effect structure, is empty in the oracle's null result).
	strong = strongly_connected(connectivity(system), jnp.asarray(candidate_mask))
	return SystemPhi(
		phi=jnp.where(strong, distances[index], 0.0),
		cut_index=index,
		ces=dataclasses.replace(whole, exists=whole.exists & strong),
	)

major_complex(system, state)

Find the major complex: the candidate system with globally maximal Φ.

Candidates are the strongly connected subsets of two or more units whose conditioned current state is reachable (unreachable candidates are skipped, as the oracle skips them). Ties resolve to the larger candidate, then first in powerset order — matching the oracle's ordering key up to its final index comparison. A Python driver by design; each candidate's analysis is the jitted :func:system_phi.

Parameters:

Name Type Description Default
system System

The system.

 required
state Array

Current state of the whole system, shape (n,).

 required

Returns:

Type Description
Complex | None

The major complex, or None if no candidate has positive Φ.
Source code in src/iitx/measures/iit3.py 
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
def major_complex(system: System, state: jax.Array) -> Complex | None:
	"""Find the major complex: the candidate system with globally maximal Φ.

	Candidates are the strongly connected subsets of two or more units whose conditioned
	current state is reachable (unreachable candidates are skipped, as the oracle skips
	them). Ties resolve to the larger candidate, then first in powerset order — matching
	the oracle's ordering key up to its final index comparison. A Python driver by
	design; each candidate's analysis is the jitted :func:`system_phi`.

	Args:
		system: The system.
		state: Current state of the whole system, shape ``(n,)``.

	Returns:
		The major complex, or ``None`` if no candidate has positive Φ.

	"""
	best: Complex | None = None
	for size in range(2, system.n + 1):
		for units in combinations(range(system.n), size):
			if not is_strongly_connected(system, units):
				continue
			if not _reachable(system, state, units):
				continue
			analysis = system_phi(system, state, units)
			phi = float(analysis.phi)
			if phi > 0.0 and (
				best is None
				or phi > float(best.analysis.phi)
				or (phi == float(best.analysis.phi) and len(units) > len(best.units))
			):
				best = Complex(units=units, analysis=analysis)
	return best