diff --git a/kwant/system.py b/kwant/system.py index f16e7813ef144d87f8173458ebbcecfe76c4a9cf..5daced9f264d4e5be663a5a7305bd9df819ccc6a 100644 --- a/kwant/system.py +++ b/kwant/system.py @@ -22,7 +22,8 @@ class System2(metaclass=abc.ABCMeta): Attributes ---------- num_nodes: int - The number of sites in the (fundamental domain of) the system. + The number of sites in the (fundamental domain + of the stored_subgroup of) the system. num_entries: int The number of entries (onsite elements + hopping elements) in the system. @@ -46,6 +47,11 @@ class System2(metaclass=abc.ABCMeta): symmetry_quotient_group: sequence of GroupElements Representative elements from the quotient group G/T of the left cosets of T in G, excluding the identity. + stored_subgroup: sequence of GroupElements, or None + The subgroup S of the full symmetry group that defines the domain + for which the nodes are explicitly stored in the system. If None, + this signifies that the fundamental domain of the full symmetry + group is stored. Notes ----- @@ -182,6 +188,40 @@ class System2(metaclass=abc.ABCMeta): ### Symmetry parts of API + @abc.abstractmethod + def node_images(self, g, nodes): + """Get the images of some nodes under a symmetry operation. + + Parameters + ---------- + g: GroupElement + nodes: sequence of int + + Returns + ------- + (image_nodes, g_mapped) + image_nodes are the images of the nodes under the action of g, + or -1 if g maps a given node outside the domain stored in the + system. + g_mapped is a sequence of group elements from the abelian normal + subgroup that are in stored_subgroup. Non-trivial elements mean + that image_node actually corresponds to the node number in + the domain indexed by g_mapped. + + Raises + ------ + IndexError + If any element of nodes >= num_nodes. + + Notes + ----- + If node i maps to i and its g_mapped is the trivial element, this means + that i is invariant under the action of g (this places a constraint + on the onsite Hamiltonian of i). + -1 is typically returned for a node when g is in stored_subgroup, + except if the node lies at the boundary of the domain. + """ + @abc.abstractmethod def symmetry_abelian_representation(self, k, t): """Get a U(1) representation of a symmetry element.