-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Utilities for condensed matter physics tight binding calculations.
--   
--   TBit provides tools for parameterizing and computing condensed matter
--   physics quantities based on tight-binding models. It provides
--   utitilies for computing Chern numbers and Berry curvatures of
--   electronic band structure, generating gnuplot-readable dispersion
--   plots, and calculating assorted quantities such as orbital
--   magnetization and Nernst conductivity.
@package TBit
@version 0.4.2.1

module TBit.Numerical.Derivative

-- | Takes the element-wise first derivative of the given
--   vector/matrix-valued function of a single variable. The first argument
--   gives the spacing epsilon as used in the difference formula,
--   <i>i.e.</i> that thing which limit is taken to zero. The second
--   argument is the matrix function, and the third argument is the point
--   at which to evaluate the derivative.
--   
--   The derivative is taken using the finite difference method to second
--   order.
diff :: (Num (c e), Container c e) => e -> (e -> c e) -> e -> c e

-- | As <a>diff</a>, but uses fourth order finite difference method. This
--   means that the matrix argument will need to be evaluated at twice as
--   many points, which increases the runtime twofold until we can
--   implement a full-gridded calculation.
diff4 :: (Num (c e), Container c e) => e -> (e -> c e) -> e -> c e

module TBit.Hamiltonian.Builder.Matrification

-- | Take a list of matrices, some of which may differ from the others in
--   dimensionality by a factor of two, and maybe return the sum of these
--   matrices with appropriate (right) kronecker products taken to make the
--   summation well-formed. Useful for combining matrices written in forms
--   with and without spin indices.
mixedSum :: [Matrix (Complex Double)] -> Maybe (Matrix (Complex Double))

-- | Send a tight-binding graph model to the corresponding Hamiltonian
--   matrix.
toMatrix :: Gr (Matrix (Complex Double)) (Matrix (Complex Double)) -> Matrix (Complex Double)

module TBit.Numerical.Integration

-- | Integrate a function of n variables by giving the corresponding n
--   integration domains, <i>i.e.</i>
--   
--   <pre>
--   let f x y z = x^2 + log (y-z)
--   integrate f (0,1) (3,4) (1,2)
--   </pre>
--   
--   This code was borrowed from the excellent answer at
--   <a>http://stackoverflow.com/questions/23703360/using-numeric-integration-tanhsinh-for-n-dimensional-integration</a>.
--   
--   The integration uses the Tanh-Sinh quadrature method and relies on
--   Kmett's integration libary.
integrate :: (Integrable r, CurryBounds (Bounds r)) => r -> Curried (Bounds r) Res
instance Integrable Double
instance Integrable r => Integrable (Double -> r)
instance CurryBounds ()
instance CurryBounds bs => CurryBounds (b, bs)

module TBit.Types
type Parameterized = ExceptT TBError (State Parameters)
data Parameters
[Parameters] :: Lattice -> Meshing -> [LEdge Displacement] -> Map String (Complex Double) -> Map String (Vector (Complex Double)) -> Parameters
[latticeData] :: Parameters -> Lattice
[meshingData] :: Parameters -> Meshing
[decomData] :: Parameters -> [LEdge Displacement]
[scalarParams] :: Parameters -> Map String (Complex Double)
[vectorParams] :: Parameters -> Map String (Vector (Complex Double))
type Lattice = [Vector Double]
data TBError
[SingularLatticeError] :: TBError
[DimensionalityError] :: String -> TBError
[UndefinedError] :: String -> TBError
[UnknownParameter] :: String -> TBError
type Grid = Map GridIndex
type BandIndex = Int
type Filling = BandIndex
data Meshing
[Spacing] :: Double -> Meshing
data GridIndex
[GID] :: [Int] -> GridIndex
type Chern = Double
type Curvature = Double
type Wavevector = Vector Double
type KPath = [(String, Wavevector)]
type Hamiltonian = Wavevector -> Matrix (Complex Double)
type Magnetization = Double
type Moment = Vector Double
type ChemEnergy = Double
type Energy = Double
type Eigenstate = Vector (Complex Double)
type Eigenbra = Matrix (Complex Double)
type Eigenket = Matrix (Complex Double)
type AFOrder = Complex Double
type Hopping = Complex Double
type OnSite = Complex Double
type Rashba = Complex Double
type SOC = Complex Double
type Parameterizable = ExceptT TBError (State Parameters)
data SiteData
[ScalarSite] :: Int -> SiteData
[num] :: SiteData -> Int
[VectorSite] :: Int -> Moment -> SiteData
[num] :: SiteData -> Int
[mom] :: SiteData -> Moment
type Displacement = Vector Double
type CellGraph = Gr SiteData Displacement
type AdjMatrix = Gr (Matrix (Complex Double)) (Matrix (Complex Double))
type Term = String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)
sigmaX :: Matrix (Complex Double)
sigmaY :: Matrix (Complex Double)
sigmaZ :: Matrix (Complex Double)
instance Show Parameters
instance Show SiteData
instance Show GridIndex
instance Eq GridIndex
instance Ord GridIndex
instance Show Meshing
instance Show TBError
instance NFData Meshing
instance NFData Parameters
instance Traversable ((,,) a b)
instance Foldable ((,,) a b)
instance Functor ((,,) a b)
instance Traversable ((,,,) a b c)
instance Foldable ((,,,) a b c)
instance Functor ((,,,) a b c)
instance NFData TBError

module TBit.Parameterization

-- | Given a list of (<a>String</a>, a) pairs, return a mapping from the
--   string to the value. Such a map is suitable for setting the
--   <a>scalarParams</a> and <a>vectorParams</a> records of the
--   <a>Parameters</a> type.
loadParams :: [(String, a)] -> Map String a

-- | Given a <a>String</a>, retrieve that value from the parameterization
--   monad. If no such scalar has been uploaded to the <a>Parameters</a>
--   type, <a>getScalar</a> with throw an error in
--   'TBit.Types.Parameterized'\'s <a>ExceptT</a> monad.
getScalar :: String -> Parameterized (Complex Double)

-- | Given a <a>String</a>, retrieve that value from the parameterization
--   monad. If no such scalar has been uploaded to the <a>Parameters</a>
--   type, <a>getScalar</a> with throw an error in
--   'TBit.Types.Parameterized'\'s <a>ExceptT</a> monad.
getVector :: String -> Parameterized (Vector (Complex Double))

-- | Return the spacing information for purposes of gridding the Brillouin
--   zone.
getMesh :: Parameterized Meshing

-- | Compute a <a>Parameterized</a> quantity given a set of input
--   parameters.
crunch :: Parameterized a -> Parameters -> Either TBError a

-- | Return a list of primitive lattice vectors.
primitiveLattice :: Parameterized Lattice

-- | Return a list of reciprocal primitive lattice vectors. They correspond
--   in order to the return values of <a>primitiveLattice</a>, in the sense
--   that:
--   
--   <pre>
--   do as &lt;- primitiveLattice
--      bs &lt;- primitiveLattice
--      return $ zipWith `dot` as bs
--   </pre>
--   
--   will return the list
--   
--   <pre>
--   replicate dim (2*pi)
--   </pre>
--   
--   up to numerical precision.
recipPrimitiveLattice :: Parameterized Lattice

module TBit.Framework

-- | Returns a mesh of points within the <i>n</i>-parallelepiped subtended
--   by the reciprocal lattice vectors. Covers the entire brillouin zone,
--   though not in the shape you might expect, and not in a way that's
--   pretty for graphing.
meshBZ :: Parameterized (Grid Wavevector)

-- | As <a>meshBZ</a>, but with parallelepipeds extending in each quadrant,
--   octant... <i>n</i>-ant of the reciprocal lattice basis. Should cover
--   more than the entire first Brillouin zone.
meshBigBZ :: Parameterized (Grid Wavevector)

-- | Integrates using a simple grid-sum.
bzIntegral :: (Wavevector -> Parameterized Double) -> Parameterized Double

-- | As <a>bzIntegral</a>, but also gives the absolute error as the second
--   value in the returned tuple.
bzIntegral' :: (Wavevector -> Parameterized Double) -> Parameterized (Double, Double)

-- | Given a function defined on the Brillouin zone, evaluate it everywhere
--   by doing nested single integrations and using Takahashi and Mori's
--   Tanh-Sinh quadrature method. Should be robust against singularities
--   and the like, and is <i>properly</i> set up for massive
--   parallelization (via EdwardKmett's integration library, certainly not
--   mine). Watch Dirac run this thing. Only implemented in 2D.
bzIntegral'' :: (Wavevector -> Parameterized Double) -> Parameterized Double

-- | Given a list of points in <i>k</i>-space, return a list of points that
--   interpolates affine paths between them, in turn; a typical usage case
--   might be
--   
--   <pre>
--   kPath [gammaPoint, kPoint, mPoint, gammaPoint]
--   </pre>
--   
--   which is used in the <a>bandPlot</a> function. The spacing between
--   points on the interpolated path is determined by the
--   <a>meshingData</a> parameter.
kPath :: [Wavevector] -> Parameterized ([Wavevector])

module TBit.Hamiltonian.Eigenstates

-- | Returns a list of eigenvectors sorted by eigenvalue. The lowest energy
--   state is the first element of the returned list.
eigenstates :: Hamiltonian -> Wavevector -> Parameterized [Eigenstate]

-- | As <a>eigenkets</a>, takes the conjugate transpose of each ket.
eigenbras :: Hamiltonian -> Wavevector -> Parameterized [Eigenbra]

-- | As <a>eigenstates</a>, but converts each vector to a column matrix for
--   convenience in certain caclulations.
eigenkets :: Hamiltonian -> Wavevector -> Parameterized [Eigenket]

-- | Returns a list of eigenvalues, sorted in ascending order.
eigenenergies :: Hamiltonian -> Wavevector -> Parameterized [Energy]

-- | Returns the full eigensystem, sorted by energy. Equivalent to zipping
--   the results of <a>eigenenergies</a> and <a>eigenstates</a>.
eigensystem :: Hamiltonian -> Wavevector -> Parameterized [(Energy, Eigenstate)]

module TBit.Plots

-- | Given a hamiltonian and a set of parameters, plot a real-valued
--   function over the Brillouin zone. For a Berry curvature plot,
--   <i>e.g.</i>,
--   
--   <pre>
--   bzPlot (kagomeAF, defaultParams) (bandCurvature 0)
--   </pre>
--   
--   The output string is suitable for gnuplot, unless that string is
--   reporting an error from the calculation.
bzPlot :: (Parameterized Hamiltonian, Parameters) -> (Hamiltonian -> Wavevector -> Parameterized Double) -> String

-- | Given a hamiltonian and a set of parameters, plot a real-valued
--   function over some range of a parameter. For a Chern number plot over
--   the hopping parameter, <i>e.g.</i>,
--   
--   <pre>
--   paramPlot (kagomeAF, defaultParams) (chern 1) ("t", [1.0, 1.1 .. 5.0])
--   </pre>
--   
--   The output string is suitable for gnuplot, unless that string is
--   reporting an error from the calculation.
paramPlot :: (Parameterized Hamiltonian, Parameters) -> (Hamiltonian -> Parameterized Double) -> (String, [Double]) -> String

-- | Given a hamiltonian and a set of parameters, plot the bands over a
--   path anchored by the provided wavevectors. For instance,
--   
--   <pre>
--   gamma  = vector [0.0 ,  0.0]
--   point1 = vector [0.5 ,  1.0]
--   point2 = vector [0.5 , -1.0]
--   bandPlot (kagomeAF, defaultParams) [gamma, point1, point2, gamma]
--   </pre>
--   
--   The output string is suitable for gnuplot, unless that string is
--   reporting an error from the calculation.
bandPlot :: (Parameterized Hamiltonian, Parameters) -> [Wavevector] -> String

module TBit.Topological.Curvature

-- | Calculate the Berry curvature of a single band, which is to be given
--   indexed from zero (i.e. to calculate the lowest band, pass in 0 for
--   the <a>BandIndex</a>. Uses the five-point stencil method for
--   differentiation.
bandCurvature :: BandIndex -> Hamiltonian -> Wavevector -> Parameterized Curvature

-- | Calculate the total Berry curvature of a the occupied bands, which are
--   specified by passing in the number of filled bands as the first
--   argument. For example, to find the curvature due to occupied bands of
--   a 4 band system at half-filling, pass in 2 for the <a>BandIndex</a>.
--   Uses the five-point stencil method for differentiation.
occupiedCurvature :: BandIndex -> Hamiltonian -> Wavevector -> Parameterized Curvature

-- | Deprecated?
curvatureFieldBand :: BandIndex -> Hamiltonian -> Parameterized [(Wavevector, Curvature)]

-- | Deprecated?
curvatureFieldOcc :: BandIndex -> Hamiltonian -> Parameterized [(Wavevector, Curvature)]

module TBit.Topological.Chern

-- | Calculate the Chern number of the first n occupied bands by using a
--   grid of closed loops and calculating many Berry phases using the
--   discretized formula. This function is <i>guaranteed</i> to return an
--   integer result by rounding the actual calculation. It tries to
--   determine if the Chern number is undefined due to a degeneracy, and if
--   it is then it throws an error via the <a>ExceptT</a> monad
--   transformer.
chern :: BandIndex -> Hamiltonian -> Parameterized Chern
chernRaw :: BandIndex -> Hamiltonian -> Parameterized Chern

-- | Calculate the Chern number of the nth band (indexed from 0) by
--   integrating the Berry curvature over the Brillouin zone. The
--   <a>BandIndex</a> parameter is passed directly to <a>bandCurvature</a>,
--   and should use the same conventions for specifying the band.
--   
--   The output is appropriately normalized by 1/2π. The integration is
--   carried out using the TanhSinh quadrature method via <a>integrate</a>.
chernBand :: BandIndex -> Hamiltonian -> Parameterized Chern

module TBit.Magnetic.OrbitalMagnetization

-- | Returns the total orbital magnetization due to filling the first n
--   bands.
orbMag :: Filling -> Hamiltonian -> Parameterized Magnetization

-- | Returns the gauge-invariant self-rotational orbital magnetization,
--   i.e. the circular dichroism, of the occupied bands, accomplished by
--   integrating <a>dichroicIntegrand</a>.
dichroism :: Filling -> Hamiltonian -> Parameterized Magnetization

-- | Essentially equation (12) from PRB _77_, 054438 (2008) with alpha,
--   beta set to x, y respectively so as to give the z-component of the
--   (expectation value of) the circular dichroism pseudovector. This form
--   takes a double sum over occupied and then unoccupied states, which
--   improves over the implementation of <a>integrandMk</a> by allowing for
--   intra-(un)occupied band degeneracies as long as there is still an
--   electronic band gap.
--   
--   As is consistent with our API for these types of functions, the
--   <a>Filling</a> argument should be a positive integer counting the
--   number of filled bands.
dichroicIntegrand :: Filling -> Hamiltonian -> Wavevector -> Parameterized Magnetization

-- | Sums <a>bandIntrinsicOM</a> over the first n bands.
intrinsicOM :: Filling -> Hamiltonian -> Parameterized Magnetization

-- | Gives the gauge-invariant self-rotational orbital magnetism, which is
--   proportional to the circular dichroism for a particular band index.
--   This is m(k) in Xiao et al's semiclassical approach (hence the name).
integrandMk :: BandIndex -> Hamiltonian -> Wavevector -> Parameterized Magnetization

-- | Returns the intrinsic orbital magnetization of the n<i>th</i> band,
--   namely the integral of _m_(k) from (Xiao et al., 2005).
bandIntrinsicOM :: BandIndex -> Hamiltonian -> Parameterized Magnetization

module TBit.Electronic.Conductance
nernstConductivity :: Hamiltonian -> Parameterized Double

module TBit.Hamiltonian.Builder.Examples
ring :: Int -> CellGraph
squareLattice :: CellGraph
hexLattice :: CellGraph
kagomeLattice :: CellGraph
kagomeRibbon :: Int -> CellGraph
kagomeRibbon' :: Int -> CellGraph
hermitize :: CellGraph -> CellGraph
instance Graph g => Monoid (g a b)

module TBit.Hamiltonian.Builder.Terms

-- | Add nearest-neighbor hopping to a lattice model.
neighborTerm :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)

-- | Add an onsite energy term to a lattice model.
onsiteTerm :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)

-- | Add an staggered onsite term to a lattice model. Works based on the
--   integer parity of graph nodes, making it model-detail-dependent.
parityStaggeredTerm :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)

-- | Produces a representation of local magnetic moments given by site-wise
--   <a>VectorSite</a> data. Fails clumsily if applied to Scalar sites.
localMoments :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)

-- | Produces a spin-orbit interaction in the style of that given by Hua et
--   al in PRL <i>112</i>, 017205 (2014). It should probably only be used
--   with a Kagomé lattice <a>CellGraph</a>. It works by looking at nearest
--   neighbor pairs (<i>i</i>,<i>j</i>) and then looking up the
--   <a>VectorSite</a> moment of site <i>k</i>; <i>k</i> is computed as
--   
--   <pre>
--   k = let i' = succ $ (i - 1) `mod` 3
--           j' = succ $ (j - 1) `mod` 3
--        in head $ [1,2,3] \\ [i',j']
--   </pre>
--   
--   (Recall that <i>i</i> and <i>j</i> are indexed from 1 as nodes.)
--   Clearly, this function is not safe unless it's applied to the correct
--   lattice.
--   
--   Once <a>mom</a> is computed for <a>VectorSite</a> <i>k</i>, it is
--   coupled to the Pauli matrix tensor as expected. The parity &amp;nu; is
--   chosen by asking whether succ <i>i</i> == <i>j</i> mod 3.
kagomeSOC :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)

-- | Produces a Rashba spin-orbit coupling term for an E-field applied
--   along the <i>z</i> direction.
rashbaZ :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)


-- | This module re-exports several useful functions so that we don't need
--   to import a bunch of libraries at once into a script we'll frequently
--   be switching the output from.
module TBit.Toolbox

-- | Calculate the Chern number of the first n occupied bands by using a
--   grid of closed loops and calculating many Berry phases using the
--   discretized formula. This function is <i>guaranteed</i> to return an
--   integer result by rounding the actual calculation. It tries to
--   determine if the Chern number is undefined due to a degeneracy, and if
--   it is then it throws an error via the <a>ExceptT</a> monad
--   transformer.
chern :: BandIndex -> Hamiltonian -> Parameterized Chern

-- | Calculate the Chern number of the nth band (indexed from 0) by
--   integrating the Berry curvature over the Brillouin zone. The
--   <a>BandIndex</a> parameter is passed directly to <a>bandCurvature</a>,
--   and should use the same conventions for specifying the band.
--   
--   The output is appropriately normalized by 1/2π. The integration is
--   carried out using the TanhSinh quadrature method via <a>integrate</a>.
chernBand :: BandIndex -> Hamiltonian -> Parameterized Chern

-- | Calculate the Berry curvature of a single band, which is to be given
--   indexed from zero (i.e. to calculate the lowest band, pass in 0 for
--   the <a>BandIndex</a>. Uses the five-point stencil method for
--   differentiation.
bandCurvature :: BandIndex -> Hamiltonian -> Wavevector -> Parameterized Curvature

-- | Calculate the total Berry curvature of a the occupied bands, which are
--   specified by passing in the number of filled bands as the first
--   argument. For example, to find the curvature due to occupied bands of
--   a 4 band system at half-filling, pass in 2 for the <a>BandIndex</a>.
--   Uses the five-point stencil method for differentiation.
occupiedCurvature :: BandIndex -> Hamiltonian -> Wavevector -> Parameterized Curvature

-- | Returns the total orbital magnetization due to filling the first n
--   bands.
orbMag :: Filling -> Hamiltonian -> Parameterized Magnetization

-- | Sums <a>bandIntrinsicOM</a> over the first n bands.
intrinsicOM :: Filling -> Hamiltonian -> Parameterized Magnetization

-- | Returns the intrinsic orbital magnetization of the n<i>th</i> band,
--   namely the integral of _m_(k) from (Xiao et al., 2005).
bandIntrinsicOM :: BandIndex -> Hamiltonian -> Parameterized Magnetization
nernstConductivity :: Hamiltonian -> Parameterized Double

-- | Returns a list of eigenvectors sorted by eigenvalue. The lowest energy
--   state is the first element of the returned list.
eigenstates :: Hamiltonian -> Wavevector -> Parameterized [Eigenstate]

-- | Returns a list of eigenvalues, sorted in ascending order.
eigenenergies :: Hamiltonian -> Wavevector -> Parameterized [Energy]
squareLattice :: CellGraph
hexLattice :: CellGraph
kagomeLattice :: CellGraph
kagomeRibbon :: Int -> CellGraph
ring :: Int -> CellGraph

-- | Send a tight-binding graph model to the corresponding Hamiltonian
--   matrix.
toMatrix :: Gr (Matrix (Complex Double)) (Matrix (Complex Double)) -> Matrix (Complex Double)

-- | Add nearest-neighbor hopping to a lattice model.
neighborTerm :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)

-- | Add an onsite energy term to a lattice model.
onsiteTerm :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)

-- | Add an staggered onsite term to a lattice model. Works based on the
--   integer parity of graph nodes, making it model-detail-dependent.
parityStaggeredTerm :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)

-- | Produces a representation of local magnetic moments given by site-wise
--   <a>VectorSite</a> data. Fails clumsily if applied to Scalar sites.
localMoments :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)

-- | Produces a Rashba spin-orbit coupling term for an E-field applied
--   along the <i>z</i> direction.
rashbaZ :: String -> CellGraph -> Parameterized (Wavevector -> AdjMatrix)

-- | Given a hamiltonian and a set of parameters, plot a real-valued
--   function over the Brillouin zone. For a Berry curvature plot,
--   <i>e.g.</i>,
--   
--   <pre>
--   bzPlot (kagomeAF, defaultParams) (bandCurvature 0)
--   </pre>
--   
--   The output string is suitable for gnuplot, unless that string is
--   reporting an error from the calculation.
bzPlot :: (Parameterized Hamiltonian, Parameters) -> (Hamiltonian -> Wavevector -> Parameterized Double) -> String

-- | Given a hamiltonian and a set of parameters, plot a real-valued
--   function over some range of a parameter. For a Chern number plot over
--   the hopping parameter, <i>e.g.</i>,
--   
--   <pre>
--   paramPlot (kagomeAF, defaultParams) (chern 1) ("t", [1.0, 1.1 .. 5.0])
--   </pre>
--   
--   The output string is suitable for gnuplot, unless that string is
--   reporting an error from the calculation.
paramPlot :: (Parameterized Hamiltonian, Parameters) -> (Hamiltonian -> Parameterized Double) -> (String, [Double]) -> String

-- | Given a hamiltonian and a set of parameters, plot the bands over a
--   path anchored by the provided wavevectors. For instance,
--   
--   <pre>
--   gamma  = vector [0.0 ,  0.0]
--   point1 = vector [0.5 ,  1.0]
--   point2 = vector [0.5 , -1.0]
--   bandPlot (kagomeAF, defaultParams) [gamma, point1, point2, gamma]
--   </pre>
--   
--   The output string is suitable for gnuplot, unless that string is
--   reporting an error from the calculation.
bandPlot :: (Parameterized Hamiltonian, Parameters) -> [Wavevector] -> String

-- | Given a list of points in <i>k</i>-space, return a list of points that
--   interpolates affine paths between them, in turn; a typical usage case
--   might be
--   
--   <pre>
--   kPath [gammaPoint, kPoint, mPoint, gammaPoint]
--   </pre>
--   
--   which is used in the <a>bandPlot</a> function. The spacing between
--   points on the interpolated path is determined by the
--   <a>meshingData</a> parameter.
kPath :: [Wavevector] -> Parameterized ([Wavevector])

module TBit.Systems.KagomeLattice

-- | The default set of scalar parameters is:
--   
--   <ul>
--   <li>"t" = 1, the hopping parameter</li>
--   <li>"tSO" = 1, the intrinsic spin-orbit coupling</li>
--   <li><a>J</a> = 1, the Heisenberg exchange parameter</li>
--   </ul>
--   
--   The default vector parameters are the d-orbital local moments on the
--   three sites. Each of them takes the form: (-cos theta, -sin theta, 0)
--   where theta is:
--   
--   <ul>
--   <li>"d0" : theta = pi/2</li>
--   <li>"d1" : theta = pi<i>2 + 2pi</i>3</li>
--   <li>"d2" : theta = pi<i>2 + 4pi</i>3</li>
--   </ul>
--   
--   These can be changed by using <a>parameters</a> to set all of them
--   explicitly.
defaultParams :: Parameters

-- | Set the named parameters to their given complex values. This function
--   is used to implement <a>defaultParams</a> as
--   
--   <pre>
--   defaultParams = parameters [ ("t"  , 1.0 :+ 0.0)
--                              , ("tSO", 0.2 :+ 0.0)
--                              , ("J" ,  1.7 :+ 0.0) ]
--                              [ ("d0" , n21 )
--                              , ("d1" , n02 )
--                              , ("d2" , n10 ) ]
--      where n10 = negate $ fromList [ cos ang01 , sin ang01 , 0.0 ]
--            n21 = negate $ fromList [ cos ang12 , sin ang12 , 0.0 ]
--            n02 = negate $ fromList [ cos ang20 , sin ang20 , 0.0 ]
--            ang01 = pi/2.0 + 4.0*pi/3.0
--            ang12 = pi/2.0
--            ang20 = pi/2.0 + 2.0*pi/3.0
--   </pre>
--   
--   but you can use it to generate your own parameter list. For more
--   advanced manipulation, like setting the mesh size or the primitive
--   lattice vectors, you'll have to constuct a <a>Parameters</a> type
--   explicitly.
parameters :: [(String, Complex Double)] -> [(String, Vector (Complex Double))] -> Parameters

-- | The kagomé hamiltonian provided here includes nearest-neighbor
--   hopping, noncollinear AF order due to localized d-orbital moments, and
--   spin-orbit coupling which breaks mirror symmetry.
kagomeAF :: Parameterized Hamiltonian

module TBit.Systems.HoneycombLattice

-- | The default set of scalar parameters is:
--   
--   <ul>
--   <li>"t" = 1, the hopping parameter</li>
--   <li>"soc" = 1, the intrinsic spin-orbit coupling</li>
--   <li>"r" = 1, the Rashba spin-orbit coupling</li>
--   <li>"v" = 1, the staggered on-site energy</li>
--   <li>"hz" = 1, the out-of-plane AF parameter</li>
--   </ul>
--   
--   These can be changed by using <a>parameters</a> to set all of them
--   explicitly.
defaultParams :: Parameters

-- | Exported directly from a Mathematica and hard-coded into this module.
--   Uses the exact conventions of Kane Mele, excep that the Gamma_15 term
--   also includes a constant value for AF order. This AF order is taken in
--   the large Hubbard U limit by construction.
kaneMele :: Parameterized Hamiltonian

-- | Set the named parameters to their given complex values. This function
--   is used to implement <a>defaultParams</a> as
--   
--   <pre>
--   defaultParams = parameters [ ("t"  , 1.0 :+ 0.0)
--                              , ("soc", 1.0 :+ 0.0)
--                              , ("r"  , 1.0 :+ 0.0)
--                              , ("v"  , 1.0 :+ 0.0)
--                              , ("hz" , 1.0 :+ 0.0) ]
--   </pre>
--   
--   but you can use it to generate your own parameter list. For more
--   advanced manipulation, like setting the mesh size or the primitive
--   lattice vectors, you'll have to constuct a <a>Parameters</a> type
--   explicitly.
parameters :: [(String, Complex Double)] -> Parameters

module TBit.Systems.SquareLattice
parameters :: Parameters
hgteHamiltonian :: Parameterized Hamiltonian


-- | Provide routines for determining the spillage, and in particular
--   Vanderbilt and Liu's spin-orbit spillage, given a Hamiltonian whose
--   spin-orbit coupling term can be turned on and off.
module TBit.Topological.Spillage
spillage :: String -> Filling -> Parameterized Hamiltonian -> Wavevector -> Parameterized Double

module TBit.Hamiltonian.Builder.PrimitiveLattice

-- | Determine a primitive lattice for a given <a>CellGraph</a>.
--   
--   This is currently accomplished by determining the diameter of the
--   thegraph, collecting all non-zero displacements from an arbitary site
--   to itself which are within a diameter's worth of NN hopping, and
--   returning a maximal linearly independent subset of these with a
--   preference for vectors with smaller L2 norms.
--   
--   For finite nanoribbons such as those generated by <a>decompactify</a>,
--   the graph diameter can be quite large. This means that finding the
--   primitive lattice vectors as described above can become unreasonably
--   slow. In the future, we will label decompactified lattice vectors in
--   the CellGraph so that <a>graphDiameter</a> will understand not to
--   count them.
primLattice :: [LEdge Displacement] -> CellGraph -> Lattice

-- | Sets the <a>latticeData</a> field of the <a>Parameters</a> state
--   according to a <a>primLattice</a>.
setPrimLattice :: CellGraph -> Parameterizable CellGraph

-- | Delete a list of <a>LEdge</a>s from a graph.
delLEdges :: (Eq b, DynGraph gr) => [LEdge b] -> gr a b -> gr a b

-- | Replicate a <a>LEdge</a> n times, each time increasing the in and out
--   nodes by m. (n is the first argument, m the second, somewhat
--   stupidly.)
replicateE :: Int -> Int -> LEdge Displacement -> [LEdge Displacement]

-- | Replicate a <a>CellGraph</a> n times, each time increasing the in and
--   out nodes by the number of nodes in the <a>CellGraph</a>.
replicateG :: Int -> CellGraph -> CellGraph

module TBit.Hamiltonian.Builder.Decompactification

-- | Perform so-called "truncated decompactification" on a
--   <a>CellGraph</a>.
--   
--   Since the neighbor-data is stored in a unit-cell-level graph, it's in
--   a sense "compact", i.e. it's a local periodic structure instead of an
--   extended (to infinity) structure. Truncated decompactification sends
--   the periodic structure (on T^2, roughly speaking) back to something of
--   infinite extent (i.e. the integers), but then truncates the result to
--   keep only a finite subset (i.e. the ribbon-width).
--   
--   It may not be clear <i>a priori</i> how to choose the edge you want to
--   <a>decompactify</a> on to get the desired edge configuration; for
--   honeycomb, you can show on paper that decompactifying on a single
--   graph edge (there are three, corresponding to the three nearest
--   neighbors of a site) gives you zig-zag edge, while decompactifying on
--   two graph edges gives you an armchair configuration. The square
--   lattice is even more straightforward.
decompactify :: Int -> LEdge Displacement -> CellGraph -> Parameterizable CellGraph