dynamite.operators

Single-site operators

These operators apply to a single spin, identified by an index passed to their constructor. The default index is 0. It is implied that they are tensored with the identity on every other site in the spin chain. Explicitly, a single spin operator \(O\) here has the form \(I_0 \otimes I_1 \otimes \ldots \otimes O_{i} \otimes \ldots \otimes I_L\), where \(i\) is the index passed in the constructor and \(L\) is the length of the spin chain.

dynamite.operators.sigmax(i=0)[source]

The Pauli \(\sigma_x\) operator on site \(i\).

dynamite.operators.sigmay(i=0)[source]

The Pauli \(\sigma_y\) operator on site \(i\).

dynamite.operators.sigmaz(i=0)[source]

The Pauli \(\sigma_z\) operator on site \(i\).

dynamite.operators.sigma_plus(i=0)[source]

The \(\sigma_+ = \sigma_x + i \sigma_y\) operator.

Note

\(\sigma_+ = \left( \begin{array}{cc} 0 & 2 \\ 0 & 0 \\ \end{array} \right)\), so \(S_+ = \left( \begin{array}{cc} 0 & 1 \\ 0 & 0 \\ \end{array} \right) = \frac{1}{2} \sigma_+\)

dynamite.operators.sigma_minus(i=0)[source]

The \(\sigma_- = \sigma_x - i \sigma_y\) operator.

Note

\(\sigma_- = \left( \begin{array}{cc} 0 & 0 \\ 2 & 0 \\ \end{array} \right)\), so \(S_- = \left( \begin{array}{cc} 0 & 0 \\ 1 & 0 \\ \end{array} \right) = \frac{1}{2} \sigma_-\)

dynamite.operators.identity()[source]

The identity operator.

dynamite.operators.zero()[source]

The zero operator—equivalent to a matrix of all zeros.

Sums and Products

dynamite.operators.op_sum(terms, nshow=3)[source]

A sum of several operators. This object can be used in a couple ways. All of the following return the exact same object, \(\sigma^x_0 + \sigma^y_0\):

sigmax() + sigmay()
op_sum([sigmax(), sigmay()])
op_sum(s() for s in [sigmax, sigmay])
Parameters:
  • terms (list) – A list of operators to sum

  • nshow (int, optional) – The number of terms to show in the string representations before adding an ellipsis.

dynamite.operators.op_product(terms)[source]

A product of several operators. Called in same way as op_sum(). For example:

>>> sigmax() * sigmay() == op_product([sigmax(), sigmay()])
True
Parameters:

terms (list) – A list of operators to multiply

Translations

The following two classes translate the given operator op along the spin chain, and take the sum or product of the results.

dynamite.operators.index_sum(op, size=None, start=0, boundary='open')[source]

Duplicate the operator onto adjacent sites in the spin chain, and sum the resulting operators. In most cases, op should have support on site 0 (and possibly others).

See the examples for more information.

Parameters:
  • op (Operator) – The operator to translate along the spin chain.

  • size (int, optional) – The size of the support of the resulting operator. For open boundary conditions, the number of terms in the sum may be smaller than this. If not provided, defaults to the value of Operator.L.

  • start (int, optional) – The site for the first operator in the sum.

  • boundary (str, optional) – Whether to use ‘open’ or ‘closed’ boundary conditions. When op has support on more than one site, this determines whether the last few terms of the sum should wrap around to the beginning of the spin chain.

dynamite.operators.index_product(op, size=None, start=0)[source]

Duplicate the operator onto adjacent sites in the spin chain, and multiply the resulting operators together. In most cases, op should have support on site 0 (and possibly others).

Parameters:
  • op (Operator) – The operator to translate along the spin chain.

  • size (int, optional) – The size of the support of the resulting operator. If not provided, defaults to the value of Operator.L.

  • start (int, optional) – The site for the first operator in the sum.

Saved Operators

dynamite.operators.load_from_file(filename)[source]

DEPRECATED: use dynamite.operators.Operator.load

dynamite.operators.from_bytes(data)[source]

DEPRECATED: use dynamite.operators.Operator.from_bytes

Member Functions

class dynamite.operators.Operator(msc=None, string_rep=None)[source]

A class representing a quantum operator.

This class generally won’t be directly instantiated by the user, but is returned by the other functions in this module.

copy()[source]

Return a copy of the operator. Copy will not have its PETSc matrix already built, even if the operator being copied does.

Returns:

A copy of the operator

Return type:

Operator

evolve(state, t, result=None, tol=None, ncv=None, algo=None, max_its=None)

Evolve a quantum state according to the Schrodinger equation under the Hamiltonian H. The units are natural, that is, the evolution is simply

\[\Psi_t = e^{-iHt} \Psi_0\]
Parameters:
  • H (Operator) – The Hamiltonian

  • state (dynamite.states.State) – A dynamite State object containing the state to be evolved.

  • t (float) – The time for which to evolve. Can be negative to evolve backwards in time.

  • result (dynamite.states.State, optional) – Where to store the result state. If not given, a new vector is created in which to store the result. If evolving repeatedly many times, it is a good idea to pass a result vector to avoid repeatedly allocating a lot of memory. Will be overwritten.

  • tol (float, optional) – The tolerance for the evolution. Error estimation is difficult for Krylov exponentiation; this merely requests that the error be somewhat close to tol. There is no guarantee that it will actually be smaller.

  • ncv (int, optional) – The Krylov subspace size to use. Increasing subspace size can increase performance by reducing the number of iterations necessary, but also linearly increases memory usage and the number of matrix multiplies performed. Optimizing this parameter can significantly affect performance.

  • algo (string, optional) – Allowed options: ‘krylov’ or ‘expokit’. Which SLEPc algorithm to use to compute the matrix exponential. Default is ‘expokit’.

  • max_its (int, optional) – Maximum number of iterations for the solver.

Returns:

The result state

Return type:

dynamite.states.State

eigsolve(getvecs=False, nev=1, which='lowest', target=None, tol=None, subspace=None, max_its=None)

Solve for a subset of the eigenpairs of the Hamiltonian.

By default, solves for the eigenvalue with the lowest (most negative) real part, e.g. the ground state. Which eigenvalues are sought and how many can be adjusted with the options.

Note

Krylov algorithms have difficulty with degenerate or very nearly degenerate eigenvalues. Degenerate eigenvalues may be missed, and near-degenerate eigenstates may be inaccurate.

Note

Do not try to use this function to solve for the whole spectrum! It’s very efficient at finding a few eigenvalues, but no faster than other routines for finding all of them. In the future an efficient solver for the whole spectrum may be included with dynamite.

Parameters:
  • getvecs (Bool) – Whether to return eigenvectors as well as eigenvalues.

  • nev (int) – The number of eigenvalues sought. The algorithm may return more eigenvalues than nev if more happen to converge.

  • which (str) –

    Which eigenvalues to seek. Options are:

    • "lowest", to find the eigenvalues with lowest (most negative) real part

    • "highest", to find the eigenvalues with highest (most positive) real part

    • "exterior", to find eigenvalues largest in absolute magnitude

    • "target", to find eigenvalues closest to the given target

    If target is set, which can be omitted and will automatically be set to "target".

  • target (float) – Using the shift-invert method, the eigensolver can seek the eigenvalues with real part closest to some target value. This requires a linear solve and so will be slower than solving for exterior eigenvalues. PETSc must be configured with a parallel linear solver (e.g. --download-mumps option in configure) to use this option in parallel.

  • tol (float) – The tolerance for the computation.

  • subspace (dynamite.subspaces.Subspace, optional) – The subspace on which to solve for eigenvalues. If not given, defaults to the most recent subspace set with Operator.add_subspace, or config.subspace if no subspaces have been added.

Returns:

Either a 1D numpy array of eigenvalues, or a pair containing that array and a list of the corresponding eigenvectors.

Return type:

numpy.array or tuple(numpy.array, list(dynamite.states.State))

property max_spin_idx

Read-only property giving the largest spin index on which this operator has support.

property L

Property representing the length of the spin chain.

establish_L()[source]

If L has not been set, set it to the minimum value possible based on the support of the operator (and propagate that value to all registered subspaces). Does nothing if the operator already has a value for L other than None.

get_length()[source]

Returns the length of the spin chain for this operator. It is defined by the property Operator.L() if it has been set by the user. Otherwise, one plus the largest spin index on which the operator has support is returned.

property dim

Read-only attribute returning the dimensions of the matrix.

property nnz

The number of nonzero elements per row of the sparse matrix.

property nterms

The number of terms in the operator, when written as a sum of products of Paulis. Note that Operator.reduce_msc() is called when accessing this property, which cleans up and sorts the internal representation used by dynamite for the operator.

property msc_size

(deprecated)

property density

The density of the sparse matrix—that is, the number of non-zero elements per row divided by the length of a row.

Note

This quantity is not always well defined when using a subspace, since it can vary by row. In that case, the returned quantity will be an upper bound.

infinity_norm(subspaces=None)[source]

Computes the infinity norm of the operator’s matrix, on the given subspace(s). If subspace is not supplied, defaults to the operator’s default subspace (the most recently added one, or Full).

Parameters:

subspaces (tuple(Subspace, Subspace), optional) – The subspace pair on which to compute the infinity norm

Returns:

The norm

Return type:

float

property shell

Switch whether to use shell matrices or not. For a description of shell matrices and their benefits, see the documentation.

Note

Changing this value after the matrix has been built will invoke a call to Operator.destroy_mat().

property precompute_diagonal

Whether shell matrices should precompute and store the matrix diagonal. Usually should only be turned off if a matrix will be “single-use” (destroyed after a single multiplication).

Note

Changing this value after the matrix has been built will invoke a call to Operator.destroy_mat().

property left_subspace

Get the default left subspace for this operator. This is the subspace most recently added with Operator.add_subspace(), or config.subspace if Operator.add_subspace() has not been called.

property right_subspace

Get the default right subspace for this operator. This is the subspace most recently added with Operator.add_subspace(), or config.subspace if Operator.add_subspace() has not been called.

property subspace

Get the default subspace for this operator. This is the subspace most recently added with Operator.add_subspace(), or config.subspace if Operator.add_subspace() has not been called.

add_subspace(left, right=None)[source]

Add a pair of subspaces that this operator is compatible with.

Parameters:
  • left (dynamite.subspaces.Subspace) – A subspace the operator can map to (or multiply from the left)

  • right (dynamite.subspaces.Subspace, optional) – A subspace the operator can map from (or multiply to the right). If omitted, the left subspace is reused for the right.

get_subspace_list()[source]

Return a list of the subspaces that have been registered for this operator.

has_subspace(left, right=None)[source]

Check if a subspace or pair of subspaces has been added to the operator.

Parameters:
conserves(left, right=None)[source]

Return whether the operator conserves the given subspace. If both left and right are supplied, return whether the image of the operator when applied to the right subspace is completely contained in the left subspace.

property allow_projection

Whether to allow subspaces for which matrix multiplication implements a projection (those for which Operator.conserves(subspace) or Operator.conserves(left_subspace, right_subspace) returns False).

table()[source]

Return a string containing an ASCII table of the coefficients and terms that make up this operator.

The table is generated directly from the MSC representation, so it is expanded and simplified to the same form no matter how the operator was built.

Call Operator.reduce_msc() first for a more compact table.

serialize()[source]

Serialize the operator into a string of bytes. The byte string ONLY contains dynamite’s internal representation of the operator. It does not include any other information, such as subspaces etc.

Returns:

The byte string containing the serialized object.

Return type:

bytes

classmethod from_bytes(data)[source]

Load operator from a byte string generated with the Operator.serialize() method.

Parameters:

data (bytes) – The byte string containing the serialized object.

Returns:

The operator.

Return type:

Operator

save(filename)[source]

Save the operator to disk. Can be loaded again via the Operator.load() method. Only saves the operator itself, not any associated subspaces or other data.

Parameters:

filename (str) – The path to the file to save the operator in.

classmethod load(filename)[source]

Load the operator in file filename and return the corresponding object.

Parameters:

filename (str) – The path of the file to load.

Returns:

The operator as a dynamite object.

Return type:

dynamite.operators.Load

get_mat(subspaces=None)[source]

Get the PETSc matrix corresponding to this operator, building it if necessary.

Parameters:

subspaces (tuple(Subspace, Subspace), optional) – The subspace pair to get the matrix for. If the matrix is already built for this pair, it will be reused. If this option is omitted, the last subspace added with Operator.add_subspace() will be used, or the Full space by default.

Returns:

The PETSc matrix corresponding to the operator.

Return type:

petsc4py.PETSc.Mat

build_mat(subspaces=None)[source]

Build the PETSc matrix, destroying any matrix that has already been built, and store it internally. This function does not return the matrix–see Operator.get_mat() for that functionality. This function is rarely needed by the end user, since it is called automatically whenever the underlying matrix needs to be built or rebuilt.

destroy_mat(subspaces=None)[source]

Destroy the PETSc matrix, freeing the corresponding memory. If the PETSc matrix does not exist (has not been built or has already been destroyed), the function has no effect.

Parameters:

subspaces (tuple(Subspace, Subspace), optional) – Destroy only the matrix for a particular pair of subspaces.

estimate_memory(mpi_size=None)[source]

Estimate the total amount of memory that will be used by this operator once the matrix is constructed (for example, after calling .evolve()), summed across all MPI ranks.

Note that the memory allocated for communication etc. depends on a number of different parameters, so actual memory usage may vary.

For operators containing terms that cancel to zero in some cases (such as XX+YY), this function will overestimate the required memory for non-shell matrices.

Parameters:

mpi_size (int, optional) – The number of ranks to estimate memory usage for. If not provided, the mpi size of the running program is used.

Returns:

The expected memory usage, in gigabytes

Return type:

float

create_states()[source]

Return a bra and ket compatible with this matrix.

Returns:

The two states

Return type:

tuple

expectation(state, tmp_state=None)[source]

Convenience function to compute the expectation value with respect to a given state.

Parameters:
  • state (dynamite.states.State) – The state for which to compute the expectation value

  • tmp_state (dynamite.states.State, optional) – A “scratch space” state to use during the computation. Must be in the correct subspace. A state vector is allocated internally if one is not provided.

property msc

The (mask, sign, coefficient) representation of the operator. This representation is used internally by dynamite.

reduce_msc()[source]

Combine and sort terms in the MSC representation, compressing it and preparing it for use in the backend.

property is_reduced

Whether Operators.reduce_msc() has been called. Can also be set manually to avoid calling that function, if you are sure that the terms are sorted already.

get_shifted_msc(shift, wrap_idx=None)[source]

Get the MSC representation of the operator, with all terms translated along the spin chain (away from zero) by shift spins.

Parameters:
  • shift (int) – Shift the whole operator along the spin chain by shift spins.

  • wrap (bool) – The site at which to begin wrapping around to the beginning of the spin chain. e.g. takes a site index i to i % wrap_idx. If None, do not wrap.

Returns:

A numpy array containing the representation.

Return type:

numpy.ndarray

truncate(tol=1e-12)[source]

Remove terms whose magnitude (absolute value) is less than tol.

Parameters:

tol (float) – The cutoff for truncation

to_numpy(subspaces=None, sparse=True)[source]

Get a SciPy sparse matrix or dense numpy array representing the operator.

Parameters:
  • subspaces (tuple(Subspace, Subspace), optional) – The subspaces for which to get the matrix. If this option is omitted, the last subspace added with Operator.add_subspace() will be used, or the Full space by default.

  • sparse (bool, optional) – Whether to return a sparse matrix or a dense array.

Returns:

The array

Return type:

np.ndarray(dtype = np.complex128)

spy(subspaces=None, max_size=1024)[source]

Use matplotlib to show the nonzero structure of the matrix.

Parameters:
  • subspaces (tuple(Subspace, Subspace), optional) – The pair of subspaces for which to plot the matrix. Defaults to the most recent added with the Operator.add_subspace method, or otherwise config.subspace.

  • max_size (int, optional) – The maximum matrix dimension for which this function can be called. Calling it for too large a matrix will not be informative and probably run out of memory, so this is a small safeguard.

dot(x, result=None)[source]

Compute the matrix-vector product \(\vec{y} = A\vec{x}\)

Parameters:
Returns:

The result

Return type:

dynamite.states.State

scale(x)[source]

Scale an operator by a numerical value without making a copy. This is more efficient than just doing x*Operator.

Parameters:

x (numeric type) – The coefficient to scale by