HilbertSpace

class scqubits.core.hilbert_space.HilbertSpace(subsystem_list, interaction_list=None, ignore_low_overlap=False, evals_method=None, evals_method_options=None, esys_method=None, esys_method_options=None)

Class holding information about the full Hilbert space, usually composed of multiple subsystems. The class provides methods to turn subsystem operators into operators acting on the full Hilbert space, and establishes the interface to qutip. Returned operators are of the qutip.Qobj type. The class also provides methods for obtaining eigenvalues, absorption and emission spectra as a function of an external parameter.

Parameters:

• subsystem_list (List[QuantumSys]) – List of all quantum systems comprising the composite Hilbert space

• interaction_list (List[Union[InteractionTerm, InteractionTermStr]]) – (optional) typically, interaction terms are added one by one by means of the add_interaction method. Alternatively, a list of interaction term objects can be supplied here upon initialization of a HilbertSpace instance.

• esys_method (Union[Callable, str, None]) – method for esys diagonalization, callable or string representation

• esys_method_options (Union[dict, None]) – dictionary with esys diagonalization options

• evals_method (Union[Callable, str, None]) – method for evals diagonalization, callable or string representation

• evals_method_options (Union[dict, None]) – dictionary with evals diagonalization options

• ignore_low_overlap (bool)

Methods

HilbertSpace.__init__(subsystem_list[, ...])
HilbertSpace.add_interaction([...])	Specify the interaction between subsystems making up the HilbertSpace instance.
HilbertSpace.all_params_fixed(param_indices)	Checks whether the indices provided fix all the parameters.
HilbertSpace.annihilate(subsystem)	Annihilation operator a for subsystem
HilbertSpace.bare_eigenstates(subsys[, ...])	Return ndarray of bare eigenstates for given subsystems and parameter index.
HilbertSpace.bare_eigenvals(subsys[, ...])	Return NamedSlotsNdarray of bare eigenenergies for given subsystem, usually to be used with preslicing.
HilbertSpace.bare_hamiltonian([bare_esys])	type bare_esys: Optional[Dict[int, ndarray]]
HilbertSpace.bare_index(dressed_index[, ...])	For given dressed index, look up the corresponding bare index.
HilbertSpace.bare_productstate(bare_index)	Return the bare product state specified by bare_index.
HilbertSpace.broadcast(event, **kwargs)	Request a broadcast from CENTRAL_DISPATCH reporting event.
HilbertSpace.create()	rtype: HilbertSpace
HilbertSpace.create_from_file(filename)	Read initdata and spectral data from file, and use those to create a new SpectrumData object.
HilbertSpace.deserialize(io_data)	Take the given IOData and return an instance of the described class, initialized with the data stored in io_data.
HilbertSpace.diag_hamiltonian(subsystem[, evals])	Returns a qutip.Qobj which has the eigenenergies of the object subsystem on the diagonal.
HilbertSpace.diag_operator(diag_elements, ...)	For given diagonal elements of a diagonal operator in subsystem, return the Qobj operator for the full Hilbert space (perform wrapping in identities for other subsystems).
HilbertSpace.dressed_index(bare_labels[, ...])	For given bare product state return the corresponding dressed-state index.
HilbertSpace.eigensys([evals_count, bare_esys])	Calculates eigenvalues and eigenvectors of the full Hamiltonian.
HilbertSpace.eigenvals([evals_count, bare_esys])	Calculates eigenvalues of the full Hamiltonian.
HilbertSpace.energy_by_bare_index(bare_tuple)	Look up dressed energy most closely corresponding to the given bare-state labels
HilbertSpace.energy_by_dressed_index(...[, ...])	Look up the dressed eigenenergy belonging to the given dressed index, usually to be used with pre-slicing
HilbertSpace.filewrite(filename)	Convenience method bound to the class.
HilbertSpace.generate_bare_esys([...])	rtype: dict
HilbertSpace.generate_lookup([...])	For each parameter value of the parameter sweep, generate the map between bare states and dressed states.
HilbertSpace.get_initdata()	Returns dict appropriate for creating/initializing a new HilbertSpace object.
HilbertSpace.get_spectrum_vs_paramvals(...)	Return eigenvalues (and optionally eigenstates) of the full Hamiltonian as a function of a parameter.
HilbertSpace.get_subsys_index(subsys)	Return the index of the given subsystem in the HilbertSpace.
HilbertSpace.hamiltonian([bare_esys])	type bare_esys: Optional[Dict[int, ndarray]]
HilbertSpace.hubbard_operator(j, k, subsystem)	Hubbard operator \(|j\rangle\langle k|\) for system subsystem
HilbertSpace.interaction_hamiltonian([bare_esys])	Returns the interaction Hamiltonian, based on the interaction terms specified for the current HilbertSpace object
HilbertSpace.lookup_exists()	rtype: bool
HilbertSpace.op_in_dressed_eigenbasis(...[, ...])	Express a subsystem operator in the dressed eigenbasis of the full system (as opposed to both the "native basis" or "bare eigenbasis" of the subsystem).
HilbertSpace.receive(event, sender, **kwargs)	Receive a message from CENTRAL_DISPATCH and initiate action on it.
HilbertSpace.reset_preslicing()
HilbertSpace.serialize()	Convert the content of the current class instance into IOData format.
HilbertSpace.set_npindextuple([param_indices])	Convert the NpIndices parameter indices to a tuple of NpIndices.
HilbertSpace.standardize_eigenvector_phases()	Standardize the phases of the (dressed) eigenvectors.
HilbertSpace.subsys_by_id_str(id_str)	rtype: QuantumSys

Attributes

dimension	Returns total dimension of joint Hilbert space
hilbertspace	[Legacy] Auxiliary reference to self for compatibility with SpectrumLookupMixin class.
interaction_list	Descriptor class for properties that are to be monitored for changes.
osc_subsys_list	Descriptor for read-only properties (stored in xxx._name)
qbt_subsys_list	Descriptor for read-only properties (stored in xxx._name)
subsys_list
subsystem_count	Returns number of subsystems composing the joint Hilbert space
subsystem_dims	Returns list of the Hilbert space dimensions of each subsystem
subsystem_list

add_interaction(check_validity=True, id_str=None, **kwargs)

Specify the interaction between subsystems making up the HilbertSpace instance. add_interaction(…) offers three different interfaces:

• Simple interface for operator products

• String-based interface for more general interaction operator expressions

• General Qobj interface

1. Simple interface for operator products

   Specify ndarray, csc_matrix, or dia_matrix (subsystem operator in subsystem-internal basis) along with the corresponding subsystem

   signature:

   .add_interaction(g=<float>,
                   op1=(<ndarray>, <QuantumSystem>),
                   op2=(<csc_matrix>, <QuantumSystem>),
                    …,
                   add_hc=<bool>)
   

   Alternatively, specify subsystem operators via callable methods.

   signature:

   .add_interaction(g=<float>,
                    op1=<Callable>,
                    op2=<Callable>,
                    …,
                    add_hc=<bool>)
   

2. String-based interface for more general interaction operator expressions

   Specify a Python expression that generates the desired operator. The expression enables convenience use of basic qutip operations:

   .add_interaction(expr=<str>,
                    op1=(<str>, <ndarray>, <subsys>),
                    op2=(<str>, <Callable>),
                    …)
   

3. General Qobj operator

   Specify a fully identity-wrapped qutip.Qobj operator. Signature:

   .add_interaction(qobj=<Qobj>)
   

Parameters:

• check_validity – optional bool indicating whether to check the validity of the interaction; switch this off for speed if you are sure the interaction is valid

• id_str (Optional[str]) – optional string by which this instance can be referred to in HilbertSpace and ParameterSweep. If not provided, an id is auto-generated.

Return type:

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.

annihilate(subsystem)

Annihilation operator a for subsystem

Parameters:

subsystem (QuantumSys) – specifies subsystem in which annihilation operator acts

Return type:

qt.Qobj

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_hamiltonian(bare_esys=None)

Parameters:

bare_esys (Optional[Dict[int, ndarray]]) – optionally, the bare eigensystems for each subsystem can be provided to speed up computation; these are provided in dict form via <subsys>: esys

Return type:

Qobj

Returns:

composite Hamiltonian composed of bare Hamiltonians of subsystems independent of the external parameter

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

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

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

Return type:

HilbertSpace

Parameters:

io_data (IOData)

diag_hamiltonian(subsystem, evals=None)

Returns a qutip.Qobj which has the eigenenergies of the object subsystem on the diagonal.

Parameters:

• subsystem (QuantumSys) – Subsystem for which the Hamiltonian is to be provided.

• evals (ndarray) – Eigenenergies can be provided as evals; otherwise, they are calculated.

Return type:

qt.Qobj

diag_operator(diag_elements, subsystem)

For given diagonal elements of a diagonal operator in subsystem, return the Qobj operator for the full Hilbert space (perform wrapping in identities for other subsystems).

Parameters:

• diag_elements (ndarray) – diagonal elements of subsystem diagonal operator

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

Return type:

qt.Qobj

property dimension: int

Returns total dimension of joint Hilbert space

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.

eigensys(evals_count=6, bare_esys=None)

Calculates eigenvalues and eigenvectors of the full Hamiltonian. Qutip’s qutip.Qobj.eigenenergies() is used by default, unless self.evals_method has been set to something other than None.

Parameters:

• evals_count (int) – number of desired eigenvalues/eigenstates

• bare_esys (Optional[Dict[int, Union[ndarray, List[ndarray]]]]) – optionally, the bare eigensystems for each subsystem can be provided to speed up computation; these are provided in dict form via <subsys>: esys

Return type:

Tuple[ndarray, QutipEigenstates]

Returns:

eigenvalues and eigenvectors

eigenvals(evals_count=6, bare_esys=None)

Calculates eigenvalues of the full Hamiltonian. Qutip’s qutip.Qobj.eigenenergies() is used by default, unless self.evals_method has been set to something other than None.

Parameters:

• evals_count (int) – number of desired eigenvalues/eigenstates

• bare_esys (Optional[Dict[int, Union[ndarray, List[ndarray]]]]) – optionally, the bare eigensystems for each subsystem can be provided to speed up computation; these are provided in dict form via <subsys>: esys

Return type:

ndarray

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

filewrite(filename)

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

Return type:

None

Parameters:

filename (str)

generate_lookup(update_subsystem_indices=None)

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

Return type:

None

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)

Parameters:

update_subsystem_indices (List[int])

get_initdata()

Returns dict appropriate for creating/initializing a new HilbertSpace object.

Return type:

Dict[str, Any]

get_spectrum_vs_paramvals(param_vals, update_hilbertspace, evals_count=10, get_eigenstates=False, param_name='external_parameter', num_cpus=None)

Return eigenvalues (and optionally eigenstates) of the full Hamiltonian as a function of a parameter. Parameter values are specified as a list or array in param_vals. The Hamiltonian hamiltonian_func must be a function of that particular parameter, and is expected to internally set subsystem parameters. If a filename string is provided, then eigenvalue data is written to that file.

Parameters:

• param_vals (ndarray) – array of parameter values

• update_hilbertspace (Callable) – update_hilbertspace(param_val) specifies how a change in the external parameter affects the Hilbert space components

• evals_count (int) – number of desired energy levels (default value = 10)

• get_eigenstates (bool) – set to true if eigenstates should be returned as well (default value = False)

• param_name (str) – name for the parameter that is varied in param_vals (default value = “external_parameter”)

• num_cpus (Optional[int]) – number of cores to be used for computation (default value: settings.NUM_CPUS)

Return type:

SpectrumData

get_subsys_index(subsys)

Return the index of the given subsystem in the HilbertSpace.

Return type:

int

Parameters:

subsys (QuantumSys)

hamiltonian(bare_esys=None)

Parameters:

bare_esys (Optional[Dict[int, ndarray]]) – optionally, the bare eigensystems for each subsystem can be provided to speed up computation; these are provided in dict form via <subsys>: esys

Return type:

Qobj

Returns:

Hamiltonian of the composite system, including the interaction between components

property hilbertspace: HilbertSpace

[Legacy] Auxiliary reference to self for compatibility with SpectrumLookupMixin class.

hubbard_operator(j, k, subsystem)

Hubbard operator \(|j\rangle\langle k|\) for system subsystem

Parameters:

• j (int) – eigenstate indices for Hubbard operator

• k (int) – eigenstate indices for Hubbard operator

• subsystem (QuantumSys) – subsystem in which Hubbard operator acts

Return type:

qt.Qobj

interaction_hamiltonian(bare_esys=None)

Returns the interaction Hamiltonian, based on the interaction terms specified for the current HilbertSpace object

Parameters:

bare_esys (Optional[Dict[int, ndarray]]) – optionally, the bare eigensystems for each subsystem can be provided to speed up computation; these are provided in dict form via <subsys>: esys

Return type:

Qobj

Returns:

interaction Hamiltonian

op_in_dressed_eigenbasis(op_callable_or_tuple, truncated_dim=None, **kwargs)

Express a subsystem operator in the dressed eigenbasis of the full system (as opposed to both the “native basis” or “bare eigenbasis” of the subsystem). The returned operator should not retain memory of the Hilbert-space sizes of the underlying subsystems, thus we modify the dims of the returned operator. truncated_dim should be set to the cutoff Hilbert-space size of the dressed system: if it is set to the default value None, no cutoff of the resulting operator is made but the dims of the resulting Qobj will be [[dimension], [dimension]]

op_in_dressed_eigenbasis(…) offers two different interfaces: :rtype: qt.Qobj

1. subsystem operators may be expressed as Callables

   signature:

   .op_in_dressed_eigenbasis(op=<Callable>, truncated_dim=<int>)
   

2. subsystem operators may be passed as arrays, along with the corresponding subsystem. In this case the user must additionally specify if the operator is in the native, subsystem-internal basis or the subsystem bare eigenbasis:

   .op_in_dressed_eigenbasis(op=(<ndarray>, <subsys>),
                             truncated_dim=<int>,
                             op_in_bare_eigenbasis=<Bool>)
   

Parameters:

• op_callable_or_tuple (Union[Tuple[Union[np.ndarray, csc_matrix], QuantumSys], Callable])

• truncated_dim (Optional[int])

Return type:

qt.Qobj

receive(event, sender, **kwargs)

Receive a message from CENTRAL_DISPATCH and initiate action on it.

Parameters:

• event (str) – event name from EVENTS

• sender (Any) – original sender reporting the event

• **kwargs

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)

standardize_eigenvector_phases()

Standardize the phases of the (dressed) eigenvectors.

Return type:

None

property subsystem_count: int

Returns number of subsystems composing the joint Hilbert space

property subsystem_dims: List[int]

Returns list of the Hilbert space dimensions of each subsystem