Python API¤
The floquet Python API consists largely of the floquet_analysis function which initializes a FloquetAnalysis class. We can then call run(filepath)
on instances of this class to perform the Floquet simulation. The computed data is then saved both as attributes of the class and also to the file specified by filepath
, which should be a string specifying a h5py
file.
Floquet methods¤
FloquetAnalysis
¤
Bases: Serializable
Perform a floquet analysis to identify nonlinear resonances.
In most workflows, one needs only to call the run() method which performs both the displaced state fit and the Blais branch analysis. For an example workflow, see the transmon tutorial.
Parameters:
Name  Type  Description  Default 

model 
Model

Class specifying the model, including the Hamiltonian, drive amplitudes, frequencies 
required 
state_indices 
list  None

State indices of interest. Defaults to [0, 1], indicating the two lowestenergy states. 
None

options 
Options

Options for the Floquet analysis. 
Options()

init_data_to_save 
dict  None

Initial parameter metadata to save to file. Defaults to None. 
None

bare_state_array()
¤
Return array of bare states.
Used to specify initial bare states for the Blais branch analysis.
identify_floquet_modes(f_modes_energies, params_0, displaced_state, previous_coefficients)
¤
Return floquet modes with largest overlap with ideal displaced state.
Also return that overlap value.
Parameters:
Name  Type  Description  Default 

f_modes_energies 
tuple[ndarray, Qobj]

output of self.run_one_floquet(params) 
required 
params_0 
tuple[float, float]

(omega_d_0, amp_0) to use for displaced fit 
required 
displaced_state 
DisplacedState

Instance of DisplacedState 
required 
previous_coefficients 
ndarray

Coefficients from the previous amplitude range that will be used when calculating overlap of the floquet modes against the 'bare' states specified by previous_coefficients 
required 
run(filepath=None)
¤
Perform floquet analysis over range of amplitudes and drive frequencies.
This function largely performs two calculations. The first is the Xiao analysis introduced in https://arxiv.org/abs/2304.13656, fitting the extracted Floquet modes to the "ideal" displaced state which does not include resonances by design (because we fit to a low order polynomial and ignore any floquet modes with overlap with the bare state below a given threshold). This analysis produces the "scar" plots. The second is the Blais branch analysis, which tracks the Floquet modes by stepping in drive amplitude for a given drive frequency. For this reason the code is structured to parallelize over drive frequency, but scans in a loop over drive amplitude. This way the two calculations can be performed simultaneously.
A nice bonus is that both of the above mentioned calculations determine essentially independently whether a resonance occurs. In the first, it is deviation of the Floquet mode from the fitted displaced state. In the second, it is branch swapping that indicates a resonance, independent of any fit. Thus the two simulations can be used for cross validation of one another.
We perform these simulations iteratively over the drive amplitudes as specified by fit_range_fraction. This is to allow for simulations stretching to large drive amplitudes, where the overlap with the bare eigenstate would fall below the threshold (due to ac Stark shift) even in the absence of any resonances. We thus use the fit from the previous range of drive amplitudes as our new bare state.
run_one_floquet(omega_d_amp)
¤
Run one instance of the problem for a pair of drive frequency and amp.
Returns floquet modes as numpy column vectors, as well as the quasienergies.
Parameters:
Name  Type  Description  Default 

omega_d_amp 
tuple[float, float]

Pair of drive frequency and amp. 
required 
Displaced state¤
DisplacedState
¤
Class providing methods for computing displaced states.
Parameters:
Name  Type  Description  Default 

hilbert_dim 
int

Hilbert space dimension 
required 
model 
Model

Model including the Hamiltonian, drive amplitudes, frequencies, state indices 
required 
state_indices 
list

States of interest 
required 
options 
Options

Options used 
required 
bare_state_coefficients(state_idx)
¤
For bare state only component is itself.
Parameters:
Name  Type  Description  Default 

state_idx 
int

Coefficients for the state \(state_idx\rangle\) that when evaluated at any amplitude or frequency simply return the bare state. Note that this should be the actual state index, and not the array index (for instance if we have state_indices=[0, 1, 3] because we're not interested in the second excited state, for the 3rd excited state we should pass 3 here and not 2). 
required 
displaced_state(omega_d, amp, state_idx, coefficients)
¤
Construct the ideal displaced state based on a polynomial expansion.
overlap_with_bare_states(amp_idx_0, coefficients, floquet_modes)
¤
Calculate overlap of floquet modes with 'bare' states.
'Bare' here is defined loosely. For the first range of amplitudes, the bare states are truly the bare states (the coefficients are obtained from bare_state_coefficients, which give the bare states). For later ranges, we define the bare state as the state obtained from the fit from previous range, with amplitude evaluated at the lower edge of amplitudes for the new region. This is, in a sense, the most natural choice, since it is most analogous to what is done in the first window when the overlap is computed against bare eigenstates (that obviously don't have amplitude dependence). Moreover, the fit coefficients for the previous window by definition were obtained in a window that does not include the one we are currently investigating. Asking for the state with amplitude values outside of the fit window should be done at your own peril.
Parameters:
Name  Type  Description  Default 

amp_idx_0 
int

Index specifying the lower bound of the amplitude range. 
required 
coefficients 
ndarray

coefficients that specify the bare state that we calculate overlaps of Floquet modes against 
required 
floquet_modes 
ndarray

Floquet modes to be compared to the bare states given by coefficients 
required 
Returns: overlaps with shape (w,a,s) where w is the number of drive frequencies, a is the number of drive amplitudes (specified by amp_idxs) and s is the number of states we are investigating
overlap_with_displaced_states(amp_idxs, coefficients, floquet_modes)
¤
Calculate overlap of floquet modes with 'ideal' displaced states.
This is done here for a specific amplitude range.
Parameters:
Name  Type  Description  Default 

amp_idxs 
list

list of lower and upper amplitude indices specifying the range of drive amplitudes this calculation should be done for 
required 
coefficients 
ndarray

coefficients that specify the displaced state that we calculate overlaps of Floquet modes against 
required 
floquet_modes 
ndarray

Floquet modes to be compared to the displaced states given by coefficients 
required 
Returns: overlaps with shape (w,a,s) where w is the number of drive frequencies, a is the number of drive amplitudes (specified by amp_idxs) and s is the number of states we are investigating
DisplacedStateFit
¤
Bases: DisplacedState
Methods for fitting an ideal displaced state to calculated Floquet modes.
displaced_states_fit(omega_d_amp_slice, ovlp_with_bare_states, floquet_modes)
¤
Perform a fit for the indicated range, ignoring specified modes.
We loop over all states in state_indices and perform the fit for a given amplitude range. We ignore floquet modes (not included in the fit) where the corresponding value in ovlp_with_bare_states is below the threshold specified in options.
Parameters:
Name  Type  Description  Default 

omega_d_amp_slice 
list

Pairs of omega_d, amplitude values at which the floquet modes have been computed and which we will use as the independent variables to fit the Floquet modes 
required 
ovlp_with_bare_states 
ndarray

Bare state overlaps that has shape (w, a, s) where w is drive frequency, a is drive amplitude and s is state_indices 
required 
floquet_modes 
ndarray

Floquet mode array with the same shape as ovlp_with_bare_states except with an additional trailing dimension h, the Hilbertspace dimension. 
required 
Returns:
Type  Description 

ndarray

Optimized fit coefficients 
Model¤
Model
¤
Bases: Serializable
Specify the model, including the Hamiltonian, drive strengths and frequencies.
Can be subclassed to e.g. override the hamiltonian() method for a different (but still periodic!) Hamiltonian.
Parameters:
Name  Type  Description  Default 

H0 
Qobj  ndarray  list

Drift Hamiltonian, which must be diagonal and provided in units such that H0 can be passed directly to qutip. 
required 
H1 
Qobj  ndarray  list

Drive operator, which should be unitless (for instance the chargenumber operator n of the transmon). It will be multiplied by a drive amplitude that we scan over from drive_parameters.drive_amplitudes. 
required 
omega_d_values 
ndarray

drive frequencies to scan over 
required 
drive_amplitudes 
ndarray

amp values to scan over. Can be one dimensional in which case these amplitudes are used for all omega_d, or it can be two dimensional in which case the first dimension are the amplitudes to scan over and the second are the amplitudes for respective drive frequencies 
required 
amp_to_idx(amp, omega_d)
¤
Return index corresponding to amplitude value.
Because the drive amplitude can depend on the drive frequency, we also must pass the drive frequency here.
hamiltonian(omega_d_amp)
¤
Return the Hamiltonian we actually simulate.
omega_d_amp_params(amp_idxs)
¤
Return ordered chain object of the specified omega_d and amplitude values.
omega_d_to_idx(omega_d)
¤
Return index corresponding to omega_d value.
Amplitude conversion utilities¤
ChiacToAmp
¤
Convert given induced acstark shift values to drive amplitudes.
Consider a qubit coupled to an oscillator with the interaction Hamiltonian \(H_I = g(ab^{\dagger} + a^{\dagger}b)\). If the oscillator is driven to an average occupation number of \(\bar{n}\), then the effective drive strength seen by the qubit is \(\Omega_d = 2 g \sqrt{\bar{n}}\). On the other hand based on a SchriefferWolff transformation, the interaction hamiltonian is \(H^{(2)} = \chi a^{\dagger}ab^{\dagger}b\). The average induced acstark shift is then \(\chi_{ac} = \chi \bar{n}\). Thus \(\Omega_d = 2g\sqrt{\chi_{\rm ac}/\chi}\). Observe that since \(\chi \sim g^2\), \(g\) effectively cancels out and can be set to 1.
XiSqToAmp
¤
Convert given \(\xi^2\) value into a drive amplitude.
This is based on the equivalence \(\xi = 2 \Omega_d \omega_d / (\omega_d^2\omega^2)\), where in this definition \(\xi^2= 2 \chi_{\rm ac} / \alpha\) where \(\chi_{\rm ac}\) is the induced ac stark shift, \(\alpha\) is the anharmonicity and \(\Omega_d\) is the drive amplitude.
amplitudes_for_omega_d(xi_sq_linspace)
¤
Return drive amplitudes corresponding to \(\xi^2\) values.
Options¤
Options
¤
Bases: Serializable
Options for the floquet analysis.
Parameters:
Name  Type  Description  Default 

fit_range_fraction 
float

Fraction of the amplitude range to sweep over before changing the definition of the bare state to that of the fitted state from the previous range. For instance if fit_range_fraction=0.4, then the amplitude range is split up into three chunks: the first 40% of the amplitude linspace, then from 40% > 80%, then from 80% to the full range. For the first fraction of amplitudes, they are compared to the bare eigenstates for identification. For the second range, they are compared to the fitted state from the first range. And so on. Defaults to 1.0, indicating that no iteration is performed. 
1.0

floquet_sampling_time_fraction 
float

What point of the drive period we want to sample the Floquet modes. Defaults to 0.0, indicating the floquet modes at t=0*T where T is the drive period. 
0.0

fit_cutoff 
int

Cutoff for the fit polynomial of the displaced state. Defaults to 4. 
4

overlap_cutoff 
float

Cutoff for fitting overlaps. Floquet modes with overlap with the "bare" state below this cutoff are not included in the fit (as they may be experiencing a resonance). Defaults to 0.8. 
0.8

nsteps 
int

QuTiP integration parameter, number of steps the solver can take. Defaults to 30_000. 
30000

num_cpus 
int

Number of cpus to use in parallel computation of Floquet modes over the different values of omega_d, amp. Defaults to 1. 
1

save_floquet_modes 
bool

Indicating whether to save the extracted Floquet modes themselves. Such data is often unnecessary and requires a fair amount of storage, so the default is False. 
False

File utilities¤
Serializable
¤
Mixin class for reading and writing to file using h5py.
__new__(*args, **kwargs)
¤
Records which parameters should be saved so they can be passed to init.
serialize()
¤
Serialize a class so that it is ready to be written.
This method creates nested dictionaries appropriate for writing to h5 files. Importantly, we save metadata associated with the class itself and any classes it takes as input so that they can be reinstantiated later.
Returns:
Name  Type  Description 

initdata 
dict

Dictionary of data to save, in a format appropriate to pass to h5 
write_to_file(filepath, data_dict=None)
¤
Write a class and associated data to file.
The goal is to be able to read back both the data that was saved and all of the data necessary to reinitialize the class.
Parameters:
Name  Type  Description  Default 

filepath 
str  Path

Path to the file where we want to save the data. Must be an h5 or h5py file 
required 
data_dict 
dict  None

Dictionary containing various raw data to save 
None

get_init_params(obj)
¤
Returns a list of parameters entering __init__
of obj
.
read_from_file(filepath)
¤
Read a class and associated data from file.
Parameters:
Name  Type  Description  Default 

filepath 
str  Path

Path to the file containing both raw data and the information needed to reinitialize our class 
required 
Returns:
Name  Type  Description 

new_class_instance 
Serializable

Class that inherits from Serializable that was earlier written with its method write_to_file 
data_dict 
dict

Dictionary of data that was passed to write_to_file at the time 