WannierIO.jl

Appearance

Tight-binding models ​

API reference for tight-binding reduction and storage helpers.

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

R-vector reducers ​

Reducers that absorb R-degeneracy (and optional MDRS corrections) into operator definitions.

WannierIO.AbstractRvectorReducer Type

Simplify the R-vectors of a tight-binding operator, such that the inverse Fourier transform is a simple sum (and is faster).

source
WannierIO.MdrsRvectorReducer Type

MDRS R-vector reducer, which simplifies the R-vectors by absorbing the R degeneracies, T vectors and degeneracies into the operator.

This expands the R-vectors to a new set of R-vectors R̃ = R + T, where T is the translation vectors; also divide the operator by the degeneracies of R and T vectors.

julia
struct MdrsRvectorReducer <: WannierIO.AbstractRvectorReducer

Fields

  • Rvectors: The new R vectors.

  • mapping: The contribution mapping from new R vectors to original operator entries. mapping[iR] is a vector of (iR0, m, n) tuples, where each tuple means one MDRS contribution from operator[iR0][m, n] to the new iR-th R vector.

  • degens: The combined R and T degeneracies of the original R vectors. degens[iR0] (iR0 ∈ iR0s) gives the degeneracy matrices of the original iR0-th R vector by combining the original Rdegens and the Tdegens of the T vectors. The operator[iR0] will be divided by degens[iR0] to absorb the degeneracies.

source
WannierIO.WsRvectorReducer Type

Wigner-Seitz R-vector reducer, which simplifies the R-vectors by absorbing the R degeneracies into the operator.

The R-vectors are still the same, the operator will be divided by the R-vector degeneracy.

julia
struct WsRvectorReducer <: WannierIO.AbstractRvectorReducer

Fields

  • Rvectors: The new R vectors (same as the original R vectors).

  • degens: The R degeneracies of the (original) R vectors. degens[iR] gives the degeneracy of the (original) iR-th R vector. The original operator[iR] is divided by degens[iR] to absorb the degeneracy.

source
WannierIO.RvectorReducer Function

Reduce the R-vectors of a tight-binding operator by absorbing the R degeneracies (and T vectors & degeneracies, if provided) into the operator.

This is a general interface for R-vector reduction, which can be implemented for different input argument types.

source

Tight-binding operators ​

High-level TB API and conversions.

WannierIO.read_w90_tb Function
julia
read_w90_tb(file)

Read Wannier90 prefix_tb.dat (and optional matching prefix_wsvec.dat).

The Rvectors and degeneracies will be reduced by RvectorReducer automatically, resulting in a OperatorPack with just the Rvectors and the operator matrices defined on them.

If a corresponding wsvec.dat file is found, the MDRS Tvectors and degeneracies will also be reduced automatically.

As a consequence, the Wannier interpolation will be just a simple inverse Fourier transform without any complications from R-degeneracies or MDRS T vectors and degeneracies.

See also read_w90_tb_dat and read_w90_wsvec for reading just the prefix_tb.dat and prefix_wsvec.dat files without any reduction.

This high-level API is intentionally for native Wannier90 text files only. For HDF5/JLD2/Zarr backends, use read_operator.

source
WannierIO.write_w90_tb Function
julia
write_w90_tb(file, tbdat)
write_w90_tb(file, tbdat, wsvec)

Write Wannier90 tight-binding text data.

This high-level API is intentionally for native Wannier90 text files only. For HDF5/JLD2/Zarr backends, use write_operator.

For W90Dat:

  • write_w90_tb(file, tbdat, W90Dat()) writes only prefix_tb.dat.

  • write_w90_tb(file, tbdat, wsvec, W90Dat()) writes both prefix_tb.dat and prefix_wsvec.dat.

source

Hamiltonian operators ​

High-level HR API and conversions.

WannierIO.read_w90_hr Method
julia
read_w90_hr(file)

Read Wannier90 prefix_hr.dat (and optional matching prefix_wsvec.dat).

The Rvectors and degeneracies will be reduced by RvectorReducer automatically, resulting in a OperatorPack with just the Rvectors and the H operator matrices defined on them.

If a corresponding wsvec.dat file is found, the MDRS Tvectors and degeneracies will also be reduced automatically.

Because prefix_hr.dat does not store lattice vectors, the returned OperatorPack uses a 3×3 lattice filled with NaN as a sentinel for "lattice unavailable".

As a consequence, the Wannier interpolation will be just a simple inverse Fourier transform without any complications from R-degeneracies or MDRS T vectors and degeneracies.

See also read_w90_hr_dat and read_w90_wsvec for reading just the prefix_hr.dat and prefix_wsvec.dat files without any reduction.

This high-level API is intentionally for native Wannier90 text files only. For HDF5/JLD2/Zarr backends, use read_operator.

source
WannierIO.write_w90_hr Function
julia
write_w90_hr(file, hrdat)
write_w90_hr(file, hrdat, wsvec)

Write Wannier90 Hamiltonian text data.

This high-level API is intentionally for native Wannier90 text files only. For HDF5/JLD2/Zarr backends, use write_operator.

For W90Dat:

  • write_w90_hr(file, hrdat) writes only prefix_hr.dat.

  • write_w90_hr(file, hrdat, wsvec) writes both prefix_hr.dat and prefix_wsvec.dat.

source

Operator containers ​

Container types and conversions for generic operator storage.

WannierIO.OperatorPack Type

Series of operators with dense matrix storage.

The operators should have been simplified by WsRvectorReducer or MdrsRvectorReducer, i.e., no Rdegens or Tvectors.

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 vectors of dense matrices. The operators can be either real or complex.

  • n_Rvecs: Number of R-vectors.

  • n_wann: Number of Wannier functions.

source
WannierIO.pack Function

Pack tight-binding operators into an OperatorPack struct.

e.g., from TbDat and WsvecDat structs to OperatorPack.

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 length-L vector of N × N sparse matrices into one struct with concatenated nonzero values and indices.

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.

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.

  • n_Rvecs: Number of R-vectors.

  • n_wann: Number of Wannier functions.

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 matrix as a SparseMatrixCSC.

source
Base.length Method

Number of packed matrices.

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.matrix_order Method

Size N of each N × N inner matrix.

source
WannierIO.sparsify Function
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: a vector of n_wann × n_wann matrices representing the operator at different R-vectors.

Keyword Arguments

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

Pack a set of Wannier90 operators into sparse CSC matrices suitable for storage in HDF5, JLD2, or Zarr.

See densify for the inverse.

source

Page index ​