Components

pbcgraph.component.PeriodicComponent dataclass

A connected quotient component with periodic-lift invariants.

A component is computed on the quotient graph (nodes are templates living in the reference cell). In addition to the node set, it stores information needed to reason about the infinite periodic lift.

Attributes:

Name	Type	Description
graph	PeriodicDiGraphLike	Parent graph that produced this component. PeriodicGraph is accepted since it is a subclass of PeriodicDiGraph.
nodes	FrozenSet[NodeId]	Quotient node ids in this component.
root	NodeId	Deterministic root node used for spanning-tree potentials.
created_structural_version	int	Structural version of graph at creation.
rank	int	Rank of the translation subgroup L (the periodic dimension).
translation_generators	Tuple[TVec, ...]	A (possibly redundant) generator set for L.
torsion_invariants	Tuple[int, ...]	Invariant factors d_i > 1 describing the torsion part of Z^d / L. An empty tuple means no torsion.

Notes

This dataclass is frozen for safety. Internal caches are populated in __post_init__ using object.__setattr__.

graph instance-attribute

graph: PeriodicDiGraphLike

nodes instance-attribute

nodes: FrozenSet[NodeId]

root instance-attribute

root: NodeId

created_structural_version instance-attribute

created_structural_version: int

rank class-attribute instance-attribute

rank: int = 0

translation_generators class-attribute instance-attribute

translation_generators: Tuple[TVec, ...] = ()

torsion_invariants class-attribute instance-attribute

torsion_invariants: Tuple[int, ...] = ()

_potentials class-attribute instance-attribute

_potentials: Dict[NodeId, TVec] = field(
    default_factory=dict, repr=False
)

_tree_parent class-attribute instance-attribute

_tree_parent: Dict[NodeId, Tuple[NodeId, TVec, int]] = (
    field(default_factory=dict, repr=False)
)

_snf class-attribute instance-attribute

_snf: Optional[SNFDecomposition] = field(
    default=None, repr=False
)

snf property

snf: SNFDecomposition

Smith normal form decomposition for the translation subgroup.

Raises:

Type	Description
StaleComponentError	If the parent graph has changed structurally.

__init__

__init__(
    graph: PeriodicDiGraphLike,
    nodes: FrozenSet[NodeId],
    root: NodeId,
    created_structural_version: int,
    rank: int = 0,
    translation_generators: Tuple[TVec, ...] = (),
    torsion_invariants: Tuple[int, ...] = (),
    _potentials: Dict[NodeId, TVec] = dict(),
    _tree_parent: Dict[
        NodeId, Tuple[NodeId, TVec, int]
    ] = dict(),
    _snf: Optional[SNFDecomposition] = None,
) -> None

__post_init__

__post_init__() -> None

is_stale

is_stale() -> bool

Return True if the parent graph has changed structurally since creation.

_require_fresh

_require_fresh() -> None

tree_parent_map

tree_parent_map() -> Mapping[
    NodeId, Tuple[NodeId, TVec, int]
]

Read-only spanning-tree parent mapping.

The mapping records, for each non-root node child, a tuple (parent, tvec, key) describing the tree edge used to assign the node potential.

Raises:

Type	Description
StaleComponentError	If the parent graph has changed structurally.

potential

potential(u: NodeId) -> TVec

Return the spanning-tree potential pot(u).

Parameters:

Name	Type	Description	Default
u	NodeId	Quotient node id.	required

Returns:

Type	Description
TVec	Integer translation vector in Z^d.

Raises:

Type	Description
StaleComponentError	If component is stale.
KeyError	If u is not in the component.

inst_key

inst_key(node_inst: NodeInst) -> Hashable

Return a canonical coset key for the lifted instance in Z^d / L.

Representation (v0.1): Returns a tuple of ints with layout: (torsion_residues..., free_coords...)

Torsion residues are reduced modulo the SNF diagonal invariants
(>1) and free coordinates are unbounded integers.

Parameters:

Name	Type	Description	Default
node_inst	NodeInst	(u, shift) where shift in Z^d.	required

Raises:

Type	Description
StaleComponentError	If component is stale.
KeyError	If u is not in the component.

same_fragment

same_fragment(inst_a: NodeInst, inst_b: NodeInst) -> bool

Decide connectivity of two instances in the infinite lift.

The criterion is

A(a) - A(b) in L

where A(u, s) = s - pot(u) and L is the translation subgroup induced by cycles.

Parameters:

Name	Type	Description	Default
inst_a	NodeInst	(u, shift) instance.	required
inst_b	NodeInst	(v, shift) instance.	required

Returns:

Type	Description
bool	True if the two instances are in the same connected component of
bool	the infinite lift (with connectivity ignoring edge directions,
bool	consistent with v0.1 components).

Raises:

Type	Description
StaleComponentError	If component is stale.
KeyError	If either quotient node is not in this component.

transversal_basis

transversal_basis() -> Dict[str, List[TVec]]

Return a deterministic transversal basis description.

Returns:

Type	Description
Dict[str, List[TVec]]	A dict with keys: - 'free': list of vectors spanning the free part Z^(d-r) - 'torsion_dirs': list of vectors corresponding to torsion coordinates - 'torsion_moduli': list of moduli (same length as torsion_dirs)

Notes

Direction vectors are given in the original coordinate basis of Z^d.

canonical_lift

canonical_lift(
    *,
    strand_key: Hashable | None = None,
    seed: NodeInst | None = None,
    anchor_shift: TVec | None = None,
    placement: str = "tree",
    score: str = "l1",
    return_tree: bool = False,
    node_order: Callable[[NodeId], Any] | None = None,
    edge_order: Callable[[tuple], Any] | None = None,
) -> "CanonicalLift"

Return a deterministic finite representation of a single strand.

This is a thin wrapper over :func:pbcgraph.alg.lift.canonical_lift.

Parameters:

Name	Type	Description	Default
strand_key	Hashable | None	Optional explicit strand (coset) key.	None
seed	NodeInst | None	Optional seed instance used to determine strand_key and/or default anchor_shift.	None
anchor_shift	TVec | None	Target anchor cell shift.	None
placement	str	Placement mode. v0.1.2 step4 implements 'tree', 'best_anchor', and 'greedy_cut'.	'tree'
score	str	Score metric, 'l1' or 'l2'.	'l1'
return_tree	bool	If True, include spanning-tree edge records.	False
node_order	Callable[[NodeId], Any] | None	Optional ordering key for quotient node ids.	None
edge_order	Callable[[tuple], Any] | None	Optional ordering key for periodic edges (reserved for later placement modes).	None

Returns:

Name	Type	Description
A	'CanonicalLift'	class:~pbcgraph.alg.lift.CanonicalLift.

_compute_potentials

_compute_potentials() -> Tuple[
    Dict[NodeId, TVec],
    Dict[NodeId, Tuple[NodeId, TVec, int]],
]

_compute_generators

_compute_generators(pot: Dict[NodeId, TVec]) -> List[TVec]