From a6da0e8ed2c20f04cf8a55c6f75668be6cdd6826 Mon Sep 17 00:00:00 2001 From: Thomas Christensen Date: Tue, 24 Jan 2023 14:22:17 +0100 Subject: [PATCH] python docs for band symmetry methods (#149) * python docs for band symmetry methods * warn about `transformed-overlap`, `compute-symmetr*` not working for mpb-mpi/mpbi/mpbi-mpi --- doc/docs/Python_User_Interface.md | 26 ++++++++++++++++++++++++++ doc/docs/Scheme_User_Interface.md | 10 +++++----- 2 files changed, 31 insertions(+), 5 deletions(-) diff --git a/doc/docs/Python_User_Interface.md b/doc/docs/Python_User_Interface.md index 2b2735e..9102cce 100644 --- a/doc/docs/Python_User_Interface.md +++ b/doc/docs/Python_User_Interface.md @@ -531,6 +531,32 @@ Returns a list of the group-velocity components (units of *c*) in the given *dir            As above, but returns the group velocity or component thereof only for band `which_band`. +### Band symmetry + +MPB can compute the "characters" or "symmetry eigenvalues" of eigenfields under a symmetry operation $g$, i.e. MPB can compute the overlap integrals: + +\[(\mathbf{F}|g\mathbf{F}') = \int \mathbf{F}(\mathbf{r})^\dagger [g\mathbf{F}'(\mathbf{r})] \, \mathrm{d}\mathbf{r} = \int \mathbf{F}(\mathbf{r})^\dagger (g\mathbf{F}')(g^{-1}\mathbf{r}) \, \mathrm{d}\mathbf{r}\] + +where **F** denotes either the **E**- or **H**-field and **F**′ denotes the associated **D**- or **B**-field (including Bloch phases) and integration is over the unit cell. +The space group operation $g$ may include both rotational ($W$) and translational ($w$) parts, and are specified by the associated matrix-column pair $g = \{W|w\}$ acting on points as $\{W|w\}\mathbf{r} = W\mathbf{r} + w$. +$W$ and $w$ should be supplied as `Matrix` and `vector3` variables in the basis of the lattice (listings of space group operations are available e.g. on the [Bilbao Crystallographic Server](https://www.cryst.ehu.es/)). +(Note that $g$ transforms both the vectorial components of **F**′ as well as its coordinates: if **F**′ refers to a **B**-field, an additional factor of $\mathop{\mathrm{det}}W$ is incorporated to account for its pseudovectorial nature.) + +Given the character tables associated with the little groups of a considered photonic crystal, this functionality can e.g. be used to infer which irreducible representation (irrep) a given band (or band grouping) transforms as across the Brillouin zone. + +**`ModeSolver.compute_symmetry(which_band, W, w)`** +           +Compute the $(\mathbf{H}|g\mathbf{B})$ character for `which_band` under a symmetry operation with rotation `W` and translation `w`, returning a complex number. + +**`ModeSolver.compute_symmetries(W, w)`** +           +Equivalent to `compute_symmetry`, but returns characters for *all* computed bands, returning a list of complex numbers. + +**`ModeSolver.transformed_overlap(W, w)`** +           +Sets **F**′ to the currently loaded field (must be either a **D**- or **B**-field) and computes the associated character under the symmetry operation specified by `W` and `w`, returning a complex number. +Usually, it will be more convenient to call `compute_symmetry` (which wraps `transformed_overlap` with an initialization of the current field from `get_bfield`). + Field Manipulation ------------------ diff --git a/doc/docs/Scheme_User_Interface.md b/doc/docs/Scheme_User_Interface.md index 39a014f..8623ec0 100644 --- a/doc/docs/Scheme_User_Interface.md +++ b/doc/docs/Scheme_User_Interface.md @@ -573,19 +573,19 @@ As above, but returns the group velocity or component thereof only for band `whi ### Band symmetry -MPB can compute the "characters" of a symmetry operation $g$ applied to a field at a particular point, i.e. MPB can compute the overlap integrals: +MPB can compute the "characters" or "symmetry eigenvalues" of eigenfields under a symmetry operation $g$, i.e. MPB can compute the overlap integrals: -```math -(\mathbf{F}|g\mathbf{F}') = \int \mathbf{F}(\mathbf{r})^\dagger [g\mathbf{F}'(\mathbf{r})] \, \mathrm{d}\mathbf{r} = \int \mathbf{F}(\mathbf{r})^\dagger (g\mathbf{F}')(g^{-1}\mathbf{r}) \, \mathrm{d}\mathbf{r} -``` +\[(\mathbf{F}|g\mathbf{F}') = \int \mathbf{F}(\mathbf{r})^\dagger [g\mathbf{F}'(\mathbf{r})] \, \mathrm{d}\mathbf{r} = \int \mathbf{F}(\mathbf{r})^\dagger (g\mathbf{F}')(g^{-1}\mathbf{r}) \, \mathrm{d}\mathbf{r}\] where **F** denotes either the **E**- or **H**-field and **F**′ denotes the associated **D**- or **B**-field (including Bloch phases) and integration is over the unit cell. -The space group operation $g$ may include both rotational ($W$) and translational ($w$) parts, and are specified by the associated matrix-column pair $g = \{W,w\}$ acting on points as $\{W,w\}\mathbf{r} = W\mathbf{r} + w$. +The space group operation $g$ may include both rotational ($W$) and translational ($w$) parts, and are specified by the associated matrix-column pair $g = \{W|w\}$ acting on points as $\{W|w\}\mathbf{r} = W\mathbf{r} + w$. $W$ and $w$ should be supplied as `matrix3x3` and `vector3` variables in the basis of the lattice (listings of space group operations are available e.g. on the [Bilbao Crystallographic Server](https://www.cryst.ehu.es/)). (Note that $g$ transforms both the vectorial components of **F**′ as well as its coordinates: if **F**′ refers to a **B**-field, an additional factor of $\mathop{\mathrm{det}}W$ is incorporated to account for its pseudovectorial nature.) Given the character tables associated with the little groups of a considered photonic crystal, this functionality can e.g. be used to infer which irreducible representation (irrep) a given band (or band grouping) transforms as across the Brillouin zone. +**Note:** the following utilities currently require that MPB is [compiled serially](#parallel-mpb) and without explicit assumption of [inversion symmetry](#inversion-symmetry) (i.e., works for `mpb` but not for `mpb-mpi`, `mpbi`, or `mpbi-mpi`). + **`(compute-symmetry which-band W w)`** Compute the $(\mathbf{H}|g\mathbf{B})$ character for `which-band` under a symmetry operation with rotation `W` and translation `w`, returning a complex number.