ParameterSweep Class

ParameterSweep

class scqubits.ParameterSweep(hilbertspace, paramvals_by_name, update_hilbertspace, evals_count=20, subsys_update_info=None, bare_only=False, autorun=True, deepcopy=False, num_cpus=None)[source]

ParameterSweep supports array-like access (“pre-slicing”) and dict-like access. With dict-like access via string-keywords <ParameterSweep>[<str>], the following data is returned:

“evals” and “evecs”

dressed eigenenergies and eigenstates as NamedSlotsNdarray; eigenstates are decomposed in the bare product-state basis of the non-interacting subsystems’ eigenbases

“bare_evals” and “bare_evecs”

bare eigenenergies and eigenstates as NamedSlotsNdarray

“lamb”, “chi”, and “kerr”

dispersive energy coefficients

“<custom sweep>”

NamedSlotsNdarray for custom data generated with add_sweep.

Array-like access is responsible for “pre-slicing”, enable lookup functionality such as <Sweep>[p1, p2, …].eigensys()

Parameters
  • hilbertspace (HilbertSpace) – HilbertSpace object describing the quantum system of interest

  • paramvals_by_name (Dict[str, ndarray]) – Dictionary that, for each set of parameter values, specifies a parameter name and the set of values to be used in the sweep.

  • update_hilbertspace (Callable) – function that updates the associated hilbertspace object with a given set of parameters; signature is either update_hilbertspace(paramval1, paramval2, …) or update_hilbertspace(self, paramval1, paramval2, …) where self makes the ParameterSweep instance available, and thereby dict-like access to subsystems and interaction terms

  • evals_count (int) – number of dressed eigenvalues/eigenstates to keep. (The number of bare eigenvalues/eigenstates is determined for each subsystems by truncated_dim.) [default: 20]

  • subsys_update_info (Optional[Dict[str, List[Union[QubitBaseClass, Oscillator, KerrOscillator, GenericQubit]]]]) –

    To speed up calculations, the user may provide information that specifies which subsystems are being updated for each of the given parameter sweeps. This information is specified by a dictionary of the following form:

    {
        "<parameter name 1>": [<subsystem a>],
        "<parameter name 2>": [<subsystem b>, <subsystem c>, ...],
        ...
    }
    

    This indicates that changes in <parameter name 1> only require updates of <subsystem a> while leaving other subsystems unchanged. Similarly, sweeping <parameter name 2> affects <subsystem b>, <subsystem c> etc.

  • bare_only (bool) – if set to True, only bare eigendata is calculated; useful when performing a sweep for a single quantum system, no interaction (default: False)

  • autorun (bool) – Determines whether to directly run the sweep or delay it until .run() is called manually. (Default: settings.AUTORUN_SWEEP=True)

  • deepcopy (bool) – if set to True, the parameter sweep is run with an exact copy of the Hilbert space; this ensures that all parameters after the sweep are identical to parameters before the sweep. Note: changing global HilbertSpace or QuantumSystem attributes will have no effect with this option; all updates must be made via `<ParameterSweep>.hilbertspace[<id_str>] = … If set to False (default), updates to global instances have the expected effect. The HilbertSpace object and all its constituent parts are left in the state reached by the very final parameter update.

  • num_cpus (Optional[int]) – number of CPU cores requested for computing the sweep (default value settings.NUM_CPUS)

add_matelem_sweep(operator, sweep_name, subsystem=None)

Generate data for matrix elements with respect to a given operator, as a function of the sweep parameter(s)

Parameters
  • operator (Union[str, Qobj]) – name of the operator in question (str), or full operator in Qobj form

  • sweep_name (str) – The sweep data will be accessible as <ParameterSweep>[<sweep_name>]

  • subsystem (Union[ForwardRef, ForwardRef, ForwardRef, ForwardRef, None]) – subsystems for which to compute matrix elements, required if operator is given in str form

Returns

Return type

None; results are saved as <ParameterSweep>[<sweep_name>]

add_sweep(sweep_function, sweep_name=None, **kwargs)

Add a new sweep to the ParameterSweep object. The generated data is subsequently accessible through <ParameterSweep>[<sweep_function>] or <ParameterSweep>[<sweep_name>]

Parameters
  • sweep_function (Union[str, Callable]) – name of a sweep function in scq.sweeps as str, or custom function ( callable) provided by the user

  • sweep_name (Optional[str]) – if given, the generated data is stored in <ParameterSweep>[<sweep_name>] rather than [<sweep_name>]

  • kwargs – keyword arguments handed over to the sweep function

Returns

Return type

None

bare_eigenstates(subsys, param_indices=None)

Return ndarray of bare eigenstates for given subsystems and parameter index. Eigenstates are expressed in the basis internal to the subsystems. Usually to be with pre-slicing.

Return type

NamedSlotsNdarray

bare_eigenvals(subsys, param_indices=None)

Return NamedSlotsNdarray of bare eigenenergies for given subsystem, usually to be used with preslicing.

Parameters
  • subsys (QuantumSys) – Hilbert space subsystem for which bare eigendata is to be looked up

  • param_indices (Optional[Tuple[int, …]]) – position indices of parameter values in question

Return type

NamedSlotsNdarray

Returns

  • bare eigenenergies for the specified subsystem and the external parameter

  • fixed to the value indicated by its index

bare_index(dressed_index, param_indices=None)

For given dressed index, look up the corresponding bare index.

Return type

Optional[Tuple[int, …]]

Returns

  • Bare state specification in tuple form. Example ((1,0,3) means subsystem 1)

  • is in bare state 1, subsystem 2 in bare state 0,

  • and subsystem 3 in bare state 3.

bare_productstate(bare_index)

Return the bare product state specified by bare_index. Note: no parameter dependence here, since the Hamiltonian is always represented in the bare product eigenbasis.

Parameters

bare_index (Tuple[int, …]) –

Returns

Return type

ket in full Hilbert space

property bare_specdata_list: List[scqubits.core.storage.SpectrumData]

Wrap bare eigensystem data into a SpectrumData object. To be used with pre-slicing, e.g. <ParameterSweep>[0, :].bare_specdata_list

Returns

Return type

List of SpectrumData objects with bare eigensystem data, one per subsystem

broadcast(event, **kwargs)

Request a broadcast from CENTRAL_DISPATCH reporting event.

Parameters
  • event (str) – event name from EVENTS

  • **kwargs

Return type

None

classmethod create_from_file(filename)

Read initdata and spectral data from file, and use those to create a new SpectrumData object.

Returns

new SpectrumData object, initialized with data read from file

Return type

SpectrumData

dressed_index(bare_labels, param_indices=None)

For given bare product state return the corresponding dressed-state index.

Parameters
  • bare_labels (Tuple[int, …]) – bare_labels = (index, index2, …)

  • param_indices (Union[int, slice, Tuple[int], List[int], Tuple[Union[int, slice, Tuple[int], List[int]], …], None]) – indices of parameter values of interest

Returns

Return type

dressed state index closest to the specified bare state

property dressed_specdata: scqubits.core.storage.SpectrumData

Wrap dressed eigensystem data into a SpectrumData object. To be used with pre-slicing, e.g. <ParameterSweep>[0, :].dressed_specdata

Returns

Return type

SpectrumData object with bare eigensystem data

eigensys(param_indices=None)

Return the list of dressed eigenvectors

Parameters

param_indices (Optional[Tuple[int, …]]) – position indices of parameter values in question

Return type

ndarray

Returns

  • dressed eigensystem for the external parameter fixed to the value indicated

  • by the provided index

eigenvals(param_indices=None)

Return the array of dressed eigenenergies - primarily for running the sweep

Parameters

question (position indices of parameter values in) –

Return type

ndarray

Returns

  • dressed eigenenergies for the external parameters fixed to the values

  • indicated by the provided indices

energy_by_bare_index(bare_tuple, subtract_ground=False, param_indices=None)

Look up dressed energy most closely corresponding to the given bare-state labels

Parameters
  • bare_tuple (Tuple[int, …]) – bare state indices

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

  • param_indices (Union[int, slice, Tuple[int], List[int], Tuple[Union[int, slice, Tuple[int], List[int]], …], None]) – indices specifying the set of parameters

Returns

Return type

dressed energies, if lookup successful, otherwise nan;

energy_by_dressed_index(dressed_index, subtract_ground=False, param_indices=None)

Look up the dressed eigenenergy belonging to the given dressed index, usually to be used with pre-slicing

Parameters
  • dressed_index (int) – index of dressed state of interest

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

  • param_indices (Optional[Tuple[int, …]]) – specifies the desired choice of parameter values

Returns

Return type

dressed energy

filewrite(filename)

Convenience method bound to the class. Simply accesses the write function.

Return type

None

generate_lookup()

For each parameter value of the parameter sweep, generate the map between bare states and dressed states.

Return type

NamedSlotsNdarray

Returns

  • each list item is a list of dressed indices whose order corresponds to the

  • ordering of bare indices (as stored in .canonical_bare_labels,

  • thus establishing the mapping)

get_sweep_indices(multi_index)

For given generalized multi-index, return a list of the indices that are being swept.

Return type

List[int]

property param_info: Dict[str, numpy.ndarray]

Return a dictionary of the parameter names and values used in this sweep.

Return type

Dict[str, ndarray]

plot_transitions(subsystems=None, initial=None, final=None, sidebands=False, photon_number=1, make_positive=True, coloring='transition', param_indices=None, **kwargs)

Plot transition energies as a function of one external parameter. Usage is based on preslicing of the ParameterSweep object to select a single parameter to be involved in the sweep. E.g.,

<ParameterSweep>[0, :, 2].plot_transitions()

plots all eigenenergy differences for transitions starting in the ground state (default when no initial state is specified) as a function of the middle parameter while parameters 1 and 3 are fixed by the indices 0 and 2.

Parameters
  • subsystems (Union[QubitBaseClass, Oscillator, KerrOscillator, GenericQubit, List[Union[QubitBaseClass, Oscillator, KerrOscillator, GenericQubit]], None]) – single subsystems or list of subsystems considered as “active” for the transitions to be generated; if omitted as a parameter, all subsystems are considered as actively participating in the transitions

  • initial (Union[int, Tuple[int, …], None]) – initial state from which transitions originate, specified as a bare product state of either all subsystems the subset of active subsystems (default: ground state of the system)

  • final (Union[int, Tuple[int, …], None]) – concrete final state for which the transition energy should be generated; if not provided, a list of allowed final states is generated

  • sidebands (bool) – if set to true, sideband transitions with multiple subsystems changing excitation levels are included (default: False)

  • photon_number (int) – number of photons involved in transition; transition frequencies are divided by this number (default: photon_number=1, i.e., single-photon transitions)

  • make_positive (bool) – boolean option relevant if the initial state is an excited state; downwards transition energies would regularly be negative, but are converted to positive if this flag is set to True (default: True)

  • coloring (Union[str, ndarray]) – For “transition” (default), transitions are colored by their dispersive nature; “plain”, curves are colored naively

  • param_indices (Union[int, slice, Tuple[int], List[int], Tuple[Union[int, slice, Tuple[int], List[int]], …], None]) – usually to be omitted, as param_indices will be set via pre-slicing

Return type

Tuple[Figure, Axes]

Returns

  • A tuple consisting of a list of all the transitions and a corresponding

  • list of difference energies, e.g.

  • ((0,0,0), (0,0,1)), <energy array for transition 0,0,0 -> 0,0,1>.

  • If as_specdata is set to True, a SpectrumData object is returned instead,

  • saving transition label info in an attribute named labels.

run()[source]

Create all sweep data: bare spectral data, dressed spectral data, lookup data and custom sweep data.

Return type

None

set_update_func(update_hilbertspace)

Account for the two possible signatures of the update_hilbertspace function. Inspect whether a self argument is given. If not, return a function that accepts self as a dummy argument.

Return type

Callable

transitions(as_specdata=False, subsystems=None, initial=None, final=None, sidebands=False, photon_number=1, make_positive=False, param_indices=None)

Use dressed eigenenergy data and lookup based on bare product state labels to extract transition energy data. Usage is based on preslicing to select all or a subset of parameters to be involved in the sweep, e.g.,

<ParameterSweep>[0, :, 2].transitions()

produces all eigenenergy differences for transitions starting in the ground state (default when no initial state is specified) as a function of the middle parameter while parameters 1 and 3 are fixed by the indices 0 and 2.

Parameters
  • subsystems (Union[QubitBaseClass, Oscillator, KerrOscillator, GenericQubit, List[Union[QubitBaseClass, Oscillator, KerrOscillator, GenericQubit]], None]) – single subsystems or list of subsystems considered as “active” for the transitions to be generated; if omitted as a parameter, all subsystems are considered as actively participating in the transitions

  • initial (Union[int, Tuple[int, …], None]) – initial state from which transitions originate, specified as a bare product state of either all subsystems the subset of active subsystems (default: ground state of the system)

  • final (Optional[Tuple[int, …]]) – concrete final state for which the transition energy should be generated; if not provided, a list of allowed final states is generated

  • sidebands (bool) – if set to true, sideband transitions with multiple subsystems changing excitation levels are included (default: False)

  • photon_number (int) – number of photons involved in transition; transition frequencies are divided by this number (default: photon_number=1, i.e., single-photon transitions)

  • make_positive (bool) – boolean option relevant if the initial state is an excited state; downwards transition energies would regularly be negative, but are converted to positive if this flag is set to True

  • as_specdata (bool) – whether data is handed back in raw array form or wrapped into a SpectrumData object (default: False)

  • param_indices (Union[int, slice, Tuple[int], List[int], Tuple[Union[int, slice, Tuple[int], List[int]], …], None]) – usually to be omitted, as param_indices will be set via pre-slicing

Return type

Union[Tuple[List[Tuple[Tuple[int, …], Tuple[int, …]]], List[NamedSlotsNdarray]], SpectrumData]

Returns

  • A tuple consisting of a list of all the transitions and a corresponding

  • list of difference energies, e.g.

  • ((0,0,0), (0,0,1)), <energy array for transition 0,0,0 -> 0,0,1>.

  • If as_specdata is set to True, a SpectrumData object is returned instead,

  • saving transition label info in an attribute named labels.