qutip_qtrl.pulseoptim

Wrapper functions that will manage the creation of the objects, build the configuration, and execute the algorithm required to optimise a set of ctrl pulses for a given (quantum) system. The fidelity error is some measure of distance of the system evolution from the given target evolution in the time allowed for the evolution. The functions minimise this fidelity error wrt the piecewise control amplitudes in the timeslots

There are currently two quantum control pulse optmisations algorithms implemented in this library. There are accessible through the methods in this module. Both the algorithms use the scipy.optimize methods to minimise the fidelity error with respect to to variables that define the pulse.

GRAPE

The default algorithm (as it was implemented here first) is GRAPE GRadient Ascent Pulse Engineering [1][2]. It uses a gradient based method such as BFGS to minimise the fidelity error. This makes convergence very quick when an exact gradient can be calculated, but this limits the factors that can taken into account in the fidelity.

CRAB

The CRAB [3][4] algorithm was developed at the University of Ulm. In full it is the Chopped RAndom Basis algorithm. The main difference is that it reduces the number of optimisation variables by defining the control pulses by expansions of basis functions, where the variables are the coefficients. Typically a Fourier series is chosen, i.e. the variables are the Fourier coefficients. Therefore it does not need to compute an explicit gradient. By default it uses the Nelder-Mead method for fidelity error minimisation.

References

1. N Khaneja et. al. Optimal control of coupled spin dynamics: Design of NMR pulse sequences by gradient ascent algorithms. J. Magn. Reson. 172, 296–305 (2005).

2. Shai Machnes et.al DYNAMO - Dynamic Framework for Quantum Optimal Control arXiv.1011.4874

3. Doria, P., Calarco, T. & Montangero, S. Optimal Control Technique for Many-Body Quantum Dynamics. Phys. Rev. Lett. 106, 1–4 (2011).

4. Caneva, T., Calarco, T. & Montangero, S. Chopped random-basis quantum optimization. Phys. Rev. A - At. Mol. Opt. Phys. 84, (2011).

Functions

create_pulse_optimizer(drift, ctrls, ...[, ...])	Generate the objects of the appropriate subclasses required for the pulse optmisation based on the parameters given Note this method may be preferable to calling optimize_pulse if more detailed configuration is required before running the optmisation algorthim, or the algorithm will be run many times, for instances when trying to finding global the optimum or minimum time optimisation
opt_pulse_crab(drift, ctrls, initial, target)	Optimise a control pulse to minimise the fidelity error.
opt_pulse_crab_unitary(H_d, H_c, U_0, U_targ)	Optimise a control pulse to minimise the fidelity error, assuming that the dynamics of the system are generated by unitary operators.
optimize_pulse(drift, ctrls, initial, target)	Optimise a control pulse to minimise the fidelity error.
optimize_pulse_unitary(H_d, H_c, U_0, U_targ)	Optimise a control pulse to minimise the fidelity error, assuming that the dynamics of the system are generated by unitary operators.

qutip_qtrl.pulseoptim.create_pulse_optimizer(drift, ctrls, initial, target, num_tslots=None, evo_time=None, tau=None, amp_lbound=None, amp_ubound=None, fid_err_targ=1e-10, min_grad=1e-10, max_iter=500, max_wall_time=180, alg='GRAPE', alg_params=None, optim_params=None, optim_method='DEF', method_params=None, optim_alg=None, max_metric_corr=None, accuracy_factor=None, dyn_type='GEN_MAT', dyn_params=None, prop_type='DEF', prop_params=None, fid_type='DEF', fid_params=None, phase_option=None, fid_err_scale_factor=None, tslot_type='DEF', tslot_params=None, amp_update_mode=None, init_pulse_type='DEF', init_pulse_params=None, pulse_scaling=1.0, pulse_offset=0.0, ramping_pulse_type=None, ramping_pulse_params=None, log_level=0, gen_stats=False)

Generate the objects of the appropriate subclasses required for the pulse optmisation based on the parameters given Note this method may be preferable to calling optimize_pulse if more detailed configuration is required before running the optmisation algorthim, or the algorithm will be run many times, for instances when trying to finding global the optimum or minimum time optimisation

Parameters:

driftQobj or list of Qobj

The underlying dynamics generator of the system can provide list (of length num_tslots) for time dependent drift.

ctrlsList of Qobj or array like [num_tslots, evo_time]

A list of control dynamics generators. These are scaled by the amplitudes to alter the overall dynamics. Array-like input can be provided for time dependent control generators.

initialQobj

Starting point for the evolution. Typically the identity matrix.

targetQobj

Target transformation, e.g. gate or state, for the time evolution.

num_tslotsinteger or None

Number of timeslots. None implies that timeslots will be given in the tau array.

evo_timefloat or None

Total time for the evolution. None implies that timeslots will be given in the tau array.

tauarray[num_tslots] of floats or None

Durations for the timeslots. If this is given then num_tslots and evo_time are dervived from it. None implies that timeslot durations will be equal and calculated as evo_time/num_tslots.

amp_lboundfloat or list of floats

Lower boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

amp_uboundfloat or list of floats

Upper boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

fid_err_targfloat

Fidelity error target. Pulse optimisation will terminate when the fidelity error falls below this value.

mim_gradfloat

Minimum gradient. When the sum of the squares of the gradients wrt to the control amplitudes falls below this value, the optimisation terminates, assuming local minima.

max_iterinteger

Maximum number of iterations of the optimisation algorithm.

max_wall_timefloat

Maximum allowed elapsed time for the optimisation algorithm.

algstring

Algorithm to use in pulse optimisation. Options are:

• ‘GRAPE’ (default) - GRadient Ascent Pulse Engineering

• ‘CRAB’ - Chopped RAndom Basis

alg_paramsDictionary

options that are specific to the algorithm see above

optim_paramsDictionary

The key value pairs are the attribute name and value used to set attribute values. Note: attributes are created if they do not exist already, and are overwritten if they do. Note: method_params are applied afterwards and so may override these.

optim_methodstring

a scipy.optimize.minimize method that will be used to optimise the pulse for minimum fidelity error Note that FMIN, FMIN_BFGS & FMIN_L_BFGS_B will all result in calling these specific scipy.optimize methods Note the LBFGSB is equivalent to FMIN_L_BFGS_B for backwards capatibility reasons. Supplying DEF will given alg dependent result:

• GRAPE - Default optim_method is FMIN_L_BFGS_B

• CRAB - Default optim_method is Nelder-Mead

method_paramsdict

Parameters for the optim_method. Note that where there is an attribute of the Optimizer object or the termination_conditions matching the key that attribute. Otherwise, and in some case also, they are assumed to be method_options for the scipy.optimize.minimize method.

optim_algstring

Deprecated. Use optim_method.

max_metric_corrinteger

Deprecated. Use method_params instead

accuracy_factorfloat

Deprecated. Use method_params instead

dyn_typestring

Dynamics type, i.e. the type of matrix used to describe the dynamics. Options are UNIT, GEN_MAT, SYMPL (see Dynamics classes for details)

dyn_paramsdict

Parameters for the Dynamics object The key value pairs are assumed to be attribute name value pairs They applied after the object is created

prop_typestring

Propagator type i.e. the method used to calculate the propagtors and propagtor gradient for each timeslot options are DEF, APPROX, DIAG, FRECHET, AUG_MAT DEF will use the default for the specific dyn_type (see PropagatorComputer classes for details)

prop_paramsdict

Parameters for the PropagatorComputer object The key value pairs are assumed to be attribute name value pairs They applied after the object is created

fid_typestring

Fidelity error (and fidelity error gradient) computation method Options are DEF, UNIT, TRACEDIFF, TD_APPROX DEF will use the default for the specific dyn_type (See FidelityComputer classes for details)

fid_paramsdict

Parameters for the FidelityComputer object The key value pairs are assumed to be attribute name value pairs They applied after the object is created

phase_optionstring

Deprecated. Pass in fid_params instead.

fid_err_scale_factorfloat

Deprecated. Use scale_factor key in fid_params instead.

tslot_typestring

Method for computing the dynamics generators, propagators and evolution in the timeslots. Options: DEF, UPDATE_ALL, DYNAMIC UPDATE_ALL is the only one that currently works (See TimeslotComputer classes for details)

tslot_paramsdict

Parameters for the TimeslotComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

amp_update_modestring

Deprecated. Use tslot_type instead.

init_pulse_typestring

type / shape of pulse(s) used to initialise the the control amplitudes. Options (GRAPE) include:

RND, LIN, ZERO, SINE, SQUARE, TRIANGLE, SAW DEF is RND

(see PulseGen classes for details) For the CRAB the this the guess_pulse_type.

init_pulse_paramsdict

Parameters for the initial / guess pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

pulse_scalingfloat

Linear scale factor for generated initial / guess pulses By default initial pulses are generated with amplitudes in the range (-1.0, 1.0). These will be scaled by this parameter

pulse_offsetfloat

Linear offset for the pulse. That is this value will be added to any initial / guess pulses generated.

ramping_pulse_typestring

Type of pulse used to modulate the control pulse. It’s intended use for a ramping modulation, which is often required in experimental setups. This is only currently implemented in CRAB. GAUSSIAN_EDGE was added for this purpose.

ramping_pulse_paramsdict

Parameters for the ramping pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created

log_levelinteger

level of messaging output from the logger. Options are attributes of qutip_qtrl.logging_utils, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN

gen_statsboolean

if set to True then statistics for the optimisation run will be generated - accessible through attributes of the stats object

Returns:

optOptimizer

Instance of an Optimizer, through which the Config, Dynamics, PulseGen, and TerminationConditions objects can be accessed as attributes. The PropagatorComputer, FidelityComputer and TimeslotComputer objects can be accessed as attributes of the Dynamics object, e.g. optimizer.dynamics.fid_computer The optimisation can be run through the optimizer.run_optimization

qutip_qtrl.pulseoptim.opt_pulse_crab(drift, ctrls, initial, target, num_tslots=None, evo_time=None, tau=None, amp_lbound=None, amp_ubound=None, fid_err_targ=1e-05, max_iter=500, max_wall_time=180, alg_params=None, num_coeffs=None, init_coeff_scaling=1.0, optim_params=None, optim_method='fmin', method_params=None, dyn_type='GEN_MAT', dyn_params=None, prop_type='DEF', prop_params=None, fid_type='DEF', fid_params=None, tslot_type='DEF', tslot_params=None, guess_pulse_type=None, guess_pulse_params=None, guess_pulse_scaling=1.0, guess_pulse_offset=0.0, guess_pulse_action='MODULATE', ramping_pulse_type=None, ramping_pulse_params=None, log_level=0, out_file_ext=None, gen_stats=False)

Optimise a control pulse to minimise the fidelity error. The dynamics of the system in any given timeslot are governed by the combined dynamics generator, i.e. the sum of the drift+ctrl_amp[j]*ctrls[j] The control pulse is an [n_ts, n_ctrls] array of piecewise amplitudes. The CRAB algorithm uses basis function coefficents as the variables to optimise. It does NOT use any gradient function. A multivariable optimisation algorithm attempts to determines the optimal values for the control pulse to minimise the fidelity error The fidelity error is some measure of distance of the system evolution from the given target evolution in the time allowed for the evolution.

Parameters:

driftQobj or list of Qobj

the underlying dynamics generator of the system can provide list (of length num_tslots) for time dependent drift

ctrlsList of Qobj or array like [num_tslots, evo_time]

a list of control dynamics generators. These are scaled by the amplitudes to alter the overall dynamics Array like imput can be provided for time dependent control generators

initialQobj

Starting point for the evolution. Typically the identity matrix.

targetQobj

Target transformation, e.g. gate or state, for the time evolution.

num_tslotsinteger or None

Number of timeslots. None implies that timeslots will be given in the tau array.

evo_timefloat or None

Total time for the evolution. None implies that timeslots will be given in the tau array.

tauarray[num_tslots] of floats or None

Durations for the timeslots. If this is given then num_tslots and evo_time are dervived from it. None implies that timeslot durations will be equal and calculated as evo_time/num_tslots.

amp_lboundfloat or list of floats

Lower boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

amp_uboundfloat or list of floats

Upper boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

fid_err_targfloat

Fidelity error target. Pulse optimisation will terminate when the fidelity error falls below this value.

max_iterinteger

Maximum number of iterations of the optimisation algorithm.

max_wall_timefloat

Maximum allowed elapsed time for the optimisation algorithm.

alg_paramsDictionary

Options that are specific to the algorithm see above.

optim_paramsDictionary

The key value pairs are the attribute name and value used to set attribute values. Note: attributes are created if they do not exist already, and are overwritten if they do. Note: method_params are applied afterwards and so may override these.

coeff_scalingfloat

Linear scale factor for the random basis coefficients. By default these range from -1.0 to 1.0. Note this is overridden by alg_params (if given there).

num_coeffsinteger

Number of coefficients used for each basis function. Note this is calculated automatically based on the dimension of the dynamics if not given. It is crucial to the performane of the algorithm that it is set as low as possible, while still giving high enough frequencies. Note this is overridden by alg_params (if given there).

optim_methodstring

Multi-variable optimisation method. The only tested options are ‘fmin’ and ‘Nelder-mead’. In theory any non-gradient method implemented in scipy.optimize.mininize could be used.

method_paramsdict

Parameters for the optim_method. Note that where there is an attribute of the Optimizer object or the termination_conditions matching the key that attribute. Otherwise, and in some case also, they are assumed to be method_options for the scipy.optimize.minimize method. The commonly used parameter are:

• xtol - limit on variable change for convergence

• ftol - limit on fidelity error change for convergence

dyn_typestring

Dynamics type, i.e. the type of matrix used to describe the dynamics. Options are UNIT, GEN_MAT, SYMPL (see Dynamics classes for details).

dyn_paramsdict

Parameters for the qutip.control.dynamics.Dynamics object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

prop_typestring

Propagator type i.e. the method used to calculate the propagtors and propagtor gradient for each timeslot options are DEF, APPROX, DIAG, FRECHET, AUG_MAT DEF will use the default for the specific dyn_type (see PropagatorComputer classes for details).

prop_paramsdict

Parameters for the PropagatorComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

fid_typestring

Fidelity error (and fidelity error gradient) computation method. Options are DEF, UNIT, TRACEDIFF, TD_APPROX. DEF will use the default for the specific dyn_type. (See FidelityComputer classes for details).

fid_paramsdict

Parameters for the FidelityComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

tslot_typestring

Method for computing the dynamics generators, propagators and evolution in the timeslots. Options: DEF, UPDATE_ALL, DYNAMIC UPDATE_ALL is the only one that currently works. (See TimeslotComputer classes for details).

tslot_paramsdict

Parameters for the TimeslotComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

guess_pulse_typestring, default None

Type / shape of pulse(s) used modulate the control amplitudes. Options include: RND, LIN, ZERO, SINE, SQUARE, TRIANGLE, SAW, GAUSSIAN.

guess_pulse_paramsdict

Parameters for the guess pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

guess_pulse_actionstring, default ‘MODULATE’

Determines how the guess pulse is applied to the pulse generated by the basis expansion. Options are: MODULATE, ADD.

pulse_scalingfloat

Linear scale factor for generated guess pulses. By default initial pulses are generated with amplitudes in the range (-1.0, 1.0). These will be scaled by this parameter.

pulse_offsetfloat

Linear offset for the pulse. That is this value will be added to any guess pulses generated.

ramping_pulse_typestring

Type of pulse used to modulate the control pulse. It’s intended use for a ramping modulation, which is often required in experimental setups. This is only currently implemented in CRAB. GAUSSIAN_EDGE was added for this purpose.

ramping_pulse_paramsdict

Parameters for the ramping pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

log_levelinteger

level of messaging output from the logger. Options are attributes of qutip_qtrl.logging_utils, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN.

out_file_extstring or None

Files containing the initial and final control pulse. Amplitudes are saved to the current directory. The default name will be postfixed with this extension. Setting this to None will suppress the output of files.

gen_statsboolean

If set to True then statistics for the optimisation run will be generated - accessible through attributes of the stats object.

Returns:

optOptimResult

Returns instance of OptimResult, which has attributes giving the reason for termination, final fidelity error, final evolution final amplitudes, statistics etc

qutip_qtrl.pulseoptim.opt_pulse_crab_unitary(H_d, H_c, U_0, U_targ, num_tslots=None, evo_time=None, tau=None, amp_lbound=None, amp_ubound=None, fid_err_targ=1e-05, max_iter=500, max_wall_time=180, alg_params=None, num_coeffs=None, init_coeff_scaling=1.0, optim_params=None, optim_method='fmin', method_params=None, phase_option='PSU', dyn_params=None, prop_params=None, fid_params=None, tslot_type='DEF', tslot_params=None, guess_pulse_type=None, guess_pulse_params=None, guess_pulse_scaling=1.0, guess_pulse_offset=0.0, guess_pulse_action='MODULATE', ramping_pulse_type=None, ramping_pulse_params=None, log_level=0, out_file_ext=None, gen_stats=False)

Optimise a control pulse to minimise the fidelity error, assuming that the dynamics of the system are generated by unitary operators. This function is simply a wrapper for optimize_pulse, where the appropriate options for unitary dynamics are chosen and the parameter names are in the format familiar to unitary dynamics. The dynamics of the system in any given timeslot are governed by the combined Hamiltonian, i.e. the sum of the H_d + ctrl_amp[j]*H_c[j] The control pulse is an [n_ts, n_ctrls] array of piecewise amplitudes.

The CRAB algorithm uses basis function coefficents as the variables to optimise. It does NOT use any gradient function. A multivariable optimisation algorithm attempts to determines the optimal values for the control pulse to minimise the fidelity error. The fidelity error is some measure of distance of the system evolution from the given target evolution in the time allowed for the evolution.

Parameters:

H_dQobj or list of Qobj

Drift (aka system) the underlying Hamiltonian of the system can provide list (of length num_tslots) for time dependent drift.

H_cList of Qobj or array like [num_tslots, evo_time]

A list of control Hamiltonians. These are scaled by the amplitudes to alter the overall dynamics. Array like imput can be provided for time dependent control generators.

U_0Qobj

Starting point for the evolution. Typically the identity matrix.

U_targQobj

Target transformation, e.g. gate or state, for the time evolution.

num_tslotsinteger or None

Number of timeslots. None implies that timeslots will be given in the tau array.

evo_timefloat or None

Total time for the evolution. None implies that timeslots will be given in the tau array.

tauarray[num_tslots] of floats or None

Durations for the timeslots. If this is given then num_tslots and evo_time are derived from it. None implies that timeslot durations will be equal and calculated as evo_time/num_tslots.

amp_lboundfloat or list of floats

Lower boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

amp_uboundfloat or list of floats

Upper boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

fid_err_targfloat

Fidelity error target. Pulse optimisation will terminate when the fidelity error falls below this value.

max_iterinteger

Maximum number of iterations of the optimisation algorithm.

max_wall_timefloat

Maximum allowed elapsed time for the optimisation algorithm.

alg_paramsDictionary

Options that are specific to the algorithm see above.

optim_paramsDictionary

The key value pairs are the attribute name and value used to set attribute values. Note: attributes are created if they do not exist already, and are overwritten if they do. Note: method_params are applied afterwards and so may override these.

coeff_scalingfloat

Linear scale factor for the random basis coefficients. By default these range from -1.0 to 1.0. Note this is overridden by alg_params (if given there).

num_coeffsinteger

Number of coefficients used for each basis function. Note this is calculated automatically based on the dimension of the dynamics if not given. It is crucial to the performance of the algorithm that it is set as low as possible, while still giving high enough frequencies. Note this is overridden by alg_params (if given there).

optim_methodstring

Multi-variable optimisation method. The only tested options are ‘fmin’ and ‘Nelder-mead’. In theory any non-gradient method implemented in scipy.optimize.minimize could be used.

method_paramsdict

Parameters for the optim_method. Note that where there is an attribute of the Optimizer object or the termination_conditions matching the key that attribute. Otherwise, and in some case also, they are assumed to be method_options for the scipy.optimize.minimize method. The commonly used parameter are:

• xtol - limit on variable change for convergence

• ftol - limit on fidelity error change for convergence

phase_optionstring

Determines how global phase is treated in fidelity calculations (fid_type='UNIT' only). Options:

• PSU - global phase ignored

• SU - global phase included

dyn_paramsdict

Parameters for the Dynamics object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

prop_paramsdict

Parameters for the PropagatorComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

fid_paramsdict

Parameters for the FidelityComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

tslot_typestring

Method for computing the dynamics generators, propagators and evolution in the timeslots. Options: DEF, UPDATE_ALL, DYNAMIC. UPDATE_ALL is the only one that currently works. (See TimeslotComputer classes for details).

tslot_paramsdict

Parameters for the TimeslotComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

guess_pulse_typestring, optional

Type / shape of pulse(s) used modulate the control amplitudes. Options include: RND, LIN, ZERO, SINE, SQUARE, TRIANGLE, SAW, GAUSSIAN.

guess_pulse_paramsdict

Parameters for the guess pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

guess_pulse_actionstring, ‘MODULATE’

Determines how the guess pulse is applied to the pulse generated by the basis expansion. Options are: MODULATE, ADD.

pulse_scalingfloat

Linear scale factor for generated guess pulses. By default initial pulses are generated with amplitudes in the range (-1.0, 1.0). These will be scaled by this parameter.

pulse_offsetfloat

Linear offset for the pulse. That is this value will be added to any guess pulses generated.

ramping_pulse_typestring

Type of pulse used to modulate the control pulse. It’s intended use for a ramping modulation, which is often required in experimental setups. This is only currently implemented in CRAB. GAUSSIAN_EDGE was added for this purpose.

ramping_pulse_paramsdict

Parameters for the ramping pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

log_levelinteger

Level of messaging output from the logger. Options are attributes of qutip_qtrl.logging_utils, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL. Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN.

out_file_extstring or None

Files containing the initial and final control pulse amplitudes are saved to the current directory. The default name will be postfixed with this extension. Setting this to None will suppress the output of files.

gen_statsboolean

If set to True then statistics for the optimisation run will be generated - accessible through attributes of the stats object.

Returns:

optOptimResult

Returns instance of OptimResult, which has attributes giving the reason for termination, final fidelity error, final evolution final amplitudes, statistics etc.

qutip_qtrl.pulseoptim.optimize_pulse(drift, ctrls, initial, target, num_tslots=None, evo_time=None, tau=None, amp_lbound=None, amp_ubound=None, fid_err_targ=1e-10, min_grad=1e-10, max_iter=500, max_wall_time=180, alg='GRAPE', alg_params=None, optim_params=None, optim_method='DEF', method_params=None, optim_alg=None, max_metric_corr=None, accuracy_factor=None, dyn_type='GEN_MAT', dyn_params=None, prop_type='DEF', prop_params=None, fid_type='DEF', fid_params=None, phase_option=None, fid_err_scale_factor=None, tslot_type='DEF', tslot_params=None, amp_update_mode=None, init_pulse_type='DEF', init_pulse_params=None, pulse_scaling=1.0, pulse_offset=0.0, ramping_pulse_type=None, ramping_pulse_params=None, log_level=0, out_file_ext=None, gen_stats=False)

Optimise a control pulse to minimise the fidelity error. The dynamics of the system in any given timeslot are governed by the combined dynamics generator, i.e. the sum of the drift + ctrl_amp[j]*ctrls[j].

The control pulse is an [n_ts, n_ctrls] array of piecewise amplitudes Starting from an initial (typically random) pulse, a multivariable optimisation algorithm attempts to determines the optimal values for the control pulse to minimise the fidelity error. The fidelity error is some measure of distance of the system evolution from the given target evolution in the time allowed for the evolution.

Parameters:

driftQobj or list of Qobj

The underlying dynamics generator of the system can provide list (of length num_tslots) for time dependent drift.

ctrlsList of Qobj or array like [num_tslots, evo_time]

A list of control dynamics generators. These are scaled by the amplitudes to alter the overall dynamics. Array-like input can be provided for time dependent control generators.

initialQobj

Starting point for the evolution. Typically the identity matrix.

targetQobj

Target transformation, e.g. gate or state, for the time evolution.

num_tslotsinteger or None

Number of timeslots. None implies that timeslots will be given in the tau array.

evo_timefloat or None

Total time for the evolution. None implies that timeslots will be given in the tau array.

tauarray[num_tslots] of floats or None

Durations for the timeslots. If this is given then num_tslots and evo_time are derived from it. None implies that timeslot durations will be equal and calculated as evo_time/num_tslots.

amp_lboundfloat or list of floats

Lower boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

amp_uboundfloat or list of floats

Upper boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

fid_err_targfloat

Fidelity error target. Pulse optimisation will terminate when the fidelity error falls below this value.

mim_gradfloat

Minimum gradient. When the sum of the squares of the gradients wrt to the control amplitudes falls below this value, the optimisation terminates, assuming local minima.

max_iterinteger

Maximum number of iterations of the optimisation algorithm.

max_wall_timefloat

Maximum allowed elapsed time for the optimisation algorithm.

algstring

Algorithm to use in pulse optimisation. Options are:

• ‘GRAPE’ (default) - GRadient Ascent Pulse Engineering

• ‘CRAB’ - Chopped RAndom Basis

alg_paramsDictionary

Options that are specific to the algorithm see above.

optim_paramsDictionary

The key value pairs are the attribute name and value used to set attribute values. Note: attributes are created if they do not exist already, and are overwritten if they do. Note: method_params are applied afterwards and so may override these.

optim_methodstring

A scipy.optimize.minimize method that will be used to optimise the pulse for minimum fidelity error. Note that FMIN, FMIN_BFGS & FMIN_L_BFGS_B will all result in calling these specific scipy.optimize methods. Note the LBFGSB is equivalent to FMIN_L_BFGS_B for backwards compatibility reasons. Supplying DEF will given alg dependent result:

• GRAPE - Default optim_method is FMIN_L_BFGS_B

• CRAB - Default optim_method is FMIN

method_paramsdict

Parameters for the optim_method. Note that where there is an attribute of the Optimizer object or the termination_conditions matching the key that attribute. Otherwise, and in some case also, they are assumed to be method_options for the scipy.optimize.minimize method.

optim_algstring

Deprecated. Use optim_method.

max_metric_corrinteger

Deprecated. Use method_params instead.

accuracy_factorfloat

Deprecated. Use method_params instead.

dyn_typestring

Dynamics type, i.e. the type of matrix used to describe the dynamics. Options are UNIT, GEN_MAT, SYMPL (see Dynamics classes for details).

dyn_paramsdict

Parameters for the Dynamics object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

prop_typestring

Propagator type i.e. the method used to calculate the propagators and propagator gradient for each timeslot options are DEF, APPROX, DIAG, FRECHET, AUG_MAT. DEF will use the default for the specific dyn_type (see PropagatorComputer classes for details).

prop_paramsdict

Parameters for the PropagatorComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

fid_typestring

Fidelity error (and fidelity error gradient) computation method. Options are DEF, UNIT, TRACEDIFF, TD_APPROX. DEF will use the default for the specific dyn_type (See FidelityComputer classes for details).

fid_paramsdict

Parameters for the FidelityComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

phase_optionstring

Deprecated. Pass in fid_params instead.

fid_err_scale_factorfloat

Deprecated. Use scale_factor key in fid_params instead.

tslot_typestring

Method for computing the dynamics generators, propagators and evolution in the timeslots. Options: DEF, UPDATE_ALL, DYNAMIC. UPDATE_ALL is the only one that currently works. (See TimeslotComputer classes for details.)

tslot_paramsdict

Parameters for the TimeslotComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

amp_update_modestring

Deprecated. Use tslot_type instead.

init_pulse_typestring

Type / shape of pulse(s) used to initialise the control amplitudes. Options (GRAPE) include: RND, LIN, ZERO, SINE, SQUARE, TRIANGLE, SAW. Default is RND. (see PulseGen classes for details). For the CRAB the this the guess_pulse_type.

init_pulse_paramsdict

Parameters for the initial / guess pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

pulse_scalingfloat

Linear scale factor for generated initial / guess pulses. By default initial pulses are generated with amplitudes in the range (-1.0, 1.0). These will be scaled by this parameter.

pulse_offsetfloat

Linear offset for the pulse. That is this value will be added to any initial / guess pulses generated.

ramping_pulse_typestring

Type of pulse used to modulate the control pulse. It’s intended use for a ramping modulation, which is often required in experimental setups. This is only currently implemented in CRAB. GAUSSIAN_EDGE was added for this purpose.

ramping_pulse_paramsdict

Parameters for the ramping pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

log_levelinteger

Level of messaging output from the logger. Options are attributes of qutip_qtrl.logging_utils, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL. Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN.

out_file_extstring or None

Files containing the initial and final control pulse amplitudes are saved to the current directory. The default name will be postfixed with this extension. Setting this to None will suppress the output of files.

gen_statsboolean

If set to True then statistics for the optimisation run will be generated - accessible through attributes of the stats object.

Returns:

optOptimResult

Returns instance of OptimResult, which has attributes giving the reason for termination, final fidelity error, final evolution final amplitudes, statistics etc.

qutip_qtrl.pulseoptim.optimize_pulse_unitary(H_d, H_c, U_0, U_targ, num_tslots=None, evo_time=None, tau=None, amp_lbound=None, amp_ubound=None, fid_err_targ=1e-10, min_grad=1e-10, max_iter=500, max_wall_time=180, alg='GRAPE', alg_params=None, optim_params=None, optim_method='DEF', method_params=None, optim_alg=None, max_metric_corr=None, accuracy_factor=None, phase_option='PSU', dyn_params=None, prop_params=None, fid_params=None, tslot_type='DEF', tslot_params=None, amp_update_mode=None, init_pulse_type='DEF', init_pulse_params=None, pulse_scaling=1.0, pulse_offset=0.0, ramping_pulse_type=None, ramping_pulse_params=None, log_level=0, out_file_ext=None, gen_stats=False)

Optimise a control pulse to minimise the fidelity error, assuming that the dynamics of the system are generated by unitary operators. This function is simply a wrapper for optimize_pulse, where the appropriate options for unitary dynamics are chosen and the parameter names are in the format familiar to unitary dynamics The dynamics of the system in any given timeslot are governed by the combined Hamiltonian, i.e. the sum of the H_d + ctrl_amp[j]*H_c[j] The control pulse is an [n_ts, n_ctrls] array of piecewise amplitudes Starting from an initial (typically random) pulse, a multivariable optimisation algorithm attempts to determines the optimal values for the control pulse to minimise the fidelity error The maximum fidelity for a unitary system is 1, i.e. when the time evolution resulting from the pulse is equivalent to the target. And therefore the fidelity error is 1 - fidelity.

Parameters:

H_dQobj or list of Qobj

Drift (aka system) the underlying Hamiltonian of the system can provide list (of length num_tslots) for time dependent drift.

H_cList of Qobj or array like [num_tslots, evo_time]

A list of control Hamiltonians. These are scaled by the amplitudes to alter the overall dynamics. Array-like input can be provided for time dependent control generators.

U_0Qobj

Starting point for the evolution. Typically the identity matrix.

U_targQobj

Target transformation, e.g. gate or state, for the time evolution.

num_tslotsinteger or None

Number of timeslots. None implies that timeslots will be given in the tau array.

evo_timefloat or None

Total time for the evolution. None implies that timeslots will be given in the tau array.

tauarray[num_tslots] of floats or None

Durations for the timeslots. If this is given then num_tslots and evo_time are derived from it. None implies that timeslot durations will be equal and calculated as evo_time/num_tslots.

amp_lboundfloat or list of floats

Lower boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

amp_uboundfloat or list of floats

Upper boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

fid_err_targfloat

Fidelity error target. Pulse optimisation will terminate when the fidelity error falls below this value.

mim_gradfloat

Minimum gradient. When the sum of the squares of the gradients wrt to the control amplitudes falls below this value, the optimisation terminates, assuming local minima.

max_iterinteger

Maximum number of iterations of the optimisation algorithm.

max_wall_timefloat

Maximum allowed elapsed time for the optimisation algorithm.

algstring

Algorithm to use in pulse optimisation. Options are:

• ‘GRAPE’ (default) - GRadient Ascent Pulse Engineering

• ‘CRAB’ - Chopped RAndom Basis

alg_paramsDictionary

options that are specific to the algorithm see above

optim_paramsDictionary

The key value pairs are the attribute name and value used to set attribute values. Note: attributes are created if they do not exist already, and are overwritten if they do. Note: method_params are applied afterwards and so may override these.

optim_methodstring

A scipy.optimize.minimize method that will be used to optimise the pulse for minimum fidelity error Note that FMIN, FMIN_BFGS & FMIN_L_BFGS_B will all result in calling these specific scipy.optimize methods Note the LBFGSB is equivalent to FMIN_L_BFGS_B for backwards compatibility reasons. Supplying DEF will given algorithm-dependent result:

• GRAPE - Default optim_method is FMIN_L_BFGS_B

• CRAB - Default optim_method is FMIN

method_paramsdict

Parameters for the optim_method. Note that where there is an attribute of the Optimizer object or the termination_conditions matching the key that attribute. Otherwise, and in some case also, they are assumed to be method_options for the scipy.optimize.minimize method.

optim_algstring

Deprecated. Use optim_method.

max_metric_corrinteger

Deprecated. Use method_params instead.

accuracy_factorfloat

Deprecated. Use method_params instead.

phase_optionstring

Determines how global phase is treated in fidelity calculations (fid_type='UNIT' only). Options:

• PSU - global phase ignored

• SU - global phase included

dyn_paramsdict

Parameters for the Dynamics object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

prop_paramsdict

Parameters for the PropagatorComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

fid_paramsdict

Parameters for the FidelityComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

tslot_typestring

Method for computing the dynamics generators, propagators and evolution in the timeslots. Options: DEF, UPDATE_ALL, DYNAMIC. UPDATE_ALL is the only one that currently works. (See TimeslotComputer classes for details.)

tslot_paramsdict

Parameters for the TimeslotComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

amp_update_modestring

Deprecated. Use tslot_type instead.

init_pulse_typestring

Type / shape of pulse(s) used to initialise the control amplitudes. Options (GRAPE) include: RND, LIN, ZERO, SINE, SQUARE, TRIANGLE, SAW. DEF is RND. (see PulseGen classes for details.) For the CRAB the this the guess_pulse_type.

init_pulse_paramsdict

Parameters for the initial / guess pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

pulse_scalingfloat

Linear scale factor for generated initial / guess pulses. By default initial pulses are generated with amplitudes in the range (-1.0, 1.0). These will be scaled by this parameter.

pulse_offsetfloat

Linear offset for the pulse. That is this value will be added to any initial / guess pulses generated.

ramping_pulse_typestring

Type of pulse used to modulate the control pulse. It’s intended use for a ramping modulation, which is often required in experimental setups. This is only currently implemented in CRAB. GAUSSIAN_EDGE was added for this purpose.

ramping_pulse_paramsdict

Parameters for the ramping pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

log_levelinteger

Level of messaging output from the logger. Options are attributes of qutip_qtrl.logging_utils in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN.

out_file_extstring or None

Files containing the initial and final control pulse amplitudes are saved to the current directory. The default name will be postfixed with this extension. Setting this to None will suppress the output of files.

gen_statsboolean

If set to True then statistics for the optimisation run will be generated - accessible through attributes of the stats object.

Returns:

optOptimResult

Returns instance of OptimResult, which has attributes giving the reason for termination, final fidelity error, final evolution final amplitudes, statistics etc.