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[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, **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:
- 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 callingeigsolve
.- 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).
- 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 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
- 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: