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.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_+\)
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¶
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:
- 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:
- 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 inconfigure
) 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).
- 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 ifOperator.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 ifOperator.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 ifOperator.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:
left (dynamite.subspaces.Subspace) – The left subspace
right (dynamite.subspaces.Subspace, optional) – The right subspace. If omitted, the left subspace is reused for the right.
- conserves(left, right=None)[source]¶
Return whether the operator conserves the given subspace. If both
left
andright
are supplied, return whether the image of the operator when applied to theright
subspace is completely contained in theleft
subspace.
- property allow_projection¶
Whether to allow subspaces for which matrix multiplication implements a projection (those for which
Operator.conserves(subspace)
orOperator.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:
- 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.
- 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
toi % wrap_idx
. IfNone
, 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:
x (dynamite.states.State) – The input state x.
result (dynamite.states.State, optional) – A state in which to store the result. If omitted, a new State object is created.
- Returns:
The result
- Return type: