Added CoordinateVector to represent coordinates in real/reciprocal space

CHANGELOG.md

@@ -11,12 +11,20 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   - `StateDensity{T}` type which combines `EnergyOccupancy{T}` with a density of states value at the
 energy provided.
   - `ByCoordinate` traits: `ByCartesianCoordinate` and `ByFractionalCoordinate`.
-  - `ShiftVector{S,D,T} <: StaticVector{D,T}` type describing the shift of a lattice or data defined
-on it with respect to the origin, along with an optional weight parameter.
+  - `ShiftVector{S,D,T} <: AbstractCoordinateVector{S,ByFractionalCoordinate,D,T}`, representing a
+potentially weighted vector which shifts a data grid.
   - `require_same_space`, `require_dual_space`, and `require_same_coordinate` functions for checking
 whether `BySpace` and `ByCoordinate` traits are compatible in an operation.
+  - `AbstractCoordinateVector{S<:Electrum.BySpace,C<:Electrum.ByCoordinate,D,T}` type for coordinate
+vectors in real or reciprocal space with either fractional or Cartesian coordinates.
+  - `CoordinateVector{S,C,D,T}` and aliases:
+      + `RealCartesianCoordinate`
+      + `RealFractionalCoordinate`
+      + `ReciprocalCartesianCoordinate`
+      + `ReciprocalFractionalCoordinate`
 
 ### Changed
+  - [BREAKING] `KPoint{D}` is now `KPoint{D,T}`, equivalent to `ShiftVector{ByReciprocalSpace,D,T}`.
   - `BySpace` traits are now part of the public API.
   - `BySpace{D}` and its subtypes have lost their dimension type parameter.
 

docs/make.jl

@@ -15,7 +15,7 @@ makedocs(
     warnonly = is_ci_env,
     pages = [
         "Home" => "index.md",
-        "Lattices" => "lattices.md",
+        "Geometry" => "geometry.md",
         "Atoms and crystals" => "atoms.md",
         "Data grids" => "grids.md",
         "File formats" => "filetypes.md",

docs/src/api/geometry.md

@@ -39,8 +39,13 @@ eachvertex
 maxHKLindex
 ```
 
-## Shift vectors
+## Coordinate vectors
 ```@docs
+CoordinateVector
+RealCartesianCoordinate
+RealFractionalCoordinate
+ReciprocalCartesianCoordinate
+ReciprocalFractionalCoordinate
 ShiftVector
 KPoint
 weight

docs/src/lattices.md → docs/src/geometry.md

@@ -1,17 +1,103 @@
-# Lattices
+# Geometry
 
 The starting point for solid state structures is a periodic lattice. Electrum provides convenient
 types and functions for working with lattices of arbitrary dimension, not just three dimensions. 
 
-## Real and reciprocal space traits
+## Traits
+
+Julia parametric types can be used to encode information about data types that are wrapped by a
+new composite type: for instance, Julia's `Array{T,D}` type includes information about the types of
+the elements in the type parameter `T`. However, type parameters can be used as tags that provide
+additional information about data types without relying on inheritance from another abstract type.
+One example of this is `Ptr{T}`: although a pointer is underlyingly a `UInt`, the type parameter
+encodes the type of data pointed at.
+
+Electrum uses several traits to encode information about numerical data, particularly vectors. If a
+user is given an instance of `SVector{3,Float64}`, the data type itself does not encode important
+information, like whether the data corresponds to a real or reciprocal space coordinate, or whether
+the coordinates are fractional coordinate or Cartesian coordinates. Electrum's data types use these
+traits in their declarations to convey this extra information.
+
+### Conventions
+
+Trait types are declared as singleton structs (no fields). If more information needs to be encoded,
+use a type parameter. The names of traits generally tend to start with `By`.
+
+If creating a new data type that uses one of the traits mentioned below, use the type itself as a
+parameter, not the singleton instance.
+
+### Real and reciprocal space
 
 The `BySpace` supertype contains two types, `ByRealSpace` and `ByReciprocalSpace`. These types are 
 used to denote whether data is associated with real space (e.g. electron density) or reciprocal 
 space (e.g. the Fourier transform of the electron density). When working with lattices, it is 
 important to distinguish the two types of lattice: this is the primary reason why bare
 `SMatrix{D,D,T}` instances are not used in this package.
 
-## `Electrum.LatticeBasis` and methods
+The units associated with data bearing the `Electrum.ByRealSpace` trait are bohr or powers of bohr,
+whereas those associated with `Electrum.ByReciprocalSpace` are rad bohr⁻¹ or powers thereof.
+
+```@docs; canonical=false
+Electrum.BySpace
+Electrum.ByRealSpace
+Electrum.ByReciprocalSpace
+```
+
+### Coordinate system
+
+The `Electrum.ByCoordinate{D}` supertype contains `Electrum.ByCartesianCoordinate{D}` and
+`Electrum.ByFractionalCoordinate{D}`, corresponding to Cartesian or fractional coordinates in `D`
+dimensions.
+
+```@docs; canonical=false
+Electrum.ByCoordinate
+Electrum.ByCartesianCoordinate
+Electrum.ByFractionalCoordinate
+```
+
+## Coordinate vectors
+
+The traits above can be incorporated into new coordinate types that wrap a `SVector{D,T<:Real}`, and
+retain information about what type of information is being stored by the coordinate.
+
+### `CoordinateVector`
+
+The `CoordinateVector{S,C,D,T}` type is the primary data type for working with spatial coordinates.
+The `RealCartesianCoordinate`, `RealFractionalCoordinate`, `ReciprocalCartesianCoordinate`, and
+`ReciprocalFractionalCoordinate` aliases correspond to the four possible combinations of `S` and `C`
+type parameters, and are preferred for interactive use.
+
+This type behaves almost identically to `SVector{D,T}`, but forbids nonsenical operations between
+data types: for instance, adding a `RealCartesianCoordinate` to a `ReciprocalCartesianCoordinate`.
+
+```@docs; canonical=false
+CoordinateVector
+RealCartesianCoordinate
+RealFractionalCoordinate
+ReciprocalCartesianCoordinate
+ReciprocalFractionalCoordinate
+```
+
+### `ShiftVector`
+
+A `ShiftVector` is almost identical to a `CoordinateVector`, and wraps one as a field, but includes
+a weight parameter that defaults to 1.
+
+The primary use for `ShiftVector` is to provide information about how data associated with a lattice
+is shifted with respect to the origin. In particular, it forms the implementation of `KPoint{D,T}`,
+which is simply an alias for `ShiftVector{ByReciprocalSpace,D,T}`. In many cases, lists of k-points
+are symmetry-reduced, and the weight parameter is used to account for coordinates not present in the
+list due to symmetry reduction.
+
+To retain the 
+
+```@docs; canonical=false
+ShiftVector
+KPoint
+weight
+```
+
+## Lattices
 
 The `Electrum.LatticeBasis{S<:BySpace,D,T}` data type is a wrapper for an
 `SMatrix{D,D,T,D^2}` which represents the real or reciprocal space basis vectors of a lattice.

src/Electrum.jl

@@ -105,6 +105,27 @@ Computes the dot product of a vector with itself.
 """
 _selfdot(v) = dot(v,v)
 
+"""
+    Electrum.promote_typeof(args...)
+
+Calls `promote_type()` on the types of the arguments, equivalent to `promote_type(typeof.(x)...)`.
+
+This function is implemented in Julia Base, but it is not part of the public API; a stable
+implementation is provided here.
+"""
+promote_typeof(x...) = promote_type(typeof.(x)...)
+
+"""
+    Electrum.promote_eltype(args...)
+
+Calls `promote_type()` on the element types of the arguments, equivalent to 
+`promote_type(eltype.(x)...)`.
+
+This function is implemented in Julia Base, but it is not part of the public API; a stable
+implementation is provided here.
+"""
+promote_eltype(x...) = promote_type(eltype.(x)...)
+
 # Methods used in array operations that go beyond what's available in LinearAlgebra
 include("math.jl")
 export FFTBins, FFTLength
@@ -118,7 +139,8 @@ export RealBasis, ReciprocalBasis, AbstractBasis
 export eachvertex, basis, dual, dualbasis, lengths, volume, angles_cos, angles_rad, angles_deg, 
     gram, isdiag, qr, triangularize, maxHKLindex
 include("vectors.jl")
-export ShiftVector, KPoint
+export CoordinateVector, RealCartesianCoordinate, RealFractionalCoordinate, 
+    ReciprocalCartesianCoordinate, ReciprocalFractionalCoordinate, ShiftVector, KPoint
 export weight
 # Methods and structs for working with atomic positions
 include("atoms.jl")