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[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, **kwargs)[source]

Time-evolve a state, using the operator as the Hamiltonian.

This method wraps dynamite.computations.evolve() (see that documentation for a full description of the method’s functionality).

Parameters:
  • state (dynamite.states.State) – The initial state.

  • t (float) – The time \(t\) for which to evolve the state (can be negative or complex).

  • **kwargs – Any further keyword arguments are passed to the underlying call to dynamite.computations.evolve(). See that documentation for a detailed description of possible arguments.

Returns:

The result vector \(\Psi_f\).

Return type:

dynamite.states.State

eigsolve(**kwargs)[source]

Find eigenvalues (and eigenvectors if requested) of the Hamiltonian. This class method is a wrapper on dynamite.computations.eigsolve(). Any keyword arguments are passed to that function; see its documentation for details.

By default, finds one (or possibly a few) eigenvalues with the smallest real values (i.e. the ground state).

Note

The spin chain length L must be set before calling eigsolve.

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 msc_size

The number of elements in the MSC representation of the matrix.

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 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

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