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 – A dictionary where keys are directions, and values are MarblSets containing Marbls generated from the TPMs of the mechanism nodes’ corresponding to the direction.


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


dict – The inverse of normalized_indices.


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.


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


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.


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


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


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


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


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.


NormalizedMechanism – The mechanism the concept consists of.


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


NormalizedMice – The concept’s normalized core cause.


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.