qutip_qtrl.optimizer

Classes here are expected to implement a run_optimization function that will use some method for optimising the control pulse, as defined by the control amplitudes. The system that the pulse acts upon are defined by the Dynamics object that must be passed in the instantiation.

The methods are typically N dimensional function optimisers that find the minima of a fidelity error function. Note the number of variables for the fidelity function is the number of control timeslots, i.e. n_ctrls x Ntimeslots The methods will call functions on the Dynamics.fid_computer object, one or many times per interation, to get the fidelity error and gradient wrt to the amplitudes. The optimisation will stop when one of the termination conditions are met, for example: the fidelity aim has be reached, a local minima has been found, the maximum time allowed has been exceeded

These function optimisation methods are so far from SciPy.optimize The two methods implemented are:

BFGS - Broyden–Fletcher–Goldfarb–Shanno algorithm

This a quasi second order Newton method. It uses successive calls to the gradient function to make an estimation of the curvature (Hessian) and hence direct its search for the function minima The SciPy implementation is pure Python and hance is execution speed is not high use subclass: OptimizerBFGS

L-BFGS-B - Bounded, limited memory BFGS

This a version of the BFGS method where the Hessian approximation is only based on a set of the most recent gradient calls. It generally performs better where the are a large number of variables The SciPy implementation of L-BFGS-B is wrapper around a well established and actively maintained implementation in Fortran Its is therefore very fast. # See SciPy documentation for credit and details on the # scipy.optimize.fmin_l_bfgs_b function use subclass: OptimizerLBFGSB

The baseclass Optimizer implements the function wrappers to the fidelity error, gradient, and iteration callback functions. These are called from the within the SciPy optimisation functions. The subclasses implement the algorithm specific pulse optimisation function.

Classes

OptimIterSummary()	A summary of the most recent iteration of the pulse optimisation
Optimizer(config, dyn[, params])	Base class for all control pulse optimisers.
OptimizerBFGS(config, dyn[, params])	Implements the run_optimization method using the BFGS algorithm
OptimizerCrab(config, dyn[, params])	Optimises the pulse using the CRAB algorithm [Caneva].
OptimizerCrabFmin(config, dyn[, params])	Optimises the pulse using the CRAB algorithm [Doria], [Caneva].
OptimizerLBFGSB(config, dyn[, params])	Implements the run_optimization method using the L-BFGS-B algorithm

class qutip_qtrl.optimizer.OptimIterSummary

A summary of the most recent iteration of the pulse optimisation

Attributes:

iter_numint

Iteration number of the pulse optimisation

fid_func_call_numint

Fidelity function call number of the pulse optimisation

grad_func_call_numint

Gradient function call number of the pulse optimisation

fid_errfloat

Fidelity error

grad_normfloat

fidelity gradient (wrt the control parameters) vector norm that is the magnitude of the gradient

wall_timefloat

Time spent computing the pulse optimisation so far (in seconds of elapsed time)

class qutip_qtrl.optimizer.Optimizer(config, dyn, params=None)

Base class for all control pulse optimisers. This class should not be instantiated, use its subclasses. This class implements the fidelity, gradient and interation callback functions. All subclass objects must be initialised with a

• OptimConfig instance - various configuration options

• Dynamics instance - describes the dynamics of the (quantum) system to be control optimised

Attributes:

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.

params: Dictionary

The key value pairs are the attribute name and value. Note: attributes are created if they do not exist already, and are overwritten if they do.

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 pulse optim algorithm alg.

disp_conv_msgbool

Set true to display a convergence message (for scipy.optimize.minimize methods anyway)

optim_methodstring

a scipy.optimize.minimize method that will be used to optimise the pulse for minimum fidelity error

method_paramsDictionary

Options for the optim_method. Note that where there is an equivalent attribute of this instance or the termination_conditions (for example maxiter) it will override an value in these options

approx_gradbool

If set True then the method will approximate the gradient itself (if it has requirement and facility for this) This will mean that the fid_err_grad_wrapper will not get called Note it should be left False when using the Dynamics to calculate approximate gradients Note it is set True automatically when the alg is CRAB

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

boundsList of floats

Bounds for the parameters. If not set before the run_optimization call then the list is built automatically based on the amp_lbound and amp_ubound attributes. Setting this attribute directly allows specific bounds to be set for individual parameters. Note: Only some methods use bounds

dynamicsDynamics (subclass instance)

describes the dynamics of the (quantum) system to be control optimised (see Dynamics classes for details)

configOptimConfig instance

various configuration options (see OptimConfig for details)

termination_conditionsTerminationCondition instance

attributes determine when the optimisation will end

pulse_generatorPulseGen (subclass instance)

(can be) used to create initial pulses not used by the class, but set by pulseoptim.create_pulse_optimizer

statsStats

attributes of which give performance stats for the optimisation set to None to reduce overhead of calculating stats. Note it is (usually) shared with the Dynamics instance

dumpqutip_qtrl.dump.OptimDump

Container for data dumped during the optimisation. Can be set by specifying the dumping level or set directly. Note this is mainly intended for user and a development debugging but could be used for status information during a long optimisation.

dumpingstring

The level of data dumping that will occur during the optimisation

dump_to_filebool

If set True then data will be dumped to file during the optimisation dumping will be set to SUMMARY during init_optim if dump_to_file is True and dumping not set. Default is False

dump_dirstring

Basically a link to dump.dump_dir. Exists so that it can be set through optim_params. If dump is None then will return None or will set dumping to SUMMARY when setting a path

iter_summaryOptimIterSummary

Summary of the most recent iteration. Note this is only set if dummping is on

apply_method_params(params=None)

Loops through all the method_params (either passed here or the method_params attribute) If the name matches an attribute of this object or the termination conditions object, then the value of this attribute is set. Otherwise it is assumed to a method_option for the scipy.optimize.minimize function

apply_params(params=None)

Set object attributes based on the dictionary (if any) passed in the instantiation, or passed as a parameter This is called during the instantiation automatically. The key value pairs are the attribute name and value Note: attributes are created if they do not exist already, and are overwritten if they do.

property dumping

The level of data dumping that will occur during the optimisation

• NONE : No processing data dumped (Default)

• SUMMARY : A summary at each iteration will be recorded

• FULL : All logs will be generated and dumped

• CUSTOM : Some customised level of dumping

When first set to CUSTOM this is equivalent to SUMMARY. It is then up to the user to specify which logs are dumped

fid_err_func_wrapper(*args)

Get the fidelity error achieved using the ctrl amplitudes passed in as the first argument.

This is called by generic optimisation algorithm as the func to the minimised. The argument is the current variable values, i.e. control amplitudes, passed as a flat array. Hence these are reshaped as [nTimeslots, n_ctrls] and then used to update the stored ctrl values (if they have changed)

The error is checked against the target, and the optimisation is terminated if the target has been achieved.

fid_err_grad_wrapper(*args)

Get the gradient of the fidelity error with respect to all of the variables, i.e. the ctrl amplidutes in each timeslot

This is called by generic optimisation algorithm as the gradients of func to the minimised wrt the variables. The argument is the current variable values, i.e. control amplitudes, passed as a flat array. Hence these are reshaped as [nTimeslots, n_ctrls] and then used to update the stored ctrl values (if they have changed)

Although the optimisation algorithms have a check within them for function convergence, i.e. local minima, the sum of the squares of the normalised gradient is checked explicitly, and the optimisation is terminated if this is below the min_gradient_norm condition

init_optim(term_conds)

Check optimiser attribute status and passed parameters before running the optimisation. This is called by run_optimization, but could called independently to check the configuration.

iter_step_callback_func(*args)

Check the elapsed wall time for the optimisation run so far. Terminate if this has exceeded the maximum allowed time

run_optimization(term_conds=None)

This default function optimisation method is a wrapper to the scipy.optimize.minimize function.

It will attempt to minimise the fidelity error with respect to some parameters, which are determined by _get_optim_var_vals (see below)

The optimisation end when one of the passed termination conditions has been met, e.g. target achieved, wall time, or function call or iteration count exceeded. Note these conditions include gradient minimum met (local minima) for methods that use a gradient.

The function minimisation method is taken from the optim_method attribute. Note that not all of these methods have been tested. Note that some of these use a gradient and some do not. See the scipy documentation for details. Options specific to the method can be passed setting the method_params attribute.

If the parameter term_conds=None, then the termination_conditions attribute must already be set. It will be overwritten if the parameter is not None

The result is returned in an OptimResult object, which includes the final fidelity, time evolution, reason for termination etc

class qutip_qtrl.optimizer.OptimizerBFGS(config, dyn, params=None)

Implements the run_optimization method using the BFGS algorithm

run_optimization(term_conds=None)

Optimise the control pulse amplitudes to minimise the fidelity error using the BFGS (Broyden–Fletcher–Goldfarb–Shanno) algorithm The optimisation end when one of the passed termination conditions has been met, e.g. target achieved, gradient minimum met (local minima), wall time / iteration count exceeded.

Essentially this is wrapper to the: scipy.optimize.fmin_bfgs function

If the parameter term_conds=None, then the termination_conditions attribute must already be set. It will be overwritten if the parameter is not None

The result is returned in an OptimResult object, which includes the final fidelity, time evolution, reason for termination etc

class qutip_qtrl.optimizer.OptimizerCrab(config, dyn, params=None)

Optimises the pulse using the CRAB algorithm [Caneva]. It uses the scipy.optimize.minimize function with the method specified by the optim_method attribute. See Optimizer.run_optimization for details It minimises the fidelity error function with respect to the CRAB basis function coefficients.

References

[Caneva] (1,2)

T. Caneva, T. Calarco, and S. Montangero. Chopped random-basis quantum optimization, Phys. Rev. A, 84:022326, 2011 (doi:10.1103/PhysRevA.84.022326)

init_optim(term_conds)

Check optimiser attribute status and passed parameters before running the optimisation. This is called by run_optimization, but could called independently to check the configuration.

class qutip_qtrl.optimizer.OptimizerCrabFmin(config, dyn, params=None)

Optimises the pulse using the CRAB algorithm [Doria], [Caneva]. It uses the scipy.optimize.fmin function which is effectively a wrapper for the Nelder-Mead method. It minimises the fidelity error function with respect to the CRAB basis function coefficients. This is the default Optimizer for CRAB.

References

[Doria] (1,2)

P. Doria, T. Calarco & S. Montangero. Phys. Rev. Lett. 106, 190501 (2011).

[Caneva] (1,2)

T. Caneva, T. Calarco, & S. Montangero. Phys. Rev. A 84, 022326 (2011).

run_optimization(term_conds=None)

This function optimisation method is a wrapper to the scipy.optimize.fmin function.

It will attempt to minimise the fidelity error with respect to some parameters, which are determined by _get_optim_var_vals which in the case of CRAB are the basis function coefficients

The optimisation end when one of the passed termination conditions has been met, e.g. target achieved, wall time, or function call or iteration count exceeded. Specifically to the fmin method, the optimisation will stop when change parameter values is less than xtol or the change in function value is below ftol.

If the parameter term_conds=None, then the termination_conditions attribute must already be set. It will be overwritten if the parameter is not None

The result is returned in an OptimResult object, which includes the final fidelity, time evolution, reason for termination etc

class qutip_qtrl.optimizer.OptimizerLBFGSB(config, dyn, params=None)

Implements the run_optimization method using the L-BFGS-B algorithm

Attributes:

max_metric_corrinteger

The maximum number of variable metric corrections used to define the limited memory matrix. That is the number of previous gradient values that are used to approximate the Hessian see the scipy.optimize.fmin_l_bfgs_b documentation for description of m argument

init_optim(term_conds)

Check optimiser attribute status and passed parameters before running the optimisation. This is called by run_optimization, but could called independently to check the configuration.

run_optimization(term_conds=None)

Optimise the control pulse amplitudes to minimise the fidelity error using the L-BFGS-B algorithm, which is the constrained (bounded amplitude values), limited memory, version of the Broyden–Fletcher–Goldfarb–Shanno algorithm.

The optimisation end when one of the passed termination conditions has been met, e.g. target achieved, gradient minimum met (local minima), wall time / iteration count exceeded.

Essentially this is wrapper to the: scipy.optimize.fmin_l_bfgs_b function This in turn is a warpper for well established implementation of the L-BFGS-B algorithm written in Fortran, which is therefore very fast. See SciPy documentation for credit and details on this function.

If the parameter term_conds=None, then the termination_conditions attribute must already be set. It will be overwritten if the parameter is not None

The result is returned in an OptimResult object, which includes the final fidelity, time evolution, reason for termination etc