Merge branch 'dev'

Project.toml

@@ -1,15 +1,16 @@
 name = "LatticeTools"
 uuid = "8a267902-5e0e-44c3-8ef8-9b2b5c352816"
 author = "Kyungmin Lee"
-version = "0.7.0"
+version = "0.8.0"
 
 [deps]
-LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
-YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+MathExpr = "7e419fb4-4148-4024-80a8-2502d26d6b11"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
 
 [compat]
 julia = ">= 1.5"

README.md

@@ -6,7 +6,7 @@
 |:-----------------:|:----------------:|:-----------------:|
 | [![**STABLE**][docs-stable-img]][docs-stable-url] [![**DEV**][docs-dev-img]][docs-dev-url] | [![Build Status][travis-img]][travis-url] [![Build Status][appveyor-img]][appveyor-url] | [![Code Coverage][codecov-img]][codecov-url] [![Code Coverage][coveralls-img]][coveralls-url] |
 
-[LatticeTools.jl](https://github.com/kyungminlee/LatticeTools.jl) is a Julia package which provides functionalities to define lattices and perform symmetry analysis, with focus on interacting many-body quantum Hamiltonians.
+[LatticeTools.jl](https://github.com/kyungminlee/LatticeTools.jl) is a Julia package that provides functionalities to define lattices and perform symmetry analyses useful for studying interacting quantum many-body Hamiltonians.
 
 
 ## Installation

docs/make.jl

@@ -33,6 +33,7 @@ makedocs(
             "Symmetry/space-symmetry.md",
             "Symmetry/space-operation.md",
             "Symmetry/irrep.md",
+            "Symmetry/space-symmetry-database.md",
         ],
         "Examples" => [
             "Group Isomorphism" => "generated/example_group_isomorphism.md",

docs/src/API/symmetry.md

@@ -120,13 +120,19 @@ iscompatible
 ## PointSymmetryDatabase
 
 ```@docs
-PointSymmetryDatabase.get2d
-PointSymmetryDatabase.get3d
-PointSymmetryDatabase.find2d
-PointSymmetryDatabase.find3d
+LatticeTools.PointSymmetryDatabase
+LatticeTools.PointSymmetryDatabase.get2d
+LatticeTools.PointSymmetryDatabase.get3d
+LatticeTools.PointSymmetryDatabase.find2d
+LatticeTools.PointSymmetryDatabase.find3d
 ```
 
 
+## IrrepDatabase
+
+```@docs
+LatticeTools.IrrepDatabase
+```
 
 
 ## Symmorphic Symmetry

docs/src/Symmetry/irrep.md

@@ -1,5 +1,39 @@
 # Irreducible Representations
 
+Given a symmetry of a system, its Hamiltonian can be broken into sectors corresponding to the irreducible representations, or *irreps*, of the symmetry group.
+(See [Using Symmetry in Exact Diagonalization](http://kyungminlee.org/symmetry-for-numerics).)
+
+
+## IrrepComponent
+
+A symmetry group in general has multiple irreps, and some of those irreps may be of dimension higher than one.
+The data structure that represents the component of an irrep of a symmetry is [`IrrepComponent`](@ref), which has three fields:
+`symmetry`, the underlying symmetry, `irrep_index`, the irrep it refers to, and `irrep_component`, the component in a multidimensional irrep.
+
+
+## Irreps of Translation Symmetry
+
+Translation symmetry forms an Abelian group.
+All irreps of a translation symmetry are, therefore, one-dimensional, corresponding to *Fourier modes*, or *momentum sectors*.
+Given a Bravais lattice, together with its generating translations, irreps can be computed simply as
 ```math
-\Gamma_i
-```
+\Phi_{\mathbf{k}} = \exp \left( - 2 \pi i \sum_{i} k_{i} x_{i} / L_{i} \right)
+```
+where $k_{i} \in \{0, 1, \ldots, L_{i}-1 \}$ labels the irrep,
+$x_{i}$ labels the translation operations in units of the generators,
+and $L_{i}$ is the order (i.e. period length) of the *i*th generator.
+
+Also since all irreps are one-dimensional, `IrrepComponent` of translation symmetry must, therefore, always have `irrep_component=1`.
+
+
+## Irreps of Point Symmetry
+
+Point symmetry, on the other hand, is not always Abelian.
+Unlike with translation symmetry which is abelian, **LatticeTools.jl** does not compute the irreps of the point group.
+Instead, it keeps a database of the point symmetries in two and three dimensions, and their irreps in [`PointSymmetryDatabase`](@ref).
+(* This may later be replaced by [`IrrepDatabase`](@ref).)
+The representation of the point operation, and their irreps are taken from the [Bilbao Crystallographic Server](https://www.cryst.ehu.es).
+
+
+[Group representation](https://en.wikipedia.org/wiki/Group_representation)
+[Irreducible representation](https://en.wikipedia.org/wiki/Irreducible_representation)

docs/src/Symmetry/space-operation.md

@@ -8,6 +8,7 @@ Here `S` is the type for the coordinates.
 using LatticeTools
 ```
 
+
 ## Translation Operation
 
 The type [`TranslationOperation{S}`](@ref) represents translation operation
@@ -30,6 +31,7 @@ t([3, 4])
 apply_operation(t, [5, 6])
 ```
 
+
 ## Point Operation
 
 Point operation is represented by the type [`PointOperation{S}`](@ref),
@@ -52,6 +54,7 @@ p = PointOperation([0 1; 1 0])
 p([2, 5])
 ```
 
+
 ## Space Operation
 
 ```@repl tbl

docs/src/Symmetry/space-symmetry-database.md

@@ -0,0 +1,5 @@
+# Space Symmetry Database
+
+[`PointSymmetryDatabase`](@ref)
+
+[`IrrepDatabase`](@ref)

docs/src/Symmetry/space-symmetry.md

@@ -1,4 +1,4 @@
-# Space symmetry analysis
+# Space Symmetry Analysis
 
 **LatticeTools.jl** provides functionalities space symmetry analysis, useful for creating symmetry sectors of quantum Hamiltonian.
 (Check out [Using Symmetry in Exact Diagonalization](http://kyungminlee.org/symmetry-for-numerics/).)
@@ -7,38 +7,42 @@
 ## Group
 
 Space symmetry operations (translation, rotation, inversion, mirror, etc.) form a mathematical structure called [*group*](https://en.wikipedia.org/wiki/Group).
-Within **LatticeTools.jl**, ther term **group** refers to the mathematical group structure of a symmetry, which essentially boils down to its multiplication table.
+Within **LatticeTools.jl**, the term **group** refers to the mathematical group structure of a symmetry, which essentially boils down to its multiplication table.
 Currently, the only type which implements a group is [`FiniteGroup`](@ref).
 
 The elements of a [`FiniteGroup`](@ref) are consecutive integers from 1 to n:
 The identity element is always represented by 1.
 The following example produces the [Klein four-group](https://en.wikipedia.org/wiki/Klein_four-group).
-```@repl
-using LatticeTools; # hide
+
+```@setup group
+using LatticeTools
+g = FiniteGroup([1 2 3 4; 2 1 4 3; 3 4 1 2; 4 3 2 1])
+```
+
+```@repl group
 g = FiniteGroup([1 2 3 4; 2 1 4 3; 3 4 1 2; 4 3 2 1])
 ```
 
 Group binary operation can be applied by [`group_product`](@ref)
-```@repl
-using LatticeTools; # hide
-g = FiniteGroup([1 2 3 4; 2 1 4 3; 3 4 1 2; 4 3 2 1]); #hide
+
+```@repl group
 group_product(g, 3, 4)
 p = group_product(g);
 p(3, 4)
 ```
 
 Given a group, a subgroup which contains certain elements can be generated by [`generate_subgroup`](@ref).
 The function returns the set of elements, not the group structure, of the subgroup including all of the specified elements, along with elements that are generated by the group law.
-```@repl
-using LatticeTools; # hide
-g = FiniteGroup([1 2 3 4; 2 1 4 3; 3 4 1 2; 4 3 2 1]); #hide
+
+```@repl group
 generate_subgroup(g, 3)
 generate_subgroup(g, [1, 3])
 generate_subgroup(g, [2, 3])
 ```
 
 A group multiplication table of arbitrary objects with an arbitrary operation can be produced using [`group_multiplication_table`](@ref):
-```@repl
+
+```@repl group
 group_multiplication_table([[1 0; 0 1], [1 0; 0 -1], [-1 0; 0 1], [-1 0; 0 -1]])
 ```
 
@@ -48,7 +52,7 @@ group_multiplication_table([[1 0; 0 1], [1 0; 0 -1], [-1 0; 0 1], [-1 0; 0 -1]])
 The term **symmetry**, on the other hand, is used to refer to realizations of the group structures on the lattice.
 Examples are [`TranslationSymmetry`](@ref), [`PointSymmetry`](@ref).
 
-In the current implementation of `LatticeTools.jl`, a symmetry object contains the following fields:
+In the current implementation of **LatticeTools.jl**, a symmetry object contains the following fields:
 - group
 - generators
 - conjugacy classes
@@ -83,42 +87,40 @@ In some (not all) cases, a space symmetry can be decomposed into translation sym
 In other words, if there is a point $O$ where every element of the space group can be written as a product of translation operation and point operation about the point *O*, then the space group can be called symmorphic space group.
 If no such point exists, then the space group is non-symmorphic.
 
-This can be written in the following way
+A symmorphic space symmetry is thus a semidirect product of translation symmetry and point symmetry:
 ```math
     S = T \rtimes P
 ```
 where *S*, *T*, and *P* are space symmetry, translation symmetry, and point symmetry about a point *O*.
 
-In the current implementation of `LatticeTools.jl`, the point *O* is always assumed to be the origin.
+In the current implementation of **LatticeTools.jl**, the point *O* is always assumed to be the origin.
 For proper specification of the space group, the sites need to be located at the correct positions.
 
 
 ## Symmetry embedding
 
 The elements of the space symmetry (without considering combination with some local unitary transformation) can be thought of as a subset of the permutation group of the lattice sites.
 
-An "embedding" of a symmetry onto a lattice, is a symmetry structure whose elements are permutations of sites represented by [`SitePermutation`](@ref).
+An **embedding** of a symmetry onto a lattice, is a symmetry structure whose elements are permutations of sites represented by [`SitePermutation`](@ref).
 
 ### Symmetry embedding of symmorphic symmetry
 
 The semi-direct product and the embedding commutes.
-See the following commutative diagram:
 ```
-     T ⋊ P  →  E(L,P)
+    (T, P)           ↦   T ⋊ P
 
-       ↓    ↘    ↓
+      ↧                    ↧
 
-     E(L,T) →  E(L, T ⋊ P)
+    (E(L,T), E(L,P)) ↦ E(L, T ⋊ P)
 ```
-where E(L, S) is embedding of *abstract* space group S onto lattice L.
+*E(L, S)* is embedding of *abstract* space group *S* onto lattice *L*.
 
 
 ## Compatibility between symmetries, symmetry-embeddings, and their irrep components
 
-In case of (symmorphic) space symmetry, we want to make sure that the translation symmetry and the point symmetry are "compatible".
-
-The compatibility condition is the following
-
+In case of (symmorphic) space symmetry, we need to make sure that the translation symmetry and the point symmetry are "compatible".
+In other words, the symmetry that we impose must be allowed by the underlying lattice.
+Let's consider compatibilities between lattices and symmetries.
 
 ### 1. Between lattice and translation symmetry
 
@@ -128,38 +130,15 @@ encodes directly the information of the translation symmetry,
 a [`Lattice`](@ref) and a [`TranslationSymmetry`](@ref) is compatible if they
 *share the same Bravais lattice*. No further requirement is needed.
 
-
 ### 2. Between lattice and point symmetry
 
 In order for a point symmetry to be a good symmetry of the lattice,
-we need the Bravais lattice to be invariant under the point symmetry at least.
-In an infinite lattice, this is always the case, and no requires no checks.
-For finite size lattice, however, the situation is different:
-Since the finite size lattice with periodic boundary condition can be
-understood as an infinite lattice modulo supercell,
-the Bravais lattice of the *supercell* also needs to be invariant under
-all operations of the point symmetry. The requirement therefore is that
-the column vectors of the shape matrix after point operation remain
-integer multiples of themselves.
-
-
-### 3. Between translation symmetry and point symmetry
-
-Same as 2.
-
-
-### 4. Between lattice and translation symmetry embedding
-
-Translation symmetry embedding is 
-
-|  a  |  TS    |  PS    |  L     |  TSE   |  PSE   |
-| :-: | :---------------: | :----: | :----: | :----: | :----: |
-| TS  | same matrix | shape matrix invariant under point operation     | same shape matrix  |       |       |
-| PS  |        |      |      |       |       |
-| L   |        |      |      |       |       |
-| TSE |        |      |      |       |       |
-| PSE |        |      |      |       |       |
-
+we need the Bravais lattice to be invariant under the point symmetry at least:
+whether this is the case or not depends on the lattice vectors, included in the `UnitCell`.
 
+The current implementation of **LatticeTools.jl**, however, represent the point group operations in integer coordinates in units of lattice vectors.
+This makes a point symmetry always be always compatible with an infinite lattice of the right dimension.
 
-## Symmorphic Symmetry
+For finite size lattices, however, the situation is different.
+Since a finite size lattice with periodic boundary condition can be understood as an infinite lattice modulo supercell, the Bravais lattice of the *supercell* also needs to be invariant under all operations of the point symmetry.
+The requirement therefore is that the column vectors of the shape matrix after point operation remain integer multiples of themselves.