Overview

The purpose of the lattice_builder is to generate representations of various Hamiltonians exhibiting a repetitive structure, such as solids. The lattice_builder can process human-readable input describing the structure of the Hamiltonian to provide matrix representations of the coupling coefficients present in the Hamiltonian.

Furthermore, the lattice_builder provides convenience functions for visualizing information about the (periodic) Hamiltonian, such as the band structure or spectral function. The Builder class, from which instances of various Hamiltonians can be instantiated, must be initialized by passing a valid Python dictionary to the constructor. To faciliate the validation of an input dictionary, please use the lattice_validator.

The minimalistic usage scenario for the lattice_builder is the following:

• Setup a valid (python) dictionary representing a Hamiltonian

• Instantiate a Builder object from the dictionary

• Use convenience methods of the Builder object to visualize information about Hamiltonian

Python script implementing these steps for a 2-band tight-binding model of graphene:

# import pretty print to display dictionaries
from pprint import pprint
# import yaml for serializing dictionaries
import yaml
# import matplotlib for plotting
from matplotlib import pyplot as plt
from lattice_validator import Validator
from lattice_builder import Builder
# STEP 0: generating a valid (python) dictionary representing graphene ...
from math import cos, sin, pi
# define atoms in unitcell
atoms = [
    {
        "id": 1,
        "name": "C",
        "position": [0, 0, 0],
        "e0": 0,
    },
    {
        "id": 2,
        "name": "C",
        "position": [0, 1, 0],
        "e0": 0,
    },
]
# define lattice vectors for hexagonal unit cell
lattice_vectors = [
    [cos(pi / 6), -(1 + sin(pi / 6)), 0],
    [cos(pi / 6), 1 + sin(pi / 6), 0],
]
# define bonds between the carbon atoms
bonds = [
    {
        "id_from": 1,
        "id_to": 2,
        "t": -2.6,  # hopping amplitude for graphene in eV
        "translation": [0, 0, 0],  # intra-cell bond
    },
    {
        "id_from": 1,
        "id_to": 2,
        "t": -2.6,  # hopping amplitude for graphene in eV
        "translation": [1, 0, 0],  # inter-cell bond
    },
    {
        "id_from": 2,
        "id_to": 1,
        "t": -2.6,  # hopping amplitude for graphene in eV
        "translation": [0, 1, 0],  # inter-cell bond
    },
]
# compose the unit cell
unitcell = {
    "atoms": atoms,
    "bonds": bonds,
    "lattice_vectors": lattice_vectors,
}
# define system parameters
system = {
    "site_type": "spinless",
    "BC": ["periodic", "periodic", "HW"],
    "system_size": [3, 3, 1],
}
# compose configuration for Builder input
configuration = {
    "system": system,
    "unitcell": unitcell,
}
# validate input using the lattice_validator
lv = Validator(profile="onPremise")
valid, normalized_configuration_or_error = lv.validateConfiguration(configuration)
if not valid:
    pprint(normalized_configuration_or_error)
    exit(1)

# serialize **valid** configuration to yaml file
filename = "graphene"
with open(f"{filename}.yaml", mode="w") as stream:
    yaml.safe_dump(configuration, stream)

# STEP 1: setup graphene configuration from yaml file
with open(f"{filename}.yaml", mode="r") as stream:
    try:
        configuration = yaml.safe_load(stream)

    except:
        print(f"Error parsing {filename}.yaml")
        exit(2)

valid, normalized_configuration_or_error = lv.validateConfiguration(configuration)
if not valid:
    pprint(normalized_configuration_or_error)
    exit(3)

# STEP 2: initialize a Builder object using the normalized configuration
lb = Builder(normalized_configuration_or_error)

# STEP 3: using Builder methods to visualize information about the system
# extract positions of the atoms for entire system
positions = lb.get_atom_positions()
x_pos = [pos[0] for pos in positions]
y_pos = [pos[1] for pos in positions]

plt.axes().set_aspect("equal")
plt.plot(x_pos, y_pos, "ro")
plt.show()
# get band structure of graphene
band_structure_svg_string = lb.bandStructure()
# display the band structure using matplotlib
plt.show()
with open(f"{filename}.svg", mode="w") as stream:
    # writing the generated svg string to a file
    stream.write(band_structure_svg_string.getvalue())