Boundary API

AbstractBoundaryCondition

Abstract supertype for lattice boundary conditions.

The canonical concrete type is LatticeBoundary, which composes:

• a tuple of per-axis boundary conditions (subtypes of AbstractAxisBC: PeriodicAxis, OpenAxis, TwistedAxis)
• a non-topological modifier (subtype of AbstractBoundaryModifier: NoModifier, SSD)

The split is deliberate: an axis BC decides whether a candidate bond exists (and whether it carries a twist phase), while a modifier only reweights existing bonds (e.g. sine-square deformation). Multiple concerns are composed, not shoehorned into a single taxonomy.

See dev/note/04_architecture/03_boundary_and_coordinates/README.md for the design rationale.

AbstractAxisBC

Abstract supertype for per-axis boundary conditions. Concrete subtypes decide how a raw candidate cell index is wrapped into the lattice's index range along a single axis.

Subtypes:

• PeriodicAxis — wraps via mod1
• OpenAxis — rejects out-of-range indices
• TwistedAxis — wraps like PeriodicAxis but attaches a phase factor to bonds that cross the boundary

AbstractBoundaryModifier

Abstract supertype for boundary modifiers. A modifier does not change which bonds exist — it only reweights existing bonds through bond_weight. Examples: NoModifier, SSD.

Periodic axis BC: wrap-around via mod1.

Open axis BC: bonds crossing the boundary are dropped.

TwistedAxis(phase::Real)

Periodic axis BC with a phase angle (radians) attached to boundary-crossing bonds. The connectivity is identical to PeriodicAxis; only the phase returned by axis_phase differs.

Identity modifier: every bond has weight 1.0.

SSD(L)

Sine-square deformation modifier. L is the characteristic scale used by the envelope sin²(π · x/L). The concrete weight implementation will land with the MC layer; for now this serves as a placeholder carrying the scale parameter.

LatticeBoundary{N, A, M}(axes::NTuple{N, <:AbstractAxisBC}, modifier)

Composite boundary condition for an N-dimensional lattice. Stores one AbstractAxisBC per axis plus a single AbstractBoundaryModifier. Supports mixed-axis boundary conditions natively — a cylinder is

LatticeBoundary((PeriodicAxis(), OpenAxis()))

The zero-modifier form is the default.

apply_axis_bc(axis_bc::AbstractAxisBC, idx::Int, L::Int) → (wrapped, is_valid)

Apply the axis-level BC to a raw cell index idx ∈ ℤ on an axis of length L. Returns a tuple (wrapped::Int, is_valid::Bool):

• PeriodicAxis, TwistedAxis: (mod1(idx, L), true)
• OpenAxis: (idx, 1 <= idx <= L)

The twist phase is intentionally reported separately by axis_phase: MC code paths that do not need phases (classical Ising / XY / Heisenberg) are not forced to traffic in complex numbers.

axis_phase(axis_bc::AbstractAxisBC, idx::Int, L::Int) → ComplexF64

Phase factor attached to a bond that steps from a valid cell index to idx (possibly out of 1:L) along a single axis.

• PeriodicAxis, OpenAxis: always 1 + 0im.
• TwistedAxis(θ): cis(+θ) if idx > L, cis(-θ) if idx < 1, otherwise 1 + 0im.

Classical MC paths may ignore this; quantum / flux-carrying code should multiply bond contributions by the phase.

bond_weight(modifier::AbstractBoundaryModifier, lat, i::Int, j::Int) → Float64

Multiplicative weight applied to the bond (i, j) by a boundary modifier. Default implementation for NoModifier returns 1.0. SSD and other non-trivial modifiers will override this.