From 5743fa5918529cc5bb41d56084a15fc31fa3ba14 Mon Sep 17 00:00:00 2001 From: Josh Izaac Date: Mon, 14 Nov 2022 20:33:23 -0500 Subject: [PATCH 001/122] Development branch --- requirements.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/requirements.txt b/requirements.txt index 31a775730e..d67ec324af 100644 --- a/requirements.txt +++ b/requirements.txt @@ -17,12 +17,12 @@ cirq-core==0.14.1 cirq-pasqal==0.14.1 openfermionpyscf==0.5 # required by 2 tutorials: tutorial_quantum_chemistry and tutorial_adaptive_circuits and tutorial_diffable_shadows pennylane-lightning -pennylane==0.27.0 -pennylane-sf==0.20.1 -pennylane-cirq==0.27.0 -pennylane-qiskit==0.27.0 +git+https://github.com/PennyLaneAI/pennylane.git +git+https://github.com/PennyLaneAI/pennylane-sf.git +git+https://github.com/PennyLaneAI/pennylane-cirq.git +git+https://github.com/PennyLaneAI/pennylane-qiskit.git qulacs==0.1.10.1 -pennylane-qulacs==0.24.0 +git+https://github.com/PennyLaneAI/pennylane-qulacs.git scikit-learn==0.23.2 docutils==0.16 markupsafe==2.0.1 From a8284e3b65c67b02774a8469ad495ec16e66cd98 Mon Sep 17 00:00:00 2001 From: Rashid N H M <95639609+rashidnhm@users.noreply.github.com> Date: Mon, 19 Dec 2022 15:47:32 -0500 Subject: [PATCH 002/122] Bumped requirement package versions (#667) * Bumped jax versions * Updated neural-tangents --- requirements.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/requirements.txt b/requirements.txt index ecdab7aae1..c0cf2b1ec2 100644 --- a/requirements.txt +++ b/requirements.txt @@ -42,9 +42,9 @@ matplotlib==3.5.3 noisyopt==0.2.2 Jinja2==2.11.3 pyyaml==5.4.1 -jax==0.3.15 -jaxlib==0.3.15 -neural-tangents==0.6.0 +jax==0.4.1 +jaxlib==0.4.1 +neural-tangents==0.6.1 flamingpy>=0.10.1b1 plotly>=4.5.0 kahypar==1.1.7 From ccfcf459a29f6b38d520a8f8469aef4acccf8e3b Mon Sep 17 00:00:00 2001 From: Rashid N H M <95639609+rashidnhm@users.noreply.github.com> Date: Wed, 21 Dec 2022 11:54:52 -0500 Subject: [PATCH 003/122] Merge dev in master following v0.28.0 release of PennyLane (#671) (#672) * Development branch * Bumped requirement package versions (#667) * Bumped jax versions * Updated neural-tangents * Apply suggestions from code review Co-authored-by: Josh Izaac Co-authored-by: GitHub Nightly Merge Action Co-authored-by: Rashid N H M <95639609+rashidnhm@users.noreply.github.com> Co-authored-by: Jay Soni Co-authored-by: Josh Izaac Co-authored-by: GitHub Nightly Merge Action From 6583546a545a3564c2900a7d95796143466c6cbf Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 23 Jan 2023 11:25:28 +0100 Subject: [PATCH 004/122] vqe example --- .../pulse_programming101/thumb_temporary.png | Bin 0 -> 9781 bytes .../tutorial_pulse_programming101.py | 219 ++++++++++++++++++ demos_qml.rst | 6 + 3 files changed, 225 insertions(+) create mode 100644 demonstrations/pulse_programming101/thumb_temporary.png create mode 100644 demonstrations/tutorial_pulse_programming101.py diff --git a/demonstrations/pulse_programming101/thumb_temporary.png b/demonstrations/pulse_programming101/thumb_temporary.png new file mode 100644 index 0000000000000000000000000000000000000000..a773cb55b5774faafd21685be6649cc2ce8864a3 GIT binary patch literal 9781 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, 2022. +# +# .. [#Leng2022] +# +# Jiaqi Leng, Yuxiang Peng, Yi-Ling Qiao, Ming Lin, Xiaodi Wu +# Differentiable Analog Quantum Computing for Optimization and Control +# `arXiv:2210.15812 `__, 2022# + +############################################################################## +# About the author +# ---------------- +# .. include:: ../_static/authors/korbinian_kottmann.txt diff --git a/demos_qml.rst b/demos_qml.rst index c2641a8f4b..1f8c71473e 100644 --- a/demos_qml.rst +++ b/demos_qml.rst @@ -140,6 +140,12 @@ IBM, Google, Rigetti, and many more—or on real hardware devices. :description: :doc:`demos/tutorial_geometric_qml` :tags: pytorch geometric qml +.. gallery-item:: + :tooltip: Simulating differentialble pulse programs in PennyLane + :figure: demonstrations/pulse_programming101/thumb_temporary.png + :description: :doc:`demos/tutorial_pulse_programming101` + :tags: jax pulses pulse programming gate quantum optimal control + :html:`
` From e0189e436ee27e7a675b6aeb690178dffb66ca84 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 23 Jan 2023 13:15:04 +0100 Subject: [PATCH 005/122] introduction --- .../tutorial_pulse_programming101.py | 94 +++++++++++++++---- 1 file changed, 77 insertions(+), 17 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index ebcc5c8173..b4c6f18509 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -1,8 +1,8 @@ -r"""Simulating differentialble pulse programs in PennyLane -========================================================== +r"""Differentiable pulse programming with qubits in PennyLane +============================================================= .. meta:: - :property="og:description": Simulating differentialble pulse programs in PennyLane + :property="og:description": Simulating differentialble pulse programs in PennyLane with qubits :property="og:image": https://pennylane.ai/qml/_images/pauli_shadows.jpg *Author: Korbinian Kottmann — Posted: 20 February 2023. @@ -16,28 +16,88 @@ Reference literature, ctrl vqe paper MET [#Asthana2022]_ .. math:: \sum_i c_i k_i -Pulse programming ------------------ -Introduce pulses, channels, pulse gates, time dependent Schrodinger equation +Pulses in quantum computers +--------------------------- +# Introduce pulses, channels, pulse gates, time dependent Schrodinger equation +In non-measurement-based quantum computers such as superconducting and ion trap systems, qubits are realized through physical systems with a discrete set of energy levels. +For example, transmon qubits realize an anharmonic oscillator whose ground and first excited states can serve as the two energy +levels of a qubit. Such a qubit can be controlled via an electromagnetic field tuned to its energy gap. In general, this +electromangnetic field can be altered in time, leading to a time-dependent Hamiltonian interaction :math:`H(t)`. +We call driving the system with such an electromagnetic field for a fixed time window a pulse sequence. During a pulse sequence, the state evolves according +to the time-dependent Schrodinger equation + +.. math:: \frac{d}{dt}|\psi\rangle = -i H(t) |\psi\rangle + +realizing a unitary evolution :math:`U(t_0, t_1)` from times :math:`t_0` to :math:`t_1` of the input state, i.e. +:math:`|\psi(t_1)\rangle = U(t_0, t_1) |\psi(t_0)\rangle`. + +In non-measurement-based digital quantum computers, the amplitude and frequencies of predefined pulse sequences are +fine tuned to realize the native gates of the quantum computer. More specifically, the Hamiltonian interaction :math:`H(t)` +is tuned such that the respective evolution :math:`U(t_0, t_1)` realizes for example a Pauli or CNOT gate. + +Pulse programming in PennyLane +------------------------------ + +A user of a quantum computer typically operates on the higher and more abstract gate level. +Future fault tolerance quantum computers require this abstraction to allow for error correction. +For noisy and intermediate sized quantum computers, the abstraction of decomposing quantum algorithms +into a fixed native gate set can be a hindrance and unnecessarily increase execution time, therefore leading +to more decoherence. The idea of differentiable pulse programming is to optimize quantum circuits on the pulse +level and therefore allowing for the shortest interaction sequence a hardware system allows. + +In PennyLane, we can now simulate arbitrary qubit system interactions to explore the possibilities of such pulse programs. +We can create a time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p, t) H_i` with envelope :math:`f_i(p, t)` that may +depend on parameters :math:`p` and constant operators :math:`H_i` in PennyLane in the following way +""" -Pulse gates in PennyLane ------------------------- -Implementation of the above concepts in PennyLane +import pennylane as qml +import jax.numpy as jnp -Gradients of pulse gates ------------------------- -Can compute them on hardware with parameter shift rule [#Leng2022]_ +def f1(p, t): + return jnp.polyval(p, t) +def f2(p, t): + return p[0] * jnp.sin(p[1] * t) +Ht = f1 * qml.PauliX(0) + f2 * qml.PauliY(1) -""" +############################################################################## +# Note that when constructing such a Hamiltonian, the ``callable`` functions are +# expected to have the fixed signature ``(p, t)``, such that the Hamiltonian itself +# can be called via ``H((p1, p2), t)``. -import pennylane as qml -import pennylane.numpy as np -from matplotlib import pyplot as plt +p = (jnp.ones(5), jnp.array([1., jnp.pi])) +print(Ht(p, 0.5)) + +############################################################################## +# We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using ``qml.ops.dot`` +# in the following way. +coeffs = [1.] * 2 +coeffs += [lambda p, t: jnp.polyval(p, t) for _ in range(3)] +ops = [qml.PauliX(i) @ qml.PauliX(i+1) for i in range(2)] +ops += [qml.PauliZ(i) for i in range(3)] + +Ht = qml.ops.dot(coeffs, ops) +p = tuple(jnp.ones(3) for _ in range(3)) +print(Ht(p, 0.5)) + +############################################################################## +# PennyLane also provides a variety of convenience functions to enable for example piece-wise-constant parametrizations, +# i.e. defining the function values at fixed time bins as parameters. + +# PWC example ############################################################################## -# More text +# Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. +# For an example of a transmon qubit system, scroll down to the ctrl-VQE example. + + +############################################################################## +# More text +# Gradients of pulse gates +# ------------------------ +# Can compute them on hardware with parameter shift rule [#Leng2022]_# + import pennylane as qml From 44692bc92fa84f04a878cb857c9310dc7aaf5100 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 23 Jan 2023 16:28:14 +0100 Subject: [PATCH 006/122] main body first draft with some gaps --- .../tutorial_pulse_programming101.py | 198 ++++++++++++------ 1 file changed, 133 insertions(+), 65 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index b4c6f18509..9feb9576df 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -10,15 +10,9 @@ In this demo we are going to introduce pulse gates and differentiable pulse programming, showcase the current functionality in PennyLane and run the ctrl-VQE algorithm for an example molecule. -Topic1 ------- -Reference docs :doc:`tutorial_classical_shadows` -Reference literature, ctrl vqe paper MET [#Asthana2022]_ -.. math:: \sum_i c_i k_i - Pulses in quantum computers --------------------------- -# Introduce pulses, channels, pulse gates, time dependent Schrodinger equation + In non-measurement-based quantum computers such as superconducting and ion trap systems, qubits are realized through physical systems with a discrete set of energy levels. For example, transmon qubits realize an anharmonic oscillator whose ground and first excited states can serve as the two energy levels of a qubit. Such a qubit can be controlled via an electromagnetic field tuned to its energy gap. In general, this @@ -43,15 +37,18 @@ For noisy and intermediate sized quantum computers, the abstraction of decomposing quantum algorithms into a fixed native gate set can be a hindrance and unnecessarily increase execution time, therefore leading to more decoherence. The idea of differentiable pulse programming is to optimize quantum circuits on the pulse -level and therefore allowing for the shortest interaction sequence a hardware system allows. +level with the aim of achieving the shortest interaction sequence a hardware system allows. In PennyLane, we can now simulate arbitrary qubit system interactions to explore the possibilities of such pulse programs. -We can create a time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p, t) H_i` with envelope :math:`f_i(p, t)` that may -depend on parameters :math:`p` and constant operators :math:`H_i` in PennyLane in the following way +First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p, t) H_i` with envelope :math:`f_i(p, t)` that may +depend on parameters :math:`p` and constant operators :math:`H_i`. In PennyLane, we can do this intuitively in the following way. """ import pennylane as qml +import pennylane.numpy as np import jax.numpy as jnp +import jax +import matplotlib.pyplot as plt def f1(p, t): return jnp.polyval(p, t) @@ -65,21 +62,43 @@ def f2(p, t): # expected to have the fixed signature ``(p, t)``, such that the Hamiltonian itself # can be called via ``H((p1, p2), t)``. -p = (jnp.ones(5), jnp.array([1., jnp.pi])) -print(Ht(p, 0.5)) +params = (jnp.ones(5), jnp.array([1., jnp.pi])) +print(Ht(params, 0.5)) ############################################################################## -# We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using ``qml.ops.dot`` -# in the following way. +# We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using :func:`~pennylane.ops.dot`. +# We use two sinusodials with random frequencies as the time-dependent parametrization. -coeffs = [1.] * 2 -coeffs += [lambda p, t: jnp.polyval(p, t) for _ in range(3)] +coeffs = [jnp.array(1.)] * 2 +coeffs += [lambda p, t: jnp.sin(p[0]*t) + jnp.sin(p[1]*t) for _ in range(3)] ops = [qml.PauliX(i) @ qml.PauliX(i+1) for i in range(2)] ops += [qml.PauliZ(i) for i in range(3)] Ht = qml.ops.dot(coeffs, ops) -p = tuple(jnp.ones(3) for _ in range(3)) -print(Ht(p, 0.5)) + +# random coefficients +key = jax.random.PRNGKey(777) +subkeys = jax.random.split(key, 3) +params = [jax.random.uniform(subkeys[i], shape=[2], maxval=5) for i in range(3)] +print(Ht(params, 0.5)) + +############################################################################## +# We can visualize the Hamiltonian interaction by plotting the time-dependent envelopes. + +def draw(H, params, t, resolution=200): + ts = jnp.linspace(0, t, resolution) + fs = H.coeffs_parametrized + ops = H.ops_parametrized + n_channels = len(fs) + fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels)) + for n in range(n_channels): + ax = axs[n] + ax.plot(ts, fs[n](params[n], ts)) + ax.set_ylabel(f"{ops[n].__repr__()}") + axs[0].set_title(f"Drift term: {H.H_fixed()}") + plt.show() + +draw(Ht, params, 4.) ############################################################################## # PennyLane also provides a variety of convenience functions to enable for example piece-wise-constant parametrizations, @@ -89,26 +108,46 @@ def f2(p, t): ############################################################################## # Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. -# For an example of a transmon qubit system, scroll down to the ctrl-VQE example. +# For example, we will later simulate a transmon qubit system in the ctrl-VQE example in the last section of this demo. +# +# A pulse program is then executed by using the :func:`~pennylane.ops.evolve` transform to create the evolution +# gate :math:`U(t_0, t_1)`, which implicitly depends on the parameters ``p``. +dev = qml.device("default.qubit", range(4)) -############################################################################## -# More text -# Gradients of pulse gates -# ------------------------ -# Can compute them on hardware with parameter shift rule [#Leng2022]_# +ts = jnp.array([0., 3.]) +H_obj = sum([qml.PauliZ(i) for i in range(4)]) +@jax.jit +@qml.qnode(dev, interface="jax") +def qnode(params): + qml.evolve(Ht)(params, ts) + return qml.expval(H_obj) +print(qnode(params)) -import pennylane as qml -import pennylane.numpy as np -import jax.numpy as jnp -import jax +############################################################################## +# We used the decorator ``jax.jit`` to just-in-time compile this executions. This means the first execution will typically take a little longer with the +# benefit that all following executions will be significantly faster. JIT-compiling is optional, and one can remove the decorator when only single executions +# are of interest. +# +# Gradients of pulse programs +# --------------------------- +# Internally, this program solves the the time-dependent Schrodinger equation using the `Dopri5 `_ solver for +# ordinary differential equations (ODEs). In particular, the step sizes between :math:`t_0` and :math:`t_1` are chosen adaptively to stay within a given error tolerance. +# We can backpropagate through this ODE solver and obtain the gradient via ``jax.grad``. -import optax # for jax optimization +print(jax.grad(qnode)(params)) + +############################################################################## +# Alternatively, one can compute the gradient with the parameter shift rule [#Leng2022]_, which is particularly interesting for +# real hardware execution. In classical simulations, however, backpropagation is recommended. +# +# Variational quantum eigensolver with pulse programming +# ------------------------------------------------------ +# We can now use those gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Asthana2022]_. +# First, we define the molecular Hamiltonian whose energy estimate we want to minimize. We are choosing :math:`H_2` as a simple example. -import matplotlib.pyplot as plt -from datetime import datetime symbols = ["H", "H"] coordinates = np.array([[0., 0., 0.],[0., 0., 1.5]]) @@ -124,19 +163,23 @@ def f2(p, t): method="pyscf", ) -print(f"no qubits: {n_wires}") +print(f"number of qubits: {n_wires}") coeffs, obs = jnp.array(H.coeffs), H.ops -H_obj = qml.Hamiltonian(coeffs, obs, grouping_type="qwc") + +############################################################################## +# For such small systems, we can of course compute the exact ground state energy. +# We will later use this to determine if our ctrl-VQE algorithm was successful. +H_obj = qml.Hamiltonian(coeffs, obs) H_obj_m = qml.matrix(H_obj) E_exact = np.min(np.linalg.eigvalsh(H_obj_m)) ############################################################################## -# We are considering a coupled transmon qubit system with the constant drift term Hamiltonian +# As a realistic physical system to simulate, we are considering a coupled transmon qubit system with the constant drift term Hamiltonian # # .. math:: H_D = \sum_q \omega_q a_q^\dagger a_q + \sum_q \frac{\delta_q}{2} a^\dagger_q a^\dagger_q a_q a_q + \sum_{\braket{pq}} g_{pq} a^\dagger_p a_q # -# with bosonic creation and annihilation operators. We are only going to consider qubit subspace such that the quadratic term is zero. -# The order of magnitude of the resonance frequencies $\omega_q$ and coupling strength $g_{pq}$ are taken from [#Asthana2022]_. +# with bosonic creation and annihilation operators. We are only going to consider the qubit subspace such that the quadratic term proportional to :math:`\delta_q` is zero. +# The order of magnitude of the resonance frequencies :math:`\omega_q` and coupling strength :math:`g_{pq}` are taken from [#Asthana2022]_. def a(wires): return 0.5*qml.PauliX(wires) + 0.5j* qml.PauliY(wires) @@ -155,6 +198,7 @@ def ad(wires): # .. math:: H_C(t) = \sum_q \Omega_q(t) \left(e^{i\nu_q t} a_q + e^{-i\nu_q t} a^\dagger_q \right) # # with the (real) time-dependent amplitude :math:`\Omega(t)` and frequency :math:`\nu_q` of the drive. +# We let :math:`\Omega(t)` be a piece-wise-constant real function that is optimized alongside the frequencies :math:`\nu_q`. # TODO use official convenience functions once merged def pwc(t1, t2): @@ -165,27 +209,28 @@ def wrapped(params, t): return wrapped -def f(t1, t2, sgn=1.): +def envelope(t1, t2, sign=1.): # assuming p = (len(t_bins) + 1) for the frequency nu def wrapped(p, t): - return pwc(t1, t2)(p[:-1], t) * jnp.exp(sgn*1j*p[-1]*t) + return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) return wrapped t1 = 0. t2 = 15. -fs = [f(t1, t2, 1.) for i in range(n_wires)] -fs += [f(t1, t2, -1.) for i in range(n_wires)] +fs = [envelope(t1, t2, 1.) for i in range(n_wires)] +fs += [envelope(t1, t2, -1.) for i in range(n_wires)] ops = [a(i) for i in range(n_wires)] ops += [ad(i) for i in range(n_wires)] -# ops = [qml.PauliX(i) for i in range(n_wires)] -# ops += [qml.PauliY(i) for i in range(n_wires)] H_C = qml.ops.dot(fs, ops) +############################################################################## +# Overall, we end up with the time-dependent parametrized Hamiltonian :math:`H(p, t) = H_D + H_C(p, t)` +# under which the system is evolved for the given time window. + H_pulse = H_D + H_C -t_bins = 200 # number of time bins -p = jnp.array([jnp.ones(t_bins + 1) for _ in range(n_wires)]) + dev = qml.device("default.qubit", wires=range(n_wires)) @jax.jit @@ -194,21 +239,36 @@ def qnode(p, t=15.): qml.evolve(H_pulse)(params=(*p, *p), t=t) return qml.expval(H_obj) +############################################################################## +# Our aim is to minimize the energy expectation value :math:`\langle H_\text{obj} \rangle` but we also need to take +# certain physical constraints into account. For example, the amplitude of the physical driving field :math:`\Omega(t)` cannot +# reach arbitrarily large values and cannot change arbitrarily quickly in time. We therefore add two penalty terms quantifying the +# mean absolute square of the amplitude and changes in the amplitude. The overall cost function is thus +# +# .. math:: \mathcal{C}(p) = \langle H_\text{obj} \rangle + \sum_{ki} |p^k_i|^2 + \sum_{ki} |p^k_i - p^k_{i-1}|^2. +# def abs_diff(p): """compute |p_i - p_i-1|^2""" - #p = jnp.array(p) - return jnp.mean(jnp.abs(jnp.diff(p, axis=1))**2) + return jnp.mean(jnp.abs(jnp.diff(p[:, :-1], axis=1))**2) + def cost_fn(p): - C_exp = qnode(p) - C_par = jnp.mean(jnp.abs(p)**2) - C_der = abs_diff(p) - return C_exp + C_par + C_der -theta = jnp.array([jnp.ones(t_bins) for _ in range(n_wires)]) + C_exp = qnode(p) # expectation value + C_par = jnp.mean(jnp.abs(p)**2) # parameter values + C_der = abs_diff(p) # derivative values + return C_exp + 10*C_par + 10*C_der + + +############################################################################## +# We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax`` for optimizations in ``jax`` for our optimization loop. +import optax +from datetime import datetime + +t_bins = 200 # number of time bins +theta = jnp.array([jnp.ones(t_bins, dtype=float) for _ in range(n_wires)]) n_epochs = 50 -cosine_decay_scheduler = optax.cosine_decay_schedule(0.5, decay_steps=n_epochs, alpha=0.95) -optimizer = optax.adam(learning_rate=0.1) # cosine_decay_scheduler +optimizer = optax.adam(learning_rate=0.1) opt_state = optimizer.init(theta) value_and_grad = jax.jit(jax.value_and_grad(cost_fn, argnums=0)) @@ -219,10 +279,10 @@ def cost_fn(p): ## Optimization loop -t0 = datetime.now() +time0 = datetime.now() _ = value_and_grad(theta) -t1 = datetime.now() -print(f"grad and val compilation time: {t1 - t0}") +time1 = datetime.now() +print(f"grad and val compilation time: {time1 - time0}") for n in range(n_epochs): val, grad_circuit = value_and_grad(theta) @@ -236,21 +296,29 @@ def cost_fn(p): if not n%5: print(f"{n+1} / {n_epochs}; energy: {energy[n]}; cost: {val}") -# TODO: how can the energy be smaller than the exact diagonalization one -fig, axs = plt.subplots(ncols=2, figsize=(10,4)) +############################################################################## +# We see that the energy converges relatively quickly to the desired exact result. + +fig, axs = plt.subplots(nrows=2, figsize=(5,5), sharex=True) ax = axs[0] -ax.plot(cost,".:", label="cost") -ax.plot(energy, "x:", label="energy") -#ax.plot(cost - energy, "x:", label="control contribution") +ax.plot(energy, ".:", label="energy") ax.plot([0, n_epochs], [E_exact]*2, "--", label="exact", color="grey") -ax.legend() +ax.set_ylabel("Energy") ax = axs[1] -for i in range(n_wires): - ax.plot(theta[i],"-", label=f"qubit {i}", alpha=0.5) -ax.legend() +ax.plot(cost,".:", label="cost") +ax.plot([0, n_epochs], [E_exact]*2, "--", label="exact", color="grey") +ax.set_xlabel("epoch") +ax.set_ylabel("Cost") + plt.show() +############################################################################## +# We can also visualize the paths for the envelopes for each qubit take in time. + +# this plot doesnt make sense atm due to complex valued envelopes +draw(H_pulse, theta, 15.) + ############################################################################## # # Conclusion From 1681bd65f766290302bac39ad3fd8eca91ab829e Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 23 Jan 2023 17:40:42 +0100 Subject: [PATCH 007/122] from qml to quantum computing --- demonstrations/tutorial_pulse_programming101.py | 1 - demos_qml.rst | 7 ------- demos_quantum-computing.rst | 7 +++++++ 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 9feb9576df..33be9530c3 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -307,7 +307,6 @@ def cost_fn(p): ax = axs[1] ax.plot(cost,".:", label="cost") -ax.plot([0, n_epochs], [E_exact]*2, "--", label="exact", color="grey") ax.set_xlabel("epoch") ax.set_ylabel("Cost") diff --git a/demos_qml.rst b/demos_qml.rst index 1f8c71473e..e09a191058 100644 --- a/demos_qml.rst +++ b/demos_qml.rst @@ -140,13 +140,6 @@ IBM, Google, Rigetti, and many more—or on real hardware devices. :description: :doc:`demos/tutorial_geometric_qml` :tags: pytorch geometric qml -.. gallery-item:: - :tooltip: Simulating differentialble pulse programs in PennyLane - :figure: demonstrations/pulse_programming101/thumb_temporary.png - :description: :doc:`demos/tutorial_pulse_programming101` - :tags: jax pulses pulse programming gate quantum optimal control - - :html:`
` diff --git a/demos_quantum-computing.rst b/demos_quantum-computing.rst index 55f9398c15..24694e7901 100644 --- a/demos_quantum-computing.rst +++ b/demos_quantum-computing.rst @@ -107,6 +107,13 @@ such as benchmarking and characterizing quantum processors. :figure: demonstrations/mbqc/thumbnail_mbqc.png :description: :doc:`demos/tutorial_mbqc` :tags: quantumcomputing MBQC + +.. gallery-item:: + :tooltip: Simulating differentialble pulse programs in PennyLane + :figure: demonstrations/pulse_programming101/thumb_temporary.png + :description: :doc:`demos/tutorial_pulse_programming101` + :tags: jax pulses pulse programming gate quantum optimal control + :html:`
` From a5deb7199f5ddc7a12456af4df27bebb8d2975a3 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Tue, 24 Jan 2023 10:49:13 +0100 Subject: [PATCH 008/122] small updates --- demonstrations/tutorial_pulse_programming101.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 33be9530c3..e506db4555 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -127,7 +127,7 @@ def qnode(params): print(qnode(params)) ############################################################################## -# We used the decorator ``jax.jit`` to just-in-time compile this executions. This means the first execution will typically take a little longer with the +# We used the decorator ``jax.jit`` to just-in-time compile this execution. This means the first execution will typically take a little longer with the # benefit that all following executions will be significantly faster. JIT-compiling is optional, and one can remove the decorator when only single executions # are of interest. # @@ -149,8 +149,8 @@ def qnode(params): # First, we define the molecular Hamiltonian whose energy estimate we want to minimize. We are choosing :math:`H_2` as a simple example. -symbols = ["H", "H"] -coordinates = np.array([[0., 0., 0.],[0., 0., 1.5]]) +symbols = ["H", "O", "H"] +coordinates = np.array([-0.0399, -0.0038, 0.0, 1.5780, 0.8540, 0.0, 2.7909, -0.5159, 0.0]) basis_set = "sto-3g" H, n_wires = qml.qchem.molecular_hamiltonian( @@ -159,17 +159,18 @@ def qnode(params): charge=0, mult=1, basis=basis_set, - mapping="bravyi_kitaev", - method="pyscf", + active_electrons=4, + active_orbitals=3, ) print(f"number of qubits: {n_wires}") -coeffs, obs = jnp.array(H.coeffs), H.ops +coeffs, obs = H.coeffs, H.ops +H_obj = qml.Hamiltonian(jnp.array(coeffs), obs) ############################################################################## # For such small systems, we can of course compute the exact ground state energy. # We will later use this to determine if our ctrl-VQE algorithm was successful. -H_obj = qml.Hamiltonian(coeffs, obs) + H_obj_m = qml.matrix(H_obj) E_exact = np.min(np.linalg.eigvalsh(H_obj_m)) From 0bd5f4541abe8dc670bab1333161478e686c4efb Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Tue, 24 Jan 2023 13:09:06 +0100 Subject: [PATCH 009/122] update hyper parameters and example --- .../tutorial_pulse_programming101.py | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index e506db4555..394a0743cd 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -146,26 +146,13 @@ def qnode(params): # Variational quantum eigensolver with pulse programming # ------------------------------------------------------ # We can now use those gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Asthana2022]_. -# First, we define the molecular Hamiltonian whose energy estimate we want to minimize. We are choosing :math:`H_2` as a simple example. - - -symbols = ["H", "O", "H"] -coordinates = np.array([-0.0399, -0.0038, 0.0, 1.5780, 0.8540, 0.0, 2.7909, -0.5159, 0.0]) - -basis_set = "sto-3g" -H, n_wires = qml.qchem.molecular_hamiltonian( - symbols, - coordinates, - charge=0, - mult=1, - basis=basis_set, - active_electrons=4, - active_orbitals=3, -) +# First, we define the molecular Hamiltonian whose energy estimate we want to minimize. +# We are going to look at the :math:`H_3^+` as a simple example and load it from the `quantum datasets `_ website. +# -print(f"number of qubits: {n_wires}") -coeffs, obs = H.coeffs, H.ops -H_obj = qml.Hamiltonian(jnp.array(coeffs), obs) +data = qml.data.load("qchem", molname="H3+", basis="STO-3G", bondlength=1.5)[0] +H_obj = data.hamiltonian +n_wires = len(H_obj.wires) ############################################################################## # For such small systems, we can of course compute the exact ground state energy. @@ -216,11 +203,10 @@ def wrapped(p, t): return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) return wrapped -t1 = 0. -t2 = 15. +duration = 15. -fs = [envelope(t1, t2, 1.) for i in range(n_wires)] -fs += [envelope(t1, t2, -1.) for i in range(n_wires)] +fs = [envelope(0., duration, 1.) for i in range(n_wires)] +fs += [envelope(0., duration, -1.) for i in range(n_wires)] ops = [a(i) for i in range(n_wires)] ops += [ad(i) for i in range(n_wires)] @@ -236,7 +222,7 @@ def wrapped(p, t): @jax.jit @qml.qnode(dev, interface="jax") -def qnode(p, t=15.): +def qnode(p, t=duration): qml.evolve(H_pulse)(params=(*p, *p), t=t) return qml.expval(H_obj) @@ -253,8 +239,10 @@ def abs_diff(p): """compute |p_i - p_i-1|^2""" return jnp.mean(jnp.abs(jnp.diff(p[:, :-1], axis=1))**2) -def cost_fn(p): - C_exp = qnode(p) # expectation value +def cost_fn(params): + # params.shape = (n_wires, {n_bins}+1) + p = params[:, :-1] + C_exp = qnode(params) # expectation value C_par = jnp.mean(jnp.abs(p)**2) # parameter values C_der = abs_diff(p) # derivative values return C_exp + 10*C_par + 10*C_der @@ -265,8 +253,8 @@ def cost_fn(p): import optax from datetime import datetime -t_bins = 200 # number of time bins -theta = jnp.array([jnp.ones(t_bins, dtype=float) for _ in range(n_wires)]) +t_bins = 30 # number of time bins +theta = jnp.array([jnp.ones(t_bins + 1, dtype=float) for _ in range(n_wires)]) n_epochs = 50 optimizer = optax.adam(learning_rate=0.1) @@ -314,10 +302,22 @@ def cost_fn(p): plt.show() ############################################################################## -# We can also visualize the paths for the envelopes for each qubit take in time. +# We can also visualize the envelopes for each qubit in time. +# Because the field is complex valued with :math:`\Omega(t) e^{-i\nu_q t}` we plot only +# :math:`\Omega(t)` and indicate the numerical value of :math:`nu_q`. -# this plot doesnt make sense atm due to complex valued envelopes -draw(H_pulse, theta, 15.) + +ts = jnp.linspace(0, duration, t_bins) +fs = H_pulse.coeffs_parametrized[:n_wires] +n_channels = len(fs) +fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels)) +for n in range(n_channels): + ax = axs[n] + ax.plot(ts, jnp.abs(fs[n](params[n], ts)), label=f"$\\nu$_{n}: {jnp.angle(fs[n](params[n], 1.))/jnp.pi:.3}/$\\pi$") + ax.set_ylabel(f"amplitude_{n}") + ax.legend() + +plt.show() ############################################################################## # From bba18a5f6effd6d42e038d4df9efcc4dd890df33 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Tue, 24 Jan 2023 13:19:25 +0100 Subject: [PATCH 010/122] bug fix --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 394a0743cd..6db80570e7 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -313,7 +313,7 @@ def cost_fn(params): fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels)) for n in range(n_channels): ax = axs[n] - ax.plot(ts, jnp.abs(fs[n](params[n], ts)), label=f"$\\nu$_{n}: {jnp.angle(fs[n](params[n], 1.))/jnp.pi:.3}/$\\pi$") + ax.plot(ts, jnp.abs(fs[n](theta[n], ts)), label=f"$\\nu$_{n}: {jnp.angle(fs[n](theta[n], 1.))/jnp.pi:.3}/$\\pi$") ax.set_ylabel(f"amplitude_{n}") ax.legend() From 343c890c118bcbe24848e9683c5987368c2a336d Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Tue, 24 Jan 2023 14:10:23 +0100 Subject: [PATCH 011/122] update zstd dill in requirements --- demonstrations/tutorial_pulse_programming101.py | 1 - requirements.txt | 2 ++ 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 6db80570e7..1f081a45f1 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -220,7 +220,6 @@ def wrapped(p, t): dev = qml.device("default.qubit", wires=range(n_wires)) -@jax.jit @qml.qnode(dev, interface="jax") def qnode(p, t=duration): qml.evolve(H_pulse)(params=(*p, *p), t=t) diff --git a/requirements.txt b/requirements.txt index c0cf2b1ec2..1d1ad20f39 100644 --- a/requirements.txt +++ b/requirements.txt @@ -51,3 +51,5 @@ kahypar==1.1.7 optax==0.1.3 pennylane-sphinx-theme # Not pinned so that it always uses the latest theme jaxopt==0.5.5 +zstd +dill From 3ed8708b179a90e00b488aa7979f66b518ec0a8b Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Tue, 24 Jan 2023 14:45:12 +0100 Subject: [PATCH 012/122] HF state --- demonstrations/tutorial_pulse_programming101.py | 1 + 1 file changed, 1 insertion(+) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 1f081a45f1..edc3c52f2b 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -222,6 +222,7 @@ def wrapped(p, t): @qml.qnode(dev, interface="jax") def qnode(p, t=duration): + qml.QubitStateVector(data.hf_state, wires=H_obj.wires) qml.evolve(H_pulse)(params=(*p, *p), t=t) return qml.expval(H_obj) From c49c63561299babcc2a50ab302568de6f9e07c40 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Tue, 24 Jan 2023 14:46:14 +0100 Subject: [PATCH 013/122] compare to right energy --- demonstrations/tutorial_pulse_programming101.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index edc3c52f2b..12dc0c4ef4 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -291,7 +291,8 @@ def cost_fn(params): fig, axs = plt.subplots(nrows=2, figsize=(5,5), sharex=True) ax = axs[0] ax.plot(energy, ".:", label="energy") -ax.plot([0, n_epochs], [E_exact]*2, "--", label="exact", color="grey") +ax.plot([0, n_epochs], [data.fci_energy]*2, "--", label="FCI", color="grey") +ax.plot([0, n_epochs], [E_exact]*2, ":", label="exact diag", color="grey") ax.set_ylabel("Energy") ax = axs[1] From 7e93caf330b7723eac37eefdd9e1bc9dea64fdf7 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Tue, 24 Jan 2023 15:29:09 +0100 Subject: [PATCH 014/122] basis state instead of QubitStateVector --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 12dc0c4ef4..74645e2e3e 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -222,7 +222,7 @@ def wrapped(p, t): @qml.qnode(dev, interface="jax") def qnode(p, t=duration): - qml.QubitStateVector(data.hf_state, wires=H_obj.wires) + qml.BasisState(data.hf_state, wires=H_obj.wires) qml.evolve(H_pulse)(params=(*p, *p), t=t) return qml.expval(H_obj) From 8f0854e26479b6338cafda08d56768309872a0c9 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Tue, 24 Jan 2023 18:17:03 +0100 Subject: [PATCH 015/122] update hamiltonian and do 100 epochs --- .../tutorial_pulse_programming101.py | 26 ++++++++++++++----- 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 74645e2e3e..b977a0c0ed 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -150,9 +150,24 @@ def qnode(params): # We are going to look at the :math:`H_3^+` as a simple example and load it from the `quantum datasets `_ website. # -data = qml.data.load("qchem", molname="H3+", basis="STO-3G", bondlength=1.5)[0] -H_obj = data.hamiltonian -n_wires = len(H_obj.wires) +# data = qml.data.load("qchem", molname="H3+", basis="STO-3G", bondlength=1.5)[0] +# H_obj = data.hamiltonian +# n_wires = len(H_obj.wires) + +symbols = ["H", "H", "H"] +coordinates = np.array([-0.0399, -0.0038, 0.0, 1.5780, 0.8540, 0.0, 2.7909, -0.5159, 0.0]) + +basis_set = "sto-3g" +H, n_wires = qml.qchem.molecular_hamiltonian( + symbols, + coordinates, + basis=basis_set, + method='pyscf', + mult=2 +) + +coeffs, obs = H.coeffs, H.ops +H_obj = qml.Hamiltonian(jnp.array(coeffs), obs) ############################################################################## # For such small systems, we can of course compute the exact ground state energy. @@ -222,7 +237,7 @@ def wrapped(p, t): @qml.qnode(dev, interface="jax") def qnode(p, t=duration): - qml.BasisState(data.hf_state, wires=H_obj.wires) + qml.BasisState(np.array([1, 1, 1, 0, 0, 0]), wires=H_obj.wires) qml.evolve(H_pulse)(params=(*p, *p), t=t) return qml.expval(H_obj) @@ -256,7 +271,7 @@ def cost_fn(params): t_bins = 30 # number of time bins theta = jnp.array([jnp.ones(t_bins + 1, dtype=float) for _ in range(n_wires)]) -n_epochs = 50 +n_epochs = 100 optimizer = optax.adam(learning_rate=0.1) opt_state = optimizer.init(theta) @@ -291,7 +306,6 @@ def cost_fn(params): fig, axs = plt.subplots(nrows=2, figsize=(5,5), sharex=True) ax = axs[0] ax.plot(energy, ".:", label="energy") -ax.plot([0, n_epochs], [data.fci_energy]*2, "--", label="FCI", color="grey") ax.plot([0, n_epochs], [E_exact]*2, ":", label="exact diag", color="grey") ax.set_ylabel("Energy") From 9ffecf09b976a44c5f60aa06946d618de4da76c2 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 25 Jan 2023 11:59:33 +0100 Subject: [PATCH 016/122] back to H2, resulting energy below exact energy --- .../tutorial_pulse_programming101.py | 41 ++++++++++--------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index b977a0c0ed..21248c4e66 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -150,24 +150,24 @@ def qnode(params): # We are going to look at the :math:`H_3^+` as a simple example and load it from the `quantum datasets `_ website. # -# data = qml.data.load("qchem", molname="H3+", basis="STO-3G", bondlength=1.5)[0] -# H_obj = data.hamiltonian -# n_wires = len(H_obj.wires) +# symbols = ["H", "H", "H"] +# coordinates = np.array([-0.0399, -0.0038, 0.0, 1.5780, 0.8540, 0.0, 2.7909, -0.5159, 0.0]) -symbols = ["H", "H", "H"] -coordinates = np.array([-0.0399, -0.0038, 0.0, 1.5780, 0.8540, 0.0, 2.7909, -0.5159, 0.0]) +# basis_set = "sto-3g" +# H, n_wires = qml.qchem.molecular_hamiltonian( +# symbols, +# coordinates, +# basis=basis_set, +# method='pyscf', +# mult=2 +# ) -basis_set = "sto-3g" -H, n_wires = qml.qchem.molecular_hamiltonian( - symbols, - coordinates, - basis=basis_set, - method='pyscf', - mult=2 -) +# coeffs, obs = H.coeffs, H.ops +# H_obj = qml.Hamiltonian(jnp.array(coeffs), obs) -coeffs, obs = H.coeffs, H.ops -H_obj = qml.Hamiltonian(jnp.array(coeffs), obs) +data = qml.data.load("qchem", molname="H2", basis="STO-3G", bondlength=1.9)[0] +H_obj = data.hamiltonian +n_wires = len(H_obj.wires) ############################################################################## # For such small systems, we can of course compute the exact ground state energy. @@ -218,7 +218,7 @@ def wrapped(p, t): return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) return wrapped -duration = 15. +duration = 20. fs = [envelope(0., duration, 1.) for i in range(n_wires)] fs += [envelope(0., duration, -1.) for i in range(n_wires)] @@ -235,9 +235,10 @@ def wrapped(p, t): dev = qml.device("default.qubit", wires=range(n_wires)) +@jax.jit @qml.qnode(dev, interface="jax") def qnode(p, t=duration): - qml.BasisState(np.array([1, 1, 1, 0, 0, 0]), wires=H_obj.wires) + qml.BasisState(np.array([1, 1, 0, 0]), wires=H_obj.wires) qml.evolve(H_pulse)(params=(*p, *p), t=t) return qml.expval(H_obj) @@ -260,7 +261,7 @@ def cost_fn(params): C_exp = qnode(params) # expectation value C_par = jnp.mean(jnp.abs(p)**2) # parameter values C_der = abs_diff(p) # derivative values - return C_exp + 10*C_par + 10*C_der + return C_exp + C_par + C_der ############################################################################## @@ -268,7 +269,7 @@ def cost_fn(params): import optax from datetime import datetime -t_bins = 30 # number of time bins +t_bins = 40 # number of time bins theta = jnp.array([jnp.ones(t_bins + 1, dtype=float) for _ in range(n_wires)]) n_epochs = 100 @@ -314,6 +315,7 @@ def cost_fn(params): ax.set_xlabel("epoch") ax.set_ylabel("Cost") +plt.tight_layout() plt.show() ############################################################################## @@ -332,6 +334,7 @@ def cost_fn(params): ax.set_ylabel(f"amplitude_{n}") ax.legend() +plt.tight_layout() plt.show() ############################################################################## From 18e6bfd905dc9fd9941d49eb1e9b6c5b91375639 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 25 Jan 2023 12:10:18 +0100 Subject: [PATCH 017/122] back to H2, resulting energy below exact energy --- demonstrations/tutorial_pulse_programming101.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 21248c4e66..326832e0c3 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -189,8 +189,8 @@ def a(wires): def ad(wires): return 0.5*qml.PauliX(wires) - 0.5j* qml.PauliY(wires) -omega = 4.8 * jnp.ones(n_wires) -g = 0.01 * jnp.ones(n_wires-1) +omega = 2 * jnp.pi * jnp.array([4.8080, 4.8333, 4.9400, 4.7960]) +g = 2 * jnp.pi * jnp.array([0.01831, 0.02131, 0.01931, 0.02031]) H_D = qml.op_sum(*[qml.s_prod(omega[i], ad(i) @ a(i)) for i in range(n_wires)]) H_D += qml.op_sum(*[qml.s_prod(g[i], ad(i) @ a(i+1)) for i in range(n_wires-1)]) @@ -215,7 +215,7 @@ def wrapped(params, t): def envelope(t1, t2, sign=1.): # assuming p = (len(t_bins) + 1) for the frequency nu def wrapped(p, t): - return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) + return jnp.clip(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t), -0.02, 0.02) return wrapped duration = 20. @@ -261,7 +261,7 @@ def cost_fn(params): C_exp = qnode(params) # expectation value C_par = jnp.mean(jnp.abs(p)**2) # parameter values C_der = abs_diff(p) # derivative values - return C_exp + C_par + C_der + return C_exp + 3*C_par + 3*C_der ############################################################################## @@ -309,6 +309,7 @@ def cost_fn(params): ax.plot(energy, ".:", label="energy") ax.plot([0, n_epochs], [E_exact]*2, ":", label="exact diag", color="grey") ax.set_ylabel("Energy") +ax.legend() ax = axs[1] ax.plot(cost,".:", label="cost") @@ -321,7 +322,7 @@ def cost_fn(params): ############################################################################## # We can also visualize the envelopes for each qubit in time. # Because the field is complex valued with :math:`\Omega(t) e^{-i\nu_q t}` we plot only -# :math:`\Omega(t)` and indicate the numerical value of :math:`nu_q`. +# :math:`\Omega(t)` and indicate the numerical value of :math:`\nu_q`. ts = jnp.linspace(0, duration, t_bins) @@ -330,7 +331,7 @@ def cost_fn(params): fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels)) for n in range(n_channels): ax = axs[n] - ax.plot(ts, jnp.abs(fs[n](theta[n], ts)), label=f"$\\nu$_{n}: {jnp.angle(fs[n](theta[n], 1.))/jnp.pi:.3}/$\\pi$") + ax.plot(ts, jnp.abs(fs[n](theta[n], ts)), ".:", label=f"$\\nu$_{n}: {jnp.angle(fs[n](theta[n], 1.))/jnp.pi:.3}/$\\pi$") ax.set_ylabel(f"amplitude_{n}") ax.legend() From b411eeb4edf29af6aa973031d8b5dd620a48a128 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 25 Jan 2023 12:22:57 +0100 Subject: [PATCH 018/122] no restriction to 20MHz --- demonstrations/tutorial_pulse_programming101.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 326832e0c3..433bcc5815 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -182,7 +182,7 @@ def qnode(params): # .. math:: H_D = \sum_q \omega_q a_q^\dagger a_q + \sum_q \frac{\delta_q}{2} a^\dagger_q a^\dagger_q a_q a_q + \sum_{\braket{pq}} g_{pq} a^\dagger_p a_q # # with bosonic creation and annihilation operators. We are only going to consider the qubit subspace such that the quadratic term proportional to :math:`\delta_q` is zero. -# The order of magnitude of the resonance frequencies :math:`\omega_q` and coupling strength :math:`g_{pq}` are taken from [#Asthana2022]_. +# The order of magnitude of the resonance frequencies :math:`\omega_q` and coupling strength :math:`g_{pq}` are taken from [#Asthana2022]_ (in GHz). def a(wires): return 0.5*qml.PauliX(wires) + 0.5j* qml.PauliY(wires) @@ -202,6 +202,7 @@ def ad(wires): # # with the (real) time-dependent amplitude :math:`\Omega(t)` and frequency :math:`\nu_q` of the drive. # We let :math:`\Omega(t)` be a piece-wise-constant real function that is optimized alongside the frequencies :math:`\nu_q`. +# Further, the amplitude of :math:`\Omega(t)` is restricted to :math:`20` MHz. # TODO use official convenience functions once merged def pwc(t1, t2): @@ -215,7 +216,9 @@ def wrapped(params, t): def envelope(t1, t2, sign=1.): # assuming p = (len(t_bins) + 1) for the frequency nu def wrapped(p, t): - return jnp.clip(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t), -0.02, 0.02) + # return jnp.clip(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t), -0.02, 0.02) + # but when I put this restriction to 20 MHz amplitudes nothing is happening + return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) return wrapped duration = 20. @@ -263,7 +266,6 @@ def cost_fn(params): C_der = abs_diff(p) # derivative values return C_exp + 3*C_par + 3*C_der - ############################################################################## # We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax`` for optimizations in ``jax`` for our optimization loop. import optax From ae515ae4ec5798d0559ab6924a6ca44eb2bfe58b Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 25 Jan 2023 13:06:36 +0100 Subject: [PATCH 019/122] remove 2 pi --- demonstrations/tutorial_pulse_programming101.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 433bcc5815..4e3712df7d 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -189,11 +189,11 @@ def a(wires): def ad(wires): return 0.5*qml.PauliX(wires) - 0.5j* qml.PauliY(wires) -omega = 2 * jnp.pi * jnp.array([4.8080, 4.8333, 4.9400, 4.7960]) -g = 2 * jnp.pi * jnp.array([0.01831, 0.02131, 0.01931, 0.02031]) +omega = jnp.array([4.8080, 4.8333, 4.9400, 4.7960]) +g = jnp.array([0.01831, 0.02131, 0.01931, 0.02031]) -H_D = qml.op_sum(*[qml.s_prod(omega[i], ad(i) @ a(i)) for i in range(n_wires)]) -H_D += qml.op_sum(*[qml.s_prod(g[i], ad(i) @ a(i+1)) for i in range(n_wires-1)]) +H_D = qml.ops.dot(omega, [ad(i) @ a(i) for i in range(n_wires)]) +H_D += qml.ops.dot(g, [ad(i) @ a((i+1)%n_wires) for i in range(n_wires)]) ############################################################################## # The system is driven under the control term @@ -216,9 +216,9 @@ def wrapped(params, t): def envelope(t1, t2, sign=1.): # assuming p = (len(t_bins) + 1) for the frequency nu def wrapped(p, t): - # return jnp.clip(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t), -0.02, 0.02) + return jnp.clip(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t), -0.02, 0.02) # but when I put this restriction to 20 MHz amplitudes nothing is happening - return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) + # return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) return wrapped duration = 20. From bfb5c5c60d35a4f9f8691c168596542332446f21 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 25 Jan 2023 15:38:38 +0100 Subject: [PATCH 020/122] bug fix on non-hermitian drive hamiltonian, clip envelope - no optimization possible --- .../tutorial_pulse_programming101.py | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 4e3712df7d..8c39fc10b1 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -193,7 +193,7 @@ def ad(wires): g = jnp.array([0.01831, 0.02131, 0.01931, 0.02031]) H_D = qml.ops.dot(omega, [ad(i) @ a(i) for i in range(n_wires)]) -H_D += qml.ops.dot(g, [ad(i) @ a((i+1)%n_wires) for i in range(n_wires)]) +H_D += qml.ops.dot(g, [ad(i) @ a((i+1)%n_wires) + ad((i+1)%n_wires) @ a(i) for i in range(n_wires)]) ############################################################################## # The system is driven under the control term @@ -238,11 +238,21 @@ def wrapped(p, t): dev = qml.device("default.qubit", wires=range(n_wires)) +t_bins = 40 # number of time bins +theta = jnp.array([jnp.ones(t_bins + 1, dtype=float) for _ in range(n_wires)]) + +# KK meta comment: +# The step sizes are chosen adaptively, so there is in principle no need to provide +# explicit time steps. However, because the pwc function can be discontinuous it makes +# sense to force the solver to evaluate the points of the evolution. +# The error is still guaranteed to stay within the tolerance by using adaptive steps in between. +ts = jnp.linspace(0., duration, t_bins) + @jax.jit @qml.qnode(dev, interface="jax") -def qnode(p, t=duration): +def qnode(theta, t=ts): qml.BasisState(np.array([1, 1, 0, 0]), wires=H_obj.wires) - qml.evolve(H_pulse)(params=(*p, *p), t=t) + qml.evolve(H_pulse)(params=(*theta, *theta), t=t) return qml.expval(H_obj) ############################################################################## @@ -271,9 +281,6 @@ def cost_fn(params): import optax from datetime import datetime -t_bins = 40 # number of time bins -theta = jnp.array([jnp.ones(t_bins + 1, dtype=float) for _ in range(n_wires)]) - n_epochs = 100 optimizer = optax.adam(learning_rate=0.1) opt_state = optimizer.init(theta) From 4640bea9e935d7aeaed6c9c91b4b57db3a9c1750 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 25 Jan 2023 15:39:23 +0100 Subject: [PATCH 021/122] alternative normalization option (also does not work --- demonstrations/tutorial_pulse_programming101.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 8c39fc10b1..8889959d89 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -213,9 +213,18 @@ def wrapped(params, t): return wrapped +def normalize(z): + """eq. (8) in https://arxiv.org/pdf/2210.15812.pdf""" + def S(x): + return (1-jnp.exp(-x))/(1+jnp.exp(-x)) + absz = jnp.abs(z) + argz = jnp.angle(z) + return S(absz) * jnp.exp(1j*argz) + def envelope(t1, t2, sign=1.): # assuming p = (len(t_bins) + 1) for the frequency nu def wrapped(p, t): + #return 0.02*normalize(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t)) return jnp.clip(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t), -0.02, 0.02) # but when I put this restriction to 20 MHz amplitudes nothing is happening # return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) From 2257369877927d46550cae9f15321e62e9b779e0 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 25 Jan 2023 17:20:40 +0100 Subject: [PATCH 022/122] look at mean gradient in iterations --- demonstrations/tutorial_pulse_programming101.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 8889959d89..0562d79725 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -224,10 +224,10 @@ def S(x): def envelope(t1, t2, sign=1.): # assuming p = (len(t_bins) + 1) for the frequency nu def wrapped(p, t): - #return 0.02*normalize(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t)) - return jnp.clip(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t), -0.02, 0.02) + return 0.02*normalize(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t)) + #return jnp.clip(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t), -0.02, 0.02) # but when I put this restriction to 20 MHz amplitudes nothing is happening - # return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) + #return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) return wrapped duration = 20. @@ -285,13 +285,15 @@ def cost_fn(params): C_der = abs_diff(p) # derivative values return C_exp + 3*C_par + 3*C_der +cost_fn = qnode + ############################################################################## # We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax`` for optimizations in ``jax`` for our optimization loop. import optax from datetime import datetime n_epochs = 100 -optimizer = optax.adam(learning_rate=0.1) +optimizer = optax.adam(learning_rate=0.5) opt_state = optimizer.init(theta) value_and_grad = jax.jit(jax.value_and_grad(cost_fn, argnums=0)) @@ -309,6 +311,7 @@ def cost_fn(params): for n in range(n_epochs): val, grad_circuit = value_and_grad(theta) + print(f"mean grad: {jnp.mean(grad_circuit)}") updates, opt_state = optimizer.update(grad_circuit, opt_state) theta = optax.apply_updates(theta, updates) From a4ef9889529413ca9fb0e0b34f655bdd9ce5b4b2 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 26 Jan 2023 17:47:42 +0100 Subject: [PATCH 023/122] amplitude modulation --- .../tutorial_pulse_programming101.py | 46 ++++++++++--------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 0562d79725..659c9a96ee 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -50,6 +50,9 @@ import jax import matplotlib.pyplot as plt +# remove jax CPU/GPU warning +jax.config.update('jax_platform_name', 'cpu') + def f1(p, t): return jnp.polyval(p, t) def f2(p, t): @@ -165,7 +168,7 @@ def qnode(params): # coeffs, obs = H.coeffs, H.ops # H_obj = qml.Hamiltonian(jnp.array(coeffs), obs) -data = qml.data.load("qchem", molname="H2", basis="STO-3G", bondlength=1.9)[0] +data = qml.data.load("qchem", molname="H2", basis="STO-3G", bondlength=0.82)[0] H_obj = data.hamiltonian n_wires = len(H_obj.wires) @@ -174,7 +177,7 @@ def qnode(params): # We will later use this to determine if our ctrl-VQE algorithm was successful. H_obj_m = qml.matrix(H_obj) -E_exact = np.min(np.linalg.eigvalsh(H_obj_m)) +E_exact = data.fci_energy #np.min(np.linalg.eigvalsh(H_obj_m)) ############################################################################## # As a realistic physical system to simulate, we are considering a coupled transmon qubit system with the constant drift term Hamiltonian @@ -205,10 +208,10 @@ def ad(wires): # Further, the amplitude of :math:`\Omega(t)` is restricted to :math:`20` MHz. # TODO use official convenience functions once merged -def pwc(t1, t2): +def pwc(T): def wrapped(params, t): N = len(params) - idx = jnp.array(N/(t2 - t1) * (t - t1), dtype=int) # corresponding sample + idx = jnp.array(N/(T) * t, dtype=int) # corresponding sample return params[idx] return wrapped @@ -221,19 +224,20 @@ def S(x): argz = jnp.angle(z) return S(absz) * jnp.exp(1j*argz) -def envelope(t1, t2, sign=1.): +def envelope(T, omega, sign=1.): # assuming p = (len(t_bins) + 1) for the frequency nu def wrapped(p, t): - return 0.02*normalize(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t)) - #return jnp.clip(pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t), -0.02, 0.02) - # but when I put this restriction to 20 MHz amplitudes nothing is happening - #return pwc(t1, t2)(p[:-1], t) * jnp.exp(sign*1j*p[-1]*t) + #amp = jnp.clip(pwc(T)(p[:-1], t), -0.02, 0.02) + amp = pwc(T)(p[:-1], t) + phase = jnp.exp(sign*1j*p[-1]*t) + return amp * phase + return wrapped -duration = 20. +duration = 30. -fs = [envelope(0., duration, 1.) for i in range(n_wires)] -fs += [envelope(0., duration, -1.) for i in range(n_wires)] +fs = [envelope(duration, omega[i], 1.) for i in range(n_wires)] +fs += [envelope(duration, omega[i], -1.) for i in range(n_wires)] ops = [a(i) for i in range(n_wires)] ops += [ad(i) for i in range(n_wires)] @@ -247,8 +251,9 @@ def wrapped(p, t): dev = qml.device("default.qubit", wires=range(n_wires)) -t_bins = 40 # number of time bins -theta = jnp.array([jnp.ones(t_bins + 1, dtype=float) for _ in range(n_wires)]) +t_bins = 100 # number of time bins +key = jax.random.PRNGKey(999) +theta = jax.random.uniform(key, shape=jnp.array([n_wires, t_bins + 1])) # KK meta comment: # The step sizes are chosen adaptively, so there is in principle no need to provide @@ -260,7 +265,7 @@ def wrapped(p, t): @jax.jit @qml.qnode(dev, interface="jax") def qnode(theta, t=ts): - qml.BasisState(np.array([1, 1, 0, 0]), wires=H_obj.wires) + qml.BasisState(data.hf_state, wires=H_obj.wires) qml.evolve(H_pulse)(params=(*theta, *theta), t=t) return qml.expval(H_obj) @@ -283,17 +288,17 @@ def cost_fn(params): C_exp = qnode(params) # expectation value C_par = jnp.mean(jnp.abs(p)**2) # parameter values C_der = abs_diff(p) # derivative values - return C_exp + 3*C_par + 3*C_der + return C_exp + C_par + C_der -cost_fn = qnode +#cost_fn = qnode ############################################################################## # We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax`` for optimizations in ``jax`` for our optimization loop. import optax from datetime import datetime -n_epochs = 100 -optimizer = optax.adam(learning_rate=0.5) +n_epochs = 50 +optimizer = optax.adam(learning_rate=0.5) #adabelief opt_state = optimizer.init(theta) value_and_grad = jax.jit(jax.value_and_grad(cost_fn, argnums=0)) @@ -308,10 +313,8 @@ def cost_fn(params): _ = value_and_grad(theta) time1 = datetime.now() print(f"grad and val compilation time: {time1 - time0}") - for n in range(n_epochs): val, grad_circuit = value_and_grad(theta) - print(f"mean grad: {jnp.mean(grad_circuit)}") updates, opt_state = optimizer.update(grad_circuit, opt_state) theta = optax.apply_updates(theta, updates) @@ -320,6 +323,7 @@ def cost_fn(params): theta_i.append(theta) if not n%5: + print(f"mean grad: {jnp.mean(grad_circuit)}") print(f"{n+1} / {n_epochs}; energy: {energy[n]}; cost: {val}") ############################################################################## From 9ef011f0f83421016a595f6cd3e5a658f332bdd7 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 26 Jan 2023 18:14:59 +0100 Subject: [PATCH 024/122] hyper parameter update, still not great, best I could get so far --- demonstrations/tutorial_pulse_programming101.py | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 659c9a96ee..80a5a048fa 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -252,8 +252,8 @@ def wrapped(p, t): dev = qml.device("default.qubit", wires=range(n_wires)) t_bins = 100 # number of time bins -key = jax.random.PRNGKey(999) -theta = jax.random.uniform(key, shape=jnp.array([n_wires, t_bins + 1])) +key = jax.random.PRNGKey(666) +theta = 0.02*jax.random.uniform(key, shape=jnp.array([n_wires, t_bins + 1])) # KK meta comment: # The step sizes are chosen adaptively, so there is in principle no need to provide @@ -262,7 +262,6 @@ def wrapped(p, t): # The error is still guaranteed to stay within the tolerance by using adaptive steps in between. ts = jnp.linspace(0., duration, t_bins) -@jax.jit @qml.qnode(dev, interface="jax") def qnode(theta, t=ts): qml.BasisState(data.hf_state, wires=H_obj.wires) @@ -290,18 +289,16 @@ def cost_fn(params): C_der = abs_diff(p) # derivative values return C_exp + C_par + C_der -#cost_fn = qnode - ############################################################################## # We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax`` for optimizations in ``jax`` for our optimization loop. import optax from datetime import datetime n_epochs = 50 -optimizer = optax.adam(learning_rate=0.5) #adabelief +optimizer = optax.adabelief(learning_rate=0.1) #adabelief opt_state = optimizer.init(theta) -value_and_grad = jax.jit(jax.value_and_grad(cost_fn, argnums=0)) +value_and_grad = jax.jit(jax.value_and_grad(cost_fn)) energy = np.zeros(n_epochs) cost = np.zeros(n_epochs) @@ -350,13 +347,13 @@ def cost_fn(params): # :math:`\Omega(t)` and indicate the numerical value of :math:`\nu_q`. -ts = jnp.linspace(0, duration, t_bins) fs = H_pulse.coeffs_parametrized[:n_wires] n_channels = len(fs) fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels)) for n in range(n_channels): ax = axs[n] - ax.plot(ts, jnp.abs(fs[n](theta[n], ts)), ".:", label=f"$\\nu$_{n}: {jnp.angle(fs[n](theta[n], 1.))/jnp.pi:.3}/$\\pi$") + amp = fs[n](theta[n], ts) + ax.plot(ts, jnp.sign(amp) * jnp.abs(amp), ".:", label=f"$\\nu$_{n}: {jnp.angle(fs[n](theta[n], 1.))/jnp.pi:.3}/$\\pi$") ax.set_ylabel(f"amplitude_{n}") ax.legend() From 409a8c5d0c611b4e9851a17de409672c485fdba4 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 26 Jan 2023 18:21:49 +0100 Subject: [PATCH 025/122] move to tapered HeH+, reaches gs energy --- demonstrations/tutorial_pulse_programming101.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 80a5a048fa..bfc40a1681 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -168,8 +168,8 @@ def qnode(params): # coeffs, obs = H.coeffs, H.ops # H_obj = qml.Hamiltonian(jnp.array(coeffs), obs) -data = qml.data.load("qchem", molname="H2", basis="STO-3G", bondlength=0.82)[0] -H_obj = data.hamiltonian +data = qml.data.load("qchem", molname="HeH+", basis="STO-3G", bondlength=0.82)[0] +H_obj = data.tapered_hamiltonian n_wires = len(H_obj.wires) ############################################################################## @@ -192,8 +192,8 @@ def a(wires): def ad(wires): return 0.5*qml.PauliX(wires) - 0.5j* qml.PauliY(wires) -omega = jnp.array([4.8080, 4.8333, 4.9400, 4.7960]) -g = jnp.array([0.01831, 0.02131, 0.01931, 0.02031]) +omega = jnp.array([4.8080, 4.8333]) +g = jnp.array([0.01831, 0.02131]) H_D = qml.ops.dot(omega, [ad(i) @ a(i) for i in range(n_wires)]) H_D += qml.ops.dot(g, [ad(i) @ a((i+1)%n_wires) + ad((i+1)%n_wires) @ a(i) for i in range(n_wires)]) @@ -264,7 +264,7 @@ def wrapped(p, t): @qml.qnode(dev, interface="jax") def qnode(theta, t=ts): - qml.BasisState(data.hf_state, wires=H_obj.wires) + qml.BasisState(data.tapered_hf_state, wires=H_obj.wires) qml.evolve(H_pulse)(params=(*theta, *theta), t=t) return qml.expval(H_obj) From 3264f1a4e7c84322bb95c23294558c287d7d21fd Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 26 Jan 2023 18:27:17 +0100 Subject: [PATCH 026/122] stronger penalty term, more realistic amplitudes --- demonstrations/tutorial_pulse_programming101.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index bfc40a1681..54b491ae1e 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -287,7 +287,7 @@ def cost_fn(params): C_exp = qnode(params) # expectation value C_par = jnp.mean(jnp.abs(p)**2) # parameter values C_der = abs_diff(p) # derivative values - return C_exp + C_par + C_der + return C_exp + 5*C_par + 5*C_der ############################################################################## # We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax`` for optimizations in ``jax`` for our optimization loop. @@ -319,9 +319,9 @@ def cost_fn(params): cost[n] = val theta_i.append(theta) - if not n%5: - print(f"mean grad: {jnp.mean(grad_circuit)}") - print(f"{n+1} / {n_epochs}; energy: {energy[n]}; cost: {val}") + # if not n%5: + # print(f"mean grad: {jnp.mean(grad_circuit)}") + # print(f"{n+1} / {n_epochs}; energy: {energy[n]}; cost: {val}") ############################################################################## # We see that the energy converges relatively quickly to the desired exact result. From 1af9207db92feaa1ae27c1c4a751043d90721477 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann <43949391+Qottmann@users.noreply.github.com> Date: Thu, 26 Jan 2023 15:11:40 -0800 Subject: [PATCH 027/122] Apply suggestions from code review Co-authored-by: David Wierichs Co-authored-by: lillian542 <38584660+lillian542@users.noreply.github.com> Co-authored-by: Tom Bromley <49409390+trbromley@users.noreply.github.com> --- .../tutorial_pulse_programming101.py | 39 +++++++++---------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 54b491ae1e..713b5f8fb6 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -7,22 +7,22 @@ *Author: Korbinian Kottmann — Posted: 20 February 2023. -In this demo we are going to introduce pulse gates and differentiable pulse programming, showcase -the current functionality in PennyLane and run the ctrl-VQE algorithm for an example molecule. +In this demo we are going to introduce pulse operations in PennyLane and run the +ctrl-VQE algorithm for an example molecule. Pulses in quantum computers --------------------------- -In non-measurement-based quantum computers such as superconducting and ion trap systems, qubits are realized through physical systems with a discrete set of energy levels. +In many quantum computing architectures such as superconducting and ion trap systems, qubits are realized through physical systems with a discrete set of energy levels. For example, transmon qubits realize an anharmonic oscillator whose ground and first excited states can serve as the two energy levels of a qubit. Such a qubit can be controlled via an electromagnetic field tuned to its energy gap. In general, this electromangnetic field can be altered in time, leading to a time-dependent Hamiltonian interaction :math:`H(t)`. -We call driving the system with such an electromagnetic field for a fixed time window a pulse sequence. During a pulse sequence, the state evolves according +We call driving the system with such an electromagnetic field for a fixed time window a *pulse sequence*. During a pulse sequence, the state evolves according to the time-dependent Schrodinger equation .. math:: \frac{d}{dt}|\psi\rangle = -i H(t) |\psi\rangle -realizing a unitary evolution :math:`U(t_0, t_1)` from times :math:`t_0` to :math:`t_1` of the input state, i.e. +following a unitary evolution :math:`U(t_0, t_1)` of the input state from time :math:`t_0` to :math:`t_1`, i.e. :math:`|\psi(t_1)\rangle = U(t_0, t_1) |\psi(t_0)\rangle`. In non-measurement-based digital quantum computers, the amplitude and frequencies of predefined pulse sequences are @@ -33,15 +33,15 @@ ------------------------------ A user of a quantum computer typically operates on the higher and more abstract gate level. -Future fault tolerance quantum computers require this abstraction to allow for error correction. +Future fault-tolerant quantum computers require this abstraction to allow for error correction. For noisy and intermediate sized quantum computers, the abstraction of decomposing quantum algorithms into a fixed native gate set can be a hindrance and unnecessarily increase execution time, therefore leading -to more decoherence. The idea of differentiable pulse programming is to optimize quantum circuits on the pulse +to more noise in the computation. The idea of differentiable pulse programming is to optimize quantum circuits on the pulse level with the aim of achieving the shortest interaction sequence a hardware system allows. -In PennyLane, we can now simulate arbitrary qubit system interactions to explore the possibilities of such pulse programs. -First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p, t) H_i` with envelope :math:`f_i(p, t)` that may -depend on parameters :math:`p` and constant operators :math:`H_i`. In PennyLane, we can do this intuitively in the following way. +In PennyLane, we can simulate arbitrary qubit system interactions to explore the possibilities of such pulse programs. +First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p, t) H_i` with constant operators :math:`H_i` and driving fields :math:`f_i(p, t)` that may +depend on parameters :math:`p`. In PennyLane, we can do this in an intuitive way: """ import pennylane as qml @@ -53,8 +53,7 @@ # remove jax CPU/GPU warning jax.config.update('jax_platform_name', 'cpu') -def f1(p, t): - return jnp.polyval(p, t) +f1 = jnp.polyval def f2(p, t): return p[0] * jnp.sin(p[1] * t) @@ -69,8 +68,8 @@ def f2(p, t): print(Ht(params, 0.5)) ############################################################################## -# We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using :func:`~pennylane.ops.dot`. -# We use two sinusodials with random frequencies as the time-dependent parametrization. +# We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using :func:`qml.ops.dot `. +# We use two sinusodials with random frequencies as the time-dependent parametrization for each :math:`Z_i`. coeffs = [jnp.array(1.)] * 2 coeffs += [lambda p, t: jnp.sin(p[0]*t) + jnp.sin(p[1]*t) for _ in range(3)] @@ -111,9 +110,9 @@ def draw(H, params, t, resolution=200): ############################################################################## # Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. -# For example, we will later simulate a transmon qubit system in the ctrl-VQE example in the last section of this demo. +# For example, we will simulate a transmon qubit system in the ctrl-VQE example in the last section of this demo. # -# A pulse program is then executed by using the :func:`~pennylane.ops.evolve` transform to create the evolution +# A pulse program is then executed by using the :func:`~.pennylane.ops.evolve` transform to create the evolution # gate :math:`U(t_0, t_1)`, which implicitly depends on the parameters ``p``. dev = qml.device("default.qubit", range(4)) @@ -130,7 +129,7 @@ def qnode(params): print(qnode(params)) ############################################################################## -# We used the decorator ``jax.jit`` to just-in-time compile this execution. This means the first execution will typically take a little longer with the +# We used the decorator ``jax.jit`` to compile this execution just-in-time. This means the first execution will typically take a little longer with the # benefit that all following executions will be significantly faster. JIT-compiling is optional, and one can remove the decorator when only single executions # are of interest. # @@ -150,7 +149,7 @@ def qnode(params): # ------------------------------------------------------ # We can now use those gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Asthana2022]_. # First, we define the molecular Hamiltonian whose energy estimate we want to minimize. -# We are going to look at the :math:`H_3^+` as a simple example and load it from the `quantum datasets `_ website. +# We are going to look at :math:`H_3^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. # # symbols = ["H", "H", "H"] @@ -203,7 +202,7 @@ def ad(wires): # # .. math:: H_C(t) = \sum_q \Omega_q(t) \left(e^{i\nu_q t} a_q + e^{-i\nu_q t} a^\dagger_q \right) # -# with the (real) time-dependent amplitude :math:`\Omega(t)` and frequency :math:`\nu_q` of the drive. +# with the (real) time-dependent amplitudes :math:`\Omega_q(t)` and frequencies :math:`\nu_q` of the drive. # We let :math:`\Omega(t)` be a piece-wise-constant real function that is optimized alongside the frequencies :math:`\nu_q`. # Further, the amplitude of :math:`\Omega(t)` is restricted to :math:`20` MHz. @@ -290,7 +289,7 @@ def cost_fn(params): return C_exp + 5*C_par + 5*C_der ############################################################################## -# We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax`` for optimizations in ``jax`` for our optimization loop. +# We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax``, a package for optimizations in ``jax``. import optax from datetime import datetime From 782049e23ff36cf522b4bfa6eb394706cfc78474 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:12:04 +0100 Subject: [PATCH 028/122] hyper parameters --- demonstrations/tutorial_pulse_programming101.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 54b491ae1e..d71a9305c2 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -234,7 +234,7 @@ def wrapped(p, t): return wrapped -duration = 30. +duration = 15. fs = [envelope(duration, omega[i], 1.) for i in range(n_wires)] fs += [envelope(duration, omega[i], -1.) for i in range(n_wires)] @@ -287,7 +287,7 @@ def cost_fn(params): C_exp = qnode(params) # expectation value C_par = jnp.mean(jnp.abs(p)**2) # parameter values C_der = abs_diff(p) # derivative values - return C_exp + 5*C_par + 5*C_der + return C_exp + 3*C_par + 3*C_der ############################################################################## # We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax`` for optimizations in ``jax`` for our optimization loop. @@ -295,7 +295,7 @@ def cost_fn(params): from datetime import datetime n_epochs = 50 -optimizer = optax.adabelief(learning_rate=0.1) #adabelief +optimizer = optax.adabelief(learning_rate=0.2) #adabelief opt_state = optimizer.init(theta) value_and_grad = jax.jit(jax.value_and_grad(cost_fn)) @@ -310,6 +310,7 @@ def cost_fn(params): _ = value_and_grad(theta) time1 = datetime.now() print(f"grad and val compilation time: {time1 - time0}") + for n in range(n_epochs): val, grad_circuit = value_and_grad(theta) updates, opt_state = optimizer.update(grad_circuit, opt_state) @@ -319,9 +320,9 @@ def cost_fn(params): cost[n] = val theta_i.append(theta) - # if not n%5: - # print(f"mean grad: {jnp.mean(grad_circuit)}") - # print(f"{n+1} / {n_epochs}; energy: {energy[n]}; cost: {val}") + if not n%5: + print(f"mean grad: {jnp.mean(grad_circuit)}") + print(f"{n+1} / {n_epochs}; energy: {energy[n]}; cost: {val}") ############################################################################## # We see that the energy converges relatively quickly to the desired exact result. From 8d6d6356e721d70687521de9b919876f82ad3263 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:14:35 +0100 Subject: [PATCH 029/122] umlaute ftw --- demonstrations/tutorial_pulse_programming101.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index b2cf09b0fb..eb57616d0f 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -18,7 +18,7 @@ levels of a qubit. Such a qubit can be controlled via an electromagnetic field tuned to its energy gap. In general, this electromangnetic field can be altered in time, leading to a time-dependent Hamiltonian interaction :math:`H(t)`. We call driving the system with such an electromagnetic field for a fixed time window a *pulse sequence*. During a pulse sequence, the state evolves according -to the time-dependent Schrodinger equation +to the time-dependent Schrödinger equation .. math:: \frac{d}{dt}|\psi\rangle = -i H(t) |\psi\rangle @@ -135,7 +135,7 @@ def qnode(params): # # Gradients of pulse programs # --------------------------- -# Internally, this program solves the the time-dependent Schrodinger equation using the `Dopri5 `_ solver for +# Internally, this program solves the the time-dependent Schrödinger equation using the `Dopri5 `_ solver for # ordinary differential equations (ODEs). In particular, the step sizes between :math:`t_0` and :math:`t_1` are chosen adaptively to stay within a given error tolerance. # We can backpropagate through this ODE solver and obtain the gradient via ``jax.grad``. From 62ecc943db8f68122986d311c55965d1c53163aa Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:15:56 +0100 Subject: [PATCH 030/122] switched back to f1(p, t): return polzval(p, t) because it is more explicit and understandable --- demonstrations/tutorial_pulse_programming101.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index eb57616d0f..26879cc0d2 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -53,7 +53,8 @@ # remove jax CPU/GPU warning jax.config.update('jax_platform_name', 'cpu') -f1 = jnp.polyval +def f1(p, t): + return jnp.polyval(p, t) def f2(p, t): return p[0] * jnp.sin(p[1] * t) From 2c7ae5d62a66ea69406f26a4022e121e8823572f Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:22:00 +0100 Subject: [PATCH 031/122] update drawing to instance specifics --- .../tutorial_pulse_programming101.py | 25 ++++++++----------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 26879cc0d2..c59735fea6 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -88,20 +88,17 @@ def f2(p, t): ############################################################################## # We can visualize the Hamiltonian interaction by plotting the time-dependent envelopes. -def draw(H, params, t, resolution=200): - ts = jnp.linspace(0, t, resolution) - fs = H.coeffs_parametrized - ops = H.ops_parametrized - n_channels = len(fs) - fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels)) - for n in range(n_channels): - ax = axs[n] - ax.plot(ts, fs[n](params[n], ts)) - ax.set_ylabel(f"{ops[n].__repr__()}") - axs[0].set_title(f"Drift term: {H.H_fixed()}") - plt.show() - -draw(Ht, params, 4.) +ts = jnp.linspace(0., 5., 100) +fs = Ht.coeffs_parametrized +ops = Ht.ops_parametrized +n_channels = len(fs) +fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels)) +for n in range(n_channels): + ax = axs[n] + ax.plot(ts, fs[n](params[n], ts)) + ax.set_ylabel(f"Z_{n}") +axs[0].set_title(f"Drift term: X_0 X_1 + X_1 X_2") +plt.show() ############################################################################## # PennyLane also provides a variety of convenience functions to enable for example piece-wise-constant parametrizations, From 087ac4804466eb22ed7d06468fe84ba214501fa8 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:30:20 +0100 Subject: [PATCH 032/122] naming drive field and comment about parameter length --- demonstrations/tutorial_pulse_programming101.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index c59735fea6..e07b232a9a 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -181,7 +181,8 @@ def qnode(params): # # .. math:: H_D = \sum_q \omega_q a_q^\dagger a_q + \sum_q \frac{\delta_q}{2} a^\dagger_q a^\dagger_q a_q a_q + \sum_{\braket{pq}} g_{pq} a^\dagger_p a_q # -# with bosonic creation and annihilation operators. We are only going to consider the qubit subspace such that the quadratic term proportional to :math:`\delta_q` is zero. +# with bosonic creation and annihilation operators. The quadratic part propotional to :math:`\delta_q` is describing the anharmonic contribution to higher energy levels. +# We are only going to consider the qubit subspace such that this term is zero. # The order of magnitude of the resonance frequencies :math:`\omega_q` and coupling strength :math:`g_{pq}` are taken from [#Asthana2022]_ (in GHz). def a(wires): @@ -221,8 +222,8 @@ def S(x): argz = jnp.angle(z) return S(absz) * jnp.exp(1j*argz) -def envelope(T, omega, sign=1.): - # assuming p = (len(t_bins) + 1) for the frequency nu +def drive_field(T, omega, sign=1.): + # assuming len(p) = len(t_bins) + 1 for the frequency nu def wrapped(p, t): #amp = jnp.clip(pwc(T)(p[:-1], t), -0.02, 0.02) amp = pwc(T)(p[:-1], t) @@ -233,8 +234,8 @@ def wrapped(p, t): duration = 15. -fs = [envelope(duration, omega[i], 1.) for i in range(n_wires)] -fs += [envelope(duration, omega[i], -1.) for i in range(n_wires)] +fs = [drive_field(duration, omega[i], 1.) for i in range(n_wires)] +fs += [drive_field(duration, omega[i], -1.) for i in range(n_wires)] ops = [a(i) for i in range(n_wires)] ops += [ad(i) for i in range(n_wires)] From 352e3b55cad56230eba8fb5e2e02e506ffd4f846 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:34:34 +0100 Subject: [PATCH 033/122] specify cost function --- demonstrations/tutorial_pulse_programming101.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index e07b232a9a..81ec472720 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -272,12 +272,13 @@ def qnode(theta, t=ts): # reach arbitrarily large values and cannot change arbitrarily quickly in time. We therefore add two penalty terms quantifying the # mean absolute square of the amplitude and changes in the amplitude. The overall cost function is thus # -# .. math:: \mathcal{C}(p) = \langle H_\text{obj} \rangle + \sum_{ki} |p^k_i|^2 + \sum_{ki} |p^k_i - p^k_{i-1}|^2. +# .. math:: \mathcal{C}(p) = \langle H_\text{obj} \rangle + \frac{1}{N_p} \sum_{ki} |p^k_i|^2 + \frac{1}{N_p} \sum_{ki} |p^k_i - p^k_{i-1}|^2, # +# where :math:`N_p` is the total number of drive field amplitude segments. def abs_diff(p): """compute |p_i - p_i-1|^2""" - return jnp.mean(jnp.abs(jnp.diff(p[:, :-1], axis=1))**2) + return jnp.mean(jnp.abs(jnp.diff(p, axis=1))**2) def cost_fn(params): # params.shape = (n_wires, {n_bins}+1) From 892a8561a80d3def7cefeb63d70c5c50f2a0c98a Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:35:38 +0100 Subject: [PATCH 034/122] placeholder comment about resulting curve --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 81ec472720..ece91cc862 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -324,7 +324,7 @@ def cost_fn(params): print(f"{n+1} / {n_epochs}; energy: {energy[n]}; cost: {val}") ############################################################################## -# We see that the energy converges relatively quickly to the desired exact result. +# placeholder: comment on resulting curve when example is fixed. fig, axs = plt.subplots(nrows=2, figsize=(5,5), sharex=True) ax = axs[0] From bb33ff1cd6170c53dabb022922ca04f6097910f3 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:37:23 +0100 Subject: [PATCH 035/122] update bio --- _static/authors/korbinian_kottmann.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_static/authors/korbinian_kottmann.txt b/_static/authors/korbinian_kottmann.txt index 8a43541d0f..7a94abea10 100644 --- a/_static/authors/korbinian_kottmann.txt +++ b/_static/authors/korbinian_kottmann.txt @@ -1,4 +1,4 @@ .. bio:: Korbinian Kottmann :photo: ../_static/authors/korbinian_kottmann.jpg - Korbinian is a summer resident at Xanadu, interested in quantum simulation and quantum software. \ No newline at end of file + Korbinian is a Quantum Scientist - Software at Xanadu, interested in quantum simulation and quantum software. \ No newline at end of file From 28873598d2abc75b5eedef89616c9e3650e771dd Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:37:57 +0100 Subject: [PATCH 036/122] update bio --- _static/authors/korbinian_kottmann.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_static/authors/korbinian_kottmann.txt b/_static/authors/korbinian_kottmann.txt index 7a94abea10..c71938b3fd 100644 --- a/_static/authors/korbinian_kottmann.txt +++ b/_static/authors/korbinian_kottmann.txt @@ -1,4 +1,4 @@ .. bio:: Korbinian Kottmann :photo: ../_static/authors/korbinian_kottmann.jpg - Korbinian is a Quantum Scientist - Software at Xanadu, interested in quantum simulation and quantum software. \ No newline at end of file + Korbinian is a Quantum Scientist at Xanadu, interested in quantum simulation and quantum software. \ No newline at end of file From 1cddb41f6d106ec8ae1b1e20d7720f10c0ae5c7a Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:39:25 +0100 Subject: [PATCH 037/122] tight layout --- demonstrations/tutorial_pulse_programming101.py | 1 + 1 file changed, 1 insertion(+) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index ece91cc862..130c2a02b3 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -98,6 +98,7 @@ def f2(p, t): ax.plot(ts, fs[n](params[n], ts)) ax.set_ylabel(f"Z_{n}") axs[0].set_title(f"Drift term: X_0 X_1 + X_1 X_2") +plt.tight_layout() plt.show() ############################################################################## From f7f0470f0799338f6647ec1e1e3b702a4326e89b Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann <43949391+Qottmann@users.noreply.github.com> Date: Thu, 26 Jan 2023 15:42:47 -0800 Subject: [PATCH 038/122] Update demonstrations/tutorial_pulse_programming101.py Co-authored-by: David Wierichs --- demonstrations/tutorial_pulse_programming101.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index ece91cc862..4ed2cc487a 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -303,13 +303,13 @@ def cost_fn(params): cost = np.zeros(n_epochs) theta_i = [theta] -## Optimization loop - +## Compile the evaluation and gradient function and report compilation time time0 = datetime.now() _ = value_and_grad(theta) time1 = datetime.now() print(f"grad and val compilation time: {time1 - time0}") +## Optimization loop for n in range(n_epochs): val, grad_circuit = value_and_grad(theta) updates, opt_state = optimizer.update(grad_circuit, opt_state) From 585c24179589b40504469e645343559943d7de97 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:44:52 +0100 Subject: [PATCH 039/122] plot label changes --- demonstrations/tutorial_pulse_programming101.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 130c2a02b3..48df09096b 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -329,13 +329,13 @@ def cost_fn(params): fig, axs = plt.subplots(nrows=2, figsize=(5,5), sharex=True) ax = axs[0] -ax.plot(energy, ".:", label="energy") -ax.plot([0, n_epochs], [E_exact]*2, ":", label="exact diag", color="grey") +ax.plot(energy, ".:", label="$\langle H_\\text{obj}\rangle (p)$") +ax.plot([0, n_epochs], [E_exact]*2, ":", label="$E_\\text{min}$", color="grey") ax.set_ylabel("Energy") ax.legend() ax = axs[1] -ax.plot(cost,".:", label="cost") +ax.plot(cost,".:", label="$C(p)$") ax.set_xlabel("epoch") ax.set_ylabel("Cost") From 6fff1b5d64ef47d7264d2388e8569415f6e8f7d3 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:52:11 +0100 Subject: [PATCH 040/122] latex matplotlib fix --- demonstrations/tutorial_pulse_programming101.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 91870dd156..adf542210a 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -329,8 +329,8 @@ def cost_fn(params): fig, axs = plt.subplots(nrows=2, figsize=(5,5), sharex=True) ax = axs[0] -ax.plot(energy, ".:", label="$\langle H_\\text{obj}\rangle (p)$") -ax.plot([0, n_epochs], [E_exact]*2, ":", label="$E_\\text{min}$", color="grey") +ax.plot(energy, ".:", label="$\\langle H_{{obj}}\\rangle (p)$") +ax.plot([0, n_epochs], [E_exact]*2, ":", label="$E_{{min}}$", color="grey") ax.set_ylabel("Energy") ax.legend() From 082eb3e529d80fd2d8c3660512a01f93bb90db6e Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:55:37 +0100 Subject: [PATCH 041/122] reference jax docs on jitting --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index adf542210a..167ae0c27f 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -129,7 +129,7 @@ def qnode(params): ############################################################################## # We used the decorator ``jax.jit`` to compile this execution just-in-time. This means the first execution will typically take a little longer with the -# benefit that all following executions will be significantly faster. JIT-compiling is optional, and one can remove the decorator when only single executions +# benefit that all following executions will be significantly faster, see the `jax docs on jitting `_. JIT-compiling is optional, and one can remove the decorator when only single executions # are of interest. # # Gradients of pulse programs From 5e6264e19118964cb4425be462e3faec6082ca70 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 00:58:31 +0100 Subject: [PATCH 042/122] official pwc --- demonstrations/tutorial_pulse_programming101.py | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 167ae0c27f..8b79bd57ec 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -206,15 +206,6 @@ def ad(wires): # We let :math:`\Omega(t)` be a piece-wise-constant real function that is optimized alongside the frequencies :math:`\nu_q`. # Further, the amplitude of :math:`\Omega(t)` is restricted to :math:`20` MHz. -# TODO use official convenience functions once merged -def pwc(T): - def wrapped(params, t): - N = len(params) - idx = jnp.array(N/(T) * t, dtype=int) # corresponding sample - return params[idx] - - return wrapped - def normalize(z): """eq. (8) in https://arxiv.org/pdf/2210.15812.pdf""" def S(x): @@ -227,7 +218,7 @@ def drive_field(T, omega, sign=1.): # assuming len(p) = len(t_bins) + 1 for the frequency nu def wrapped(p, t): #amp = jnp.clip(pwc(T)(p[:-1], t), -0.02, 0.02) - amp = pwc(T)(p[:-1], t) + amp = qml.pulse.pwc(T)(p[:-1], t) phase = jnp.exp(sign*1j*p[-1]*t) return amp * phase From dab4874e653cb94343c4885eb421e1839416898b Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 01:01:55 +0100 Subject: [PATCH 043/122] sentence about amplitude --- demonstrations/tutorial_pulse_programming101.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 8b79bd57ec..6058a00614 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -204,7 +204,6 @@ def ad(wires): # # with the (real) time-dependent amplitudes :math:`\Omega_q(t)` and frequencies :math:`\nu_q` of the drive. # We let :math:`\Omega(t)` be a piece-wise-constant real function that is optimized alongside the frequencies :math:`\nu_q`. -# Further, the amplitude of :math:`\Omega(t)` is restricted to :math:`20` MHz. def normalize(z): """eq. (8) in https://arxiv.org/pdf/2210.15812.pdf""" @@ -235,7 +234,7 @@ def wrapped(p, t): ############################################################################## # Overall, we end up with the time-dependent parametrized Hamiltonian :math:`H(p, t) = H_D + H_C(p, t)` -# under which the system is evolved for the given time window. +# under which the system is evolved for the given time window of ``15ns``. H_pulse = H_D + H_C @@ -266,7 +265,7 @@ def qnode(theta, t=ts): # # .. math:: \mathcal{C}(p) = \langle H_\text{obj} \rangle + \frac{1}{N_p} \sum_{ki} |p^k_i|^2 + \frac{1}{N_p} \sum_{ki} |p^k_i - p^k_{i-1}|^2, # -# where :math:`N_p` is the total number of drive field amplitude segments. +# where :math:`N_p` is the total number of drive field amplitude segments. Ther resulting values are within the realm of possbility in real devices, :math:`\mathcal{O}(10^7 \text{Hz})`. def abs_diff(p): """compute |p_i - p_i-1|^2""" From c19bbf8ad72c0d0c298734870cc17b60cd9f219e Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 01:03:06 +0100 Subject: [PATCH 044/122] commit about fix ts --- demonstrations/tutorial_pulse_programming101.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 6058a00614..ffdb399545 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -244,11 +244,12 @@ def wrapped(p, t): key = jax.random.PRNGKey(666) theta = 0.02*jax.random.uniform(key, shape=jnp.array([n_wires, t_bins + 1])) -# KK meta comment: + # The step sizes are chosen adaptively, so there is in principle no need to provide # explicit time steps. However, because the pwc function can be discontinuous it makes # sense to force the solver to evaluate the points of the evolution. -# The error is still guaranteed to stay within the tolerance by using adaptive steps in between. +# The error is still guaranteed to stay within the tolerance by using adaptive steps in between +# the fixed ones we provide. ts = jnp.linspace(0., duration, t_bins) @qml.qnode(dev, interface="jax") From ae5eed920fccd2def244a6a75742be265259ff2b Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 01:06:25 +0100 Subject: [PATCH 045/122] refernce typo --- demonstrations/tutorial_pulse_programming101.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index ffdb399545..6f08cfc536 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -362,17 +362,19 @@ def cost_fn(params): # References # ---------- # +# .. [#Leng2022] +# +# Jiaqi Leng, Yuxiang Peng, Yi-Ling Qiao, Ming Lin, Xiaodi Wu +# Differentiable Analog Quantum Computing for Optimization and Control +# `arXiv:2210.15812 `__, 2022 +# # .. [#Asthana2022] # # Ayush Asthana, Chenxu Liu, Oinam Romesh Meitei, Sophia E. Economou, Edwin Barnes, Nicholas J. Mayhall # "Minimizing state preparation times in pulse-level variational molecular simulations." # `arXiv:2203.06818 `__, 2022. # -# .. [#Leng2022] -# -# Jiaqi Leng, Yuxiang Peng, Yi-Ling Qiao, Ming Lin, Xiaodi Wu -# Differentiable Analog Quantum Computing for Optimization and Control -# `arXiv:2210.15812 `__, 2022# + ############################################################################## # About the author From f4d86f7baa1c20e696bab8b092c78cf7718563bb Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 18:23:48 +0100 Subject: [PATCH 046/122] add pulse example --- .../tutorial_pulse_programming101.py | 27 +++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 6f08cfc536..d1b6dc857c 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -103,9 +103,32 @@ def f2(p, t): ############################################################################## # PennyLane also provides a variety of convenience functions to enable for example piece-wise-constant parametrizations, -# i.e. defining the function values at fixed time bins as parameters. +# i.e. defining the function values at fixed time bins as parameters. We can construct such a callable with :func:`~.pennylane.pulse.pwc` +# by providing a ``timespan`` argument that is either a total time (``float``) or a tuple ``(t0, t1)``. + +timespan = 10. +coeffs = [qml.pulse.pwc(timespan) for i in range(2)] + +############################################################################## +# This creates a callable with signature ``(p, t)`` that returns ``p[int(t/duration)]``, such that the passed parameters are the function values +# for different time bins. + +key = jax.random.PRNGKey(777) +params = jax.random.uniform(key, shape=[2, 10], maxval=5) + +ts = jnp.linspace(0., 10., 100)[:-1] +fig, axs = plt.subplots(nrows=2, sharex=True) +for i in range(2): + ax = axs[i] + ax.plot(ts, coeffs[i](params[i], ts), ".-") + +############################################################################## +# We can use these callables as usual to construct a :func:`~.pennylane.pulse.ParametrizedHamiltonian`. + +ops = [qml.PauliX(i) for i in range(2)] +H = qml.pulse.ParametrizedHamiltonian(coeffs, ops) +print(H(params, 0.5)) -# PWC example ############################################################################## # Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. From c4cc54c7f89f07edcf82ae6171ff87c2248ad40d Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 18:27:55 +0100 Subject: [PATCH 047/122] move convenience function part just above gradients --- .../tutorial_pulse_programming101.py | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index d1b6dc857c..8cf85d6cb4 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -101,6 +101,29 @@ def f2(p, t): plt.tight_layout() plt.show() +############################################################################## +# +# A pulse program is then executed by using the :func:`~.pennylane.ops.evolve` transform to create the evolution +# gate :math:`U(t_0, t_1)`, which implicitly depends on the parameters ``p``. + +dev = qml.device("default.qubit", range(4)) + +ts = jnp.array([0., 3.]) +H_obj = sum([qml.PauliZ(i) for i in range(4)]) + +@jax.jit +@qml.qnode(dev, interface="jax") +def qnode(params): + qml.evolve(Ht)(params, ts) + return qml.expval(H_obj) + +print(qnode(params)) + +############################################################################## +# We used the decorator ``jax.jit`` to compile this execution just-in-time. This means the first execution will typically take a little longer with the +# benefit that all following executions will be significantly faster, see the `jax docs on jitting `_. JIT-compiling is optional, and one can remove the decorator when only single executions +# are of interest. + ############################################################################## # PennyLane also provides a variety of convenience functions to enable for example piece-wise-constant parametrizations, # i.e. defining the function values at fixed time bins as parameters. We can construct such a callable with :func:`~.pennylane.pulse.pwc` @@ -134,27 +157,6 @@ def f2(p, t): # Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. # For example, we will simulate a transmon qubit system in the ctrl-VQE example in the last section of this demo. # -# A pulse program is then executed by using the :func:`~.pennylane.ops.evolve` transform to create the evolution -# gate :math:`U(t_0, t_1)`, which implicitly depends on the parameters ``p``. - -dev = qml.device("default.qubit", range(4)) - -ts = jnp.array([0., 3.]) -H_obj = sum([qml.PauliZ(i) for i in range(4)]) - -@jax.jit -@qml.qnode(dev, interface="jax") -def qnode(params): - qml.evolve(Ht)(params, ts) - return qml.expval(H_obj) - -print(qnode(params)) - -############################################################################## -# We used the decorator ``jax.jit`` to compile this execution just-in-time. This means the first execution will typically take a little longer with the -# benefit that all following executions will be significantly faster, see the `jax docs on jitting `_. JIT-compiling is optional, and one can remove the decorator when only single executions -# are of interest. -# # Gradients of pulse programs # --------------------------- # Internally, this program solves the the time-dependent Schrödinger equation using the `Dopri5 `_ solver for From 7a882427713d7990fbf60658ac158a769ac2a41b Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 27 Jan 2023 19:23:42 +0100 Subject: [PATCH 048/122] bug fix --- demonstrations/tutorial_pulse_programming101.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 8cf85d6cb4..475204c6f8 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -69,7 +69,7 @@ def f2(p, t): print(Ht(params, 0.5)) ############################################################################## -# We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using :func:`qml.ops.dot `. +# We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using :func:`qml.dot `. # We use two sinusodials with random frequencies as the time-dependent parametrization for each :math:`Z_i`. coeffs = [jnp.array(1.)] * 2 @@ -77,7 +77,7 @@ def f2(p, t): ops = [qml.PauliX(i) @ qml.PauliX(i+1) for i in range(2)] ops += [qml.PauliZ(i) for i in range(3)] -Ht = qml.ops.dot(coeffs, ops) +Ht = qml.dot(coeffs, ops) # random coefficients key = jax.random.PRNGKey(777) @@ -137,20 +137,20 @@ def qnode(params): # for different time bins. key = jax.random.PRNGKey(777) -params = jax.random.uniform(key, shape=[2, 10], maxval=5) +theta = jax.random.uniform(key, shape=[2, 10], maxval=5) ts = jnp.linspace(0., 10., 100)[:-1] fig, axs = plt.subplots(nrows=2, sharex=True) for i in range(2): ax = axs[i] - ax.plot(ts, coeffs[i](params[i], ts), ".-") + ax.plot(ts, coeffs[i](theta[i], ts), ".-") ############################################################################## # We can use these callables as usual to construct a :func:`~.pennylane.pulse.ParametrizedHamiltonian`. ops = [qml.PauliX(i) for i in range(2)] H = qml.pulse.ParametrizedHamiltonian(coeffs, ops) -print(H(params, 0.5)) +print(H(theta, 0.5)) ############################################################################## @@ -219,8 +219,8 @@ def ad(wires): omega = jnp.array([4.8080, 4.8333]) g = jnp.array([0.01831, 0.02131]) -H_D = qml.ops.dot(omega, [ad(i) @ a(i) for i in range(n_wires)]) -H_D += qml.ops.dot(g, [ad(i) @ a((i+1)%n_wires) + ad((i+1)%n_wires) @ a(i) for i in range(n_wires)]) +H_D = qml.dot(omega, [ad(i) @ a(i) for i in range(n_wires)]) +H_D += qml.dot(g, [ad(i) @ a((i+1)%n_wires) + ad((i+1)%n_wires) @ a(i) for i in range(n_wires)]) ############################################################################## # The system is driven under the control term @@ -255,7 +255,7 @@ def wrapped(p, t): ops = [a(i) for i in range(n_wires)] ops += [ad(i) for i in range(n_wires)] -H_C = qml.ops.dot(fs, ops) +H_C = qml.dot(fs, ops) ############################################################################## # Overall, we end up with the time-dependent parametrized Hamiltonian :math:`H(p, t) = H_D + H_C(p, t)` From 7c4b8ad0039a49a1244dbe74cdaf3f69c8d6e7f6 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 10 Feb 2023 13:05:46 +0100 Subject: [PATCH 049/122] nice result with clip and pwc and realistic values --- .../tutorial_pulse_programming101.py | 89 +++++++------------ 1 file changed, 32 insertions(+), 57 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 475204c6f8..0cef69edc8 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -191,7 +191,7 @@ def qnode(params): # coeffs, obs = H.coeffs, H.ops # H_obj = qml.Hamiltonian(jnp.array(coeffs), obs) -data = qml.data.load("qchem", molname="HeH+", basis="STO-3G", bondlength=0.82)[0] +data = qml.data.load("qchem", molname="HeH+", basis="STO-3G", bondlength=1.5)[0] H_obj = data.tapered_hamiltonian n_wires = len(H_obj.wires) @@ -216,8 +216,8 @@ def a(wires): def ad(wires): return 0.5*qml.PauliX(wires) - 0.5j* qml.PauliY(wires) -omega = jnp.array([4.8080, 4.8333]) -g = jnp.array([0.01831, 0.02131]) +omega = 2*jnp.pi* jnp.array([4.8080, 4.8333]) +g = 2*jnp.pi* jnp.array([0.01831, 0.02131]) H_D = qml.dot(omega, [ad(i) @ a(i) for i in range(n_wires)]) H_D += qml.dot(g, [ad(i) @ a((i+1)%n_wires) + ad((i+1)%n_wires) @ a(i) for i in range(n_wires)]) @@ -228,22 +228,13 @@ def ad(wires): # .. math:: H_C(t) = \sum_q \Omega_q(t) \left(e^{i\nu_q t} a_q + e^{-i\nu_q t} a^\dagger_q \right) # # with the (real) time-dependent amplitudes :math:`\Omega_q(t)` and frequencies :math:`\nu_q` of the drive. -# We let :math:`\Omega(t)` be a piece-wise-constant real function that is optimized alongside the frequencies :math:`\nu_q`. - -def normalize(z): - """eq. (8) in https://arxiv.org/pdf/2210.15812.pdf""" - def S(x): - return (1-jnp.exp(-x))/(1+jnp.exp(-x)) - absz = jnp.abs(z) - argz = jnp.angle(z) - return S(absz) * jnp.exp(1j*argz) +# We let :math:`\Omega(t)` be a piece-wise-constant real function that is optimized alongside the frequencies :math:`\nu_q`. +# We restrict the amplitude to :math:`\pm 20 \text{MHz}` to abide by realistic hardware constraints. def drive_field(T, omega, sign=1.): - # assuming len(p) = len(t_bins) + 1 for the frequency nu def wrapped(p, t): - #amp = jnp.clip(pwc(T)(p[:-1], t), -0.02, 0.02) - amp = qml.pulse.pwc(T)(p[:-1], t) - phase = jnp.exp(sign*1j*p[-1]*t) + amp = jnp.clip(qml.pulse.pwc(T)(p, t), -0.02, 0.02) + phase = jnp.exp(sign*1j*omega*t) return amp * phase return wrapped @@ -263,11 +254,9 @@ def wrapped(p, t): H_pulse = H_D + H_C -dev = qml.device("default.qubit", wires=range(n_wires)) - t_bins = 100 # number of time bins -key = jax.random.PRNGKey(666) -theta = 0.02*jax.random.uniform(key, shape=jnp.array([n_wires, t_bins + 1])) +key = jax.random.PRNGKey(42) +theta = 0.01*jax.random.uniform(key, shape=jnp.array([n_wires, t_bins])) # The step sizes are chosen adaptively, so there is in principle no need to provide @@ -277,49 +266,36 @@ def wrapped(p, t): # the fixed ones we provide. ts = jnp.linspace(0., duration, t_bins) +dev = qml.device("default.qubit", wires=range(n_wires)) + @qml.qnode(dev, interface="jax") def qnode(theta, t=ts): qml.BasisState(data.tapered_hf_state, wires=H_obj.wires) qml.evolve(H_pulse)(params=(*theta, *theta), t=t) return qml.expval(H_obj) -############################################################################## -# Our aim is to minimize the energy expectation value :math:`\langle H_\text{obj} \rangle` but we also need to take -# certain physical constraints into account. For example, the amplitude of the physical driving field :math:`\Omega(t)` cannot -# reach arbitrarily large values and cannot change arbitrarily quickly in time. We therefore add two penalty terms quantifying the -# mean absolute square of the amplitude and changes in the amplitude. The overall cost function is thus -# -# .. math:: \mathcal{C}(p) = \langle H_\text{obj} \rangle + \frac{1}{N_p} \sum_{ki} |p^k_i|^2 + \frac{1}{N_p} \sum_{ki} |p^k_i - p^k_{i-1}|^2, -# -# where :math:`N_p` is the total number of drive field amplitude segments. Ther resulting values are within the realm of possbility in real devices, :math:`\mathcal{O}(10^7 \text{Hz})`. - -def abs_diff(p): - """compute |p_i - p_i-1|^2""" - return jnp.mean(jnp.abs(jnp.diff(p, axis=1))**2) - -def cost_fn(params): - # params.shape = (n_wires, {n_bins}+1) - p = params[:, :-1] - C_exp = qnode(params) # expectation value - C_par = jnp.mean(jnp.abs(p)**2) # parameter values - C_der = abs_diff(p) # derivative values - return C_exp + 3*C_par + 3*C_der - ############################################################################## # We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax``, a package for optimizations in ``jax``. import optax from datetime import datetime -n_epochs = 50 -optimizer = optax.adabelief(learning_rate=0.2) #adabelief +n_epochs = 100 +optimizer = optax.adabelief(learning_rate=1e-2) #adabelief opt_state = optimizer.init(theta) -value_and_grad = jax.jit(jax.value_and_grad(cost_fn)) +value_and_grad = jax.jit(jax.value_and_grad(qnode)) energy = np.zeros(n_epochs) cost = np.zeros(n_epochs) theta_i = [theta] +############################################################################## +# The optimization is dependent on three hyper parameters that we have access to: +# * The learning rate +# * The initial values +# * The strength of the penalty terms +# Reducing the magnitude of the initial values gives a better guess close to # + ## Compile the evaluation and gradient function and report compilation time time0 = datetime.now() _ = value_and_grad(theta) @@ -343,17 +319,15 @@ def cost_fn(params): ############################################################################## # placeholder: comment on resulting curve when example is fixed. -fig, axs = plt.subplots(nrows=2, figsize=(5,5), sharex=True) -ax = axs[0] -ax.plot(energy, ".:", label="$\\langle H_{{obj}}\\rangle (p)$") -ax.plot([0, n_epochs], [E_exact]*2, ":", label="$E_{{min}}$", color="grey") -ax.set_ylabel("Energy") -ax.legend() +fig, ax = plt.subplots(nrows=1, figsize=(5,3), sharex=True) -ax = axs[1] -ax.plot(cost,".:", label="$C(p)$") +y = np.array(energy) - E_exact +ax.plot(y, ".:", label="$\\langle H_{{obj}}\\rangle - E_{{FCI}}$") +ax.fill_between([0, len(y)-1], [1e-3]*2, 5e-4, alpha=0.2, label="chem acc.") +ax.set_yscale("log") +ax.set_ylabel("Energy ($E_H$)") ax.set_xlabel("epoch") -ax.set_ylabel("Cost") +ax.legend() plt.tight_layout() plt.show() @@ -366,13 +340,14 @@ def cost_fn(params): fs = H_pulse.coeffs_parametrized[:n_wires] n_channels = len(fs) -fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels)) +fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels), sharex=True) for n in range(n_channels): ax = axs[n] amp = fs[n](theta[n], ts) - ax.plot(ts, jnp.sign(amp) * jnp.abs(amp), ".:", label=f"$\\nu$_{n}: {jnp.angle(fs[n](theta[n], 1.))/jnp.pi:.3}/$\\pi$") - ax.set_ylabel(f"amplitude_{n}") + ax.plot(ts, np.clip(theta[n], -0.02, 0.02), ".:", label=f"$\\nu$_{n}: {omega[n]/2/jnp.pi:.3}/$2\\pi$") + ax.set_ylabel(f"amp_{n} (GHz)") ax.legend() +ax.set_xlabel("t (ns)") plt.tight_layout() plt.show() From 004532babb1590dc545ecb823946c722111756d5 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 10 Feb 2023 17:05:48 +0100 Subject: [PATCH 050/122] update text --- .../tutorial_pulse_programming101.py | 38 +++++++------------ 1 file changed, 14 insertions(+), 24 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 0cef69edc8..bc5dd2618e 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -176,32 +176,12 @@ def qnode(params): # We are going to look at :math:`H_3^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. # -# symbols = ["H", "H", "H"] -# coordinates = np.array([-0.0399, -0.0038, 0.0, 1.5780, 0.8540, 0.0, 2.7909, -0.5159, 0.0]) - -# basis_set = "sto-3g" -# H, n_wires = qml.qchem.molecular_hamiltonian( -# symbols, -# coordinates, -# basis=basis_set, -# method='pyscf', -# mult=2 -# ) - -# coeffs, obs = H.coeffs, H.ops -# H_obj = qml.Hamiltonian(jnp.array(coeffs), obs) - data = qml.data.load("qchem", molname="HeH+", basis="STO-3G", bondlength=1.5)[0] H_obj = data.tapered_hamiltonian +H_obj = qml.Hamiltonian(jnp.array(H_obj.coeffs), H_obj.ops) +E_exact = data.fci_energy n_wires = len(H_obj.wires) -############################################################################## -# For such small systems, we can of course compute the exact ground state energy. -# We will later use this to determine if our ctrl-VQE algorithm was successful. - -H_obj_m = qml.matrix(H_obj) -E_exact = data.fci_energy #np.min(np.linalg.eigvalsh(H_obj_m)) - ############################################################################## # As a realistic physical system to simulate, we are considering a coupled transmon qubit system with the constant drift term Hamiltonian # @@ -254,8 +234,18 @@ def wrapped(p, t): H_pulse = H_D + H_C +############################################################################## +# The success of the optimization is sensitive to the initial values of the parameters. +# We choose ``t_bins = 100`` segments for the piece-wise-constant parametrization of the pulses. +# We showcase a good random seed here. In reality, this experiment would have to +# repeated multiple times with different random initializations. More physically informed +# initial values are always appreciated, though for pulse programs, intuition is still lacking +# as of now. The Hartree-Fock state is always a good starting point, i.e. choosing all parameters to zero. +# However, this is contrasted by zero gradient at this setting, which is why we choose a trade-off in reducing +# the initial amplitude of the random values. + t_bins = 100 # number of time bins -key = jax.random.PRNGKey(42) +key = jax.random.PRNGKey(999) theta = 0.01*jax.random.uniform(key, shape=jnp.array([n_wires, t_bins])) @@ -270,7 +260,7 @@ def wrapped(p, t): @qml.qnode(dev, interface="jax") def qnode(theta, t=ts): - qml.BasisState(data.tapered_hf_state, wires=H_obj.wires) + qml.BasisState(list(data.tapered_hf_state), wires=H_obj.wires) qml.evolve(H_pulse)(params=(*theta, *theta), t=t) return qml.expval(H_obj) From 97b0adf4b8cf9fcdf3669bd123f8436525b1d3fe Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 10 Feb 2023 17:59:54 +0100 Subject: [PATCH 051/122] update text --- .../tutorial_pulse_programming101.py | 73 ++++++++++--------- 1 file changed, 38 insertions(+), 35 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index bc5dd2618e..699602c19e 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -13,7 +13,7 @@ Pulses in quantum computers --------------------------- -In many quantum computing architectures such as superconducting and ion trap systems, qubits are realized through physical systems with a discrete set of energy levels. +In many quantum computing architectures such as superconducting ion trap and Rydberg systems, qubits are realized through physical systems with a discrete set of energy levels. For example, transmon qubits realize an anharmonic oscillator whose ground and first excited states can serve as the two energy levels of a qubit. Such a qubit can be controlled via an electromagnetic field tuned to its energy gap. In general, this electromangnetic field can be altered in time, leading to a time-dependent Hamiltonian interaction :math:`H(t)`. @@ -25,7 +25,7 @@ following a unitary evolution :math:`U(t_0, t_1)` of the input state from time :math:`t_0` to :math:`t_1`, i.e. :math:`|\psi(t_1)\rangle = U(t_0, t_1) |\psi(t_0)\rangle`. -In non-measurement-based digital quantum computers, the amplitude and frequencies of predefined pulse sequences are +In most digital quantum computers (with the exception of measurement-based architectures), the amplitude and frequencies of predefined pulse sequences are fine tuned to realize the native gates of the quantum computer. More specifically, the Hamiltonian interaction :math:`H(t)` is tuned such that the respective evolution :math:`U(t_0, t_1)` realizes for example a Pauli or CNOT gate. @@ -103,7 +103,7 @@ def f2(p, t): ############################################################################## # -# A pulse program is then executed by using the :func:`~.pennylane.ops.evolve` transform to create the evolution +# A pulse program is then executed by using the :func:`~evolve` transform to create the evolution # gate :math:`U(t_0, t_1)`, which implicitly depends on the parameters ``p``. dev = qml.device("default.qubit", range(4)) @@ -126,14 +126,14 @@ def qnode(params): ############################################################################## # PennyLane also provides a variety of convenience functions to enable for example piece-wise-constant parametrizations, -# i.e. defining the function values at fixed time bins as parameters. We can construct such a callable with :func:`~.pennylane.pulse.pwc` +# i.e. defining the function values at fixed time bins as parameters. We can construct such a callable with :func:`~pennylane.pulse.pwc` # by providing a ``timespan`` argument that is either a total time (``float``) or a tuple ``(t0, t1)``. timespan = 10. -coeffs = [qml.pulse.pwc(timespan) for i in range(2)] +coeffs = [qml.pulse.pwc(timespan) for _ in range(2)] ############################################################################## -# This creates a callable with signature ``(p, t)`` that returns ``p[int(t/duration)]``, such that the passed parameters are the function values +# This creates a callable with signature ``(p, t)`` that returns ``p[int(len(p)*t/duration)]``, such that the passed parameters are the function values # for different time bins. key = jax.random.PRNGKey(777) @@ -171,9 +171,9 @@ def qnode(params): # # Variational quantum eigensolver with pulse programming # ------------------------------------------------------ -# We can now use those gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Asthana2022]_. +# We can now use those gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. # First, we define the molecular Hamiltonian whose energy estimate we want to minimize. -# We are going to look at :math:`H_3^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. +# We are going to look at :math:`\text{HeH}^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. # data = qml.data.load("qchem", molname="HeH+", basis="STO-3G", bondlength=1.5)[0] @@ -189,7 +189,7 @@ def qnode(params): # # with bosonic creation and annihilation operators. The quadratic part propotional to :math:`\delta_q` is describing the anharmonic contribution to higher energy levels. # We are only going to consider the qubit subspace such that this term is zero. -# The order of magnitude of the resonance frequencies :math:`\omega_q` and coupling strength :math:`g_{pq}` are taken from [#Asthana2022]_ (in GHz). +# The order of magnitude of the resonance frequencies :math:`\omega_q` and coupling strength :math:`g_{pq}` are taken from [#Mitei]_ (in GHz). def a(wires): return 0.5*qml.PauliX(wires) + 0.5j* qml.PauliY(wires) @@ -208,7 +208,8 @@ def ad(wires): # .. math:: H_C(t) = \sum_q \Omega_q(t) \left(e^{i\nu_q t} a_q + e^{-i\nu_q t} a^\dagger_q \right) # # with the (real) time-dependent amplitudes :math:`\Omega_q(t)` and frequencies :math:`\nu_q` of the drive. -# We let :math:`\Omega(t)` be a piece-wise-constant real function that is optimized alongside the frequencies :math:`\nu_q`. +# We let :math:`\Omega(t)` be a piece-wise-constant real function whose values are optimized. +# In principle one can also optimize the drive frequency :math:`\nu_q`, but we already find good results by setting it to the qubit frequencies. # We restrict the amplitude to :math:`\pm 20 \text{MHz}` to abide by realistic hardware constraints. def drive_field(T, omega, sign=1.): @@ -235,19 +236,10 @@ def wrapped(p, t): H_pulse = H_D + H_C ############################################################################## -# The success of the optimization is sensitive to the initial values of the parameters. -# We choose ``t_bins = 100`` segments for the piece-wise-constant parametrization of the pulses. -# We showcase a good random seed here. In reality, this experiment would have to -# repeated multiple times with different random initializations. More physically informed -# initial values are always appreciated, though for pulse programs, intuition is still lacking -# as of now. The Hartree-Fock state is always a good starting point, i.e. choosing all parameters to zero. -# However, this is contrasted by zero gradient at this setting, which is why we choose a trade-off in reducing -# the initial amplitude of the random values. +# We choose ``t_bins = 100`` segments for the piece-wise-constant parametrization of the pulses +# and define the ``qnode`` that computes the expectation value of the molecular Hamiltonian. t_bins = 100 # number of time bins -key = jax.random.PRNGKey(999) -theta = 0.01*jax.random.uniform(key, shape=jnp.array([n_wires, t_bins])) - # The step sizes are chosen adaptively, so there is in principle no need to provide # explicit time steps. However, because the pwc function can be discontinuous it makes @@ -266,25 +258,30 @@ def qnode(theta, t=ts): ############################################################################## # We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax``, a package for optimizations in ``jax``. +# The success of the optimization is sensitive to the initial values of the parameters. +# We showcase a good random seed here. In reality, this optimization easily gets stuck in local minima +# such that we would have to repeat the experiment multiple times with different random initializations. +# On the other hand, the Hartree-Fock state is usually a good starting point, i.e. choosing all parameters to zero. +# However, this results in a near-zero gradient in our case. This is why we choose a trade-off by reducing +# the initial amplitude of the random values. +# +# Further, the optimization is sensitive to the choice of optimizer and learning rate, which can be subject to +# hyper parameter optimization. We here provide one of many possible choices leading to good results. + +key = jax.random.PRNGKey(999) +theta = 0.01*jax.random.uniform(key, shape=jnp.array([n_wires, t_bins])) + import optax from datetime import datetime n_epochs = 100 -optimizer = optax.adabelief(learning_rate=1e-2) #adabelief +optimizer = optax.adabelief(learning_rate=1e-2) opt_state = optimizer.init(theta) value_and_grad = jax.jit(jax.value_and_grad(qnode)) energy = np.zeros(n_epochs) cost = np.zeros(n_epochs) -theta_i = [theta] - -############################################################################## -# The optimization is dependent on three hyper parameters that we have access to: -# * The learning rate -# * The initial values -# * The strength of the penalty terms -# Reducing the magnitude of the initial values gives a better guess close to # ## Compile the evaluation and gradient function and report compilation time time0 = datetime.now() @@ -300,14 +297,13 @@ def qnode(theta, t=ts): energy[n] = qnode(theta) cost[n] = val - theta_i.append(theta) - if not n%5: + if not n%10: print(f"mean grad: {jnp.mean(grad_circuit)}") print(f"{n+1} / {n_epochs}; energy: {energy[n]}; cost: {val}") ############################################################################## -# placeholder: comment on resulting curve when example is fixed. +# We see that we have converged well within chemical accuracy after half the number of epochs. fig, ax = plt.subplots(nrows=1, figsize=(5,3), sharex=True) @@ -324,8 +320,7 @@ def qnode(theta, t=ts): ############################################################################## # We can also visualize the envelopes for each qubit in time. -# Because the field is complex valued with :math:`\Omega(t) e^{-i\nu_q t}` we plot only -# :math:`\Omega(t)` and indicate the numerical value of :math:`\nu_q`. +# We only plot the real amplitude :math:`\Omega(t)` without the qubit frequency modulation. fs = H_pulse.coeffs_parametrized[:n_wires] @@ -358,12 +353,20 @@ def qnode(theta, t=ts): # Differentiable Analog Quantum Computing for Optimization and Control # `arXiv:2210.15812 `__, 2022 # +# .. [#Mitei] +# +# Oinam Romesh Meitei, Bryan T. Gard, George S. Barron, David P. Pappas, Sophia E. Economou, Edwin Barnes, Nicholas J. Mayhall +# Gate-free state preparation for fast variational quantum eigensolver simulations: ctrl-VQE +# `arXiv:2008.04302 `__, 2020 +# # .. [#Asthana2022] # # Ayush Asthana, Chenxu Liu, Oinam Romesh Meitei, Sophia E. Economou, Edwin Barnes, Nicholas J. Mayhall # "Minimizing state preparation times in pulse-level variational molecular simulations." # `arXiv:2203.06818 `__, 2022. # +# +# ############################################################################## From 5732a4490930c913968d83a662e735f89933dbdb Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 10 Feb 2023 18:25:06 +0100 Subject: [PATCH 052/122] conclusion --- demonstrations/tutorial_pulse_programming101.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 699602c19e..65bbc486fa 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -321,6 +321,8 @@ def qnode(theta, t=ts): ############################################################################## # We can also visualize the envelopes for each qubit in time. # We only plot the real amplitude :math:`\Omega(t)` without the qubit frequency modulation. +# Note that we obtain bang-bang like solutions as indicated in [#Asthana2022]_, making it +# likely we are close to the minimal evolution time with ``15ns``. fs = H_pulse.coeffs_parametrized[:n_wires] @@ -341,8 +343,14 @@ def qnode(theta, t=ts): # # Conclusion # ---------- -# Conclusion -# +# Pulse programming is an exciting new field within noisy quantum computing. By skipping the digital abstraction, one can +# write variational programs on the hardware level, potentially minimizing the computation time. This then ideally leads to effectively deeper +# circuits on noisy hardware. +# On the other hand, the possibility to continuously vary the Hamiltonian interaction in time significantly increases +# the parameter space. A good parametrization trading off flexibility and number of parameters is therefore necessary as systems scale up. +# Further, the increased flexibility also affects the search space in Hilbert space that pulse gates can reach. +# Barren plateaus in variational quantum algorithms are typically due to a lack of a good inductive bias in the ansatz, i.e. having a search space that is too large. +# It is therefore crucial to find physically motivated ansätze for pulse programs. # # References # ---------- From f8d59d033f9d73bcf6fa8c707e333972dc889e83 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 10 Feb 2023 18:41:07 +0100 Subject: [PATCH 053/122] adabelief --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 65bbc486fa..9befa06324 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -257,7 +257,7 @@ def qnode(theta, t=ts): return qml.expval(H_obj) ############################################################################## -# We now have all the ingredients to run our ctrl-VQE program. We use the adam implementation in ``optax``, a package for optimizations in ``jax``. +# We now have all the ingredients to run our ctrl-VQE program. We use the ``adabelief`` implementation in ``optax``, a package for optimizations in ``jax``. # The success of the optimization is sensitive to the initial values of the parameters. # We showcase a good random seed here. In reality, this optimization easily gets stuck in local minima # such that we would have to repeat the experiment multiple times with different random initializations. From 2a1f1ffccb3300962f86bb10b2e2a935a99c5fbb Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Fri, 10 Feb 2023 18:44:43 +0100 Subject: [PATCH 054/122] paper titles in quotation marks --- demonstrations/tutorial_pulse_programming101.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 9befa06324..09848315dc 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -358,13 +358,13 @@ def qnode(theta, t=ts): # .. [#Leng2022] # # Jiaqi Leng, Yuxiang Peng, Yi-Ling Qiao, Ming Lin, Xiaodi Wu -# Differentiable Analog Quantum Computing for Optimization and Control +# "Differentiable Analog Quantum Computing for Optimization and Control" # `arXiv:2210.15812 `__, 2022 # # .. [#Mitei] # # Oinam Romesh Meitei, Bryan T. Gard, George S. Barron, David P. Pappas, Sophia E. Economou, Edwin Barnes, Nicholas J. Mayhall -# Gate-free state preparation for fast variational quantum eigensolver simulations: ctrl-VQE +# "Gate-free state preparation for fast variational quantum eigensolver simulations: ctrl-VQE" # `arXiv:2008.04302 `__, 2020 # # .. [#Asthana2022] From bd5c2e75a275297b8dedcdc90e9d82e078e0ebe1 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 10:35:54 +0100 Subject: [PATCH 055/122] anharmonic resolved --- demonstrations/tutorial_pulse_programming101.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 09848315dc..8d97f6399b 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -187,8 +187,8 @@ def qnode(params): # # .. math:: H_D = \sum_q \omega_q a_q^\dagger a_q + \sum_q \frac{\delta_q}{2} a^\dagger_q a^\dagger_q a_q a_q + \sum_{\braket{pq}} g_{pq} a^\dagger_p a_q # -# with bosonic creation and annihilation operators. The quadratic part propotional to :math:`\delta_q` is describing the anharmonic contribution to higher energy levels. -# We are only going to consider the qubit subspace such that this term is zero. +# with bosonic creation and annihilation operators. The anharmonicity :math:`\delta_q` is describing the contribution to higher energy levels. +# We are only going to consider the qubit subspace and hence set this term to zero. # The order of magnitude of the resonance frequencies :math:`\omega_q` and coupling strength :math:`g_{pq}` are taken from [#Mitei]_ (in GHz). def a(wires): From 342ff848554cd3bc0f65d5f6f754dc946ff6c567 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 10:55:30 +0100 Subject: [PATCH 056/122] absolute of mean gradient --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 8d97f6399b..5e12017b1f 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -299,7 +299,7 @@ def qnode(theta, t=ts): cost[n] = val if not n%10: - print(f"mean grad: {jnp.mean(grad_circuit)}") + print(f"mean grad: {jnp.mean(jnp.abs(grad_circuit))}") print(f"{n+1} / {n_epochs}; energy: {energy[n]}; cost: {val}") ############################################################################## From db37d1850c8efb403774c4eb983ffabc9f8ebb19 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 10:56:49 +0100 Subject: [PATCH 057/122] review comment --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 5e12017b1f..33d1890fcb 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -309,7 +309,7 @@ def qnode(theta, t=ts): y = np.array(energy) - E_exact ax.plot(y, ".:", label="$\\langle H_{{obj}}\\rangle - E_{{FCI}}$") -ax.fill_between([0, len(y)-1], [1e-3]*2, 5e-4, alpha=0.2, label="chem acc.") +ax.fill_between([0, len(y)], [1e-3]*2, 5e-4, alpha=0.2, label="chem acc.") ax.set_yscale("log") ax.set_ylabel("Energy ($E_H$)") ax.set_xlabel("epoch") From 873a3141026ad841b2ed6350483c106eb91f7005 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 10:57:51 +0100 Subject: [PATCH 058/122] review comment label in pulse plot --- demonstrations/tutorial_pulse_programming101.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 33d1890fcb..d42e0379eb 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -330,8 +330,8 @@ def qnode(theta, t=ts): fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels), sharex=True) for n in range(n_channels): ax = axs[n] - amp = fs[n](theta[n], ts) - ax.plot(ts, np.clip(theta[n], -0.02, 0.02), ".:", label=f"$\\nu$_{n}: {omega[n]/2/jnp.pi:.3}/$2\\pi$") + label=f"$\\nu$_{n}: {omega[n]/2/jnp.pi:.3}/$2\\pi$" + ax.plot(ts, np.clip(theta[n], -0.02, 0.02), ".:", label=label) ax.set_ylabel(f"amp_{n} (GHz)") ax.legend() ax.set_xlabel("t (ns)") From 1ca947ece499b16daa059f92396e71b1901a50d3 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 11:00:00 +0100 Subject: [PATCH 059/122] review comment qc overview page --- demos_quantum-computing.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/demos_quantum-computing.rst b/demos_quantum-computing.rst index 37120ac8f4..52945442d5 100644 --- a/demos_quantum-computing.rst +++ b/demos_quantum-computing.rst @@ -108,19 +108,18 @@ such as benchmarking and characterizing quantum processors. :figure: demonstrations/mbqc/thumbnail_mbqc.png :description: :doc:`demos/tutorial_mbqc` :tags: quantumcomputing MBQC - -.. gallery-item:: - :tooltip: Simulating differentialble pulse programs in PennyLane - :figure: demonstrations/pulse_programming101/thumb_temporary.png - :description: :doc:`demos/tutorial_pulse_programming101` - :tags: jax pulses pulse programming gate quantum optimal control - .. gallery-item:: :tooltip: Test if a system possesses discrete symmetries :figure: demonstrations/testing_symmetry/thumbnail_tutorial_testing_symmetry.jpg :description: :doc:`demos/tutorial_testing_symmetry` :tags: quantumcomputing symmetry + +.. gallery-item:: + :tooltip: Simulate differentiable pulse programs with qubits in PennyLane + :figure: demonstrations/pulse_programming101/thumb_temporary.png + :description: :doc:`demos/tutorial_pulse_programming101` + :tags: jax pulses pulse programming gate quantum optimal control :html:`
` From 806cd1e7de4bca2eeb4f5b9b97daef2939a411c3 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann <43949391+Qottmann@users.noreply.github.com> Date: Mon, 13 Feb 2023 02:02:33 -0800 Subject: [PATCH 060/122] Apply suggestions from code review Co-authored-by: David Wierichs --- .../tutorial_pulse_programming101.py | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index d42e0379eb..045116a58f 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -37,7 +37,7 @@ For noisy and intermediate sized quantum computers, the abstraction of decomposing quantum algorithms into a fixed native gate set can be a hindrance and unnecessarily increase execution time, therefore leading to more noise in the computation. The idea of differentiable pulse programming is to optimize quantum circuits on the pulse -level with the aim of achieving the shortest interaction sequence a hardware system allows. +level instead, with the aim of achieving the shortest interaction sequence a hardware system allows. In PennyLane, we can simulate arbitrary qubit system interactions to explore the possibilities of such pulse programs. First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p, t) H_i` with constant operators :math:`H_i` and driving fields :math:`f_i(p, t)` that may @@ -70,7 +70,7 @@ def f2(p, t): ############################################################################## # We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using :func:`qml.dot `. -# We use two sinusodials with random frequencies as the time-dependent parametrization for each :math:`Z_i`. +# We use two sinusoids with random frequencies as the time-dependent parametrization for each :math:`Z_i`. coeffs = [jnp.array(1.)] * 2 coeffs += [lambda p, t: jnp.sin(p[0]*t) + jnp.sin(p[1]*t) for _ in range(3)] @@ -92,12 +92,12 @@ def f2(p, t): fs = Ht.coeffs_parametrized ops = Ht.ops_parametrized n_channels = len(fs) -fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels)) +fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels), gridspec_kw={"hspace": 0}) for n in range(n_channels): ax = axs[n] ax.plot(ts, fs[n](params[n], ts)) ax.set_ylabel(f"Z_{n}") -axs[0].set_title(f"Drift term: X_0 X_1 + X_1 X_2") +axs[0].set_title(f"Drift term: $X_0 X_1 + X_1 X_2$") plt.tight_layout() plt.show() @@ -125,9 +125,9 @@ def qnode(params): # are of interest. ############################################################################## -# PennyLane also provides a variety of convenience functions to enable for example piece-wise-constant parametrizations, +# PennyLane also provides a variety of convenience functions to create for example piece-wise-constant parametrizations, # i.e. defining the function values at fixed time bins as parameters. We can construct such a callable with :func:`~pennylane.pulse.pwc` -# by providing a ``timespan`` argument that is either a total time (``float``) or a tuple ``(t0, t1)``. +# by providing a ``timespan`` argument which is expected to be either a total time (``float``) or a start and end time (``tuple``). timespan = 10. coeffs = [qml.pulse.pwc(timespan) for _ in range(2)] @@ -146,7 +146,7 @@ def qnode(params): ax.plot(ts, coeffs[i](theta[i], ts), ".-") ############################################################################## -# We can use these callables as usual to construct a :func:`~.pennylane.pulse.ParametrizedHamiltonian`. +# We can use these callables as before to construct a :func:`~.pennylane.pulse.ParametrizedHamiltonian`. ops = [qml.PauliX(i) for i in range(2)] H = qml.pulse.ParametrizedHamiltonian(coeffs, ops) @@ -159,7 +159,7 @@ def qnode(params): # # Gradients of pulse programs # --------------------------- -# Internally, this program solves the the time-dependent Schrödinger equation using the `Dopri5 `_ solver for +# Internally, pulse programs in PennyLane solve the the time-dependent Schrödinger equation using the `Dopri5 `_ solver for # ordinary differential equations (ODEs). In particular, the step sizes between :math:`t_0` and :math:`t_1` are chosen adaptively to stay within a given error tolerance. # We can backpropagate through this ODE solver and obtain the gradient via ``jax.grad``. @@ -344,10 +344,10 @@ def qnode(theta, t=ts): # Conclusion # ---------- # Pulse programming is an exciting new field within noisy quantum computing. By skipping the digital abstraction, one can -# write variational programs on the hardware level, potentially minimizing the computation time. This then ideally leads to effectively deeper +# write variational programs on the hardware level, potentially minimizing the computation time. This then ideally allows for effectively deeper # circuits on noisy hardware. # On the other hand, the possibility to continuously vary the Hamiltonian interaction in time significantly increases -# the parameter space. A good parametrization trading off flexibility and number of parameters is therefore necessary as systems scale up. +# the parameter space. A good parametrization trading off flexibility and the number of parameters is therefore necessary as systems scale up. # Further, the increased flexibility also affects the search space in Hilbert space that pulse gates can reach. # Barren plateaus in variational quantum algorithms are typically due to a lack of a good inductive bias in the ansatz, i.e. having a search space that is too large. # It is therefore crucial to find physically motivated ansätze for pulse programs. From 53c56efb2df4c8a4026cc15caeacbfa9bbcc1aa1 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 11:09:52 +0100 Subject: [PATCH 061/122] move convenience after gradient, change pwc example to different shapes --- .../tutorial_pulse_programming101.py | 41 +++++++++++-------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 045116a58f..fd8a6f5654 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -124,7 +124,27 @@ def qnode(params): # benefit that all following executions will be significantly faster, see the `jax docs on jitting `_. JIT-compiling is optional, and one can remove the decorator when only single executions # are of interest. + +############################################################################## +# Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. +# For example, we will simulate a transmon qubit system in the ctrl-VQE example in the last section of this demo. +# +# Gradients of pulse programs +# --------------------------- +# Internally, pulse programs in PennyLane solve the the time-dependent Schrödinger equation using the `Dopri5 `_ solver for +# ordinary differential equations (ODEs). In particular, the step sizes between :math:`t_0` and :math:`t_1` are chosen adaptively to stay within a given error tolerance. +# We can backpropagate through this ODE solver and obtain the gradient via ``jax.grad``. + +print(jax.grad(qnode)(params)) + +############################################################################## +# Alternatively, one can compute the gradient with the parameter shift rule [#Leng2022]_, which is particularly interesting for +# real hardware execution. In classical simulations, however, backpropagation is recommended. + + ############################################################################## +# Piece-wise-constant parametrizations +# ------------------------------------ # PennyLane also provides a variety of convenience functions to create for example piece-wise-constant parametrizations, # i.e. defining the function values at fixed time bins as parameters. We can construct such a callable with :func:`~pennylane.pulse.pwc` # by providing a ``timespan`` argument which is expected to be either a total time (``float``) or a start and end time (``tuple``). @@ -137,7 +157,8 @@ def qnode(params): # for different time bins. key = jax.random.PRNGKey(777) -theta = jax.random.uniform(key, shape=[2, 10], maxval=5) +subkeys = jax.random.split(key, 2) +theta = [jax.random.uniform(subkeys[i], shape=[num], maxval=5) for num in [10,30]] ts = jnp.linspace(0., 10., 100)[:-1] fig, axs = plt.subplots(nrows=2, sharex=True) @@ -146,29 +167,15 @@ def qnode(params): ax.plot(ts, coeffs[i](theta[i], ts), ".-") ############################################################################## +# Note how the number of time bins is implicitly defined through the length of the parameters, +# which we chose to be ``10`` and ``30`` in the example above, respectively. # We can use these callables as before to construct a :func:`~.pennylane.pulse.ParametrizedHamiltonian`. ops = [qml.PauliX(i) for i in range(2)] H = qml.pulse.ParametrizedHamiltonian(coeffs, ops) print(H(theta, 0.5)) - ############################################################################## -# Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. -# For example, we will simulate a transmon qubit system in the ctrl-VQE example in the last section of this demo. -# -# Gradients of pulse programs -# --------------------------- -# Internally, pulse programs in PennyLane solve the the time-dependent Schrödinger equation using the `Dopri5 `_ solver for -# ordinary differential equations (ODEs). In particular, the step sizes between :math:`t_0` and :math:`t_1` are chosen adaptively to stay within a given error tolerance. -# We can backpropagate through this ODE solver and obtain the gradient via ``jax.grad``. - -print(jax.grad(qnode)(params)) - -############################################################################## -# Alternatively, one can compute the gradient with the parameter shift rule [#Leng2022]_, which is particularly interesting for -# real hardware execution. In classical simulations, however, backpropagation is recommended. -# # Variational quantum eigensolver with pulse programming # ------------------------------------------------------ # We can now use those gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. From 5f794022228983aea6cfa8ec1f8b2f1ebdc6f200 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 11:11:46 +0100 Subject: [PATCH 062/122] merging sections --- demonstrations/tutorial_pulse_programming101.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index fd8a6f5654..1812825632 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -123,9 +123,7 @@ def qnode(params): # We used the decorator ``jax.jit`` to compile this execution just-in-time. This means the first execution will typically take a little longer with the # benefit that all following executions will be significantly faster, see the `jax docs on jitting `_. JIT-compiling is optional, and one can remove the decorator when only single executions # are of interest. - - -############################################################################## +# # Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. # For example, we will simulate a transmon qubit system in the ctrl-VQE example in the last section of this demo. # From 5c978c22ac647a7361dbb92a776d9247ae220549 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 11:15:52 +0100 Subject: [PATCH 063/122] tapering comment and realistic physical system --- demonstrations/tutorial_pulse_programming101.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 1812825632..073896e05e 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -179,7 +179,7 @@ def qnode(params): # We can now use those gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. # First, we define the molecular Hamiltonian whose energy estimate we want to minimize. # We are going to look at :math:`\text{HeH}^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. -# +# We are going to use the tapered Hamiltonian which makes use of symmetries to reduce the number of qubits, see :doc:`tutorial_qubit_tapering` for details. data = qml.data.load("qchem", molname="HeH+", basis="STO-3G", bondlength=1.5)[0] H_obj = data.tapered_hamiltonian @@ -188,7 +188,7 @@ def qnode(params): n_wires = len(H_obj.wires) ############################################################################## -# As a realistic physical system to simulate, we are considering a coupled transmon qubit system with the constant drift term Hamiltonian +# As a realistic physical system with pulse level control, we are considering a coupled transmon qubit system with the constant drift term Hamiltonian # # .. math:: H_D = \sum_q \omega_q a_q^\dagger a_q + \sum_q \frac{\delta_q}{2} a^\dagger_q a^\dagger_q a_q a_q + \sum_{\braket{pq}} g_{pq} a^\dagger_p a_q # From d8d6ba48cfff348bb6774d17291ce7737b368288 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 11:27:33 +0100 Subject: [PATCH 064/122] comment about canceling exponents GHz and ns --- demonstrations/tutorial_pulse_programming101.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 073896e05e..5d2ea42143 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -236,7 +236,9 @@ def wrapped(p, t): ############################################################################## # Overall, we end up with the time-dependent parametrized Hamiltonian :math:`H(p, t) = H_D + H_C(p, t)` -# under which the system is evolved for the given time window of ``15ns``. +# under which the system is evolved for the given time window of ``15ns``. Note that we are expressing time +# in nanoseconds (:math:`10^{-9}`s) and frequencies in gigahertz (:math:`10^{9}`Hz), such that both +# exponents cancel. H_pulse = H_D + H_C From 94dcb9cd2ab58ed9c9c8dd87ab9ee8c489f8a0e4 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 11:53:32 +0100 Subject: [PATCH 065/122] bug fix local run --- demonstrations/tutorial_pulse_programming101.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 5d2ea42143..dc9aa3ae10 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -156,7 +156,7 @@ def qnode(params): key = jax.random.PRNGKey(777) subkeys = jax.random.split(key, 2) -theta = [jax.random.uniform(subkeys[i], shape=[num], maxval=5) for num in [10,30]] +theta = [jax.random.uniform(subkeys[i], shape=[num], maxval=5) for i, num in enumerate([10,30])] ts = jnp.linspace(0., 10., 100)[:-1] fig, axs = plt.subplots(nrows=2, sharex=True) @@ -237,7 +237,7 @@ def wrapped(p, t): ############################################################################## # Overall, we end up with the time-dependent parametrized Hamiltonian :math:`H(p, t) = H_D + H_C(p, t)` # under which the system is evolved for the given time window of ``15ns``. Note that we are expressing time -# in nanoseconds (:math:`10^{-9}`s) and frequencies in gigahertz (:math:`10^{9}`Hz), such that both +# in nanoseconds (:math:`10^{-9}` s) and frequencies in gigahertz (:math:`10^{9}` Hz), such that both # exponents cancel. H_pulse = H_D + H_C @@ -264,7 +264,7 @@ def qnode(theta, t=ts): return qml.expval(H_obj) ############################################################################## -# We now have all the ingredients to run our ctrl-VQE program. We use the ``adabelief`` implementation in ``optax``, a package for optimizations in ``jax``. +# We now have all the ingredients to run our ctrl-VQE program. We use the ``adabelief`` implementation in `optax `_, a package for optimizations in ``jax``. # The success of the optimization is sensitive to the initial values of the parameters. # We showcase a good random seed here. In reality, this optimization easily gets stuck in local minima # such that we would have to repeat the experiment multiple times with different random initializations. From 96dc7b4c0d27cdd46ebf203cbf3acfa94cb3e5f6 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 18:30:13 +0100 Subject: [PATCH 066/122] abstract, num rename to shape --- demonstrations/tutorial_pulse_programming101.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index dc9aa3ae10..377f9b86b4 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -7,8 +7,8 @@ *Author: Korbinian Kottmann — Posted: 20 February 2023. -In this demo we are going to introduce pulse operations in PennyLane and run the -ctrl-VQE algorithm for an example molecule. +In this demo we are going to introduce pulse programming with qubits in PennyLane and run the +ctrl-VQE algorithm on a two-qubit Hamiltonian (HeH+). Pulses in quantum computers --------------------------- @@ -156,7 +156,7 @@ def qnode(params): key = jax.random.PRNGKey(777) subkeys = jax.random.split(key, 2) -theta = [jax.random.uniform(subkeys[i], shape=[num], maxval=5) for i, num in enumerate([10,30])] +theta = [jax.random.uniform(subkeys[i], shape=[shape], maxval=5) for i, shape in enumerate([4, 10])] ts = jnp.linspace(0., 10., 100)[:-1] fig, axs = plt.subplots(nrows=2, sharex=True) From 7e93710c8eaed7ed8ccb59dd06b82a24d7ba56a0 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 13 Feb 2023 18:30:46 +0100 Subject: [PATCH 067/122] shapes in text --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 377f9b86b4..d5c509f7ad 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -166,7 +166,7 @@ def qnode(params): ############################################################################## # Note how the number of time bins is implicitly defined through the length of the parameters, -# which we chose to be ``10`` and ``30`` in the example above, respectively. +# which we chose to be ``4`` and ``10`` in the example above, respectively. # We can use these callables as before to construct a :func:`~.pennylane.pulse.ParametrizedHamiltonian`. ops = [qml.PauliX(i) for i in range(2)] From 59940195f3b3b1147b2f1ea95a21c6cd797c1aca Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Tue, 14 Feb 2023 12:17:13 +0100 Subject: [PATCH 068/122] update optimizer and learning rate remark --- demonstrations/tutorial_pulse_programming101.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index d5c509f7ad..512d7dfd52 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -272,8 +272,9 @@ def qnode(theta, t=ts): # However, this results in a near-zero gradient in our case. This is why we choose a trade-off by reducing # the initial amplitude of the random values. # -# Further, the optimization is sensitive to the choice of optimizer and learning rate, which can be subject to -# hyper parameter optimization. We here provide one of many possible choices leading to good results. +# Further, we note that with the increase in the number of parameters due to the continuous evolution, the optimization +# becomes harder. In particular, besides the random initilization, the optimization is also very sensitive to the choice of +# optimizer and learning rate. We systematically tried a variety of combinations and provide one possible choice leading to good results. key = jax.random.PRNGKey(999) theta = 0.01*jax.random.uniform(key, shape=jnp.array([n_wires, t_bins])) From 1d45b04cec2342d0ea731fbcc4490b09692f0998 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 15 Feb 2023 12:35:25 +0100 Subject: [PATCH 069/122] minus sign in anharmonicity definition --- demonstrations/tutorial_pulse_programming101.py | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 512d7dfd52..faf5861d73 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -190,7 +190,7 @@ def qnode(params): ############################################################################## # As a realistic physical system with pulse level control, we are considering a coupled transmon qubit system with the constant drift term Hamiltonian # -# .. math:: H_D = \sum_q \omega_q a_q^\dagger a_q + \sum_q \frac{\delta_q}{2} a^\dagger_q a^\dagger_q a_q a_q + \sum_{\braket{pq}} g_{pq} a^\dagger_p a_q +# .. math:: H_D = \sum_q \omega_q a_q^\dagger a_q - \sum_q \frac{\delta_q}{2} a^\dagger_q a^\dagger_q a_q a_q + \sum_{\braket{pq}} g_{pq} a^\dagger_p a_q # # with bosonic creation and annihilation operators. The anharmonicity :math:`\delta_q` is describing the contribution to higher energy levels. # We are only going to consider the qubit subspace and hence set this term to zero. @@ -288,8 +288,8 @@ def qnode(theta, t=ts): value_and_grad = jax.jit(jax.value_and_grad(qnode)) -energy = np.zeros(n_epochs) -cost = np.zeros(n_epochs) +energy = np.zeros(n_epochs+1) +energy[0] = qnode(theta) ## Compile the evaluation and gradient function and report compilation time time0 = datetime.now() @@ -303,12 +303,11 @@ def qnode(theta, t=ts): updates, opt_state = optimizer.update(grad_circuit, opt_state) theta = optax.apply_updates(theta, updates) - energy[n] = qnode(theta) - cost[n] = val + energy[n+1] = val if not n%10: print(f"mean grad: {jnp.mean(jnp.abs(grad_circuit))}") - print(f"{n+1} / {n_epochs}; energy: {energy[n]}; cost: {val}") + print(f"{n+1} / {n_epochs}; energy: {energy[n]}") ############################################################################## # We see that we have converged well within chemical accuracy after half the number of epochs. @@ -338,9 +337,9 @@ def qnode(theta, t=ts): fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels), sharex=True) for n in range(n_channels): ax = axs[n] - label=f"$\\nu$_{n}: {omega[n]/2/jnp.pi:.3}/$2\\pi$" + label=f"$\\nu_{n}$: {omega[n]/2/jnp.pi:.3}/$2\\pi$" ax.plot(ts, np.clip(theta[n], -0.02, 0.02), ".:", label=label) - ax.set_ylabel(f"amp_{n} (GHz)") + ax.set_ylabel(f"$amp_{n}$ (GHz)") ax.legend() ax.set_xlabel("t (ns)") From a61e13d33ba6e0c98ececa69a19758002d7724f2 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann <43949391+Qottmann@users.noreply.github.com> Date: Wed, 15 Feb 2023 03:42:04 -0800 Subject: [PATCH 070/122] Apply suggestions from code review Co-authored-by: Tom Bromley <49409390+trbromley@users.noreply.github.com> --- demonstrations/tutorial_pulse_programming101.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 512d7dfd52..e62fbc43d8 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -5,10 +5,10 @@ :property="og:description": Simulating differentialble pulse programs in PennyLane with qubits :property="og:image": https://pennylane.ai/qml/_images/pauli_shadows.jpg -*Author: Korbinian Kottmann — Posted: 20 February 2023. +Author: Korbinian Kottmann — Posted: 20 February 2023. In this demo we are going to introduce pulse programming with qubits in PennyLane and run the -ctrl-VQE algorithm on a two-qubit Hamiltonian (HeH+). +ctrl-VQE algorithm on a two-qubit Hamiltonian for the HeH+ molecule. Pulses in quantum computers --------------------------- @@ -41,7 +41,7 @@ In PennyLane, we can simulate arbitrary qubit system interactions to explore the possibilities of such pulse programs. First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p, t) H_i` with constant operators :math:`H_i` and driving fields :math:`f_i(p, t)` that may -depend on parameters :math:`p`. In PennyLane, we can do this in an intuitive way: +depend on parameters :math:`p`. In PennyLane, we can do this in the following way: """ import pennylane as qml @@ -136,15 +136,15 @@ def qnode(params): print(jax.grad(qnode)(params)) ############################################################################## -# Alternatively, one can compute the gradient with the parameter shift rule [#Leng2022]_, which is particularly interesting for +# Alternatively, one could consider computing the gradient with the parameter shift rule [#Leng2022]_, which is particularly interesting for # real hardware execution. In classical simulations, however, backpropagation is recommended. ############################################################################## # Piece-wise-constant parametrizations # ------------------------------------ -# PennyLane also provides a variety of convenience functions to create for example piece-wise-constant parametrizations, -# i.e. defining the function values at fixed time bins as parameters. We can construct such a callable with :func:`~pennylane.pulse.pwc` +# PennyLane also provides a variety of convenience functions to create, for example, piece-wise-constant parametrizations +# defining the function values at fixed time bins as parameters. We can construct such a callable with :func:`~pennylane.pulse.pwc` # by providing a ``timespan`` argument which is expected to be either a total time (``float``) or a start and end time (``tuple``). timespan = 10. @@ -176,7 +176,7 @@ def qnode(params): ############################################################################## # Variational quantum eigensolver with pulse programming # ------------------------------------------------------ -# We can now use those gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. +# We can now use the ability to access gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. # First, we define the molecular Hamiltonian whose energy estimate we want to minimize. # We are going to look at :math:`\text{HeH}^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. # We are going to use the tapered Hamiltonian which makes use of symmetries to reduce the number of qubits, see :doc:`tutorial_qubit_tapering` for details. From 2ac2d6f5c5b88f5bf328ef83aacf038aa5c22e16 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 15 Feb 2023 12:49:33 +0100 Subject: [PATCH 071/122] missing plot label --- demonstrations/tutorial_pulse_programming101.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index a4208b1a54..725ae4fe83 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -70,9 +70,8 @@ def f2(p, t): ############################################################################## # We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using :func:`qml.dot `. -# We use two sinusoids with random frequencies as the time-dependent parametrization for each :math:`Z_i`. -coeffs = [jnp.array(1.)] * 2 +coeffs = [1.] * 2 coeffs += [lambda p, t: jnp.sin(p[0]*t) + jnp.sin(p[1]*t) for _ in range(3)] ops = [qml.PauliX(i) @ qml.PauliX(i+1) for i in range(2)] ops += [qml.PauliZ(i) for i in range(3)] @@ -163,6 +162,9 @@ def qnode(params): for i in range(2): ax = axs[i] ax.plot(ts, coeffs[i](theta[i], ts), ".-") + ax.set_ylabel(f"coeffs[{i}]") +ax.set_xlabel("time t") +plt.show() ############################################################################## # Note how the number of time bins is implicitly defined through the length of the parameters, From bc1eedf7c9923ea8a6179e0592fbd71b34bd9a5e Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 15 Feb 2023 12:51:47 +0100 Subject: [PATCH 072/122] evolve link :func: --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 725ae4fe83..a5027e5119 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -102,7 +102,7 @@ def f2(p, t): ############################################################################## # -# A pulse program is then executed by using the :func:`~evolve` transform to create the evolution +# A pulse program is then executed by using the :func:`~.pennylane.evolve` transform to create the evolution # gate :math:`U(t_0, t_1)`, which implicitly depends on the parameters ``p``. dev = qml.device("default.qubit", range(4)) From ce3305843f38e4fe365adb3de3f7b05065ab88af Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 15 Feb 2023 12:52:53 +0100 Subject: [PATCH 073/122] black --- .../tutorial_pulse_programming101.py | 102 ++++++++++-------- 1 file changed, 59 insertions(+), 43 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index a5027e5119..beeab7d0f1 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -51,29 +51,33 @@ import matplotlib.pyplot as plt # remove jax CPU/GPU warning -jax.config.update('jax_platform_name', 'cpu') +jax.config.update("jax_platform_name", "cpu") + def f1(p, t): return jnp.polyval(p, t) + + def f2(p, t): return p[0] * jnp.sin(p[1] * t) + Ht = f1 * qml.PauliX(0) + f2 * qml.PauliY(1) ############################################################################## -# Note that when constructing such a Hamiltonian, the ``callable`` functions are +# Note that when constructing such a Hamiltonian, the ``callable`` functions are # expected to have the fixed signature ``(p, t)``, such that the Hamiltonian itself -# can be called via ``H((p1, p2), t)``. +# can be called via ``H((p1, p2), t)``. -params = (jnp.ones(5), jnp.array([1., jnp.pi])) +params = (jnp.ones(5), jnp.array([1.0, jnp.pi])) print(Ht(params, 0.5)) ############################################################################## # We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using :func:`qml.dot `. -coeffs = [1.] * 2 -coeffs += [lambda p, t: jnp.sin(p[0]*t) + jnp.sin(p[1]*t) for _ in range(3)] -ops = [qml.PauliX(i) @ qml.PauliX(i+1) for i in range(2)] +coeffs = [1.0] * 2 +coeffs += [lambda p, t: jnp.sin(p[0] * t) + jnp.sin(p[1] * t) for _ in range(3)] +ops = [qml.PauliX(i) @ qml.PauliX(i + 1) for i in range(2)] ops += [qml.PauliZ(i) for i in range(3)] Ht = qml.dot(coeffs, ops) @@ -87,11 +91,11 @@ def f2(p, t): ############################################################################## # We can visualize the Hamiltonian interaction by plotting the time-dependent envelopes. -ts = jnp.linspace(0., 5., 100) +ts = jnp.linspace(0.0, 5.0, 100) fs = Ht.coeffs_parametrized ops = Ht.ops_parametrized n_channels = len(fs) -fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels), gridspec_kw={"hspace": 0}) +fig, axs = plt.subplots(nrows=n_channels, figsize=(5, 2 * n_channels), gridspec_kw={"hspace": 0}) for n in range(n_channels): ax = axs[n] ax.plot(ts, fs[n](params[n], ts)) @@ -107,15 +111,17 @@ def f2(p, t): dev = qml.device("default.qubit", range(4)) -ts = jnp.array([0., 3.]) +ts = jnp.array([0.0, 3.0]) H_obj = sum([qml.PauliZ(i) for i in range(4)]) + @jax.jit @qml.qnode(dev, interface="jax") def qnode(params): qml.evolve(Ht)(params, ts) return qml.expval(H_obj) + print(qnode(params)) ############################################################################## @@ -146,7 +152,7 @@ def qnode(params): # defining the function values at fixed time bins as parameters. We can construct such a callable with :func:`~pennylane.pulse.pwc` # by providing a ``timespan`` argument which is expected to be either a total time (``float``) or a start and end time (``tuple``). -timespan = 10. +timespan = 10.0 coeffs = [qml.pulse.pwc(timespan) for _ in range(2)] ############################################################################## @@ -157,7 +163,7 @@ def qnode(params): subkeys = jax.random.split(key, 2) theta = [jax.random.uniform(subkeys[i], shape=[shape], maxval=5) for i, shape in enumerate([4, 10])] -ts = jnp.linspace(0., 10., 100)[:-1] +ts = jnp.linspace(0.0, 10.0, 100)[:-1] fig, axs = plt.subplots(nrows=2, sharex=True) for i in range(2): ax = axs[i] @@ -178,8 +184,8 @@ def qnode(params): ############################################################################## # Variational quantum eigensolver with pulse programming # ------------------------------------------------------ -# We can now use the ability to access gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. -# First, we define the molecular Hamiltonian whose energy estimate we want to minimize. +# We can now use the ability to access gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. +# First, we define the molecular Hamiltonian whose energy estimate we want to minimize. # We are going to look at :math:`\text{HeH}^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. # We are going to use the tapered Hamiltonian which makes use of symmetries to reduce the number of qubits, see :doc:`tutorial_qubit_tapering` for details. @@ -190,47 +196,55 @@ def qnode(params): n_wires = len(H_obj.wires) ############################################################################## -# As a realistic physical system with pulse level control, we are considering a coupled transmon qubit system with the constant drift term Hamiltonian +# As a realistic physical system with pulse level control, we are considering a coupled transmon qubit system with the constant drift term Hamiltonian # # .. math:: H_D = \sum_q \omega_q a_q^\dagger a_q - \sum_q \frac{\delta_q}{2} a^\dagger_q a^\dagger_q a_q a_q + \sum_{\braket{pq}} g_{pq} a^\dagger_p a_q -# +# # with bosonic creation and annihilation operators. The anharmonicity :math:`\delta_q` is describing the contribution to higher energy levels. # We are only going to consider the qubit subspace and hence set this term to zero. # The order of magnitude of the resonance frequencies :math:`\omega_q` and coupling strength :math:`g_{pq}` are taken from [#Mitei]_ (in GHz). + def a(wires): - return 0.5*qml.PauliX(wires) + 0.5j* qml.PauliY(wires) + return 0.5 * qml.PauliX(wires) + 0.5j * qml.PauliY(wires) + + def ad(wires): - return 0.5*qml.PauliX(wires) - 0.5j* qml.PauliY(wires) + return 0.5 * qml.PauliX(wires) - 0.5j * qml.PauliY(wires) + -omega = 2*jnp.pi* jnp.array([4.8080, 4.8333]) -g = 2*jnp.pi* jnp.array([0.01831, 0.02131]) +omega = 2 * jnp.pi * jnp.array([4.8080, 4.8333]) +g = 2 * jnp.pi * jnp.array([0.01831, 0.02131]) H_D = qml.dot(omega, [ad(i) @ a(i) for i in range(n_wires)]) -H_D += qml.dot(g, [ad(i) @ a((i+1)%n_wires) + ad((i+1)%n_wires) @ a(i) for i in range(n_wires)]) +H_D += qml.dot( + g, [ad(i) @ a((i + 1) % n_wires) + ad((i + 1) % n_wires) @ a(i) for i in range(n_wires)] +) ############################################################################## # The system is driven under the control term # # .. math:: H_C(t) = \sum_q \Omega_q(t) \left(e^{i\nu_q t} a_q + e^{-i\nu_q t} a^\dagger_q \right) -# +# # with the (real) time-dependent amplitudes :math:`\Omega_q(t)` and frequencies :math:`\nu_q` of the drive. # We let :math:`\Omega(t)` be a piece-wise-constant real function whose values are optimized. # In principle one can also optimize the drive frequency :math:`\nu_q`, but we already find good results by setting it to the qubit frequencies. # We restrict the amplitude to :math:`\pm 20 \text{MHz}` to abide by realistic hardware constraints. -def drive_field(T, omega, sign=1.): + +def drive_field(T, omega, sign=1.0): def wrapped(p, t): amp = jnp.clip(qml.pulse.pwc(T)(p, t), -0.02, 0.02) - phase = jnp.exp(sign*1j*omega*t) + phase = jnp.exp(sign * 1j * omega * t) return amp * phase return wrapped -duration = 15. -fs = [drive_field(duration, omega[i], 1.) for i in range(n_wires)] -fs += [drive_field(duration, omega[i], -1.) for i in range(n_wires)] +duration = 15.0 + +fs = [drive_field(duration, omega[i], 1.0) for i in range(n_wires)] +fs += [drive_field(duration, omega[i], -1.0) for i in range(n_wires)] ops = [a(i) for i in range(n_wires)] ops += [ad(i) for i in range(n_wires)] @@ -248,40 +262,42 @@ def wrapped(p, t): # We choose ``t_bins = 100`` segments for the piece-wise-constant parametrization of the pulses # and define the ``qnode`` that computes the expectation value of the molecular Hamiltonian. -t_bins = 100 # number of time bins +t_bins = 100 # number of time bins -# The step sizes are chosen adaptively, so there is in principle no need to provide +# The step sizes are chosen adaptively, so there is in principle no need to provide # explicit time steps. However, because the pwc function can be discontinuous it makes # sense to force the solver to evaluate the points of the evolution. # The error is still guaranteed to stay within the tolerance by using adaptive steps in between # the fixed ones we provide. -ts = jnp.linspace(0., duration, t_bins) +ts = jnp.linspace(0.0, duration, t_bins) dev = qml.device("default.qubit", wires=range(n_wires)) + @qml.qnode(dev, interface="jax") def qnode(theta, t=ts): qml.BasisState(list(data.tapered_hf_state), wires=H_obj.wires) qml.evolve(H_pulse)(params=(*theta, *theta), t=t) return qml.expval(H_obj) + ############################################################################## # We now have all the ingredients to run our ctrl-VQE program. We use the ``adabelief`` implementation in `optax `_, a package for optimizations in ``jax``. # The success of the optimization is sensitive to the initial values of the parameters. # We showcase a good random seed here. In reality, this optimization easily gets stuck in local minima -# such that we would have to repeat the experiment multiple times with different random initializations. +# such that we would have to repeat the experiment multiple times with different random initializations. # On the other hand, the Hartree-Fock state is usually a good starting point, i.e. choosing all parameters to zero. # However, this results in a near-zero gradient in our case. This is why we choose a trade-off by reducing # the initial amplitude of the random values. # # Further, we note that with the increase in the number of parameters due to the continuous evolution, the optimization # becomes harder. In particular, besides the random initilization, the optimization is also very sensitive to the choice of -# optimizer and learning rate. We systematically tried a variety of combinations and provide one possible choice leading to good results. +# optimizer and learning rate. We systematically tried a variety of combinations and provide one possible choice leading to good results. key = jax.random.PRNGKey(999) -theta = 0.01*jax.random.uniform(key, shape=jnp.array([n_wires, t_bins])) +theta = 0.01 * jax.random.uniform(key, shape=jnp.array([n_wires, t_bins])) -import optax +import optax from datetime import datetime n_epochs = 100 @@ -290,7 +306,7 @@ def qnode(theta, t=ts): value_and_grad = jax.jit(jax.value_and_grad(qnode)) -energy = np.zeros(n_epochs+1) +energy = np.zeros(n_epochs + 1) energy[0] = qnode(theta) ## Compile the evaluation and gradient function and report compilation time @@ -305,20 +321,20 @@ def qnode(theta, t=ts): updates, opt_state = optimizer.update(grad_circuit, opt_state) theta = optax.apply_updates(theta, updates) - energy[n+1] = val + energy[n + 1] = val - if not n%10: + if not n % 10: print(f"mean grad: {jnp.mean(jnp.abs(grad_circuit))}") print(f"{n+1} / {n_epochs}; energy: {energy[n]}") ############################################################################## # We see that we have converged well within chemical accuracy after half the number of epochs. -fig, ax = plt.subplots(nrows=1, figsize=(5,3), sharex=True) +fig, ax = plt.subplots(nrows=1, figsize=(5, 3), sharex=True) y = np.array(energy) - E_exact ax.plot(y, ".:", label="$\\langle H_{{obj}}\\rangle - E_{{FCI}}$") -ax.fill_between([0, len(y)], [1e-3]*2, 5e-4, alpha=0.2, label="chem acc.") +ax.fill_between([0, len(y)], [1e-3] * 2, 5e-4, alpha=0.2, label="chem acc.") ax.set_yscale("log") ax.set_ylabel("Energy ($E_H$)") ax.set_xlabel("epoch") @@ -328,7 +344,7 @@ def qnode(theta, t=ts): plt.show() ############################################################################## -# We can also visualize the envelopes for each qubit in time. +# We can also visualize the envelopes for each qubit in time. # We only plot the real amplitude :math:`\Omega(t)` without the qubit frequency modulation. # Note that we obtain bang-bang like solutions as indicated in [#Asthana2022]_, making it # likely we are close to the minimal evolution time with ``15ns``. @@ -336,10 +352,10 @@ def qnode(theta, t=ts): fs = H_pulse.coeffs_parametrized[:n_wires] n_channels = len(fs) -fig, axs = plt.subplots(nrows=n_channels, figsize=(5,2*n_channels), sharex=True) +fig, axs = plt.subplots(nrows=n_channels, figsize=(5, 2 * n_channels), sharex=True) for n in range(n_channels): ax = axs[n] - label=f"$\\nu_{n}$: {omega[n]/2/jnp.pi:.3}/$2\\pi$" + label = f"$\\nu_{n}$: {omega[n]/2/jnp.pi:.3}/$2\\pi$" ax.plot(ts, np.clip(theta[n], -0.02, 0.02), ".:", label=label) ax.set_ylabel(f"$amp_{n}$ (GHz)") ax.legend() @@ -365,7 +381,7 @@ def qnode(theta, t=ts): # ---------- # # .. [#Leng2022] -# +# # Jiaqi Leng, Yuxiang Peng, Yi-Ling Qiao, Ming Lin, Xiaodi Wu # "Differentiable Analog Quantum Computing for Optimization and Control" # `arXiv:2210.15812 `__, 2022 From 7fca88edf5300f8b1d4e3dd3e200ce55b8974625 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 15 Feb 2023 12:54:46 +0100 Subject: [PATCH 074/122] print energy difference --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index beeab7d0f1..1e1eb1bac2 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -325,7 +325,7 @@ def qnode(theta, t=ts): if not n % 10: print(f"mean grad: {jnp.mean(jnp.abs(grad_circuit))}") - print(f"{n+1} / {n_epochs}; energy: {energy[n]}") + print(f"{n+1} / {n_epochs}; energy discrepancy: {val-E_exact}") ############################################################################## # We see that we have converged well within chemical accuracy after half the number of epochs. From 1349767f6510debc7186826db8ebd414c71b3f58 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 16 Feb 2023 10:36:01 +0100 Subject: [PATCH 075/122] rerun From ff69d1e80a0097052f8a717621a66c2e6106aa09 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 16 Feb 2023 10:44:08 +0100 Subject: [PATCH 076/122] revert changes --- demonstrations/tutorial_pulse_programming101.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 1e1eb1bac2..1f057a468c 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -308,6 +308,7 @@ def qnode(theta, t=ts): energy = np.zeros(n_epochs + 1) energy[0] = qnode(theta) +gradients = np.zeros(n_epochs) ## Compile the evaluation and gradient function and report compilation time time0 = datetime.now() @@ -322,10 +323,11 @@ def qnode(theta, t=ts): theta = optax.apply_updates(theta, updates) energy[n + 1] = val + gradients[n] = np.mean(np.abs(grad_circuit)) if not n % 10: - print(f"mean grad: {jnp.mean(jnp.abs(grad_circuit))}") print(f"{n+1} / {n_epochs}; energy discrepancy: {val-E_exact}") + print(f"mean grad: {gradients[n]}") ############################################################################## # We see that we have converged well within chemical accuracy after half the number of epochs. From edac721b7c3585c1ff82ed5ea38598515564c998 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 16 Feb 2023 12:08:09 +0100 Subject: [PATCH 077/122] rerun From fde5b03156ee5f734568f9e9223fab554748906d Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 16 Feb 2023 23:40:46 +0100 Subject: [PATCH 078/122] retrigger From 14bc2356473536e16a7c5547c292622390dd7179 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann <43949391+Qottmann@users.noreply.github.com> Date: Fri, 17 Feb 2023 11:54:04 -0800 Subject: [PATCH 079/122] Update demonstrations/tutorial_pulse_programming101.py Co-authored-by: lillian542 <38584660+lillian542@users.noreply.github.com> --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 1f057a468c..74f8fffbec 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -40,7 +40,7 @@ level instead, with the aim of achieving the shortest interaction sequence a hardware system allows. In PennyLane, we can simulate arbitrary qubit system interactions to explore the possibilities of such pulse programs. -First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p, t) H_i` with constant operators :math:`H_i` and driving fields :math:`f_i(p, t)` that may +First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p_i, t) H_i` with constant operators :math:`H_i` and driving fields :math:`f_i(p_i, t)` that may depend on parameters :math:`p`. In PennyLane, we can do this in the following way: """ From 7f6e0f5b6c228a0ee6981cccf80fae89458e66c6 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 20 Feb 2023 13:11:43 +0100 Subject: [PATCH 080/122] add see-also section for VQE --- demonstrations/tutorial_pulse_programming101.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 1f057a468c..2ad46461b6 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -10,6 +10,8 @@ In this demo we are going to introduce pulse programming with qubits in PennyLane and run the ctrl-VQE algorithm on a two-qubit Hamiltonian for the HeH+ molecule. +.. seealso:: :doc:`tutorial_vqe` + Pulses in quantum computers --------------------------- From f8e271376e36aad62fdafb30b7b0b2e0a39b5e13 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Mon, 20 Feb 2023 13:28:36 +0100 Subject: [PATCH 081/122] also add pulse module reference --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index e55f72686a..5ecd683fb2 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -10,7 +10,7 @@ In this demo we are going to introduce pulse programming with qubits in PennyLane and run the ctrl-VQE algorithm on a two-qubit Hamiltonian for the HeH+ molecule. -.. seealso:: :doc:`tutorial_vqe` +.. seealso:: :doc:`tutorial_vqe`, :mod:`~.pulse` Pulses in quantum computers --------------------------- From 8356ccaea7c2485bc3cad5da0fc2e57c0ed32f42 Mon Sep 17 00:00:00 2001 From: soranjh <40344468+soranjh@users.noreply.github.com> Date: Tue, 21 Feb 2023 16:51:18 -0500 Subject: [PATCH 082/122] Update chemical reactions demo to use pyscf for openshell H3 (#704) * use pyscf for openshell H3 * change date and fix interface warning --- demonstrations/tutorial_chemical_reactions.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/demonstrations/tutorial_chemical_reactions.py b/demonstrations/tutorial_chemical_reactions.py index ce29d79acd..e6c048aa04 100644 --- a/demonstrations/tutorial_chemical_reactions.py +++ b/demonstrations/tutorial_chemical_reactions.py @@ -10,7 +10,7 @@ tutorial_quantum_chemistry Building molecular Hamiltonians tutorial_vqe A brief overview of VQE -*Authors: Varun Rishi and Juan Miguel Arrazola — Posted: 23 July 2021. Last updated: 23 July 2021.* +*Authors: Varun Rishi and Juan Miguel Arrazola — Posted: 23 July 2021. Last updated: 21 February 2023.* The term "chemical reaction" is another name for the transformation of molecules -- the breaking and forming of bonds. They are characterized by an energy barrier that determines @@ -129,13 +129,13 @@ coordinates = np.array([0.0, 0.0, 0.0, 0.0, 0.0, r]) # Obtain the qubit Hamiltonian - H, qubits = qchem.molecular_hamiltonian(symbols, coordinates) + H, qubits = qchem.molecular_hamiltonian(symbols, coordinates, method='pyscf') # define the device, optimizer and circuit dev = qml.device("default.qubit", wires=qubits) opt = qml.GradientDescentOptimizer(stepsize=0.4) - @qml.qnode(dev) + @qml.qnode(dev, interface='autograd') def circuit(parameters): # Prepare the HF state: |1100> qml.BasisState(hf, wires=range(qubits)) @@ -283,12 +283,12 @@ def circuit(parameters): coordinates = np.array([0.0, 0.0, 0.0, 0.0, 0.0, r, 0.0, 0.0, 4.0]) # We now specify the multiplicity - H, qubits = qchem.molecular_hamiltonian(symbols, coordinates, mult=multiplicity) + H, qubits = qchem.molecular_hamiltonian(symbols, coordinates, mult=multiplicity, method='pyscf') dev = qml.device("default.qubit", wires=qubits) opt = qml.GradientDescentOptimizer(stepsize=1.5) - @qml.qnode(dev) + @qml.qnode(dev, interface='autograd') def circuit(parameters): AllSinglesDoubles(parameters, range(qubits), hf, singles, doubles) return qml.expval(H) # we are interested in minimizing this expectation value From e95d226aefa22acefc33e39283622fed2d93542c Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 22 Feb 2023 15:46:48 +0100 Subject: [PATCH 083/122] enable float64 --- demonstrations/tutorial_pulse_programming101.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 5ecd683fb2..8c199c9482 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -52,7 +52,8 @@ import jax import matplotlib.pyplot as plt -# remove jax CPU/GPU warning +# Set to float64 precision and remove jax CPU/GPU warning +jax.config.update("jax_enable_x64", True) jax.config.update("jax_platform_name", "cpu") From 53a51c55ed2686a86035879271a75bcf1d44b4b3 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 22 Feb 2023 15:52:49 +0100 Subject: [PATCH 084/122] update --- demonstrations/tutorial_pulse_programming101.py | 1 - 1 file changed, 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 8c199c9482..7562fde462 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -56,7 +56,6 @@ jax.config.update("jax_enable_x64", True) jax.config.update("jax_platform_name", "cpu") - def f1(p, t): return jnp.polyval(p, t) From 94e66f3b60ec88bdcab424729c60b083e42811ab Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 22 Feb 2023 17:18:10 +0100 Subject: [PATCH 085/122] small update --- .../tutorial_pulse_programming101.py | 20 +++++++------------ 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 7562fde462..5353de15af 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -261,23 +261,12 @@ def wrapped(p, t): H_pulse = H_D + H_C ############################################################################## -# We choose ``t_bins = 100`` segments for the piece-wise-constant parametrization of the pulses -# and define the ``qnode`` that computes the expectation value of the molecular Hamiltonian. - -t_bins = 100 # number of time bins - -# The step sizes are chosen adaptively, so there is in principle no need to provide -# explicit time steps. However, because the pwc function can be discontinuous it makes -# sense to force the solver to evaluate the points of the evolution. -# The error is still guaranteed to stay within the tolerance by using adaptive steps in between -# the fixed ones we provide. -ts = jnp.linspace(0.0, duration, t_bins) +# Now we define the ``qnode`` that computes the expectation value of the molecular Hamiltonian. dev = qml.device("default.qubit", wires=range(n_wires)) - @qml.qnode(dev, interface="jax") -def qnode(theta, t=ts): +def qnode(theta, t=duration): qml.BasisState(list(data.tapered_hf_state), wires=H_obj.wires) qml.evolve(H_pulse)(params=(*theta, *theta), t=t) return qml.expval(H_obj) @@ -295,6 +284,10 @@ def qnode(theta, t=ts): # Further, we note that with the increase in the number of parameters due to the continuous evolution, the optimization # becomes harder. In particular, besides the random initilization, the optimization is also very sensitive to the choice of # optimizer and learning rate. We systematically tried a variety of combinations and provide one possible choice leading to good results. +# +# We choose ``t_bins = 100`` segments for the piece-wise-constant parametrization of the pulses. + +t_bins = 100 # number of time bins key = jax.random.PRNGKey(999) theta = 0.01 * jax.random.uniform(key, shape=jnp.array([n_wires, t_bins])) @@ -356,6 +349,7 @@ def qnode(theta, t=ts): fs = H_pulse.coeffs_parametrized[:n_wires] n_channels = len(fs) +ts = jnp.linspace(0, duration, t_bins) fig, axs = plt.subplots(nrows=n_channels, figsize=(5, 2 * n_channels), sharex=True) for n in range(n_channels): ax = axs[n] From 10d6d86def924de3f453e3b2f4682d00d96e1f55 Mon Sep 17 00:00:00 2001 From: Romain Moyard Date: Wed, 22 Feb 2023 13:14:13 -0500 Subject: [PATCH 086/122] Change ibm device in Quantum volume (#703) * Ibm oslo * Update to new hardware * Change to Lima * Typo * Replace * One below --- demonstrations/quantum_volume.py | 148 +- .../quantum_volume/{ourense.svg => lima.svg} | 0 .../lima_heavy_output_distributions.svg | 2241 +++++++++++++++++ .../ourense_heavy_output_distributions.svg | 2127 ---------------- 4 files changed, 2314 insertions(+), 2202 deletions(-) rename demonstrations/quantum_volume/{ourense.svg => lima.svg} (100%) create mode 100644 demonstrations/quantum_volume/lima_heavy_output_distributions.svg delete mode 100644 demonstrations/quantum_volume/ourense_heavy_output_distributions.svg diff --git a/demonstrations/quantum_volume.py b/demonstrations/quantum_volume.py index f3c33be50d..87f7ec93b7 100644 --- a/demonstrations/quantum_volume.py +++ b/demonstrations/quantum_volume.py @@ -397,38 +397,38 @@ def qv_circuit_layer(num_qubits): # # .. code-block:: none # -# 0: ─╭SWAP─╭U(M0)─╭U(M1)─╭SWAP───────╭U(M2)─┤ -# 1: ─╰SWAP─╰U(M0)─╰U(M1)─│─────╭SWAP─╰U(M2)─┤ -# 2: ─────────────────────╰SWAP─╰SWAP────────┤ -# 3: ────────────────────────────────────────┤ -# 4: ────────────────────────────────────────┤ -# M0 = -# [[-0.17514647+0.00759447j 0.11975927+0.16007614j -0.41793925+0.49643728j -# 0.62304058-0.34640531j] -# [-0.73367896-0.58079555j -0.11348577+0.00751965j -0.02640159-0.15592112j -# -0.19507153-0.21998821j] -# [ 0.02988983+0.09364586j -0.74053162+0.55032455j 0.31350059-0.01305651j -# 0.16283233-0.11885036j] -# [-0.13103809-0.25850305j 0.18298996+0.2497364j 0.34879438+0.57771772j -# -0.02385446+0.60346274j]] -# M1 = -# [[ 0.14296171+0.28087257j -0.5985737 -0.27489922j -0.43838149+0.10344812j -# 0.04022491+0.51216658j] -# [-0.21538853+0.02728431j -0.24776721-0.57146257j 0.60975755+0.36241573j -# 0.21787038-0.11953391j] -# [-0.24405375+0.05780278j -0.11688629-0.17397518j -0.51628349-0.11381455j -# 0.44143429-0.64714776j] -# [-0.750841 -0.47630904j -0.28666068+0.22820556j -0.09459735+0.07429451j -# -0.17243398+0.17582253j]] -# M2 = -# [[-0.63733359+1.91519046e-01j -0.49615702+9.79920998e-05j -# 0.06949634+4.54968771e-01j 0.21112196-2.33571716e-01j] -# [ 0.4774216 +5.19692450e-02j -0.2741782 -3.71778068e-01j -# 0.09817361+6.01972062e-01j -0.39517581+1.66741872e-01j] -# [ 0.14401687-1.53582182e-01j 0.51636466-1.58216631e-01j -# 0.43804144+3.62586089e-01j 0.4473567 -3.74872915e-01j] -# [ 0.51670588+1.23210608e-01j -0.48982566-9.40288988e-02j -# -0.19210465-2.36457367e-01j 0.53202679-3.05278186e-01j]] +# 0: ─╭SWAP───────╭U(M0)─╭SWAP───────╭U(M1)─╭U(M2)─┤ +# 1: ─│─────╭SWAP─╰U(M0)─╰SWAP─╭SWAP─╰U(M1)─╰U(M2)─┤ +# 2: ─╰SWAP─╰SWAP──────────────╰SWAP───────────────┤ +# 3: ──────────────────────────────────────────────┤ +# 4: ──────────────────────────────────────────────┤ +# M0 = +# [[ 0.22234537+0.12795769j 0.24613682-0.34470179j 0.58179809-0.36478045j +# -0.16337007-0.50650086j] +# [-0.08840637-0.42456216j -0.01961572+0.35189839j 0.4214659 +0.31514336j +# -0.63733039+0.06764003j] +# [ 0.28919627-0.23577761j -0.11249786-0.67687982j 0.22914826+0.37205064j +# 0.12755164+0.42749545j] +# [ 0.59999195+0.49689511j -0.29294024+0.37382355j 0.23724315-0.06544043j +# -0.039832 +0.3246437j ]] +# M1 = +# [[ 0.11583153-0.3628563j 0.55797708+0.48315028j -0.22400838-0.264741j +# -0.34856401+0.26149824j] +# [-0.04549494-0.25884483j 0.00258749-0.20351027j -0.26326583-0.70408962j +# 0.33442905-0.46109931j] +# [-0.46824254-0.14274112j -0.00491681+0.61278881j -0.02506472+0.26582603j +# 0.54135395-0.14312156j] +# [ 0.73672445-0.05881259j 0.19534118+0.01057264j -0.29145879+0.398047j +# 0.33955583-0.23837031j]] +# M2 = +# [[-0.33352575+0.21982221j -0.29128941-0.51347253j 0.63543764-0.11913356j +# 0.27186717+0.00704727j] +# [-0.22330473+0.02289549j 0.1997405 -0.47316218j -0.23040621-0.14078015j +# -0.47922028-0.61909121j] +# [-0.00705247+0.82724695j 0.52220719+0.02527864j -0.05490671-0.04899343j +# 0.03167901+0.18935341j] +# [ 0.23396138-0.22566431j 0.32400589+0.09694607j 0.54666955-0.45261179j +# -0.48177768+0.2101061j ]] ############################################################################## @@ -510,19 +510,19 @@ def heavy_output_set(m, probs): # # .. code-block:: none # -# State Probability -# 000 0.0157 -# 001 0.0200 -# 010 0.0026 -# 011 0.2765 -# 100 0.0175 -# 101 0.4266 -# 110 0.0045 -# 111 0.2365 +# State Probability +# 000 0.0559 +# 001 0.3687 +# 010 0.0326 +# 011 0.0179 +# 100 0.0550 +# 101 0.3590 +# 110 0.1103 +# 111 0.0005 # -# Median is 0.0188 -# Probability of a heavy output is 0.9596 -# Heavy outputs are ['001', '111', '011', '101'] +# Median is 0.0554 +# Probability of a heavy output is 0.8939 +# Heavy outputs are ['000', '110', '101', '001'] # ############################################################################## @@ -531,7 +531,7 @@ def heavy_output_set(m, probs): # ~~~~~~~~~~~~~~~~~~~~~~~~ # # Now it's time to run the protocol. First, let's set up our hardware -# device. We'll use a simulated version of the 5-qubit IBM Ourense as an example +# device. We'll use a simulated version of the 5-qubit IBM Lima as an example # --- the reported quantum volume according to IBM is :math:`V_Q=8`, so we # endeavour to reproduce that here. This means that we should be able to run our # square circuits reliably on up to :math:`\log_2 V_Q =3` qubits. @@ -551,13 +551,10 @@ def heavy_output_set(m, probs): # # .. note:: # -# In the time since the original release of this demo, the Ourense device is -# no longer available from IBM Q. However, we leave the original results for -# expository purposes, and note that the methods are applicable in general. # Users can get a list of available IBM Q backends by importing IBM Q, # specifying their provider and then calling: ``provider.backends()`` # -dev_ourense = qml.device("qiskit.ibmq", wires=5, backend="ibmq_bogota") +dev_lima = qml.device("qiskit.ibmq", wires=5, backend="ibmq_lima") ############################################################################## # @@ -567,18 +564,18 @@ def heavy_output_set(m, probs): import matplotlib.pyplot as plt import networkx as nx -ourense_hardware_graph = nx.Graph(dev_ourense.backend.configuration().coupling_map) +lima_hardware_graph = nx.Graph(dev_lima.backend.configuration().coupling_map) nx.draw_networkx( - ourense_hardware_graph, + lima_hardware_graph, node_color="cyan", - labels={x: x for x in range(dev_ourense.num_wires)}, + labels={x: x for x in range(dev_lima.num_wires)}, ) ############################################################################## # -# .. figure:: ../demonstrations/quantum_volume/ourense.svg +# .. figure:: ../demonstrations/quantum_volume/lima.svg # :align: center # :width: 75% # @@ -589,16 +586,16 @@ def heavy_output_set(m, probs): # to make some adjustments when non-connected qubits need to interact. # # To actually perform the simulations, we'll need to access a copy of the -# Ourense noise model. Again, we won't be running on Ourense directly --- +# Lima noise model. Again, we won't be running on Lima directly --- # we'll set up a local device to simulate its behaviour. # from qiskit.providers.aer import noise -noise_model = noise.NoiseModel.from_backend(dev_ourense.backend) +noise_model = noise.NoiseModel.from_backend(dev_lima.backend) dev_noisy = qml.device( - "qiskit.aer", wires=dev_ourense.num_wires, shots=1000, noise_model=noise_model + "qiskit.aer", wires=dev_lima.num_wires, shots=1000, noise_model=noise_model ) ############################################################################## @@ -609,7 +606,7 @@ def heavy_output_set(m, probs): # qubit placement and routing techniques [#sabre]_ in order to fit the circuits # on the hardware graph in the best way possible. -coupling_map = dev_ourense.backend.configuration().to_dict()["coupling_map"] +coupling_map = dev_lima.backend.configuration().to_dict()["coupling_map"] dev_noisy.set_transpile_args( **{ @@ -697,24 +694,24 @@ def heavy_output_set(m, probs): # .. code-block:: none # # Ideal mean probabilities: -# m = 2: 0.797979 above threshold. -# m = 3: 0.844052 above threshold. -# m = 4: 0.841203 above threshold. -# m = 5: 0.856904 above threshold. +# m = 2: 0.801480 above threshold. +# m = 3: 0.853320 above threshold. +# m = 4: 0.832995 above threshold. +# m = 5: 0.858370 above threshold. # # Device mean probabilities: -# m = 2: 0.773760 above threshold. -# m = 3: 0.794875 above threshold. -# m = 4: 0.722860 above threshold. -# m = 5: 0.692935 above threshold. +# m = 2: 0.765920 above threshold. +# m = 3: 0.773985 above threshold. +# m = 4: 0.674380 above threshold. +# m = 5: 0.639500 below threshold. ############################################################################## # # We see that the ideal probabilities are well over 2/3. In fact, they're quite # close to the expected value of :math:`(1 + \ln 2)/2`, which we recall from # above is :math:`\approx 0.85`. For this experiment, we see that the device -# probabilities are also above the threshold. But it isn't enough that just the -# mean of the heavy output probabilities is greater than 2/3. Since we're +# probabilities are also above the threshold (except one). But it isn't enough +# that just the mean of the heavy output probabilities is greater than 2/3. Since we're # dealing with randomness, we also want to ensure these results were not just a # fluke! To be confident, we also want to be above 2/3 within 2 standard # deviations :math:`(\sigma)` of the mean. This is referred to as a 97.5% @@ -766,13 +763,14 @@ def heavy_output_set(m, probs): label="2σ", ) -fig.suptitle("Heavy output distributions for (simulated) Ourense QPU", fontsize=18) +fig.suptitle("Heavy output distributions for (simulated) Lima QPU", fontsize=18) plt.legend(fontsize=14) plt.tight_layout() + ############################################################################## # -# .. figure:: ../demonstrations/quantum_volume/ourense_heavy_output_distributions.svg +# .. figure:: ../demonstrations/quantum_volume/lima_heavy_output_distributions.svg # :align: center # :width: 90% # @@ -795,16 +793,16 @@ def heavy_output_set(m, probs): # # .. code-block:: none # -# m = 2: 0.714590 above threshold. -# m = 3: 0.737770 above threshold. -# m = 4: 0.659562 below threshold. -# m = 5: 0.627701 below threshold. +# m = 2: 0.706039 above threshold. +# m = 3: 0.714836 above threshold. +# m = 4: 0.608109 below threshold. +# m = 5: 0.571597 below threshold. # ############################################################################## # # We see that we are :math:`2\sigma` above the threshold only for :math:`m=2`, -# and :math:`m=3`. Thus, we find that the quantum volume of our simulated Ourense is +# and :math:`m=3`. Thus, we find that the quantum volume of our simulated Lima is # :math:`\log_2 V_Q = 3`, or :math:`V_Q = 8`, as expected. # # This framework and code will allow you to calculate the quantum volume of many @@ -831,7 +829,7 @@ def heavy_output_set(m, probs): # number of qubits continues to increase and error rates are getting lower, # both of which imply that our square circuits will be growing in both width and # depth as time goes on. Eventually they will reach a point where they are no -# longer classical simulable and we will have to design new benchmarks. +# longer classical simulable, and we will have to design new benchmarks. # # Another limitation is that the protocol only looks at one type of circuit, # i.e., square circuits. It might be the case that a processor has very few diff --git a/demonstrations/quantum_volume/ourense.svg b/demonstrations/quantum_volume/lima.svg similarity index 100% rename from demonstrations/quantum_volume/ourense.svg rename to demonstrations/quantum_volume/lima.svg diff --git a/demonstrations/quantum_volume/lima_heavy_output_distributions.svg b/demonstrations/quantum_volume/lima_heavy_output_distributions.svg new file mode 100644 index 0000000000..0a12856aef --- /dev/null +++ b/demonstrations/quantum_volume/lima_heavy_output_distributions.svg @@ -0,0 +1,2241 @@ + + + + + + + + 2023-02-21T16:23:37.357171 + image/svg+xml + + + Matplotlib v3.6.2, https://matplotlib.org/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/demonstrations/quantum_volume/ourense_heavy_output_distributions.svg b/demonstrations/quantum_volume/ourense_heavy_output_distributions.svg deleted file mode 100644 index 759fcfbdc2..0000000000 --- a/demonstrations/quantum_volume/ourense_heavy_output_distributions.svg +++ /dev/null @@ -1,2127 +0,0 @@ - - - - - - - - - 2021-01-24T11:24:04.152682 - image/svg+xml - - - Matplotlib v3.3.1, https://matplotlib.org/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - From ab34e2aa5ed66240b7fef111f3486a558e8d1871 Mon Sep 17 00:00:00 2001 From: Mudit Pandey Date: Wed, 22 Feb 2023 16:17:50 -0500 Subject: [PATCH 087/122] Update demos to remove warnings (#705) * Added interface, removed deprecated functionality * Addressing PR comments --------- Co-authored-by: Romain Moyard --- demonstrations/tutorial_adaptive_circuits.py | 10 +-- demonstrations/tutorial_backprop.py | 14 ++-- demonstrations/tutorial_barren_plateaus.py | 4 +- demonstrations/tutorial_classical_kernels.py | 2 +- .../tutorial_classically_boosted_vqe.py | 4 +- demonstrations/tutorial_coherent_vqls.py | 6 +- .../tutorial_data_reuploading_classifier.py | 2 +- demonstrations/tutorial_diffable_shadows.py | 22 +++--- demonstrations/tutorial_differentiable_HF.py | 2 +- demonstrations/tutorial_doubly_stochastic.py | 6 +- .../tutorial_expressivity_fourier_series.py | 8 +- demonstrations/tutorial_falqon.py | 8 +- demonstrations/tutorial_givens_rotations.py | 10 +-- .../tutorial_kernel_based_training.py | 2 +- demonstrations/tutorial_kernels_module.py | 2 +- .../tutorial_local_cost_functions.py | 16 ++-- demonstrations/tutorial_mbqc.py | 16 ++-- .../tutorial_measurement_optimize.py | 14 ++-- demonstrations/tutorial_mol_geo_opt.py | 2 +- .../tutorial_noisy_circuit_optimization.py | 77 ++++++++++--------- demonstrations/tutorial_plugins_hybrid.py | 2 +- demonstrations/tutorial_qgrnn.py | 2 +- .../tutorial_quantum_natural_gradient.py | 14 ++-- demonstrations/tutorial_quanvolution.py | 2 +- demonstrations/tutorial_qubit_rotation.py | 4 +- demonstrations/tutorial_qubit_tapering.py | 14 ++-- demonstrations/tutorial_rosalin.py | 10 +-- demonstrations/tutorial_sc_qubits.py | 16 ++-- demonstrations/tutorial_testing_symmetry.py | 2 +- demonstrations/tutorial_tn_circuits.py | 10 +-- demonstrations/tutorial_trapped_ions.py | 14 ++-- .../tutorial_variational_classifier.py | 6 +- demonstrations/tutorial_vqe.py | 2 +- demonstrations/tutorial_vqe_qng.py | 4 +- demonstrations/tutorial_vqe_spin_sectors.py | 8 +- demonstrations/tutorial_vqls.py | 4 +- demonstrations/tutorial_vqt.py | 2 +- 37 files changed, 174 insertions(+), 169 deletions(-) diff --git a/demonstrations/tutorial_adaptive_circuits.py b/demonstrations/tutorial_adaptive_circuits.py index b40804500d..13e4649ff3 100644 --- a/demonstrations/tutorial_adaptive_circuits.py +++ b/demonstrations/tutorial_adaptive_circuits.py @@ -123,7 +123,7 @@ def circuit_1(params, excitations): # with respect to the Hartree-Fock state. dev = qml.device("default.qubit", wires=qubits) -cost_fn = qml.QNode(circuit_1, dev) +cost_fn = qml.QNode(circuit_1, dev, interface="autograd") circuit_gradient = qml.grad(cost_fn, argnum=0) @@ -181,7 +181,7 @@ def circuit_2(params, excitations, gates_select, params_select): ############################################################################## # We now compute the gradients for the single excitation gates. -cost_fn = qml.QNode(circuit_2, dev) +cost_fn = qml.QNode(circuit_2, dev, interface="autograd") circuit_gradient = qml.grad(cost_fn, argnum=0) params = [0.0] * len(singles) @@ -213,7 +213,7 @@ def circuit_2(params, excitations, gates_select, params_select): # We perform one final step of optimization to get the ground-state energy. The resulting energy # should match the exact energy of the ground electronic state of LiH which is -7.8825378193 Ha. -cost_fn = qml.QNode(circuit_1, dev) +cost_fn = qml.QNode(circuit_1, dev, interface="autograd") params = np.zeros(len(doubles_select + singles_select), requires_grad=True) @@ -239,7 +239,7 @@ def circuit_2(params, excitations, gates_select, params_select): # PennyLane function :func:`~.pennylane.utils.sparse_hamiltonian`. This function # returns the matrix in the SciPy `sparse coordinate `_ format. -H_sparse = qml.utils.sparse_hamiltonian(H) +H_sparse = H.sparse_matrix() H_sparse ############################################################################## @@ -264,7 +264,7 @@ def circuit_2(params, excitations, gates_select, params_select): params = np.zeros(len(excitations), requires_grad=True) -@qml.qnode(dev, diff_method="parameter-shift") +@qml.qnode(dev, diff_method="parameter-shift", interface="autograd") def circuit(params): qml.BasisState(hf_state, wires=range(qubits)) diff --git a/demonstrations/tutorial_backprop.py b/demonstrations/tutorial_backprop.py index 285df1d23e..2198861a50 100644 --- a/demonstrations/tutorial_backprop.py +++ b/demonstrations/tutorial_backprop.py @@ -64,7 +64,7 @@ # create a device to execute the circuit on dev = qml.device("default.qubit", wires=3) -@qml.qnode(dev, diff_method="parameter-shift") +@qml.qnode(dev, diff_method="parameter-shift", interface="autograd") def circuit(params): qml.RX(params[0], wires=0) qml.RY(params[1], wires=1) @@ -167,7 +167,7 @@ def parameter_shift(qnode, params): dev = qml.device("default.qubit", wires=4) -@qml.qnode(dev, diff_method="parameter-shift") +@qml.qnode(dev, diff_method="parameter-shift", interface="autograd") def circuit(params): qml.StronglyEntanglingLayers(params, wires=[0, 1, 2, 3]) return qml.expval(qml.PauliZ(0) @ qml.PauliZ(1) @ qml.PauliZ(2) @ qml.PauliZ(3)) @@ -264,7 +264,7 @@ def circuit(params): # mode* for the ``default.qubit`` device. -@qml.qnode(dev, diff_method="backprop") +@qml.qnode(dev, diff_method="backprop", interface="autograd") def circuit(params): qml.StronglyEntanglingLayers(params, wires=[0, 1, 2, 3]) return qml.expval(qml.PauliZ(0) @ qml.PauliZ(1) @ qml.PauliZ(2) @ qml.PauliZ(3)) @@ -336,8 +336,8 @@ def circuit(params): # forward pass timing # =================== - qnode_shift = qml.QNode(circuit, dev, diff_method="parameter-shift") - qnode_backprop = qml.QNode(circuit, dev, diff_method="backprop") + qnode_shift = qml.QNode(circuit, dev, diff_method="parameter-shift", interface="autograd") + qnode_backprop = qml.QNode(circuit, dev, diff_method="backprop", interface="autograd") # parameter-shift t = timeit.repeat("qnode_shift(params)", globals=globals(), number=num, repeat=reps) @@ -353,8 +353,8 @@ def circuit(params): # Gradient timing # =============== - qnode_shift = qml.QNode(circuit, dev, diff_method="parameter-shift") - qnode_backprop = qml.QNode(circuit, dev, diff_method="backprop") + qnode_shift = qml.QNode(circuit, dev, diff_method="parameter-shift", interface="autograd") + qnode_backprop = qml.QNode(circuit, dev, diff_method="backprop", interface="autograd") # parameter-shift t = timeit.repeat("qml.grad(qnode_shift)(params)", globals=globals(), number=num, repeat=reps) diff --git a/demonstrations/tutorial_barren_plateaus.py b/demonstrations/tutorial_barren_plateaus.py index f5209dd09e..876e18dfff 100644 --- a/demonstrations/tutorial_barren_plateaus.py +++ b/demonstrations/tutorial_barren_plateaus.py @@ -132,7 +132,7 @@ def rand_circuit(params, random_gate_sequence=None, num_qubits=None): for i in range(num_samples): gate_sequence = {i: np.random.choice(gate_set) for i in range(num_qubits)} - qcircuit = qml.QNode(rand_circuit, dev) + qcircuit = qml.QNode(rand_circuit, dev, interface="autograd") grad = qml.grad(qcircuit, argnum=0) params = np.random.uniform(0, 2 * np.pi, size=num_qubits) gradient = grad(params, random_gate_sequence=gate_sequence, num_qubits=num_qubits) @@ -161,7 +161,7 @@ def rand_circuit(params, random_gate_sequence=None, num_qubits=None): grad_vals = [] for i in range(num_samples): dev = qml.device("default.qubit", wires=num_qubits) - qcircuit = qml.QNode(rand_circuit, dev) + qcircuit = qml.QNode(rand_circuit, dev, interface="autograd") grad = qml.grad(qcircuit, argnum=0) gate_set = [qml.RX, qml.RY, qml.RZ] diff --git a/demonstrations/tutorial_classical_kernels.py b/demonstrations/tutorial_classical_kernels.py index 7b73263966..cecc229c68 100644 --- a/demonstrations/tutorial_classical_kernels.py +++ b/demonstrations/tutorial_classical_kernels.py @@ -416,7 +416,7 @@ def ansatz(x1, x2, thetas, amplitudes, wires): ############################################################################### # Next, we construct the quantum node: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def QK_circuit(x1, x2, thetas, amplitudes): ansatz(x1, x2, thetas, amplitudes, wires = range(n_wires)) return qml.probs(wires = range(n_wires)) diff --git a/demonstrations/tutorial_classically_boosted_vqe.py b/demonstrations/tutorial_classically_boosted_vqe.py index 0621a66170..0bd1707812 100644 --- a/demonstrations/tutorial_classically_boosted_vqe.py +++ b/demonstrations/tutorial_classically_boosted_vqe.py @@ -154,7 +154,7 @@ def circuit_VQE(theta, wires): # dev = qml.device('default.qubit', wires=qubits) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def cost_fn(theta): circuit_VQE(theta,range(qubits)) return qml.expval(H) @@ -424,7 +424,7 @@ def cost_fn(theta): wires = range(qubits + 1) dev = qml.device("default.qubit", wires=wires) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def hadamard_test(Uq, Ucl, component='real'): if component == 'imag': diff --git a/demonstrations/tutorial_coherent_vqls.py b/demonstrations/tutorial_coherent_vqls.py index 83f4d9672f..2001971d0f 100644 --- a/demonstrations/tutorial_coherent_vqls.py +++ b/demonstrations/tutorial_coherent_vqls.py @@ -361,7 +361,7 @@ def full_circuit(weights): dev = qml.device("default.qubit", wires=tot_qubits) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def global_ground(weights): # Circuit gates full_circuit(weights) @@ -370,7 +370,7 @@ def global_ground(weights): P[0, 0] = 1.0 return qml.expval(qml.Hermitian(P, wires=range(tot_qubits))) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def ancilla_ground(weights): # Circuit gates full_circuit(weights) @@ -489,7 +489,7 @@ def cost(weights): dev_x = qml.device("default.qubit", wires=n_qubits, shots=n_shots) -@qml.qnode(dev_x) +@qml.qnode(dev_x, interface="autograd") def prepare_and_sample(weights): # Variational circuit generating a guess for the solution vector |x> diff --git a/demonstrations/tutorial_data_reuploading_classifier.py b/demonstrations/tutorial_data_reuploading_classifier.py index 3e5b9a4357..7d1ae371cc 100644 --- a/demonstrations/tutorial_data_reuploading_classifier.py +++ b/demonstrations/tutorial_data_reuploading_classifier.py @@ -262,7 +262,7 @@ def density_matrix(state): # Install any pennylane-plugin to run on some particular backend -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def qcircuit(params, x, y): """A variational quantum circuit representing the Universal classifier. diff --git a/demonstrations/tutorial_diffable_shadows.py b/demonstrations/tutorial_diffable_shadows.py index 9653b19f8b..28861db562 100644 --- a/demonstrations/tutorial_diffable_shadows.py +++ b/demonstrations/tutorial_diffable_shadows.py @@ -105,7 +105,7 @@ H = qml.Hamiltonian([1., 1.], [qml.PauliZ(0) @ qml.PauliZ(1), qml.PauliX(0) @ qml.PauliX(1)]) dev = qml.device("default.qubit", wires=range(2), shots=10000) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def qnode(x, H): qml.Hadamard(0) qml.CNOT((0,1)) @@ -132,7 +132,7 @@ def qnode(x, H): # class methods. dev = qml.device("default.qubit", wires=range(2), shots=1000) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def qnode(x): qml.Hadamard(0) qml.CNOT((0,1)) @@ -196,7 +196,7 @@ def circuit(): obs = qml.PauliX(0) @ qml.PauliZ(3) @ qml.PauliX(6) @ qml.PauliZ(7) dev_ideal = qml.device("default.qubit", wires=range(n_wires), shots=None) -@qml.qnode(dev_ideal) +@qml.qnode(dev_ideal, interface="autograd") def qnode_ideal(): circuit() return qml.expval(obs) @@ -214,12 +214,12 @@ def qnode_ideal(): # repeating experiment 10 times to obtain averages and standard deviations dev = qml.device("default.qubit", wires=range(10), shots=shots) - @qml.qnode(dev) + @qml.qnode(dev, interface="autograd") def qnode_finite(): circuit() return qml.expval(obs) - @qml.qnode(dev) + @qml.qnode(dev, interface="autograd") def qnode_shadow(): circuit() return qml.shadow_expval(obs) @@ -297,7 +297,7 @@ def circuit(): for i in range(n): qml.CNOT((i, (i+1)%n)) -@qml.qnode(dev_ideal) +@qml.qnode(dev_ideal, interface="autograd") def qnode_ideal(): circuit() return qml.expval(H) @@ -311,7 +311,7 @@ def qnode_ideal(): coeffs = np.random.rand(len(all_observables)) H = qml.Hamiltonian(coeffs, all_observables, grouping_type="qwc") - @qml.qnode(dev_ideal) + @qml.qnode(dev_ideal, interface="autograd") def qnode_ideal(): circuit() return qml.expval(H) @@ -321,13 +321,13 @@ def qnode_ideal(): for _ in range(10): dev = qml.device("default.qubit", wires=range(5), shots=shots) - @qml.qnode(dev) + @qml.qnode(dev, interface="autograd") def qnode_finite(): circuit() return qml.expval(H) dev = qml.device("default.qubit", wires=range(5), shots=shots*n_groups) - @qml.qnode(dev) + @qml.qnode(dev, interface="autograd") def qnode_shadow(): circuit() return qml.shadow_expval(H) @@ -421,7 +421,7 @@ def circuit(): # execute qwc measurements dev_finite = qml.device("default.qubit", wires=range(n_wires), shots=int(shots)) - @qml.qnode(dev_finite) + @qml.qnode(dev_finite, interface="autograd") def qnode_finite(H): circuit() return qml.expval(H) @@ -431,7 +431,7 @@ def qnode_finite(H): # execute shadows measurements dev_shadow = qml.device("default.qubit", wires=range(n_wires), shots=int(shots)*n_groups) - @qml.qnode(dev_shadow) + @qml.qnode(dev_shadow, interface="autograd") def qnode(): circuit() return classical_shadow(wires=range(n_wires)) diff --git a/demonstrations/tutorial_differentiable_HF.py b/demonstrations/tutorial_differentiable_HF.py index 512a4f82c7..fc147f43b4 100644 --- a/demonstrations/tutorial_differentiable_HF.py +++ b/demonstrations/tutorial_differentiable_HF.py @@ -267,7 +267,7 @@ dev = qml.device("default.qubit", wires=4) def energy(mol): - @qml.qnode(dev) + @qml.qnode(dev, interface="autograd") def circuit(*args): qml.BasisState(np.array([1, 1, 0, 0]), wires=range(4)) qml.DoubleExcitation(*args[0][0], wires=[0, 1, 2, 3]) diff --git a/demonstrations/tutorial_doubly_stochastic.py b/demonstrations/tutorial_doubly_stochastic.py index 3153900461..df31247a34 100644 --- a/demonstrations/tutorial_doubly_stochastic.py +++ b/demonstrations/tutorial_doubly_stochastic.py @@ -151,8 +151,8 @@ def circuit(params): # Now, we create three QNodes, each corresponding to a device above, # and optimize them using gradient descent via the parameter-shift rule. -qnode_analytic = qml.QNode(circuit, dev_analytic) -qnode_stochastic = qml.QNode(circuit, dev_stochastic) +qnode_analytic = qml.QNode(circuit, dev_analytic, interface="autograd") +qnode_stochastic = qml.QNode(circuit, dev_stochastic, interface="autograd") param_shape = StronglyEntanglingLayers.shape(n_layers=num_layers, n_wires=num_wires) init_params = np.random.uniform(low=0, high=2*np.pi, size=param_shape, requires_grad=True) @@ -293,7 +293,7 @@ def circuit(params): ) -@qml.qnode(dev_stochastic) +@qml.qnode(dev_stochastic, interface="autograd") def circuit(params, n=None): StronglyEntanglingLayers(weights=params, wires=[0, 1]) idx = np.random.choice(np.arange(5), size=n, replace=False) diff --git a/demonstrations/tutorial_expressivity_fourier_series.py b/demonstrations/tutorial_expressivity_fourier_series.py index 4614bff616..be09145d18 100644 --- a/demonstrations/tutorial_expressivity_fourier_series.py +++ b/demonstrations/tutorial_expressivity_fourier_series.py @@ -284,7 +284,7 @@ def W(theta): qml.Rot(theta[0], theta[1], theta[2], wires=0) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def serial_quantum_model(weights, x): for theta in weights[:-1]: @@ -489,7 +489,7 @@ def cost(weights, x, y): dev = qml.device('default.qubit', wires=4) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def ansatz(weights): StronglyEntanglingLayers(weights, wires=range(n_qubits)) return qml.expval(qml.Identity(wires=0)) @@ -517,7 +517,7 @@ def W(theta): StronglyEntanglingLayers(theta, wires=range(r)) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def parallel_quantum_model(weights, x): W(weights[0]) @@ -675,7 +675,7 @@ def W(theta): BasicEntanglerLayers(theta, wires=range(n_qubits)) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def quantum_model(weights, x): W(weights[0]) diff --git a/demonstrations/tutorial_falqon.py b/demonstrations/tutorial_falqon.py index 6962dcb415..b913530f8e 100644 --- a/demonstrations/tutorial_falqon.py +++ b/demonstrations/tutorial_falqon.py @@ -250,7 +250,7 @@ def expval_circuit(beta, measurement_h): def max_clique_falqon(graph, n, beta_1, delta_t, dev): comm_h = build_hamiltonian(graph) # Builds the commutator cost_h, driver_h = qaoa.max_clique(graph, constrained=False) # Builds H_c and H_d - cost_fn = qml.QNode(expval_circuit, dev) # The ansatz + measurement circuit is executable + cost_fn = qml.QNode(expval_circuit, dev, interface="autograd") # The ansatz + measurement circuit is executable beta = [beta_1] # Records each value of beta_k energies = [] # Records the value of the cost function at each step @@ -296,7 +296,7 @@ def max_clique_falqon(graph, n, beta_1, delta_t, dev): # we can create a graph showing the probability of measuring each possible bit string. # We define the following circuit, feeding in the optimal values of :math:`\beta_k`: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def prob_circuit(): ansatz = build_maxclique_ansatz(cost_h, driver_h, delta_t) ansatz(res_beta) @@ -418,7 +418,7 @@ def qaoa_circuit(params, **kwargs): qml.layer(qaoa_layer, depth, params[0], params[1]) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def qaoa_expval(params): qaoa_circuit(params) return qml.expval(cost_h) @@ -450,7 +450,7 @@ def qaoa_expval(params): # define a circuit which outputs the probabilities of measuring each bit string, and # create a bar graph: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def prob_circuit(params): qaoa_circuit(params) return qml.probs(wires=dev.wires) diff --git a/demonstrations/tutorial_givens_rotations.py b/demonstrations/tutorial_givens_rotations.py index 5c1ce99a83..948964e036 100644 --- a/demonstrations/tutorial_givens_rotations.py +++ b/demonstrations/tutorial_givens_rotations.py @@ -189,7 +189,7 @@ dev = qml.device('default.qubit', wires=3) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(x, y): # prepares the reference state |100> qml.BasisState(np.array([1, 0, 0]), wires=[0, 1, 2]) @@ -260,7 +260,7 @@ def circuit(x, y): dev2 = qml.device('default.qubit', wires=6) -@qml.qnode(dev2) +@qml.qnode(dev2, interface="autograd") def circuit2(x, y): # prepares reference state qml.BasisState(np.array([1, 1, 1, 0, 0, 0]), wires=[0, 1, 2, 3, 4, 5]) @@ -356,7 +356,7 @@ def circuit2(x, y): dev = qml.device('default.qubit', wires=6) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit3(x, y, z): qml.BasisState(np.array([1, 1, 0, 0, 0, 0]), wires=[i for i in range(6)]) qml.DoubleExcitation(x, wires=[0, 1, 2, 3]) @@ -380,7 +380,7 @@ def circuit3(x, y, z): # above, this time controlling on the state of the first qubit and verify that we can prepare the # desired state. To perform the control, we use the :func:`~.pennylane.ctrl` transform: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit4(x, y, z): qml.BasisState(np.array([1, 1, 0, 0, 0, 0]), wires=[i for i in range(6)]) qml.DoubleExcitation(x, wires=[0, 1, 2, 3]) @@ -438,7 +438,7 @@ def circuit4(x, y, z): dev = qml.device('default.qubit', wires=4) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def state_preparation(params): qml.BasisState(np.array([1, 1, 0, 0]), wires=[0, 1, 2, 3]) qml.SingleExcitation(params[0], wires=[1, 2]) diff --git a/demonstrations/tutorial_kernel_based_training.py b/demonstrations/tutorial_kernel_based_training.py index 2a786fe4e2..0c8126c61c 100644 --- a/demonstrations/tutorial_kernel_based_training.py +++ b/demonstrations/tutorial_kernel_based_training.py @@ -254,7 +254,7 @@ projector = np.zeros((2**n_qubits, 2**n_qubits)) projector[0, 0] = 1 -@qml.qnode(dev_kernel) +@qml.qnode(dev_kernel, interface="autograd") def kernel(x1, x2): """The quantum kernel.""" AngleEmbedding(x1, wires=range(n_qubits)) diff --git a/demonstrations/tutorial_kernels_module.py b/demonstrations/tutorial_kernels_module.py index c7d226fc8d..0b90f5c9f7 100644 --- a/demonstrations/tutorial_kernels_module.py +++ b/demonstrations/tutorial_kernels_module.py @@ -292,7 +292,7 @@ def random_params(num_wires, num_layers): # finally extract the probabilities of observing each basis state. -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def kernel_circuit(x1, x2, params): ansatz(x1, params, wires=wires) adjoint_ansatz(x2, params, wires=wires) diff --git a/demonstrations/tutorial_local_cost_functions.py b/demonstrations/tutorial_local_cost_functions.py index 75ade6e3d5..580d64a851 100644 --- a/demonstrations/tutorial_local_cost_functions.py +++ b/demonstrations/tutorial_local_cost_functions.py @@ -124,9 +124,9 @@ def local_cost_simple(rotations): qml.RY(rotations[1][i], wires=i) return [qml.probs(wires=i) for i in range(wires)] -global_circuit = qml.QNode(global_cost_simple, dev) +global_circuit = qml.QNode(global_cost_simple, dev, interface="autograd") -local_circuit = qml.QNode(local_cost_simple, dev) +local_circuit = qml.QNode(local_cost_simple, dev, interface="autograd") def cost_local(rotations): return 1 - np.sum(local_circuit(rotations)[:,0])/wires @@ -252,9 +252,9 @@ def local_cost_simple(rotations): qml.broadcast(qml.CNOT, wires=range(wires), pattern="chain") return qml.probs(wires=[0]) -global_circuit = qml.QNode(global_cost_simple, dev) +global_circuit = qml.QNode(global_cost_simple, dev, interface="autograd") -local_circuit = qml.QNode(local_cost_simple, dev) +local_circuit = qml.QNode(local_cost_simple, dev, interface="autograd") def cost_local(rotations): return 1 - local_circuit(rotations)[0] @@ -344,7 +344,7 @@ def cost_global(rotations): # dev.shots = None -global_circuit = qml.QNode(global_cost_simple, dev) +global_circuit = qml.QNode(global_cost_simple, dev, interface="autograd") print( "Current cost: " + str(cost_global(params_local)) @@ -378,7 +378,7 @@ def cost_tunable(rotations): return 1 - tunable_circuit(rotations)[0] dev.shots = 10000 -tunable_circuit = qml.QNode(tunable_cost_simple, dev) +tunable_circuit = qml.QNode(tunable_cost_simple, dev, interface="autograd") locality = 2 params_tunable = params_local fig, ax = qml.draw_mpl(tunable_circuit, decimals=2)(params_tunable) @@ -441,7 +441,7 @@ def cost_tunable(rotations): wires = 8 dev = qml.device("default.qubit", wires=wires, shots=10000) -global_circuit = qml.QNode(global_cost_simple, dev) +global_circuit = qml.QNode(global_cost_simple, dev, interface="autograd") for runs in range(samples): print("--- New run! ---") @@ -474,7 +474,7 @@ def cost_tunable(rotations): wires = 8 dev = qml.device("default.qubit", wires=wires, shots=10000) -tunable_circuit = qml.QNode(tunable_cost_simple, dev) +tunable_circuit = qml.QNode(tunable_cost_simple, dev, interface="autograd") for runs in range(samples): locality = 1 diff --git a/demonstrations/tutorial_mbqc.py b/demonstrations/tutorial_mbqc.py index b59366e35b..d23e4ca68b 100644 --- a/demonstrations/tutorial_mbqc.py +++ b/demonstrations/tutorial_mbqc.py @@ -97,7 +97,7 @@ dev = qml.device("default.qubit", wires=qubits) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def cluster_state(): for node in qubits: qml.Hadamard(wires=[node]) @@ -159,7 +159,7 @@ def cluster_state(): dev = qml.device("default.qubit", wires=2) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def one_bit_teleportation(input_state): # Prepare the input state qml.QubitStateVector(input_state, wires=0) @@ -302,7 +302,7 @@ def generate_random_state(n=1): dev = qml.device("default.qubit", wires=1) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def RZ(theta, input_state): # Prepare the input state qml.QubitStateVector(input_state, wires=0) @@ -323,7 +323,7 @@ def RZ(theta, input_state): mbqc_dev = qml.device("default.qubit", wires=2) -@qml.qnode(mbqc_dev) +@qml.qnode(mbqc_dev, interface="autograd") def RZ_MBQC(theta, input_state): # Prepare the input state qml.QubitStateVector(input_state, wires=0) @@ -364,7 +364,7 @@ def RZ_MBQC(theta, input_state): dev = qml.device("default.qubit", wires=1) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def RX(theta, input_state): # Prepare the input state qml.QubitStateVector(input_state, wires=0) @@ -379,7 +379,7 @@ def RX(theta, input_state): mbqc_dev = qml.device("default.qubit", wires=3) -@qml.qnode(mbqc_dev) +@qml.qnode(mbqc_dev, interface="autograd") def RX_MBQC(theta, input_state): # Prepare the input state qml.QubitStateVector(input_state, wires=0) @@ -444,7 +444,7 @@ def RX_MBQC(theta, input_state): dev = qml.device("default.qubit", wires=2) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def CNOT(input_state): # Prepare the input state qml.QubitStateVector(input_state, wires=[0, 1]) @@ -456,7 +456,7 @@ def CNOT(input_state): mbqc_dev = qml.device("default.qubit", wires=4) -@qml.qnode(mbqc_dev) +@qml.qnode(mbqc_dev, interface="autograd") def CNOT_MBQC(input_state): # Prepare the input state qml.QubitStateVector(input_state, wires=[0, 1]) diff --git a/demonstrations/tutorial_measurement_optimize.py b/demonstrations/tutorial_measurement_optimize.py index cd6310bc29..d5d3f4c0f7 100644 --- a/demonstrations/tutorial_measurement_optimize.py +++ b/demonstrations/tutorial_measurement_optimize.py @@ -141,7 +141,7 @@ ) # generate the cost function -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def cost_circuit(params): ansatz(params, wires=dev.wires) return qml.expval(H) @@ -386,13 +386,13 @@ def cost_circuit(params): dev = qml.device("default.qubit", wires=3) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit1(weights): qml.StronglyEntanglingLayers(weights, wires=range(3)) return qml.expval(obs[0]) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit2(weights): qml.StronglyEntanglingLayers(weights, wires=range(3)) return qml.expval(obs[1]) @@ -407,7 +407,7 @@ def circuit2(weights): # Now, let's use our QWC approach to reduce this down to a *single* measurement # of the probabilities in the shared eigenbasis of both QWC observables: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit_qwc(weights): qml.StronglyEntanglingLayers(weights, wires=range(3)) @@ -453,7 +453,7 @@ def circuit_qwc(weights): # Luckily, PennyLane automatically performs this QWC grouping under the hood. We simply # return the two QWC Pauli terms from the QNode: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(weights): qml.StronglyEntanglingLayers(weights, wires=range(3)) return [ @@ -704,7 +704,7 @@ def format_pauli_word(term): dev = qml.device("default.qubit", wires=4) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(weights, group=None, **kwargs): qml.StronglyEntanglingLayers(weights, wires=range(4)) return [qml.expval(o) for o in group] @@ -729,7 +729,7 @@ def circuit(weights, group=None, **kwargs): # automatically optimize the measurements. H = qml.Hamiltonian(coeffs=np.ones(len(terms)), observables=terms, grouping_type="qwc") -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def cost_fn(weights): qml.StronglyEntanglingLayers(weights, wires=range(4)) return qml.expval(H) diff --git a/demonstrations/tutorial_mol_geo_opt.py b/demonstrations/tutorial_mol_geo_opt.py index 76b43f617c..108604dfd7 100644 --- a/demonstrations/tutorial_mol_geo_opt.py +++ b/demonstrations/tutorial_mol_geo_opt.py @@ -195,7 +195,7 @@ def H(x): dev = qml.device("default.qubit", wires=num_wires) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(params, obs, wires): qml.BasisState(hf, wires=wires) qml.DoubleExcitation(params[0], wires=[0, 1, 2, 3]) diff --git a/demonstrations/tutorial_noisy_circuit_optimization.py b/demonstrations/tutorial_noisy_circuit_optimization.py index 879b4967e3..8a8f73cb3b 100644 --- a/demonstrations/tutorial_noisy_circuit_optimization.py +++ b/demonstrations/tutorial_noisy_circuit_optimization.py @@ -94,39 +94,40 @@ B2 = qml.Hermitian(np.array([[1, -1], [-1, -1]]) / np.sqrt(2), wires=1) CHSH_observables = [A1 @ B1, A1 @ B2, A2 @ B1, A2 @ B2] + # subcircuit for creating an entangled pair of qubits def bell_pair(): qml.Hadamard(wires=0) qml.CNOT(wires=[0, 1]) + # circuits for measuring each distinct observable @qml.qnode(dev) def measure_A1B1(): bell_pair() return qml.expval(A1 @ B1) + @qml.qnode(dev) def measure_A1B2(): bell_pair() return qml.expval(A1 @ B2) + @qml.qnode(dev) def measure_A2B1(): bell_pair() return qml.expval(A2 @ B1) + @qml.qnode(dev) def measure_A2B2(): bell_pair() return qml.expval(A2 @ B2) -circuits = qml.QNodeCollection([measure_A1B1, - measure_A1B2, - measure_A2B1, - measure_A2B2]) # now we measure each circuit and construct the CHSH inequality -expvals = circuits() +expvals = [measure_A1B1(), measure_A1B2(), measure_A2B1(), measure_A2B2()] # The CHSH operator is A1 @ B1 + A1 @ B2 + A2 @ B1 - A2 @ B2 CHSH_expval = np.sum(expvals[:3]) - expvals[3] @@ -152,10 +153,11 @@ def measure_A2B2(): # circuit declarations. from pennylane_cirq import ops as cirq_ops + # Note that the 'Operation' op is a generic base class # from PennyLane core. # All other ops are provided by Cirq. -available_ops = [op for op in dir(cirq_ops) if not op.startswith('_')] +available_ops = [op for op in dir(cirq_ops) if not op.startswith("_")] print("\n".join(available_ops)) ############################################################################## @@ -181,23 +183,20 @@ def bell_pair(): qml.CNOT(wires=[0, 1]) cirq_ops.BitFlip(p, wires=0) cirq_ops.BitFlip(p, wires=1) + # measuring the circuits will now use the new noisy bell_pair() function - expvals = circuits() + expvals = [measure_A1B1(), measure_A1B2(), measure_A2B1(), measure_A2B2()] noisy_expvals.append(expvals) noisy_expvals = np.array(noisy_expvals) -CHSH_expvals = np.sum(noisy_expvals[:,:3], axis=1) - noisy_expvals[:,3] +CHSH_expvals = np.sum(noisy_expvals[:, :3], axis=1) - noisy_expvals[:, 3] # Plot the individual observables -plt.plot(noise_vals, noisy_expvals[:, 0], 'D', - label = r"$\hat{A1}\otimes \hat{B1}$", markersize=5) -plt.plot(noise_vals, noisy_expvals[:, 1], 'x', - label = r"$\hat{A1}\otimes \hat{B2}$", markersize=12) -plt.plot(noise_vals, noisy_expvals[:, 2], '+', - label = r"$\hat{A2}\otimes \hat{B1}$", markersize=10) -plt.plot(noise_vals, noisy_expvals[:, 3], 'v', - label = r"$\hat{A2}\otimes \hat{B2}$", markersize=10) -plt.xlabel('Noise parameter') -plt.ylabel(r'Expectation value $\langle \hat{A}_i\otimes\hat{B}_j\rangle$') +plt.plot(noise_vals, noisy_expvals[:, 0], "D", label=r"$\hat{A1}\otimes \hat{B1}$", markersize=5) +plt.plot(noise_vals, noisy_expvals[:, 1], "x", label=r"$\hat{A1}\otimes \hat{B2}$", markersize=12) +plt.plot(noise_vals, noisy_expvals[:, 2], "+", label=r"$\hat{A2}\otimes \hat{B1}$", markersize=10) +plt.plot(noise_vals, noisy_expvals[:, 3], "v", label=r"$\hat{A2}\otimes \hat{B2}$", markersize=10) +plt.xlabel("Noise parameter") +plt.ylabel(r"Expectation value $\langle \hat{A}_i\otimes\hat{B}_j\rangle$") plt.legend() plt.show() @@ -223,10 +222,9 @@ def bell_pair(): # values greater than 2 can safely be considered "quantum". plt.plot(noise_vals, CHSH_expvals, label="CHSH") -plt.plot(noise_vals, 2 * np.ones_like(noise_vals), - label="Quantum-classical boundary") -plt.xlabel('Noise parameter') -plt.ylabel('CHSH Expectation value') +plt.plot(noise_vals, 2 * np.ones_like(noise_vals), label="Quantum-classical boundary") +plt.xlabel("Noise parameter") +plt.ylabel("CHSH Expectation value") plt.legend() plt.show() @@ -260,6 +258,7 @@ def bell_pair(): # technique for modelling noise, but may not be appropriate for all # situations. + @qml.qnode(dev) def circuit(gate_params, noise_param=0.0): qml.RX(gate_params[0], wires=0) @@ -267,6 +266,7 @@ def circuit(gate_params, noise_param=0.0): cirq_ops.Depolarize(noise_param, wires=0) return qml.expval(qml.PauliZ(0)) + gate_pars = [0.54, 0.12] print("Expectation value:", circuit(gate_pars)) @@ -284,12 +284,12 @@ def circuit(gate_params, noise_param=0.0): # :class:`~pennylane.ops.PauliZ` expectation value changes as # a function of the noise strength. -noise_vals = np.linspace(0., 1., 20) +noise_vals = np.linspace(0.0, 1.0, 20) expvals = [circuit(gate_pars, noise_param=p) for p in noise_vals] plt.plot(noise_vals, expvals, label="Expectation value") -plt.plot(noise_vals, np.ones_like(noise_vals), '--', label="Highest possible") -plt.plot(noise_vals, -np.ones_like(noise_vals), '--', label="Lowest possible") +plt.plot(noise_vals, np.ones_like(noise_vals), "--", label="Highest possible") +plt.plot(noise_vals, -np.ones_like(noise_vals), "--", label="Lowest possible") plt.ylabel(r"Expectation value $\langle \hat{Z} \rangle$") plt.xlabel(r"Noise strength $p$") plt.legend() @@ -302,13 +302,16 @@ def circuit(gate_params, noise_param=0.0): # i.e., to tune the qubit state until it has a ``PauliZ`` expectation value # of :math:`-1` (the lowest possible). + # declare the cost functions to be optimized def cost(x): return circuit(x, noise_param=0.0) + def noisy_cost(x): return circuit(x, noise_param=0.3) + # initialize the optimizer opt = qml.GradientDescentOptimizer(stepsize=0.4) @@ -326,10 +329,11 @@ def noisy_cost(x): noisy_circuit_params = opt.step(noisy_cost, noisy_circuit_params) if (i + 1) % 5 == 0: - print("Step {:5d}. Cost: {: .7f}; Noisy Cost: {: .7f}". - format(i + 1, - cost(params), - noisy_cost(noisy_circuit_params))) + print( + "Step {:5d}. Cost: {: .7f}; Noisy Cost: {: .7f}".format( + i + 1, cost(params), noisy_cost(noisy_circuit_params) + ) + ) print("\nOptimized rotation angles (noise-free case):") print("({: .7f}, {: .7f})".format(*params)) @@ -452,17 +456,18 @@ def noisy_cost(x): angles = np.linspace(0, 2 * np.pi, 50) theta2 = np.pi / 4 + def param_shift(theta1): - return 0.5 * (noisy_cost([theta1 + np.pi / 2, theta2]) - \ - noisy_cost([theta1 - np.pi / 2, theta2])) + return 0.5 * ( + noisy_cost([theta1 + np.pi / 2, theta2]) - noisy_cost([theta1 - np.pi / 2, theta2]) + ) + noisy_expvals = [noisy_cost([theta1, theta2]) for theta1 in angles] noisy_param_shift = [param_shift(theta1) for theta1 in angles] -plt.plot(angles, noisy_expvals, - label="Expectation value") # looks like 0.4 * cos(phi) -plt.plot(angles, noisy_param_shift, - label="Parameter-shift value") # looks like -0.4 * sin(phi) +plt.plot(angles, noisy_expvals, label="Expectation value") # looks like 0.4 * cos(phi) +plt.plot(angles, noisy_param_shift, label="Parameter-shift value") # looks like -0.4 * sin(phi) plt.ylabel(r"Expectation value $\langle \hat{Z} \rangle$") plt.xlabel(r"Angle $\theta_1$") plt.legend() @@ -538,4 +543,4 @@ def param_shift(theta1): # # About the author # ---------------- -# .. include:: ../_static/authors/nathan_killoran.txt \ No newline at end of file +# .. include:: ../_static/authors/nathan_killoran.txt diff --git a/demonstrations/tutorial_plugins_hybrid.py b/demonstrations/tutorial_plugins_hybrid.py index f7a24efffa..8ebc31d08f 100644 --- a/demonstrations/tutorial_plugins_hybrid.py +++ b/demonstrations/tutorial_plugins_hybrid.py @@ -260,7 +260,7 @@ def cost(params): dev_fock = qml.device("strawberryfields.fock", wires=2, cutoff_dim=10) -@qml.qnode(dev_qubit) +@qml.qnode(dev_qubit, interface="autograd") def qubit_rotation(phi1, phi2): """Qubit rotation QNode""" qml.RX(phi1, wires=0) diff --git a/demonstrations/tutorial_qgrnn.py b/demonstrations/tutorial_qgrnn.py index 695ff344af..a88df5799d 100644 --- a/demonstrations/tutorial_qgrnn.py +++ b/demonstrations/tutorial_qgrnn.py @@ -557,7 +557,7 @@ def cost_function(weight_params, bias_params): qgrnn_dev = qml.device("default.qubit", wires=2 * qubit_number + 1) # Defines the new QNode -qgrnn_qnode = qml.QNode(qgrnn, qgrnn_dev) +qgrnn_qnode = qml.QNode(qgrnn, qgrnn_dev, interface="autograd") steps = 300 diff --git a/demonstrations/tutorial_quantum_natural_gradient.py b/demonstrations/tutorial_quantum_natural_gradient.py index 2e7e6f053c..22f8b7fd21 100644 --- a/demonstrations/tutorial_quantum_natural_gradient.py +++ b/demonstrations/tutorial_quantum_natural_gradient.py @@ -192,7 +192,7 @@ dev = qml.device("default.qubit", wires=3) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(params): # |psi_0>: state preparation qml.RY(np.pi / 4, wires=0) @@ -273,7 +273,7 @@ def layer0_subcircuit(params): # We can see that the diagonal terms are simply given by the variance: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def layer0_diag(params): layer0_subcircuit(params) return qml.var(qml.PauliZ(0)), qml.var(qml.PauliZ(1)) @@ -289,13 +289,13 @@ def layer0_diag(params): # off-diagonal covariance terms of :math:`g^{(0)}`: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def layer0_off_diag_single(params): layer0_subcircuit(params) return qml.expval(qml.PauliZ(0)), qml.expval(qml.PauliZ(1)) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def layer0_off_diag_double(params): layer0_subcircuit(params) ZZ = np.kron(np.diag([1, -1]), np.diag([1, -1])) @@ -350,7 +350,7 @@ def layer1_subcircuit(params): # :target: javascript:void(0) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def layer1_diag(params): layer1_subcircuit(params) return qml.var(qml.PauliY(1)), qml.var(qml.PauliX(2)) @@ -369,13 +369,13 @@ def layer1_diag(params): # observables to be computed. -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def layer1_off_diag_single(params): layer1_subcircuit(params) return qml.expval(qml.PauliY(1)), qml.expval(qml.PauliX(2)) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def layer1_off_diag_double(params): layer1_subcircuit(params) X = np.array([[0, 1], [1, 0]]) diff --git a/demonstrations/tutorial_quanvolution.py b/demonstrations/tutorial_quanvolution.py index 465d261a78..43a3ea9c11 100644 --- a/demonstrations/tutorial_quanvolution.py +++ b/demonstrations/tutorial_quanvolution.py @@ -145,7 +145,7 @@ # Random circuit parameters rand_params = np.random.uniform(high=2 * np.pi, size=(n_layers, 4)) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(phi): # Encoding of 4 classical input values for j in range(4): diff --git a/demonstrations/tutorial_qubit_rotation.py b/demonstrations/tutorial_qubit_rotation.py index b8de2d943d..acc9ab0b19 100644 --- a/demonstrations/tutorial_qubit_rotation.py +++ b/demonstrations/tutorial_qubit_rotation.py @@ -214,7 +214,7 @@ def circuit(params): # **directly above** the function definition: -@qml.qnode(dev1) +@qml.qnode(dev1, interface="autograd") def circuit(params): qml.RX(params[0], wires=0) qml.RY(params[1], wires=0) @@ -266,7 +266,7 @@ def circuit(params): # two positional arguments, instead of one array argument: -@qml.qnode(dev1) +@qml.qnode(dev1, interface="autograd") def circuit2(phi1, phi2): qml.RX(phi1, wires=0) qml.RY(phi2, wires=0) diff --git a/demonstrations/tutorial_qubit_tapering.py b/demonstrations/tutorial_qubit_tapering.py index 1036c75866..5a77fe3458 100644 --- a/demonstrations/tutorial_qubit_tapering.py +++ b/demonstrations/tutorial_qubit_tapering.py @@ -177,8 +177,8 @@ # representation of Hamiltonians. This allows us to directly diagonalize them to obtain exact values # of the ground-state energies. -H_sparse = qml.SparseHamiltonian(qml.utils.sparse_hamiltonian(H), wires=H.wires) -H_tapered_sparse = qml.SparseHamiltonian(qml.utils.sparse_hamiltonian(H_tapered), wires=H_tapered.wires) +H_sparse = qml.SparseHamiltonian(H.sparse_matrix(), wires=H.wires) +H_tapered_sparse = qml.SparseHamiltonian(H_tapered.sparse_matrix(), wires=H_tapered.wires) print("Eigenvalues of H:\n", qml.eigvals(H_sparse, k=16)) print("\nEigenvalues of H_tapered:\n", qml.eigvals(H_tapered_sparse, k=4)) @@ -202,23 +202,23 @@ # Hartree-Fock energies for each Hamiltonian. dev = qml.device("default.qubit", wires=H.wires) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(): qml.BasisState(np.array([1, 1, 0, 0]), wires=H.wires) return qml.state() qubit_state = circuit() -HF_energy = qubit_state.T @ qml.utils.sparse_hamiltonian(H).toarray() @ qubit_state +HF_energy = qubit_state.T @ H.sparse_matrix().toarray() @ qubit_state print(f"HF energy: {np.real(HF_energy):.8f} Ha") dev = qml.device("default.qubit", wires=H_tapered.wires) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(): qml.BasisState(np.array([1, 1]), wires=H_tapered.wires) return qml.state() qubit_state = circuit() -HF_energy = qubit_state.T @ qml.utils.sparse_hamiltonian(H_tapered).toarray() @ qubit_state +HF_energy = qubit_state.T @ H_tapered.sparse_matrix().toarray() @ qubit_state print(f"HF energy (tapered): {np.real(HF_energy):.8f} Ha") ############################################################################## @@ -245,7 +245,7 @@ def circuit(): ] dev = qml.device("default.qubit", wires=H_tapered.wires) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def tapered_circuit(params): qml.BasisState(state_tapered, wires=H_tapered.wires) for idx, tapered_op in enumerate(tapered_doubles + tapered_singles): diff --git a/demonstrations/tutorial_rosalin.py b/demonstrations/tutorial_rosalin.py index 57a0d94e18..13368b6626 100644 --- a/demonstrations/tutorial_rosalin.py +++ b/demonstrations/tutorial_rosalin.py @@ -186,7 +186,7 @@ from pennylane.templates.layers import StronglyEntanglingLayers -@qml.qnode(non_analytic_dev, diff_method="parameter-shift") +@qml.qnode(non_analytic_dev, diff_method="parameter-shift", interface="autograd") def qnode(weights, observable): StronglyEntanglingLayers(weights, wires=non_analytic_dev.wires) return qml.expval(observable) @@ -235,7 +235,7 @@ def cost(params): # Here, we will split the 8000 total shots evenly across all Hamiltonian terms, # also known as *uniform deterministic sampling*. -@qml.qnode(non_analytic_dev, diff_method="parameter-shift") +@qml.qnode(non_analytic_dev, diff_method="parameter-shift", interface="autograd") def qnode(weights, obs): StronglyEntanglingLayers(weights, wires=non_analytic_dev.wires) return qml.expval(obs) @@ -448,7 +448,7 @@ def estimate_hamiltonian(self, params, shots): results = [] - @qml.qnode(rosalin_device, diff_method="parameter-shift") + @qml.qnode(rosalin_device, diff_method="parameter-shift", interface="autograd") def qnode(weights, observable): StronglyEntanglingLayers(weights, wires=rosalin_device.wires) return qml.sample(observable) @@ -555,7 +555,7 @@ def step(self, params): # also create a separate cost function using an 'exact' quantum device, so that we can keep track of the # *exact* cost function value at each iteration. -@qml.qnode(analytic_dev) +@qml.qnode(analytic_dev, interface="autograd") def cost_analytic(weights): StronglyEntanglingLayers(weights, wires=analytic_dev.wires) return qml.expval(qml.Hamiltonian(coeffs, obs)) @@ -593,7 +593,7 @@ def cost_analytic(weights): non_analytic_dev.shots = adam_shots_per_eval -@qml.qnode(non_analytic_dev, diff_method="parameter-shift") +@qml.qnode(non_analytic_dev, diff_method="parameter-shift", interface="autograd") def cost(weights): StronglyEntanglingLayers(weights, wires=non_analytic_dev.wires) return qml.expval(qml.Hamiltonian(coeffs, obs)) diff --git a/demonstrations/tutorial_sc_qubits.py b/demonstrations/tutorial_sc_qubits.py index 65b11d26d5..973fc1aa67 100644 --- a/demonstrations/tutorial_sc_qubits.py +++ b/demonstrations/tutorial_sc_qubits.py @@ -416,14 +416,14 @@ # Implement displacement and rotation and measure both X and P observables -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def measure_P_shots(time, state): qml.Displacement(epsilon * time, 0, wires=0) qml.Rotation((-1) ** state * chi * time, wires=0) return qml.sample(qml.P(0)) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def measure_X_shots(time, state): qml.Displacement(epsilon * time, 0, wires=0) qml.Rotation((-1) ** state * chi * time, wires=0) @@ -499,7 +499,7 @@ def measure_X_shots(time, state): dev2 = qml.device("default.qubit", wires=1) # Implement Hamiltonian evolution given phase phi and time t, from a given initial state -@qml.qnode(dev2) +@qml.qnode(dev2, interface="autograd") def H_evolve(state, phi, time): if state == 1: @@ -513,7 +513,7 @@ def H_evolve(state, phi, time): # Implement X rotation exactly -@qml.qnode(dev2) +@qml.qnode(dev2, interface="autograd") def Sc_X_rot(state, phi): if state == 1: @@ -524,7 +524,7 @@ def Sc_X_rot(state, phi): # Implement Y rotation exactly -@qml.qnode(dev2) +@qml.qnode(dev2, interface="autograd") def Sc_Y_rot(state, phi): if state == 1: @@ -617,7 +617,7 @@ def Sc_Y_rot(state, phi): Two_qubit_H = qml.Hamiltonian(coeffs, ops) # Implement Hamiltonian evolution for time t and some initial computational basis state -@qml.qnode(dev3) +@qml.qnode(dev3, interface="autograd") def Sc_ISWAP(basis_state, time): qml.templates.BasisStatePreparation(basis_state, wires=range(2)) ApproxTimeEvolution(Two_qubit_H, time, 1) @@ -625,7 +625,7 @@ def Sc_ISWAP(basis_state, time): # Implement ISWAP exactly -@qml.qnode(dev3) +@qml.qnode(dev3, interface="autograd") def iswap(basis_state): qml.templates.BasisStatePreparation(basis_state, wires=range(2)) qml.ISWAP(wires=[0, 1]) @@ -732,7 +732,7 @@ def cnot_with_iswap(): # the evolution under this Hamiltonian for a time :math:`t=\tfrac{\pi}{4\Omega}` with :math:`R_x` and :math:`R_y` rotations # and a ``qml.Hadamard`` gate: # -@qml.qnode(dev3) +@qml.qnode(dev3, interface="autograd") def H_evolve(state, phi, time): # Prepare initial state qml.templates.BasisStatePreparation(state, wires=range(2)) diff --git a/demonstrations/tutorial_testing_symmetry.py b/demonstrations/tutorial_testing_symmetry.py index a1bf46471b..9c858dd0e3 100644 --- a/demonstrations/tutorial_testing_symmetry.py +++ b/demonstrations/tutorial_testing_symmetry.py @@ -322,7 +322,7 @@ def CU_cpy(): # # Circuit for average symmetry -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def avg_symm(hamiltonian, time): # Use Choi-Jamiołkowski isomorphism diff --git a/demonstrations/tutorial_tn_circuits.py b/demonstrations/tutorial_tn_circuits.py index 3bb5e7c3b1..f91b2999f4 100644 --- a/demonstrations/tutorial_tn_circuits.py +++ b/demonstrations/tutorial_tn_circuits.py @@ -138,7 +138,7 @@ def block(weights, wires): dev = qml.device("default.qubit", wires=4) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(template_weights): qml.MPS( wires=range(4), @@ -173,7 +173,7 @@ def deep_block(weights, wires): dev = qml.device("default.qubit", wires=4) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(template_weights): qml.MPS( wires=range(4), @@ -222,7 +222,7 @@ def wide_block(weights, wires): dev = qml.device("default.qubit", wires=8) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(template_weights): qml.MPS( wires=range(8), @@ -253,7 +253,7 @@ def block(weights, wires): dev = qml.device("default.qubit", wires=8) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(template_weights): qml.TTN( wires=range(8), @@ -330,7 +330,7 @@ def block(weights, wires): dev = qml.device("default.qubit", wires=4) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(image, template_weights): qml.BasisStatePreparation(image, wires=range(4)) qml.TTN( diff --git a/demonstrations/tutorial_trapped_ions.py b/demonstrations/tutorial_trapped_ions.py index fd990fadcf..ee95f54799 100644 --- a/demonstrations/tutorial_trapped_ions.py +++ b/demonstrations/tutorial_trapped_ions.py @@ -422,7 +422,7 @@ def evolution(phi, t): dev = qml.device("default.qubit", wires=1) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def ion_hadamard(state): if state == 1: @@ -440,7 +440,7 @@ def ion_hadamard(state): return qml.state() #For comparison, we use the Hadamard built into PennyLane -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def hadamard(state): if state == 1: @@ -459,7 +459,7 @@ def hadamard(state): # A similar exercise can be done for the :math:`T` gate: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def ion_Tgate(state): if state == 1: @@ -472,7 +472,7 @@ def ion_Tgate(state): return qml.state() -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def tgate(state): if state == 1: @@ -504,7 +504,7 @@ def tgate(state): import matplotlib.pyplot as plt -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def evolution_prob(t): qml.QubitUnitary(evolution(0, t / Omega), wires=0) @@ -811,7 +811,7 @@ def Molmer_Sorensen(t): dev2 = qml.device("default.qubit",wires=2) -@qml.qnode(dev2) +@qml.qnode(dev2, interface="autograd") def ion_cnot(basis_state): #Prepare the two-qubit basis states from the input @@ -827,7 +827,7 @@ def ion_cnot(basis_state): return qml.state() #Compare with built-in CNOT -@qml.qnode(dev2) +@qml.qnode(dev2, interface="autograd") def cnot_gate(basis_state): qml.templates.BasisStatePreparation(basis_state, wires=range(2)) diff --git a/demonstrations/tutorial_variational_classifier.py b/demonstrations/tutorial_variational_classifier.py index c4a7ff1059..411a8bcc0f 100644 --- a/demonstrations/tutorial_variational_classifier.py +++ b/demonstrations/tutorial_variational_classifier.py @@ -113,7 +113,7 @@ def statepreparation(x): # we call the parameters ``weights``. -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(weights, x): statepreparation(x) @@ -318,7 +318,7 @@ def statepreparation(a): ang = get_angles(x) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def test(angles): statepreparation(angles) @@ -355,7 +355,7 @@ def layer(W): # layer functions. -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def circuit(weights, angles): statepreparation(angles) diff --git a/demonstrations/tutorial_vqe.py b/demonstrations/tutorial_vqe.py index e8ebad0245..f5065bc8da 100644 --- a/demonstrations/tutorial_vqe.py +++ b/demonstrations/tutorial_vqe.py @@ -146,7 +146,7 @@ def circuit(param, wires): # run the cost function as an executable QNode with the gate parameter :math:`\theta`: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def cost_fn(param): circuit(param, wires=range(qubits)) return qml.expval(H) diff --git a/demonstrations/tutorial_vqe_qng.py b/demonstrations/tutorial_vqe_qng.py index 4eecfdbccb..806a490372 100644 --- a/demonstrations/tutorial_vqe_qng.py +++ b/demonstrations/tutorial_vqe_qng.py @@ -64,7 +64,7 @@ def circuit(params, wires=0): H = qml.Hamiltonian(coeffs, obs) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def cost_fn(params): circuit(params) return qml.expval(H) @@ -297,7 +297,7 @@ def ansatz(params, wires=[0, 1, 2, 3]): # the Hartree-Fock state of the hydrogen molecule described in the minimal basis. # Again, we define the cost function to be the following QNode that measures ``expval(H)``: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def cost(params): ansatz(params) return qml.expval(hamiltonian) diff --git a/demonstrations/tutorial_vqe_spin_sectors.py b/demonstrations/tutorial_vqe_spin_sectors.py index 04f03f2fc1..9596a81271 100644 --- a/demonstrations/tutorial_vqe_spin_sectors.py +++ b/demonstrations/tutorial_vqe_spin_sectors.py @@ -191,7 +191,7 @@ def circuit(params, wires): # a cost function that can be evaluated with the circuit parameters: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def cost_fn(params): circuit(params, wires=range(qubits)) return qml.expval(H) @@ -202,7 +202,7 @@ def cost_fn(params): # we can now define a function to compute its expectation value: -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def S2_exp_value(params): circuit(params, wires=range(qubits)) return qml.expval(S2) @@ -304,13 +304,13 @@ def circuit(params, wires): # and the total spin operator for the new circuit. -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def cost_fn(params): circuit(params, wires=range(qubits)) return qml.expval(H) -@qml.qnode(dev) +@qml.qnode(dev, interface="autograd") def S2_exp_value(params): circuit(params, wires=range(qubits)) return qml.expval(S2) diff --git a/demonstrations/tutorial_vqls.py b/demonstrations/tutorial_vqls.py index 64d7db0792..d4c3ac1746 100644 --- a/demonstrations/tutorial_vqls.py +++ b/demonstrations/tutorial_vqls.py @@ -280,7 +280,7 @@ def variational_block(weights): dev_mu = qml.device("default.qubit", wires=tot_qubits) -@qml.qnode(dev_mu) +@qml.qnode(dev_mu, interface="autograd") def local_hadamard_test(weights, l=None, lp=None, j=None, part=None): # First Hadamard gate applied to the ancillary qubit. @@ -467,7 +467,7 @@ def cost_loc(weights): dev_x = qml.device("default.qubit", wires=n_qubits, shots=n_shots) -@qml.qnode(dev_x) +@qml.qnode(dev_x, interface="autograd") def prepare_and_sample(weights): # Variational circuit generating a guess for the solution vector |x> diff --git a/demonstrations/tutorial_vqt.py b/demonstrations/tutorial_vqt.py index c6138d962e..d5543fa344 100644 --- a/demonstrations/tutorial_vqt.py +++ b/demonstrations/tutorial_vqt.py @@ -274,7 +274,7 @@ def quantum_circuit(rotation_params, coupling_params, sample=None): # Constructs the QNode -qnode = qml.QNode(quantum_circuit, dev) +qnode = qml.QNode(quantum_circuit, dev, interface="autograd") ###################################################################### From 7d45ecb09b14741358162a8848c5219aebb36516 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 23 Feb 2023 11:54:15 +0100 Subject: [PATCH 088/122] add demo illustration --- .../pulse_illustration.png | Bin 0 -> 420600 bytes .../pulse_programming101/thumb_temporary.png | Bin 9781 -> 0 bytes .../tutorial_pulse_programming101.py | 2 +- demos_quantum-computing.rst | 2 +- 4 files changed, 2 insertions(+), 2 deletions(-) create mode 100644 demonstrations/pulse_programming101/pulse_illustration.png delete mode 100644 demonstrations/pulse_programming101/thumb_temporary.png diff --git a/demonstrations/pulse_programming101/pulse_illustration.png b/demonstrations/pulse_programming101/pulse_illustration.png new file mode 100644 index 0000000000000000000000000000000000000000..568d8feab2e033a9aca66f9173dc98850ef96558 GIT binary patch literal 420600 zcmeEucRba7_`aSz4GE=?ove_ZJyNm~vbXG!y~jb1LJ~rkMQ zLgwFh+NU~DIBN`>%2DZj-5e>^HtXF5cel9Xqb#_soNu6RH9piw^;~C{r4w8h9KB$* zV$zdFO!&7A!#+P`WcqC6L%m7S;octgjxpff-omN?fAjh_ zA~D1mSG-|)Y(Y z!K)KT-@jovQ}_Fyw-90*|NegBtk3Z~tYC{>`TghaKL7XfSpT;<5DxzrIj{-;msS{H z`2Plloxumhm>?RbMx3;&H(mQ5m zW)>D~weX%QP5uS9D{p1#+p}KD5@7fB_1Tm!emlojP7ql0yvCp`*jGtH@;7cy6c*y@ zSQwa@F@~dPF9vX#HaX5+xBYdDy|;=A;H?OEcX#vh^3s*-gy?_J9pkmmO+mr!Z)7$d zI;7+z>dcq6wzile>P|<<5MYnmmnfzS_5X0)*;xE9F-n%+)YMc`QW78WPaNJcfVT+O z7%Zkl>RRNxGeipVis-tet7ckRTEfq%>*-|+dAdKAOceDN2}gZ3$T``6F6~bVag;95 zq@bYiTpE!c=p0#DDe(1GZMq&=zrM8jgwCWXLAXpX#Jr04%k@9iMW?N7XxUzCD ze03F(^bsxN=jX>6{h}DRLgIMyOMia46S=0Gt~@uo{Bvpw0-)0RQe;y1pB<@H$?W|3 z^XKgBY-uJEU&mrjSEQ=Eyd3Q&`-^i0@3a!uI`}g zikY6v`Sa&}^+^J2dezU8^ZwZo4d2`P_V&50Q<@^8oSbcI{;Et7RXVy&^ISd-dpnz! zJc0rOy=(46e8+|IFzRq> zG8IrGAwT=)_TH$otPOpBQhLvdsNtm>gt-BY{n6_MZ1 z(fUX-W>h88- zVO32Ku`3r%5Y9p)NZkxEevQsjhPT}??Djte{MLrocyeHjNeIjPE1wfK#! zy1Kf@vanr6tnANbco^mNz-CBfa!sy$|1QNl%^y`+S^4PPIT!nq&;R`=%xhy~vp;lN zl!THJulnP1%4hv671)Pwh-Ia~LZs(DnIe(77!c4`WbHIJ86h+JL}s+dd+jcbKmKTk zMZsu9M5lIE&8}&4LZeAuj{3~YX5Xd@$6!`{7)O+rv*9R%Uc87Sqk>Cxp}l@|sdIC)HiW9EczXOQ7_{b*o&JF-@_(u6a#xbWjgba8`MGXH)^kDMC|6$0}bS zTB_V@*~BB!_4})aEGgQhtu{p=O3_d4aC+84?j2hMk1vjau zhv=@F=7V(Q%2+9KPP*lW|H=j+>7!y}Gle{R4}S3UpC2S>RKlD%#PPb|pqV@|n@+D9 zZ=^7V31>$I!pqG~L)(u~{1}(kkP3{lJWY{MG0IB%VIw@KwrmZD+g2PsnsI#|-bfU+ zO)t>2x*2&+O>Mn%1hzK$Pxx;u{SM{i^Zw@TZC~rvvOb`z&}L4Yp&P@Zd&AUcEDAJB zw5=-^8#aFY7!Y*9Q;I6aW$-=To|)=|>(SAU?)352+YXNkdiQSvT4Ru{GJgf37UfSy zHfrx?Xqc?c%1iaq5zxGQXu(s(^<%Lti5~>7KSCh?_VHRY3ruC;C|q~P8s&saQT-{Z z2CVqJJg*}o$qJ&)4SP-p*3*WgWa+Q5-bwRZet+&LXdj2`H@|}WQ}?O-;}Br>`=T3R1OC<*bnW z@r|q%n##~aidH&h#?sBk#Kc&5E<+_L{TVU#BpPq%lU+1q_rZPmALrdCN=<20f8!_= zyHbtL6DzB$LE^~+h<>kOPAIk66>Gf{6J{iS6j{N#w8!|T2D@09I-D+I^LZ1!FgNg4i1Hu;%!acS??)dEfA&W2qqQ*Yvv8e{8$ z($z2L*!n9y%i2ddZ@+#)0bA}qefkuhZjYBx zV7)B;MI_p3v@XI?V4x&pg5o$F70{4NV`C=CoviZOq*tz(cRVw;_Nt8d(9l^@f=E(u zF)tUxNxK89)~#}L(6fuyDzdII$Wcu1X#K*s`sY4^4RSVs5^!tI+RK=9cZ?V%r;KSt z+n4MNh`)UxLx096Jw3gesL1=tlP6_%(Th1bs%xUI3qv);dJRULofZY{1$LUA!}V-c zLQ|wi=RV{Lv>-V-8FnqbOn{I5qbj2#KOG^qSc>ANHO&JT=e8_h0I~wRonHWCy>lxE zX=wjSeY%yCa{i~!wg`@9L;=e{xL6iR&988Fdlcl`~ z`#0-r$255ycl#NCFtyceWp=H=p8tg=(%H_vv<4*;)bOsIYtpeyMj#6Q>}u$HKq<58 zqRLfdv&gn(vqS#tq`Lygq_e8dh!cvG7(sbuen+E0%*6C`S#14%N^WA{vDVoi$o*e6 z)J#s&Uyp|S8rWYH4Qp@rpe*Rqq>qp>zj4Rm_?2!EV2dRwM8(Bf=9jXIdXFeQPbezS z&4sUQE%+I@BRxGme;JDb7s3Gg`*z=Izs(Jnn~(r;=ja{ z3GhbR2-Pwj)ac6BW9Gt_9S_)v!*?A1h~to^mZH7*=+Psm$Wy0Jb>a99xA>$4*q4-h z?eA6l<1^bbn&q=yzgDaY+e@QjO+GXST$|*hHIr(g5+fG5bdEp<{Bhe0p_#-CsXS ziWX0uF|Cz1r1U5~u=r#;EpA50+|-PhPD?TBomjXYO?^fYHPYw%1;BFI3ScQbJluqR zQRVmuTH0f9bx5hm$~?y9BB%Ll>PDA*zr}m_P!~hd>~yT|X372lUo$0*B=iZ#HUEvv z%`2ss0>lSdFP%Dlx=g#xT!l4~O-`OSIx-*qsv*xXyQx{!Yo~a#FexeNb`m=%CiF7D z@eAD}qVq;_mfulYCRGQD4d9`yfahb3Lb-PBnu|lp$cp2#6{L7Tje$N1<hz=(z;T#jmE=aBUjsj1S0N`+%q3t5*CA1}P{gzw)! z?@fF;uqIO1J$)`L>E7%rpb^UK-Nx6ivsy*HOK)USmUfxd*2t@0{btL(OA2yC6u)h! z34T9Tr$#tRdQ^lNx4VORx=u4GIXR+C;fDim`_z;L3sI(O=Bzs_!?WXX6lMrV3Aru3 zn^WW_z3G^)lhxEXdd^oO6Y>zaGhBoIg`9ro4h~#Ife|t(Ya%hj%@cG-hw6SWJn5bo z!H3ah*qwn76Pka4fR#{G%j4wG_2Yf&Drq|Lv5&&Su27K)emRPJ8)6*5j#fVqlj z^-47^|Iu5Yu17YSsHv%uA)DT{Ll{^gw2`VF<_2$38%bRQ>e?Tanfyi5&H>>@3}*>J zSOMaJvdQ}V`EyxG+y_}U!rx?li2Gdi!fDYBvEkuliK(=8B*eat_}@7{KnOyR@jO4K@S^8$NX5jR&xoqqjR_I zorw;MmZcTAFvQ6FOdFU&0ix0xLv-L6T!p->^ncF93jz+6B@*4zPr8JI?wJpNwUhxD7o{;{9CSEnF$0+>NzVp2?+^OC%PWjl?fnj z%>E#XCF0G4`+@k~jC_<2syF)vi(_8GngFjz0%p%*WKuFZEqJGs{xmH3dVnJL_G%_~ zW~CT8H#RhIYt|9tc$gT2QwCuR88{wEde^pe3;?Qs2a((figOI96+hS0ZVo3NenK`~ zIiqZ}#p|dVDoEz2%cdyisI$a2ZcVXck(;I~TR1rtv|2=B@J9B&oJ4Y~L}r;rv?g+G zrwt+ks#YXDJ*B9Z_WGdp-i-t`*2q}-kkZ)t^LTj9$OJrdk;mp%R#wi=g|VwG&ghM$ zdbW_#!z#k3yEoIkH#5ICH=nROPPOxyYNuLsr#f*5l}N5Hjde>0B&--gKWeloD8vPs zpaZVo1GOj}h%UCaNq`RmY;YBRRs(S(i%64?rSdog`No36RMku!DcTri*QW(eUxI3C z=m}E?-KTFLjpbO64q`*Ju&_|qbG5T-f4geGcNM)|f!_X!?>%wuE0*nt!vaH37R+9e z1BRZxz`(bY01|_nY2FsY|7|Z})J9?~^%>xk-9$vC8uDqtjll)DzgIV3zAOjy-{5Y3 zQ0u*eatnO)V?hDbU|o=j-mK5?N!w!FCsG z==)`$l5t@@H*fOux2L9Z@wSHXn(>AeHbHHH@9gX zxNYUnS^Uvd8FRq8yWgcXdCXUgbNxgec@&=})sU+29@gTiD31cq(1;U{=YUW_xp#2L zYxOgX3hM!?saI*A@?c`*5l!fK5SC2Qpd3kpk-2uv-eu`nW3{R;m~s8?c5Y>*?%w*W zw8Yz1s2#&x-`;Dp>P3M{a&I^(O#y$433Id62sK@lN#4K*|C2}cedsG}RgHIh(ilgh z+s%Kl;+-uNIcxQhs%0;wxMMDM){9PMIyh|JPHN3qSdqSZbYIe|EadG**wvM=GG)#Z zK_dOCb^6~*wov&WEQHFDeuYYK#P~JZt~(!+p($1nQ(#0bP9oZk;iQ2V4tt}|PekwS z?HT0oflED_@q_IsmF2<|)APxKHMF!I4d*~na}^S~$$tg=^MQcg+Z0A`brp$h&*ahj z#|e8Bs6Pyo59F8I{RKTJ>!x=5R9A%lJIH}2zrUmQDDgI#wwz003`h9j~S)u}9N zYilrb{Pceey!~-HIr0Fx_#_f;hFrgd1ER<3!Lyr)-?IQh{G>r%3>d3)W;10O@Ha9w zEwM@@Tn;=jF#_%Q*m`1|MtpwnJ;Z@McN$5Ibp{d|gMY$B=YiCfyDfv2L@XnKgwXaC ze+zAa0hMKB!unDK^Yr>Wucqf{gj#NoCDb~nqpTu7r%ytJ;|rEFPeMtb&{%(ogC1E{ zhc>K9!REuQLq%TZjai@(`{yhO6ic31&^=0=SPS0o6w^C9JBfHhLV}=1KC35hsJR!( zLn#ccArE8YD&&S-g(kAAymd&+ref4#Xz@rEe0l&bH24x$GgP2;pbEj2NCsx}dO{UN zkchV(!g2=aSM%Pou81hFXw~=wVpi=l)e8;LT&FX!vD|xjD;I-y2WeOxuo?+JHOEXX zf{-393;23KSmrC%2SHcy-g|rb_ZoxPajV%83qxXBa%8~cLGoLRj4h-UTzqxb2iTY% zuz)3JBQAhdO|HBL- zxJsERy2h>l$P{Q%0X>gfZOOAef(pMwc{xa;IVfa)EyUb2SCLs0w+>rO0W4yRyL-S4{CDyRf+UnsBgz#4&u1*S?d;XKNh@OO3)Ypot}mk)5_i14 z*Ih(+Vyn#af6nye)flugd@{Uy6vnJQu%9M*pukP)zzPeHmyN?La$^H1JX!sAMyXgd z^cGz9CKIRTY(zc|MT633#|2t>wf^K|B}?#0oSmJ)N7FeC(x9QC0Z2NwNF`MJ3T}?p z_q@6Xm4L$arEv(DR&Z7Bj>TfMp$DsWu>#{I&_9hwjJ?Iq_x4rX>gw`E@F@aohsVFw zmMs^K{Ytq9_NK7+u4#~9?T74az4%151Fq7W0$eQa*C?aho*8}40uafEPESwCo7sS6 zAOq5BhHBOw$Yvbp<*LoTCnZ0d%?~M@AP3dH-?rgngBhCTlz|XX2GbL22LZ zv4;+X;QV~6t*s&qDe}y1OTZ(*95yToF)A}aR)yL7jTo>y1O+`dP%k{5%gcfz=rBAS z@72QL;$+Q=E^b5}2v(Q81j4Dw_OwLrJvRbuD({^|y^5`=ZP9(Vdz?)=A4c(Flv~hW#!~uN?Zn7nIh|nNg1Ak zHvlps&5Qc<+GJXy*Gj9TUd7Vh_Wb^6W;Rb<9mYOWXK_yEj5+G3zc~-hY!W|cn0k14 zRINj}$=<(Dk?ErBk6SmRsjH!(t6^?D4h{4#>?`LDvD{^NVjGP(Z+O{1lSl@1uZ&3r zEdzdH_dHq@0X-vH5spP-E-vt;{Y7V^FcjiqfW!?q;2M3tx7l{cdw;?9Y_4W|?-m5^ zFNExGR99`rN)%}yK)GWf%i3=$^BKrA^mhGzLOT=Bb~`8Dz2)^AV2_|%r*;s5NMp|E z2CxMxn@&Ftf3MDxs+dkBDm26687&QUMdYAIoVBgBjRm|)i7L`KucV_xQJ z7w33$VzWu!U_6$sCe&7F?skcaLV9N1V3~>5z7T2tpt!WOIKRWpN#9EZOt!p)@VRPy z(Vc;LFEy7*5AVJ4`Td=7r%33T%cO*<`bbJ0g@-5OB^)>fC#ThiMe}kRF%WHIY>B;O zug1CK262lvmlE0Tz98$H@lhG%y2PaE%NTUqx&$U z$6$6@Nr~IXzH6aU2m_i3+29v1@{2wOPbnzCMgZkDw9BbsE7L2sg>1sZ$ER9K!m_1x zep0w?A>N(!5G=3FzR}Ubuf_)n0`3I9cgF>bu&zVXFMRdEEZ@dTyS(VuMDm!2b=Brr z1)_3J(c62!tLrtMkK|E@?XdueP@dTH)eER_hSP%3D@YAP0eO|)akd}#;Vc8g2zt8` zdH9tXkn7IQJnb9P-?40Q!622TUxt~0E*tQuJfJ(b7A%mV%mnxho<#(@q>_Rm3 zNj_e`$B^&a(CsL|c+kQr0X<;wC_2v+f>R?r3X5+H?mkK3yAkI$POr1T6UEHVu6eYc zu5K30gM3f^MMwzQ+Z#JJnSao;Fk5i}meUU%yn4ELysE9vY_IJ;^jyj8?mBvZa2G^zONjVuh+OP#RuPoqTjp*a$=)z|+GTNVn{7ErTNLY`YI%gv%T#-?*k z@%{0FPLapPge81@9O@4jzUJeFkyi4rxCgoUN zZu?79oUYoaVbetKL}piRwI}Z7&$adBnSxCWb0EFS#2!b=VZuqDWX?tWHUTy)%fjB? z!hT6SMBQSfuXSRXxEA^@JR3XDYFn&v$I^n zIW5%#dF#!=<&b|p9Gvu``g;F>dh-1)P7nqu0Ra+0(?>E~yDfe32;7kX?EX|<^UeD^ z2W2NlmcE+ZQrhiXWGklQ7r@xG zw$1_y&m6nGy$zFCTtQXIxLBw2`b1MfwG{35b3y%s!I`wQ5bu_?mv+&HH&MUEXK!N& zcUotAn!M=#&hqZy>S8UG_xv_`f1w(GItz@42pPJ`an_@Gq=~CNmOLOLZET8)tGa18 z%Sb&>ZjZIKDG$5IQDnSZ?REk*2D;krg@rf&ayi0zcJ1x-Qg%~yUr;^wWKG*wj%ZWx z;8|%e2K_43A)#}d@`OP+D#XI)&vTypyX#f!yP!QPY=7QPQs6Vw$v^TT-!MQ4!c;Up zmsJySlWt7QxIap(hG-%4NioO9QdTcnL2$%DEWztg;5jwTDS zE&N@uSJ&!fged1tgwxvA*4D1>*DiHOH+ugwzaRr)cp+=n@o-%& z2&L0d%WJOUyFondFLkPkZjOYPW*%z2iK|p%*N#9sO$MrvN#6FB^9H2&AvKK8oWgc1 z&apFhhx8gYG<2EopY#%Til`qY3k-A`ztdSj7Kt+AjAy}lJPczTBIjx`9l#r=;0!?F zO1tUwAhUC9Y#hTmcOJm-5A2gmt~kc1em^EfYY#?{=MC@Ruj8N)@<+|18h3XqJZ$zh zYMmkvjitV&O9@BDk}av_5znj~{4XdZNJmS3p=%@)CLr|Wjh{Kv*9S6P-wsk^enNUsoI{8i1LPiXIsNZ*5KsaWW^d|_yo7?Qq zn2Ppw|D=dVC_}@Ud+*gnh&s<{RfdGVSTDfvd=AM~V2S0flZpd$_l*UPoXa6`CZfOt zQv%vbo&zKS;wEjA%A7q(U*t+94A0Gt*keSco;>pbC=+L874G$p9Zja48WLwF3Iv~! zmpl*Me9~ho9?_81wVi+C!1Dtt=j64wI9!VqeS2p)FOcqm=B8+qqPmz^THBPNf=d>)4zJ$l3(+X#NiNrZ;b#ejE^=qve=boUXwq3^fb zroF8!$(Iwgz{ATaj$*r{Sw)A*O3XM?@a2DR3CzgNEnHqKFNXPbG{JW_k{^w;qpc)>y?BD*W?AtGDvXKTmi`cVTVN-mRnd!u?rF?~mF+t5Y^Cf1S^ z7{O4dn8Cgf?FqBL#8VaWn3;yYq1l?n6)1Wz&f2mdVlw;?>V*oY46!a{If{jFqp^&dKp722M7oK;{32ex1&k5uJvxGgW-(% ziEA4%5KwX>oiW@IFmQ_T!TJ(^3?J!$;N&k={0sZUqHruXZ_?4^v4OqLme$^^XEV%O zRhGVLgPJELCB>;`KdeWUa~dpAhMl>uD0QFRrErl#?mvGak!&+qdK2bU5D)_%paHwC zWt1_X8%ObW_>l)b(_l}}0cl||oY7=)xHm3n4fwu_k7epTV z37KJW*m)R7~89+F>h}50Zz29zx!`;_|G;kKh(;XEDndck9&ik7t7}0bQrz}KeD@AJ)G+A< z{c|10mG7cvk)DT;dzV3O4=A5*xnufV+ab{sSZql+YEas)97P=Em{pJUx#)D1^!#1C z8L)ets?K>GjE4{Iy7!v78PjR&SglCRJ_2Hmp)%33{(=8YT!!AUVEZd)aHYX{feSJl zMrxed_WW~l=&Sw(%?It7G!f&nYza>2f(UO<7FYvM!YJ}8+b1WDjUk7j9|zN^yuG#_ z#-knkN|XUG1~n5|wPQTqv_CC7HsFHx+}mntX@Rmcp3wK?_jxNODV(XcwX&N1#BkUp z=;-K>mbWKA9i&UM_hGT@J>fgmOyrn7(z|_tmj3Zc4<4CxL192S5^@p}n2ZH~O^RES zchC;JBIx~yjyQ(smx4>0B*Cetbma6=*LTnGGPmy}F1@U22Y0f`25_$_zN(~TQ*D2= zszayLYqu2Jf$WGHlK+Q9B0+3zT(}2KtC3)A0c#*Q(4uJ83xUv@Uo~0WH=XxN?k%22 zEaG40*cbW|5bl(@$dgskCs;aeIb<35<4#);#q~*R2YD9rL|U?YH28D$94%Yj^xcow zvmz1_PuSRNX+Dh?UQbYxcI{gcqvLn!OCUfE(c1=p>p}Z84{*gL5R$oEv9L6Jh<(Zk zx9W7b{n?l+68k0+ZQHAF{F`1#P@UU7hh9gB{QGpcm}-4>wpg`va-ucatIE4MLD&t6 zgY~ARvAOviisUMJ-p7w`zQp5jMKo|*<)}Nq(3tt*C$8|yFiQQka8GLzZAqBjwP-8X z1kv`+l$~}}H&qFdIm0~7=GAp(gHnU6^$lyf82d zXXxdvJ73}WXF468bMo8V+#DR#twJZ-ox4&8)~977rF^K)2$ITEBymFhZBuZtNeJAm zGWfyGj!t&%?J{^-nVHkGvo)ZY7>%cjf|4-fPGG~|Ai9?o#*EWWCOk0UJ6Is6&;IPY z&b4S|J3s!xHX4B+5At!N-vuhaRl5~7vK@M+l5R|%Ga7mXsW>jQoyvaH&ytd^A_(ix z{=Jz?kL>N+rdLn>^IwCtT-dut3#&EPr5x9jS`;?s7j*8CojDaamf`*Y?p2gPq1bO6 zW;b-_|2uhlN&6DkV^&Lg!*2&y?v<$bEnP-0qEnYUD8%*Mlizq`@r`(k$;T{h% z;>>#bvZ?MPi$}xk>&*xqT>nKKj%=W-{rzz`F5FNTD|peD22|A4czJkIZ=b)5f86MY zr=$>9C@I(6E3U|E}ohCP})>+>Fo z6t?^IHGq&|ZKfxD{tFgX2RHx0#lu6tlPw@@C>6%t?g(?x>`KxF!PG*{R5s>4cBl0I zGcg{Kyku3UcNnB&&hm`g5}`2>Ki&4;53mvzT=!WM-EujIQe&sN=`x#gyVWU`Rvpou zpZFZ-xjc@?1tCmF643MO?iJBGE^_UTd9@Jb%Z?ZLpZ#*%n>MgAWDGZ-Xro)5ZWWKy z@9pcmth)qtKE$J95ay(Wi2ucU=>g-|*kUh&f-tG|GYVp8ana6c&NI*SMIDOdfuiB* zBBl=?UM$(&+q9<5yI%@pFV{jF_qTlpSRL*}>|dpOWMN_9>8TUHUCPhp&@g&&Kt)SS zkcY=_&`aabh&ME%OvlE@!J37Os~9VuRywV^b!O45?4fGzFWh1KGNq!v4_ywsyHnlC zN%`~~(EV9mTcZ>~@HO8(fyGFNttalSkakBlqcMTQEk5-X2c2OQ4jnV$K`75gZM>6B zO-P`;KgN_`X@hSg{ptG;M8l|!B4bs|?V{XV`{}M5H|K#E5s;G*3^=V!v_8uQ@KcWbpUHHPG zS@871?Qtu^S3fvDwYCq;I`S!JN?uJEKl%Ahn64SEbi&k3N42OJVB@L#?ZiHxZzEDK zzm4U!p%0gin0GXCT*>cdF3rr!vbMC89k73nbEJa~Zt%);aT>7sV6swf-S4%ZpGnB+ z8%BY=qOwf-A>8&e1c$(_WT~p zuF^R2ms8n=lLmYrGQG_i$wdIMjkKxnx0{xgttug2Yg`GVWy5~5wK;yN2yD0X^y~NM zw*Dl!jzJ-_O1(_b7qcb>v|yQr@h=dG`-o7*OF<$^C#3sg~e zS66-pL$+(eeyMsNNu3dCsiX9+`-;S-&^dV8#(T%E3LRnxVIebtlQ-+_bdyt>5}bN? z@})<+*vilum{Xsiz`M06(=K^N^1110r5|gu%XatP=A!Ce+1CoL-e6-xS9)rNmsRp} zEl)klzH#G5%AEVoVy*9@!^;zY1LLch#Kd_Zkh8P*UFJ?ohc$w=HQUvP)5vq`Nz&W5 zZ*y}q%FDHqD+l@HMROQwK_kT#^%#-(n=Q=6!LfoZDuiX zDTY&xPCA@Yy$~B8e>o`Q{k5Zv@lEBta_7+BKREt}rZ7RQo6UO^pB9fEweK597#pjo zsEpphpH+0-0jvf;^7U(?Wz7hSo&RpBxwuR@H+KKyB(=F@q@xp$o`(rBwIn7ig~S$o zzYPRE6b&DeXxitT(TvYIV;jM1H^?E8&V4oB`@Q)g>GK+H^N>hYalaOHaf&kFs6!b8 zJ^d^6SN)>I*-4b1^h*nOcg^ao=YfHN*_C@+n4-?g9f2bGJ813w{QV)rPt|)JL~Jdf zdvb>MbvCx_4<9lzGMHexe`pN;C)7M%&a^7sD8e_sJh{XB{_H`{H2gEAnkJtJ<-slM z43@nO*GBH<6M|<~arklWguRPS?Fqma~GqFPg|umJzC|rz++; zB4z1q2Fuf}&QsyyRqi$kzAbA}rsw(_$)80fCc;pTZua`OAhOB9F8w0Gc)57CLKS6Y zWi>Tso2%DS_;NYfe$2i-r>v>Np+^8@r@gaAyCiow6x{Y=^t>oy!*(z5pT`uIh5ubG zqi+(F7J!WGo=f=~uNH1AT4^8Zr&;XSV(NPf8s)2ZHlyn4wg&G; z%MxD;y?7<-9d`4w?RkZA&f=OzfX_mT#u=J%$(J%>HeN=dXo zUP;kHLCMeZaqStstrSiEH}VfT0I~w??|ONcGW*g>_kQTIDJqzB)BpC69jGxZ&ZO(M zM8}seJ1_u~)sz~L-R3wY5k|YOB8KzstMq-O3=keb-gQik4Z~V7f5c?mo*?YONhbf= zy|B@lEq&j`%gYOa5PIU#dNqj-SBxMiC7|@wV<@o zlsG&k1$vem$jprwvP#j=Q>5avy)|HuL-tp~E4&5D0Ua7B>2G`?Dh{$U6LDE()xr$KTCktqdeK5VmPf@X6Yk~4iflk#Khmi&B_bx)b1s3KP;_w4>xvdthHWan&n9xC=t) z@nz{%^B<|@uJ zllV}Rl98SDArSZ)Wv*#6z-FZBqCnr?l5&r!JK0pRIwLo+^69e|jOj*gJZ7GeHl;CT zv}f>evFS8*!8nY#y~n3^{2VfnX+;hmp02(=vH)>TEl&nae%J|+$7pX?Cg5N& z#f$0p5Ib#LDbxP8&l}jaJ>A`FP3%wzakT2OZhh`~@#Rc)m{iy$1788z>hIw=G8dmw zzvEkK;Ceehb@KB=6Ng;BV8Ncj;Abyh5znlh{TF?wWtTA+_2liiJiDjV<;*||dI+{4A=UXr_XL48hczaeTWTT8U zR2>D0B=fqvdZ!%uI3JNbP4wkq|I++g6!B>`?fpdrnk%-^3W8 z+zN^S)cqi$Kr;n;7*%yj09l)w$vp7dkSDWq()N||^rhrh*Q~1jsJMn&Mz=o&cQ=QIUF`yeG9r`sB_l9xm%colh1TbRGfa#W4AGw@30XDC2 zqg{V6Z#sPL0us5qJMW!X`Y5laUNv@B7kgy9ui}#4dZZ8lZ<2x(chP6bH2v` z<8ICdKA0!!-@2JZHf+^PoXUF*??1dK^eAs~e_LH7s&PyyJ{~molK*{K*?bqrxaoPd zw2ZbKcy_iFn5Dgu!o|lwcOlx>*Y}0I zfw>t04JSVfi#Nm(m77s^mkLY~_g4sNz0rsszHy^foyBPzSo>y%5ywxr%I0yxSqUtK zTRbP3FWsF*S0!#Bglc5l6;XFz8_PR8%1Y5L^R#k%7M78nAda}3+&bK59u@fWV_nsS z;9-#$5?B0swie%QI$VpD_Pv6@=9^gq{+<2r?M3oCA$^`1c}l+SGX5gttY;-8B;`FS z-j>0T1|F5j2aB7&f1dcq!eX=p76&XI8V^7?t|Y#Dtohw?_4_ps7`V3~hsLG7wYA(d z6Q?6a|B{{EaZX#c{Ek(ho3^(%zu#Q7U)JUOmt>Y0zt(OzVLrMl@5@^Q}BC(CB zx25men46nBJF8AJjUd?hHr52^pUvG?x);`bArb`;OKUewRZ4P+U;#5THyWGvF9ybNeamZ`@;*o$4wi zM}Q3o{;@)a$*T4rCj7duS5mXHTD%$eOv%KRLO%4a?%e*eS9zLnDz)Ai*3rpL3#sgnQ?qwtRz-DrLC8Bb^ByY3Mc#!sX4mM2agU*O zk*w;e@F8VqFzzgvy1-Q*J^kp><}^|A(?YQ;>8HoN_u56l460J4486+!==wQ^zP<>d zj_-9w!()xH(6^jsx)f^8Q$&SKs zZw(ENyLXM9oSeW0=$ZvCd+N#0!3vLi_X4jZYWKa7wR;B=XG8POlZmYro6EQ-ed3e` zHBTiAC<9PIBb_4r1ibr`;o@#BO(T<+`Xq4{>aTbAzkMq$D|0H7$ZCEgtI2ZyJP4#v ziN!cJN_ zDP5qi^o%pw-QE4AT>~XZz7MK&C5ng6wr|*T6d0#rwW^{JH$tFBz?YhOt;GHp>|os( zHTrt-emmHuleT7MMy#E;C2*RTK}TOf4-8g>kmCBiut|t!dDIp0zf6ly^rJ{)sW73= zo&ba&4h(#vg7G%>o)=cI;>7RN@&1D-`I5_$Cm$qkx%dflbZSITGXG4tbd&|nilY#j? z>*W@ip`jrZz@8WC@cBrwja@T~3YQ}KdfQUo`O0PhKlSz9d@l_@b7VLuy4`Y-y5=l!GiFTtKEan!s3Yj{2HXN0$vJc`ZebrjiYa@H>&L>1w0n zIV>;`+`SKjY~JyzevfHUCLy)M&dJ+qP12r0(!MVEqaYlhnOTrUV+DOKw8!%ORvpaj z9gy4qy<8Qj_rUXtig<@F+`|ZQ)wK3>|E_-{BEYzbz!%PE&WlBt(s`|>U9^zXgO5KM z-Snl|_E?I}Vr@0&JS;_C!Y^eY)O@IgtX;GoF?Sg(ThyKvdxdi3xcJ%Tsv!(k6tB2D zo8vva=>Ex;yw)zR<&+=wnO#Sp3$P{_=`+L6bJ{Mv^#ZpwnDeOwJU7cnj^oSe+Q320 zhJIyg%uXSn1hu`hQw5p%{i~>J1)Mjcfu&syih+ZcptgB`Qqhb zJ2N)l27)#MKPM|oE)x!MbF;*VGkUR6#f&L0C+G9>xqnMdsOK?2HKP`DueG#h8Q~!* z$xWnW&n_JXB^p{Lm6=S&f+ogrIK-z;b+Dv=monaX_RG`q&QDuz(or|BKIix}{lXk> zZf+i)81r6(9HadkqZnUyJ0ZrDy=vxPj3WP1@l;34Z9JM_Ff zIr!kPQv$`y%+7AnIP#IX`E@7an7U_wi|~VH2}XnOz0mp&P+U9g)@9OO{T#En^mLSp zkni|rM8v4&bGMPu3JpIeBbFOCpu8)8@RoR8s=Ht0PTG9Jhp#%nsK^1+=1Dc*0xz0U zK<;uTMII+*(Kh@phVC*Uu#DbW#pX4dN9S^e9i;uuVtB%6?>+##n&AwMldYoMcSoGf zr}|42#KBy$)C3Aq3jL=pTv@%|Q1?(^Fc_ll?h|_7U&Ki*n=a_f12?(39XA&Ao$6Z! z|4K4yy{BNs*GF=dm9QJ6_YAk9&@1(Ibru%R@GSHALfk#f71$Gpu{sN#<+G+Pz(=`! z$jX8h3A-*(7nye92M-6UBh&i=3-s??7;+OKz+Kx!;DpqE4=L~EKtJyKx91s#&=3vW z4I5ElQRSAO5lNKa4Ak_DC4AMueV;VQBt~^Mblh$4StnC(T}oc^HF?iG*MyL722j#* zlmhywX_7CG{>K$Yiw+TA5WEQOHW6T&PM3S!dq!iTFGNqfA9M_w?xdXji)Mb$foE3_ z8g5k|Kfdg_a){i`cbAQgjXOJU_TX#EM0hHIuUS`@p?zZj7W2?;b8ufbl2 zv{#0oeEwX7c9V4MUY+j7C+B-(&0p$w{Io5!kl>lb#qC{UHr@BGIyyQqNUx<;Um4{?-T95$TW#tN9_SN5y|)!aiU*QKiy;F-8-QigGZ<|s{k|ZH3*(593WMuEXvq$#cijbYX2_ZW>J7lk9WrysQP1bwedYjOQa17FZ$C<@M45V`iHj$w_z5pB93a3Q5mSJMZlBxYQd#obxfNF+?Wg)V z0H_KG9j)|XtYjrx2Xvz^hv~yv@X@c%Jq2N!I7I|`ROpCZO$IrBV1@-T>Q(zKE)-|3 z-u**2xkpdsoX6M8hm`W>=MxodDUjhJZ=cTt1Rd{ozhld;m~ne=GAa@dAU4n+$xK)i z_T?izyeiY62}-*ioyZd9&)gMPP|(Hkhi%p2M55)5OI941u;BvnCyYv)@*X)%RrhmMTzLDSoh z9UWrXo{a#7&g7+KIUfHdGsmaV zS8b(ocq5QHi$>mch+?v@QKvnK%cR~y^m;7+goj3n{$C6AA^_2&>Jl*NWSb=;nRI^| z6I(o9uw&c#U3OCtqQpBgcI?3E{m&*YE>*^Ivrml-5qF@P!QF)RVuZN!?=(T*O8uX~ zbtqB6FIHT1$V`xi4=soun(F9y*xNr@$a;c{o~;@OL4BK(MngMeX&{)r@;ULqz4J++ zKShe1Dzq$nJB!oZS+Q-u*hRwKc(EETC*#Eti1y{#9$kK2ux@dv$7NB`XN>)w;g99z z2z9xlo~|miO)hxM2I1y%aFF|_`4;m@+MfOy)jwwq%zxRu=S0(vv!JVl+a z;gK*OfkBk5$0!tc*Qjkg9{bStFz6Iz?gZm>0%^PuQf&svPdNxfpn>z%ao~zgNXGDK zfk2;C+ocV081I``RCSX35!MG0d+?oQ_+Y<{AP}=mLFP z6a*>r-Cz$O2@|#J|GB2X1mY$Pjl7?UN4Ed6iN)Sd}xr7)dbM@Q1)k<8(VE>j{lvWvY0%&~!-v@YxM)!;c_HOd zfC*dgsM(gg0k9b!d+z4eAGbUua$RM7a--i{ko3Wyj+xBNcy6L>b!&oqXnto6E4#Z0 z0ECvHUL^e2Hi&9R*4JV15@kr2ZH!vabNKwFzaZq?w8*JA7>5FPDljhzE}`0Sg9r~V zE+IjDLa3jGWBK~Ge?4U26?b4|Wi_lAgOHl~+bNvP=SG;lO@^zpvok~~A)ySVhtY!h z;KWDQ^-@!anq%I^pOuh0eiHr5KTSy#fkd1HbV%kxVXWU02Li>ddKQ{y6Y=7%IgsGe z#oJqCJ7_1I7thgZub|a>sFb@{5IFsNNZ5P9*;i)f0*JzrKak z#=rf3x&?%wcNPg<{I{Vu$3XvJ;klF%;{j5K9PLnye~8$KBZ|a{d;dNsbOMd_4_9)O z>!F;2PfiYm8nt0kUBFmOOk`JR#QKy?)a;Hd`!$qMlJr#ffbh{MDgjBWgqxeZS|yft z%hu~}VDU~wjy4DtbNi%*k5B(L-xud2;X-qyq0+pQxHt=r_{93BvEIF%H;vQAEFHyp zi*GUsuTL8a>IY!;ZbO1R98hQvX;IhKPDxItuXAAXlIA_x864J@o;U?Q{Zy^1@`;Px z;tjR`OlXmis#tk>rv?T-kdf<|7~`T|g_33GUHI+ibZZkwi|Z2~c;uM?c&slp#<=tg zr?WV14Dthw@})yV)`Z9C=yncv@5m}=8@i%sh4Y30E#d0Tl~FHZ!Vd;qH~Sh_m`Kg! z_cR;P<_7Qe$nEF_ALefEL}Ulga&2PL8x9 z6+>z~zX=}fz_PM(QgZpopy#uyBlMCe&jj^~KCiyX)P3^wsd64QG!6ht3RU!WcLQ9K zqaG-A@#%!az~*d6`pgdO4o?|$qUIXEyqfPPc32xVV8JJLT@4L-t|uhqQ{LP*_Tz^L z#qG#GBwA}t`|MpxD#C7}UKu*W2waU~NfKNx-LgNIU%M$Qe(f^c&hC-QuDx^Tj!{+B zKwg%yTXnvqsd5;%9t0qX@c^p!Jebtnb?1X)Re!t{6PFZ`x%B$QZ!_szq)g4-W~>!u zML{>I6cSM5vTTYDZeDi^$I)EQjv^Cl(Y#U{XYI!bcX$2fqOOOf_@ZwH*_(*Mkg zk&t#4e@{07r(<%HL0rHaP!s)eIY3RIIfQW;uxJ15CzB^HC@VP_4_-dB>YCFn(11|S zNbp=Kb8!G)p2AM!L`v_B0v^0q|oG z)#FFo4gvVH`%(0eV&uod@1=`-Q(}e9{9!t(d-}qDUCT$T=d2w{Il?92PrV(C7aho zRF3E6V>`jOq0y?@cbTN1@Ip`k?C-LdfBuY%=I41EjXIHX*Ya%75;FQ>f!G4NR-y6= z{&}QA{KlsZlm&!%sMI1{ge8WJ2zTcMvS^)D9y&x@6j@j*>x>P-PP z8XB7Am6ax}S*`-jdW*~@s628s6jP5tho>O^As`@N#x+0*>dUiy%ai%^&<|IiO;+0a zEgT}!kOIBL9mrK%&-~2IlvY5dd2j;W7P}j#1t6fbnr(h}2d;1H=AcTn`%?40z$0gH zukctI%10FPH`+69UA+c`#Nd#S$$C%iY00{+s6wvY0eRg#^coPu;Y}qo83*Etz%A|_pT}+wD6F4(3v7ce0H@#gy=@urwdy;0> zgBRQayraHy(&nnRT0JF0H@9)!qSeQ*kpa*cAx3TcdISUaK3!*UiGhK5uY)5(8wFRq zNP79wbR5a9uLPzbbp7r}dnK$10YcepJxQEmmx_I6pfBs!+W6^5Ok+k?Vxp(ll(b7# z!SDBv4-MiC_{|Olm6@W86<-sKYWdq3h^&Pgs zd8(85rr5IvZKr>&&ybMVS-809BEk;?TUttca6$w_I0#xb3O?@)=4PW`6@cRNVd&~a z^?u((bvvmzi~_^fg;L%L$Vm$^OXg}^U-TO>t7Bk*+8|wmg1nVkxd6CM0HBD}P}|kj zr;v&EX-LCvbqrHfqut$mP}56RND?1CCY08Fz92GYf{%{Qt6@r(Rt@ASAMwH9=MOuJJC33OUYWLXY7HX?J~1@?)s7KRKTVe9rlHQ$`l~^+ ztg6}vj|X6;a|Tp6nY6t_j`pp^4k)6bW%nY%uB(UnO-qD1vF7&+TI-WHmY6EfVxdHTdB z25a>r+zo8BcDp;b4HNH936H^3L$KWnNNu43^Wp8UrSX6KeZ1P`@mW=VT2a}{F`#GnUR|q zfG-EFk$nCKH*qp7m_Df~howRQu-<N+&*ZI$j>bm;cl}Y{H;&SG-HhT&V+yF5)cq}S6+KP z+{ON#kH>$=X~_pngA z-s9(&*Jdlw1A+>h=y)3U+w zdh{85pTSUP%4xQAI6+Cw5SW&hb(<}`wMXkik86GKyqv} z|DILo9O}8w+^p>$%k&EqdnQ&{>*_YnI&^wk-77u8ZZ2LeTN##jgyYXf7?S2mN(h6s zbCECq1-Lo#|H$s_I^DQ&!zW5!TSH^@q%X9m{%F0cD`-m{ zj`zmFO5s_>)2ZVK0YABYc+d9#cHw8ICo$R{?AvNL2>$bW1>zdUnm#r?+Y>c9BUcw_ zp#3J2t18ON_p*bt*0jd?NI!H&>jmSG-DHFH8ElbQYZE{ zOG*=4nsd+FSQEr-G@^wm+=nJqmb8}726}~eWYkr(_<`9PK^^*kbRygCv_I@qpdj%7 z%~fc_DDxIVXvQQTE3n4sI&As>q zf}xJ{ZQ3P^JRuXSfQD1n3?@6=1d5A$##K0SpQKn+#hb-1@))N^#OKR1|NT zd-97PyqKV66H4LuQ@*1d2@Rg9QrdNxFO{eXIqpV1mnLij_x=bM9P{|tSeQW%WK&ka zkli6M?&BQZ^=A=7a!#<1nXR!M1L^5Rsa zF=#?*@xCZnJ^mOK6~&KNwG$|_2xRb0faExdRORJo?bzti(cPw2@^f>=SF}E4KEBvq zl7pwg*4A8SS~ZsmhNc+wlprcC<`R7dk{lU&!$%f!wlUZteaIq%L!*B@$cksn4ld1i zM5SZ2LWusrhr%Rj5Wq7TX4@b4S!i>C9{iYCFX+f6>Fs$Wei>FJ-Fb$& zc4hYvrU+V?0x?i4xsA+moUK=LhN$OcXIocmoN+N&9q$g;Q?Uw~2+I)~09GhozD<6i ziy@cHNkSJ5AE}6VCT3`0pt?fyibQ{&{t0Ui9Kk#Ao`a4l@ZUx8I7v}*e<{9$t<(7k`k26bYiq-;PmJ(c!?VC1i{)H-?3ZX0~*ta znNmFw70)T(``!ge!~cw@jMAIKH*$99fS~K2F_NkhltvY`LT#-5(iqcy{iOVJF%w;9 z3!bk|EL#(mbG|G^f3wJk#rj~8lRa*WeQ5C^^<9F23H_4~HvQ}=(r1@x0hIeo1e~$x z=|acAfZR7) zvtC^(26gnNzI?>uUicc-|2E?w@hvT{t=&ZcQ6-h}DP-+{V8AtegU(@Leto%S$~8MI zv07pDgo|VWFq@I&WOzaYGO6ZoL?tq6V%Ne{euj$G7(NRaz^;5#7gJg>?ab4|aLV^n zLV1`mX65D0n-GX*^Yh(#h;8S@3>Q|n4+A_dg$;a56eN8egGD7QJ1~L(+`$yyRoIVX zSKkmE!9XvxLUUROA{em7gZkT~(9zCLVLE?rZET-+(qnARX0AL|zz<^(fG&%A>)95F zpcWgsBo{OuGHJ&i^$MJEfM^=H0VzU8RW)j}`^Iof%hld(u3o*#+DVao>}5|kBy7@> z5jUL|@3X4aMfD!(^lip=HW%lil`RD;tT0))RDDxV{U|{**0F5A6aLO0$j$CNQ^3JV z)#)03gcCD1F*repdNqz#8M{1qq_2H%FELTL0`Odg$F$jrRIjKKy36&nOO5F=$B>2^ z8ynACa5rcXj{&3@Tekz#217%`$f-}+*-I%sDNt{93M;}B21_5Fb*Y7p-&1D)9wnrV zr7y29KeZSanXoW1{!GI9Me9L&pNiMBxU#Y*$=ZAm@dyExSiwrt^VKafu^7~rA8^^X{)*#z;VkCe;d6M7c_-L9SvP`A+CRp$%wCkYRK#l|Lf5P z&dI%>xg}aSK*=(H=dK^nKWoaKAgZIYoImL|uLLg~raM$Ge(8`rhjCnvN};2vv|j=E z1lWzhL&HV$;i+|aG;x3ZZw(@DplX9?YGK$&Y3~Zt!t1P27n26|;mN78ma~xEFdswg zrbs-rl)^+K2|}7zObiUz!$f{s=Kmopa}$B_CAsq<-N&GF{uWvUa%B5Jf4{t(Km+jg z7fEi>{m$|+7)jS%b1s&sGlZXFYx+djS)BK$C{}??w2s&xTa_vN9|~ylf&r0{eh-PJ z+yAnU!SC#p&YuTpi3-o47m%ziVpbA*xnn|e%GES9N;#9#stf+s#BTTA z(_WaqMUrMaFr5QaaxGcz2Ozn2F;>R0znk3L{1s}i(t=Aols!OOLCwDbk>?oX*y7yJ zDT8s|3ks(9K~CNpUbF;(A&4tos#Ue=nq zRDq2#Q{2Gv~t zfPxr6eoJ|)Ximx6s;a=%JAjeyDIW=bAhjw_4K7APx8dEKOPIeAGc!jG7wmUrBSWKV z<4wA(Ng%)rEOX?i3@WX8Q6ViM0qnf~ph~tTGA9q_ic|)aXaVq@C{h8cc{fY#p<&PV zG0^^(AD$0=@)}~3i|A+td1uihtdCJ2lefJZQ177V(67SvUz|=j12R&_bd4mUk4^ms zmj%>;rO9$QT9yPMz?O2urkMT9Mv$D)^6HPdfF4n?JDXCLIBuk0^?ndoh1L!e(ed#K zI9T~Nkk9FJphOVTWAtg&%ei4po_~(^LpLUrvKSs8>N{+r_F?Ne-hwuJNWu&oNVR<* zpn~mPz@5`VhkESz%=?d^=m!y?c!uYPWGTUE^cPrHm0>V$*2t)S_t{fI8RGMS_@U8z zqWEo)f_3-wU{IjJzH9{uvCFsxw?0(4p=V!}0@pt{Q2?|0D`U(=*y?R(vaKkY^nCkGVt)0m|IyPT8Z&gV|t+}vp1mwZHW?gyMJGhn{z^A@5A z*6Y}*fNp6WRVCa+Y?v=0(=Nk|R-*r$nXP^BV0O^)%DJ-iV`2h#$A8P{o<#nVLG=gHtThI$8^=kLzmS+(1k(lm-TYUz4 zNW0B=^N49wtXH?`+R{3G#}&)CcdeA@@{wo1+|H#DVS%q-yqjgyv4S;K3wN%YM=*{t zF@ETa-NuaVLZaYr&ilYnN7Jyq`W56|(0(2NjA=VyZ6iLXDbF3H*gM#Lw$k`Zfi0nz90ni=;Z?seiFNuu=TXQk96JA=0h#re;3vp?v?Oh-h{d-DQOswy zNhI9trMaS~sN5B~2e%}nU)*^6uJ#2k&}jniJw9FMJr!695CnEIgc0fhXwk}AMC8l^ zP`yYHg!9;}0}&Q{14;_8++{WC2?9z0sux2-H)}%vTUVLa@gS2rMxxlQ#>p=%oT{>? zEo|R4+hRm{wmMePyJlm;V<6fBoe%|w`_iA?m1`ITGPMNe7Xu{?1WNr9tV3v3d4X?1 zxBR^t*jT{bI6r_QqM#9Pb$5@usWzHfT)Z`0e@reUJCcG%qI|AbDX=m~Vu}L?GvK6W zD$&ANO7NPj3EQxMrBgD{mf!4=$;-Enu*MVZ|ax7KEk}g?z zt}-&Gb_t6?<)wkz`qn{3w&1_Cpm8@^ z`5)C~_Ly`E&)Tkw;$z|a7c)9a;qcLrx~2d6^3uA)`p$x-EU>r$;#7h8mqW%<-^o$? z`ToXC`v)1~pZTT$_1FHIxcpN4Xmsi9bc&Y<@36IEDwFc;u6MBgEku zeY%VZ-98D_VWw(7t*g%wU}>JOc+cN9{^oitAt|>1NXj;{T~Ia>C@INirc&}9d?~%d zpx|0Fe`yZC6rE@ubbT$RYqjPVeD1UJ-HB52J2NwE zQt{Y@-HFE0SRylo{}cT*sLi&=^iYQP|3V$Qh= zqQUpQMz3T2uTKv{>Y#n2$M;uZ1&BOTtA1jQGASi>9O6o$9$ignMMX2{2**xPnfr%N zbuay*;2=PoXS5yIQv*Zm?FIDizyL!8sg91~A)iR9kXe2pkzj{w`-%b~M%!cd{^Q!6 z@AG9ffB8&e7PMu8Xz#C`J6E)cR?UEiVJ{S3S(%x@8%EbY;2*hH_iocB9rNo*;#qi; zk6ZFWJ^iK&*TOa|anzWQH7uu~%w#M0$4V$ z!vN(iU9KUW?}0!>vRh3il8uN*G+tP*j2;Y@T=y+nh}9ddGQ#@$fIPbzI0D#Hgrww^ zVSb9iPWqU|%W@n`w=XcR5Yo3_%5__J`!s=~PVBF5)dOuIl;STLaEoarAH#~gn3#>! zz#s~?kRt~Cn?6l=c^naBOV-u(yThKfFNX{A$KbRldG2fa7=6Y>w=hpYeosr#3bmiI z^9awQgqO#S*vWJWAq18t{w=!MW41iBlE$0G_BWas5OU*p1Gi5tr!hprDUXM`F2&RT z+2;cm1swA@W^sYbt=3D1EX?JH;kVUxN%F2=5nO)cBCj^vg$;Iaf5B|&ecy-a>97L_ zeuolpBt}+Vep_F@ACi*PqJ|1e9ju{MF4U5o@PGwg=S=&Ms~5Ab4d@kL^YPg!x2&-M z5f$bj`pPkT(AGm&45-1Tk=!n@!GfE?QmW-T5~wamzi)jLxRpVX7}=#cDtI2^FcD1B?X(MQ32G+F=bb2elY$=?>$QWA!7w?i|xw zj@{D~Th!f}Lh=?^kki+6oT9C>uH~x$YO@!D5w$S@I>VqsETZF?m7&WSzO$bJIFI8o zI&Z?*kEO~=OIbKM6NV(W!a|+5z{1$n>qG{wfJZ1~Xu&?+IL)t5>~}2nj!jtGfe>yUCa(QI_`M>n4jc2lcU- zx}6Nz@RyOPAK9z<4=2t@D=pVd`dUf0V zF+}r{5g;^m`}rXM5;%`)?F8>~GnrtT1Gp1f6Fp2};LQcs;?<4#gC@5ODC1{3Tg}h_ zmuWr~XCS~BTXWc5k^SF_O(dk|)xSIioC$kIf*v!W?!OFu+bqj4xM=LOth!vEX-qP6C4k7y^x%n_~+>@(;|^M_sz1U%!*__~dlIK8B;Rb&Y3m zBu-Ta$#jOThZt3VTh5DL-^7^Y^jj(=rF?-{{|yJ%kd0v6<; zV!Hdm<--nC|8fDEXExbfy0A;T8AZno$!?>(#$aT3EU!K?UY}g>X%{mrsqE8jkRYeJ zjX=-yB@N%H!m{fALHqJ7%Gqia6_p=*_U^fW=xpXHL$%masFf5K*M6YIO32~#2{?$K z6I$Q?nW=MEi+Rs@v7}dn^6InotnXq$stR3+P|_uH%6{vdZLr;wbL~^6Sg;8Xy{*>9 zmed2v4t*sV#BBxR6ivI~*7`$97+K!VeG(=jGNIRE9*tCb*9bS-0LlqAj7q$TVip$M z;O9CLSVFS=M!5NbH0+=uVvaqbl&Hkw_@hFHbG-ikE24_$eaUomD;PQ`undJ+=zu2w zb}U5FT;;+{S2bCfB>@J$`71&?+DuDunR6RN^W0oqc`oeueE;JKzM2^r8>5X1H+gB^ zZT30~bF6*5KBdNGcNrYV^+QZH7Jsr8PM@?RRA5`F-8b-$m zKG9xgCWUvy3l@A(xg+?~d0mVZM<*gEohdR__>ZFVotZ*rGuc9PaFZ8QqfdCxPB-9n z8`~sX6RaG39)0NL8$`PFYM?hkOk##3S6IoAh>g^(d+e+wamZ0+U6BAoj!;2q4ZdhIJ zs0LxkX}9IDwuX760*&N4dJYCOXcodywRtOQ^%aYdg-=imgT@N}5to}(>wNRuVX+3_1 z`Q*tH*ZuXotR33dgR_va@&3wYeM2%j*yJiD6LpGt{jqgOBD;`(MaK!pCSOK+r@nQ& zi_leNi|cH&tqpwmS0LPKNGgH87oa>yDUe7sl1fxgyoX^+di;g7SpNS4Ey2;*NcGw8 z%=IISgKK7HL3SwDuiIqkrz(|;b{bl1Cd~2dO8Ctg>_1CYi)@`q@C_|=;X2qoI zXSGl^yEES7Xm)vNv?qM2c2}6}S@m2?8(;FxLL5!+@xAaPx-AjYN}LyFC&l^?el3KS z9Aq9O>YcE0{F&Zg87;ffv+vq-_!F0Hu4ebp&d!eE5#dYA-qm=ZMy0D+V;5VoeGLa; zB|jNf5+T0snUTBc^#}e@AKilbmv$tjjhv~2)$;p{zniKua&mSi!%sG@IrI~0pOS4t z$G6q6UO*p>A>iPb4up_=G-Nc`-N)TGXiwsEYhRwDx{8ZPde0L}SMW9xUp9w6QxTV} zAOC~E!K&iyuGr2wJC2fGbzVLtd4VUPVeR?^TIHqO)DeAG4M5=9;QGk<)&B$}e4;Q# zh4l-mnsS4K23)G|b8<{4s_az|o#?l{An$rC7q$Iy%x8u$aBo>QSWFI?qI@B6(K?fZM%@rm1mf+{&wdJl6Yt^Yl$jN)XWp!Nc7<6 zwmJ1@A4d{(wedb&MMioBi<}2d%IKsAym4;ajf53D3Ov5G`Fd3!r^UoFii=X8QDNIS z%{}3#!+|^V@EP6(Ru2_5D7V3Tp~57lXJn1K=d-HG%8+mel>HxRE6zRRl1fj@B5DgE zn}XeP-e8qs3Dfwz-VVovMeuW2v0>#xgJ85ymX1iJu$OE(f$8J0i%YbpSokkspp_oW zhqjjVzIf4b^BtMZoSVlyDq#Xo@X7ih#n@2R@v#XpXG(H6N%y1l&Xh|6Vct-1K+qip+a9)*#ZGA zc29_sVJ#)U&Fd25ffWxGV`k+w3wl)4Q0jOcj88WK>PQ>9;knsd>vFOsO-nU$Az+z@LK=d8oYdN~R37VffIP6CHCPSb=P8~v(Yk+I>z9xSfi-7hgy zd8iuKxI}DQKOoOEZKdL>jX&>U@s=$L^pl>;wfv8U_DUCkIFST67HQ4KU2J7C z(2liH$62vOT8n`uQT`=tr8F?1Vq#=063?d}Jmlm_vHYe>UFwETzKbZJl!b*&LOX%Q zgmA049sFE0yyom}c9}ikzDwKRfKY4>+~U`-u>+B*(C~xj^AzG|a4D7@uOV*NZzR~$ z*Kf*hM)MFSFngY{V^obLw7rbdfNAu77h)C?8Pzz_EI11HA!R6kbtg5;TE^CBJL z=8w+SEiK)DYGF22mo#PLT2_N~ ze=kWgKc8SSl9(rDBdvc4Vx!rEh-!FI@Pom86%og_wydM_y<#RA7q5n&n>{@WSB)aITpuAJwf*QTFSqlfZ#OlK6eAzx zr4UwprWX5$>9l+5xO)MX0iCW)-@L%y!R9V^V4{#`Rn{7@Pv?8n^uPjf(--YIvK3r@ z{(KglD5&ju2EJNFdwX8pw;pXfap}>=w9Zl?9J`&D9_qVO?O<}^#r_SsJcva-W9a?UWL~jf|eL3mG^~P-5d06zOdeN(3~Sb z8f^%o7e0$|k)4BmhJ64Z37b*H!bhUEmY}Kn!pbcvKjDO0Q#0$@c!rGDd0nC}D`1 z920(7Rdw#lR$E*4Yvfv3ryVK5f{*Bh=*R^aDk5$NHq#+;2ADqS72&RhYh}GO!svLz zpXz>9;MvLWwVwgmWo4W`jwueHr?=aZxdkRVkuMmWO7kC0Ac7K@wKV>=q8Ia`Qw(e_ zj>jL(0Q0MD4fK?Y_=YYFkw2->m5S$7Rk=jb%+dlY)9i;#*yd8@9rUY+B{%)*RM-Kw z7=9Y`Mk4|l+z4dv@J%iolenn=%vbjMG4jw z9gxDnXpgOPJi~x4B3Uiyd6H6RX+R!&B*WhOAI0g0wo=T2K%Ov$H=V~@XYhf$1ZE_) z3akm*I~dGWb}o1$eIb!y7lnjiWM#);XMi<^?TQzgm-b6@_ z%pSac$e#?}lfA z2E)v~EcekJ{2nGeek+wrSgiI~yJ|p}Wh*-L0V*j@AWXn3D=W?L+ht;T7HD#_byBKJ zgEF$=$xdi$(gphf<#7)Wy{&^!l%sE=b~(kPCoGIHCNRYX`t;C5sRhIhZBIVZb}M>a zmNCT;-+}#s5|1ch3XCwF;Kr_i8^D(4<^Nu0eO)N?E$dHM*S^n%g_%8H0DY){4^E`2 znp%89HI!Nh^<~`_+GW;WeJ|LCCX@S_5~Z@bEgVCF^qmPSH42884$O#3=)y!$E+I!# z&@cT_uq{bhPj81WU|pz{G9y%OG12jz*FT==%hsVurH03l>D*c1^)KE=$}fpXqD1Jm ztG=pp!vUydkpkW+`3ux$=`ykBRy2R57Dyy{I^Rn1;s4UsM+ z=!aRkB5!jiKTQ}cqk`>sg>nYlwP8iDW&#!EvpMRoU6=Dr1p@v|k0f{;;QqL~vUF4^ zFYp<5$;Z{5Drm=TV+b!hqEO)&XjfzE&Ub&>< zOEIz}yy{}#-#33Bo~k!hm}#4Ca`mXiYfoSuTVe)_lc#HwCup{vcx^Ggggjh4JatN zu1sfmweic;3j0l1;?3y8xqA>_e0h;-ZIjzBe|F@`CFIw9GFm+cx8~7&y#5sS?o_p{ zTfyPi2%Wn0Q@d8oz|?$gWy5InRVGwQ2AS607j-VoFgHkCCKW~W7+_NFgL>Z#*^Dg#a0 z($dm+hCV&|EoRM{qSOc8H=r0OwtQdAMAm+A|Eq2p1XOg3n=(Ho^7Cyf6Ac8kwTUg8 zVT3OQ54L(>Sy7$|jPMF~cfMiBVxjrm?7F1~2Te7O)MmCN*e&MW#bGLT94vu_(mK>3 zyV)4qUl32*dA217LFSTP&>#(?`XbGkytuCQgx0pEggHulWOdKIyBq!wm}`=WE|-ql zIvhFsJ?yl6MF-4l87dZTZg;oZ875m3(*!OmO^r z7w(s;m^mEfY&`hUKDULFE}O2jz(^nfZ$FTrD=}K>5;l)a5}NMdb!)1DmV-7-WT?>S z$Ss>cb#Z;!lsO@eRYn|F;4=C1RGCk=Uf`FiZ1Jq$L_%VUp7~7fMS|Yl?K^L{#~pn0 zCRDiDhr}Em*d(cZ?>4XwF8CtwF)ppGb)VM(C~&Vj59}=N+KBlUn<~wpei4N3nIZzJ zrqYo$Fiek%!KC|u1%wG;4#OS}*5P(77W|AY#&-Si-Xjd=QbgV_eTXCn8U;|=61(rn z?wJpG%Ih1v$Y;byhjf~~AGI+lpC6{V1XJ$xpplUq_! z!hG-Jl6YKq2TJnY7mm^ek&Nztpk)8&gVud~Tmzf5H8eCT$)ZH0ZldeE&DpOEnNQYa zSa~to+ByOYuP#@m*&^7`)YMd0*UQA)R{sOI3)h&BRcmcP7ziQY{sVJR11?>E64YQd z_k%gGW&&`0T9`M!ke;bs-v-)wY_y3=Td)HJrB%!sS3g9a(iGXr++m|Tk&xrUL|~9+ z_T$rQ_XPe_(B911Fq&J11c_wGncn9!0dE#~dwareXWo>{wrdR`bc==y7=g!)QC?m! zI{zs(bsGLbX{JzhmoJEggH4`)C^H8GZr+DUfB#1;8|WTRXC3QGwhlm!qpqd~eaNkg zeFzKmA(vkxt%01TW4?n-6h}%7f(DKU;=yUh)vv9UVcZ1zjiK9(Y{4|SY-l33Id!Rt zLLbx9)6>y?n=d_p^l;+AyCx@(V;d6yZYJvce zGq9*IiTQvf%4(|xjXbMGUI)BrP;f#Wv_bRzlc^F#38-oFhm2WvX%vZs<7B2|Rp>xK z*tTs&j&lzeXu&Kj3a}han>S8kvd+C4O1{A)NQT^Z?$AB*`M43Fx3=ai!G>(rsn5jN zO_&fH`(=k5>6LC690gU$Zp3J(i>L@N4S4*z&U})0Bm9y^Z@78 zN{$J|R>rr<@ezPD%})KQxv;~##OxC%!4bOe3x+mX6C~%%;U%a6)M^*)wp1Zg>Sq?# zpRp%d3`PcNWx39F#RYk{tu{rCTR0lVT;T!7`i1H@8mg^l2P*#_0VI)Ous{bMDdYht zeoF)dAW#Ap70R_`{Gdw{czx(70S76%q2*;oJ5f56IDxwynqbiXOMn=P08-K7v^1}= ztyt(YU;x~r%b4Sd&ik}Gc6jBa>-2;+^ahHTtpjJp{%DnbE+2`Cy*dN#xDmsrohSh5 zXu=ZlabaogxZ<^UPg^-TA1TqU$whk-BO`r+VnLpV_!%aBOdtmnD{D(BpjkY7KlD(Z z!8UTxfZ4EDRm-~ZOr3gP8%a@rE7AHWe<$vq_KuX)cY6Qk8OzziApXW3;#`GovWsyQ zMP;--RwC1^Ktr{%2vd#;q9g8yvnx1(cP1t_>d#K=&wf#wBn_6j?k8tbWXOr0u)wZ0 zIG<#4va$~_QQ?9+IxCNr#|25Bks}DYK!Ju)@-zED)w{RW^bxN<@E_}POrx^(0g1~S z95rO+6n-ANcaWI{xPei=5~K%|QruvPXL!S9FB@K9TBakDT-GE0s{Qs>8bia2Z?l`2 zDARGVs6PBln(L!wQLVphD&La9ZhH6%*$M-pB{Wq(c6Rq~snO+nFd9600)dV+qP@6Y zPhS2`{|@=Ni937c4J&>U#L3aRcybp1Jvj;>C!|qiy(gVv^t=G@uPc|f$$y(POM_<= z^;Ltfx|_)WnrBjETI|7VM-&Re^Qf2@Xcy(IBa^2etKQ7co`j*r7cWOzfGby1#S zYf|_Q4fe^7&aT#;Fhg>wHXkcjtUiJ=0jmAgN3dw!y(GzwN)i-b&;Ot#gWjbixQM^U+0-S>55#G*Z5|_Wj2X+`1;@ zp-VZ)uqg;wcAcB|QhFB>l6xFYmNq4&k214N`k8?#M2?xXdFbXjHs*SIjaS7!3)<~Z zo@em>VQgqU!T~fbHuJG2A>l;su&onkTT2Af2q?KaX5kA=K~CA2`$cd;2XW<5)|x)6 z#dvJ@QX~bGpl0KDn&?%@_3kue_qG9hjgz82emA zlR&F)3HcExaK7Sdfy~A`xe@2(oh1PMO5>&P$u}hvltrlG1V0x@#S{(CHXB;8lgr+L zEKfIuX!wd?S*D!-n{vyquw9K7(7S<&dq_h}& z2-mL_%aEZ`pizvD+a-v*g#x?FE!~bh&o&fD{~|&HwzeTQSWx5)r9Q|U%uP?P^myk@ zH}To};S~9=i>mo6=2lkk_MGsd`edXl3-4(l3yyWM}H5V zsE|(A+!o?QSelv9;i7@&?N@c$4D{lO4n@8V)>vp zfCQ972-=s@p>DbZ`)K=_CoGBxE~%>}7)%umMl>GW2Lj9M zFUN>F80}|b>#XR$PlTh*)?Aa{6q_xDFnJX2{sG&X^(2o^;yK5ZT&nW=I}tLDmt|09 zbf&Or11e6X1+On3$$NLgBTL>tx6k1FiUI29$He&Bg7H`dqg!ScWim}rU~}+EF1t%pXJ4Ks3WEE_FMT$G=T`IKzyvB##2FrzD((KI0#~0j;x8qaJ2SOb~4-8u1|jWOhTA%AlgDg@rR!6t7rC^V%JV-vuQ@lpvl1Uwb3q^lZ%iQ zfBIwvQ{*FgrpUh;P3JHRUaC!}M3T2Rnwp@wSlSF1?O&g`>iv4bh*C^I;IjPU$eIJF z3Xd;l6HJH-5ChA4qf59A}coRK%s5>eF6yU5-DRAX2x)8wbzyo6>OR1 zVIfiAJp-nZ$-HWmD2B}U5?WfherlSE9D0CJrwV+<2n64cXr7uvC|=dzen$F=2N?9Tyy}L!k0`G zCXU@vPc8CBKc$jFum&;!)cn8ZhS=@3epYYdZ8RU( z_;?!?gFfB3>d2Tv6{fhvzqzKLV@1Wa+DO;S0Q2hI^k)$C-YU>c>@B80wVY6^v?H|S zMz(o~fK?q5CbZ}xqC~D&H-5b52oHsz?s zL2of~Omyw1yq?}e^IWphYesjP0nuqs@m*YJpVxR@l}`cNtrGCFcyZNxxA822AV(%Iz$RPlPhepSuA3(*t}0YYTP_Abyy5C1~)=~~#n zsYVAX@u%ELQ)1BNL&~MX9ysguz?6HC{+)UMnlTsAt-DEhwv{%+J*^x2@`T482*;T3-BHUDI2XPX0@1JPq<63~QQd?dh8#uZ*geF8m;We&nH$ZFr&nG7+X z5P2}7zJD^`((BL5cj2_AtlEWjXZUdcfl!`x@Un|i<7r}!#3XAK-A_!X0Mn!?T} z_wIGC);!a_Rp27L5AMU3ZPj<|`~+8u>uW;JW1vE}4cB$0ryY8G$?j;l=t4ALRKFY<^-s2H33CPUPr5%6vx%6x64!8{n(9-V(J0D`~#bJ$$OGJ_@&vmfGM%}#>Nk;du4E#GF4V#^^9 zLktHjG=mp=DU6WgkkvU0Da@O2n@i}+V9`nmQgh5%vjq$5m{Odzh2KMc!fFT;eJ$Cr zUcEn&tcr;uZl2kY_k9rXQU-nLvfxXznCO^XseT_~8^OarW!>X5RavpS>Y~)d z$7@P@_t95(_uV`AC4doO2FN}WLe9KiT*rU7kBpPh6_9S+!4ypx>L}LL(@X9&7ktPX zrs;`NPJQsx*W^7rpgiPzeAHo;nANxD)-&ZLN(pPfgL%~`dG?oe1_J*5PTZSEA7wuO zWdy!rxqlJUrVaPD;cKS$ZE93QkN?*Z!b!J>wNyrZ!uowQPoTDG$}rYpN(HW*qR+tV z#p&lH0S5h|5n|%I0ZX%J^Lbj;QZ7|+CVwCp!C?vLwML@;rzhz~t!+HwV!-D0@lc$HQ@QuDG?l9XB)NaI9VL| znUR^6ABh|DoOO@zBkT>8V#yj<+F$e@vA_GVc&eaO7jeg*9zVz}zu-JPmna|-; zX-s0%o8~kbeF)VAq}4e5W%Pmu_%t!-P-pQZML$-9Y_O$ydGF#G#{(M$8ELWil+*2) zsPBL=G<0>Y7?3~``{^&9tG%5D+`NT2funZT232`&3>qt2rzS2s>eb%}ci1HlG<0$@ z)q9(rM<4y}hsJlxu*d>{7N*hj^8-5&7L_VCLKbYwI1xSjWz5v~+dfeS@Dc6K?*Y|9tR+Eq{eeAghJy9DNT$Tb2 z0D5w)u6`5FW?{OS`yatrQi7@_CXxg4#>q<`j;|&o8U^( zYPkfP>S@k{;=Z!>sPb4T_9-$KEK09#yn(aNeKA~m0nPuI;&EkE=P0%3}eWpr8PI5$QV<(G^f_vJ_rRd@*LMJ69 zEpCQVjxlM_xY?KwHn>Bp>Y!YC9Et&%wd(D~;z(6^>>B5tEC*}r*$60eWD}TjnIAUl z85qo<2_1hn)|)zY5M9Q!S?w)^(iV(CVfed4P98QrVtNC~xNePy*_IN@FFc~lP;8VO ziLwXfI&?@u;FjKHgZM1QSV9;~B!n+KDM1tIFEVv{4|x8+mIu)Z)sc}xhdrT!pqXEP zscEsIvr5DvDA;98{k6%k7Zr%x|NJSln{A8!r_ZuJ(h4uY=U_A_C*`AKK^rL>G!3^l zE+*$GxQZ^iI)Tnv>u}k4&vjW}lUD9{d0t3f0Fqk+FixX)n*2fQNE_K2Bo949WN()k zN?l+&OZqA>0)!0>saH0ZEV#R)QD&4`3741FCeoC?Av#IY4LD!zWS*Y7*V?a$IB+Yn zr|E(SceW16XUQDNf8a;7TRT!mwyK;G1Q5HwLD9bO1zLn4a4P!4kgJ1Aw50s49xIm!!bq zG#p%O_&EwN-Za*SMT@a1^f&XoezEh(VD0J7S=F0+MXp$BkQrY2OxI_ zH@KHf=yAwZXh9N>Qvdv$G z@e#L!vFyW$&tF{?U7>ew81$45kL-7Ck|{C)=n;J{W+$(2HN0`{3hm%z9q3_VYWb8p z|B;5g@3iQiV@CO)6MvP1m$%i18pU;riweZe|5X^+=2U;oe0Dp^!;!yhJM633yj*(6 zHaG(XvT?|oq1lKd-q=RbOPo`P7^4i`4*wI$p_mOr(+H{Ee8qOR=z#DI(1}g+g(_-l znBKw#gePda(h1Ge=S&W?%1o^k)$S7Cg;K**8+ZT2ZRsbDbVNFiWA%6+xUlpkopL60 zu@wVn_zW_b!j-tVal16X!;tfa95k)DieO0|2*0}L#86cAoKwg{o1OAdJ;;G7)++&B zppErI;Nze=|I%+lRwM=~urTLz5nRc-)^qK29pem5p4|d1DzayHk~p%$9IQ=)$8%wt zpe18`Tq`}z{2c+K zj2o~VFDAJeot**~YLgf-1O)%*a>R()+%Tv|C~#Ufsj_#0<^Q2qvTA05eeJ#K_;m{X zP_}P1gf`{-Ij9takOn|_#a!~}C22GHowR@Zo-`J(RDsar#>MnNv zyKS0h(co{z;|koO(BXcw_S#xfLPGogquE*WmF~dpN@iFVH}ULge&5HxYXFB0LqTc` z8U|d9FqXJmSIoRRE!?5oP4pv<>ZK;|*n_p&l|Hwm&2GDhBVHB6(X+1X9T^{=j^Z_P z13v5P-4VXwoqttE`xwsCmO485#fXyt11{-_x0%HBxs;iarPnqZQZ99Qt4_zt)YQMe z9X}Qso73KFgg#~Ghxw2g3py-4YS%XPpx!BN)@-qSA_-q2 zvHumQSSPk^n+Tj>=b!KFlUx2`%4_Yg`YSG`N{c09cBT`1E`+`KwghGEh4(;VW-Ez& z*56N$hnX0tTUb`+c(lv3d$Tr%KgOQDTL_-zC@84fdIr5O!p?+_1lz`~`B(YaD#1;X z--DyBE6qY(=54(oy-0|UM?O8;eAnCAc5UeXA@e-JN|bag3xR|%9kTP4Aja2@huP@l z`xLrgmPIPL-KHh5t@YRid?ZXmmDC^()j4?qe3E3J3YJ^_%DRkO=;BC2Cw}S}NCS z66%mj-s2xz-ASZ(owr;jTxQoNkFJObe_pqQ1|pMs>DLc#haCt#*EgVKP;_D_eQ+)b z>HpHdJmT8dhkV140)4cVjii%hW8^E|0cc&En>(bVBh{7;%`;mEJIxx~f5Z(WF=(O> zq8E6j-=#)1;nE|v9)lM5AO|%jS_YTl&IPzMg9fJT(8ujDDXiKD>y68v2j+4h>wu0U z{M7AIQXZWa#)l*a8K=wLUc$N|tJ#B#Kr^iLE-cU`!K_Dkc&y;jP&G@{y0g3cwUcM7 z-Oa9ZeMxyn`=YG|g=_A6m6!wR^hsw^1Y0Arv>agE4MMmfZE+Cf-z8)%Db1_6oonb} zEOT-bnxc+*s1zbSid>D1WJ&ik|c?j?T;s z5fi{hsCgHP#ps|LwyJoERHaCMdBRrg_)_q}lsP=F><03-YbIHug`dfRp zL7pEU>hxIIcwWheh#7pEQ+m2qSBu-|P=S50w~xurMyRRF@9ah1Z>hgBkGEBm*Jl9;=Y091^38&@uL}gHq0OKarwae`cQvif z=o_-P1l(2AW?|t6x5j_c4=`QI%%G)vo*`cg*V6af5qPB9!bLo7>R5P(hR zk8*d10H5{{^++!4^Z$!*-#CC*e1!M(LFv-RM={a&@q}0Y?Qs~Pb z!TAN+5f_8yY~sfcVSX}kDIW}JKBCCh7tfy6J-yMd$0ofOH7J+(L3jT?^X*sZy-y++ zLxnc{LCl1oZFig@)X7c_zfzvt9P;c5(8`0Mo00tUK8{NJ0&|nI`)s-_%C?o2x|9515VC{ zUJn;TyZx8T!hkPwWRz=%~SH-^%jp+`9d-iiU;(W~-qLG^!kU zfZWPng-->tclduJ3-ukji-P{{%a@!E2MiR`uR|-9iB2@_enFWfJDV-&RP13?a&va+ z31Q3zj8DMSRa>gIH`(WcIQ#o0-}<`Waz5p6(APt&k*fecpvo$41HC09J>J?Hdy^b? zUl(U{xWPKA)wSK4^&d5JbL6n5?G53o6D&5riIABm4FRbZu!wd;hL9QJhBR7_|BlUC zSDO~SahuS%j(YinjF#i$zqy7Wb4~19R3iP2`aN2QHEs0sGJ?fwqAfbfer>2a90rHfD#u1hhNKMHIQOA zx7v*xwulkXQ*VXQ%VGS;>ry5_wV1YRqv6l;P$7YVtOH^*|fKV#SU`)erFF3 zve!!ciBP>zYFe?c-5%;*eLLxm9ECe`n!cv&0DBPc0iYtzkU#q~TCQBXe$^s_u>k(F zBD9u}x0BaJ2N6QB7_h5rZea?vO(24Vl-2(c<^+u1PdXaY-gQHvg{cu>i%^IY#%j)s zBO>i5DN5R8M45cjqT;0iqx7S7975;@Yb{btYrzcnqOjECmo`d080*Gd@lb z{6jp0iMCyc9Q}*7_6`oyp%g6<-Sh2mKej=e?)e_AXpt%yyxCw(xOx=PaN> z@i1mwF$gL7_FSk1etp9iO3=7AcJ&7OapH7k;&fa4q~CfZZtm?-R#6$nO%VS-Tp8~y ztb4?13&rC%XPzfFblP?_f!XEttv6xKso=oFBsF<0V6{$RwD7n>*hC!lsuBFkI~^SO z*$>~_WcqdZuUcfjXmis2$_27nTX|il-mUHq17$f~Q*#p?wY%ixH+}0}@r#UtQ~p(U zqs$1O2O&7@#FEmYlnxYGu{N4 zS+6^?AhR35abqNw+ue4o)~acn6w5<9|D|D~hcf$N^Z+{$UdAPA=@aNE#r(H#%SbOY zUE<$5a7Du=Gv^`%u)Ua={Ve-dxTnS+F1p*yxr@?_q=x8o;g7#lria?lMYjQ3U)R90 zyZ}d9%AreBb+S8BEDbEl{N14j5M@%JNQyjpq36-K(Ip4O(jNC|xyv52_8m4r_?fj$ zE1PFF<-sB~rnyCw$G4!d{r2Ppk{7&?ZTHLm{u`>f8P~4iz>~N9=?R}T%`GFdQ|$RZ z`eF{m#jZ+)Tx@CKQjV**p8w9CqTD?1)kogwJ~rIU^{-q95G!?W^M zYBI;>SJ*(aV@L-MF;T+{QkBkMzwlNz#7iw^%W+kTK%dN90stb3e!b1>e(P#p9zc=> zH`MaTx|Hcic2(vF^fJi$?;r4R{_q!ma*vMxwcG!}faPR5o6g$geZ40u2AhHo{_Onx z9mOytwOa{$j{75N-K|zXK=6w%w{vHM>*u?A)Lo#+dH1z|?H4ddJ;u^eOIM(SmS1LZ z%s)JZV)jQl+EHWW~3OCiL!EO<~?Y#p^2XETHXo$aTR9Z)~X=%Rao=a6eGN*W_n zw2vlV`V^sAslp{AD@zJ92Tg19xv7j`>L+pk$Chm70Q-s&hh#*y zg?&g6jDumbAA4Ri(|AYu1dP+VZKxG~0qf3)f8ATy^YI^0!n)PELwrBkn@Ea}2Ybfz zF%2+`BZ=COlPf(wNIC;n@ftVGPivA9)#XtCx$*4;{iJcrG4hd&b{mAoe5GtSbcq*f zqo>fBgvm{|yH1R#zkx22Ar~7oEdfc{>Ag{|?rtmyk)iI(`mRb5;_#?Pd|ivM*^A|L zlcidV#gf|4)WU+9<$X1z8A$wMxmtF{ba;Q4{|*n11`V*Ud+bfP3r$cz-T>?bv?&fc z6jk6Y1pn6E$Y>58AF2mW@PiBn*))4_noZ?clGBE0`Wwn+z@?BwaFni%8^jdgV|vR- zQxip*nwuM_{n$<$#qh09!O|Y-O{^5T;HVbH2LeZIA5%ewX@W3uq^4RL;4fOp%-ih< z(B2+&yLS~27hfB0W#sr)A^^%+Mq(JCyIH**0Vpsx)f~Dv(EDbszSBhyv;&BUUbxr3 zpi;Ff0_F=sWx`n3Q(Xl{R%Z-F(BXdxmwds9e1)Q-BAB&(^M)-q?vtI#!t6b9_JtoH zC-TWrdTwS`L3`QYUeTu@Kmk<|!UMm5elHAIl;)ixBhL^x1v{7J-v#gI_5NQcKMykO zd8HG*alIwBco?EkYgMS0bDxpE+NOKi zFPqn_=0P3GOOjb7jO{H9Rmuh=LVL4jz+(_zeJhWh++=FB{ls?QSF z{xy`8>I0per6tP>?rv>D^!X{s zx*10xKY^;?c<1xesyi_SCY+DBx%Z&!H9NZsq{gq|tY_Jw4)*LbETKA)g9p~74;%-2l2PsQSUw3buy=YazTh}WmmOltXk*q)h$(VXT zO>!Ssz={<=aJGhyYvL}6f!g8v?g|VfHmhNZ2B;#)kJo*n={sgVm-{sc^u4fe4|;F; zmw~5)gz+RW4XQ*u%z|a8wmPr9@6karKgTDRQOrbEf3US9=c4U54Jtlg$`t7x8w+M7 zpHXgNiUQ2UQ*ZDg;@9t=Rsp=kUY}(C8Xddk4=(LE!}G%(e16xbRW0uS--CPau{^K6 z)FjpVjTiDH(0i9hGD7UV?(D{~ebk%EF`=`AZiG^j`>B&)AUz$uks-5Y&G8wScx>06 zRsgS^TiOAn`(_*v)iCltn%hINwrm>`^mVORC08!vwq?p7Bk1VXa4Bv^w9Y`z1HWSU z$a%iFHKs)$1#M_@pTmmBlG0MbVBQB96n4Bs)trJ_&KoA56@J6<|MlpNtt}@BHo@sV z4J}4m{k+OCSm)O+CIVM)=1bnY3z`;`y=!P_6E154!_cZ~uwnatA7oIFnW=}7;ufmu zZd99hX&*c8h4L3R2^mTo8lKL9x5!@7G0X!(lO2w|_Q@0o%ZMyX4AXH6*&(R?`tH%U z$p4C~=vxfvjk$@jfZI`V;ZtkRdHB5J38I;GIeiA&btarrv-F(rO2@QQ<|lEd_;X;6#42K_%k)X-iPDtY1=Nk#Yk0i*~}glK5YaIoGzzscbP3q&1i z?}Q^|`4FU1v+;MUMQ}u5uG+)t5F(vc(G#L?BPXDnIllrnhngFZ?m))(KdJ?xV@mt} z7E1Z_)&cXQk04pHTN%FcKXuQG2hqaJ+NXZy-ny$1a@lDogwBlk)1`C8RjnjTPJc5q zfLq&VOb;tb=tOQ+tv$%KELeueGZ(O3NUJ?vy6ip{aqcZp4z2JiW5a*Y|M~SusxE=S z9C+2&TqBU7y@l)4y-~uhpHC}7hSj*KtVU0QT??D{Ky$P6{HMeu~b@b-A{|6?F%{MJKKM|o$KoD z@qe}swAPmN?dX+AL(y$*%wFv#^?ZPD* zR_qy~r4ps5JV#a%VdJiwJF^&lnjWA5q@y4lp<=^!{6x!-EEftOtHpnGw!i~-H%9S; z9NeVf_p<#iKEchnxHuiBPL|kq(-EB+ht-JwSB7e^z$8Oz)B8ybR6pR?f;c_QADY-i zPE6UrUt?c{`1XTcK|z%W(&YH$!qVE>(wep%$3uT0-eLQ#Upoq(H~a&(@79rWB4l3h z3(2gdjcK3FK)c2|e;rc+Vmr<2QZDj!B}5Gbhh=U2EcK2`EzA43<*W9{H#*gm2fM5W z@Z%^}%Y|VyzFS0?7bN`}dZx4~puWvbi^?4qrO`*a$_dnb{rdf&S`iQ1_iV!bfFQkJ z$Z7H_gg7ebP~UGI8dBYT4W;Ml?5|&~w`pN&Tgcn+6HHm2drdriwezgVsegd|v%(h` z`Twc+L?hkH`&}L2$)UDszce%rLNcQ@v|W^sN-oKjd=5J(2KN%|+3{jpBrx<5HMV0b zT%6on8uCqFWIC*~<0N=GMsU)OkcMs0zlWKGd4PqPIS*^1nsuJ2$_(UyRIV-eqax?z-G%mBp*EZoDtGk7HCS4 zdsd3c9{oByTxw}cmHVuaI<9u@4Wf5Ww?+E(+kM?c22ZR8y#fWgs0n=bb}c@qh{YA2 zTrl-X4f`C%CQzFO%YA}FL-YApcbto=tSRAbM2`CDP$4LjU{^LbW4vq8r}0UC@xZ|q zrGSv;;+gWvMDCYx46nZflWQ^4Pk5mYdk~$am8K>bF~RLOadf(eh&ioF^KKRn2r@LG z+v$Xq-_mCA9rF6%B50~W$)j$!WvwBW-v^3|xJboKvawPoDEJdV^ns4LIWFu2GEQwl zSDu|c7{UWU(OiEAuMDWwxrMg0F(aS1hY{(Sl1k6-<>k34f`Nts;AEP}jjiK3`$~*= zaR)joy>{Oc=z^B9BiM*8EPeMNhEWmYSG0Y|c{`a*(8@w1(5VdeVQHVdWeeo53AU;n zgAbRk3FA$|d_*+)ANdihF4qkV+3!V5bz|R18=r?RAIR_m`@x_EM*U9wIZ^&RVMjo6 z2L=TpGgldNhBV)C*th!Y-XDQ`ps~r!h>1~ zFWigKg_V^w0lA3O9-Tksaf)`}_Ylp!0V8a)}7m)#yH z4bw$^_ib@+lEs!3TVDr8hUAei$}PYxrOu+9SPMNRkAtepB~1ucFJ zm~`s_D*>54)wu~wR0JmOL|?uj!{uRxb=y`vCjV%R8*BuqLFle#R~0CiEnvVdu-+s< zh~*4xF_2ayK$0qUbb>bT%bpd{j5*IX%h_SRjI?ugVz*R)Fb~P8o;X^&asJt#o2P#= zgiaQbl5Zcq);1WpFoQvxcbr1BAD_cOnu?1{U{BoCeVPDE=Zd22?4oSx6eTm@0o8(q zSObwWhyq$#N=-J@-&0wU^BGnDfSjEZiPp!rTE|AyN*-svn5*=1O%|hP^3^XjABtED zkixm}QAh|$NU)INViQ`pDV7-wbmdu|o1y5sxYMU0o_C)`TGLHzopLgPt1~ zSt!^^KRsZc8B~ajYtle&Py96vPY%BofCr>*?p2V%1LkjpP4&<+@Sm5`NrPe;(|dED zfGE(m(p{1|0!Gx}^$Oq?9x#9Q1CNl)o}W;r-IT(GL9{QUN`p5jXvakM3SFy?We zsF6_W+Fz3mogSr5Y5i4C8l_rcAjudgY32D)`828{rZeIF1Wa$1I_#~|7qQy$f3FFkv&oX4-IURjw*UsuEq zvjOH@pv9I>>vbIbK}8rldDo_?e$r}rsPbD{$(=U{5uZ;oQ!rr(llS4i(F;3=&0Ln) znLm6E4`CQ>AsQ8j`i;3{++~ya)zwv_G3sy$7#R*)n*99Y0Rgi{Tx=}&r2Dicfy||U zyLcXcSXfve9@z!hDZ|`OP@p8VkTiYjo(yP)?=78ZQ}c;5>;ZO*ht(xM3lX4hrV#W1Ohp<~eKTsDn6*qZN75)yJI@cwcEsYIaY z7brSmMkJE039J0-?=P@m`M`n3{Wx$oH;;K>B`pwNw8mh3aIm>TGo`0tBmG$a<3|nI zyO@}mtPb=#ZBaomlw?wWEiouiEq8qES3^=X5h>~G(UNw(0@t<5iQwWXIvXAmsN;Qz zEhMC+109%_F|S`wa{HSpOU!LgDl|SmPS(p$<6Ga8)nEFmtQ*NhIBK5_#BYE_K$5;+Fd;}D-bH@3z_>PgS;if;#=re`QM1tB?*AbUx`v7ec zBt~Syg*?p62#fHXp&nT7^7Onku%cbFqx7sR$s}E-6?)Nmm3Wt%#MPlMCz^9ZQRbab z+yAtDG!d~HMB|JPjQgs-+o1t!J z8b4=BTV&lBpqk}nmW!v~{D_ZyqEIvkUQ~u=q|#+CN)^!_%W~H2P@CPi=#|9F44yq8 zGgr&qU>5n3oSaN>_wKl$Th-?pt&|?G?cb-Tr;qjK@+#Nd+(7Ip`Iv&La;&DJ%C&pE znm@44kvs@Dse2F1xZ^tKO!6B7XH|@i=hZDScmdo#{55DfT*fvGQ8qy(<);rX?g5Oy zM{UuDa1W2TSLt4H@7RMSAa#uQajyT1KEgP^5FL2gA07!(F*{V5QF?_%(#mU9*!tTM z%rW~fY%liZj3`G%i@I%sY52g(n`7mD_=iM$c5nkOV5GUUVs36eS`s+#!K%o9$up;8 z%weq2J+67$$+bOZ;&}Jl=R~1h5^UdA16;FQ=4+SlA+X6G{YvkTVOGQYTYuyI`&_lx zFYR_-2jUBCuh+we1y;7_%WbeB8c^jk~*U5L=81lg=keTLAU2)j0 z3!J1^@+MvfwQyC+X-(*tA&$(UH>=q_zkW3!gA^k(Q}7!$`kcKEqJb5|WK_f95!G+* zJ0W~jLQaI+&ef&4!Dg0k-fY-f(CTv{N-Zb4Cc=c4&p*4%s}U|Jd}kJ(o!)bYyIip~ zpX7A7h$?>ttN~!vmV!c<2FG3e*cfIDGrqBrO5<*_JY^IzY~Pfn{f)foW(-Q}a@RMe zrm%k(+-t&tnPUz&GkrZ)Yoy&^MSMIVLFA9JyTV>Quk{M^@|f%YP%P!8Nym!0ohra4nqPhLTO{iZF-&X> zG(G65;{L4Ex3?GWg+f7pTJz8=49NSlx*Noax!Hlo0ncW)4myl%z;d!T*c83VP)%L^ zN@gr;(9KR9Va)js`Uej%XN>0X@%6aEtggMEw6(O9He+zVhoCTs5SiIJ0L`_^jR$(B z?lv6m6>Olk&s8gVFua4((6q4dg>IfLUPhx5_qfOxhf{WKv?Mzt!}p9eO>qduoVB#b z60&p-FWzmb#CN}!2Wxgi*vU2Tb6kfnF6rzXbbay_Ef~eJJ$x);ACi7GdDM2icet%W zKr2`sf{1#a*6gsl>NB?2BdyDp7ISwa?xbpc{o~K1-k`=^0r*1oLI3l!`Lp$W8DiP= z|D@!-91Z$5yOf5tJ#|L>ZzBTwO+k)>xP^^rX^@g`T&rIdaH$9(Pbv(@5UT(4N!QBC zbvfO(hss;{84!A4a;~DnbEA&~evZOAoa14ulci668S=zf*YZ>-35u`X3hXq3WGKn` zl*z`S;Nl?p&g8Siv`z%4s#38IJyQV+9>m(&9XhYiN)fQfapej*YZG?4@S@>NEkT@@NBkscLIiHL~MKG}>VCUf=^La;r0G+bsj2m|ta`}(2O`&rR_izK9^ zA9-zzz!Qh3R z{6Rh*9tZ*y;rC}4j$hzmiW-U{|Mx}TL->vf|I@r?6P2s=oH^ikaJk4=N?IC&vd7|u zel6KMj8ZR*RNceFqkGGBw@ViX;>0xo`MoNUJNO&>Ramw)idoHz7AqC&+|fjoH(D#- zcr3B1mc_F8o7u>)S5+CHbWkf$QeWx0u)0wuB5`%lU8E{SgeJ|}#!p77HLW1&b%W{g zcG?@lz-Xe<=S9Yf9M_XIg*7!vmv#d-H)l>_mrT7gK6bo~j%H&9xQYx3wu>xGOq$4g zV#%KmBGT$`e_tQRY&bEQD{GceAsD%NiqrHE(i9DSNJ;`WaavP)A28e%f5hWZL>|X+ zcFupb0C{;BOuBj$gz37CJD9Ll7RE&pzp{O_zY@uOpKXu5VoF$9e=F^a!c0WLj@&z| zat-`IY9eE%t6uRDlnYI0ncnUu`VutVKdy&K=?{uOXZ%47h^7tfS?ma#uRXiaKlm!~ zynD~xF&xM>d)zIYr|7NW3f4r=9_aB-`t{E&N+;bV)@Rn%WmI~#`eC6TiHN0Re=~du z5^uWv<13g{4y-69j;f z-wNPa1NIGanrJC^HDzT*McjleFNtI}8Kvz075nZuwtGa)tic4!Y){b_|Neb6HZs!R zf2ZGH_!j1zn#c#TXb;Y~N<4gkNd+n*8it|Oka4|j=Az&)%OvyoO-w{|Yv~2x#+;E_ z$95(?O)4%g?g-UVb5&{Sc92=8XyeH^Twv!CNF;}ut{;R)YIKI5d;-w`1c~y|4sim1#V2Dt3FxcWC^f({XURTTtf;K`#df>r0zk0#k`Om- zC}y^90Qec@16voGTq~Cn&h=iCU?Nh!=g)UjYb6>T^Pqwu|IRKAswl-LGl~!7Zw2#Xl83-MvvKk17d=1E5TaPy zP_b1V%q8Shvhq;S6Jq(q3@8m~vLhIqkggOb5X<3(_aRVL?~R9bA!1_S^QI|gcF)_K zw?^i-M3sz!NS2mICq@}(ET;d0?k_8gFbc2KfT$ia9ANvxP~CV&o;ZITy>BB&hezPl zbp-h5@DR6rNCubw0|%`5Nw3V9|CRYX2Tf;HQ35n${jX%3Z1r(u`$8?pb7~#gexc!a zA#NXuS)lYlQ%2-?^kK_J;!8yh#sTVNsf@mp)I9890}8ea4X9D;`=+AYM?0~8fhYD& zX8wqFWr+~4_;B)~2CRwgv~InQr$LQUogbcbD*0QR=GjA;NWvgcF!NPDJZfrlW*`^a z_dOJ`qN0pzKhsPP%jc8kRf(!s7_^(DSs|gao*yw0)=hB#gfpHFF6^G8m zhYU@!Qh$l>GHcg#lyF1Sn)*`qbzxYDWMFIzJ2~XN4oF7_!&Vho%p+o z_es+YbN4x-*Xkp_{k%X8S{JfEx zg5KNI8riv)c6P6!SV?^jhCCbFLXMmMw8Ghp?2xIFR##?u|D;_(!wc}U)|`fQcby-2 zZLF+*uI&Zdb+wp|43C>w5)@VeZUQcK6tg!uqCRiwicy&J6YS)pY%98J|xtM1(a@t^R^usod-f*rBL3g*$|Lv*62 zZD8S}_c35@-y;fvpodHMB!BQMHLnX9?$cj900Tj&r1hWQ`EKxU1oof+-ar`L<^Yq3 z`1ZC(0b7$EH9mulKk5|w6t+>a(TuNx49?2-*~;3lWyGYc-c)?$i)UJb2No_kqTyoo z71g!1wbdz49R*u0zUAlU&HZ(^8vN)m?!1(%8$$@Or+FgK4a(o-o6HynhJeAT3=Bi; z>|c!xr)!8{D6ps?A^fY7N5e0@@BgHn^W0e?7;`%+%}APC!vG+62tQ#G&zq@M+C+)< z%I`p&w9h^O_Aj87q#Bh#CerKhh>&nyq^U%c_w6AkWrGeYkb#X%g>X5)6Dt7Dg9;ym z(vuU*jF|A&jy0NL(_V&Wt71wx7Nvo)eo9!#Eq*1haUyJra9HtvOUQ6>$9Z4{I6&Mb z+~mH}68OyN{N`}_0GJ|S8y$wng`$-L@8P|qw$2TAN46kG%%^{#bUc`{)Ay0>!cQn(R2*J5rSvp%0%;6BKJM;kGn(q(UKfq52>WQk85Agg zO{^>>#vE(;cC%ID`kf9Fc7c-)4t})Ja&y%$oz|#eK&AK~T8Uweu!Ih*+4&q+a0$aH zyh!2&Fwt?dmA;u3A#^aa!K4l&ODwNPDjtT@vVkd8N)OoZMN1i0 znMo>nUXnM^_+j*e#qO)}jWd*#jmsOcf5=6Z9DZ+HzI*4XQI;xSReL7VM#mhTLC?xq9ju>fcVqKa-)9132J#?YrFuyn6!^&{5K!s3!+?hyk#g3=UM-(h}d+%!dFD0N0Q)&|J z21B3>9~c0c`9^UJK$0nNL>9I`9&}F=*MCGv9G?#4@0`8O>0w9Jq>pBBa1X;{=Gf4n zAiv76dtq`JX0Ofo+)t~%PX`7DCjBm?4!=ST4KSHMgfzk}XymS6OS7_IpuZvu7OpjZ zs#^bT&K27Zu6eZK5>uMen3$EyvhR4H4%teMPj$~U0qH5=JZ6^Ksbo{<`8-Wnw0bKM zt^2lw04!*OA7?sL$Y|`eQQhL!#)I$_Q)hRZqOchaNy*mFPkraQlgLk!QPMA9KQFql z=!12=I8_A2aO+Pw;SMay`{Kg0b746$RFTihaXnk_L?p^}eyrCpSlgsR)hE;Qc`dBg z{$KhwHY|h&#~)~5WbR>VyL(QA?;eMc8Uov+RaN%&D{I;A0B|J0!n(|1b+@+1u+&b6 z@afsRp8;ez&kD*^;l~rP+9A8aKRAp!2=QF@uh%NvL#j|d-ymL9EoaYqi7}IE>M1Vx z)$Q%GXFXfpLTjWSA5{;I_q>@|=s9}8K(10NSa><5WoakA(+Eb6UOedQ?VZxZz8?l< zd!8oHu8oBe29s7i=3MGjGBtt!00w@;K0k_b4Z$_QtRraTGUMK#uu=(YCs-_SS0m*G zb;lBU>gi15E!GwsQ>w=nZRMP-AP0aHay#%c4w$<97e%3KIy(b|jPq;{>SXT1(6pFS zTW;#W5$^313htVjSx;5@!hbdLoO0mq})iC6xXTHf46_$9*npbsBNV%zVmTo3U{8ghc#njl@B}=CU3(^iGTih zh5i={JY!GZ2*F)j$ml^lZYL^_augSp{_7}y@|OG=6p%%<%${4@82Oob`15~RqoIdV z(%;XYT||j7I(OR0;>O1H)XyZ|4P0IwvCEJ!68LF71)OY>a~S0VeKae zzYC^m<;)$|>-w{myp>F_cuBA``iT768!GYrLeC=sM5X4!2(MXCS^D@O4?d;H$iTqC zfcoW|dH*!$*6qOeV~GvD?Qy_{bM=&4PVdrA&WLemJoVH|)MV3&>Xhl=UHd#!g-Eb| z&reI6?c!StGSWo3b-`1CD(0SKWjv6+h0(g>a!jM7ws)5qrOurIzHV;ia>4 zg&)HsT@iy+#YKQ~{V!kY_2b;o*t5A_i*NxR$YJ8`x6<4dSUo9RGntZ-Qn|Ox3nRtp zzT|S>@%b(ROJY>S`%w;D(4wU>+)z^S6GPacnBHHp;voSdUS>={V7Qda6OH@VU?};$ z-_1Q}d0)Orc(tM6`jmnEd2b;Nc%(oVN;k2{%%UQWR6js5AXF$RDS`Bhf&Fhx#CiHp zOk|*$3*a43^V2mCDtGknVEi=KH5XqAhCg3BZWBQ34`8iskZwf#Yyy`BRzt$E+ZpVv zNO}Ip*miH*>P8~E$(MZjzqE?KZy_MZcztBUYj~*fnCVlB40sQ@nAH0K93jwl-RKx9 z5+-AZqrV@+q+LB7;!E!481rh1wG4Fp{0e{C2(^&jnC=)M()@ofz z@ltyXlNpTNzlleq;J<)pO}-30po(OR6{OL6Vk3r20y&dpn=&No%5ZB#Eco`iSxtW6 zg}&Uw{{FfqCawh8?YgItCwpsdd+pjM0rMWfEMb@hu-!h$?am|($KYvxBji9h8Lj%@ z9cfAfwh=M)}V7$Jm&G7R4M^m4Z~FD&;UKrJqC zd@?d`tJT|0XdweZ^O%y+@M zy%|)fX^Lrzh;UCk-xp0B4w>c^rIFBjfBN(({eT3`V^Ak^i(c1}1=I#~f=Z}%m16;V zI#R|i^THV2($%fn}{uQ-p+)JgtYUJ zggn-Oa^oIzq@Lq&YuMsm*TUWr6Mo?TQFWD3Rc>3`77zsi5d=}XJCv60kZzKw4Trx|B}oE&(YKkS>95ZqGf}`!PKJIK!c^_WRB?=QE#JNut1kPgWpcS9Nxl0x>hz!RBH?yTcAC)(t!Q*!6up>6de6K{C^UTB8WJA; z)l<#2CP%1@YbTtcpycJ{)xgGG3`|a#{%2ja0xLR|jh?gDUET;n!^n2|y59QFZ>wZ% zhi3W>2#AfR%ghI#=_V6W&B_?&-;X%VEHG2Oc=tUkhO` z9m^{!)|mD1ARF4h{R-6Dk2d-=j*sFLsabCee@*7EDbM|p=QOqTs|kzRSqJjqU|@r% z1|GI6byN3Eq_cabGN0XInDG&f1K{T6{**HmGvJ}Gkdz zyw9lA$j__op8=|sdo8Es2;|9;kzJUzi5MG}n^=z5KA z)|6l!cW0SXqZqQ|ZLyC`_y ze)$}uOyQj$PhuZetGC(L7v8%ZWutf}35N*}>?c*NCfK73~ zpkDHVnVAIIZIfSV^4XKKQ^ZP`)qqw)&vEZ<%7uBfzZawbZ41Q3m~6?k5w`3Z!7kXZ ziP(R0c+Nb^W(_V?qv?i7cqpsSeC}Q$nVOw#sICQ43ej6t5mH*hgsd7jSAZ^jIZOgF zbVRAXK_fDQ=R*<*t9y2iKkOHJ`Od`t^_ zuCNw#bSziO5!InueZh%FI`~lV$Ig+judm_08jb{q+;d1Q?L2scD%65Ez+_qWdaCCO zoHz8eH82rL$`cLbXFd_lf|y>&3XTlAM8Wp=+Iu+i0eLlAXX(LVeC50jm=& zNT2uik`2yNt$-%@(kr$5)>C7O`n@rG0g4Y3z8#!UZ({I1!2JkR z2|q3?$zp%m&rs$5Y*2FVo3zr?(z-0FH}L$~qG=vt(a_Gbk%UoW$944f_M#YP+z;^- zB#=Y5Iv*3?0*>S{U4pCQ#suf$6MUE{1s!N#(bGgt^y0^>0Xn{NRAsZ_$Xqe&>E^tQ zX+DBO#>V3DKcm}LIJp%4@g+dsjBcf#iZdkfbtQNB|FV%s(?(ros44Xx>m0hjD7tzR z5ox*2q&V7betG~8p?Plg!o9Q;18S`VXdxD4st*q)Ww?_5osZzT| zetLBh0r$htGR!U#5?2N2H0RmG)1T7Cz%&_*$)HNXQ!_o&%PQrUVdFitdEf={>hQzP z_%!>M7s$2C#==~P;bYj@q#;3x!u92$sLQ~K!srAPEQi{O8ES-loAF4_NWIJ`LWm{Y4b-P6Wyma@Sgxh?+JX?7T1SQm>zk_Jn z=D_=vLwlyu&_~vvY}CNG>=#CSdxn%2JFaT0m1xxS{G@BMo;UZ7Zx8(SN%GAm zIQq;7Yl-6Nw{a3Bd0;VMSS%YQ&gPAsBu|||s|C#=G{f(hcNc-XE)c`JE^Jg!94cyu1O@$WL zNFVFhr>LBq!sL(rs}4X7TDiMN=(fMUFcAX=@KDca@dDra_*mxU8O6px3Xcce)eg(O ze$#wZkRzk2uF9xeLQzJ}c2Nf+TAKHYn4>yKz|*-pH}@zr4x|TEzh8sE-qu5;DX7Lt zT}{RPr2YhFhnm2@3qXF5U<8QbY}&nQ`IJxt_cz=?U5mgFV=c2EWg_(hdr~y+V9O1h zH*Dc-up?X%;z{o?u9(zx@>tM6=gioFK9LX5v+%deJ&B;IRngO9`u+Pt&i{}J{VV>g z@Z!7F34%ChGIi{Kc^Tp-BkO;^^!wWGTR+?RR-Q;tuCjWlXiSjA%=QenOz{<@0h>-%7FTrHCe0n*V5nz*Rix2{#~ zkQ2_{$1x4hcm^*Xsc4Q0K#_o`p)+7TZ26y;8T}!D(mxQyB7Fdh@9Na-xIJbjt<$W# zlG(6DRrN={67#`BLHP8|K7C0Upl4*%sj2_v!yK$ohlh_(GGsBTroLlpf@kLf0kYvT zuzpy-v9h_$Z3<|us)<+&kT6YiR1A~YX<>=?-4%mUSdr>kth8!_(RI1O)LTZN4OqW_ zA0B)N4Fp+u| zF`dlT^|~Xot}f}N+xYh47by++t}M!0DJkvqOYP0f{4F;Xl3fsu_&&n6ih0x3*4m?6 z3p!!0c9Z4szU1Esd@9{~MKTkPCU#0)Ge<42h2Os9n--&9m7!SLO9S*e9Ja=@Reh>}7Ec!NQ$nVFfZFEy0aEFH~yaAf_L z3ovTNadU64vA5%RpCYa+eaot&9re}S+1U-hw|~<<0ArC`o;@tVpm;XgFt!-#Hut4_VbDHc4F78dv z&ZzRnjzmh8u;p~iM#c~}-BS+j>Its&AMJWPA8r?K^{2$dYA-L^xdh&fm&Ab2UndC@ zvaT-agIi(g_|H98BaP8)=cWG;u+4ZfavU9qWOvTo>L0S*149Dzgo0`yyJ zj<=VYp5nn69s>h25*Y($GD8SBA$$>v3jqC^ZC+I8ns<=6VyhV&++I+SVt8qA?k*zc0_|TrxcL3r^k94M#}Wh;Ct3pH7h1WuS4Ur;OP0_EcpIDG zm~WI3+?0h-qTot&Qtzw)C& zbRsRJA*s8tRXn+^zOU~I+FWNR?3td2Z7Tzq1LZj*Bf~gh+33=xs9+5z2t#hRs=>jN z(rE>&BB)1ii|Sq1;_5$H4CgL7&EBu$X<9Nu?XUyKZtm~_GYjL)P)fbh6Ld;P!taD3sEO{;~` zPma0Dm(07kuJLQ!L@;=DWMx#13bPwb|F}o4$Gkvz(^IZdgZ`c^yOELm_27^ek7y-H zfPSIOuohmCKiIe1Q-p{_3U6?k4r;-fOcQvU4N*NVN73{_zcrCGv`kET)y5r-k&))S z`T;R0&SFkZbuL|Ni#Ihv9JlSf=wx1zR>4R($yo)Kz#%LHI5s9;!l-xtK8xyN3JG8g z3tLx~SRs4pjFA2zKF~fXI>KYARpG};y_1JSf#sI%W89C4 zGGveU&NN5XrRs>|Gb%x0{uQZQj|gco3=m&)n>(EBfJ-1MJgT;@uWxj=ckrVS-jAy{ zq%Q>q;l5~;pSll)UHb9|m0a(nnr7HW73kHu0;mX0Hr(?}I+fT1O&$WEGX{o-8)OH4 zpYl9e7d-0^L*%GDrQ_uL;v&n<%?*qY)Q;g!W+f0r3U%*=P-Tdd2Q>ZR0K(p4Q+R$8 zK#}u{FfFDg4?bi0XoL0KGgCA&Dlw5L@tF<+p(ga@rrO%D+3t;rVhiQssKgtS^3?vgc1mIdQYNB*8Vu-*mQs@@t0O@RXm4=$Jg!%6qkwqJx>P zs48>?7UFcZJY2@La7AFbz*JpW*D)ZEC;>3$^2q^k9sj_On)|;WV8wOq0T>MF=)6#f z76b2Cj^s;yGL1l0dL1x}R?5Mny-ygabOEee;Ya?V|^&9_~ORB*e zaMQ#db#s!;PNSiFq@DmLl8Mj8H`>#CPF%wFnNs?;H6V1ypQm3gC%tAC4r!161I@ zOwFEut>%}CyBwuOFF|w}EOUl=H~ihC#iJeBgkYn1TU|6mDMzb7PeVybNhe<|ub*2S ztxoTJY^g_QO%I-)$h@R(V<7n*-{)-%?ZOte;+ouqmUs5_?BLO~!(i@n4@+o;((V$X zr}W-6V~I*ix(~mjkgGH$?`fN5i?uu0;zbdM!sJNwPg;!U7wLr`@R&mbh$?{;zc9A~ z+k=^(q$+9^sI$IBrwUS16z}Z^Z3uijI2NLSW&P6*1t=3g3H+SVPM79%US^Pq0$^f}%Ja!=tza-d2tL;FiE^>`lZKU&(23jjp{-T|2ZL(S=7d zpbz~?z9S5%z(a1j(Rn3`)uQa4wNYc=^k8XeafE6A8tf(wH5GP&rNAKvtirS1Y{9Cj zx!R%gg$L(jb*8=brzZ{WYXw02Qv~6Vo+$-f%8)k%TaAtmFpiI`^j1`s$y2i=ApSl< z4=)CW7!U@-A!m22{a zd)F(`1qYt=A&ZrDR5gKY2Z3^z(qAZ8{vXB)l$5)fEU)nXzA70EtsBoU)!Q{1i~NI+ zkOoAA<*c@{-2j)d-{^bh`yxyaqSOOzDF>%)LbFm{ks4+a9DH}-W22_)!;w*?jHVkm`0sc3jn zUv4~t*3Z}yveF%vps>Gsc>-3XP&!1>1s?wAZFxcm>_$v=0=G|RwCq|qq^!7REbL)A zmMkI?nKjOA7&$^{qVSEucDA{C4H}UJfv5git92*)w(B>`l7gXaS*|?yL@8JXtE)vV z7a|yfsRqBciqGZAf%68808bfdLt~ls>)ns+(mNauf6b+P9f~;L49QnpgAF)vCX4jS za^W)CXo$zXB7wTofCCt8j4>RgU4g-!59}8BQq6;o5w=%FkhsFgC3AeslSH0lB0v|`V`2=VNWwUpuElx1M?mRe+yvY^*ur%5^hTQKdF5}f>oVOPol%_Z zs2v`r`~~#SBPbn$vt>6lk&1HMhUS-0Bx>NuBgD`RVx{-e!3#kGyy^9dyfVx7evX$K z$fCmiptXcwfMlFtjTR|>-gnJj8VMwK}GO|<4r z5t5SfTro(gj4I^^4-R|dQ!1ysS7>ZqprwA?RK=O1%fcFkl%h2r3hs@_m+hBl5>>>Hlr18`qO5S=8agqhe!j_XkFb8ZCscs1i8NdIM_^NlMf3ye3TRoX z_I)Ry5Drj2rV$B`LGOaSNULs*uxq;@BoUU4>U%vqJ*J6?HXE|o^E%zl_6}cY3wyxr z`U!OV47->sDSXl_M;CJqhkdJ%MhK9t^$$g1 z-!WfvvA-_jyeAhSt_-Uj6&1YFso=@=@^LGv(Ho*gqk|j;yk0Y)eUQs~cAWvRV&|T) z41U=UjiH(Qdwaz;>h08sdT15_F`Vz#GK9|YcJxJI|JluDbSVi*Cl3ZKN$iM={@5)n zK>PWpbB{pKU1iGTH+1?W)CKio{NJB^PO&xNCbr z-o4jdIb~bvD*K7VW#_Egv~pi9Iu5m5>T=CWrLM49#ONfpvJ85z2oy}g3R$5kx9qNZ`;YU&EHCCYIUhG4WHL2Ee=87lF`E(onp6 z-1Y3c)IDG>muaO}B;POp>_9PHx%!+#PQOxsnO0iYpi%9y>DNhWdGCXcUMl^a=CEy=;p>}^jzGPVo zG@ZT_#rRYDK-5gvR5=YT_54kiwC!kH!VZU!uAX?mcmp>TDutHek4?oeLynmxtiAe2 z)~ON8Q2-=g_%TeU%K)sTF1HG>>*YV-uJ?u#lo1@0N z0|SF6ZH)Bt*aw^9^MANU_Hc)ZdBU|(hUiJ~I){`;K~+20x`cV1?ZCp5H;?nTqamtK zSg)8ahd<)oLj)BVVA3AM&hd4U!<9y#Lp3%5S!Ett9*DRJ3JjzY>|A%`P5N5dEEfzQ zj2Y(HR^#4~3=0Nsmpn_F|M&E-(L#g)6cS8v)XwC{Em(S)@o4q4O5%gFXMdNB$L7iG zBd_g%aPr#`7qM^umkS+^AuQ8@x&*g#2vf*c&HEVwdsbG;uYB8?S-51>`?nw+I;qR=bum8h{CNC@Fd&`HIdC~OX z{Fk31wLO1>kwl&vuZx@9%e|}+A{5?YYy$EiZ4e7c#w7~Cy#Y=Idv}=woxlG4`O`%I z-1X(lmyOp1(%Q_}>UOsQMLe;g=<oMh)s1?zqs{hZ6ve%RlnSBF}m#`+2w~ke~aI$Pk3a2 zktl-gX&d`f48jiO)`Bm=qi)s|QO=C^^Ff02AY8a*QI;xB_9|s^{cIL&FE`yc-SXWQ zCZC{GdkclSzuP{Uml9!+5f=6ehyq!_c;=T3pjVnXs;yj*b744rHkSm@T5B zA|h^YYBewKx$=`JJS4*%6CV5&9xV&zYOuI|p75xsCOaE`!NU8vML1tmEOHiRjK+ic=r(Q!_^qSw%C+GX_^lQhtzcfWRIE46w(2Rrz0#>D6~CK1vZO`<$v$ zDFh!+k!%Nd zhwW~51{m=o?>cP?H1>a|TFJ4V92p++c10v}D}T9t2h@SH+BLECJFhRw;=+#6ezb6m zVFonZ>K^AO07Qp=DZ>frH+J1>x!e1WpT2V(fQ@B*d=x46z;l7fqD(8=K9C05dvqIU-MDkFl9>%;K@V;1mCzHH$vM?PO~$;>27*ne=5acV}7Y-dc(11UiWIV z-z3Dh_w@4$dflt}vmdhokglKp!n29Lt$U;f8ZC01&O+St)7tGX@hP^CB_DF&3MCTK zDM)R{M02P&4+vuubQqJ66}H<6Ztc%Mza_9=nxx}qnVW}FLTijfxdNS`2XVte7S_X- zdAS-`LF&ZbS*z>40w6v;#5x&y)Nr(ua>@|AQ}L-B^t36pC<+uTNw3y}>+0P&tU&J zx^|z4Xveiq=Q_ABr3?+D2UOvKEaaUVr~1EJhvahHpn1u%qX(Jz*ga)M{Y*)dt)%8HpJ)=z+^fBzqeAHF}n6v5FBkl(1J#KLq_@%lHj$b6pX<@wL1(8s7=B| z;zb|L9Mo5MZPugp5<0;|1RfSU7cwYd>OJ}-u{f07YTRjk^}V^tWDQG>_fy z7QCtaATBxCad27c;a4*6$)?8={`TIsH6lUT#wJQgq-cVSlzmHYPbGiwF#g%ItX&Ri zrfdX$vn2^G>31z1-_ZH>_@`_?Uoaew@N*^XaLscSIKuG6AR~Pd_#%kXkWJxKC|b)a zgt(A+2wMjrO^I!;;4xo{$S?+a2Q2qmtJl^S+F)IDS^qlG+0K=KEPG|xIfKC1UhZdt zEM%w`n{*9O${fl&fBU=zW3k3JbsD_M6c@zA8EWR4Yw`nP!GzTto;n}80AY5i*IDM) z+C-K_m(_YlhPQst%eL<1-iiW?3n&RgQxQi3vbzSB7ij! z9O_yyq7qM!ky@fv@VeEnzcefD4QGM>9rssef90Ez;gjpZ0< zmQlfKJgr_J+8Y!q8&1zj1Q?7-dahJ>EYhEY(I|IP6mh>iuz~ID?1paO=WCT&98Eh( ztm5Q={(ciEn*!uHC28}iISD{Qy%P;crKe#RepElflrV1+Frly^BP=A#Qn*@83A76D z6FAopWz`v#hl3%8*#?zpgw?>M11UM)QP~?IB(v91*XFxpneWuHSI|0T6~G4d#S50& zGrdc;9@P*>G!B?!x|8mOhyNwYJlQ5B+BsiHXG%!Qa3XEUbnG{NkPN;88Ey>s?~n{r)|tp&PHL8b+`GTZ&W@?;GC^J zn1N29<iZk6{5}0ka=ni3V{b%4FA4nq zC329_>Inb?n3+>WP4h9mz8mk4cgTZyNZ6=Lj85uv9bJn3GDc!mb3iC9g2qXhR!c+fG z7W2dgzShA>x40c5lf`=uiDR;Z0fH}PMT{joM8%)kkKU;9I-wiY13N>-JUQf5Qrj(2 z(AmJDIyYS#IlBnF_~G*Mct+L%j=HS~2^59i3zAGn6jD668t3qI){Q|>?sC!`u%!)K zN(eMoJ3P&$8)^Bv-^sy8eAa^f|_K$#hWWXJ@Ov3h>h_ zg6H9ER}hTtzkPegANY$s`*4@R8A!M+g)PHWq=@?; z0hoE;Brw@6TcFmJp@fv>s@lV|-0;I57#=6o^I-+x%(nB$0XG3DHjf`d)uIGmOUP9V z2t!|6$kV7~>uWe{VTJ&vbXW5W?f!p5vq+!)49x+uh@wyFkun=V-KT%C(9xXWH zcBxXaBugd8(0+g8D`Fe5q%@#o5eqFtJSjcWp@==3)$3d0lSSH`H|}H+-ufamAmpub zrwnlIxN>T^6V-IfZ-2#Lr0(?e6qer+G00bfWVn4mf-bXg11V>>5*yGhyP^~()*a89 zws*F*^js(#rL+Nw$fpHAk1Q}8vLd{H`pFUk(`$-KB3}wYOS|lV)@k-forRTS)chYo zTO)O(EY-<@*GYxfd4(4WLf?Pzn5BJdA@O}t!};q6XD=p43jA%bg<)8S+2FE1v;h?g z$-mdC>_N)LzkEC}CmpU}%u@D++ouQ$Wrj{oY7_>0cO@13h*k8YXRrGQ~BLzg( z6W`{8$?q4LTQ>MyCk%F!l$2y7i0{rRbR>@?XjuWyphcP8psY6X>9h2J>pFjszWVtS z3P?;_DulT{Txpj_g#%0o+yRX3iH(b}OjBaD&0_6>s}RA=5A6Th#V0;gwe; zTyT1sxdd}ger;A`0ST8esS1b>^Cg4PAg*-g7m5_JVuA;o!mZ2*iUsDb@*OiXco-So}i)_9npJUfzfoes(7*}|5Brz}HhMT4F16^mQ>?*_qul&!gcFm|#xb^q% zHbo3>&eB)*2l2D#VP3v{j+9)jtps@?8rGOq!W1|#*-P0sS+SFMWMP;p`*;(U-{$QZ zyD$7;h1lR7xh#T8HC$nl7K|Mpt1r**v8i_lQ?6={EO#tY>z(aQ3syhSBxHhP14at* zt=BTryhKD*jsV$;SdA#_Pt~2Y_opk9>;oA0VrL;t!m}!Tq64VX=-ROAp;ym;W{uT1 zJ)M**gajBWQH1zRN%QGbFhs(y3+tV?!dI|9l^MWh&S|MnCva* z7hmInp|Vj_sG;12-o!`1=VHF5em#Ck>DT(dyj~?7BPSL|*TA;}gE@`k@7!?NDcN67 z_UPEMdxHc@nhDDx0eyi3p6BnhInYbUv&ZH&^NQsKTZ&5{LF2$D`lo_ZXd(@Cj@gwc z$#A2o*%;4FGObrt@&|;M!iVz`<0s zkpqM(BzT_LKOMOZWBf0eps+{Ye+FK`_*=GxvB0GS9C*U^OWgAN zHnptM3PPO}Yi@R#OzAY1DEVx1)SI6qzkIcB#+bu*$Sy$QrK;*n)fk#=X+j5oY=a6`6CGFdTB#ESy*x1sZ(Yba3cdOt;4VjetS|FZ?_Il4Ch5TF zZf97|*~Jv=)N#erVke-hBB=g>kEckWHzU3!6o6zE1d@EW2pn?)KYRBE8|~c)bge@% zx%Wkw3TjJ*i~s4)SPL1MAYHn>-JiW#Of(_uXtG08XA}>Fu;-w5Yg!_Ht= zQUw~Sr176y?MFwI_ZGMU<(u`>@Pam8IysfvfO7_G zq3C1Mbz=b0Xw(YTnc}i7qDZ$(I|7}e3GY)H88xqy!UcJs(&p*8Ip^be zTK=R?Wu>Fe7g=mlB{?XMA9g}sIpSNbbSq3!h_Tkk#DGXYW#1O@@5-t?YaQx#fHb8;XGck4_FS(n|4&U1OTr5&*O8iu!G71A|nW zQAi5{3#0rRjmZw|&`{W-0YT;kXN(ju*?{Z_%t*<%MrvRWQfjM<+iqNP_s1GATR|kQ zQ7X3p8`;w@$9w0?IoV3jR}@r2Qu<)}(m&rk7XX{Ar`55beK>6iT1aOHaxXL*#wCfv zKR!QrPI3?gaNwcW=9@2Z7baGR*7ip0vsQ16HiTMS5=Z-|O(z?%L>slVlCmwPSq`I2 zZtmzo{~b9wGxOE!39#QS_gz}{ghd>}7^h2_ywFR43(Vpk+q@&PYI zcDO|NLvgVsKca-Kh!VjjLK3ojUg~r(C-=^2W@R(tBY=#|PZ&OGO6F&9P8K$gGrdr= z!7{%*KWo-DPz{FP4;Y zvg|9DxvQ8!qOhJXMf6>)vfHuZl;;SUmEBf2PL_ntwr^jrmoS~y|Id3y8 zhb007x3ry1JbnJz3 z!Ai#dcIbiq`b3#kA(4+Tsh3m5PpX{WhYRG{L%3*s5DI5Rrx%l_Uf{ajmr5Mk=Q`g< zI&ny__mT}~VmEVCB-QXie58;l+{YhZpEu!Ifz$WpZys{=fb7mJlwr< zsq>`$Y^CFg=6EgPyGYUxQAiWmeSu#R*Rrc0PV^VZOtb#WpL2~Cct#dwJ_ZgY!cPPF}CI z#96D!Vsbyzh8J^INeg>OA(BB>IJYq%4hMliS=nCk^^~TvP zGo@^zTKE$fw%Mg$aWvUZd01QfSnDATwr_K$-=qVoGB;lk!ptaxgJd@rA3n(KF7FZJ z*g`OvFg(9Wory}%Mnt^(U6_ZnKFY<>dBN;2f4`5Dl}p%=yz_*`id$Kzsw7!5w`1Jh z`9p#aMh^!e+r7-GU==Qrd0SSl$fy#+)i1Y0;*jvLJ@cd@M@mZ= zFx9(-s>H`vw>*$HOo+LSl(G~kQ*yZmFh_Gol#|Wai^C4;IA;CA#R)sIt|RG^TTYGx zjo4g?*6EW;dAM@Y^km9fTE}Bw-g2iPU!Gsa>f_?CbgTHej`6^Z3n@Et>^k0fEp#D} z-kB8bO+(E|TOLZn^+6*;7!Ue>M8ExUXMZ_b-*+@$Grb3v&i~~;^>J<~{cya9DE4tZxDnSLU(FKO|CvEI(j+37&csAk zlQ5za(b`(%r(1&FLxE%HtbvIYRl=549hs9WTl35pJ1aL*MU`z~VSZ7Fm5c_j+yAyu zu&r#5aH~~951bplz|5}!g)one#B&znfWG~z7hCg5OrsmRHC$z%%&N+*!0j4zFFUrE zJ-)pE+5NDCzlx+fS`9||5{K0RBf%3*@Z_|Ko7>#*TpU(6c~qcPWd}@-M>7Jftf{}h zO|CnRzwhR4!Hu4Kyiqw@^vhkbui8XLfK9c^uuRMASmAuP{p_^pLp=6wmubo=%smJE zv*-0Trj;vKl-Q~kbt($0s$3#`j)_!SuL!*#rr_Y>TKes9B!1)c@n}I;TY4NW|La$F zym8}JHs&^8w;3>-AfAU6GiuS+VPm39MOoV58X*zUpw$4rUzN-SpT7);l{f+tsx7<+ z^TxUKIdXKxw^`FRL|%)(or}%P$YL%<)HJZIMaFgur&lFj zN|mzAL_$akUAZD&GaApY&|k#BLPtEI*&%`&H}G;I0zG|;x#93gnYp3Xd=L_VGCnSl zpX?`rL4@DQ!7`s;gm$rpm9w+6p&{9_1j)Cf%Mj9D0M87!taI(J#v6j?EzC-4uCg&Z zwla~Bz4lguB-Og-y}Y=vTmHa(T@`Hp*H084hL69ena1ysHDW`O9JP7zZ5*6;^?JsZ zggnFv`1#8@e{aw2U}Jba^Pus^jcZsA4i71#_+w2TRZq)jvwQV&Xq7Z;>FYZvY+g*p zQmQBB_w!Ve_nI6Uh&-*Oh~?}-vhOgnrO6}I`t#*|``&{7^U8Z9@|+#>KRrfZoU;qd zqQH=p)GDT~A-*O?cqDSEsju76oG*&two+(PB&B#71fBf>tknc?*J#}p}Y(>Jtap`OF zsg^P>73=f|YV4I?uERgU4fK|49VqaJX3uZ6*%GVc^|M-o98KKMsBRFsiQE5%%~d|O z52PI(Gd9H<_wL^cxtp%k$ph2d{!2Fd<*$s)y2?- zjlf1db?TDl=%vpDlnv7O)i`8TDV0@eZ~3%zy&d8R?tg-biIl{CD*N1p{gSfk7Zts8 zSw~gXVZg;u-b-x{ymaQ6`pr~wV_jYx*l0-#yTMpRd~3O^VD5>8pYYpu`7r7eWn*k` z?XYsFapM2=WIv@KZgF!%z;-+1C-{=pdQ5VS%K_QOL??hN%WwbUV&lDUE)BD@xM;?| ziR}xuE6U1-jinoC^4?z&0w><(!RjvN6p#I(E@n5!pPwnH0*<4D%j(bO_8o=&r)^T) zcdrP2dn}L9gZaxH!7ttddWSLVa)<}1>B;KplEA)VaWzOUiW1}Z^mIwZ+L5J{CiTL^ zN7AkbF5>CMX~L!r+{+Stp;a=a?Qk`+A)n@$ikmfj1e2Eago2CDV*ifL4${Qck#-L( zlDZEoALFULOhDb>x>%Q<(RF7ub~BWR7u&KP3z<eV*0TXE+U8h0ZMIWmf0 zT^*KH%^YCKS{r5yz@!$x!;X+z|D;Xg_Otj7z1q}C(k7+^8HSTPl)_DiDjgy&zDhTz zWU_ldAaVt)F2X`W7B}(W?R{SnS6=qAE0%$J6`Z*rkUV~Iq~ImJrsu+lf>tVD2)V4_ ztZNss$r%gluTDGfJScAK&Tt~Q0Pz--8Ddi1qx*BqVs z^nW+r-8efQ4PqjS*1pceqaxq}bpQxZj|6mJ4`N{htXWFL<4`w#ym=Q-U)8T487#}R z)W_DrRL!Ey;=D0+xC7kFPivWTGWsOHk64z)B=8`gKc7ur)C9s8fp5q5Lorg4(L((z z81mQyzr8dx3BI|E>+gq0T#dkI4;?`CC{B>LeF8jknw(FPs!pYE#DWKwp& zIWqp@P8ES|L{35G-*2Whj`yc0NZVplHZX)H(ug98BRHp8sn$U=SdprcAf)-(!-b=S ziFA?fHx^2CJD5|S%%e_YkG&2@Dukcc<+yuqEGP5YZhy~$t=ZC&aEl3tWCy(F7(Q^@ zGbS4FT;^*428%-}8lv3J;&;r7JG9K(x&8?5WLWGQaDgjfDcXcT-Xl zoiZDKkQf&wxr}r;2M_T;cu7YmVe)e3JhIl&axoBS=VvB9)ADFwWlI%1+!RD9N=TKq zjDer9;MwqV9r}%F@dKrij!ztqMu&$@>@i|FK~Rmb_cpv87Dk0QaOl@GF*FqJV%7e{ zL)fi*>HnSe{Nk7B6Pn=;Z@=MpJ~^6_ot*<(@k|6Eqn3zvLpWWs{@rWrl>f8_`VTr( zRCCIoWo3A4YPB_sN8V-X2rDxrP|^~n!Vztn*}jzKc$*Su|7t9>pUks+XCK$pnQ0zS z+zSz~UFlP93%x_f6tx+R*=7q*mzlO^Y>arO@e^$CujvwQuC4>saa=&YZO8Sy1vZwx z<-QL#W)*4{etpcXU=~JW6nr|iD)Z){eWUqfQpqxz8=4EwG$c(~q}7O&Y5 z1x2QE;E@BlCc9!%qy*+U#|m=&_e@53lkOE!xP2@>n{_r$${>#TjZ$?vmZAm^R@hhx2 za^uZAq~;WZi$YnA%|i?s{Ks z9?mz5-n%KDAO_=QgU4bF^{xA9*38hp9EoT~R~pOSGsZ=`QWAjok)fu4 z-H|6r>^_ujv^Vd6bysLGNbvHWy!k>d5tduUc7STKdh3C8x_{@SDNRYA#rb`@$l{IH zCgX4Qp4%*tE5pFNhI#amUj)s?RC=-d^XJb`cwT?(_!(r(c2NY;Ss7CQOmUw`J=i|Z z72>0#6jRn8E1^ei3nXf3m2@w_egtdbxkaL%AC0EvZxASiza&+?cZr;{{mK!@4G zYre7+{xn%ToOm%u(Wc+V4u`0JB~^HB95fux>OVi9=_)#9S|m;HUnwpuG}6_z+^lR` zw<~})Ry`;NgjhSrTbe@H(M66GHsg^SWpmwRY@D2&1qB5YC?q*T(s+&kps&0TTp{Eb z89x>LScCr?1ctgTc1B(odUr1K6$yP1#`ae9^3vCzwFKvwzCJ}RzmkzrU@aK_d{-Iq z5RDga$AEWoLY8XKHMKL`e5y? zXT2?=}zr;8};H4b3YN(#20t`1%c+U}g4E^yDBwc@Jacw~yI3(%Qq7t-Ok zpmDXwXfVVMmEVfuir?O!d_HPNc%gL4>L}vcf2yz;c?7nyUM(|Y>LT~hNXN%TSs(76 zm^srHHZ@Ht+!p_5!(2#dYN$p9hPIHxw zu2$Ud>&|Ce&}!^CehfylmFmA}&-0j}HvklMjsq9uNBFsnYIT}%J`!)RV_dt<&>UMXF*L;r=| z>$E~hXfL2&gUn61Ru?@=@}rQdA|P*PpG5oNDcE~w!oM4I=w?-z7yddU?~2v(fYBt= zjIsn3Wu(QLaiG_VlEokn`&$DxPmyeTo$tay6K6tBu)hZNGo)Acok% zEQmG8rHMs9F3vDd@DX&hHjRa<;|nS-8z`mq{-g199)(y(y;A>M~3F#CSqN zDb{ZcMAvKed~VE)93Ll$N%R6qQPO zq*_vNvrTD-UQed(+m2TpwoCUz-FA8&0mV!(gVRj>b&H{Gjm}!qS0tW;Br?+WF>zG7 zI~8MzhNs>4cJ_utpUqWhFY06(_Vy>`dV0K0N4-v8xVi1$7zuC)GDcHkt8TV^XJw<% z*<{|3Y}J=*3vY@*1OCk)#@$PV3CwYCd61eWR#rbJIEUX_+RyDNO71(NuC2f6I`5h1 z-@AYPCL&HQa%5EJuC^d<#hq^Rxet>S86VKr^6MiE5!5i)Mr|e=joHEU8{H#UTndwK zp+PQv)G~8~v-|M~stb!g$~F{6@ALk(3%Qs)TWYEh=&qqnWWA=|upQIuv0)E^J+;oOk=p^HPeIXkz5vEz(2{?B zWuWTu<=fm>`SDj*LwXQym38-N3F}gO=;&JS@-miZ_7<7ET2>zEK(&-yFWD9s7bz(- z31{mnb!r@MzGN$v)>{tmOpAGLuz~ZcmB1F^k#POrS#4r(RWLCAhjf-rF(mS>Rt#ev z8^n(Ej8)0}@Grj2hKHa2CL!%E;){D0f|T{1%6%6a20fDKb0&W>!W2oT99M9>`su|~ zL+NsC&6Z22`fJ;=XoG(Osiw1(F2kZ0-vjhtqK(>}=VwdL*=mkoZs-J#Y9VepI9zdc zGlw35-}O71^^4$#XyEMc1#z5+@Gw$u)H0$eOU|0tF~hCx9R#MQ)GgeaSd0aj>Ta@| z{M-g#uj&5lrLyP`%>hrI^h{rOPF{GN!@g8dF>{Ytk`0F{V@MM_n09(ze}rIEzr@m&`t;udyer!BjRH<}d=h{@3neyC-^FIb zy+Yx+ejJ=zmFZ2|d348iCD8e0yrxc*ifR@gOX>TB9F~AMrl1I-`Ae80OR;QJvC*;q z{RFoI%SMuUoXp*IOkfvVvZPF}f85a-ynu>sbl>}dx{*--9Y8P&QdTCG;b>>EOK=C- z>%KIY@^wjhL6c`{Jm*~`_sX7pO(%_y(b;6dQ3;c6bs~Y^7&0Kh(*+myd20Rdg+DZ#q=#78=rO z5`H@Z`-?@HlM*O-YSM2mVubE{ruE|EU;X5WZ|PBYYqt5Cv%sQ^IrvA7zk6dMS4vHZ z8x}@J$(|>g{xn3Hjkv8N%NP<@e4{a6wf>hbbzxePqB%OQLq_I9)GHNlD>TyX#vdGU zoVX#aHy`9t?{pTPo05_0-N$cgqL8mrNs;u2iUMt_lq@A>_W%zSS7hyrfM5@Y$}pP1 zr>|LyjU71Fic(*Eu#X$Kb%zilrg0}6@fCu41~ zk2u_aD5o6ftBGw8xAnKGhGQwgfUr24EiZLS3447#3Y-ql&tFUhPFMX7HW;7%zZ#Bp zu&%5(^QUXp1Pim0(d_d@2!gyHdNAWP+g#%H*n@`+(1I)lh@}N2BE5f(Cia3v^)=_S zClV5!wGr6`un^4^%pbNm9ar!=UVxym)zJpEQo-IGC5^T!n`zf<<=!NILJ4Dy*y)K0 zEu9vMQVi>j$g=wS6}_`hMJ?-&mbEyX)z#I}P9O3LdJy=j5N5=j!nhzU_H@V-0}D^> znlf|gt}6|N8}Aa+MKi3wXypx7vT)JBu-*P2#*)7i2#B8A<8zkLu#=R2PcO|27KgV1 ze&K`#y*1d%{mtpd%0*VcQ#c_dYgP5dH3%-rT0W1+Aev_Xeo0Z`Pp4N*Z3sf(GofLR zu09hQNl+-z*~y7<<9g1&Kfervjkz)$^K?o+pwDIRadvmb#*Y~RZJFC$fBcW_%lp0Sl$M;Y{R9h zWkBAi;cvI9-doJ5$^ZJox>!Mz1uojDsRl6yC2+8q-~6ZrS%Hs22jgP4PD!LRsJv`LB z^E;$s)B5?SLA~h3^*hTt6*k#z>8GyIneR@@Efzbom2dhgD{5(Jsd8!u6126o4Pn;4 zMSh=e37WWW@~4Wgxj_|Ybwz(-WETCeF^GpGg;JJrJVvP%6y3DwAMw&A z>erSo1~~z9E3EGDck$g6thzl!VJM#*S%kkh@ZfjB3%KZP!zrqwlmQ%Je;*AGga4gc z-b>GyoTSDM4!b=Sv!UphNWV9>1cCe7MBFg0FsSJvD`fMyQ~i@5XAg|u{YteGRr~*P z0oeX2=P{cA%14}%YwGD0dMJW-&HlMg-GohrcEQLvc4!3Jn{S&NYV~Z45r_~I%{LH< z&Gt18;D6W&Rn9idtUA<8Pk4o05n8!%?bH)GS1W|X=gLgOFVG1}`e%5+3IN zu1lZXh4V&BZPjV^XW@TMnwR07!;)Q9sL7zJBOWZ;GKPk_AT{H+p8?uw#PxqveRWtA zTK6>uDu{}Rlys-U&@J6v(t-ohNVlkzv^0oxNh>KJpdt;@Ag!dtfONyR$9v!F@8h}u z-RE)O%sD&OT6^u#gv(|jzG2d)?D#U3T^|vq(Tx_gM(rCranNuJ8lQ~0H5^v%-8J%t zj-~!==j_yL+TPI%`!zsZq0OiJt)h71xtA=k-+ugf%n4$)3wzV0LD)(8PmelST5D@9 z^nE|r8+TydxKViZpl=5gMneWJznPbSaf=hSYVVm_Y465uq*Jg{MLD}*%K5_9gX?SY*q0= zy02dC;`wu<FWkz38`k^>@`i`^v*^=TPg&3tTHqDTHiO=JU z{kM=dqvtRzjh8FH7P@_1L!kyKC~|k}$6Q-?W##n2@<>6KdG`y%p_-9V159{(HJ+d# zauRy7Aze>hMT09LRjgi|MFO4Mx^ zHa!VOjE(1uq=i=m`Sio!OF94PYJLn9J&zte3NXU7U?z_woJ)pfX$)RRz#ecJVPW9@ zpWCGQ%@9E{x0Z}gQy_A)O;gAG9T%lP(2q`?>X3R;8zoy>^Xwy9(Om{X*JCS!4&TUJ z^~A48F5C+ecyiH$v$XUrU5L2bWyxPZvmBH(c^oI@nc2fIE0#}QXula3NdlYU;b_m( zU2C_=oa)m=OZ>pQU{+%@UBxzk({a;s;bDPw&a&>x3cyoCR`o+xY_-fUg>GK_`Q-8A z^lF{%Z>*hb+wP8d*NJ`{#7bx(hJBlyiQ~<3K6GK%rQl|Y+=u=Gimml028{R}?R-4d zokJ6Yu|C8%ECPqE)t#LZ@DWDJCzxgz#Z;eel@=De)EN*{`0ft2f1S(tzqaWR0v*>&Q^JeS7nLfgBJJ zN9nM!x?{fqO3G^V7z+B(43Y0CiJh_<9{vVmqT?7WJfJla*1?Jd*p02{5;PrBy9*Ppzhyh7SK?;609j7l9IHW(UzW_}zisgu>DX7HQ=(3Pg2y(Vb{ z%ScCRa*A+CYV=KFBabw$b5%Op>R(2}Ae4rdR?dbg#ugnpwXdsC9V;+bQWdt#4-o2I>2_X@c&V_+MjN zY^9hQg$i+!Hvhgh5QY>m128%>wB&0|@Q7wcaGm37LDK7h{2N;8Uk2G4p1%FwCc{IF zlRbDJuYKv(Yp&LbZj1SId$u(g@Mx(G}^^ut&Aq_jC~s zNhM80n2(R|(-zFisBk93dXRuoRw)yagLaj>AD40)_rEfPa9qoxJjzg@m2pZi(wStu zg>&f+*>xYIjiKa<5G0_`=$K^U)Pm7N@#~lBR9;R#dP9Jl0CYPWYipzt)BTCfrj~YA zUk1wD`}7{LHfyU(S$p=PFqq~A-dDO!M3oIGih=2V%N`p6RE-ky=B~_|DPdnea6uTt z2HEDnRT|^FrHw1Py5C?rz~u2M#Yv^M-WOKgF4iJtC>C;kZr#FSl6dr1UvW@q^G|r9 z=b^rpz(MlzITZ}r)q2s~lFs@$yMrxJ_qEdx$=c|GXf=v0jgec~nz?=Z_JH1FS~!eT z6iX@aNn5Z`^TQJ=l3;^7cQhKSYQTS(Vz9}3GbYUd4)C#kqv6S9s3yEStLu27&Ghv2 zWyS#LFT1V%_6#-}zv)a}OigU)iHDWwjgi?iKxse4B!z_`Z`ye^B~ zA|dac0wB%P%Z#_i@NPI^3>{k8gF5sM$tCr!g4{pr$BCn%&2w+Iju6wiy~{kHASR>o z{wQiU*}g${yb|M+%ikG;jQqqD$?zKgp_AemHU{ZO0@mk;Iy!KwS#QI=IZzm2zzq*) zm=L|@2X~5Qw0TNr7)#ealz5bha zBZ@VYC^+Q(&B~a>D<;f}iUD$fP=0BmI5@SslVHN!-PNryfBC5#Ui;iZ=mGgvm(}LQ zAj|_=U7j>T9s1Ap=4h;=gO}u*eDy~p~_~}DRKQ9;edeT<(>v(#OQyP+Z zJaYzhlsGx)6b>Fp8?%3(kGavJH1^B&UfBZ+{Smt<4tScbBB z{eZ5)wCNZIQ*w9iZ%3ANH~hMFF~YOWd@)>CFa%J%(W9c)6@aQwMQ7mv&DiiKl^KQclsIT`MlTK;4{Z0BJy<^d`Qo zojA~BnII=@=jGzJm?(E60(MN>H8jb$vb?fJ$_>h)t@j- zh_h@$u5l{ho~~-)f{-j_W98}yra-g*jQHx`Un{Aae|y8LBHKZ>H~cs~!iumXCx z?@ft```nO~`CPgPnsBqCfZ`iBbL2a=0C|?BVFy>F`_E`T((b+9oRMiE$j6N_ld+8g z#OeG#hub&EJ^ZU&Ku!TFJ9Vcw21DS!V3cRf0{#fD$x2jbH-DkXejEgikB1iSQw2dm zn|lAg84A0z48HC=TdoJjkV44Fm~OEF!!bxPU{wia%SEv(J9~ROJGW^$n#ydln%++> zRg9xZ(nvO$@v-}+j390-l?Ma_x}MXozL2eceNy9~Np^UmX4@e~>MmX|lqisQ@zpcX zsrvwb_tAE2KEeExzwmGv^R#-j9-_t&%U;nttuC+?ba@}K?S#%H(byY)I5p!R-`$F_LZmu_AB8Fg}Gsh>Qgls<4{4AaIZ7b#ni;Z>+z z(zWmdq$Ax6YlpNUGrxZiy|*+AV($!#h#)9X&b>#JebVt9EoOpE6#pg{e9ew`3J@Wl zn0O!4JjW6kY`2)DVM1s=4;qe1mV%pu_5t!5F@7oe5WRaG*jnHe%c zgEljVa7IK|s9JDtapFkGE8y^+CB0T0+KKIwq@GXJtpy6$cbRTfiS2Dn-vnHzIY7P2 zlDo{e&~TN<8`9xFw7b52r5+X)?8BZIE#IrGgcp=e+1v%MW%uHFvF29W*WQHfvgB6w zDoN4rheryDYh!09wO0mJW6=d0)_bB>hdI9&nKtLSpmKxi&#t;BFmJ%d^#j^yPu6wd zV;SPiHOn~*R(>LdnAlEze$vX7CQgC>NQDK{|!$&Q=#JjpnxV2VCU5j2TmVHS{l z{7Jnw4ot)v?AuX}mhUhU=fDp1=^FpoFlxMt&A7o}KEv?=!@$T$-n${Ya=Ei;1k0_^ z=G}_wI>VBM++1SaQ|PI=%$O#RWg0?}v_XP`8WFyxx~_SxF^jMKH`X3q?3?zmIE9G;DrRCW>L*Ae#)0is!*o?eu^N8T>tG(dc76$dFIPb@Z1|6 zx8+H;8xc*PV2o*=$N}kQ*m|MLty{N#{=Uu8M4tz^i>5bB>YkZ%lqN z=x=C2M^WI1u!wEv&57-zo&V4^WCFZ_hE~$B2go(^**RSNzm^6^F$RZw6QxBj2ovY* z1dp8Q)T(}YwQ}_#(I07|Cifebr)(Z;LczuZ^mG!xoDx7R1AZYE<(DY`0C8v)m;T6< zLo59drf5yQa@GVRCwJv51dGI#4L7&Fi|4_NwYrm=a|ZE8#rym|rI~JL_#Zs8;Pa2T zhKIe=lPQk8sMbevdCA@clS_`1M4a-pcx*~aq0U zq?d2+R>x)h))qEKsB>`z>mpS4 zw_OBfRVaH2adNp$EejTM>23SPUr>@l&0C)OLIq*v%!l;T7JmL|cvu@XasiX$(-u76 zd>iwSX44dzh>Pc+16N+_Bg((9^+)N3eVVC3*)1QVrK6v$6kAo{yl~NMW}^@AvR_)y z?&7~wmd3rPS9CDtwLav|f$@aq|Gz@W%M5hUNE?H0VvCq$N``)gc187Y$E|d6mn99A#bv_9Y`?~R>Fhd21F@*n;$Ji2DDLA(D z%0eZ(T(Qt183i&W$*CIzn!N0L;-eldNz%fFZw@6~x43%rj#+Yabk}ui>5GuCqGc`K zM0>2yG!rVH=(*lnMpkTtDwN-80mpU)w7UJ+Z1cYbx-oiKMsj*5IG zqN`KF6{?E2*N`+(vZ+r63n8|s(cZ#Bh=}1)D1nsJ)Sd5uo}s}@IqV8QpPC+?+{Ogv z#)JogL#&0NLJ`Uta$o7w<&;sI;e*zR$I+mbSw_cP?UBH1mI3k7GBQr?DJ?2BYt)c} zv7g^49P+Fvhne>rp{s7Ys|#%U79;N1cFz_gk4}=SZ4UG_VjAlN%VWd3&Bw>5PMy;1 zv&M_f5&~KNx0|nN2Mj zmz5B9$&@R%l2Mk5f+;CKS}s}8*2NzYPwVcK26P57<206=dBO+pE`aQ|^TfK!K_V}q zfb#p#t1QhQ zUXfjLcb29nN#koc;-9pvhJUplw>Jt2tBs_uy0`{RKNuSyuQa@hq54<67Lblu62J3? zi>G9HEw)|hRYsqCw3iCXFD*Pf2rHT{{s;mcdEx2Bfv(VbXzY3^x2t@p)vg41F`w&S?DHwV*I233w|CVMobsTKarFb12gC zq~l?4;-@Xr*7_y~CPAG+#{HK$mV6O)pzrgbh&OZd6dEgHFa+X-hYTnVUU3cp4t_tuc#s~cguu3Okv__o5Kp5}hPqGLa|0kq*-cuFtSjT@ov2dL< zq!Ytc7y0Oq%O>d6U)hGu?Q)6`mNe<7ve8>C zzK@N)9$7qt8g@$R@%@x80Hkf!?AY1!-TIT|fn24r z5=@NPzkn}hdWl+K|MkqL+c)T}E?C|S`T|89=8Y&^1RaM&+s=ou=LfPD(w7Y+nu{8*w*HtnN^d6LQfboUSLc@J^&or&37)Ox{0)g4;ZwX@RJ24OC=y$&bmI=6)?gS+VL__7_F%;QP5>Gv4i= z9*CEUN8sB=^$X%Solq=o^@h#lWlC)vipoX($}c?IcswV%V8@dT)p}4%Xp&ZTELsm? zA;`tWg+w<)bGriJ)9X6lt;$Es>`j3I0O2K*AHwrdaj9D!*rju+#RyUM_vUE&C1HPq zN5M)kI??2So;qKyx_)`EO-tT98oyES568}|p9Q%FbW;BSY`eF8;7M>#fDqC&*n=r{ zJ6n+W-CHSYP={5(ADe>yV^_n(v7koxe8jl@ubC&t!(lak!Qdo@X~wLA@IYMCuhYV1 zIn%LST$!?vOk`hepsNlTsygEo5u>MX`x?$mFH4;d6$$tae-GVsN|?B-BPA8kvXZ1l z{=HIxpKi-pN9WS?i{RkkzP>kxEms4?J9J9*9i8KJa6=X@9D-5_#Qu3c4Oub~MQ#E+ zNzw2^xnaZ~rYvOAjK6SI2#K*02=?}6Y?x98Ii^M@RrH}wYkKlTf&rkd^=^O>Gng8v zUCad9)WmrbIyr-sx6jPmOR+NF-I*u><|Nh|a ze8t+>wrk4j8d5YFxBH(7NX0~}Q4Y2ID&m(Op6wA5R>Weov9j!Q=P2($xArhZS5XX0 z;L6dqUheLEp)N|$FKL(*!h*1I6hD7d2Ne_M+!H<_Tic$4lgsr};da%jEQ)*);~&jJ zU&nTR3ApMa;%wOu3BbI(-EMh(U8jxu**B1BrAEevp@9)zZei3G|46Zh2Vv@>;K!+M z{i-LV38QihSTEAqo#oDGdLBkIhWz{;NBWJ+KPm5>3&Q6!C93$63y6vT?xV6$ZeFDw z8>Ds6L{YRRAr8bzR3*I6y!-NyA=t&r@a7~84O8Gw3WFJ=Ls4O96?bxM*VnK99sD#_ zF#9<+2$c0l5kCZ4oY7fXU4J4;`TL1io!!x++!?;LhAN&o6~E7)KZB3%I^BH8m#yN? zMV8Ea7wO5MZAx5{D1*L55BYv|+r2-e^U32Lb7MBA59Kkt1bX;1J@ibE13?Fbbow0~ z-EXs2@*Hl*=g*=_ii-H2RO!YLdSLNWeE`^JjthzI0oPx$c*gu+@P}~>+0L% zm|k_QgJo5h{L1txtn5X9?SSGVTn95LYRUwjUIp2M_-+)hW=JO&FYnRGQ-Dri*U6UV zc0~(7v+zYnhn1#>wj*n!i_>#kT}T8xbEGB-FN&Mou2Rlrz)jByAOELrdHdo&@XCUP zoB`{$@8>r%OMbzHCHi^J{m&5D$cpN{x869WLmlYB;C{H7l2E|;j@%trEB-*4;vsQ(2hfZRSwVUA2LqYcF06d}hycJ7Eu+)4g2qNseC&DVtyp`AjS?BJ zRyjEdLg8z4A6#L}Jcca?SH474@yvfINFi4dF^UXjjfY0huDY(UP=Trq!Bk$<^@kuz zw{7mtF{MI7x-O6OO$b;Zz=#)ljFy>!>ug9pte`!hP5-_#9hK-!5~4e-TN}F z5H)ADp3B3~&6v;~LS0q}Kz~$0uz4aoE{-462EQ>uJY?j|Bs||=T1!kATjPq-qeX-{ zD5Oi9tROGBH*_w>Ojdv@4AwPU){$bUcB=mRpD)FyRqBGI6v@sHUp4ni64dB<&jq+L zCH3Q(ng$1(F|#B#b9c>>8I^+A&-6Xx>hRB< z{)J@4AwnEx#rxKiWjSvb>*oDRHW@P+vBjO;_X|q2F+H`v3lIlTxT5nu=ij`q&-~@? zV2#3T!3r`=dWYpT3J)vFOSF|K$;0gHSEHWKgZCcU74ot+cK=TBHQDcMWcM!n{QJFU zQ|mJE3Idebx;7?VtW0cl{;$+3ohr@4>d%}tcU=eD=Xy>+By!Z{00cKI^eE&1Co0K$ zaO~@YkFfGLI**ioMyJ^yw`1C!x7%()-GVK%^4rt$HaBO_Pgqn^sxx1mYBowCeE18L zt-kl_xCui0MB++RV4!XFvR{QA{x6hPj3ow}18D+cFvmyU91_l!1%N%{p)j-!#?}FD zMEO&}RYO0Y*nCAc-BDD0drBtQ)6&{nVn9qntVR|Qq+1H91=Rm~w})SITdOi$NPqkv zCHX8+^SUxKOXu>MKYK;H5<4igyjP0&NZXIE&ATd>abi89-D*jAN{A$FM9j7ZDF6kC$q(YWiONnC?x7GjiYuU>$nxem%Gh;{m@PAi`*!X3F<=$=AuPEjy1VHk zFugYk4}+&^deTsmmg{1}=39l|d@s1bl-}LkA>YcAxqeNt6Y(Pu4IspFHTa~GN z>Hgy1*oJyr?9ZWoip+Srjfc9zK4c-}afqt$GLTm&QBkTbo_cuZlus3?Tb7uwyKlm) zXs$S@P|VpsMH6IZFO#B}iq2R!Jx#iHZO74?{O*m}4fm2|c$gw)#ckEq_6+`DE9|kg z!1mzXLj*_6D6wTb&iqY<4#M(B@4th1TZ&7T(GbeOY94!Se!E~?n3ELsoO{XjyZKLT z(YGt~V~3z`7Tg1&*}@j=`l4oVNUKG`w65_xwktbU7xu(8)_DP)Gk8Ch@(T0~_){Si zcJ{ERi(fy-jur6V%`1-zntmNnhM2Mv)H#|ll2fq#K%~pgv**4c5W^+UlraG@px3qf?Gnqlv?RxIxv&CO2nUUT4Qnrrf|}D%NeO$j67Y@Kb<1+? z3_NC?5`&xmzkd8kGvyG&Z+=m9E<}%&AUQFSu`T}wxGHpuS0#%+)z&){z=1@HNcuZ!XQxXzf zZ*)L=aT&Qe2TEKZP-*JgZFtU}oSm{pQbe|v8rH?ni_vDNzU0A_Gv!GJp{}L=wM!D< zhHq<&`siW#FD=mA=*6GM=gi07#C zUGhTeSXVlsndAs zG-aL9x&6BhPXGynEG^!0j4yxR$Vj!zxNzD*qX;Jg@!};8vPczOuBLynKd&OZqp778 z7r%1u8P4Cvk_0kod&7-fd@*8Xm;`F@H8S_ZkH|MRe|J`6a$pO5Z`X_EB59@^>v->x zuoeo@^}G{Z3b-auAg{u3TSc+xMD==$YrOM(nKHdrTpM(jI+~h{>yOxp&@u+hs|0U_ zm~6MBQ`9{W-QTKs0;rTYnOHah)1PuPW+&40B~;NL*OsS*%|FZrHS0o-{#jfnzruk8 z9~=Af^WCQ1^C@&ij-x8#d*h&Yehc;6JvQ%)922o6W8!t-^z^E29BqlO%N%jZDOM?eAy1p~mhDNssRud~}D!4&G__<^|$I?XntEAhFid zsnHpo8(gnt#>*JB-VZnZj; zjr6e*bcWM0mcfu-mQksrwz-qF_4}_P7UCJbyp21>0GX)FpR#t6qgFNTmMrY7)ZHiG ztqh#`(dQuX7bX>(Q-tdP{%dfKmVO23D3ASUwBt-1s6H1(((C|)05^dwGO~E4n9hFq zV3>B(YJkO=nT&x=I-B@{aAES4Q)&yBtQG8yc0a8dF6JtxtqMC(Q#|$`O@~VZ3E%RZ zWZh&$h5|t8wLR2|9H690> z^GoDauwAaUR?p<2mKA-lVdhDHaHD7%mW_xr?H!NStm#Najv{?(v%gZ?*1pKWXJ4)5~E zdouPg2^Q1@8a9|ieKNhV@g980#a}i5GXdPl;1UiiA%ulM@#OQr-`2+ zg(gPj#<#O5PAr;3ZtLB>gi-eVzn%&o%XZAdoIUIFyJH@*g-7P09%c|#;CkP)g-M$6 za#5@%_N#hd&{gZNK-E@P1W&1n^Qk%XR@<@%OPNlH{$J{%<1c+W;3sR-T7 z?E2tf`~8)Vg&!^gD))ee#IiDvs|2h?Fx-@a8B+zO6_KmsaEx$0!z36q0-An;708Lh z6{=SCW*PE{dcow=JMm^_TP!f&Z|&n_u5}9}6rdd+yDFvw_8GsurpE`S$W_jQbbNh% zYmH}trM31EwzXy_66)=XT0?9uKZBczZuLCI#?;A!&~sLMFgTIvuKi0xh4LN5EHKDo z+vY*Xs$Wqw#9x1G`z;=b9{;?tyqCt&EQP&Z2viye)lieaJ>`|Y2Z}G7{jEnz!qGqZ zuZJbs;`kk?^R5OZ-P6&yH$Z)@D$CYqIX{of;3~%4UrXEcn;cQeo$VM>LAq6Q%a!h4 zUUjS5<)g)!$fE^!O-rk?9r>-Dc&B}O^5jzqBs6em_#LBS?i=qeR3gMA zR}bXN0ruXQ;9A>LM1qZU2tll+jZN3SBpeI&qpQv{AEwb}emh|I6}@q@AN35PStPTF z1>l+|NOVbbk*SAN&PfACv7PD%4lHDXUKbvLfvccU>e1Mkg^KJ4m;i>E9XD=nmuze{ zCC54g8CXgg`|THXJvbFLa21AKQrB9=57l4d%%N|S}3Us6@E$8i?ttDlASnJbqjwa>LDKJK2ffEZa|8OfT z>6uuBsROGB^up-8da|a(SP0|bzBV{@TA7=BH|^ehIvu<~kBY2E*4EYy2?;u&27pp~ zi5@>xfG8V1PK#ZCQ47j-BOQH~I{4;_H%!yrK?ICe?={x4LcJi7fD!U{TZSqvUa)v6 z2Bi-ae9hdD`2<{76IaoKE8qv-year7%_Ot9tH+a@8^|klum{=sn$2{h)v^qfQuZA4%)^IdQ zM&1J(o(5OfVFV~{=4%B`KY7Oul0GqQGz$Mm)0aC%jrj~p7&U%AX_6M&W>C+!S=Dg9 zq`U$h#q)^k`Qp+weUC}1J6(W+v8!IR_aK3(MuCq;^KPBX%gcA{f&X5#ReQywCrI)F zk>3CHtEAX6624lCb6`Dtr|g{6xN0wPqW&+$HKBzftFo0)ce$l?`Hw-<;VVN$ZDsel4(`- zQ;}lFAJ-j|j<6c2Rr+XTG_^ZlF*zjNO|$1|HKRXz#Pea&Yit|_)+~4Ofy>RICXUH} z$?_HE9DDov;2T+Au(Uq%P4yXuIl?(M)=tl{v9ib$vFm+LGr{v?0gzvkdzV7gAgNo3 zo&vU6ZqjrK-5T(72T?2`QxXNlE5~)VXplFjjvT&)@ z)aF)v#6_Yzj33(VAKD8vkLX0BD8nL*a>LF+e*VFj5DCx=@DtZ^#eIJGwy1~{{?Ctt z)6=J;K4@vXK+5?1GS)?8UK8N5jdW|pQz@t zK9u%{r)cA%- z8~igG1)dvq22v@zvR7Ljd_F%kHm3M99Q9Dw6&})c%SWS9?8MR6^VDJns2(Y&FZ|orQ3T0s}9N>Z;WwDZBr;!{DC=6& zhxq|^Mdf(4`|#F4HdEtSA@k?Q$?;%cqDa90Te zir~@-BRU)H=Y7Pxn9;d-^kw?QFlZ!MTRyiYe<|b3kJyI_*t2WvRi(gjiHwq8A zqdVhz?VTbg8#=9Ayo44f*Z5Y>fr+M@MVlZO^8JHdF0Oa1cg|3VQFq#zy(7P@tmm;3 zk38$AmYxhgU|pf1beux1iMT1Bl1fMgct_qurl;)ew2qDIP!Q(cGn2Y^JzMJ1aC=+! z&vTSpf1@JC-oijf3{p)iwNl0?eMRpmi=Q-=dpmAiU`JdF1SL-52J1gP%S$GMb|Boo7KfMXX-C zh8RdVety6InsCyqxL^jlf#I>&k~UI6%9CC9l8_L00Bbi&+$$H)kCJ2G+~k1W?n^)A zJ9Sy(4YjSqo1+hN5YJ!H7;FVRe*fTlRh9YDRZ6Ut1-FnTg;#GXvXL)7rw>j`K}`h{ zPRn+eF)TVhuX6o+RaD!H;b4;M}%tayPvegVSyov4j+6oY(xkZF{GJ<689n ztUlJecPGNPR#;++lA`vy@sF~c}<|_Vnwjn!*lnLruoG>sv`4UB=xkgv8 zH9k$?BWsCB+Wn3iv`8(t#!)EmJkCRqM$ZLXdJW$}XJlP7*7 z#tEW%#g*J~*~)fycRR~`4~I&ZcRayO!}mH#X!H5!pUzG{-+<4ppP89CT5l9x5`Jqb zgm=^EmG8;)={VYXdAc@EU0nlKWxO9B9~(+MP4n7@3Hq41Gh!BS!;!nt@J!O$D7Uc6A} zuC^V;+{7LdVdo$~`n1uQ>%z^@=5MZU6gJjbj#+^J$%r2IH6G6~wEMV=-z0tx3Sdo5 z*=9j_^C35O0(!y}wHJ^wt!@H>OfB@6>Wz}3RL(23GVDe3qyIeK8p&EX^}V$#K6EnMTzUv;`a#WEX_hV!>H;hJVSMpSh@E`>&|?& zJt?;gQK)rarq9(DkuucqKGNW-07Xnf!d|QKLCBDm()>B^@MdbQz@G_hxFKl* zy69XEZ)#p0q2T`k=#<4tyCfbmrjaQho&9Dn|KruOQ)BU$8JRB*_^`E$MhFQBOFg2h z`6CuRevZiJnIH`spZZwdS?Tepu7jnV-3|)FDS~@EypMlauyNb+5@n}OK;<0A8OVkhos&1q|Fi&q63>0}^jN80p(knPZgi%nP*+t#tdc9GaL5zGRq>j`3_qTQJDRF;aK5xzA3$lAUqT_=e-_w}1 zQ)jThjq9F(M19uddmO1*;QS!oj7WNW2sAHz5n1Y&9p4p)gXhl&>1Ev{J`KdQ(F$n@ z&ZVZ$RXnh-Y{#>wZZh9n`0m+9I&F=tc$tpQ=^H`oQ@4}EJf>#V7FjfvgnH6eS7Rxp z7%Z%9wW!(?4u&-fRY4!qXMukb7_p@A&H#vvwiHW1H&Iz++2$M8oj(mm6Apk+j|hjkdOtqy|pIyd}Y&aZDkehIc}Xb04su$4#O|P z(qjA-WLfi8(Dn8_q|wSsmU~@$yIcrb?gP2x;A+E@Iax8WbIpP!^xSUkQ@!bs8e^Df z_(%Jw#@=v{2fuNvOA~eebtBDt^G~8ceFW@st#}Vfk8AEHMT_O2usf0J({8YKu0!y- zV(!zFE_d1&0>sa}&iyy>fbr@k!FpHj_69%y9cIyDj~@+45myBx`D*$vy*WW(Y6uHr zDA95J`s#GrvY|+Bp9RrE>K##sV?x7%{Cu_T;m+GDJ8guvzp!?w+vnxEkj;@zTC3^Effl$ll0&qOgbyWrLqW?+AF7suvHceEY^rtSikLOBl(e-`4sQO*;^#XX^|6HdMCJIh;gx|u*@ zUmrJv%$W}f2?2k52Gq4{9rHp3*`4Gswn@y|T6L2a_4ISh*>8#q2nd1$*7yWz59Z19 z`wMVDk96bBM(ew~L0vGi5_cekB&j#*d9C>6RI2e8EFO1RR9^4xU8Y;_g+=6=2MTeu zfOVIZYgpyBJ1Pe?Ej@YrE@xH!(R*2?-Z~+K`1=pam{3!D6W%Krb-F|h&qaP-Fx9P2 zDo+AW{6T!&ff@xy+4cYKR5}5PpUX@IQC+dgrdA!9D!Zu4!eY#kYWHvum%fJQlebVR zd1=a-d%8I^vo+tXut+X3d%$Py&9CLc(gyhrqsEi*#uFJ8 zk^C>~eGl2$acB-_AnDCUU1@$PA*4%O-MYooT0iI5o~J*v6b-fmm-Y2IY3a%(3y0R; zkMDg)k+xog$8?`Ebw8kE8}^TvmYVANL8(DB<8h5IMY%5>rhQSat;A0|?hEzo?d&N8 z2*tymmwPn^jL|pgZpAuy2`Pn#Gp{p9?FI%uLZJ#HkGw@LnmvRaoUS~T4eb}(abS?# z*~KNlh8RN?P^f?JS$cfkGNu{j3hR_|fik_@z$FR(fX{ONuO^h_%xkLVEUT6Q3uoRb zU4-rEUpHo%P^g#+J+kIPvjz*UTDNJDq-y*$3;Vo%a!)#Sw6~U!8#YiR30eAFZ>h+))H*GGuBwXNEnxTi{I0sj!`_Lr)#3F1kB{R@Cxz}x;*`=b^T$in z*6Q>jTLiTkvf~-kPOE3h4r_hLA`}%^n`us|le!em%&y0qZEbDYPdC(i0x--<60Xjw zqw!o*e9&#fboj*RnLzC=_F0FrEQ#fD86YWbZHsHi&taJTpXQVJ+2XB}D^Q*1dh2h_ z#%s5AE73E?#FRtXa0Qk$M;(qF=e9_Pm@(AU)Ib51>ry$tHl?*AT(>b^XK%cJ=#oDK z-6#IIXRK`dZy{g!sM9y-*4#TvcH_W1v$b(M=N^-fwHj$FQ&cn)GxOmjL+W?4%G{iY z%ofuq?2e0mV#~!m8%Q$Mr47`7LHQ+>L)k)Uxzs_5HZkcP;HBQ>Adt zMb%*?)`FrURyL-aCwD~=2=R?0L1ao&QWCfjzV&ErIDML*fvynHm6Y#)l@!J^oL3KJ z>2@3xSnee@nnkJbQDux)#my~Tzi|U?NU`nT9~}*UY~IH@-@JiI{q+(Nm&0v{gmT3^ z-)->It}vq)G;Z(gb&8gQSqd{wCs-S)J0+a{07HwVy3pk~+fli}Jh1A68aVFgk#>U>&3N+qbwU;gC2X%#EslK>XTCMXg0FmTF5#HA9U%aI}-mW|i%SK=U2tEQ}IY z@=HtCQ7igB-ffE#stZQBjwxZ@2gWKYD$wM;h9>X!U$P!!soI@kO(5nCsnRHq(oNJy z*>8c8qT*Yhz+iEW#-EFuTQ0@v&2leYVBbQoRj;m@iHTSS3q$wfR*Ha+p4E_np^`&x zoH!Ho4j;@PwFd9HF7FvCS>4H@ql?ti%0JGv6%)F43juK&YMVuoBi&)7dS*Wjf3s)3 zX2Z|rp+cb^mMDANG6dX>oYa)7AKa!6%&iN1zyG{(ajx|_?AlH+D5id z4Sr?L%-XC3ceXt_8(jltKX6V?s_)>i@R3EV7PQNil7xcm5*w7dg$aT846%cnm^EY7 zkoFe1*E(ba1b-T(JEq|DY)w1XWNW*vPk~d2<~R<<+rL)z4{dq@T5MtNvwN<^KxW(9~3NZr%$R1#=zaMgvnDk@HuBlg;&v04@-a;Lwb4mK z!@PbG@p)q6&1~Uo61d+x7k?!u6mXZdQF6mN2N=iVw z;osxA_jvzVXPvb?q0G$t?RW2|HZwD<*Unht(|+@ZdxM)%;>?FPpsbUeIH&qIFc&a2dBXUltT(JvzS-NoOi z|B`9sr(=eemnX%mHnW@~rAhrZ9^TB_Mq71u782Pa_0n=$$xP%aXE7*K%iwOK-RiwH z%9BT06#dCza$>_aZ^S&s_4@yR`=WRp*0kh5rYkj){d1lsvMotJaFDX+d`vosi-#pv ztXnhq{X3(ZqNNO4YfjkYr0zpMmOEk_)5(u^kI`0E*7wlSrHi=vlPj*X)5SvJO!~DP zCNeAGUS~y)muDUvuT5)Qs&#$R_5gG*Q|4cJ@5Ajk)R5_O=EsWcK%36y?lDX@Xq8+{ z*Eq^ZVC}kje#|v7F)>z#+tln~9yIRT%&}`VAG!0=jl0>=-%t=RoG*l4Xj!emE^0ML z+Ps32lCc%1f>6H_1597B)y*4&(u@4@k@xSbRvBw+eeK$3Jtq(Dg2B9sJMrCm$VIK09zTy^)%7 zVFBY6l5zE@}2nG_oj8F=7g z?h^7R2$lHSE&OS8#i>2JS#ABWy>iJ4)R*VU@*l;P+NyCP1 zU@LZCXL)%!6kh;}2kTV7xlmEK3CeMZ!esz$_W<=q@{7U4rPe=?5**-f0-U&gN9fHJ zl^?xw%gcFBnm%#(0L*WBO+aDgd$v`Umpv?`cMnK-j(|a&=I!3prdL&dzHD+bifHZs zUUA&+nhQT->Tfq45tLCYWeXK@o%>^DW4JSk*DGl>2XOf8X;wv*w>^5` zfL7v5R#Q_`rL7+w(^M8E=K_51bmpm6PWjqw|LrwJMb@P!_`si_IlN>PNvq}4d_trlYrQDD>e?STlalC#RI0y|+c zs?WO~7*ZS0&v{8LzY`Ij=QJ5u1>sUDXM>cXXd-#NBvEk4?eEaT6P!9F9^izshE z)pVHe6Y-bk*m* zfRhZ_2wnNEI)d3#46);Yu1#b?2Bx+baL&%Jj&PS#rIRy($f~ch(zAOpBHygj-tq{Y zF<+|$w5J(z@NcYg651%kB`6Uzkt;CLx`S7&Vu04zX8gnKs~aSMbvB(nZlZSka(Y_d zL)?t6uB=QJ9bF@c$k;X`V;(My4DaN;clYl8?(X~Y+bGhk|GsZgywdM0)0a$c_g*=G zBw+1GDAk;pLUgCc&|^r2lHds`KvMkva}tVfGIdo!1Ce%eSYer@uVYzB)|u zJbwJh{p-CZDhk$DqCe>U=1rueMq5o0zjsn=C0FLKp39p0?EB_o`*%Q@HX2pckeWdZ z0nWd9pU_Ic<+n=amVwtcPTtTYiBe2-mvol2>CgF3ZW%hs@&D@`U{;|9FXd`6}3Co9Hg%Bowq zx#{@UbzrF?U{p}0jVma~lP_202aZpB=T2D{l4ur2UPKd5H5`c;e+%|C?1U^M(+D3; zqcg+e1Sxa#+85+3E5E}3A7LiRDnhM0HrfOOXG~JEzqJ8n`ZVtOkipck=WaS7^)4IY@QL+znhKh=cN#45< z%7KLn8T|k(2e)Q?x}K-vh!NfeImYmqOT+@UPW>7IzTdPlMiDt%E&$mTbIY|#avM|K zhyKuv7qH82OIEdHowWYEc0MonJvxi}D>hFVC*2=mePhGp@6TgIxu60CoQKi;a6Qj* z%G!f%121ZHWj8OOAa48}iUZ=~oi!uV~ZMuHy)ikU+ zs$dB^Vp;(K%6OsF_iaxsy^dD^mWm01x9!>6J0IQw_z^FU2tV?bKem>PAr;*Ex(qA& zpP8lT$u`Dqm7bg+DGL3P7yWAryN_&uZRO^nq!9NF3*ExFEu)YZIMmbA1C6rUkzzhZ z`2-Uo5*9CY4#hIucvW#=cJ`6XAU6Gz@QdwxtXkF?ohIjBh6z~ z1OV1~+G3XjjBDn2s8ndnJ?bCoM5rQy5!#%jv^5m*^~?;>4~ssu+m__zZJnG!hCths zJC|jyze#U)4|4-1538kkCk#Y&rMhV0 zgx8{{`GNGwn(iwaTPx4bZ6QU4zU>`{Zkev7j6e2?zf`GyQ@gE!=j4k0I1wRKuTuxu zT=R3^Ws)Sc)8w0JrsBrXg@dm(^NOJNx9Uv$5>BYhU3n%_P zSt&EK9N;1z)lEHfhlD3`Y7QYG&z+wNc+;6oq;dT#PL{5W-n_&y$5gC#BDL-Z#X17V zm5kVx@>FuGCO&>PnSzA>@IB+~SkSIc48Yp01xMgbBh+C$X2Con7V8 zBWl9c8j0>D_8O+9!mme*j&s^-L>Yo)fsk+JC)DGx|0FehJJn2ji zsj#6oY_4tcsHn$77)HYWRLQK)*%@@*h=gYnn_lC~cHBD4Gls(+T}l0{7o{G^F0Fra{AWW_}QymmBF;+3r< z*98OPkEicR1M?I1u`w{MGPE4fV>F~2#g63bNx4$)!TckGS&NOj$gZHEfau#R$j=86$foeg zukwt7T*cJll7jA2)tKXBw}G^vWe`N>aaOd-(Da`k&WBc2RM0hCLg~=@TT-^oHj6z& zL|bb(P%dm&=e=`gB63}qKjQ_$@2*OU#5L46N&rbBH*w?t{9C(glB6%a+0RswcY3<9 z`KjXZF8irxwg8By^BuppVA zST!5baCQdZx?tZ8DJix15-La`fX3_LMaO6Z?hU;=z(d$rS(QyZ?d~=<0ogzLKMj)8 z-chq3hc}8EpdgC5kI!y@=4 zZHKK;{lNvByG>uFsx!G!{2!lIt4Nj?nY0f6{{0&`b_tO#UA<)455|1aYbF2&Btu)Z z?(7q$Ot-sTYK)+TDMKkc(cI1L7|KyTUMH5(vZ{G*4;lc6mPz*Hcv0HyH&%;ly(_!= z^x!thuZiahmZAUxO2S=0gCk!4Bq1?2K@cE%p@E@~ckiivPpx&oC9_`;xmW@by?Svdy<8qnqt%}0J80r9R5_*{0|;krXFJCoI7j;~5hRPS!m1W` z8w4S+7m*GBBM~~m9$|<5jql%5p7Bb=0tXu>PeYCyy^FWu@Y%4R6!q}RtE?t|s7Hwj z31A0|=xApGq z+uH2~N{7eaN9zl=8x|v;eY`glPl zstT0M>^<4<%rZezth%yhwzjs2ov+({AJa3wK=RSOd*w8djn#1)nP|<0=nu^5Iu5Hp8~)%8=^EK}JA+Qosxm{2 zhA*#AlfnlwT?Pj!IM&(8A=@z?I+ev}O$}D47ee04{nlHimxi*T4Xntb@;E#G1I@O5 z;ZA$F!cP#NE(Z=jn9BpE@1vAm{@d3Vw)#MXH;+H55}getdlQ=IAV3(Q8im44k7zT8 zR^WX2bR~meq{dTV@ola|y~i)OAmWCt-t@+_%ojtI2IISH?%GoUPyafW$RC3U`~HE z-SF*_Yq}UE7HXDPFJ2AcwSP#P0<9RMxb^FAklM?XaKh+Hp_4i*P{D|OUF9H=|NltJ}-F?~zjzX>E^-%^98 zXF+J)lxMz#(Xeij4f!iQ@D0 z{ps%N8~8jSuNp_FDX%nqRQ*2GAXIXz(at0wEu5TQe}d9vkp`ZxEy0rWwCqKg){b(A z0hm{sSAUl>tv@giWr#7wKmXK{II1`j?yW4L2iWM>m7Ja1_?TN)?0Knkrm@7@vRTVm z=20O+0)Lc)#2>;ZOU8)INtKd(3W^RhfUYuR13Df)AFQ-=Es;oamy{)57GC~iZrHUO zyGxfk;^P5wGKHUwm zB%GxbDBnx^!l|3XD?_RUl9^k-;yE1jtw7QU7sc86JZ~pYh_Z((6*)169Cf6I=EokY z;o)dRlhc&6+nULr8G8LbVZf3Jn7BU_DF}z%As~&_(GkkB6rvwp^9`53No^JbF+O5W zG+zl5doFrzmBwv>qtIU$?K&k8(bA)($K55iogqJEgHE_RRM>T2a#rd?%K zO2!sqA)Ha!DQB4R3vX+OsDn)y9b8D;KRk|z<`mCJ&SYnWd6l1iI%S#VzBDUD{&uUm4%H583hhR}yq@z9SorbU^e(CV= zaMrWLhcG+3y4Ea*ayACuV+{@Z#g;f$FHMIFKXQ6$DS$F16IkMbJ$fKxc-uV78B_Iu zAi_Y|)ctY!oKHf4z5fbm{yAy)nIW_u^%KEBIMNy&9I6mj|xipCvjbYMeR; zpUP^!Etp}f6MSC2J|IVvQ2i2-@o!ya zPfy1%W$F(%n=Z}|SDqQ zE>9+IqC&78U^T|zHkBG-a=8!?Z(@=w{13bymGpDLmM!XXeVRVaEp(L8!cgb=C18lHj zt_8IcWEXgzIR6aN(y$#;nNItA`c8P9J-Pd|1C zBGvml5n&RBRE94P_zr-t(B3JSNa5!6x3 zuSc#oOv7Lo{Xt!F(KrT%QP+iVDG8+P$IGa}sWiwFv8bk_O0nCE+RA}H66G8)`bRYZ zvZ0a1XGZV@75?23OGlqBNg(+IT_GbFG{OGKm>+_mGt}Y#kRLoz$9j}k@-B>PJrgeJ9d2ZZu2W>o*Z_Lx>VSA&NX`-9%@5! z6(}x!&f_Z3SsyC_)C+wdE35Zb>%CACp@fa#_Y59qZXgi>dC?c|o0$m! z->6t}!oV#X{r%N5+@eUni3$2W>YlQvaM+(!U4O~+KQpLlc-LgM4~rNo zunMXOhk*rKY@w9?-!x(%pQ8^4eAeNVH~R6y(vsb`D7i(|tvZNB2i{}wh3nCH=^`bj zhD%XNNm?4&pEhMO65AKKLbnihCYh)tqpNssL<|emle#UFQSIGI&HAxS*SBNmI4MQy<#P50bFflo71-qC zxhLcV5U`+3Bo00=K>gwO;wM$p&@d~Xu(Gx;rywm~04Aj?+eB7Q78Gajs<}K9SV+d(G|n+9I z;WUAN46hcd0oUKDk{vDBE!^t0jJY(mP)5P{A#ddGn=K$c%E2t z(D(T*B&|&1c76m>Yj8Y>>_{;cwK*htKyi)N?c{rY>;y-2AX_rmac@myks_6G@HV4C zVP5+4d+D|k9qm*+f)7i^1n!3n6WO+TojVT9hYBBC1Zch;@mcOsZIETd_b4v1*|T(O z5Z+k=_KK!R13V%?P_?=V9s9ipC^zpE?}6|}D5$9*lP;r<=Xr<3E1X90 zl)L7fE@$6~xD-24=Rd_|F8*Zcibr8~_CqU~iWo|?Yu9|CC+y0etE#Sk@AO8F4mX0H z>j=}}SQTc(g@vpPcjd3~8@BNy(CdIGz$#H2y0TPc=PQ#t&F*p)F+Iqpgg|kbe6{B7K}+&8Z8f0uU>#r;P(?8N!~4Fe!WlFKichT{+$ka z8XR&7)D|o;tw{g=LopP3uxzk-Gy8kxEs}VjZb8qLlSAY7SnWHwezR%h+KeqFR4gs& zi`b(wG6t5_6mxs1a$?L=I{W&7mIwOU>L(c)LcSBLN}-Gp^RSodu|AJb{1?Y2x9962bu%@d+Z`=FkaTDq@<)t?6tl+JIR9x zt7!;`F!TROMLks$sl}{@{1K4)9HG&{wY?dSeeH)lY44$b*h7)DPa2djUJ&$N4jUeX z|5>vM%?ngd$)Yb`F1hCQ>3ey3ffZ^unh$wTo?Ll_>n#8R-eg5{hVmGVU#rC}JdJ&x z`{nAkmk^*QZAkyTzQrVBfryWZpp%m!%o`)=+Yx&!$wuN&H75Lpt!Ljf@4keQ`bXRl z8Mo@e2w(wz6@_WDq^sUeR@AiQyea<9$3E!EiH_xFqbGtMdU8h?>9;8XZNndTf)2NT zJg%o5TD4x}Y?C`Q0_xB4(oFc+xHz^FlakcmE54nt2G%A^Lyu*Q|8VXa%Hm%VB|s}l zChIc=tyDc4O?n^_w@6dD9zn5(4kv|+KRM690CKJ?Yhebsn!RQMl3gLBH2yfE`(gHb zO1-aO*@M0f&(p3!Ftv|%&+8Z{(ww%ok@gW}WcBMog3PQXmTPZ5PlFZ$0`rz7O|F7= zDUf8Q+JTa0<-IZBe;Nh%cio`FZ)W4V+a1upx?Q2OzO8&~j#=Ahp4Xeq-n7WVI0-r| zfKUO003DfXlg>Aw_~b@9pMI-Y*_f&W!1A%BrKxH5#M5Fc8%Vj6FQa_Ywo)^$#oLom+G{y(N(>omOx09C&>N;-v;=> z)iIgZ84n2HLqVs(8Uby(b}}aZuG``*Gz{g0&giS@9a2`0@|Psn(}E=AaAfk0jr-Tu z*EW@kXN~>!OJ+!Ere_7397-GBBZ+@q(X8#m%+#r&Xu&dZ5INEC^-NAvl` zRtBIopu7bc%XI(CmY}H4&Q5sW)Wsga&0CnqO?6o-@IQ}@E$*8tV7T%Vr=(kNy>3`?yz@y{}UyPP)| zWzWkLIr2e^$^F;9&x<4=S7S>e^GXWjjFWrFR~$5fh+l3)B4N<{PLI)cz@?p3$4TN3 zj>ch9pIeI*(Cy~+xJU4i_y>iC2C|%e4Y_}F3ik(zghSaNc8sa7hrFvRUy-#LYCN4i z03m!6AxoI|BaU;-I0+5b*5p_!>-l+bF#LQMg5=#5#Nc5IsjRx?9}gq5yr~YrON#0I z@jJFvFD#_3z_k71%#-;F%HK6kFDdSB(qKo0C&Wg^d2br4%U^83@E%dRzA4!~HL+M^|OMT|>0 zwGY0OQ%}#+v*B#MZn7H$FL^DdAngWNUbR3m*D*O- z?9xlIzkQ7<6{nm39oFyCPP-A;gArk5NBjf~n0!wBdbMvs1ZK9`{}k&^igD`>&97Kp z7HY}w@4*RCD?}2HGk7TJag;6x&FekSG+r*Q>}9Ot5rFnp<*2i>L7R{Dnt+s)G*kkW zJace~*2f5+oB-DFlc_y1>_k?U;k|l1`08O-qZ;$M`AtV-=MRdnl=9aauNf5s-yU&*SI{0y2{Y5bw~(^rEW80|QssSX`V}>frit zM#vNd6aJ)vV2qCGrmob{QQZd1o^lgCN}=3e9P{$eB^&_*2FbAHWophY(bp!cCLyFE zDaU&-S0u$&QSYsp#L8wm2x1Sc?P(`O&$^zQAmMF95i>&=L9Iz~v8~lpT~CjH@b8P4GW6=(S-F32pEx}F9tM6lx zSjfavZgL9owFH8%i_c`vgmiUOpMka~`hfDG*>Xe|C5A7b!WVOzz5brz;V5&%PaJH9 zoP;1F20gaB6%|rwf&Cl-r49y=qr_Pdy*D;qu}2a8n{pvK^CW{Za+^DlSl+@VQq;-^ z=OunTKY`=(=c|1HS3kRX^QKz8bim+tm@p^zen$60Q~=8$s5!>8iU{4(pOtC}-u7ur zD%=WALK_jJwN7FbQ`uffS9W>onY?cuxDOVL2fu#J} z+QZxpt0SUjXN}_ZZ!@SEGMKz&S#d&IqZu~MJ5?=c2!mlS4f>G>B_-wT+E`>Yk|rzN z--qG`#bnA>ljAs25}r_CWSmMmcTOFPiVz~{$-I1v2hZse7vC#q{j7Yr6oa1ga4d z>r*c+M4BMbt-iL%bhuUtV4-#-g|+d_mGFTtFQg504j?g&IKe)!YdZAJ7&FH=3!SpH zvygUo7=Wp!zT+Wsxjk;m5*W~71|daNW(qaZ{s@a~Qy4fc^kX(Ij6rXtPLS`!b^kUr9 znd%xEjmp|GsAzu8;=-xl=Vd6^|5L1>>9Vu1uzHHCP;FKR&wTB@1>Oztddth2K@b#T z#1;i512K0|@E^C^CpQkI8Y=-sLK+d~1K+2>;!y74)9)egF4$6{T93*M*NegF+`So( zon9w9lk7i8H_|5rF~QDtpFgn$v3-!KWV_n814Pt9pUiw_-NIXzUie~bB7ZOm5>Ef* zT^$=<+bish+NYOegkjR|_zViCU*?Ao_E4?>E@k${LWzGfUkzviKDsJ#@h)^2w`TEs z9&4BV?9WE0N5JG#q25K+ARarXqNDQ-jx!9qPEUZi&#x*efxnY; z>%In!iT$3fC0EFh>ylx8ctL1lL4g7EAzO2pg1?bMr+|Cu7EVqTl|_|MIFIJp%Xih{ zVcp8G?)Le~re8B$7Zy*0+`_#Cfsg%cXsAGA^fdAr4?np5I7I!h0HB_(c421@#m^jA z2E0r)^@0+5?vYO5+au>hBM*y?I)fsuypLs0%&gY}>c^h(Cl?P|OqLq^{b}YL9UXK3 zyoM0yx5$`JU%l)n#qpPTuZy+Fj)2vU`T6-&j-O5r%%ziq`j);kHbj=^Dw!K52MHQ6 zMD{J+GH6O^@w>GX2f+u!JUM0HbpeB}?=>sCcu-VXWBBzbA<&yo51P)`N=`dd`)est zCI$XpZpUECMSlTkloW}pgcJQ};e==)NhkIOiaU{ZbO-FnI zEg9LLaNWH%#fa(F00!#qrL3)iscFxXtW^_}3_W-|W07u8VrxtIi2a3e&G9AQeSxBJ z>?zjCx9MEMS76PTIY75yM&kaf^m4MTn_I%%ki^TL&pY)ZSP)r#F8WeK19Opm%K{8M z`H}2|!84@z%B~_A@TfqoQU<6uA zP-0M5(SXz`af+qZX~y$F=xCAkR+E_m&FsB+(sy?tnUg0WG4lL3v?o^OH36o_JpJ6$G{)`qQR_=`{Slz@Vg}5W;#Gl-do}O2#vYP1L2I6I8yBb}DcRU;VPV(2U*Xz!B zNZj7dDO~z7{WoW>KlWolQ6;J}jjwI~rrf|)a$PXSbL;lIe$B8USz7C|l4UEr1 z%#>artqo*}U5)@91V8brt<)WBj5pF9z=>-|uI!{<2zHkN;1F$n`Tbir;p>a+G95AL zav*2`M^eSG)z2(f3)o5`)X)I9e&nJ5`_E=4J6CR$QL~go!8tpA9>8U}oopi}o3rmv zOLEp@ZZUNSWrOQ|#($#oU+x)iZRp*8jrb5#pji@tT+soY0Tl~Ah99s5uuqkb7{mQW zL*BaL1N7#}8V>QbU`KE&AiH$?SHR@AwFbg3(_tS7H!MklK9XuHXVpc5;!agNXhr~5 zg2nFe5m@kaB9$WGEM5TGXvOV~yPZL*x@?=S9&=m-@L#{85{u-!B*gpzLc8jG4HrJT}aRS*i%h zOm=Zq1dPTs)Q%u*dL9FI12`lpyk5F=aeU8LqlS5$R8n4D>iZ=6rq`_M`wMA_NRD<; z(9`FD#4KFczcgZDJ_`NuBi|@=l&s7D8eT*Vo*=PWumLka6Wo#{=%vK8jyv@czPj;% zC3bCjAhRHpD7bAiuvIwg(4!I5!hlS!l(ugfuPce1aVG0AP{K;~CxS%*iNa*WdxhYS?l$+7&(ed^i?F%NiGkcNSpPEbLTQQ+ty@&_N7f%*^Hi(q?s2 z3mNwg)2^7SJcFB?TjTj&iCmGHv_hcAgM^yeW3Cm$mRbi_6Yy*Xz71N8FDSqy<_#-# z0Ju3GB;v~TX+4qN>J}X<>pjo0%2V7#YWPSxmT){fwl+qrS61))4*|&!5f{>1saI2<@k&m+S?@W- z#TzT@XN&(?mbI} z^p=#4@1raERXPttiNF#?DDn`Q5gF$(?mjmyld54HZQ1rYO=r-~TwGs}QM zi8-o0DmFIPtI~Zkno$#gPFh;phngJb%Y#s~0o@N^DIz%2HHXyL@ACjFC^(U*nYEeT zy?Yl@w&`QW!KaF?in#t}wjA&Cbr!rnrbXtpo?&GbI@;)K0wk-HaKkeoztJ0iX`I)dT z1=3+q@2i>_Si{u;f_#6L2_ixe-xk!928??2eqa(16!b79$fLKDF~-kndje{K&xSP0 zp9k%;4cX$33)#^%RlmT959ZQg1K5VPNZ-D`Ma=J^WwrNfWeC^@s|{KlDxOe(6MbEz zaD^c^`fAEj(@%TpGhc`ms_nKq8*aul2JR!v*0>e~jQ_mWdY}Aq1`od&D!-wq0zi2g z?Q3hR@a#fPMOBGiFVDH~=?Cd)#w&|UOEZo4Gxzpu?wgg@)aq31wZQaJ_5C5~!ots= zckkT;5Xsot*?EtlyG-svPSr(~2)2pzB?B@GTBw5dGoZut%kLp8j%6Y09|KD^C`!XG z#wBL56bHT|O*p&e3Be$T#{J_cz{SHGf!!mcqc?AWY8Grw2th%ns}`!>QTTzapn055 zC#NzK<#Xyb1~>{Zxn485Gpi3`NJ5Wn6YNY0iQ(87ex{9?0Gu5dLPb+mRyMS=_`t&n zH338gd6#QO;Fx#MI+;o9nmIeiJc0iPskz;2PH9D^&saU@&oV)Id6Tp2zaN%q;HLKn z-tbQ%aaJE!xiBYbpC!L&4jgDn*@JEO3*cRW!y9=1=6q`(WcJMgZ)WYQbF0SIw_0!n z4(IMQ9lqJTu;V9s6lax<*xodSIpz?~*ydyn&P40`N#qD7x7AZ((eK168V3wmWny{^fi%e)hSn3~tHM;o*v( zW7nvP3JTUH%u}Ovf*sScZk~6T5fKsL=phJ$OZN6m565Mn!#K0Dz8;;RNKL)&5WltM zFwpN9p&2OgN3n$e_9*fE9Q@e{te%$hlEb1XDA)dWGmpw&+&fn&QxqM3yB-==-&+vM zdcHl?I=+6DC92A`d0z^S=#}P|h0muSMT9c?Zz3qMvc>2*b=OD;waAqcf??#TNdOnM%VW{%z%R z@z;U%DB|Sq60C7Q*xlV-oezzQMP^jwH>KjD`AUM)3o%0IkYl1z?Y6i2yWPUqjOp$z zYz{1ul%?1%W7X6`Dp6rcE<`338aWI@=6y*jjv}fi&r-qQUfI~#)g>EU71aris6h(< zqKv(vM(rG8cuBC!#3r;>7xoDpz3`IC9a5=>zP9^sUz>mp+gWN7xdpAT^t2DPFB4o7 zLp9pw5sbKBZbzmEJ+%ZaE>p=e=rSSI@+Pu}-kWJ~V}3l1cRyIt+)QE+y%R<;Iy;6j z`0|MkQM<#8h3#FvG9J!f(OO+#dPduOXx&&5A=g>>fiquyX?~{g< zu4_g@kV*y$O0{BD^3DEK(I|NJFV`u(r>EYh9A1= zctj!KUR0-ZAz!nFk!I{XjWHVjQ$HSwUInZ+PY7;VE*B}wW_#zShUTaT<{Ma-A zNm^f9gIkf4#c}R%3!42!ZW?5Td3b9fV!wA(BX7VCGFe0*t1%T~59y{cP*DEWu&0^L zt{X(ew^)&Ld$fsi+vs?DY`q~0h0%Kh7d=Hl;4EP8hS z<5j^;y;Q=-C~MhA%1_1RnBD~U&5Hn9p00qq@wvKJY+tl}y@Gv{d(!sB>4=0xd{oaf z%@Tb)Yz}oRGZ=5#qWw)LhD)wbJbW*e!E0c7urURzuReafdlXk;0kV3iQ#z04>f*ve zfzd)r_}Ot;fv?tgs*yly zT|SZu>_0X*yxa=M4C`Nl>t#$U5h?TZAzeD=0PZp;X5ht@4YB2WRG*~|6QoE+*^baW zQ76@a9g*iG$&^ci~uzwJz8?+)5&@z}z?3+Sbo zYAZadqoXD!CSWigt^(6NaFSF9g1jl746-?j(4n8{K)jcx3#=%i|N1~$y>8pLHu69}a+LJ8s0&xKU%fO~dCdttG6k#>CtWDJFq&iZEE?)Ys%geZ3%0tZuc90xK6cMrhE7nBv+0 zxbiul1e*AZS1;*%2zQb;;XYYNs0OG zY4qgD9G+~HMv+EnXz1p6sd&EiB@{u7zn>K2dFxa)YuGRCo{)9<^pxxm#DT$Q+$$qD z_uwCNrd%VsVY4xqfS#QV%fUWBne~2=UhNWiS{3VqcJ&khi^1Zf{jGV=DB5pFoXC(n z@W)}dy>MwW{nnRcl$=dX8-C^jX)RNAG6!=J{ed%QEJdlo1ywu^YF+@f!CrO7vUW+( zNW!)NIZ6TyF!N&giRZVVlOuD1V0tJlEX>QB4Y>{!SoDQ@Y)p)XK4i`_@)02qQ(Rme z>eV-pxdwl#|2x15cpLPa5ZZYkJ}95QCgUrg@L24^(}`9ZE9F{TSXg#CuIQ@<>qKDS zgUQB)n5Vju`J)KfXW+fN9NzJeQeW>b0`-a zT$mk@n|j{b=gqR?g`Hz=CVaFIIo&91L>YsPJ;eoG%D1`>d!qaI6?Wqs>ZY(+tT_o^ z;G;wQMzmz6M((_KB-fn;2(KNm;3US#loKBM>qw#ior)e@$~Dd z$n+0;UVX14Q=L7D$BDgGc&`3I$Gc_q^~9)$IB0@D!r;R)u?CP9CP&6!x*A_oNX(Tm ztye<#e;th(oXLJco~ld#o~j9E)^;4VfSA~tHoV235%rTTb_CCJPREbYEU4qB6XGtE}|+?h~(oArZyGwZah>HwSi z_7Gs*5}o~7iceYwgNb;qmKav*;N0deE3Rt;RZI8cGhX6B8Z#1ePQvFpMT)s{@{B`P zm5j#S&iLpRBE|mxiXckzpA4#SoEi0lCzO?zPC-74;%@onqqtvy-ay)`ga>3~M`R-vz_{@Ed0 z5$$MhDr8YAqlBscJ7r{P2v$prkzV7c5UMZ-6Ml`M%wL1?;ut^F${ zmRI6;6$}y*-Qgl&T2CNWFg-l5jZa93_$|yYrTq4{Vn!B*lmP6aH4~06s_4_3!%zMl zC>P7XF#hS4*~ zGG|7!rfq&Y(}iny_alMULA|~mP`-U{vI##&s_fjVc5T?f7ACHLJ*p1rAo@ha3yyM1 z-}cXm&lKNDh%>gNRYuNUEOw38$iYQRy6xVkM-|R&GV1w~EIbY>!(1w%{H@5&3Pk!! ze8A1%w+%;=<~TU7J`t)+*-%q||7b($qrN_^fC_@I2&Y_Z`?{&r$?93>y2Z|Rs;phH zu$yqP!lK*j)-v#iJM;TiUYAkMX!tKEG(8ky}Dvek~3m8!{?Ck z`APUf2DDnfz8*t-D|o1fV1uPLh{?=DzwnD&T3R~uvNU6{r{Y5;m&{a2VY|Tyg$|XR zgM&j(u1tbs!hRtPL-^tpGxWaPRQ8oupGMBlq0W6~Ho>^h9~Jk2a-|V5w!FOD-yhb! zn8Ed4YX(rZq5+GPy!UkU^b;DYst@|+-m!mGWgoUEq@fBktMj}sD)PU&IMaAvPGHrVhzs!GE@ z{;0Gb0|YO-_AUyFLYo5d)qhZw4i@<64lg@28Q9xXQH#lKl_X5Gppna7Q^~_-HgEhT zM5*qvVRV}Ejs(-Sre~CSxYe8#Ra-4OGz#4wpO8>z2Y;*2L7pz=Ae6b1B(oSadpy(TV+1ZdQ49)bg|@8?!>M+kdmuOtS*fz?T-E6RFI!n5i; zr1ACY$-yQpnBhw7U8@utd^`Bt@YsmIOebhg&5@Y<7q%dMgLee-r0v&A*mbnZ#ai4V;der%CqN0i!T(>F3Khy< z!>z3&-=JkuN>K{-NDJ=FE?QaY$i(jZJpL!ATQ#oOxFfD&rPj3RElzXgm_FA`@td7< zq*={0KQvA}{kXAV8*(LL6%tJ$5+#pYrp}B31V4uM!DuvJ>^Wsi<9atMt9G;{zW9ql z2T?-ICsrWK^_)>Vq9PI;`2f^JY%rn`8;s-j>d8u&Sd`L&Yl(lYv$Qy#;WgUce6*5^h;8cl3Kur6!tfOLFT3uyr((+eLsP*E7`B#t1C6)-}JYO zZ+)qKn{XJlMICqKXJn%Sjoh+(9O%sXYLiA3{G z8DkI0+H5T@23zcBM!RX|wY1tt)vW;ZtiGcx+2!SqN=lfi4`FtN{A22gzRz!Nu%4YR6;k&N zN1YDE+G1c1y_VoEh+azV0efK^l0-@^(a(;iN~*&}z3O&yoOF8LBUoHm*z=UT>f=Y- ziaTAttEbtk- zjPm1c$bWOu1esXd%}HC9`qv)QMa#l*S7Fc!bTA-0Z`Cup#h6m?BL)B3?>D5UY4E1^ z)_|bN*#byP(5?3%CFWhl<(EliT%0%mISyor zho@p5Zjz@z(t`szsKsN99r}cfZgKG6Rz-Zsf%PAwX+h{>=~8h2PMl1Bq?+b)czrj@ z^AKww*9i+ zOb-R(3(n4<$Ni@8e_VZcJeB|Z|7lYQ$taP%_ueIY7P3P*_TGDxkYtY&Lb9?VBcY5W zduQ*Ry|ejUN1u9sA3qO&y{pIj+~>aU>vdhvb@8Y}jC)B*k8#n2w@!8*wE!Fjd!$v7 zDYC`svWKFbAB|_Wv2W%IIR3i-F5;>b!5GPU7wno3S^G0^4^=Na$lFkUq*U=WR@t@bt|8&^>c8n&N9LF0+*XNwGwK9?FNqD^X7R(+`l=jnpJd%UGxAE zf|P*B9WFldDwIUBZ~g-!dgo;VS5`}QcoqBd_4SYTgFf*l^u#aZEN=TlzI0aQO9RgH zMxLT$Ps;@dk6x2yIw&h*Cp*C~1Yn?qb%4jI(7o;ok%Zo}tI6#icRl?5onD0%gQMBsU#+YXpS`BAomm7nlRJL1bsL@=p0q#7wVTWBB-! zrQbx)P|`vqma_RP)vy-p9e02gKO*gGHf7MmzrbVME zw|7IYrV&q8dFEk*b=6&R;;qGr$H#_Y=Tn^qWV25b3ETz2gIQiejUHO8LVG@@O6&8x zvJYJFmqac(3(fNQ%7pP1Xp!K>6hvB2xL&v;P8-#@>|7Kp@hJ)bX~rJfnoN`Ez^il6 zq?EfvY(s?|74eE!wul?4aDf~D5jx>#`P(Buqmvwe6k@GK~lyIF)$lr{dyo5EIL6zfS}orvW^ zpmKyqllkk{uen!Q0RwSyc3PiLLC+UG=6l0!6Q68W^+Mk&ly)~(r34$G{~BOZJ?qMi z5~-cs8AzDAP0?LSRPh?3oqWF=vOidPw4Tb<%|Ug4<=c)^awpM{U2A1J3Kze$i_BS zj&1>Yqb> zb8+!cSdQMN`=1C-UV0GJIX0%uv^-J)nEaZqiM#RaQIUzhxuxUptu=*4IPy=rmBpO+ zN#Sd*b_Wy+c93hyYv=K1@nNU~yh^FjK#F(hrAP_f(WL(sqKa}riiV{jWh=^A$jTF+ zZ!j?D=wOE`0Ru7rFJGt{g>G$(1#5Ko4-0yH*W5=Ys2#03g_iP7$zE#lWvz`5naL1 zGAKE7X%c!E3lkN7g!&TPz7b-*)~*%_DUVf?_D6NeCwuYIf*$VP$kIz^Ww97$P47y} z2SC2ZU+w`p8@BaV3xGg~V+4(TB}(=RUwMQSG4{Z$9a*G_h{SVn(8x0QWR2%7XsHHJ zX?|Z(EW8EU0odQCKtPs{MI@&#Ocu4Q-J3x>xY^{zO4R;6QZ9Y4*et3c5jKI^s;LgD z1*9gvYBg7ctPxS=Rp$ybE`kQ_yK#4Jk1x#&AV0nlaajSGk8u9`zD1w??qm?#O?EmU zG*KW0fo*v0+MLm`+6nOzACeO)yj5mv4DcDS#~JX0JXfm@QB?vSpVHEvA2fhIQo|M%pU)=Ufo@>dZh!qtTKa}4^+qe8 zVF9=)k3XT{2vJ)a%-WUmpWJz+TZJFEJlMF@-)1@T4SwHWA$GbeEQe6*ctst=mK#bJwmp)+|(a=Oe-P04XpN<~+pq?Yp zHW?QamlT&$@;0?q^1}a_FA7o`!y{#>4GAio85xsRg*9rRm4K@xAi{Gx^MELvr{XOg zjw%tm|2~@^XN5ET!e4t7)XA<>%3hby9hKDB{1E=d5;rc*+*J~4*+%;7msiS^5N|*} zWfu0qJtLz$QOWJo#I`#Mg_UHhSH61B4X}CYraR_l#^-p%qBnD$)eI^e^ZOaRO7ne9^6@J%cFp?^~QP z&8u0@h>M#1ic=Qdd%g`$V;qXJ zR}l06yrY)73<{0(F$xh$17-If?CDaH-1~XKLPGYrEYcMHP}q10i)3B@%J5ugJ=7d9;?u!OQwN%I8V0l6Hu?D_{sw$Y1)QI58ao@FNy(u&#NjU-M z>$AIhe%`)f+H$maQ#%ir%N&O9js~@h`J4<3gq|CYZpVVNat^*emFHTQ5_|u5+?;>W zF7j$DA;$Yr%*z3l@1`XTL3J2}K>*H@X;U^gQx{9bq9Dj0Q#w*lIt!_`r{5-~GP5Z_ zwesi%{HxnEsoenSzR*4Ii#z!TMebFB5pRY%K@THC#j0!GaYHxw9yLD1J)lm?A@1SM zqr|aQ{YQm=MsVHw)t%ts6S&c4*Un&2zyyJP(eL#(xy!iD*oJ~)p7*0u(2Zbi?y_ndlh4O9v?L=y}gr6UTwoLq}9f) z;8(Y?5J8oj4kt(EfT%`GdwVKu5=_%j`lme#zqr14p;47H2v6RkR6{m+ST{1^z||#= z&4<2{REH#x;3}(%a(lB88h~6G^m|vyDtd4me&^5#73_qt!At!N=$ZH~tN-38Yzcis;vV#K|E zEtB1MrSxJjoJ_zTtR@T9N8E8o69N#W0{yHA7oy*kKY;bC%dEmn&XQ9f?zKrkQmh8k znp#`s>mGjB)YHT9hxC`!SMlm)*599e92n3#UQZ>$A@j_5H`$shZI(;|ogNfp^>#g2 zIF-u~mz~Y{W$N6W!IZxX87+kYiv3N56rk;KC%F|Ni<;3Kc3@jEG$W$$os6@8ry^TO zfIttNXuL6(<`4h%_!^!ypc`}3X`8a2Kv?$S?nS_|wPCk?QJgw>@_-Ne_`2F=9>P;A z;Ej8XCmY{nd)WNaj2Jh#4h*EGCo4=JU(dr&97(8~tjgY3pOe*-MP=_uHL5u1S779S za(otHslbYA7LT)_GC>KYt3ZZlK8)3?CXuef;6bB`SnKM--{8ms=NGxCC;eMlSUh=N zT3sqn{RG}S;P=9+c45P|&&k?E&n2Baby!!u1g4O*|7s6=bMwb`T3PD7tb4i9;4VRnF6^oKVpPM8TRiO=M6kvL#J2FP9q`oy3tSHwUnhU2^y^CJZ1hhQb@6W}> zar(31+}=@7m#z(aK-$gj1IY)&E|N3dT^_;#bH02z1mrlE#?0hoJzAy(Byuxzn>Ri( z>QUqC>FI?^rGmjW^6|537J|znu4{K}zq}S=QiT!8$6@6SD7z00y}gf5Hrr1;_gmt6 zq?3f*x~xmD44p&xs{MBc)1V1R<@n#2uaugJKV3@~UlJ$f3X7I|7db!ovr97+kkjvT zWO5~Bs_#vl(eF$9;&vOED1hWD)en|aPkSEsQ zj|K%~0sq7wAjP!DuU+h<*03If0)n6O)cHK;gmN9|4)*su6mSq-|0vl0JChDqr*@2K zG-a}oSVJU!Mv)+3LukdzQzpu99 zWBN?zopL>eJ&4Ls!_hMo({lRya54xBf%Ngh1+&*9gkkloW2i};cNqDVzXz+w#~1oQ z8_BBox!UJe#JSg>6PjLNDRthM!xd+BcIxTtqpKM2@7J`^9|KMSv~e{Ra=|dvhlb(| z-#mvH$5?tv(ufiSbnyd|hOx=&HSs3r6Cr}IBh?f&2J$i}vM5O}p)^!;$9R|TBvk*x>>1`MWu4kb(C2^q^t zUM)h`o7*mGjCG;Qvfv7on5;x#vi|T3Rtb=)gr2O@QaI|vR*OCJ$_{{JGCUUZ^4Xry zkV<4l+bjC!g8^6LgYIJ%l8_(GN|~0WS-du^vD0?TX>i}xuM!5MV-Oi>{34frVsf<0 zI`GBdIkb1pZ5};_h>om`@_o)D(Qfk~PXMhEi?suBtI&Nyo9FLuwwQb#5iYRgd;n~* zraax?prv|F%fZA{LQhZbNGEmN1B|R|AyVYRuD6%pxAKLNeRWzS%-f$knHQ6!#M74h zoSkj%=&1G$eZ^6C!xGQ@x#l#r76)b6{`w*DiwbA+$ImVl-Uq?`Cqj5teAjmNRM87U zzWW8+C5yrN;k}~=W%J|5u^&HYdY&w|hu&z$t3N5^_2SH-3tOvE#74$Upt4T|FES+k0jV7W1i3pQgojnV0PC zoi*t(*ry?gelYDhIq*5W zs*TpJ4h}Ld8^Z>%yV4|ozLkDlYLfEr1oI@dze~b&LhI(pe$36PM!&+N@3f(1Lru?$ z3N!>&b*KoFQlxaCu8XuZFwbD&tR;inEK^p`0+1o% z4P4i+-)Kc`p3iY!H5S<|3JQwJ5Q2+I%E|(@i=~;_GPCii_5@Mmf|7bNF`? za-^&cLbOh@kb1r{&gJpEiFYGT{75oG~M*7@2;8Y{W2H>8L?f&3P^7uUv z85voaD8y$q82zH*#ZRa8Nst@v9^Msn+ejO+Ci0O)_~!C*b32Y#pXpWk5ugO8d}wLO z$Jpst1m}FRh)atH**rYZi2Gp}_}uQ@yNA&R%;Ud!u-+=5sqI#uy{CaUn`_2`^qTG~ zx3r`?#hq|v^W$i-OE*ZhG;=JRkHcg2^yyu_@2i|5$qt;lFTwye&-GHxRa9Jk!ymC^ z{!AK60qFFf{W5TAKC%|EMeYn?^;5rAW{E8$m{U97cbhXYF*yms3guQDzX<>=xo>PA z9D#HOsAbB09${h2ll8DY&sNZatlIL!l6grzJj87e$mb{>YSnJ)@4#HP(zdPOk;#J4 zcZiz8v?xF^uY|8(17D%Kj!r_;G6F$O5x4S}yV9a3(~Z7OQ)EHccc%H{?$?3-Ww!80 zybBB@GEv{Yi3ir+&B4LK5v1S5Q>mHL!6nxnr@9uvnpdEemz#eT3kyTjYIC;r+oz9t zX~@;luf+>%4KM1aWX)?}r&3|%=vx1)%!Jxn!0*Z4=PWu4)}^73G*I$F8FGKqHWnJ@ z^UMCx$~??lL4aV2@bKhR^ud`0QuG+mgAqa7G>uWoN|Bb4F`IlmL0-9c$){j80#H*( zBq2R1JA=rz0m>O@3@~jQXCV0l5TA;R8@`Zeg0=S>bVoC?ki+2Zy3}7Ymptb%eTm%D z7o06f0>|h-b*wv{iDl99+dM}_5NefW@{Kc=cmwb4EYR^+i&A~*fkW#=lN zm0>W;#!FWo?=QmTJ^29huoE!-p!8i{4&seuTh=qTM0(|j3&km13$BAL6@E2u4^hYM zV+Uk;Jci$t0Z#$Cbl~?nMD;(Kvf7<6SsynB3LA%|J{66_!Id=RcX7FkoW9UTK!D4` zF>8y>J3MU93m>8WYXwH$m1Cf9sDL}yt%*7N6?8Gu7rfIgC-*lJw|V!=(FaYHGT=%=UOmc}Bz5rH#lN zu+rB}0QQ5;ZMzEyntySal#r|Xc;!c@(huVjx3>JkLP9q~q>L(8K=`F29R>>{ z{HBP(w{bh_AM>#o+u+Q3ISr}us?!W$n@Hh(Bokr)tok`UaygYFy;2F8QI|!>#9vx_ zFtZp9SM$TV&clSy!YQ9WYo^HT&m|AZ$$@M_5nXyN4=EHvj7*(nEDQN2e~C7WC{vUv zi$jyOMotfDAVkH1?2wY_9AZ&NTKbX|ucD$8PhO_>;8%}*?!`qwe+_lUExDn7#wR9* z)IH(U?}PWtes}HrT(SeHAG#Ls{}mYllTS8A&MUX& zjLP}WuBC;BhJu8*H*##%=U~@vz!|zmugVLJCe$o!Y|SVA9OT79{y;;2BUGa&DAv** z=Fec;JMvCC0QbWOU-@g|%*LBQH^boLmjCrpn`g@ubz>8*`0wSB0~Zky(i*B~xmbu? z7rlH`Z@yAaPbJVUo8GPq%ZoS3$xT>N5)}f#$^?}kB}U`0-j!Y&dTWXd|0Vh&V0+-7 z4#dFgr3caTY<(~n|!jSko#T5S?~39_se&_JU#;BMZ!9+ ziWhP*Dt>dp|+Wsa{fqYA64=F-5GoHvtg^t7M)5kD1+K|$`hc1DF05q|yO zz_=}=5KF^`Vqks3#!?Sm?>CLn@t+q!2Enhr4Tn(0NTtt-xAyk#`czkd#%F)=u(M~X zsO8~Pw!Eo`zLQw_bBM`RF-ES$tUCkQK3Hl)F1?*v65j+f{owbPbRcChGLSHqw6pu@ z8!McPeu_%x+U$_BvYf4M>#b9g12Gp3jxx zD|HCdp?vPSR&xoE{@7b*5HJ4C{kcNT%}-`o?XV$;k?M=k`Rdj8S6)97x(+Y(mtjYn z3%4;@QSxYV0KSp>p~2~4h%SCYza<$q6(k!Yb8 z&%?otadOmta;UStZQ-3&qHP6jClQ-&L(7Ynmn=G;=n1+GiOb%-d(xVVWnFNly1b@S z39wpsWyKJ9nC3^iGmpG~yIO<&tR>+oT|;st=4mla6cHH?gcAq)djgwDNCEioZb&J} z1x(Ly`Y-L&$=Y(PL}jGbUfg&n5%7R0&4URc%f!q)ZF)Vf%&?*U&DJM7Ap$QJ-x}jb{S|2%MV6*a4rELKD z_tJd$um|*>jmSt74Fn?czfLq^*UznH&b~M*Xe8nKm!*JIHFke@=t*BR-1!9KBRDMt z^Y%e?NERmDb_C>XdOA%_raVs-Lwc?{)8Zl=gt-F*NyXY$g;o!M-Q~~DRWv#dBR_i4 zuB2340&N(iBFZk)g}~qN_O4XR$%ECpdow7Ayhtx6McmOw+6a+oXMKgrl~{dkTDcK& zPl01SEv4k3Y;5f8?1a+d=6nHh`}%+N2-9DNnsQAyJ+jkWi^*>FET;eSRr8QV#uw$j z3_rO5q=#Q2Y#1b!j|VHao6YU;0Mu7dOlB9vHthf4`r+BY$Hez)^P@Pv=b@y)LWw zcPjiIp|hwuGmM6X2`GZ8=v-1R~DJP$&)> z0+=^)(-m-bEYUCf7q=})8Jy+^SAc$nbE|b}a|vW@Gcc?lUHMagd!u%b1U6(0-ub&_ zzwRs?D-QOVplIg6JJ6=#Lv@?U6=)_s+#8HZ*c5?zF^Qd}yj?1k~`IxbP%jjXw zL1VO7kb;j2j9TmjEhF-ETCP3qQRLYGKd@A z^uA5OrOF9{yc5`*V8ngHXy`h^w|LC~mX)J_G&LqGea9W(OF4)iy?{?Rm~PDDbf&2L z?XJ{?B156n?#M5?4|1~9UX}X}l=~0pz3VSgT@Sfjw@PxoJ^JJWreaFc`ztTxx)KVr zJ*6@q0~-STn3`ygt1(g0*XNyPK`IP04-uRJz@obL=N9EySXwIlSO(aqydYenD8!UI z{!y#I4Q4{^9imG^)l^9kkfzsu?3Fa@?|12R<`+dZgZeQfWF4LBhSs*5raNf&F-%sJ<8qNjbFhzJ^2rxO8>HM9?z}-qu&*8V zCZ@0I8~t_tgv7KzQtPzG2DRWS{fi%6HL6O@SGVA&?aS5F)x|o0$hjn~4LvaY=B8Wt z`8~1j8~N(NmzBZ!M;o8FkMdb3I@wh|ncks0x^8V|4ZljibBlE}HQ$cxUta>A-OS4f zBHyQ{saI;x+;IlLggZ_lcZ>xXY_{$()vm>KkVCwErJi%tF(ZDTmW7j@22w>qc?LSp zR|#hkGMN7g!VwTLLG7(qgir%zew}8TmutY2$|hmObQg_NLSDuAglg2Gyg8reUfn&6IR)His}Ob-DnQHxeWD}&!2bKCLkxyGZu{~0a5aV zwk^un$rVMf5o`Q!9cOQ8#Pu;@GJkpKp4mvD|b0<=ET3tYe6M{Q}tYuF> zywiWjAteE21pi9ckH1=g7X_+u;vyc81qhQ-x9OobuHJ_ZNZ;qkNqc)MjtgQb?N`xVfJ{et{@R`mc$U z5dKWRtDEscgq})Phy)r(Xfk`TD@OFx)unR0R}aQ^_B`!ZOm1-zW5Jo7n;!Pv>9H*D zLd}R;fYVX4(p+ch=zhn{B-e*`L-U?lA31c6r$K6tG`#2OnVIq!+>g2Gux7a!QYgIP zxM*~8bkwc#PAq{ng{Y6qNblZ(#(lxT#YS(e$|S_31VvD)(LeS=6C-N05s_dsQaCh}ci4=n ztmM&Y#tM4{Rh!yJn)0zqry8V+0g7*`KMf5BmcdzHER)iqG1n>V-bmQQ2%L7@PA$X& zrGCxn?dwTNeAN;jc?J;<@h5*C=K?*9W%}9<>s|j?8O?F#%rTZq!-|IMh}+$;7$bB* zq-w9#2AbdL;da4ZgO3HqoQK{gtrL$qm@?mIwOnI}dk(totB*eLkT*ecU3+ZqE8jFc zav0?x7}D$^tUQ9@cu(>SLSn=H>nS;Y_%lnj*bvIDU(M~g54#Wmxp{DuOEZWiA%nN4 z%K1m?{4F99jMO-R=Rk9a4IP=DHR}!s=p31#C4N^wKaKMXk!o9X79awf0EUz#c(o`vDxLNeNmE`7%779Xp+(5De ziS2`DU@?@bX#UKA@JWs{A~O!7P#}8iee5q>Le*OV8;I0+4*sn!v;pv>vn-H zJDy%5i;IxVLr|0}o-!^VXXY=J8stC*q|ZPy03(97v;Bv`Eg#QY8Vf zMVvS7Tmc_a)$tJmaSR{WigyU0zP4nss)A}J9Uow`fN_H-J!@1)<>JMQr<2Rz);*aE z@C|Dm9Ow(!Qxju#;oJdKrB~!%kru%neh@IYE_pbdKCCN+ioCRP=5`1v&ZT6XCn@*e zZ-?-4E_-Y8W@nx^3XqnP_@H|~+_64i=J}%61i;KZ8j#0<@^A-|Qy{eQ<>_;v{P*<+ zX%7IGDt7R3MFG;XuvmnTYZ{`-zg4Eo#=~Ru)5H(_6uo_LvVi)#;Y%F0{Bd*(DDT^n zgzD`O@G=$P{r8SP8xQ4-p1_-&W9_6BJab2Vs#}S6;`j8l&ekY#HF@5J=3t*~4S*kM zy`7w$z=!E3Om^IC4WLMh%t~hJaA!E!eiIHaii7@Ne`#UzwO;h~KVL0W;R25xYi-~d z;l<{bL|sI@U3dTLT=5l%#>2hMXG9RsD0W{1MKLxiLe^eAe%k_b8Ht26$!Uc~IF5iw zNxzVW4=`9$#I{Cyg3ANY%(RaVP-5xJcIBjN>^hq66E{APXu z(I9-*xDr5w^(D@;+`#T1Ui}S%a%ZPo?{hp3cGr2PI2(UUn87^#%TXL--l1&Qr3C8N zVaE(m8O7(Id<+L-ZOru4YjBl@4<_ z?W$5D2LLu=Nh&9F zw0iSTi9-xbq@bQhehw*r)|pLmtGWBo&c}E6>=Wnj!Vg;r(iVPG0O{Sgh)(C$k{>Fy zx^n*g7&oj2+t*;LgygT}!n`~a0C;Xa3($r9)t%qlK-4%4ufk$M#caMi&{PAGC|Y9F z3^c7qv7w{jNK*Wbq$>-KSOyp>BF%J8>Ga(`GB;ud| zCMo@+1r2~@3oW6mIqG2$oReoJq>!Si1W>OpPERA{AUWrz z`n&ueKwr9&*>EIyylI0&CMHD^JTaxo0<~W1rQK*_?>k<`pVH9-%D^sM^t%g>H8<$% z3e%C`-5nKl--4Wh;Xtjt-jtM-{|%|(nEy_bCA#+@9e)1c&WR@fYjgN;V<9WzzNz%B)a{x z7xWHSE??$kN)=YGQE+?LYTS*$k` z>G$bX_`Db<0;R*cp2z}^KwNzukp&tmci^p(LXdzQmekZhFRW2|&7wdPdR7(_-^%tG z_wABCWK!YW=H9+8Yp)6f*S--N@SUBV{X9o5+W=T6_yy2dCwf4a4Xk~Nej)ztj=U3l zZCELwL#XM6Rupcpof1U$>#`Cp2gJ3S)1Y(129=YhHB+Vz_Z)dHK!)AGmok1nzOVyW zC0Jq9tO}liYm=PNhg&hg@f4K7oU29hSRl;n;J2MxlojJWh-a}KRsi-YL{SmmnZ^%q z%t`myWntJNA6hP60G1BASC#TJi2nN^c>)^E&70~35W8!5B%y@NaNK=P4F{B{rUn%s zKi$%V1;!AxflMIs?d_yD3~1Yf%`KrHUIJhB#`^k9GOOCpB61D?I#cgB2M1D}ZC7Iq zidt2rW~@&f@F1s0=aX>E zLWH1&`_7hG)fn5vGw-V8?FcV_@d#A?b&4k?d1=oLsd1MtQkMc|@H~9V%4+^b*WIX7 zBLg^jAmp(-+m!JfLdC937mg5cGq+NONEwE8yOm`Iwnx8%P6_^D(49<6t++G$!!&NZ z1!rI-3>a<)R5*#)9tnD^knV6m-wrNw<07pjmNN+CjeqsHSyt3V)^@|#$O!&ZFHwG< z2bjluRqoxZojU378vYW(NgIF*536_uPmG{>iQoVZ2UhK`ZGXW;R!JT0YxOc1;xg;A zt;;5Dhk)dkPE7^rYwYg>2Gj%H1>0g=yn7H!BXvO*mI(dS&Vhf3tlY4|BL^92DI+7W ziNTMGR}7kIkCe48O^7uFtpzCfYoB}sqq8kJ*er+I-|ThFXp5Kz`6*={bj%dm(&8hV zn|3`#wcm1eQeUNpELC82z`7-j@;F%<;L+*$3X?HhE4msjVZf&2f1Q(-61o^o!uFU% z7)b6_U{|?|KUK;U^7zeMuOcSwt=l$m`8k-34Qj8(n0L>%)|rviez$X}f5NMOH0NVo zph?z_&Pg21?QIqj0l{8basYIvt4j;+lah^ooX?L7j^jaQ&8GLcz*v12#@M)%+jilZ zCmlJ`q3?Uld-08>5WX_7(+q7;*klKJO-aq&n%baI3!AxL!qU@CO&uzn;OT}t8m;GU z7|BI*4deW%uzT@IY8Zbgw5|XP-<6gQ#5w>8HuC>Gp3=`R8qwb}dNFd5rULDUO`v3q8EiqOw~8|}j9V+wID|dU{CI{+7V>k`r^v`v&#zCr zUqVL<{YPWLC4{CAbdHL&sxB^kJCB3l*m%QFQ8+RPLZV`*uy(#!S|kg@>HGUXA34@u z4y*;oE)-UDRRsYzDLRH38yg$w9TFfM!zcb#Rc5-+XB5b2Iw|e9@U65E4N3rgK)%Fd zmQGrNVs1W&02q8WqLf)b6=CdPffs(_Dz06~X$UA~zCJj>+vlOT8NM6kqMYnKdHu1X zQMU7HMhx_?%HQoGRkXDBQknrs5(tg3lBth>?zMg1v_MmiKDD(&?IPklIB-GL08i&Z z0r1L56Bax8)2`Ps6R#_%Kda(&z<#V#aT#rG2|hy{s7~kjGfssrKcRImAV>JN{M-11 zEHip4=9X6C9TXTVu@o@+{vx9An$-%(MoS>@l?AexcZP-pdOd*6`nzrJ>TW)cx-?kw)yqtU`%|MR8NFu^O9T zyoA&f5>`L~U}n;i2c8@3meG%|A__zml$0Qvt#bXxO*kA#13{_+2O(H~%<|jlm^Q&U zC+pF9UR&;mDK}sd#n6PFqO;Q&E^Yz&Y`VmB=FNDdz>+6xctJQ68^;i;M)1D?YHwRk)IQ!{Y|UsZlIZiOu^K zhvS>n7wS2=xnE>f?`(dL#(pgF;8RSrn(z^K-r!Ilok43o`WqS?QZ6pBBaNcaiqkFo zfm3O__EtO3n59!H4Z;{|;65p2fU4Ai98CFMlI2pI%5b|rY;D_di`|4iSTZ;E_d1p2 zN&HQ9NPmGm3Kkl4m;!jRN$b&&+Mnt0|3qL6DA?YY%A%J0R7DUh3ybP79z%Cya0`lY zZhJgP4`DD|aTv3($sFmVd;Vs>QTe-dXtE47bE6<&8Rk4rNzqs^*F=gK0ohQJ6;#5_ z&cC~hV6G8)z#rcPjh{THVY6{bhMmkM7@N1`q(WlN&LK28xVhEz^t=~-GOS2( zKF19n01_M$$kMI3hFjY)D7;wv7POu|F<6NdepWLMF<`=da%sqCHMi?I(CkrR8Um5? zuksBr6W}|Ov9#e62{z2ToL)f6h{pT;9G%VCxEh1qMU;NVLla|T7|A89LX&MZpUul- z!cO8OOrhe6fU^N4Fw}IbAN*QW?zv*YScE3=vK!{*nRc<}`P&9uX?r#{XRZX13A=`G zZ$l}#4J0Zzy!#O3{}~qX#9xBuYLjdZLozEjE@mFI8#{D5913n4z*@i)rUnQf1Q|^a zTt(b*{%5u*e7)8wUu-hwPis^8eJ~x~l9)ObBi`@%I7fKkY%d2{bn5YJBvvH%v9RT zN8S={8rk{zD5Mv3^6hV;U+LwaY;`L~00#25rhWBK^LyLEpGv~^-0Ls8zx(dVKP$b5 zA>wlmq17;9TTp4uePd6|^$3EWyX8R5+!d;3Py(?dVfE?Sidkw+?7s7Eva9`_D=wmT zV;pR3$|-=xsDx&47Gn~9TO;YBcs%tKIWwy=s;N4DK~6O;C52+(Hv*wmGh-ivLM4m& zB(>K-^9pAa48CdZ8p{2usneGy z#wjJavpkZco}*FaJ=d1l+4%tI2t-`V;`X2=Z*U!?9~I2j0N^K~GXzG(-Zwd~DTk?k z!^9WSr+3XQ2;B=42g2G+v75!mEv>C~VRs@sdXBvTqC}=BxsrXW+QqTY$d8et`;DwUG zpQF-gBH^u75$)H^=}QsGGSjw)W8a?=4$8c3EyI1~ArlBxennm@(8eAQL^n1EuDxdv zx0v>umj_uO$*o%;p2Bo*;C>%2sMTOylN0BJonMC9;dhONWUt4{QV`^ZahKYh&4&p#UTn_*gVCJ z;13KvUI9sW4&tf6fy;`@`ShuG**V`W4a`aP^9qJkadhy3by|$IOWJ4fyVIAziI$tc zI#49N77qe*=)#QT8^8GcUIITgKMp+;(>)mded+$Snt*B?f4e`)Y{$W3j!%Cr5mbV3 z66v9V&Yv9})n3*ho0c1;q@#l>cTF4+pVFA<4yCtrIrjfVKb)t4P$u8d*+$c?RjHTyjo$i zZQo*y)y+S8g56g-p!)-f5Qw7ryEAaU_KjMnRSjUSkj!rGLBZCP|3y!wNl6p+QdukK z!YK%|eDaGb)DUJ}7%|Xq`Z(r4Fh(0M#W2#;j?fOh^8l=16=xAhM8!zkKDbb$4?=I$ zvIiksUcz+u-C@C`Jt;l0TyQ!lJ#w@!R!p zQn$*N9HDlfN=sm*JD)3SVFNo`xY81odLzI+%)znV6hQ@nwv(rgimB;)NRA3PLLhRl z{_82#@kL#NI;7eB#nHz(?zi{;!;dfczJdeYtXl^t;GHt_5@V<2>oMk0N|{5@#8vo+ zEq@0eQ1p)*-zNQha~k4ahKCe{0yvWau^MJQ2@J0*qdUB3U%?krGQD#!Ch9FL*_R&S zwjUY9=>^}UFLuM?Hnb(qE-ru0ZY$e0v@k>|@RwtG^VaSX$N>%Wd|G=Zd237yXtRcQB^p!2H}+9(<~X;{dsk`?XnGnBZPZXTA|UCYNvs&rf%zpHKL=_xG9 zKo3~M`nL<(Q%@nv0E7o>x+q$W(VZGbv=C4ng9215Fs2p91u^|$!nKYP#m+rcSGRBJ zyN3HA{eqD>r{#v4I`9r4pxsDAvg(yP{vIwfU~jN%IX*f-KUuhc{gu$@J`rbeixzUD z{Klu-eD;odN-NqxG<@}~1^1Gh|9O~GAaAaj$D$Kf9IDj7wN+H(8 z#oSVPo*N;)@_+io2Tf<0Adi96=l$rZM313-%N&Ggm;F7(Y(Knnj0Q`LUcSaBE5sf5 zkkHWhQz@t&+_Nn?{bZ}WPqrj=#wCCo7sW;{lgzHWg1ASc3I^%2OLE`LCv07voq6Gg z?~4OP7E>G8_h!_zMEmrD{w-wdchw|!BjRcf!hKdIk68TH(b0jHyvjq@PfC~F6A!5Y zD|I|KmUpUlM8Lo!G@e&FI$0$9SY`c}!|_S`=!kTQ)9BtipHJt-Z&N>ACiWZd=gFe# zUBGtKwzVm0!^YuGENT-7G3YIub5z1bu9(LYnQl)09CyTzR6^97O%V>vx4bD~p3Ze@ zPt-D;ZgcE?iOo@&_chio>YR0(%tyZvFBU`O^HG0XnS)~rl%TO#LSEk2?XzR;8{{kA zNk>bW#PZ+UHLCO$Kzi!euVq<54)nxW zINHn`BJL$vL@{pXC5;fgAYB{m2i5L5)X)3+K3&%NSy_$!AJXh?4SX|=U$0$MC?;lA z;mnfDKthVt@KyLq4sEQgR5kK9lszClG*>-mIN=OJGymT~eMk^u>~SgQz97KXWGRV! z0IDQyQo}KAQSO-B)RbLy+^B4tx+3H<9n8bbn$h*g}bm^*XmcfqQy5K@}XSe0*GlP#8!dqii(kW5RPLDkgzwLhhjGfa% z(yG++;AInF=mmI=j*h}dTiu5YafDIxepB^(SH8_K`_-%sK0R05S$XUoSWAISyh6lk zt0z5{9*tzC*;J-e`m(W*bGRG}bTDkX4`!>R-vJGLFUR3EvOg`Sei7404HKmba>7pA?CuDxLzBk62OR=_)0kiDOa^z(ySD zsW>=yEcw$2Bt2ETGi(BZu93>Z4}Dxc=Yr^5rKF{#C36|VVH3GoH8(&1=h@4!`{tmc zqDoJ{sx&LB)zX?Pp{lc^U}wGl5=(3}K9{|x*xGwZNhnvK59{ga=^QQ8z}ng&CnauZ ziA8n|c8TYZNMQ_&byFenv|9+S8$EAUkfSBI{B?Bb;5gsAP7G2`oh>a}U^Xl#LHIgd z{dVOP+nsDNnuGK_Oiw>*oT&f@fIxd z+1`G0PxzLgE-T8()O2+!Ol)jGz_Rp`Uk%%<(Q+Qsk4skO_f? zVAr?q5{jM$Du4g%!NEc2qB!1(rGX-b?It`{{2-Z1z7W4{S}R%1}0)1Ns9 z5n8HNR#QZ58!Z!Et+Uq;481Zn1vhwymuGu>$Kg|k zHXhbRxV5YC3gYIs8u8vtY6P#yBW?ykyoIIZv`uMRkGWXEfNNLyo@8eCt)5S#(a z!F}f_(p~6g+nhGDd@5|BmHFlrf)H>wk zpNk{&+Ilb;4y!=p;?48kXJw`E7+k*S*NAhA6=l)!WZ+o7xo_RVfQ#R#J2k;Djt_l}GS$H|U z>Li#brOK#!P&PYje0)(sc$KaA7fYV&&0!`k29lxmslZV$KJdG@07hlf_GW&Wccd5Z zuNGiA#)%GaceKdh@6XRl`Bp{6i+)d?QJ?w!RkDW5OP*z(=`NW!)6Rdxy-r^Hq82Qw z7O=0WDk&(I!hhE+(pO0S@fEm*7#9pe+Ua^v0eiI#;f8kM^W^HY4MzC2x|86&`Uw zr>R_woY8{^owKbvVD-%HG`)P~Av}50L;4##=1w1_Qem}{&-l|k&~9g`$$h>g-f#yx zo*5Cywch!5rTC^9+u*N?;tbf7e(>8$OBEJp{7SqRXjvb&shpFSm-za%sikGK4f>1t zr#D9+3Oa#BK!X)HC7ZEPcwYD!ou=A4+OC4zhf8x}SI?iFB%H$wu6x&c!K{y&IXeA7 z<(`*_m1Dp4$%n@8dklN@_*J(2 zOY5#kF9}$+Y&2F0k@uU*7B)7?r)4Aa^o8*K_d+0iLqgS+0At#CLmk9K7nP>Q*t0NM z`ineNUsreO(PHZ6dbBo~fW! zO&C~m6x`DwbRDE#X-Cn~Q%P@_@f_pans*o}-xmJrcqW35zit&zZX9a_h3I{XqzHk8 zog@L6DL=RV=%#z{9C`G*ONFJD9W0CAg`R0Y`eN2?j9KL8apQ*R(KZIfJ>H>(L;8|c ze36%zsr?w@vT`)sW`Aw(8`g(v<*94AoJABo{)e^PRCbJ*dY3^xbpUEMc3xg7p{G*< zPV$*=6jWqoWfc__D+Ux2*4V1{u$Nyj-C}OuKN4+3#k_$dh#@p`y4=a4!Puj+XmhWv z?QXD9>kEah1e>o;Ph4GF%_hs)dLCSUgX?~BrE%Tymu8fDjul7TZu|XuHa*f}P195o z>#q_RZZEplFT-_iB!)-7>NGtp8DV|w6%A`Bp{jT+*1urIN>yWQZswDH9W%eMH0|c4 z_h>y>z0tBgNkqlU?5OdM9PGzhxYRCEpBy;=BO_F6z?^f1pjtQly?eePbY$(BMrZCA zgLC6eANIqCc`Pi&6gLR)JPP z-Mb=RS;jK`{d@YJnC_DwG7whhaa=a1@--)=()(@I$y6}WRU9l&+r!-l!Ty==+TYf} zIy3%2(9(%Vbow}FIO)eHCACfSf|67{XB#rQ)@k#RFo_uvl>8?$+rY0 z5^Se_U@vyu-@mHOf*&N2dc{7MInVFhIeVlLz;wrKNwoHi46wZeDf}RnVWe>8OiBEWN7n&Cij9_uO@a3X{x}7e`h||_aE1^@n}vTs zw7Y{321q@4O*v`6#O*eF_)8j`Bj_ZD!jPcSxpe`FG{}I^-H`v$L`U`p1-SiimK2a}(Knlqef!E7^MJUDZC zeG4{}A~~_wV^zTYQ*ZT&N5AqpaE5T;!bSs?uX)|D$Z`3Kp@vCjM3*Q7G1kiJ3N1Zd z)Jt8NMkqR5CT-AbH|d#F^UUSs~87c;EhsS zXMFq(GndF!dukdkUf$mRe)=&O0LDfC!Vw6_0O1x9Q9Ni7R2CqKk)xSNxzSu09PF}a zD6)C9YBTU9j(0O1r60SHk^|IdS((t}AUg|7qn?tnKZG043SZnmaJykhBXl{DC}xP-O>%xCEeYr0#ef5($Xyg5(-Fn2?|JqNOym0qtAK&GavKJ znR8}%&akh2-`85}SIad3tIXmDYtPCDnk!+qxQcnO4qV-R?qSuL4FLysFn3@1{H~eNxImhkyMy!XmcV2UA_gy4@3*y3w%e*pF)cIex# zoSvp@w?;&X8<^xOjmy7O9qONia8@1!M~y2yGRUhb$tg=a)M%njQhcGWc703oJ8U7G zuoMA2kaYY1xnFMkK~)TD7g`aAeosx4VVD?vntG+oQF@>o_T1?g=}qQrWk0t%Ut5RD z;p5bWO@>_l^*CBQYxp-LPlu@^NTRA^HwNor4nR&ec(NK*ma2YlImUmmTQSgx9%{>$ z--}9n(K5S4c1`}m%J z1*CcxKLKsqy;CTpH&Sd7ynlYD-^Rn2h>3Wq%8EO~Hgc3$HJM&n2)XgRE~gH;tc|eJ z%!SMDHJ?tmLY=Wae|97nKGVu1LGQZ~u&!@{=H=>Z{msO#PWO!4*q0u%OUlR? zx!po(%*n{m>yGMros#lI0RcIXaED}NjWcBH>$}#%^?&2|*tfTsU-m6lM0iveZ!#NF zw86*pKUAFWzWI|x13VNyHk)}65x2BZ%CC~)1X!oU6QI8(;o3%DEdu_gU;M2o(|yei z=YlqcW%n7s`$6noWTH4s6Xz3 z1v#^A2@w!y%Dn!=>GzIF3OmTRQRXiH2YjQT=v=|plol?GDOi^${k537G3mD6{}x_s zXVcU+AA>PtdotXcuIDsF81tIqRLhlDZWs$f$&Z@D{y|4)EC@nQ_^$*Dw$(|})QecF z#pnaiQTSkV11E}BL+W~AA4D1IlxIc$7QGwM?#pT|A@R8S2kuR)#)_OY{*mN4p3v5Z z+8142w8t@%W=%884N$I57sDI6=7KwwZ7T8EFo7pO#M?9lyQjF?OB;Q$}F zmleTgk+k|0JLB(`iv@`hrZ!Pv#qEE)wS&2~TF=w7!qv@#d-GZu0>wHNfEt)7U^7sp zms$cX0i?)0^wp0*3}(xUUZKk9k9(awhX`$j?!!RsX3oOWbsgLUN%aN|@|Iyjt>E_0Xd?c%{{2y-fody7L3;%|scN8LL zo6hdt*%I_nbTLz0-m)IGQ>VUr_b#&`D>yehI~!(qqWcZbHV$$GU_TwsxPlnPd%rtm z&6fO{kFWU+hM%674CZ2(QvQ6g7U}e;R0SNQxfQtRdKX#ZB_V5K_!#e=_2osyX z^Lnh8G<=p`nKTrXFqi+Q(7ye(eTYHA)5YGb4P{AQCC>5=L5#tvCrM}7S1TA8F5a|? z{qAQi&q-cwETj)G(<#Ww@e{%TZo*Vg)zfny^pkCd5)QdAoyx>_S7ejHY;ZzJlKESS zs_$VaSJ}}FY=vT}2B`>`o?wI8Hsp((3|6SE+9VcMWHE1QA#%m`f20gbZ<<#_!)h@ zn2iR$kG~zUWF6#DZ>aeoS(Mzc^((h^BWjExQ*Sh2db%!@m&dqtqYF9kF~f`|FJHDm z1RD6OcfrFCQ$)kZAHJV63%)&)baAN`&cL=QE{KWI#bMQ~dBk(3sQzOzJNsoVcd`S| z*<9qXSl_ONi_6%mBQ*{h`(14o%5s>4frY)3_2VH5ivIt4QWTs3MgzASD10pn(%C_i zzSLq_bhxKK;nIc%ja(ja-phL;m^emsv(Tn%uOq)WaAI6IXK>j#+UFay*5~2_adA9@ zgDl07=RUBq?Cp_jPnyo719ziEct5G%`mG1404)a)01O3tJZH{MGNAy4rHDKk8r{Z! zsrEV$fkGJ8ySTEnge5NuLkw}HiWa9e-%oE~sXv;#ke*KZM?kN&cjz9$5dE&LBEB1d zL-Dd-KRi4l3L^1w0-9ma`6!P7E(hEL4h{~sTn``|NjYrw_P-KefREf^KSy(Bi#Vwx zhW$()sQAH5S1(_}eg+-;-GkgsB-ja{oeVbiuYOBbb-%Z4waO}fZ!s{?3r=Kw$$c@2 zfbiOScU|5pCOogGsE8FnP7cpaU5*Q#O&lnVaTX$rn?@+1u8MOubwb;W>-s>^+zZk#^Fil*m<9P4-=&TLw?0X zu~I>Ngo%|^m0F=K*L_IjdILxF@28|E3%;WgSxI(y*RQ;ON-4aJcszO;P! z>%gX83_n>qww#v0ru*(XoHPK;5nPm!_A||B>@nR>wTkiK#z*<}{}iJFJGk+&1cag@ zRpASAUCikBRkVU2HMmXSTBn`B3lOStbCvhFOHrBF4U~ml8^@E1Ew?Or+TlCvD=rj~ zqZmYw?gtMP(UL>XEG-k0bS^O_%3Lm3?qThSYqtrsitxl=`)H*e{4x$ug8X6j@exMo zqr`=%vOY7wj@%axL%P*}>|yals2T$!>>w%(#zJ^*&iKOG#Kf*!V2jPxH8jiCp9Dt? zlBwUie0JyBf2VmhsI|P#I|`to{&{^Ne_{OQd1o+OH1%YsoLB|aGgbkg$ox+{P zz5rMvm*om=xv^k8S_hyOfJvg2BYb^*i_hn%XT;fX@fVlESy4p4E^fo>f;6|UzDY_q z+wY-Yx51Q)p zReUtuTCw_-kZ)3TwqVsffyCBV;(8asHOU2e-{%!iZncNGi?;iJpb$Z=e#FB>PClrM zNG2jaJD6z!*n}QC-VKnI^SxNFLvN#$>CYYjnZOJz$VRm1S_jw)1?6CWKUr(WB@{l4 z|EgHyw>!bMT81~Vqb{jjQOMTgo@~xZE#(Q1W<_+FRw4xlcB139hzsb=#!ufTj6cY? zVRqoo)Y-@C!eAo-3LKaDVdWNX4{z{u!I!_-mv9ZoHVO2nzYaF9aC38Uv-#LvAfExB zN&&+<&AGydk#GU=LafVNYK$QnkjQ^g#J4Ynib?6QY2*1wbspRwzX0XSH;~^Gbgd_+ z2M1qXzlQ7W>Ed<;{>i*6104itaTA9U(IexeO3wa=U;sPxII%MzFRXd?&+y8h?s#)6 zBZ~@K1b`r~=k;eUcPuh6GrQGogP4eR)uP3Ba}z$4(VObR)z;#AQ%kest)67ALAa0Z zoH@M8uB?pSu7P!$aDC3LthwiONFbxn&fuLV>B^j`HO67TE>Mc0t3^`QN4k19&LOylLQp%BK4}PlkmP% zXm|N~Jq09sHHg=|s<=EI0dbRHu-GyXOzXo;@wkg@_;zpnUq6KA34TF9*;F;&ZB@xbucozrvbAN~aeSNs-ZaQs*k4u8r5vpD;ysu5z8lmuja3(U z+e}8#8{C0JYRmPCapJ?JHREb%A1NOsOOFDAv5*leje$wBv~2P?{{HWk_2Xe(1aL6K zRbxE$&f!YBepqDztrq=^I%zu28S`$HO4Ad9@w!XjJ1^)_9$(Ro=Pa4QJAipi6 z-(QPgiJ`Nn*UcwK9{?8K;gOg>Ww_|qeR)5$=!-ukFHfH^&%Ryw`Agvy@PAoWafZKt z@*NK@_PR2wsiEO~E<2=mu1$e`yc;^Z^jU?!iYmt>Si&Pn%(7Y_Lj^N;sDfZkL(GjedKtS;DnBl-QDnhx!BHV>DI6$c?b`h>pOz!16Y0b1{Uux zzwDSlZ}0Bn3TMeL?;5cGu%tblecc%M2l|XV)Y9*? zKga!6P?O9iadgPqCe9pO2E?~#O&Z)1j^!>7P8y*e!RUkh$giT_r~k{ngL3p1X~)*^ z-1lmZ!HF#{Beqgs^hIjHdJ#%IEn}QKH!(_^ z0c=$VhX}CNug}ixX%VbW&(T>s);ofkEU2d}~Sn2d;<+nPPWdp!Ky$;!^3 zBf_=xW3K|d=9?N0e4D04&Fly1pjc%!731K6f)x>Q2fGj(vlwzx}8Q>m|1@v#E(jW#6xg~*G~4q9PY zJ6T{QPU-!*xXZ4~0i>D0iYOlX_5J-F)N|s<+7Df;W2!wXkepP;gRkSgw7NPkgS;!@ z0jt&)eQPkrM~ZcGv$EHYjR-zQWqdd7Q#DXZ!CYq~ETRov>K4#G0C}rzJob|4gVTFI zG=a{`s9wmz)C?KynCLJjhd zaR|}NiJ3WBBu?iy%f37!L^qn>y-CUp@bl-xg+#791Cp>sA&Xs0l!`bMYES>tWeWjP ztnX73r}`2S;@C(f$lS(8@#@}4%-w1)9uo_T`OjDK@VK_ zHB-=B>xhx1z#)V5$6t%xEA*F5;k6CwhusM`Z$-AIzLV!4GIiO5KI`zJL6$0HsnWK*{gxYC1+q67#bqNA6}%7%Mkm*9-2jz+4$$=b_e^xbl*+z6BL z@&KMReG)CU7i1>xhTjCReRQysV^?9(c}FR_OzCL z{rczX@>R8q`~)|j3t>vD?S+EktFB}WF+AdN6|7e&J)zdD={|X$#~d{zpWEi~ z!cKtf_d`Xxba^uOE7dX(PtVT}#vEpvwq@@;S(EY<@qy>-n1 zkRm1Rp>3)dp_#ybf4lt_*%!|H1|^^3Xgj?ptxNd9{S?`54-{kyJ0sQLm)DnUR`79g zqhhUe?+O20C4d-qz-v}t&|{(6@9*^C_~aAh<<->Gl&Q}af+kJr>1wREcltRE3vIY4 z2&Tp2B48P!>tY|-S(K!O#VQcKpkGnMyoT~h<9*xSUn?gc7b_7wI{{|Ta8fzO%$|KG zct(iY9v6|OszyGIx{{)2^$9072PdQxenVxSh!7Rxq6ZUS-`4Hkc1CFfF`8T*%Y3cC z%MtEYt%i23>V$(i%mA6Quutw!Z4T);9g>sd4U7y`;on3r|6(n^PIW;nLv4ULGxKwM z(&+ere5sQC>{c{AC=Lt^c~|(Pq=M7(0_~O{hnHYd62$%DkYTxdR0d^kn9hW$XmA;M zF%v>!7ziKUggwZvzD=Bz75$r-wPRnXy*WmdrmN@ESpMjp$n$UTH}!OtjanJHsh6Zd ztPh}8iM5!H2{4}eu9Z^2B=M;bPL>i^5J zRUT;7QcA>M7B>6n!1V zr_-Gj9pwNoKfa@InF;4+q-@;o4LD`aSwr|0<)Sj>A}XqL#?5vToDljyLk=U{B6rg( zuE83b!X)%neVQpqxlH&mK9a<$U#@wNq_@#?#LuzAsk3@}k>&H9*Kj(-&N^l$xgSep zVZD)}S{@@keZ%_bNFko9hbl(^JOK%>&pgMM05ddOCGl#N8Fl$JN@rQVh$ho0U^3A1CpoCDWel4F`QQ64#E_f3{EZQH z((sUNAmEOVDDBox4uNBzUDqC)oD4zMWY>S;V0=9OjHOzgY&`q!2OBSY)Io#*uo_~G zF~5Gh`HtCL*p_?67>QUWh;2u=GL+&-E&|kauB{r>nqW7AEZl*?{H1OOB% zsry11KgFJ|^z}JOWp4)I`!Wn$vZh`TjT+^Qnp6bn*T*{#0`5>FKF3En*J+)}N{I77 zF%O>9I=hC9)W{#E8@_W1g>>}av=`QtE(f#E!HL?;7Vb*I%PV9!u?2Wejue6{?cyw{ z+Ikaq6yk-*C1EZia&_Lg`7E26-*Hqwonx8l>b@DFNYBrgIO8^m3`~WM-#Yiq_`bGxyY~K`fjVNK$BY0?fvh}}CZ=8Il?%7QXiMrVi$QyiWkJZN4 zNr7zz?@u?YL1K={X(-1=bayKne+fuXjJji{^CW-^`)gb-qck4<>&f`m0))rn$C`~4 z0(x`c4hUc}bQ9e2XDVB(ZeASpqGJKl^bmAce@<|))eFce%{R_4F9DAa)|{UvE~K(F zExnSr80hTaMuf`xUCM%?A|1hw7xnTUV3`WvXkC;F2bYD2lvlt$26_p3x=PrIcnX7j zWsv^w`klj}D56foYvt8RV_Na6nvKE~k0>L1)J_3=Vm7Z^<@-3OM$;j z%t?)!V^n%iCfwh(O2ovJ)ul-uD#XWkigp2CRHys2T+fY)7&mC*xB*BrKbjoQbl!uM zOBEGgfV!906c?3)l}v7an6(;3iuhBn5)u>GinmF~j8x?0)UG8B{noYd8@cX1t>eXu zlu7}0FG9#jLnE83n9E}$Rk249JazDPt~Ua&yqZgpISoZS>UESPTnO*q^X;r|{k`j8 zK+X4qRb<=DpGh;r{-P9IaNPkHG&hzVWz2h@Jz4rJPbVI1w=l(Js!558!&q2QS}J$( zL3{rDpvNl3yf&-C@BnkpPVybb4bPxaAho@hvL#y;Eu&8#mr~lw*j>#Z?qHXIAjrh- zGAm(*ahvhn!5puRKjpv(?f0Y!Rv8)jGVCT(r(nrz=)Zh<>2{nC2pu0Qz9_7RT?BU2 z^pTz~--5IWFuWkP8cR#dwcmd-gE4-rav7jCzxXo!jQ>!uKi1Z$-}a6?BJ4Rx|H`uU z;ci3xbdf?uvKrc?SUReXyGwwV)JaJJx@cB3D64&LR-3%|;_)b`Xzl7-!-?qWA}@wk z95fRSSs7pkbM%4VgpH9vY*M&DqcHbh@@E$oXTcdB~e0i2o8t&S(po-W&SR6CKYNlD!<{Llq(Kr9oGfQH#VmC=Vi zcVtlG_kcp08+xqLWBR^1j*3~cV?$cM1%UcPs>&L+VM4fUO}aV34|sZ7QFgVZg_hS$ zY8uO_DXPXVID%J#sm0V@o6(fe8 zs`{UX`4xjs6ZYP>?&f*gky%O`6P^c^Jd}4>MlF$L4z8?^uRB-y>KmtwU-8QS`6)fX zgv~caN%n|aI|AtbifWS z)i3)*BgGN<@*ZTtk<;7lv|+1BT^4AA2e#2=oK9pv3&eTK+C#B1;>Wm$j}klaYMt88 z63`m6GBUhJY9G;dBX?8g3<8_jb2B1Hh#XGffIDkh>61ngXn?)%b|wVDmjXHwi|o&; zbDv;xQB&M+-mrfAtf_rv_gnpUBbJN3#D!ucWSMn!50E2E@IQOQt9QCh;mwtVe<}&h zUmfceH(HnkIP_97$xs$e=+vE=uR||&RW^6dva$L4dVTyr2lCEbJfr^XE9An2M*p&` zFg@LMl!=T5HXpf8xk|Kk1;100GyMH~7%R(D>@5Hw61#G40{;F5@4&Y1I)`d81oN~L zk}|9SvGZ#CR#piP~CNGWKFNb>d~1R?ttQ)2}ZJ$}MQy zP{ERr@(Fn@{D^A&)mDnpLUsIatt_A8-C&-6dXDSE>2$^=6PyHdTAmT0$HcV%wYnp` z7p-nvt0--X4!0IO%LzEylD$!j8cl8}D5AP_^xx@+LN~HQcbzejM5+FVypCAG0uW9O zK74qRs?F;KY1F)LS%_Wc!Y%OdAcrO2V-7n)oNa-pcz+M_kCT%sG@sfTgPPgHL*M;MBHj&!20-uT?Az6FqT5W+1FCcRRpz% zd~{QqN2Qa}ygff{wkFCZPzns2!mT^SZtu?uFW&`p^7dbw_9{tN0&NtX z9D%qg62VT9t0m zkt8}qmPVBR3+O{qyr!?gmw!SJ01QA{vBW zv;VFWx9g1TV&?PFTBDn(y+kF?2;JuC7MX#i_6dv3$hjC4qt4K@p(T8KzRi2S*u}fA z?YT|(L}v#1ZG6a6^WcU&Z)xf5a`XF%HIVkVzz`OOQK+OY8}`+R!GUAq%b6!5CCc1| z)uMJiU9IqLLj!Yql@>yL7Zry2xZ*$Ze~2}ltvyWByffoj8)h(tSp!=6Y{ zJmsJz>-o5)wh?T26a@}yHOsC0h$BLR0tePVgN`!qT4??G+0YA9O~H$VJF4MwnBUj` zHK(N9tXPunJl!>mWp&}V{dN!Uq{>jk^>!t~;mHk@@4w&}ZogIC|2d)3mD2;Kpi``2 zP&}n?^pgUY>eiSf&3LbSvkO?GXd9%ezdcX;!=e20M49J!Md6s;kA*bib(DGnK|FcQw3}lmoyefG9H936pn`~~gRBlbrk-c2>Z3d#3 zFa@Vdm1=o?th$U6#(OutfVmOo%4bGriqur`0oAtAb?kP}?%wH4d&Z{y$l3NCCrzX_ zQh5cuMPt1L`N=Wwxt*Olp~aK?!H!&~6_TM^H|i&TcDW?;(y+Auco0;ctN^j|Z37Yd zenDc$AQl7KWIHF2vtnqVk%7){U${(Oe0t-3Ok{gY;k&1p8 zW|2JM#m7(i@8cuP*&;r1wOpq-6JqwSfH%Sr`Qg{taYBvUAZn=^FcXj0wWV<|=38sL zEY>nI`dQ${wBn$9m4kgRoVR)NWB#ydBJK3sp8$KmHD`^#Tm0d}qpHgIALAdbrlb?M zm(P#1*U$bKAuLFz`sq5ldU_@o==38LL4V9;2DZB6hPeA;(87g%z7#2+%K%j903(2? zN!@vH@qWlZrKtZFn%(1TztL@AUkN|7+nkov!(6_FYGs*bFaqq zhw_-Z|0(4<8ZhWeuCAUsTXV`U&R5K<3l6TRt*`JnUK06P_$30yD$niWbG14%NT8@4 zn4%zqbrZSo-^=F32-AajMKuO*OEb1&LWk4`;zR60z^VZB1cg~U10!SBl=18av*(xU zs?>%uZN}#<_p$HQNte3edlJ7Q3ZF){zQxQ6`s=)(V3!yYBcxn`Tl9SQbbWiD1MVDT zt@b*p^`h>*Zr6VWldDm642G&AP-TrIaFnY2fwgGzFND-tDDD1yFXe?27CWa3Nc1|z zSuqvzD|~gE`o7ehC>a4nbVp%1^iSM>B%XV2QdSa%d$&mc);$4H`|x04F}ANv3=zh} z_DiIjR{=WY-tJnE>RPZ(SA?;@1f#V7In@t0l=t#gwVKuif44#a{UT(f^V%?6ZRhPP$$vM@I+b zKiRbs@btfa<<%K;MGoeAL0$bqeMb*74)_ zkeYEnIEi^YM?{!|X4h~a7ADWd#XD#wXY2;uQIc+MZs5kDKsF{0|GC6BRf<#VxDzL$ z&>`Jg-vZs?8!sXsKo}*Po9p=184w~=}Z>|w!qr0N1OL5RN#B!^YS_pDQD<(t=mTGeeIHm?K$d3 zIU7EIX0Sf{a&|^dE3z)gs%~eu4Kya~*m>ggob$}<&&t?Rtzv-^U_G=wi`iKv_4+&) zDxQVB@i^=>*+)2OF-hQda*oIqTQ%JNW>RIJ8nWlugWC^En!`5;WaYMrzK+W;icBjK z-(rABa1vQ77}DW}p%_^)(qtJEYyWUF-j;j&mt%`^aF_RWLpztd@`!yox_g?m3e_(* z`=p1<_F{8X_J4A)F;4mqbm_^}vyW+fz_>=rk}a8Y@Vn_9 z&pI!i$DZEWU4bb}%bpEsA;Jn3Hr_fZ)ZB}j*1p*{Ffib)(ITgm#O=0sd&g885*z>Y zvK6OtI)ylP7C@*gnZCaL4sH3^v~}j^@)z)iUU|)TwDQvrIqNciRsvx8woH5y=-nvB z@E9-2?w80#?D|T4RENzwwjxT%eh-y4o3a`Nc84yQGUA4yWrZcvKy2Smgh~fft&Nrw z7 zI3=I|k$7u}9vwI_9Owr)^-bZ};DLRCf@XuyXMhjOM;fO4rg`{queyrTuePJuCdjud zuItp7(dXO={_Otc*W7$Bn_t2<1&!THclS2KjNmipDIPV!)E%%W^X~sC=el#Ye!j^I z;A`j34%hB?y-*vi)X(+-j-87N3bfo`m+g5BSVKWg`;mpIf9Va8YW$lwm*HsKJ%NPk zZ+oC(!;w6aMiwm|y%3X4qdnK99Q87fPBsVY;&gn%cFyI4umXgfe{25jf0`UQdv8Jy zIJZ$UryYEfKDZ2G5OzOliOp~Jsn%>n=+`M#I~-3A;1EIcB9;Qg;|kh8GMpAz))Hc? zg%l{0^R6wiB#M8E4C$&28=NJ@Z{CXUo`=T@9wI|GN`<1{mWMvhZvf8b5!9e6ZiZg* z%B#<<#!mx_?*rIhebDharkuoXUo+ikbPu;K15tQ}Pg${PDorQjhBe%Jc)L5?R;TW3n)wDby!ikbbHSkp7K z+E0v2eFW0%Ss_j~yGRQ*FlnnL90no+I+fc6EUQR-Z$DH=&H?=V!dE_RI{#eUek%a3 zOLl7bJ94@V&n_&4jfVNTx#32khdy_o5|fa`?(xIG1mtbm5RkWHAta0OVUq0--6poh z25+0pKOLFqZBCZXBLrTKY<~P|bon7dT$+ICY> z(dv(?ZOH>>SXNbrpvMWg%2+4F8NASC?Y=CbosO5I+CMtgkeZT#Bb{9UJ6EtL)qHa< zDZpWY|1b^f9CN6`mM7H1yO!q7=b25P*_)g!K`AL=njq|}K+2IV9w^E{_&GpCDh$Gj z@EQBmh^WXY?U>cJJ3u&tmKt%Pt)!5svs>x|52@)Jjm3IG~d3NNUQ0M3k|2Xs_Tj-Fm4^QfvBG*_A zJGz@C*}iJkewq9f@P?9|@s#&LWx}kk>uM6pR-8Pn>Mr_lc$0RXCN4bD*dumprXZ+c zc|g6cZtJOLjk1Z!GT0PkX2|Xb*B=Z>*itZV^@GVRW9sPcBG%&TC#zAe&}D$Wiub5L z^ne5=;`Q}4>GL3F1trkp(qB720aYHFGBeje`7Nqx<9=gb|5vAirkbQ+cTvUUw4F;@%FGF3BLKCebW>ICu zZ%F;{@|lq`%-k+hJV+5G>4SfaHfoFOX@QyWq!CRtun&O=6YtUx6L%&0pO4Je5e6L& z#RD}$PT;;5o=`*o@nA?({Sh-KN>-X#4tx_8SCU-}`81FA-dy=$5PL^3(8jc0K zOs0Y6Sl)F_@dG#-l&eg!^urUA)L^4I_TXx5CkKz;iLvUx2HcCCjmDL*;z^^P_W9eT zr<7Rgy2VqH?!SdJt|KIM#DzzMXgfO+Ic4_LAn?3B*5E$)w5oDVK(PwsZ>Ij*L#KVp zP`_f-Fh1~|BTXK1fq|6Vuv-GjeWURHbE5bJ2+vC)OW$gAU_vo0OYvtWi+uO-&}-lt82prn>%CDspurY3QblNRXHGg+ zBqUadSp!vMb=yC6&FAZ1daTjr16E2bfxGxw3_`BO&RoQ(SGiKEpX%Mk@SCMAXTOKO z)kOd_uPEk*g?>fjrtdBM0c~(s_%%&G!54$ofZFHE6;)L~R$;d&^t>ehO2XylSs=gX z)VK)3;gO5l^vH`dH3`^tUVp0>@l=mO^4mtx1!j=Jg5k?p7T z5@2$zwJeOD}{KP?0PEUM^7`b2(F=Z zPRB#B`@;ANUwuAmvvn`+By)SyX% zN#3gGy(n25od^=va^_0$#F^m%*(p!z=xltDFa)$QJfcL36eq5a;+Z~=55gbRU`HC< zQl8*r$3?()auXg@ux9+{j~a>j}?>Fqw z^4Fw5_->9VUeHN~SI9Q=bA#>)W~DFCckPJ_E09kxwFEMijavQ+d+1bRvL~8upt`Ym z%bGb_9A=;LIs~2g2&I0 zQhN()zLy5~=xZo9M3=xwk)N{)4o1kP+t-2^2tqGU4m0~2mf8c@ywG<0?_jDs3XyEhAZJPOs!jltf&0JJ$hM7%8-Wh5>J z5N>=&lm#=J&NR3?NRwS^qapX-8YCA4>oYwoF6-bAEY(L{RGXzAk>Di-3mNQ`gO--` z-^)GHShF}_!Px9OR`a~HHUVnqxP^p-)AnQFi@CQ=Mux*A%ma42%AZ++)-7Ar@Gb2i zi?-(@k(*s5JYGniIlgy|^%Yjcnzopl69w&AHp}ny9sEme50E$TM6IYz(UTU5gwH1g zi@OWi*-(o=L8fd&j-R7zY;?B7K6~FpoyW0b3K{^-%R~|LmC^4dA%$Ym=QuA>QdYVE z4voE7y>MiI(k;{r6ZuO<1}ZVTu5|)=2-GNfxp>eqLhcPaMf!&>kSwql^X~0hW!5NC zHP0?JUqvAKD~Rc}c+x~0pJ{AA-SePoY8@W78Ct6T*cezOVC^|MyV(V6hNr7;!6G%C z@_xGP#z5$_t+ixwFn>YD6iz?|k1GYm#psH!?fy792W-V}-~3Yrg3|`%EdxdE#^Sh` z%CJicE9)0Y+br71qKrFF@_{)WoTSE?qTvD@vJb*0NzJJI<~vQ5Sv1;?!O zmYf*ch|F}!k9Rat2I!UOP3ylZT6XX8tZ^JacG~npE@fRtd?uI%WD2}|7Ejcnjd`J_ zW_mc!JZxGoJH*0!z|XO$e`uDqi&L21A zQslzCT*bS1Xj1-=3XdVanxq)ik;LhhQeGESUs194GGoI5aXUGV&lGr1$jhzhFUZta zVqjvre)&?U(Hb0K@8WIWH?ZRV!X&BW3BJj>q>d#d5!3bR}4bJa;ePPFzI$ zW``Yn`nR@IIu0gQ214}f%9Fy+-4-XDMkU)p4+tp_C=kB=ukm>w)H;^PBG2?e5rJuG z1h`k_`xa9P3Aomva@4U44wyfS)a<9>WJy%g70%V^*g;Md%)D{)o|5g-k}TzHb8R6z z=j5_8N;q?=J~>k;TelTdzqlJH#|#F3u1{`C#h#j);6`wW6MC$T8I^yxU)BPLL4)%; zcgoKum?VKI08LK2ra^L83<=-?T8ADqxEwOHj$iM9Srh);liu?~-d)%FkfbKZT1C}( zS%25`Bv}57>q%$!EYak-!5M9|D?7}_GORpI?&0R}XrQ&?jZ~GM5x*wVa^HLosjg&m zAeFWyyZ^P!oZ&7IiPP3J;No1L-ar02Ez3p(azDwZMCF%h2~7Ic9#7g=3l)HO`NY%9 zm6IGiYeH^%ls@3*pPoi8EJPuFaX`(598po|Ht}RXJxaiVdO)C=+ei2ndv81#lo17^ z4Mmp;_NffrJ#l2}E|+Kf9Bz3d$1vOaNQ&xGVk>xu3Bwk`(Bw)7x$iq>y+kbgER5w8VEV2_v$`> zLiciz5{O4oXQ-s|+PKi!tbXHIU%wL!z&nzgyp2zYn&s~Hl1%S|;?N(%kCyFfzf(`}jS`2Uv)myl zth(JF-OWxog5}u#%k?*Zf)n8pcKjxlPJ8#3935cNxV13D2bw><`tnK|vfpD#jn1(G zzkA0N#eN#DM>tjN+dxFg<42qyS)$d;cXwLrwR&AV^zDZz^JrhW!!@*xBv-6<_hMph zGCie+z=PU`6_R_u*ljdm>`F~+r(hSlcJ)b9T5b3gKy#pLm`Qs0nO;a$bqwN|IJ36I zBjD9@=HlU9haqb@3OsNZcfVj-Wz%2`N%B4%ZWCfxy@C*$N_3uwD#_Lr5Kn4z?^#8kxel@;*C={V!mnFYBeA{6^DEIwj+P>nm?mTclrM8vglUDP)|XfvKjiwE%yz=#keQ%3@Pofqaz5 z7UFuE@#Bo@*Q(AZ4!3Dj0(|g8NMe^hT}AOaoe2UPJ8fcUMSE_p5hl?=j@OydA?DcV z&p(?50a>SQ1C#EZ(TR!*n^bF}6pfs-UcXzQF8r?ak z>FUL2!g(lajyAQvAGE8eMvC`*e2~TqBYr+eT5^b9mi9)PL6>2<&>4yXLM|>sPM}~- z*~_cp#Jj7DrY5p^ahu!ePn^za$%i0(<_?D8w-BR^_VqnFpsFxMULG>3X)cp|!9EvQ z(8264wA6Nw7jeDgen$aue~hFP!;opvvsym%Bl~X#CzmD>Z?X&`By5s={a-}M&EJm8 zE)z!0x<<>AmA{>=GU30Ll9IT|FiipZZ4-K|65v&Nz@<`UrreQDvHH#Hq}3_KW3Rl{ zY1TDrbcNe`Lnk6TiXG|1_Y`whrq{aKwzwUD$I0%xV|>{tHa=R8vb5PI>BlNq@54pO zEfA1VADdXqzwisNJgRb4>sXZmm#%IOYCp507j0(I%4UY7pcsEHta{HrfzuOkluHEn)~j`|@rrQqt|iA4|x zx3&^NNQU$?FDIXncXG<^c!`4qv0nxdV%c94pKoZkZ{~3s2qos6kfIvgj*(JkE0{;? zufe{7K`dz%A2~TW$!)m3u~7noq4LA!E|rPRLw5`2x}7?OoVlG^)!g%u!tDnS@_Okq z80e`Vu0|3*YgXFrBCigMgWb|H$sClA-`D1dwEX6ow*J0sPjxr8y)$T5&>EaFZ+j)*R2FQLpj6SpFH<38m$_Oj%kdWw;$gEt74_WAd6d9+!rm5$`8c z`AYg$wuF@?kVbhHS+J2^vYpfiOCG};aq$qKGUkZ06UZ9|hDV@vZ#jt!(`uII$$9D2 zH@@@WDDsqCe%C1^(dj(1^ebde{%#cZ?XnN@($|lf$gqb<-b+8Llo_-k`V`WuRQljGWgRnYyxW&=$5fdxz8#G|WqWQkrBB`{T;1KZd`VzYKQ&ml#{F6ih z9j2&oIK`HoD%vc<_*!fyC3ZD{YhR+!Va%t@BIhTF$AywN7EQ0rdm?LY1y#hzC?{g} zAv_~;_oDbO4$BzrMMryBdT{gmSdO5k_NfP7v?Od$Mc}iN)Cd-``Y%qd9e#RO$~Jt; z&z2IRy8NBZT0^|IHZM1f5DTs2L!>Bh&BpvRLJwH%&AAfZrajafGR@dC`E4t>qwtNy z*_w9t;0EF8>%;e5anT{~HX9x+Sg9|4XLIP%SG0WVdU}%VX8$wh8+(%L!mIC0!-7|A zg<{v30-pG)Vo9}wvJw;?Lz0qx)XyxrD!tBqNzT~}$>Kp#4I2PbPv)qhvC!2U&}yO1 z6)0;c^swIjJv0>ctEl;iiE#wBHO&;Dqkx?)v~|{6(ocY2JU7YDc&7awF^{{7_35)fq+THv*XR}tPvwTB1ckF)sW ze`+jDiwB&-@kl@S^~dgCz}72OS>nIfs?dt=z^0I_(QhmokH)$6f&4zHtnF2KE#aG6 z*Fv}qUua$OzZVoxsxr+ld-s;e2VN8{=G_}JbY6HQ7N9hu9_MQ7mKvd@kSk6d&u)yx z#>3EZJ^ngXZ^v(LMW@_ZWbf4Aeq`T8{ zb|3FE|1d69Npaaz{UWI8wYcuYT_$*zTaMWokuK1OkCn_ip}@cV_|c<{%3=>G^L6zH z4}ew5O$xOIf89^hRc*OQb7+aKaZGfq#I?>s5n|{c!%{%}9L(`C-qSL8pv#DNg5 zaFMN$d$dpb%D}%g4)=Gi2S=6+KZStEH@re)$bve-ufvgkBuISFLg~#O~HoS>Q?pf@A?{b znNxWll!u|CByrmrS}EK?0sll6?7rSUtYOlwADCb?D$y!lUtZ45&sYBrn?=Up2X-p5 z)&IS5{V*TM8{`o@_gp0@^{w+Q3AY826bfm0bihcoOL4x$ZY+1!6D*{#{^!rzgsgL* zWutGsdU?|$?k+AaGMUx=_~cJVbTof_YCu$E?xW~}g(&n+9KlO-W&vrW!@JmWQ~~v; z*I-+Nk({`pvGJ0)larNIv4gIFZk%+E*@xmO$c)M0bh?}k`Llf>l@>wo-4;(k)+Cbp zt-$Yov?x2fyD!C|B!vZ*?Be__(3ms~N|#WYRTxTDLTCvbkpH^ zQ(no@La7C}PXp)WX|@F6wE3^tS^PdfHFSK>@Q4y#Wc6T)DfnVWF%8XT>CK+>84VfA zz@Jwt>cf$AG9h>N(RVyM!owvEgPPa=S%y49PFc%MFqQd!Y=yKW+`((Bt5O4Fg-R>+ zr^kBP`mhOYzNn~9TS&4wu#95(hH^1arB_2&R2Q)2kj##sqo3YoxE=mbq?y>EK4W$v z@GHugwC5D%V|WE{I)9+~k9mWTbIr^$=1_y06!#_!9KF0%wG&JYQ@os zX7`3uHfhFQegHAdUdbr(W>NeCo5a?o4lIz3#yxQ0De=5iTmtIv9B zaa0LlFVwHTv{;!`rPHD0SfL_Y!qt1jn}3-4;Y(}ljcUDC zEtlOF0qPa_FyfACd({;e_v$=C#W044v9J)&&DoxvWwY9lSbDQltHl;^Yfj%FB$ch- zWjW$^juszna&q$Su?K9#Uba7SpKQJ>A^}L&`XuA0d@~c4V$32fJh$6bT>Wv4xh%@{ zF^W;$i+bpvHbNWcZN)Ui%E(FoKdQbus;jhX8x;is=@#iu32EsDNofITL|TvrQM%(t ziJ)|gv~);^v`C9I2uMr68)xSE*5{f(be2n9=RW7&dtbGkvg=MuPfno4;oRe7IWVj{ z>=!+uSwkps^;l7H8b--Fc-|)tpLnA#F}~ExCp8?61mtXn-8w$pG}r%o#ucvw-=Rf` zg`x#)Xd?CTEsJ%>i9L}?>9onG@Ax@7lis`I+^5iKn_M&dZVlloi_1cjr94N+%20mG zfvi&H>ie(=l3OMS-bKk9>%f{xKYTWZ)`u*4_4>2bQ^!(O*%!N?e@7oSWp{Cb=Q&p3 z>Qvt3J9lxOJMb=~hSK@ZVEPfekzu_*kO=N++UBI3()z^0mk@*i_jeCT6UamS{QNRy zqZF_lKB-9Ea<)5hu#^*umJn2 z*1H*QR;xUE#KxXZrKOy6yz}r@DmxRmB4+|!hsiRFellB%yqa;XK}^{9omvjeThnInk_t3}o0IEnmhdKb0C6bh0XngvNk zbUli$(RW&Hhw@0plkxfXB=Y$vVoFtRBxWEaU-SF;6fE!tIFhV8?7D85OAmZbU?452 z|HiJSeG4ftDCmffugT%;b1bne4>f#l0?>cJX4Rv*I_;`2(Hh^R2@DcBM4>li_*0D#I1^5>YvDzGxrSb2B|&Xav=H*w!+y;<7e(a=~@!cj_d)$$F0%l5qf zPlIfZyzb2MW%@-*C(&J?T?C`f2JOhOC|tT+kuw3e*IXhunyaMc)4qFLUxiWeds zxQ#JU#br{F-m%(yWiG#e^GjK;kpNkf1Hs!UhvOU0Lmm7%n@$>uDfo+$LmkMkpEys; zY>w=RFh`JXyfpG%nVIpuu&q{Memp)iGUB{GoCas+Z`UkRvHlt5&DAk#)~3V z4vgxl;!hGGWJ6PBxj8wD7~eJyKySiX*u`qfn-WDPKwb3`u1eUunQ+`&?WC%J=kp7$ zbWrV$ri8tM8}aDi0LI%8%@m|p^YimE<;TT*bA8_{7opxRpPw4JAB@G<*-d}u6nJnj znDa=x#E`(tCLrHzoJJ^CxFxH52-}pC6aOjyE&1rrB28|)W`TSLwG(quOvz)GR#sLM zgh5|obdDY({XX^@xFEK^IiFk4n%xizqT3ElV zx-UqErshkz<($YH#q^-tJH(01z6PripFl)yym@opzWTiXN9q)(EO@yE97&=&;WQ?X z_g0GW@VHhS{tQyJgrg4ZL9mhhW*y|-yRGe-Cr2b8{pgCJfn&H`B5FI==$_)GR&p&~KbM>Z zVSBK~=@B|RV$0TA5G*|^n{ymV=O_OK;%@@qo#(I8PGr~3>C%OV zJ6aE(t?amcb#;ESzOFFKq}7?L6gZ`>QSP)*Hl8-V;Ub84X8Cqt#q;7jXK#b2$qjbH z`lKw(z^n6k`tK-Bh4jk7zsXe13CV<&zQd%&z}ZYGzJqWynjrQ}B}=&H7E<3g>y|8h-_8tSJTbIgdH3X2 z&?(_Y{x)3**-z{3r)v+8%2m`7v7n30HRN#f+Qs9}%8MoryNRx=7R0^aag%;MyPD%{ zQ;29W3ifQk!U6~+I`U}HuB|J1QbXP3uY}O4%VsR?3UG3Kpm!Y!7J$yqe*AVm0h5Q( z>Et-=EwckXi~Gc9XL|$Mc9-3Am*=7v)tB@;VoT3GM>m3=V%PhSVoKgeMv5*;wI8AR zSXp^6oUJ%4o8Xh4(+&X=1AB2A8mEWbL}b6SIlR{(XJDphvyS}u8YIueH~&&njGg-wuEoD0NHfTf9cNc}O>-j;<6^=SVjbK~F>%zP3H0(qGUbum9sJ zc1=y+m-y>bG&mPk!>E`@*l{uVwvT$pJXfWJ4{5M)(1^*HOvS)%Jt>CZ z%!EX}A_kv;{bKaPLKQO0s#!slugk`ohVP3xLZg+t7ZCG6i6k#2{&<$|8cb0fX~Il1 zqx5>*lI?MNtO@T8YIeIL?!KO}ZhI%_vc5W$xqf(K{nsxq2$*d@1j_5Eww9~vmmg2{ zR706zB-{xn0~bme{ZimzZ*CUzvP277vqAO}LG`z~&v?TAb(~9|SCK;gWG(nApxJd< zDNvY6cpxe&O7@b~K<{a`>r~_1u9T_MayF?6SExB2PAomdU+0dT*XQO|RPY>V#J+^S za%m*j{F`!E@&UjKmoE$qC@FudtU+Oq`e>x$kibX|XT9Cz@_gw~=*yRM)xV`ZFjlnA zX{j~Jm$j-IU?M2)4>r+pBv6aZ{{wWM-#c(yOVaGdX=B!;ZFr}&<)L1|nR=WQ&mZaG z_2WQ2iepA229eU66z-H*aei&qT2YM#H-RdfUj2h&drcY2y}R0fLaC+i!T~y%C8k79 zA;<(m-9K{?n7>oqrBi(x4qsieyq#q=KFqw{dRj6XnN%Gn>Uk)U3v5R%M6$Eg`k(7( z`7S^ed)U7xFW3mfB77>(>=Hf>fFq2~iNFz3cFq<%B2?_Aqm3l!twA*e{T&3~7ATn} zLlb(nP13}(oR4Mic;!886KU7?5}DhBe0-Q4J{-}->Wj3RS#GiqoAO?zwB*795q`>sGixS#|Z%tFAeoI3bl{ zdH_c8z4R_iTxavue@Fa$Q>YCsg66-ymWr{f9DFNskuGa#S2}n2`P#DjV-A0-y|!<% zajwrrI9KHzjp^C@%2}C4CDYT)+)U{4f68{qrKbs3Fue@IwBKI;WwP+=Zc?Ayy z`W&$_bFF=tH2=iga%`T|f? z`Nxl^PYz5oAVLnnTX3Wz`o#4-J?naxaG#$*7S7QFK1)+A`m&1htag**d6p8nEKs)< zH{bg`WX;(^=|F}ofmp!B$S!4NVn%Qe+VDbaRasSa6%!W$X*-=N?>@WlSxnYdvw~?} zU%&3z2z@fuCmNM4#mTHu@o?#+Sn=C<&*yR==;>{WhA_!9pqk-vBSuP8Ax}ocISpryELnvGnaYHo^$SDOx*=TeAyaJL-V?lEU!-&7;PqrUkpataN#&>eIn z)g^B!sSJ$udUW>gVWtC)(Z%_Wy%_jF-tPy#^a54D%cL3jEl-SLksKoIhYK{lEZHn5=tVDPQ~^~VzxqWBEc}|*|+?{@+%Jy z4`YhS>x2ezpUWd(BW2a)uDH`XwMyF>@&MG=f_8U_ z=s$3$0utQrvGG(nk6HCNX@2v4_6O*L01<(+R!tG0}t*^8GWd>a0;wG zFrZETVq#>wf%Ku@RN+zK%0v`}sI%<6qBN_$l!2X~orcpQBLLe)=W*>n6(Gxl=|MYD z#6R6D(g6y>kjLpo2rm|lF)4|1NeD(8lMye?Av!qOQOp0Hjb3`Ip5fHCFSN*!3;+5F?f z+)CW)LL6~}q3?d(-1*k!iGRyeqy&T2Gl>R8h4kq9JI!35jKBQk?5TOe9s-;IL}S`? z_k5n&vKlA?uu`FKwSz+BMD%<^-=5()Gi$Gx`SVt_HQ+Acs5^dL#_N=#1ZXwNdWpPu z-!@#6UEAB+KL7cq532_WX)nGwIxcQY_X8`pprD?nCf(SQI4))&2Y*fd3n4W?S*fiQ!(rjxOf3q~y;=j0@&Hw|MpdTCr2QA>e=^nDwa`t z)OWJXf_bA5iQSL#9L~J%uo0Btreog;Xy%l>Cg+EVwi}{MBx@3Ao{`SE?xb;A@%Txg z@hfAkM^9u_&E>n>6McT{dNduhmSWjo1jS0~GSC;{;Uzmf_k<84ef_Dk;_ofkzANMo zRO@(l1Ql*VH(!z6SzN?UCFHfC+<5U+@^#{aWEXRh+LvsZdO@hL%Uk6A_OWSa))%E? zcX!_-ZHCzIw}Q<9N{YwFx3RUIY4nC&O^v>njcuP44Gj2BPX|&3;(CZjdOQ?iRr1`Q z4n7#zsdn;;7#Z-SH!)e6-~6PDA^1Kuif9dyi;0V!09di6+%n!$w`yz@^_F=@u@**8 zo)x$)wgIEPXtzb#+Y1<(zu{xBhoeXzlX#|(qsmbwA#cEGHx=*V z^(M{zvr}cZ86mvf##(WF%)%#sl@fh@K)O8NgMT3X)6KekkH)lM z|8@^oPdO_q%OpiVg{p@`2tHX5il;UWAv;*Jxay>gC9NtZd~(rmR5Seb#8XP)Rz*p=ep5WuDAksw1CR7+WW)# zoLNi!+tX(xks4_NcoEnAEymoxl`ZDHtRU;$IVvtw=h~fOa}=&rDb!L^B46Km-KqG3 zr|koS^xdT(OnGq;{6#$9SGCilOcyey#9hX(7RsH9wPlprK8yg9HIq2&^Bi~{q^GEv z{Zqf~n=aya6O_7h#y6mo0!ag`q9?|^4>l>Z58_8kpc{Bh3ytch9>ba~`_WoYl$`=WeqPfcsK4{wJ zIG$jvjdG)uLCymbQm5MKzTUAy)ac;I2+cRf&AK40TsN-QfSt%eK#8^WXz?Sugev%> zj8F#q?5@a zR%`QtZDWngP^U|Nb455nmGP(_okxD4;LX_T=xjq4%8LtNM}Va*d3pBR$cRGqG}>=P z@X=^Q0W>8ZNxzn>$QSV7{c=dXO1`YF@)o*|8oeTP1Z5`f0&qiOIE{Cb$!(6T6_H^_ zs-E&xs>De=kZYCHzicH%zx*^~L_(URLGhpVpGFRuN zn_83KXUFce0}w8efK@sOP_G5=#|YU~cmpSsLZk<{B%xa-b) z)odWLDG^MRkyMhgP<+5isMwIDd&`L@d6bbnNK{hHslHUKDq zIueuy2_GJ?7Lm6&p5-YRKd6|5esHGA*T_K|K;}?}^4QJ=_xZNlA=jXe3%VW_t+(d| z1_s@%-fnZ^+CdMH0DH2DN$d7euY5OBvn19-#P^y-02wzn@IHnHL5;{p{@(=^Uv@%~ zrOMwyHP$RaA7RlSAE(PS8P%;rw)vX2@S#GiKh0SeG1H`+lFXVPlkFFLHns(4ZgYB| z^iS4?{ea{?b-=Mr`<)@uDan}i`^T##vobuFTJy^No__O!9#ek_#F3s!@~VCkE4o2| z1dqpz;%a87;LPY6{Y^pj$EdqT*{qV`?eN|k*jc|P+@$I%YrfySLuv0#S166g&8EUr zTR#g(O5t{5waCR7N4r8+o^;8${iOu#@Pf^n!!&kX=2bS!+tZ5P3C~Zzy|pqRDb>;% zy12LUHSN)6Ju-;)VP4)htRsA}cyw_#p)nwwGClE$RpU5&u{{MYBzP5}1Av`ev=4Wo zgSEHc2L3zWgeaadZRI9Q&)M&I?Y5ro#pT7bJ+LqfMd0ro=X;Yj&1NP|PEFmc9v>Yw zlZZ+O{>^abYrEyZy9p@bJ;xtDgXuM@lUs;|hN%&uRY))`@@Fjjzyq2KFV-qjFstP7+{ z6?CJ1R6iG1)m!|SZp@cmOqJsNQgW7GZj<$W7+i1)a~!?`4wi1e z4>wP%Zqtnv{Y{$-w=l_=Ps*CsOP$b7mZk9KY3MBkG!kBTJ(Fwv3h&>~ooDjBd{{

v%-vroI;v(wXeI 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%0D=NQlm>;UVy4|pA%s_wU8mxf3A!mKowzyXK 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 z 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 Date: Thu, 23 Feb 2023 11:55:50 +0100 Subject: [PATCH 089/122] add to main text --- demonstrations/tutorial_pulse_programming101.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 54e6f124b2..5b36872dc6 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -12,6 +12,15 @@ .. seealso:: :doc:`tutorial_vqe`, :mod:`~.pulse` +| + +.. figure:: ../demonstrations/pulse_programming101/pulse_illustration.png + :align: center + :width: 75% + :target: javascript:void(0) + +| + Pulses in quantum computers --------------------------- From c6400ee9beea6524074da4962457849e6b6064a8 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 23 Feb 2023 12:08:37 +0100 Subject: [PATCH 090/122] added abstract sentence to relate to picture and moved reference to VQE tutorial to VQE section --- demonstrations/tutorial_pulse_programming101.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 5b36872dc6..3a66588836 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -8,15 +8,15 @@ Author: Korbinian Kottmann — Posted: 20 February 2023. In this demo we are going to introduce pulse programming with qubits in PennyLane and run the -ctrl-VQE algorithm on a two-qubit Hamiltonian for the HeH+ molecule. - -.. seealso:: :doc:`tutorial_vqe`, :mod:`~.pulse` +ctrl-VQE algorithm on a two-qubit Hamiltonian for the HeH+ molecule. The overall idea is to continuously +manipulate qubits with electromagnetic pulses in time. These pulses can be optimized to achieve a task like +minimizing the expectation value of an observable. | .. figure:: ../demonstrations/pulse_programming101/pulse_illustration.png :align: center - :width: 75% + :width: 50% :target: javascript:void(0) | @@ -196,6 +196,7 @@ def qnode(params): # Variational quantum eigensolver with pulse programming # ------------------------------------------------------ # We can now use the ability to access gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. +# For a more general introduction to VQE see :doc:`tutorial_vqe`. # First, we define the molecular Hamiltonian whose energy estimate we want to minimize. # We are going to look at :math:`\text{HeH}^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. # We are going to use the tapered Hamiltonian which makes use of symmetries to reduce the number of qubits, see :doc:`tutorial_qubit_tapering` for details. From e8811cdfe6d93b63335f6fe06ebbb02e491f48c1 Mon Sep 17 00:00:00 2001 From: Romain Moyard Date: Thu, 23 Feb 2023 16:32:33 -0500 Subject: [PATCH 091/122] Update classical shadows (#708) * More * typo * Trigger CI * lightning req no depth * Trigger CI --- demonstrations/tutorial_classical_shadows.py | 26 ++++++++++++-------- requirements.txt | 1 - requirements_no_deps.txt | 1 + 3 files changed, 17 insertions(+), 11 deletions(-) diff --git a/demonstrations/tutorial_classical_shadows.py b/demonstrations/tutorial_classical_shadows.py index b82544f943..80b7b87d3d 100644 --- a/demonstrations/tutorial_classical_shadows.py +++ b/demonstrations/tutorial_classical_shadows.py @@ -198,6 +198,7 @@ def calculate_classical_shadow(circuit_template, params, shadow_size, num_qubits # set up a two-qubit device with shots = 1 to ensure that we only get a single measurement dev = qml.device("default.qubit", wires=num_qubits, shots=1) + # simple circuit to prepare rho @qml.qnode(dev) def local_qubit_rotation_circuit(params, **kwargs): @@ -352,6 +353,7 @@ def shadow_state_reconstruction(shadow): dev = qml.device("default.qubit", wires=num_qubits, shots=1) + # circuit to create a Bell state and measure it in # the bases specified by the 'observable' keyword argument. @qml.qnode(dev) @@ -387,6 +389,7 @@ def bell_state_circuit(params, **kwargs): bell_state = np.array([[0.5, 0, 0, 0.5], [0, 0, 0, 0], [0, 0, 0, 0], [0.5, 0, 0, 0.5]]) + ############################################################################## # To measure the closeness we can use the operator norm. @@ -435,6 +438,7 @@ def operator_2_norm(R): plt.ylabel("Distance") plt.show() + ############################################################################## # As expected, when the number of snapshots increases, the state reconstruction # becomes closer to the ideal state. @@ -520,8 +524,8 @@ def estimate_shadow_obervable(shadow, observable, k=10): # assign the splits temporarily b_lists_k, obs_lists_k = ( - b_lists[i : i + shadow_size // k], - obs_lists[i : i + shadow_size // k], + b_lists[i: i + shadow_size // k], + obs_lists[i: i + shadow_size // k], ) # find the exact matches for the observable of interest at the specified locations @@ -581,8 +585,7 @@ def shadow_bound(error, observables, failure_rate=0.01): dev = qml.device("default.qubit", wires=num_qubits, shots=1) -@qml.qnode(dev) -def circuit(params, **kwargs): +def circuit_base(params, **kwargs): observables = kwargs.pop("observable") for w in range(num_qubits): qml.Hadamard(wires=w) @@ -594,6 +597,8 @@ def circuit(params, **kwargs): return [qml.expval(o) for o in observables] +circuit = qml.QNode(circuit_base, dev) + params = np.random.randn(2 * num_qubits) ############################################################################## @@ -604,9 +609,9 @@ def circuit(params, **kwargs): # O = \sum_{i=0}^{n-1} X_i X_{i+1} + Y_i Y_{i+1} + Z_i Z_{i+1}. list_of_observables = ( - [qml.PauliX(i) @ qml.PauliX(i + 1) for i in range(num_qubits - 1)] - + [qml.PauliY(i) @ qml.PauliY(i + 1) for i in range(num_qubits - 1)] - + [qml.PauliZ(i) @ qml.PauliZ(i + 1) for i in range(num_qubits - 1)] + [qml.PauliX(i) @ qml.PauliX(i + 1) for i in range(num_qubits - 1)] + + [qml.PauliY(i) @ qml.PauliY(i + 1) for i in range(num_qubits - 1)] + + [qml.PauliZ(i) @ qml.PauliZ(i + 1) for i in range(num_qubits - 1)] ) ############################################################################## @@ -652,9 +657,10 @@ def circuit(params, **kwargs): dev_exact = qml.device("default.qubit", wires=num_qubits) # change the simulator to be the exact one. -circuit.device = dev_exact +circuit = qml.QNode(circuit_base, dev_exact) + expval_exact = [ - circuit(params, wires=dev_exact.wires, observable=[o]) for o in list_of_observables + circuit(params, observable=[o]) for o in list_of_observables ] ############################################################################## @@ -691,7 +697,7 @@ def circuit(params, **kwargs): # calculate entanglement witnesses, and even find a way to approximate the von Neumann entropy. # These applications illustrate the potential power # of classical shadows for the characterization of quantum systems. - + ############################################################################## # References diff --git a/requirements.txt b/requirements.txt index cb793fce5c..3fb1c53526 100644 --- a/requirements.txt +++ b/requirements.txt @@ -16,7 +16,6 @@ pyscf==2.1.1 cirq-core==0.14.1 cirq-pasqal==0.14.1 openfermionpyscf==0.5 # required by 2 tutorials: tutorial_quantum_chemistry and tutorial_adaptive_circuits and tutorial_diffable_shadows -pennylane-lightning git+https://github.com/PennyLaneAI/pennylane.git git+https://github.com/PennyLaneAI/pennylane-sf.git git+https://github.com/PennyLaneAI/pennylane-cirq.git diff --git a/requirements_no_deps.txt b/requirements_no_deps.txt index fd5d3d3aa6..2cbcb376ed 100644 --- a/requirements_no_deps.txt +++ b/requirements_no_deps.txt @@ -1,2 +1,3 @@ mitiq==0.13.0 pyquil==2.21 +pennylane-lightning \ No newline at end of file From 942cbb57e9373dc0630d19e3a1a94b1071553146 Mon Sep 17 00:00:00 2001 From: David Wierichs Date: Fri, 24 Feb 2023 17:15:46 +0100 Subject: [PATCH 092/122] Update SPSA demo to count circuit executions manually. (#706) * new version of SPSA demo * Update demonstrations/spsa.py Co-authored-by: Josh Izaac * simplify code, update outputs and figures * Apply suggestions from code review Co-authored-by: Romain Moyard * review and tweaking * make spsa an executing tutorial * move file * fix links * fix some more links * author bio * line breaks, undo link change, fixing them actually * links... * links again... bio * update to count executions manually * reword device executions -> circuit executions. avoid recreating device and qnode * print executions --------- Co-authored-by: Josh Izaac Co-authored-by: Romain Moyard --- demonstrations/tutorial_spsa.py | 106 +++++++++++++++----------------- 1 file changed, 49 insertions(+), 57 deletions(-) diff --git a/demonstrations/tutorial_spsa.py b/demonstrations/tutorial_spsa.py index d4dcd6dee3..3c313a49df 100644 --- a/demonstrations/tutorial_spsa.py +++ b/demonstrations/tutorial_spsa.py @@ -14,7 +14,7 @@ tutorial_vqe_qng Accelerating VQEs with quantum natural gradient qnspsa Quantum natural SPSA optimizer -*Authors: Antal Szava & David Wierichs — Posted: 19 March 2021. Last updated: 10 February 2023.* +*Authors: Antal Szava & David Wierichs — Posted: 19 March 2021. Last updated: 23 February 2023.* In this tutorial, we investigate using a stochastic optimizer called the Simultaneous Perturbation Stochastic Approximation (SPSA) algorithm to optimize quantum @@ -29,7 +29,7 @@ 2. The variational quantum eigensolver on a simulated hardware device. Throughout the demo, we show results obtained with SPSA and with gradient -descent and also compare the number of device executions required to complete +descent and also compare the number of executed circuits required to complete each optimization. Background @@ -147,7 +147,7 @@ .. note:: - Just as with other PennyLane device, the number of samples taken for a device + Just as with other PennyLane device, the number of samples taken for a circuit execution can be specified using the ``shots`` keyword argument of the device. @@ -191,51 +191,44 @@ def circuit(param): ############################################################################## # We will execute a few optimizations in this demo, so let's prepare a convenience -# function that runs an optimizer instance and records the cost values and the -# number of device executions along the way. The latter will be an interesting -# quantity to evaluate the optimization cost on hardware! +# function that runs an optimizer instance and records the cost values +# along the way. Together with the number of executed circuits, this will be an +# interesting quantity to evaluate the optimization cost on hardware! -def run_optimizer(optimizer, cost_function, init_param, num_steps, interval): +def run_optimizer(opt, cost_function, init_param, num_steps, interval, execs_per_step): # Copy the initial parameters to make sure they are never overwritten param = init_param.copy() # Obtain the device used in the cost function dev = cost_function.device - # Initialize the memory for cost values and device executions during the optimization + # Initialize the memory for cost values during the optimization cost_history = [] - exec_history = [0] # Monitor the initial cost value cost_history.append(cost_function(param)) - execs_per_cost_eval = dev.num_executions + exec_history = [0] - print( - f"\nRunning the {optimizer.__class__.__name__} optimizer for {num_steps} iterations." - ) + print(f"\nRunning the {opt.__class__.__name__} optimizer for {num_steps} iterations.") for step in range(num_steps): - # Perform an update step - param = optimizer.step(cost_function, param) - - # Monitor the device executions, deducting the executions for cost monitoring - exec_history.append(dev.num_executions - (step + 1) * execs_per_cost_eval) - - # Monitor the cost value - cost_history.append(cost_function(param)) - # Print out the status of the optimization if step % interval == 0: print( - f"Iteration = {step:3d}, " - f"Device executions = {exec_history[step]:4d}, " + f"Step {step:3d}: Circuit executions: {exec_history[step]:4d}, " f"Cost = {cost_history[step]}" ) + # Perform an update step + param = opt.step(cost_function, param) + + # Monitor the cost value + cost_history.append(cost_function(param)) + exec_history.append((step + 1) * execs_per_step) + print( - f"Iteration = {num_steps:3d}, Device executions = {exec_history[-1]:4d}, " + f"Step {num_steps:3d}: Circuit executions: {exec_history[-1]:4d}, " f"Cost = {cost_history[-1]}" ) - return cost_history, exec_history @@ -269,32 +262,30 @@ def run_optimizer(optimizer, cost_function, init_param, num_steps, interval): num_steps_spsa = 200 opt = qml.SPSAOptimizer(maxiter=num_steps_spsa, c=0.15, a=0.2) +# We spend 2 circuit evaluations per step: +execs_per_step = 2 cost_history_spsa, exec_history_spsa = run_optimizer( - opt, cost_function, init_param, num_steps_spsa, 20 + opt, cost_function, init_param, num_steps_spsa, 20, execs_per_step ) ############################################################################## # Now let's perform the same optimization using gradient descent. We set the # step size according to a favourable value found after grid search for fast -# convergence. Note that we also create a new device in order to reset the -# execution count to 0. With the new device, we recreate the cost function as well. - -# Create a new device and a qnode as cost function -device = qml.device("qiskit.aer", wires=num_wires, shots=1000) -cost_function = qml.QNode(circuit, device) +# convergence. num_steps_grad = 15 opt = qml.GradientDescentOptimizer(stepsize=0.3) +# We spend 2 circuit evaluations per parameter per step: +execs_per_step = 2 * np.prod(param_shape) cost_history_grad, exec_history_grad = run_optimizer( - opt, cost_function, init_param, num_steps_grad, 3 + opt, cost_function, init_param, num_steps_grad, 3, execs_per_step ) ############################################################################## # SPSA and gradient descent comparison # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ # -# At this point, nothing else remains but to check which of these approaches did -# better! +# At this point, nothing else remains but to check which of these approaches did better! import matplotlib.pyplot as plt plt.figure(figsize=(10, 6)) @@ -302,7 +293,7 @@ def run_optimizer(optimizer, cost_function, init_param, num_steps, interval): plt.plot(exec_history_grad, cost_history_grad, label="Gradient descent") plt.plot(exec_history_spsa, cost_history_spsa, label="SPSA") -plt.xlabel("Device executions", fontsize=14) +plt.xlabel("Circuit executions", fontsize=14) plt.ylabel("Cost function value", fontsize=14) plt.grid() @@ -316,15 +307,15 @@ def run_optimizer(optimizer, cost_function, init_param, num_steps, interval): # compared to gradient descent! # # Let's take a deeper dive to see how much better it actually is by computing -# the ratio of required device executions to reach an absolute accuracy of 0.01. +# the ratio of required circuit executions to reach an absolute accuracy of 0.01. # grad_execs_to_prec = exec_history_grad[np.where(np.array(cost_history_grad) < -0.99)[0][0]] spsa_execs_to_prec = exec_history_spsa[np.where(np.array(cost_history_spsa) < -0.99)[0][0]] -print(f"Device execution ratio: {np.round(grad_execs_to_prec/spsa_execs_to_prec, 3)}.") +print(f"Circuit execution ratio: {np.round(grad_execs_to_prec/spsa_execs_to_prec, 3)}.") ############################################################################## # This means that SPSA found the minimum up to an absolute accuracy of 0.01 while -# using ten times fewer device executions than gradient descent! That's a huge +# using multiple times fewer circuit executions than gradient descent! That's an important # saving, especially when running the algorithm on actual quantum hardware. # # SPSA and the variational quantum eigensolver @@ -398,14 +389,18 @@ def circuit(param): # This random seed was used in the original VQE demo and is known to allow the # gradient descent algorithm to converge to the global minimum. np.random.seed(0) -init_param = np.random.normal(0, np.pi, (2, num_qubits, 3), requires_grad=True) +param_shape = (2, num_qubits, 3) +init_param = np.random.normal(0, np.pi, param_shape, requires_grad=True) # Initialize the optimizer - optimal step size was found through a grid search opt = qml.GradientDescentOptimizer(stepsize=2.2) +# We spend 2 * 15 circuit evaluations per parameter per step, as there are +# 15 Hamiltonian terms +execs_per_step = 2 * 15 * np.prod(param_shape) # Run the optimization cost_history_grad, exec_history_grad = run_optimizer( - opt, cost_function, init_param, num_steps_grad, 3 + opt, cost_function, init_param, num_steps_grad, 3, execs_per_step ) final_energy = cost_history_grad[-1] @@ -426,11 +421,11 @@ def circuit(param): plt.xticks(fontsize=13) plt.yticks(fontsize=13) -plt.xlabel("Device executions", fontsize=14) +plt.xlabel("Circuit executions", fontsize=14) plt.ylabel("Energy (Ha)", fontsize=14) plt.grid() -plt.axhline(y=true_energy, color="black", linestyle="dashed", label="True energy") +plt.axhline(y=true_energy, color="black", linestyle="--", label="True energy") plt.legend(fontsize=14) @@ -448,23 +443,19 @@ def circuit(param): # ^^^^^^^^^^^^^ # # Now let's perform the same experiment using SPSA for the VQE optimization. -# SPSA should use only 2 device executions per term in the expectation value. +# SPSA should use only 2 circuit executions per term in the expectation value. # Since there are 15 terms and we choose 160 iterations with two evaluations for # each gradient estimate, we expect 4800 total device -# executions. Again we create a new device and cost function in order to reset -# the number of executions. - -noisy_device = qml.device( - "qiskit.aer", wires=num_qubits, shots=1000, noise_model=noise_model -) -cost_function = qml.QNode(circuit, noisy_device) +# executions. num_steps_spsa = 160 opt = qml.SPSAOptimizer(maxiter=num_steps_spsa, c=0.3, a=1.5) -# Run the SPSA algorithm +# We spend 2 * 15 circuit evaluations per step, as there are 15 Hamiltonian terms +execs_per_step = 2 * 15 +# Run the optimization cost_history_spsa, exec_history_spsa = run_optimizer( - opt, cost_function, init_param, num_steps_spsa, 20 + opt, cost_function, init_param, num_steps_spsa, 20, execs_per_step ) final_energy = cost_history_spsa[-1] @@ -476,15 +467,16 @@ def circuit(param): ############################################################################## # The SPSA optimization seems to have found a similar energy value. # We again take a look at how the optimization curves compare, in particular -# with respect to the device executions spent on the task. +# with respect to the circuit executions spent on the task. plt.figure(figsize=(10, 6)) plt.plot(exec_history_grad, cost_history_grad, label="Gradient descent") plt.plot(exec_history_spsa, cost_history_spsa, label="SPSA") +plt.axhline(y=true_energy, color="black", linestyle="--", label="True energy") plt.title("$H_2$ energy from VQE using gradient descent vs. SPSA", fontsize=16) -plt.xlabel("Device executions", fontsize=14) +plt.xlabel("Circuit executions", fontsize=14) plt.ylabel("Energy (Ha)", fontsize=14) plt.grid() @@ -504,7 +496,7 @@ def circuit(param): # ---------- # # SPSA is a useful optimization technique that may be particularly beneficial on -# near-term quantum hardware. It uses significantly fewer device executions to achieve +# near-term quantum hardware. It uses significantly fewer circuit executions to achieve # comparable results as gradient-based methods, giving it the potential # to save time and resources. It can be a good alternative to # gradient-based methods when the optimization problem involves executing From c8ad5e329c386a292d0269e1c2bfeba9f58b37fe Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann <43949391+Qottmann@users.noreply.github.com> Date: Wed, 1 Mar 2023 07:48:33 -0800 Subject: [PATCH 093/122] Apply suggestions from code review Co-authored-by: Guillermo Alonso-Linaje <65235481+KetpuntoG@users.noreply.github.com> --- demonstrations/tutorial_pulse_programming101.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 502cf414be..5a2117b08b 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -24,10 +24,10 @@ Pulses in quantum computers --------------------------- -In many quantum computing architectures such as superconducting ion trap and Rydberg systems, qubits are realized through physical systems with a discrete set of energy levels. +In many quantum computing architectures such as `superconducting ion trap `_ and Rydberg systems, qubits are realized through physical systems with a discrete set of energy levels. For example, transmon qubits realize an anharmonic oscillator whose ground and first excited states can serve as the two energy levels of a qubit. Such a qubit can be controlled via an electromagnetic field tuned to its energy gap. In general, this -electromangnetic field can be altered in time, leading to a time-dependent Hamiltonian interaction :math:`H(t)`. +electromagnetic field can be altered in time, leading to a time-dependent Hamiltonian interaction :math:`H(t)`. We call driving the system with such an electromagnetic field for a fixed time window a *pulse sequence*. During a pulse sequence, the state evolves according to the time-dependent Schrödinger equation @@ -36,7 +36,7 @@ following a unitary evolution :math:`U(t_0, t_1)` of the input state from time :math:`t_0` to :math:`t_1`, i.e. :math:`|\psi(t_1)\rangle = U(t_0, t_1) |\psi(t_0)\rangle`. -In most digital quantum computers (with the exception of measurement-based architectures), the amplitude and frequencies of predefined pulse sequences are +In most digital quantum computers (with the exception of `measurement-based `_ architectures), the amplitude and frequencies of predefined pulse sequences are fine tuned to realize the native gates of the quantum computer. More specifically, the Hamiltonian interaction :math:`H(t)` is tuned such that the respective evolution :math:`U(t_0, t_1)` realizes for example a Pauli or CNOT gate. @@ -145,7 +145,7 @@ def qnode(params): # # Gradients of pulse programs # --------------------------- -# Internally, pulse programs in PennyLane solve the the time-dependent Schrödinger equation using the `Dopri5 `_ solver for +# Internally, pulse programs in PennyLane solve the time-dependent Schrödinger equation using the `Dopri5 `_ solver for # ordinary differential equations (ODEs). In particular, the step sizes between :math:`t_0` and :math:`t_1` are chosen adaptively to stay within a given error tolerance. # We can backpropagate through this ODE solver and obtain the gradient via ``jax.grad``. @@ -292,7 +292,7 @@ def qnode(theta, t=duration): # the initial amplitude of the random values. # # Further, we note that with the increase in the number of parameters due to the continuous evolution, the optimization -# becomes harder. In particular, besides the random initilization, the optimization is also very sensitive to the choice of +# becomes harder. In particular, besides the random initialization, the optimization is also very sensitive to the choice of # optimizer and learning rate. We systematically tried a variety of combinations and provide one possible choice leading to good results. # # We choose ``t_bins = 100`` segments for the piece-wise-constant parametrization of the pulses. From ecd78cbc0cff82a2c6531ae5882a64ca8398d637 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 16:52:09 +0100 Subject: [PATCH 094/122] add polyval comment --- demonstrations/tutorial_pulse_programming101.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 5a2117b08b..db3866dca0 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -66,6 +66,8 @@ jax.config.update("jax_platform_name", "cpu") def f1(p, t): + # polyval(p, t) evaluates a polynomial of degree N=len(p) + # i.e. p[0]*t**(N-1) + p[1]*t**(N-2) + ... + p[N-2]*t + p[N-1] return jnp.polyval(p, t) From 5bd88dedfd3e574d3067469b27e2290dba4710d2 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 16:58:48 +0100 Subject: [PATCH 095/122] add link to each qc system --- demonstrations/tutorial_pulse_programming101.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index db3866dca0..c895a64cae 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -24,7 +24,9 @@ Pulses in quantum computers --------------------------- -In many quantum computing architectures such as `superconducting ion trap `_ and Rydberg systems, qubits are realized through physical systems with a discrete set of energy levels. +In many quantum computing architectures such as `superconducting `_, `ion trap `_ +and `neutral atom Rydberg `_ systems, +qubits are realized through physical systems with a discrete set of energy levels. For example, transmon qubits realize an anharmonic oscillator whose ground and first excited states can serve as the two energy levels of a qubit. Such a qubit can be controlled via an electromagnetic field tuned to its energy gap. In general, this electromagnetic field can be altered in time, leading to a time-dependent Hamiltonian interaction :math:`H(t)`. From 386c6dfdcdbb3be4a3026aec8a17e301ef49b1b9 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 18:22:18 +0100 Subject: [PATCH 096/122] comment about parameter order and calling parametrized Hamiltonians --- .../tutorial_pulse_programming101.py | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index c895a64cae..c36112b1fb 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -35,8 +35,8 @@ .. math:: \frac{d}{dt}|\psi\rangle = -i H(t) |\psi\rangle -following a unitary evolution :math:`U(t_0, t_1)` of the input state from time :math:`t_0` to :math:`t_1`, i.e. -:math:`|\psi(t_1)\rangle = U(t_0, t_1) |\psi(t_0)\rangle`. +from an initial state :math:`|\psi(t_0)\rangle` to a final state :math:`|\psi(t_1)\rangle`. This process corresponds to a unitary evolution :math:`U(t_0, t_1)` +of the input state from time :math:`t_0` to :math:`t_1`, i.e. :math:`|\psi(t_1)\rangle = U(t_0, t_1) |\psi(t_0)\rangle`. In most digital quantum computers (with the exception of `measurement-based `_ architectures), the amplitude and frequencies of predefined pulse sequences are fine tuned to realize the native gates of the quantum computer. More specifically, the Hamiltonian interaction :math:`H(t)` @@ -81,11 +81,14 @@ def f2(p, t): ############################################################################## # Note that when constructing such a Hamiltonian, the ``callable`` functions are -# expected to have the fixed signature ``(p, t)``, such that the Hamiltonian itself -# can be called via ``H((p1, p2), t)``. +# expected to have the fixed signature ``(p, t)``. The Hamiltonian on the other hand +# is passed a ``tuple`` or ``list`` of the parameters for each of the functions in the same +# order the Hamiltonian was constructed. -params = (jnp.ones(5), jnp.array([1.0, jnp.pi])) -print(Ht(params, 0.5)) +p1 = jnp.ones(5) # parameters for f1 +p2 = jnp.array([1.0, jnp.pi]) # parameters for f2 +t = 0.5 # some fixed point in time +print(Ht((p1, p2), t)) # order of parameters p1, p2 matters ############################################################################## # We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using :func:`qml.dot `. @@ -104,7 +107,8 @@ def f2(p, t): print(Ht(params, 0.5)) ############################################################################## -# We can visualize the Hamiltonian interaction by plotting the time-dependent envelopes. +# We can visualize the Hamiltonian interaction by plotting the time-dependent envelopes. We refer to the drift term as all constant terms in time, i.e. :math:`\sum_i X_i X_{i+1}`, +# and plot the envelopes :math:`f_i(p, t)` of the time dependent terms :math:`\sum_i f_i(p, t) Z_i`. ts = jnp.linspace(0.0, 5.0, 100) fs = Ht.coeffs_parametrized @@ -116,6 +120,7 @@ def f2(p, t): ax.plot(ts, fs[n](params[n], ts)) ax.set_ylabel(f"Z_{n}") axs[0].set_title(f"Drift term: $X_0 X_1 + X_1 X_2$") +axs[-1].set_xlabel("time t") plt.tight_layout() plt.show() From 0035bf6c56fbe143025198b539cbeb0cd2955d0b Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 18:32:31 +0100 Subject: [PATCH 097/122] driving field -> control field --- demonstrations/tutorial_pulse_programming101.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index c36112b1fb..a78a8bb366 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -53,7 +53,7 @@ level instead, with the aim of achieving the shortest interaction sequence a hardware system allows. In PennyLane, we can simulate arbitrary qubit system interactions to explore the possibilities of such pulse programs. -First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p_i, t) H_i` with constant operators :math:`H_i` and driving fields :math:`f_i(p_i, t)` that may +First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p_i, t) H_i` with constant operators :math:`H_i` and control fields :math:`f_i(p_i, t)` that may depend on parameters :math:`p`. In PennyLane, we can do this in the following way: """ @@ -91,7 +91,11 @@ def f2(p, t): print(Ht((p1, p2), t)) # order of parameters p1, p2 matters ############################################################################## -# We can construct more complicated Hamiltonians like :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` using :func:`qml.dot `. +# We can construct general Hamiltonians of the form :math:`\sum_i H_i^d + \sum_i f_i(p, t) H_i` +# using :func:`qml.dot `. Such a time-dependent Hamiltonian consists time-indepdenent drift terms :math:`H_i^d` +# and time dependent control terms :math:`f_i(p, t) H_i` with scalar complex-valued function :math:`f_i(p, t)` in time that is +# parametrized by some parameters :math:`p`. +# In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` coeffs = [1.0] * 2 coeffs += [lambda p, t: jnp.sin(p[0] * t) + jnp.sin(p[1] * t) for _ in range(3)] @@ -136,7 +140,7 @@ def f2(p, t): @jax.jit -@qml.qnode(dev) +@qml.qnode(dev, interface="jax") def qnode(params): qml.evolve(Ht)(params, ts) return qml.expval(H_obj) @@ -284,7 +288,7 @@ def wrapped(p, t): dev = qml.device("default.qubit.jax", wires=range(n_wires)) -@qml.qnode(dev) +@qml.qnode(dev, interface="jax") def qnode(theta, t=duration): qml.BasisState(list(data.tapered_hf_state), wires=H_obj.wires) qml.evolve(H_pulse)(params=(*theta, *theta), t=t) From 6e5f5981df1af67883359837085161fc473acbac Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 18:35:34 +0100 Subject: [PATCH 098/122] code review suggestion --- demonstrations/tutorial_pulse_programming101.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index a78a8bb366..d34c8eeb85 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -80,9 +80,9 @@ def f2(p, t): Ht = f1 * qml.PauliX(0) + f2 * qml.PauliY(1) ############################################################################## -# Note that when constructing such a Hamiltonian, the ``callable`` functions are -# expected to have the fixed signature ``(p, t)``. The Hamiltonian on the other hand -# is passed a ``tuple`` or ``list`` of the parameters for each of the functions in the same +# This constructs a :class:`~ParametrizedHamiltonian`. Note that the ``callable`` functions ``f1`` and ``f2`` +# are expected to have the fixed signature ``(p, t)``. When calling the :class:`~ParametrizedHamiltonian`, +# a ``tuple`` or ``list`` of the parameters for each of the functions is passed in the same # order the Hamiltonian was constructed. p1 = jnp.ones(5) # parameters for f1 From 7aba5ada7f39828c08d8ebb00a3cf2f71c948170 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 18:37:39 +0100 Subject: [PATCH 099/122] comment about objective hamiltonian --- demonstrations/tutorial_pulse_programming101.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index d34c8eeb85..e753faf6b8 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -131,7 +131,8 @@ def f2(p, t): ############################################################################## # # A pulse program is then executed by using the :func:`~.pennylane.evolve` transform to create the evolution -# gate :math:`U(t_0, t_1)`, which implicitly depends on the parameters ``p``. +# gate :math:`U(t_0, t_1)`, which implicitly depends on the parameters ``p``. The objective of the program +# is then to compute the expectation value of some objective Hamiltonian ``H_obj``. dev = qml.device("default.qubit.jax", range(4)) From 5baf9a32968735bc49b69a7635af18409cc8c2ae Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 18:38:22 +0100 Subject: [PATCH 100/122] further comment about objective hamiltonian --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index e753faf6b8..553326b1e5 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -132,7 +132,7 @@ def f2(p, t): # # A pulse program is then executed by using the :func:`~.pennylane.evolve` transform to create the evolution # gate :math:`U(t_0, t_1)`, which implicitly depends on the parameters ``p``. The objective of the program -# is then to compute the expectation value of some objective Hamiltonian ``H_obj``. +# is then to compute the expectation value of some objective Hamiltonian ``H_obj`` (here :math:`\sum_i Z_i` for simplicity). dev = qml.device("default.qubit.jax", range(4)) From 5291c9223bd9595bde4f66eac238479798b9dc7a Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 18:52:10 +0100 Subject: [PATCH 101/122] clean up the messy pwc section --- demonstrations/tutorial_pulse_programming101.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 553326b1e5..1f5019b209 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -183,12 +183,17 @@ def qnode(params): ############################################################################## # This creates a callable with signature ``(p, t)`` that returns ``p[int(len(p)*t/duration)]``, such that the passed parameters are the function values # for different time bins. +# Note how the number of time bins is implicitly defined through the length of the parameters. In the following example we are going to use +# ``4`` and ``10`` time bins defined through the length of parameters, respectively. Let us create uniformly random parameters between 0 and 5 and plot +# the corresponding piece-wise-constant function sampled at ``100`` different points in time. key = jax.random.PRNGKey(777) -subkeys = jax.random.split(key, 2) -theta = [jax.random.uniform(subkeys[i], shape=[shape], maxval=5) for i, shape in enumerate([4, 10])] +subkeys = jax.random.split(key, 2) # creates a list of two sub-keys +theta0 = jax.random.uniform(subkeys[0], shape=[4], maxval=5) +theta1 = jax.random.uniform(subkeys[1], shape=[10], maxval=5) +theta = [theta0, theta1] -ts = jnp.linspace(0.0, 10.0, 100)[:-1] +ts = jnp.linspace(0.0, timespan, 100)[:-1] fig, axs = plt.subplots(nrows=2, sharex=True) for i in range(2): ax = axs[i] @@ -198,8 +203,6 @@ def qnode(params): plt.show() ############################################################################## -# Note how the number of time bins is implicitly defined through the length of the parameters, -# which we chose to be ``4`` and ``10`` in the example above, respectively. # We can use these callables as before to construct a :func:`~.pennylane.pulse.ParametrizedHamiltonian`. ops = [qml.PauliX(i) for i in range(2)] From 685940282f89fc306f5e8623745fb9d1de39991c Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 19:17:38 +0100 Subject: [PATCH 102/122] add toctree --- demonstrations/tutorial_pulse_programming101.py | 11 ++++++++--- demos_quantum-computing.rst | 1 + 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 1f5019b209..c7797696be 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -8,7 +8,7 @@ Author: Korbinian Kottmann — Posted: 20 February 2023. In this demo we are going to introduce pulse programming with qubits in PennyLane and run the -ctrl-VQE algorithm on a two-qubit Hamiltonian for the HeH+ molecule. The overall idea is to continuously +ctrl-VQE algorithm on a two-qubit Hamiltonian for the :math:`\text{HeH}^+` molecule. The overall idea is to continuously manipulate qubits with electromagnetic pulses in time. These pulses can be optimized to achieve a task like minimizing the expectation value of an observable. @@ -210,6 +210,8 @@ def qnode(params): print(H(theta, 0.5)) ############################################################################## +# Note that this construction is equivalent to using :func:`qml.dot `. +# # Variational quantum eigensolver with pulse programming # ------------------------------------------------------ # We can now use the ability to access gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. @@ -220,6 +222,8 @@ def qnode(params): data = qml.data.load("qchem", molname="HeH+", basis="STO-3G", bondlength=1.5)[0] H_obj = data.tapered_hamiltonian + +# casting the Hamiltonian coefficients to a jax Array H_obj = qml.Hamiltonian(jnp.array(H_obj.coeffs), H_obj.ops) E_exact = data.fci_energy n_wires = len(H_obj.wires) @@ -232,6 +236,7 @@ def qnode(params): # with bosonic creation and annihilation operators. The anharmonicity :math:`\delta_q` is describing the contribution to higher energy levels. # We are only going to consider the qubit subspace and hence set this term to zero. # The order of magnitude of the resonance frequencies :math:`\omega_q` and coupling strength :math:`g_{pq}` are taken from [#Mitei]_ (in GHz). +# Let us construct the Hamiltonian in PennyLane: def a(wires): @@ -370,8 +375,6 @@ def qnode(theta, t=duration): ############################################################################## # We can also visualize the envelopes for each qubit in time. # We only plot the real amplitude :math:`\Omega(t)` without the qubit frequency modulation. -# Note that we obtain bang-bang like solutions as indicated in [#Asthana2022]_, making it -# likely we are close to the minimal evolution time with ``15ns``. fs = H_pulse.coeffs_parametrized[:n_wires] @@ -390,6 +393,8 @@ def qnode(theta, t=duration): plt.show() ############################################################################## +# Note that we obtain bang-bang like solutions as indicated in [#Asthana2022]_, making it +# likely we are close to the minimal evolution time with ``15ns``. # # Conclusion # ---------- diff --git a/demos_quantum-computing.rst b/demos_quantum-computing.rst index 6b3fd3bf8c..9ea2ee6898 100644 --- a/demos_quantum-computing.rst +++ b/demos_quantum-computing.rst @@ -143,4 +143,5 @@ such as benchmarking and characterizing quantum processors. demos/tutorial_testing_symmetry demos/tutorial_diffable_shadows demos/tutorial_mbqc + demos/tutorial_pulse_programming101 From 6bdc282624c69a8e394944dbaccf47aa5a6fe03d Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 19:24:00 +0100 Subject: [PATCH 103/122] comment about wrapper function --- demonstrations/tutorial_pulse_programming101.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index c7797696be..d8e381de2b 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -265,7 +265,9 @@ def ad(wires): # In principle one can also optimize the drive frequency :math:`\nu_q`, but we already find good results by setting it to the qubit frequencies. # We restrict the amplitude to :math:`\pm 20 \text{MHz}` to abide by realistic hardware constraints. - +# Because ParametrizedHamiltonian expects each callable function to have the signature +# f(p, t) but we have additional parameters it depends on, we create a wrapper function +# that constructs the callables with the appropriate parameters imprinted on it def drive_field(T, omega, sign=1.0): def wrapped(p, t): amp = jnp.clip(qml.pulse.pwc(T)(p, t), -0.02, 0.02) From 746bf77219f0fb386c76b10f2485a84b214d9fb9 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 19:31:06 +0100 Subject: [PATCH 104/122] small things --- demonstrations/tutorial_pulse_programming101.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index d8e381de2b..8682943af0 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -54,7 +54,7 @@ In PennyLane, we can simulate arbitrary qubit system interactions to explore the possibilities of such pulse programs. First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p_i, t) H_i` with constant operators :math:`H_i` and control fields :math:`f_i(p_i, t)` that may -depend on parameters :math:`p`. In PennyLane, we can do this in the following way: +depend on parameters :math:`p`. One way to do this in PennyLane is in the following way: """ import pennylane as qml @@ -72,16 +72,14 @@ def f1(p, t): # i.e. p[0]*t**(N-1) + p[1]*t**(N-2) + ... + p[N-2]*t + p[N-1] return jnp.polyval(p, t) - def f2(p, t): return p[0] * jnp.sin(p[1] * t) - Ht = f1 * qml.PauliX(0) + f2 * qml.PauliY(1) ############################################################################## -# This constructs a :class:`~ParametrizedHamiltonian`. Note that the ``callable`` functions ``f1`` and ``f2`` -# are expected to have the fixed signature ``(p, t)``. When calling the :class:`~ParametrizedHamiltonian`, +# This constructs a :class:`~pennylane.pulse.ParametrizedHamiltonian`. Note that the ``callable`` functions ``f1`` and ``f2`` +# are expected to have the fixed signature ``(p, t)``. When calling the :class:`~pennylane.pulse.ParametrizedHamiltonian`, # a ``tuple`` or ``list`` of the parameters for each of the functions is passed in the same # order the Hamiltonian was constructed. From 6041e867768227fab0b9ee44045c9cb869ddcc83 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 19:47:17 +0100 Subject: [PATCH 105/122] small fixes --- .../tutorial_pulse_programming101.py | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 8682943af0..c268748b71 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -90,10 +90,10 @@ def f2(p, t): ############################################################################## # We can construct general Hamiltonians of the form :math:`\sum_i H_i^d + \sum_i f_i(p, t) H_i` -# using :func:`qml.dot `. Such a time-dependent Hamiltonian consists time-indepdenent drift terms :math:`H_i^d` -# and time dependent control terms :math:`f_i(p, t) H_i` with scalar complex-valued function :math:`f_i(p, t)` in time that is -# parametrized by some parameters :math:`p`. -# In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` +# using :func:`qml.dot `. Such a time-dependent Hamiltonian consists of time indepdenent drift terms :math:`H_i^d` +# and time dependent control terms :math:`f_i(p, t) H_i` with scalar complex-valued functions :math:`f_i(p, t)` in time that may be +# parametrized by parameters :math:`p`. +# In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` as an example: coeffs = [1.0] * 2 coeffs += [lambda p, t: jnp.sin(p[0] * t) + jnp.sin(p[1] * t) for _ in range(3)] @@ -104,13 +104,13 @@ def f2(p, t): # random coefficients key = jax.random.PRNGKey(777) -subkeys = jax.random.split(key, 3) +subkeys = jax.random.split(key, 3) # create list of 3 subkeys params = [jax.random.uniform(subkeys[i], shape=[2], maxval=5) for i in range(3)] print(Ht(params, 0.5)) ############################################################################## # We can visualize the Hamiltonian interaction by plotting the time-dependent envelopes. We refer to the drift term as all constant terms in time, i.e. :math:`\sum_i X_i X_{i+1}`, -# and plot the envelopes :math:`f_i(p, t)` of the time dependent terms :math:`\sum_i f_i(p, t) Z_i`. +# and plot the envelopes :math:`f_i(p, t)` of the time dependent terms :math:`f_i(p, t) Z_i`. ts = jnp.linspace(0.0, 5.0, 100) fs = Ht.coeffs_parametrized @@ -120,7 +120,7 @@ def f2(p, t): for n in range(n_channels): ax = axs[n] ax.plot(ts, fs[n](params[n], ts)) - ax.set_ylabel(f"Z_{n}") + ax.set_ylabel(f"$f_{n}$") axs[0].set_title(f"Drift term: $X_0 X_1 + X_1 X_2$") axs[-1].set_xlabel("time t") plt.tight_layout() @@ -149,8 +149,9 @@ def qnode(params): ############################################################################## # We used the decorator ``jax.jit`` to compile this execution just-in-time. This means the first execution will typically take a little longer with the -# benefit that all following executions will be significantly faster, see the `jax docs on jitting `_. JIT-compiling is optional, and one can remove the decorator when only single executions -# are of interest. +# benefit that all following executions will be significantly faster, see the `jax docs on jitting `_. +# Note that when removing the ``jax.jit`` decorator, the numerical solver `odeint `_ for the time evolution +# inside `qml.evolve` is still jit-compiled by default (just that function). # # Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. # For example, we will simulate a transmon qubit system in the ctrl-VQE example in the last section of this demo. From 2cb74b82f65a0a3a08cab4168c3a47e6277183bf Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 1 Mar 2023 23:59:38 +0100 Subject: [PATCH 106/122] PULSE DEMO 2.0 - physics bam! --- .../tutorial_pulse_programming101.py | 34 +++++++++++-------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index c268748b71..320c67ae7f 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -237,15 +237,12 @@ def qnode(params): # The order of magnitude of the resonance frequencies :math:`\omega_q` and coupling strength :math:`g_{pq}` are taken from [#Mitei]_ (in GHz). # Let us construct the Hamiltonian in PennyLane: - def a(wires): return 0.5 * qml.PauliX(wires) + 0.5j * qml.PauliY(wires) - def ad(wires): return 0.5 * qml.PauliX(wires) - 0.5j * qml.PauliY(wires) - omega = 2 * jnp.pi * jnp.array([4.8080, 4.8333]) g = 2 * jnp.pi * jnp.array([0.01831, 0.02131]) @@ -264,18 +261,22 @@ def ad(wires): # In principle one can also optimize the drive frequency :math:`\nu_q`, but we already find good results by setting it to the qubit frequencies. # We restrict the amplitude to :math:`\pm 20 \text{MHz}` to abide by realistic hardware constraints. +def normalize(x): + """Differentiable normalization to +/- 1 outputs (shifted sigmoid)""" + return (1 - jnp.exp(-x))/(1 + jnp.exp(-x)) + # Because ParametrizedHamiltonian expects each callable function to have the signature # f(p, t) but we have additional parameters it depends on, we create a wrapper function -# that constructs the callables with the appropriate parameters imprinted on it +# that constructs the callables with the appropriate parameters imprinted on them def drive_field(T, omega, sign=1.0): def wrapped(p, t): - amp = jnp.clip(qml.pulse.pwc(T)(p, t), -0.02, 0.02) - phase = jnp.exp(sign * 1j * omega * t) - return amp * phase + amp = qml.pulse.pwc(T)(p[:-1], t) + d_angle = normalize(p[-1]) # difference to drive maximal 1 GHz + phase = jnp.exp(sign * 1j * (omega + d_angle) * t) + return 0.02*normalize(amp) * phase return wrapped - duration = 15.0 fs = [drive_field(duration, omega[i], 1.0) for i in range(n_wires)] @@ -304,6 +305,7 @@ def qnode(theta, t=duration): qml.evolve(H_pulse)(params=(*theta, *theta), t=t) return qml.expval(H_obj) +value_and_grad = jax.jit(jax.value_and_grad(qnode)) ############################################################################## # We now have all the ingredients to run our ctrl-VQE program. We use the ``adabelief`` implementation in `optax `_, a package for optimizations in ``jax``. @@ -323,13 +325,16 @@ def qnode(theta, t=duration): t_bins = 100 # number of time bins key = jax.random.PRNGKey(999) -theta = 0.01 * jax.random.uniform(key, shape=jnp.array([n_wires, t_bins])) +theta = 0.9*jax.random.uniform(key, shape=jnp.array([n_wires, t_bins+1])) import optax from datetime import datetime -n_epochs = 100 -optimizer = optax.adabelief(learning_rate=1e-2) +n_epochs = 60 +schedule0 = optax.constant_schedule(1e-1) +schedule1 = optax.constant_schedule(5e-1) +schedule = optax.join_schedules([schedule0, schedule1], [10]) +optimizer = optax.adam(learning_rate=schedule) opt_state = optimizer.init(theta) value_and_grad = jax.jit(jax.value_and_grad(qnode)) @@ -378,14 +383,13 @@ def qnode(theta, t=duration): # We only plot the real amplitude :math:`\Omega(t)` without the qubit frequency modulation. -fs = H_pulse.coeffs_parametrized[:n_wires] -n_channels = len(fs) +n_channels = n_wires ts = jnp.linspace(0, duration, t_bins) fig, axs = plt.subplots(nrows=n_channels, figsize=(5, 2 * n_channels), sharex=True) for n in range(n_channels): ax = axs[n] - label = f"$\\nu_{n}$: {omega[n]/2/jnp.pi:.3}/$2\\pi$" - ax.plot(ts, np.clip(theta[n], -0.02, 0.02), ".:", label=label) + label = f"$\\Delta \\nu_{n}$: {normalize(theta[n][-1]):.3}" + ax.plot(ts, 0.02*normalize(theta[n][:-1]), ".:", label=label) ax.set_ylabel(f"$amp_{n}$ (GHz)") ax.legend() ax.set_xlabel("t (ns)") From 637259873a027d01f38f9d062821774aafc1628c Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 2 Mar 2023 02:01:40 +0100 Subject: [PATCH 107/122] update text according to version 2.0 --- .../tutorial_pulse_programming101.py | 75 +++++++++++++------ 1 file changed, 52 insertions(+), 23 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 320c67ae7f..7324c7405d 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -215,8 +215,8 @@ def qnode(params): # ------------------------------------------------------ # We can now use the ability to access gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. # For a more general introduction to VQE see :doc:`tutorial_vqe`. -# First, we define the molecular Hamiltonian whose energy estimate we want to minimize. -# We are going to look at :math:`\text{HeH}^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. +# First, we define the molecular Hamiltonian whose energy expectation value we want to minimize. This serves as our objective Hamiltonian. +# We are using :math:`\text{HeH}^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. # We are going to use the tapered Hamiltonian which makes use of symmetries to reduce the number of qubits, see :doc:`tutorial_qubit_tapering` for details. data = qml.data.load("qchem", molname="HeH+", basis="STO-3G", bondlength=1.5)[0] @@ -258,8 +258,14 @@ def ad(wires): # # with the (real) time-dependent amplitudes :math:`\Omega_q(t)` and frequencies :math:`\nu_q` of the drive. # We let :math:`\Omega(t)` be a piece-wise-constant real function whose values are optimized. -# In principle one can also optimize the drive frequency :math:`\nu_q`, but we already find good results by setting it to the qubit frequencies. -# We restrict the amplitude to :math:`\pm 20 \text{MHz}` to abide by realistic hardware constraints. +# In a transmon qubit systems, entangling gates such as ``CNOT`` are realized by driving a target qubit with the resonance frequency of the control qubit. +# This is referred to as cross resonance and is described in [#Sheldon2016]_. +# Here, we allow for more general two-qubit interactions by training the drive frequency :math:`\nu_q` on each qubit. +# +# For this drive, there are certain restrictions by the hardware that we want to already account for to make our simulation as realistic as possible. +# We therefore restrict the amplitude to :math:`\pm 20 \text{MHz}` and the frequency deviation :math:`\Delta \nu_q = \omega_q - \nu_q` to :math:`\pm 1 \text{GHz}` +# (as is done in [#Mitei]_). We achieve this by normalizing the respective quantities with a shifted sigmoid :math:`\mathcal{N}(x) = \frac{1 - e^{-x}}{1 + e^{-x}}`, +# which ensures differentiability. def normalize(x): """Differentiable normalization to +/- 1 outputs (shifted sigmoid)""" @@ -270,10 +276,16 @@ def normalize(x): # that constructs the callables with the appropriate parameters imprinted on them def drive_field(T, omega, sign=1.0): def wrapped(p, t): + # The first len(p)-1 values of the trainable params p characterize the pwc function amp = qml.pulse.pwc(T)(p[:-1], t) - d_angle = normalize(p[-1]) # difference to drive maximal 1 GHz + # The amplitude is normalized to maximally reach +/-20MHz (0.02GHz) + amp = 0.02*normalize(amp) + + # The last value of the trainable params p provide the drive frequency deviation + # We normalize as the difference to drive can maximal be +/-1 GHz + d_angle = normalize(p[-1]) phase = jnp.exp(sign * 1j * (omega + d_angle) * t) - return 0.02*normalize(amp) * phase + return amp * phase return wrapped @@ -289,7 +301,7 @@ def wrapped(p, t): ############################################################################## # Overall, we end up with the time-dependent parametrized Hamiltonian :math:`H(p, t) = H_D + H_C(p, t)` # under which the system is evolved for the given time window of ``15ns``. Note that we are expressing time -# in nanoseconds (:math:`10^{-9}` s) and frequencies in gigahertz (:math:`10^{9}` Hz), such that both +# in nanoseconds (:math:`10^{-9}` s) and frequencies (and energies) in gigahertz (:math:`10^{9}` Hz), such that both # exponents cancel. H_pulse = H_D + H_C @@ -308,17 +320,20 @@ def qnode(theta, t=duration): value_and_grad = jax.jit(jax.value_and_grad(qnode)) ############################################################################## -# We now have all the ingredients to run our ctrl-VQE program. We use the ``adabelief`` implementation in `optax `_, a package for optimizations in ``jax``. -# The success of the optimization is sensitive to the initial values of the parameters. -# We showcase a good random seed here. In reality, this optimization easily gets stuck in local minima -# such that we would have to repeat the experiment multiple times with different random initializations. -# On the other hand, the Hartree-Fock state is usually a good starting point, i.e. choosing all parameters to zero. -# However, this results in a near-zero gradient in our case. This is why we choose a trade-off by reducing -# the initial amplitude of the random values. +# We now have all the ingredients to run our ctrl-VQE program. We use the ``adam`` implementation in `optax `_, +# a package for optimizations in ``jax``. +# +# It has been shown that the loss landscapes of pulse programs are trap free for a variety of conditions and loss functions, including ours [#Russell2016]_. +# In practice however, we see that the optimization is senstive to the initial values of the parameters and the optimization strategy. +# In particular, we often find ourselves with very slow progress during optimization, indicating wide flat regions in the loss landscape. +# This can be salvaged by increasing the learning rate. Sometimes it proved advantageous to increase the learning rate after an +# initial finer search for a better starting point. Further, we note that with the increase in the number of parameters due to the continuous evolution, +# the optimization becomes harder. # -# Further, we note that with the increase in the number of parameters due to the continuous evolution, the optimization -# becomes harder. In particular, besides the random initialization, the optimization is also very sensitive to the choice of -# optimizer and learning rate. We systematically tried a variety of combinations and provide one possible choice leading to good results. +# Whether or not that is due to the increased parameter search space or an inherent effect of pulse programs like barren plateaus in variational quantum circuits +# is to be determined in future work. +# +# We systematically tried a variety of combinations of learning rate schedule, optimizer, and initial values. Here, we provide one possible choice leading to good results. # # We choose ``t_bins = 100`` segments for the piece-wise-constant parametrization of the pulses. @@ -331,14 +346,15 @@ def qnode(theta, t=duration): from datetime import datetime n_epochs = 60 + +# The following block creates a constant schedule of the learning rate +# that increases from 0.1 to 0.5 after 10 epochs schedule0 = optax.constant_schedule(1e-1) schedule1 = optax.constant_schedule(5e-1) schedule = optax.join_schedules([schedule0, schedule1], [10]) optimizer = optax.adam(learning_rate=schedule) opt_state = optimizer.init(theta) -value_and_grad = jax.jit(jax.value_and_grad(qnode)) - energy = np.zeros(n_epochs + 1) energy[0] = qnode(theta) gradients = np.zeros(n_epochs) @@ -369,7 +385,7 @@ def qnode(theta, t=duration): y = np.array(energy) - E_exact ax.plot(y, ".:", label="$\\langle H_{{obj}}\\rangle - E_{{FCI}}$") -ax.fill_between([0, len(y)], [1e-3] * 2, 5e-4, alpha=0.2, label="chem acc.") +ax.fill_between([0, len(y)], [1e-3] * 2, 3e-4, alpha=0.2, label="chem acc.") ax.set_yscale("log") ax.set_ylabel("Energy ($E_H$)") ax.set_xlabel("epoch") @@ -380,7 +396,9 @@ def qnode(theta, t=duration): ############################################################################## # We can also visualize the envelopes for each qubit in time. -# We only plot the real amplitude :math:`\Omega(t)` without the qubit frequency modulation. +# We only plot the real amplitude :math:`\Omega(t)` and indicate the deviation +# :math:`\Delta \nu_q = \omega_q - \nu_q` of the drive frequency :math:`\nu_q` from the qubit frequency :math:`\omega_q` +# in the labels. n_channels = n_wires @@ -430,12 +448,23 @@ def qnode(theta, t=duration): # .. [#Asthana2022] # # Ayush Asthana, Chenxu Liu, Oinam Romesh Meitei, Sophia E. Economou, Edwin Barnes, Nicholas J. Mayhall -# "Minimizing state preparation times in pulse-level variational molecular simulations." +# "Minimizing state preparation times in pulse-level variational molecular simulations" # `arXiv:2203.06818 `__, 2022. # +# .. [#Sheldon2016] +# +# Sarah Sheldon, Easwar Magesan, Jerry M. Chow, Jay M. Gambetta +# "Procedure for systematically tuning up crosstalk in the cross resonance gate" +# `arXiv:1603.04821 `__, 2016. +# +# .. [#Russell2016] +# +# Benjamin Russell, Herschel Rabitz, Rebing Wu +# "Quantum Control Landscapes Are Almost Always Trap Free" +# `arXiv:1608.06198 `__, 2016. +# # # - ############################################################################## # About the author From 25fada1c7db6effda54e00dc4427f6059131d145 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Thu, 2 Mar 2023 13:29:47 +0100 Subject: [PATCH 108/122] typo --- demonstrations/tutorial_pulse_programming101.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 7324c7405d..5e8977a629 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -281,8 +281,8 @@ def wrapped(p, t): # The amplitude is normalized to maximally reach +/-20MHz (0.02GHz) amp = 0.02*normalize(amp) - # The last value of the trainable params p provide the drive frequency deviation - # We normalize as the difference to drive can maximal be +/-1 GHz + # The last value of the trainable params p provides the drive frequency deviation + # We normalize as the difference to drive can maximally be +/-1 GHz d_angle = normalize(p[-1]) phase = jnp.exp(sign * 1j * (omega + d_angle) * t) return amp * phase @@ -379,7 +379,7 @@ def qnode(theta, t=duration): print(f"mean grad: {gradients[n]}") ############################################################################## -# We see that we have converged well within chemical accuracy after half the number of epochs. +# We see that we have converged to chemical accuracy after half the number of epochs. fig, ax = plt.subplots(nrows=1, figsize=(5, 3), sharex=True) From 3ab30799d2b2237b68a155f3563ec1cb6394f0e0 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann <43949391+Qottmann@users.noreply.github.com> Date: Wed, 8 Mar 2023 01:16:43 -0800 Subject: [PATCH 109/122] Apply suggestions from code review Co-authored-by: Alvaro Ballon <91897656+alvaro-at-xanadu@users.noreply.github.com> --- .../tutorial_pulse_programming101.py | 27 +++++++++---------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 7324c7405d..403ee2189c 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -7,7 +7,7 @@ Author: Korbinian Kottmann — Posted: 20 February 2023. -In this demo we are going to introduce pulse programming with qubits in PennyLane and run the +In this demo, we are going to introduce pulse programming with qubits in PennyLane and run the ctrl-VQE algorithm on a two-qubit Hamiltonian for the :math:`\text{HeH}^+` molecule. The overall idea is to continuously manipulate qubits with electromagnetic pulses in time. These pulses can be optimized to achieve a task like minimizing the expectation value of an observable. @@ -47,7 +47,7 @@ A user of a quantum computer typically operates on the higher and more abstract gate level. Future fault-tolerant quantum computers require this abstraction to allow for error correction. -For noisy and intermediate sized quantum computers, the abstraction of decomposing quantum algorithms +For noisy and intermediate-sized quantum computers, the abstraction of decomposing quantum algorithms into a fixed native gate set can be a hindrance and unnecessarily increase execution time, therefore leading to more noise in the computation. The idea of differentiable pulse programming is to optimize quantum circuits on the pulse level instead, with the aim of achieving the shortest interaction sequence a hardware system allows. @@ -90,9 +90,8 @@ def f2(p, t): ############################################################################## # We can construct general Hamiltonians of the form :math:`\sum_i H_i^d + \sum_i f_i(p, t) H_i` -# using :func:`qml.dot `. Such a time-dependent Hamiltonian consists of time indepdenent drift terms :math:`H_i^d` -# and time dependent control terms :math:`f_i(p, t) H_i` with scalar complex-valued functions :math:`f_i(p, t)` in time that may be -# parametrized by parameters :math:`p`. +# using :func:`qml.dot `. Such a time-dependent Hamiltonian consists of time-independent drift terms :math:`H_i^d` +# and time dependent control terms :math:`f_i(p, t) H_i` with scalar complex-valued functions :math:`f_i(p, t).` # In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` as an example: coeffs = [1.0] * 2 @@ -151,7 +150,7 @@ def qnode(params): # We used the decorator ``jax.jit`` to compile this execution just-in-time. This means the first execution will typically take a little longer with the # benefit that all following executions will be significantly faster, see the `jax docs on jitting `_. # Note that when removing the ``jax.jit`` decorator, the numerical solver `odeint `_ for the time evolution -# inside `qml.evolve` is still jit-compiled by default (just that function). +# inside `qml.evolve` is still jit-compiled by default. # # Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. # For example, we will simulate a transmon qubit system in the ctrl-VQE example in the last section of this demo. @@ -170,7 +169,7 @@ def qnode(params): ############################################################################## -# Piece-wise-constant parametrizations +# Piecewise-constant parametrizations # ------------------------------------ # PennyLane also provides a variety of convenience functions to create, for example, piece-wise-constant parametrizations # defining the function values at fixed time bins as parameters. We can construct such a callable with :func:`~pennylane.pulse.pwc` @@ -182,7 +181,7 @@ def qnode(params): ############################################################################## # This creates a callable with signature ``(p, t)`` that returns ``p[int(len(p)*t/duration)]``, such that the passed parameters are the function values # for different time bins. -# Note how the number of time bins is implicitly defined through the length of the parameters. In the following example we are going to use +# Note how the number of time bins is implicitly defined through the length of the parameters. In the following example, we are going to use # ``4`` and ``10`` time bins defined through the length of parameters, respectively. Let us create uniformly random parameters between 0 and 5 and plot # the corresponding piece-wise-constant function sampled at ``100`` different points in time. @@ -214,10 +213,10 @@ def qnode(params): # Variational quantum eigensolver with pulse programming # ------------------------------------------------------ # We can now use the ability to access gradients to perform the variational quantum eigensolver on the pulse level (ctrl-VQE) as is done in [#Mitei]_. -# For a more general introduction to VQE see :doc:`tutorial_vqe`. +# For a more general introduction to VQE, see :doc:`tutorial_vqe`. # First, we define the molecular Hamiltonian whose energy expectation value we want to minimize. This serves as our objective Hamiltonian. # We are using :math:`\text{HeH}^+` as a simple example and load it from the `PennyLane quantum datasets `_ website. -# We are going to use the tapered Hamiltonian which makes use of symmetries to reduce the number of qubits, see :doc:`tutorial_qubit_tapering` for details. +# We are going to use the tapered Hamiltonian, which makes use of symmetries to reduce the number of qubits, see :doc:`tutorial_qubit_tapering` for details. data = qml.data.load("qchem", molname="HeH+", basis="STO-3G", bondlength=1.5)[0] H_obj = data.tapered_hamiltonian @@ -257,7 +256,7 @@ def ad(wires): # .. math:: H_C(t) = \sum_q \Omega_q(t) \left(e^{i\nu_q t} a_q + e^{-i\nu_q t} a^\dagger_q \right) # # with the (real) time-dependent amplitudes :math:`\Omega_q(t)` and frequencies :math:`\nu_q` of the drive. -# We let :math:`\Omega(t)` be a piece-wise-constant real function whose values are optimized. +# We let :math:`\Omega(t)` be a real piecewise-constant function whose values are optimized. # In a transmon qubit systems, entangling gates such as ``CNOT`` are realized by driving a target qubit with the resonance frequency of the control qubit. # This is referred to as cross resonance and is described in [#Sheldon2016]_. # Here, we allow for more general two-qubit interactions by training the drive frequency :math:`\nu_q` on each qubit. @@ -323,10 +322,10 @@ def qnode(theta, t=duration): # We now have all the ingredients to run our ctrl-VQE program. We use the ``adam`` implementation in `optax `_, # a package for optimizations in ``jax``. # -# It has been shown that the loss landscapes of pulse programs are trap free for a variety of conditions and loss functions, including ours [#Russell2016]_. +# It has been shown that the loss landscapes of pulse programs are trap-free for a variety of conditions and loss functions, including ours [#Russell2016]_. # In practice however, we see that the optimization is senstive to the initial values of the parameters and the optimization strategy. # In particular, we often find ourselves with very slow progress during optimization, indicating wide flat regions in the loss landscape. -# This can be salvaged by increasing the learning rate. Sometimes it proved advantageous to increase the learning rate after an +# This can be salvaged by increasing the learning rate. Sometimes, it proved advantageous to increase the learning rate after an # initial finer search for a better starting point. Further, we note that with the increase in the number of parameters due to the continuous evolution, # the optimization becomes harder. # @@ -422,7 +421,7 @@ def qnode(theta, t=duration): # Conclusion # ---------- # Pulse programming is an exciting new field within noisy quantum computing. By skipping the digital abstraction, one can -# write variational programs on the hardware level, potentially minimizing the computation time. This then ideally allows for effectively deeper +# write variational programs on the hardware level, potentially minimizing the computation time. Ideally, this allows for effectively deeper # circuits on noisy hardware. # On the other hand, the possibility to continuously vary the Hamiltonian interaction in time significantly increases # the parameter space. A good parametrization trading off flexibility and the number of parameters is therefore necessary as systems scale up. From b2c6d59930ddc17edc9ca899eeb2bd6c9565bf15 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 10:18:06 +0100 Subject: [PATCH 110/122] add vqe reference in abstract --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index aafe3d1f7c..4d86e60128 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -8,7 +8,7 @@ Author: Korbinian Kottmann — Posted: 20 February 2023. In this demo, we are going to introduce pulse programming with qubits in PennyLane and run the -ctrl-VQE algorithm on a two-qubit Hamiltonian for the :math:`\text{HeH}^+` molecule. The overall idea is to continuously +ctrl-VQE algorithm [#Mitei]_ on a two-qubit Hamiltonian for the :math:`\text{HeH}^+` molecule. The overall idea is to continuously manipulate qubits with electromagnetic pulses in time. These pulses can be optimized to achieve a task like minimizing the expectation value of an observable. From 0cbf5e3de510e8e657432857f1f0a2d0a2f5c3a9 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 10:22:27 +0100 Subject: [PATCH 111/122] hook in the abstract --- demonstrations/tutorial_pulse_programming101.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 4d86e60128..e60b7ea083 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -7,10 +7,11 @@ Author: Korbinian Kottmann — Posted: 20 February 2023. +Quantum computers perform gates via electromagnetic pulses on the hardware level. In differentiable pulse programming, we +can write quantum algorithms directly on the hardware level and variationally optimize the shape, phase and amplitude of the interactions +for our desired goals. In this demo, we are going to introduce pulse programming with qubits in PennyLane and run the -ctrl-VQE algorithm [#Mitei]_ on a two-qubit Hamiltonian for the :math:`\text{HeH}^+` molecule. The overall idea is to continuously -manipulate qubits with electromagnetic pulses in time. These pulses can be optimized to achieve a task like -minimizing the expectation value of an observable. +ctrl-VQE algorithm [#Mitei]_ on a two-qubit Hamiltonian for the :math:`\text{HeH}^+` molecule. | From 1b449ba19d6e270f81ac5d6ab4d5a044d90ddb5d Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 10:33:05 +0100 Subject: [PATCH 112/122] interaction picture confusion --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index e60b7ea083..b075593dba 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -30,7 +30,7 @@ qubits are realized through physical systems with a discrete set of energy levels. For example, transmon qubits realize an anharmonic oscillator whose ground and first excited states can serve as the two energy levels of a qubit. Such a qubit can be controlled via an electromagnetic field tuned to its energy gap. In general, this -electromagnetic field can be altered in time, leading to a time-dependent Hamiltonian interaction :math:`H(t)`. +electromagnetic field can be altered in time, leading to a time-dependent Hamiltonian :math:`H(t)` describing the effect of the field on the qubits. We call driving the system with such an electromagnetic field for a fixed time window a *pulse sequence*. During a pulse sequence, the state evolves according to the time-dependent Schrödinger equation From 6ce3360c652697f90353cbf9e8aa3c298896b26f Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 10:52:39 +0100 Subject: [PATCH 113/122] p_i explicitly --- .../tutorial_pulse_programming101.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index b075593dba..901092885c 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -31,8 +31,8 @@ For example, transmon qubits realize an anharmonic oscillator whose ground and first excited states can serve as the two energy levels of a qubit. Such a qubit can be controlled via an electromagnetic field tuned to its energy gap. In general, this electromagnetic field can be altered in time, leading to a time-dependent Hamiltonian :math:`H(t)` describing the effect of the field on the qubits. -We call driving the system with such an electromagnetic field for a fixed time window a *pulse sequence*. During a pulse sequence, the state evolves according -to the time-dependent Schrödinger equation +We call driving the system with such an electromagnetic field for a fixed time window :math:`[t_0, t_1]` a *pulse sequence*. +During a pulse sequence, the state evolves according to the time-dependent Schrödinger equation .. math:: \frac{d}{dt}|\psi\rangle = -i H(t) |\psi\rangle @@ -54,8 +54,8 @@ level instead, with the aim of achieving the shortest interaction sequence a hardware system allows. In PennyLane, we can simulate arbitrary qubit system interactions to explore the possibilities of such pulse programs. -First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p_i, t) H_i` with constant operators :math:`H_i` and control fields :math:`f_i(p_i, t)` that may -depend on parameters :math:`p`. One way to do this in PennyLane is in the following way: +First, we need to define the time-dependent Hamiltonian :math:`H(p, t)= \sum_i f_i(p_i, t) H_i` with constant operators :math:`H_i` and control fields :math:`f_i(p_i, t)`. +The Hamiltonian depends on the set of parameters :math:`p = \{p_i\}`. One way to do this in PennyLane is in the following way: """ import pennylane as qml @@ -90,10 +90,10 @@ def f2(p, t): print(Ht((p1, p2), t)) # order of parameters p1, p2 matters ############################################################################## -# We can construct general Hamiltonians of the form :math:`\sum_i H_i^d + \sum_i f_i(p, t) H_i` +# We can construct general Hamiltonians of the form :math:`\sum_i H_i^d + \sum_i f_i(p_i, t) H_i` # using :func:`qml.dot `. Such a time-dependent Hamiltonian consists of time-independent drift terms :math:`H_i^d` -# and time dependent control terms :math:`f_i(p, t) H_i` with scalar complex-valued functions :math:`f_i(p, t).` -# In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p, t) Z_i` as an example: +# and time dependent control terms :math:`f_i(p_i, t) H_i` with scalar complex-valued functions :math:`f_i(p, t).` +# In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p_i, t) Z_i` as an example: coeffs = [1.0] * 2 coeffs += [lambda p, t: jnp.sin(p[0] * t) + jnp.sin(p[1] * t) for _ in range(3)] @@ -110,7 +110,7 @@ def f2(p, t): ############################################################################## # We can visualize the Hamiltonian interaction by plotting the time-dependent envelopes. We refer to the drift term as all constant terms in time, i.e. :math:`\sum_i X_i X_{i+1}`, -# and plot the envelopes :math:`f_i(p, t)` of the time dependent terms :math:`f_i(p, t) Z_i`. +# and plot the envelopes :math:`f_i(p_i, t)` of the time dependent terms :math:`f_i(p_i, t) Z_i`. ts = jnp.linspace(0.0, 5.0, 100) fs = Ht.coeffs_parametrized @@ -130,7 +130,7 @@ def f2(p, t): # # A pulse program is then executed by using the :func:`~.pennylane.evolve` transform to create the evolution # gate :math:`U(t_0, t_1)`, which implicitly depends on the parameters ``p``. The objective of the program -# is then to compute the expectation value of some objective Hamiltonian ``H_obj`` (here :math:`\sum_i Z_i` for simplicity). +# is then to compute the expectation value of some objective Hamiltonian ``H_obj`` (here :math:`\sum_i Z_i` as a simple example). dev = qml.device("default.qubit.jax", range(4)) From 5ca9c48c676e2fbe10f5d5d077829f9e98425a0a Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 10:57:13 +0100 Subject: [PATCH 114/122] update plot title fig 1 --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 901092885c..23c68a15ad 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -121,7 +121,7 @@ def f2(p, t): ax = axs[n] ax.plot(ts, fs[n](params[n], ts)) ax.set_ylabel(f"$f_{n}$") -axs[0].set_title(f"Drift term: $X_0 X_1 + X_1 X_2$") +axs[0].set_title(f"Envelopes $f_i(p_i, t)$ of $\sum_i X_i X_{{i+1}} + \sum_i f_i(p_i, t) Z_i$") axs[-1].set_xlabel("time t") plt.tight_layout() plt.show() From 787e836a8407d8307c10c7a2ca7a73974e5ef70b Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 11:41:13 +0100 Subject: [PATCH 115/122] change bib order --- demonstrations/tutorial_pulse_programming101.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 23c68a15ad..cfb502934f 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -433,18 +433,18 @@ def qnode(theta, t=duration): # References # ---------- # -# .. [#Leng2022] -# -# Jiaqi Leng, Yuxiang Peng, Yi-Ling Qiao, Ming Lin, Xiaodi Wu -# "Differentiable Analog Quantum Computing for Optimization and Control" -# `arXiv:2210.15812 `__, 2022 -# # .. [#Mitei] # # Oinam Romesh Meitei, Bryan T. Gard, George S. Barron, David P. Pappas, Sophia E. Economou, Edwin Barnes, Nicholas J. Mayhall # "Gate-free state preparation for fast variational quantum eigensolver simulations: ctrl-VQE" # `arXiv:2008.04302 `__, 2020 # +# .. [#Leng2022] +# +# Jiaqi Leng, Yuxiang Peng, Yi-Ling Qiao, Ming Lin, Xiaodi Wu +# "Differentiable Analog Quantum Computing for Optimization and Control" +# `arXiv:2210.15812 `__, 2022 +# # .. [#Asthana2022] # # Ayush Asthana, Chenxu Liu, Oinam Romesh Meitei, Sophia E. Economou, Edwin Barnes, Nicholas J. Mayhall From 0b7c46f03b7eb3704e2912fd2d214b9063bc4f50 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 11:43:40 +0100 Subject: [PATCH 116/122] cross resonance comment --- demonstrations/tutorial_pulse_programming101.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index cfb502934f..5260c003b7 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -41,7 +41,7 @@ In most digital quantum computers (with the exception of `measurement-based `_ architectures), the amplitude and frequencies of predefined pulse sequences are fine tuned to realize the native gates of the quantum computer. More specifically, the Hamiltonian interaction :math:`H(t)` -is tuned such that the respective evolution :math:`U(t_0, t_1)` realizes for example a Pauli or CNOT gate. +is tuned such that the respective evolution :math:`U(t_0, t_1)` realizes for example a Pauli or CNOT gate (see e.g. *cross-resonance* gates for superconducting qubits in [#Sheldon2016]_). Pulse programming in PennyLane ------------------------------ @@ -439,6 +439,12 @@ def qnode(theta, t=duration): # "Gate-free state preparation for fast variational quantum eigensolver simulations: ctrl-VQE" # `arXiv:2008.04302 `__, 2020 # +# .. [#Sheldon2016] +# +# Sarah Sheldon, Easwar Magesan, Jerry M. Chow, Jay M. Gambetta +# "Procedure for systematically tuning up crosstalk in the cross resonance gate" +# `arXiv:1603.04821 `__, 2016. +# # .. [#Leng2022] # # Jiaqi Leng, Yuxiang Peng, Yi-Ling Qiao, Ming Lin, Xiaodi Wu @@ -451,12 +457,6 @@ def qnode(theta, t=duration): # "Minimizing state preparation times in pulse-level variational molecular simulations" # `arXiv:2203.06818 `__, 2022. # -# .. [#Sheldon2016] -# -# Sarah Sheldon, Easwar Magesan, Jerry M. Chow, Jay M. Gambetta -# "Procedure for systematically tuning up crosstalk in the cross resonance gate" -# `arXiv:1603.04821 `__, 2016. -# # .. [#Russell2016] # # Benjamin Russell, Herschel Rabitz, Rebing Wu From b2b3c88d40c0960706ec4d3e6fa571cfd3504dd5 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 11:47:42 +0100 Subject: [PATCH 117/122] commit about explicit functional form --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 5260c003b7..c8fadb629a 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -93,7 +93,7 @@ def f2(p, t): # We can construct general Hamiltonians of the form :math:`\sum_i H_i^d + \sum_i f_i(p_i, t) H_i` # using :func:`qml.dot `. Such a time-dependent Hamiltonian consists of time-independent drift terms :math:`H_i^d` # and time dependent control terms :math:`f_i(p_i, t) H_i` with scalar complex-valued functions :math:`f_i(p, t).` -# In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p_i, t) Z_i` as an example: +# In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p_i, t) Z_i` with :math:`f_i(p_i, t) = \sin(p_i^0 t) + \sin(p_i^1 t)` as an example: coeffs = [1.0] * 2 coeffs += [lambda p, t: jnp.sin(p[0] * t) + jnp.sin(p[1] * t) for _ in range(3)] From d4972a4b59a2d0d0d586fd471ef3ec4fcf5d7cdc Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 11:48:24 +0100 Subject: [PATCH 118/122] commit about explicit functional form --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index c8fadb629a..ff1e57e700 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -93,7 +93,7 @@ def f2(p, t): # We can construct general Hamiltonians of the form :math:`\sum_i H_i^d + \sum_i f_i(p_i, t) H_i` # using :func:`qml.dot `. Such a time-dependent Hamiltonian consists of time-independent drift terms :math:`H_i^d` # and time dependent control terms :math:`f_i(p_i, t) H_i` with scalar complex-valued functions :math:`f_i(p, t).` -# In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p_i, t) Z_i` with :math:`f_i(p_i, t) = \sin(p_i^0 t) + \sin(p_i^1 t)` as an example: +# In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p_i, t) Z_i` with :math:`f_i(p_i, t) = \sin(p_i^0 t) + \sin(p_i^1 t) \forall i` as an example: coeffs = [1.0] * 2 coeffs += [lambda p, t: jnp.sin(p[0] * t) + jnp.sin(p[1] * t) for _ in range(3)] From 2a153ab30c78d15ee6c2f714384500f70171835c Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 11:55:19 +0100 Subject: [PATCH 119/122] small typos --- demonstrations/tutorial_pulse_programming101.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index ff1e57e700..b8f1fb42f9 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -92,7 +92,7 @@ def f2(p, t): ############################################################################## # We can construct general Hamiltonians of the form :math:`\sum_i H_i^d + \sum_i f_i(p_i, t) H_i` # using :func:`qml.dot `. Such a time-dependent Hamiltonian consists of time-independent drift terms :math:`H_i^d` -# and time dependent control terms :math:`f_i(p_i, t) H_i` with scalar complex-valued functions :math:`f_i(p, t).` +# and time-dependent control terms :math:`f_i(p_i, t) H_i` with scalar complex-valued functions :math:`f_i(p, t).` # In the following we are going to construct :math:`\sum_i X_i X_{i+1} + \sum_i f_i(p_i, t) Z_i` with :math:`f_i(p_i, t) = \sin(p_i^0 t) + \sin(p_i^1 t) \forall i` as an example: coeffs = [1.0] * 2 @@ -110,7 +110,7 @@ def f2(p, t): ############################################################################## # We can visualize the Hamiltonian interaction by plotting the time-dependent envelopes. We refer to the drift term as all constant terms in time, i.e. :math:`\sum_i X_i X_{i+1}`, -# and plot the envelopes :math:`f_i(p_i, t)` of the time dependent terms :math:`f_i(p_i, t) Z_i`. +# and plot the envelopes :math:`f_i(p_i, t)` of the time-dependent terms :math:`f_i(p_i, t) Z_i`. ts = jnp.linspace(0.0, 5.0, 100) fs = Ht.coeffs_parametrized @@ -151,7 +151,7 @@ def qnode(params): # We used the decorator ``jax.jit`` to compile this execution just-in-time. This means the first execution will typically take a little longer with the # benefit that all following executions will be significantly faster, see the `jax docs on jitting `_. # Note that when removing the ``jax.jit`` decorator, the numerical solver `odeint `_ for the time evolution -# inside `qml.evolve` is still jit-compiled by default. +# inside :func:`~.pennylane.evolve` is still jit-compiled by default. # # Researchers interested in more specific hardware systems can simulate them using the specific Hamiltonian interactions. # For example, we will simulate a transmon qubit system in the ctrl-VQE example in the last section of this demo. From 3e5293c63e6467049fe256a28d75b73a5f98c19f Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 15:14:21 +0100 Subject: [PATCH 120/122] re-trigger --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index b8f1fb42f9..21416417b2 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -5,7 +5,7 @@ :property="og:description": Simulating differentialble pulse programs in PennyLane with qubits :property="og:image": https://pennylane.ai/qml/_images/pulse_illustration.png -Author: Korbinian Kottmann — Posted: 20 February 2023. +Author: Korbinian Kottmann — Posted: 13 March 2023. Quantum computers perform gates via electromagnetic pulses on the hardware level. In differentiable pulse programming, we can write quantum algorithms directly on the hardware level and variationally optimize the shape, phase and amplitude of the interactions From 275702f3d17eb35e8a282052ef533289554dbb95 Mon Sep 17 00:00:00 2001 From: Korbinian Kottmann Date: Wed, 8 Mar 2023 15:18:01 +0100 Subject: [PATCH 121/122] fix v0.29.1 --- requirements.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/requirements.txt b/requirements.txt index 4101f48662..4db0fbff94 100644 --- a/requirements.txt +++ b/requirements.txt @@ -16,12 +16,12 @@ pyscf==2.1.1 cirq-core==0.14.1 cirq-pasqal==0.14.1 openfermionpyscf==0.5 # required by 2 tutorials: tutorial_quantum_chemistry and tutorial_adaptive_circuits and tutorial_diffable_shadows -git+https://github.com/PennyLaneAI/pennylane.git -git+https://github.com/PennyLaneAI/pennylane-sf.git -git+https://github.com/PennyLaneAI/pennylane-cirq.git -git+https://github.com/PennyLaneAI/pennylane-qiskit.git +pennylane==0.29.1 +pennylane-sf==0.29.0 +pennylane-cirq==0.29.0 +pennylane-qiskit==0.29.0 qulacs==0.1.10.1 -git+https://github.com/PennyLaneAI/pennylane-qulacs.git +pennylane-qulacs==0.29.0 scikit-learn==0.23.2 docutils==0.16 markupsafe==2.0.1 From 3a21766b4bc64426518f03fa9df234c1355aaeb1 Mon Sep 17 00:00:00 2001 From: Guillermo Alonso-Linaje <65235481+KetpuntoG@users.noreply.github.com> Date: Wed, 8 Mar 2023 11:11:14 -0500 Subject: [PATCH 122/122] Update demonstrations/tutorial_pulse_programming101.py --- demonstrations/tutorial_pulse_programming101.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/demonstrations/tutorial_pulse_programming101.py b/demonstrations/tutorial_pulse_programming101.py index 21416417b2..6eda92bd26 100644 --- a/demonstrations/tutorial_pulse_programming101.py +++ b/demonstrations/tutorial_pulse_programming101.py @@ -5,7 +5,7 @@ :property="og:description": Simulating differentialble pulse programs in PennyLane with qubits :property="og:image": https://pennylane.ai/qml/_images/pulse_illustration.png -Author: Korbinian Kottmann — Posted: 13 March 2023. +Author: Korbinian Kottmann — Posted: 8 March 2023. Quantum computers perform gates via electromagnetic pulses on the hardware level. In differentiable pulse programming, we can write quantum algorithms directly on the hardware level and variationally optimize the shape, phase and amplitude of the interactions