subsystem

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

class pyphi.subsystem.Subsystem(network, state, nodes=None, cut=None, repertoire_cache=None, single_node_repertoire_cache=None, forward_repertoire_cache=None, unconstrained_forward_repertoire_cache=None, _external_indices=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.

Keyword Arguments:

• 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. If this is None then the full network will be used.

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

network

The network the subsystem belongs to.

Type:

Network

tpm

The TPM conditioned on the state of the external nodes.

Type:

pyphi.tpm.ExplicitTPM

cm

The connectivity matrix after applying the cut.

Type:

np.ndarray

state

The state of the network.

Type:

tuple[int]

node_indices

The indices of the nodes in the subsystem.

Type:

tuple[int]

cut

The cut that has been applied to this subsystem. Defaults to the null cut.

Type:

Cut

property nodes

The nodes in this Subsystem.

Type:

tuple[Node]

property proper_state

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].

Type:

tuple[int]

property connectivity_matrix

Alias for cm.

Type:

np.ndarray

property size

The number of nodes in the subsystem.

Type:

int

property is_cut

True if this Subsystem has a cut applied to it.

Type:

bool

property cut_indices

The nodes of this subsystem to cut for \(\Phi\) computations.

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

Yields:

tuple[int]

Type:

tuple[int]

property cut_mechanisms

The mechanisms that are cut in this system.

Type:

list[tuple[int]]

property cut_node_labels

Labels for the nodes of this system that will be cut.

Type:

NodeLabels

property tpm_size

The number of nodes in the TPM.

Type:

int

cache_info()

Report repertoire cache statistics.

clear_caches()

Clear the mice and repertoire caches.

__bool__()

Return False if the Subsystem has no nodes, True otherwise.

__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.

__lt__(other)

Return whether this subsystem has fewer nodes than the other.

__gt__(other)

Return whether this subsystem has more nodes than the other.

__len__()

Return the number of nodes in this Subsystem.

to_json()

Return a JSON-serializable representation.

apply_cut(cut)

Return a cut version of this Subsystem.

Parameters:

cut (Cut) – The cut to apply to this Subsystem.

Returns:

The cut subsystem.

Return type:

Subsystem

indices2nodes(indices)

Return Node for these indices.

Parameters:

indices (tuple[int]) – The indices in question.

Returns:

The Node objects corresponding to these indices.

Return type:

tuple[Node]

Raises:

ValueError – If requested indices are not in the subsystem.

cause_repertoire(mechanism, purview, **kwargs)

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:

The cause repertoire of the mechanism over the purview.

Return type:

np.ndarray

Note

The returned repertoire is a distribution over purview node states, not the states of the whole network.

effect_repertoire(mechanism, purview, mechanism_state=None)

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:

The effect repertoire of the mechanism over the purview.

Return type:

np.ndarray

Note

The returned repertoire is a distribution over purview node states, not the states of the whole network.

repertoire(direction, mechanism, purview, **kwargs)

Return the cause or effect repertoire based on a direction.

Parameters:

• direction (Direction) – CAUSE or EFFECT.

• mechanism (tuple[int]) – The mechanism for which to calculate the repertoire.

• purview (tuple[int]) – The purview over which to calculate the repertoire.

Returns:

The cause or effect repertoire of the mechanism over the purview.

Return type:

np.ndarray

Raises:

ValueError – If direction is invalid.

unconstrained_repertoire(direction, purview, **kwargs)

Return the unconstrained cause/effect repertoire over a purview.

unconstrained_cause_repertoire(purview, **kwargs)

Return the unconstrained cause repertoire for a purview.

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

unconstrained_effect_repertoire(purview, **kwargs)

Return the unconstrained effect repertoire for a purview.

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

partitioned_repertoire(direction, partition, repertoire_distance=None, **kwargs)

Compute the repertoire of a partitioned mechanism and purview.

forward_probability(direction: Direction, mechanism: Tuple[int], purview: Tuple[int], purview_state: Tuple[int], **kwargs) → float

forward_effect_probability(mechanism: Tuple[int], purview: Tuple[int], purview_state: Tuple[int], **kwargs) → float

forward_cause_probability(mechanism: Tuple[int], purview: Tuple[int], purview_state: Tuple[int], **kwargs) → float

forward_repertoire(direction: Direction, mechanism: Tuple[int], purview: Tuple[int], **kwargs) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

forward_cause_repertoire(mechanism: Tuple[int], purview: Tuple[int]) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

forward_effect_repertoire(mechanism: Tuple[int], purview: Tuple[int], **kwargs) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

unconstrained_forward_repertoire(direction: Direction, mechanism: Tuple[int], purview: Tuple[int]) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

unconstrained_forward_effect_repertoire(mechanism: Tuple[int], purview: Tuple[int]) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

unconstrained_forward_cause_repertoire(mechanism: Tuple[int], purview: Tuple[int]) → _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

expand_repertoire(direction, repertoire, new_purview=None)

Distribute an effect repertoire over a larger purview.

Parameters:

• direction (Direction) – CAUSE or EFFECT.

• repertoire (np.ndarray) – The repertoire to expand.

Keyword Arguments:

new_purview (tuple[int]) – The new purview to expand the repertoire over. If None (the default), the new purview is the entire network.

Returns:

A distribution over the new purview, where probability is spread out over the new nodes.

Return type:

np.ndarray

Raises:

ValueError – If the expanded purview doesn’t contain the original purview.

expand_cause_repertoire(repertoire, new_purview=None)

Alias for expand_repertoire() with direction set to CAUSE.

expand_effect_repertoire(repertoire, new_purview=None)

Alias for expand_repertoire() with direction set to EFFECT.

cause_info(mechanism, purview, **kwargs)

Return the cause information for a mechanism over a purview.

effect_info(mechanism, purview, **kwargs)

Return the effect information for a mechanism over a purview.

cause_effect_info(mechanism, purview, **kwargs)

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, repertoire=None, partitioned_repertoire=None, repertoire_distance=None, partitioned_repertoire_kwargs=None, **kwargs)

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

Parameters:

• direction (Direction) – CAUSE or EFFECT.

• mechanism (tuple[int]) – The nodes in the mechanism.

• purview (tuple[int]) – The nodes in the purview.

• partition (Bipartition) – The partition to evaluate.

Keyword Arguments:

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

Returns:

The distance between the unpartitioned and partitioned repertoires, and the partitioned repertoire.

Return type:

tuple[int, np.ndarray]

find_mip(direction, mechanism, purview, partitions=None, state=None, **kwargs)

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

Parameters:

• direction (Direction) – CAUSE or EFFECT.

• mechanism (tuple[int]) – The nodes in the mechanism.

• purview (tuple[int]) – The nodes in the purview.

Keyword Arguments:

**kwargs – MapReduce kwargs control parallelization; others are passed to |evaluate_partition|.

Returns:

The irreducibility analysis for the mininum-information partition in one temporal direction.

Return type:

RepertoireIrreducibilityAnalysis

cause_mip(mechanism, purview, **kwargs)

Return the irreducibility analysis for the cause MIP.

Alias for find_mip() with direction set to CAUSE.

effect_mip(mechanism, purview, **kwargs)

Return the irreducibility analysis for the effect MIP.

Alias for find_mip() with direction set to EFFECT.

phi_cause_mip(mechanism, purview, **kwargs)

Return the \(\varphi\) of the cause MIP.

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

phi_effect_mip(mechanism, purview, **kwargs)

Return the \(\varphi\) of the effect MIP.

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

phi(mechanism, purview, **kwargs)

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

intrinsic_information(direction: Direction, mechanism: Tuple[int], purview: Tuple[int], repertoire_distance: str | None = None, states: Iterable[Iterable[int]] | None = None)

potential_purviews(direction, mechanism, purviews=False)

Return all purviews that could belong to the MaximallyIrreducibleCause/MaximallyIrreducibleEffect.

Filters out trivially-reducible purviews.

Parameters:

• direction (Direction) – CAUSE or EFFECT.

• mechanism (tuple[int]) – The mechanism of interest.

Keyword Arguments:

purviews (tuple[int]) – Optional subset of purviews of interest.

find_mice(direction, mechanism, purviews=False, **kwargs)

Return the MaximallyIrreducibleCause or MaximallyIrreducibleEffect for a mechanism.

Parameters:

• direction (Direction) – CAUSE or EFFECT.

• 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:

The MaximallyIrreducibleCause or MaximallyIrreducibleEffect.

Return type:

MaximallyIrreducibleCauseOrEffect

mic(mechanism, purviews=False, **kwargs)

Return the mechanism’s maximally-irreducible cause (MaximallyIrreducibleCause).

Alias for find_mice() with direction set to CAUSE.

mie(mechanism, purviews=False, **kwargs)

Return the mechanism’s maximally-irreducible effect (MaximallyIrreducibleEffect).

Alias for find_mice() with direction set to EFFECT.

phi_max(mechanism)

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

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

property 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, cause_purviews=False, effect_purviews=False, **kwargs)

Return the concept specified by a mechanism within this subsytem.

Parameters:

mechanism (tuple[int]) – The candidate set of nodes.

Keyword Arguments:

• purviews (tuple[tuple[int]]) – Restrict the possible purviews to those in this list.

• cause_purviews (tuple[tuple[int]]) – Restrict the possible cause purviews to those in this list. Takes precedence over purviews.

• effect_purviews (tuple[tuple[int]]) – Restrict the possible effect purviews to those in this list. Takes precedence over purviews.

Returns:

The pair of maximally irreducible cause/effect repertoires that constitute the concept specified by the given mechanism.

Return type:

Concept