ParameterSweep Class

ParameterSweep

class scqubits.ParameterSweep(hilbertspace, paramvals_by_name, update_hilbertspace, evals_count=20, subsys_update_info=None, bare_only=False, autorun=True, 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

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

    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)

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

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

Return type

None

Returns

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 (QuantumSystem) – 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, ...]) –

Return type

Qobj

Returns

ket in full Hilbert space

property bare_specdata_list: List[SpectrumData]

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

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

Return type

Union[ndarray, int, None]

Returns

dressed state index closest to the specified bare state

property dressed_specdata: SpectrumData

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

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

Return type

NamedSlotsNdarray

Returns

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

Return type

float

Returns

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]

matrix_elements(operator_name, sweep_name, subsystem)

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

Parameters
  • operator_name (str) – name of the operator in question

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

  • subsystem (Union[QubitBaseClass, Oscillator]) – subsystems for which to compute matrix elements.

Return type

None

Returns

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

property param_info: Dict[str, ndarray]

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

plot_transitions(subsystems=None, initial=None, final=None, sidebands=False, 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, List[Union[QubitBaseClass, Oscillator]], 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)

  • 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

transitions(subsystems=None, initial=None, final=None, sidebands=False, make_positive=False, as_specdata=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, List[Union[QubitBaseClass, Oscillator]], 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)

  • 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[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.