moirepy.moire.BilayerMoireLattice

Bilayer moire lattice wrapper with Rust-backed geometry and Hamiltonian assembly.

This class builds two rotated/translating copies of a monolayer lattice, generates points in a common moire supercell, and exposes fast methods for connection generation, phase factors, and sparse Hamiltonian construction.

Parameters:

Name	Type	Description	Default
latticetype	type[Layer]	Layer class (not instance) that subclasses :class:moirepy.layers.Layer.	required
ll1	int	Integer coefficients defining the lower-layer supercell direction.	required
ll2	int	Integer coefficients defining the lower-layer supercell direction.	required
ul1	int	Integer coefficients defining the upper-layer direction used to infer twist angle relative to the lower layer.	required
ul2	int	Integer coefficients defining the upper-layer direction used to infer twist angle relative to the lower layer.	required
n1	int	Number of supercell tiles along moire vectors mlv1 and mlv2.	1
n2	int	Number of supercell tiles along moire vectors mlv1 and mlv2.	1
translate_upper	tuple[float, float]	Translation applied to the upper layer after rotation.	(0, 0)
pbc	bool	Whether periodic boundary conditions are enabled.	True
study_proximity	int	Neighbor-search shell depth used by each layer.	1
k	int	Number of orbitals per site.	1
verbose	bool	If True, prints twist angle and generated-cell counts.	True

Raises:

Type	Description
ValueError	If latticetype is not a Layer subclass, or if the computed moire vectors are incompatible with layer periodicity.
AssertionError	If generated upper and lower point counts are inconsistent.

ll1 property writable

ll1

int: First lower-layer integer coefficient.

ll2 property writable

ll2

int: Second lower-layer integer coefficient.

mlv1 property writable

mlv1

First Moiré lattice vector.

mlv2 property writable

mlv2

Second Moiré lattice vector.

n1 property writable

n1

int: Number of moire tiles along :attr:mlv1.

n2 property writable

n2

int: Number of moire tiles along :attr:mlv2.

orbitals property writable

orbitals

int: Number of orbitals per lattice site.

pbc property writable

pbc

bool: Whether periodic boundary conditions are enabled.

theta property writable

theta

float: Twist angle in radians.

translate_upper property writable

translate_upper

Translation vector applied to the upper layer.

ul1 property writable

ul1

int: First upper-layer integer coefficient.

ul2 property writable

ul2

int: Second upper-layer integer coefficient.

generate_connections

generate_connections(inter_layer_radius=1.0)

Populate connection instruction buffers for all hopping channels.

Parameters:

Name	Type	Description	Default
inter_layer_radius	float	Maximum distance for inter-layer neighbor search.	1.0

Raises:

Type	Description
RuntimeError	If lattice points have not been generated on either layer.

generate_hamiltonian

generate_hamiltonian(tll=0.0, tuu=0.0, tlu=0.0, tul=0.0, tuself=0.0, tlself=0.0, data_type=np.complex128, extra_inputs=None)

Assemble the tight-binding Hamiltonian as a sparse COO matrix.

Parameters:

Name	Type	Description	Default
tll	float or callable	Intra-/inter-layer hopping terms. Each can be: (1) scalar, or (2) callable returning (N, k, k) blocks.	0.0
tuu	float or callable	Intra-/inter-layer hopping terms. Each can be: (1) scalar, or (2) callable returning (N, k, k) blocks.	0.0
tlu	float or callable	Intra-/inter-layer hopping terms. Each can be: (1) scalar, or (2) callable returning (N, k, k) blocks.	0.0
tul	float or callable	Intra-/inter-layer hopping terms. Each can be: (1) scalar, or (2) callable returning (N, k, k) blocks.	0.0
tuself	float or callable	Upper/lower onsite terms. Same scalar-or-callable contract.	0.0
tlself	float or callable	Upper/lower onsite terms. Same scalar-or-callable contract.	0.0
data_type	dtype	Output sparse matrix dtype, typically np.float64 or np.complex128.	complex128
extra_inputs	dict	Extra keyword arguments passed into user callables.	None

Returns:

Type	Description
coo_matrix	Hamiltonian matrix with shape (n_tot, n_tot).

Notes

Complex assembly is automatically selected if any input resolves to a complex array or if data_type is np.complex128.

get_hopping_instructions

get_hopping_instructions()

Return raw hopping instruction objects from the Rust backend.

Returns:

Type	Description
dict[str, object]	Mapping with keys tll, tuu, tul, tlu, tlself, and tuself.

get_phase

get_phase(k)

Compute Peierls phase matrix for one or multiple wavevectors.

Parameters:

Name	Type	Description	Default
k	array - like	Either shape (2,) for one wavevector or (N, 2) for a batch.	required

Returns:

Type	Description
coo_matrix or list[coo_matrix]	Phase matrix/matrices with shape (n_tot, n_tot) where n_tot = (n_lower + n_upper) * orbitals.

Raises:

Type	Description
ValueError	If k does not have shape (2,) or (N, 2).

plot_lattice

plot_lattice()

Plot both layer point clouds and moire/simulation boundaries.

Notes

Adds artists to the current Matplotlib axes and sets equal aspect ratio. Call plt.show() or save the figure after invoking this method.