diff --git a/tutorials-v5/optimal-control/control-pulseoptim-CRAB-2qubitInerac.ipynb b/tutorials-v5/optimal-control/control-pulseoptim-CRAB-2qubitInerac.ipynb new file mode 100644 index 00000000..1d080207 --- /dev/null +++ b/tutorials-v5/optimal-control/control-pulseoptim-CRAB-2qubitInerac.ipynb @@ -0,0 +1,454 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Calculation of control fields for state-to-state transfer of a 2 qubit system using CRAB algorithm" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Jonathan Zoller (jonathan.zoller@uni-ulm.de)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Example to demonstrate using the control library to determine control\n", + "pulses using the ctrlpulseoptim.optimize_pulse_unitary function.\n", + "The CRAB algorithm is used to optimize pulse shapes to minimize the fidelity\n", + "error, which is equivalent maximising the fidelity to an optimal value of 1.\n", + "\n", + "The system in this example are two qubits, where the interaction can be\n", + "controlled. The target is to perform a pure state transfer from a down-down\n", + "state to an up-up state.\n", + "\n", + "The user can experiment with the timeslicing, by means of changing the\n", + "number of timeslots and/or total time for the evolution.\n", + "Different initial (starting) pulse types can be tried as well as\n", + "boundaries on the control and a smooth ramping of the pulse when\n", + "switching the control on and off (at the beginning and close to the end).\n", + "The initial and final pulses are displayed in a plot\n", + "\n", + "An in depth discussion of using methods of this type can be found in [1,2]" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "import datetime" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "from qutip import Qobj, identity, sigmax, sigmaz, tensor\n", + "import random\n", + "\n", + "#QuTiP control modules\n", + "import qutip_qtrl.pulseoptim as cpo\n", + "\n", + "example_name = '2qubitInteract'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the physics" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The dynamics of the system are governed by the combined Hamiltonian:\n", + "H(t) = H_d + sum(u1(t)*Hc1 + u2(t)*Hc2 + ....)\n", + "That is the time-dependent Hamiltonian has a constant part (called here the drift) and time vary parts, which are the control Hamiltonians scaled by some functions u_j(t) known as control amplitudes\n", + "In this example we describe an Ising like Hamiltonian, encompassing random coefficients in the drift part and controlling the interaction of the qubits:\n", + "\n", + "$ \\hat{H} = \\sum_{i=1}^2 \\alpha_i \\sigma_x^i + \\beta_i \\sigma_z^i + u(t) \\cdot \\sigma_z \\otimes \\sigma_z $\n", + "\n", + "Initial $\\newcommand{\\ket}[1]{\\left|{#1}\\right\\rangle} \\ket{\\psi_0} = \\text{U_0}$ and target state $\\ket{\\psi_t} = \\text{U_targ}$ are chosen to be:\n", + "\n", + "$ \\ket{\\psi_0} = \\begin{pmatrix} 1 \\\\ 0 \\\\ 0 \\\\ 0 \\end{pmatrix}$\n", + "\n", + "$ \\ket{\\psi_t} = \\begin{pmatrix} 0 \\\\ 0 \\\\ 0 \\\\ 1 \\end{pmatrix}$" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [], + "source": [ + "random.seed(20)\n", + "alpha = [random.random(),random.random()]\n", + "beta = [random.random(),random.random()]\n", + "\n", + "Sx = sigmax()\n", + "Sz = sigmaz()\n", + "\n", + "H_d = (alpha[0]*tensor(Sx,identity(2)) + \n", + " alpha[1]*tensor(identity(2),Sx) +\n", + " beta[0]*tensor(Sz,identity(2)) +\n", + " beta[1]*tensor(identity(2),Sz))\n", + "H_c = [tensor(Sz,Sz)]\n", + "# Number of ctrls\n", + "n_ctrls = len(H_c)\n", + "\n", + "q1_0 = q2_0 = Qobj([[1], [0]])\n", + "q1_targ = q2_targ = Qobj([[0], [1]])\n", + "\n", + "psi_0 = tensor(q1_0, q2_0)\n", + "psi_targ = tensor(q1_targ, q2_targ)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the time evolution parameters" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To solve the evolution the control amplitudes are considered constant within piecewise timeslots, hence the evolution during the timeslot can be calculated using U(t_k) = expm(-i*H(t_k)*dt). Combining these for all the timeslots gives the approximation to the evolution from an initial state $\\psi_0$ at t=0 to U(T) at the t=evo_time.\n", + "The number of timeslots and evo_time have to be chosen such that the timeslot durations (dt) are small compared with the dynamics of the system." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "# Number of time slots\n", + "n_ts = 100\n", + "# Time allowed for the evolution\n", + "evo_time = 18" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the conditions which will cause the pulse optimisation to terminate" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "At each iteration the fidelity of the evolution is tested by comparaing the calculated evolution U(T) with the target U_targ. For unitary systems such as this one this is typically:\n", + "f = normalise(overlap(U(T), U_targ)). The maximum fidelity (for a unitary system) calculated this way would be 1, and hence the error is calculated as fid_err = 1 - fidelity. As such the optimisation is considered completed when the fid_err falls below such a target value.\n", + "\n", + "In some cases the optimisation either gets stuck in some local minima, or the fid_err_targ is just not achievable, therefore some limits are set to the time/effort allowed to find a solution.\n", + "\n", + "The algorithm uses the CRAB algorithm to determine optimized coefficients that lead to a minimal fidelity error. The underlying optimization procedure is set to be the Nelder-Mead downhill simplex. Therefore, when all vertices shrink together, the algorithm will terminate." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [], + "source": [ + "# Fidelity error target\n", + "fid_err_targ = 1e-3\n", + "# Maximum iterations for the optisation algorithm\n", + "max_iter = 500\n", + "# Maximum (elapsed) time allowed in seconds\n", + "max_wall_time = 120" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the initial pulse type" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The control amplitudes must be set to some initial values. Typically these are just random values for each control in each timeslot. These do however result in erratic optimised pulses. For this example, a solution will be found for any initial pulse, and so it can be interesting to look at the other initial pulse alternatives." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "# pulse type alternatives: RND|ZERO|LIN|SINE|SQUARE|SAW|TRIANGLE|\n", + "p_type = 'DEF'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Give an extension for output files" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [], + "source": [ + "#Set to None to suppress output files\n", + "f_ext = \"{}_n_ts{}_ptype{}.txt\".format(example_name, n_ts, p_type)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Run the optimisation" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In this step, the actual optimization is performed. At each iteration the Nelder-Mead algorithm calculates a new set of coefficients that improves the currently worst set among all set of coefficients. For details see [1,2] and a textbook about static search methods. The algorithm continues until one of the termination conditions defined above has been reached. If undesired results are achieved, rerun the algorithm and/or try to change the number of coefficients to be optimized for, as this is a very crucial parameter." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "result = cpo.opt_pulse_crab_unitary(H_d, H_c, psi_0, psi_targ, n_ts, evo_time, \n", + " fid_err_targ=fid_err_targ, \n", + " max_iter=max_iter, max_wall_time=max_wall_time, \n", + " init_coeff_scaling=5.0, num_coeffs=5, \n", + " method_params={'xtol':1e-3},\n", + " guess_pulse_type=None, guess_pulse_action='modulate',\n", + " out_file_ext=f_ext,\n", + " gen_stats=True)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Report the results" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Firstly the performace statistics are reported, which gives a breakdown of the processing times. In this example it can be seen that the majority of time is spent calculating the propagators, i.e. exponentiating the combined Hamiltonian.\n", + "\n", + "The optimised U(T) is reported as the 'final evolution', which is essentially the string representation of the Qobj that holds the full time evolution at the point when the optimisation is terminated.\n", + "\n", + "The key information is in the summary (given last). Here the final fidelity is reported and the reason for termination of the algorithm." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "------------------------------------\n", + "---- Control optimisation stats ----\n", + "**** Timings (HH:MM:SS.US) ****\n", + "Total wall time elapsed during optimisation: 0:00:10.827474\n", + "Wall time computing Hamiltonians: 0:00:00.370447 (3.42%)\n", + "Wall time computing propagators: 0:00:10.074860 (93.05%)\n", + "Wall time computing forward propagation: 0:00:00.096581 (0.89%)\n", + "Wall time computing onward propagation: 0:00:00.073354 (0.68%)\n", + "Wall time computing gradient: 0:00:00 (0.00%)\n", + "\n", + "**** Iterations and function calls ****\n", + "Number of iterations: 427\n", + "Number of fidelity function calls: 618\n", + "Number of times fidelity is computed: 618\n", + "Number of gradient function calls: 0\n", + "Number of times gradients are computed: 0\n", + "Number of times timeslot evolution is recomputed: 618\n", + "\n", + "**** Control amplitudes ****\n", + "Number of control amplitude updates: 617\n", + "Mean number of updates per iteration: 1.4449648711943794\n", + "Number of timeslot values changed: 61699\n", + "Mean number of timeslot changes per update: 99.99837925445705\n", + "Number of amplitude values changed: 61699\n", + "Mean number of amplitude changes per update: 99.99837925445705\n", + "------------------------------------\n", + "Final evolution\n", + "Quantum object: dims=[[2, 2], [1, 1]], shape=(4, 1), type='ket', dtype=Dense\n", + "Qobj data =\n", + "[[-0.01205275-0.01273372j]\n", + " [-0.03672336-0.00406319j]\n", + " [ 0.01304093+0.00067749j]\n", + " [ 0.98345844-0.17597286j]]\n", + "\n", + "********* Summary *****************\n", + "Final fidelity error 0.0009219530359995121\n", + "Final gradient normal 0.0\n", + "Terminated due to Goal achieved\n", + "Number of iterations 427\n", + "Completed in 0:00:10.827474 HH:MM:SS.US\n" + ] + } + ], + "source": [ + "result.stats.report()\n", + "print(\"Final evolution\\n{}\\n\".format(result.evo_full_final))\n", + "print(\"********* Summary *****************\")\n", + "print(\"Final fidelity error {}\".format(result.fid_err))\n", + "print(\"Final gradient normal {}\".format(result.grad_norm_final))\n", + "print(\"Terminated due to {}\".format(result.termination_reason))\n", + "print(\"Number of iterations {}\".format(result.num_iter))\n", + "print(\"Completed in {} HH:MM:SS.US\".format(\n", + " datetime.timedelta(seconds=result.wall_time)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Plot the initial and final amplitudes" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here the (random) starting pulse is plotted along with the pulse (control amplitudes) that was found to produce the target gate evolution to within the specified error." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig1 = plt.figure()\n", + "ax1 = fig1.add_subplot(2, 1, 1)\n", + "ax1.set_title(\"Initial Control amps\")\n", + "ax1.set_ylabel(\"Control amplitude\")\n", + "ax1.step(result.time, \n", + " np.hstack((result.initial_amps[:, 0], result.initial_amps[-1, 0])), \n", + " where='post')\n", + "\n", + "ax2 = fig1.add_subplot(2, 1, 2)\n", + "ax2.set_title(\"Optimised Control Amplitudes\")\n", + "ax2.set_xlabel(\"Time\")\n", + "ax2.set_ylabel(\"Control amplitude\")\n", + "ax2.step(result.time, \n", + " np.hstack((result.final_amps[:, 0], result.final_amps[-1, 0])), \n", + " where='post')\n", + "plt.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Versions" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
SoftwareVersion
QuTiP5.1.0.dev0+0b4260e
Numpy1.26.4
SciPy1.13.0
matplotlib3.9.0
Number of CPUs8
BLAS InfoGeneric
IPython8.25.0
Python3.12.3 | packaged by Anaconda, Inc. | (main, May 6 2024, 19:46:43) [GCC 11.2.0]
OSposix [linux]
Cython3.0.10
Thu Jan 30 09:56:04 2025 IST
" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qutip.ipynbtools import version_table\n", + "\n", + "version_table()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### References" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "[1] Doria, P., Calarco, T. & Montangero, S.: Optimal Control Technique for Many-Body Quantum Dynamics. Phys. Rev. Lett. 106, 1–4 (2011).\n", + "\n", + "[2] Caneva, T., Calarco, T. & Montangero, S.: Chopped random-basis quantum optimization. Phys. Rev. A - At. Mol. Opt. Phys. 84, (2011)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.3" + } + }, + "nbformat": 4, + "nbformat_minor": 1 +} diff --git a/tutorials-v5/optimal-control/control-pulseoptim-CRAB-QFT.ipynb b/tutorials-v5/optimal-control/control-pulseoptim-CRAB-QFT.ipynb new file mode 100644 index 00000000..011a04fe --- /dev/null +++ b/tutorials-v5/optimal-control/control-pulseoptim-CRAB-QFT.ipynb @@ -0,0 +1,495 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Calculation of control fields for QFT gate on two qubits using the CRAB algorithm" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alexander Pitchford (agp1@aber.ac.uk)" + ] + }, + { + "cell_type": "raw", + "metadata": {}, + "source": [ + "Example to demonstrate using the CRAB [1][2] algorithm in the control library \n", + "to determine control pulses using the ctrlpulseoptim.create_pulse_optimizer function to \n", + "generate an Optimizer object, through which the configuration can be\n", + "manipulated before running the optmisation algorithm. In this case it is\n", + "demonstrated by modifying the CRAB pulse parameters to show how pulse constraints\n", + "for controls can be applied.\n", + "\n", + "The system in this example is two qubits in constant fields in x, y and z\n", + "with a variable independant controls fields in x and y acting on each qubit\n", + "The target evolution is the QFT gate. The user can experiment with the\n", + "different:\n", + " phase options - phase_option = SU or PSU\n", + " propagtor computer type prop_type = DIAG or FRECHET\n", + " fidelity measures - fid_type = UNIT or TRACEDIFF\n", + "\n", + "The user can experiment with the timeslicing, by means of changing the\n", + "number of timeslots and/or total time for the evolution.\n", + "Different guess and ramping pulse parameters can be tried.\n", + "The initial and final pulses are displayed in a plot" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "import datetime" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "from qutip import Qobj, identity, sigmax, sigmay, sigmaz, tensor\n", + "from qutip_qip.algorithms import qft\n", + "\n", + "#QuTiP control modules\n", + "import qutip_qtrl.pulseoptim as cpo\n", + "import qutip_qtrl.pulsegen as pulsegen\n", + "\n", + "example_name = 'QFT'\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the physics" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "Sx = sigmax()\n", + "Sy = sigmay()\n", + "Sz = sigmaz()\n", + "Si = 0.5*identity(2)\n", + "\n", + "# Drift Hamiltonian\n", + "H_d = 0.5*(tensor(Sx, Sx) + tensor(Sy, Sy) + tensor(Sz, Sz))\n", + "# The (four) control Hamiltonians\n", + "H_c = [tensor(Sx, Si), tensor(Sy, Si), tensor(Si, Sx), tensor(Si, Sy)]\n", + "n_ctrls = len(H_c)\n", + "# start point for the gate evolution\n", + "U_0 = identity(4)\n", + "# Target for the gate evolution - Quantum Fourier Transform gate\n", + "U_targ = qft(2)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the time evolution parameters" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Number of time slots\n", + "n_ts = 200\n", + "# Time allowed for the evolution\n", + "evo_time = 10" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the conditions which will cause the pulse optimisation to terminate" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Fidelity error target\n", + "fid_err_targ = 1e-3\n", + "# Maximum iterations for the optisation algorithm\n", + "max_iter = 20000\n", + "# Maximum (elapsed) time allowed in seconds\n", + "max_wall_time = 300" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Give an extension for output files" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "#Set to None to suppress output files\n", + "f_ext = \"{}_n_ts{}.txt\".format(example_name, n_ts)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Create the optimiser objects" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "optim = cpo.create_pulse_optimizer(H_d, H_c, U_0, U_targ, n_ts, evo_time, \n", + " fid_err_targ=fid_err_targ, \n", + " max_iter=max_iter, max_wall_time=max_wall_time,\n", + " alg='CRAB', \n", + " dyn_type='UNIT', \n", + " prop_type='DIAG', \n", + " fid_type='UNIT', fid_params={'phase_option':'PSU'}, \n", + " gen_stats=True)\n", + " " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Configure the pulses for each of the controls" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "dyn = optim.dynamics\n", + "\n", + "# Control 1\n", + "crab_pgen = optim.pulse_generator[0]\n", + "# Start from a ramped pulse\n", + "guess_pgen = pulsegen.create_pulse_gen('LIN', dyn=dyn, \n", + " pulse_params={'scaling':3.0})\n", + "crab_pgen.guess_pulse = guess_pgen.gen_pulse()\n", + "crab_pgen.scaling = 0.0\n", + "# Add some higher frequency components\n", + "crab_pgen.num_coeffs = 5\n", + "\n", + "# Control 2\n", + "crab_pgen = optim.pulse_generator[1]\n", + "# Apply a ramping pulse that will force the start and end to zero\n", + "ramp_pgen = pulsegen.create_pulse_gen('GAUSSIAN_EDGE', dyn=dyn, \n", + " pulse_params={'decay_time':evo_time/50.0})\n", + "crab_pgen.ramping_pulse = ramp_pgen.gen_pulse()\n", + "\n", + "# Control 3\n", + "crab_pgen = optim.pulse_generator[2]\n", + "# Add bounds\n", + "crab_pgen.scaling = 0.5\n", + "crab_pgen.lbound = -2.0\n", + "crab_pgen.ubound = 2.0\n", + "\n", + "\n", + "# Control 4\n", + "crab_pgen = optim.pulse_generator[3]\n", + "# Start from a triangular pulse with small signal\n", + "guess_pgen = pulsegen.PulseGenTriangle(dyn=dyn)\n", + "guess_pgen.num_waves = 1\n", + "guess_pgen.scaling = 2.0\n", + "guess_pgen.offset = 2.0\n", + "crab_pgen.guess_pulse = guess_pgen.gen_pulse()\n", + "crab_pgen.scaling = 0.1\n", + "\n", + "init_amps = np.zeros([n_ts, n_ctrls])\n", + "for j in range(dyn.num_ctrls):\n", + " pgen = optim.pulse_generator[j]\n", + " pgen.init_pulse()\n", + " init_amps[:, j] = pgen.gen_pulse()\n", + "\n", + "dyn.initialize_controls(init_amps)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Run the pulse optimisation" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Initial amplitudes output to file: ctrl_amps_initial_QFT_n_ts200.txt\n", + "***********************************\n", + "Starting pulse optimisation\n" + ] + } + ], + "source": [ + "# Save initial amplitudes to a text file\n", + "if f_ext is not None:\n", + " pulsefile = \"ctrl_amps_initial_\" + f_ext\n", + " dyn.save_amps(pulsefile)\n", + " print(\"Initial amplitudes output to file: \" + pulsefile)\n", + "\n", + "print(\"***********************************\")\n", + "print(\"Starting pulse optimisation\")\n", + "result = optim.run_optimization()\n", + "\n", + "# Save final amplitudes to a text file\n", + "if f_ext is not None:\n", + " pulsefile = \"ctrl_amps_final_\" + f_ext\n", + " dyn.save_amps(pulsefile)\n", + " print(\"Final amplitudes output to file: \" + pulsefile)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Report the results" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "------------------------------------\n", + "---- Control optimisation stats ----\n", + "**** Timings (HH:MM:SS.US) ****\n", + "Total wall time elapsed during optimisation: 0:05:00.003775\n", + "Wall time computing Hamiltonians: 0:00:22.547817 (7.52%)\n", + "Wall time computing propagators: 0:04:24.789280 (88.26%)\n", + "Wall time computing forward propagation: 0:00:03.857988 (1.29%)\n", + "Wall time computing onward propagation: 0:00:03.634444 (1.21%)\n", + "Wall time computing gradient: 0:00:00 (0.00%)\n", + "\n", + "**** Iterations and function calls ****\n", + "Number of iterations: 8610\n", + "Number of fidelity function calls: 10459\n", + "Number of times fidelity is computed: 10459\n", + "Number of gradient function calls: 0\n", + "Number of times gradients are computed: 0\n", + "Number of times timeslot evolution is recomputed: 10459\n", + "\n", + "**** Control amplitudes ****\n", + "Number of control amplitude updates: 10458\n", + "Mean number of updates per iteration: 1.2146341463414634\n", + "Number of timeslot values changed: 2091599\n", + "Mean number of timeslot changes per update: 199.99990437942245\n", + "Number of amplitude values changed: 8350196\n", + "Mean number of amplitude changes per update: 798.4505641614076\n", + "------------------------------------\n", + "Final evolution\n", + "Quantum object: dims = [[4], [4]], shape = (4, 4), type = oper, isherm = False\n", + "Qobj data =\n", + "[[-0.47890815-0.25124383j -0.47862720-0.14293885j -0.47089104-0.19654053j\n", + " -0.39814103-0.19780087j]\n", + " [-0.48524763-0.18754841j 0.19902638-0.45262542j 0.45666538+0.17490099j\n", + " -0.22150294+0.44348832j]\n", + " [-0.44119050-0.18412439j 0.49542987+0.17619236j -0.42828736-0.17952947j\n", + " 0.50360656+0.16023168j]\n", + " [-0.41755379-0.18434167j -0.18861574+0.44037804j 0.50645054+0.16836502j\n", + " 0.23840544-0.4695553j ]]\n", + "\n", + "********* Summary *****************\n", + "Initial fidelity error 0.9483036893449602\n", + "Final fidelity error 0.0032564547889728512\n", + "Terminated due to Max wall time exceeded\n", + "Number of iterations 8611\n", + "Completed in 0:05:00.003775 HH:MM:SS.US\n" + ] + } + ], + "source": [ + "result.stats.report()\n", + "print(\"Final evolution\\n{}\\n\".format(result.evo_full_final))\n", + "print(\"********* Summary *****************\")\n", + "print(\"Initial fidelity error {}\".format(result.initial_fid_err))\n", + "print(\"Final fidelity error {}\".format(result.fid_err))\n", + "print(\"Terminated due to {}\".format(result.termination_reason))\n", + "print(\"Number of iterations {}\".format(result.num_iter))\n", + "print(\"Completed in {} HH:MM:SS.US\".format(\n", + " datetime.timedelta(seconds=result.wall_time)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Plot the initial and final amplitudes" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig1 = plt.figure()\n", + "ax1 = fig1.add_subplot(2, 1, 1)\n", + "ax1.set_title(\"Initial Control amps\")\n", + "ax1.set_xlabel(\"Time\")\n", + "ax1.set_ylabel(\"Control amplitude\")\n", + "for j in range(n_ctrls):\n", + " ax1.step(result.time, \n", + " np.hstack((result.initial_amps[:, j], result.initial_amps[-1, j])), \n", + " where='post')\n", + "ax2 = fig1.add_subplot(2, 1, 2)\n", + "ax2.set_title(\"Optimised Control Amplitudes\")\n", + "ax2.set_xlabel(\"Time\")\n", + "ax2.set_ylabel(\"Control amplitude\")\n", + "for j in range(n_ctrls):\n", + " ax2.step(result.time, \n", + " np.hstack((result.final_amps[:, j], result.final_amps[-1, j])), \n", + " where='post', label='u{}'.format(j))\n", + "ax2.legend(loc=8, ncol=n_ctrls)\n", + "plt.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Versions" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "data": { + "text/html": [ + "
SoftwareVersion
QuTiP4.1.0
Numpy1.11.3
SciPy0.18.1
matplotlib2.0.0
Cython0.25.2
Number of CPUs4
BLAS InfoINTEL MKL
IPython5.1.0
Python3.6.0 |Anaconda 4.3.1 (64-bit)| (default, Dec 23 2016, 12:22:00) \n", + "[GCC 4.4.7 20120313 (Red Hat 4.4.7-1)]
OSposix [linux]
Fri Jul 14 16:41:51 2017 BST
" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 13, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qutip.ipynbtools import version_table\n", + "\n", + "version_table()" + ] + }, + { + "cell_type": "raw", + "metadata": {}, + "source": [ + "References:\n", + "\n", + "3. Doria, P., Calarco, T. & Montangero, S. \n", + " Optimal Control Technique for Many-Body Quantum Dynamics. \n", + " Phys. Rev. Lett. 106, 1–4 (2011).\n", + "\n", + "4. Caneva, T., Calarco, T. & Montangero, S. \n", + " Chopped random-basis quantum optimization. \n", + " Phys. Rev. A - At. Mol. Opt. Phys. 84, (2011)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.3" + } + }, + "nbformat": 4, + "nbformat_minor": 0 +} diff --git a/tutorials-v5/optimal-control/control-pulseoptim-Hadamard.ipynb b/tutorials-v5/optimal-control/control-pulseoptim-Hadamard.ipynb new file mode 100644 index 00000000..734a2018 --- /dev/null +++ b/tutorials-v5/optimal-control/control-pulseoptim-Hadamard.ipynb @@ -0,0 +1,432 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Calculation of control fields for Hadamard gate on single qubit using L-BFGS-B algorithm" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alexander Pitchford (agp1@aber.ac.uk)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Example to demonstrate using the control library to determine control\n", + "pulses using the ctrlpulseoptim.optimize_pulse_unitary function.\n", + "The (default) L-BFGS-B algorithm is used to optimise the pulse to\n", + "minimise the fidelity error, which is equivalent maximising the fidelity\n", + "to an optimal value of 1.\n", + "\n", + "The system in this example is a single qubit in a constant field in z\n", + "with a variable control field in x\n", + "The target evolution is the Hadamard gate irrespective of global phase\n", + "\n", + "The user can experiment with the timeslicing, by means of changing the\n", + "number of timeslots and/or total time for the evolution.\n", + "Different initial (starting) pulse types can be tried.\n", + "The initial and final pulses are displayed in a plot\n", + "\n", + "An in depth discussion of using methods of this type can be found in [1]" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "metadata": {}, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "import datetime" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "metadata": {}, + "outputs": [], + "source": [ + "from qutip import Qobj, identity, sigmax, sigmaz\n", + "from qutip import gates\n", + "#QuTiP control modules\n", + "import qutip_qtrl.pulseoptim as cpo\n", + "\n", + "example_name = 'Hadamard'\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the physics" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The dynamics of the system are governed by the combined Hamiltonian:\n", + "H(t) = H_d + sum(u1(t)*Hc1 + u2(t)*Hc2 + ....)\n", + "That is the time-dependent Hamiltonian has a constant part (called here the drift) and time vary parts, which are the control Hamiltonians scaled by some functions u_j(t) known as control amplitudes\n", + "In this case the drift is simply a rotation about z and the (time-varying) control is a rotation about x\n", + "In theory this system is fully controllable (irrespective of global phase) and so any unitary target could be chosen; we have chosen the Hadamard gate." + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "metadata": {}, + "outputs": [], + "source": [ + "# Drift Hamiltonian\n", + "H_d = sigmaz()\n", + "# The (single) control Hamiltonian\n", + "H_c = [sigmax()]\n", + "# start point for the gate evolution\n", + "U_0 = identity(2)\n", + "# Target for the gate evolution Hadamard gate\n", + "U_targ = gates.hadamard_transform(1)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the time evolution parameters" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To solve the evolution the control amplitudes are considered constant within piecewise timeslots, hence the evolution during the timeslot can be calculated using U(t_k) = expm(-i*H(t_k)*dt). Combining these for all the timeslots gives the approximation to the evolution from the identity at t=0 to U(T) at the t=evo_time\n", + "The number of timeslots and evo_time have to be chosen such that the timeslot durations (dt) are small compared with the dynamics of the system." + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "metadata": {}, + "outputs": [], + "source": [ + "# Number of time slots\n", + "n_ts = 10\n", + "# Time allowed for the evolution\n", + "evo_time = 10" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the conditions which will cause the pulse optimisation to terminate" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "At each iteration the fidelity of the evolution is tested by comparaing the calculated evolution U(T) with the target U_targ. For unitary systems such as this one this is typically:\n", + "f = normalise(overlap(U(T), U_targ))\n", + "For details of the normalisation see [1] or the source code.\n", + "The maximum fidelity (for a unitary system) calculated this way would be 1, and hence the error is calculated as fid_err = 1 - fidelity. As such the optimisation is considered completed when the fid_err falls below such a target value.\n", + "\n", + "In some cases the optimisation either gets stuck in some local minima, or the fid_err_targ is just not achievable, therefore some limits are set to the time/effort allowed to find a solution.\n", + "\n", + "The algorithm uses gradients to direct its search for the minimum fidelity error. If the sum of all the gradients falls below the min_grad, then it is assumed some local minima has been found." + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "metadata": {}, + "outputs": [], + "source": [ + "# Fidelity error target\n", + "fid_err_targ = 1e-10\n", + "# Maximum iterations for the optisation algorithm\n", + "max_iter = 200\n", + "# Maximum (elapsed) time allowed in seconds\n", + "max_wall_time = 120\n", + "# Minimum gradient (sum of gradients squared)\n", + "# as this tends to 0 -> local minima has been found\n", + "min_grad = 1e-20" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the initial pulse type" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The control amplitudes must be set to some initial values. Typically these are just random values for each control in each timeslot. These do however result in erratic optimised pulses. For this example, a solution will be found for any initial pulse, and so it can be interesting to look at the other initial pulse alternatives." + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "metadata": {}, + "outputs": [], + "source": [ + "# pulse type alternatives: RND|ZERO|LIN|SINE|SQUARE|SAW|TRIANGLE|\n", + "p_type = 'RND'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Give an extension for output files" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "metadata": {}, + "outputs": [], + "source": [ + "#Set to None to suppress output files\n", + "f_ext = \"{}_n_ts{}_ptype{}.txt\".format(example_name, n_ts, p_type)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Run the optimisation" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In this step the L-BFGS-B algorithm is invoked. At each iteration the gradient of the fidelity error w.r.t. each control amplitude in each timeslot is calculated using an exact gradient method (see [1]). Using the gradients the algorithm will determine a set of piecewise control amplitudes that reduce the fidelity error. With repeated iterations an approximation of the Hessian matrix (the 2nd order differentials) is calculated, which enables a quasi 2nd order Newton method for finding a minima. The algorithm continues until one of the termination conditions defined above has been reached." + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "metadata": {}, + "outputs": [], + "source": [ + "result = cpo.optimize_pulse_unitary(H_d, H_c, U_0, U_targ, n_ts, evo_time, \n", + " fid_err_targ=fid_err_targ, min_grad=min_grad, \n", + " max_iter=max_iter, max_wall_time=max_wall_time, \n", + " out_file_ext=f_ext, init_pulse_type=p_type, \n", + " gen_stats=True)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Report the results" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Firstly the performace statistics are reported, which gives a breadown of the processing times. The times given are those that are associated with calculating the fidelity and the gradients. Any remaining processing time can be assumed to be used by the optimisation algorithm (L-BFGS-B) itself. In this example it can be seen that the majority of time is spent calculating the propagators, i.e. exponentiating the combined Hamiltonian.\n", + "\n", + "The optimised U(T) is reported as the 'final evolution', which is essentially the string representation of the Qobj that holds the full time evolution at the point when the optimisation is terminated.\n", + "\n", + "The key information is in the summary (given) last. Here the final fidelity is reported and the reasonn for termination of the algorithm." + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "------------------------------------\n", + "---- Control optimisation stats ----\n", + "**** Timings (HH:MM:SS.US) ****\n", + "Total wall time elapsed during optimisation: 0:00:00.057406\n", + "Wall time computing Hamiltonians: 0:00:00.001933 (3.37%)\n", + "Wall time computing propagators: 0:00:00.042375 (73.82%)\n", + "Wall time computing forward propagation: 0:00:00.000466 (0.81%)\n", + "Wall time computing onward propagation: 0:00:00.000365 (0.64%)\n", + "Wall time computing gradient: 0:00:00.002932 (5.11%)\n", + "\n", + "**** Iterations and function calls ****\n", + "Number of iterations: 5\n", + "Number of fidelity function calls: 7\n", + "Number of times fidelity is computed: 7\n", + "Number of gradient function calls: 6\n", + "Number of times gradients are computed: 6\n", + "Number of times timeslot evolution is recomputed: 7\n", + "\n", + "**** Control amplitudes ****\n", + "Number of control amplitude updates: 6\n", + "Mean number of updates per iteration: 1.2\n", + "Number of timeslot values changed: 60\n", + "Mean number of timeslot changes per update: 10.0\n", + "Number of amplitude values changed: 60\n", + "Mean number of amplitude changes per update: 10.0\n", + "------------------------------------\n", + "Final evolution\n", + "Quantum object: dims=[[2], [2]], shape=(2, 2), type='oper', dtype=Dense, isherm=False\n", + "Qobj data =\n", + "[[ 7.29974151e-07+0.70710553j -1.69311118e-06+0.70710803j]\n", + " [ 1.69311118e-06+0.70710803j 7.29974151e-07-0.70710553j]]\n", + "\n", + "********* Summary *****************\n", + "Final fidelity error 3.2678304506816858e-12\n", + "Final gradient normal 2.8203618768226e-05\n", + "Terminated due to Goal achieved\n", + "Number of iterations 5\n", + "Completed in 0:00:00.057406 HH:MM:SS.US\n" + ] + } + ], + "source": [ + "result.stats.report()\n", + "print(\"Final evolution\\n{}\\n\".format(result.evo_full_final))\n", + "print(\"********* Summary *****************\")\n", + "print(\"Final fidelity error {}\".format(result.fid_err))\n", + "print(\"Final gradient normal {}\".format(result.grad_norm_final))\n", + "print(\"Terminated due to {}\".format(result.termination_reason))\n", + "print(\"Number of iterations {}\".format(result.num_iter))\n", + "print(\"Completed in {} HH:MM:SS.US\".format(\n", + " datetime.timedelta(seconds=result.wall_time)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Plot the initial and final amplitudes" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here the (random) starting pulse is plotted along with the pulse (control amplitudes) that was found to produce the target gate evolution to within the specified error." + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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rNI5rROkpqaiRo0aAAAbGxukpqYCAFq1aoXRo0frNt0L+vbtiwcPHmD69OlISkqCj48P9u7dqxogcefOHRgZ/a8TskWLFti4cSOmTp2KKVOmoFatWvj555/RoEEDveYkIiKil7M0NYafuz1O3X4kdxSDo3VhV6NGDSQkJKB69eqoU6cOtm7dimbNmmHnzp2ws7PTQ0R1ISEhCAkJKXTeoUOHCrT17t0bvXv31nMqIiIi0pQkSdg2yh/Zefq5Ll8OlqbGckcAUIzCLjg4GOfOnUPbtm0xadIkdO3aFStWrEBeXh6WLFmij4xERERkYCRJKhWnLg2N1p/o+PHjVV8HBATgypUriIuLQ82aNdGwYUOdhiMiIiIizb12qezu7g53d3ddZCEiIiKi1/BaNygmIiIiotKDhR0RERGRgWBhR0RERGQgWNgRERERGQiNBk+kp6drvEEbG5tihyEiIiKi4tOosLOzs4MkSUUuI4SAJElQKAznZoNEREREZYlGhV1sbKy+cxARERHRa9KosGvbtq2+cxARERHRayrWDYrT0tKwZs0aXL58GQBQv359DB06FLa2tjoNR0RERESa03pU7KlTp+Dl5YWlS5ciNTUVqampWLJkCby8vHD69Gl9ZCQiIiIiDRTrWbHdunXD119/DROT56s/e/YMw4cPR1hYGH7//XedhyQiIiKiV9O6sDt16pRaUQcAJiYm+OSTT+Dn56fTcERERESkOa1PxdrY2ODOnTsF2hMTE2Ftba2TUERERESkPa0Lu759+2LYsGHYsmULEhMTkZiYiM2bN2P48OHo37+/PjISERERkQa0PhW7aNEiSJKEwYMH49mzZwAAU1NTjB49GgsWLNB5QCIiIiLSjFaFnUKhwLFjxzBjxgzMnz8fN27cAAB4eXnByspKLwGJiIiISDNaFXbGxsbo0KEDLl++DE9PT3h7e+srFxERERFpSetr7Bo0aICbN2/qIwsRERERvQatC7s5c+ZgwoQJ+PXXX3H//n2kp6ervYiIiIhIHloPnujUqRMAoFu3bpAkSdUuhIAkSVAoFLpLR0REREQa07qwi42N1UcOIiIiInpNWhd2np6ecHNzU+utA5732CUmJuosGBERERFpR+tr7Dw9PfHgwYMC7ampqfD09NRJKCIiIiLSntaFXf61dC/KzMyEhYWFTkIRERERkfY0PhUb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ckcql9LT00VoaKioXr26sLCwEDVq1BCfffaZyMnJkTtauRAbG1vo34mgoCAhhBBKpVJMmzZNODs7C3Nzc9G+fXtx9erVEs/J+9gRERERGQheY0dERERkIFjYERERERkIFnZEREREBoKFHREREZGBYGFHREREZCBY2BEREREZCBZ2RERERAaChR0RERGRgWBhR0T0moYMGVLyjw0iIioEnxVLRFQESZKKnB8REYEvv/wSfIgPEZUGLOyIiIpw//591ddbtmzB9OnTcfXqVVVbxYoVUbFiRTmiEREVwFOxRERFcHFxUb1sbW0hSZJaW8WKFQucin3rrbcwduxYhIWFwd7eHs7Ozvj666+RlZWF4OBgWFtbo2bNmtizZ4/avi5cuIB3330XFStWhLOzMwYNGoSHDx+W8DsmorKMhR0RkR6sW7cOlStXxokTJzB27FiMHj0avXv3RosWLXD69Gl06NABgwYNwpMnTwAAaWlpaNeuHRo3boxTp05h7969SE5ORp8+fWR+J0RUlrCwIyLSg0aNGmHq1KmoVasWJk+eDAsLC1SuXBkjRoxArVq1MH36dPz777+Ij48HAKxYsQKNGzfGvHnzUKdOHTRu3Bhr165FbGws/v77b5nfDRGVFbzGjohIDxo2bKj62tjYGJUqVYK3t7eqzdnZGQCQkpICADh37hxiY2MLvV7vxo0beOONN/ScmIgMAQs7IiI9MDU1VZuWJEmtLX+0rVKpBABkZmaia9euWLhwYYFtValSRY9JiciQsLAjIioFmjRpgh9//BEeHh4wMeGvZiIqHl5jR0RUCowZMwapqano378/Tp48iRs3bmDfvn0IDg6GQqGQOx4RlREs7IiISgFXV1f89ddfUCgU6NChA7y9vREWFgY7OzsYGfFXNRFpRhK8XToRERGRQeC/gUREREQGgoUdERERkYFgYUdERERkIFjYERERERkIFnZEREREBoKFHREREZGBYGFHREREZCBY2BEREREZCBZ2RERERAaChR0RERGRgWBhR0RERGQg/h8OEiaIaPRL7AAAAABJRU5ErkJggg==", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig1 = plt.figure()\n", + "ax1 = fig1.add_subplot(2, 1, 1)\n", + "ax1.set_title(\"Initial control amps\")\n", + "#ax1.set_xlabel(\"Time\")\n", + "ax1.set_ylabel(\"Control amplitude\")\n", + "ax1.step(result.time,\n", + " np.hstack((result.initial_amps[:, 0], result.initial_amps[-1, 0])),\n", + " where='post')\n", + "\n", + "ax2 = fig1.add_subplot(2, 1, 2)\n", + "ax2.set_title(\"Optimised Control Sequences\")\n", + "ax2.set_xlabel(\"Time\")\n", + "ax2.set_ylabel(\"Control amplitude\")\n", + "ax2.step(result.time,\n", + " np.hstack((result.final_amps[:, 0], result.final_amps[-1, 0])),\n", + " where='post')\n", + "plt.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Versions" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
SoftwareVersion
QuTiP5.1.0.dev0+0b4260e
Numpy1.26.4
SciPy1.13.0
matplotlib3.9.0
Number of CPUs8
BLAS InfoGeneric
IPython8.25.0
Python3.12.3 | packaged by Anaconda, Inc. | (main, May 6 2024, 19:46:43) [GCC 11.2.0]
OSposix [linux]
Cython3.0.10
Thu Jan 30 09:53:07 2025 IST
" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 30, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qutip.ipynbtools import version_table\n", + "\n", + "version_table()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### References" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "[1] Machnes et.al., DYNAMO - Dynamic Framework for Quantum Optimal Control. arXiv.1011.4874" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.3" + } + }, + "nbformat": 4, + "nbformat_minor": 1 +} diff --git a/tutorials-v5/optimal-control/control-pulseoptim-Lindbladian.ipynb b/tutorials-v5/optimal-control/control-pulseoptim-Lindbladian.ipynb new file mode 100644 index 00000000..7894314b --- /dev/null +++ b/tutorials-v5/optimal-control/control-pulseoptim-Lindbladian.ipynb @@ -0,0 +1,412 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Calculation of control fields for Lindbladian dynamics using L-BFGS-B algorithm" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Christian Arenz (christianarenz.ca@gmail.com), Alexander Pitchford (alex.pitchford@gmail.com)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Example to demonstrate using the control library to determine control pulses using the ctrlpulseoptim.optimize_pulse function. The (default) L-BFGS-B algorithm is used to optimise the pulse to\n", + "minimise the fidelity error, which in this case is given by the 'Trace difference' norm.\n", + "\n", + "This in an open quantum system example, with a single qubit subject to an amplitude damping channel. The target evolution is the Hadamard gate. For a $d$ dimensional quantum system in general we represent the Lindbladian\n", + "as a $d^2 \\times d^2$ dimensional matrix by creating the Liouvillian superoperator. Here done for the Lindbladian that describes the amplitude damping channel. Similarly the control generators acting on the qubit are also converted to superoperators. The initial and target maps also need to be in superoperator form. \n", + "\n", + "The user can experiment with the strength of the amplitude damping by changing the gamma variable value. If the rate is sufficiently small then the target fidelity can be achieved within the given tolerence. The drift Hamiltonian and control generators can also be swapped and changed to experiment with controllable and uncontrollable setups.\n", + "\n", + "The user can experiment with the timeslicing, by means of changing the\n", + "number of timeslots and/or total time for the evolution.\n", + "Different initial (starting) pulse types can be tried.\n", + "The initial and final pulses are displayed in a plot\n", + "\n", + "For more background on the pulse optimisation see:\n", + "[QuTiP overview - Optimal Control](http://nbviewer.ipython.org/github/qutip/qutip-notebooks/blob/master/examples/example-optimal-control-overview.ipynb) " + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "import datetime" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "from qutip import Qobj, identity, sigmax, sigmay, sigmaz, sigmam, tensor\n", + "from qutip import liouvillian, sprepost\n", + "from qutip import gates\n", + "\n", + "#QuTiP control modules\n", + "import qutip_qtrl.pulseoptim as cpo\n", + "\n", + "example_name = 'Lindblad'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the physics" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [], + "source": [ + "Sx = sigmax()\n", + "Sy = sigmay()\n", + "Sz = sigmaz()\n", + "Sm = sigmam()\n", + "Si = identity(2)\n", + "#Hadamard gate\n", + "had_gate = gates.hadamard_transform(1)\n", + "\n", + "# Hamiltonian\n", + "Del = 0.1 # Tunnelling term\n", + "wq = 1.0 # Energy of the 2-level system.\n", + "H0 = 0.5*wq*sigmaz() + 0.5*Del*sigmax()\n", + "\n", + "#Amplitude damping#\n", + "#Damping rate:\n", + "gamma = 0.1\n", + "L0 = liouvillian(H0, [np.sqrt(gamma)*Sm])\n", + "\n", + "#sigma X control\n", + "LC_x = liouvillian(Sx)\n", + "#sigma Y control\n", + "LC_y = liouvillian(Sy)\n", + "#sigma Z control\n", + "LC_z = liouvillian(Sz)\n", + "\n", + "#Drift\n", + "drift = L0\n", + "#Controls - different combinations can be tried\n", + "ctrls = [LC_z, LC_x]\n", + "# Number of ctrls\n", + "n_ctrls = len(ctrls)\n", + "\n", + "# start point for the map evolution\n", + "E0 = sprepost(Si, Si)\n", + "\n", + "# target for map evolution\n", + "E_targ = sprepost(had_gate, had_gate)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the time evolution parameters" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "# Number of time slots\n", + "n_ts = 10\n", + "# Time allowed for the evolution\n", + "evo_time = 2" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the conditions which will cause the pulse optimisation to terminate" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [], + "source": [ + "# Fidelity error target\n", + "fid_err_targ = 1e-3\n", + "# Maximum iterations for the optisation algorithm\n", + "max_iter = 200\n", + "# Maximum (elapsed) time allowed in seconds\n", + "max_wall_time = 30\n", + "# Minimum gradient (sum of gradients squared)\n", + "# as this tends to 0 -> local minima has been found\n", + "min_grad = 1e-20" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the initial pulse type" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "# pulse type alternatives: RND|ZERO|LIN|SINE|SQUARE|SAW|TRIANGLE|\n", + "p_type = 'RND'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Give an extension for output files" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [], + "source": [ + "#Set to None to suppress output files\n", + "f_ext = \"{}_n_ts{}_ptype{}.txt\".format(example_name, n_ts, p_type)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Run the optimisation" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "# Note that this call will take the defaults\n", + "# dyn_type='GEN_MAT'\n", + "# This means that matrices that describe the dynamics are assumed to be\n", + "# general, i.e. the propagator can be calculated using:\n", + "# expm(combined_dynamics*dt)\n", + "# prop_type='FRECHET'\n", + "# and the propagators and their gradients will be calculated using the\n", + "# Frechet method, i.e. an exact gradent\n", + "# fid_type='TRACEDIFF'\n", + "# and that the fidelity error, i.e. distance from the target, is give\n", + "# by the trace of the difference between the target and evolved operators \n", + "result = cpo.optimize_pulse(drift, ctrls, E0, E_targ, n_ts, evo_time, \n", + " fid_err_targ=fid_err_targ, min_grad=min_grad, \n", + " max_iter=max_iter, max_wall_time=max_wall_time, \n", + " out_file_ext=f_ext, init_pulse_type=p_type, \n", + " gen_stats=True)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Report the results" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "------------------------------------\n", + "---- Control optimisation stats ----\n", + "**** Timings (HH:MM:SS.US) ****\n", + "Total wall time elapsed during optimisation: 0:00:00.874979\n", + "Wall time computing Hamiltonians: 0:00:00.014692 (1.68%)\n", + "Wall time computing propagators: 0:00:00.741438 (84.74%)\n", + "Wall time computing forward propagation: 0:00:00.003442 (0.39%)\n", + "Wall time computing onward propagation: 0:00:00.002870 (0.33%)\n", + "Wall time computing gradient: 0:00:00.060661 (6.93%)\n", + "\n", + "**** Iterations and function calls ****\n", + "Number of iterations: 99\n", + "Number of fidelity function calls: 129\n", + "Number of times fidelity is computed: 129\n", + "Number of gradient function calls: 129\n", + "Number of times gradients are computed: 129\n", + "Number of times timeslot evolution is recomputed: 129\n", + "\n", + "**** Control amplitudes ****\n", + "Number of control amplitude updates: 128\n", + "Mean number of updates per iteration: 1.292929292929293\n", + "Number of timeslot values changed: 1280\n", + "Mean number of timeslot changes per update: 10.0\n", + "Number of amplitude values changed: 2560\n", + "Mean number of amplitude changes per update: 20.0\n", + "------------------------------------\n", + "Final evolution\n", + "Quantum object: dims=[[[2], [2]], [[2], [2]]], shape=(4, 4), type='super', dtype=Dense, isherm=False\n", + "Qobj data =\n", + "[[ 0.50233453-3.19965324e-17j 0.43105374-3.05776067e-03j\n", + " 0.43105374+3.05776067e-03j 0.49783518+2.48785704e-17j]\n", + " [ 0.43122246-7.30100353e-04j -0.44947273-3.94083570e-03j\n", + " 0.4537969 -2.23501542e-03j -0.42964721+9.79923387e-04j]\n", + " [ 0.43122246+7.30100353e-04j 0.4537969 +2.23501542e-03j\n", + " -0.44947273+3.94083570e-03j -0.42964721-9.79923387e-04j]\n", + " [ 0.49766547+2.31069658e-17j -0.43105374+3.05776067e-03j\n", + " -0.43105374-3.05776067e-03j 0.50216482-1.58076451e-17j]]\n", + "\n", + "********* Summary *****************\n", + "Initial fidelity error 0.7093424411165612\n", + "Final fidelity error 0.005981406588275161\n", + "Final gradient normal 1.9954485495553325e-05\n", + "Terminated due to function converged\n", + "Number of iterations 99\n", + "Completed in 0:00:00.874979 HH:MM:SS.US\n" + ] + } + ], + "source": [ + "result.stats.report()\n", + "print(\"Final evolution\\n{}\\n\".format(result.evo_full_final))\n", + "print(\"********* Summary *****************\")\n", + "print(\"Initial fidelity error {}\".format(result.initial_fid_err))\n", + "print(\"Final fidelity error {}\".format(result.fid_err))\n", + "print(\"Final gradient normal {}\".format(result.grad_norm_final))\n", + "print(\"Terminated due to {}\".format(result.termination_reason))\n", + "print(\"Number of iterations {}\".format(result.num_iter))\n", + "print(\"Completed in {} HH:MM:SS.US\".format(datetime.timedelta(seconds=result.wall_time)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Plot the initial and final amplitudes" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAnYAAAHVCAYAAAB8NLYkAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjkuMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy80BEi2AAAACXBIWXMAAA9hAAAPYQGoP6dpAABsGUlEQVR4nO3dd1gUV/s38O/QFpAeuiLVLnYltqgRwa4ptkSjWONjjVGjiQGJiSUhtoREk8eeWKPGJCpWiHlsiVhQo0YRFQsQC1IV2D3vH/7Y13UBWdzCLt/Pde0le+bMzH12ttyeOXNGEkIIEBEREZHRMzN0AERERESkHUzsiIiIiEwEEzsiIiIiE8HEjoiIiMhEMLEjIiIiMhFM7IiIiIhMBBM7IiIiIhPBxI6IiIjIRDCxIyIiIjIRTOyISG8kScLs2bPLVdfPzw/Dhg3TeB/Xrl2DJElYvXq1xusau9WrV0OSJFy7ds3QoRCRgTCxI6JyK04cTpw4oZXtHTlyBLNnz0ZmZqZWtmcMdu3aVe7klohIUxaGDoCIqo78/HxYWPz/r50jR44gOjoaw4YNg5OTk0rdS5cuwczM9P7vuWvXLsTGxjK5IyKdYGJHRHpjbW1d7roymUyHkRiHoqIiKBQKWFlZGToUIjISpvffYSLSq2HDhsHOzg63bt1C3759YWdnBzc3N0ydOhVyuVyl7tNj7GbPno1p06YBAPz9/SFJksr4sGfH2N2/fx9Tp05FcHAw7Ozs4ODggG7duuHMmTMVjj0zMxPvvfce/Pz8IJPJUKNGDbzzzju4e/eusk5GRgZGjBgBDw8PWFtbo3HjxlizZo3KdorH9cXExOC7775DYGAgZDIZWrZsib/++kvltYqNjVW+FsWPZ7exePFi5Tb+/vtvAMDBgwfRvn17VKtWDU5OTujTpw8uXLhQoXYnJSVh2LBhCAgIgLW1NTw9PTF8+HDcu3dPpd7s2bMhSRL++ecfDB48GI6OjnBzc8PHH38MIQRSU1PRp08fODg4wNPTE19++aXK+gkJCZAkCZs2bcKHH34IT09PVKtWDb1790ZqaqpK3cuXL+ONN96Ap6cnrK2tUaNGDQwcOBAPHz6sUBuJqir22BHRC5PL5QgPD0dISAhiYmKwf/9+fPnllwgMDMTYsWNLXOf111/HP//8gw0bNmDRokVwdXUFALi5uZVY/+rVq/j555/Rr18/+Pv7Iz09HcuXL0eHDh3w999/w9vbW6OYc3Jy0L59e1y4cAHDhw9Hs2bNcPfuXfzyyy+4efMmXF1dkZ+fj44dO+LKlSsYP348/P39sWXLFgwbNgyZmZmYNGmSyjbXr1+P7OxsjBkzBpIk4fPPP8frr7+Oq1evwtLSEmPGjMHt27exb98+rFu3rsS4Vq1ahUePHmH06NGQyWRwcXHB/v370a1bNwQEBGD27NnIz8/HV199hbZt2+LkyZPw8/PTqO379u3D1atXERERAU9PT5w/fx7fffcdzp8/j2PHjimTzWIDBgxAvXr1MH/+fOzcuROffvopXFxcsHz5crz66qtYsGABfvzxR0ydOhUtW7bEK6+8orL+Z599BkmS8MEHHyAjIwOLFy9GaGgoTp8+DRsbGxQUFCA8PByPHz/GhAkT4OnpiVu3buG3335DZmYmHB0dNWofUZUmiIjKadWqVQKA+Ouvv5RlQ4cOFQDEJ598olK3adOmonnz5iplAERUVJTy+RdffCEAiJSUFLV9+fr6iqFDhyqfP3r0SMjlcpU6KSkpQiaTqew7JSVFABCrVq0qsy2RkZECgNi2bZvaMoVCIYQQYvHixQKA+OGHH5TLCgoKROvWrYWdnZ3IyspS2edLL70k7t+/r6y7Y8cOAUD8+uuvyrJx48aJkr56i7fh4OAgMjIyVJY1adJEuLu7i3v37inLzpw5I8zMzMQ777yjLCs+PiW9nk/Ly8tTK9uwYYMAIA4dOqQsi4qKEgDE6NGjlWVFRUWiRo0aQpIkMX/+fGX5gwcPhI2Njcoxi4+PFwBE9erVla+VEEJs3rxZABBLliwRQghx6tQpAUBs2bKlzLiJ6Pl4KpaItOLdd99Ved6+fXtcvXpVa9uXyWTKiynkcjnu3bsHOzs71KlTBydPntR4e1u3bkXjxo3x2muvqS0r7rHatWsXPD09MWjQIOUyS0tLTJw4ETk5Ofj9999V1hswYACcnZ2Vz9u3bw8AGr0Ob7zxhkqv5Z07d3D69GkMGzYMLi4uyvJGjRqhS5cu2LVrV7m3XczGxkb596NHj3D37l28/PLLAFDiazly5Ejl3+bm5mjRogWEEBgxYoSy3MnJCXXq1Cmxre+88w7s7e2Vz9988014eXkpYy/ukduzZw/y8vI0bg8R/X9M7IjohVlbW6udQnV2dsaDBw+0tg+FQoFFixahVq1akMlkcHV1hZubG5KSkio0Dis5ORkNGzYss87169dRq1Yttatz69Wrp1z+tJo1a6o8L07yNHkd/P391WIAgDp16qjVrVevHu7evYvc3Nxybx94Ml5x0qRJ8PDwgI2NDdzc3JT7Lem1fLZdjo6OsLa2Vp4+f7q8pLbWqlVL5bkkSQgKClKOp/T398eUKVPw3//+F66urggPD0dsbCzH1xFVABM7Inph5ubmOt/H3LlzMWXKFLzyyiv44YcfsGfPHuzbtw8NGjSAQqHQ+f7Lo7TXQQhR7m083ZumK/3798f333+Pd999F9u2bcPevXsRFxcHACW+liW1SxttfdqXX36JpKQkfPjhh8jPz8fEiRPRoEED3Lx5s0LbI6qqePEEERnMs4P0y/LTTz+hU6dOWLFihUp5ZmamWs9ReQQGBuLcuXNl1vH19UVSUhIUCoVKr93FixeVyzWlSZuf3selS5fUll28eBGurq6oVq1aubf34MEDHDhwANHR0YiMjFSWX758WaO4NPHstoUQuHLlCho1aqRSHhwcjODgYMyaNQtHjhxB27ZtsWzZMnz66ac6i43I1LDHjogMpjghKc+dJ8zNzdV6g7Zs2YJbt25VaN9vvPEGzpw5g+3bt6stK95P9+7dkZaWhk2bNimXFRUV4auvvoKdnR06dOig8X41aTMAeHl5oUmTJlizZo3KOufOncPevXvRvXt3jfZf3NP27Gu5ePFijbajibVr1yI7O1v5/KeffsKdO3fQrVs3AEBWVhaKiopU1gkODoaZmRkeP36ss7iITBF77IjIYJo3bw4A+OijjzBw4EBYWlqiV69eJfZA9ezZE5988gkiIiLQpk0bnD17Fj/++CMCAgIqtO9p06bhp59+Qr9+/TB8+HA0b94c9+/fxy+//IJly5ahcePGGD16NJYvX45hw4YhMTERfn5++Omnn3D48GEsXrxY5YIATds8ceJEhIeHw9zcHAMHDixznS+++ALdunVD69atMWLECOV0J46OjhrfwcLBwQGvvPIKPv/8cxQWFqJ69erYu3cvUlJSNG5Lebm4uKBdu3aIiIhAeno6Fi9ejKCgIIwaNQrAkzn6xo8fj379+qF27dooKirCunXrYG5ujjfeeENncRGZIiZ2RGQwLVu2xJw5c7Bs2TLExcVBoVAgJSWlxMTuww8/RG5uLtavX49NmzahWbNm2LlzJ2bMmFGhfdvZ2eGPP/5AVFQUtm/fjjVr1sDd3R2dO3dGjRo1ADwZ75aQkIAZM2ZgzZo1yMrKQp06dbBq1SqVyZM18frrr2PChAnYuHEjfvjhBwghnpvYhYaGIi4uDlFRUYiMjISlpSU6dOiABQsWqF1sUR7r16/HhAkTEBsbCyEEwsLCsHv3bo3nAiyvDz/8EElJSZg3bx6ys7PRuXNnfPPNN7C1tQUANG7cGOHh4fj1119x69Yt2NraonHjxti9e7fyal0iKh9JVHSkKxERURkSEhLQqVMnbNmyBW+++aahwyGqEjjGjoiIiMhEMLEjIiIiMhFM7IiIiIhMBMfYEREREZkI9tgRERERmQhOd/IcCoUCt2/fhr29vcYzxhMRERG9KCEEsrOz4e3trXbv6mcxsXuO27dvw8fHx9BhEBERURWXmpqqnGezNEzsnqN4ZvnU1FQ4ODgYOBoiIiKqarKysuDj41Ouu90wsXuO4tOvDg4OTOyIiIjIYMozJIwXTxARERGZCCZ2RERERCaCp2KJiHRJCKAwz9BRaIelLcDZAYgqNSZ2RES6IgSwMhxIPW7oSLTD52VgeByTO6JKjKdiiYh0pTDPdJI6AEg9Zjq9j0Qmij12RET6MPUKYGVr6CgqpiAPiAkydBREVA5M7IiI9MHKFrCqZugoiMjE8VQsERERkYlgYkdERERkIpjYEREREZkIJnZEREREJoKJHREREZGJYGJHREREZCIqNN1JUVEREhISkJycjLfeegv29va4ffs2HBwcYGdnp+0YifSHt38iIiIjpnFid/36dXTt2hU3btzA48eP0aVLF9jb22PBggV4/Pgxli1bpos4iXSPt38iIiIjp/Gp2EmTJqFFixZ48OABbGxslOWvvfYaDhw4oNXgiPSKt38iIiIjp3GP3R9//IEjR47AyspKpdzPzw+3bt3SWmBEBsXbPxERkRHSOLFTKBSQy+Vq5Tdv3oS9vb1WgiIyON7+iYiIjJDGp2LDwsKwePFi5XNJkpCTk4OoqCh0795dm7ERERERkQY07rH78ssvER4ejvr16+PRo0d46623cPnyZbi6umLDhg26iJGIiIiIykHjxK5GjRo4c+YMNm7ciKSkJOTk5GDEiBF4++23VS6mICIiIiL9qtA8dhYWFhg8eLC2YyEiIqLyMJU5NznfptaVK7H75Zdfyr3B3r17VzgYIiIieg5TmnOT821qXbkSu759+6o8lyQJQgi1MgAlXjFLREREWmJKc24Wz7fJWQi0plyJnUKhUP69f/9+fPDBB5g7dy5at24NADh69ChmzZqFuXPn6iZKIiIiUmesc25yvk2d0XiM3eTJk7Fs2TK0a9dOWRYeHg5bW1uMHj0aFy5c0GqAz4qNjcUXX3yBtLQ0NG7cGF999RVatWpVYt3Vq1cjIiJCpUwmk+HRo0c6jZGIiEgvOOcmPUPjeeySk5Ph5OSkVu7o6Ihr165pIaTSbdq0CVOmTEFUVBROnjyJxo0bIzw8HBkZGaWu4+DggDt37igf169f12mMRERERIaicWLXsmVLTJkyBenp6cqy9PR0TJs2rdSeM21ZuHAhRo0ahYiICNSvXx/Lli2Dra0tVq5cWeo6kiTB09NT+fDw8NBpjERERESGonFit3LlSty5cwc1a9ZEUFAQgoKCULNmTdy6dQsrVqzQRYwAgIKCAiQmJiI0NFRZZmZmhtDQUBw9erTU9XJycuDr6wsfHx/06dMH58+fL3M/jx8/RlZWlsqDiIiIyBhoPMYuKCgISUlJ2LdvHy5evAgAqFevHkJDQ5VXxurC3bt3IZfL1XrcPDw8lHE8q06dOli5ciUaNWqEhw8fIiYmBm3atMH58+dRo0aNEteZN28eoqOjtR4/ERERka5VaIJiSZIQFhaGsLAwbcejVa1bt1ZeuQsAbdq0Qb169bB8+XLMmTOnxHVmzpyJKVOmKJ9nZWXBx8dH57ESERERvSiNE7tPPvmkzOWRkZEVDqYsrq6uMDc3VxnbBzwZ3+fp6VmubVhaWqJp06a4cuVKqXVkMhlkMtkLxUpERERkCBondtu3b1d5XlhYiJSUFFhYWCAwMFBniZ2VlRWaN2+OAwcOKCdMVigUOHDgAMaPH1+ubcjlcpw9exbdu3fXSYxEREREhqRxYnfq1Cm1sqysLAwbNgyvvfaaVoIqzZQpUzB06FC0aNECrVq1wuLFi5Gbm6ucq+6dd95B9erVMW/ePABPehdffvllBAUFITMzE1988QWuX7+OkSNH6jROIqJn5RUUASgydBgVU1AEI5wCl6hKqtAYu2c5ODggOjoavXr1wpAhQ7SxyRINGDAA//77LyIjI5GWloYmTZogLi5OeUHFjRs3YGb2/y/0ffDgAUaNGoW0tDQ4OzujefPmOHLkCOrXr6+zGImIigkhUHxJWfNP9yMf1gaNp6Js8AgX/i/0p9tERJWPVhI7AHj48CEePnyorc2Vavz48aWeek1ISFB5vmjRIixatEjnMRERlSS/UG5yPV35hXLYGvEwZCEE8guN/J7m7EGlMmic2C1dulTluRACd+7cwbp169CtWzetBUZEZEr+mN4JtnYOhg6jQvJysoClz69X2Qkh8Oayo0i8/sDQobwQ9qBSWTRO7J7tATMzM4ObmxuGDh2KmTNnai0wIiJTYmtlDlsrrZ0k0S8rc0NHoBX5hXKjT+qeZew9qKR9Gn/LpKSk6CIOIiIivTkxKxS2RpqwmkoPKumGxond8OHDsWTJEtjb26uU5+bmYsKECWXet5WIiMiwBGzwGLZ4BFvtDTPXL+mxoSOgSkzjd/WaNWswf/58tcQuPz8fa9euZWJHRESVkxD4ySoaLcz+AWIMHUzF8cIJKku5E7usrCwIISCEQHZ2Nqyt//9l+3K5HLt27YK7u7tOgjRpQgCFeYaOQnssbQEd3jOYiKjCCvOeJHUm4i9FbTSwZJpHqsqd2Dk5OUGSJEiShNq1a6stlyQJ0dHRWg2uSijMA+Z6GzoK7fF5GRgex+SOiCq1vEkXYVvNSK9SLij6v3kRZfib37X0jHIndvHx8RBC4NVXX8XWrVvh4uKiXGZlZQVfX194e5tQgkIVk3rsSbJqVc3QkRARlc7S1oi/p4qMdrJr0r1yJ3YdOnQA8OSq2Jo1a0Li/xK0w9IW+PC2oaN4cQV5QEyQoaMgIiKq0sqV2CUlJaFhw4YwMzPDw4cPcfbs2VLrNmrUSGvBVQmSZMT/ayQiIqLKpFyJXZMmTZCWlgZ3d3c0adIEkiRBCKFWT5IkyOVGfqsWIiIiIiNVrsQuJSUFbm5uyr+JiIiIqPIpV2Ln6+tb4t9EREREVHmUK7H75Zdfyr3B3r17VzgYIiIiIqq4ciV2ffv2LdfGOMaOiIiIyHDKldgpFApdx0FEREREL8jM0AEQERERkXZUKLE7cOAAevbsicDAQAQGBqJnz57Yv3+/tmMjIiIiIg1onNh988036Nq1K+zt7TFp0iRMmjQJDg4O6N69O2JjY3URIxERERGVQ7lvKVZs7ty5WLRoEcaPH68smzhxItq2bYu5c+di3LhxWg2QiIiIiMpH4x67zMxMdO3aVa08LCwMDx8+1EpQRERERKQ5jRO73r17Y/v27WrlO3bsQM+ePbUSFBERERFpTuNTsfXr18dnn32GhIQEtG7dGgBw7NgxHD58GO+//z6WLl2qrDtx4kTtRUpEREREZdI4sVuxYgWcnZ3x999/4++//1aWOzk5YcWKFcrnkiQxsSMiIiLSI40Tu5SUFF3EQUREREQviBMUExEREZkIjXvshBD46aefEB8fj4yMDLXbjW3btk1rwRERERFR+WncYzd58mQMGTIEKSkpsLOzg6Ojo8pD12JjY+Hn5wdra2uEhITgzz//LLP+li1bULduXVhbWyM4OBi7du3SeYxEREREhqBxj926deuwbds2dO/eXRfxlGnTpk2YMmUKli1bhpCQECxevBjh4eG4dOkS3N3d1eofOXIEgwYNwrx589CzZ0+sX78effv2xcmTJ9GwYUO9x09ERESkSxr32Dk6OiIgIEAXsTzXwoULMWrUKERERKB+/fpYtmwZbG1tsXLlyhLrL1myBF27dsW0adNQr149zJkzB82aNcPXX3+t58iJiIiIdE/jxG727NmIjo5Gfn6+LuIpVUFBARITExEaGqosMzMzQ2hoKI4ePVriOkePHlWpDwDh4eGl1geAx48fIysrS+VBREREZAw0PhXbv39/bNiwAe7u7vDz84OlpaXK8pMnT2otuKfdvXsXcrkcHh4eKuUeHh64ePFiieukpaWVWD8tLa3U/cybNw/R0dEvHjARERGRnmmc2A0dOhSJiYkYPHgwPDw8IEmSLuIymJkzZ2LKlCnK51lZWfDx8TFgRERERETlo3Fit3PnTuzZswft2rXTRTylcnV1hbm5OdLT01XK09PT4enpWeI6np6eGtUHAJlMBplM9uIBExEREemZxmPsfHx84ODgoItYymRlZYXmzZvjwIEDyjKFQoEDBw4o71n7rNatW6vUB4B9+/aVWp+IiIjImGmc2H355ZeYPn06rl27poNwyjZlyhR8//33WLNmDS5cuICxY8ciNzcXERERAIB33nkHM2fOVNafNGkS4uLi8OWXX+LixYuYPXs2Tpw4gfHjx+s9diIiIiJd0/hU7ODBg5GXl4fAwEDY2tqqXTxx//59rQX3rAEDBuDff/9FZGQk0tLS0KRJE8TFxSkvkLhx4wbMzP5/rtqmTRusX78es2bN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ERGRIRk0sXNzc4Obm5tOtu3v7w9PT08cOHBAmchlZWXh+PHjGDt2rE72SURERGRIRnPxxI0bN3D69GncuHEDcrkcp0+fxunTp5GTk6OsU7duXWzfvh3Ak9OCkydPxqeffopffvkFZ8+exTvvvANvb2/07dvXQK0gIiIi0h2jGRAVGRmJNWvWKJ83bdoUABAfH4+OHTsCAC5duoSHDx8q60yfPh25ubkYPXo0MjMz0a5dO8TFxWk0h13xPXF5dSwREREZQnEOUpyTlEUS5alVhd28eZMXTxAREZHBpaamokaNGmXWYWL3HAqFArdv34a9vb3OpsAovvI2NTUVDg4OOtlHZcR2s91VQVVtN1B12852s93aJoRAdnY2vL29YWZW9ig6ozkVayhmZmbPzY61xcHBoUp9GIqx3VUL2131VNW2s91Vi67b7ejoWK56RnPxBBERERGVjYkdERERkYlgYlcJyGQyREVFVbmJkdlutrsqqKrtBqpu29luttuQePEEERERkYlgjx0RERGRiWBiR0RERGQimNgRERERmQgmdkREREQmgokdERERkYlgYqcDsbGx8PPzg7W1NUJCQvDnn3+WWX/Lli2oW7curK2tERwcjF27dqksF0IgMjISXl5esLGxQWhoKC5fvqzLJlSYJm3//vvv0b59ezg7O8PZ2RmhoaFq9YcNGwZJklQeXbt21XUzNKZJu1evXq3WJmtra5U6xnLMNWl3x44d1dotSRJ69OihrGMMx/vQoUPo1asXvL29IUkSfv755+euk5CQgGbNmkEmkyEoKAirV69Wq6Pp94a+adrubdu2oUuXLnBzc4ODgwNat26NPXv2qNSZPXu22vGuW7euDluhOU3bnZCQUOL7PC0tTaWeqR3vkj67kiShQYMGyjrGcLznzZuHli1bwt7eHu7u7ujbty8uXbr03PUq0+84Ezst27RpE6ZMmYKoqCicPHkSjRs3Rnh4ODIyMkqsf+TIEQwaNAgjRozAqVOn0LdvX/Tt2xfnzp1T1vn888+xdOlSLFu2DMePH0e1atUQHh6OR48e6atZ5aJp2xMSEjBo0CDEx8fj6NGj8PHxQVhYGG7duqVSr2vXrrhz547ysWHDBn00p9w0bTfw5NYzT7fp+vXrKsuN4Zhr2u5t27aptPncuXMwNzdHv379VOpV9uOdm5uLxo0bIzY2tlz1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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig1 = plt.figure()\n", + "ax1 = fig1.add_subplot(2, 1, 1)\n", + "ax1.set_title(\"Initial control amps\")\n", + "ax1.set_xlabel(\"Time\")\n", + "ax1.set_ylabel(\"Control amplitude\")\n", + "for j in range(n_ctrls):\n", + " ax1.step(result.time, \n", + " np.hstack((result.initial_amps[:, j], result.initial_amps[-1, j])), \n", + " where='post')\n", + "\n", + "ax2 = fig1.add_subplot(2, 1, 2)\n", + "ax2.set_title(\"Optimised Control Sequences\")\n", + "ax2.set_xlabel(\"Time\")\n", + "ax2.set_ylabel(\"Control amplitude\")\n", + "for j in range(n_ctrls):\n", + " ax2.step(result.time, \n", + " np.hstack((result.final_amps[:, j], result.final_amps[-1, j])), \n", + " where='post')\n", + "fig1.tight_layout()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Versions" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
SoftwareVersion
QuTiP5.1.0.dev0+0b4260e
Numpy1.26.4
SciPy1.13.0
matplotlib3.9.0
Number of CPUs8
BLAS InfoGeneric
IPython8.25.0
Python3.12.3 | packaged by Anaconda, Inc. | (main, May 6 2024, 19:46:43) [GCC 11.2.0]
OSposix [linux]
Cython3.0.10
Thu Jan 30 09:54:22 2025 IST
" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 11, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qutip.ipynbtools import version_table\n", + "\n", + "version_table()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": true + }, + "outputs": [], + "source": [] + } + ], + "metadata": { + "anaconda-cloud": {}, + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.3" + } + }, + "nbformat": 4, + "nbformat_minor": 1 +} diff --git a/tutorials-v5/optimal-control/control-pulseoptim-QFT.ipynb b/tutorials-v5/optimal-control/control-pulseoptim-QFT.ipynb new file mode 100644 index 00000000..c06dfec6 --- /dev/null +++ b/tutorials-v5/optimal-control/control-pulseoptim-QFT.ipynb @@ -0,0 +1,642 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Calculation of control fields for QFT gate on two qubits using L-BFGS-B algorithm" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alexander Pitchford (agp1@aber.ac.uk)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Example to demonstrate using the control library to determine control\n", + "pulses using the ctrlpulseoptim.create_pulse_optimizer function to \n", + "generate an Optimizer object, through which the configuration can be\n", + "manipulated before running the optmisation algorithm. In this case it is\n", + "demonstrated by modifying the initial ctrl pulses. Also re-uses objects in repeated runs with different total evolution times.\n", + "\n", + "The (default) L-BFGS-B algorithm is used to optimise the pulse to\n", + "minimise the fidelity error, which is equivalent maximising the fidelity\n", + "to optimal value of 1.\n", + "\n", + "The system in this example is two qubits in constant fields in x, y and z\n", + "with variable independant controls fields in x and y acting on each qubit\n", + "The target evolution is the QFT gate. The user can experiment with the\n", + "different:\n", + " * evolution times - evo_times list values, try anything \n", + " * phase options - phase_option = SU or PSU\n", + " * propagtor computer type prop_type = DIAG or FRECHET\n", + " * fidelity measures - fid_type = UNIT or TRACEDIFF\n", + "\n", + "The user can experiment with the timeslicing, by means of changing the\n", + "timeslots durations.\n", + "Different initial (starting) pulse types can be tried.\n", + "The initial and final pulses are displayed in a plot\n", + "\n", + "This example assumes that the example-control-pulseoptim-Hadamard has already been tried, and hence explanations in that notebook are not repeated here." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "import datetime" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "from qutip import Qobj, identity, sigmax, sigmay, sigmaz, tensor\n", + "from qutip_qip.algorithms import qft\n", + "\n", + "#QuTiP control modules\n", + "import qutip_qtrl.pulseoptim as cpo\n", + "import qutip_qtrl.pulsegen as pulsegen\n", + "\n", + "example_name = 'QFT'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the physics" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Note here that there are two controls acting on each qubit." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "Sx = sigmax()\n", + "Sy = sigmay()\n", + "Sz = sigmaz()\n", + "Si = 0.5*identity(2)\n", + "\n", + "# Drift Hamiltonian\n", + "H_d = 0.5*(tensor(Sx, Sx) + tensor(Sy, Sy) + tensor(Sz, Sz))\n", + "# The (four) control Hamiltonians\n", + "H_c = [tensor(Sx, Si), tensor(Sy, Si), tensor(Si, Sx), tensor(Si, Sy)]\n", + "n_ctrls = len(H_c)\n", + "# start point for the gate evolution\n", + "U_0 = identity(4)\n", + "# Target for the gate evolution - Quantum Fourier Transform gate\n", + "U_targ = qft(2)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the time evolution parameters" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Multiple total evolution times will be tried. Using this approach, the minimum evolution time required to achieve the target fidelity could be determined (iteratively).\n", + "\n", + "Note that the timeslot duration dt is fixed, and so the number of timeslots depends on the evo_time" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Duration of each timeslot\n", + "dt = 0.05\n", + "# List of evolution times to try\n", + "evo_times = [1, 3, 6]\n", + "n_evo_times = len(evo_times)\n", + "evo_time = evo_times[0]\n", + "n_ts = int(float(evo_time) / dt)\n", + "#Empty list that will hold the results for each evolution time\n", + "results = list()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the conditions which will cause the pulse optimisation to terminate" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Fidelity error target\n", + "fid_err_targ = 1e-5\n", + "# Maximum iterations for the optisation algorithm\n", + "max_iter = 200\n", + "# Maximum (elapsed) time allowed in seconds\n", + "max_wall_time = 120\n", + "# Minimum gradient (sum of gradients squared)\n", + "# as this tends to 0 -> local minima has been found\n", + "min_grad = 1e-20" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the initial pulse type" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here the linear initial pulse type is used, simply because it results in smooth final pulses" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# pulse type alternatives: RND|ZERO|LIN|SINE|SQUARE|SAW|TRIANGLE|\n", + "p_type = 'LIN'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Give an extension for output files" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "#Set to None to suppress output files\n", + "f_ext = \"{}_n_ts{}_ptype{}.txt\".format(example_name, n_ts, p_type)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Create the optimiser objects" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here is the main difference between this and the Hadamard example. In this case we use a different pulseoptim function that just creates the objects that can be used to set the physics and configure the optimisation algorithm. This gives greater flexibility (shown here by seting different initial pulse parameters for each control) and is also more efficient when running multiple optimisations on the same system." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "optim = cpo.create_pulse_optimizer(H_d, H_c, U_0, U_targ, n_ts, evo_time, \n", + " amp_lbound=-5.0, amp_ubound=5.0, \n", + " fid_err_targ=fid_err_targ, min_grad=min_grad, \n", + " max_iter=max_iter, max_wall_time=max_wall_time, \n", + " optim_method='fmin_l_bfgs_b',\n", + " method_params={'max_metric_corr':20, 'accuracy_factor':1e8},\n", + " dyn_type='UNIT', \n", + " fid_params={'phase_option':'PSU'},\n", + " init_pulse_type=p_type, \n", + " gen_stats=True)\n", + "\n", + "# **** get handles to the other objects ****\n", + "optim.test_out_files = 0\n", + "dyn = optim.dynamics\n", + "dyn.test_out_files = 0\n", + "p_gen = optim.pulse_generator\n", + " " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Optimise the pulse for each of the different evolution times" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here a loop is used to perform the optimisation for each of the evo_times given in the list above. The first optimisation is completed using the timeslot parameters passed when the optimisation objects are created. For the subsequent runs, the Dynamics object 'dyn' is used to set the timeslot parameters before the initial pulses are generated and optimisation is completed. Note that using this method, the dyn.initialize_controls method must be called with an array of the initial amplitudes before the optim.run_optimization method is called." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Initial amplitudes output to file: ctrl_amps_initial_QFT_n_ts20_ptypeLIN.txt\n", + "***********************************\n", + "\n", + "+++++++++++++++++++++++++++++++++++\n", + "Starting pulse optimisation for T=1\n", + "+++++++++++++++++++++++++++++++++++\n", + "\n", + "Final amplitudes output to file: ctrl_amps_final_QFT_n_ts20_ptypeLIN.txt\n", + "\n", + "------------------------------------\n", + "---- Control optimisation stats ----\n", + "**** Timings (HH:MM:SS.US) ****\n", + "Total wall time elapsed during optimisation: 0:00:00.239246\n", + "Wall time computing Hamiltonians: 0:00:00.014204 (5.94%)\n", + "Wall time computing propagators: 0:00:00.177386 (74.14%)\n", + "Wall time computing forward propagation: 0:00:00.001417 (0.59%)\n", + "Wall time computing onward propagation: 0:00:00.001277 (0.53%)\n", + "Wall time computing gradient: 0:00:00.025678 (10.73%)\n", + "\n", + "**** Iterations and function calls ****\n", + "Number of iterations: 56\n", + "Number of fidelity function calls: 58\n", + "Number of times fidelity is computed: 58\n", + "Number of gradient function calls: 58\n", + "Number of times gradients are computed: 58\n", + "Number of times timeslot evolution is recomputed: 58\n", + "\n", + "**** Control amplitudes ****\n", + "Number of control amplitude updates: 57\n", + "Mean number of updates per iteration: 1.0178571428571428\n", + "Number of timeslot values changed: 630\n", + "Mean number of timeslot changes per update: 11.052631578947368\n", + "Number of amplitude values changed: 1261\n", + "Mean number of amplitude changes per update: 22.12280701754386\n", + "------------------------------------\n", + "Final evolution\n", + "Quantum object: dims=[[4], [4]], shape=(4, 4), type='oper', dtype=Dense, isherm=False\n", + "Qobj data =\n", + "[[-0.18496187+0.47646074j 0.00650274+0.32387897j -0.78128529+0.06667085j\n", + " -0.08600938+0.10763398j]\n", + " [ 0.0091788 +0.3089635j 0.15052907-0.4653102j -0.10161082-0.24956273j\n", + " 0.76676768+0.06888927j]\n", + " [-0.7898436 +0.03568447j -0.0602883 -0.2559864j 0.11247485+0.50171211j\n", + " 0.04752862-0.19770026j]\n", + " [-0.06513334+0.11774096j 0.76595754+0.00573387j 0.02496387-0.21806685j\n", + " -0.21183752-0.54965389j]]\n", + "\n", + "********* Summary *****************\n", + "Final fidelity error 0.34374119125360847\n", + "Final gradient normal 0.014751686098976114\n", + "Terminated due to function converged\n", + "Number of iterations 56\n", + "Completed in 0:00:00.239246 HH:MM:SS.US\n", + "Initial amplitudes output to file: ctrl_amps_initial_QFT_n_ts20_ptypeLIN.txt\n", + "***********************************\n", + "\n", + "+++++++++++++++++++++++++++++++++++\n", + "Starting pulse optimisation for T=3\n", + "+++++++++++++++++++++++++++++++++++\n", + "\n", + "Final amplitudes output to file: ctrl_amps_final_QFT_n_ts20_ptypeLIN.txt\n", + "\n", + "------------------------------------\n", + "---- Control optimisation stats ----\n", + "**** Timings (HH:MM:SS.US) ****\n", + "Total wall time elapsed during optimisation: 0:00:00.373056\n", + "Wall time computing Hamiltonians: 0:00:00.022471 (6.02%)\n", + "Wall time computing propagators: 0:00:00.286680 (76.85%)\n", + "Wall time computing forward propagation: 0:00:00.002560 (0.69%)\n", + "Wall time computing onward propagation: 0:00:00.002160 (0.58%)\n", + "Wall time computing gradient: 0:00:00.043716 (11.72%)\n", + "\n", + "**** Iterations and function calls ****\n", + "Number of iterations: 29\n", + "Number of fidelity function calls: 36\n", + "Number of times fidelity is computed: 36\n", + "Number of gradient function calls: 35\n", + "Number of times gradients are computed: 35\n", + "Number of times timeslot evolution is recomputed: 36\n", + "\n", + "**** Control amplitudes ****\n", + "Number of control amplitude updates: 35\n", + "Mean number of updates per iteration: 1.206896551724138\n", + "Number of timeslot values changed: 2100\n", + "Mean number of timeslot changes per update: 60.0\n", + "Number of amplitude values changed: 8390\n", + "Mean number of amplitude changes per update: 239.71428571428572\n", + "------------------------------------\n", + "Final evolution\n", + "Quantum object: dims=[[4], [4]], shape=(4, 4), type='oper', dtype=Dense, isherm=False\n", + "Qobj data =\n", + "[[-0.18922387+0.46120317j -0.19352353+0.46212201j -0.19278561+0.46360969j\n", + " -0.18771204+0.46167283j]\n", + " [-0.18926712+0.46237894j -0.46052942-0.19175575j 0.19104394-0.46161315j\n", + " 0.46401084+0.19140406j]\n", + " [-0.19133929+0.46005139j 0.19127929-0.46261849j -0.19190677+0.46291531j\n", + " 0.19214148-0.46162888j]\n", + " [-0.19289196+0.46519277j 0.46053463+0.1934903j 0.19031547-0.45932179j\n", + " -0.46156574-0.19135913j]]\n", + "\n", + "********* Summary *****************\n", + "Final fidelity error 9.09345058086597e-06\n", + "Final gradient normal 0.00021946915681973\n", + "Terminated due to Goal achieved\n", + "Number of iterations 29\n", + "Completed in 0:00:00.373056 HH:MM:SS.US\n", + "Initial amplitudes output to file: ctrl_amps_initial_QFT_n_ts20_ptypeLIN.txt\n", + "***********************************\n", + "\n", + "+++++++++++++++++++++++++++++++++++\n", + "Starting pulse optimisation for T=6\n", + "+++++++++++++++++++++++++++++++++++\n", + "\n", + "Final amplitudes output to file: ctrl_amps_final_QFT_n_ts20_ptypeLIN.txt\n", + "\n", + "------------------------------------\n", + "---- Control optimisation stats ----\n", + "**** Timings (HH:MM:SS.US) ****\n", + "Total wall time elapsed during optimisation: 0:00:00.634567\n", + "Wall time computing Hamiltonians: 0:00:00.038307 (6.04%)\n", + "Wall time computing propagators: 0:00:00.495125 (78.03%)\n", + "Wall time computing forward propagation: 0:00:00.004598 (0.72%)\n", + "Wall time computing onward propagation: 0:00:00.003715 (0.59%)\n", + "Wall time computing gradient: 0:00:00.072676 (11.45%)\n", + "\n", + "**** Iterations and function calls ****\n", + "Number of iterations: 24\n", + "Number of fidelity function calls: 30\n", + "Number of times fidelity is computed: 30\n", + "Number of gradient function calls: 29\n", + "Number of times gradients are computed: 29\n", + "Number of times timeslot evolution is recomputed: 30\n", + "\n", + "**** Control amplitudes ****\n", + "Number of control amplitude updates: 29\n", + "Mean number of updates per iteration: 1.2083333333333333\n", + "Number of timeslot values changed: 3480\n", + "Mean number of timeslot changes per update: 120.0\n", + "Number of amplitude values changed: 13920\n", + "Mean number of amplitude changes per update: 480.0\n", + "------------------------------------\n", + "Final evolution\n", + "Quantum object: dims=[[4], [4]], shape=(4, 4), type='oper', dtype=Dense, isherm=False\n", + "Qobj data =\n", + "[[ 0.4620758 +0.19122715j 0.46151636+0.19126417j 0.46241052+0.19094127j\n", + " 0.46213112+0.19102767j]\n", + " [ 0.46199149+0.19151454j -0.19197958+0.46204899j -0.46180318-0.19115039j\n", + " 0.19122368-0.46170712j]\n", + " [ 0.46165031+0.19097801j -0.46193761-0.1917004j 0.46197027+0.19137927j\n", + " -0.46218878-0.19133733j]\n", + " [ 0.46216726+0.19134259j 0.19167781-0.46173526j -0.46181095-0.19132534j\n", + " -0.19139753+0.46188943j]]\n", + "\n", + "********* Summary *****************\n", + "Final fidelity error 2.433648946809086e-07\n", + "Final gradient normal 0.0006194193096311807\n", + "Terminated due to Goal achieved\n", + "Number of iterations 24\n", + "Completed in 0:00:00.634567 HH:MM:SS.US\n" + ] + } + ], + "source": [ + "for i in range(n_evo_times):\n", + " # Generate the tau (duration) and time (cumulative) arrays\n", + " # so that it can be used to create the pulse generator\n", + " # with matching timeslots\n", + " dyn.init_timeslots()\n", + " if i > 0:\n", + " # Create a new pulse generator for the new dynamics\n", + " p_gen = pulsegen.create_pulse_gen(p_type, dyn)\n", + " \n", + " #Generate different initial pulses for each of the controls\n", + " init_amps = np.zeros([n_ts, n_ctrls])\n", + " if (p_gen.periodic):\n", + " phase_diff = np.pi / n_ctrls\n", + " for j in range(n_ctrls):\n", + " init_amps[:, j] = p_gen.gen_pulse(start_phase=phase_diff*j)\n", + " elif (isinstance(p_gen, pulsegen.PulseGenLinear)):\n", + " for j in range(n_ctrls):\n", + " p_gen.scaling = float(j) - float(n_ctrls - 1)/2\n", + " init_amps[:, j] = p_gen.gen_pulse()\n", + " elif (isinstance(p_gen, pulsegen.PulseGenZero)):\n", + " for j in range(n_ctrls):\n", + " p_gen.offset = sf = float(j) - float(n_ctrls - 1)/2\n", + " init_amps[:, j] = p_gen.gen_pulse()\n", + " else:\n", + " # Should be random pulse\n", + " for j in range(n_ctrls):\n", + " init_amps[:, j] = p_gen.gen_pulse()\n", + " \n", + " dyn.initialize_controls(init_amps)\n", + " \n", + " # Save initial amplitudes to a text file\n", + " if f_ext is not None:\n", + " pulsefile = \"ctrl_amps_initial_\" + f_ext\n", + " dyn.save_amps(pulsefile)\n", + " print(\"Initial amplitudes output to file: \" + pulsefile)\n", + "\n", + " print(\"***********************************\")\n", + " print(\"\\n+++++++++++++++++++++++++++++++++++\")\n", + " print(\"Starting pulse optimisation for T={}\".format(evo_time))\n", + " print(\"+++++++++++++++++++++++++++++++++++\\n\")\n", + " result = optim.run_optimization()\n", + " results.append(result)\n", + "\n", + " # Save final amplitudes to a text file\n", + " if f_ext is not None:\n", + " pulsefile = \"ctrl_amps_final_\" + f_ext\n", + " dyn.save_amps(pulsefile)\n", + " print(\"Final amplitudes output to file: \" + pulsefile)\n", + " \n", + " # Report the results\n", + " result.stats.report()\n", + " print(\"Final evolution\\n{}\\n\".format(result.evo_full_final))\n", + " print(\"********* Summary *****************\")\n", + " print(\"Final fidelity error {}\".format(result.fid_err))\n", + " print(\"Final gradient normal {}\".format(result.grad_norm_final))\n", + " print(\"Terminated due to {}\".format(result.termination_reason))\n", + " print(\"Number of iterations {}\".format(result.num_iter))\n", + " print(\"Completed in {} HH:MM:SS.US\".format(\n", + " datetime.timedelta(seconds=result.wall_time)))\n", + " \n", + " if i+1 < len(evo_times):\n", + " # reconfigure the dynamics for the next evo time\n", + " evo_time = evo_times[i+1]\n", + " n_ts = int(float(evo_time) / dt)\n", + " dyn.tau = None\n", + " dyn.evo_time = evo_time\n", + " dyn.num_tslots = n_ts" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Plot the initial and final amplitudes" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAABKUAAAMWCAYAAAAgRDUeAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjkuMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy80BEi2AAAACXBIWXMAAA9hAAAPYQGoP6dpAAEAAElEQVR4nOzdeXxTVf7/8Xfa0jYFCgVaSqVCkV1FtgFBHFEqRRwVd0YdFkdQvjIu6Kg4gIIoLqiIMtYZRVFBGcdlxtFBAcUVkUV+bsiog4BAAaFQaWuX9P7+6CQkbdImaZZ7k9fz8ciD5ube5ARKTu7nnvM+NsMwDAEAAAAAAAARlBDtBgAAAAAAACD+UJQCAAAAAABAxFGUAgAAAAAAQMRRlAIAAAAAAEDEUZQCAAAAAABAxFGUAgAAAAAAQMRRlAIAAAAAAEDEUZQCAAAAAABAxFGUAgAAAAAAQMRRlAICYLPZdOedd0a7GQCAKKAPAID4Rj8AhB5FKcSVZ555RjabTRs2bAjJ83388ce68847dejQoZA8nxU4/w4bu3Xu3LlJr7N161bdeOONGjp0qFJTU2Wz2fTDDz+E5D0AiE/0AU0XqT7g1VdfVUFBgXJycpSSkqKOHTvqoosu0pdffhmaNwIgLtEPNF2k+gGn5cuXa8iQIWrevLlat26toUOH6p133gnJc8MckqLdAMBKysvLlZR09L/Nxx9/rNmzZ2vChAlq3bp19BoWQb/+9a/13HPPeWy76qqrNGjQIE2ePNm1rUWLFk16nbVr12rhwoXq3bu3evXqpc2bNzfp+QCgqegDItcHfPHFF8rIyND111+vdu3aqaioSIsXL9agQYO0du1anXTSSU16fgAIBv1A5PoBSbrzzjs1Z84cXXTRRZowYYKqqqr05ZdfateuXU1+bpgHRSkgAKmpqdFuQtR16dJFXbp08dh2zTXXqEuXLrriiitC9jrnnnuuDh06pJYtW2r+/PkUpQBEHX1A5PqAWbNm1dt21VVXqWPHjnr88cdVWFgYstcCAH/RD0SuH/jkk080Z84cPfjgg7rxxhtD9rwwH6bvIe5NmDBBLVq00K5duzRmzBi1aNFCmZmZuvnmm+VwODz2dZ9Hfuedd+qPf/yjJCkvL881VLWhKWYffPCBLr74Yh177LFKSUlRbm6ubrzxRpWXl3tt044dO/Sb3/xGLVq00DHHHKNFixZJqr2CfMYZZ6h58+bq1KmTli1b5nG8c1jt+++/r6uvvlpt27ZVenq6xo0bp+LiYo99N2zYoIKCArVr1052u115eXm68sorg/mrDKk2bdqoZcuW0W4GgBhHH2DOPsCbrKwspaWlxdU0GQDhRz9gzn5gwYIFys7O1vXXXy/DMHTkyJFoNwlhwkgpQJLD4VBBQYEGDx6s+fPna9WqVXrwwQd13HHHacqUKV6PueCCC/Sf//xHL7zwgh5++GG1a9dOkpSZmenzdV566SWVlZVpypQpatu2rT799FM9+uij+vHHH/XSSy/Va9NZZ52lX//617r//vu1dOlSTZ06Vc2bN9ef/vQnXX755brgggtUWFiocePGaciQIcrLy/N4jqlTp6p169a68847tXXrVj3++OPavn271qxZI5vNpn379mnkyJHKzMzUbbfdptatW+uHH37QK6+80sS/0aMqKir0888/+7Wv8+8QACKJPsC8fcChQ4dUVVWloqIiLViwQCUlJRoxYkTI2gcAEv2AGfuB1atXa+jQoVq4cKHmzp2rAwcOKDs7W3/60580derUkLUPJmAAceTpp582JBnr1693bRs/frwhyZgzZ47Hvv369TMGDBjgsU2Scccdd7juP/DAA4YkY9u2bX69fllZWb1t8+bNM2w2m7F9+/Z6bbrnnntc24qLiw273W7YbDbjxRdfdG3/5ptv6rXL+T4HDBhgVFZWurbff//9hiTjH//4h2EYhvHqq6/W+/sIRvPmzY3x48d7fczZFn9uvgT69wwA3tAHWK8P6NGjh+vxFi1aGDNmzDAcDkeT2gsgftEPWKMfOHjwoCHJaNu2rdGiRQvjgQceMJYvX26MGjXKkGQUFhY2qb0wF0ZKAf9zzTXXeNw/9dRT64X4NZXdbnf9XFpaqvLycg0dOlSGYeizzz7Tscce67H/VVdd5fq5devW6tGjh7777jtdcsklru09evRQ69at9d///rfe602ePFnNmjVz3Z8yZYpuv/12vfnmmzr33HNdgYz/+te/dNJJJ3nsGyoFBQVauXJlyJ8XAEKJPsCcfcDTTz+tkpIS/fe//9XTTz+t8vJyORwOJSSQQAEgtOgHzNMPOKfqHThwQC+++KIuvfRSSdJFF12kE088UXPnztXVV18d8rYiOihKAaoNLaw71DYjI6PenOum2rFjh2bNmqV//vOf9Z778OHDjbapVatW6tixo2w2W73t3trarVs3j/stWrRQhw4dXHPdTzvtNF144YWaPXu2Hn74YQ0fPlxjxozRZZddppSUlGDfpocOHTqoQ4cOIXkuAAgH+gDz9gFDhgxx/Tx27Fj16tVLkjR//vwmtw0AnOgHzNUPOIt3zZo100UXXeTanpCQoEsvvVR33HGHduzYUa+IB2uiKAVISkxMDPtrOBwOnXnmmTp48KBuvfVW9ezZU82bN9euXbs0YcIE1dTU+NUmX9sNwwi4TTabTX//+9/1ySef6PXXX9dbb72lK6+8Ug8++KA++eSTkCzlWl5eXq+T9SU7O7vJrwcAgaIPsEYfkJGRoTPOOENLly6lKAUgpOgHzNUPtGnTRqmpqWrdunW995uVlSVJKi4upigVIyhKAU1Q9ypFQ7744gv95z//0ZIlSzRu3DjX9nBObfv22291+umnu+4fOXJEe/bs0ejRoz32O/nkk3XyySfr7rvv1rJly3T55ZfrxRdf9BgyHKzly5dr4sSJfu0bTGcKANFCH9C4UPcBgZzcAEC40Q80Lph+ICEhQX379tX69etVWVmp5ORk1z67d++W1HCgPKyFohTQBM2bN5ckv5andlb53b90G4ahRx55JCxtk6S//OUvmjhxomt++OOPP67q6mqdddZZkmqvMLRu3dqjQ+3bt6+k2pUyQoFMKQCxij6gccH2Afv27XNdDXf64YcftHr1ag0cODAkbQOApqIfaFyw/cCll16qTz75REuWLNGkSZMkSb/88ouWLl2q3r17KycnJyTtQ/RRlAKaYMCAAZKkP/3pTxo7dqyaNWumc845x9VBuevZs6eOO+443Xzzzdq1a5fS09P18ssvh3yuurvKykqNGDFCl1xyibZu3ao///nPGjZsmM4991xJ0pIlS/TnP/9Z559/vo477jj9/PPP+utf/6r09PR6V1CCFWyeyOHDh/Xoo49Kkj766CNJ0mOPPabWrVurdevWLAULIOroAxoXbB9w4oknasSIEerbt68yMjL07bff6qmnnlJVVZXuvffekLQNAJqKfqBxwfYDV199tZ588klde+21+s9//qNjjz1Wzz33nLZv367XX389JG2DOVCUAprgV7/6le666y4VFhZqxYoVqqmp0bZt27x2RM2aNdPrr7+u6667TvPmzVNqaqrO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7NHKlStVVVWliRMnavLkyVq2bFmDx02aNElz5sxx3U9z++LqcDh09tlnKzs7Wx9//LH27NmjcePGqVmzZrrnnnvC9l4QmOL9O5tckNqeY1P3zNwQtQgAAABApHmbtkeoObwh/Nw6LFGU2rJli1asWKH169dr4MCBkqRHH31Uo0eP1vz585WTk+Pz2LS0NGVnZ3t97O2339bXX3+tVatWqX379urbt6/uuusu3XrrrbrzzjuVnJwclveD4CUtf1IZWb7/vX3pnpmrREa/AYAlsdIeQoEV+QDrcvYDNV6m7ZEjiIYQfm5+ljhLX7t2rVq3bu0qSElSfn6+EhIStG7dOp1//vk+j126dKmef/55ZWdn65xzztHMmTNdo6XWrl2rE088Ue3bt3ftX1BQoClTpuirr75Sv379wvemEJSMrBy165AX7WYAACKElfYQKqzIB1iTr36AaXvwB+Hn5meJolRRUZGysrI8tiUlJalNmzYqKiryedxll12mTp06KScnR59//rluvfVWbd26Va+88orred0LUpJc9xt63oqKClVUVLjul5SUBPyeAABA41hpD03BinyA9XnrBwg2RyAIPze3qP7t33bbbbrvvvsa3GfLli1BP//kyZNdP5944onq0KGDRowYoe+//17HHXdc0M87b948zZ49O+jjAQBA4FhpD4FiRT7A2ryFmifY7Xz+I2CEn5tXVItSN910kyZMmNDgPl26dFF2drb27dvnsb26uloHDx70mRflzeDBgyVJ3333nY477jhlZ2fr008/9dhn7969ktTg806fPl3Tpk1z3S8pKVFuLiHaAACEEyvtIRisyAdYk69Qc/oBBIvwc3OKag+dmZmpzMzMRvcbMmSIDh06pI0bN2rAgAGSpHfeeUc1NTWuQpM/Nm/eLEnq0KGD63nvvvtu7du3zzU9cOXKlUpPT1fv3r19Pk9KSopSUlL8fl0AAOA/92BzQs0RToSfA+ZDqDnCjfBzc7HEZaNevXpp1KhRmjRpkgoLC1VVVaWpU6dq7NixrpX3du3apREjRujZZ5/VoEGD9P3332vZsmUaPXq02rZtq88//1w33nijfv3rX6tPnz6SpJEjR6p379763e9+p/vvv19FRUWaMWOGrr32WopOAABEAcHmiCTCzwFzIdQckUD4ubkkRLsB/lq6dKl69uypESNGaPTo0Ro2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Tz5Zt956q1atWqVBgwapa9euGjlypC677DKdcsopQb0/bwYMGBCy5wIAb+gDYrMPSE9PV35+viTpvPPO07Jly3Teeedp06ZNOumkk0LVRAAxgH4gtvoBZ/HunHPOcRWkJOnkk09WXl6ePv7445C1D5FDphTgJjExsdF9PvjgA5177rlKTU3Vn//8Z7355ptauXKlLrvsMhmGEfBrBvp8vtroa3swberVq5e2bt2qF198UcOGDdPLL7+sYcOG6Y477gj4uXw5ePCgioqKGr0dPnw4ZK8JAA2hD6hltT7gggsukCS9+OKLIWsfgPhEP1DLrP2Ac9RU+/bt6z1fVlaWXyOvYD6MlAIC9PLLLys1NVVvvfWWUlJSXNuffvppUzxfY3bv3q3S0lKPKyT/+c9/JMljaG/z5s116aWX6tJLL1VlZaUuuOAC3X333Zo+fXpIltC94IIL9N577zW63/jx4z1WRgGAaKIPMF8fUFFRoZqaGi5iAIgI+oHo9QPO0VW7du2qt9/u3bvVs2fPJrcLkUdRCghQYmKibDabx9KwP/zwg1577TVTPF9jqqur9cQTT2jatGmSpMrKSj3xxBPKzMx0fdAfOHBAbdu2dR2TnJys3r1769///reqqqpC0hGRKQXAiugDotcHHDp0SM2bN1ezZs089nnyySclKaApOgAQLPqB6PUDPXr00EknnaR//OMf+umnn9SuXTtJ0ttvv62dO3fqD3/4Q5PbhcijKAUE6Oyzz9ZDDz2kUaNG6bLLLtO+ffu0aNEide3aVZ9//nnUn68xOTk5uu+++/TDDz+oe/fuWr58uTZv3qy//OUvri/6I0eOVHZ2tk455RS1b99eW7Zs0WOPPaazzz7bI0CxKYLNE3n//ff1/vvvS5L279+v0tJSV6Dhr3/9a/36178OSfsAwBv6gOj1AWvWrNF1112niy66SN26dVNlZaU++OADvfLKKxo4cKCuuOKKkLQNABpCPxDdc4GHH35YZ555poYNG6arr75ahw8f1kMPPaTu3btrypQpIWkbIotMKSBAZ5xxhp566ikVFRXphhtu0AsvvKD77rtP559/vimerzEZGRl68803tWHDBv3xj3/Uzp079dhjj2nSpEmufa6++modOXJEDz30kK699lq99tpruu666/T888+HpU2BeOeddzRz5kzNnDlT+/bt0w8//OC6/84770S7eQBiHH1A9Jx44ok6/fTT9Y9//EM33XSTbrvtNn3zzTeaNWuW1qxZo+Tk5Ki2D0B8oB+IrtNPP10rVqxQRkaGbr/9dj366KMaM2aM3nvvPY/wc1iHzQgm+QyAJQ0fPlw//fSTvvzyy2g3BQAQYfQBABDf6AdgRoyUAgAAAAAAQMRRlAIAAAAAAEDEUZQCAAAAAABAxJEpBQAAAAAAgIhjpBQAAAAAAAAijqIUAAAAAAAAIi4p2g2IBTU1Ndq9e7datmwpm80W7eYAgCkYhqGff/5ZOTk5SkiI3Wsg9AEAUF+89AES/QAAeONvP0BRKgR2796t3NzcaDcDAExp586d6tixY7SbETb0AQDgW6z3ARL9AAA0pLF+gKJUCLRs2VJS7V92enp6lFsDAOZQUlKi3Nxc12dkrKIPAID64qUPkOgHAMAbf/sBilIh4Bymm56eTkcEAHXE+lQG+gAA8C3W+wCJfgAAGtJYPxDbE7wBAAAAAABgShSlAAAAAAAAEHEUpQAAAAAAABBxFKUAAAAAAAAQcRSlAAAAAAAAEHEUpQAAAAAAABBxFKUAAAAAAAAQcRSlAAAAAAAAEHEUpQAAAAAAABBxFKUAAAAAAAAQcUnRbkA8MwxD5VWOaDcjMIYhVZVFuxWxr1maZLNF9CUNw5BRXh7R14w7hiFVR+fv2JaaKlsTfqfsaS1lS+A6BgD4yzAMlXv5zLcn2Zv0eQwAQLjVPTe02cPXd1GUiqLyKod6z3or2s0IgKG/J8/WwIT/RLshMW99TXddXHmHpAh9aTUMzf9gkY4/+ENkXg8RZ29XoU4jDgRd6yy7eYfSWrQKbaMAIEYZhqFx/x6nzfs313usX1Y/LRm1hMIUAMCUDMPQ9ssuV/lnn7m29di0Uba0tLC8HkUp+M2uCgpSEfKrhP/IrgqVKzUir5fiqKQgFePKf0qR4bDJlmREuykAEHPqjooqry73WpCSpM/2faby6nKlNQvPl3sAAJrCKC/3KEiFG0WpKLI3S9TXcwqi3Qz/VZZK82t/LLv+m9opZgitqjKlPdJTkrRxRr6U3DwiL1tTVqad//qTJKnju2tks9sj8rpxxe3ftuz/NkXs/49RXq4fR46ufd3rv1FCkP+29rSWoWwWAMSMhkZFSdKaS9bInmRXeXW5hv9teETbBgBAU3T76EMl2O1hPT+kKBVFNptNaclW+ic42ta05ukRK5jElUq3v+PkJClCvx811Udfp3mrlkoI09DMuFaZKP1vlFKLdu0jWnB0Smuezr8tAIRYQ6Oi+mX1U5vUNkzVAwBYUoLdHvbzBytVRAAAAADTco6KciLUHACAhlGUAgAAAELAnmT3Kyuq7qp8FK8AAPGKohQAAAAQQXWzpViRDwAQrxKi3QAAAADAKgzDUFlVmetWd9STL/Yku/pl9fP6mHNFPgAAosUwDNWUlammPLL9ESOlAAAAAD80ttJeQ2w2m5aMWuJRfGJFvuh7/PHH9fjjj+uHH36QJB1//PGaNWuWzjrrrOg2DAAiyDAMbb/scpV/9lnEX5uiFAAAAOCHxlbacw8598Zms/mVOYXI6dixo+69915169ZNhmFoyZIlOu+88/TZZ5/p+OOPj3bzACAijPLyegUpe//+stkb7tdCgaIUAAAAECBW2osN55xzjsf9u+++W48//rg++eQTilIA4lK3jz5Ugt0umz0y/RpFKQAAACBA/q60B+twOBx66aWXVFpaqiFDhvjcr6KiQhUVFa77JSUlkWgeAEREgt2uhLTI9W8EnQMAAACIW1988YVatGihlJQUXXPNNXr11VfVu3dvn/vPmzdPrVq1ct1yc3Mj2FoAiC0UpQAAAADErR49emjz5s1at26dpkyZovHjx+vrr7/2uf/06dN1+PBh123nzp0RbC0AxBam7wEAAAAWZBiGDC9Ld0cqByRWJCcnq2vXrpKkAQMGaP369XrkkUf0xBNPeN0/JSVFKSkpkWwiAMQsilIAAABAlJVXexaXGgtOb2j5bnv//uq09HkKU0GqqanxyIwCAIQPRSkAAAAgyob/bbjH/X5Z/bRk1BKfhSVvy3c7lW/aJKO8XLYIBtVa1fTp03XWWWfp2GOP1c8//6xly5ZpzZo1euutt6LdNACICMMwVONl1G2kUJQCAAAAosCeZFe/rH76bF/94tJn+z5TeXW5Xyv8OZfvrikv17enDAtHU2PWvn37NG7cOO3Zs0etWrVSnz599NZbb+nMM8+MdtMAIOwaGnUbKRSlAAAAgCiw2WxaMmqJx9S98uryeqOmGhPp5btjyVNPPRXtJgBA1NQddWvv3182uz2ibaAoBQAAAHhhGEa9glGo2Ww2v0ZDAQAQTt0++lCJbdpEPI+QohQAAABQh2EYGvfvcdq8f3O0mwIAQNglRGnl1oSIvyIAAABgcuXV5T4LUv2y+smeFNnpDQAAxCJGSgEAAAANWHPJGo8ilD0pOleTAQCINRSlAAAAgAbYk+zkPgEAEAYUpQAAAAAAAOKEYRgyystVUx76BTwCRaYUAATKMKTK0gBvZdFuNfxw7733ymaz6YYbboh2UwAAAICQMwxD2y+7XFv7D9C3pwyLdnMYKQUAATEMaXGBtHNdtFuCEFu/fr2eeOIJ9enTJ9pNAQAAAMLCKC9X+WefeWyz9+8vmz06C3gwUqoOrpIDaFBVWdMKUrknS+SSmM6RI0d0+eWX669//asyMjKi3RwAAAAg7Lp99KF6bNqoTkufj9oCHoyUcsNVcgABufk7KTnAAlOzNIkVm0zn2muv1dlnn638/HzNnTs32s0BAAAAwi7BbldCWnQvmFOU+h/3q+SckADwS3KalNw82q1AE7344ovatGmT1q9f79f+FRUVqqiocN0vKSkJV9MAAACAmMb0vf9xv0oOAIgPO3fu1PXXX6+lS5cqNTXVr2PmzZunVq1auW65ublhbqUF+Ar/N4xotwywtPLqcpVVlbluRpD/pwzDUE1ZWb1bsM8HAECoMFJKXCUHgHi1ceNG7du3T/3793dtczgcev/99/XYY4+poqJCiYmJHsdMnz5d06ZNc90vKSmJ78JUQ+H/2SdKE1d4TlllCivgt+F/G+5xv19WPy0ZtSSg3A/nKkt1Q20lKaVXL3V+/jmP/5M2uz1quSIAgPgT90Up51XylStXBnSVfPbs2WFuGQAg3EaMGKEvvvjCY9vEiRPVs2dP3XrrrfUKUpKUkpKilJSUSDXR/BoK/y/6Qpp3jOe23JOlK1dQmAJ8sCfZ1S+rnz7bV7+I9Nm+z1ReXa60ABbM8LbKklPFli3aOmCg5+v37x/VwFsAQHyJ+6IUV8kBIH61bNlSJ5xwgse25s2bq23btvW2438Mo7YQ5VTp9rMz/N8wpKdH1Ral6tr5Se3x5LHBZAzDUHl1ueu++8+RZLPZtGTUknptqTtqKhjdPvpQCXa7ZBj64YrfqWLLlnr7lG/aJKO8XLYoB98CAELPMAzVlEenf/Ml7otSXCUHAMBPDU3VkzzD/6/+oH7xan7X8LcRCIJhGBr373HavH9ztJsiqbYwVW80lGEopUqqKStXTTMFdVLhvspS3isvy3B7jprycn17yrAmtRsAYF4NTeeOprgvSnGVHADgbs2aNdFugnk1NFUv9+TavCgnm833aCj30VUSOVOIuvLqcp8FqX5Z/WRPske2QXUYhqE5zznUc5e088HQFI5sNhujoQAgjtSdzm3v3182e3T7N4miFAAACIZzqp5TIIWluiOmyJmCiay5ZI1HEcqeFP3gb6P8F/Xc5f0xXycVzpFUZpumAQCIvm4ffajENm2i3r9JFKW84io5AACNcJ+q549mabXFp52f1H+MnCmYiD3JHlCQeKR1XLNSzdPbuO77Wi2PqXgAAF8STLTSKkUpAAAQfjZb7WgocqaAJrG55UJ5e8zev7/KN22q95hZpmkAAOCOohQAAPCuoZX2gtFQzhSAJrPZbOq09HmPAHPXYya6Kg4AgBNFKQAAUF9jK+0BMCUCzAEAVkJRCgAA1BfISnuhwIp8gGl4C0dnpBUAIBwoSgEAgIY1ZaU9f7EiH2Aa3kLSe2zayAgsALAgwzBklJebdjVWilIAAKBhga605y9W5ANMo6GQdACANRmGoe2XXa7yzz6LdlN8oigFAACigxX5ANNoKCRdEiv3AYAFGeXl9QpSZluNlaIUAACIHlbkA0yDkHQAiF3dPvpQCXa76TICKUoBAAAAAADEsAS7XQkmvPBAUQoAAEiGUX8aHQDT+cVRrgS3/6v2JHNd8QYAIBAUpQCTMQzJcNiksnKpOvAvmWYbjgnAAgxDWlwg7VwX7ZYAaMSol0epIvloP98vq5+WjFpC3w8AsCSKUoCJGIah7avbqfynZOnvpwb1HPb+/dVp6fN8OQXgv6oy3wWp3JNrV8kDEDX2pFSfj3227zOVV5crjf+nAAALoigFmIhR/kttQaoJyjdtklFeTlApgODc/J2U7Pb50SytNow8GtynEEazHYg5hmGovProKnPuP5uR+4WmNZe8p4Q0u8qryzX8b8Oj1yg0Wd3fQ7NNxTQMQ+VVjnrb7c0STdVOANZGUQowqW7vvq2EVm393r+mvFzfnjIsjC0CEBeS08yzGt78rkd/zj1ZunIFhSk0mWEYGvfvcdq8f3O0mxKUtGZ2JTAqKiaUV5dr8LLBrvtmmoppGIYuKlyrjduL6z02sFOGXrpmiCnaCcA3wzBUU27uiy4SRSnAtMy6OgIAhFWztNoC1M5PPLfv/KR2mqFZCmawrPLqcp8FqX5Z/WRPske2QcD/mGkqZnmVw2tBSpI2bC/WgdJKpSUnMmoKMCnDMLT9sstV/tln0W5KoyhKAQAA87DZakdEOVcXqyzzHDEFhNCaS9Z4FKHMNn0Ksc2eZNe6y9aZfirmhhn5SktOVFmlQwPnrpKko38yagowJaO83KMgZe/fXza7OS+6UJQCzKqqTKos9X//SvMPzQQAv9hsjIhCRNiT7KYYlYL4ZLPZ6v3+OTOmolkgNQxDZZVHs6TSkhOVlpwke7NEDeyUoQ1uI6g2bC9WeZVDacmcVgJm1e2jD5XYpo1pi8d8egBm9UgfKcnwf/9qm6QOtT8bARwHAAAAU3COmIpWvlRDWVI2m00vXTNE5VUOj1FTAMwtwW7uUcAJ0W4AADfNQjSksopRUwAaYBi1IzFdt7LGjwEQMYZhqKas7OjNAkG1CJ49ya5+Wf08tjnzpSKtbpbUwE4ZsjdLdN232WxKS05SWnKit8MBIGCMlALMxL2CffN3UloARarDB6S/F4S+TQBii2FIiwukneui8NKG15MscnyAo6wUTovQsNlsWjJqicqry4PLlzKMozl8zdJCtkrphhn5ats8udHP57JKB4HnAIJGUQowq+S02pu/mnEVFYAfqsp8F6RyT649oQkBbwWo8SvG65uD39Tb10zLoAPRVjec1p2Zg2rRNN7ypRrlHPX69Cip6IvabdknShNX1BammligSkv2r9A0cO4qAs8BBI2iFAAA8erm7zyL3yG6wm4Yhsb9e5w279/s1/5+L4Ned5phCEcEAGbU7aMPleBWhLKZPBcEEeRr1GvRF9K8Y2p/zj25djXTMPzO1A09J/AcQLD41AAAIF4lp4Vllbvy6nKfBamebXpqyaglrv0CmqYyv6vn/TCecAFmkGC3KyGN1QHhRd1Rr+1PrP1z7xdHt+38pHY/Pz7nDcNwBZj7wxl6fqC0ksBzwEQMw5BRXm6pLEKKUgAAIGzWXLJG9qSjIz0Czo9qllZbfNr5Sf3HAjjhAoCYdfN3UvN2tT9XldWOKq1bxG9AQyvuNaQ29JzAc8AsrJpJSFEKAACEjT3JHnhOijubrXY0VJXb1L0AT7gAIGY4Q83dpzMnu01lDqJIX3fFPan+qnsAzM9bJqEVsggpSgEAAHOz2RgNBTSg7qICrGgZG8qryz3/LYNZPbWyLKD8vQ0z8pWWnBjUanrOqX+sxAdEnzOT0ApZhBSlAACIZe5LhUv1w8JNgpNqIHh1s9lY0TI2DP/bcM9/S2+rpza2aur8rgHl76UlJwYdVu7MlmIlPiD6rJRJSFEKAIBYFcxV9SjhpBoIjD3Jrn5Z/fTZvvrZIX6vaAnNmzdPr7zyir755hvZ7XYNHTpU9913n3r06BGV9tT9d/X5b+lcPdXbKKi6WXxhzN+ruwqfxEp8AALDJwUAxImyqnIlVAV3LKNWLMrbVXWnxq6uRwAn1UDwbDabloxa4jHKMOAVLaH33ntP1157rX71q1+purpat99+u0aOHKmvv/5azZtHftqw89/14C8HG/63bGj1VGcWX+lPYc/fc67C51y5j5X4AASKohQAxDDDMFw/D//baapIDq6wtO6ydRQHrM55Vd0pgIyRcOGkGpFgGEa937FYYbPZ+GxuohUrVnjcf+aZZ5SVlaWNGzfq17/+dVTaZLPZPFYtlVQ78jWQ6dc2m+dnfhjVrsLHaSWA4PDpAQAxrLz6l2g3AWbR0FX1JmrKST8n1QgnwzA07t/jtHn/5mg3BRZx+PBhSVKbNm2i3BI3FpqKDSA6DMNQTbk1L7pQlAKAOLHiwhVKaxncl+x6V2yB/+GkH2ZWXl3u83ezX1Y/PtvgoaamRjfccINOOeUUnXDCCT73q6ioUEVFhet+SUlJeBtWXe5ZkDLB9GsA5mEYhrZfdrnKP6sfh2AFFKUAIE6kJtoZkYKQi/pJf93pLCaYlghzWnPJGo/fR7LyUNe1116rL7/8Uh9++GGD+82bN0+zZ8+OUKvquPk7qXm7wD/nnJ+VdT4jDcNQWaUjhA0EEGlGeblHQcrev79sdutcdKEoBQBArDCM2nBzp0DyR0IgKif9dUN8A1j6HPHFnkRhHr5NnTpV//rXv/T++++rY8eODe47ffp0TZs2zXW/pKREubm54W5ireQgC+/Oz0q3z0jDMHRR4VptdFs5L1TKKh2yN0uk8AtEWLePPlRimzaW+r9HUQoAgFhggsyRiJ30113u3F0Ylz4HEHsMw9Af/vAHvfrqq1qzZo3+f3t3Hh9Vfe+P/3WyTDLDJhHCIjGAoOAeiCCL19AiRNtaer8Vb1UWtbT6A5UiVWhVSqWit7i01gvWK5qrdcG9rYor0UJBy+ZSgRIVTFFAiBLMHDLJ5PP7YziTM2fO7Gef1/PxyANmMsl8TpI5Z877vJdBgwal/JqSkhKUlJRYsLoc6e0rVftIuS0cE5CqruwJf3GhIU9dveR1VFf2xFNXjXHVyTGR2xX43ZcFzKAUERGRF7QFEwekvNZ/RBl3rs0KM3n0ORF5z+zZs/HYY4/hhRdeQLdu3bB3714AQI8ePeB3UfmLLvW+MsU+cuNNE3FsF19OJ7P+4kJUV/bExqOBro27v4LcFuZkPiJKinsIIiIir5nfEDsK3It9liSJ2VBElLPly5cDAGpqamLuf+ihhzBz5kzrF6Qnl1LsNPeVAV/upXaSJOGpq8bgYEsI1Utez+l7EVH+YFCKiIjIa3wBBmyIiNIghLB7CfrU6/rd6fatI0OSJCHgM6YEkIjyA4NSREREbmRzU3MryO1y9P+clEaUGfXrB+BryHU0vz8A3ivFJqKcCCEgZBkdss7+wkUYlCIiInIbBzQ1t0LNqpro/6vKq1BXW8eTaqI0qV8/AF9DbibPfhcIlMFf6q6JWkRkHiEEdl9yKeQtW+xeSs4K7F4AERFRXhICCLXof6QqJ/FwU3N/kR9V5VVx92/ZvyUu84OIYiV6/QB8DblZzYv/D6OfmoAZr8x0brkhEVlKyHJcQMo/YgQkFw5oYKYUERGRHdqCwG399T/X9zTg8tWJm5OrS/U81tRckiTU1dZFT57ldjku44PIS5TyC0UuZRja1w/A15Bb+QtLUXXkCLaUlkbvUwKLARddeAiGwgAik/mY5UVkjqHr1qLA74fkd2eZNoNSRERETrP3A2Dpcek91oNNzSVJctVJF1G2zCi/4OvHGyRJQt0X+yFLEuSffYCa5y4w7puHgpZl1CpT+Kore+Kpq8a48oSZyOkK/H4UBNy732dQioiIyA7FAeAXn8feJwTwUG0kKJUOl5fqmUbb9N3l2WPkXXrlFwq3lmGQcSQAASGAIoP/DpYNiRw/Lvursd/3KH9xIaore2Lj7q+i923c/RXktjACPp5+ElEs7hWIiIjsIEn6GU4//VvsVL1kGGzRt2xI7O2Ks4ErkpRDEjmAUn6hcGsZBhlACOMnqhYHIvvCxg2R240bEGw5bOxzHCVJEp66agzktjCCoXA0W4qIjCGEcP3EPTUGpYiIiJwkUbCKktOecKk1bogE+vhzJQdze/kFGcSs6aqSBFyxGqLlS0jLhgIAzvnvNQBKk39d1k8nMSuKyARemrqn4J6CiIiI3O/oCVdMllkoGJ81RZ4mhIhr8k3kKtrpqhVnG1e+J0mQUQJt6LO6sif8xYXGPAcRmUpb9u2FUm8GpYiIiMgbmGWW14QQmP7ydGz9cqvdS3EsbZDOX8QSQUeb3wB06QWYFFz92w0TEOjanZPxiFxq6Lq1KCwrc/3rl0EpIiIiShszUcip5HY5YUCqqrwKfqObRbtQzaqamNtV5VWoq61z/QmNZ/nM7RsY8BWyxI7IxQo80nuQeyEiIiJKCzNRyC3qp9bHBKHyOSPIX+RHVXkVtuyP7z+yZf8WyO0yApziSRYIhsLMyiKiOHkflFq6dCmeffZZbN++HX6/H2PHjsUdd9yBk046ye6lEREROQozUcgt/EV+BlqOkiQJdbV1cRmO2qwpIrNVL3kd1ZU98dRVYxiYIsqQEAJClj01dU+R90Gpt956C7Nnz8ZZZ52F9vZ2/OIXv8CkSZPw0UcfoUsX9qUgIiLSw0wUIveQJIlBOrKFv7gQ1ZU9sXH3VwCAjbu/gtwWZtkgUQa8OHFPLe/3BqtXr465/fDDD6O8vBybNm3Cf/zHf9i0KiIiImdjJgoRkYGEiEzeCwVTP9ZFJEnCU1eNwcGWEKqXvG73cohcSTtxD7Bg6p6yT1IUm9fjLu+DUlqHDh0CAJSVlSV8TGtrK1pbW6O3m5ubTV8XEREREZHROJHPAYQAVk4GGt+xeyWmkCQJAV+h3csg8oSh69ZGGpyb2eRcb5/0i89Nm3DsqKBUe3s76uvr8fHHH+OSSy5Bt27d8Pnnn6N79+7o2rWr6c/f0dGBuXPnYty4cTj11FMTPm7p0qVYvHix6eshIiLvEkJAbgun/Xg2h+XJM5EZtL2lhpUNQ11tXdzj+HozUVswPiBVcXYkM4GISKXA70dBwOR9g94+yUSOCUrt3r0btbW1+Oyzz9Da2orzzjsP3bp1wx133IHW1lasWLHC9DXMnj0bH374IdauXZv0cQsXLsS8efOit5ubm1FRUWH28oiIyEPktjBOvuWVtB/P5rA5jrPXlsSYmIZO5HTJJvJtb9qO0Y+Njrv/nUveYcmuFeY3AL6ANfuotiAQKuL+kMjBhBD2NjdX75NM4pig1HXXXYfq6mq89957OPbYY6P3/+AHP8CsWbNMf/45c+bgr3/9K95++20MGDAg6WNLSkpQUlJi+pqIiIgU+doc1rBx9suGxN6uOBu4YjVPxCgv6U3kA4AZq2dge9N2m1ZFACInfyaVyGgFfjcs8h/uD4kcyRENzi3YJznmne3f/vY3/P3vf4fP54u5f+DAgdizZ49pzyuEwDXXXIPnnnsO9fX1GDRokGnPRUREpPAXF+KjX09O+bhgKJzXzWFzGmdfHIicbDVuiP9c44ZIloBFJ39ETqM3kW/Vd1fFBaoU6mmbZB+5Xc6tlLI4gH90nIizCv7VeZ/F+8NgKFK6zrJ0ouS0Dc5Nb25uE8cEpTo6OhAOx/fW+Pe//41u3bqZ9ryzZ8/GY489hhdeeAHdunXD3r17AQA9evSA34O/cCIiirV06VI8++yz2L59O/x+P8aOHYs77rgDJ510kqnPG2n86pjDsKNlPc5ekiJX/9XTY0LB+KwpIgKQw2uNLFOzqiaz0mUtScJFoUXwoxWbbhzbmS1lIeVCC8vSidI3dN1aFJaVefL1UmD3AhSTJk3CPffcE70tSRK++eYbLFq0CBdccIFpz7t8+XIcOnQINTU16NevX/TjySefNO05iYjIOd566y3Mnj0bGzZswGuvvYa2tjZMmjQJLS0tdi+NjCBJkav/0Q+ecBORQwgBhFrie95pKGXMCqV0OfOnE0ezlCTIKLW0kbq/uBDVlT1j7lPK0okolhACHcFgTC+pAjOn7dnMMZdo77zzTkyePBknn3wyjhw5gksuuQQ7d+5Er1698Pjjj5v2vEII0743kV06ZBnwJX+DE/d4ojy1evXqmNsPP/wwysvLsWnTJvzHf/yHTavSp5Q8KFj6QETkYm1B4Lb+KR+mlDE3HWlKr3RZhxACP1yxHpt2f5XV1+dKkiQ8ddUYyG3hvC9LJ0rGEX2kLOaYoNSAAQPw3nvv4YknnsD777+Pb775BldeeSUuvfRSltERZWjnhEl2L4HItQ4dOgQAKCsrs3kl8bRv4ln6QETkIRVnJ8xekiQpp75ecls4JiBVXdkT/uLCrL9fNli2TpSato8U4N1eUgpH7RWKiopw2WWX2b0MIleS/KXw92qFfCD7yZBe3+ERpdLR0YG5c+di3LhxOPXUU3Uf09raitbW1ujt5uZmU9eklDxs1Lm6na8T+YiAyNVkbQN8ypEQsT3Y1IoDnM5mtOIA8IvPY29b8DPeeNNEHNvFBynR75qIbCGEiKlgGbpubaRsz8Ole4DNQak///nPaT/2wgsvNHElRO4nSRIqv30QIiwB8xuy6pvi9R0eUSqzZ8/Ghx9+iLVr1yZ8zNKlS7F48WLL1qQueVCw9IHynRAC01+ejq1fbrV7Kd4hBLByMtD4jv7nf/E5p1UaTel5Z7GAzzml38FQmKXoRNAv2yvw+1EQ8H4vTFuDUlOmTIm5LUlSXI8nZQelN5mPiGJJEiAVCSDgZzNfogzNmTMHf/3rX/H2229jwIABCR+3cOFCzJs3L3q7ubkZFRUVpq6NJQ9EseR2OWFAqqq8KqcyJzMJISBUV8Ed1dOxLZg4IEVkkuolr7MUnfKaclzo0JTt5VMFi63vcDs6OqL/f/3113HjjTfitttuw5gxYwAA69evx0033YTbbrvNriUSEZHHCSFwzTXX4LnnnkN9fT0GDRqU9PElJSUoKcm+TJaIjFU/tT4mCOUvcmbWr6ua1+plXFs4qY28TVuWzlJ0ykdCCIhgELsum4bWbdtiPjd03VoUlpU58lhmBse88ufOnYsVK1Zg/Pjx0fsmT56MQCCAn/zkJ9im+UUREREZYfbs2XjsscfwwgsvoFu3bti7dy8AoEePHhy04XXaMezsmeNK/iI/Ai4ImOg1r1U47oq4L8BSPTKNUpZ+sCXEUnTKO8mCUUDkeJBPASnAQUGpjz/+GMccc0zc/T169MCuXbssXw8REeWH5cuXAwBqampi7n/ooYcwc+ZM6xdE1lk2JPZ2xdnAFasZmCLTKc1rFezpSPkmUpZu7fQ/Iitoy7Q1n9QNRpUMH46Bjz4CSFJeHg8cE5Q666yzMG/ePDzyyCPo06cPAGDfvn34+c9/jlGjRtm8OiIi8iptL0PyuOJAJPjUuCH+c40bIn11mCFCJsuX5rVERPkiVQaUHiUYJQUCeReIUnNMUGrlypX4wQ9+gOOPPz7aMLaxsRFDhw7F888/b+/iiIiIyBskKZINpR6FHgrGZ00REZFlgqHIUCtO4iM3iWZFJciASoTBqFiOCUoNGTIE77//Pl577TVs374dADB8+HBMnDiRvygiIiIyjk1j2IkcRYj44Czlr1DQ1r56Sm8pTuIjN0iVFaUux9OTjyV6yTgmKAVEaosnTZqESZMm2b0UIiIicgG5PbZvg1MnrxE5ihDAyslA4zt2r4ScYtkQy/vqaafwAdZP4hNCQG4LJ30Ms7dILdkkVWZAZccxQalf//rXST9/yy23WLQSIiIiAo6+WVcFfbQBICeoWVUTc7uqvAp1tXV8M0iUTFswcUCq4uxIxgx5n7bHnsV99ZQpfHJbGMFQ2NJJfEIIBENhXLRiPT76ojnpY5m9RUBnqV6HZpJqvjcpN4JjglLPPfdczO22tjZ8+umnKCoqwgknnMCgFBERkQ6lD4fCqCu6QghMf3k6tn65NefvZTR/kR9V5VXYsj/+KuWW/Vsgt8sI8KSaKD3zGwCf6vViYwkXWUzpsddywLa+epEpfNZmRQmBtIJRio27v8LBlhCO7eJjwCFPJcqOGrpuLQrLyvh3kSPHBKW26KS/NTc3Y+bMmfjBD35gw4qIiIicT3tl2agrunK7nDAgVVVeBX+RX/dzVpAkCXW1dXFZXNqsKSJKgy/AHmv5TJJig5IOEAyFDS+ZE0LghyvWY5OqVFBxcr/uR4+b8euI9rpa8jozpvKUEALhpqa4gJR/xAjvBaSUXoMW9xh0TFBKT/fu3bF48WJ873vfw7Rp0+xeDhERkSPo9eFQmNGPo35qfUwQygl9myRJYjYUEVEKSnaQNqvWyYwOAAkhcLAlFBeQUoJRAZ9+AEx7rFUypgK+QvaZyhN6GVJD161Fgd/vvVI9G3sNOjooBQCHDh3CoUOH7F4GERGRY6j7cCjM7MfhL/IzAERE5DLJsoOcRi8AZMQFFr2fwcabJqYVWFKOtQdbQjEZUwD7THldov5RnsyOUuj1GrSox6BjglK///3vY24LIfDFF1/gkUcewfnnn2/TqoiIiJzJyj4clLlEE514dT07bmi6T+Q0cls4LiBVXdkT/uJCm1aUmF4AKBfqDDH1z6C6smdGvaEkScKxXXy2Twkk67B/FDp7DVrUY9Axr6K777475nZBQQF69+6NGTNmYOHChTatioiIiPKKto9CFm/IMu1dwkBVck5uuu8aSp8QhcX9Qsh4SmA23XLqdLOD7BS52NIZMFNKDjNZc7KpehtvmphVs3I7pwSS9YQmOwrweIaUHot7DTomKPXpp5/avQQiIiLKd9oJVBVnR6ZTZfBGVC87QfHRF804ZdErMfexDCQ5JzfddwUb+4SQeZTBDlXlVairrUu5/wj4Cl2X1ZNpqVyyCwKZZkhp6WUnm9GQnewlhECH3JmJ69n+UQ7jmD3TFVdcgd/97nfo1q1bzP0tLS245pprsHLlSptWRkRERJ5WHIgEnxo3xH+ucUMkwyTJFUNtqZ66obCSnZBsBDnLQNLnxKb7jqfXJ0RhUb8QMoa/yI+q8ips2d+ZxbFl/xbI7bJn+v7pDfJQGownCiolKtVTZ6aaETziRD5v0SvbK/D7URDwxmvLyRzz7qeurg633357XFBKlmX83//9H4NSREREZA5JimRDacubtFlTOlI1ElZnJ7x47XjLmtN7FZvu50jpE6KwqF8IGUOSJNTV1kFulyG3y9FsKS9JVCpXveT1uCATAMNL9VIxqyE72U9btucfMQKSn5m4VrD91dPc3Bzpbi8EDh8+jNLS0ujnwuEwXnrpJZSXl9u4QiIiIvI8Scqqf0KyUj1tQ+Fkzem149pZEkKmsLhPCBlPkiTPB2aVfaU2AKQufx7erzsAYJtO9mmupXqp1mZkQ3ayn3rSniKvmpo7gO1BqWOOOQaSJEGSJJx44olxn5ckCYsXL7ZhZURERETpU0r1FJkElrQnNywJIaJ8pwSA9LKhtMEos0v1tOtS7+vJvRJN2itgDylL2R6UWrNmDYQQ+Na3voVnnnkGZWVl0c/5fD5UVlaif//+Nq6QiIiIKLVMGwnr9U5RsCTE/ZSr7wr1VXgiSo8kSehSUhQtf9b251OCUQGffdml2UwJJGdINGmPZXvWsv2dzrnnngsgMn3v+OOP5wuZiIiIHCtZU/NMqXunqL8fS0LcL9HVd3Kmt99+G7/97W+xadMmfPHFF3juuecwZcoUu5dFKuryZ3V/PicEgjKdEkjOwEl7zmFrUOr999/HqaeeioKCAhw6dAgffPBBwseefvrpFq6MiIiIKFaqpubZSNZnitxL7+q7glfhnaelpQVnnHEGrrjiCvznf/6n3cuhFJyw30w0JZAZru7ASXvOYusr5swzz8TevXtRXl6OM888E5IkQQgR9zhJkhAOZ38lkoiIiChXmTQ1NwKbn3uDcvVdwavwznP++efj/PPPt3sZzhA6OoWUkxmTSjQlkNyBk/acxdag1KefforevXtH/09ERESUK7k9tnePv8j4IEAuTc3Txebn3mD51XchgLZg5+1QMPFjibSWDYn8W3E2cMVqBqaScELGFuWOk/bsZ+urqLKyUvf/RERERNmqWVUTc7uqvAp1tXWGvuHMtKl5utj8nHIiBLByMtD4jt0r8bTW1la0trZGbzc3Nyd5tAsUByJBqMYNnfc1bogEN31d7FuXCwVDYWa1OpgygELdS4qT9uxn67uaP//5z2k/9sILLzRxJURERORm/iI/qsqrsGV/fB+fLfu3QG6XESjOMltFyTQJtcOPI5BRksNKk2Pz86PN5FXZbtrMN0qiLZg4IFVxdiT4QDlbunQpFi9ebPcyjCNJkayotmBkf6dkS1HGqpe8zqxWh+IACueyNSiV7lQL9pQiIiJKXz72IpIkCXW1dXHBDG3WVFaOnqAFAGwrBf7RcSIgJuf+fRPI55IQIQSmvzwdW7/cavdS3G9+A+BTBaHYI8gwCxcuxLx586K3m5ubUVFRYeOK4gkhMpsOKknMisqSNsOVWa3OpDeAgr2knMHWV0pHR4edT09ERORJ+dqLSJKk7LOhtPTKWY46q+BfCLYFgZIexjwXRcntcsKAVFV5FfxFPHlImy/AIINJSkpKUFJiXsZkrsyYFEqJKRmuB1tCeZXV6iZCiJiSPWUABQdPOAPDt0RERB7AXkQGU5ezHBVsaUbgd8NsXFR+qZ9aHxOEMqNhPREAfPPNN2hoaIje/vTTT7F161aUlZXh+OOPt3Fl2dFOCjVjOijFimS48mfsRHple5YPoKCkHPXu9I033sDdd9+Nbdu2AQCGDx+OuXPnYuLEiTavjIiIyNnYi8gE2nKWULt9azkqn0oz/UV+4zLfiJLYuHEjJkyYEL2tlObNmDEDDz/8sE2rMsbGmybi2C4+z+4niFLRlu2xZM95HBOU+p//+R9cd911+OEPf4jrrrsOALBhwwZccMEFuPvuuzF79mybV0hERORs+dyLyAxCiLggn90hknwtzSQyU01NDYQQdi/DFAGfdwPXRJkaum4tCsvK+JrQEqJzqIsNHPPO9bbbbsPdd9+NOXPmRO+79tprMW7cONx2220MShEREZFl9Hqy+HEE20qtXwtLM4mI3EXJavVyNqsbFbCHVDwhgJWTE09utYBj3sF8/fXXqK2tjbt/0qRJuPHGG21YEREREeUrbU8WLSv7s7A0k4jIXZT9syezWYWI6bcY5bAJn0IICFmOaXBOOtqCsQGpirMjv0sLOSYodeGFF+K5557Dz3/+85j7X3jhBXz3u9+1aVVERESU7zbeNDHSwDbUAiyL3Gf1CQZLM4mInE0vq9Vz2azJsmr6ngZcvjoSmLI5QKXX3JzSML8B6NLL8t+dY14dJ598Mn7zm9+gvr4eY8aMARDpKbVu3Tpcf/31+P3vfx997LXXXmvXMomIiCjPBHyFR08oHPO2iShCm7FgY08Qonynzmp1ejarEAJye2cGUVrTTYUAWg4kLvPa+wGw9LjI/yvOjkywtSkwpW1uDrDBeVp89gQTHfPu6sEHH0TPnj3x0Ucf4aOPPoref8wxx+DBBx+M3pYkiUEpIiIig2nfoKr/T0TJKWUiCkvKRRzQB4SIYjk9q1U51s9YPQPbm7ZH7x9WNgx1tXWJg1N6+5v5DZEghhDAQ7WRoJSicUMkYK6eYGuToevWRnpJsZ+UYznmFfPpp5/avQQiIqK8JITA9JenY+uXW+1eintoM1Ic1kvDLbwQDLWtTETbB0TNhp4gRORM6v2sNhil2N60HaMfGx0NTgGa7Cm9vkPqMq+f/i3ymFAQWDbE1O1JRQgRc2GgwO9HQYD7QydzTFCKiIiI7CG3ywkDUlXlVfAXMd09jvZNt82lCm7klWCoXpmIwrJyESVjQcEgaV6R2+X0yq8o7yTbzw4rG4aHax/GzNUzo4EqJTgFRI7/dbV18X9Xen2HJCk+KyoUtHxfxF5S7uSYoJQQAk8//TTWrFmD/fv3o6OjI+bzzz77rE0rIyIiyh/1U+tjglBeOdHRZuBktV3FgUjwqXFD/OdsLFVQRo8r3DKC3IvBUKVMRGFZuYgv4IgyGbJHzaqaxAEEyltCCDQdaYrbz2pL9VZ9d5VuSd+W/VvQJB9EWWEppDbVMTTdvkPLhlh+wUZ7kYB9pNzBMUGpuXPn4v7778eECRPQp08f7lCJiIhs4C/yI+DBsp+aVTUxt7M6gZOkyJtrbWNpm0sVtM103TiC3CvBUJaJkFX8RX5UlVdhy/7ICfiW/Vsgt8ue3H+7XTAUtvxigV6GlLKf1e5fJUlCoDgQDU7J7XL0mFnz1ARUHTmCui/2I63Vay/e2HjBZui6tSgsK3PlsSTfOCYo9cgjj+DZZ5/FBRdcYPdSiIiIyAO0J21qWZ/A6ZUo2EBv9LjCjSPIvRoMJTKLJEmoq61D05GmuKC7YWwov/Ki6iWvW36xQJuJWlVehbLS5AEaJTgVF/AsLYUsSQgIkbpfnXLxpuWA7RdsCtjY3DUc826lR48eGDx4sN3LICIiIo9QTtq0jbRNO4GzkHr0uMLpI8iJyFiSJJlb5mpD+ZVXaC8cWHWxQGlqrj7u1U+tTxmQUosGPA//GzXPRRJG5NnvAoEy+NP5PpIU2+OOKAXHBKV+9atfYfHixVi5ciX8rPskIiIiAyhXflMRQsQFeJzO6aPHichaQggEQ+257b8cVH7lZsqFg4MtIcsuFiRqap5NObQ24Fnz4v8DkGXpuzKt1sSsOyEEhCzHTN0j93DMO5mpU6fi8ccfR3l5OQYOHIji4uKYz2/evNmmlREREZGXCSHwwxXrsUmnFI6IyC0ue/BdbNkdTP3AZBxUfuV2kQsHhZY9n97wiFyGRvgLS1F15Ai2lJZG78uq9F35OzIp644T99zPMUGpGTNmYNOmTbjsssvY6JyIiIgsI7eFEwakqit7wl9s3UkFEVG2tnz2NQBf9HbW+y+WX7leoqbmaRMCUpuMui/2Q5YkyD/7oLOUr11O/X31ptWalHWnnbgHcOqe2zgmKPXiiy/ilVdewfjx4215/vvuuw+//e1vsXfvXpxxxhm49957MWrUKFvWQkRERPbYeNPEmCvbVk9M8jKl14lC/X8iMo6yH+P+K39o9685DY8QAlg5GWh8BxIQaXCuLuVbVZO6jE89rdbCKbVD162NNDhnk3NXcUxQqqKiAt27d7fluZ988knMmzcPK1aswOjRo3HPPfdg8uTJ2LFjB8rLy21ZExEREVkv4CtknyYTJOp1QkTG434svxi+f20LAo3vdN6uOBv+0rLYiXzplPHZMK22wO9HQYBZfm5TYPcCFHfeeSduuOEG7Nq1y/LnvuuuuzBr1ixcfvnlOPnkk7FixQoEAgGsXLnS8rUQERER5SoYCh9teBz5EELYuh69XieKXHqe2EEIgY5gsPPDqsa6QgChFtVHjr2DiMgTtPtXQ/ep8xuAK1ZDKihAXW0d6qfWxzxvsC2Y2fElFIzsywwihGBzcw9wTAj9sssuQzAYxAknnIBAIBDX6LypqcmU5w2FQti0aRMWLlwYva+goAATJ07E+vXrTXlOIiIiq2mnMbGswwTaIIGJk4ZS0U57qq7siaeuGuOI37nS60Sh7U2iTFFKh9UlGrY11FWV0xCROynHYTOPv/VT61FWWmbc9/d1HsfiJvKtqgGQ4US+ZUMMa3jOBufe4Zig1D333GPL8x44cADhcBh9+vSJub9Pnz7Yvn277te0traitbU1eru5udnUNRIREeXKyUEKz9D2zDBp0lAi/uJCVFf2xEadpu0bd38FuS3siJKeZL1OMj3JKBk+HAMffSTmZ2xmoEqvoa7C1Ma62nIatYqzIwFQInI05Ths5vE368bmGXx/dRkfkEYpn7bpuUENz7X7YzY3z5AQnT2/bGb/O5OjZsyYYfcS0rZ06VIsXrzY7mUQEREl5ZYghavpTRhSmDRpKBFJkvDUVWMgt3VmxQVD4biApJNos6I6kgR99LRu24YdI6tj7vOPGIHKPz1qesBVaairsCxra35D7GQ0GzPyiCg5veOwUcdfpbm5lUMjJElCXW1d9HmVbKkUXxS5QNNywLSG50PXrUVhmYEZYl7nsOxbR74TPXLkCEKhUMx9ZjVB79WrFwoLC7Fv376Y+/ft24e+ffvqfs3ChQsxb9686O3m5mZUVFSYsj4iIqJsuTFIYSXljbzcHgakECCKU3yFDvWEIYWFk4bilyO5JtCYKitKG/TRfDF2XTYNrdu2xX1K3rwZ4aYm0wNGtjXU9QUsbx5MRNlRH4eNPP7aOTxCkqS4rCi5XU6epSVJscF0gxVw2l5m9LJvbcy6dcy7lpaWFtx4441YtWoVDh48GPf5cDis81W58/l8GDlyJN544w1MmTIFANDR0YE33ngDc+bM0f2akpISlJSUmLIeIiIiI7kpSGE19RXebsOA9mAlhJic+TeyYcKQF6QqhUt11XvQs8/EZVntHDceAKL/qr+fFdlTRERaZhyH9YZH5NzgPIdyrppVNZn1liLnULJvbcy6dcy71BtuuAFr1qzB8uXLMW3aNNx3333Ys2cP7r//ftx+++2mPve8efMwY8YMVFdXY9SoUbjnnnvQ0tKCyy+/3NTnJSIiImvp9cNQFAV240j4CLogi4wpiqOUlgBIWV6STSmcJEmQVJlKkt8P/4gRkDdvjnusvHkzhCzHPJ6IyAuU4RE59ZPKopxLezxN2VvKIErZN6fuGcQB2beOCUr95S9/wf/93/+hpqYGl19+Oc455xwMGTIElZWV+NOf/oRLL73UtOe++OKL8eWXX+KWW27B3r17ceaZZ2L16tVxzc+JiIjI3dT9MBRN8jc4/7lv27gq79EtLRECJW1AR1BGRzFiTiiMKIWTJAmVf3o0YfaU9gQmncCXXs8rIiInSTY8Im1ZlHMpx9OmI03p9ZZSU7KxMszO4cQ9b3JMUKqpqQmDBw8GEOkf1dTUBAAYP348rr76atOff86cOQnL9YiIiMg7tP0w1D23yBhxpSVC4NePhDFsD9B45/iEX5crbfaUWqYlfTz5IaK8lEE5lyRJMSWDygWflFlbSt/FDKfU6pV9u3XqnjqbWM3sCYpO5Jig1ODBg/Hpp5/i+OOPx7Bhw7Bq1SqMGjUKf/nLX3DMMcfYvTwiIiIiVwuGYoNv/uJCS9741k+tR0kIaLxdPxhl5glFqpK+ZA3RU/W8cuNJUCpCiIRBWqv+Xii/8MQ8c4l+ZobJoZxLyZjS7S+lN602hym1Stm3ZZNPDaL8/masnoHtTdvjPj+sbBjqauvy6jXgmKDU5Zdfjvfeew/nnnsuFixYgO9973v4wx/+gLa2Ntx11112L4+IiIjI1bRTn6ore+Kpq8aY/qbXX+RHqei8nU3/qGylKunTZk+VDB+OgY8+AkhSTKmelWu2ixACP1yxHptUo+vVPvr1ZA5NIEMlmyCnnJgD3gxQBUPhrAK9dk7dS0SvV6Nufyn1tFoDptTaNgE1C+pAYqJglGJ703aMfmy0518Dao45svzsZz+L/n/ixInYvn07Nm3ahCFDhuD000+3cWVERETkJdpsEG0GkZf4iwtRXdkTG3UCDRt3fwW5LWx5oMHqE4lMGqK3btuGHSOr4+5308lPtuS2cMKAFJEZ9CbIKZQTcyBB1o3LVS95PasLA9qfWc4T9wyg7tUot8vJ+0vl4bTadIOvQGzAyuuvATXHBKW0KisrUVlZafcyiIiIyEN0s0GkELoNM+kJtaO1LR65LEkSnrpqTFwQTps1lSttOYncLsc2Nm839Olyopc9BSGw67JpaN22Le7xXi3VS2bjTRMR8BXG3OcvLkzwaLKTECL1g3KVZVPqZLT7DGWCHBCfSWLVVDezaS8S5HphoH5qPcpKyxwRqND2agQixwGvZ/ikQy/4mqhEb9V3V+mW9nnlNZCIY4NSREREXqad6qXmxdIgp0iVDVJaVGDsE2rLEzJs6moESZJMzYZKNGnPisbm2dJriD7o2Wd0X5NefT0myxgM+ApZqucSR9o7Ym5XV/Y0PoCYZVPqRPT2GeoJcsqJecqsG5dRLhIcbAkZcmHA6QGfmlU1hmb4CCFcNwE1UfA10e9OCe7pvQa8HOTj0YaIiMgGQpaxY8RI3c+lmgpGxlCyQeR2GTVP3QIAxvzM9Zq5KnJo6upUeleBS9qAYXviH+vkrKNkk/ssJ0Tk70ShzbjL+dsn7x9F7vTa9WfjhLI+5u3HDNp/pSpB83LWTeQigcOyDoUwbB+j7S9lVIaPG6ehpgq+JqP3GjA6yOckDEoRERE5jLx5M4QsO+cE2aOi2SBS5wmCdqJRVidB6mauCgOaurqBchW4IyhHM6TUTcK9mnVkKCGAlZOBxndMe4pkGYOmZNqQJf7zxUnGnbQa3JQ6kXRL0Lx8Qm4rg/c3Sn+ppiNNMRk+QJLjaSiYsjRUOw3VyRc4FEb0/zIryOc0DEoRERHZQPL7cdLmTTH3qaeCkT20pSJZnwTlYTNXoPMqcEdx53350CTcUG3BxCeIFWdHTt4MpO0flc1EMLJPaWEp2oOVKArsBmDwSasF+7Fkgf98OSFPh1IGpr1wkjPt/saAfYwkSTHBF+W4mvB4umxIRqWhQ9etRWGZM3pp6dH7XWXb/0svyOdFtgalmpub035s9+7dTVwJERHlu/vuuw+//e1vsXfvXpxxxhm49957MWrUKNOez1GlQnlOb5y1Ip9PghJJ2dS8GK7r++FY8xsAn+pvz4RG+ewf5W6SJEHefRWkwhZ0PXGJ3ctJKtPASr6ckKeSbHqboeY3AF16GbKP0TuuxhxPteWhGZSGFjg44zbR7yqX0lNtkC9l5pkL2XoEOuaYY1L+IIUQkCQJ4bB3xzUTEZG9nnzyScybNw8rVqzA6NGjcc8992Dy5MnYsWMHysvL7V4emUw9zlrhtQa7iaibWwOps2Tc2NTc1XyBvMy4o0xJEB0+uxeRVLaBlXw4IU9Fr29fNqVgKfmMC3qrj6u6x1OlPLTlgKdK2634XaXMPHMhW4NSa9assfPpiYiIAAB33XUXZs2ahcsvvxwAsGLFCrz44otYuXIlFixYYPPqzCAAqS3y5l4qNL4cwIX0mormA+0EqOrKnnjqqjEJ3+Rm0tQccEffj3yQbNIekRWMOln34gl5JlJNb3OSlA3rJSk2E9RjjPxdpcw8y4SBje2NYmtQ6txzz7Xz6YmIiBAKhbBp0yYsXLgwel9BQQEmTpyI9evX27gycwghEKhcgcLA7ujEOcov/uJCVFf2xEadRtcbd38FuS2cVjlXqqbmABubOwEn7ZHTZHqybugJuculO73NqTJtWC+EgJBlV5SEa0vbjfxdpcw8S3+Rpg/SyIajCsi//vprPPjgg9i2bRsA4JRTTsEVV1yBHj162LwyIiLyqgMHDiAcDqNPnz4x9/fp0wfbt2+Pe3xraytaW1ujtzPpj+gER8JHUHi0Ia6WKeUA5DiSJOGpq8bEZc5os6aABP2jjmJTc3fgpD1ymkxP1g07IXcgJWvRywMGsm1YL4TA7ksujZm651RW9P1KmXmWDhMa2xvBMUGpjRs3YvLkyfD7/dHGsnfddRd+85vf4NVXX8WIESNsXiERERGwdOlSLF682O5lGOLlH7yBMn/X6G03lAN4gjZt3oTm1alIkpQyG8qy5rpkGU7aI7fyaom1cjEgVem0m+k1rI/2BhMC0S0OBWOOh0KW4wJSTi0J15anWnWRL9PMsxgGNrbPlWOCUj/72c9w4YUX4oEHHkBRUWRZ7e3t+PGPf4y5c+fi7bfftnmFRETkRb169UJhYSH27dsXc/++ffvQt2/fuMcvXLgQ8+bNi95ubm5GRUWF6es0g9vLAFxL29Q1g1HYVtLrAQMAEAKjjjkDJSGBjragK8oqKIKT9ojsp1dCrS2dVsrWhBAItn6FkpBAa3Gi7+h82ob10d5gvU5HHRAJTC0bkvB4qJSGu6EkvH5qPcpKy0xbZ7aZZ3EMbGyfK8cclTZu3BgTkAKAoqIi3HDDDaiurrZxZURE5GU+nw8jR47EG2+8gSlTpgAAOjo68MYbb2DOnDlxjy8pKUFJSYnFqyQ7aRvBZ5VRph1/rZbBKGxzJW6Ar/SAEUJg3/Qr0bp1M/61gO/PiOwkhHBF03ptGXC+U5dQq0unhRDoCAYBIbDrsmloPdrSBgAeAfBpH6DjB0F0FLuzX59ub7AD70OuGIVA47uROxIcD51aGq78bWtL28383ehlnrmdY4JS3bt3x2effYZhw4bF3N/Y2Ihu3brZtCoiIsoH8+bNw4wZM1BdXY1Ro0bhnnvuQUtLS3Qan1cFQ2H4i9qjt1nKo0/7pi+rVHll/HWbqnQvFHTMKOxUDfCj/aOCQbRufU/3ezi1rILIi9zSwN7MMuCM++k4SFwJtRDYN2M6WrduTfg1g/YBjaPPARDZ31b+6dHst12IyPHIwilsCXuDTXveUcfDdNlZ4q7NPHM7xwSlLr74Ylx55ZVYtmwZxo4dCwBYt24dfv7zn+NHP/qRzasjIiIvu/jii/Hll1/illtuwd69e3HmmWdi9erVcc3PveacO9YAwhe97eWeFpnSu6KryDpVXpIckA2lL2kD/N76vTE4ac+ZhBBxTezJe7QN7Eccfwx22rieRMzstZNTPx0nEQI9Qt/EBaSKh52E//pOAwDg8b8ORvuOzt+wvHkzhCxDyiZ7yMYJbLrNusNH4C/2w22/Qb0Sd7sGxkR7dLk0SOuYoNSyZcsgSRKmT5+O9vbIVdvi4mJcffXVuP32221eHRERed2cOXN0y/W8prSoIOHntD0t8pn6iq7CS1Ofkk3V++ZfN0F0dAYrW4Llut/DqeUU+cwt2TNkrI03TYTf146zH7d7JckZ0WvHsH46DiGEwLK/3YdTmnZF71MC/nKRQOvjZwMA+j/1OPztEjpkGTvHjQcAdMhydhcDtBPYAFunsNWsqontLeVCSom7XUGhaI8ulwZpHfGuMxwOY8OGDfjVr36FpUuX4uOPPwYAnHDCCQjwzQ4REeUhbfNoo7JQ1N9j080T4S/yx/S0oE5enfaUquRAdPg6M+iEwIcf70PLocMI+IrY1NzhtNkzatWVPeEvLtT9HLlbwFcISM7PiDPihN1r/XSELMcEpPwjRqCwLBK4k1Tl3pIkxV0E2DlufO5lfPMbIg2vLZ4CGxdcPPA+ZElCQAgAR/trOfh4o72wY8fgGN0eXS4N0joiKFVYWIhJkyZh27ZtGDRoEE477TS7l0RERGQr5UqoIuc3njr8xYUIFDvirYBpWMqknxWVKCB1eq8z8cdffReSJKGltR1vTf4BTmnahca//tKi1ZJRNt40MRKsOIo948grvNBPJzpdTxV4GbCmHl37lid9nUp+P/wjRkDevBlAjmV8QCQgZUNZuV5wUZYk+IUAhMDuSy6FvCW+fN4J7OwlpZawR5cLOead6KmnnopPPvkEgwYNsnspREREttC+2VTL+Y1nHjKzlMmQiXwWSPXmWSk5UKi3oyMYjLmCr8am5gZSGg4rDGo8HPAVshSXjBcKWp5V4zUiQdBFnRGdaGKhJEmo/NOjCDc1xZTxab/eDbTBxZrKAag6cgQPHToY87Nx2vHGzD5pmfJKRrdjjlRLlizB/Pnzceutt2LkyJHo0iU2Ytu9e3ebVkZERGQN5c2m+sqpun8EZcbMUiZDJvKpaQMRWZ70ZZIVVVVelXZ/lwFr6tGlR+c0ZLed/DiWjQ2HKdZ9992H3/72t9i7dy/OOOMM3HvvvRg1apTdy3KeZUMi/YeuWM3AVJaELMcFpP5ZNhC9Cn3ocrR8LdnFBEmSYoZMKO8RzMioNltcGV9pKb76QxWAyKCZoWv/hsJjj3XsNhnRJ81obpxK6Zig1AUXXAAAuPDCC2N+gEIISJKEcDj/0u2JiCj/SJLEbCgTGFHKZMpEPoV2FHYWJ325ZEWlIrGpuTn0Gg4rbGw8nG+efPJJzJs3DytWrMDo0aNxzz33YPLkydixYwfKy/Ub/eeV4kDk77FxQ+R244bI365Dpom68SRcMWBNParvXIfWQh/wmzdQXdkTdVeekTITRy+z2o0Z1dEyPvkgap6aAACoreiPRxA595cKhWN+r8pFH20vKaesT+HGqZSOCUqtWbPG7iUQERGRRxlRymT4RD7tiZ5aGid9ZmVFkU2UhsMKlkhZ5q677sKsWbNw+eWXAwBWrFiBF198EStXrsSCBQtsXp0DSFIkSN5yID6AnoDeCbxZ3HQSrm3gHejeFaed0Bcbj2b1btz9FY60d0Q/nygTR51Z7faMakmSUOY/FlW9q7Dly9iLPnLHEXS1aV1qTukjlYjbp1I6Jig1aNAgVFRUxL3ghBBobGy0aVVEREREnZL1b8i4z5RyoqftJ5TGSZ8ZWVFK493obdX/5bYOFITaO78fm2YbL4uGw2zkn7tQKIRNmzZh4cKF0fsKCgowceJErF+/3saVOYwkxQZNk7DiBN6NJ+F6vaQkScJTV43BwZaQ7hTcZPtuvczqDll2ZXm1JEmoOz9y0SfY9G98eef3AQBH2mV0EfZnS+ld9LGzl5RWyqmUSu9Cg3oWGs1RQakvvvgiLkW2qakJgwYNYvkeEREROVpWfaYkKa1AhNlZUYka7yrG3/EmWotKorerK3viqavG2H6ikM/MbOSfTw4cOIBwOIw+ffrE3N+nTx9s375d92taW1vR2toavd3c3GzqGtWUQKSTA5BWnMCnPAl3IG0vKaWBtyRJMeXludg5brwre0spStuAcFvnumv//J84ecAIR2XBKRd9nFa6l3AqpQt6FzomKCUSREC/+eYblJaW2rAiIiIiouRS9ZlqOtKUdR8nhZm9oqLPodN4V/HPsoGRficqG3d/BbktzOluNjKzkT8lt3TpUixevNjy53VjINLME/iEJ+EuMHTdWhSWGVNSre0v5cbeUskujKiPpXYEgrQXhfxFfkdn5MXR613osJ6Ftr+TmDdvHoDITuXmm29GQPXiCYfDeOedd3DmmWfatDoiIiKixFL1mcome0oAkCUJaJcBSbK8V9TQdWujk52EEDi+yIcLjn7/YCisW2JC9jKikX++6tWrFwoLC7Fv376Y+/ft24e+ffvqfs3ChQuj5zBAJFOqoqLC1HUC+oFIJQAptyf4Ipu57gTeIgUGltgp/aXCTU2pe0sJ4cgSLr0LI8W9Q2gtjhyLlGOp1b3DnN5LKhnlfYlfCER/WkrvQof1LLQ9KLXl6B+fEAIffPABfL7OK3E+nw9nnHEG5s+fb9fyiIiIiJLS9pnKNHsqRlsQM/r3xfYSH3B0EpGaEVlRqRRoJu05Y74WJWNEI/985fP5MHLkSLzxxhuYMmUKAKCjowNvvPEG5syZo/s1JSUlKCkp0f2cVZRApF4AMnoy6rDyonyl9OtTNzhP8EhAasuqObwkSdGLCQCizxXTX8oFZVwAMHTNqyi47zSgUKCq1wXYcvDD6OeUY6hVgzu0F4Wc1EcqlWggr9fpqAMigaksehdawfajlzJ17/LLL8fvfvc7dO/e3eYVEREREWUv0+ypOCU+3burehuXFaVtap76ZInIu+bNm4cZM2aguroao0aNwj333IOWlpboND4nShaItCurxG4ZBeOUxs+AqVkjqfr1qR8XqFyBwsBunP9c7s+rZEzF9JfSlnE5rIRLUeD3o6BIAADqNr4EuWIU5B89jpqjF2qsmLaoNz0y0SREJ9G7KLblwPuQJQkBIWxcWXK2B6UUDz30kN1LICIiIjJEJtlTeoa1hlD3RWw5kb+9H4x4K5zuSVIq2kbLLBkjt7r44ovx5Zdf4pZbbsHevXtx5plnYvXq1XHNz51M92TUBRPpjJQyGKcEooQAHqoF9n4Qub/i7MgkVBP2X3plaUqDc7Uj4SMoDOyOuS/TrBxtbykgSX+p+Q1Al16OKuGKKvZHfieNGyABCDS+C39hady0RbP6TCUq2XND5qH6opj6YpjTOSYo1dLSgttvvx1vvPEG9u/fj46OjpjPf/LJJzatjIiIiCg3etlTuoQAHpkC/+fvxgegGt+JnFDlmHqfrKm53slSItreUpzIR242Z86chOV6buDWk9FcpR2MS1a61rgBaDlgeq8dpV+flKKf1LPfeRVlga7oWdolo/2p0ltKKRVM2l/K56yeQjEkKRIkbDkALBty9K74aYtmZAQKIdB0pMn06ZFm0l4UcwPHBKV+/OMf46233sK0adPQr18/vqEhIiIiT0n7jeIVr3aWlQCRprRH35gbTd3UHEDKkyV/cSGqK3tio870L07kI7KXG09Gc5VWME6ISIBDG5AqOwFo+jjyf2Ufa2LWlLZfXyLn3bkBEL6sAv2SJLlq6l5CkhQJnMXcJaGstEw3CGlEnym9DCkzp0dSJ8e8a3j55Zfx4osvYty4cXYvhYiIiMg+kmRoI9Jk/aPSPUnqXJqEp64aA7mts3SPE/msIYSI+7kTUYpgnF6GlDKBrMgPPHR+JFNK0bjBkIzUTJUWFcTdZ1Sgv0OWIxcccvou5hFCpN3XMFEQsmZVDYaVDUNdbR2AzErt1P2jtE3Nnd5DyiscE5Tq2bMnysrK7F4GERGRY2nftKXKaiEyqn+UmiRJzIaymBACP1yxHpt0MtQoPwghXBGIVE7wHUOvube6l9IVqyOPUWekhoKGlPFlGmxR/O3GCTjn9nU5PbfaznHjIw3PH7rfcYGpbI5RShBSW7q5vWk7Rj82GgCiAapUwalE/aPc0NQ8E7IkwS+E437/Cse8o7j11ltxyy23oK6uDgEvpBwSEREZTNsfImaqDpEOo/pHkb3ktnDCgFR1ZU/4iwstXhEZQZv9lmhYgFuCkolO8B1Dr7m3XmbqsiE5l/FlEmzRBvICvtxfz9qm55GG50ccF5TQHqMSHpdC8ZMS1VlTM1bPwPam7dGHKwEqbfYUgLjJuHr9o7wUkAKAmsoBqDpyBHUODUw5Jih155134uOPP0afPn0wcOBAFBcXx3x+s2qKABERUb7Qm6ajSDhVh0hHpv2jssGJfCmox9ADnSdaGdh408SYk1b+jN1Lbgvj5Fteid5O1ENIG5R0aiBSr/zJUc2hkzX3Lg5EJ74ByLmML91gi1mBPKXpebipKXnDcwcZum4tCssSBIMS9PxSsqZWfXdVNNikDlCps6dO6nkSAGDHVzt0n99r/aO0mWRbSkshh48ggK42ryyeY4JSU6ZMsXsJREREjqOepqNIOVWHvEsbxMigxCTT/lHZ4ES+JJJN/8pAwFfI8kmPSqeH0MabJuLYLj77X1M6mStqdpc/yW1B+Ds6ILWlWUqoM/HNKMmCLXqBvNLCUkOeV5KkmAsRTlegvVCiDRQCCYOF6r5iSoBKmz2VKBgFeDM7SpIk1E1+GE1NDah58f/ZvZykHHNEW7Rokd1LICIiciTPTNOh3GlPljRXjZM1NTcLJ/KlSdvbRq3i7MgJGOUVf3EhPvr15IyGBQR8DsmMSzGtzu5sk5qnJkTKlb7Yn365knbiW4rAW7rigi0JKIE8dUlnXlMChdqeXym/LHn2lLqkT2H336sphID0UC38/34XGFhh92qSctw7hE2bNmHbtm0AgFNOOQVVVVU2r4iIiIjcwLPTyfSuFitUV43NaGqeDk7ky4Iy/UthQFNlcp9UQwOUfZpj9mUZZK7YQbdcSZIQECK7wG+KwJvRzA6MdDQ3Ae0SpEJn9hXSlcM0Wr3sKcCjASg9yoUQ9bY6qZxWxTFBqf379+O//uu/UF9fj2OOOQYA8PXXX2PChAl44okn0Lt3b3sXSERE5ELaBqqppiK5tSeQWxoBZ0V9tVihc9XYzqbmyU6u1X9Tbvl7Mp0v4IiTeHIe5fVSWlSIi+532D4ty8wVqyiNr5sO/xs1z10QufO694HAsekHfh0eeMuYENH/7pz0fQD94O/Vispf2B+YymQ6Ya7UAaq85tDjr2OCUtdccw0OHz6Mf/7znxg+fDgA4KOPPsKMGTNw7bXX4vHHH7d5hURERO6STQNVt/YE8vx0sgyvFlvR1Dxd6r8pt/w9EdlFeb0M6tUFnx5oif2cE/ZlOWSuWEGSpNjm6pkGgHMMvCkl1FYFW1KRigT8vVohHyiJ3icfKIFolyCVJPlCk+WU2RsKMrvUYxwTlFq9ejVef/31aEAKAE4++WTcd999mDRpko0rIyIicie9UccK9VQkr/UEypfpZEIAIiwBQRlol2JOgqxoap5Mor8pN/49EZlN7/WiDkgp+zSv7ssMJURWUy1jZBl4M6OEOhgK5/R7lyQJld8+CBGW0PGTd49mS8H2gE660wl1LRtiWUml1zi1hNEx7wg6OjpQXFwcd39xcTE6OjpsWBEREZF3KKOOFeo3JF7rCZQP08mEENj9Ri/IB3zA0+fYvZw42r8p9d+TW0tEreTZ/mikS/16EQK4aMV6fPRFM4BIdpQjpu25gTLh0qbGznol1ImCLUppfaqS+uolr+ecYSpJkYwpdC/L6uvNlmw6YZS2rNLNJZU2qllVAyByYbKuts4x+xXHvGP71re+heuuuw6PP/44+vfvDwDYs2cPfvazn+Hb3/62zasjIiJyN3+RP2k/hVQNd8lZhHwkEpDS4T+uBFKpMSPFc5Hob8qtJaJW8XR/NEpI/Xp58drx0aAkg7YZcFBjZ6WEWq90OlVpvTZzzowM0w5ZtrWsWy2t6YRKWWXLAcf1MnM6vxCo6nU6thx4P3rflv1bILfLjumz5Zh3n3/4wx9w4YUXYuDAgaioiES2Gxsbceqpp+LRRx+1eXVEREREDlLceaI1dMpeFBR1NrOVCgWkdtlRV5BTlYgebAnlRcllOjzfH41S4kUC48jhI0CblHu5UoZ9jJKVUOuV1qtL6pXMuYMtIdMylneOGw//iBGo/NOj7tnXSlLs1FJKiwSgbuL9kAsKILfL0WwpJ3HM3q6iogKbN2/G66+/ju3btwMAhg8fjokTJ9q8MiIiIiJ7Kc1zFR1HjkT/X7BgJwoCfkdOw1KkKhFl9pS+fOmPRu4WKTcNpixFs4Nh5Uom9TFSSuu1QbNIYNLYALTkL4V/xAjImzcDAOTNmyFkGZKN/QfJGk6fPuiYoBQQ+WGdd955OO+88+xeChEREZEjpGye6wu44uqxNvuD2VOp5UN/NHI3AWD66z/B1gMf2L2UKMPKlSzoY5SqtN5IkiSh8k+PItzUhJ3jxlvynFqGTidUGtpzEp/r2X6Ue/PNNzFnzhxs2LAB3bt3j/ncoUOHMHbsWKxYsQLnnOO8Jp5EREREZtNrnqtIOLFIO33KgW/aM82eOrlf96PZU5335WOgishJZEmKC0ipS9HsYFi5kgf7GEmShIJ0p9wZzPDphMrvhJP4YgkRCZ7mOoXSQrYHpe655x7MmjUrLiAFAD169MBPf/pT3HXXXaYEpXbt2oVbb70Vb775Jvbu3Yv+/fvjsssuwy9/+Uv4fPrNQ4mIiIjsojTPVSRsVKs9gXLom/ZMsqc++qIZpyx6JeY+lvkROUeiUjTT6ZyEG1aulGYfIyGEMdk/HpbJdMKEtNlrACfxqSkTKBvfsXslGbE9KPXee+/hjjvuSPj5SZMmYdmyZaY89/bt29HR0YH7778fQ4YMwYcffohZs2ahpaXFtOckIiIykvZNsFOm6VD24vpHqf6frHmu7pt1hUvetOtlTwkBXLRiPT76ojnu8SzzI0pObpctCxJZWYoW5YCT8EwygIQQjuq9pRxfrH7vkGw6YVJK9poShPRIBpthlAmUahVnR94faFi5b0jF9qDUvn37UFxcnPDzRUVF+PLLL0157traWtTW1kZvDx48GDt27MDy5csZlCIiIlfQ9oVw3TQdipFTeYP6zbrChW/a9SaPvXjteDZJJ8pCzaqa3Jt8O1kGJ+Fm0WYAJcr+EUJg+svT4ybv2Ul5D2H1e4ekF1hSkSTHX2BxhPkNkSy/BOX7Tto3FNj67ACOO+44fPjhhwk///7776Nfv36WrefQoUMoKyuz7PmIiIgyJfn98I8Yofs5ZZoOuVNW/aPUlDfr0Q/nN0BPhxKoUj6O7eJDdWVP3ccq2VPBUHv0Qwhh8YqJ7OMv8qOqvCp6W2ny7XnzG4BffG5uqXIoCIRaIhlaOoauW5swuCO3yzEBqUx6bwVD4cz3Y0Lo9hXSew/h+vcOoWDC30ne8gUi7wNUf4tO3TfYnil1wQUX4Oabb0ZtbS1KS0tjPifLMhYtWoTvfve7lqyloaEB9957b8osqdbWVrS2tkZvNzfHp5MTERGZRZmgoy3xsmuaDpkj7f5R6XJB8/N0Zdok3ZbsKaXPjSJB01khRNx2EOVCkiTU1dah6UhT9k2+s2F3UEA5CU/AkHKlFM21C9LcT9dPrUdZaVnaa6le8npm+7EkZY3q9xBWvXcwvefWsiGO7Z3oJLbtG1KwPSh100034dlnn8WJJ56IOXPm4KSTTgIQ6fd03333IRwO45e//GVG33PBggVJ+1QBwLZt2zBs2LDo7T179qC2thYXXXQRZs2alfRrly5disWLF2e0JiIiIiNJkgQp29R3coys+0dlwyXNz9OVSZP0jbu/gtwWjisLNE2afW6EEPjhivXYpLNmolxIkmTuBDylh92/VX/j7bKjy6qyLlcyobl2OsEx7T4to/2YtqxRU9Jo5XsIw6fuKbS/F5f0TrSb6fuGLNgelOrTpw/+/ve/4+qrr8bChQujaYmSJGHy5Mm477770KdPn4y+5/XXX4+ZM2cmfczgwYOj///8888xYcIEjB07Fn/84x9Tfv+FCxdi3rx50dvNzc2oqKjIaI1ERESU30x7o67mgebn6UqVPWUpvT43CtXJodwWThiQqq7sCX9xoe7niGyn9LA71Ai88B27V5OQUq60ZX9kP6uUK2XUkN2m5trKPu1gSyi3/dj8BqBLr5QXIDpk2ZSG5+n23MqY8ntpOeC63okUy/agFABUVlbipZdewldffYWGhgYIITB06FD07KnfKyCV3r17o3fv3mk9ds+ePZgwYQJGjhyJhx56CAUFqdtslZSUoKSkJKu1EREREQEG9I9Kh0ean6dLr0m6QlsWZ9mUPqXZrCJB2eTGmyZyiiC5iyTZ27cuQc8kNcPKlWxqrh3Zp+UYnPalV6q9c9x40xueD123FoVl6ZctpqT9G1T+Hlxcnp6PHBGUUvTs2RNnnXWWZc+3Z88e1NTUoLKyEsuWLYuZ8te3b1/L1kFERET5zfD+UWqcVATAxj5TKfrcKAK+QuvKC4ncLs0SWcC8ciUhBEQwmLJXkhACcrvsiIbSWkrTc3nzZgCdDc/NKu1Lt+dW1lL0/PK0NIK0TpXXR77XXnsNDQ0NaGhowIABA2I+xyktREREZCRL+0ely0PNz/U4qs8UERknRc8kswkB7J5xJeSt76d4nMD0l6fHTN1zEqXpebipyb3DUkzo+eU6GQRpnSivj8IzZ85M2XuKiIiInMdtE8ss6R+VDY81P9dyVJ8pIo9RMoBsl2bPJCOJsBQXkNIru5bb5biAVFV5laMaTUuSFJOpq1wwyTVjV7kQY+rUPcC2nl+OkkOQVnkN5zyZMgd5HZQiIiIi93HjxDJL+kelK4+anwMO7TNF5HKOygBKs2eSwuiTcKX8OlUQp35qPfxFfltP/tOhZEzl0l/K8gsxemXqoaDnsn/TkmGQVum1ltVkSoMwKEVERESu4vaJZab2j0pHnjU/T8a2PlNELqfNAKo6cgT+wlL7FpQBo0/C0y2/9hf5M5v6p0MJpBsdQNf2lgJy6y+ldyHG8gswy4Z4Lvs3LWkEabVTKYEsJ1MahEEpIpNoe4ekw/T0ViIij3HjxDLb+kep5XHzczv7TLmt7JQoHfW7/42yjg5H73tNPQm3sBexEkg3OoCu9JZSyu2M7C+VbiaZIbSZwI0bgJYDkUBNPmZNJaBMpVQa8Oc0mdIADEoRmcCxvUMorwlZRkdxdlM5LM/kIEqTUyeWJWtq7ngeb35uV58pN5adEqXDLwScvocw7CRcCXp8qurf0yYDMC/IrxdINyOALklSXFZUhyxn/B5QCGHfIA8lE7jlQGf2bz5P5EtCkiRbsqL0OO9dHJEHJOsdkg7L01spL/y75rysv/akzZtMGw9Mzse+O5lx/YUJjzc/B5L3mTKL28tOiRxDiPjgeRoMOQlXgh4HGoGnJyd9qFGN4NWBdKsHNewcNz6j3lKOOP5JUqSnUj5M5BOis8G7izEoRWQybe+QdDArhYwi+UuxfQAw7N92r4SspFyh7GiTURISaC3O7fux705mHNXUPF151vw8GSuCsG4sOyVyBCGAlZNjJ41ZvQQAHe3JX69GN4JPO5BuQJBC218qk95S2uOfbce8RBP5vNT83AGvBaMwKEVkMkf0DqG8JUkSbrmsECVtQP3UtxAozu6NgSNPoikhdS+IRwBsHwCISzLreWFn3x0vsb2pebrY/DzKiiCsU8tOiXKiBELMPOlvC8aehFecHXk+i6SbCRTXCL68Cv4ik99LGRSkUPpLhZuaou8nlItdiY5hSsm6umxv6Lq1KCwrs++Yp9c70UvNz7WvBcDy14NReDQkIvI6SUKrDygI+FHgwgMVpUdvco5i2L8BIR/JKNPFrr47XuOqCxNsfs4gLFEurO7dM78hUqaVw/PI7TL8RelfLIjLBOrVCsmffOpg/dR6lJVaEJwxMEghSVLMBRUlOKVXypcoUFfglIsw+dD8fH6Dq7eHR1ciIiIPkCQJxz/6CIKHO0+q5W++woFvfy+n78kT8dRc3dQ8XWx+nrVgqB1AOyftkXcNOAtofLfztlUlv77c90M1q2pQVV6Futq6jAMoQ6fsRWFJ6qmDmQS9DGNAkELvYpe8eTPCTU3RDCghBMJNTXEBKUeVqudD83NfwNUXlfhOk4iIyAOEEJixekZMuUBJSOAR+5aUFxzR1NUKed78PGWfKaWPi3Iz1BKdRjZyyeuQkTyTgsjVpj0f+dclJb/+Ij+qyquwZX9kv71l/xbI7XLGTdALikTcLlBpbm5Eg/OcGBCkUMr4lLI8JVtq57jxKBk+HJWPPILd06ahddu26NcoJeuOK1VP1vy85UDOGXeUGwaliIiIPEDbv0LLX8STYjO4sql5utj8PCppnymdPi7JTm04aY/soARJTMnakSRX9bGRJAl1tXVoOtKEmlU1uX/Do5mkosiP6ZqLQ2YKhsKmD0mQJAlSIBCXNdW6bRv+VV0d81j/iBH29pBKJVHz82VDgL6nAZev7vxbtnAbhBAxWbqKpL/bLCdQppJpOatRGJQiIiLymPqp9fAX+dERlNF4Z+TKpmPfJHqIa5qapyvPm5+n6jN1sCUUmaAXakEgQWPhf3SciL/98jsIlHS+5eakPbKDEnzJtlRNYVsmkAFT5dQkSTKu8fjRfaJcMQpbi/bGfMrMBufVS163bBpuNGsqGMSuy2Kzo0qGD8fARx+JBK+cvm9TeidqL7rs/QBYelzk/xZlAgshEAyFcdGK9fjoi+a4z5/cr/vR363muGHi1L1cyllzwaAUERGRx/iL/AgUB9BRbPdK8ourmpqnK4+bn6fqM6X868cRbDuaiDjyyHIEURJ9vIwSfFRSxN5spEvbj87oQLa2TA3IvlQNiKx3+svTLcsEUj2xaSfhiqwyyY47C9in6qX1738AAysAdF4cMjrrRBsst3IQgyRJkLp0waBnnzH179YSykWXUAvwUG0kKKUwuaQvVTBK8dEXzThl0SsANNm5Bk+gNKqcNRc8QhIRERER6dD2mUqWPQUAQZTE9I9iqR4lI2QZO0aMjN7Wm2yWC6VMTclsyrVUTa9M3MxMoCgDp8olklUm2fTngWLoZpAqF4eMpgTLD7aEbJuGq5T0uZ4kASVdgZ/+Tb+kz4SMKSEEfrhiPTZpjiHqrCghEBewShh8NGACpeHlrFlgUIqIiIgoTXkxaS9dHp/Ip0cvewqhFmBZ5L+bbpoYk1nGUj3KhLx5M4QsG3rCL0mSKcERszKBUjJgqpwik0wyZd8fs8+XpMhaAAgAskU/h0iwnMFuwyQq6VMypgz4e1P6RgVD4ZiAlBKMCvhijxUvXjs++ngl+BjtIab+xgZMoAQMLmfNAoNSRERERGnIm0l76cqDiXx64qf0df4/4CsCWKpHaZL8fpy0eVPMZDO3MCsTKCUDpsop0s0kS7XvF0Jger8+2Fpaovt5cgmlpK/lQGzGFJDT8S1RdtTGmybi2C4+3aCu3jTY6iWvYdzxATw6/dSkwzTcqMDuBRARERG5gacn7aVLuZKsR5nIR0RpkSQJBYFAzIAEspaSSabOEpHbZQghorf19v3qfb4cPhITkLKkpJHMIUmRcjjtcU7JmlL9XaRLbgvHBaSqK3smDEipKSXjgMDTvsX40/4fQFo2NOM1OB0v5RARERFlyHOT9tKV5xP5iChNoaBrS3qTTSBT9v1KQCrYFoyZRFj/g5dQ1m2ApceDYCgMCAF/W4vnMmhsoT7O5dhnSmlqrth400QEfIVpl3ZHe4h99RV6/f5fsd+74mxIdmQrmoBBKSIiIqIMeXLSXrryeCIfEaXJpEbRZkl3Apmy7080idDyHluIlHU97VuM6oJ/pX4wpceAPlN6ZXsBX2HGkxK1PcSUKa+ntPbFU4AnApEs3yMiory1a9cuXHnllRg0aBD8fj9OOOEELFq0CKFQyO6lGa5DltERDEY/RBYp6HaJXGlsV32EU38REVEafvOb32Ds2LEIBAI45phj7F6Ou2nLe40o6RUifqiCCZT+UvVT66P3ye0ygm36x0vdSYRHjsAf7siqxCtTnWVdgB+tsQEpgycT5jUla2p+Q+d9y4YAt/UH7j8HaP0m7vetvGc52BKKCUhlPY1VCPjRGr2pTHnd+NnXsUM3XIyZUkRElLe2b9+Ojo4O3H///RgyZAg+/PBDzJo1Cy0tLVi2bJndyzOUtomu0aPHzZKoQSgRkRFCoRAuuugijBkzBg8++KDdy3E3vUbRuRACWDkZaHwn9++VBu0EMqXx+agep2N+zLJEXMme/+7T4BcC0p1DLckQU08CDX7TDPw+cn/wuu0IHNPXFdlprqHuM6VkTAHA3g+ApcfF/L6zaWqe1NHXgKR6Dfzthgmo/u/1uWyR4zAoRUREeau2tha1tbXR24MHD8aOHTuwfPlyTwSlJL8f/hEjIG/eHPc5M0aPm0GvQagi66uOaVJGgCtiRoETkScsXrwYAPDwww/bu5CjlP2Ma/vUSVKktMkIbcHYgJQFGUDaMj4AeO/L96L/D7bJuPyNGdjetL3za0rLEBgwOrbEqy1oeplzdEKbqrTLrX28HE/dZ0oI4KHaSFAKiCnpk4Uv66bmunReA4Eu3aI3g6Fw2v2pnIxBKSIiIpVDhw6hrKws4edbW1vR2tqZRt3c3GzFsrIiSRIq//RoXGDFbaPHFUqDUIWZb8RSjQCnBLRlNjxBIg8y8zig7J/dks1qmfkNkWwVk38eShmf3C5DbpdR8+S5KGnr/HzNqnPR6utcQ1V5FfzFAWMzxMiZ1P0Uf/q32N/30X+LjxsF4DoAUsZNzWMI0dloXaG8BlQle9VLXkd1ZU88ddUYQ/cVSiagVT3SGJQiIiI6qqGhAffee2/SLKmlS5dGr6y7gSRJjs+GSlc2DUKzpTcCXKEeBU4a2hMyFzU6JkqX0ccBvaxWp2WzakvWLOezLsAtSRICxQGUFpbirif8GLDrm7jHDCsbhrrautiTdqMyxMj5EpT0Fe95F8eiGQfRPfv3LInKVo++BpR+YhuPZmRt3P0V5Lawoe+PlNLV03udiT9OXBkpbTXxQiAbnRMRkecsWLAgEoxJ8rF9+/aYr9mzZw9qa2tx0UUXYdasWQm/98KFC3Ho0KHoR2Njo9mbQzYbum4tTtq8KfrB7AUNbXNjNSMaHTuNEECoRfXhse3zgGyOAZkw+jigZLWetHkThq5bm9P3MoMyaU45Uc0bR47EBKRKqs7AWzPewTuXvINV312FQHHAcceCYCjsqkEmriZJEJe/jOD8z3Dw6n9G795UejXWdL0ZfiFHjhGZ/D6EiGRgaQNSqtJVpZ/YxpsmGrEVUUrpqtr7B7bilF/9FSff8oqpTdWZKUVERJ5z/fXXY+bMmUkfM3jw4Oj/P//8c0yYMAFjx47FH//4x6RfV1JSgpKSEiOW6WraCXhe6GmQiDICnBJQ99pQhILeLGOxuPEyZSfTY0CmzDgOWJnVKrfLGZXlaCfNVZVXxTQET0oJ2mZSyqtXumSzoevWorCszPHHuXP+ew1OqexneDkXxRNC4If3bzjaQ0rgKd+JOOvoFMRB7Z8ASwdEHtj3NODy1ZHSP73fifL3ru1VBURK9nyBuNdPpJ9YZzsD5T1ZLu/F1KWrTfI3OP+5b2f1fbLBoBQREXlO79690bt377Qeu2fPHkyYMAEjR47EQw89hIICJhGno3rJ67G3TehpQC6i7rXhZdqms2ocw+4YmRwD8lHNqhpUlVehrrYu4312/dR6lJVmEJxRgtPplvI6NPBb4ODG89qBH2aUc1EsIQQOtoRUTc0lXBRahPEVfjxSuAiSOrCkTOlTglPqvyO9QJSi4uy0+6gp78lyfS+mlK6qs6L+duMEHBvoaupgGf6lEhFR3tqzZw9qampQWVmJZcuW4csvv4x+rm/fvjauzJm0fQzU+CaY8o5yBVvBpu6u9Nlnn6GpqQmfffYZwuEwtm7dCgAYMmQIunbtau/iDKSdKrdl/xbI7TICGQZS08qwUkp6Vb120p5Ipxf4ZcA3KacGy7xKCIEfrlgfM2Uvpqk5vqWf+aQEp1JJlVl1lN57MjPei1nRz5PvHImIKG+99tpraGhoQENDAwYMGBDzOfZkiKf0MVBfQQuGwnFZU24khIibUkiUlC+QH9lhHnfLLbegrq4ueruqKtJTZc2aNaipqbFpVcZTSnOajjSZ3xtKXdKbSylvgtIlOsqBZY5eJoSA3BZGMBSOCUhVV/bEsV18scFB9ZS+UEvibCiFOosqzb939Xsyt78XY1CKiIjy1syZM1P2HaFYkT4G3nr7IITA7ksuTThtj4i86+GHH8bDDz9s9zIsIUlS+r2gcn+y3IO2bg78ZtNLKxMpyhyN6DFEEUIIBENhXLRiPT76ojnmcxtvmhgfkFKTJKCkayQ4lWzoR5Z/J155T+b+LSAiIiLKgZDlhAEp/4gRkPwWncR5lfoqPjMeiCgRIbyT9ZNpL61M6ZQ5hgeMhtwQacBvVI+hfKVkRQkB3WAUkCBDKhEL+y4GQ2HXBSMZlCIiIspT2hI1ycGNXK0ydN1aFKiCUPyZGEBdumPWCRoROZYQgAhLwKGDkI71Q9IbKOKgBudKOXfGZdy59NLKxdEyx4IiP6rv32B6jyEvS5YVBQAn9+t+NMjn3Cy06iWvuy4Yyb9OIiIiFxJCQG7vfMOs/n+6do4bH3PbP2IEKv/0qGvexJihwO9HgUVj2T1N7+QMsOYEjcgjOmTZtYHxaJ++UBC7XumN1q+Lgacno6S8GANf+jtQUBC7bdrMH5uam+dUzm1UL61MHS1zlADP9BiygpIN1Xk7cVaUEowK+JwZiNI2PXdbMNIdqyQiIqIoIQSmvzwdW7/cmvHXSn4//CNGQN68Oe5z8ubNELIMiUEZypX65Ayw9gSNyCN2jhtv68UC5eJHJhc9hBAQwSB2XTYNrdu2Hb23OPr51v1t2FF9FoCjF0IefQRSuxxbtje/AejSy5aMSr1y7ozKuC0s09J/+vgeQ24s5zJLOmV5CjdkRSmUpucHW0KuDEYyKEVEROQycrucMCBVVV6VtJGtJEmo/NOjcZPmtFlTRDmz+eSMyI20Fw7suliQzcWPZFlGJScOAfZvi2RMHSVv3ozwH85D4cGNsfEnnzN6zynl3G7NVlO4sZzLCJlkQqk5PSsqkUhAsjCn76GeMGglBqWIiIhcrH5qfUwQyl+U+s2zJEmOzoZSv5G0+o0REZGdlAsH4aYmWy8W6F38SHXRQ5tlVDJ8OAY++gggSZAKO4DbjoMIS+hol7Dz+b4AgJ3/8zn8vY5F5bcPRuJQNpXt6XFzObfby7lykaovlJo6G0rh9KyodGU6gVEIgR+uWI9Nu78CpBC6DTN7hZ28/1dJRETkYf4iPwIOeQNvhJg3RUREeUiSpJiBC2ZRyvJSXcxQLn4kepxeY/Ch69aisKys8/FCAMefDalxA6RCAX+vVsgHIpPi5AMlCF/5DxR0L4PUvcwTAQG76ZVzZRqkcINssqHcVJaXi0wnMMptYd33XgKtCLYVpnXRM1sMShEREZFjJHpTVF3ZE/7i3NLSiYioU82qGgCRDKi62rqEJ5zJLn4kKtkr0Ja8qfrMSUKgsu9khHd/1JkxNen7kefy4sCNUDCS/WXUNgkR24MrAW05V6ZBCqfKti+UwsuBKG2GHJBdltzfbpyAC16I/H/CUxMAAO9c8o5pF0EZlCIiIiJH2njTxOgbaiPfREanQh2V8dhvyo32ZMrIkzWjCdHZrB1I60SQyMn8RX5UlVdhy/7OINKW/Vsgt8tZnXBm1Bhc1WdOumotCkMt8O/+MeQt70UfYufADSGEOceDZUMiZYlXrM59XycEsHJy7KTCJBIFKQ62hHBsF19Gx1VtVlK2Mjme51tfqFwpGXK5TmAs83eJ20+YiUEpIiIicqSAr9Dw/hc5jfsmY2in8Bl1sma0DE/+iNxAkiTU1dZFp+op2VJGyKgxuCRBKumKyscej5b+2dlDy/BjQ3Egsm9r3BC53bghEuDOdfhDWzB2n5SiB1eiIEX1kteTlrFlGwxKh172kp5MA1D5kg2VihETGNX7CUWyfnK5YlCKiIiI8obeVX1FRmO/KTPaEzQ1o07WjKY9+VNzUDNmokxJkpQ0K0oIEXMymuxx6syibBqD6w3e6JBlyyfeaY8NOR8PlHLFlgPxgXijzG8AuvRKGdBXghTarKmPvmjGKYteARAb2DEyAKVH/bzZype+UEbJZgJjqv2EkRiUIiIioiht6UImJwbaSXlOf6OoXNVXuH3st6Op+slEhYLmnawZbX5DZEy9wsklh0Q5EEJg+svT4ybv6T3OrKzTnePG29pbKq5Je7YkKXa/YTRfZvshJWtKbzJduoGidLOc9GQb7GImVHYymcCoTCy0C4NSREREFKUtn8jkxEDbu8DpzVTdPO7blVT9ZFzHF3Dv2onSILfL8Bf5IbfLMQGpqvIq3bIdozOLJL8f/hEjIG/eHFmPjb2l4pq0e4gkSehSUoQXrx2fslm4GcEg5XkzwQBUdvQmMOpxwtRjBqWIiIjynPZkQC3ViYFeE1VFNhNfiIjIejWrajCsbBiWT1weva9+aj3KSlNnDBmRWSRJEir/9CjCTU3RiyNK5i6zWI2n7juUKFBkRjBIr98RmUc7gVHJhlL/brVTj+2Ydsy/CCIiojynnAxoJ9Kl03RW3URVkcvEFyIiimVWcEY7iW9703ZMWDUh5vPa51Oml2p7SRmxLkmSYkqqlWOQnaV8hlKmdzqs/JeBovwRbXRf2ROrfjoGR9rDMWV7G2+amPFURiPwr4+IiIh0m81m8rV8Q0tEZA6zgjPqCVszVs/A9qbt0c/ple1ZMb1UL3PXzFI+vSCbaZQeetlMHBUi0pMvFEz9WCIVvYz2jbu/wrfvegufHmiJeWzAZ0+pJN9BEhEREREROYhVwRllwtaq766KG/8elyWlM73U6Kml6szddDN2s2VFkE138mimE0eFAFZOTjwNlCgJdUa7OpNdG5Cyo2xPwaAUERER2UYIEVf6R3lIe/XfYeUtRFazMjijPF8m49+V6aVm9HvSy9ztkGXDn8uKIFvM5NFsJ462BeMDUhVnR/aTRGlQMtq1WVPqZvZ2NpRnUIqIiIhs4YSJL+QQ2hO1bMpbiDwml7Jqs1k9vXTnuPGm9pYyM8hm6OTR+Q2RaaAM3FMWtH1AnTLZsMDuBRAREVF+0k58UbMzjZwsopS16FHKW4jIEYQQ1vRdUlFKGBVK+aIZlCCbE07Qk/IFIgEup6+THEvJmgr4ihzz985MqaNaW1sxevRovPfee9iyZQvOPPNMu5dEREQE4GiJm6rXh/r/VtCeiGRyJVlbjpfoqtzGmybGjC12ytU7MpG6rEWRbXmLEZRGwuq1EJE1vZd0KCWM4aYmw8sX7QiyxQgFme1EdBSDUkfdcMMN6N+/P9577z27l0JERBQlhMD0l6dj65dbbVuD9mQgkxIKpaFm9HZlz6P9C2K/NuAr5AS/fGRkWUsu2EiYKCFt7yXD+y4lIUkSClTPpQSScimzsyvIFmPZkPTKlIVggJw8j+V7AF5++WW8+uqrWLZsmd1LISIiiiG3ywkDUnoju42iLZuIWVOKEgqlkaaejbu/wsGWEIKhdkuamgsh0BEMdn7YeWWcnEuvkbCCDYWJooauW2taX6d07Bw3HjtGjMTuSy+DECKr72FbkE1bspyqTFkJltuVPUpkkby/JLlv3z7MmjULzz//PAJpNutrbW1Fa2tr9HZzc7NZyyMiIoqqn1ofE4TSG9ltFPXkJ0W6E6C0jTQBxIwh1mZPmcURV8PJfZRGwgqW2BBFFZjRCDwF5SKJvHlz9D7l4kiujeCHrluLwrIya7ZJKVluOZBeoEkbLGeAnDwqr4NSQgjMnDkTV111Faqrq7Fr1660vm7p0qVYvHixuYsjIiLS8Bf5MxrZnatcJj8pjTQV2jHEamY1Ndcb9x1dj4XlJ5QlbcmKVcEhpZEwUZ4TQkDIsu0ZpuqLJOleHEmX5UE2SYoNeiv7uVT7t/kNQJdeDJCTJ3kyKLVgwQLccccdSR+zbds2vPrqqzh8+DAWLlyY0fdfuHAh5s2bF73d3NyMioqKrNZKRESUD/SypxRWNDVXxn1H12PD1X7KkDaTIJ3+K0Qe1yHLluy/nJZpqneRJNOfhVOCbDGU/Zx2/6btJeVjxiZ5lyeDUtdffz1mzpyZ9DGDBw/Gm2++ifXr16OkpCTmc9XV1bj00ktRV1en+7UlJSVxX0NERETJabOnrKSM+yaHU3quNG6I/5zSf4VZTJTHdo4bn9GwiWzpZZo6LcM0k5+Fo4Jsevs59f6Ngxcoz3gyKNW7d2/07t075eN+//vfY8mSJdHbn3/+OSZPnownn3wSo0ePNnOJRERErqa90szMIzKE0nNF3fw3FGSjX8pr2p5KRvVTSpeSaeqE/bzezyLc1JSyL5Sjgmzq/Zx6/6ZkRoXYS4ryiyeDUuk6/vjjY2537doVAHDCCSdgwIABdiyJiIjIFbQ9Pay4ck95QpKYDUWkovRUCjc1GdpPKV1OyjTV+1mkypgSQsRcSHFEkE1vP6cXfGcvKcoDBXYvgIiIiNxBuUKtR7lyT+QKQgChFtVHkrHsRA4gSVJMX7x8JkkSCsvKYo5HSsZURzAIIUT0fqVsTx3MU4JsjriIopTy6ak4mwEpygt5nSmlNXDgwJidGBERkdWEEJDbO4M76v/bTT0BSWH0JCQi07FfC1FS2swiJ0qUMQUAJcOHY+CjjwCShA5N2Z7T+mLpliwrrJo4SmQzBqWIiIgcQgiB6S9Px9Yvt9q9lIT0JiARWUab0ZTNSVtbMHFAir1bKM85qiF4CuqMKaXHFAC0btuGHSOr4x4/dN3alL2nbMGSZcpzDEoRERE5hNwuJwxIVZVXwV/koKu7RHbQ9lzRjlHP1PyGyKh1BTMTKM9pG4I7LrNIIyaDVwjsumwaWrdti3ucf8QIZwakiIhBKSIiIjtoy/SA2FK9+qn1MUEof5H9U49S4UQ+MoXe+HSFeox6NnwBZigQJeDYzCINdQbvoGef0e1vyOMRkXMxKEVERGQDuV3G6MdGJ/y8v8iPgMvKiOyeyCeEiOt3RR6g13NFPUY9FSHiv5bI5ZT9m5nBlgIXBnJYYk7kPgxKEREROYybSvWUiXzqfh4KZSKfFScIbuqDQllI1nMlWZ8pNjUnj1IuAlgd/CciMhqDUkRERDbwF/nxziX6J8puKNVTOGUin7YPiprTe6JQjrQZU31PAy4/2mcqxKbm5B16FwGMCv4rmabMMCUiqzEoRUREZANJklxXnpeI08olhq5biwJVEIq9RDwoWZ+pvR8AS4+Lv59Nzcnl1BcBjAz+M9OUiOzEoBQRERF5SoHfjwIHBcnIBHp9poQAHqqNBKW0Ks4GuvRiEIpcz4yLAHqZpswwJSKrMChFREREpuFEPjKNXp+pn/4tNlClYFYUUVqUTFPuq4nIKgxKERERkWnsnshHeSZZQ3QiSomZpkRktQK7F0BERETeojTj1aM05SUiIvsJIdjcnIhsxUwpIiIiMpRTJvIREeWDDlnOqtyODc6JyAkYlCIicgEhBOT2zK9kZvM1REYweyKfMr5cwSv9RJSvdo4bn1VptLbBOZubE5EdGJQiInI4IQSmvzwdW7/cavdSiByBV/eJKN8pZdLy5s0AOkujs70YMHTdWhSWlbHfHxFZjj2liIgcTm6Xcw5IVZVXwV/Eq5/kDXrjyxW80k9E+UApkx66bq0h36+A0/aIyCbMlCIicpH6qfVZBZf8RXyzSd6kjC9XcIw5EeULSZJi9n/pUsqfWfZMRE7AoBQRkYv4i/wIFHNUM7mb9kQol0ASx5cTUbZ27dqFW2+9FW+++Sb27t2L/v3747LLLsMvf/lL+Hw+u5dnCpY/E5HTMChFREREltJO4cumQS8RUa62b9+Ojo4O3H///RgyZAg+/PBDzJo1Cy0tLVi2bJndy8tYOlP49MqfWfZMRHZiUIqIiIhMp23Kq5Zrg14iomzU1taitrY2envw4MHYsWMHli9f7sqgVKopfEKImExVpfyZZc9EZCcGpYiIiMh0SlNeoToh6pDluKwpPUr/E/XXERGZ4dChQygrK0v6mNbWVrS2tkZvNzc3m72shNKdwqdXtsfyZyJyAgaliIiIUhpItQAAFzFJREFUyBKSJGWcDcX+J0RklYaGBtx7770ps6SWLl2KxYsXW7Sq5JSAf7ipKRrkVwL36gwobdkeS/aIyCkK7F4AERERUYcsoyMYjH4IIQDo9z9R8KSKiPQsWLAgEgRP8rF9+/aYr9mzZw9qa2tx0UUXYdasWUm//8KFC3Ho0KHoR2Njo5mbk5J2Ct/OceOxY8RI7L70MoiOjsh+VVO2xz5+ROQUzJSyUUc4jODXn9u9jPSFZCB8NI55uAkoOmLvehxMXWYSbJNR0GbBk7bLgPLmIngwcpuMFwp2/pzVP3MTyfxdUh7QlvGVDB+OgY8+go4jnccapf+Jgn1QiEjP9ddfj5kzZyZ9zODBg6P///zzzzFhwgSMHTsWf/zjH1N+/5KSEpSUlOS6TEPp9e2TN2/GJ+dfgNDu3TGPLeC+k4gchEEpGwW//hyN4ybZvYwM9Y3885Tb1m2fmlXnotVn0YF/YEXk3xe+Y83z5Svl5/zUBHvXQeRyyZqft27bhh0jq2PuY/8TIkpH79690bt377Qeu2fPHkyYMAEjR47EQw89hIICdxaSqPv2qfv1aQNSzDAlIqdhUIrIRNsHAK3Fdq+CvKKqvAr+Ir6RJO/Qa34OIbDrsmlo3bYt5rE8kSIio+3Zswc1NTWorKzEsmXL8OWXX0Y/17dvXxtXlh2lb5824K9knkKSmGFKRI7DoJSNAsf0R8W6V+1eRuYK/ZaULHnB8f5STLbyZyUEy/asUmT968BfxDeS5D16zc8HPftMbKAKLNUjIuO99tpraGhoQENDAwYMGBDzOaWvnRtpA/7cfxKRkzEoZaOCwkJ0PbbC7mWQ1/i62L0CIqKcZDOlj4goUzNnzkzZe8qtuB8lIrdwZ9E0ERERERERERG5GoNSRERERERERERkOQaliIiIALS2tuLMM8+EJEnYunWr3cshIiIiIvI8BqWIiIgA3HDDDejfv7/dyyAiIiIiyhsMShERUd57+eWX8eqrr2LZsmV2L4WIiIiIKG9w+h4REeW1ffv2YdasWXj++ecRSGNSUWtrK1pbW6O3m5ubzVweEREREZFnMVOKiIjylhACM2fOxFVXXYXq6uq0vmbp0qXo0aNH9KOiosLkVRIREREReRODUkRE5DkLFiyAJElJP7Zv3457770Xhw8fxsKFC9P+3gsXLsShQ4eiH42NjSZuCRERERGRd7F8j4iIPOf666/HzJkzkz5m8ODBePPNN7F+/XqUlJTEfK66uhqXXnop6urq4r6upKQk7vFERERERJQ5BqWIiMhzevfujd69e6d83O9//3ssWbIkevvzzz/H5MmT8eSTT2L06NFmLpGIiIiIKO8xKEVERHnr+OOPj7ndtWtXAMAJJ5yAAQMG2LEkIiIiIqK8waCUAYQQADiBiYhITdknKvtIr+IxgIgoXr4cAwAeB4iI9KR7HGBQygCHDx8GAE5gIiLScfjwYfTo0cPuZaRl4MCBGZ9A8RhARJSYm44B2eJxgIgosVTHAUnkw+ULk3V0dODzzz9Ht27dIElSRl/b3NyMiooKNDY2onv37iat0BnyaVuB/NrefNpWIL+2N5dtFULg8OHD6N+/PwoKvDvslccAb2yHF7YB8MZ2eGEbAG5HvhwDAB4HvLANgDe2wwvbAHA7nMSKcwFmShmgoKAg594j3bt3d+0faqbyaVuB/NrefNpWIL+2N9tt9frVcYDHADUvbIcXtgHwxnZ4YRuA/N6OfDgGADwOKLywDYA3tsML2wBwO5zEzHMBb1+2ICIiIiIiIiIiR2JQioiIiIiIiIiILMeglM1KSkqwaNEilJSU2L0U0+XTtgL5tb35tK1Afm1vPm2rHbzy8/XCdnhhGwBvbIcXtgHgdlB6vPDz9cI2AN7YDi9sA8DtcBIrtoGNzomIiIiIiIiIyHLMlCIiIiIiIiIiIssxKEVERERERERERJZjUIqIiIiIiIiIiCzHoJTJ7rvvPgwcOBClpaUYPXo03n333aSPf+qppzBs2DCUlpbitNNOw0svvWTRSo2RyfY+8MADOOecc9CzZ0/07NkTEydOTPnzcZJMf7eKJ554ApIkYcqUKeYu0GCZbu/XX3+N2bNno1+/figpKcGJJ57omr/nTLf1nnvuwUknnQS/34+Kigr87Gc/w5EjRyxabW7efvttfO9730P//v0hSRKef/75lF9TX1+PESNGoKSkBEOGDMHDDz9s+jrdzCvHgUy24+GHH4YkSTEfpaWlFq42nhf+1jPdhvr6+rjfgyRJ2Lt3rzUL1rF06VKcddZZ6NatG8rLyzFlyhTs2LEj5dc57XWRzXY48XWxfPlynH766ejevTu6d++OMWPG4OWXX076NU77XbhZtu8lnSKb/arTZLtPcppsXstOd/vtt0OSJMydO9fupWTkV7/6Vdy+ftiwYXYvKyt79uzBZZddhmOPPRZ+vx+nnXYaNm7caPjzMChloieffBLz5s3DokWLsHnzZpxxxhmYPHky9u/fr/v4v//97/jRj36EK6+8Elu2bMGUKVMwZcoUfPjhhxavPDuZbm99fT1+9KMfYc2aNVi/fj0qKiowadIk7Nmzx+KVZy7TbVXs2rUL8+fPxznnnGPRSo2R6faGQiGcd9552LVrF55++mns2LEDDzzwAI477jiLV565TLf1sccew4IFC7Bo0SJs27YNDz74IJ588kn84he/sHjl2WlpacEZZ5yB++67L63Hf/rpp/jOd76DCRMmYOvWrZg7dy5+/OMf45VXXjF5pe7kleNANvu87t2744svvoh+7N6928IVx/PC33qm26DYsWNHzO+ivLzcpBWm9tZbb2H27NnYsGEDXnvtNbS1tWHSpEloaWlJ+DVOfF1ksx2A814XAwYMwO23345NmzZh48aN+Na3voXvf//7+Oc//6n7eCf+Ltwq2/eSTpLtPslJsn0tO02mr2Wn+8c//oH7778fp59+ut1Lycopp5wSs69fu3at3UvK2FdffYVx48ahuLgYL7/8Mj766CPceeed6Nmzp/FPJsg0o0aNErNnz47eDofDon///mLp0qW6j586dar4zne+E3Pf6NGjxU9/+lNT12mUTLdXq729XXTr1k3U1dWZtUTDZLOt7e3tYuzYseJ///d/xYwZM8T3v/99C1ZqjEy3d/ny5WLw4MEiFApZtUTDZLqts2fPFt/61rdi7ps3b54YN26cqes0AwDx3HPPJX3MDTfcIE455ZSY+y6++GIxefJkE1fmXl45DmS6HQ899JDo0aOHRavLnBf+1tPZhjVr1ggA4quvvrJkTdnYv3+/ACDeeuuthI9x6utCLZ3tcPrrQtGzZ0/xv//7v7qfc8Pvwi1yfd/sNOnsk9wgndeyWyR7LTvZ4cOHxdChQ8Vrr70mzj33XHHdddfZvaSMLFq0SJxxxhl2LyNnN954oxg/frwlz8VMKZOEQiFs2rQJEydOjN5XUFCAiRMnYv369bpfs379+pjHA8DkyZMTPt5JstlerWAwiLa2NpSVlZm1TENku62//vWvUV5ejiuvvNKKZRomm+3985//jDFjxmD27Nno06cPTj31VNx2220Ih8NWLTsr2Wzr2LFjsWnTpmjK/SeffIKXXnoJF1xwgSVrtpqb91NW88pxINt93jfffIPKykpUVFS48mqtE38X2TrzzDPRr18/nHfeeVi3bp3dy4lx6NAhAEh67HfD7yKd7QCc/boIh8N44okn0NLSgjFjxug+xg2/Czcw4n0zmSPd17KTpfNadrLZs2fjO9/5Tty+xk127tyJ/v37Y/Dgwbj00kvx2Wef2b2kjP35z39GdXU1LrroIpSXl6OqqgoPPPCAKc/FoJRJDhw4gHA4jD59+sTc36dPn4S9HPbu3ZvR450km+3VuvHGG9G/f3/H74Cy2da1a9fiwQcfNO2FbKZstveTTz7B008/jXA4jJdeegk333wz7rzzTixZssSKJWctm2295JJL8Otf/xrjx49HcXExTjjhBNTU1LimfC9TifZTzc3NkGXZplU5k1eOA9lsx0knnYSVK1fihRdewKOPPoqOjg6MHTsW//73v61YsiG88Lfer18/rFixAs888wyeeeYZVFRUoKamBps3b7Z7aQCAjo4OzJ07F+PGjcOpp56a8HFOfF2opbsdTn1dfPDBB+jatStKSkpw1VVX4bnnnsPJJ5+s+1in/y7cwoj3zWS8dF/LTpXJa9mpnnjiCWzevBlLly61eylZGz16NB5++GGsXr0ay5cvx6effopzzjkHhw8ftntpGfnkk0+wfPlyDB06FK+88gquvvpqXHvttairqzP8uYoM/45EWbj99tvxxBNPoL6+3vamn0Y7fPgwpk2bhgceeAC9evWyezmW6OjoQHl5Of74xz+isLAQI0eOxJ49e/Db3/4WixYtsnt5hqqvr8dtt92G//mf/8Ho0aPR0NCA6667Drfeeituvvlmu5dHZIsxY8bEXJ0dO3Yshg8fjvvvvx+33nqrjSvLLyeddBJOOumk6O2xY8fi448/xt13341HHnnExpVFzJ49Gx9++KEre22opbsdTn1dnHTSSdi6dSsOHTqEp59+GjNmzMBbb73lupNZoly5fZ/k9tdyY2MjrrvuOrz22muuPh88//zzo/8//fTTMXr0aFRWVmLVqlWuqpjp6OhAdXU1brvtNgBAVVUVPvzwQ6xYsQIzZsww9LkYlDJJr169UFhYiH379sXcv2/fPvTt21f3a/r27ZvR450km+1VLFu2DLfffjtef/11VzSzy3RbP/74Y+zatQvf+973ovd1dHQAAIqKirBjxw6ccMIJ5i46B9n8bvv164fi4mIUFhZG7xs+fDj27t2LUCgEn89n6pqzlc223nzzzZg2bRp+/OMfAwBOO+00tLS04Cc/+Ql++ctfoqDAWwmpifZT3bt3h9/vt2lVzuSV40Au+3dFcXExqqqq0NDQYMYSTeHVv/VRo0Y54oRrzpw5+Otf/4q3334bAwYMSPpYJ74uFJlsh5ZTXhc+nw9DhgwBAIwcORL/+Mc/8Lvf/Q73339/3GOd/LtwEyP2q2SsXF7LTpHJa9mJNm3ahP3792PEiBHR+8LhMN5++2384Q9/QGtra8y5hVscc8wxOPHEE23f12eqX79+cQHN4cOH45lnnjH8ubx1tuQgPp8PI0eOxBtvvBG9r6OjA2+88UbC2t4xY8bEPB4AXnvtNVfUAmezvQDw3//937j11luxevVqVFdXW7HUnGW6rcOGDcMHH3yArVu3Rj8uvPDC6ESniooKK5efsWx+t+PGjUNDQ0M0+AYA//rXv9CvXz/HBqSA7LY1GAzGBZ6UA6YQwrzF2sTN+ymreeU4kO3+XS0cDuODDz5Av379zFqm4Zz4uzDC1q1bbf09CCEwZ84cPPfcc3jzzTcxaNCglF/jxN9FNtuh5dTXRUdHB1pbW3U/58TfhRsZsV8lYxjxWnaqZK9lJ/r2t78dd85UXV2NSy+9FFu3bnVlQAqI9BL8+OOPHbevT2XcuHHYsWNHzH3/+te/UFlZafyTWdJOPU898cQToqSkRDz88MPio48+Ej/5yU/EMcccI/bu3SuEEGLatGliwYIF0cevW7dOFBUViWXLlolt27aJRYsWieLiYvHBBx/YtQkZyXR7b7/9duHz+cTTTz8tvvjii+jH4cOH7dqEtGW6rVpum76X6fZ+9tlnolu3bmLOnDlix44d4q9//asoLy8XS5YssWsT0pbpti5atEh069ZNPP744+KTTz4Rr776qjjhhBPE1KlT7dqEjBw+fFhs2bJFbNmyRQAQd911l9iyZYvYvXu3EEKIBQsWiGnTpkUf/8knn4hAICB+/vOfi23bton77rtPFBYWitWrV9u1CY7mleNAptuxePFi8corr4iPP/5YbNq0SfzXf/2XKC0tFf/85z/t2gRP/K1nug133323eP7558XOnTvFBx98IK677jpRUFAgXn/9dbs2QVx99dWiR48eor6+PubYHwwGo49xw+sim+1w4utiwYIF4q233hKffvqpeP/998WCBQuEJEni1VdfFUK443fhVqn2q26Qap/kBum8lt0g1WvZrdw4fe/6668X9fX14tNPPxXr1q0TEydOFL169RL79++3e2kZeffdd0VRUZH4zW9+I3bu3Cn+9Kc/iUAgIB599FHDn4tBKZPde++94vjjjxc+n0+MGjVKbNiwIfq5c889V8yYMSPm8atWrRInnnii8Pl84pRTThEvvviixSvOTSbbW1lZKQDEfSxatMj6hWch09+tmtuCUkJkvr1///vfxejRo0VJSYkYPHiw+M1vfiPa29stXnV2MtnWtrY28atf/UqccMIJorS0VFRUVIj/7//7/xw9gl1NGRmv/VC2ccaMGeLcc8+N+5ozzzxT+Hw+MXjwYPHQQw9Zvm438cpxIJPtmDt3bvSxffr0ERdccIHYvHmzDavu5IW/9Uy34Y477ojum8rKykRNTY1488037Vn8UXrrBxDzs3XD6yKb7XDi6+KKK64QlZWVwufzid69e4tvf/vbMSexbvhduFmy/aobpNonuUE6r2U3SPVadis3BqUuvvhi0a9fP+Hz+cRxxx0nLr74YtHQ0GD3srLyl7/8RZx66qmipKREDBs2TPzxj3805XkkITxYX0JERERERERERI7GnlJERERERERERGQ5BqWIiIiIiIiIiMhyDEoREREREREREZHlGJQiIiIiIiIiIiLLMShFRERERERERESWY1CKiIiIiIiIiIgsx6AUERERERERERFZjkEpIiIiIiIiIiKyHINSRC4zc+ZMTJkyxe5lEBGRTXgcICLKXzwGkNcU2b0AIuokSVLSzy9atAi/+93vIISwaEVERGQlHgeIiPIXjwGUjyTBv2gix9i7d2/0/08++SRuueUW7NixI3pf165d0bVrVzuWRkREFuBxgIgof/EYQPmI5XtEDtK3b9/oR48ePSBJUsx9Xbt2jUvZrampwTXXXIO5c+eiZ8+e6NOnDx544AG0tLTg8ssvR7du3TBkyBC8/PLLMc/14Ycf4vzzz0fXrl3Rp08fTJs2DQcOHLB4i4mISI3HASKi/MVjAOUjBqWIPKCurg69evXCu+++i2uuuQZXX301LrroIowdOxabN2/GpEmTMG3aNASDQQDA119/jW9961uoqqrCxo0bsXr1auzbtw9Tp061eUuIiCgbPA4QEeUvHgPIzRiUIvKAM844AzfddBOGDh2KhQsXorS0FL169cKsWbMwdOhQ3HLLLTh48CDef/99AMAf/vAHVFVV4bbbbsOwYcNQVVWFlStXYs2aNfjXv/5l89YQEVGmeBwgIspfPAaQm7HROZEHnH766dH/FxYW4thjj8Vpp50Wva9Pnz4AgP379wMA3nvvPaxZs0a3Jv3jjz/GiSeeaPKKiYjISDwOEBHlLx4DyM0YlCLygOLi4pjbkiTF3KdM8ujo6AAAfPPNN/je976HO+64I+579evXz8SVEhGRGXgcICLKXzwGkJsxKEWUh0aMGIFnnnkGAwcORFERdwNERPmGxwEiovzFYwA5CXtKEeWh2bNno6mpCT/60Y/wj3/8Ax9//DFeeeUVXH755QiHw3Yvj4iITMbjABFR/uIxgJyEQSmiPNS/f3+sW7cO4XAYkyZNwmmnnYa5c+fimGOOQUEBdwtERF7H4wARUf7iMYCcRBJCCLsXQURERERERERE+YVhUCIiIiIiIiIishyDUkREREREREREZDkGpYiIiIiIiIiIyHIMShERERERERERkeUYlCIiIiIiIiIiIssxKEVERERERERERJZjUIqIiIiIiIiIiCzHoBQREREREREREVmOQSkiIiIiIiIiIrIcg1JERERERERERGQ5BqWIiIiIiIiIiMhyDEoREREREREREZHl/n8/giMVzRMg4gAAAABJRU5ErkJggg==", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig1 = plt.figure(figsize=(12,8))\n", + "for i in range(n_evo_times):\n", + " #Initial amps\n", + " ax1 = fig1.add_subplot(2, n_evo_times, i+1)\n", + " ax1.set_title(\"Init amps T={}\".format(evo_times[i]))\n", + " # ax1.set_xlabel(\"Time\")\n", + " ax1.get_xaxis().set_visible(False)\n", + " if i == 0:\n", + " ax1.set_ylabel(\"Control amplitude\")\n", + " for j in range(n_ctrls):\n", + " ax1.step(results[i].time, \n", + " np.hstack((results[i].initial_amps[:, j], \n", + " results[i].initial_amps[-1, j])), \n", + " where='post')\n", + " \n", + " ax2 = fig1.add_subplot(2, n_evo_times, i+n_evo_times+1)\n", + " ax2.set_title(\"Final amps T={}\".format(evo_times[i]))\n", + " ax2.set_xlabel(\"Time\")\n", + " #Optimised amps\n", + " if i == 0:\n", + " ax2.set_ylabel(\"Control amplitude\")\n", + " for j in range(n_ctrls):\n", + " ax2.step(results[i].time, \n", + " np.hstack((results[i].final_amps[:, j], \n", + " results[i].final_amps[-1, j])), \n", + " where='post')\n", + "\n", + "plt.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Versions" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "data": { + "text/html": [ + "
SoftwareVersion
QuTiP5.1.0.dev0+0b4260e
Numpy1.26.4
SciPy1.13.0
matplotlib3.9.0
Number of CPUs8
BLAS InfoGeneric
IPython8.25.0
Python3.12.3 | packaged by Anaconda, Inc. | (main, May 6 2024, 19:46:43) [GCC 11.2.0]
OSposix [linux]
Cython3.0.10
Wed Jan 01 22:48:30 2025 IST
" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 13, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qutip.ipynbtools import version_table\n", + "\n", + "version_table()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.3" + } + }, + "nbformat": 4, + "nbformat_minor": 0 +} diff --git a/tutorials-v5/optimal-control/control-pulseoptim-symplectic.ipynb b/tutorials-v5/optimal-control/control-pulseoptim-symplectic.ipynb new file mode 100644 index 00000000..f8b02dc8 --- /dev/null +++ b/tutorials-v5/optimal-control/control-pulseoptim-symplectic.ipynb @@ -0,0 +1,424 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Calculation of control fields for symplectic dynamics using L-BFGS-B algorithm" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alexander Pitchford (agp1@aber.ac.uk)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Example to demonstrate using the control library to determine control\n", + "pulses using the ctrlpulseoptim.optimize_pulse function.\n", + "The (default) L-BFGS-B algorithm is used to optimise the pulse to\n", + "minimise the fidelity error, which in this case is given by the\n", + "'Trace difference' norm.\n", + "\n", + "This in a Symplectic quantum system example, with two coupled oscillators\n", + "\n", + "The user can experiment with the timeslicing, by means of changing the\n", + "number of timeslots and/or total time for the evolution.\n", + "Different initial (starting) pulse types can be tried.\n", + "The initial and final pulses are displayed in a plot\n", + "\n", + "This example assumes that the example-control-pulseoptim-Hadamard has already been tried, and hence explanations in that notebook are not repeated here." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "import datetime" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "from qutip import Qobj, identity\n", + "\n", + "#QuTiP control modules\n", + "import qutip_qtrl.pulseoptim as cpo\n", + "import qutip_qtrl.symplectic as sympl\n", + "\n", + "example_name = 'Symplectic'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the physics" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "#Drift\n", + "w1 = 1\n", + "w2 = 1\n", + "g1 = 0.5\n", + "A0 = Qobj(np.array([[w1, 0, g1, 0], \n", + " [0, w1, 0, g1], \n", + " [g1, 0, w2, 0], \n", + " [0, g1, 0, w2]]))\n", + "\n", + "#Control\n", + "Ac = Qobj(np.array([[1, 0, 0, 0,], \\\n", + " [0, 1, 0, 0], \\\n", + " [0, 0, 0, 0], \\\n", + " [0, 0, 0, 0]]))\n", + "ctrls = [Ac] \n", + "n_ctrls = len(ctrls)\n", + "\n", + "initial = identity(4)\n", + "\n", + "# Target\n", + "a = 1\n", + "Ag = np.array([[0, 0, a, 0], \n", + " [0, 0, 0, a], \n", + " [a, 0, 0, 0], \n", + " [0, a, 0, 0]])\n", + " \n", + "Sg = Qobj(sympl.calc_omega(2).dot(Ag)).expm()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Defining the time evolution parameters" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Number of time slots\n", + "n_ts = 1000\n", + "# Time allowed for the evolution\n", + "evo_time = 10" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the conditions which will cause the pulse optimisation to terminate" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Fidelity error target\n", + "fid_err_targ = 1e-10\n", + "# Maximum iterations for the optisation algorithm\n", + "max_iter = 500\n", + "# Maximum (elapsed) time allowed in seconds\n", + "max_wall_time = 30\n", + "# Minimum gradient (sum of gradients squared)\n", + "# as this tends to 0 -> local minima has been found\n", + "min_grad = 1e-20" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Set the initial pulse type" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# pulse type alternatives: RND|ZERO|LIN|SINE|SQUARE|SAW|TRIANGLE|\n", + "p_type = 'ZERO'" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Give an extension for output files" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "#Set to None to suppress output files\n", + "f_ext = \"{}_n_ts{}_ptype{}.txt\".format(example_name, n_ts, p_type)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Run the optimisation" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# Note that this call uses\n", + "# dyn_type='SYMPL'\n", + "# This means that matrices that describe the dynamics are assumed to be\n", + "# Symplectic, i.e. the propagator can be calculated using \n", + "# expm(combined_dynamics.omega*dt)\n", + "# This has defaults for:\n", + "# prop_type='FRECHET'\n", + "# therefore the propagators and their gradients will be calculated using the\n", + "# Frechet method, i.e. an exact gradient\n", + "# fid_type='TRACEDIFF'\n", + "# so that the fidelity error, i.e. distance from the target, is give\n", + "# by the trace of the difference between the target and evolved operators \n", + "result = cpo.optimize_pulse(A0, ctrls, initial, Sg, n_ts, evo_time, \n", + " fid_err_targ=fid_err_targ, min_grad=min_grad, \n", + " max_iter=max_iter, max_wall_time=max_wall_time, \n", + " dyn_type='SYMPL', \n", + " out_file_ext=f_ext, init_pulse_type=p_type, \n", + " gen_stats=True)\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Report the results" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "------------------------------------\n", + "---- Control optimisation stats ----\n", + "**** Timings (HH:MM:SS.US) ****\n", + "Total wall time elapsed during optimisation: 0:00:02.809863\n", + "Wall time computing Hamiltonians: 0:00:00.120624 (4.29%)\n", + "Wall time computing propagators: 0:00:02.360108 (83.99%)\n", + "Wall time computing forward propagation: 0:00:00.021711 (0.77%)\n", + "Wall time computing onward propagation: 0:00:00.025040 (0.89%)\n", + "Wall time computing gradient: 0:00:00.225774 (8.04%)\n", + "\n", + "**** Iterations and function calls ****\n", + "Number of iterations: 8\n", + "Number of fidelity function calls: 14\n", + "Number of times fidelity is computed: 14\n", + "Number of gradient function calls: 13\n", + "Number of times gradients are computed: 13\n", + "Number of times timeslot evolution is recomputed: 14\n", + "\n", + "**** Control amplitudes ****\n", + "Number of control amplitude updates: 13\n", + "Mean number of updates per iteration: 1.625\n", + "Number of timeslot values changed: 13000\n", + "Mean number of timeslot changes per update: 1000.0\n", + "Number of amplitude values changed: 13000\n", + "Mean number of amplitude changes per update: 1000.0\n", + "------------------------------------\n", + "Final evolution\n", + "Quantum object: dims=[[4], [4]], shape=(4, 4), type='oper', dtype=Dense, isherm=False\n", + "Qobj data =\n", + "[[ 5.40298994e-01 -1.56965600e-06 -7.01444086e-06 8.41473111e-01]\n", + " [ 1.56965600e-06 5.40298994e-01 -8.41473111e-01 -7.01444087e-06]\n", + " [-7.01444198e-06 8.41473111e-01 5.40298994e-01 1.05774201e-05]\n", + " [-8.41473111e-01 -7.01444198e-06 -1.05774201e-05 5.40298994e-01]]\n", + "\n", + "********* Summary *****************\n", + "Final fidelity error 6.093073931039467e-11\n", + "Final gradient normal 8.70515286864752e-06\n", + "Terminated due to Goal achieved\n", + "Number of iterations 8\n", + "Completed in 0:00:02.809863 HH:MM:SS.US\n" + ] + } + ], + "source": [ + "result.stats.report()\n", + "print(\"Final evolution\\n{}\\n\".format(result.evo_full_final))\n", + "print(\"********* Summary *****************\")\n", + "print(\"Final fidelity error {}\".format(result.fid_err))\n", + "print(\"Final gradient normal {}\".format(result.grad_norm_final))\n", + "print(\"Terminated due to {}\".format(result.termination_reason))\n", + "print(\"Number of iterations {}\".format(result.num_iter))\n", + "print(\"Completed in {} HH:MM:SS.US\".format(datetime.timedelta(seconds=result.wall_time)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Plot the initial and final amplitudes" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAn4AAAHVCAYAAABv4/bQAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjkuMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy80BEi2AAAACXBIWXMAAA9hAAAPYQGoP6dpAACM/UlEQVR4nOzdd1gUV9sG8HuXLh0REEVAREVBURDEXohgjdHEEnuNvnYsQWNvRGOLFU2MmhijMVGTaKJRRI2KDey9oGIBVIQVVNrO94efgyvFRXcZYO/fde3lnjNnZp5lF/dh5hSZIAgCiIiIiKjUk0sdABEREREVDSZ+RERERDqCiR8RERGRjmDiR0RERKQjmPgRERER6QgmfkREREQ6gokfERERkY5g4kdERESkI5j4EREREekIJn5EVGzJZDJMnz5drbYuLi7o27dvoc9x+/ZtyGQyrF+/vtD7liaF+VkTUcnFxI+ItGb9+vWQyWQ4deqURo539OhRTJ8+HcnJyRo53vtISEjAuHHjUL16dZQpUwampqbw8fHB7NmztRrXgwcPMH36dJw5c0Zr5yCi0k9f6gCIiPLz4sUL6Ovn/Dd19OhRzJgxA3379oWVlZVK26tXr0Iu1+7fsidPnkSbNm2QmpqKnj17wsfHBwBw6tQpfP311zh06BD+/fdfrZz7wYMHmDFjBlxcXODt7a2VcxBR6cfEj4iKLWNjY7XbGhkZaTESIDk5GZ988gn09PRw+vRpVK9eXWX7nDlz8N1332k1hsJ4/vw5ypQpI3UYRFTM8FYvERWpvn37wszMDPfv30fHjh1hZmaGcuXKYdy4ccjOzlZp+2a/s+nTp2P8+PEAAFdXV8hkMshkMty+fRtA7j5+SUlJGDduHLy8vGBmZgYLCwu0bt0aZ8+efa+4V69ejfv372PRokW5kj4AsLe3x+TJk1XqVq5ciZo1a8LIyAiOjo4YNmxYrtvBzZo1g6enJy5duoTmzZujTJkyqFChAubPny+2OXDgAOrVqwcA6Nevn/jaX/dLfH2M6OhoNGnSBGXKlMGkSZMAAImJiRgwYADs7e1hbGyM2rVrY8OGDe/1M8jIyMDUqVPh4+MDS0tLmJqaonHjxoiMjFRp97rf5IIFC7BixQpUrlwZZcqUQatWrRAXFwdBEDBr1ixUrFgRJiYm+Pjjj5GUlKRyDBcXF7Rr1w7//vsvvL29YWxsjBo1amDbtm0q7TIzMzFjxgy4u7vD2NgYZcuWRaNGjbB37973eo1EpR2v+BFRkcvOzkZQUBD8/f2xYMEC7Nu3DwsXLoSbmxuGDh2a5z6dOnXCtWvX8Msvv2Dx4sWwtbUFAJQrVy7P9rdu3cKOHTvw2WefwdXVFQkJCVi9ejWaNm2KS5cuwdHRsVAx//nnnzAxMcGnn36qVvvp06djxowZCAwMxNChQ3H16lWsWrUKJ0+exJEjR2BgYCC2ffr0KYKDg9GpUyd06dIFv/32G7788kt4eXmhdevW8PDwwMyZMzF16lQMHjwYjRs3BgA0aNBAPMaTJ0/QunVrdOvWDT179oS9vT1evHiBZs2a4caNGxg+fDhcXV2xdetW9O3bF8nJyRg1alShfgYKhQLff/89unfvjkGDBuHZs2dYu3YtgoKCcOLEiVy3oH/++WdkZGRgxIgRSEpKwvz589GlSxe0aNECBw4cwJdffokbN25g2bJlGDduHH744QeV/a9fv46uXbtiyJAh6NOnD9atW4fPPvsMu3fvxkcffST+nMPCwjBw4ED4+flBoVDg1KlTiImJEdsQ0RsEIiItWbdunQBAOHnypFjXp08fAYAwc+ZMlbZ16tQRfHx8VOoACNOmTRPL33zzjQBAiI2NzXUuZ2dnoU+fPmL55cuXQnZ2tkqb2NhYwcjISOXcsbGxAgBh3bp1Bb4Wa2troXbt2gW2eS0xMVEwNDQUWrVqpRLD8uXLBQDCDz/8INY1bdpUACD8+OOPYl16errg4OAgdO7cWaw7efJkvnG+PkZ4eLhK/ZIlSwQAwsaNG8W6jIwMISAgQDAzMxMUCoVY//bPOi9ZWVlCenq6St3Tp08Fe3t7oX///mLd659puXLlhOTkZLF+4sSJAgChdu3aQmZmpljfvXt3wdDQUHj58qVY5+zsLAAQfv/9d7EuJSVFKF++vFCnTh2xrnbt2kLbtm0LjJuIcvBWLxFJYsiQISrlxo0b49atWxo7vpGRkTjYIzs7G0+ePIGZmRmqVauGmJiYQh9PoVDA3Nxcrbb79u1DRkYGRo8erTLgZNCgQbCwsMCuXbtU2puZmaFnz55i2dDQEH5+foX6eRgZGaFfv34qdX///TccHBzQvXt3sc7AwAAjR45EamoqDh48qPbxAUBPTw+GhoYAAKVSiaSkJGRlZcHX1zfPn+lnn30GS0tLsezv7w8A6Nmzp8qgHX9/f2RkZOD+/fsq+zs6OuKTTz4RyxYWFujduzdOnz6N+Ph4AICVlRUuXryI69evF+q1EOkqJn5EVOSMjY1z3aK1trbG06dPNXYOpVKJxYsXw93dHUZGRrC1tUW5cuVw7tw5pKSkFPp4FhYWePbsmVpt79y5AwCoVq2aSr2hoSEqV64sbn+tYsWKkMlkKnWF/XlUqFBBTMrejMPd3T3XaGcPDw+VOAtjw4YNqFWrltifrly5cti1a1eeP9NKlSqplF8ngU5OTnnWv/16q1SpkuvnUrVqVQAQ+3bOnDkTycnJqFq1Kry8vDB+/HicO3eu0K+LSFcw8SOiIqenp6f1c8ydOxchISFo0qQJNm7ciD179mDv3r2oWbMmlEploY9XvXp1XLt2DRkZGRqPNb+fhyAIah/DxMREU+Hka+PGjejbty/c3Nywdu1a7N69G3v37kWLFi3y/Jnm97o08Xpfa9KkCW7evIkffvgBnp6e+P7771G3bl18//33hT4WkS5g4kdEJcbbV38K8ttvv6F58+ZYu3YtunXrhlatWiEwMPC9J1lu3749Xrx4gd9///2dbZ2dnQG8mlvwTRkZGYiNjRW3F0ZhXvubcVy/fj1XUnblyhWVONX122+/oXLlyti2bRt69eqFoKAgBAYG4uXLl4WOTR03btzIlQxeu3YNwKtRv6/Z2NigX79++OWXXxAXF4datWpxFRKifDDxI6ISw9TUFADUSt709PRyJQ1bt27N1Y9MXUOGDEH58uUxduxYMfl4U2JiImbPng0ACAwMhKGhIZYuXaoSw9q1a5GSkoK2bdsW+vyFee2vtWnTBvHx8diyZYtYl5WVhWXLlsHMzAxNmzYtVAyvr9S9+ZqOHz+OqKioQh1HXQ8ePMD27dvFskKhwI8//ghvb284ODgAeDWa+U1mZmaoUqUK0tPTtRITUUnH6VyIqMR4vVLGV199hW7dusHAwADt27cXk6I3tWvXDjNnzkS/fv3QoEEDnD9/Hj///DMqV678Xue2trbG9u3b0aZNG3h7e6us3BETE4NffvkFAQEBAF5NMTNx4kTMmDEDwcHB6NChA65evYqVK1eiXr16KgM51OXm5gYrKyuEh4fD3Nwcpqam8Pf3h6ura777DB48GKtXr0bfvn0RHR0NFxcX/Pbbbzhy5AiWLFmi9mCV19q1a4dt27bhk08+Qdu2bREbG4vw8HDUqFEDqamphX5N71K1alUMGDAAJ0+ehL29PX744QckJCRg3bp1YpsaNWqgWbNm8PHxgY2NDU6dOoXffvsNw4cP13g8RKUBEz8iKjHq1auHWbNmITw8HLt374ZSqURsbGyeid+kSZOQlpaGTZs2YcuWLahbty527dqF0NDQ9z6/v78/Lly4gG+++Qa7du3CTz/9BLlcDg8PD4SGhqokG9OnT0e5cuWwfPlyjBkzBjY2Nhg8eDDmzp2rMoefugwMDLBhwwZMnDgRQ4YMQVZWFtatW1dg4mdiYoIDBw4gNDQUGzZsgEKhQLVq1bBu3TqVya7V1bdvX8THx2P16tXYs2cPatSogY0bN2Lr1q04cOBAoY/3Lu7u7li2bBnGjx+Pq1evwtXVFVu2bEFQUJDYZuTIkfjzzz/x77//Ij09Hc7Ozpg9e7Y42TcRqZIJ79ObloiISItcXFzg6emJnTt3Sh0KUanCPn5EREREOoKJHxEREZGOYOJHREREpCPYx4+IiIhIR/CKHxEREZGO4HQuRUCpVOLBgwcwNzd/r9n3iYiIiAoiCAKePXsGR0fHXOtzv4mJXxF48OBBrkXJiYiIiDQtLi4OFStWzHc7E78i8Hp2/Li4OFhYWEgcDREREZU2CoUCTk5O71yRh4lfEXh9e9fCwoKJHxEREWnNu7qUcXAHERERkY4ocYnfihUr4OLiAmNjY/j7++PEiRMFtt+6dSuqV68OY2NjeHl54e+//1bZ3rdvX8hkMpVHcHCwSpukpCT06NEDFhYWsLKywoABA7SyIDkRERGRNpWoxG/Lli0ICQnBtGnTEBMTg9q1ayMoKAiJiYl5tj969Ci6d++OAQMG4PTp0+jYsSM6duyICxcuqLQLDg7Gw4cPxccvv/yisr1Hjx64ePEi9u7di507d+LQoUMYPHiw1l4nERERkTaUqAmc/f39Ua9ePSxfvhzAq2lSnJycMGLECISGhuZq37VrV6Slpaks8l2/fn14e3sjPDwcwKsrfsnJydixY0ee57x8+TJq1KiBkydPwtfXFwCwe/dutGnTBvfu3YOjo2OufdLT05Geni6WX3e4TElJYR8/IiIi0jiFQgFLS8t35hol5opfRkYGoqOjERgYKNbJ5XIEBgYiKioqz32ioqJU2gNAUFBQrvYHDhyAnZ0dqlWrhqFDh+LJkycqx7CyshKTPgAIDAyEXC7H8ePH8zxvWFgYLC0txQenciEiIqLioMQkfo8fP0Z2djbs7e1V6u3t7REfH5/nPvHx8e9sHxwcjB9//BERERGYN28eDh48iNatWyM7O1s8hp2dncox9PX1YWNjk+95J06ciJSUFPERFxdX6NdLREREpGk6P51Lt27dxOdeXl6oVasW3NzccODAAbRs2fK9jmlkZAQjIyNNhUhERESkESXmip+trS309PSQkJCgUp+QkAAHB4c893FwcChUewCoXLkybG1tcePGDfEYbw8eycrKQlJSUoHHISIiIipuSkziZ2hoCB8fH0RERIh1SqUSERERCAgIyHOfgIAAlfYAsHfv3nzbA8C9e/fw5MkTlC9fXjxGcnIyoqOjxTb79++HUqmEv7//h7wkIiIioiJVYhI/AAgJCcF3332HDRs24PLlyxg6dCjS0tLQr18/AEDv3r0xceJEsf2oUaOwe/duLFy4EFeuXMH06dNx6tQpDB8+HACQmpqK8ePH49ixY7h9+zYiIiLw8ccfo0qVKggKCgIAeHh4IDg4GIMGDcKJEydw5MgRDB8+HN26dctzRC8RERFRcVWi+vh17doVjx49wtSpUxEfHw9vb2/s3r1bHMBx9+5dyOU5uWyDBg2wadMmTJ48GZMmTYK7uzt27NgBT09PAICenh7OnTuHDRs2IDk5GY6OjmjVqhVmzZql0kfv559/xvDhw9GyZUvI5XJ07twZS5cuLdoXT0RERPSBStQ8fiWVunPrEBEREb2PUjePHxERERF9mPdK/LKysrBv3z6sXr0az549AwA8ePCA69cSERERFWOF7uN3584dBAcH4+7du0hPT8dHH30Ec3NzzJs3D+np6eJSaERERERUvBT6it+oUaPg6+uLp0+fwsTERKz/5JNPck2dQkRERETFR6Gv+P333384evQoDA0NVepdXFxw//59jQVGRERERJpV6Ct+SqVSXMf2Tffu3YO5ublGgiIiIiIizSt04teqVSssWbJELMtkMqSmpmLatGlo06aNJmMjIiIiIg0q9Dx+9+7dQ1BQEARBwPXr1+Hr64vr16/D1tYWhw4dgp2dnbZiLbE4jx8RERFpk7q5xntN4JyVlYXNmzfj3LlzSE1NRd26ddGjRw+VwR6Ug4kfERERaZO6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jh07aiEMIiIiItK2Qg/uoMLj4A4iIiLSJnVzjUJf8XstOjpaXE6tZs2aqFOnzvseioiIiIiKQKETv8TERHTr1g0HDhwQl0JLTk5G8+bNsXnzZrVW4iAiIiKiolfoUb0jRozAs2fPcPHiRSQlJSEpKQkXLlyAQqHAyJEjtREjEREREWlAofv4WVpaYt++fahXr55K/YkTJ9CqVSskJydrMr5SgX38iIiISJu0NoGzUqnMNYULABgYGORat5eIiIiIio9CJ34tWrTAqFGj8ODBA7Hu/v37GDNmDFq2bKnR4IiIiIhIcwqd+C1fvhwKhQIuLi5wc3ODm5sbXF1doVAosGzZMm3ESEREREQaUOhRvU5OToiJicG+fftw5coVAICHhwcCAwM1HhwRERERaQ4ncC4CHNxBRERE2qTxwR379+9HjRo1oFAocm1LSUlBzZo18d9//71ftERERESkdWonfkuWLMGgQYPyzCItLS3xxRdfYNGiRRoNjoiIiIg0R+3E7+zZswgODs53e6tWrRAdHa2RoIiIiIhI89RO/BISEvKcv+81fX19PHr0SCNBEREREZHmqZ34VahQARcuXMh3+7lz51C+fHmNBEVEREREmqd24temTRtMmTIFL1++zLXtxYsXmDZtGtq1a6fR4IiIiIhIc9SeziUhIQF169aFnp4ehg8fjmrVqgEArly5ghUrViA7OxsxMTGwt7fXasAlEadzISIiIm1SN9dQewJne3t7HD16FEOHDsXEiRPxOl+UyWQICgrCihUrmPQRERERFWOFWrnD2dkZf//9N54+fYobN25AEAS4u7vD2tpaW/ERERERkYYUesk2ALC2tka9evU0HQsRERERaZHagzuklpSUhB49esDCwgJWVlYYMGAAUlNTC9zn5cuXGDZsGMqWLQszMzN07twZCQkJKm1kMlmux+bNm1XaHDhwAHXr1oWRkRGqVKmC9evXa/rlEREREWldiUn8evTogYsXL2Lv3r3YuXMnDh06hMGDBxe4z5gxY/DXX39h69atOHjwIB48eIBOnTrlardu3To8fPhQfHTs2FHcFhsbi7Zt26J58+Y4c+YMRo8ejYEDB2LPnj2afolEREREWqX2qF4pXb58GTVq1MDJkyfh6+sLANi9ezfatGmDe/fuwdHRMdc+KSkpKFeuHDZt2oRPP/0UwKsRyB4eHoiK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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "fig1 = plt.figure()\n", + "ax1 = fig1.add_subplot(2, 1, 1)\n", + "ax1.set_title(\"Initial Control amps\")\n", + "ax1.set_xlabel(\"Time\")\n", + "ax1.set_ylabel(\"Control amplitude\")\n", + "for j in range(n_ctrls):\n", + " ax1.step(result.time, \n", + " np.hstack((result.initial_amps[:, j], result.initial_amps[-1, j])), \n", + " where='post')\n", + "\n", + "ax2 = fig1.add_subplot(2, 1, 2)\n", + "ax2.set_title(\"Optimised Control Amplitudes\")\n", + "ax2.set_xlabel(\"Time\")\n", + "ax2.set_ylabel(\"Control amplitude\")\n", + "for j in range(n_ctrls):\n", + " ax2.step(result.time, \n", + " np.hstack((result.final_amps[:, j], result.final_amps[-1, j])), \n", + " where='post')\n", + " \n", + "plt.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Versions" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": { + "collapsed": false + }, + "outputs": [ + { + "data": { + "text/html": [ + "
SoftwareVersion
QuTiP5.1.0.dev0+0b4260e
Numpy1.26.4
SciPy1.13.0
matplotlib3.9.0
Number of CPUs8
BLAS InfoGeneric
IPython8.25.0
Python3.12.3 | packaged by Anaconda, Inc. | (main, May 6 2024, 19:46:43) [GCC 11.2.0]
OSposix [linux]
Cython3.0.10
Thu Jan 30 09:55:30 2025 IST
" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 11, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qutip.ipynbtools import version_table\n", + "\n", + "version_table()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.3" + } + }, + "nbformat": 4, + "nbformat_minor": 0 +} diff --git a/tutorials-v5/optimal-control/optimal-control-overview.ipynb b/tutorials-v5/optimal-control/optimal-control-overview.ipynb new file mode 100644 index 00000000..7d83204a --- /dev/null +++ b/tutorials-v5/optimal-control/optimal-control-overview.ipynb @@ -0,0 +1,224 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# QuTiP overview - Optimal Control" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alexander Pitchford (alex.pitchford@gmail.com),\n", + "Jonathan Zoller (jonathan.zoller@uni-ulm.de)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Introduction\n", + "In quantum control we look to prepare some specific state, effect some state-to-state transfer, or effect some transformation (or gate) on a quantum system. For a given quantum system there will always be factors that effect the dynamics that are outside of our control. As examples, the interactions between elements of the system or a magnetic field required to trap the system. However, there may be methods of affecting the dynamics in a controlled way, such as the time varying amplitude of the electric component of an interacting laser field. And so this leads to some questions; given a specific quantum system with known time-independent dynamics generator (referred to as the *drift* dynamics generators) and set of externally controllable fields for which the interaction can be described by *control* dynamics generators:\n", + "1. what states or transformations can we achieve (if any)?\n", + "2. what is the shape of the control pulse required to achieve this?\n", + "\n", + "These questions are addressed as *controllability* and *quantum optimal control* [1]. The answer to question of *controllability* is determined by the commutability of the dynamics generators and is formalised as the *Lie Algebra Rank Criterion* and is discussed in detail in [1]. The solutions to the second question can be determined through optimal control algorithms, or control pulse optimisation. \n", + "![qc_shematic](./images/quant_optim_ctrl.png \"Schematic showing the principle of quantum control\")\n", + "\n", + "Quantum Control has many applications including NMR, *quantum metrology*, *control of chemical reactions*, and *quantum information processing*.\n", + "\n", + "To explain the physics behind these algorithms we will first consider only finite-dimensional, closed quantum systems." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "collapsed": true + }, + "source": [ + "# Closed Quantum Systems\n", + "In closed quantum systems the states can be represented by kets, and the transformations on these states are unitary operators. The dynamics generators are Hamiltonians. The combined Hamiltonian for the system is given by\n", + "\n", + "$ H(t) = H_0 + \\sum_{j=1} u_j(t) H_j $\n", + "\n", + "where $H_0$ is the drift Hamiltonian and the $H_j$ are the control Hamiltonians. The $u_j$ are time varying amplitude functions for the specific control.\n", + "\n", + "The dynamics of the system are governed by *Schrödingers equation*.\n", + "\n", + "$\\newcommand{\\ket}[1]{\\left|{#1}\\right\\rangle} \\tfrac{d}{dt}\\ket{\\psi} = -i H(t)\\ket{\\psi} $\n", + "\n", + "Note we use units where $\\hbar=1$ throughout. The solutions to Schrödinger's equation are of the form:\n", + "\n", + "$\\ket{\\psi(t)} = U(t)\\ket{\\psi_0}$\n", + "\n", + "where $\\psi_0$ is the state of the system at $t=0$ and $U(t)$ is a unitary operator on the Hilbert space containing the states. $U(t)$ is a solution to the *Schrödinger operator equation*\n", + "\n", + "$\\tfrac{d}{dt}U = -i H(t)U ,\\quad U(0) = \\mathbb{1}$\n", + "\n", + "We can use optimal control algorithms to determine a set of $u_j$ that will drive our system from $\\ket{\\psi_0}$ to $\\ket{\\psi_1}$, this is state-to-state transfer, or drive the system from some arbitary state to a given state $\\ket{\\psi_1}$, which is state preparation, or effect some unitary transformation $U_{target}$, called gate synthesis. The latter of these is most important in quantum computation." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# The GRAPE algorithm\n", + "The GRadient Ascent Pulse Engineering was first proposed in [2]. Solutions to Schrödinger's equation for a time-dependent Hamiltonian are not generally possible to obtain analytically. Therefore, a piecewise constant approximation to the pulse amplitudes is made. Time allowed for the system to evolve $T$ is split into $M$ timeslots (typically these are of equal duration), during which the control amplitude is assumed to remain constant. The combined Hamiltonian can then be approximated as:\n", + "\n", + "$H(t) \\approx H(t_k) = H_0 + \\sum_{j=1}^N u_{jk} H_j\\quad$\n", + "\n", + "where $k$ is a timeslot index, $j$ is the control index, and $N$ is the number of controls. Hence $t_k$ is the evolution time at the start of the timeslot, and $u_{jk}$ is the amplitude of control $j$ throughout timeslot $k$. The time evolution operator, or propagator, within the timeslot can then be calculated as:\n", + "\n", + "$X_k:=e^{-iH(t_k)\\Delta t_k}$\n", + "\n", + "where $\\Delta t_k$ is the duration of the timeslot. The evolution up to (and including) any timeslot $k$ (including the full evolution $k=M$) can the be calculated as\n", + "\n", + "$X(t_k):=X_k X_{k-1}\\cdots X_1 X_0$\n", + "\n", + "If the objective is state-to-state transfer then $X_0=\\ket{\\psi_0}$ and the target $X_{targ}=\\ket{\\psi_1}$, for gate synthesis $X_0 = U(0) = \\mathbb{1}$ and the target $X_{targ}=U_{targ}$.\n", + "\n", + "A *figure of merit* or *fidelity* is some measure of how close the evolution is to the target, based on the control amplitudes in the timeslots. The typical figure of merit for unitary systems is the normalised overlap of the evolution and the target.\n", + "\n", + "$\\newcommand{\\tr}[0]{\\operatorname{tr}} f_{PSU} = \\tfrac{1}{d} \\big| \\tr \\{X_{targ}^{\\dagger} X(T)\\} \\big|$\n", + "\n", + "where $d$ is the system dimension. In this figure of merit the absolute value is taken to ignore any differences in global phase, and $0 \\le f \\le 1$. Typically the fidelity error (or *infidelity*) is more useful, in this case defined as $\\varepsilon = 1 - f_{PSU}$. There are many other possible objectives, and hence figures of merit.\n", + "\n", + "As there are now $N \\times M$ variables (the $u_{jk}$) and one parameter to minimise $\\varepsilon$, then the problem becomes a finite multi-variable optimisation problem, for which there are many established methods, often referred to as 'hill-climbing' methods. The simplest of these to understand is that of steepest ascent (or descent). The gradient of the fidelity with respect to all the variables is calculated (or approximated) and a step is made in the variable space in the direction of steepest ascent (or descent). This method is a first order gradient method. In two dimensions this describes a method of climbing a hill by heading in the direction where the ground rises fastest. This analogy also clearly illustrates one of the main challenges in multi-variable optimisation, which is that all methods have a tendency to get stuck in local maxima. It is hard to determine whether one has found a global maximum or not - a local peak is likely not to be the highest mountain in the region. In quantum optimal control we can typically define an infidelity that has a lower bound of zero. We can then look to minimise the infidelity (from here on we will only consider optimising for infidelity minima). This means that we can terminate any pulse optimisation when the infidelity reaches zero (to a sufficient precision). This is however only possible for fully controllable systems; otherwise it is hard (if not impossible) to know that the minimum possible infidelity has been achieved. In the hill walking analogy the step size is roughly fixed to a stride, however, in computations the step size must be chosen. Clearly there is a trade-off here between the number of steps (or iterations) required to reach the minima and the possibility that we might step over a minima. In practice it is difficult to determine an efficient and effective step size.\n", + "\n", + "The second order differentials of the infidelity with respect to the variables can be used to approximate the local landscape to a parabola. This way a step (or jump) can be made to where the minima would be if it were parabolic. This typically vastly reduces the number of iterations, and removes the need to guess a step size. The method where all the second differentials are calculated explicitly is called the *Newton-Raphson* method. However, calculating the second-order differentials (the Hessian matrix) can be computationally expensive, and so there are a class of methods known as *quasi-Newton* that approximate the Hessian based on successive iterations. The most popular of these (in quantum optimal control) is the Broyden–Fletcher–Goldfarb–Shanno algorithm (BFGS). The default method in the QuTiP Qtrl GRAPE implementation is the L-BFGS-B method in Scipy, which is a wrapper to the implementation described in [3]. This limited memory and bounded method does not need to store the entire Hessian, which reduces the computer memory required, and allows bounds to be set for variable values, which considering these are field amplitudes is often physical.\n", + "\n", + "The pulse optimisation is typically far more efficient if the gradients can be calculated exactly, rather than approximated. For simple fidelity measures such as $f_{PSU}$ this is possible. Firstly the propagator gradient for each timeslot with respect to the control amplitudes is calculated. For closed systems, with unitary dynamics, a method using the eigendecomposition is used, which is efficient as it is also used in the propagator calculation (to exponentiate the combined Hamiltonian). More generally (for example open systems and symplectic dynamics) the Frechet derivative (or augmented matrix) method is used, which is described in [4]. For other optimisation goals it may not be possible to calculate analytic gradients. In these cases it is necessary to approximate the gradients, but this can be very expensive, and can lead to other algorithms out-performing GRAPE.\n", + "\n", + "QuTiP examples of GRAPE using second order gradient ascent methods are given in: \n", + "- [pulseoptim Hadamard](http://nbviewer.ipython.org/github/qutip/qutip-tutorials/blob/master/examples/control-pulseoptim-Hadamard.ipynb)\n", + "- [pulseoptim QFT](http://nbviewer.ipython.org/github/qutip/qutip-tutorials/blob/master/examples/control-pulseoptim-QFT.ipynb) \n", + "- Open systems: [pulseoptim - Lindbladian](http://nbviewer.ipython.org/github/qutip/qutip-tutorials/blob/master/examples/control-pulseoptim-Lindbladian.ipynb) \n", + "- Symplectic dynamics: [pulseoptim - symplectic](http://nbviewer.ipython.org/github/qutip/qutip-tutorials/blob/master/examples/control-pulseoptim-symplectic.ipynb)\n", + "\n", + "\n", + "\n", + "\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# The CRAB Algorithm\n", + "It has been shown [5], the dimension of a quantum optimal control problem is a polynomial function of the dimension of the manifold of the time-polynomial reachable states, when allowing for a finite control precision and evolution time. You can think of this as the information content of the pulse (as being the only effective input) being very limited e.g. the pulse is compressible to a few bytes without loosing the target.\n", + "\n", + "This is where the Chopped RAndom Basis (CRAB) algorithm [6,7] comes into play: Since the pulse complexity is usually very low, it is sufficient to transform the optimal control problem to a few parameter search by introducing a physically motivated function basis that builds up the pulse. Compared to the number of time slices needed to accurately simulate quantum dynamics (often equals basis dimension for Gradient based algorithms), this number is lower by orders of magnitude, allowing CRAB to efficiently optimize smooth pulses with realistic experimental constraints. It is important to point out, that CRAB does not make any suggestion on the basis function to be used. The basis must be chosen carefully considered, taking into account a priori knowledge of the system (such as symmetries, magnitudes of scales,...) and solution (e.g. sign, smoothness, bang-bang behavior, singularities, maximum excursion or rate of change,....). By doing so, this algorithm allows for native integration of experimental constraints such as maximum frequencies allowed, maximum amplitude, smooth ramping up and down of the pulse and many more. Moreover initial guesses, if they are available, can (however not have to) be included to speed up convergence.\n", + "\n", + "As mentioned in the GRAPE paragraph, for CRAB local minima arising from algorithmic design can occur, too. However, for CRAB a 'dressed' version has recently been introduced [8] that allows to escape local minima.\n", + "\n", + "For some control objectives and/or dynamical quantum descriptions, it is either not possible to derive the gradient for the cost functional with respect to each time slice or it is computationally expensive to do so. The same can apply for the necessary (reverse) propagation of the co-state. All this trouble does not occur within CRAB as those elements are not in use here. CRAB, instead, takes the time evolution as a black-box where the pulse goes as an input and the cost (e.g. infidelity) value will be returned as an output. This concept, on top, allows for direct integration in a closed loop experimental environment where both the preliminarily open loop optimization, as well as the final adoption, and integration to the lab (to account for modeling errors, experimental systematic noise, ...) can be done all in one, using this algorithm.\n", + "\n", + "QuTiP examples of CRAB control are given in:\n", + "- [State-to-state 2 Qubit (CRAB)](http://nbviewer.jupyter.org/github/qutip/qutip-tutorials/blob/master/examples/control-pulseoptim-CRAB-2qubitInerac.ipynb)\n", + "- [QFT (CRAB)](http://nbviewer.jupyter.org/github/qutip/qutip-tutorials/blob/master/examples/control-pulseoptim-CRAB-QFT.ipynb) \n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# The QuTiP optimal control implementation\n", + "There are two separate implementations of optimal control inside QuTiP. The first is an implementation of first order GRAPE, and is not further described here, but there are the example notebooks listed above. The second is referred to as Qtrl (when a distinction needs to be made) as this was its name before it was integrated into QuTiP. Qtrl uses the Scipy optimize functions to perform the multi-variable optimisation, typically the L-BFGS-B method for GRAPE and Nelder-Mead for CRAB. The GRAPE implementation in Qtrl was initially based on the open-source package DYNAMO, which is a MATLAB implementation, and is described in [9]. It has since been restructured and extended for flexibility and compatibility within QuTiP. Merging the GRAPE implementations is part of the near future plans. An implementation of the 'dressed' CRAB algorithm is also planned for the near future.\n", + "\n", + "The rest of this section describes the Qtrl implementation and how to use it.\n", + "\n", + "## Object Model\n", + "The Qtrl code is organised in a hierarchical object model in order to try and maximise configurability whilst maintaining some clarity. It is not necessary to understand the model in order to use the pulse optimisation functions, but it is the most flexible method of using Qtrl. If you just want to use a simple single function call interface (as in the notebook examples) then skip to the section on 'Using the pulseoptim functions'.\n", + "![qtrl-code_obj_model](./images/qtrl-code_object_model.png \"Qtrl code object model\")\n", + "\n", + "The object's properties and methods are described in detail in the documentation, so that will not be repeated here.\n", + "\n", + "### OptimConfig\n", + "The OptimConfig object is used simply to hold configuration parameters used by all the objects. Typically this is the subclass types for the other objects and parameters for the users specific requirements. The loadparams module can be used read parameter values from a configuration file.\n", + "\n", + "### Optimizer\n", + "This acts as a wrapper to the Scipy.optimize functions that perform the work of the pulse optimisation algorithms. Using the main classes the user can specify which of the optimisation methods are to be used. There are subclasses specifically for the BFGS and L-BFGS-B methods. There is another subclass for using the CRAB algorithm.\n", + "\n", + "### Dynamics\n", + "This is mainly a container for the lists that hold the dynamics generators, propagators, and time evolution operators in each timeslot. The combining of dynamics generators is also complete by this object. Different subclasses support a range of types of quantum systems, including closed systems with unitary dynamics, systems with quadratic Hamiltonians that have Gaussian states and symplectic transforms, and a general subclass that can be used for open system dynamics with Lindbladian operators.\n", + "\n", + "### PulseGen\n", + "There are many subclasses that of pulse generators that generate different types of pulses as the initial amplitudes for the optimisation. Often the goal cannot be achieved from all starting conditions, and then typically some kind of random pulse is used and repeated optimisations are performed until the desired infidelity is reached or the minimum infidelity found is reported.\n", + "\n", + "There is a specific subclass that is used by the CRAB algorithm to generate the pulses based on the basis coefficients that are being optimised.\n", + "\n", + "### TerminationConditions\n", + "This is simply a convenient place to hold all the properties that will determine when the single optimisation run terminates. Limits can be set for number of iterations, time, and of course the target infidelity.\n", + "\n", + "### Stats\n", + "Performance data are optionally collected during the optimisation. This object is shared to a single location to store, calculate and report run statistics.\n", + "\n", + "### FidelityComputer\n", + "The subclass of the fidelity computer determines the type of fidelity measure. These are closely linked to the type of dynamics in use. These are also the most commonly user customised subclasses.\n", + "\n", + "### PropagatorComputer\n", + "This object computes propagators from one timeslot to the next and also the propagator gradient. The options are using the spectral decomposition or Frechet derivative, as discussed above.\n", + "\n", + "### TimeslotComputer\n", + "Here the time evolution is computed by calling the methods of the other computer objects.\n", + "\n", + "### OptimResult\n", + "The result of a pulse optimisation run is returned as an object with properties for the outcome in terms of the infidelity, reason for termination, performance statistics, final evolution, and more.\n", + "\n", + "## Using the pulseoptim functions\n", + "The simplest method for optimising a control pulse is to call one of the functions in the pulseoptim module. This automates the creation and configuration of the necessary objects, generation of initial pulses, running the optimisation and returning the result. There are functions specifically for unitary dynamics, and also specifically for the CRAB algorithm (GRAPE is the default). The optimise_pulse function can in fact be used for unitary dynamics and / or the CRAB algorithm, the more specific functions simply have parameter names that are more familiar in that application. \n", + "\n", + "A semi-automated method is to use the create_optimizer_objects function to generate and configure all the objects, then manually set the initial pulse and call the optimisation. This would be more efficient when repeating runs with different starting conditions. A example of this method is given in [pulseoptim QFT](http://nbviewer.ipython.org/github/qutip/qutip-notebooks/blob/master/examples/control-pulseoptim-QFT.ipynb)\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# References\n", + "1. D. d’Alessandro, *Introduction to Quantum Control and Dynamics* (Chapman & Hall/CRC, 2008)\n", + "2. N. Khaneja, T. Reiss, C. Kehlet, T. Schulte-Herbruggen, and S. J. Glaser, J. Magn. Reson. 172, 296 (2005).\n", + "3. R. H. Byrd, P. Lu, J. Nocedal, and C. Zhu, SIAM J. Sci. Comput. 16, 1190 (1995).\n", + "4. F. F. Floether, P. de Fouquieres, and S. G. Schirmer, New J. Phys. 14, 073023 (2012).\n", + "5. S. Lioyd and S. Montangero. Phys. Rev. Lett. 113, 010502 (2014)\n", + "6. P. Doria, T. Calarco & S. Montangero. Phys. Rev. Lett. 106, 190501 (2011).\n", + "7. T. Caneva, T. Calarco, & S. Montangero. Phys. Rev. A 84, 022326 (2011).\n", + "8. N. Rach, M. M. Mueller, T. Calarco, and S. Montangero. Phys. Rev. A. 92, 062343 (2015)\n", + "9. S. Machnes, U. Sander, S. J. Glaser, P. De Fouquieres, A. Gruslys, S. Schirmer, and T. Schulte-Herbrueggen, Phys. Rev. A 84, 022305 (2010)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "collapsed": true + }, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.7.3" + } + }, + "nbformat": 4, + "nbformat_minor": 1 +} diff --git a/website/index.html.jinja b/website/index.html.jinja index c44af9ee..3bd5bbaf 100644 --- a/website/index.html.jinja +++ b/website/index.html.jinja @@ -104,17 +104,9 @@ useful to have a look at these IPython notebook

Optimal control

Tomography