pyphi.core.tpm.factored.FactoredTPM#

class pyphi.core.tpm.factored.FactoredTPM(factors, state_space=None, backend=None, node_labels=None)[source]#

Bases: Displayable, ToPandasMixin

Per-node-factored conditional TPM.

Stored factors are read-only and independent of the arrays passed in: a hashed value type’s contents cannot change after construction.

Parameters:

  • factors (Sequence[ArrayLike])

  • state_space (StateSpace)

  • backend (Literal['ndarray', 'xarray'] | None)

  • node_labels (Sequence[str] | None)

property state_space: tuple[tuple[Any, ...], ...]#

Per-node label tuples, e.g. ((0, 1), (0, 1)) for binary nodes.

property node_labels: tuple[str, ...] | None#

Per-unit display labels (node names), or None for integer indices.

property alphabet_sizes: tuple[int, ...]#

Number of states per node, derived from state_space.

classmethod from_joint(joint, /, state_space=None)[source]#

Convert a joint conditional TPM into the factored form.

Accepts either:

  • Binary state-by-node form: shape (2,) * n + (n,), where the last dim’s entry i is P(node_i = 1 | s_t). Factor i is built by stacking [1 - p_on, p_on] along an explicit alphabet dim.

  • Explicit-alphabet form: shape (a_1, ..., a_N, N, a_i). Factor i is joint[..., i, :].

state_space follows the same rules as FactoredTPM.__init__. When None, integer labels are inferred from the joint’s shape.

Parameters:
Return type:

FactoredTPM

tpm_indices()[source]#

Substrate-unit indices: one entry per output unit (the leading factor axes); the trailing alphabet axis is per-unit.

Return type:

tuple[int, …]

to_joint()[source]#

Materialize the joint conditional P(s_{t+1} | s_t) from the factors.

Output shape is alphabet_sizes + (n_nodes, max_alphabet): the per-row last dim holds factor i’s distribution in slots [:alphabet_sizes[i]]; trailing slots are zero when alphabets are heterogeneous. For uniform alphabets this collapses to (a, ..., a, n, a) with no padding.

Materializing the joint costs exponential space in the number of units, so this is used only at boundaries where a dense joint is required (serialization, Substrate.joint_tpm()).

Return type:

ndarray[tuple[Any, …], dtype[float64]]

infer_edge(a, b)[source]#

Whether the TPM implies a causal edge from node a to node b.

There is an edge iff node b’s conditional distribution depends on node a’s state — i.e. factor b is not constant along input axis a. Equivalently, P(b | s) != P(b | s') for two input states s, s' differing only in node a. Holds for any per-node alphabet size.

Parameters:
Return type:

bool

infer_cm()[source]#

Infer the connectivity matrix implied by the TPM.

Entry [a, b] is 1 iff the TPM implies an edge from node a to node b (see infer_edge()); diagonal entries mark self-edges. Inferred per factor without materializing the joint, so the cost is O(N^2 * factor_size).

Return type:

ndarray[tuple[Any, …], dtype[int64]]

is_deterministic()[source]#

Whether every transition is deterministic.

True iff every factor’s probabilities are all exactly 0 or 1, so each unit’s next state is a deterministic function of the input state.

Return type:

bool

permute_nodes(permutation)[source]#

Reorder the substrate units by a permutation.

Unit permutation[k] takes position k in the result: the factor list is reordered, each factor’s leading input axes are transposed by the same permutation (so axis k still indexes the unit now at position k), and state_space / node_labels follow.

Parameters:

permutation (Sequence[int]) – A permutation of range(n_nodes) — one entry per unit.

Returns:

FactoredTPM – The relabeled TPM.

Raises:

ValueError – If permutation does not have length n_nodes.

Return type:

FactoredTPM

subtpm(fixed_nodes, state)[source]#

Return the TPM over the free units, conditioned on the fixed units.

The units in fixed_nodes are frozen at state (in the same order) and removed; the result is a FactoredTPM over just the remaining (free) units, whose transitions depend only on free-unit inputs.

Parameters:

  • fixed_nodes (Sequence[int]) – The units to condition on and drop.

  • state (Sequence[int]) – The state (per-unit integer index) of each fixed unit.

Returns:

FactoredTPM – The conditioned TPM over the free units.

Return type:

FactoredTPM

unit_labels_for_display()[source]#

Per-unit display labels: node names if set, else integer indices.

Return type:

list[str]

grid_section()[source]#

The transition-probability grid as a labeled display Section.

Binary substrates get one P(on) column per unit; non-binary ones get one column per (unit, next-state) pair. Shared by this TPM’s own card and the embedding Substrate card.

Return type:

Section

to_xarray()[source]#

Return the factored conditional as a labeled xarray.Dataset.

Each unit i is a data variable "unit_{i}" holding P(unit i next | inputs) with dims ("u0", ..., "u{N-1}", "u{i}_next") and integer coordinates from state_space. Requires the optional xarray dependency.

Return type:

Any