tightbinder.models.RealSpace#

class RealSpace(system_name=None, bravais_lattice=None, motif=None)[source]#

Bases: System

Class to construct toy models, in which one sets the hoppings manually. This models are by default OBC; by setting one hopping between different unit cells it automatically becomes PBC.

Parameters:

system_name (str) – Name of system. Defaults to None.
bravais_lattice (ndarray) – Bravais basis.
motif (ndarray) – List of atoms of the solid.

Methods

`add_atom`	Method to add one atom from a numbered species into a specific position.
`add_atoms`	Method to add a list of atoms of specified species at some positions.
`add_bond`	Method to add a hopping between two atoms of the motif.
`add_bonds`	Same method as add_hopping but we input a list of hoppings at once.
`add_hopping`	Method to add a hopping between two atoms of the motif.
`add_hoppings`	Same method as add_hopping but we input a list of hoppings at once.
`add_onsite_energies`	Same as add_onsite_energy.
`add_onsite_energy`	Method to specify the onsite energy of a given atom.
`atom_coordination_number`	Method to find the coordination number for a specific atom in the crystal.
`brillouin_zone_mesh`	Routine to compute a mesh of the first Brillouin zone using the Monkhorst-Pack algorithm.
`compute_first_neighbour_distance`	Routine to compute the first neighbour distance.
`compute_neighbour_distances`	Method to compute neighbour distance up to neighbours nni.
`compute_unit_cell_area`	Method to compute the area of the unit cell.
`coordination_number`	Method to find the coordination number of the solid.
`crystal_center`	Method to compute the geometric center of the crystal from the positions of the atoms of the motif.
`crystallographic_group`	Determines the crystallographic group associated to the material from the configuration file.
`determine_high_symmetry_points`	Routine to compute high symmetry points depending on the dimension of the system.
`extend_copy`	Method to extend the system by attaching a copy of the motif displaced by some input vector.
`find_disconnected_atoms`	Method to find which atoms do not have neighbours, i.e. they are disconnected from the lattice.
`find_first_neighbours`	Method to find the first neighbours of the atoms of the motif.
`find_lowest_coordination_atoms`	Routine to determine the atoms of the solid with the lowest coordination atoms.
`find_neighbours`	From a list of atoms (motif), it sets the list of bonds within the solid.
`hamiltonian_k`	Generic implementation of hamiltonian_k H(k).
`high_symmetry_path`	Routine to generate a path in reciprocal space along the high symmetry points (HSPs) indicated.
`identify_boundary`	Method to obtain the indices of the outermost atoms of the motif, taking into account boundary conditions.
`identify_convex_hull`	Deprecated in favour of identify_motif_edges.
`identify_motif_edges`	Method to obtain the indices of the outermost atoms of the motif.
`initialize_hamiltonian`	Method to set up the matrices that compose the Hamiltonian, either the Bloch Hamiltonian or the real-space one.
`plot_2d_crystal`	Method to visualize the crystalline structure (Bravais lattice + motif) in two dimensions.
`plot_crystal`	Method to visualize the crystalline structure (Bravais lattice + motif).
`plot_wireframe`	Method to plot a wireframe of the system according to the detected bonds.
`reciprocal_lattice`	Routine to compute the reciprocal lattice basis vectors from the Bravais lattice basis.
`reduce`	Routine to reduce the dimensionality of the System object along the specified directions, by repeating unit cells along those directions until a given size (number of unit cells) is reached.
`remove_atom`	Method to remove the atom at the specified index from the motif.
`remove_atoms`	Method to remove the atoms specified in a list with all their indices.
`remove_disconnected_atoms`	Method to remove disconnected atoms from the motif.
`restrict_lattice2rectangle`	TO BE IMPLEMENTED YET (is it really necessary?).
`ribbon`	Routine to generate a ribbon for a 2D crystal.
`rotate`	Method to rotate the whole system in the xy plane by some angle.
`solve`	Diagonalize the Hamiltonian to obtain the band structure and the eigenstates.
`specify_hopping_amplitude`	Instead of adding the hopping directly as a bond with an amplitude, we can also specify the hopping amplitude of a preexisting bond.
`specify_hopping_amplitudes`	Same as specify_hopping_amplitude but for a list of amplitudes-bond indices.
`supercell`	Routine to generate a supercell for a system using the number of cells along each Bravais vectors specified in ncells.
`update`	Routine to initialize or update the intrinsic attributes of the Crystal class whenever the Bravais lattice is changed.
`visualize`	Method to render a 3d visualization of the crystal using the self.vpython library.

Attributes

`basisdim`
`boundary`
`bravais_lattice`
`filling`
`matrix_type`
`motif`
`ndim`
`norbitals`
`unit_cell_list`

add_atom(position, species=0)#

Method to add one atom from a numbered species into a specific position.

Parameters:

position (Union[list, ndarray]) – Array with atom coordinaes. Must be three-dimensional.
species (int) – Index of corresponding chemical species. Defaults to 0.

Return type:

None

add_atoms(atoms, species=None)#

Method to add a list of atoms of specified species at some positions. Built on top of method add_atom.

Parameters:

atoms (Union[list, ndarray]) – List of length n, containing the positions of each atom.
species (list) – List with the indices of the chemical species. If None, all default to zero.

Return type:

None

add_bond(initial, final, cell=(0.0, 0.0, 0.0), neigh='1')#

Method to add a hopping between two atoms of the motif. NB: The hopping has a specified direction, from initial to final. The HSince the final Hamiltonian is computed taking into account hermiticity, it is not necessary to specify the hopping in the other direction. (TODO: Change this, no longer working like this).

Parameters:

initial (int) – Index of initial atom of the bond.
final (int) – Index of final atom of the bond.
cell (Union[list, tuple, ndarray]) – Array with cell containing the final atom. Defaults to [0., 0., 0.].
neigh (str) – String to denote if the bond corresponds to first neighbour, second, etc. Defaults to ‘1’.

Return type:

None

add_bonds(initial, final, cells=None, neigh=None)#

Same method as add_hopping but we input a list of hoppings at once.

Parameters:

initial (List[int]) – List of indices of initial atom of the bond.
final (List[int]) – List of indices of final atom of the bond.
cell – List of cell vectors containing the final atom. Defaults to None, which corresponds to the origin cell.
neigh (List[str]) – List of strings to denote if the bonds corresponds to first neighbour, second, etc respectively. Defaults to None, which corresponds to all being ‘1’.

Return type:

None

add_hopping(hopping, initial, final, cell=[0.0, 0.0, 0.0])[source]#

Method to add a hopping between two atoms of the motif. NB: The hopping has a specified direction, from initial to final. Since the final Hamiltonian is computed taking into account hermiticity, it is not necessary to specify the hopping in the other direction. Parameters: :type hopping: complex :param hopping: Value of hopping. :type initial: int :param initial: Index of first atom of bond. :type final: int :param final: Index of final atom of bond. :type cell: list :param cell: Bravais vector connecting the cells of the two atoms. Defaults to zero.

Return type:: None

add_hoppings(hoppings, initial, final, cells=None)[source]#

Same method as add_hopping but we input a list of hoppings at once. Parameters: :type hoppings: List[complex] :param hoppings: List with values of hoppings. :type initial: List[int] :param initial: List of indices of initial atom of the hoppings. :type final: List[int] :param final: List of indices of final atoms of the motif. :type cells: List[list] :param cells: Each row denotes the Bravais vector connecting two cells. Defaults to None.

Return type:: None

add_onsite_energies(indices, energies)[source]#

Same as add_onsite_energy. Used to specify the onsite energies of a collection of atom indices.

Parameters:

indices (List[float]) – List with indices of atoms.
energies (List[float]) – List with onsite energies.

Return type:

None

add_onsite_energy(index, energy)[source]#

Method to specify the onsite energy of a given atom.

Parameters:

index (int) – Index of atom.
energy (float) – Value of onsite energy.

Return type:

None

static atom_coordination_number(index, bonds)#

Method to find the coordination number for a specific atom in the crystal.

Parameters:

index (int) – Index of atom whose coordination number we want to compute.
bonds (list) – List of indices within the solid.

Return type:

int

Returns:

Number of neighbours.

brillouin_zone_mesh(mesh)#

Routine to compute a mesh of the first Brillouin zone using the Monkhorst-Pack algorithm.

Parameters:: mesh (list) – List with the number of kpoints along each axis.
Return type:: ndarray
Returns:: Array with all kpoints, nk x 3

compute_first_neighbour_distance(near_cells=None)#

Routine to compute the first neighbour distance. DEPRECATED since there is compute_neighbour_distances which works up to n neighbour distances.

Parameters:: near_cells (Union[list, ndarray]) – List of unit cells to loop over. Defaults to None.
Return type:: float
Returns:: First neighbour distance.

compute_neighbour_distances(nni)#

Method to compute neighbour distance up to neighbours nni.

Parameters:: nni (int) – Maximum neighbour distance to consider. nni=5 mean that it will find first, second up to fifth neighbours distances.
Return type:: List[float]
Returns:: List of neighbour distances.

compute_unit_cell_area()#

Method to compute the area of the unit cell. TODO: Adapt for 1D and 3D

Return type:: float
Returns:: Value of unit cell area.

coordination_number()#

Method to find the coordination number of the solid. Returns coordination number of solid, and a list with the different individual coordinations numbers found within the solid.

Return type:: Tuple[float, List[int]]
Returns:: Coordination number, and list of all individual coordination numbers found.

crystal_center()#

Method to compute the geometric center of the crystal from the positions of the atoms of the motif. Calculated as the average of all atomic positions.

Return type:: ndarray
Returns:: Numpy array with the cartesian coordinates of the center

crystallographic_group()#

Determines the crystallographic group associated to the material from the configuration file. NOTE: Only the group associated to the Bravais lattice, reduced symmetry due to presence of motif is not taken into account. Its purpose is to provide a path in k-space to plot the band structure. Workflow is the following: First determine length and angles between basis vectors. Then we separate by dimensionality: first we check angles, and then length to determine the crystal group.

Return type:: None

determine_high_symmetry_points()#

Routine to compute high symmetry points depending on the dimension of the system. These symmetry points will be used to plot the band structure along the main reciprocal paths of the system (irreducible BZ). Returns a dictionary with pairs {letter denoting high symmetry point: its coordinates}

Return type:: None

extend_copy(vector, n=1)#

Method to extend the system by attaching a copy of the motif displaced by some input vector.

Parameters:

vector – Vector by which we displace the copy of the system.
n – Number of copies to attach. The n-th copy will be displaced by n*vector. Defaults to 1.

Returns:

Extended system.

find_disconnected_atoms()#

Method to find which atoms do not have neighbours, i.e. they are disconnected from the lattice.

Return type:: List[int]
Returns:: List of indices of disconnected atoms.

find_first_neighbours()#: Method to find the first neighbours of the atoms of the motif. :rtype: list :return: List of the corresponding bonds.

find_lowest_coordination_atoms(include_first_neighbours=False)#

Routine to determine the atoms of the solid with the lowest coordination atoms. TODO: Define parameter to specify storing atoms with coordinations lower than one specified.

Parameters:: include_first_neighbours (bool) – Includes in the list of atoms, also the first neighbours of those found originally. Defaults to False.
Return type:: List[int]
Returns:: List of indices of atoms.

find_neighbours(mode='minimal', nn=1, r=None)#

From a list of atoms (motif), it sets the list of bonds within the solid. I.e.: Atom list -> List of neighbours/atom. By default it will look for the minimal distance between atoms to determine first neighbours. For amorphous systems the option radius is available to determine neighbours within a given radius R. Boundary conditions can also be set, either PBC (default) or OBC.

Parameters:

mode (str) – Search mode, can be either ‘minimal’ or ‘radius’. Defaults to ‘minimal’.
nn (int) – Next neighbour, used to specify up to which neighbour there are hoppings if mode=’minimal’
r (float) – Value for radius sphere to detect neighbours if mode=’radius’

Return type:

None

hamiltonian_k(k)[source]#: Generic implementation of hamiltonian_k H(k). To be overwritten by specific implementations of System.

high_symmetry_path(nk, points)#

Routine to generate a path in reciprocal space along the high symmetry points (HSPs) indicated. The HSPs must be within those corresponding to the associated symmetry group, otherwise the method will throw an error.

Parameters:

nk (int) – Number of kpoints in the path. They are evenly distributed between HSPs.
points (List[str]) – List of labels of desired HSPs.

Return type:

list

Returns:

List of kpoints following the path specified with the labels.

identify_boundary(alpha=0.4, ndim=2, verbose=False, corner_atoms=False)#

Method to obtain the indices of the outermost atoms of the motif, taking into account boundary conditions. NB: Currently works only in 2D

Parameters:

alpha (float) – This parameters tunes the shape of the boundary. For alpha=0, the boundary is a convex hull; as alpha increases the boundary becomes more concave. Default value is 0.4
ndim (int) – Dimension of the expected boundary. Defaults to 2.
verbose (bool) – Boolean parameter to print indices of boundary atoms. Defaults to False.
cornes_atoms – Boolean to toggle detection of atoms that might be shared by the periodic boundary and the open boundary.

Return type:

ndarray

Returns:

Indices of atoms in the boundary.

Raises:

AssertionError – Crystal dimension different from two raises error. Also raises if bonds are not computed.

identify_convex_hull(loop=6)#

Deprecated in favour of identify_motif_edges. Method to obtain the atoms that correspond to the edges of the system. This method uses directly the ConvexHull method from Scipy to identify the outmost points of the motif. Compute the ConvexHull three times, each time removing the points detected in the previous iteration.

NB: If given 3d points, they must not be coplanar for the algorithm to work. If they are, then the points must be given as 2d

Parameters:: loop (int) – Number of times the ConvexHull is applied, to increase number of points in the edge.
Return type:: ndarray
Returns:: Indices of atoms belonging to edges of motif.

identify_motif_edges(alpha=0.4, ndim=2)#

Method to obtain the indices of the outermost atoms of the motif. Note that this method returns exclusively the outermost atoms, independently of the boundary conditions. To take into account boundary conditions, one should call identify_boundary() from System. NB: Currently works only in 2D

Parameters:

alpha (float) – This parameters tunes the shape of the boundary. For alpha=0, the boundary is a convex hull; as alpha increases the boundary becomes more concave. Default value is 0.4
ndim (int) – Dimension of the boundary. If the system lies on a plane, the boundary is two-dimensional, so ndim = 2 (default value).

Return type:

ndarray

Returns:

Indices of atoms in the boundary.

Raises:

AssertionError – Crystal dimension different from two raises error.
ValueError – Crystal motif must have at least three atoms. Raised by Delaunay class.

initialize_hamiltonian()[source]#

Method to set up the matrices that compose the Hamiltonian, either the Bloch Hamiltonian or the real-space one. TODO initialize_hamiltonian RSmodel

Return type:: None

plot_2d_crystal(ax=None, fontsize=10, size=10)#

Method to visualize the crystalline structure (Bravais lattice + motif) in two dimensions. If the crystal is 3D, it will plot only the x, y coordinates.

Parameters:

ax – Axis to plot the projection of the crystal. If None, creates one.
fontsize (int) – Size of labels. Defaults to 10.
size (int) – Size of markers. Defaults to 10.

Return type:

None

plot_crystal(cell_number=1, crystal_name='')#

Method to visualize the crystalline structure (Bravais lattice + motif).

Parameters:

cell_number (int) – Number of cells appended in each direction with respect to the origin. Defaults to 1.
crystal_name (str) – Name of the crystal. Defaults to the empty string.

Return type:

None

plot_wireframe(ax=None, linewidth=1, alpha=0.5, color='black')#

Method to plot a wireframe of the system according to the detected bonds.

Parameters:

ax (Axes) – Matplotlib axes object. If None, a new Axis object is created.
linewidth (float) – Linewidth of the wireframe. Defaults to 1.
alpha (float) – Sets wireframe transparency. Defaults to 0.5
color – Wireframe color. Defaults to black.

Return type:

None

reciprocal_lattice()#

Routine to compute the reciprocal lattice basis vectors from the Bravais lattice basis. The algorithm is based on the fact that a_idot b_j=2PIdelta_ij, which can be written as a linear system of equations to solve for b_j. Resulting vectors have 3 components independently of the dimension of the vector space they span.

Return type:: None

reduce(**ncells)#

Routine to reduce the dimensionality of the System object along the specified directions, by repeating unit cells along those directions until a given size (number of unit cells) is reached. Thus we make the original system finite along those directions.

Parameters:: ncells (dict) – Number of cells of direction(s) along which we want to reduce the dimensionality of the system, n1, n2 and/or n3.
Return type:: System
Returns:: Modified System object.

remove_atom(index)#

Method to remove the atom at the specified index from the motif. Note that this method does not remove existing bonds corresponding to the removed atom.

Parameters:: index (int) – Index of atom to be removed.
Return type:: None

remove_atoms(indices)#

Method to remove the atoms specified in a list with all their indices. Built upon the method remove_atom.

Parameters:: indices (list) – List with the indices of the atoms to be removed.
Return type:: None

remove_disconnected_atoms()#: Method to remove disconnected atoms from the motif. Based on the method remove_atoms.

restrict_lattice2rectangle()#

TO BE IMPLEMENTED YET (is it really necessary?).

Return type:: None

ribbon(width, orientation='horizontal', periodic=False)#

Routine to generate a ribbon for a 2D crystal. It is designed to create rectangular ribbons, based on a rectangular lattice. Therefore there must exist a combination of basis vectors such that we can obtain a rectangular supercell. Otherwise the method returns an error.

Parameters:

width (int) – Width of the ribbon (number of cells).
orientation (str) – ‘horizontal’ or ‘vertical’. Defaults to ‘horizontal’.
periodic (bool) – Boolean to keep the ribbon periodic along the direction it is built. Defauts to False. Turning this one would correspond to a nanotube instead of nanoribbon (finite).

Return type:

System

Returns:

Modified System object.

rotate(angle=90)#

Method to rotate the whole system in the xy plane by some angle.

Parameters:: angle (float) – Value of rotation angle in degrees. Defaults to 90 degrees.
Return type:: System
Returns:: Rotated system.

solve(kpoints=None, neigval=None)#

Diagonalize the Hamiltonian to obtain the band structure and the eigenstates.

Parameters:

kpoints (list) – List of kpoints where we want to diagonalize the Bloch Hamiltonian. Defaults to None, which corresponds to [[0., 0., 0.]] for both PBC and OBC.
neigval (int) – Number of eigenvalues to compute if using sparse matrices. Defaults to None, which in turn is set to the filling.

Returns:

Spectrum object.

specify_hopping_amplitude(amplitude, bond_index)[source]#

Instead of adding the hopping directly as a bond with an amplitude, we can also specify the hopping amplitude of a preexisting bond.

Parameters:

amplitude (float) – Hopping amplitude.
bond_index (int) – Index of bond.

Return type:

None

specify_hopping_amplitudes(amplitudes, bond_indices)[source]#

Same as specify_hopping_amplitude but for a list of amplitudes-bond indices.

Parameters:

amplitudes (List[float]) – List of amplitudes of bonds.
bond_indices (List[int]) – List of indices of bonds.

Return type:

None

supercell(update=True, **ncells)#

Routine to generate a supercell for a system using the number of cells along each Bravais vectors specified in ncells.

Parameters:

update (bool) – Boolean parameter to update all of Crystal class atributes. Defaults to True, only set to false when used inside other routines (reduce)
dict – Specify number of cells in some direction: n1, n2 and/or n3.

Return type:

System

Returns:

Modified System object.

update()#

Routine to initialize or update the intrinsic attributes of the Crystal class whenever the Bravais lattice is changed.

Return type:: None

visualize()#

Method to render a 3d visualization of the crystal using the self.vpython library.

Return type:: None