subsystem

Represents a candidate system for \(\varphi\) and \(\Phi\) evaluation.

class pyphi.subsystem.Subsystem(network, state, nodes, cut=None, mice_cache=None, repertoire_cache=None)

A set of nodes in a network.

Parameters:
  • network (Network) – The network the subsystem belongs to.
  • state (tuple[int]) – The state of the network.
  • nodes (tuple[int] or tuple[str]) – The nodes of the network which are in this subsystem. Nodes can be specified either as indices or as labels if the Network was passed node_labels.
Keyword Arguments:
 

cut (Cut) – The unidirectional Cut to apply to this subsystem.

network

Network – The network the subsystem belongs to.

tpm

np.ndarray – The TPM conditioned on the state of the external nodes.

cm

np.ndarray – The connectivity matrix after applying the cut.

state

tuple[int] – The state of the network.

nodes

tuple[Node] – The nodes of the subsystem.

node_indices

tuple[int] – The indices of the nodes in the subsystem.

cut

Cut – The cut that has been applied to this subsystem.

cut_matrix

np.ndarray – A matrix of connections which have been severed by the cut.

null_cut

Cut – The cut object representing no cut.

proper_state

tuple[int]) – The state of the subsystem.

proper_state[i] gives the state of the \(i^{\textrm{th}}\) node in the subsystem. Note that this is not the state of nodes[i].

connectivity_matrix

np.ndarray – Alias for Subsystem.cm.

size

int – The number of nodes in the subsystem.

is_cut

boolTrue if this Subsystem has a cut applied to it.

cut_indices

tuple[int] – The nodes of this subsystem cut for \(\Phi\) computations.

This was added to support MacroSubsystem, which cuts indices other than node_indices.

tpm_size

int – The number of nodes in the TPM.

repertoire_cache_info()

Report repertoire cache statistics.

__repr__()

Return a representation of this Subsystem.

__str__()

Return this Subsystem as a string.

__eq__(other)

Return whether this Subsystem is equal to the other object.

Two Subsystems are equal if their sets of nodes, networks, and cuts are equal.

__bool__()

Return false if the Subsystem has no nodes, true otherwise.

__ne__(other)

Return whether this Subsystem is not equal to the other object.

__ge__(other)

Return whether this Subsystem >= the other object.

__le__(other)

Return whether this Subsystem <= the other object.

__gt__(other)

Return whether this Subsystem > the other object.

__lt__(other)

Return whether this Subsystem < the other object.

__len__()

Return the number of nodes in this Subsystem.

__hash__()

Return the hash value of this Subsystem.

to_json()

Return this Subsystem as a JSON object.

apply_cut(cut)

Return a cut version of this Subsystem.

Parameters:cut (Cut) – The cut to apply to this Subsystem.
Returns:Subsystem
indices2nodes(indices)

Return nodes for these indices.

Parameters:indices (tuple[int]) – The indices in question.
Returns:tuple[Node] – The Node objects corresponding to these indices.
Raises:ValueError – If requested indices are not in the subsystem.
indices2labels(indices)

Returns the node labels for these indices.

cause_repertoire(mechanism, purview)

Return the cause repertoire of a mechanism over a purview.

Parameters:
  • mechanism (tuple[int]) – The mechanism for which to calculate the cause repertoire.
  • purview (tuple[int]) – The purview over which to calculate the cause repertoire.
Returns:

np.ndarray – The cause repertoire of the mechanism over the purview.

Note

The returned repertoire is a distribution over the nodes in the purview, not the whole network. This is because we never actually need to compare proper cause/effect repertoires, which are distributions over the whole network; we need only compare the purview-repertoires with each other, since cut vs. whole comparisons are only ever done over the same purview.

effect_repertoire(mechanism, purview)

Return the effect repertoire of a mechanism over a purview.

Parameters:
  • mechanism (tuple[int]) – The mechanism for which to calculate the effect repertoire.
  • purview (tuple[int]) – The purview over which to calculate the effect repertoire.
Returns:

np.ndarray – The effect repertoire of the mechanism over the purview.

Note

The returned repertoire is a distribution over the nodes in the purview, not the whole network. This is because we never actually need to compare proper cause/effect repertoires, which are distributions over the whole network; we need only compare the purview-repertoires with each other, since cut vs. whole comparisons are only ever done over the same purview.

unconstrained_cause_repertoire(purview)

Return the unconstrained cause repertoire for a purview.

This is just the cause repertoire in the absence of any mechanism.

unconstrained_effect_repertoire(purview)

Return the unconstrained effect repertoire for a purview.

This is just the effect repertoire in the absence of any mechanism.

partitioned_repertoire(direction, partition)

Compute the repertoire of a partitioned mechanism and purview.

expand_repertoire(direction, repertoire, new_purview=None)

Expand a partial repertoire over a purview to a distribution over a new state space.

Parameters:
Keyword Arguments:
 

new_purview (tuple[int]) – The purview to expand the repertoire over. Defaults to the entire subsystem.

Returns:

np.ndarray – The expanded repertoire.

expand_cause_repertoire(repertoire, new_purview=None)

Expand a partial cause repertoire over a purview to a distribution over the entire subsystem’s state space.

expand_effect_repertoire(repertoire, new_purview=None)

Expand a partial effect repertoire over a purview to a distribution over the entire subsystem’s state space.

cause_info(mechanism, purview)

Return the cause information for a mechanism over a purview.

effect_info(mechanism, purview)

Return the effect information for a mechanism over a purview.

cause_effect_info(mechanism, purview)

Return the cause-effect information for a mechanism over a purview.

This is the minimum of the cause and effect information.

evaluate_partition(direction, mechanism, purview, partition, unpartitioned_repertoire=None)

Return the \(\varphi\) of a mechanism over a purview for the given partition.

Parameters:
  • direction (Direction) – PAST or FUTURE.
  • mechanism (tuple[int]) – The nodes in the mechanism.
  • purview (tuple[int]) – The nodes in the purview.
  • partition (Bipartition) – The partition to evaluate.
Keyword Arguments:
 

unpartitioned_repertoire (np.array) – The unpartitioned repertoire. If not supplied, it will be computed.

Returns:

tuple[phi, partitioned_repertoire] – The distance between the unpartitioned and partitioned repertoires, and the partitioned repertoire.

find_mip(direction, mechanism, purview)

Return the minimum information partition for a mechanism over a purview.

Parameters:
  • direction (Direction) – PAST or FUTURE.
  • mechanism (tuple[int]) – The nodes in the mechanism.
  • purview (tuple[int]) – The nodes in the purview.
Returns:

|Mip| – The mininum-information partition in one temporal direction.

mip_past(mechanism, purview)

Return the past minimum information partition.

Alias for find_mip() with direction set to Direction.FUTURE.

mip_future(mechanism, purview)

Return the future minimum information partition.

Alias for find_mip() with direction set to DIRECTIONS[FUTURE].

phi_mip_past(mechanism, purview)

Return the \(\varphi\) of the past minimum information partition.

This is the distance between the unpartitioned cause repertoire and the MIP cause repertoire.

phi_mip_future(mechanism, purview)

Return the \(\varphi\) of the future minimum information partition.

This is the distance between the unpartitioned effect repertoire and the MIP cause repertoire.

phi(mechanism, purview)

Return the \(\varphi\) of a mechanism over a purview.

find_mice(direction, mechanism, purviews=False)

Return the maximally irreducible cause or effect for a mechanism.

Parameters:
  • direction (Direction) – PAST or FUTURE.
  • mechanism (tuple[int]) – The mechanism to be tested for irreducibility.
Keyword Arguments:
 

purviews (tuple[int]) – Optionally restrict the possible purviews to a subset of the subsystem. This may be useful for _e.g._ finding only concepts that are “about” a certain subset of nodes.

Returns:

|Mice| – The maximally-irreducible cause or effect in one temporal direction.

Note

Strictly speaking, the MICE is a pair of repertoires: the core cause repertoire and core effect repertoire of a mechanism, which are maximally different than the unconstrained cause/effect repertoires (i.e., those that maximize \(\varphi\)). Here, we return only information corresponding to one direction, Direction.PAST or Direction.FUTURE, i.e., we return a core cause or core effect, not the pair of them.

core_cause(mechanism, purviews=False)

Return the core cause repertoire of a mechanism.

Alias for find_mice() with direction set to PAST.

core_effect(mechanism, purviews=False)

Return the core effect repertoire of a mechanism.

Alias for find_mice() with direction set to FUTURE.

phi_max(mechanism)

Return the \(\varphi^{\textrm{max}}\) of a mechanism.

This is the maximum of \(\varphi\) taken over all possible purviews.

null_concept

Return the null concept of this subsystem.

The null concept is a point in concept space identified with the unconstrained cause and effect repertoire of this subsystem.

concept(mechanism, purviews=False, past_purviews=False, future_purviews=False)

Calculate a concept.

See pyphi.compute.concept() for more information.

pyphi.subsystem.mip_bipartitions(mechanism, purview, partition_mechanism=False)

Return all \(\varphi\) bipartitions of a mechanism over a purview.

Excludes all bipartitions where one half is entirely empty, e.g:

 A    []
--- X --
 B    []

is not valid, but

A    []
-- X --
[]   B

is.

Parameters:
  • mechanism (tuple[int]) – The mechanism to partition
  • purview (tuple[int]) – The purview to partition
Keyword Arguments:
 

partition_mechanism (boolean) – If True, the mechanism will be strictly partitioned. See pyphi.config.PARTITION_MECHANISMS for more information.

Returns:

list[Bipartition] – Where each bipartition is

bipart[0].mechanism   bipart[1].mechanism
------------------- X -------------------
bipart[0].purview     bipart[1].purview

Example

>>> mechanism = (0,)
>>> purview = (2, 3)
>>> for partition in mip_bipartitions(mechanism, purview):
...     print(partition, "\n")  
[]   0
-- X -
2    3

[]   0
-- X -
3    2

[]    0
--- X --
2,3   []
pyphi.subsystem.effect_emd(d1, d2)

Compute the EMD between two effect repertoires.

Billy’s synopsis: Because the nodes are independent, the EMD between effect repertoires is equal to the sum of the EMDs between the marginal distributions of each node, and the EMD between marginal distribution for a node is the absolute difference in the probabilities that the node is off.

Parameters:
  • d1 (np.ndarray) – The first repertoire.
  • d2 (np.ndarray) – The second repertoire.
Returns:

float – The EMD between d1 and d2.

pyphi.subsystem.emd(direction, d1, d2)

Compute the EMD between two repertoires for a given direction.

The full EMD computation is used for cause repertoires. A fast analytic solution is used for effect repertoires.

Parameters:
  • direction (Direction) – PAST or FUTURE.
  • d1 (np.ndarray) – The first repertoire.
  • d2 (np.ndarray) – The second repertoire.
Returns:

float – The EMD between d1 and d2, rounded to constants.PRECISION.

pyphi.subsystem.measure(direction, d1, d2)

Compute the distance between two repertoires for the given direction.

Parameters:
  • direction (Direction) – PAST or FUTURE.
  • d1 (np.ndarray) – The first repertoire.
  • d2 (np.ndarray) – The second repertoire.
Returns:

float – The distance between d1 and d2, rounded to constants.PRECISION.