Geometric Tiling Partitioning

Geometric tiling partitioning assigns atoms to space-filling parallelohedra. This is useful for regular, lattice-aligned fragmentations in periodic or finite systems.

Available tiling shapes

Shape	Registry name	Notes
Cube	`cube`	Axis-aligned cubic cells.
Hexagonal prism	`hex_prism`	Hexagonal cross-section, z-axis height.
Truncated octahedron	`truncated_octahedron`	BCC Wigner-Seitz cell.
Elongated dodecahedron	`elongated_dodecahedron`	Stretched rhombic dodecahedron.
Rhombic dodecahedron	`rhombic_dodecahedron`	FCC Wigner-Seitz cell.

CLI usage

Use the geometric subcommand to partition a system using tiling cells:

autofragment geometric \
  --input sample.xyz \
  --output sample.json \
  --tiling-shape cube \
  --n-fragments 8 \
  --tiling-scale 1.0

Supported CLI options:

--tiling-shape: name from the registry table above
--n-fragments: target number of fragments
--tiling-scale: scale factor for the tiling lattice
--bounds-strategy: auto, lattice, or atoms

Python API

from autofragment.partitioners.geometric import TilingPartitioner
from autofragment.core.types import Atom, ChemicalSystem

atoms = [Atom("H", [0.5, 0.5, 0.5]), Atom("H", [1.5, 1.5, 1.5])]
system = ChemicalSystem(atoms=atoms)

partitioner = TilingPartitioner(
    tiling_shape="cube",
    n_fragments=8,
    scale=1.0,
)
tree = partitioner.partition(system)

Output metadata

Partitioning metadata records the tiling configuration:

{
  "partitioning": {
    "algorithm": "tiling",
    "n_fragments": 8,
    "tiling_shape": "cube",
    "scale": 1.0,
    "bounds_strategy": "auto",
    "periodic": false
  }
}

Each fragment includes per-cell metadata:

{
  "metadata": {
    "tiling_shape": "cube",
    "cell_index": [0, 1, 0],
    "scale": 1.0
  }
}