API Reference

This page provides complete API documentation for all public classes and functions in StateTracker, automatically generated from source code docstrings.

Core Classes

State

The main class for creating and composing states.

class statetracker.State(num_values=None, name=None, value=None, iter_order=None, *, _parents=None, _op=None)

Bases: object

A state that can be iterated and composed with other states.

__init__(num_values=None, name=None, value=None, iter_order=None, *, _parents=None, _op=None)

Create a state.

property iter_order

Iteration order for this state.

property num_values

Number of values this state can take (read-only).

property id

Unique ID assigned by Manager (None if not registered).

property name

Name of this counter.

named(name)

Set name and return self for fluent chaining.

synced_parent(name=None)

Create a synced state that shares this state’s value.

sync_with(other)

Synchronize this state with another (bidirectional).

Return type:

None

property value

Current value of this state.

advance()

Advance to next value (wraps around using this state’s num_values).

reset(value=0)

Reset to specified value (default 0).

property is_active: bool

True if state is active (value is not None). Read-only.

__iter__()

Iterate through all values of this state.

__getitem__(key)

Create sliced state: B = A[1:5] or A[::2] or A[::-1].

copy(name=None)

Create a shallow copy with the same parents but a new State object.

deepcopy(name=None)

Create a deep copy with all ancestors also copied.

print_dag(style='clean')

Print the ASCII tree visualization rooted at this state.

Parameters:

style (str) – Display style - ‘clean’ (default), ‘minimal’, or ‘repr’.

get_iteration_df(**kwargs)

get_ancestors()

get_states(include_inactive=True, named_only=True)

Return dict of {name: value} for this state and all ancestors.

Parameters:

• include_inactive (bool) – If True (default), include states with None value. If False, only include states that are currently active.

• named_only (bool) – If True (default), exclude states with auto-generated names (State[N]). If False, include all states.

Return type:

dict

Returns:

Dictionary mapping state names to their current values, in reverse topological order (derived states first, parents last).

print_states(include_inactive=True, named_only=True)

Print current values of this state and its ancestors.

Parameters:

• include_inactive (bool) – If True (default), include states with None value. If False, only include states that are currently active.

• named_only (bool) – If True (default), exclude states with auto-generated names (State[N]). If False, include all states.

Return type:

None

Manager

Context manager that must wrap all state operations.

class statetracker.Manager

Bases: object

Context manager for handling State objects.

__init__()

Initialize empty state manager.

__enter__()

Enter context and set as active manager, saving any previous.

__exit__(exc_type, exc_val, exc_tb)

Exit context and restore previous active manager.

register(state)

Register a state with this manager.

get_ancestors(state, visited=None)

Recursively collect all ancestor states and sync group peers.

clear_all_values()

Directly clear all states and sync groups to None (bypasses setter).

inactivate_all(states=None)

Set states to inactive value (None).

reset_all(states=None)

Reset states to value 0.

get_all_names()

Return list of names of all registered states.

get_by_name(name)

Return state by name.

get_iteration_df(iter_state, states=None)

Return DataFrame showing value of states as iter_state is iterated.

print_graph(style='clean')

Print an ASCII tree visualization of the state dependency graph.

Parameters:

style (str) – Display style - ‘clean’ (default), ‘minimal’, or ‘repr’.

Operation

Abstract base class for all state operations.

class statetracker.Operation

Bases: ABC

Base class for state operations.

abstractmethod compute_num_states(parent_num_values)

Compute num_values for this node given parent num_values.

Return type:

int

abstractmethod decompose(value, parent_num_values)

Decompose this node’s value into parent values.

Return type:

tuple[int, ...]

Exceptions

exception statetracker.ConflictingValueAssignmentError

Bases: RuntimeError

Raised when a state receives conflicting value assignments during propagation.

State Operation Functions

These functions create new states by combining or transforming existing states.

Product Operations

statetracker.product(states, name=None)

Create a State representing the cartesian product of the provided States.

Parameters:

• states (Sequence[statetracker.state.State]) – Sequence of parent States to combine into a product State. No duplicates allowed.

• name (Optional[str]) – Optional name for the resulting product State.

Returns:

A State whose values index the cartesian product of the input states’ values.

Return type:

State_type

statetracker.ordered_product(states, name=None)

Create a product State from the provided states, removing duplicates and automatically imposing an order based on state.iter_order and state.id.

This function recursively flattens nested product states before deduplication, which handles diamond patterns where the same state appears both as a direct parent and as an ancestor through another parent.

Parameters:

• states (Sequence[statetracker.state.State]) – Sequence of parent States to combine into the product. Duplicates are removed and order is determined by (iter_order, id).

• name (Optional[str]) – Name for the resulting product State.

Returns:

A State representing the ordered, uniquified cartesian product of the input states.

Return type:

State_type

Notes

Product is associative, so nested products are flattened: ordered_product([A*B, C, D*A]) becomes ordered_product([A, B, C, D])

Non-product operations (like stack, slice) are NOT flattened: ordered_product([stack(A,B), C]) keeps stack(A,B) as an atomic unit.

statetracker.set_product_order_mode(mode)

Set the global ordering mode for ordered_product().

Return type:

None

statetracker.get_product_order_mode()

Get the current global ordering mode for ordered_product().

Return type:

str

Stack (Disjoint Union)

statetracker.stack(states, name=None)

Create a State representing the disjoint union of the provided States.

Parameters:

• states (Sequence[statetracker.state.State]) – Sequence of parent States to combine into a disjoint union State.

• name (Optional[str]) – Optional name for the resulting disjoint union State.

Returns:

A State whose values correspond to the disjoint union of the input States’ values.

Return type:

State_type

Synchronize

statetracker.sync(a, b)

Synchronize two existing states (bidirectional).

Return type:

None

statetracker.synced_to(child_state, name=None, num_values=None)

Create a new state synchronized with child_state.

Parameters:

• child_state (statetracker.state.State) – The state to synchronize with.

• name (Optional[str]) – Optional name for the new state.

• num_values (Optional[Integral]) – Optional number of values for the new state. If not provided, uses child_state.num_values. Can be different from child_state.num_values - the group will track the max and states receive None when out of range.

Return type:

statetracker.state.State

Returns:

A new State synchronized with child_state.

Slice

statetracker.slice(state, start=None, stop=None, step=None, name=None)

Create a State whose values correspond to a slice of the parent State.

Parameters:

• state (statetracker.state.State) – The State to be sliced.

• start (Optional[Integral]) – Start index of the slice (inclusive).

• stop (Optional[Integral]) – Stop index of the slice (exclusive).

• step (Optional[Integral]) – Step size for the slice.

• name (Optional[str]) – Name for the resulting sliced State.

Returns:

A State whose values correspond to the specified slice of the parent State’s values.

Return type:

State_type

Repeat

statetracker.repeat(state, times, name=None)

Create a State that repeats the values of another State a specified number of times.

Parameters:

• state (statetracker.state.State) – The State to repeat.

• times (Integral) – Number of times to repeat the entire sequence of the parent’s values.

• name (Optional[str]) – Name for the resulting repeated State.

Returns:

A State whose values iterate through the parent’s values, repeated the specified number of times.

Return type:

State_type

Shuffle

statetracker.shuffle(state, seed=None, permutation=None, name=None)

Create a State with the values of a parent State randomly shuffled.

Parameters:

• state (statetracker.state.State) – The State whose values will be shuffled.

• seed (Optional[Integral]) – Random seed to generate the shuffle permutation. Cannot be provided with ‘permutation’.

• permutation (Optional[Sequence[Integral]]) – Explicit permutation of parent value indices, as a sequence of length parent.num_values. Cannot be provided with ‘seed’.

• name (Optional[str]) – Name for the resulting shuffled State.

Returns:

A State whose value order corresponds to a permutation of the parent’s values.

Return type:

State_type

Sample

statetracker.sample(state, num_values=None, sampled_states=None, seed=None, with_replacement=True, name=None)

Create a State that samples values from the provided parent State.

Parameters:

• state (statetracker.state.State) – Parent State whose values will be sampled.

• num_values (Optional[Integral]) – Number of values to sample from the parent. Mutually exclusive with ‘sampled_states’.

• sampled_states (Optional[Sequence[Integral]]) – Explicit sequence of parent value indices to use as samples. Mutually exclusive with ‘num_values’.

• seed (Optional[Integral]) – Random seed for sampling. Only relevant if sampling with ‘num_values’ and not supplying ‘sampled_states’.

• with_replacement (bool) – Whether to sample with replacement (True) or without replacement (False).

• name (Optional[str]) – Name for the resulting sampled State.

Returns:

A State whose values are a sampled subset of those of the parent State.

Return type:

State_type

Split

statetracker.split(state, split_spec, names=None)

Split a State into multiple sub-States according to equal or proportional partitioning.

Parameters:

• state (statetracker.state.State) – The State object to be split.

• split_spec (Union[Integral, Sequence[Real]]) – If an integer N, split into N roughly equal parts. If a sequence of proportions, split according to these proportions (sequence length = number of parts).

• names (Optional[Sequence[str]]) – Optional sequence of names for each resulting sub-State. If provided, must match the number of parts.

Returns:

Tuple of new State objects corresponding to each partition of the original values.

Return type:

Tuple[State_type, …]

Interleave

statetracker.interleave(states, name=None)

Create a State that interleaves the values from multiple State objects.

Parameters:

• states (Sequence[statetracker.state.State]) – Sequence of State instances to interleave, each with equal num_values.

• name (Optional[str]) – Optional name for the resulting interleaved State.

Returns:

A State whose values interleave across the provided states.

Return type:

State_type

Operation Classes

These are the underlying operation classes used internally. Most users will use the convenience functions above instead of instantiating these directly.

ProductOp

class statetracker.ProductOp

Bases: Operation

Cartesian product of N states.

compute_num_states(parent_num_values)

Compute num_values for this node given parent num_values.

decompose(value, parent_num_values)

Decompose this node’s value into parent values.

StackOp

class statetracker.StackOp

Bases: Operation

compute_num_states(parent_num_values)

Compute num_values for this node given parent num_values.

decompose(value, parent_num_values)

Decompose this node’s value into parent values.

SyncOp

SliceOp

class statetracker.SliceOp(start, stop, step)

Bases: Operation

Slice a state to select a subset of values.

__init__(start, stop, step)

compute_num_states(parent_num_values)

Compute num_values for this node given parent num_values.

decompose(value, parent_num_values)

Decompose this node’s value into parent values.

RepeatOp

class statetracker.RepeatOp(times)

Bases: Operation

Repeat a single state N times.

__init__(times)

compute_num_states(parent_num_values)

Compute num_values for this node given parent num_values.

decompose(value, parent_num_values)

Decompose this node’s value into parent values.

ShuffleOp

class statetracker.ShuffleOp(num_parent_values, seed=None, permutation=None)

Bases: Operation

Randomly shuffle state values using a deterministic seed.

__init__(num_parent_values, seed=None, permutation=None)

compute_num_states(parent_num_values)

Compute num_values for this node given parent num_values.

decompose(value, parent_num_values)

Decompose this node’s value into parent values.

SampleOp

class statetracker.SampleOp(num_parent_values, num_values=None, sampled_states=None, seed=None, with_replacement=True)

Bases: Operation

Sample values from parent state.

__init__(num_parent_values, num_values=None, sampled_states=None, seed=None, with_replacement=True)

compute_num_states(parent_num_values)

Compute num_values for this node given parent num_values.

decompose(value, parent_num_values)

Decompose this node’s value into parent values.

InterleaveOp

class statetracker.InterleaveOp

Bases: Operation

Interleave values from N states with equal num_values.

compute_num_states(parent_num_values)

Compute num_values for this node given parent num_values.

decompose(value, parent_num_values)

Decompose this node’s value into parent values.