Functions

Plotting

scqubits.utils.plotting.contours(x_vals, y_vals, func, contour_vals=None, show_colorbar=True, **kwargs)

Contour plot of a 2d function func(x,y).

Parameters

• x_vals ((ordered) list) – x values for the x-y evaluation grid

• y_vals ((ordered) list) – y values for the x-y evaluation grid

• func (function f(x,y)) – function for which contours are to be plotted

• contour_vals (list of float, optional) – contour values can be specified if so desired

• show_colorbar (bool, optional) –

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

matplotlib objects for further editing

Return type

tuple(Figure, Axes)

scqubits.utils.plotting.data_vs_paramvals(xdata, ydata, label_list=None, **kwargs)

Plot of a set of yadata vs xdata. The individual points correspond to the a provided array of parameter values.

Parameters

• ydata (xdata,) – must have compatible shapes for matplotlib.pyplot.plot

• label_list (list(str), optional) – list of labels associated with the individual curves to be plotted

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

matplotlib objects for further editing

Return type

tuple(Figure, Axes)

scqubits.utils.plotting.evals_vs_paramvals(specdata, which=-1, subtract_ground=False, label_list=None, **kwargs)

Generates a simple plot of a set of eigenvalues as a function of one parameter. The individual points correspond to the a provided array of parameter values.

Parameters

• specdata (SpectrumData) – object includes parameter name, values, and resulting eigenenergies

• which (int or list(int)) – number of desired eigenvalues (sorted from smallest to largest); default: -1, signals all eigenvalues or: list of specific eigenvalues to include

• subtract_ground (bool) – whether to subtract the ground state energy

• label_list (list(str), optional) – list of labels associated with the individual curves to be plotted

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

matplotlib objects for further editing

Return type

tuple(Figure, Axes)

scqubits.utils.plotting.matelem_vs_paramvals(specdata, select_elems=4, mode='abs', **kwargs)

Generates a simple plot of matrix elements as a function of one parameter. The individual points correspond to the a provided array of parameter values.

Parameters

• specdata (SpectrumData) – object includes parameter name, values, and matrix elements

• select_elems (int or list) – either maximum index of desired matrix elements, or list [(i1, i2), (i3, i4), …] of index tuples for specific desired matrix elements

• mode (str from constants.MODE_FUNC_DICT, optional) – choice of processing function to be applied to data (default value = ‘abs’)

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

matplotlib objects for further editing

Return type

tuple(Figure, Axes)

scqubits.utils.plotting.matrix(data_matrix, mode='abs', show_numbers=False, **kwargs)

Create a “skyscraper” plot and a 2d color-coded plot of a matrix.

Parameters

• data_matrix (ndarray of float or complex) – 2d matrix data

• mode (str from constants.MODE_FUNC_DICT) – choice of processing function to be applied to data

• show_numbers (bool, optional) – determines whether matrix element values are printed on top of the plot (default: False)

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

figure and axes objects for further editing

Return type

Figure, (Axes1, Axes2)

scqubits.utils.plotting.matrix2d(matrix, mode='abs', show_numbers=True, **kwargs)

Display a matrix as a color-coded 2d plot, optionally printing the numerical values of the matrix elements.

Parameters

• matrix (ndarray of float or complex) – 2d matrix data

• mode (str from constants.MODE_FUNC_DICT) – choice of processing function to be applied to data

• show_numbers (bool, optional) – determines whether matrix element values are printed on top of the plot (default: True)

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

figure and axes objects for further editing

Return type

Figure, Axes

scqubits.utils.plotting.matrix_skyscraper(matrix, mode='abs', **kwargs)

Display a 3d skyscraper plot of the matrix

Parameters

• matrix (ndarray of float or complex) – 2d matrix data

• mode (str from constants.MODE_FUNC_DICT) – choice of processing function to be applied to data

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

figure and axes objects for further editing

Return type

Figure, Axes

scqubits.utils.plotting.print_matrix(matrix, mode='abs', show_numbers=True, **kwargs)

Display a matrix as a color-coded 2d plot, optionally printing the numerical values of the matrix elements.

Parameters

• matrix (ndarray of float or complex) – 2d matrix data

• mode (str from constants.MODE_FUNC_DICT) – choice of processing function to be applied to data

• show_numbers (bool, optional) – determines whether matrix element values are printed on top of the plot (default: True)

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

figure and axes objects for further editing

Return type

Figure, Axes

scqubits.utils.plotting.wavefunction1d(wavefunc, potential_vals=None, offset=0, scaling=1, **kwargs)

Plots the amplitude of a single real-valued 1d wave function, along with the potential energy if provided.

Parameters

• wavefunc (WaveFunction object) – basis and amplitude data of wave function to be plotted

• potential_vals (array of float) – potential energies, array length must match basis array of wavefunc

• offset (float) – y-offset for the wave function (e.g., shift by eigenenergy)

• scaling (float, optional) – scaling factor for wave function amplitudes

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

matplotlib objects for further editing

Return type

tuple(Figure, Axes)

scqubits.utils.plotting.wavefunction1d_discrete(wavefunc, **kwargs)

Plots the amplitude of a real-valued 1d wave function in a discrete basis. (Example: transmon in the charge basis.)

Parameters

• wavefunc (WaveFunction object) – basis and amplitude data of wave function to be plotted

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

matplotlib objects for further editing

Return type

tuple(Figure, Axes)

scqubits.utils.plotting.wavefunction2d(wavefunc, zero_calibrate=False, **kwargs)

Creates a density plot of the amplitude of a real-valued wave function in 2 “spatial” dimensions.

Parameters

• wavefunc (WaveFunctionOnGrid object) – basis and amplitude data of wave function to be plotted

• zero_calibrate (bool, optional) – whether to calibrate plot to zero amplitude

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

matplotlib objects for further editing

Return type

tuple(Figure, Axes)

Plotting from ParameterSweep

scqubits.utils.sweep_plotting.bare_spectrum(sweep, subsys, which=-1, **kwargs)

Plots energy spectrum of bare system subsys for given ParameterSweep sweep.

Parameters

• sweep (ParameterSweep) –

• subsys (QuantumSystem) –

• which (int or list(int), optional) – default: -1, signals to plot all wavefunctions within the truncated Hilbert space; int>0: plot wavefunctions 0..int-1; list(int) plot specific wavefunctions

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

Return type

fig, axes

scqubits.utils.sweep_plotting.bare_wavefunction(sweep, param_val, subsys, which=-1, phi_grid=None, **kwargs)

Plot bare wavefunctions for given parameter value and subsystem.

Parameters

• sweep (ParameterSweep) –

• param_val (float) – value of the external parameter

• subsys (QuantumSystem) –

• which (int or list(int), optional) – default: -1, signals to plot all wavefunctions; int>0: plot wavefunctions 0..int-1; list(int) plot specific wavefunctions

• phi_grid (Grid1d, optional) – used for setting a custom grid for phi; if None use self._default_grid

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

Return type

fig, axes

scqubits.utils.sweep_plotting.charge_matrixelem(datastore, qbt_index_subsys, initial_state_idx=0, **kwargs)

Parameters

• datastore (DataStore) –

• qbt_index_subsys (tuple(int, QuantumSystem)) – index of the qubit system within the underlying HilbertSpace, and qubit object

• initial_state_idx (int) – index of initial state

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

Return type

Figure, Axes

scqubits.utils.sweep_plotting.chi(datastore, **kwargs)

Plot dispersive shifts chi_j for a given pair of qubit and oscillator.

Parameters

• datastore (DataStore) – contains sweep data for the dispersive shift, stored as datastore.chi

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

Return type

Figure, Axes

scqubits.utils.sweep_plotting.chi_01(datastore, param_index=0, **kwargs)

Plot the dispersive shift chi01 for a given pair of qubit and oscillator.

Parameters

• datastore (DataStore) –

• param_index (int, optional) – index of the external parameter to be used

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

Return type

Figure, Axes

scqubits.utils.sweep_plotting.difference_spectrum(sweep, initial_state_ind=0, **kwargs)

Plots a transition energy spectrum with reference to the given initial_state_ind, obtained by taking energy differences of the eigenenergy spectrum.

Parameters

• sweep (ParameterSweep) –

• initial_state_ind (int) –

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

Return type

Figure, Axes

scqubits.utils.sweep_plotting.dressed_spectrum(sweep, **kwargs)

Plots energy spectrum of dressed system

Parameters

• sweep (ParameterSweep) –

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

Return type

fig, axes

scqubits.utils.sweep_plotting.n_photon_qubit_spectrum(sweep, photonnumber, initial_state_labels, **kwargs)

Plots the n-photon qubit transition spectrum.

Parameters

• sweep (ParameterSweep) –

• photonnumber (int) – number of photons used in the transition

• initial_state_labels (tuple(int1, int2, ..)) – bare state index of the initial state for the transitions

• **kwargs (dict) – standard plotting option (see separate documentation)

Returns

Return type

Figure, Axes

QuTiP Operators for Composite Hilbert Spaces

scqubits.core.operators.annihilation(dimension)

Returns a dense matrix of size dimension x dimension representing the annihilation operator in number basis.

Parameters

dimension (int) –

Returns

annihilation operator matrix, size dimension x dimension

Return type

ndarray

scqubits.core.operators.annihilation_sparse(dimension)

Returns a matrix of size dimension x dimension representing the annihilation operator in the format of a scipy sparse.csc_matrix.

Parameters

dimension (int) –

Returns

sparse annihilation operator matrix, size dimension x dimension

Return type

sparse.csc_matrix

scqubits.core.operators.creation(dimension)

Returns a dense matrix of size dimension x dimension representing the creation operator in number basis.

Parameters

dimension (int) –

Returns

creation operator matrix, size dimension x dimension

Return type

ndarray

scqubits.core.operators.creation_sparse(dimension)

Returns a matrix of size dimension x dimension representing the creation operator in the format of a scipy sparse.csc_matrix

Parameters

dimension (int) –

Returns

sparse annihilation operator matrix, size dimension x dimension

Return type

sparse.csc_matrix

scqubits.core.operators.hubbard_sparse(j1, j2, dimension)

The Hubbard operator \(|j1\rangle>\langle j2|\) is returned as a matrix of linear size dimension.

Parameters

• dimension (int) –

• j2 (j1,) – indices of the two states labeling the Hubbard operator

Returns

sparse number operator matrix, size dimension x dimension

Return type

sparse.csc_matrix

scqubits.core.operators.number(dimension, prefactor=None)

Number operator matrix of size dimension x dimension in sparse matrix representation. An additional prefactor can be directly included in the generation of the matrix by supplying ‘prefactor’.

Parameters

• dimension (int) –

• prefactor (float or complex, optional) – prefactor multiplying the number operator matrix

Returns

number operator matrix, size dimension x dimension

Return type

ndarray

scqubits.core.operators.number_sparse(dimension, prefactor=None)

Number operator matrix of size dimension x dimension in sparse matrix representation. An additional prefactor can be directly included in the generation of the matrix by supplying ‘prefactor’.

Parameters

• dimension (int) –

• prefactor (float or complex, optional) – prefactor multiplying the number operator matrix

Returns

sparse number operator matrix, size dimension x dimension

Return type

sparse.csc_matrix

Utility Functions

Manipulating spectral data

scqubits.utils.spectrum_utils.absorption_spectrum(spectrum_data)

Takes spectral data of energy eigenvalues and returns the absorption spectrum relative to a state of given index. Calculated by subtracting from eigenenergies the energy of the select state. Resulting negative frequencies, if the reference state is not the ground state, are omitted.

Parameters

spectrum_data (SpectrumData) –

Returns

Return type

SpectrumData object

scqubits.utils.spectrum_utils.closest_dressed_energy(bare_energy, dressed_energy_vals)

For a given bare energy value, this returns the closest lying dressed energy value from an array.

Parameters

• bare_energy (float) – bare energy value

• dressed_energy_vals (ndarray) – array of dressed-energy values

Returns

element from dressed_energy_vals closest to bare_energy

Return type

float

scqubits.utils.spectrum_utils.convert_esys_to_ndarray(esys_qutip)

Takes a qutip eigenstates array, as obtained with .eigenstates(), and converts it into a pure numpy array.

Parameters

esys_qutip (ndarray of qutip.Qobj) – as obtained from qutip .eigenstates()

Returns

converted eigenstate data

Return type

ndarray

scqubits.utils.spectrum_utils.emission_spectrum(spectrum_data)

Takes spectral data of energy eigenvalues and returns the emission spectrum relative to a state of given index. The resulting “upwards” transition frequencies are calculated by subtracting from eigenenergies the energy of the select state, and multiplying the result by -1. Resulting negative frequencies, corresponding to absorption instead, are omitted.

Parameters

spectrum_data (SpectrumData) –

Returns

Return type

SpectrumData object

scqubits.utils.spectrum_utils.extract_phase(complex_array, position=None)

Extracts global phase from complex_array at given position. If position is not specified, the position is set to to an intermediate position to avoid machine-precision problems with tails of wavefunctions at beginning or end of the array.

Parameters

• complex_array (ndarray) – complex-valued array

• position (int, optional) – position where the phase is extracted (default value = None)

scqubits.utils.spectrum_utils.generate_target_states_list(sweep, initial_state_labels)

Based on a bare state label (i1, i2, …) with i1 being the excitation level of subsystem 1, i2 the excitation level of subsystem 2 etc., generate a list of new bare state labels. These bare state labels correspond to target states reached from the given initial one by single-photon qubit transitions. These are transitions where one of the qubit excitation levels increases at a time. There are no changes in oscillator photon numbers.

Parameters

• sweep (ParameterSweep) –

• initial_state_labels (tuple(int1, int2, ..)) – bare-state labels of the initial state whose energy is supposed to be subtracted from the spectral data

Returns

Return type

list of tuple

scqubits.utils.spectrum_utils.get_eigenstate_index_maxoverlap(eigenstates_qobj, reference_state_qobj, return_overlap=False)

For given list of qutip states, find index of the state that has largest overlap with the qutip ket reference_state_qobj. If |overlap| is smaller than 0.5, return None.

Parameters

• eigenstates_qobj (ndarray of qutip.Qobj) – as obtained from qutip .eigenstates()

• reference_state_qobj (qutip.Qobj ket) – specific reference state

• return_overlap (bool, optional) – set to true if the value of largest overlap should be also returned (default value = False)

Returns

index of eigenstate from eigenstates_Qobj with the largest overlap with the reference_state_qobj; None if |overlap|<0.5

Return type

int or None

scqubits.utils.spectrum_utils.get_matrixelement_table(operator, state_table)

Calculates a table of matrix elements.

Parameters

• operator (ndarray or sparse matrix object) – operator with respect to which matrix elements are to be calculated

• state_table (list or ndarray) – list or array of numpy arrays representing the states |v0>, |v1>, … Note: state_table is expected to be in scipy’s eigsh transposed form.

Returns

table of matrix elements

Return type

ndarray

scqubits.utils.spectrum_utils.matrix_element(state1, operator, state2)

Calculate the matrix element <state1|operator|state2>.

Parameters

• state1 (ndarray or qutip.Qobj) – state vector/ket

• state2 (ndarray or qutip.Qobj) – state vector/ket

• operator (qutip.Qobj or numpy array or numpy sparse object) – representation of an operator

Returns

matrix element

Return type

float or complex

scqubits.utils.spectrum_utils.order_eigensystem(evals, evecs)

Takes eigenvalues and corresponding eigenvectors and orders them (in place) according to the eigenvalues (from smallest to largest; real valued eigenvalues are assumed). Compare http://stackoverflow.com/questions/22806398.

Parameters

• evals (ndarray) – array of eigenvalues

• evecs (ndarray) – array containing eigenvectors; evecs[:, 0] is the first eigenvector etc.

scqubits.utils.spectrum_utils.recast_esys_mapdata(esys_mapdata)

Takes data generated by a map of eigensystem calls and returns the eigenvalue and eigenstate tables

Parameters

esys_mapdata (list of tuple of ndarray) –

Returns

eigenvalues and eigenvectors

Return type

(ndarray, ndarray)

scqubits.utils.spectrum_utils.standardize_phases(complex_array)

Uses extract_phase to obtain global phase from array and returns standardized array with global phase factor standardized.

Parameters

complex_array (ndarray) – complex

Returns

Return type

ndarray (complex)

scqubits.utils.spectrum_utils.standardize_sign(real_array)

Standardizes the sign of a real-valued wavefunction by calculating the sign of the sum of all amplitudes and making it positive.

Parameters

real_array (ndarray) –

Returns

Return type

ndarray (float)

Writing/reading data to disk

Helper routines for writing data to files.

class scqubits.io_utils.fileio.FileIOFactory

Factory method for choosing reader/writer according to given format

get_reader(file_name, file_handle=None, get_external_reader=False)

Based on the extension of the provided file name, return the appropriate reader engine.

Parameters

• file_name (str) –

• file_handle (h5py.Group, optional) –

• get_external_reader (book, optional) –

Returns

Return type

H5Reader or CSVReader

get_writer(file_name, file_handle=None)

Based on the extension of the provided file name, return the appropriate writer engine.

Parameters

• file_name (str) –

• file_handle (h5py.Group, optional) –

Returns

Return type

IOWriter

class scqubits.io_utils.fileio.IOData(typename, attributes, ndarrays, objects=None)

typename: str attributes: dict of {str: number or str} ndarrays: dict of {str: ndarray} objects: dict of {str: Serializable}, optional

as_kwargs()

Return a joint dictionary of attributes, ndarrays, and objects, as used in __init__ calls

scqubits.io_utils.fileio.deserialize(iodata)

Turn IOData back into a Python object of the appropriate kind. An object is deemed deserializable if 1) it is recorded in SERIALIZABLE_REGISTRY and has a .deserialize method 2) there exists a function file_io_serializers.<typename>_deserialize

Parameters

iodata (IOData) –

Returns

Return type

class instance

scqubits.io_utils.fileio.read(filename, file_handle=None)

Read a Serializable object from file.

Parameters

• filename (str) – Name of file to be read.

• file_handle (h5py.Group, optional) – Specify Group inside h5 file if only this subgroup should be read.

Returns

class instance initialized with the data from the file

Return type

Serializable

scqubits.io_utils.fileio.serialize(the_object)

Turn the given Python object into an IOData object, needed for writing data to file.

Parameters

the_object (Serializable) –

Returns

Return type

IOData

scqubits.io_utils.fileio.write(the_object, filename, file_handle=None)

Write the_object to a file with name filename. The optional file_handle parameter is used as a group name in case of h5 files.

Parameters

• the_object (io_serializers_serializers.Serializable) – object to be written

• filename (str) – Name of file to be written.

• file_handle (h5py.Group, optional) – Name of h5 group to be used for writing (only applies to h5 output format)