ParameterSweep

class scqubits.core.param_sweep.ParameterSweep(hilbertspace, paramvals_by_name, update_hilbertspace, evals_count=20, subsys_update_info=None, bare_only=False, ignore_low_overlap=False, autorun=True, deepcopy=False, num_cpus=None)

Create multi-dimensional parameter sweeps for a quantum system described by a HilbertSpace object.

Parameters:

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

• paramvals_by_name (Dict[str, ndarray]) – Dictionary which specifies a parameter name for each set of parameter values, 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 subsystem by truncated_dim.) (default: 20)

• subsys_update_info (Optional[Dict[str, List[QuantumSystem]]]) –

  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)

• ignore_low_overlap (bool) – if set to False (default), bare product states and dressed eigenstates are identified if |<psi_bare|psi_dressed>|^2 > 0.5; if True, then identification will always take place based on which bare product state has the maximum overlap

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

Notes

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

Methods

ParameterSweep.__init__(hilbertspace, ...[, ...])
ParameterSweep.add_matelem_sweep(operator, ...)	Generate data for matrix elements with respect to a given operator, as a function of the sweep parameter(s)
ParameterSweep.add_sweep(sweep_function[, ...])	Add a new sweep to the ParameterSweep object.
ParameterSweep.all_params_fixed(param_indices)	Checks whether the indices provided fix all the parameters.
ParameterSweep.bare_eigenstates(subsys[, ...])	Return ndarray of bare eigenstates for given subsystems and parameter index.
ParameterSweep.bare_eigenvals(subsys[, ...])	Return NamedSlotsNdarray of bare eigenenergies for given subsystem, usually to be used with preslicing.
ParameterSweep.bare_index(dressed_index[, ...])	For given dressed index, look up the corresponding bare index.
ParameterSweep.bare_productstate(bare_index)	Return the bare product state specified by bare_index.
ParameterSweep.broadcast(event, **kwargs)	Request a broadcast from CENTRAL_DISPATCH reporting event.
ParameterSweep.cause_dispatch()	rtype: None
ParameterSweep.create_from_file(filename)	Read initdata and spectral data from file, and use those to create a new SpectrumData object.
ParameterSweep.deserialize(iodata)	Take the given IOData and return an instance of the described class, initialized with the data stored in io_data.
ParameterSweep.dressed_evals_count()	Returns number of dressed eigenvalues included in sweep.
ParameterSweep.dressed_index(bare_labels[, ...])	For given bare product state return the corresponding dressed-state index.
ParameterSweep.eigensys([param_indices])	Return the list of dressed eigenvectors
ParameterSweep.eigenvals([param_indices])	Return the array of dressed eigenenergies - primarily for running the sweep
ParameterSweep.energy_by_bare_index(bare_tuple)	Look up dressed energy most closely corresponding to the given bare-state labels
ParameterSweep.energy_by_dressed_index(...)	Look up the dressed eigenenergy belonging to the given dressed index, usually to be used with pre-slicing
ParameterSweep.faulty_interactionterm_suspected()	Check if any interaction terms are specified as fixed matrices
ParameterSweep.filewrite(filename)	Convenience method bound to the class.
ParameterSweep.generate_lookup()	For each parameter value of the parameter sweep, generate the map between bare states and dressed states.
ParameterSweep.get_subsys(index)	rtype: QuantumSystem
ParameterSweep.get_subsys_index(subsys)	rtype: int
ParameterSweep.get_sweep_indices(multi_index)	For given generalized multi-index, return a list of the indices that are being swept.
ParameterSweep.keys()
ParameterSweep.plot_transitions([...])	Plot transition energies as a function of one external parameter.
ParameterSweep.receive(event, sender, **kwargs)	Hook to CENTRAL_DISPATCH.
ParameterSweep.reset_preslicing()
ParameterSweep.run()	Create all sweep data: bare spectral data, dressed spectral data, lookup data and custom sweep data.
ParameterSweep.serialize()	Convert the content of the current class instance into IOData format.
ParameterSweep.set_npindextuple([param_indices])	Convert the NpIndices parameter indices to a tuple of NpIndices.
ParameterSweep.set_update_func(...)	Account for the two possible signatures of the update_hilbertspace function.
ParameterSweep.subsys_by_id_str(id_str)	rtype: QuantumSystem
ParameterSweep.subsys_evals_count(subsys_index)	rtype: int
ParameterSweep.transitions([as_specdata, ...])	Use dressed eigenenergy data and lookup based on bare product state labels to extract transition energy data.

Attributes

bare_specdata_list	Wrap bare eigensystem data into a SpectrumData object.
dressed_specdata	Wrap dressed eigensystem data into a SpectrumData object.
hilbertspace
osc_subsys_list
param_info	Return a dictionary of the parameter names and values used in this sweep.
parameters	Return the Parameter object (access parameter values/indexing)
qbt_subsys_list
subsystem_count
system_params
tqdm_disabled

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 (QuantumSystem) – subsystems for which to compute matrix elements, required if operator is given in str form

Return type:

None

Returns:

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

Return type:

None

Returns:

None

all_params_fixed(param_indices)

Checks whether the indices provided fix all the parameters.

Parameters:

param_indices (Union[slice, tuple]) – Tuple or slice fixing all or a subset of the parameters.

Return type:

bool

Returns:

True if all parameters are being fixed by param_indices.

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 used with pre-slicing when part of ParameterSweep.

Return type:

NamedSlotsNdarray

Parameters:

• subsys (QuantumSys)

• param_indices (Tuple[int, ...] | None)

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.

Parameters:

• dressed_index (int)

• param_indices (Tuple[int, ...] | None)

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

Parameters:

filename (str)

classmethod deserialize(iodata)

Take the given IOData and return an instance of the described class, initialized with the data stored in io_data.

Return type:

StoredSweep

Parameters:

iodata (IOData)

dressed_evals_count()

Returns number of dressed eigenvalues included in sweep.

Return type:

int

dressed_index(bare_labels, param_npindices=None)

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

Parameters:

• bare_labels (Tuple[int, ...]) – bare_labels = (index, index2, …) Dimension: (self.hilbertspace.subsystem_count,)

• param_npindices (Union[int, slice, Tuple[int], List[int], Tuple[Union[int, slice, Tuple[int], List[int]], ...], None]) – indices of parameter values of interest Depending on the nature of the slice, this can be a single parameter point or multiple ones.

Return type:

Union[ndarray, int, None]

Returns:

dressed state index closest to the specified bare state with excitation numbers given by bare_labels. If param_npindices spans multiple parameter points, then this returns a corresponding 1d array of length dictated by the number of parameter points.

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)

• param_indices (Tuple[int, ...] | None)

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_npindices=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_npindices (Union[int, slice, Tuple[int], List[int], Tuple[Union[int, slice, Tuple[int], List[int]], ...], None]) – indices specifying the set of parameters

Return type:

Union[float, 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:

Union[float, NamedSlotsNdarray]

Returns:

dressed energy

faulty_interactionterm_suspected()

Check if any interaction terms are specified as fixed matrices

Return type:

bool

filewrite(filename)

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

Return type:

None

Parameters:

filename (str)

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]

Parameters:

multi_index (Tuple[int | float | complex | slice | Tuple[int] | List[int], ...])

property param_info: Dict[str, ndarray]

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

property parameters: Parameters

Return the Parameter object (access parameter values/indexing)

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[QuantumSystem, List[QuantumSystem], 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: the initial state can either be specified as a tuple referring to a bare product state, or as an integer representing the dressed state index. For bare product states, the required tuple has as many entries as the underlying HilbertSpace object has subsystems. (If subsystems is given, then the tuple may be reduced to entries for just these subsystems; other subsystems are given a “0” entry automatically.) The dressed state corresponding to the given bare product state is determined by considerations of overlaps. Note: for an initial dressed state, the sidebands option is ignored.

• final (Union[int, Tuple[int, ...], None]) – concrete final state for which the transition energy should be generated, given either as a bare product state (tuple of excitation numbers), or as a dressed state (non-negative integer). If final is omitted a list of final states is generated for dispersive transitions within each (active) subsystem. Sidebands can be switched on with the subsequent keyword option. final=-1 can be chosen for a final state list to all other dressed states (helpful when the dispersive limit breaks down).

• sidebands (bool) – if set to true, sideband transitions with multiple subsystems changing excitation levels are included (default: False). This option is ignored if initial is given as an integer dressed state index.

• 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; for “plain” no selective highlighting is attempted.

• 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:

Plot Figure and Axes objects

receive(event, sender, **kwargs)

Hook to CENTRAL_DISPATCH. This method is accessed by the global CentralDispatch instance whenever an event occurs that ParameterSweep is registered for. In reaction to update events, the lookup table is marked as out of sync.

Parameters:

• event (str) – type of event being received

• sender (object) – identity of sender announcing the event

• **kwargs

Return type:

None

run()

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

Return type:

None

serialize()

Convert the content of the current class instance into IOData format.

Return type:

IOData

set_npindextuple(param_indices=None)

Convert the NpIndices parameter indices to a tuple of NpIndices.

Return type:

Tuple[Union[int, slice, Tuple[int], List[int]], ...]

Parameters:

param_indices (int | slice | Tuple[int] | List[int] | Tuple[int | slice | Tuple[int] | List[int], ...] | 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

Parameters:

update_hilbertspace (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[QuantumSystem, List[QuantumSystem], 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 either (1) as a bare product state (tuple of excitation numbers of all subsystems or of the active ones given in subsystems); or (2) as a dressed-state index in the form of an integer >= 0. (default: (0,0,…,0) which is usually closest to the ground state)

• final (Union[int, Tuple[int, ...], None]) – concrete final state for which the transition energy should be generated, given either as a bare product state (tuple of excitation numbers), or as a dressed state (non-negative integer). If final is omitted a list of final states is generated for dispersive transitions within each (active) subsystem. Sidebands can be switched on with the subsequent keyword option. final=-1 can be chosen for a final state list to all other dressed states (helpful when the dispersive limit breaks down).

• 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[Union[int, Tuple[int, ...]], Union[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.