reorganize some docs

docs/src/index.md

@@ -1,60 +1,12 @@
-# AutoBZ.jl documentation
 
-This Julia package provides routines for multi-dimensional Brillouin zone (BZ)
-integration of both generic and Wannier-interpolated integrands.
-It aims to implement algorithms which automatically compute BZ integrals to a
-specified error tolerance by resolving smooth yet highly localized integrands.
 
-In many-body Green's function methods, BZ integrands are localized at a scale
-determined by a non-zero, but possibly small, system- and temperature-dependent
-scattering rate. For example, the single-particle retarded Green's function of
-an electronic system for frequency ``\omega`` and reciprocal space vector
-``\bm{k}`` with chemical potential ``\mu``, Hermitian Hamiltonian matrix
-``H(\bm{k})``, and self-energy matrix ``\Sigma(\omega)``, which is given by
-```math
-G(\omega) = \int_{\text{BZ}} d\bm{k}\ \operatorname{Tr} \left[ (\hbar\omega - H(\bm{k}) - \Sigma(\omega))^{-1} \right]
+# AutoBZ.jl
+
+```@docs
+AutoBZ
 ```
-is localized about the manifold defined by ``\det(\hbar\omega - H(\bm{k}))=0`` (i.e.
-the Fermi surface when ``\hbar\omega=\mu``) by a scattering rate depending on
-``\operatorname{Im}\ \Sigma(\omega)``.
 
 To start using the package, see the [Workflow](@ref) and [Demos](@ref) sections.
-It may also be helpful to see the [AutoBZCore.jl
-documentation](https://lxvm.github.io/AutoBZCore.jl/dev/) since this package is
-built on those interfaces.
-
-## Package features
-
-### Implemented
-* Iterated adaptive integration (IAI) with nested calls to
-  [QuadGK.jl](https://github.com/JuliaMath/QuadGK.jl)
-    * Algorithm with logarithmic complexity for increasingly localized integrands
-    * Irreducible Brillouin zone (IBZ) integration for the cubic lattice
-* Equispace integration (PTR) as described by Kaye et al. [^1]
-    * Automatic algorithm that refines ``k``-grid to meet requested error
-* Support for Wannier-interpolated integrands in the Applications module
-    * User-defined integrands based on Bloch Hamiltonians
-    * Density of states (DOS) calculations
-    * Transport calculations based on 
-        [TRIQS DFTTools](https://triqs.github.io/dft_tools/latest/guide/transport.html)
-        * Calculation of transport function and kinetic coefficients
-        * Option to separate intra-band and inter-band contributions
-        * Parallelized calculations available through `batchsolve` interface of AutoBZCore.jl
-    * [Wannier90](http://www.wannier.org/)-based parsers Hamiltonians
-      (`*_hr.dat` files) and position operators (`*_r.dat` files)
-    * Automated interpolation for frequency-dependent data of [Self
-      energies](@ref) in text files, using
-      [EquiBaryInterp.jl](https://github.com/lxvm/EquiBaryInterp.jl) and
-      [HChebInterp.jl](https://github.com/lxvm/HChebInterp.jl).
-* IBZ integration for arbitrary symmetry groups (via an interface to
-  [SymmetryReduceBZ.jl](https://github.com/jerjorg/SymmetryReduceBZ.jl))
-
-### More ideas
-* Support for integrands of the form ``f_{0} ( \int dx_{1} f_{1}( \int dx_{2}
-  f_{2}( \cdots \int dx_{n} f_{n})))``
-* Multi-dimensional adaptive Chebyshev interpolation, like
-  [baobzi](https://github.com/flatironinstitute/baobzi)
-* Globally adaptive IAI
 
 ## Notes
 
@@ -65,6 +17,4 @@ To see a poster showcasing calculations with the library, click this
 
 ## Contact the developer
 
-[Lorenzo Van Muñoz](https://web.mit.edu/lxvm/www/)
-
-[^1]: [Kaye et al. "Automatic, high-order, and adaptive algorithms for Brillouin zone integration"](http://arxiv.org/abs/2211.12959)
+[Lorenzo Van Muñoz](https://web.mit.edu/lxvm/www/)

docs/src/pages/app/self_energy.md

@@ -86,6 +86,8 @@ AutoBZ.ub
 
 ```@docs
 AutoBZ.EtaSelfEnergy
+AutoBZ.ConstScalarSelfEnergy
 AutoBZ.ScalarSelfEnergy
+AutoBZ.DiagonalSelfEnergy
 AutoBZ.MatrixSelfEnergy
 ```

docs/src/pages/man/fourier.md

@@ -73,14 +73,33 @@ The concrete types listed below all implement the `AbstractFourierSeries`
 interface and should cover most use cases.
 
 ```@docs
+AutoBZ.AbstractWannierInterp
+AutoBZ.AbstractGaugeInterp
+AutoBZ.AbstractHamiltonianInterp
 AutoBZ.HamiltonianInterp
+AutoBZ.AbstractCoordInterp
 AutoBZ.BerryConnectionInterp
+AutoBZ.AbstractVelocityInterp
 AutoBZ.GradientVelocityInterp
 AutoBZ.CovariantVelocityInterp
 AutoBZ.MassVelocityInterp
 ```
 
-The possible velocity components are
+### Gauges
+```@docs
+AutoBZ.AbstractGauge
+AutoBZ.Wannier
+AutoBZ.Hamiltonian
+```
+
+### Coordinate systems
+```@docs
+AutoBZ.AbstractCoordinate
+AutoBZ.Cartesian
+AutoBZ.Lattice
+```
+
+### Velocity components
 ```@docs
 Whole
 Intra

docs/src/pages/man/internal.md

@@ -6,35 +6,22 @@ The following symbols used by AutoBZ may change in future versions
 AutoBZ.SSymmetricCompact
 AutoBZ.hinv
 AutoBZ.dos_integrand
-AutoBZ.AbstractGauge
-AutoBZ.Hamiltonian
 AutoBZ.tr_kron
 AutoBZ.gloc_integrand
-AutoBZ.AbstractGaugeInterp
 AutoBZ.diag_inv
-AutoBZ.AutoBZ
-AutoBZ.ConstScalarSelfEnergy
 AutoBZ.tr_mul
 AutoBZ.to_gauge
-AutoBZ.AbstractVelocityInterp
 AutoBZ.fermi_window_halfwidth
 AutoBZ.diaggloc_integrand
-AutoBZ.Wannier
-AutoBZ.DiagonalSelfEnergy
 AutoBZ.CoordDefault
 AutoBZ.CartesianRep
 AutoBZ.to_coord
-AutoBZ.AbstractWannierInterp
 AutoBZ.AbstractVelocityComponent
-AutoBZ.AbstractCoordInterp
 AutoBZ.shift!
-AutoBZ.AbstractHamiltonianInterp
-AutoBZ.AbstractCoordinate
-AutoBZ.Cartesian
 AutoBZ.tr_inv
 AutoBZ.to_vcomp_gauge
 AutoBZ.get_safe_fermi_window_limits
-Base.parent
+AutoBZ.parentseries
 AutoBZ.commutator
 AutoBZ.trgloc_integrand
 AutoBZ.covariant_velocity
@@ -44,5 +31,4 @@ AutoBZ.SOC
 AutoBZ.GaugeDefault
 AutoBZ.VcompDefault
 AutoBZ.herm
-AutoBZ.Lattice
 ```

src/AutoBZ.jl

@@ -1,11 +1,52 @@
 """
-An applications package implementing iterated-adaptive integration and equispace
-integration for electronic structure and transport calculations. It excels at
-integrating both localized and also broadened Brillouin-zone integrands, using
-the algorithms described by [Kaye et al.](http://arxiv.org/abs/2211.12959). This
-package also provides multi-threaded routines for parallelized calculations.
-See `AutoBZCore` if you only need the essential functionality of the library to
-define custom BZ integrands.
+This Julia package provides routines for multi-dimensional Brillouin zone (BZ)
+integration for applications of Wannier interpolation to the calculation of density of
+states and optical conductivity with self energies and spin-orbit coupling.
+It uses algorithms which automatically compute BZ integrals to a
+specified error tolerance by resolving smooth yet highly localized integrands.
+
+See [AutoBZCore.jl](https://lxvm.github.io/AutoBZCore.jl/dev/) on how to create
+custom integrands and for more details on the algorithms.
+
+In many-body Green's function methods, BZ integrands are localized at a scale
+determined by a non-zero, but possibly small, system- and temperature-dependent
+scattering rate. For example, the single-particle retarded Green's function of
+an electronic system for frequency ``\omega`` and reciprocal space vector
+``\bm{k}`` with chemical potential ``\mu``, Hermitian Hamiltonian matrix
+``H(\bm{k})``, and self-energy matrix ``\Sigma(\omega)``, which is given by
+```math
+G(\omega) = \int_{\text{BZ}} d\bm{k}\ \operatorname{Tr} \left[ (\hbar\omega - H(\bm{k}) - \Sigma(\omega))^{-1} \right]
+```
+is localized about the manifold defined by ``\det(\hbar\omega - H(\bm{k}))=0`` (i.e.
+the Fermi surface when ``\hbar\omega=\mu``) by a scattering rate depending on
+``\operatorname{Im}\ \Sigma(\omega)``.
+
+## Package features
+
+* Iterated adaptive integration (IAI) with nested calls to
+  [QuadGK.jl](https://github.com/JuliaMath/QuadGK.jl)
+    * Algorithm with logarithmic complexity for increasingly localized integrands
+    * Irreducible Brillouin zone (IBZ) integration for the cubic lattice
+* Equispace integration (PTR) as described by Kaye et al. [^1]
+    * Automatic algorithm that refines ``k``-grid to meet requested error
+* Support for Wannier-interpolated integrands
+    * User-defined integrands based on Bloch Hamiltonians
+    * Density of states (DOS) calculations
+    * Transport calculations based on
+        [TRIQS DFTTools](https://triqs.github.io/dft_tools/latest/guide/transport.html)
+        * Calculation of transport function and kinetic coefficients
+        * Option to separate intra-band and inter-band contributions
+        * Parallelized calculations available through `batchsolve` interface of AutoBZCore.jl
+    * [Wannier90](http://www.wannier.org/)-based parsers Hamiltonians
+      (`*_hr.dat` files) and position operators (`*_r.dat` files)
+    * Automated interpolation for frequency-dependent self-energy data in text files, using
+      [EquiBaryInterp.jl](https://github.com/lxvm/EquiBaryInterp.jl) and
+      [HChebInterp.jl](https://github.com/lxvm/HChebInterp.jl).
+* IBZ integration for arbitrary symmetry groups (via an interface to
+  [SymmetryReduceBZ.jl](https://github.com/jerjorg/SymmetryReduceBZ.jl))
+* Supports systems with spin-orbit coupling expressed in the self-energy
+
+[^1]: [Kaye et al. "Automatic, high-order, and adaptive algorithms for Brillouin zone integration"](http://arxiv.org/abs/2211.12959)
 """
 module AutoBZ