pythtb.WFArray.links

WFArray.links(axis_idx=None, state_idx=None)

Compute unitary link matrices for specified axis directions.

For each mesh direction \(\mu\) in axis_idx, this routine computes the parallel-transport unitary (“link”) between the states at each point \(\boldsymbol{\kappa}\) and its nearest forward neighbor \(\boldsymbol{\kappa} + \hat{\mu}\).

First define the overlap matrix:

\[M_{\mu}(\boldsymbol{\kappa})_{mn} = \langle u_{m}(\boldsymbol{\kappa}) \mid u_{n}(\boldsymbol{\kappa} + \hat{\mu}) \rangle.\]

where \(m,n\) index the selected states in state_idx.

The unitary link is then obtained by taking the unitary factor of this overlap matrix:

\[U_{\mu}(\boldsymbol{\kappa}) \;\equiv\; \mathcal{U}\, \big[M_{\mu}(\boldsymbol{\kappa})\big],\]

Here \(\mathcal{U}[\cdot]\) denotes the unitary part of the matrix, i.e. the unitary factor in a matrix-factorization of \(M_{\mu}(\boldsymbol{\kappa})\). In practice this is obtained from the singular-value decomposition (see Notes).

Added in version 2.0.0.

Parameters:

axis_idxint or array_like of int, optional

List of Mesh axes along which to compute the links. If not provided, links will be computed for all directions in the mesh.

state_idxint or array_like of int, optional

Index or indices of the states for which to compute the links. If an integer is provided, only that state will be considered. If a list is provided, links for all specified states will be computed. If not provided, links will be computed for all states.

Returns:

U_forwardnp.ndarray

Array of unitary links. The leading dimension indexes the chosen axis_idx directions (or all axes if axis_idx is None). The trailing two dimensions are the matrix indices in band space.

Shape:

(ndirs, *mesh_shape, n_states, n_states)

where ndirs = len(axis_idx) (or WFArray.naxes by default).

See also

berry_connection(), berry_phase(), berry_flux()

wilson_loop()

Notes

• This is the primitive building block for berry_connection(), berry_phase(), berry_flux(), and wilson_loop() functions.

• The unitary link is construced from the singular value decomposition of the overlap matrix,

  \[M_{\mu} = V_{\mu}\,\Sigma_{\mu}\,W_{\mu}^{\dagger},\]

  as,

  \[\mathcal{U} \big[ M_{\mu}(\boldsymbol{\kappa}) \big] \equiv V_{\mu} W_{\mu}^\dagger\]

  This is equivalent to taking the unitary factor in the polar decomposition.

  \[\begin{split}M_{\mu} = U_{\mu}\,H_{\mu}, \qquad H_{\mu} = \bigl(M_{\mu}^{\dagger} M_{\mu}\bigr)^{1/2}, \\ \Rightarrow\quad \mathcal{U}[M_{\mu}] \equiv U_{\mu} = M_{\mu}\bigl(M_{\mu}^{\dagger} M_{\mu}\bigr)^{-1/2}.\end{split}\]

• Boundary behavior follows the Mesh axis type:

  • Periodic (no endpoint)

    The final point wraps to the first (looped). All entries are meaningful.

  • Periodic with endpoint included

    The endpoint is explicitly included in the mesh. No wrap is applied; the final forward link is undefined and is filled with NaN. Discard the final slice along that axis.

  • Nonperiodic (open directions)

    No physical forward neighbor exists at the boundary. Forward links there are filled with NaN to keep the shape consistent. These values are not physically meaningful and should be dropped.

  These conventions match those used internally by wilson_loop(), berry_phase(), and related routines, which automatically trim invalid points.