Python API#

Each of the following sections describes the usage of different modules in the kpm_tools package.

Bloch Module#

Handle systems with periodic boundary conditions.

‘wraparound_by_parts’ is reworked from ~kwant.wraparound, specially MR !363.

kpm_tools.bloch.separate_bloch_components(builder)[source]#

Construct two systems: the supercell onsite and supercell hopping.

kpm_tools.bloch.wrap_distance(builder)[source]#

Construct distance operators with translational symmetries.

The system has a single parameter ‘direction’ that should be a unit lenght vector in real space, of the dimensions of the site positions.

The method ‘hamiltonian_submatrix’ produces the distance operator matrix in the ‘direction’ specified.

Note that this matrix is independent of the value that takes the Hamiltonian of the original system, and does not depends on the paramters of the original system, the ‘builder’.

kpm_tools.bloch.wrap_velocity(builder)[source]#

Construct velocity operators with translational symmetries.

The system has an extra parameter ‘direction’ that should be a unit lenght vector in real space, of the dimensions of the site positions.

The method ‘hamiltonian_submatrix’ produces the velocity operator matrix in the ‘direction’ specified.

Note that this matrix depends on the value that takes the Hamiltonian of the original system, the ‘builder’.

kpm_tools.bloch.wraparound_by_parts(builder, keep=None, *, coordinate_names='xyz', separate_sites=False)[source]#

Replace translational symmetries by momentum parameters.

A new Builder instance is returned. By default, each symmetry is replaced by one scalar momentum parameter that is appended to the already existing arguments of the system. Optionally, one symmetry may be kept by using the keep argument. The momentum parameters will have names like ‘k_n’ where the ‘n’ are specified by ‘coordinate_names’.

Parameters:

  • builder (~kwant.builder.Builder) – Kwant builder with translational symmetries.

  • keep (int, optional) – Which (if any) translational symmetry to keep.

  • coordinate_names (sequence of strings, default: 'xyz') – The names of the coordinates along the symmetry directions of ‘builder’.

  • separate_sites (bool, default to 'False') – Wheather to construct a new system without the hoppings that cross the fundamental domain of the translational symmetry. If ‘True’ return the system contained inside the fundamental domain, a dictionary of wrapped sites and a dictionary of wrapped hoppings.

Notes

Wraparound is stop-gap functionality until Kwant 2.x which will include support for higher-dimension translational symmetry in the low-level system format. It will be deprecated in the 2.0 release of Kwant.

Common Module#

Utils.

kpm_tools.common.expectation_value(vectors, operator)[source]#

Braket ‘operator’ with ‘vectors’.

‘vectors’ must have t1he last axis as the dimension to be multiplied by ‘operator’

kpm_tools.common.identity_operator(x)[source]#

Return argument.

kpm_tools.common.local_expectation_value(vector, operator, norbs=2)[source]#

Trace over sites.

kpm_tools.common.position_operator(syst, pos_transform=None)[source]#

Return a list of position operators as ‘csr’ matrices.

kpm_tools.common.standard_gaussian(label, salt, s1, s2=None)[source]#

Return a gaussian distribution.

kpm_tools.common.trace_orbs(array, norbs=4, axis=-1)[source]#

Return the trace per unit-cell.

‘array’ has a length ‘num_sites * norbs’ over the ‘axis’, and the return array has a length ‘num_sites’ over the same axis.

kpm_tools.common.trace_unit_cell(sites, array)[source]#

Trace the array assuming it has the values per orbital per site.

If value_per_orbital_per_site

kpm_tools.common.transparent_cmap(cmap=None, alpha='linear')[source]#

Add transparency to a matplotlib ListedColormap.

Parameters:

  • cmap (instance of matplotlib.pylab.cm, optional) – The colormap to use.

  • alpha ('linear', float or array of floats) – If ‘alpha’ is a float or array of floats, this will be the transparency value. If it is ‘linear’ the transparency will decrease from ‘1’ to ‘0’.

kpm_tools.common.uniform(label, salt, s1, s2=None)[source]#

Return a uniform distribution in the interval ‘[-0.5, 0.5)’.

Evolution Module#

Evolution in time with a KPM expansion. (c) Pablo Piskunow 2021.

Evolve an initial vector to arbitrary chosen points in time (not necessarily small intervals), and compute expectation values of observables.

kpm_tools.evolution.coef_evo(m, e, ab, delta_time)[source]#

Return the coefficients of the time evolution operator.

The ‘delta_time’ parameter must be the real time, and will be rescaled with respect to the bounds of the spectrum.

The parameter ‘e’ is to conform with the signatures, but it is a dummy parameter, as the time evolution of a vector only depends on the Hamiltonian and the vector.

kpm_tools.evolution.evolve_observable(syst, time_steps, operator=None, vectors=None, accuracy=1e-16, save_intermediate=True, **kwargs)[source]#

Evolve an observable in time using time steps.

Parameters:

  • syst (~kwant.system or Hamiltonian matrix) – Hamiltonian of the system, where the vectors will evolve.

  • time_steps (sequence of floats) – Discrete time steps that will be used to evolve the vectors.

  • vectors (ndarray) – Initial sequence of vectors that belong to the system.

  • operator (callable, ndarray, or sparse matrix, optional) – Any operator that can be accepted by SpectralDensityIterator.

  • accuracy (float, default to '1e-16') – Precission of each time-evolution step.

  • save_intermediate (bool, default to True) – Save intermediate vectors.

  • kwargs (dict) – Key-word arguments to be passed to ‘evolve_vectors’

kpm_tools.evolution.evolve_vectors(syst, vectors, dt=0, accuracy=1e-16, **kwargs)[source]#

Evolve vectors in time, according to a Hamiltonian.

Parameters:

  • syst (~kwant.system or Hamiltonian matrix) – Hamiltonian of the system.

  • vectors (iterable of arrays) – Vectors to be passed to ~SpectralDensityIterator.

  • dt (float) – Time in units of E/hbar, where E is the units of energy of the Hamiltonian.

  • accuracy (float, default to '1e-16') – Accuracy goal for the Chebyshev expansion.

  • kwargs (dict) – Extra keyword arguments to pass to ~SpectralDensityIterator.

kpm_tools.evolution.evolve_vectors_time_steps(syst, time_steps, vectors, save_vectors=True, accuracy=1e-16, **kwargs)[source]#

Evolve vectors in time using time steps.

Parameters:

  • syst (~kwant.system or Hamiltonian matrix) – Hamiltonian of the system, where the vectors will evolve.

  • time_steps (sequence of floats) – Discrete time steps that will be used to evolve the vectors.

  • vectors (ndarray) – Initial sequence of vectors that belong to the system.

  • save_vectors (bool, default to 'True') – Whether to save the vectors at intermediate steps, and return them.

  • accuracy (float, default to '1e-16') – Precission of each time-evolution step.

  • kwargs (dict) – Key-word arguments to be passed to ‘evolve_vectors’

Hamiltonians Module#

KPM Functions Module#

KPM Generator Module#

Main module containing iterables and generators of KPM vectors.

class kpm_tools.kpm_generator.GeneralVectorExpansion(*args, coef_function=None, **kwargs)[source]#

Bases: _BaseKPM

Inherit from ~`_BaseKPM`.

add_moments(num_moments=None, *, energy_resolution=None)[source]#

Increase the number of Chebyshev moments.

Parameters:

  • num_moments (positive int) – The number of Chebyshev moments to add. Mutually exclusive with energy_resolution.

  • energy_resolution (positive float, optional) – Features wider than this resolution are visible in the spectral density. Mutually exclusive with num_moments.

vector_iterator(e)[source]#

Return vector iterator.

class kpm_tools.kpm_generator.IteratorKPM(ham, vectors, max_moments=None, operator=None, num_threads=None)[source]#

Bases: object

Iterator of KPM vectors.

This iterator yields vectors as

T_n(H) | v >

for vectors | v > in vectors, for ‘n’ in ‘[0, max_moments]’.

Notes

Returns a sequence of expanded vectors of shape (M, N). If the input is a vector then M=1.

add_moments(num_moments=0)[source]#

Increase the maximum number of moments returned.

The iterator can now return num_moments new expanded vectors. Note that it will continue after the last vector, and not start from the beggining.

load(d)[source]#

Load internal state.

operator(vector)[source]#

Normalize operator.

save()[source]#

Save internal state, except the ‘ham’.

class kpm_tools.kpm_generator.SpectralDensityIterator(*args, **kwargs)[source]#

Bases: _BaseKPM, SpectralDensity

Inherit from ~`_BaseKPM` and ~`kwant.kpm.SpectralDensity`.

add_moments(num_moments=None, *, energy_resolution=None)[source]#

Increase the number of Chebyshev moments.

Parameters:

  • num_moments (positive int) – The number of Chebyshev moments to add. Mutually exclusive with energy_resolution.

  • energy_resolution (positive float, optional) – Features wider than this resolution are visible in the spectral density. Mutually exclusive with num_moments.

add_vectors(num_vectors=None)[source]#

Increase the number of vectors.

Parameters:

num_vectors (positive int, optional) – The number of vectors to add.

kpm_tools.kpm_generator.concatenator(hamiltonian, params=None, operator_array=None, coef_array=None, return_expansion=False, first_transpose=False, ouroboros=False, logging=False, **kwargs)[source]#

Expand a concatenation of functions and matrix operators.

Take ‘n’ functions [f_i] and ‘n+1’ operators [O_j] and expand <O_0 f_0 O_1 f_1… f_n 0_{n+1}>.

‘O_j’ is an operator acting on vectors, and [f_i] are functions defined by their coefficients on a KPM expansion.

The instance created is a function. When called it returns the expectation value for a single energy. (maybe an array of energies too)

Parameters:

  • hamiltonian (ndarray or kwant.system) – Hamiltonian or system defining a Hamiltonian matrix.

  • params (dict) – Parameters of the Hamiltonian or kwant.system.

  • operator_array (iterable of operators) – The operators are normalized to an equivalent of a ‘dot’ function. If one of the elements in the iterable is ‘None’, then the identity operator is assumed. This identity is compatible with ‘first_transpose’.

  • coef_array (iterable of floats) – Array of coefficients for the expansion.

  • return_expansion (bool, default to 'False') – Return the expansion.

  • first_transpose (bool, default to 'False') – If there are more than one set of coefficients, then the first operator and set of coefficients are used to expand the vectors to the left. This means that the coefficients will be cojugated, and the that operator will be conjugate-transposed. This is achieved by different means, depending on the operator type. If the operator is a matrix, the conjugate-transpose of the matrix is taken. If it is a ~kwant.operator, then this must be Hermitian. If it is a callable, then it must be a method from a numpy ndarray, or a scipy sparse matrix. In this case, the __self__ attribute is attempted to retrieve, and the conjugate-transpose is taken. Mutually exclusive with ‘ourorboros’, in which case the saved expanded vectors to the right are the conjugate of the first expanded vectors to the left.

  • ouroboros (bool, default to 'False') – The first and last operators are equal, and the first and last functions defined by their KPM coefficients are also equal. Mutually exclusive with ‘first_transpose’. Note that the operators and coefficients must nonetheless be passed, or at least place-holders.

  • logging (bool, default to 'False') – Use logging.

Note

The first operator in the operator array must be a matrix that can be transposed.

kpm_tools.kpm_generator.general_function(*args, **kwargs)[source]#

Build a general function operator using KPM.

Returns a function that takes an energy or a list of energies, and returns the general function with that energy acting on vectors.

Parameters:

  • syst (kwant.System or ndarray) – Finalized kwant system or dense or sparse ndarray of the Hamiltonian with shape (N, N).

  • params (dict, optional) – Parameters for the kwant system.

  • kpm_params (dict, optional) – Dictionary containing the parameters to pass to the ~kwant.kpm module. ‘num_vectors’ will be overwritten to match the number of vectors, and ‘operator’ key will be deleted.

  • precalculate_moments (bool, default False) – Whether to precalculate and store all the KPM moments of vectors. This is useful if the Green’s function is evaluated at a large number of energies, but uses a large amount of memory. If False, the KPM expansion is performed every time the Green’s function is called, which minimizes memory use.

  • coef_function (callable, optional) – A function that takes a number of moments sequence of rescaled energies (to the interval ‘(-1, 1)’), and returns the coeficients of the expansion of the function.

Returns:

f – Takes an energy or array of energies and returns the general function acting on the vectors, for those energies.

Return type:

callable

kpm_tools.kpm_generator.multiprocess_update(spectrum, num_moments)[source]#

Update multiprocess.

kpm_tools.kpm_generator.process_update(spectrum, num_moments)[source]#

Update process.

kpm_tools.kpm_generator.thread_update(spectrum, num_moments, executor=None, shutdown=True)[source]#

Update thread.

Plotting Module#

Tiles Module#