Configuration options#

Every option with its default and what it does, read from the configuration classes at build time so the page cannot drift from the code. The three layers and how to set an option are described in Configure PyPhi; the formalism options that define earlier versions of IIT are set together by presets (Reproduce results from earlier versions of IIT). The classes themselves are IITConfig, ActualCausationConfig, InfrastructureConfig, and NumericsConfig.

Show code cell source

Hide code cell source

import ast
import dataclasses
import html
import inspect
import re

from IPython.display import HTML

from pyphi.conf.formalism import ActualCausationConfig, IITConfig
from pyphi.conf.infrastructure import InfrastructureConfig
from pyphi.conf.numerics import NumericsConfig


def attribute_docs(cls):
    """The docstring written under each field of a dataclass, by field name."""
    tree = ast.parse(inspect.getsource(cls))
    body = tree.body[0].body
    docs = {}
    for stmt, nxt in zip(body, body[1:]):
        if (
            isinstance(stmt, ast.AnnAssign)
            and isinstance(stmt.target, ast.Name)
            and isinstance(nxt, ast.Expr)
            and isinstance(nxt.value, ast.Constant)
            and isinstance(nxt.value.value, str)
        ):
            docs[stmt.target.id] = nxt.value.value
    return docs


def describe(doc):
    """The docstring as HTML: roles become plain names, literals become code."""
    text = " ".join(doc.split())
    text = re.sub(r":\w+:`~?([^`<]+?)(?: <[^>]*>)?`", r"\1", text)
    text = html.escape(text, quote=False)
    return re.sub(r"``([^`]+)``", r"<code>\1</code>", text)


LAYERS = (
    ("Formalism: IIT", "formalism.iit", IITConfig),
    ("Formalism: actual causation", "formalism.actual_causation", ActualCausationConfig),
    ("Infrastructure", "infrastructure", InfrastructureConfig),
    ("Numerics", "numerics", NumericsConfig),
)
parts = ['<div class="pp-options">']
for title, layer, cls in LAYERS:
    docs = attribute_docs(cls)
    instance = cls()
    parts.append(f"<h2>{title} <small>({layer})</small></h2><dl>")
    for field in dataclasses.fields(cls):
        default = html.escape(repr(getattr(instance, field.name)))
        parts.append(
            f'<dt id="opt-{field.name}"><code>{field.name}</code>'
            f' <span class="pp-default">= {default}</span></dt>'
            f"<dd>{describe(docs.get(field.name, ''))}</dd>"
        )
    parts.append("</dl>")
parts.append("</div>")
HTML("".join(parts))

Formalism: IIT (formalism.iit)

version = 'IIT_4_0_2026': Which IIT formalism computes results: "IIT_4_0_2026" (default; IIT 4.0 with the intrinsic-information requirement of Mayner et al. 2026), "IIT_4_0_2023" (Albantakis et al. 2023), or "IIT_3_0" (Oizumi et al. 2014). Select a version through a preset (pyphi.iit3, pyphi.iit4_2023, pyphi.iit4_2026) or the formalism= argument of pyphi.analyze, which also set the measures and schemes the version requires; changing this option alone can leave the others at values the version rejects.
mechanism_phi_measure = 'GENERALIZED_INTRINSIC_DIFFERENCE': The distance between a mechanism's repertoire and its partitioned repertoire, from which a distinction's φ is computed. IIT 4.0 accepts "GENERALIZED_INTRINSIC_DIFFERENCE" (default) and "INTRINSIC_INFORMATION". IIT 3.0 accepts a distribution distance: "EMD" (the 2014 paper's earth mover's distance, set by the iit3 preset), "KLD", "L1", "ENTROPY_DIFFERENCE", "ID", "AID", "PSQ2", or "MP2Q". A version rejects a measure it does not define.
system_phi_measure = 'INTRINSIC_INFORMATION': How system integrated information φₛ is computed under IIT 4.0. "INTRINSIC_INFORMATION" (default) applies the intrinsic-information requirement, φₛ = min(φ_c, φ_e, ii(s)) (Mayner et al. 2026, Eq. 23); "GENERALIZED_INTRINSIC_DIFFERENCE" gives the 2023 definition, φₛ = min(φ_c, φ_e), without it. IIT 3.0 does not read this option.
specification_measure = 'GENERALIZED_INTRINSIC_DIFFERENCE': The measure that selects the specified state, the purview or system state with maximal intrinsic information, under IIT 4.0: "GENERALIZED_INTRINSIC_DIFFERENCE" (default), "INTRINSIC_INFORMATION", or "INTRINSIC_SPECIFICATION". IIT 3.0 does not read this option.
ces_measure = 'SUM_SMALL_PHI': The distance between the unpartitioned and partitioned cause-effect structures, which is IIT 3.0's system-level Φ: "SUM_SMALL_PHI" (default; the summed φ of the concepts the partition destroys or changes) or "EMD" (the 2014 paper's earth mover's distance over concept space, set by the iit3 preset). IIT 4.0 accepts only "SUM_SMALL_PHI".
mechanism_partition_scheme = 'JOINT_PARTITION_ALL': How a mechanism and its purview are partitioned when a distinction's irreducibility is evaluated: "JOINT_PARTITION_ALL" (default; every partition of the mechanism and purview into any number of parts, the IIT 4.0 scheme), "JOINT_BIPARTITION" (bipartitions only, the IIT 3.0 scheme, set by the iit3 preset), or "WEDGE_TRIPARTITION" (bipartitions of the mechanism with a third part cut from the purview).
system_partition_scheme = 'DIRECTED_SET_PARTITION': How a system is partitioned when φₛ is evaluated: "DIRECTED_SET_PARTITION" (default; every set partition of the units with a direction assigned to each part, the IIT 4.0 scheme), "DIRECTED_BIPARTITION" (the IIT 3.0 scheme, set by the iit3 preset), "DIRECTED_BIPARTITION_CUT_ONE", "DIRECTED_BIPARTITION_SEQUENTIAL", "EDGE_CUT_ALL", or "EDGE_CUT_BIDIRECTIONAL". IIT 3.0 accepts only the two directed bipartition schemes. Under IIT 4.0 a non-default scheme computes a well-defined φₛ for that scheme, which is not the papers' value.
system_partition_include_total = False: Whether the system partition search includes the total partition, which severs every connection (default False). A single-unit system always includes it, since it has no other partition.
distinction_phi_normalization = 'NUM_CONNECTIONS_CUT': How a distinction's φ is normalized before candidate partitions are compared: "NUM_CONNECTIONS_CUT" (default; divided by the number of connections the partition severs, the IIT 4.0 rule) or "NONE" (the raw value, set by the iit3 preset).
background_conditioning = 'CAUSAL_MARGINALIZATION': How the units outside a candidate system (its background) enter its cause repertoires when the system is a proper subset of the substrate: "CAUSAL_MARGINALIZATION" (default; the background's past is causally marginalized conditional on the current state, IIT 4.0, Albantakis et al. 2023, Eq. 4) or "CONDITION_CURRENT_STATE" (the background is fixed at its observed current state, the PyPhi 1.x convention, set by the iit3 preset and the only value IIT 3.0 accepts). The effect side conditions the background at its current state under both, and a system that is the whole substrate has no background, so neither is affected.
relation_computation = 'ANALYTICAL': How the relations of a Φ-structure are computed: "ANALYTICAL" (default; relation counts and φ sums in closed form, without enumerating relations, so individual relations cannot be listed) or "CONCRETE" (every relation enumerated, which grows exponentially with the number of distinctions). See pyphi.relations.
assume_partitions_cannot_create_new_concepts = False: IIT 3.0 only. When True, evaluating a system partition considers only the mechanisms that were concepts in the unpartitioned system, which is faster but misses concepts a partition creates. Default False.
shortcircuit_sia = True: When True (default), IIT 4.0 analyses stop early on detected reducibility: a system whose specified state has no cause or no effect returns a null result without a partition search, and the system- and mechanism-level partition sweeps stop at the first partition with zero integrated information. Computed φ values are unchanged; early stops leave the selection margins undefined, since the remaining partitions were never evaluated. When False, every partition is evaluated and the margins are exact. Does not affect IIT 3.0's own early exits.
shortcircuit_distinctions = True: When True (default), evaluating a distinction stops early on detected reducibility: if the effect direction has no candidate purviews, neither search runs, and if the cause's maximally irreducible purview has φ = 0, the effect search is skipped. The distinction's φ, the minimum over the two directions, is unchanged, so cause-effect structures are identical either way; only the contents of zero-φ distinctions differ (the skipped direction is a null result without margins or ties). Applies to every formalism.
single_micro_nodes_with_selfloops_have_phi = True: Whether a single-unit system whose unit has a self-connection can have positive φₛ (default True). When False, such systems have φₛ = 0 by definition, the PyPhi 1.x convention set by the iit3 preset. A single unit without a self-connection has φₛ = 0 regardless.
state_tie_resolution = 'PHI': How a tie among candidate specified states is broken: a strategy name or a list applied in order, keeping the candidates that are extremal under each. "PHI" (default) keeps the states with maximal φ, and the tie survives in the result if several remain. Other strategies: "NORMALIZED_PHI", "PURVIEW_SIZE", their "NEGATIVE_*" forms, "PARTITION_LEX", and "NONE" (keep all). See /howto/tie-breaking.
mip_tie_resolution = ('NORMALIZED_PHI', 'NEGATIVE_PHI'): How a tie among a mechanism's candidate partitions at the minimum is broken, a list of strategies applied in order. The default ("NORMALIZED_PHI", "NEGATIVE_PHI") keeps the partitions with the smallest normalized φ, then those with the largest raw φ; the iit3 preset uses ("PHI", "PARTITION_LEX"). See /howto/tie-breaking.
purview_tie_resolution = 'PHI': How a tie among purviews with maximal φ is broken, a strategy name or a list applied in order. "PHI" (default) keeps every purview at the maximum, so the tie is reported on the result; the iit3 preset uses ("PHI", "PURVIEW_SIZE"), which then keeps the largest purview, the PyPhi 1.x convention. See /howto/tie-breaking.
sia_tie_resolution = ('NORMALIZED_PHI', 'NEGATIVE_PHI', 'PARTITION_LEX'): How a tie among system partitions at the minimum is broken, a list of strategies applied in order. The default ("NORMALIZED_PHI", "NEGATIVE_PHI", "PARTITION_LEX") keeps the partitions with the smallest normalized φ, then the largest raw φ, then the first in lexicographic order, so one minimum partition is always selected; a partition_margin of zero on the result records that it was tied. The iit3 preset uses ("PHI", "PARTITION_LEX"). See /howto/tie-breaking.

Formalism: actual causation (formalism.actual_causation)

version = 'AC_2019': The actual-causation formalism: "AC_2019" (Albantakis et al. 2019) is the only registered version.
alpha_measure = 'PMI': The pointwise information measure behind a causal link's strength α: "PMI" (default; pointwise mutual information, the 2019 paper) or "WPMI" (pointwise mutual information weighted by the probability of the occurrence).
mechanism_partition_scheme = 'JOINT_PARTITION_ALL': The family of partitions searched for an occurrence's minimum information partition: "JOINT_PARTITION_ALL" (default; the 2019 paper's family, Eq. 7 and Fig. 3B, which excludes the single-part cuts the paper forbids for first-order occurrences), "JOINT_BIPARTITION" (a variant that admits those cuts and so gives lower α on first-order occurrences), or "WEDGE_TRIPARTITION". Read independently of the IIT option of the same name.
partitioned_repertoire_scheme = 'PRODUCT': How the partitioned repertoire of an occurrence is formed: "PRODUCT" (the product of the parts' repertoires) is the only registered value.
background_scheme = 'UNIFORM': How units outside the transition are treated: "UNIFORM" (marginalized under a uniform distribution) is the only registered value.
alpha_aggregation = 'SUBTRACTIVE': How α is obtained from the unpartitioned and partitioned information: "SUBTRACTIVE" (their difference) is the only registered value.

Infrastructure (infrastructure)

parallel = False: Master switch for parallel computation (default False). False runs every level sequentially; True permits the levels whose own parallel_*_evaluation mapping has parallel set. See /howto/parallel.
parallel_complex_evaluation = FrozenMap({'parallel': False, 'sequential_threshold': 16, 'chunksize': 64, 'progress': True}): Parallelism for the candidate systems of a complexes search: a mapping with the keys parallel (whether this level may run in parallel; False by default), sequential_threshold (workloads with fewer items than this run sequentially regardless), chunksize (items per task), and progress (show a progress bar). A partial mapping merges over the level's defaults; unknown keys are rejected. The master switch parallel must also be on. See /howto/parallel.
parallel_partition_evaluation = FrozenMap({'parallel': False, 'sequential_threshold': 64, 'chunksize': 4096, 'progress': False}): Parallelism for the system partitions of a system irreducibility analysis: a mapping with the keys parallel (whether this level may run in parallel; False by default), sequential_threshold (workloads with fewer items than this run sequentially regardless), chunksize (items per task), and progress (show a progress bar). A partial mapping merges over the level's defaults; unknown keys are rejected. The master switch parallel must also be on. See /howto/parallel.
parallel_distinction_evaluation = FrozenMap({'parallel': False, 'sequential_threshold': 64, 'chunksize': 256, 'progress': True}): Parallelism for the mechanisms of a cause-effect structure: a mapping with the keys parallel (whether this level may run in parallel; False by default), sequential_threshold (workloads with fewer items than this run sequentially regardless), chunksize (items per task), and progress (show a progress bar). A partial mapping merges over the level's defaults; unknown keys are rejected. The master switch parallel must also be on. See /howto/parallel.
parallel_purview_evaluation = FrozenMap({'parallel': False, 'sequential_threshold': 64, 'chunksize': 256, 'progress': True}): Parallelism for the candidate purviews of a mechanism: a mapping with the keys parallel (whether this level may run in parallel; False by default), sequential_threshold (workloads with fewer items than this run sequentially regardless), chunksize (items per task), and progress (show a progress bar). A partial mapping merges over the level's defaults; unknown keys are rejected. The master switch parallel must also be on. See /howto/parallel.
parallel_mechanism_partition_evaluation = FrozenMap({'parallel': False, 'sequential_threshold': 8192, 'chunksize': 4096, 'progress': True}): Parallelism for the partitions of a mechanism and purview: a mapping with the keys parallel (whether this level may run in parallel; False by default), sequential_threshold (workloads with fewer items than this run sequentially regardless), chunksize (items per task), and progress (show a progress bar). A partial mapping merges over the level's defaults; unknown keys are rejected. The master switch parallel must also be on. See /howto/parallel.
parallel_relation_evaluation = FrozenMap({'parallel': False, 'sequential_threshold': 8192, 'chunksize': 4096, 'progress': True}): Parallelism for the relations of a Φ-structure under concrete relation computation: a mapping with the keys parallel (whether this level may run in parallel; False by default), sequential_threshold (workloads with fewer items than this run sequentially regardless), chunksize (items per task), and progress (show a progress bar). A partial mapping merges over the level's defaults; unknown keys are rejected. The master switch parallel must also be on. See /howto/parallel.
parallel_macro_system_evaluation = FrozenMap({'parallel': False, 'sequential_threshold': 16, 'chunksize': 64, 'progress': True}): Parallelism for the candidate macro systems of a grain search: a mapping with the keys parallel (whether this level may run in parallel; False by default), sequential_threshold (workloads with fewer items than this run sequentially regardless), chunksize (items per task), and progress (show a progress bar). A partial mapping merges over the level's defaults; unknown keys are rejected. The master switch parallel must also be on. See /howto/parallel.
parallel_workers = -1: Number of worker processes or threads; -1 (default) uses every core.
parallel_backend = 'local': Where parallel work runs: "local" (default; a pool of processes), "thread" (a pool of threads), or "auto" (threads on a free-threaded interpreter, processes otherwise). Cluster schedulers are configured through pyphi.parallel and the cluster extra.
memory_ceiling_percentage = 50: The share of the memory this process may use that the in-memory caches may occupy (default 50), above which they evict least recently used entries to admit new ones. The denominator is the process's cgroup allowance where it has one (a scheduler-managed job, a container) and total physical memory otherwise.
memory_ceiling_bytes = None: An absolute ceiling on the process's resident memory, above which the in-memory caches hold their occupancy steady by evicting least recently used entries (default None). Replaces memory_ceiling_percentage when set, for an allowance no cgroup reports. It is compared against the whole process's resident memory, of which the caches are usually a small part, so size it from what the process may use: the caches get the ceiling less the interpreter, the substrate, and working space.
cache_repertoires = True: Cache the repertoires computed within a system (default True). False recomputes them on every use, which is slower but bounds memory.
cache_potential_purviews = True: Cache each mechanism's connectivity-pruned candidate purviews on the substrate (default True).
cache_macro_construction = True: Cache the mapping-independent intermediates of macro-unit construction (the discounted transition matrix and the per-grain sequence-class distributions) per substrate, so candidate units that share a footprint, update grain, and apportionment reuse them (default True). Results are identical either way.
clear_system_caches_after_computing_sia = False: Clear a system's caches after each system irreducibility analysis (default False). Frees memory in sweeps over many systems at the cost of recomputing what a later analysis of the same system would have reused.
disk_cache_results = False: Persist top-level results (system irreducibility analyses and cause-effect structures) to a content-addressed cache on disk, in __pyphi_cache__ under the working directory, and reuse them across runs (default False). The key includes the configuration and the code version, so a changed setting or release never returns a stale result. See /howto/cache.
progress_bars = True: Show progress bars during long computations (default True).
repr_verbosity = 2: How much a result's repr shows, 0 to 4: 0 the one-line compact form; 1 the card without expensive embedded grids such as a substrate's TPM; 2 (default) the standard card; 3 the card plus all mathematical content, such as partition cut grids and selection margins; 4 that plus a provenance section recording how, when, and by what code the result was computed.
repr_max_table_rows = 50: Maximum rows shown in a collection table (distinctions, relations, account links) in a result's text or HTML rendering (default 50). Larger collections are truncated with a "… N more" line; the full data is always available from the object itself and to_pandas().
print_fractions = True: When True (default), a probability in text output that is close to a simple fraction (denominator at most 128) is printed as that fraction; otherwise probabilities print as decimals at the configured precision.
label_separator = '': The string placed between unit labels when a set of units is written as one label (default "", so units A and B print as AB; "," gives A,B).
welcome_off = False: Suppress the welcome message printed when PyPhi is imported (default False). The environment variable PYPHI_WELCOME_OFF has the same effect. Controls only the welcome; the agent note has its own switch.
agent_note_off = False: Suppress the note printed to standard error when PyPhi is imported under an AI coding agent, detected through the CLAUDECODE or PYPHI_AGENT environment variables (default False). The environment variable PYPHI_AGENT_NOTE_OFF has the same effect. Independent of welcome_off: the two messages have different audiences and channels.
validate_system_states = True: When True (default), constructing a system checks that its state can be reached under the substrate's dynamics and raises pyphi.exceptions.StateUnreachableForwardsError otherwise, since a state with no possible predecessor has no defined analysis.
validate_conditional_independence = True: When True (default), constructing a substrate checks that its units are conditionally independent given the previous state and raises pyphi.exceptions.ConditionallyDependentError otherwise. See /theory/conditional-independence.
validate_connectivity = True: When True (default), a substrate's connectivity matrix is checked against the connections its TPM implies, and a matrix that omits a real connection (which would silently marginalize a true dependency and under-count φ) is rejected with a ValueError naming the missing connections. Declaring an unused connection stays legal. Set False for a deliberately permissive matrix.
validate_phi_bounds = False: When True, every result checks its φ against the certified upper bound of Zaeemzadeh et al. (2024) and raises BoundViolationError on an overshoot within the bound's domain, which would prove a formalism bug. Off by default, since it adds bound arithmetic to the hot path; intended for continuous integration and debugging. Outside the certified domain (non-binary units, other measures) the check is skipped.
validate_config = True: When True (default), combinations of options are checked eagerly on override and when a configuration file is loaded, so that an IIT version paired with a measure or scheme it does not define is rejected with a ConfigurationError naming the two fields and a fix (see pyphi.conf.constraints). Set False to experiment with unsupported combinations.

Numerics (numerics)

precision = 13: Decimal places of agreement required when φ, Φ, and α values are compared through pyphi.numerics.eq and the other pyphi.numerics predicates; values smaller than 10**-precision are treated as zero (default 13; the iit3 preset sets 6).