build_interaction¶

Build a fully populated interaction list from a TOML config or dict.

build_interaction ¶

build_interaction(
    config: Union[dict, str, Path],
    *,
    geometry_fn: Optional[Callable] = None,
    intrcmap_fn: Optional[Callable] = None,
    model_fn: Optional[Callable] = None,
    space_fn: Optional[Callable] = None,
) -> Tuple[List[Interaction], Index, Geometry]

Build a fully populated interaction list from a TOML config.

Orchestrates the four-stage MPO construction pipeline:

Geometry — constructs a Geometry struct from geo_cfg via geometry_fn.
Intrcmap — generates the bare interaction list with sites and labels but no tensors and cpl == 0.0 via intrcmap_fn.
Model — fills cpl and tensor fields on each interaction (without baking coupling into the tensors).
Returns (interactions, spc, geo) ready for build_hamiltonian.

Callable overrides (geometry_fn, intrcmap_fn, model_fn, space_fn) take priority over [plugin] section entries in the config, which in turn take priority over the built-in dispatch tables.

Parameters:

Name	Type	Description	Default
`config`	`Union[dict, str, Path]`	Either a config dict (with `'geometry'` and `'model'` sub-dicts) or a path to a TOML file.	required
`geometry_fn`	`Optional[Callable]`	Optional override for the geometry struct factory. Signature: `geometry_fn(geo_cfg: dict) -> Geometry`.	`None`
`intrcmap_fn`	`Optional[Callable]`	Optional override for the interaction-map builder. Signature: `intrcmap_fn(geo: Geometry) -> list[Interaction2Site]`.	`None`
`model_fn`	`Optional[Callable]`	Optional override for the model builder. Signature: `model_fn(interactions, L, model_cfg: dict) -> tuple[Index, dict]`.	`None`
`space_fn`	`Optional[Callable]`	Optional override for the operator-set builder (normally called internally by the model builder). Passed through to the model builder as a keyword argument `space_fn=space_fn`.	`None`

Returns:

Type	Description
`tuple`	`(interactions, spc, geo)` where `interactions` is the populated list, `spc` is the physical `Index`, and `geo` is the `Geometry` instance.

Raises:

Type	Description
`ValueError`	If a required key is missing or an unknown `lattice`, `traverse`, `category`, or `label` value is encountered.

TOML Config Structure¶

A minimal config dict (or TOML section) must contain two sub-tables:

[model.geometry]
lattice = "chain"
lx      = 10
bcx     = "OBC"
n2x     = true

[model.model]
category = "bosonic"
label    = "Heisenberg"
symmetry = "U1"
spin     = 0.5
J        = 1.0

An optional [model.plugin] table can override geometry, intrcmap, space, or model callables:

[model.plugin]
geometry = "my_dir/my_geometry.py:build_my_lattice"
intrcmap = "my_dir/my_intrcmap.py:build_my_intrcmap"
model    = "my_dir/my_model.py:build_my_model"

Plugin specs use the format "path/to/file.py:function_name".

Extension Hooks¶

Kwarg	Plugin key	Signature	Description
`geometry_fn`	`[plugin] geometry`	`(dict) -> Geometry`	Replace the geometry-building step
`intrcmap_fn`	`[plugin] intrcmap`	`(Geometry) -> list[Interaction2Site]`	Replace the interaction-map step
`model_fn`	`[plugin] model`	`(interactions, L, **cfg) -> None`	Replace the model-filling step
`space_fn`	`[plugin] space`	`(category, **cfg) -> (Index, dict)`	Replace the local-space step

Keyword arguments take priority over [plugin] entries.

Return Value¶

build_interaction returns a three-tuple (interactions, spc, geo):

Element	Type	Description
`interactions`	`list[Interaction]`	Fully populated interaction list
`spc`	`Index`	Physical index (local space)
`geo`	`Geometry`	Resolved lattice geometry; use `geo.L` as the chain length for `build_hamiltonian`

The chain length is accessed as geo.L:

interactions, spc, geo = build_interaction(config)
hamiltonian = build_hamiltonian(interactions, geo.L, spc)

build_interaction¶