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 (Iterable[float]) – x values for the x-y evaluation grid

• y_vals (Iterable[float]) – y values for the x-y evaluation grid

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

• contour_vals (Optional[Iterable[float]]) – contour values can be specified if so desired

• show_colorbar (bool) –

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

Return type

Tuple[Figure, Axes]

Returns

matplotlib objects for further editing

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

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

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

• label_list (Union[List[str], List[int], None]) – list of labels associated with the individual curves to be plotted

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

Return type

Tuple[Figure, Axes]

Returns

matplotlib objects for further editing

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 (Union[int, Iterable[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 (Optional[List[str]]) – list of labels associated with the individual curves to be plotted

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

Return type

Tuple[Figure, Axes]

Returns

matplotlib objects for further editing

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 (Union[int, List[Tuple[int, int]]]) – either maximum index of desired matrix elements, or list [(i1, i2), (i3, i4), …] of index tuples for specific desired matrix elements

• mode (str) – choice of processing function to be applied to data (default value = ‘abs’)

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

Return type

matplotlib objects for further editing

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) – 2d matrix data

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

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

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

Return type

Tuple[Figure, Tuple[Axes, Axes]]

Returns

figure and axes objects for further editing

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) – 2d matrix data

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

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

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

Return type

Tuple[Figure, Axes]

Returns

figure and axes objects for further editing

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

Display a 3d skyscraper plot of the matrix

Parameters

• matrix (ndarray) – 2d matrix data

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

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

Return type

Tuple[Figure, Axes]

Returns

figure and axes objects for further editing

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

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

Parameters

• wavefuncs (Union[WaveFunction, List[WaveFunction]]) – basis and amplitude data of wave function to be plotted

• potential_vals (Optional[ndarray]) – potential energies, array length must match basis array of wavefunc

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

• scaling (Optional[float]) – scaling factor for wave function amplitudes

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

Return type

Tuple[Figure, Axes]

Returns

matplotlib objects for further editing

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) – basis and amplitude data of wave function to be plotted

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

Return type

Tuple[Figure, Axes]

Returns

matplotlib objects for further editing

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) – basis and amplitude data of wave function to be plotted

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

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

Return type

Tuple[Figure, Axes]

Returns

matplotlib objects for further editing

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.

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.

Return type

csc_matrix

scqubits.core.operators.creation(dimension)

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

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

Return type

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

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

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

Return type

csc_matrix

Returns

sparse number operator matrix, size dimension x dimension

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) – matrix dimension

• prefactor (Union[float, complex, None]) – prefactor multiplying the number operator matrix

Return type

ndarray

Returns

number operator matrix, size dimension x dimension

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

prefactor (Union[float, complex, None]) – prefactor multiplying the number operator matrix

Return type

dia_matrix

Returns

sparse number operator matrix, size dimension x dimension

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.

Return type

SpectrumData

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

Return type

float

Returns

element from dressed_energy_vals closest to bare_energy

scqubits.utils.spectrum_utils.convert_evecs_to_ndarray(evecs_qutip)

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

Parameters

evecs_qutip (ndarray) – ndarray of eigenstates in qt.Qobj format

Return type

ndarray

Returns

converted eigenstate data

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.

Return type

SpectrumData

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 as follows. Find the maximum between the leftmost point and the halfway point of the wavefunction. The position of that point is used to determine the phase factor to be eliminated.

Parameters

• complex_array (ndarray) – complex-valued array

• position (Optional[int]) – position where the phase is extracted (default value = None)

Return type

float

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[int, ...]) – bare-state labels of the initial state whose energy is supposed to be subtracted from the spectral data

Return type

List[Tuple[int, ...]]

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 (QutipEigenstates) – as obtained from qutip .eigenstates()

• reference_state_qobj (Qobj) – specific reference state

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

Return type

Union[int, Tuple[int, float], None]

Returns

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

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

Calculates a table of matrix elements.

Parameters

• operator (Union[ndarray, csc_matrix, dia_matrix, Qobj]) – operator with respect to which matrix elements are to be calculated

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

Return type

ndarray

Returns

table of matrix elements

scqubits.utils.spectrum_utils.identity_wrap(operator, subsystem, subsys_list, op_in_eigenbasis=False, evecs=None)

Wrap given operator in subspace subsystem in identity operators to form full Hilbert-space operator.

Parameters

• operator (Union[str, ndarray, Qobj]) – operator acting in Hilbert space of subsystem; if str, then this should be an operator name in the subsystem, typically not in eigenbasis

• subsystem (QuantumSys) – subsystem where diagonal operator is defined

• subsys_list (List[QuantumSys]) – list of all subsystems relevant to the Hilbert space.

• op_in_eigenbasis (bool) – whether operator is given in the subsystem eigenbasis; otherwise, the internal QuantumSys basis is assumed

• evecs (ndarray) – internal QuantumSys eigenstates, used to convert operator into eigenbasis

Return type

Qobj

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

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

Parameters

• state1 (Union[ndarray, Qobj]) – state vector/ket

• state2 (Union[ndarray, Qobj]) – state vector/ket

• operator (Union[ndarray, csc_matrix, Qobj]) – representation of an operator

Return type

Union[float, complex]

Returns

matrix element

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.

Return type

Tuple[ndarray, ndarray]

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

Return type

Union[Tuple[ndarray, List[QutipEigenstates]], Tuple[ndarray, List[ndarray]]]

Returns

eigenvalues and eigenvectors

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

Return type

ndarray

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 up to the wavefunctions mid-position and making it positive.

Summing up to the midpoint only is to address the danger that the sum is actually zero, which may is the case for odd wavefunctions taken over an interval centered at zero.

Return type

ndarray

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=None)

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

Return type

Union[CSVReader, H5Reader]

get_writer(file_name, file_handle=None)

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

Return type

IOWriter

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

Class for processing input/output data

as_kwargs()

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

Return type

Dict[str, Any]

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

Return type

Any

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 (Optional[Group]) – Specify Group inside h5 file if only this subgroup should be read.

Return type

Any

Returns

class instance initialized with the data from the file

scqubits.io_utils.fileio.serialize(the_object)

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

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 (Any) – object to be written

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

• file_handle (Optional[Group]) – Name of h5 group to be used for writing (only applies to h5 output format)

Return type

None