WannierIO.jl

Appearance

Tight-binding models ​

API reference for the tight-binding operator container and its storage.

For a narrative introduction and examples, see Tight-binding operators and Sparse storage.

Operator containers ​

Container types and conversions for generic operator storage.

WannierIO.OperatorPack Type

Named Wannier operators on a common set of R-vectors, with dense storage.

An OperatorPack is a storage container: it checks shapes, but holds no physics. Each operator is an array O[m, n, components..., iR] of n_wann × n_wann × component dimensions × n_Rvecs, e.g. a Hamiltonian n_wann × n_wann × n_Rvecs or a vector operator n_wann × n_wann × 3 × n_Rvecs. The R-vectors are unique and carry no degeneracy weights, so an operator at a kpoint is the plain sum   (k and R fractional). Wigner–Seitz degeneracies and minimum-distance replicas of Wannier90 tb.dat/wsvec.dat files must have been absorbed before packing, e.g. by Wannier.jl's OperatorPack(::TightBindingModel).

The operator names are free-form strings; the dense layout is preserved by sparsify/densify and by write_operator/ read_operator.

Fields

  • header: Short description of the operator set

  • lattice: Lattice vectors as columns of a 3×3 matrix, in Å.

  • Rvectors: R-vectors as a vector of 3-component integer vectors.

  • operators: Mapping operator names to dense n_wann × n_wann × … × n_Rvecs arrays. The operators can be either real or complex.

source
WannierIO.read_operator Function
julia
read_operator(file, format)
read_operator(file)

Read operators from a backend storage format (HDF5/JLD2/Zarr) and return an OperatorPack.

When called without a format argument, the format is inferred from the file extension via detect_operator_format.

source
WannierIO.write_operator Function
julia
write_operator(file, pack, format; kwargs...)
write_operator(file, pack; kwargs...)

Write an operator pack to a backend storage format (HDF5/JLD2/Zarr).

When called without a format argument, the format is inferred from the file extension via detect_operator_format.

source

Sparse representation ​

Sparse containers and conversion routines (sparsify, densify).

WannierIO.CscPack Type

Pack a series of CSC matrices into a compact representation.

julia
struct CscPack{Tv<:Number, Ti<:Integer}

This packs a dense N × N × … array, whose leading two axes are the matrix axes, into one struct with concatenated nonzero values and indices. The axes after the two matrix axes (components, R-vectors) are flattened in column-major order into L matrices; each N × N matrix is stored in compressed sparse column (CSC) format, and the L matrices are concatenated along the nonzero dimension.

For example, N = 3 and L = 2 (dims = [3, 3, 2]):

text
       l = 1             l = 2
    [ a  .  . ]       [ .  e  . ]
    [ .  .  b ]       [ .  .  . ]
    [ c  .  d ]       [ .  .  f ]

             |<---- l = 1 -->|<l = 2>|
  index      1   2   3   4   5   6   7
  nzval  = [ a   c   b   d   e   f ]
  rowval = [ 1   3   2   3   1   3 ]
  nzptr  = [ 1               5       7 ]

            l=1 l=2
  colptr = [ 1   1 ]    column j of matrix l is the local range
           [ 3   1 ]    colptr[j, l] : colptr[j+1, l] - 1, i.e. the
           [ 3   2 ]    indices nzptr[l] - 1 .+ (that range) of
           [ 5   3 ]    rowval and nzval

Fields

  • nzptr: 1-based offsets into concatenated nonzero buffers for each matrix. Length is L + 1, and nzptr[l]:nzptr[l+1]-1 are the entries of the l-th matrix in rowval and nzval.

  • colptr: CSC column pointer table for each packed matrix. Size is (N + 1, L), and colptr[:, l] is the column pointer of the l-th matrix.

  • rowval: Concatenated row indices of all nonzeros. Length is the total number of nonzeros across all matrices.

  • nzval: Concatenated nonzero values of all matrices. Length is the total number of nonzeros across all matrices.

  • dims: Dimensions of the dense array, [N, N, trailing...], in column-major (Julia) order, e.g. [n_wann, n_wann, n_Rvecs] or [n_wann, n_wann, 3, n_Rvecs]. The product of the trailing dimensions is L.

source
WannierIO.CscPack Method
julia
CscPack{Tv, Ti}(mats, dims = [N, N, length(mats)])

Pack the sparse N × N matrices mats, the column-major flattening of a dense array of dimensions dims.

source
WannierIO.SparseOperatorPack Type

Series of operators with sparse CSC storage.

Fields

  • header: Short description of the operator set

  • lattice: Lattice vectors as columns of a 3×3 matrix, in Å.

  • Rvectors: R-vectors as columns of a 3 × n_Rvecs matrix, integers.

  • operators: Mapping operator names to sparse packs.

source
WannierIO.SparseOption Type

Control sparsification behavior.

Fields

  • atol: Absolute tolerance for treating values as zero. Must be nonnegative. Elements with abs(real(v)) < atol and abs(imag(v)) < atol are dropped.

  • index_type: Integer type for storing row and column indices in sparse matrices.

  • value_type: Numeric type for storing nonzero values in sparse matrices. Can be real or complex. If real, will attempt to convert complex values to real if all imaginary parts are smaller than atol.

source
Base.getindex Method

Return the l-th packed matrix as a SparseMatrixCSC with p[:, :, l]; l is the column-major linear index over the trailing dimensions.

source
Base.length Method

Number of packed matrices L.

source
Base.size Method

Size of the dense array, (N, N, trailing...).

source
WannierIO._chunk_shape Method
julia
_chunk_shape(data)

Return a conservative HDF5/Zarr chunk shape.

For 1D arrays, cap the chunk at _MAX_CHUNK_ELEMS_1D elements. For 2D arrays, cap each edge at _MAX_CHUNK_EDGE_2D, i.e. at most _MAX_CHUNK_EDGE_2D^2 == _MAX_CHUNK_ELEMS_1D elements per chunk.

source
WannierIO._force_value_type Method
julia
_force_value_type(operator_eltype, value_type)

Return the sparse storage element type for an operator with element type operator_eltype and requested precision value_type.

source
WannierIO.densify Method
julia
densify(pack; value_type)

Reconstruct dense matrices from sparse CSC matrices produced by sparsify.

Set value_type to force conversion. Use nothing to preserve stored type.

source
WannierIO.densify Method
julia
densify(pack; value_type)

Reconstruct dense operators from a sparse CSC pack produced by sparsify.

source
WannierIO.is_almost_real Method

Check if the imaginary part is negligible compared to atol.

source
WannierIO.sparsify Function
julia
sparsify(pack)
sparsify(pack, opt)

Convert the operators of an OperatorPack to sparse CSC matrices suitable for storage in HDF5, JLD2, or Zarr.

See densify for the inverse.

source
WannierIO.sparsify Method
julia
sparsify(op)
sparsify(op, opt)

Convert an operator to sparse CSC representation.

Only entries with abs(real(v)) >= atol || abs(imag(v)) >= atol are stored.

See densify for the inverse.

Arguments

  • op: an n_wann × n_wann × … × n_Rvecs array, the operator at the R-vectors, with any component axes between the matrix axes and the R axis

  • opt: a SparseOption

source

Page index ​