From 39e2e099ea751010d340cc00d5a05399127b282c Mon Sep 17 00:00:00 2001 From: Ardavan Oskooi Date: Thu, 5 Jan 2023 13:05:13 -0800 Subject: [PATCH] Tutorial for adjoint optimization of broadband waveguide mode converter with minimum feature size (#2365) * tutorial for adjoint optimization of broadband waveguide mode converter * add figures and more content * add figures * fixes and tweaks * Update doc/docs/Python_Tutorials/Adjoint_Solver.md * Update doc/docs/Python_Tutorials/Adjoint_Solver.md * Update doc/docs/Python_Tutorials/Adjoint_Solver.md * fix spelling mistakes Co-authored-by: Steven G. Johnson --- doc/docs/Python_Tutorials/Adjoint_Solver.md | 711 +++++++++++++++++- .../images/mode_converter_objfunc_hist.png | Bin 0 -> 55476 bytes .../mode_converter_refl_tran_spectra.png | Bin 0 -> 53927 bytes doc/docs/images/mode_converter_sim_layout.png | Bin 0 -> 24160 bytes .../adjoint_optimization/mode_converter.py | 564 ++++++++++++++ 5 files changed, 1269 insertions(+), 6 deletions(-) create mode 100644 doc/docs/images/mode_converter_objfunc_hist.png create mode 100644 doc/docs/images/mode_converter_refl_tran_spectra.png create mode 100644 doc/docs/images/mode_converter_sim_layout.png create mode 100644 python/examples/adjoint_optimization/mode_converter.py diff --git a/doc/docs/Python_Tutorials/Adjoint_Solver.md b/doc/docs/Python_Tutorials/Adjoint_Solver.md index 117b8f8c5..40db53823 100644 --- a/doc/docs/Python_Tutorials/Adjoint_Solver.md +++ b/doc/docs/Python_Tutorials/Adjoint_Solver.md @@ -2,13 +2,714 @@ # Adjoint Solver --- -Meep contains an adjoint-solver module for efficiently computing the gradient of an arbitrary function of the mode coefficients (S-parameters), DFT fields, and far fields (using the analytic near-to-far field transformation) with respect to $\varepsilon$ on a discrete spatial grid (a [`MaterialGrid`](../Python_User_Interface.md#materialgrid) class object) at multiple frequencies over a broad bandwidth. Regardless of the number of degrees of freedom for the grid points, just **two** separate timestepping runs are required. The first run is the "forward" calculation to compute the objective function and the DFT fields of the design region. The second run is the "adjoint" calculation to compute the gradient of the objective function with respect to the design variables. The adjoint run involves a special type of source distribution used to compute the DFT fields of the design region. The gradient is computed in post processing using the DFT fields from the forward and adjoint runs. This is all done automatically, and is described in: +Meep contains an adjoint-solver module for efficiently computing the +gradient of an arbitrary function of the mode coefficients +($\mathcal{S}$-parameters), DFT fields, local density of states +(LDOS), and "far" fields with respect to $\varepsilon$ on a discrete +spatial grid (a +[`MaterialGrid`](../Python_User_Interface.md#materialgrid) class +object) at multiple frequencies over a broad bandwidth. Regardless of +the number of degrees of freedom for the grid points, just **two** +distinct timestepping runs are required. The first run is the +"forward" calculation to compute the objective function and the DFT +fields of the design region. The second run is the "adjoint" +calculation to compute the gradient of the objective function with +respect to the design variables. The adjoint run involves a special +type of current source distribution used to compute the DFT fields of +the design region. The gradient is computed in post processing using +the DFT fields from the forward and adjoint runs. The gradient +calculation is fully automated. The theoretical and computational +details of the adjoint-solver module are described in this +publication: -- A. M. Hammond, A. Oskooi, M. Chen, Z. Lin, S. G. Johnson, and S. E. Ralph, “[High-performance hybrid time/frequency-domain topology optimization for large-scale photonics inverse design](https://doi.org/10.1364/OE.442074),” *Optics Express*, vol. 30, no. 3, pp. 4467–4491 (2022). +- A. M. Hammond, A. Oskooi, M. Chen, Z. Lin, S. G. Johnson, and + S. E. Ralph, “[High-performance hybrid time/frequency-domain + topology optimization for large-scale photonics inverse + design](https://doi.org/10.1364/OE.442074),” *Optics Express*, + vol. 30, no. 3, pp. 4467–4491 (2022). -This interface to this functionality is implemented entirely in Python using [autograd](https://github.com/HIPS/autograd) and [JAX](https://github.com/google/jax). The adjoint solver supports inverse design and [topology optimization](https://en.wikipedia.org/wiki/Topology_optimization) by providing the functionality to wrap an optimization library around the gradient computation. +Much of the functionality of the adjoint solver is implemented in +Python using [autograd](https://github.com/HIPS/autograd) as well as +[JAX](https://github.com/google/jax). -There are seven Jupyter notebooks that demonstrate the main features of the adjoint solver. +The adjoint solver supports inverse design and [topology +optimization](https://en.wikipedia.org/wiki/Topology_optimization) by +providing the functionality to wrap an optimization library around the +gradient computation. This is demonstrated in several tutorials below. + +[TOC] + +Broadband Waveguide Mode Converter with Minimum Feature Size +------------------------------------------------------------ + +This example demonstrates some of the advanced functionality of the +adjoint solver including worst-case (minimax) optimization, multiple +objective functions, and constraints on the minimum line width and +line spacing. The design problem involves a broadband waveguide mode +converter with minimum feature size in 2D. This is based on +[M.F. Schubert et al., ACS Photonics, Vol. 9, pp. 2327-36, +(2022)](https://doi.org/10.1021/acsphotonics.2c00313). + +The mode converter must satisfy two separate design objectives: (1) +minimize the reflectance $R$ into the fundamental mode of the input +port ($\mathcal{S}_{11}$) and (2) maximize the transmittance $T$ into +the second-order mode of the output port ($\mathcal{S}_{21}$). There +are different ways to define this multi-objective and multi-wavelength +optimization. The approach taken here is *worst-case* optimization +whereby we minimize the maximum (the worst case) of $R$ and $1-T$ +across all six wavelengths (in the O-band for +telecommunications). This is known as *minimax* optimization. + +The challenge with minimax optimization is that the $\max$ objective +function is not everywhere differentiable. This property would seem to +preclude the use of gradient-based optimization algorithms for this +problem which involves 12 independent functions ($R$ and $1-T$ for +each of six wavelengths). Fortunately, there is a workaround: the +problem can be reformulated as a differentiable problem using +a so-called "epigraph" formulation: introducing +a new "dummy" optimization variable $t$ and +adding each independent function $f_k(x)$ as a new nonlinear constraint $t \ge f_k(x)$. See +the [NLopt +documentation](https://nlopt.readthedocs.io/en/latest/NLopt_Introduction/#equivalent-formulations-of-optimization-problems) +for an overview of this approach. The minimax/epigraph approach is +also covered in the [near-to-far field +tutorial](https://nbviewer.org/github/NanoComp/meep/blob/master/python/examples/adjoint_optimization/06-Near2Far-Epigraph.ipynb). + +In this example, we use a minimum feature size of 150 nm for the line +width *and* line spacing. The implementation of these constraints is +based on [A.M. Hammond et al., Optics Express, Vol. 29, pp. 23916-38 +(2021)](https://doi.org/10.1364/OE.431188). + +There are five important items to note in the set up of the +optimization problem: + +- The lengthscale constraint is activated only in the final epoch. It is + often helpful to mostly binarize the design before this final epoch. This is because + the lengthscale constraint forces binarization which could induce + large changes in an initial greyscale design and irrevocably spoil + the performance of the final design. + +- The initial value of the epigraph variable of the final epoch (in + which the linewidth constraint is imposed) should take into account + the value of the constraint itself to ensure a feasible starting + point. + +- The edge of the design region is padded by a filter radius (rather + than e.g., a single pixel) to produce measured lengthscales of the + final design that are consistent with the imposed constraint. + +- The hyperparameters of the lengthscale constraint function (`glc` in + the script below), need to be chosen carefully to produce final + designs which do not significantly degrade the performance of the + unconstrained designs at the start of the final epoch. + +- Damping of the design weights is used for the early epochs in which + the design is mostly greyscale to induce binarization. Subpixel + averaging of the design weights is used in the later epochs in which + the $\beta$ parameter of the thresholding function is large and thus + the design is mostly binarized. Note that the accuracy of the + adjoint gradients will break down for a binary design without + subpixel smoothing. + +A schematic of the final design and the simulation layout is shown +below. The minimum lengthscale of the final design, measured using a +[ruler](https://github.com/NanoComp/photonics-opt-testbed/tree/main/ruler), +is 163 nm. This value is consistent with the imposed lengthscale since +it is approximately within one design pixel (10 nm). + +![](../images/mode_converter_sim_layout.png#center) + +A plot of the reflectance and transmittance spectrum in linear and log +(dB) scales of the final design is shown below. The worst-case +reflectance is -17.7 dB at a wavelength of 1.295 μm. The worst-case +transmittance is -2.1 dB at a wavelength of 1.265 μm. + +![](../images/mode_converter_refl_tran_spectra.png#center) + +Finally, a plot of the objective function history is shown. The +"spikes" present in the plot are a normal feature of +nonlinear-optimization algorithms. The algorithm may take too large a +step which turns out to make the objective function worse. This means +the algorithm then has to "backtrack" and take a smaller step. This +occurs in the CCSA algorithm by increasing a penalty term. + +![](../images/mode_converter_objfunc_hist.png#center) + +The script is +[python/examples/adjoint_optimization/mode_converter.py](https://github.com/NanoComp/meep/tree/master/python/examples/adjoint_optimization/mode_converter.py). The +runtime of this script using three Intel Xeon 2.0 GHz processors is +approximately 14 hours. + +```py +import numpy as np +import matplotlib +matplotlib.use('agg') +import matplotlib.pyplot as plt +from autograd import numpy as npa, tensor_jacobian_product, grad +import nlopt +import meep as mp +import meep.adjoint as mpa + +resolution = 50 # pixels/μm + +w = 0.4 # waveguide width +l = 3.0 # waveguide length (on each side of design region) +dpad = 0.6 # padding length above/below design region +dpml = 1.0 # PML thickness +dx = 1.6 # length of design region +dy = 1.6 # width of design region + +sx = dpml+l+dx+l+dpml +sy = dpml+dpad+dy+dpad+dpml +cell_size = mp.Vector3(sx,sy,0) + +pml_layers = [mp.PML(thickness=dpml)] + +# wavelengths for minimax optimization +wvls = (1.265, 1.270, 1.275, 1.285, 1.290, 1.295) +frqs = [1/wvl for wvl in wvls] + +minimum_length = 0.15 # minimum length scale (μm) +eta_i = ( + 0.5 # blueprint design field thresholding point (between 0 and 1) +) +eta_e = 0.75 # erosion design field thresholding point (between 0 and 1) +eta_d = 1 - eta_e # dilation design field thresholding point (between 0 and 1) +filter_radius = mpa.get_conic_radius_from_eta_e(minimum_length, eta_e) +print(f"filter_radius:, {filter_radius:.6f}") + +# pulsed source center frequency and bandwidth +wvl_min = 1.26 +wvl_max = 1.30 +frq_min = 1/wvl_max +frq_max = 1/wvl_min +fcen = 0.5*(frq_min+frq_max) +df = frq_max-frq_min + +eig_parity = mp.ODD_Z +src_pt = mp.Vector3(-0.5*sx+dpml,0,0) + +nSiO2 = 1.5 +SiO2 = mp.Medium(index=nSiO2) +nSi = 3.5 +Si = mp.Medium(index=nSi) + +design_region_size = mp.Vector3(dx,dy,0) +design_region_resolution = int(2*resolution) +Nx = int(design_region_size.x*design_region_resolution) +Ny = int(design_region_size.y*design_region_resolution) + +# impose a bit "mask" of thickness equal to the filter radius +# around the edges of the design region in order to prevent +# violations of the minimum linewidth constraint. + +x_g = np.linspace( + -design_region_size.x / 2, + design_region_size.x / 2, + Nx, +) +y_g = np.linspace( + -design_region_size.y / 2, + design_region_size.y / 2, + Ny, +) +X_g, Y_g = np.meshgrid( + x_g, + y_g, + sparse=True, + indexing="ij", +) + +left_wg_mask = ( + (X_g <= -design_region_size.x / 2 + filter_radius) & + (np.abs(Y_g) <= w / 2) +) +right_wg_mask = ( + (X_g >= design_region_size.x / 2 - filter_radius) & + (np.abs(Y_g) <= w / 2) +) +Si_mask = left_wg_mask | right_wg_mask + +border_mask = ( + (X_g <= -design_region_size.x / 2 + filter_radius) | + (X_g >= design_region_size.x / 2 - filter_radius) | + (Y_g <= -design_region_size.y / 2 + filter_radius) | + (Y_g >= design_region_size.y / 2 - filter_radius) +) +SiO2_mask = border_mask.copy() +SiO2_mask[Si_mask] = False + +refl_pt = mp.Vector3(-0.5*sx+dpml+0.5*l) +tran_pt = mp.Vector3(0.5*sx-dpml-0.5*l) + +stop_cond = mp.stop_when_fields_decayed(50, mp.Ez, refl_pt, 1e-8) + +def mapping(x, eta, beta): + """A differentiable mapping function which applies, in order, + the following sequence of transformations to the design weights: + (1) a bit mask for the boundary pixels, (2) convolution with a + conic filter, and (3) projection via a hyperbolic tangent. + + Args: + x: design weights as a 1d array of size Nx*Ny. + eta: erosion/dilation parameter for the projection. + beta: bias parameter for the projection. + """ + x = npa.where( + Si_mask.flatten(), + 1, + npa.where( + SiO2_mask.flatten(), + 0, + x, + ) + ) + + filtered_field = mpa.conic_filter( + x, + filter_radius, + design_region_size.x, + design_region_size.y, + design_region_resolution, + ) + + projected_field = mpa.tanh_projection( + filtered_field, + beta, + eta, + ) + + return projected_field.flatten() + + +def f(x, grad): + """Objective function for the epigraph formulation. + + Args: + x: 1d array of size 1+Nx*Ny containing epigraph variable (first element) + and design weights (remaining Nx*Ny elements). + grad: the gradient as a 1d array of size 1+Nx*Ny modified in place. + """ + t = x[0] # epigraph variable + v = x[1:] # design weights + if grad.size > 0: + grad[0] = 1 + grad[1:] = 0 + return t + + +def c(result, x, gradient, eta, beta): + """Constraint function for the epigraph formulation. + + Args: + result: the result of the function evaluation modified in place. + x: 1d array of size 1+Nx*Ny containing epigraph variable (first + element) and design weights (remaining Nx*Ny elements). + gradient: the Jacobian matrix with dimensions (1+Nx*Ny, + 2*num. wavelengths) modified in place. + eta: erosion/dilation parameter for projection. + beta: bias parameter for projection. + """ + t = x[0] # epigraph variable + v = x[1:] # design weights + + f0, dJ_du = opt([mapping(v, eta, beta)]) + + f0_reflection = f0[0] + f0_transmission = f0[1] + f0_merged = np.concatenate((f0_reflection, f0_transmission)) + + dJ_du_reflection = dJ_du[0] + dJ_du_transmission = dJ_du[1] + nfrq = len(frqs) + my_grad = np.zeros((Nx * Ny, 2 * nfrq)) + my_grad[:, :nfrq] = dJ_du_reflection + my_grad[:, nfrq:] = dJ_du_transmission + + # backpropagate the gradients through mapping function + for k in range(2*nfrq): + my_grad[:, k] = tensor_jacobian_product(mapping, 0)( + v, + eta, + beta, + my_grad[:, k], + ) + + if gradient.size > 0: + gradient[:, 0] = -1 # gradient w.r.t. epigraph variable ("t") + gradient[:, 1:] = my_grad.T # gradient w.r.t. each frequency objective + + result[:] = np.real(f0_merged) - t + + objfunc_history.append(np.real(f0_merged)) + epivar_history.append(t) + + print(f"iteration:, {cur_iter[0]:3d}, eta: {eta}, beta: {beta:2d}, " + f"t: {t:.5f}, obj. func.: {f0_merged}") + + cur_iter[0] = cur_iter[0] + 1 + + +def glc(result, x, gradient, beta): + """Constraint function for the minimum linewidth. + + Args: + result: the result of the function evaluation modified in place. + x: 1d array of size 1+Nx*Ny containing epigraph variable (first + element) and design weights (remaining elements). + gradient: the Jacobian matrix with dimensions (1+Nx*Ny, + num. wavelengths) modified in place. + beta: bias parameter for projection. + """ + t = x[0] # dummy parameter + v = x[1:] # design parameters + a1 = 1e-3 # hyper parameter (primary) + b1 = 0 # hyper parameter (secondary) + gradient[:,0] = -a1 + + filter_f = lambda a: mpa.conic_filter( + a.reshape(Nx,Ny), + filter_radius, + design_region_size.x, + design_region_size.y, + design_region_resolution, + ) + threshold_f = lambda a: mpa.tanh_projection(a,beta,eta_i) + + # hyper parameter (constant factor and exponent) + c0 = 1e7*(filter_radius*1/resolution)**4 + + M1 = lambda a: mpa.constraint_solid(a,c0,eta_e,filter_f,threshold_f,1) + M2 = lambda a: mpa.constraint_void(a,c0,eta_d,filter_f,threshold_f,1) + + g1 = grad(M1)(v) + g2 = grad(M2)(v) + + result[0] = M1(v) - a1*t - b1 + result[1] = M2(v) - a1*t - b1 + + gradient[0,1:] = g1.flatten() + gradient[1,1:] = g2.flatten() + + t1 = (M1(v) - b1) / a1 + t2 = (M2(v) - b1) / a1 + + print(f"glc:, {result[0]}, {result[1]}, {t1}, {t2}") + + return max(t1, t2) + + +def straight_waveguide(): + """Computes the DFT fields from the mode source in a straight waveguide + for use as normalization of the reflectance measurement during the + optimization. + + Returns: + 1d array of DFT fields and DFT fields object returned by + `meep.get_flux_data`. + """ + sources = [ + mp.EigenModeSource( + src=mp.GaussianSource(fcen,fwidth=df), + size=mp.Vector3(0,sy,0), + center=src_pt, + eig_band=1, + eig_parity=eig_parity, + ) + ] + + geometry = [ + mp.Block( + size=mp.Vector3(mp.inf,w,mp.inf), + center=mp.Vector3(), + material=Si, + ) + ] + + sim = mp.Simulation( + resolution=resolution, + default_material=SiO2, + cell_size=cell_size, + sources=sources, + geometry=geometry, + boundary_layers=pml_layers, + k_point=mp.Vector3(), + ) + + refl_mon = sim.add_mode_monitor( + frqs, + mp.ModeRegion(center=refl_pt, + size=mp.Vector3(0,sy,0)), + yee_grid=True, + ) + + sim.run(until_after_sources=stop_cond) + + res = sim.get_eigenmode_coefficients( + refl_mon, + [1], + eig_parity=eig_parity, + ) + + coeffs = res.alpha + input_flux = np.abs(coeffs[0,:,0])**2 + input_flux_data = sim.get_flux_data(refl_mon) + + return input_flux, input_flux_data + + +def mode_converter_optimization(input_flux, input_flux_data, use_damping, + use_epsavg): + """Sets up the adjoint optimization of the waveguide mode converter. + + Args: + input_flux: 1d array of DFT fields from normalization run. + input_flux_data: DFT fields object returned by `meep.get_flux_data`. + use_damping: whether to use the damping feature of `MaterialGrid`. + use_epsavg: whether to use subpixel smoothing in `MaterialGrid`. + + Returns: + A `meep.adjoint.OptimizationProblem` class object. + """ + matgrid = mp.MaterialGrid( + mp.Vector3(Nx,Ny,0), + SiO2, + Si, + weights=np.ones((Nx,Ny)), + do_averaging=True if use_epsavg else False, + damping=0.02*2*np.pi*fcen if use_damping else 0, + ) + + matgrid_region = mpa.DesignRegion( + matgrid, + volume=mp.Volume( + center=mp.Vector3(), + size=mp.Vector3( + design_region_size.x, + design_region_size.y, + mp.inf + ), + ) + ) + + matgrid_geometry = [ + mp.Block( + center=matgrid_region.center, + size=matgrid_region.size, + material=matgrid, + ) + ] + + geometry = [ + mp.Block( + size=mp.Vector3(mp.inf,w,mp.inf), + center=mp.Vector3(), + material=Si + ) + ] + + geometry += matgrid_geometry + + sources = [ + mp.EigenModeSource( + src=mp.GaussianSource(fcen,fwidth=df), + size=mp.Vector3(0,sy,0), + center=src_pt, + eig_band=1, + eig_parity=eig_parity), + ] + + sim = mp.Simulation( + resolution=resolution, + default_material=SiO2, + cell_size=cell_size, + sources=sources, + geometry=geometry, + boundary_layers=pml_layers, + k_point=mp.Vector3(), + ) + + obj_list = [ + mpa.EigenmodeCoefficient( + sim, + mp.Volume( + center=refl_pt, + size=mp.Vector3(0,sy,0), + ), + 1, + forward=False, + eig_parity=eig_parity, + subtracted_dft_fields=input_flux_data, + ), + mpa.EigenmodeCoefficient( + sim, + mp.Volume( + center=tran_pt, + size=mp.Vector3(0,sy,0), + ), + 2, + eig_parity=eig_parity, + ) + ] + + def J1(refl_mon,tran_mon): + return npa.power(npa.abs(refl_mon), 2) / input_flux + + def J2(refl_mon,tran_mon): + return 1 - npa.power(npa.abs(tran_mon), 2) / input_flux + + opt = mpa.OptimizationProblem( + simulation=sim, + objective_functions=[J1, J2], + objective_arguments=obj_list, + design_regions=[matgrid_region], + frequencies=frqs, + ) + + return opt + + +if __name__ == '__main__': + input_flux, input_flux_data = straight_waveguide() + + algorithm = nlopt.LD_MMA + + # number of design parameters + n = Nx * Ny + + # initial design parameters + x = np.ones((n,)) * 0.5 + x[Si_mask.flatten()] = 1. # set the edges of waveguides to silicon + x[SiO2_mask.flatten()] = 0. # set the other edges to SiO2 + + # lower and upper bounds for design weights + lb = np.zeros((n,)) + lb[Si_mask.flatten()] = 1. + ub = np.ones((n,)) + ub[SiO2_mask.flatten()] = 0. + + # insert epigraph variable initial value and bounds in the design array + x = np.insert(x, 0, 1.2) # ignored + lb = np.insert(lb, 0, -np.inf) + ub = np.insert(ub, 0, +np.inf) + + objfunc_history = [] + epivar_history = [] + cur_iter = [0] + + beta_thresh = 64 + betas = [8, 16, 32, 64, 128, 256] + max_evals = [80, 80, 100, 120, 120, 100] + tol_epi = np.array([1e-4] * 2 * len(frqs)) # R, 1-T + tol_lw = np.array([1e-8] * 2) # line width, line spacing + + for beta, max_eval in zip(betas, max_evals): + solver = nlopt.opt(algorithm, n + 1) + solver.set_lower_bounds(lb) + solver.set_upper_bounds(ub) + solver.set_min_objective(f) + solver.set_maxeval(max_eval) + solver.set_param("dual_ftol_rel",1e-7) + solver.add_inequality_mconstraint( + lambda rr, xx, gg: c(rr, xx, gg, eta_i, beta), + tol_epi, + ) + solver.set_param("verbosity", 1) + + opt = mode_converter_optimization( + input_flux, + input_flux_data, + True, # use_damping + False if beta <= beta_thresh else True, # use_epsavg + ) + + # apply the minimum linewidth constraint + # only in the final epoch to an initial + # binary design from the previous epoch. + if beta == betas[-1]: + res = np.zeros(2) + grd = np.zeros((2,n+1)) + t = glc(res, x, grd, beta) + solver.add_inequality_mconstraint( + lambda rr, xx, gg: glc(rr, xx, gg, beta), + tol_lw, + ) + + # execute a single forward run before the start of each + # epoch and manually set the initial epigraph variable to + # slightly larger than the largest value of the objective + # function over the six wavelengths and the lengthscale + # constraint (final epoch only). + t0 = opt( + [mapping(x[1:], eta_i, beta)], + need_gradient=False, + ) + t0 = np.concatenate((t0[0][0],t0[0][1])) + x[0] = np.amax(t0) + if beta == betas[-1]: + x[0] = 1.05 * max(x[0], t) + else: + x[0] = 1.05 * x[0] + print(f"data:, {beta}, {t0}, {x[0]}") + + x[:] = solver.optimize(x) + + optimal_design_weights = mapping( + x[1:], + eta_i, + beta, + ).reshape(Nx,Ny) + + # save the unmapped weights and a bitmap image + # of the design weights at the end of each epoch. + fig, ax = plt.subplots() + ax.imshow( + optimal_design_weights, + cmap='binary', + interpolation='none', + ) + ax.set_axis_off() + if mp.am_master(): + fig.savefig( + f'optimal_design_beta{beta}.png', + dpi=150, + bbox_inches='tight', + ) + # save the final design (unmapped) as a 2d array in CSV format + np.savetxt( + f'design_weights_beta{beta}.csv', + x[1:].reshape(Nx,Ny), + fmt='%4.2f', + delimiter=',' + ) + + # save all the important optimization parameters and output + # as separate arrays in a single file for post processing. + with open("optimal_design.npz","wb") as fl: + np.savez( + fl, + Nx=Nx, + Ny=Ny, + design_region_size=(dx,dy), + design_region_resolution=design_region_resolution, + betas=betas, + max_eval=max_eval, + objfunc_history=objfunc_history, + epivar_history=epivar_history, + t=x[0], + unmapped_design_weights=x[1:], + minimum_length=minimum_length, + optimal_design_weights=optimal_design_weights, + ) +``` + +Compact Notebook Tutorials Demonstrating Main Features +------------------------------------------------------ + +As an alternative to the first example which combined multiple +features into a single demonstration, there are six notebook tutorials +that demonstrate various standalone features of the adjoint +solver. - [Introduction](https://nbviewer.jupyter.org/github/NanoComp/meep/blob/master/python/examples/adjoint_optimization/01-Introduction.ipynb) @@ -23,5 +724,3 @@ There are seven Jupyter notebooks that demonstrate the main features of the adjo - [Near2Far Optimization with Epigraph Formulation](https://nbviewer.jupyter.org/github/NanoComp/meep/blob/master/python/examples/adjoint_optimization/06-Near2Far-Epigraph.ipynb) - [Connectivity Constraint](https://nbviewer.jupyter.org/github/NanoComp/meep/blob/master/python/examples/adjoint_optimization/07-Connectivity-Constraint.ipynb) - -More documentation will be available soon. diff --git a/doc/docs/images/mode_converter_objfunc_hist.png b/doc/docs/images/mode_converter_objfunc_hist.png new file mode 100644 index 0000000000000000000000000000000000000000..2867b4a6d7154cac6956006181678d9ee6e53ec5 GIT binary patch literal 55476 zcmb5WbyQV*+cmra5eY>)L_xX{kWxw|HZ7&nAPCY(HzEclu$7h)Hxg1J2uLbQha!k{ zOLzBsE%d&h=Y9YBKF4sJan6CY*ZQq1<~8TMcF0Y2#nVLeL?{&Mv=UlQ3x&dizqrp% zorM1qmhL40|B!H%zvHUyXzA)<=6nyOX6EW-=jdu@eV57op0kU!qk}NN2)__7(|uQ0 zCzmS%0`~v?0e(kkD*{1xYhfP0X_(XNWu{i%z*v&p8nwX8l zqElMY)Hh{u-al&e<0^L6X5y1t-7{Bx_4cJjLI!i$4A#vh1(2 zp~pXkW;?0%_hQ_FQGb6(E9C#vrEK7{ndPrv$8ArQiM*Ak|77px@fDeeUf+0jv(&+e zl9KYix3sX3Ph4uh8%PxmHF?SJxINgr)f{rlXQ*OdbI_1YB`R;6qHa}o(8|9$1W=g{^; zm2@34N0JH=3?W~?$_>7BO1|PoWNmGIfAEutO;7&wUwH=RomeGtzun@pAok<4Hz>60 zsqXz?HU6PPnxZIgydm<9$I{U64_2goCAQB->zY&jpc@s;!4_6a$Nd($aB*Lvb0-)GowU$BjFle})(Q9G}06l2(MMY|mljL&w7y zotJ5qoZ%G4b$VE7VpPDsRK1ZmNlS&xOH$i1oK zqNAAv1W4)V=;9?@*xA*Sf)j+Tm|0lxyu7^Ns$}I?FW$<%6Brsww7$?^s(%(ARbtyy z5AmsKY#f2SURA{`BYpZHPM$jz)bW?O1{9GpF)C!;iEUmvOexsin0sT}lOHc)OO0fo z?OwVMad78H`+oX@tKV{M@F9isx2ZVd2?>y)8v8Ev=FU{;GAYu6(1b(a-3j z@@2WNUOlHFb8y-JVB>b#paUx#+vumc{2Np4$v?^-m|wpC9c9&?^f_BQv(UWZjPKq; z>Gu9w$9vx$=VH5F@()%W^$;QgvnBVPr@voB$==;U~AeHN{kjNIOIRY-WzD2D^3}u`ltknJVKig@sy0qah3b4P)K6O};@6 zmt1)208fjD>dMwu++6wOHiwIXI!9^Wp=~>3yEIgFf4I8pDN7f-fPh5>^R<)!<5|>n zTWi32NN{lL*Gb%`B!s@Fb@YiU4@3)HI0}8sCF(gCuehFq&%a*fz41Lq_nl4T##|4n z*nkrreBQJDec!ggF8DNghMZCLRO#n8o}IbK&VDk^#NVrol!LRa#0^OeMMl5Jss6i! z!j`Q!DdlivE8G{ByRfzVV$K#T7{&0wSRehqq^NFeYn;kgNMqmSo{=qUc1Z_m+M2^y4M}|>&BXrTwNyq zJMxQPWqO|(F-b0S8c_^*%k#Y%9C$x}Ag~Yr6gFV7)}fK)+8hw@jxQP{BmUS1zmOg1(oRny>|s>AI>gx2-xVorm0B=#g+h7w(zmvM)DA9#`trwp;H@XP4t3y zPq@$jemyI3bhuSR6~}r@N5>Qb9F_aB_Ux}2v(Yb4wnu_Up~O9Fz9)0I%>o_z@#?Dc z`fNAxY5L2xa|JaQVx>17D_2fl@mLJE{`pqdz<(wq?rv9>W|`*-^9Aqei_u;gPH$Bc z9+@{pj1KuM#63bWiC()Ms zl^Cj1QadGJsd~?0ez=D5w&4T(A@4apl5?V}J%_P;22Y`_-u7QgI8}DLz&NHQ#e0@( zzFEq1i9BO}x_Dv5gEh>`H~SrXN?CBiQ}P>a#^0a<19i;IE_!dy>)H20GKZ+} zm!I$$bfZC~+4p}$tE<;ToyGbDKmym*KR;*7yJZaTQBc0$rmvW*`e4%lo0&QOQ$yw( zN2>3m?QKuV-RU=;e-f;C2OToC4f&9YJIm2u)z!q2lUE929dwxSkx>4n z$$h2o$X)JySg_mmgX%2I3-V8X5JyiQ)xCDi{qZ%VHcTMLR-BB2MM@wk&MRePw9mF6 z?_(t(P|w4isg-XuCZ+(uIC**HD%-BA>Dl{IG8GmJT)9I3?c2AQ;Z#X4a)_`S!_|K8 z+Nip7^@P9Ss56<@hX?jAoY@w!Y>jW;`1$kasC&gb`Mn`}F^BLTlYsNj&YZulq(pe; z{FTSy;Up>qnnPpb8KyQz{%P0~oC0yU4_BSJvQ~Wsw%AJ5ui;#>r+4bTr}dOolo}w& zu9)a8q7nV#s80m#2`qU_?gT?|zsv>io+s<4y(GKeA;_*^!+IS$wJte1s-Q($zCPk~ z0F9wWY=c-7?nB%B@{_lXz1W~D7uxj}on_RU))Qo58? z`xoj_sqdN)D5~_5J>6Z!Y>cqged%O-O3b4Vomw-)FUUu};E(i}yrXA%yho}l&dL!s z{Fd%;nu3fhK~v%BYRAxoh4q0Gw}3!_T|N^H8Yhc^XszbxprGD-W@ZMeK{q+UE$Sb1 z*)m5v9pdiuv;ZicH82J+Xunmxrm9Nvl$6o9JOXaxPur^>(3CYR*o5*bmZ&SFg!g}N z0F33yq_|VfKr3UMGZIAs@2~nU{#hEDzVS7{G5lqQ{FedAIU8%6q^SE#NJzvSpd`8d z8E>B*U;5^)_tB2ddt+92XL8V>c8#h%w+FD1)AGo*uV258thNY{_CLsCvkUKf6Db|q zA-zX(PR!ve1ST03)sr}5Z$dtUkGY0Z?+U8FK(}0mk`mg-hq0F0N{V0j`W2m!6&}8P zbbO1#nH2FdCW)2O!rD3ET--07Uc_S2lPi|l^UKjiZc9UhOIM_PHos=X8HXa!PfUyk zkKj!1%KncxiUfmkjYGH!%NB2-;6DES`*-2_XZmMK4GaZJ0kY)+2tcw$q{mP@kLn6) z;?JM4XN>-}P}^AedAk1tN$Y%BDT(m$W#8SJwbI+_PQzJVu9MYI^g3LIx0J1`sTr7j z)dM$*Keno&rgWYxO)YMx+SEc(QPrt6vQP>i zma*%YsXf050HN_pe$}S_DPC@t=Z^`r%FD~|e6TznaX~8d#S8LYH-<9=Lc+rGONot_ zLqo%R9gHtrvVNg+qy}*`8+$HY#ewB&kuO{V(LxRQXN{6I|}9$Hw)~t zO7(jRCC2V|Ayi%qq%i_$girs&#}CDIpQZKPdTlBSjK!VRwC|jw$q%>~&nz z3Au5F=bw*foqLb*wa#C0MTQD_`-sL>At5Ze3`?O+Y;bVy*HI^(!_msb}l%Y_G_whX1yImmHB-cs5>`fL8qM^q|46 z$D*ON1YrFia7cH}&2b)z4K>|NS>q8E{k1IHJWBohvHxsW_I5|WVGukFHQq@Q1bk+x z8Kev)ylm$;9q%5m4suL zjXC}M_Co2f)7V!+IYmVlY3U1YbHC(uq6>X?DMz7(IKe1RNll$zS;?T5c=;MM5j<%{ zm}vgUa$mWk?_Lf?kp4h|;Y@T)jCF6`Js5-~+Fs!`L}dH4Z?81}!8n&cym%v8?aV+H zhSEuDo2fsC0%n-zmX-&AnPJ9#ws*7f&)C=)Kt-OKmC$EHb1rR0doNzRAkl~;>otlR zUZQ{TGGiV?Zf)KCh!Z95MugUgYd(s94ex;k?)Z)FyIcR)bWZ-ir}Go1)8)Q1pwEjt z$&Q$vm1kcXUU_{Z@aTXvs)g(w-)A1qsOFt6Za(}W|8u{~wdsc^U2}#Nu$;UnsQIHG z=`K09b?I1c1PAYjL_{dSqyMP%a)CMF6oc7yvi4D@$C6Dfb{DvqwF+W;97iUaWc3m# zYdwATAB+?P=z2UzNyv6Q^R80Tw3GE7+hYv-_p%R33|t=?axai+I*pbsvym(PK2>vg zus04Zh~(2yi$F~{{971QnhY;1Y;*I&;dAu5F2jDa!VJnPySPowcW=v>q&%=9rrsvi zkB}^I!wJ z0D!Eti4Bi*stBB(bO=#xDJ|B}VTwu0J&3OiX|(Ho68pfabrwNyars?00j}rx9gRL? zWbWzUn=dL7LLw+Pmjqf(*9QaU{$;*}cUf8G?FquOrLPi+B-g^LpHe(5YmGgBKM&pB zhW}QB#+wtlL)=feTuao`XP)5!%Bd@NnX>449ujgbjGE7>-@bITd@AK9a=n{E3N}NM zBNIw)_9YbL4+YJ!Z%=t+vC}@)$@kmZ1>Y$m5Bo`Z58|1-X23zLKAcY5K4I%NRJzTj z;YjGv$o$i_LZO$qMVn1b^N=whx4eCEur{1dR*U?S8E%^E_3dyHKQ@0sL9Jy4^1NP& zzel6=n>IT)mlwO56NaW*3h#31z^U0E3ot6NFG*InR?k@(&qzb(y*HP5pDUJkjq3w) z?3)u#F3K}e)14W_C{v(B%%sVMUc!v;HrFNNxbNxqa?)Y=jGc-2LfmA%=uX9Tu z;il>GxQ(|TCox@=)-)A0E-{U=`Ce!!w)MVp=qGYBX6A~YK7RbUq&tZswv>4^=gx%z z_8lo|;UBmAMY&Skej+Lczcn#q|529G%fvlCo_FQOs^QTg&5fpKCsmH$HD{M0zjgJ8 z`T4|a0qSR>Qrd?fFf(gHY{594gZl=$sTsiJcwwtEiQC4LWb&t$I;BM|h;?~qhKp>dTzmKGi0jkE zZHO)fI6`QK=F{I_J5>w09`BW?{TDzb;gK?jw8MT|=aDgsg#Pj=WPUhYOFc3@ zIy@+w%daT(STe3$?^H=Y6V#|x9J`4#+h?T@qVQL%ix zOIRkw_C-z(`@B%rrnl(cbWZ`}81BGRw=2oh{iOoZNBb@)*`SlBzvmf6ih)sd3-(fH?EHTm?bc78614#q!y{n{v{x4z89FtNNx?d{I2p53k?g?gqk#1 z;V};NOwrj{h~Ky}7?2MwYQ(v`&}+@o&}X6K_#IRRC5YNbODU=t*kdyMo;=ageiDcm zI8>DpFx5Vp=9ccHtp00LQUp00o#eu?l$G%YfCuLh4ze{tSkUE9EBzdlbJfJlgrt(o zDAdTv=b$p61XnU;4wQ~h$>Wkshg7FULCpbsO@2y~^CWIIXH2Q4_zw<@SH@f14#_w9 zqmTRkot**^%Ghs1H`l0w`VCCgK;@7@7XJQyr`TbT-ecHL>{qT{5R8Ai`NQQdR{KEr z)G{6}6JVZQv!ELqk7hUnqf+8rSAJeip1Ypj#!`0#W>s~)+%)irSfoQPHHbiEjzV*q zl@(=PpXC$r?^Cy()};M*(=<}0)5TOQREFrXSDn++)BjviOGMk3Y<$0}pxh#tx;Di# zEKN2OhryZe%b54jRSCI7MyAVgnMGc1cKf83gGZaP=P^>ECXT&mo!5m(%nIK1%& zm3uzUckf~wZs(d3@{?hVpI(;b=i#Xfq2PdE9rH+r5sL1;EwjoBe*q8AOH%Aak&?{} zA$DDLJzMOhrTZDhjitfG#FpUeO*7F&p96M?Aq2ZurTrcnIAH4K-X}!{qe)%|b^%MY zJpZBNZr#(l0cqV$KkH~Shwq(gF_;Yg8TR^TT)B-cow z2Otc^-LbDB!GG*h<*s>IJ=w?CQi$Hf5y8t2CEAIdPMX%1C{Jb76kj%EWfn>)w4^{t zHK4;Vv9a|`q3DZCCNV`t-(xp-4ik5Ye~bUfbguMdV`dIz07MFP@_pb5jIt&7!Ws=a zJKT$E-R5h>?Ro*oyHxejb}3ZI8b%SOC-{R&*pbZm&-Pr9MPz+XEO+ESx`&T zgan6k@J4x$KA~}ffm${BO3eA4U`iovYm+pS{&12>Hh+xd4-NriX#UL4;O_MF^k{`F zP8s{}-1A-kp@>#ex_0+2bGn5>!BvJck{eyx>F#P4dZXM6cs3tpNGZ`??7K;ql@jf4 zJGckM({fS7U_Qe!eR-bY2NX61H98|Rvu@O>cEQ~orrzJBj;X_LK+PycpU@iRUszjK zU6-(p)mfbSQ7I7>TOT5gV~K5)^yDXphr6#38r-$gPPD_bfVZx(K6{SUnh-1L8 zMhb!%Jbqenaj{U8evQA>V&$5;@A78?S_x-tqY;JP3rB@!lUmj*QO*^%#`oVBYseT^ zzR>#@E1lH{aS7a4J#@8|MwZACn1}@iqyw6O69|P#Zv;k8@)84P6=ExEMm(#5_rUh#adZ28#*6Wr(tArGk49L^8AK*_M1^v(pueD4PWm`ctbKjv*~#s+lA zr~&`Cu-ih!|4jmDfXt$z)NtOwE3J@%_@^W7KHJ5GhyvN!*;xjq{OlSjyf&qBv6gQ; zrK|RW@V4-L##-bVN4I!*K?RaK@x^VXxf%<-0Nei39b`8Ipfw2UBM`E`O#EnX z<@5`21!a=hO^n`7N|>ZrNbpw*dYG}{lvaR#3K`ibGK@Fex#{ZaL#3DdG7c6!(#C1JqdwRE9Y2V-Um8mf%2O77_4E!K zRNo(z3*PBdy!F}TB}7$Qh977KKP$DL)dg1hY}xorV~n;x%JjIr*VZSpu*ChD+2b4D z#(q7B=A8vK1LT#3B=GZrcmyXdoYb@+*X^6ayn4qQHAc(D>|;IxFdF{1&XXa!>mgYR z)~Q2bsp-r+lSzu)mm#q&za4*M1csT2Wf)%A7RPK)oJqT&*6YtU(6$=o+8~$J5xPg=$`VV`LOTWY2$zcwlZ`M}nE{tlD0@u8q4_IgktWdgo1h}!iOu^4^ejZ!?v2oWs^ zUUt1>&B4ji4wFUTL2-a*sDpW%9SKQxZkCuN5(|s%fFyV%3o{UCEsz|B{*EBH#-=7h z@rEuSZ-Rh-LCB*FF9Izps>4@mT{&!w(|<`M5+?rkBmdurl9wT!{*^RQ$DwfJDsTMc ztWt<$PEO9_BziaL!c%8*Y3(yXca7r^15gFxzO?Z&GEQeF9V^m>v`8-GELSmoFop69 z87ZViBVa7&7f=;fwGTXP)}+q{n(}p}uvVat7X^P>g88` zuKlS$jykhI9ROX0Hr?C<{(B3E2(S$ECoT#RKtTkAUN#=elV1x_mUEw%3d$HIx;qEo zu#)q@L`i|`Ye)Qko2N8SoYLu=I*3mY*3x-GQ(!^OyTF1(^rn}lrY5bZ9WBfqm6t&+ka5?ntK6*ag*WiWy`oEe2F;*d*HV|aW zvAoiu>(I%6RQvfz9<2XFhywYAM~&2m{HBd(O+VwN6?YwZ)9~vYn7CRq)(UDVjC|us zpz2Wj+XFxlCnF*zeh)v$%E2)XAlY-X*Xjo_kcgOGP_;=f=;5<)V|#|@p}Rz!zhp*ay|J*?*Y*xLX(n`60Nus z(;+DD#J#C4lV3m$cph>7Dl>Q~`1Ffw%N~p`gM5=SbW2_Rj6>DNt;@E*NCX815k3>T zWw3_yj$Gq=ava%fI8n)YhhCZLGyMgIOq0&KCb4k@t;xic)U*A!S^wAhoW@p`-2Z{A zA-Qs*`smQdZn*mV&rA))cenD8Faj8%zO@+^7WShiAfPox>KwvA6q?mVMMpn|k>7Rh z*J&8uwJY;_jD1c6r~4Ib4M@)H&u9c(ho60qT!TS^93;%|ewA{ls06yQq>j|?cN+^m zV*SNV7nf^}bWMO1zhr(gD*A+KJc^QLuHTAv#3r zpWGKhD=Q`KhAJhdKZ-gG1OxZGzBJ6()YQ~{VGah>lc(uVl=eS|sd(m!B{PbXyK_@= zcs^=KRypK&Xy51vv-nr!zu;vf4?`-oeio7O2i*JZJ(sGsfNio5XOy`BPK9p(LV&}>i7rsR{%Y!iKhS625P zwCXTb&S@O?v143=jN^bFkb(Merz2o&pxmYGV6%S(-ofj%G}O^{gUt6#4aSRmyHIOT zD41E}{02Tq%E-t}e*_iyilK88+cwM^QB&F;C6;aUz92RM&w;nQx$tf+D+HB_&Afa5 ziq4TVC17CgwU*Yd%>i^RG)o?&HXum6YWWMXxbOC*-L0iah&tfW5T6RTDL8GqbJ%Re zP!A!Ma8TqF6!#dncx617O~2cV*!@16kdP1@8u~>|Z1C|p$4W9piF2r2QNUucX)xDs zkA(@GJ$H_05&z~_puX?k?UGq~dM+n`F-Mjts$LuMRcX3?VNL=a2_N}Y<@R1Q`QfA3P?di3H0=>jQ5MG z`dj~?vo>7t;bpxRO=j#hNwq&p8X#Nae-M?L8tF3Cj>xfK@n}Fw23UEX?wxH?5EAN& z+nynOye=*C8$O|0mcsA-tTPS_wS3c7?I)a_AD%vk4d_iw=`ua;-S0&_E{@G~dW?R- z?``Nvl_5oC6_{ECI5_YlaKLqG=sctEGERCr_V;SeyZkReNCaPy@-_v&&xZ-MhDwdOPQyO096ItGxV1!*#vBxEJXM<=CVaeE5|z z`RYuOgZAW3iHW~-Sa8-ADD^;5BE-{3#MQ-G1VRAfd}CDME>gW7TL$(BBGfW)#f{R7 zdPCsYNbC28vqz!8!jMIhE(zi~&j(H0U%5YgE9I(_)J+e4N0!af^n`cZ@;~Lw9*s7m zfg78&2oz`N`)E(VytJE{!If$io;SlqYY9d`m^@kBR>tHJffYMEuOpQ?fg(A71=5=wB+=TX z#}x>Vhf0I0(sw47GkAJ>q@|7wy|H+@_&yE^1Lr}&h^*=2K;oLR{3?E8R!>U8OwHGy zj33`}h%oPLMF%%>!cfDe5}Wp5yxwzb&;uIhUb9end^{~uhY`mRQVWsn04BP#qyRV` z)g*B;6liaxwshNnaE zpq2I&2M*74t#YfA6%KEd6^sO zqAui0#m1F3_JSS1*0Gd$Jb$4D_#eCL>AY}r%%y{50D6Z2Se_j+F*IaAT32R@H<8Rh9%*(xKu8_lKXXXK2MxbI)$UiY#H_&fQSwXwrJ=;ehC z-HS6ii2^Uhje9!`sEMhm+aCpbT4r4D!a;!>?$&oVQ2a3|Dg1l!b)yI}x#Tb)ez8Fw z`}BpZvW9i)fD6!GG`DC3avVKTa+^sC>HN1|zRc)UD*2t5vTt@gM?pmcm~RHw0uvu~kP+ba!>2z6iz5VY)YcTRpGwsCboW;3K2y+i!PxAeg(_G3|15J9(0 zLq449+qcSjf4XmWCZ;q71yYe=kda*GU`8W2EUd0Mh6e{tmkk#l1-iLxoHPTdfHedXN5&TYg8@G#N_0|o+t%WH=dZtehj+;vlLB%I#|#oKt{gYn{S9>pkTR| zemssZ?4>u>{Uup4{2UHr*gNI;&pr^(ArQ4GlDD?*`@`mZrCWvol_=W1DS7p*k@Tc1 z?%EXIGtwSkyLJZao&6n>bWZWV#KrHb3D8y29EYpH)S>|FG!Qgrp4HIFgk*uJTm1;v zK6wk3W_H7RKDzHIMV^6ef9iQ!w+Gx}n;{=AMbVQa9aq?>(1?io&J30Jt}|NV3}+Ch zq1cco%ZryUF)v;`vMs2J4Wz=50I8jj(8tmGJR+9<0`Hx)MX%~LO?e@NY+4y${Y&A1 zi3VXS5Op0mc*JW3?2j3AB~VhbOlqV-zYdCyru^6V5gyQ*S!J&{dflsRaF+hU*_O=4 zN>2xbx|_bV!c$O5j(A64>Nk$QuuKZkVC!zX8O)0WH|s#Ra()6aS_6 z48W;F;^@Nbz{n|Cr*>LWG&RYpM|>P#uKFGt8HbzwGxJ@nT53D-Wk+9u#@xRTcZW#? zOb^YqO$+XC00B>TzoP-v{0vS8v4)jMa3^P-44~s$l2x{5v$Nq|ZWZo3r_TAAxQH9B z@n6nq7Zi6qU{d&vK8?&|rXp5aI&m_t5y$Z8E$3m`=3#lw>yJLR`viW>cB?{v-Fo^T zTIo4vwy%T-g;>?Lp|OVpav1rc$oLJBoj?=~?mLZH2tuFm;#x>p5$1)!|qUX;C>kh0YC@$OyyZ`AP17~C#ySE1=8ag zpTo_Bs5IYKfy=mgM8m{?VdWU%LSIjoCJPCpGy_Z?8Ua1q*e5TJ^ zL=l{iLU@7dU98;tZ7#x?Du_4z{o0^tcRmf_wsF*P_z9)FUg!WmD+~_u4K&L8U0GxR zO7Q{B6J>k|BbP_<(Q#z}9w4N!;V-zY;WI-j@I9x{H?%c$iXGuxKg!eq)gTH0qW91j z;r_X}vXjKPfoX%jX&0bAA>TyHRYI3-I>&AF*42k~)aS-OiV5Zs(By1SsORaITnCcw z-ZJ9p)vRDCI?b2iXR}S5=-HqzQ*HI1VV*atxvfne?v*F#?Zkvdv3>uou0J7mEsdSh zsO8&AEuGQ_wBdh~3fO*G8@M!<$s3hDafN1aU(zOSB>F-C>2S8*>9b<=b!_CNouDA2LujygYpw+L}HTPCuro|p6bO}EJ zA0cVS!Er$(459m`ViWEKA;dn6l`A1EOCX5anUn<;)<4-1B1ba79NXGg(%~WX>_-2C zUK{~+L_UZsl$}NJEKKE8PUqp>Nx1wuR+E4+^->nnN>|yt{@$2%49@;@IOSgzMKSWi zH(-5MzEWr)BzgTfSf1se6e7OF%kVl8u37`$op8)1SFb;I1bFIWG6A6hkW2=PD)MoN zFA9(?591zUWI=pu@P_K(!kE-l0fh9)#1?l1=le0RWH1gBBPReZwpma#ft`8)PzOO+ z$Tbk(1js&S>(f6FFTH}oNrd!y{P@K2QzHR!DT?TPwU`BUE0A4u8gH}E6)<)p6cf@9 zSAZ+J3wD}gU;22m$I$1=I1_$n54n$LBRZv}<}|5{b6@B#9~a#FO!%mK_wH@OxaS0e zLRr93iyvTRAc%v9s4#rAgC!b^w>x<05TbeXI+Fk?CpYeF4}q4}!!8}58wdP@nNQ<^ zvu&I(SrN*i5mJW`)utGDh*ZB#I?#Ndz`*$$V3y}XNsruOL?iW=A0+|EgaCY04b-0ZI%`P{i{ z2{HH|#)=q=*klp65ZLDt{(&vdP;2LRmgbvfU`*3ZYW#uyyarEq3|m@-E*3N{5WI+G zk6Goy#1W__Vt1p0nJ@f324bv3+2~0-C~lw?$NEV^@|*Z=P^APMdQnnQg&^qRiS6|v zr|3;8N>p#}Y|6_Rw&xi_ETB03x3VLXHKerY$Q8hZ2(btS=`Ui!*8;`I#=DeON}+l5 zrax~&!ePtKJ{Mn1ij@K+%DWLr6jn%hZf@nBxB1n(HpdZDE~o`sQFZPW1!Zfc)Pe!S zg*_5BhylGz$7IO&d_OsCiXlQIdu|yWbr4!9C^u~${Lt^V{bgf{kS0iT7E1Z!g$1Na z0PO-SN(hZ`zb8L=Z0ZWbnfbwr+jIFLcJlmDeV?ed4}Fe0R?Z7k1t;{S0@KhpMfcp} z;9u#;l!&_GG=f5IMxSU zI&K|=RR6vI3k_(pCke5#L^p@12UN|m$8&p^eZVnqKIn4&$$#(hxV%j$??vD2qc+rF zVvDoy^tl#`xfrv}g-PPgbEHCQl4+ENyY`(^tqH&loLXPxJGknR?=?k-ZDit&>I2yy z;r+~^?smsIf-evFBV>QT30(Cf5L478D$EAo6EV2aCHU~bgtGKKB>?pNE02U~;%R4A zsCYnh@!Jz7M`~L5q_a{gfsztv{GHq(O6T-{k~J1>U= zbkQG>J?3kXT?ia%-es8tA8W4Ve_12Z6Z7}5{xo6A zI3duOBe&}F+4&r^kk&C@x+tOi?}FU?{0hZARA%6fs@_|?Y8Y^^kp-^v$yM0<8G}VL zL`w70$K%Sd|158XWtQ+&~q^N$9Oxu@UyVoJ=z||G!OFu=71!4-SxyjA} zX#6+9)&T_FZG(fUiMKfN!-_D;J~RcT@^xESo62rVPCzl?|UKuM4v?vy!Q zguMwv`(z+rF95o!gU-T*bTtkz1z=H;GW?c%B-n6@kR|*U``nA<9co2185E^^TAhzW z(3Iz&$Jr{Ys>*qLe;RH8lGAv=XQ_(WL&?I+Il~X)@B#C3GtX)VX71}0X#<*$gM64c zw*QVcYtkzVf$Z#B;f}19hdlPjX9r!|dc2@mfVch4lfQYEI5x|y-dojB&5J_0#H${ zEv?kxFI#0#FOD?Fu7`cyViwWmPSp&W6n#w-GR58-`IC^>gkSA&VQEQSHGF+LlwZke!#E74oQQWu8(%t62vzH{OR0$6qneP4RlqTzV zABH~74FM;GafW~cFI4r1Db>{WSC=V`kvo#jFYd@~V`moejH1X!4!2c63#5$no1F}3 zFcY5vrYdj$aQNs@4BBWbKWMp}hQYI=j))Ck)GO9=u=Z56m|@kh!g<-;2#7b+I|sWPKR?+rw}6@V;th~oj^<7zwk0og zv_UZavjkY5!6Lln0Qin*#T*PLiv+5-abbDmN%~Y=T%7Ho2xc-P1OH5Vv{MCMhsb1A zN}_#^5yuOG-yk~ey_rbDejhJacCW1wun2TPJ1UmPEpRbQL zxuyuX&)q*BE=&_*VXTuEIvMj1c0=#NeF&3I8h{McL-?Hm&++GXitl5h@K}o8wYJvY z^HJ8-Ik7lD^|`b9`#(i{K6pwb;d#Dnv%#%f)ch6mLYl8wiukJ7{4OZV+@ys_e_?V} zkNB@P{$CSGuf8TGeu2|o{PX5iJ#ryLiG~i?pSt%F7-B*S_7M>OWFZTG0HFpsGt6ftazcAedHMf0pY8R1F5dh7a@?Dl2b}5l9nlDd?S75d4O;*+^d3kw6 zK3f4;1&HMWc*)L|t1!1HsZ)PAUq#2Inc;^ChnMg_c-Pr^`L}uGMJUOUQk%4h(1cJV znHs6}un)JgJsye7qwye>AQUKqKav0{vMU_9x00h*9vzQu#D^&_&c8p9NI(pJLzP}x zy6>oOd)ZDTS7+bN+@_2EBi&R4au z7dyP9xv#rz-1T*bFthA2uV!| z*GZeS0kTw|wZ>gY>_0=PQJE7WiW7e_{$SaL0Al3+S^q6<3z1dP7hV>noId8x8MQbYmwB# zgo8(c3dyOjAdH+oCrSci$5$ZVoPgt?k4%;Fp+;PM$jS{Y8zV02$!`rRfiFvK3u0mw z@wZP;N@|VLG!-PbKL0y^sx@A<@4Jlj;5(I`g3^2Q!Xy_YX$M2 zrl`IWRfEH@yU3rvyOr`nnk+DSz}s6$i#f&oHt++yo^?UTWK}jGPjm2F#DirRVTehk zx6|scln#0G{OL%I1aOb^C_b1~4}3J3sP2dBl(A1t;_FjY)BMka;m87~TnM}nvI&L^ zL?CEz#|=a3fF7RLI7rs})RAejNsdmhuR&H>rkY0NK?;q_NIBa5E0V0&@wg(PQw!Z^ z*7|Is&`e~G4Q|}u_EAA_t|f&WHaS*MYjn1cV@$#w=DB}y3Nxe-PC$lVl4A3~{|vJi z!48I1&r;dj=d)sxr_>`N4tzo!SSgv7bt=n*5v_!yrJcb=8{GOhRm?*4xbmtnWq>by zPLvJ}?YrNbxP7ePuPNK!YCfShjT1t>r1JPPcK0+6F*us}e~r*Aq? z_Fx;(j)?sdjE_ie|A2xC=X?$n0D183t$=TxP}(_twz!prDnd}pxx;)})`HL4IxvXS z(aWnAtMv538O&WE9W2dzWpluUg~&n@SC+hl^|0`1?&vOpH7| z=aA)_o1Ttq@X=0ijP0y0k>UqJwz+1%j*-{L3{Sw6rKM$?pyuc3Smlma(nhWC!IS^w zdw3U2+Jf%$cZ#6{s%KIF@m^$7VlxvqjJRuod&EO6|9Rzj>!cz5ue=qp`8O2*v3zP^SNor4uxW=fYO)Y48mWVDvV4-T($0cVO7fXF4+wtpv|u z4x|S}p!^Prhfs%483Z&hS@JEse5W`?aGMI5{PvSy$;y^*etbO zxBqtq{8Jv{14P|~jbhlor-3(}wYeQmCydxq#@@bi&~p91wb37N0?`b=yXw<@30GjLV-Af@v8(Vje5w8UxI91x28c#+&7hk|SLszNix{^N>bjhT{{r(h0KV+Sax~(f{`DEwWOC*0OgDhImS=bk!wNkh=Q6E#h3dTaFfI6=(Ivo$(x!w zcjYX<)|68^fK3WMspcYCj2*4;T&3_`b2DbC+uwOOs@H91#08w*nWT0|2tIs7k7Dr9^$S}%TI%0}?- z8P!BqwU0bv1v-CMF0%BzRV}FZeQu1h!vyEE$-7uKeg;`ZfSqDk6VDiS+c>F(bavEs zGH1_+N@(oYN++#T7wLE==O&t7qD=4bcrc@apXVL=al+u8|IW<-6AZ8;W~qGUSiAUO zsWj<-;rtbJMnHBp?-a}0`0=?0c2Q_Z1_GmxL^|S;M3SuTQ6yrzgMEwN6&?Z~9R@>z zi+kHQ4r|O8QKsNmxK`>`cUlZt5(PUN^7R%!fLOGN^ikfO`16jL{F@jZeZH)6)5myB z4q~ZQo++O>#|!p&?M!+X7z0-v`Jo=j&cgSC+<-5-K)$Gtk@bL>7TfNeCrvLoVEdNN6G*rfkSK1q2g2;d zZDC~vo?X)~j|rbvvokv?*P~}ZpP+dR?%ZUw|AK{sq!<_ZvScQbx#foZpoh?2kn?H< zRTTU_UtnuH2!I13>xg?UGa*J5%eF+bAL;VlzhuBy?7lb<0&wrw?_VZIySH<}YYV@1 z9U2fKp&~wGq>zI}26-6R6yawr2s>qJovOR?Uocsi@7H7KavE_;+4ET%)|?t7v5{3h8nHD^6~E7yUTzy$KlIMWMO7S_LN6}{YQw_Sbn3>nV*^G zwv~e)e)%#xTws70oTB6Q0@THU@Y*~_7@y37pjgbqDG{U=cOlM*i#MK{g1AU4=~``Zsp>q*A@ zQa==Hg#W+i`K`Ww45}I;hdk(z+A^(uh~wX%iia39H7vUJ@9%-AbHA6+J|yeyqeqF8zBccR1@^a%&yqbMJ^G_n224-UhA|bnd{nDy zTCvWsC_rj5%+968%zwY%Bh9R(uA!8wSf;$^8F=f-U*KNEGW>-jrH9f1A>z}r&_|-t zme`43h$GMQy*{8CW+JM?s@F~wxBA3D_x&~pl%9p9WoRGFR9yuH0p~2a7RCwaFgwdz z(J;;kCa9qs&|aT*1*6i@aY-Z-6Vv?);_MUmm~_t%hb8`YX=Lzp&|)3&QbVeNK6t3- zS7HB`LE0C|iLdb80+C>SA%XGh*q{A(Rn?@9kVQyK`QtZI{-f<7c;GYt9vCD|{Hh^HIdq_lFe#cIxgiTn(G(QU6mPPAQLzJncn$Q9+w7PS=@E zdN`A_k?N2KUsEM?YG?*U#R@2_~X_+E^-mZOK8(;l$!;uFNM=}t`br_ z9J@Q&Kk?s~uudh1ZRN&}4n-ZxihK$jtxF;S(wA&wFDp4Z+l=!P4?l4)}=n%Jw#gJlEi|S+ytG<5XDq+PMV!obW9RHt;(s6Zl z{q6=v9ay(}3LE1}$b8V21%d&rD16@^_qpaxNr@t|B+q8&QE9&4&_H0U(NTtG{xG(q zg1l$gdU{mXp=$ybf5csd7%L%#kR?-uy8eZ$`?=^imZQ)K3A34UoWNO&`FU?ldJFxM zv;4Le)2aaWTkxi9zG6-v#wWsxUv%7-U$x~}iH=?0X>QA-gJl_oPzXPPC+8}p&nCoc z(s8x3+#{)`@g-g7!9&AEAAcuZGxrF&921j)HE`=f z0TFoeYI$=C&|qUrOC9VqXliLOS47l}%34~!oi?KAjp*#GK9)POFE>{BdE4YvheyAV z<$fX4i1=4Mq2U^8+GJo)m^`E7D#H6H!+{Kd$$(72uv82FrI9nvmcmiYTI_eMQ(M?d zQ~+j5prwung}#!P0r?CkwUD7)N=rM?Dn+x$iJ4u&I|X)WG+9Uf9;NsE`-VdI1$`uP z;R`VoVfz$8U7D{rLeYV^*<*L_QFts4=(&{tB4v!g~ z#hjzapz1Iy5;}hBdh`aEGQrfzuMm0Rxq(ADKC)AeK%vPgB?;D3@w<%X z68^AuXBfOq7XQPj-c!knu#4dm91`;R>QZHp$B-At$frr~*%!ggk2P!9Nw8lp%~l0Z zY(Hu>W>%)|%a@l!rhTbllxAA<{G@kdTF-AU`MKC_5G{l#I4v2KMO@T z54*?DYsEo0fpUnvi5Fn-I-vnU6Y?2xUZ2#mAlTo(hy-E@e3KKvXfk9KE7Rh-dLD30 z#|r@}dyNs>J2#LwLNDcg8Sx_lgbwXv)s*Am?yPwpPn%{`k=UZw$DsfKnn+6I<@pcA zk$-6b=*{B*@sI770Jh3@dJ@oayBj4kTSYB7?2DC~eTk8_RatjGgv{RQqq$@D+V#Sj z|EeOzN!P;yA)a6rO!P~l8e-N$Azxg9Y{0@HU%P(&(Yz#>@$q0ema4>-*+5zSq_cCe zl$Z#W=j#7q?9IceZr^`zLn=c_2qm;6mJA`OWXP1vRtTBO)S@CH(=s#}!!lDD*D}vT zLZ%dDhzywuWhxoUn0cR?&BXzY!}1bcvNhkq)&w{KZ4@C?6o_VVRC*H z1O~Nie}szS3QNPL19tB6PT*RPz@%$IOIxRZ_2+PC!d*@1=4uJ3ujkIoCduTy)>Yf# zKBV|7)>`r?yVijM08g>9()WGr$v#Ky)YjvOolWmo-U!Z>w2<#?<_d+zLo}#4S9!NPV_9bS&}Y{CLx#E zj~_RCMpK}&C%g12F)5~BRVSahO`;H#1Ud%vKIOe-Y)Byuow8z1&VE0;8VD@QZ^Ur0 z$!+0Yfv!4Gihr1yDX_8Fr42DxUiepP|2M=AxFgUSHomXPB1W~T2KFm`wj?&uH6LiC zJ=QwD8;1#1fBPIy^j%OTmhY^W_}uHd#M9O)YC-p$g=J;GT(V^tde2(|7%xQ3f{%me zGHY3eDUex!SKmxz+b4O=Kll>}j2jmZHLtwMohu0#?Ub-R{L}LDLeNI=*iRa_nuz|J z`%#ab+FM&`4ZDv-CHbaXLjHv%iHhE3-MLEbGVKaeAEN|rdCW<9d6DWh@sdpg$U-O5 zCBx|q1|}J)u>`|`3`mCS1u5MS3op(nEq$M8<_p3!dNjaL5Y+p%6dwuEvVP-aJEOUg z59Oup&wj|O&B-cVXctoGzx5{9D@=dp>s*oLjC7*nY2J_YCtuhT^ONNTC$BWz>7s`Y z1A6aFU3&D9y_70{)U^tEw!x}+3GJc6U&sWfu;A7h!%f9-GC?vd=OQ)FIir4OFwouQ zJkABbJu=?NSwruX>$Cs)!+v~9Lk=UPctH5F;mNj()tReXp#8hwRO$P-0NGe9(gG2kzJ|+SVjSPFWLzdsArL zzs@0tQan77zdFuq`o2hK8-aB{t-?O309>Z zOe{dFE|%hEM=~V>9$s^(W(9SUCtd3W9R(<@(nIc(M@_s}$1(RWS$U>>RK?E>u+4%% zIiY`DMeXa|yV>;}*LkevU^gF@D4RZAP0_9`e&pLsJ17BQdX*aii5$iEtG*(PmLSzv zaej;uW*{kNwWs6;&v^V*>w2nf>LQtiYz8i&JW)DPg?DEpQaVP@-8!0;wbgWV&9eO8 zbW*>_ zUL{BY3XJs~v0HbAvr1F6?q8L(1nv@Mu;w>`BI^h_QC_&jP)xsr_)(GDpBqRegyjEO z5YQjN5f3#>^PrxhYU3T>jC(Ojq+59{C^RE6cekJTzENx|W?>S4hl7JC16Sbc&idQ`{3bvNwF#Z!Kz9SkDY=U7J>80<-#lt__Fk`5& zK5PpRG?o~AEl6aC8~zG&RDFHA#nZ!Y4|ncX-xY1;&x=$S%t6Yb!GS0IA{fx9^G6-e zo&vG#KN9~f&0p+UsMcHxrcSY|_G^22wTWE`le<$Ordxy77HH_E zQkni)MXl1EG8LY|d5F~+IsgL?Y6DbTXJ6(ve}o8L5fhxQbka_Z*$UirT5ZjUZGU5Ffl;H zA{bs(Uhv6*(14yxAU8l+MX@qx>jSd7GJ1td&pbPzJ7D`bB+Aw-nub0~?$X$6!RZ0E zzpq+7T8X}})c)7c0<8!EGeKE@0u+H!P=-+u1W>Uklk^?pv!ITu0NNG>kf#UBwRaYS zU+maC4y=Qn$V3CHD&<7N)pze1T}sSO?K&?~71p~~k~n&FGtc((LP%86`W)wf9w%gW z21$Da{>6=%lefvA?Zu9UH|h3WbK|<%_Oc$cYStMtWQX*A6xqJjg=(se}ASP2tm+EG+8A; zREm-UP8ZRzk~IGY{V?SpjLgd3=GTC2BXlcRnk^-Nt*6?AL?yU~t8&|rFwDrC5(AP7 zsL0CDCj>`@4hZBB0bmJ}T@&B}g6nhX`}@Jep#=W${hVigfqQvv=bqq80#!w4=-I%4 z%JPG=xY_>HNv-$l_2}uDTqr9%VEF35`xfe;Am2X2pE;#00$AdSh`CRS9uS09|J7X} z+7=v_aJaIWeutF-Cba8tV*3lq`6+;jAQu3h?COc4B19&LQO^J2E14bv-}%(_nY zy{IK1fwOrhFL9mEjpz1RV}>PHzy7eq z)kfH;SDiPPdPmoO6-aqVDZONYIPVshtxB_-froi_2r(6Q1=e`X%>9polQ}5Tf}uI1 za^6L)S&IzGVrcicO<@5VzF-CSR(w9 z5t(z+E8%iJeuIaV1D?2&snvuS8?OUoC1o0T$Lh+5)%<$?3&*2l!a18(a^f2YS}QC- z90LHN0Gy~d@}=NC`BZhH_$b+uq|kHg&G5Wxn`%-2F7kAukYYt%c}yluyzQ)ce*iBhm-E_;w@HzMPn0nZ&a^Iw+FV8NPQn~yUITJkU0J8$2tm< z&Q;EH)KAa(AdzlsKDHJ?W6oN5Z(^zh41D#mNAZE))hF+Qs%(iESyctPTM!Q;oBe^X+F$+#MTdvGgex}!hv z#|0eo35`0$wCwKg_WgxeXUcElFOecS29qShvkx}InqDK?s>*T63d>E6^(=<4d>)@; zMTPvWTT9j{UeyM-@FKW7BBuzIi$0Ps4$S~%rwsVlC?f~G41Z8k;H~Z7dalZ!2T6Px z6}23l8AZ)}Ax)85cZ7ep| zI;Pu0K)@P$xU+!h4By5Y9Q{ox`0+A@bG2`H4c|aMcyf(~svvz|;rS0#VT9DB-K~Uu^wf@ADVvCwQ%h4EL>h1Tq0wM-+#e_^jDhBMcu#If9nC6fGH{s zdr z;HA;CPJAO17GqXlJU0haS-MICurUI%jw0jrT6FGriNlYWf&- zmp#ZrjM$D)>0;C-)H+ZP>);zb%nM+sq^hmIetaV&>N()eJZEXYV6L|Le%1*k-sqLJ zAt?b^r{3^x2n)|VZTG5O*^`5Wb%c$*6h<{O_-timxsEbf znI20I@Cr^jvjxMvp&8(bM9)ZSE&*oqH&pIxrm@i47q6$v0`D$|jLMXQ&lTDB09*NA z8>>^x*ID53azO=^7`Y06yx~DOb8>s*xz|FLS@$Izd@_qqoL!PJN#wthir%=AJYOMJ@+}-)MVX|GlB`ww0rp;G+HaxUvr9_068hUny5;ZVzuie*x%>7ygBwX|a_V1!$hArk(L3uL8Z^2Bu`0noP+z2zR z47~}dyO_e8#I2df*9xDd+3@B<3C7CCmIijoI2q3~(5v%@zTPn`mKGR6h^z)SfDHFR zB$EOGzb=ihQ^mf7Hfr^QPqfQ+$U@z;3^c}h5f1n*p0h`3~V_r>s_3x(RAk*O7BcU1^<7^se{4c zdHM`k6%Y{>Y&*W`lgxo606o1B#~HJ*a@2mC578Uo0M*WS#@(0&}Ks5reFZ6|4hokpzJG5Vb}nk z%sXF7>Qm4e>1k3vo&byf9?!(Xsj_giTiK3dog@}_z6*yS3Gw#a44fEPLXI}7W*z(P zB`g$mr$gYj9Z6XuYKe~1!Gk0l7K8HJ*ItFmp99u}^~gx9PCa1MYW$ZH&h7Pd5n z1vn_OUp|Y8*&W;R7(7SnOJYnM$NnwzjUjq!L4VeDif0_HYv07zGqI|=&mP#5(D1IS zAOG6|PpIm0mWAe-xY9towgYzf)m>cSp9aS7p&xpySE$%Tscb*0a%5IGD@qUX^HRV1 z)7UZ7zPBmVD1+*vGu3Z&FfF!jIYn5z_ZrfQe<9VnKcg!Ud)c^7$ zfNJv1sba*n3S|*_AVmO3f8FXiZtv}VphZ+6iav}52r6HN{wF$ABNYUB0XLxP$qoxv zE!An~wSLkGy?N5CvKqvh`Ixu*+(V*T_@bSxY6qfl3X{%#C(@(`dmzzoFgDc2UtFBKDm~-6=MKjDM5Q1W9uR|_ z7ykDjIF7aC4+H-bc^-B;=Kx@6TbH@_;{XNR9bM!ufsCr)z!2JPI}{nwpB{JKC3|8N zbFl5!f@;>+#Dq=v5Kh{SmD=WVG1proRRn|01GFz&BkP$Y?-m(=72Ei{tx;Y{Bp^i6 zEHE>Z8B0s)$m?i(65`!^ux^N z?MgyyeqFRr-tPfYuY}`_T9BX3|F6YMTh6B8|~v~4*T1@qadgEAgjW8ocn$SiK6BG zpBu*5*N+&bzg5d16tdQf^MOOT*U|U`DBzBQDx;#7>~~1%da_GM)O`!`#En)4GNH^~ zy+87DB#BY3f_^%VeVotUm6O*xogp*3X5*Mp%WKYJGKUn67OZb0e4FwzsV!_7^tOaa0SwHe#2u&f9@s7 z2`%1YN0g1@itLjO5&h)}UsYQ< zO8IY`dGuSz;V8*yTeNoL0W>W!$Bt1V&U{%Dj851`0ro6s>vTb>j@%@r-Fsc|N#%~a zaa=XrYP7Ud5(hvIpz$9JgK`3yU* z$h$NaCP<5JxMe=m4A=_a-zyt3;F?K=m9TcCscqrN6zaHy}B|EI2 zfx2dVh5p~r9H$CW^2Fwf;(c!;Y?bYY&YJ(-jAA_c2PlyTC{95m#CH&S%lp3EDWC3z z?VgeX_D<(<@l>5Z8XAX%+GexvlwDbO{#0vcAml>3ToZ?V$cy2PP7pK=&%92Sjxk1+ z-1QRL?O*Wq`_r|Kj#U1FrM){g{#tYw?d$dY?x-6Br|}WrfQ2vG{-|MnMP2HxQlYVH zdxRgFWwMisMYfZZO-hs~v+>WVVrBBng>|j*h(j`vDB{lCHhv!#tGbVmInqPpxj>#n zxfsslQ4Xb&zzTVZ`eZi;Cz;J1+97dbQ!j6$AJvcLW&L$S8S<2XB^8K?5<>HMIVW&&z(4|K@GbA_Vq(UorROch2;=To$#bWt z2+T-a;UU``G^~E3KM=bE<*lsBQ?Yj3IGWRtGK&#~Vy8^qWYAN3ud-|X5BX+>NR>e& zk~K@uYcnFb6+#C`9DZ}|d)sx~?z0f~$lrHtxb*By)$E80H{GekAFEygfs}`(cAvi& zekYfdZY*)C%nE>+AZ-ytiQRsfVWy+(}iA+!&&r@u2axY?(11 z7;kHv8sdq#Vs2>@!(Gxg=rP-5=-CjuaNDgZY{h)Swg;|hAP~toIk0^FF72dGh?^OC z-u16%#*>8Jlc`bXu(aUPG<m)`jc$9ZQH5dy~FW9uVwR>)8#gy z3!34%>`Ih}_LC^;{)PY1G$YU%92bA+T3K5k6B8?HMBW*Y7vCGWMJIrZ1r#5Md(q0; zVYW+OmJL;uz!@!!*a@e6>%r)2F)(`RZTou$tz=7mY43)rna%KHJ>0=jfA$XLnhj)F zcizPD!*j4ox9G7H(tr0X>DieoSIUcr<*z(qHXA@}l3N3%v~d5Fp?Vu$f@ZC-M=t~= z%hK216Q_oc0I$uVB3^ABb3KGbCwgaJ$sCW}C)s|sJX}iYG z{R4*Gy_)oNDs36^%=6j7tCe^~mXHqlDHLypeSPYFstE=Bc@VY%H;mQIyq{Zyff6+X z4qofGFBRg6^Q_JAP1Pp|oyW6e^1v}$N6pCYqbrzQ8fMqIu=QA)mu%blLzN++EU0u? zOtL`g80C-8nupbMKPO+DN>U_(ey{{y&+ka@y?5_4avLHkYiUOI8ir_L>|-4ioa4j& zVWzzyo=@DV%5RyKn=ypbNG3c%oF?EYtIsX9&|tqPc7y$-*3;3aS6S@obbPR z*l4eu3_lBJJ{tN%=Z3mTE@|Yvng2t97iBUwlcSSe*!)nEFuA zsLV9{yE0FSIOm#lGUc#$jyE^)R2fwuRM&68T26faycHmz{@r@`@Eo(0{iIUdky8Th z4%4Sp)ZV%(u$G?UwdOo&`|lS))v@7W-1vjClhgL!hk*A(RaG90gg}lLz9 z6Znx^W(A+cJj{LaHVp;D;q2Pk)pd7uJa+Wu;GKpYM173F_b>M%<7WO=#p%y;`m~oQ z@UUW$RQ!YqbiYn#4Wg^xUPEcvabfWau_TT4jwN_W&RN|5h{C7P0m3&?I}Rh zl$3iydVtXQFXnKfIJ#SJB;K|=n(r*<{Qd2;w4Ry4{eF69AwFmKd|7?@{9v!u1%!VS-Xp<@4JxrVUV~+;G6*ugd4` zl-(Do_xsBS(?a=GXXBT@3CLsjM-}JL-5&C9M14A=Mc~O->KMBo0VdfZ33N)ZDUUP1=z87^3I4Og1=6 zjrD0tp4=>2f8l!001;9XPoF=QV&^{jv5v5EnZqq+0dG4|dr?Ja&7(}u)iHz%4>!>c zCCoLMlrQkzccT0`+Yk6`?rp<`q98iLs9i3c1pV^~u5GID0G&^9+g5NnHhV-!W`6JQ z4#mdllM#J<;W*<=(&Ca`*7OLwOef|I9bZ6hgERli@9T(hSx1q4RWw;QE!#yUET;MT zm`K9Yy+}H_!o&KJo*t6f@hSa}estETTKb1X$>siLYY>SvJE9wu04vl!xuzdP188}0 zK{(P75{n2cVeYfZO3_hlt&VzHNNT>&K)~ojy#HqxS(E}KsF9ok(zfTobI)?=l~aPe ztUufzKZfKC?(z-jayv@#z4KWO{VI;Lp(9Pl5R0d1Qn?Jcd6gSS+eN{=<6CCGxxE<> z6d|tb@VZ{igY*>EAYh2RLHQ2w;J>Q&e&z!WHAK)tQ(K7f@qq|&g1N8GqWii@#+^!_ zf-!J@z9V`$I*I}yPZA&2V~$OXQT+TlPu-lCNECN|*}~w*GMMy>IcP=HgzY==@4{&X z5)DqxykG~#<5?rZ5-cac&BScFBx*M6CkjqmwbR{RSw?1l+dBM)X28Nr-%1^p29 z^~Itqcy3X>r}gq`-qkR-Dsp~e{PHL<5Tyxa!0ie~qNY9EUcRXMLHR)#*@ZNN@8}KP z`Tu4AQjp1HbTvTo7x@0(ngm@S{&KHh2G)Zsn{~z4RGKx&1RG9XVDPyt?n<>eIkO<+ z3OTa|5ld1O&Z*`QFc6vSKpr9gRI-CL05!7_=Ms!rzpFk1k`bLE0B3CgofC}KEBMLt zTXn@A@UebT@2A5Kr@*cB&M?&y7^-!o!J!LEC4rOd{m`n{yUZE>xxKa9+k~Y8L`Zb_ z0K@Eq{9c&y0M>97^nsxq5;!|I9}8IatXZmd;V=)4tA_EhV7s7e-0w3-Q3Uvd9WNU| zS%PlCLJpl2ukFp1i@k%DE+-GZwjJli=)b1MezGLJ=79d1KDVJA^=>}ym#*(svHe#I zo7xT_fsh+4Fih(@ya#=}Q!HZT)y7th^++@9rLtidFeTeTOaMWT(zTO9o#F>a!GI0v zgtyS^3#os&2SP-;Z~xpm!;}e;LJn;56t((o9t6N=5(u{E#S|nwf)B@#&c-##n5^{y@xg zSpNPKng^;M7h=I6ygg@a?>D!Js7hcv6hf05vd7Ta)_toxa4R)cVe?&Z#Jm_2cekHx zVeVFu*sz6v|0Sf!bZD0Y?W5 z!PgK@Ue=&a**Qj`Dr?eNmFzX~nB|{oleTutA@I@#GyR0f)Gtj{irMO`QwMUo`-)&n zV~u6n`{Sp>=Ydy!y+g_B00i$-rUuwntB z>uuKLh7)h#lg_(}%#^It_+<8_L>cYlL;a`ep**i=AXRd3tc3<+VvoUGQjWC31Awy0 zp4(pF<`LQd%B^UkGKG`3r|e{S61Uena0ulJa}$Z39!x-o!^7x9V$C@JxpO@wp=#x~ z)5UOHn6MACYynQw-M1e2MT$*F5D)fmT@c=9Sgy5NBYiJi_EKOej2OuSL=J`HSC`&n zA|m%p|5&H} zfVq?mt8(=4NxojpivT;E(>G!MC^)wWfo1UbdtUHg=?l;GGqcN@9A@TQImRj!-sz-! z;A2P>Oja4-4`Fyq=NFYICQEcXc4x9v7S;&ADADq3vg)kUOExyy_TrR!ng`_wm6elB zl;^3?#0G@O25qsYh94wyGdHL`*?zpKxH~%4A|dWOR2@B|eJ4I9xWEyV-j|}n_tm5C z4BmlQ?(J!RPIM4fW7L>AIQ%S8GhjHTb+uZHWkim=Z!e08Tejk z(Zr2g`p{ZPRDgTV^mAh8l}=kS7$%URj82oMS-yE-+Nq&lYMr#?wWP6}AM<&V306Sx z8Tv!EVYjIRxVq5nL*&{>NTi=@m!&80j6Wmdu7yriwN69kX|5o#DiO}uJ4=l9H3ri3 z2Xx8EFf?k+>h}6*hzuzjEK}g7gUMHh9ZR9ya-s0XqfmL?&x+qeuZ=e1f-Jc2)cENY z;^fNwq9S^kKhg(Vtam#1cI84nRamOcARWD|46O&2)KQvyyqW;x4p66&T6_rrdu>UBO(zWlw)g?ekA z4R7?dvTmQ0>QlZA&4b#c7)UW!;gujShvGf(y{dC!OvG3kdeVNc$&Xn+vk+d{9?A>> z0FW&l7fQ_>J!WIH5_VZxe<&{x3pE&~{B(x{Yvwix*!P`3TKxklb9u7n^)?{LPj1ej z`9bViJvmoT+WBZHO`UxqAI5d#rS&}?*2{4AU0-f;E?qV?gatAXXRQsmGh)pOP~^T{rUL$(?GyXJ#$IPEGYQht)?IO z1Qn@gI+*A1=(CCa`BSGUrEh+QaK0niZ*8 z*q!?eLzN}3R4ymwtkV3R{*droHESb!-;VCAA4lQ1RJgpB|fP7tu_np7N;~&GJwP4^Wu_Z-$y)u^J)z`hgiQcofU>bN(Wbd2J#~U5bu_5vC zD(YWj@}ST{p8*6-m;&Xwa_6*Nw<`K$8@Jbe8s`+jjpW1j5gKw9P08a5U#2YK6!Q)y zI=oJvkKNf$zui1jFW+nooA=bV-Q>i=`!=Y&F!B~WF3@?q0X~=a`y5p!CMIq`z5Amp zBMcQSA$z!^Y%Cf10YJrwJYXUR6B5WdW2D`YRIwU zpeidXelQl6TuLhHEO4@*m4AD!Ij#J`lx8i6{r#7yvih)Z}@7zx6|TooC-XEo+@g) zAlh%UmjvI_zob=l7-^Z)Yo4j&UOj95aS^FA?n=IO@^loPot;R~LTn`%_>3l#X+1yd z2YD})Ezh}H&Nc{H`h-IleY;!<@-v(*4&s&YF~0L<7HiSo@2=4h!9G7&iHpi9(?OpL(zT)Y{LJ~on_RkeSK zN_U?OY-6`S2v4$O?TcF0vrl*IcdfCpqNsAkuHVu?W1u=43W0GJ5)Jy|W@#V24HWM| z!DR8bFm!6cb8L*_(Sz>q97e}4L2X=c_C(f^2 zj`URy_AM?>7z_v`itBQ4K#XES@dOo*TSzyY&mM_cHiAFj)$#m`fY8twz|RE#IYKmp z=OT&|Jg&q36QCmk% z7KC1d*Bk5_EDBGLsK+O*&qi`Pk1;V*zhCnCb0-s93B6$h00{M$A9@~s^^JV98JPh4 zUxNq-mPjUW4f*L+dklmI3$TN019n&#tt$lS71Dz)Y|q2(wH!Ta?*(Y|WnC@s=otI< zl~QAo9V<+A^x;tnTupnCac_M6u&iVSNT8dyxQg>Ie=(uU}j`7e&PBseucF{RQ=YXUnACJlZf zWLtqTiL#JDt3k4*<9m~`im!JdL=WS-c3(*#;+R!wEbsA*yMHl1q&a&IPBY}kCitY7 zO`~JsomU2Id+3#9ly*Z_$r7Jb*2gDrtrC>02D=zI+FAe?%;EvU%%9Po*cWGyZC}TT z^IG4-C)pY$&p!Gl|myr3T22uKeSmN2=7 zt=+YvE8qWzJB*5|0K4ilQvgX#%1Yo+@(PQg69re-*#mI2`nvFXZXj?!=?UW=5wl&z z#lD@L3GKn5`Kz3KetJ9xRfPw7%G&AB3!24SSt<%MIH)Zx`^Hz4KKuflx6ScfdzfN# z)i_~|r#W^-xjKPS*vBubfpW)*&j9ag54Y#CkwtS<-Fk=9rJ*Sftj}m`>wF~vY)WTS zKZ;4NTc|V}PajOSBOG-CqhQMEr0<{e^jm8FDi~`WPXM?9pvqVa0E~^iE|C1xeGBfi zVp)%)=Wt6tsCxCec+u-Zcm$@+Vf@cnB#a<#o@*Fh-Vk0`@v4|p7Q411&%zPeQb|Ry zPaIs)hjOe(Ha{g0=O>&lORl~r~hV9WUB7$^v56i9bG%pd(Z z)s)Vnbi>+)%G!FZ+u%n&YgmnihS-`3OBOUT9zUX*DmL5Dlm6-fw!Dhi~Q8R|(wo0DqCO{H-#TepG<*J@{=>1{0jgaZcWUrG4mkCbGlRVpKvZcE-pkfZPF27)XcgNo2g& z@+?3v$6W68`nkJQXWa@XoZx_I1ERUruv(^jJC&HFidwr^|F~8aS1Po!1!qdS+Pk{G z{P(mV#jY=PB2t`-R?y)duX?i^XDlcardkkwe?}dQ8=yNYR$s$hQ`g%6wZ@BoZOP_| zydYG|!XXKln*RxYVmG+5EL!4-xR2vhjbVGBERL7(d(LUmu>0pQ^wP(fPf)yj*Ld_H zEC(_(?PW19PqGhav*@W(W5Lk@;k^BKZ^bGc*RvDUIjL0gCce7=Q4iRy!Tk@f*3OI2 z|0rS!+}5M`JB2Vc?p8oXMLmKysuTj4WohN>%xAL!uIvc6VyWw~W?&_mUkB-HvJhq| zBZ4y;Gl0%wVCCM$bL^tsuS$!HZp(88Q71cI>lw7GeqhocuqBJ({6f{WPrdDw^@JKi zI9y!anHqL3z$f8_Z!_v&zR(Y;7IgcX% zvB(|e+Nz4bz6Acje^vb_4lEKUHQM$~M^xy~pWk><`{4ub92t}@XcdhC;-d%Zo!Xr( z=0BNPOHgPbyC&}2MVo6v3;kBYdw*VLW{~U3T|6?yag!e}Q`axdlW?JHOJv55Zao5< zByUVb!nClo{rTc)Daig#7r{E&GjNM4d@Dw7A*3?t@=l>ut#JOBC=*A^&nVg4 z$&bbe}1>EV6??2u_kE3x%~z5yuH%`L1kh$ z18M9h-X{?SPSf&B3DbrzW%x19Bq4ooIh$5?z=G(!zsN*nPn34SNZRQ+$H#Qa^2M_;`RScX^c%5@ zueMJDK^96xeoi2!Cgwab75Pi)EGbpkG8YKgxSe?h1E1Eb+}U>qaX)?~xC_(f7uEIi zEuv^XqDWn7wBVRE@7P{#_+v`SXif$?vviU(AEvV0}N+>bkt&i8^t%M9-}&J?)>y`5nhQ45NP~~Zd4%lb3=i5wPG4V zsda4TUMW9T$G7fO9V9x!Wi7FxWRzp@TGZ{a{PRb@KkmoPZ4M^+wT|;%uO{YAt9&^m z>_U^~w|p1B=EsZUeAoO&QbcC1RK0LC(+OnfwT_M8lbP0owhz5GqlBc?sjj(d12vGy zKkCojg=_P26oXT6=8;4ZeTamr$BMi|y~r0Yp2Et5q5zn%uz+1bVS8q427P!~r?(no zgyoZi%!U~yB~CxnQF|-@+tGCfDuPYKT9UxkL%3fmJnG(WiQ)>sqj%1-6J@MOxWIEC=F;d98x}HIa10-F%_k*#`UVAR=iN92JxU2z_C$2)LBX;;8Cf4Hk~e&T#Mr|Do#mw2e~w?^RcRY~sbg9?MK1CQENzsD5_jFP*+Kwe&8W%C60!BpKk` z5+7;4_k>13@Bpa0nW%s}!lBB_qPIER3d=2Zy|Srqb6H5ax=Qn~sWqPwq>=ieO_`CD z@ue?A2Oj8#b-~L1T~OZ99lZ_$vC%^q=Oxq>4-6I40<kM~N>*B(_f8)5TCi>E!bMnZ1 z{ad7&3JZw$Gnhz_0+2+3H^7D3T#w{`Iv9Ju-{O@x1b;W2$kg?lU(0G%ZLHTBRq{)< zL!%p2Y0f_hqRVRYKIJN4)Ts`>?nT+|Q*aFsn3VR*?SfJkxAof=lUi9RkK!c`L)v8V z^s^CmES(hfrAzEU8q zpySi`()buB6vvGFmJT5pSLhx1g&`kNP0VX_CLBRYq2fXYS`_Sob{Hbb6oXA4&9sHQ z)hAbkQT_tcS`CY>Xb(%;JpydncXZ;1_8G7nPNYB`fcQc61y2O-HHI;Mtr4jp?My@I zK{&Q{cm^Bg-DZtN4M*gDvq-+wz~hr%G=jJwLXF*SfsAE7N7jRX46od5_vP0240AbV zDpn*oS7aKV3HN{@9!22WM5BqJ#rGzHPrdN&sLIa13NxNy(SVT^Q0=^n!d^im1#k5i z)9g%TLUT_50(cXELa6-)*rU%QR~4-;fUAGSY(#FG_N#35GrF6!r0)F+21ndh(|P{|DyHScHeXzDT0lC%;p z1U`Sx`5K1YBA?JBhiynfBE${_1)|AMx$j#;D8m13Y7@*XdBSGqMhUF-?3b@0If*)s zloS9ZO{`1fr<2isV*Td^VerrG7hD>d{9~+l@0+%m+UKoPO@j)ZVf5hWZ0Rq)%4hMN z*6p&_N}?p;aX6K-*2gRfuT!^^^DYV}=f_-6bl`rUJtk@t4}D*lWA$o%wu%@Y?h8%0 zQD~mM1EugJw>dCX4@=z%f$R8lpdB&0{vRYUiaMC8;4(7_$>QA6MHh%5Iwx3>?BsSL4xLJNBfrKf8i~a$pUIFbFzY0Bgc+?Po?2 zaDz60p_RJsK^t-NHip0+ymZi$Txk&$IGqI}9fuJ5(> zN4c8tXgHQ2>lU)^fE|jm*B)9Y*^n`ZU3(8j=IGaJ{pw(Np`=hgpC5oGY25&$+K#gl z;%kE5X0alsR<%Ig%~>@JSUeDaopw28{Fy1JhibR8o)1;Edr)I_P1jq)iJi=Q0tXK0QUgpY z;lsXSo%$|v`|ySqWPN~J*6V2R4k27L7!Z;7kiQi~PMxI<m&zHSspuh(TY%8 z+bP@bZ;%{Jh9OE`)Y#!C>@_=m*-vKsu^3*mb(PId^C=0HSs(q=mv=uk5)b)@B@tgj zMWBt1|1dMmN_?Y$-;$eaX~-3_Xl8NV^VZ4~tQ`oP4{EqSa1Pf^Cjr1!2g}bV==Ynh z&zA~r|2OZfEPG}aNR%L>zlF|Ncw%BGjEhj}y?Zd;?>z&c_f^|YdVz<@bZHt(K|fFA?+b(k!ryT6vGxYc+~`SzxLTps{V*nC(mlCW z62L$b>S|Pp9@%T>7bbo>3~P^tfo@B@#B~v9)X0SaT~1)V!7w5;fDZiQVt2nQ!4Hl) zaHqdm8CkHwAR#z30o_S4aKLcNc(CB{_`ie0Tj{^p16vhZUQzgjauTLR)|`BG*3*wOxc-fwlmufab@v_M~dO4b7^(pUWt z1?sq9DCQB7ME8SiLch%~CzliCh;r~k!g6KV9EAmHQ4`Qt1L5%pX?p|}i^#nJSBn$w zeFJQ$cVW$)8n}v_+5jj3AUqpjQ1bq~%BWt0eiiHOIY2ESEIC3^1AO>9{O3I`UP?Bp zQVpp}mjf3m$Dg^-f#WwIge7@8-$hvN@uzQgXRhz4u~$S`K#8|m>FD&W58+T5#uZe$ zkZ02j1Sv}t0nl0WD8c<;*~>Zp`Aa_@y+*0#7$KtvIr)`zuyH*YoY|RMj6nVf_zPfE z8<+#{DF?fLv{4>BC$F3|SSVVbNil*$A4cFbLPYXf#l};qA$dshiUB>t!zKmlKx2|4yFDFLU@_ zrOt*oKX-1vof*VT>nhM4q2+T94u=)v#>G9xhfkdX{o?4*RhhOEYHHo>k(uP3i=UwB z_5~(Zy&4Ubc7&lgh{Or}D2P-j0mkO>tS$5v456v{U-PfPxbP0{RuOE{Xpkgu2C`pn zLHnf$OuUEpiP^Nq`9aJQHG9DDrI4L8c&k6v<}@E2HEeg_b=;`Wtcs~^*U;;thluO3LE!y*)F=-sNZcjvxJN2p^|LBf5TFK?Kiia889qbLct>j$=O9F z*vRj3qe<`@dMZy|7AZ1>JiYD@lde>zS~+g7x3NN;py#c;Q`1f zbXVShmk`Zi1`j{xF2{*=BP)N6p^{J)y!!T5I zFyE*NJ!Tc)W7>DbVB1WIdiO~y_B^-H{$uj`YxfoIRO^(XHwFS;;DV`zS#)UNG>o1( z1!wEGO-)FMFoe;;&1FMpcrYmnpWd}U8x$r4-ttL|&mz1rsfIB&>!8l_D`ZZn(=JMM zcYW@oV;fTGVh)(<_h&*PFr2|MUr01R`|PWFd)*u3162m9EKsNrJTH@60EZFY}NyYD^vQNg1n;GUe6o9JFL&Q_Rr* zHT>itYI6MG;Rk(I0@ny76gi_`=~nI<9lh|(dfPmEHU*H12jD`gdrkj*k1ktU^tJ$kG&wRc*oPUOQe6UR0{&I?(3OL{NHQS(N z767wzzxW&PJR9-XWGHI}^YY&)*rUtIu#ZGx0Vo9E9D;vZ2H{I7aKD@|;{N=J6n3-; zdoRvDoDK8YwYE}FVFEMU5{s2iMlA>OuytpDiyw3QpEJYlwX8nCH$AfF!txH;Z(V>l zp*1hjhWXBY{m1YA{@H5TfcK>7YHr7ndxUD}F+V+^wwrm*NTOM}Fx{>ZW@#0|I7~DI z6&4*jeDFOCozSt1f-VQp56CI-ovX>Icui9Bgln~s{0Yh)+(3q;{iM@nHqL)TEjaa$ zoKfBWxYJ5c$&P=_L?)y(N5s7VD;nm{Bz{*FXn`_UWfqQe$udA#q-S*Bks$oeUP|i@ zTW2sBANHap1B7Il`h*${kktB?=s8;tBU~H-ARaVul!-QqNIBg{nR|_`l5l6>xLii` zia)uQ{;u|9Jq>;LTrc^SscftJ0;7s(kLL*-B_tU3MKt3nKRbITLcp=82miznv> zHwX?i9ul~r@1x|}>)c*E1fMp^=Wekf@U9{oH0)r;+8yMV_4be{8{qj~8=t?Sd;SXv}tGe(1E>VE}Z^gW2L(uNTxsNT>Cp5)v zLRhG=fku_f6<>WDn7nHJ`p$*ZO-_rr3dFMzL0aFGGSlln4_md`I^u2u7~TRJEXX#T zNLV)7t*dnCJ6`tgV&*+IQ5KldS~2aeA!R$ z%{0A6XBNfza3I)Rc;{++u6#E62!JYhIIbF`3pf0H$^mwcWAdzEY5*1IxDf92vs$gjjel!>%uK}WOu-14)64KT*{vizoXm@eg0Ta2 zwpMx$#GIG*!|#bW$5GK!3+X3#$Bibg*|Fc0w!3*dmJ1kW&~c8lhW8u#1A9Z1O`rUw zCn?-za)84QP~n>4OJO^E0=a$AA#w=XO3Nu3ZLfO%zFcxWpA)m5zehFi&G^`an)w!$ zgo7Q`?lkJGF)M7cUXGE(cI2XXcqczge1)pW4D+8#ifunVfjBXFeRZpKXOtc_PS7s8 zm9(r?1C_hX&D#=p^b=nWf#^Kk;xYr%9zH};J2aVFOlYd(lXU%}Vx}!M7&=}G7v8?M zG%hs5%xhvv^5S4pbzeUEalHTzLJEEySqac_NY$acNF&N*6rb@&DU9ozY(&S0=IrL; z_bxN)>eMycX8kWO_{DR=s4PCdEpGakLI<>$b)ObllC>UeEw_b4$zleZ)~|8pi{a$| z`lP3d0m?k0r z_Rn(DO926AGLm8yG5T*x5UI%AjvAOeth;eru~^ef>Ub6l6CT#tBy5vvJTGGgt@P!LJKR&ixWM4}WlWF6hd-f5dt&+dE<4{p zDk~&2i--K=cNP0XZ$kQm9Sg7UST~OJN%ej52o>WchyAc&1{o&m|J7(ml!w`sPJA8J zp0C2*x+S`fq>2cRPvCJ^2H3LYn@1zmvwh@l>^ep8Xp5PJJyi>I0fkRnUxtfyioq+o z-;xA_F#)BNLi+#Vv=dl-t_8+pNAAaea5$0=0j`K?jhzP;S(DNWKpfwcaq2~M};H^T?BIHd6*M7Ebxe|+w zQ$MS8U?6e8k6MyC_SM;}Z;y-<>sp^BF3Y(B;4m%L^KQNckd8S{Kc|KPI`XFCVV*~~1AOX1tzKpaI7w~>;toWp>xa%!_ z+Gn8RLYwA!&&Qqn|G`u~Du(J;Z?DOY?M$~sk53Oy@xAtM*|QwY@A)gj74%YW22@8u zq#r!s14(R$sOZ_$x-@SMnJm4k4eSCRoPkUwczKQ=KOO+ygLp$H@$g9I*|bwnGV;p( z9VouJsxJr&8^V0WA-{O3ir~DjResKs8xAciH`<{L%73H-vUmuu2UixrZBrD<$wSVv z;=KCG_P;ID!Cf+!b;zSwdwd+n_6geO&t%$V_G~OaTa^0R#pADf9C9=OY5Me`eBx2S zEv#gZHy?A&?P?h>x##NYWXAEF0)v;P!*DgfC~GJ4sC|4FoWjA&Cy4qhPR7Hv^lW3X z4t+er3H;x*v)9;8WaK@U*rEM zY^)~@{+imt5Z#-=cPj4rXmeR9JtCaP+8VUag{k3TXU5-uN9(}XtSLoFy+>`7NJl?T zjm=;NvwPk8Z?-sh=DRC@-#qRB;{ffBohF9f8Whd-*}7ja2Ex=tuwn$j0~`YNi%cyz)h@bQcbfpSPSI8ylxwnxZim#i7l~+d(Ne4$^eZE#%dq z+{LOCeqOSQ!6ASUyASUvJ^_?^g!l)Sk+NRYwx-IZOQRq=HiG-;IP_3iPM~SD6;Upq z1`b{@0d0J%x|aT3Ck{_#JZ$azKWh8(aID*?+aH=EJ(^HbkI0aaP?QFeDKbl@GE`)U zWF8t`LmA5uC1su|Gl?cdB_at4nLzs3)>-*yzSAX>O*7N*^``-83 zd#}CL0_*tF&7pC2O2N_Mnr^7xyQuE2! zfHw%w%)9Pz0awA-&lSJ=vnI>7md=$NNJ=_rnf%0N^&gBX{qJl-|7SIWi~8!9PK+=a z6s?+U;7_@<>1L5BHp7PjA|N-?_~!Vh?Ylw+g_zJO*thvvnfaSlJzJZMRl)ln%1#Am zbY|8fv1ymqmfnzPZ>hr(VT?ZQhI4IO#=y?8`jjtl3Fhb*%OSCs0G}X24B&g0%#v%i zRMhtF_#-W=l8(zFH)mOXNAYx@t{ai;`hgjaETJs@YtKcCz6SXT+5xw=;s2% zBX()Jd8xntT}Dd}gb_hgc__ln<+W5|Qqn2R`jc`K5S@MZi{*FsTwnxy5lZo*ME4d9 z%^U5!v=j0k`+gQxC?$F84*%}YO06kweDYC$yqagjSAWnblJeERLZn^a6Zd;VDS@xH z(E40lDkLP0@7(LWAU7rPJGI0d)83#iN@G|LxT&l z9llKFV!9*0`)!)|7i_MLM@|?yEPq#+wa{PlMs%z5jt8}huf*ieahuMKuD0qtAiTyx zCiZE|Lu;J4f!d(!ur^g*CK7bpmrf@2&xybP`>K`g_Q71*k((`mZyyrR;9w%R4Ml`s zK8`9h4fC<@zt0pLply_-7G_gs%^W}q+HkZwxY@8}WJ#&htP(XzdXBEZ^x{zy zCvc;Y2ce!c(5%uraqE_x)Ycr0H%z}p--F%em^kRVfJglxB|k@lXVCLkR6v%FikrvF z6Qepd%Bbv$Ec#llCav1qq zL=rWPH(~2jJ>dmG=)#hlJH| zKWKOjL2rAshPq+m^6%I%zp!u?b0XnLLLGVyx5rNgh2TvB4lVNLr|u=MMbCWAcIC@Q zi|f3uj5=Q+E`=p~ZnpVWEWgB%wkEz^pV!;M*S2Wl;aN*-@9apfD!H?s3sxWA^WZ@%uiO>&&=`>Jwa&jK0V6q zNg}#A&pqbmFrLc%bB$b8)8kpqx1Zg@jPQl8!pFDhXeY{sHr7gorl*Eh)M#&1oEx#5 zul88cAV&8B6UWexh+ zic-N%KVLH?^%{!y=x+t?`eD(~Ai;fRbPWfb5+u+9B`!A*dm#?7M9{QFe>>d8h{7ql zQACN+TyAu<@g+*fn(O;!UC*5lZC{$yx@j-nV$u2??{M}?dX56ph?e(mS?Ik4&ep$T@@2jgnx6;59n*^q8*XDS1&=!@b?^(9s0 zS}iQoy({+pI+#|{wR(-&=ZA;MLAEk6aNxAkS6pfVu#=&4hZB@}O)JNV?lOiZG5U$%@M+-Vrg9%p(OFbY6nTXB{(fh+D(Ma_A>;uTOa3CG-oY_qsitEe z1(VcXA4u*{o+I_;QLiL~ks2$kiTu6Kb9(p9wT7*vxRpe=)1zs;@DGVnzLl&VrF`0; zfX#ifjag98C(c`U@@~=Ru?pd=uUGg=z9@h1wrrsH{yNu-InD0)gx)(2XHO;Xb@;uy zV^D49%yxQcqvpM21=xR9A5d;p4eLphFA#3Y=s}DG@LvJ><7$f1=LkJUE@^7NTdK&_n=2E)m!za8ev3ZibI0z3v2O3N-yVl; zi;Bl`?Af>!IU>S#r6;Nj7xbi&KHT)A5HIiSFZ%#`dh4}z*V=>E0|5ry#$IhFV-_H$ z^l&dsErr{OAh(Rux3z%l*P5CZIzN|JA34!C$F#s)-NheppMUxF__E|ozwywmmoy(T zs}Cfca1m^4+)!?)2Y#eF_B5hX9Z8VDr?J<0U3)Mrm; zC->xMrsvGhUyF*0|8%V|{w0__bCJcQaz>`b$vfxVvSrI4x$L;f=>*-XYIZhULT86? z&BwbIXPC~s<*(OGTj{PKPkGJ=#{E3$_W4Eo?kB&0rwg9XsaQ4K*_morZ6$L_zvzBi zMxHZQ_NU!V{^3H$lCnag%|wOKH|gWYc*D}`*M9gm6Fqb1WtwNxyG@ab zPVmoy-0o%Loa)!n;tfcS&+g_V)1ai!|5v3NtbK5rkAQ{u_u~3+aek@waeB7jH&EsTawGQ(r-u5&)RTbNK%C$5<-S$?Ty z=g@@XKQw{LLV?=mmdg%N^0kfAr!nC3*y>R~hX9}ESLRj65~(f7)CfrlJry`cFvhC+ zK`^Grd%oX$^_n$319foX*4Qxq=Is(XPi)6Vha-{6-g`@5T=FbdX_j?QPLbGVox)lA z%zv$E$65==p@SuI50_hi*dRVxPQJu3U~S5ThMc1d{fPY674Zp|wNk2y-Zat%sV##Ry!m%XNpg!m76U&IR#`RpA9n1>$RVy0>h|J0oA) zF0MJ-rp^)+u$Crq;@g0>m+a3*mD*CRKIN~PzqCB3qa@;D+GYZEJQa%DldQN+O%}hQ z@$3kx{5@#a_DB2b(vwATLOW_sY7Kor1nI~;q3nL_1D|G}f)%Hn=Z6h>5@DsDZSz0& zYIuI!KhXNn>?oE4@q6NuzIYIuKTB3Op`j9sSxijq_U?0RRl!`=c2fTS-yU~zukD~15|QqRh$NII{YfM4BB-i>GM7}SAq9( z?P=#Fn~%lLThyoYad1?bw5SHkhtqbdyo#2777?AcZA+i+#g23GD^g?bNqWn!-gwga zDOeM7CbF!o> zGgI5x!lIVt<;xqDD@CZwm*0LD*n35KE<-jhMlXd=q2dqAyR=(2Jcb3H!2>&o6r1se zoazPAe&iH?EH0mJnIMlbBUrIHP|GGDT$o35;`f6m?~R7?p0FQHtTEa%a*iQO_r}ze z3(=N>P5K30yynctQi)ubhYpVRqw!!jr>Xs}V}Cf? zY+-8F_4_3ot93F0;~wssWd6`OZ#gf`vY)PFWFxiEoF-K#VON~tZB!l~o09V9*X@k6 zXIS(+6jq4NecsCx_Qrgio6*fD!L8;!>;_j+{UY1gys|^`<`Pa; zUof`v4r1J9y?A9ai zPMY33Aa7N>wrxf1NAZs4_J3bpWP^U}DwokCzuNBVT(}j(>bG4J-DZ6hC*UVdJRdPn zg^~8tUC;h0HtjPjMU#;(An>Z8V+-BtVnajiFYyf`f;x-|2@EDCy?ceYxwq`mcl|TP zAD8X!CfH_E&X73$s!q!`x71nB_L<-drD zYd`5I?$sA)qqDTGHdAGr)tyggM#6I+$f13fpRy~yEJX3dOkmSw=Sh=VlN7CVflt$p z7Pd;4r!z$?NBqN$b5su*mVI#O98N1%GH3DQ)8zJ^6+3Na78Vn89gL42Fhz)VaiLvj za8r{u7U=2T+6WSg!|KxhJZ{c9S<5mUw6QkharGJ6UW4?vMtON#5ot~`X5Tmr!6LmJL8)jdJ3*-f^x7aM zA?>j8XV1bH+}vC29yZ44EVcWbDHvvS+_Yn_*Q|zXvv!-m_L~X2Ct}B*?HGS(X(6w- zDQuV2>Fxn}G=u8Cs z<3D$!KmGN(s9Z}=F;>?1FVd#nwT{+q(qLDJy>fQ&hftU>Fu)wfZTv$*q?F>*$$Y^5 zLs#t~MtjsK(m%B|t)$Z4srgpsjSZJ?vQ@X+(oJT}p z7nj>Pr!LG)*pQAkROB6+ECT#fS4Ar1?nvAFPwr#Gl5=Y>v>)4~VWt%qJ2o!SacLq` zGxhMX!q1+1Y3V20_#4p=bSoWn^_tV!t8SI9Y1{c;Yp-7t>vr1?O|KR!L178+xsUqp z6--rL^Q{j5C|avVpEl}t?eQIK5jME}J!RhWLerJj=H@e=Lh&(pNx}yC%b+t%R`VzX zI_@6{>I{VVXE%f=k770*xbCPQ(5RAN&AG_Ca3C2Sejvrr5OjA*9qLiDTz;t8!{-~y=Y zy+M1jleOJb>Sxu)s{R!#82jEXmYrdq>RMVoF*@t2JCYzcUVflRCT#5IPalPZ%lrMT zcXPJe`YXNL83;%e1|=hg<;xG+X6LydmJhz)P~5k4o4V{dgYvMLqUq0ZZTkyCRt~Yz z!g%D5GHq8EIXiB?$vPdxEg;j>W zg1mW9jMl1v^o$>KC4a`;^fs^OwOs7nlp8VHfx5*`Hak|OB!~)`d zzvQNSHbasLBV5CWU@}XQK~LfB*33<62+erFp_M^_f}7e&4`AW=eEz{JXQeDIZi9i5~etdr4lx z&OymN1tI>ar*zZ{-`-`&Hp&p>7#Tb<9+0n=vd=GReyD$Nxr?hnPFqpL&E{_gCnQ>4 zr$4c?NOJIUDpN?vzwvXg2wm?PeU0|U6rGU_0ho`#wDeh$N)+*QhwU4o7;y$I0eR{< zYA2ylQGWjZ%RsE&LZ?5YMLBI$O~i$>I^N(I8uuwRF8A}h8Q!eg?vuW#{<)lM$CIqb z{xz~Y+|>#$M9U*}yZ3agw{8?=H8Xfu{?ypO@+Sm~r7J1Q_^^Qi=RMaxj>qr>3@*-W zGX->(pU_;BCt>X~JDX0EkZ4Vpy^=hi@x6!XnxD|hdwqS38+I03N=U?4!5X;sSCo8n zi7K6_y`L>GAWEzS-+Aa$komp=sZ4V{ldvp~zn}S5*D*0O{;<-ED_0|4WF#h9NhcN+ zHE!O--2QmEVMX@&99dz_q~Ls=xFt$ol{b5=p86(qX7Y+*(EATz>E!W%!St{=L?Pi2 zM0tr6E{T}HNKL><0K!(wB;vG$c4Wpx4h)`%$X&NiKq*?fph0JYeNu8lYEA3@`^hz@ z0GuNb@~FLiZo*C#EUle~g-z`0*QS3MH zAEhOIXH}v-pBs^d-35AVUCnuho{L zyR&Q_9^Q=glzS!-ZWtklt}Z#0&|o?{HA);#y62LZuA+7X6+c;b#hdyYVj1nBURjt$RxB52xtPAQRnWRjIXUF}C`1 zB_ajIehOL=!eNHo850^dhRGinQN&DC-14=LT8elkR}vd->d&99tE{r{wZ65kf%i9W87Q5-3C>x%3x}Tq)-dFYR$(%;^W zO4)Y%F59`lAw_(LAWHs30E}3|5=tVpQYq?Fp$$Q@Fh^&B_;?DBNWbK5MH=qKEY{50p)l7p7*S*^AmViLjfRZ%QOc<_-O#ZLR%fZADL7zcnB@+f7m}fx*KwqAbN&7K>I1jsHJ*3-Yx9s8 zL_Tup%fG*&Y4Dhly?`Hc9zM;#zmb6w|#WSr=;OAia`c|1_)CeC@f z*@gi?v)!QZ>BbG!MhFeG6^VcVzu(2x^%Tc=r6(S?!(J1p&XiHkpkZ6aFg%!H{2 zcCRRex|Vq0Ou^4r+ud~f+wa%11O)|GZ{8fdQOfoUin;@>c_|GOz~3O(FM=J_Ku1~8 zOGkKN^X%HiW^8O+19NS_LzcGMy1EPSaqY%cV(xm)cEM+r#cPs{$#LX zQc4Qw>Kj1<6H|(($V@fm1FMx5*K9meY!n_@+0Xm|jFgFqNg%rzW075F6}BbUd)L38 z;^1x@tvH8hNBO{4Bf2BIkbAE~qDK9{Z}ZL7s5}`{B3VTpG&fId9kFs(Q&UU0w=$KJ zo+%(Cv=Z62ZtT^+576)qE(XHsOw{b$+#6fgWy>gP?Yeam-%9@e?^IX&I+}o2dPNYr zFpj`7LR5Yl3as@W!*fZYA5Wq3+VVBWH8d{6+=w$GBEr{3D5%F9}0vvH^&wJy^pHP&@x$_Q@iN;N&q= z6UVCm!=pFqzb}&P^z(I7g&CR#%=49E;c`UXX^E)euT$`!s7E+7Ht(t-GxjsZm zUA-D_826;IXvvazSYS`#Uk|1hHSUOrjO>QvSTz(V-X*DQz`4I@(IVnQ2jS79Sc6&B zyL_{GgoRniR{_BQbFBQ&m`5ztf}w;kbRqD;5Lgs~2mlWn&b~|2+J0kZS8(>JpI@H( zdNaK#N2+2uv8SqjoX}2**ENPgzV!F|p)?b(mt#EjV`1JdZ^rKPV-5_?EL*jTlx>!< zZVn_y(d%5W z@nWBA|NNt*s~eeD_VN5SUf$)@ttj5SGxh7K?*9JmN=iz*E)EzL3yr zhUS&Xy?giK8_sTnvos``LrrHu7v+1a0Ra<9F9-RV?xaCn5Sk@l4< zR~GqP9QmZP)2P(kVUyW_!C^VMBN@%g_(?4;46ZD9%Bx^7$UFmKXg!47?V#$@sGE21 z?rtz zIzC=-ThSBdP>ct0bG;Z?@SVW=3J3`axpwWE;;B;)8pQAdBffkwW!M7K714Z?$1WPs zci%>tW32>xS-*Lfu9NZg)%Lh>cpI=6V7%)P4E_WtbGW!Gw6V*z4qJ z_6&0eiUfgFXq@+a>pKLI?8ZjT0I;Vz=O>CBFnV+&U~SKU!TDo}><3zY`5l-&MAaY& zo&V%LG2F`62GyZOK2V2wpXv#|4C6uc@$r2K1dDvyomz}0E_R+GHvl7mte4*Uef4o7 z)K?5{Shoj<`Rl7CDyyilwAIHQuzNHIa3L-ezXxt+3|n9}7w}39cOBnsg~b~)Cx35P zPgC>s?FphpO*_Thq0y3UwAhCv1N3L?rKLoX6)X5FKIGQ$@UX!`x!ES85Mf+;zZ<@T zm!Dsek&!VmKffv63^p7hlsRxPUmJ+Xi+#}1;V3vTKh?u{kYJ*`eqe!wWAF(xeHg$u z+#lz?g!=uhxo-GU!5og7pby(0saaa`0cFr|Ce+j@-Wn-*`Bw9_r-z3*~9oqf|HU}qptwc{*6%9FR#P* zb}&T@mda#c639lP)$iZ!$1f;&7?+MT(hvL)Hh6qJMK>o1SzR|K6%}T{ZRl9t1|S!6 z_XpAa#BvP1b?Yj2I_Ia3F4@Qc?KR2s?_y@2YnAWczCER3TK+?t&?N>2hGol_9|C>^ z3xuMi>^{GM+Ru*7)wiVr!QI_JiJt!`iulTC%52nu!A&tRR)}$UcG>r57}yC$;z+7< z2vxXEy`+{QF*tHyFMb&*>dbcZu4-@+*3YG|J*tUY2O7ylox$$$sBeR8VBFANXjM^L z_U+q5q-}8^ka~zIC}3pVvjJfnA6=DO!TDU~dodHP)Uy8E&duNLx$ET9muuCD&CJXI zjLeH>c)Qd%HLa7W-0js|XD8klbOvZp|KaJykIT!0Y;j#Jg`P8)NGnXg!fQWaIUsV8 zt1fq+lpKD}UYblsD$y2uh8v`DavJo{2PO=0fSV%w=j$3EsRyXuM@L5!+m^20-hXfm zHvjBeTRBw{54#qM4CP-2bUfAi$fDTe&n`@0`H|sO>DX0>u2WDor#^0wvkrFrhkaKV zo&M-OxGiD;A^yvVD=J{^8Rvk^e6#9R{>xUZTscbY2r&=@U{iU=?#bYAcG%*Qk`kBR z2)$4Yr{dqrl*yQ*(B5y>n5YC#4W8NA+0|%(LO81n2j^0X_@TTTy!duxTeGrJMcSiB zY&bfr$y&+HB~8pzqunpb6cswPM5lH8WPX=enAI~zCME{{l>sqY=$ui&{8st0VNTz! zbD44;7-v_h7V8VXg+c)!+k@QP)nxS{UkEA`_x-+g+qOl3OCO<->o)m42sLHmKSY@g zTqn6d;N}-Q@0mNz)uO@Q&1yooLdK01nF$f5q)cZGHO7DZz<{!9A{FD{TW{km8caX3R?@zm&^ zs&+B78hy9Q`ECKWA}(YmP)NMx$u2jEGcO2TK{@$c*I$-Y-~%Btv_pVcla~5lSkU4< z*W%4^T=vWHHq1ya^SN+Q%IaYh&KxQ*PDr!j%>4ZPGH6)0Zsy`*p~zeINoQZbem&>S zxR}>3pL2aTi$<*bwmad!0A#YmK$%$S;pqtzP#-|0|BM%Q9i{(3B;!y z-P92@J&Ru}5%HR8-LdQtKKa^mjLMeWw~`mww(Uje+BuBH@y*16e4v+YcnI=#SFT=V z8Trqxv=KJOM4>V>bH{Tg@8&Fcxl^L2U-&D0=V*ReU(ZT%M#>b!w0v#WH#+24_nYUJ zmqL!}J^~(ml&E}ztc0@m9Z-cMDJ78_#ynw=;N#{O?4{gJoXV=I%v9C8bpem&lU@nI zdB=xMrr_9|_T38?xnbx@{0)548$Tc%oa=nDAIHcRx^Kmu<}{mTmDrQl{q~Dt<8l+q z7CBaYJDpPO-;U`t>677mhAoIuMR_!)d?RtKJo0Vp5MN$(MM}6l%C1Ir0yQ(A`~KTY&;^-nnD_5l84!m6c=HMT4`q z?cZ+%0MCyXq%Z=MunTljhAkoc#{3&3fjd1A;~5W@I{&cM_cxaRTFvbp4(z#t`cttm zb3kqeoBZYb_gYvu7EmDYoq$fD(%G}A$j4tn_#`MBBQ*aNH|*RQ`9E-j#q)9{A<;0a z?u*i~5KUL76y?EL-6-|;r<1<^ZG^JDWjEeHrQ>8Gjtk!?g#;R(Vst82PyF2o^t}ZWONT7K8)i(T0DjJ`P}>b zi-VdBTPSnDOu&xQ6FSF_n_dJ2l}2qrfJ%fr1p&CxdoIK?bL^5wTC~Uq!2U$prL0#3 zt7iy>v7Opv^v|^WN3?f1WIc*i@9xo9vT75*L6$D1SY+Gr6)kAKYB8_u?Yz84D8xp8 za3&4Emroi$_j{qfZ}i%$c}(3h9(?@x@isUk;UZqt*Q--C?mx=UOmJd8+}D#({BSek zvu`%bT*@36pZ4{-vmSwO2|)=G5;~_(pTNS6TTZ{mCJXn-|`S8&A@>bqG#6#E2DY^VNO_YDbeB;>azx9Sz z|G$+m6dr&@|NaT>|NS48Fb64Ig_-pk=Y*%K_x5q1FpZ&Lhf8`WAKoKh8>Z4$V7&n; zC59}AhqIdm{#LK6TG4rpSNPI9yb2ea1{?7Wz*{n98(A!o65f_^-U+n#V>o*?O=Ca0 zRCIb2sSccResBnt8dB&c|DL||OOq^}?!X}t7Zw8%3bLT6N^D15lbK674pN2cdkC7) ze2_;J%Qp}vX)Gp^*%491OVq{(uMkr=baH4M9Lq&SM0OaJt_7fu3n}XK+K6>R6qh_a zJlu;9yg1~fh-_kf zJbj0LZsoTh5;R(?A_^9Ui>QF>*LPX9l{ltQq2b|c^QzlX8^`N?fq)6(uuc954j+eV zE@wqk)BA=`JX*ir{Tr9!-w&$3bqDci@1^0}N;4<{kll_=FQ3!0(dNeW>uf3u`N@fi z%cxd-_Jd>Y?Kc? z*YL&785>YC)f+0ouXcEk%to`-FUo{S}G4H>e!!kJCXqm?R2T}>d zV37T-otlP5n2u-uS0pgh@u9;ntlW)_@4YHSYL!>LXz^l(<7|iMbSrjJq^ijp9CxE2 zOlU@1z54i&SD$jmojZ+7Df$)EScs{d%eSpjH#=u%LVM((aDO14$)?H zof9Vlz}RThK9vIq@bl+SSWK zsI_Oa>sK08iIJKRGWLouL0ry$X?+gFL?EDLEG$H1rvZ9OIPYm>5*O}LEUc`oQ0HdE zd80cS=kL$Cd5r*`mMh9Rl}MQh5S;xLxA5ZnIwAY1pQoNrpx8z@EiSNWp>5g}2vTwn z@}Q$?YO7Go%C%}1B)lg{BS++wB;UpmnGb}AmXNA56YD-7G+~hxMepw;g;t`~j3-8_ zxM))Dh qJl{2*|5jJ$zt{Wu|NFNR7FZwoGS0XUyEanzQ97a~pMBW$%6|YRSQxbc literal 0 HcmV?d00001 diff --git a/doc/docs/images/mode_converter_refl_tran_spectra.png b/doc/docs/images/mode_converter_refl_tran_spectra.png new file mode 100644 index 0000000000000000000000000000000000000000..b380d529ee67ea3727acd17e23f93cc248bc9002 GIT binary patch literal 53927 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 design_region_size.x / 2 - filter_radius) & ( + np.abs(Y_g) <= w / 2 +) +Si_mask = left_wg_mask | right_wg_mask + +border_mask = ( + (X_g <= -design_region_size.x / 2 + filter_radius) + | (X_g >= design_region_size.x / 2 - filter_radius) + | (Y_g <= -design_region_size.y / 2 + filter_radius) + | (Y_g >= design_region_size.y / 2 - filter_radius) +) +SiO2_mask = border_mask.copy() +SiO2_mask[Si_mask] = False + +refl_pt = mp.Vector3(-0.5 * sx + dpml + 0.5 * l) +tran_pt = mp.Vector3(0.5 * sx - dpml - 0.5 * l) + +stop_cond = mp.stop_when_fields_decayed(50, mp.Ez, refl_pt, 1e-8) + + +def mapping(x, eta, beta): + """A differentiable mapping function which applies, in order, + the following sequence of transformations to the design weights: + (1) a bit mask for the boundary pixels, (2) convolution with a + conic filter, and (3) projection via a hyperbolic tangent. + + Args: + x: design weights as a 1d array of size Nx*Ny. + eta: erosion/dilation parameter for the projection. + beta: bias parameter for the projection. + """ + x = npa.where( + Si_mask.flatten(), + 1, + npa.where( + SiO2_mask.flatten(), + 0, + x, + ), + ) + + filtered_field = mpa.conic_filter( + x, + filter_radius, + design_region_size.x, + design_region_size.y, + design_region_resolution, + ) + + projected_field = mpa.tanh_projection( + filtered_field, + beta, + eta, + ) + + return projected_field.flatten() + + +def f(x, grad): + """Objective function for the epigraph formulation. + + Args: + x: 1d array of size 1+Nx*Ny containing epigraph variable (first element) + and design weights (remaining Nx*Ny elements). + grad: the gradient as a 1d array of size 1+Nx*Ny modified in place. + """ + t = x[0] # epigraph variable + v = x[1:] # design weights + if grad.size > 0: + grad[0] = 1 + grad[1:] = 0 + return t + + +def c(result, x, gradient, eta, beta): + """Constraint function for the epigraph formulation. + + Args: + result: the result of the function evaluation modified in place. + x: 1d array of size 1+Nx*Ny containing epigraph variable (first + element) and design weights (remaining Nx*Ny elements). + gradient: the Jacobian matrix with dimensions (1+Nx*Ny, + 2*num. wavelengths) modified in place. + eta: erosion/dilation parameter for projection. + beta: bias parameter for projection. + """ + t = x[0] # epigraph variable + v = x[1:] # design weights + + f0, dJ_du = opt([mapping(v, eta, beta)]) + + f0_reflection = f0[0] + f0_transmission = f0[1] + f0_merged = np.concatenate((f0_reflection, f0_transmission)) + + dJ_du_reflection = dJ_du[0] + dJ_du_transmission = dJ_du[1] + nfrq = len(frqs) + my_grad = np.zeros((Nx * Ny, 2 * nfrq)) + my_grad[:, :nfrq] = dJ_du_reflection + my_grad[:, nfrq:] = dJ_du_transmission + + # backpropagate the gradients through mapping function + for k in range(2 * nfrq): + my_grad[:, k] = tensor_jacobian_product(mapping, 0)( + v, + eta, + beta, + my_grad[:, k], + ) + + if gradient.size > 0: + gradient[:, 0] = -1 # gradient w.r.t. epigraph variable ("t") + gradient[:, 1:] = my_grad.T # gradient w.r.t. each frequency objective + + result[:] = np.real(f0_merged) - t + + objfunc_history.append(np.real(f0_merged)) + epivar_history.append(t) + + print( + f"iteration:, {cur_iter[0]:3d}, eta: {eta}, beta: {beta:2d}, " + f"t: {t:.5f}, obj. func.: {f0_merged}" + ) + + cur_iter[0] = cur_iter[0] + 1 + + +def glc(result, x, gradient, beta): + """Constraint function for the minimum linewidth. + + Args: + result: the result of the function evaluation modified in place. + x: 1d array of size 1+Nx*Ny containing epigraph variable (first + element) and design weights (remaining elements). + gradient: the Jacobian matrix with dimensions (1+Nx*Ny, + num. wavelengths) modified in place. + beta: bias parameter for projection. + """ + t = x[0] # dummy parameter + v = x[1:] # design parameters + a1 = 1e-3 # hyper parameter (primary) + b1 = 0 # hyper parameter (secondary) + gradient[:, 0] = -a1 + + filter_f = lambda a: mpa.conic_filter( + a.reshape(Nx, Ny), + filter_radius, + design_region_size.x, + design_region_size.y, + design_region_resolution, + ) + threshold_f = lambda a: mpa.tanh_projection(a, beta, eta_i) + + # hyper parameter (constant factor and exponent) + c0 = 1e7 * (filter_radius * 1 / resolution) ** 4 + + M1 = lambda a: mpa.constraint_solid(a, c0, eta_e, filter_f, threshold_f, 1) + M2 = lambda a: mpa.constraint_void(a, c0, eta_d, filter_f, threshold_f, 1) + + g1 = grad(M1)(v) + g2 = grad(M2)(v) + + result[0] = M1(v) - a1 * t - b1 + result[1] = M2(v) - a1 * t - b1 + + gradient[0, 1:] = g1.flatten() + gradient[1, 1:] = g2.flatten() + + t1 = (M1(v) - b1) / a1 + t2 = (M2(v) - b1) / a1 + + print(f"glc:, {result[0]}, {result[1]}, {t1}, {t2}") + + return max(t1, t2) + + +def straight_waveguide(): + """Computes the DFT fields from the mode source in a straight waveguide + for use as normalization of the reflectance measurement during the + optimization. + + Returns: + 1d array of DFT fields and DFT fields object returned by + `meep.get_flux_data`. + """ + sources = [ + mp.EigenModeSource( + src=mp.GaussianSource(fcen, fwidth=df), + size=mp.Vector3(0, sy, 0), + center=src_pt, + eig_band=1, + eig_parity=eig_parity, + ) + ] + + geometry = [ + mp.Block( + size=mp.Vector3(mp.inf, w, mp.inf), + center=mp.Vector3(), + material=Si, + ) + ] + + sim = mp.Simulation( + resolution=resolution, + default_material=SiO2, + cell_size=cell_size, + sources=sources, + geometry=geometry, + boundary_layers=pml_layers, + k_point=mp.Vector3(), + ) + + refl_mon = sim.add_mode_monitor( + frqs, + mp.ModeRegion(center=refl_pt, size=mp.Vector3(0, sy, 0)), + yee_grid=True, + ) + + sim.run(until_after_sources=stop_cond) + + res = sim.get_eigenmode_coefficients( + refl_mon, + [1], + eig_parity=eig_parity, + ) + + coeffs = res.alpha + input_flux = np.abs(coeffs[0, :, 0]) ** 2 + input_flux_data = sim.get_flux_data(refl_mon) + + return input_flux, input_flux_data + + +def mode_converter_optimization(input_flux, input_flux_data, use_damping, use_epsavg): + """Sets up the adjoint optimization of the waveguide mode converter. + + Args: + input_flux: 1d array of DFT fields from normalization run. + input_flux_data: DFT fields object returned by `meep.get_flux_data`. + use_damping: whether to use the damping feature of `MaterialGrid`. + use_epsavg: whether to use subpixel smoothing in `MaterialGrid`. + + Returns: + A `meep.adjoint.OptimizationProblem` class object. + """ + matgrid = mp.MaterialGrid( + mp.Vector3(Nx, Ny, 0), + SiO2, + Si, + weights=np.ones((Nx, Ny)), + do_averaging=True if use_epsavg else False, + damping=0.02 * 2 * np.pi * fcen if use_damping else 0, + ) + + matgrid_region = mpa.DesignRegion( + matgrid, + volume=mp.Volume( + center=mp.Vector3(), + size=mp.Vector3(design_region_size.x, design_region_size.y, mp.inf), + ), + ) + + matgrid_geometry = [ + mp.Block( + center=matgrid_region.center, + size=matgrid_region.size, + material=matgrid, + ) + ] + + geometry = [ + mp.Block(size=mp.Vector3(mp.inf, w, mp.inf), center=mp.Vector3(), material=Si) + ] + + geometry += matgrid_geometry + + sources = [ + mp.EigenModeSource( + src=mp.GaussianSource(fcen, fwidth=df), + size=mp.Vector3(0, sy, 0), + center=src_pt, + eig_band=1, + eig_parity=eig_parity, + ), + ] + + sim = mp.Simulation( + resolution=resolution, + default_material=SiO2, + cell_size=cell_size, + sources=sources, + geometry=geometry, + boundary_layers=pml_layers, + k_point=mp.Vector3(), + ) + + obj_list = [ + mpa.EigenmodeCoefficient( + sim, + mp.Volume( + center=refl_pt, + size=mp.Vector3(0, sy, 0), + ), + 1, + forward=False, + eig_parity=eig_parity, + subtracted_dft_fields=input_flux_data, + ), + mpa.EigenmodeCoefficient( + sim, + mp.Volume( + center=tran_pt, + size=mp.Vector3(0, sy, 0), + ), + 2, + eig_parity=eig_parity, + ), + ] + + def J1(refl_mon, tran_mon): + return npa.power(npa.abs(refl_mon), 2) / input_flux + + def J2(refl_mon, tran_mon): + return 1 - npa.power(npa.abs(tran_mon), 2) / input_flux + + opt = mpa.OptimizationProblem( + simulation=sim, + objective_functions=[J1, J2], + objective_arguments=obj_list, + design_regions=[matgrid_region], + frequencies=frqs, + ) + + return opt + + +if __name__ == "__main__": + input_flux, input_flux_data = straight_waveguide() + + algorithm = nlopt.LD_MMA + + # number of design parameters + n = Nx * Ny + + # initial design parameters + x = np.ones((n,)) * 0.5 + x[Si_mask.flatten()] = 1.0 # set the edges of waveguides to silicon + x[SiO2_mask.flatten()] = 0.0 # set the other edges to SiO2 + + # lower and upper bounds for design weights + lb = np.zeros((n,)) + lb[Si_mask.flatten()] = 1.0 + ub = np.ones((n,)) + ub[SiO2_mask.flatten()] = 0.0 + + # insert epigraph variable initial value and bounds in the design array + x = np.insert(x, 0, 1.2) # ignored + lb = np.insert(lb, 0, -np.inf) + ub = np.insert(ub, 0, +np.inf) + + objfunc_history = [] + epivar_history = [] + cur_iter = [0] + + beta_thresh = 64 + betas = [8, 16, 32, 64, 128, 256] + max_evals = [80, 80, 100, 120, 120, 100] + tol_epi = np.array([1e-4] * 2 * len(frqs)) # R, 1-T + tol_lw = np.array([1e-8] * 2) # line width, line spacing + + for beta, max_eval in zip(betas, max_evals): + solver = nlopt.opt(algorithm, n + 1) + solver.set_lower_bounds(lb) + solver.set_upper_bounds(ub) + solver.set_min_objective(f) + solver.set_maxeval(max_eval) + solver.set_param("dual_ftol_rel", 1e-7) + solver.add_inequality_mconstraint( + lambda rr, xx, gg: c(rr, xx, gg, eta_i, beta), + tol_epi, + ) + solver.set_param("verbosity", 1) + + opt = mode_converter_optimization( + input_flux, + input_flux_data, + True, # use_damping + False if beta <= beta_thresh else True, # use_epsavg + ) + + # apply the minimum linewidth constraint + # only in the final epoch to an initial + # binary design from the previous epoch. + if beta == betas[-1]: + res = np.zeros(2) + grd = np.zeros((2, n + 1)) + t = glc(res, x, grd, beta) + solver.add_inequality_mconstraint( + lambda rr, xx, gg: glc(rr, xx, gg, beta), + tol_lw, + ) + + # execute a single forward run before the start of each + # epoch and manually set the initial epigraph variable to + # slightly larger than the largest value of the objective + # function over the six wavelengths and the lengthscale + # constraint (final epoch only). + t0 = opt( + [mapping(x[1:], eta_i, beta)], + need_gradient=False, + ) + t0 = np.concatenate((t0[0][0], t0[0][1])) + x[0] = np.amax(t0) + if beta == betas[-1]: + x[0] = 1.05 * max(x[0], t) + else: + x[0] = 1.05 * x[0] + print(f"data:, {beta}, {t0}, {x[0]}") + + x[:] = solver.optimize(x) + + optimal_design_weights = mapping( + x[1:], + eta_i, + beta, + ).reshape(Nx, Ny) + + # save the unmapped weights and a bitmap image + # of the design weights at the end of each epoch. + fig, ax = plt.subplots() + ax.imshow( + optimal_design_weights, + cmap="binary", + interpolation="none", + ) + ax.set_axis_off() + if mp.am_master(): + fig.savefig( + f"optimal_design_beta{beta}.png", + dpi=150, + bbox_inches="tight", + ) + # save the final design (unmapped) as a 2d array in CSV format + np.savetxt( + f"design_weights_beta{beta}.csv", + x[1:].reshape(Nx, Ny), + fmt="%4.2f", + delimiter=",", + ) + + # save all the important optimization parameters and output + # as separate arrays in a single file for post processing. + with open("optimal_design.npz", "wb") as fl: + np.savez( + fl, + Nx=Nx, + Ny=Ny, + design_region_size=(dx, dy), + design_region_resolution=design_region_resolution, + betas=betas, + max_eval=max_eval, + objfunc_history=objfunc_history, + epivar_history=epivar_history, + t=x[0], + unmapped_design_weights=x[1:], + minimum_length=minimum_length, + optimal_design_weights=optimal_design_weights, + )