API: Analysis Tools

Perturbative Analysis

class qubricks.analysis.perturbation.Perturb(H_0=None, V=None, subspace=None)

Bases: object

Perturb is a class that allows one to perform degenerate perturbation theory. The perturbation theory logic is intentionally separated into a different class for clarity. Currently it only supports using RSPT for perturbation theory, though in the future this may be extended to Kato perturbation theory. The advantage of using this class as compared to directly using the RSPT class is that the energies and eigenstates can be computed cumulatively, as well as gaining access to shorthand constructions of effective Hamiltonians.

Parameters:

• H_0 (Operator, sympy matrix or numpy array) – The unperturbed Hamiltonian to consider.
• V (Operator, sympy matrix or numpy array) – The Hamiltonian perturbation to consider.
• subspace (list of int) – The state indices to which attention should be restricted.

E(index, order=0, cumulative=True)

This method returns the index th eigenvalue correct to order order if cumulative is True; or the the order th correction otherwise.

Parameters:

• index (int) – The index of the state to be considered.
• order (int) – The order of perturbation theory to apply.
• cumulative (bool) – True if all order corrections up to order should be summed (including the initial unperturbed energy).

Es(order=0, cumulative=True, subspace=None)

This method returns a the energies associated with the indices in subspaces. Internally this uses Perturb.E, passing through the keyword arguments order and cumulative for each index in subspace.

Parameters:

• order (int) – The order of perturbation theory to apply.
• cumulative (bool) – True if all order corrections up to order should be summed (including the initial unperturbed energy).
• subspace (list of int) – The set of indices for which to return the associated energies.

H_eff(order=0, cumulative=True, subspace=None, adiabatic=False)

This method returns the effective Hamiltonian on the subspace indicated, using energies and eigenstates computed using Perturb.E and Perturb.Psi. If adiabatic is True, the effective Hamiltonian describing the energies of the instantaneous eigenstates is returned in the basis of the instantaneous eigenstates (i.e. the Hamiltonian is diagonal with energies corresponding to the instantaneous energies). Otherwise, the Hamiltonian returned is the sum over the indices of the subspace of the perturbed energies multiplied by the outer product of the corresponding perturbed eigenstates.

Parameters:

• order (int) – The order of perturbation theory to apply.
• cumulative (bool) – True if all order corrections up to order should be summed (including the initial unperturbed energies and states).
• subspace (list of int) – The set of indices for which to return the associated energies.
• adiabatic (bool) – True if the adiabatic effective Hamiltonian (as described above) should be returned. False otherwise.

Psi(index, order=0, cumulative=True)

This method returns the index th eigenstate correct to order order if cumulative is True; or the the order th correction otherwise.

Parameters:

• index (int) – The index of the state to be considered.
• order (int) – The order of perturbation theory to apply.
• cumulative (bool) – True if all order corrections up to order should be summed (including the initial unperturbed state).

Psis(order=0, cumulative=True, subspace=None)

This method returns a the eigenstates associated with the indices in subspaces. Internally this uses Perturb.Psi, passing through the keyword arguments order and cumulative for each index in subspace.

Parameters:

• order (int) – The order of perturbation theory to apply.
• cumulative (bool) – True if all order corrections up to order should be summed (including the initial unperturbed state).
• subspace (list of int) – The set of indices for which to return the associated energies.

dim

The dimension of \(H_0\).

pt

A reference to the perturbation calculating object (e.g. RSPT).

class qubricks.analysis.perturbation.RSPT(H_0=None, V=None, subspace=None)

Bases: object

This class implements (degenerate) Rayleigh-Schroedinger Perturbation Theory. It is geared toward generating symbolic solutions, in the hope that the perturbation theory might provide insight into the quantum system at hand. For numerical solutions, you are better off simply diagonalising the evaluated Hamiltonian.

Warning

This method currently only supports diagonal \(H_0\).

Parameters:

• H_0 (Operator, sympy matrix or numpy array) – The unperturbed Hamiltonian to consider.
• V (Operator, sympy matrix or numpy array) – The Hamiltonian perturbation to consider.
• subspace (list of int) – The state indices to which attention should be restricted.

E(index, order=0)

This method returns the order th correction to the eigenvalue associated with the index th state using RSPT.

The algorithm:

If order is 0, return the unperturbed energy.

If order is even:

\[\begin{split}E_n = \left< \Psi_{n/2} \right| V \left| \Psi_{n/2-1} \right> - \sum_{k=1}^{n/2} \sum_{l=1}^{n/2-1} E_{n-k-l} \left< \Psi_k \big | \Psi_l \right>\end{split}\]

If order is odd:

\[\begin{split}E_n = \left< \Psi_{(n-1)/2} \right| V \left| \Psi_{(n-1)/2} \right> - \sum_{k=1}^{(n-1)/2} \sum_{l=1}^{(n-1)/2} E_{n-k-l} \left< \Psi_k \big| \Psi_l \right>\end{split}\]

Where subscripts indicate that the subscripted symbol is correct to the indicated order in RSPT, and where n = order.

Parameters:

• index (int) – The index of the state to be considered.
• order (int) – The order of perturbation theory to apply.

H_0

Psi(index, order=0)

This method returns the order th correction to the index th eigenstate using RSPT.

The algorithm:

If order is 0, return the unperturbed eigenstate.

Otherwise, return:

\[\begin{split}\left| \Psi_n \right> = (E_0-H_0)^{-1} P \left( V \left|\Psi_{n-1}\right> - \sum_{k=1}^n E_k \left|\Psi_{n-k}\right> \right)\end{split}\]

Where P is the projector off the degenerate subspace enveloping the indexed state.

Parameters:

• index (int) – The index of the state to be considered.
• order (int) – The order of perturbation theory to apply.

V

dim

The dimension of \(H_0\).

get_unperturbed_states()

This method returns the unperturbed eigenvalues and eigenstates as a tuple of energies and state-vectors.

Note

This is the only method that does not support a non-diagonal \(H_0\). While possible to implement, it is not currently clear that a non-diagonal \(H_0\) is actually terribly useful.

inv(index)

This method returns: \((E_0 - H_0)^{-1} P\), for use in Psi, which is computed using:

\[A_{ij} = \delta_{ij} \delta_{i0} (E^n_0 - E^i_0)^{-1}\]

Where n = order.

Note

In cases where a singularity would result, 0 is used instead. This works because the projector off the subspace P reduces support on the singularities to zero.

Parameters:index (int) – The index of the state to be considered.

qubricks.analysis.perturbation.debug(*messages)

Spectral Analysis

qubricks.analysis.spectrum.energy_spectrum(system, states, ranges, input=None, output=None, threshold=False, hamiltonian=None, components=[], params={}, hamiltonian_init=None, components_init=None, params_init=None, complete=False, derivative_decimals=8)

This function returns a list of sequence which are the energy eigenvalues of the states which map adiabatically to those provided in states. Consequently, the provided states should be eigenstates of the Hamiltonian (determined by components_init or hamiltonian_init) when the parameters are set according to params_init. Where the initial conditions are not set, the states are assumed to be eigenstates of the Hamiltonian provided for analysis (hamiltonian or components) in the corresponding parameter context params.

Parameters:

• system (QuantumSystem) – A QuantumSystem instance.
• states (list of object) – A list of states (assumed to be eigenstates as noted above) for which we are interested in examining the eigen-spectrum.
• ranges (dict) – A range specification for iteration (see Parameters.range).
• input (str, Basis or None) – The basis of the specified states.
• output (str, Basis or None) – The basis in which to perform the calculations.
• threshold (bool or float) – Whether to use a threshold (if boolean) or the threshold to use in basis transformations. (See Basis.transform.)
• hamiltonian (Operator or None) – The Hamiltonian for which a spectrum is desired.
• components (list of str) – If hamiltonian is None, the components to use from the provided QuantumSystem (see QuantumSystem.H).
• params (dict) – The parameter context in which to perform calculations.
• hamiltonian_init (Operator) – The Hamiltonian for which provided states are eigenstates. If not provided, and components_init is also not provided, this defaults to the value of hamiltonian.
• components_init – The components to enable such that the provided states are eigenstates. If not provided, this defaults to the value of components. (see QuantumSystem.H)
• params_init (dict) – The parameter context to be used such that the provided states are eigenstates of the initial Hamiltonian. If not provided, defaults to the value of params.
• complete (bool) – If True, then the eigen-spectrum of the remaining states not specifically requested are appended to the returned results.

Warning

This method tracks eigenvalues using the rule that the next accepted eigenvalue should be the one with minimal absolute value of the second derivative (or equivalently, the one with the most continuous gradient). If you find that this causes unexpected jumps in your plot, please try decreasing the granularity of your trace before reporting a bug.

Utilities

class qubricks.analysis.model.ModelAnalysis(*args, **kwargs)

Bases: object

ModelAnalysis is a helper class that can simplify the routine of running simulations, processing the results, and then plotting (or otherwise outputting) them. One simply need subclass ModelAnalysis, and implement the following methods:

• prepare(self, *args, **kwargs)
• simulate(self, *args, **kwargs)
• process(self, *args, **kwargs)
• plot(self, *args, **kwargs)

Each of these methods is guaranteed to be called in the order specified above, with the return values of the previous method being fed forward to the next. Calling process (with no arguments), for example, will also call prepare and simulate in order, with the return values of prepare being passed to simulate, and the return values of simulate being passed to process. If a method is called directly with input values, then this chaining does not occur, and the method simply returns what it should.

It is necessary to be a little bit careful about what one returns in these methods. In particular, this is the way in which return values are processed:

• If a tuple is returned of length 2, and the first element is a

tuple and the second a dict, then it is assumed that these are respectively the args and kwargs to be fed forward. - If a tuple is returned of any other length, or any of the above conditions fail, then these are assumed to be the args to be fed forward. - If a dictionary is returned, then these are assumed to be the kwargs to be fed forward. - Otherwise, the result is fed forward as the first non-keyword argument.

Note

It is not necessary to return values at these steps, if it is unnecessary or if you prefer to save your results as attributes.

Note

Return values of all of these methods will be cached, so each method will only be run once.

plot(*args, **kwargs)

This method should perform whatever plotting/output is desired based upon return values of process.

prepare(*args, **kwargs)

This method should prepare the ModelAnalysis instance for calling the rest of the methods. It is invoked on class initialisation, with the arguments passed to the constructor. Any return values will be passed onto simulate if it is ever called with no arguments.

process(*args, **kwargs)

This method should perform whatever processing is interesting on return values of simulate. Any values returned will be passed onto plot if it is ever called with no arguments.

simulate(*args, **kwargs)

This method should perform whichever simulations are required. Any values returned will be passed onto process if it is ever called with no arguments.