Select supercells

Tell enumerate which supercells (multiples of the parent cell) to iterate over via the SupercellSelection family. The three concrete subtypes cover the common cases.

Setup

julia> using Enumlib

julia> p = ParentLattice([0.0 0.5 0.5; 0.5 0.0 0.5; 0.5 0.5 0.0]);   # FCC primitive

The three options at a glance

Selection	Use when	Example
`VolumeRange`	"all supercells of volume N to M"	`VolumeRange(2:8)`
`RadiusBound`	"supercells whose physical size (cell radius) is ≤ X"	`RadiusBound(; max_radius_ratio = 2.0)`
`ExplicitHNFs`	"this specific list of HNFs" — regression tests, literature reference cases	(see below)

VolumeRange — most common

Enumerate every symmetry-inequivalent supercell of volume n for each n in the range:

julia> hnfs = enumerate_hnfs(VolumeRange(2:4), p)
12-element Vector{HNF{3}}:
 HNF{3} (volume 2)  1 0 0 / 0 1 0 / 0 0 2
 HNF{3} (volume 2)  1 0 0 / 0 1 0 / 0 1 2
 HNF{3} (volume 3)  1 0 0 / 0 1 0 / 0 0 3
 HNF{3} (volume 3)  1 0 0 / 0 1 0 / 0 1 3
 HNF{3} (volume 3)  1 0 0 / 0 1 0 / 0 2 3
 HNF{3} (volume 4)  1 0 0 / 0 1 0 / 0 0 4
 HNF{3} (volume 4)  1 0 0 / 0 1 0 / 0 1 4
 HNF{3} (volume 4)  1 0 0 / 0 1 0 / 0 2 4
 HNF{3} (volume 4)  1 0 0 / 0 1 0 / 0 3 4
 HNF{3} (volume 4)  1 0 0 / 0 1 0 / 1 2 4
 HNF{3} (volume 4)  1 0 0 / 0 2 0 / 0 0 2
 HNF{3} (volume 4)  1 0 0 / 1 2 0 / 1 0 2

Two HNFs at volume 2, three at volume 3, seven at volume 4 — the FCC inequivalent-HNF count summed across n = 2, 3, 4. Each row of the matrix is one supercell basis vector in the parent's lattice coordinates; the diagonal entries multiplied give the volume.

RadiusBound — when cell shape matters

For DFT convergence and similar applications, the supercell's physical size (distance between periodic images) may be a more useful criterion for enumeration than atom count (i.e., volume). RadiusBound enumerates HNFs whose Minkowski-reduced cell radius is at most max_radius_ratio times the parent cell's radius:

julia> sel = RadiusBound(; max_radius_ratio = 1.5, max_volume = 8);  # ≤ 1.5x parent radius, hard cap at vol 8

julia> length(enumerate_hnfs(sel, p))
5

The max_volume is a safety stop — without it, a generous max_radius_ratio could scan very large volumes, leading to a combinatorial explosion.

ExplicitHNFs — hand-curated

Pass a list of HNFs you've chosen yourself. No symmetry reduction happens (the dispatcher assumes you've already done it):

julia> custom = [HNF([1 0 0; 0 1 0; 0 0 2]),    # 1×1×2 stacking
                 HNF([1 0 0; 0 1 0; 0 0 3]),    # 1×1×3 stacking
                 HNF([1 0 0; 0 1 0; 0 0 4])];   # 1×1×4 stacking

julia> length(enumerate_hnfs(ExplicitHNFs(custom), p))
3

Useful for regression tests, literature reference cases, or when you want to study one specific supercell in isolation.