diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 34ea709..22123e9 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -4,9 +4,11 @@ on: push: branches: - main + - dev pull_request: branches: - main + - dev jobs: diff --git a/docs/notebooks/networks/Net0.inp b/docs/notebooks/networks/Net0.inp index 414a644..fd9e0a2 100644 --- a/docs/notebooks/networks/Net0.inp +++ b/docs/notebooks/networks/Net0.inp @@ -16,8 +16,8 @@ File obtained via Mario of a 2 node sysem [PIPES] ;ID Node1 Node2 Length Diameter Roughness MinorLoss Status - P1 R1 J1 100 250 0.05 0 Open ; - P2 J1 D1 1000 200 0.04 0 Open ; + P1 R1 J1 1000 250 0.05 0 Open ; + P2 J1 D1 1000 250 0.05 0 Open ; [PUMPS] ;ID Node1 Node2 Parameters @@ -94,7 +94,7 @@ File obtained via Mario of a 2 node sysem Headloss D-W Specific Gravity 1 Viscosity 1 - Trials 40 + Trials 50 Accuracy 0.1 CHECKFREQ 2 MAXCHECK 10 diff --git a/docs/notebooks/networks/Net0_CM.inp b/docs/notebooks/networks/Net0_CM.inp new file mode 100644 index 0000000..25f9e25 --- /dev/null +++ b/docs/notebooks/networks/Net0_CM.inp @@ -0,0 +1,128 @@ +[TITLE] +File obtained via Mario of a 2 node sysem + + +[JUNCTIONS] +;ID Elev Demand Pattern + J1 0 0 ; + D1 0 50 ; + +[RESERVOIRS] +;ID Head Pattern + R1 30 ; + +[TANKS] +;ID Elevation InitLevel MinLevel MaxLevel Diameter MinVol VolCurve Overflow + +[PIPES] +;ID Node1 Node2 Length Diameter Roughness MinorLoss Status + P1 R1 J1 1000 1000 0.015 0 Open ; + P2 J1 D1 1000 1000 0.015 0 Open ; + +[PUMPS] +;ID Node1 Node2 Parameters + +[VALVES] +;ID Node1 Node2 Diameter Type Setting MinorLoss + +[TAGS] + +[DEMANDS] +;Junction Demand Pattern Category + +[STATUS] +;ID Status/Setting + +[PATTERNS] +;ID Multipliers + +[CURVES] +;ID X-Value Y-Value + +[CONTROLS] + +[RULES] + +[ENERGY] + Global Efficiency 75 + Global Price 0 + Demand Charge 0 + +[EMITTERS] +;Junction Coefficient + +[QUALITY] +;Node InitQual + +[SOURCES] +;Node Type Quality Pattern + +[REACTIONS] +;Type Pipe/Tank Coefficient + + +[REACTIONS] + Order Bulk 1 + Order Tank 1 + Order Wall 1 + Global Bulk 0 + Global Wall 0 + Limiting Potential 0 + Roughness Correlation 0 + +[MIXING] +;Tank Model + +[TIMES] + Duration 1 + Hydraulic Timestep 1:00 + Quality Timestep 0:05 + Pattern Timestep 1:00 + Pattern Start 0:00 + Report Timestep 1:00 + Report Start 0:00 + Start ClockTime 12 am + Statistic None + +[REPORT] + Status No + Summary No + Page 0 + +[OPTIONS] + Units LPS + Headloss C-M + Specific Gravity 1 + Viscosity 1 + Trials 40 + Accuracy 0.1 + CHECKFREQ 2 + MAXCHECK 10 + DAMPLIMIT 0 + Unbalanced Continue 10 + Pattern 1 + Demand Multiplier 1.0 + Emitter Exponent 0.5 + Quality None mg/L + Diffusivity 1 + Tolerance 0.01 + +[COORDINATES] +;Node X-Coord Y-Coord +J1 10.00000 60.00000 +D1 110.00000 60.00000 +R1 -11.72214 74.24023 + +[VERTICES] +;Link X-Coord Y-Coord + +[LABELS] +;X-Coord Y-Coord Label & Anchor Node + +[BACKDROP] + DIMENSIONS 0.000 0.000 10000.000 10000.000 + UNITS None + FILE + OFFSET 0.00 0.00 + +[END] diff --git a/docs/notebooks/networks/Net1.json b/docs/notebooks/networks/Net1.json deleted file mode 100644 index 381797b..0000000 --- a/docs/notebooks/networks/Net1.json +++ /dev/null @@ -1,620 +0,0 @@ -{ - "version": "wntr-0.4.1", - "comment": "WaterNetworkModel - all values given in SI units", - "name": "Net1.inp", - "options": { - "time": { - "duration": 86400.0, - "hydraulic_timestep": 3600, - "quality_timestep": 300, - "rule_timestep": 360, - "pattern_timestep": 7200, - "pattern_start": 0.0, - "report_timestep": 3600, - "report_start": 0.0, - "start_clocktime": 0.0, - "statistic": "NONE", - "pattern_interpolation": false - }, - "hydraulic": { - "headloss": "H-W", - "hydraulics": null, - "hydraulics_filename": null, - "viscosity": 1.0, - "specific_gravity": 1.0, - "pattern": "1", - "demand_multiplier": 1.0, - "demand_model": "DDA", - "minimum_pressure": 0.0, - "required_pressure": 0.07, - "pressure_exponent": 0.5, - "emitter_exponent": 0.5, - "trials": 40, - "accuracy": 0.001, - "unbalanced": "CONTINUE", - "unbalanced_value": 10, - "checkfreq": 2, - "maxcheck": 10, - "damplimit": 0.0, - "headerror": 0.0, - "flowchange": 0.0, - "inpfile_units": "GPM", - "inpfile_pressure_units": null - }, - "report": { - "pagesize": 0, - "report_filename": null, - "status": "YES", - "summary": "NO", - "energy": "NO", - "nodes": false, - "links": false, - "report_params": { - "elevation": false, - "demand": true, - "head": true, - "pressure": true, - "quality": true, - "length": false, - "diameter": false, - "flow": true, - "velocity": true, - "headloss": true, - "position": false, - "setting": false, - "reaction": false, - "f-factor": false - }, - "param_opts": { - "elevation": {}, - "demand": {}, - "head": {}, - "pressure": {}, - "quality": {}, - "length": {}, - "diameter": {}, - "flow": {}, - "velocity": {}, - "headloss": {}, - "position": {}, - "setting": {}, - "reaction": {}, - "f-factor": {} - } - }, - "quality": { - "parameter": "CHEMICAL", - "trace_node": null, - "chemical_name": "Chlorine", - "diffusivity": 1.0, - "tolerance": 0.01, - "inpfile_units": "mg/L" - }, - "reaction": { - "bulk_order": 1.0, - "wall_order": 1.0, - "tank_order": 1.0, - "bulk_coeff": -5.787037037037037e-06, - "wall_coeff": -3.527777777777778e-06, - "limiting_potential": 0.0, - "roughness_correl": 0.0 - }, - "energy": { - "global_price": 0.0, - "global_pattern": null, - "global_efficiency": 75.0, - "demand_charge": 0.0 - }, - "graphics": { - "dimensions": [ - "7.000", - "6.000", - "73.000", - "94.000" - ], - "units": "NONE", - "offset": [ - "0.00", - "0.00" - ], - "image_filename": null, - "map_filename": null - }, - "user": {} - }, - "curves": [ - { - "name": "1", - "curve_type": "HEAD", - "points": [ - [ - 0.0946352946, - 76.2 - ] - ] - } - ], - "patterns": [ - { - "name": "1", - "multipliers": [ - 1.0, - 1.2, - 1.4, - 1.6, - 1.4, - 1.2, - 1.0, - 0.8, - 0.6, - 0.4, - 0.6, - 0.8 - ] - } - ], - "nodes": [ - { - "name": "10", - "node_type": "Junction", - "coordinates": [ - 20.0, - 70.0 - ], - "demand_timeseries_list": [ - { - "base_val": 0.0, - "pattern_name": "1" - } - ], - "elevation": 216.40800000000002, - "emitter_coefficient": null, - "initial_quality": 0.0005, - "minimum_pressure": null, - "pressure_exponent": null, - "required_pressure": null, - "tag": null - }, - { - "name": "11", - "node_type": "Junction", - "coordinates": [ - 30.0, - 70.0 - ], - "demand_timeseries_list": [ - { - "base_val": 0.00946352946, - "pattern_name": "1" - } - ], - "elevation": 216.40800000000002, - "emitter_coefficient": null, - "initial_quality": 0.0005, - "minimum_pressure": null, - "pressure_exponent": null, - "required_pressure": null, - "tag": null - }, - { - "name": "12", - "node_type": "Junction", - "coordinates": [ - 50.0, - 70.0 - ], - "demand_timeseries_list": [ - { - "base_val": 0.00946352946, - "pattern_name": "1" - } - ], - "elevation": 213.36, - "emitter_coefficient": null, - "initial_quality": 0.0005, - "minimum_pressure": null, - "pressure_exponent": null, - "required_pressure": null, - "tag": null - }, - { - "name": "13", - "node_type": "Junction", - "coordinates": [ - 70.0, - 70.0 - ], - "demand_timeseries_list": [ - { - "base_val": 0.00630901964, - "pattern_name": "1" - } - ], - "elevation": 211.836, - "emitter_coefficient": null, - "initial_quality": 0.0005, - "minimum_pressure": null, - "pressure_exponent": null, - "required_pressure": null, - "tag": null - }, - { - "name": "21", - "node_type": "Junction", - "coordinates": [ - 30.0, - 40.0 - ], - "demand_timeseries_list": [ - { - "base_val": 0.00946352946, - "pattern_name": "1" - } - ], - "elevation": 213.36, - "emitter_coefficient": null, - "initial_quality": 0.0005, - "minimum_pressure": null, - "pressure_exponent": null, - "required_pressure": null, - "tag": null - }, - { - "name": "22", - "node_type": "Junction", - "coordinates": [ - 50.0, - 40.0 - ], - "demand_timeseries_list": [ - { - "base_val": 0.01261803928, - "pattern_name": "1" - } - ], - "elevation": 211.836, - "emitter_coefficient": null, - "initial_quality": 0.0005, - "minimum_pressure": null, - "pressure_exponent": null, - "required_pressure": null, - "tag": null - }, - { - "name": "23", - "node_type": "Junction", - "coordinates": [ - 70.0, - 40.0 - ], - "demand_timeseries_list": [ - { - "base_val": 0.00946352946, - "pattern_name": "1" - } - ], - "elevation": 210.312, - "emitter_coefficient": null, - "initial_quality": 0.0005, - "minimum_pressure": null, - "pressure_exponent": null, - "required_pressure": null, - "tag": null - }, - { - "name": "31", - "node_type": "Junction", - "coordinates": [ - 30.0, - 10.0 - ], - "demand_timeseries_list": [ - { - "base_val": 0.00630901964, - "pattern_name": "1" - } - ], - "elevation": 213.36, - "emitter_coefficient": null, - "initial_quality": 0.0005, - "minimum_pressure": null, - "pressure_exponent": null, - "required_pressure": null, - "tag": null - }, - { - "name": "32", - "node_type": "Junction", - "coordinates": [ - 50.0, - 10.0 - ], - "demand_timeseries_list": [ - { - "base_val": 0.00630901964, - "pattern_name": "1" - } - ], - "elevation": 216.40800000000002, - "emitter_coefficient": null, - "initial_quality": 0.0005, - "minimum_pressure": null, - "pressure_exponent": null, - "required_pressure": null, - "tag": null - }, - { - "name": "9", - "node_type": "Reservoir", - "base_head": 243.84, - "coordinates": [ - 10.0, - 70.0 - ], - "head_pattern_name": null, - "initial_quality": 0.001, - "tag": null - }, - { - "name": "2", - "node_type": "Tank", - "bulk_coeff": null, - "coordinates": [ - 50.0, - 90.0 - ], - "diameter": 15.3924, - "elevation": 259.08000000000004, - "init_level": 36.576, - "initial_quality": 0.001, - "max_level": 45.72, - "min_level": 30.48, - "min_vol": 0.0, - "mixing_fraction": null, - "mixing_model": null, - "overflow": false, - "tag": null, - "vol_curve_name": null - } - ], - "links": [ - { - "name": "10", - "link_type": "Pipe", - "start_node_name": "10", - "end_node_name": "11", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.4572, - "initial_setting": null, - "initial_status": "Open", - "length": 3209.5440000000003, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "11", - "link_type": "Pipe", - "start_node_name": "11", - "end_node_name": "12", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.35559999999999997, - "initial_setting": null, - "initial_status": "Open", - "length": 1609.344, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "12", - "link_type": "Pipe", - "start_node_name": "12", - "end_node_name": "13", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.254, - "initial_setting": null, - "initial_status": "Open", - "length": 1609.344, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "21", - "link_type": "Pipe", - "start_node_name": "21", - "end_node_name": "22", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.254, - "initial_setting": null, - "initial_status": "Open", - "length": 1609.344, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "22", - "link_type": "Pipe", - "start_node_name": "22", - "end_node_name": "23", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.30479999999999996, - "initial_setting": null, - "initial_status": "Open", - "length": 1609.344, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "31", - "link_type": "Pipe", - "start_node_name": "31", - "end_node_name": "32", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.15239999999999998, - "initial_setting": null, - "initial_status": "Open", - "length": 1609.344, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "110", - "link_type": "Pipe", - "start_node_name": "2", - "end_node_name": "12", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.4572, - "initial_setting": null, - "initial_status": "Open", - "length": 60.96, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "111", - "link_type": "Pipe", - "start_node_name": "11", - "end_node_name": "21", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.254, - "initial_setting": null, - "initial_status": "Open", - "length": 1609.344, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "112", - "link_type": "Pipe", - "start_node_name": "12", - "end_node_name": "22", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.30479999999999996, - "initial_setting": null, - "initial_status": "Open", - "length": 1609.344, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "113", - "link_type": "Pipe", - "start_node_name": "13", - "end_node_name": "23", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.2032, - "initial_setting": null, - "initial_status": "Open", - "length": 1609.344, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "121", - "link_type": "Pipe", - "start_node_name": "21", - "end_node_name": "31", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.2032, - "initial_setting": null, - "initial_status": "Open", - "length": 1609.344, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "122", - "link_type": "Pipe", - "start_node_name": "22", - "end_node_name": "32", - "bulk_coeff": null, - "check_valve": false, - "diameter": 0.15239999999999998, - "initial_setting": null, - "initial_status": "Open", - "length": 1609.344, - "minor_loss": 0.0, - "roughness": 100.0, - "tag": null, - "vertices": [], - "wall_coeff": null - }, - { - "name": "9", - "link_type": "Pump", - "start_node_name": "9", - "end_node_name": "10", - "pump_type": "HEAD", - "base_speed": 1.0, - "efficiency": null, - "energy_pattern": null, - "energy_price": null, - "initial_setting": null, - "initial_status": "Open", - "pump_curve_name": "1", - "speed_pattern_name": null, - "tag": null, - "vertices": [] - } - ], - "sources": [], - "controls": [ - { - "type": "simple", - "condition": "TANK 2 LEVEL BELOW 33.528", - "then_actions": [ - "PUMP 9 STATUS IS OPEN" - ] - }, - { - "type": "simple", - "condition": "TANK 2 LEVEL ABOVE 42.672000000000004", - "then_actions": [ - "PUMP 9 STATUS IS CLOSED" - ] - } - ] -} \ No newline at end of file diff --git a/docs/notebooks/networks/Net2LoopsDWflat.inp b/docs/notebooks/networks/Net2LoopsDWflat.inp new file mode 100644 index 0000000..3e28b73 --- /dev/null +++ b/docs/notebooks/networks/Net2LoopsDWflat.inp @@ -0,0 +1,145 @@ +[TITLE] +shamir -- Bragalli, D'Ambrosio, Lee, Lodi, Toth (2008) + +[JUNCTIONS] +;ID Elev Demand Pattern + 2 0.00 27.77 ; + 3 0.00 27.77 ; + 4 0.00 33.33 ; + 5 0.00 75.00 ; + 6 0.00 91.67 ; + 7 0.00 55.55 ; + +[RESERVOIRS] +;ID Head Pattern + 1 210.00 ; + +[TANKS] +;ID Elevation InitLevel MinLevel MaxLevel Diameter MinVol VolCurve Overflow + +[PIPES] +;ID Node1 Node2 Length Diameter Roughness MinorLoss Status + 1 1 2 1000.00 457.20 0.05 0.00 Open ; + 2 2 3 1000.00 203 0.05 0.00 Open ; + 3 2 4 1000.00 457 0.05 0.00 Open ; + 4 4 5 1000.00 153 0.05 0.00 Open ; + 5 4 6 1000.00 406.40 0.05 0.00 Open ; + 6 6 7 1000.00 254.00 0.05 0.00 Open ; + 7 3 5 1000.00 153 0.05 0.00 Open ; + 8 5 7 1000.00 153 0.05 0.00 Open ; + +[PUMPS] +;ID Node1 Node2 Parameters + +[VALVES] +;ID Node1 Node2 Diameter Type Setting MinorLoss + +[TAGS] + +[DEMANDS] +;Junction Demand Pattern Category + +[STATUS] +;ID Status/Setting + +[PATTERNS] +;ID Multipliers + +[CURVES] +;ID X-Value Y-Value + +[CONTROLS] + + + +[RULES] + + + +[ENERGY] + Global Efficiency 75 + Global Price 0 + Demand Charge 0 + +[EMITTERS] +;Junction Coefficient + +[QUALITY] +;Node InitQual + +[SOURCES] +;Node Type Quality Pattern + +[REACTIONS] +;Type Pipe/Tank Coefficient + + +[REACTIONS] + Order Bulk 1 + Order Tank 1 + Order Wall 1 + Global Bulk 0 + Global Wall 0 + Limiting Potential 0 + Roughness Correlation 0 + +[MIXING] +;Tank Model + +[TIMES] + Duration 0:00 + Hydraulic Timestep 1:00 + Quality Timestep 0:05 + Pattern Timestep 2:00 + Pattern Start 0:00 + Report Timestep 1:00 + Report Start 0:00 + Start ClockTime 12 am + Statistic NONE + +[REPORT] + Status Yes + Summary No + Page 0 + +[OPTIONS] + Units LPS + Headloss D-W + Specific Gravity 1.0 + Viscosity 1.0 + Trials 40 + Accuracy 0.001 + CHECKFREQ 2 + MAXCHECK 10 + DAMPLIMIT 0 + Unbalanced Continue 10 + Pattern 1 + Demand Multiplier 1.0 + Emitter Exponent 0.5 + Quality Chlorine mg/L + Diffusivity 1.0 + Tolerance 0.01 + +[COORDINATES] +;Node X-Coord Y-Coord +2 2000.000 3000.000 +3 1000.000 3000.000 +4 2000.000 2000.000 +5 1000.000 2000.000 +6 2000.000 1000.000 +7 1000.000 1000.000 +1 3000.000 3000.000 + +[VERTICES] +;Link X-Coord Y-Coord + +[LABELS] +;X-Coord Y-Coord Label & Anchor Node + +[BACKDROP] + DIMENSIONS 900.000 900.000 3100.000 3100.000 + UNITS None + FILE + OFFSET 0.00 0.00 + +[END] diff --git a/docs/notebooks/pipe_diameter_optimization/design_pipe_diameter.ipynb b/docs/notebooks/pipe_diameter_optimization/design_pipe_diameter.ipynb new file mode 100644 index 0000000..57ed226 --- /dev/null +++ b/docs/notebooks/pipe_diameter_optimization/design_pipe_diameter.ipynb @@ -0,0 +1,410 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Designing Water Networks with a QUBO approach\n", + "\n", + "In this notebook we present how to optimize the diameters of the pipe of a water network to minimize the cost of the network while keeping the pressure abov a certain threshold. \n", + "\n", + "The hydraulics equations can be written as:\n", + "\n", + "$$\n", + " \\sum_j s_{ij} y_{ij} - D_i = 0 \\newline\n", + " h_{L_{ij}} \\equiv h_i - h_j = A s_{ij} y_{ij}^{B}\n", + "$$\n", + "\n", + "In order to consider several pipe diameters we extend these equations with new variables\n", + "\n", + "\n", + "$$\n", + " \\sum_j s_{ij} y_{ij} - D_i = 0 \\newline\n", + " h_{L_{ij}} \\equiv h_i - h_j = \\sum_d \\delta_{d,ij} A_{d,ij} s_{ij} y_{ij}^{B}\n", + "$$\n", + "\n", + "where $\\delta_{d,ij} = [0,1]$ is used to select a given diameter, $d$, of the pipe $ij$. If only a single $\\delta_{d,ij}$ equals 1 while all the other are null, we find the original head loss equation. It is therefore immediately clear that we need to enforce at all time the following condition:\n", + "\n", + "$$\n", + " \\sum_d \\delta_{d,ij} = 1 \\quad \\forall \\quad ij\n", + "$$\n", + "\n", + "For the QUBO problem to also minimize the cost of the total network we need to add one equation:\n", + "\n", + "$$\n", + " \\omega_\\mu \\sum_{ij}\\sum_d \\delta_{d,ij} \\mu_{d,ij} \\rightarrow 0\n", + "$$\n", + "\n", + "\\noindent where $\\mu_{d,ij}$ is the price of pipe $ij$ for a diameter $d$. $\\omega_\\mu$ is a parameter that determines the relative weight of this equation when optimizing the QUBO problem. Finally if we want to constrain the values of the head node we need to impose conditions such as:\n", + "\n", + "$$\n", + " h_k \\geq H_{\\textnormal{min}} \\quad \\forall \\quad k\n", + "$$\n", + "\n", + "these equations are enforced by introducing slack variables and extra penalty terms in the QUBO objective function." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Example \n", + "\n", + "We demonstrate here how to optimize the water network using our QUBO approach. We start by defining the network." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "import wntr\n", + "inp_file = '../networks/Net0_CM.inp'\n", + "wn = wntr.network.WaterNetworkModel(inp_file)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# QUBO Designer\n", + "\n", + "We now show how to optimize the problem using the QUBO designer included in `wntr_quantum`. The unknown of the problem can take continuous values and therefore must be encoded using several qubits before being used in a QUBO formulation. We use here the encoding implemented in our library `qubops`. We use these encoding schemes to instantiate the polynomial solver." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [], + "source": [ + "from wntr_quantum.sim.solvers.qubo_polynomial_solver import QuboPolynomialSolver\n", + "from qubops.encodings import PositiveQbitEncoding\n", + "\n", + "nqbit = 5\n", + "step = (4./(2**nqbit-1))\n", + "flow_encoding = PositiveQbitEncoding(nqbit=nqbit, step=step, offset=+0.0, var_base_name=\"x\")\n", + "\n", + "nqbit = 7\n", + "step = (200/(2**nqbit-1))\n", + "head_encoding = PositiveQbitEncoding(nqbit=nqbit, step=step, offset=+0.0, var_base_name=\"x\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can now create an instance of the designer. We choose to explore a small problem where each pipe can only take 3 distinct values: 250 cm, 500 cm and 1000 cm. We fix the threshold pressure at 29 m. We also adjust the weight of the constraints related to the cost minimization and pressure. " + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Head Encoding : 0.000000 => 200.000000 (res: 1.574803)\n", + "Flow Encoding : -4.000000 => -0.000000 | 0.000000 => 4.000000 (res: 0.129032)\n" + ] + } + ], + "source": [ + "from wntr_quantum.design.qubo_pipe_diam import QUBODesignPipeDiameter \n", + "pipe_diameters = [250, 500, 1000]\n", + "designer = QUBODesignPipeDiameter(wn, flow_encoding, head_encoding, \n", + " pipe_diameters, head_lower_bound=29,\n", + " weight_cost=2, weight_pressure=0.5)\n", + "designer.verify_encoding()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can enumerate the possible values of the flow and pressure for all possible values of the pipe diameters" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "price \t diameters \t variables\t energy\n", + "0.16907910944516957 [250. 250.] [ 0.05 0.05 20.689 11.378] -7664.1098579916925\n", + "0.25361866416775436 [250. 500.] [ 0.05 0.05 20.689 20.457] -8935.861761472075\n", + "0.42269777361292393 [ 250. 1000.] [ 0.05 0.05 20.689 20.683] -8936.03578895648\n", + "0.25361866416775436 [500. 250.] [ 0.05 0.05 29.769 20.457] -9306.916077552014\n", + "0.33815821889033915 [500. 500.] [ 0.05 0.05 29.769 29.537] -9683.3290149783\n", + "0.5072373283355087 [ 500. 1000.] [ 0.05 0.05 29.769 29.763] -9683.388691481696\n", + "0.42269777361292393 [1000. 250.] [ 0.05 0.05 29.994 20.683] -9305.869457285251\n", + "0.5072373283355087 [1000. 500.] [ 0.05 0.05 29.994 29.763] -9682.168043730535\n", + "0.6763164377806783 [1000. 1000.] [ 0.05 0.05 29.994 29.988] -9681.999018271925\n" + ] + }, + { + "name": "stderr", + "output_type": "stream", + "text": [ + "/home/nico/miniconda3/envs/vitens_wntr_1/lib/python3.9/site-packages/quantum_newton_raphson/utils.py:74: SparseEfficiencyWarning: spsolve requires A be CSC or CSR matrix format\n", + " warn(\"spsolve requires A be CSC or CSR matrix format\", SparseEfficiencyWarning)\n" + ] + } + ], + "source": [ + "solutions = designer.enumerates_classical_solutions(convert_to_si=True)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Initial sample for the QUBO optimization \n", + "\n", + "Before minimizing the energy of the QUBO problem we need to define the initial configuration of the binary variables in the QUBO problem. We have implemented two different ways to obtain an initial sample that respects all the conditions imposed by the quadratization constraings of the polynomial qubo solver. \n", + "\n", + "We can for example create a completely random sample that simply ensure that quadratization constraints are respected" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "from wntr_quantum.sampler.simulated_annealing import modify_solution_sample\n", + "x = modify_solution_sample(designer, solutions[(500,500)][2], modify=['flows','heads'])\n", + "x0 = list(x.values())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Temperature scheduling for the Simulated Annealing optimization\n", + "\n", + "One important parameters of the simulated Annealing process is the the so-called temperature schedule. This schdule defines the acceptance probability of the new samples that increase the QUBO energy. While high temperature that leads to accepting samples that increase energy is usefull to escape local minima the temperature must be decreased in order to converge towards a minima. \n", + "\n", + "The temperature schedule usually starts with high temperature values that allows to explore the energy landscape but progressively decrease the tempearture in order for the optimization to converge. " + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "num_temp = 5000\n", + "Tinit = 1E3\n", + "Tfinal = 1E-1\n", + "Tschedule = np.linspace(Tinit, Tfinal, num_temp)\n", + "Tschedule = np.append(Tschedule, Tfinal*np.ones(1000))\n", + "Tschedule = np.append(Tschedule, np.zeros(100))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Solve the problem\n", + "\n", + "We can then use the `solve()` method of the qubo polynomial solver to obtain a solution of the problem" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "100%|██████████| 6100/6100 [00:20<00:00, 296.20it/s]\n" + ] + } + ], + "source": [ + "designer.step_func.optimize_values = np.arange(2,12)\n", + "data = designer.solve(init_sample=x0, Tschedule=Tschedule,\n", + " save_traj=True, verbose=False)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can plot the evoluion of the QUBO energy along the optimization path" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAlUAAAG1CAYAAADQqgGtAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjguNCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8fJSN1AAAACXBIWXMAAA9hAAAPYQGoP6dpAACCB0lEQVR4nO3dd3xTVf8H8E+SbtpCGR2stuxZpmBVBKFQARXcAjLc8ANlPQg8KsuBiqCoKCoqoAhuUECglA1l71VWy27LatPdNLm/P/o0Ns3oTXOT3Jt+3q+XL8nNyb3fnNzmfnPOueeoBEEQQEREREQOUbs7ACIiIiJPwKSKiIiISAJMqoiIiIgkwKSKiIiISAJMqoiIiIgkwKSKiIiISAJMqoiIiIgk4OXuAKoKg8GAa9euISgoCCqVyt3hEBERkQiCICA7Oxt169aFWm27LYpJlYtcu3YNDRo0cHcYREREVAmXL19G/fr1bZZhUuUiQUFBAEo+lODgYEn3rdPpsGHDBvTp0wfe3t6S7ttTsI7EYT2Jw3oSh/UkDutJHHfVk1arRYMGDYzXcVuYVLlIaZdfcHCwU5KqgIAABAcH8w/SCtaROKwncVhP4rCexGE9iePuehIzdIcD1YmIiIgkwKSKiIiISAJMqoiIiIgkwKSKiIiISAIcqE5ERE6h1+vh5eWFgoIC6PV6d4cjWzqdjvUkgtT1pNFoJB/wzqSKiIgkJQgC0tLSkJmZifDwcFy+fJmTHtsgCALrSQRn1JOvry9q164t2V35TKqIiEhSWVlZyMzMRO3atSEIAgIDAyuciboqMxgMyMnJYT1VQMp6EgQBOp0OWVlZuHr1KgBIklgxqSIiIskIgoCMjAwEBwejVq1a0Gq18PPzY7Jgg8FgQFFREeupAlLXk7+/P4KCgnDlyhXcvHlTkqSKnx4REUlGr9dDr9dLPskxkTOoVCpUr14dhYWF0Ol0Du+PSRUREUmmuLgYAODlxY4QUobSwepSDH5nUkVERJLjgGtSCinPVf6UIHKC9SfSsGzPJegNBjx9V0M80q6uu0MiIiInY1JFJLEtyRkY+eMBCELJ453nbsFbrULfthHuDYyIiJyK3X9EEvsh6aIxoSr18/7L7gmGiIhchkkVkcQST2eYbduSfMMNkRCRM5w4cQLPPvss6tWrB19fX9StWxfPPvssTp48aVZ2xowZUKlUuHnzpsV9tWnTBj179jQ+Tk1NhUqlMvkvODgY7du3x+eff25xMHVubi7efvttxMTEICAgANWrV0e3bt2wdOlSCOV/4VnRo0cPs+OW/teiRQuRNUOKTqqioqLMPvz333/fpMzRo0fRrVs3+Pn5oUGDBvjwww/N9vPrr7+iRYsW8PPzQ9u2bbF27VqT5wVBwLRp0xAREQF/f3/ExcXh7NmzTn1vREQkP3/88Qc6duyIxMREPPfcc/jiiy/wwgsvYNOmTejYsSNWrVolyXEGDRqEH374AT/88ANmz56NevXq4dVXX8WUKVNMyqWnp6Nr166YMWMG2rZti08++QRvv/021Go1hg8fjkGDBom+q61+/frGY5b9b86cOZK8p6pA8WOqZs2ahZdeesn4OCgoyPhvrVaLPn36IC4uDgsXLsSxY8fw/PPPo0aNGnj55ZcBALt27cKgQYMwe/ZsPPTQQ/jpp58wcOBAHDx4EG3atAEAfPjhh/j000+xZMkSREdH46233kJ8fDxOnjwJPz8/175hIiJyi/Pnz2Po0KFo1KgRtm3bhjp16hifGzt2LLp164Znn30WR48eRXR0tEPH6tixI5599lnj4//7v/9D165d8dNPP5kkOcOHD8epU6fw559/4pFHHjFuf+211zBp0iR89NFH6NChAyZPnlzhMatXr25yTHfKy8tDQECAu8Owm+KTqqCgIISHh1t8btmyZSgqKsJ3330HHx8ftG7dGocPH8a8efOMSdX8+fPx4IMPYtKkSQCAt99+GwkJCfj888+xcOFCCIKATz75BG+++SYGDBgAAFi6dCnCwsKwcuVKPPPMM655o0RECjX1j2M4k5Hj7jDMNA8LwvuPx4guP2fOHOTl5eHrr782SagAoHbt2vjqq6/QvXt3zJkzB1988YWksapUKoSFhSE9Pd24bffu3Vi/fj2ef/55k4Sq1OzZs7Fq1Sp88MEHeO211+Dv7+9wHDNmzMDMmTNx9uxZvPPOO1i5ciUEQcBjjz2GBQsWmCVCP/74Iz7++GOcPHkS/v7+6NOnD+bMmYMGDRoYy/To0QM3b97EkiVLMH78eOzfvx8vv/wyPvnkE9y6dQvjxo3DqlWroFar0bdvX7z++uvo2LEjvv/+e4wYMQLff/89nn/+eRw8eBAdOnQwOf57772Ht956C5cuXUK9evUcfv8VUXxS9f777+Ptt99Gw4YNMXjwYIwfP9446VxSUhLuv/9++Pj4GMvHx8fjgw8+wJ07dxASEoKkpCRMmDDBZJ/x8fFYuXIlACAlJQVpaWmIi4szPl+9enV07doVSUlJVpOqwsJCFBYWGh9rtVoAJatsSzFra1ml+5N6v55EDnWkhM9HDvWkBKwn63Q6HQRBgMFgMI7nOZOejUOXs9wcmQVCydInYv3999+IiorCvffea/F19913H6KiovD333/j888/LznE/+rAYDBYPVZpmdJ6A0rGSWVklIzP1Gq1WLduHdatW4cpU6YYy/z1118AgGeffdbivtVqNQYNGoRZs2Zh+/btJtcxS/R6vfGYZfn7+6NatWomsT711FOIiorCu+++i0OHDuHbb79FnTp1TIbgvPfee5g2bRqefPJJPP/887h58yY+//xz3H///Thw4ABq1KhhLHvr1i307dsXTz/9NAYPHoywsDAUFxfj4Ycfxt69ezFy5Eg0b94cf/75J5577jmTOn3ssccwevRo/Pjjj2jXrp1J7MuWLUOPHj0QERFhtf5Lz1WdTgeNRmP2vD1/54pOql577TV07NgRNWvWxK5duzB16lRcv34d8+bNAwCkpaWZNcGGhYUZnwsJCUFaWppxW9kyaWlpxnJlX2epjCWzZ8/GzJkzzbZv2LDBaU2aCQkJTtmvJ3FNHVn+syo/Vk/OeC6Jw3oy5+XlhfDwcOTk5KCoqAgAoNeLT1xcSa/XG3/wViQrKwvXrl1Dv379bL6mZcuW+Oeff3D16lUEBQUZf1xnZ2eb/MAvG0PpmKfs7Gzk5JS06M2YMQMzZswwKfv8889jwoQJxuMfPXoUANCoUSOrMTVt2hQAcPjwYXTp0sVq3MXFxTh9+rTZtQ4ARowYgY8//hgAjO+ndevW+OyzzwAAQ4YMQXp6Or799lv897//BQBcunQJM2bMwBtvvIGJEyca99W7d290794dH3/8sXF7cXEx0tLSMG/ePGPCBADLly9HUlISZs+ejZEjRxqP9eijjwIACgoKjO+7X79+WL58Od544w3juoBHjx7FyZMnMXr0aJufWVFREfLz87Ft2zbjigBl5eXlWX1tebJLqqZMmYIPPvjAZplTp06hRYsWJi1MMTEx8PHxwSuvvILZs2fD19fX2aHaNHXqVJP4tFotGjRogD59+ki+JpZOp0NCQgJ69+5tnG6fTLmyjsYmbbC4vV+/fk49rhR4LonDerKuoKAAly9fRmBgIHx9fZGdnQ2NRp73RGk0GtHfx6UX5ZCQEJuvCQkJAQDjXXul16KgoCCLr9NoNMbWkaCgIAQGBgIAXnrpJTzxxBPGY2/evBkLFy5EUFCQseGgoKAAAFC3bl2LLSwAEBoaCqAkcbAVt5eXF6KiovDVV1+ZPVe/fn3ja0vfz5gxY0z298ADD2D16tUAgODgYGzcuBEGgwFDhw41JtcA0KRJEzRt2hRJSUnG13t5ecHX1xejRo0ySTy3bdsGb29vjBkzBgEBARAEAdnZ2Xj11Vexbds2+Pn5Gffx/PPP4/fff8eBAwfQq1cvAMCqVavg7++PIUOGmIy3Lq+goAD+/v64//77LY6TFpt4AzJMqiZOnIgRI0bYLNOoUSOL27t27Yri4mKkpqaiefPmCA8PN+l/BmB8XDoOy1qZss+XbouIiDAp0759e6sx+vr6WkzsvL29nfYl7Mx9ewp31pGSPhueS+Kwnszp9XqoVCqo1eoyy3/IdMkaFYytGhWpXr06ACAnJ8fma3JycqBSqRAaGmpSB2q12urrSreX1hsANGvWDH369DGWeeKJJ6BWqzF//ny88MILaNu2rTFRyM3NNelKKys3NxdASaJT0XutVq2ayTEtKX0/UVFRJvurWbMmgJIWvRo1auDcuXMQBAHNmze3uB9vb2+T19erV88sobl06RIiIiKMiWZp912TJk0AmNZpfHw8IiIisHz5cvTu3RsGgwErVqzAgAEDjJ+dNaWfk7W/Z3v+xmWXVNWpU8dsAKBYhw8fhlqtNmbmsbGxeOONN6DT6YyVkpCQgObNmxt/TcTGxiIxMRHjxo0z7ichIQGxsbEAgOjoaISHhyMxMdGYRGm1WuzZswejRo2q5LskIqo6moUFyjKvah5mvfWivOrVq6Nu3brGLjdrjh49ivr16xtbXEoThfz8fIvl8/LyRPes9OrVC59//jm2bduGtm3bomXLlli5ciWOHj2K+++/32o8ANCqVStRxxDLWstY2TFkKpUK//zzj8WypYlSKUcH0Ws0GgwePBjffPMNvvjiC+zcuRPXrl1z+d2MskuqxEpKSsKePXvwwAMPICgoCElJSRg/fjyeffZZY8I0ePBgzJw5Ey+88AImT56M48ePY/78+ca+YaDkNtju3btj7ty56N+/P1asWIH9+/fj66+/BlCSlY8bNw7vvPMOmjZtapxSoW7duhg4cKA73joRkaLMfqyt6BYhOXv44Yfx1VdfYceOHbjvvvvMnt++fTtSU1NNhn5ERkYCAJKTk03ueANKEqrLly+jd+/eoo5fOt6ndNzVQw89hNmzZ2Pp0qUWkyq9Xo+ffvoJISEhuPfee8W9SYk0btwYgiAgOjoazZo1q9Q+IiMjsXnzZrPpFc6dO2ex/LBhwzB37lz8/fff+Oeff1CnTh3Ex8dX6tiVpdiz3NfXFytWrED37t3RunVrvPvuuxg/frwxGQJKflls2LABKSkp6NSpEyZOnIhp06YZp1MAgHvuuQc//fQTvv76a7Rr1w6//fYbVq5caZyjCgBef/11vPrqq3j55Zdx1113IScnB+vWreMcVUREVch//vMfBAQE4JVXXsGtW7dMnrt9+zZGjhyJ4OBgjBkzxri9V69e8PHxwZdffml299nXX3+N4uJiPPjgg6KO//fffwOA8Q63e+65B3Fxcfj++++N45nKeuONN3DmzBm8/vrrkkynYI/HHnsMGo0GM2fONJvVXRAEs/qzJD4+HjqdDt98841xm8FgwJdffmmxfExMDGJiYrBo0SL8/vvveOaZZ4yzAbiKYluqOnbsiN27d1dYLiYmBtu3b7dZ5sknn8STTz5p9XmVSoVZs2Zh1qxZdsdJRESeoUmTJli6dCkGDRqEtm3b4oUXXkB0dDRSU1Px7bff4s6dO1ixYoXJXeehoaGYNm0a3nzzTdx///145JFHEBAQgF27dmH58uXo06cPHn74YWPrU6mDBw/ixx9/BFByV2BiYiJ+//133HPPPSbjnpYuXYpevXphwIABGDx4MLp164bCwkL88ccf2LJlC55++mnjPIwVycrKMh6zPHu70Ro3box33nkHU6dORWpqKgYOHIigoCCkpKTgzz//xMsvv4z//Oc/NvcxcOBAdOnSBRMnTsS5c+eMUyrcvn0bAMqM2fvXsGHDjPt1x0Smik2qiIiIXO3xxx/HwYMHMXv2bCxatAgZGRkwGAzw8/PDgQMHLI5deuONNxAVFYXPP/8cs2bNQnFxMaKjozFz5kxMnjzZYtfo8uXLsXz5cgAld8c1bNgQkyZNwrRp00zKR0REYO/evZg7dy5+/fVX/P777/Dy8kJMTAwWL16MYcOGWUw+LLly5QqGDh1q8bnKJChTpkxBs2bN8PHHHxunGCq9C97SZKXlaTQarFmzBmPHjsWSJUugVqvRv39/zJw507j8XHlDhgzB5MmT0bhxY5tTSDgLkyoiIiI7tGnTBsuWLTM+Xrp0KUaMGIH3338fS5cutfiaIUOGYMiQIRafK9stGBUVJXoR5FKBgYGYPn06pk+fbtfrytqyZYuocpbmzwJK5rKydOf+Y489hscee6zSx65du7axrg0GA7RaLTZt2gSgZKqH8ry8vKBSqdy23A6TKiIiIgcMGzYM169fx5QpU1C/fn2899577g7JY+Tn55uMB9Pr9ViwYAGCg4PRsWNHs/KLFy+GXq+32uLmbEyqiIiIHDR58mRRixaTfV599VXk5+cjNjYWBQUF+PXXX7F371689957JsnWpk2bcPLkSbz77rsYOHAgoqKi3BIvkyoiIiKSpZ49e2Lu3LlYvXo1CgoK0KhRI3z66ad49dVXTcrNmjULu3btwr333mtcPscdmFQRERGRLA0ePBiDBw8G8O+YKkvL7YgdE+Zsip2nioiIiEhOmFQREZHk7L2DjchdpDxXmVQREZFkSmewLl1ShUjudDodAOvrGdqDSRUREUlGo9FAo9FAq9W6OxSiCgmCgKysLPj6+sLb29vh/XGgOhERSUalUiE0NBTXr1+Hj48PBEFAQUGBRyyo7CwGgwFFRUWspwpIWU+CIECn0yErKws5OTmoV6+eJDEyqSIiIklVr14d+fn5uHnzJvLy8uDv7y96qZSqSBAE4ySXrCfrnFFPvr6+qFevnsU7CiuDSRUREUlKpVIhIiICISEhSExMxP333y9J14qn0ul02LZtG+upAlLXk0ajkby+mVQREZFTaDQaFBcXw8/Pj8mCDawncZRQT+y8JSIiIpIAkyoiIiIiCTCpIiIiIpIAkyoiIiIiCTCpIiIiIpIAkyoiIiIiCTCpIiIiIpIAkyoiIiIiCTCpIiIiIpIAkyoiIiIiCTCpIiIiIpIAkyoiIiIiCTCpIiIiIpIAkyoiIiIiCTCpIiIiIpIAkyoPIwiCu0MgIiKqkrzcHQBJIzUbeOKrPTh/Ixddo2vigydiUDvQ191hERERVRlsqfIAmXk6fHlKgyNXspBTWIzE0xl45YcD7g6LiIioSmFS5QHWHE9DgV5lsu3AxTu4fDvPTRERERFVPUyqPMDvB69a3H7imtbFkRAREVVdTKqIiIiIJMCkyqPxTkAiIiJXYVJFREREJAEmVURuJAgCdHqDu8MgIiIJcJ4qD6CquAjJ0KbT6Xh79SlcuZOHzpE18fHT7RFe3c/dYRERUSWxpcoDcOSU8lzNzMfIHw8i5WYudHoBSRduYcT3e2Ew8NMkIlIqJlVEEriamY9zGTmilwnaee4miopNu/1Op2XjTEa2M8IjIiIXYPefB2D3n/sUFRvw6vKDWH8iHQDQvkENUa/bff6Wxe0pN3LRIjxYqvCIiMiF2FLlAdhh5D4/7r5oTKgA4PDlTFGvu2RltvsiDlonIlIsJlVEDpi1+mSlXufjZflPr3yXIBERKQeTKg/A7j/lUassf2psdSQiUi4mVUREREQSYFJFREREJAEmVUREREQSYFJFJCccVEVEpFhMqoiIiIgkwKTKg4mc3JvkhLdyEhEpFpMqIiIiIglwmRqSTFGxAVuSM3D+Ri5iG9cSvWQLERGRJ2BSRZIo1hsw5qeD2HDy3yVb3n20DYZ0jXRjVArELlsUFutx4UYuompVg7+Pxt3hEBGJxqTKE8hgHM7hy5kmCRUAfLQ+GYPuagi1WgYByoyVCdWrLINBwL7U21i0IwUJ/zuP/L01+OjJdugfE+Hm6IiIxOGYKk8gg9aNuRvOmG27k6fD4SuZrg+GFEUQBLyx8hie/nq3MaECgHydHv/59Qiy8nVujI6ISDwmVSSJ61n5FrcX6PQujoSU5nRaNpbvvWzxuXydHiv2XnJxRERElcOkyhOwK4kUbMHmczafP3Qp0zWBEBE5iEkVOZcMuiaVRKiCFXbpdp7N5zn+jIiUgkkVEbkVcyYi8hSKT6rWrFmDrl27wt/fHyEhIRg4cKDJ85cuXUL//v0REBCA0NBQTJo0CcXFxSZltmzZgo4dO8LX1xdNmjTB4sWLzY6zYMECREVFwc/PD127dsXevXud+K48CK+YdlFVxQpjUxQReQhFJ1W///47hg4diueeew5HjhzBzp07MXjwYOPzer0e/fv3R1FREXbt2oUlS5Zg8eLFmDZtmrFMSkoK+vfvjwceeACHDx/GuHHj8OKLL2L9+vXGMj///DMmTJiA6dOn4+DBg2jXrh3i4+ORkZHh0verSFWvN4skxpyLiJRCsUlVcXExxo4dizlz5mDkyJFo1qwZWrVqhaeeespYZsOGDTh58iR+/PFHtG/fHn379sXbb7+NBQsWoKioCACwcOFCREdHY+7cuWjZsiXGjBmDJ554Ah9//LFxP/PmzcNLL72E5557Dq1atcLChQsREBCA7777zuXvW65UvPIREVEVp9jJPw8ePIirV69CrVajQ4cOSEtLQ/v27TFnzhy0adMGAJCUlIS2bdsiLCzM+Lr4+HiMGjUKJ06cQIcOHZCUlIS4uDiTfcfHx2PcuHEAgKKiIhw4cABTp041Pq9WqxEXF4ekpCSr8RUWFqKwsND4WKvVAgB0Oh10Omnn3REMlpuDdMXFkh/LGoOVGIr1rovBltIY3BlL2WPLtb7cUk8VrPwtGARZnENlyeF8UgLWkzisJ3HcVU/2HE+xSdWFCxcAADNmzMC8efMQFRWFuXPnokePHjhz5gxq1qyJtLQ0k4QKgPFxWlqa8f+Wymi1WuTn5+POnTvQ6/UWy5w+fdpqfLNnz8bMmTPNtm/YsAEBAQH2v2EbtFoNLA1eOnToEIRLrul/y82zHMOePXtx57R8+gATEhIk3qP4P6G1a9ca/33rphqWGoqPHj2GaulHpQjMIdLXk3VZmZbPnVLX065j7dqrLovHHq6sJyVjPYnDehLH1fWUl2f7DuWyZJdUTZkyBR988IHNMqdOnYLBYAAAvPHGG3j88ccBAN9//z3q16+PX3/9Fa+88orTY7Vl6tSpmDBhgvGxVqtFgwYN0KdPHwQHB0t6rEUXk4CcbLPtHTp0QN824ZIey5p5yTtws8D8xOvatQtiG9VySQy26HQ6JCQkoHfv3vD29pZsv2OTNogu269fP+O/f71xAMi6ZVYmJqYt+nWqL0lsleGserLl+yt7gJwsq8/XjYhAv37tXBKLWO6oJyViPYnDehLHXfVU2tMkhuySqokTJ2LEiBE2yzRq1AjXr18HALRq1cq43dfXF40aNcKlSyUzMIeHh5vdpZeenm58rvT/pdvKlgkODoa/vz80Gg00Go3FMqX7sMTX1xe+vr5m2729vSU/GVRW1tbz8vJy2YlnbX0/L43rYhDDGfVvz7FLWRuDptFoZFFfrqwndQXj8VRqtSzqxBJ3nk9KwnoSh/UkjqvryZ5jyS6pqlOnDurUqVNhuU6dOsHX1xfJycm47777AJRksampqYiMjAQAxMbG4t1330VGRgZCQ0MBlDQbBgcHG5Ox2NhYk26Z0jKxsbEAAB8fH3Tq1AmJiYnG6RoMBgMSExMxZswYSd6zo+RwG75QwbgYIiIiT6fYu/+Cg4MxcuRITJ8+HRs2bEBycjJGjRoFAHjyyScBAH369EGrVq0wdOhQHDlyBOvXr8ebb76J0aNHG1uRRo4ciQsXLuD111/H6dOn8cUXX+CXX37B+PHjjceaMGECvvnmGyxZsgSnTp3CqFGjkJubi+eee871b9yCqjgLN1Ud7v/JQEQkjuxaquwxZ84ceHl5YejQocjPz0fXrl2xadMmhISEACjpSlm9ejVGjRqF2NhYVKtWDcOHD8esWbOM+4iOjsaaNWswfvx4zJ8/H/Xr18eiRYsQHx9vLPP000/jxo0bmDZtmvEuw3Xr1pkNXq/KOKUCVZa2oLjiQkRECqDopMrb2xsfffQRPvroI6tlIiMjzbr3yuvRowcOHTpks8yYMWNk091Xnhy6/4gq61xGjs3nmbATkVIotvuP/iXn7j/5RkZERCQtJlVEJGtspyIipWBS5QHk3P0n38jkiTdREhEpF5MqcirmCJZxnBARkedhUkWSYIpAzsL8k4iUgkmVB3NlVxJbpMhZmFMRkVIwqSJyA85ALx67SolIKZhUkVO98sMBHL9qfbFcIiIiT8GkyoOdSc92WYuItbaEnMJiDP5mN9K1BS6Jo6zLt/OwfO8lbEnOQFGxocLyGdoCJJ2/hbwizvAtJ2ynIiKlUPSM6lTCWu/I/MSz2JNyC9+NuAsBPs79qG2lbtqCYmw+nYFnujR0agxlbT97Ay8u2Y/C/yVT3ZrUwoBa1ssv2HwOc9YnAwACfDT4bsRduLuRjRc4iF1aRESehy1VHsBWY9TuC7exaHuK64Kx4tsdro1h9trTxoQKALafu4WTdywnMucyso0JFQDkFekx4efDHPdERER2YVJVBcxLOOP0Y1TU7pJb6LoutQKdHieva822/55i+XT/etsFs23Xsgos7oPcgI16RKQQTKo8gBJ6krJdmFQZrLQwZeksV9ShS5kWt9/ILpQqJHKAl1oBJzgREZhUeQQl9FLlF+ndHYJVckpK3fFRCoKAHBcmvfYK8vN2dwhERKJwoDq5hFpOmYsMyKU21hy9jrdXn0SatgDt6lfHx0+1dXdIZuRSV0REFWFLlQdQQr5SpK94SgO5cWarkRwaF1Nu5uK1FYeQ9r/pLo5cycL/LTvs3qCIiBSMSRW5TLFMEyuVjNpCXBnJuuNp0BtM07vT6Tm45fopxWxSwo8GIiKASRW50JErme4Ogcr4ae9Fi9vvFLk4kApwTi8iUgomVeQyF27kujsEi5LTsy0/4YY+Olce0mCl4ZApDBFR5TCpIpfx8eLpVoqJi3isKyJSCl7lyGV8NDzdlEB2SYzsAiIisoxXOZKGiAufRmGTOAqyuEeP5HQjARGRLUyqPICYS87tXCePPhaRf3DAsbxwbUMiImkxqfIAYi6NHd9OwCcbz7j1QsqLeMVcWUXWDiW33Fdu8RARWcOkqgr5ZONZHL2S5Zyde+CFL13rvLX/5JAoKCXHlUFVERGJwqRK4f48dAWHL4tPlN5cedyJ0XiWD9eddtq+5ZDQWBszxiSGiKhyuPafgn27IwVvrz5p12uOXXVSS5UHupOnc/kx5dCCJTcyyD+JiERhS5WC/bjb8ozYRGLIobVMDKXESUTEpErBUm7KZ4Zyuc6WrjSyGKjuuhBE4dQWRKQUTKrIZXhp/FdF3XyCICBdW+DUOyat7lp+WRURkSJwTBWRzCSeSsfk34/hZk4hwoP9MO+pdrinSW3Jj3Mzx3l3N0qJORURKQVbqohk5HZuIUb9eNCY8KRpC/DCkv3ILSyW9Dh6g3JSFc5vRkRKwaSKSEY2nspAkd5gsi1fp8e2MzckPc6hS3esPie73j/mVESkEEyqFIq/3j3T4cuZFrefuq6V9Dj5Or3V52SXVLk7ACIikZhUKZQScyolxuyplLRIMc8bIlIKJlUKxetM1SL15622kVPJbQJSTqlARErBpEqh2P1XtUj+ccsscbKFpzoRKQWTKiIFkLq1Ri235igiIg/ApEqh+OPdOrZsVMxWUiW3dIutskSkFEyqFIrXGWWzN3GR+vNWUkMVT3UiUgrOqK5QjnYHncvIwfoTafDWqNC3TQQa1AyQKDJbeHmsiErlmoTZ1kB1ueEPCCJSCiZVCuXIhebAxdsY+u1e5BWVzFW0cOsF/PLK3WgSGiRRdCQ16fMK5WRVvPuPiJSC3X9V0FdbLxgTKgC4nVuEpUkX3RgRlbKW6kjdWsOWKiIi6TGpqoI2nEw32+ZJSZWSr8EqK4OdpG6tCfb3lnR/zqTkz5OIqhYmVQrFX++eyVUNSApqqOK5TkSKwaRKoZQ4zoQXRwdIXHe2dncxR24pF08cIlIGJlUKxQTFM1n9WF2Y5/x8QYP9F++47oBERB6CSRVVSkZ2AY5fzYLeIL/szpmTRd7KKcQv+y5j8c4UXL6d57TjlOfqBZB/3nfFpcezhT8giEgpOKWCQrnrOiMIAmb8dQJL/jewvUFNfyx74W43ReNaVzPz8dTCJFzNzAcAfLThjOTHkMvs4SuPXMcng9wdRQmZVAkRUYWYVCmUuy6+m05nGBMqALh8Ox9vrDzmllhc7Yeki8aECgByCosrvS/rd/lZK1+54xTo9Nhx9ibO38jBXdE10bFhSOV25EZKHD9IRFUTkyqFctdlxlLrzPazN90Qiest3Hre3SHYpUCnx4tL9mPHuX8/nwm9m+G1Xk0V1fqjpFiJqGrjmCqFcteF5tR1baVfy2tjxaT8XLckZ5gkVAAwP/EstAU66Q7iAjxviEgpmFSRx1HCRdje7tvK9P79dsB8sLneIOD4laxK7M19DGyqIiKFYFKlVLzOKNq1zAK7yldmTFXqLct3JxbL8I5NW/44eNWld1oSEVUWkyqF4uBdZbuRU+jmCJR1/vz3z6pxMwQRKZtDSdXPP/8MnU5Z4zM8BXtElM3+7j/7m6rkMj2DFLafvQmDwlrYiKjqcSipGjRoEOrVq4f//Oc/OH36tFQxkQhKvLz8sv+yu0MgVH56BndT4jlPRFWLQ0nVm2++CT8/P8ybNw+tW7fG/fffjx9++AEFBfaNF6GqYUvyDZccx4MaaDweW5+IyJM4lFTNmjULqamp+Pvvv/HII49g9+7dGDFiBCIiIvDqq6/iyJEjUsVJ5Si1a+eWm8cSFRYbsOfCLRy/mqWoC7qUrUtyOnWSLtwSXVap5zwRVR0OD1RXq9Xo378//vzzT1y5cgXvvfce6tSpgwULFqBjx47o0qULFi1ahJycHCnipf9R6uXF3XlM/PwdePrr3Xjosx0Y9M1u5DowK7orSd1jJ5f85PwNfi8QkeeQ9O6/0NBQTJ48GWfOnMH69esRERGBAwcO4JVXXkHdunXxf//3f7h48WLFOxJhy5YtUKlUFv/bt2+fsdzRo0fRrVs3+Pn5oUGDBvjwww/N9vXrr7+iRYsW8PPzQ9u2bbF27VqT5wVBwLRp0xAREQF/f3/ExcXh7NmzkryPypLLRVFprpaZymBPym38sFua81FJ5DSmyp7zmKc8Ecmd5FMqnDx5EuPHj8fgwYNx7do1BAQEYMiQIYiKisLChQvRqlUr/PPPPw4f55577sH169dN/nvxxRcRHR2Nzp07AwC0Wi369OmDyMhIHDhwAHPmzMGMGTPw9ddfG/eza9cuDBo0CC+88AIOHTqEgQMHYuDAgTh+/LixzIcffohPP/0UCxcuxJ49e1CtWjXEx8e7dewYp1SwwY6q+WWfQgbPyykTIiIiiyRZ+y8/Px8rVqzAN998gz179kAQBMTExGDWrFl49tlnERQUBAD4559/MGLECEyePBl9+/Z16Jg+Pj4IDw83PtbpdFi1ahVeffVV42K1y5YtQ1FREb777jv4+PigdevWOHz4MObNm4eXX34ZADB//nw8+OCDmDRpEgDg7bffRkJCAj7//HMsXLgQgiDgk08+wZtvvokBAwYAAJYuXYqwsDCsXLkSzzzzjMX4CgsLUVj47/ghrVZrjFOKaSiKddJ3W1mLSxAEnMvIRZ0gX4ePoS/WQadz7vRoumLx9XvhZq7tfUk4ZUjZfdnb0mjQ6+2OxdoYpOJiPXTFFZ8/rpguRa/Xiy5bVKQDvOQxtV5p3XBKGdtYT+KwnsRxVz3ZczyHkqr9+/dj0aJFWLFiBbKzs+Hn54dhw4Zh5MiR6Nq1q1n5vn374oUXXsBHH33kyGEt+uuvv3Dr1i0899xzxm1JSUm4//774ePjY9wWHx+PDz74AHfu3EFISAiSkpIwYcIEk33Fx8dj5cqVAICUlBSkpaUhLi7O+Hz16tXRtWtXJCUlWU2qZs+ejZkzZ5pt37BhAwICAhx5qwCArCJA6vWwy3d7AsDtQuCLkxrcKFBBBQGOju7ZmJiIIG+HdlGhvGJAqroxrRPH9ll2X0U6Deypy3PnzmFtofli1rbk5Fg+xr69exHsI6Ci92PpfJDaiesqABpRZdetWyeXnMooISHB3SEoAutJHNaTOK6up7w88Ss6OHSV6NKlCwCgVatWeOWVVzBs2DBUr17d5msaNmyIevXqOXJYi7799lvEx8ejfv36xm1paWmIjo42KRcWFmZ8LiQkBGlpacZtZcukpaUZy5V9naUylkydOtUkWdNqtWjQoAH69OmD4ODgSrxDU+naAkw7sM3h/ZTVr18/s23PLzmAGwUld2gJEgyXjuvVC7UCHW/xsiUrX4ep+zZLsq+ydTI2aYNk+5p+eDPy7GhRa9q0Cfr1bGLX8eaf3YGMAvMvgy5duyA00BfvH9ll8/WWzgep3dx9Cb+nipvjLv7BB+Erk6xKp9MhISEBvXv3hre3k38lKBjrSRzWkzjuqqfSniYxHEqqhgwZgldeeQX33Xef6NeMHDkSI0eOtPr8lClT8MEHH9jcx6lTp9CiRQvj4ytXrmD9+vX45ZdfRMfhbL6+vvD1NU8evL29JTkZvLzEd5uIZSmu7efE3/IuhpdE798WbwlbhqWM1WRfduanarXG/lisjMPSaDTw8q74T98VX1oatfgkycvLC97e4lq1XEWqv2dPx3oSh/UkjqvryZ5jOZRU/fDDD4683KKJEydixIgRNss0atTI5PH333+PWrVq4ZFHHjHZHh4ejvT0dJNtpY9Lx2NZK1P2+dJtERERJmXat28v7k05AQeqW+eJdcNx6kRE8iftoBwJ1KlTB3Xq1BFdXhAEfP/99xg2bJhZNhkbG4s33ngDOp3O+FxCQgKaN2+OkJAQY5nExESMGzfO+LqEhATExsYCAKKjoxEeHo7ExERjEqXVarFnzx6MGjXKgXdKVZm9A9Wtrf13M6cQaVkFaBkRDI1aXOZVmXUEiYioYg4lVeVbjCxRq9UIDg5G8+bN8eijj+Kpp55y5JBmNm3ahJSUFLz44otmzw0ePBgzZ87ECy+8gMmTJ+P48eOYP38+Pv74Y2OZsWPHonv37pg7dy769++PFStWYP/+/cZpF1QqFcaNG4d33nkHTZs2RXR0NN566y3UrVsXAwcOlPS92IPzVClboK8XsvIr308pCALeXXMKi3akAADq1fDHshe7Iqp2NZGvr/ShJWVPGHKJmYjIGodGfRoMBhQVFSE1NRWpqam4cuUKCgoKcOXKFeO2goICnDt3Dj///DMGDRqEPn36oKioSKr48e233+Kee+4xGWNVqnr16tiwYQNSUlLQqVMnTJw4EdOmTTNOpwCUzHf1008/4euvv0a7du3w22+/YeXKlWjTpo2xzOuvv45XX30VL7/8Mu666y7k5ORg3bp18PPzk+x92MsV1xcuC+I8D8VEVFyojPLdf9vO3jQmVABwNTMf//3zmGkhBXx8xXoFBElEJJJDSdXhw4cRERGBnj17YteuXSgsLMS1a9dQWFiIXbt2oVevXqhbty4uXbqEM2fOoF+/fkhMTMTcuXOlih8//fQTdu7cafX5mJgYbN++3ZjsTZ482azMk08+ieTkZBQWFuL48eNmdz2pVCrMmjULaWlpKCgowMaNG9GsWTPJ3kNlKDXhcUXHk1RVI7I3rVKq+TrW8z4vwXx6hV3nb0EvYh0gOY3Pyi0SP9+aJ46VIyLP4lBSNXnyZBQWFmLDhg24++67jZNuqlQq3H333Vi3bh0KCgowZcoUNGnSBL/++isiIyOxYsUKSYKvyhSaUymKM6vY0bzmyOVMi9vFJNtyOnfsWdRaTnETEVniUFK1atUq9OvXD2ort0VrNBr069cPq1atAgD4+fmhZ8+eOHfunCOHJapyJF9QWSatPnpmSkTkQRxKqrRabYWTYmVlZSErK8v4uHbt2o4cklyI1zv5ENtlJ+Yjk1P3n94gvixPRyKSO4eSqlatWmH58uW4cOGCxecvXLiAFStWoFWrVsZtly5dsmvKBLKMCY/zyamOj13NQtf3NuLu9xKxN+W21XJyilkMpY4NJCKyxKHRsv/973/xxBNPoH379njxxRdx7733IjQ0FBkZGdi5cye+/fZb5OTk4L///S8AoKioCBs2bECfPn0kCb4qk0v3jRx5Ys2sP/HvBLVPfZVktZzSzgsxA+tLMQEjIrlzKKl67LHHsGjRIowbNw6ffPIJ5s+fb3xOEAQEBgbiq6++wmOPPQagZFHCb7/9Fq1bt3YsalJciwS5nhJOEXvGVCnh/RBR1ebwjOrPP/88Hn/8caxatQpHjhyBVqtFcHAw2rVrhwEDBpgssFyjRg0MGDDA0UOSi/AipjxichRBkE9SXt2f65wRkedwKKmaNWsWoqOjMXToUAwbNkyqmEgEZ18Td5y9iR92p0q+X5WcRkl7OCXUdKuIYNFl5ZIIEhFZ49BA9XfeeQfHjh2ruCBJzpnjS3ZfuIUR3+81GcdD0rqTV/klamwpe1ooIQexK0YlvCEiqtIcSqoaNmyIzMxMiUIhezjz+vLHwSsotmMAsT1cMdhYymM4I94jlzPx3c6UigtWARx8TkSexKGk6plnnsG6detM5qEi13DmteiX/Vect3PCO2tOOm3fYu/+k0suY08cSruzkYiqHoeSqrfeegsxMTHo2bMn1qxZg4yMDKniIg/FMVXAvtQ7Ttu3XJIlsRQWLhGRTQ4NVA8ICABQ0oT/yCOPWC2nUqlQXCx+4VQSg5cjVxAEaWcgv5lTKN3OLCh7Viiha82ulir5vx0iquIcSqq6devGlgc34QXGOjlXzQYnD/4XtaCyjGrIwHmqiMiDOJRUbdmyRaIwyF5KvcBU9RQ86cItlx1LCT94lHoeExFZ4tCYKnIftlS5htTVrHFyniO2+08urVVFxeJXVFZCdyYRVW0Oz6gOlKzpt3HjRpw+fRq5ubl46623AAAFBQXQarWoXbs21Grmb1S1ZWQXQO3k1iOl5R17XNhyR0TkbA4nVX/99Rdefvll3LhxA4IgQKVSGZOqo0ePIjY2Fj/88AMGDx7scLD0L7m0NJB4Xd5NdP5BFHZa7DovPqlS2FsjoirIoeajnTt34oknnoCvry/mz59vljh16dIFTZo0we+//+5QkGROaS0SriRl3bDLybnua1JbdFl+FEQkdw61VL399tuoUaMGDhw4gNq1a+PWLfNfnZ07d8aePXscOQxZwAsMWSKmBVNOCyo3Dq3m7hCIiCTjUEvVnj17MGDAANSubf3XZoMGDZCWlubIYYhIJLkkS2LZsxoSu7yJSO4cSqoKCwsRHGx7lfnMzEwOUncCXmBcQ2m1rLR47ZmniohI7hzKdho1aoR9+/bZLJOUlIQWLVo4chiyQKnXIldMncSEs4TUtVCsFz/9gVh2ncf8WIlI5hxKqh5//HHs3LkT33//vcXnP/roIxw/fhxPP/20I4chcrvCYr27QxDFGQPrT1zLwkOfbUfzt9ZhwIKdOJeRI9m+DXb0/zGnIiK5cyipmjRpElq2bIkXX3wRvXv3RmJiyS3jr7/+Orp164bJkyejffv2GDNmjCTB0r+U2lKltLhL41VK3FKHWVisx9Bv9+L4VS30BgFHLmdi2Ld77EqGbJFoN0REsuBQUhUYGIjt27fjmWeewZYtW7Bjxw4IgoCPPvoIu3btwlNPPYWNGzfC19dXqniJyAYxyZ89ecyW5Bu4nVtksu1aVgF2SzRpp96etf+YgBGRzDk8+WdISAiWLVuGTz/9FPv27cPt27cRHByMu+66C2FhYVLESBYoddyQApajM6HUepbK5tMZFrfvvnAL99gxx5Q19nRXVvXPgojkT5JlagCgVq1aePDBB6XaHVXAWb/adU4YjOxyVfjaK3XioVFbzoLtaWGyhXf/EZEn4VwHCuWsS9Gp61on7VnZFHPtFxmn2PfjZSWpKnbDmCrFfAZEVGU53FJ18uRJfP7559i3bx8yMzOh15vfJaVSqXD+/HlHD0VlOGv5FF64TCmtPsqGK0XsamstVXq2VBERledQUrV161Y8+OCDKCwshJeXF8LCwuDlZb5Lrp+mHM4e86SCwgZV/U9VHc/j7JYqe74aquYnQERK4lBSNWXKFBQXF2PRokUYPnw4NBqNVHFRBWLq18CxGX1w8poWT3+9293hyEpVvvhK/ftF5eQsW2/PPFX8cUZEMudQUnXkyBE888wzeP7556WKh0TSqFUI8vNGoJ9k9xq4RFVt8XEVcQsqy+czOHI5090hEBFJxqErcrVq1RAaGipVLFQJUnenKbV7ztlklIfYJCbOaatOWO3Wc7X9F++ILquUz4CIqi6Hkqp+/fph+/btUsVClaC0eZ/I/S7dznN3CEREHsmhKRXmzJmDzMxMvPbaa8jL4xe1J6hsklYnyDNnzTcuU+PeMESTOk7m7ERE4jnUUvXMM88gMDAQCxYswOLFi9GsWTMEBweblVOpVMZ1AUlacmmpklPXjJxicbWy46UcHb8m1fp+UqnKnysRKYNDSdWWLVuM/87JycHBgwctlnP2HUREVELKxGP/xTuKaaEjIpIDh5Iqg8EDljRROA4sd67S1h453THnKnfyiiou5EK8c5SI5M7py9QUFRVBq+XSJ56PFzxPIwjyGlNVBfNaIlIYu5OqRo0a4dNPPzXZtn79ekyYMMFi+dmzZyMkJKRy0VGF5NKzKvaCp9QLo1LClrZ+lfKuiYjkwe6kKjU1FZmZmSbbdu/ejfnz50sVE7lRZZM0OV1+pewmUloS6MnvXWbhEBGZcXr3HzmXTBqqquSYo6qMnzcRkTkmVeRRtAU6DP12r+T7VUoOUTZOR2OW21tmIkdEcsekSuGkHlNV2bsJ5XK5m/nXSZzLyJFsf3J5X2JJGa+tHMYd06Qo7bMgoqqHSRVJQi6NCL8fvOLuENyqbGuOXG5iICKqKphUKZ7ECypXcndZ+TpJ45AdmSSNFSkbpuPdf9Z34I6uOEEAbuYUshuQiGSrUpN//vjjj9i9e7fx8blz5wCULLBcXulzRIBichOjqnwBFwTI504IAHHztgIA6lb3wyfPdECX6JpujoiIyFSlkqpz585ZTJbWrVtnsTyXqXEeVq1rKGU2bylzQLm+42tZBXh+8T7sfzMOft4ad4dDRGRkd1KVkpLijDhIJpikUSk5t9LlFBZj46l0PBRT192hEBEZ2Z1URUZGOiMOqiTmQM4l37SiYjLOiSSxP/UOkyoikhWHFlQmqiqUk6C4N9ACnR5/HLyK5DQtOkfVxEMxEU7r/vdS8ycFEckLkyqFk/qCVdl5qkh+HD017E0kDQYBr/xwAFvP3AAALEm6iCOXM/HmQ60cC8QKjYbnKhHJC6dUILKhNLFQSkOVtDOq27eDk9e1xoSq1JKkVOQWFjsWiBVsqSIiuWFSpXC8rJCz2ErKLD21YLP5HcE6vYCEk+nSBVWGl5pfX0QkL+z+UzjJl6lxcpYm5zvKyNSEX47YVT7HSotUUbFBinDMsKWKiOSGP/UUTuoxULxMlVPa/aeQZFCOUTprji8vDb++iEhe+K2kcJxXitzB0mln7aYJa/moo4mqNweqE5HMMKlSODW7QFxCji1A7mRPfVgrm3orz6EYGtQMcOj1RERSU3RSdebMGQwYMAC1a9dGcHAw7rvvPmzevNmkzKVLl9C/f38EBAQgNDQUkyZNQnGx6diPLVu2oGPHjvD19UWTJk2wePFis2MtWLAAUVFR8PPzQ9euXbF3715nvjXRqkpKlVNYjBl/ncAjn+/A5N+OIkNb4JLjKmV5mlLu7KW091zcVu5OQXupVSocvZKJ//x6BC8t3Y+/jlyzWE4QBOj04sZ1ObOb98fdF9F3/nY8+Mk2/JCU6rTjEJH7KHqg+kMPPYSmTZti06ZN8Pf3xyeffIKHHnoI58+fR3h4OPR6Pfr374/w8HDs2rUL169fx7Bhw+Dt7Y333nsPQMmyO/3798fIkSOxbNkyJCYm4sUXX0RERATi4+MBAD///DMmTJiAhQsXomvXrvjkk08QHx+P5ORkhIaGurMKoJZ6niqZZmkvL92PXedvAQCOXsnCvou3sWHc/RxXIyPWzh1reYrBwQTmTHo2xq04hNwiPQAg4WQ6Cor0eOquBsYyK/ZewvzEs7iTV4S4lmGY80Q7+PuYrxd4+HImpq86jjPpOegSXRNznohBaLCfQ/GVterwVby58rjx8VurTiDIzxsDO9ST7BhE5H6KvSLdvHkTZ8+exZQpUxATE4OmTZvi/fffR15eHo4fL/ny2rBhA06ePIkff/wR7du3R9++ffH2229jwYIFKCoqAgAsXLgQ0dHRmDt3Llq2bIkxY8bgiSeewMcff2w81rx58/DSSy/hueeeQ6tWrbBw4UIEBATgu+++c8t7L6sq9P5dvp1nTKhKXbiRi72pt10Wg0LGqbusZc1SfVg7Fa3F5Gid/nX4mjGhKvXT3kvGf+9LvY0pfxzD9awCFOgMWH30Omb8dcJsP1l5OgxdtAdHrmQhX6fH1jM38NLS/Y4FV85XWy+Yb9tmvo2IlE2xLVW1atVC8+bNsXTpUmPX3VdffYXQ0FB06tQJAJCUlIS2bdsiLCzM+Lr4+HiMGjUKJ06cQIcOHZCUlIS4uDiTfcfHx2PcuHEAgKKiIhw4cABTp041Pq9WqxEXF4ekpCSr8RUWFqKwsND4WKvVAgB0Oh10Op3D779U+a5MR5TE5pyJGk2PYV8uv+645W6dxTtTcFfD6lKEZVWRTgedToXiYuk+M2cq1hUbzy9ndmUZDAaz89hay1Nxsd7iOV+s11soLV5yerbZtsOXM43HWrTtvNnzP++/jHcGtDTZ9uehy8guNx3EkStZOJeehUgr47ZKjyH2b/nkda3ZtlPXtZJ+F8iRvfVUVbGexHFXPdlzPMUmVSqVChs3bsTAgQMRFBQEtVqN0NBQrFu3DiEhIQCAtLQ0k4QKgPFxWlqazTJarRb5+fm4c+cO9Hq9xTKnT5+2Gt/s2bMxc+ZMs+0bNmxAQIB0A2yzdYBUH+PatWuRni/d/izZmJiIIG/7XnPyugqAeZdNWloa1q5dW26rtLFvTNiIat6Atkj6fTvD9u3bcb5ayb/z8jVw1qi7SxcvYu3aFJNtNzLUsNT4ffz4cay9ecxs+8lrlj9XR5WeE+tPWv68yp8zi49Zrqcf12xFh1q2E9OEhASRUYmLxVOJr6eqjfUkjqvrKS9P/E01srtKTJkyBR988IHNMqdOnULz5s0xevRohIaGYvv27fD398eiRYvw8MMPY9++fYiIiHBRxJZNnToVEyZMMD7WarVo0KAB+vTpg+DgYMmOczu3CG/u3yLJvvr164fzN3Lx3uGdkuzPkrhevVAr0Neu19xIuog/U5PNtoeFhaNfv/Ym28YmbXAkPDNxveMQEuCDG9mFeOvAVkn37Qz3deuGFuFBAID3T25DZpFzBvRHRkWiXz/TFp+Vtw/iZOZNs7KtW7dGv64NzbZf35kKXDwjeWz9+vUDYP1c6Nu3r8n0D99f2QPkZJmV69ihA/q2Cbe4D51Oh4SEBPTu3Rve3hX/SrAWS2msnsreeqqqWE/iuKueSnuaxJBdUjVx4kSMGDHCZplGjRph06ZNWL16Ne7cuWNMUr744gskJCRgyZIlmDJlCsLDw83u0ktPL1kyIzw83Pj/0m1lywQHB8Pf3x8ajQYajcZimdJ9WOLr6wtfX/PkwdvbW9KTwcdbui4eb29veHk595TwqsT712gst2aoVCqn/2F5eZXEe/GO+D8qd/Ly8jLWidQ3MZSlUqnN6l5jZdkYjUZj8XNSO2mZmYrOCY2XNzRlBiNam19LbSXu8sdy5BysKhdQqb/3PBXrSRxX15M9x5JdUlWnTh3UqVOnwnKlzXHlv5jVajUMhpLbp2NjY/Huu+8iIyPDeJdeQkICgoOD0apVK2OZ8k3wCQkJiI2NBQD4+PigU6dOSExMxMCBAwGUjCdJTEzEmDFjKv9GJVIV7v6TQ0g/77tUcaEqz8rkn1ZKu2vwf7HBAI3630RdDucXEXkGxd79Fxsbi5CQEAwfPhxHjhzBmTNnMGnSJOMUCQDQp08ftGrVCkOHDsWRI0ewfv16vPnmmxg9erSxFWnkyJG4cOECXn/9dZw+fRpffPEFfvnlF4wfP954rAkTJuCbb77BkiVLcOrUKYwaNQq5ubl47rnn3PLey1JJ/AnyAmPZysOWB8vLTdlExdVL6+RbucnB6ozqTozFFr1B3JGVcscnEcmH7FqqxKpduzbWrVuHN954Az179oROp0Pr1q2xatUqtGvXDkBJt8Pq1asxatQoxMbGolq1ahg+fDhmzZpl3E90dDTWrFmD8ePHY/78+ahfvz4WLVpknKMKAJ5++mncuHED06ZNQ1paGtq3b49169aZDV53B2d28cidK655Slnzz50EQcA7a05h57lbVp+3xNF5qipLbFJFRGQvxSZVANC5c2esX7/eZpnIyMgK77Dp0aMHDh06ZLPMmDFjZNHdV17VTalILv46cg3f7kix+rzcuv+YVBGRsyi2+49KKK2lqjIXUnsX6q3K3LGszofrzO/MLMtZCypXVnG5pMra+UVEZC8mVQrH64FzMW+r2NXM/Eq9ji1VRORpFN39R9InVUq93AiCYLZkSVUkx9Y7q91/Lo3iX+VbqqyRYVUSkcwxqVI4pXX/OUPiqXS8tfI4rmU5Z6JLMmdPN6PsBqrrmS4RkXMwqVK4qpBUWX+LAtKyCjDyxwPQOelCKceWH7HkHro756kicYqKDTh06Q6C/b3RIjyI48+IKsCkSuGk/oqTYxJh7T0KArB87yWnJVRknUqCM89dA9XLj6limmDZlTt5GPTNbly+XTJm7oHmdfDls53g5y39eo1EnoID1RWuKvxw3H7WfD25UquPKmNSzqrMXZN/WvvbyMguFPX6qj5H2Qfrko0JFQBsTr6B3w9ecWNERPLHpErhlNYcb+8t/2fTs7HhZHrFBZ3EHVMUKIE99WJtYLizcxZr+zefUsG5cSjV30fMf7C8ufK4GyIhUg4mVR4g2M9ze3GX773s7hAURY6NK39ZuDgDzk9YA3ysLMRdPg4Z1pmjMvOK8MG60xjx/V58lngWhcXS3BnriXVFJCUmVR7glfujJdybc781M/N0dpX/bqftmbqL9M4ddHw9k3cUOkpn5TNy9nRRAT6Wf2x4el5QrDdg6Ld78eWW89iSfANzE85g3IrD7g6LqEpgUuUBHo6JcHcIovWdvx2pN3Ml21/ZMR/OsOFkmlP3XxXUDPCxuN1drR7lx0p5Wvff0atZOHY1y2TbP8fTcEPkWDIiqjwmVeRSeoOAHh9tQb/52/HS0v04fDmz0vtyxUDiBZvPO/0YUirbpSabrhorSYuzu/+sJUtyqRZn+Xa75dbdNbypg8jpmFSRW5y8rkXCyXQM+3aPpC1XpCBOzm6sT8VRfkoFz2qqspasnrqe7eJIiKoeJlVkwtWtG9qCYqzYJ9/B6D4aZf2JyKZ1SgRnz6hutaVKQXVUGd5Wztk9KbdcHAlR1aOsKwZ5pIVbK9fF5opr48Pt6rrgKM4h9+kg3Demyj3HdZVmYUEWt4dUszy2jYikw6TKA3jaQFs5qe7v7e4QKs2Zd9dJkZg4++4/a916Hp5TIaK6n8Xtnp5MEskBkyoyIafv3Yxs29MZ8CJhrmyVyL1+3DVQXWy3o9zrz15VfYZ4Ilfw3Fkjq5CaAT7wUQsoMjjeZHVTRrddfyGDO+/k3oVmizMvolK0jjr7Gm9rzUhRBe2UoS3A55vP4cQ1LWLqV8fYXk1Rw8p0Es7krmWBiIhJlUfw8VIjNlTA1jTHrg65hcUYvGiPRFE5bvGuVHeHoGjOHggud9aXcBLZUmVHGlKg0+OZr3fjwv/uZD1w8Q72pd7GX6Pvg1rt2v55a1HbczoccWCqE6KqjN1/HmJglAFv9Gvu0D64WKo5peUlZVunnBm6NGOq3FO5zjjs/tQ7xoSq1PGrWpy4ppX+YJVkT5L4w+6LToyEyHMxqfIQahUwIjYSA9pX/m616X+dkDAi+1y+nWf3axSW77icXBJC0d1wLuKMAfKrrUysufVMhvQHq4C1bl976vu3A/yBRVQZTKrIyJ0X4SWV6OrjwFtzAkrqpVhvkE33n9XuKLfNqF5+8k/H6fSW34uz73AsL79Ij4OXMi0+J5PTgcijcUyVh1HqF2fSBXlOTKi0xO3b7SnYm3ob+UV65BQWuzscm5w+UN2Fk3/K4YaGo1cyMeL7fbidW2TxefdHSOT5mFQR2aC0C9GaY9fdHYIZay1B7pqnylOnVJj8+zGrCRWgvB8IRErE7j9SrO1nb7o7BHIAL/LS0RbocOq6fAbFE1VVTKpIFuR6fZVrXJ7Ak7r/rMYA1ySPRcWGCsvwXCZyPiZVRGQ3Ka7PTh+oLvK4zl7mqdgFo9XFJExyuXGByJMxqSKyQQ4DkJXOWtJSt4a/xe3BftIM9bQ2+aeh4kYdANK17Oj0Ig/oZPa8nbb1qlvc7ufNSwaRLfwLIVmQa+rCH/eOs1aH1harHnJ3pBOjMT/XrA1ol8qtHOuDx13Jnm7IelYS3h7NQqUKh8gj8e4/IhuW7bmEFhHB7g5DdqRIQ6z1ijWsGSDB3m1NOmp6YElaI23sorBY7/j+Kzx8xe/BnndZbKU5z9ldpURKx5YqD8OGFem9tfK4u0OQHXvOM+sDxi3vRbKl8qxO/uk6KhVQVCyTv0o7wth4yvJM8K5quTW4etZUIomwpYqIZMXZ3XHlkzlnH89aq4+kROQgYtOUWzmFDoXiiHXHr+PDdclI0xage7M6+OCJGAT7We4mJpIjJlVE5BbWWj2k6mJydM1BqdpKrC1h42op5RZ8tuZcRo6TI7HsTHo2xvx0yHi35D/H06BWqbBgSEe3xENUGez+I1nQu+LXPLnF0StZFrdbGwekliirsnb3n9lAdQkOZyttupFd4PgBXMgVU0BYsvl0htmx1xy7jvwi549JI5IKkyqShZsyuUOKpJdXpLc427e1a7daom8l68vjiF2mRprk4q8j1yTZjy1SpkG2poBw5hQjc9YnW9yenJ7ttGMSSY1JFcmCXObyIedYefiq2Tar3X9OH1Ml/T5tRbzznDwXC7em2E3dldZayDLz+IOLlINJlYdR6npqet7t49G+2nrBbJu1FiONRLf/Wb3rUPTrxcdhbZ8qlQoR1f1E76eypPyzd8nAegvqWqknhX6lURXFpIpkwV3jOMh9rCXSXlIlVVbnVHBt91/7BjUk2Y+rFLmppSqId/mRB2BSRbLAeWmURYp8I6ew2OJ2Z7dUlT/VnD2hpdJaWhJPpVt9TmnvhcjVmFSRLJRvqdp+9oabIpFGt6a13R2CrGXl6fD1NvMuQUC6pMoasS1QUuUPrlg/Uspj5BRYTnbdhrO4k4IwqSLZSb2ZixeW7Hd3GA6Z/VhbRNaSZrkVT/T7wStWn3M0qapo8kpnpDi2EjWlNcLWCvRxdwhEisXJPz2Mr5fG3SE4LOFkOoqKlX03YP2QAGz5Tw+cv5GLuHlb3R2O5BztMvtuZ4rV5xxNqjq9sxED2te1OhDe1V1YYqdwcISUh7CVBDrznVhtbVNYUkpVG1uqPEzXRjXdHYLDVh91/rw+rqBSqdAkNBChQb7uDkVyjl7Er9zJt/qct8bxr6VVh6/hTLrlmcENggC9QUByWjZyC4sVOYWDM7kiCbSHK7pPiaTClioPc1eU8pMqTzOqR2PM/Puku8NQDGcPoTl1PRuxsxORkV0Ib43K6cvIKG2aE7ndNKKw6qMqji1VHia6djUM6tLQ3WFQGfc05qB1sbo3q2PX/FCV8fvBK8jILhl3ZTOhkuhi7oocRewhxCR4MsupZBcPkS1MqjzQe4+2cXcIVIbculPItax9/lLNx2UPMQmKrfPVHaey0lr6qGpjUuWBnP1Ln+zDpKrEyWtaUTPne9rpa+3jLzYIOHw5U6JjSDehaYFOXgsY86+HlIRJFZGTRVT3d3cIstDv0+145PMduGljygOVSpnTEllfpsb2QOtXftjv0paY7WdvVlhm46kMF0Ri7qqVmxf4m4SUhEkVyY+HNVXUrMZ5f0qduKbFp4ln3R2GKFLddWZrKb10bSFOXtdKchwxnlu8D9/bmM7CXW5kFyK3yFoLGbMqUg4mVUQu8OHjMe4OQTaWJl20+byH5dQVdv9maG1PViqGPa05Czafc+AOP+ckOP8cv279iMypSEGYVBG5QFh1P3eHIDFe6cSqMH9xcRJ5M6cIZzKyXXvQCiTa6HLk3X+kJEyqSBbiWoa59Hg1ArxdejxHbvSq5qP8WfLFKmmV8LCmqgoSULUbmuay8nRO2e+5jBwsTUrF5uQMu1ZFsFWWk3+SknDyT5KF5uGBLj2eqy9k7rhwKpUSq8pWF1VFLS2lCbfBIOBsRg58vNSIqhXg1Lt4S+fpktLaY9fx6vJDxjs841qG4tOnHe/2ZvcfKQmTKqqSnHnH1cTezcy2OXJ55BQZ7lHRKZJZCOw6fwudom1P7lrRmCq1SoVzGdkY/t0+XM0suQPurqgQfDW0s9NucqjsUkDW3oogCPi/ZQdNtm08lYE9KXcqdRyTfTu8ByLXYVJFslD6ZW0wCMgucE7XhKv0aR1uto2JkTgClNH5t2DLBXxy0As4eAB+3moE+lruTlZBVWFLlQrA+J+PGBMqANiXegfzEpLxzsC2ouKR6jdCZX9sWJuqYW7CWbwUafu1eoOApAu3JI+JyB04popkQQCw6vBV3PXuRly4keuS4zlLRA3zQelumDxbseSSgFo7R85lZOOTxHPGxwU6g825typKCvKK9Dh2Ncts+y/7r4iKs3JMYyrQ6bHtzA2sOWb9Ljxblu2xfEdnys2K/5bnK2SKDSIx2FJFspByIxdfbT3vsjt9nPnj11JKoHYgq5JHikGlvtlm3zxPFc0iX6S3PEjbnoHejgzmzsrXYdh3e3HEgdnd159It7hdTIK8bLftKTa4IgEpCVuqSBbWnUjzmFunLV1IHGmpkmO1OOs6JwiCbJJIa3HYu7TMrvPWu7bk4Nf9l0UnVPZ+7GXPe4NBQL6FCT5v5RbZPqYc/wCIrGBLFVVJ9rQC2MvyxVguqQKJ5aprefkB3q72zppTTtt36V2vP+29jE83nUdWvg7dm9XBJ8+0R5CfuGlNmFSRkrCliqqkfCcuGmupx8ORlio5pmPOHPYkkyFV+Od4GqatOo6lSakmN0/YE59KBdR1wcSvl29bXjfP3VQq4IIWmP73KdzKLUKxQUDi6Qy8ufK46H0wpyIlUXRSdfDgQfTu3Rs1atRArVq18PLLLyMnJ8ekzKVLl9C/f38EBAQgNDQUkyZNQnFxsUmZLVu2oGPHjvD19UWTJk2wePFis2MtWLAAUVFR8PPzQ9euXbF3715nvjVSMJWFNEjDkeqiWao/d9h25gaWJl3EtFUnMOy7vSioZCLuaFIgCAIOXbqDpUmpVrvpnv12j4NHcQ61SoXEa+aXmVWHrwEANp+uePFm3v1HSqLYpOratWuIi4tDkyZNsGfPHqxbtw4nTpzAiBEjjGX0ej369++PoqIi7Nq1C0uWLMHixYsxbdo0Y5mUlBT0798fDzzwAA4fPoxx48bhxRdfxPr1641lfv75Z0yYMAHTp0/HwYMH0a5dO8THxyMjwz2ruZO8WWrJCA92oLVCHjmGiap2nTt0KdPmbf+2OFJXn286i+ipa/HoF7swbdUJDFiwE/M3SnG3XOVOKksJzv7U21bLq1XA8TuWLzMpN3PxwpJ9FR9TfHhEbqfYMVWrV6+Gt7c3FixYALW65I924cKFiImJwblz59CkSRNs2LABJ0+exMaNGxEWFob27dvj7bffxuTJkzFjxgz4+Phg4cKFiI6Oxty5cwEALVu2xI4dO/Dxxx8jPj4eADBv3jy89NJLeO6554zHWbNmDb777jtMmTLFYnyFhYUoLPz3NmuttmQlep1OB51O2nmYSvcn9X4dEVUrAKm38twdhlsU63TQwXTMlkpw3hgudzAYDE453wRBgF5fXHFBN1iyMwX3NQqB3iD+s9Tr9Q61tHy04YzZtk8Sz2DwXfUcWmqpuLgYOp0OX2+3705GgyCYfe7LdqdaLW+rq3T98Wuibk4pjdWTyfE7XI7cVU/2HE+xSVVhYSF8fHyMCRUA+Pv7AwB27NiBJk2aICkpCW3btkVY2L/rysXHx2PUqFE4ceIEOnTogKSkJMTFxZnsOz4+HuPGjQMAFBUV4cCBA5g6darxebVajbi4OCQlJVmNb/bs2Zg5c6bZ9g0bNiAgIKBS77kiCQkJZR6596MtyMtFjwgBW67LszFUBQHOus9s/fr18Cr3tgv1QGU/k2KdDnJrrrp8+TLWri29FV66c+3GjRvYsSNd0n1K5dTlG1i7di1uZ2kg9vNIPn0a+QVq0eXFEATgnZ82omfdshmJffV18OBB3DwjYM5B+153IyMDa9euNdn252Hr+ygqLIS19/791mSrz5V19OgxVEs/ak+YimX6HU7WuLqe8vLENxDI75tLpJ49e2LChAmYM2cOxo4di9zcXGOr0fXrJRPYpaWlmSRUAIyP09LSbJbRarXIz8/HnTt3oNfrLZY5ffq01fimTp2KCRMmGB9rtVo0aNAAffr0QXBwcCXftWU6nQ4JCQno3bs3vL1Lfr2mBlzAx2UmKHS1oKBAtG4ehi3XL7gtBls6RYZg/8VMp+z7wQcfhE+5rKpYb8DrezdWan91qgfgkswGIjdo0AD9+rUGAIxN2iDZfmvXroP77muKj47tlmyfUgkMDES/fvfi/ZPbgMICUa9p3LQ5dt+5DK1O2rX2atdvhH4PNjc+tvcz6NixI9766yQA+37x16kTin79Oppss3VsPz8/oMjye0/PF5dotmnbFv061xcfpAJZ+g4nc+6qp9KeJjFkl1RNmTIFH3zwgc0yp06dQuvWrbFkyRJMmDABU6dOhUajwWuvvYawsDCT1it38fX1ha+vr9l2b29vp50MZfc9umdTtyZVKpVKFp+DNWqV82Lz8fE2W1vNkY98+D3ReHv1SQejkpZarXbKeaxWq+DtLbuvJQAl57S3t3eFk3mW9cXWCwj2l76eNBqNsf7ziuzvLr14pwB38uzvQlGpVXZ97lLMjq9Wa6pMouHM64MncXU92XMs2X17TZw40WSwuSWNGjUCAAwePBiDBw9Geno6qlWrBpVKhXnz5hmfDw8PN7tLLz093fhc6f9Lt5UtExwcDH9/f2g0Gmg0GotlSvchR14aNYbFRmJpku3Zip1FLndwWSOX2/bFuLtRTXeH4DJyHwBfVGxARrb4VqfCYoNT3tP1rH9byt5ebf88U38cdOYSOP+S4s49R2aLJ3I12TUl1KlTBy1atLD5n4+P6crtYWFhCAwMxM8//ww/Pz/07t0bABAbG4tjx46Z3KWXkJCA4OBgtGrVylgmMTHRZH8JCQmIjY0FAPj4+KBTp04mZQwGAxITE41l5MrdF6gnOzVwbwA2DO7a0Gn7ljpf8/fWYO6T7STeq3zJNSFXAfj1wOVKvFL6P8S/j1zD41/uQmZeEZbvvWT368+7YH1NAKgTZN5aby93f48R2UN2SZU9Pv/8cxw8eBBnzpzBggULMGbMGMyePRs1atQAAPTp0wetWrXC0KFDceTIEaxfvx5vvvkmRo8ebeyaGzlyJC5cuIDXX38dp0+fxhdffIFffvkF48ePNx5nwoQJ+Oabb7BkyRKcOnUKo0aNQm5urvFuwKqgZYT948Aa1grAvU1qOSEax/VuFYbagT4VF6wEqRcEVqlUqOWkWMu6r0ltpx9DjAAfjbtDsGrVoWt2v8ZZScGBi3cw62/Xdgvb+146R4ZIcExmVaQcik6q9u7di969e6Nt27b4+uuv8dVXX+G1114zPq/RaLB69WpoNBrExsbi2WefxbBhwzBr1ixjmejoaKxZswYJCQlo164d5s6di0WLFhmnUwCAp59+Gh999BGmTZuG9u3b4/Dhw1i3bp3Z4HVPtuS5u+wqX5pXfD20Mx7rUM8JEVVeu/rVEeDjheUv3Y1uTWsjLNgXD8VESLZ/Z7RUueKy8ty9UaLL6vTOiUiAgCA/2Y1KMNprY04md/jj0FWXHu/SbfumSZFi0lumVKQk8v32EmHp0qUVlomMjDS7Bbi8Hj164NChQzbLjBkzBmPGjLErPgKq+Xrh9QdbuPzL35bHOpbcSdQ0LAg/vNDVuH310TWS7F/q8Vrh1f1wKk383SeVFWbHBKVZ+bYXwXWEl4xvcKgMT0oKUm7mIq+oGAE+4i4dUrQyfb7pHJLTstGzRSh6taw6P2RJmTzr24tMSDrA05G162Q2ROaZLs4d6yVl919o6ZgUmV2ZG9UJBADczJF2qgAA8NLI7IT5n9zCyk1K6mndV7srObN8ZWVkF2LZnkt4Ycl+LE1KdemxiezFpIpEcWTwsNwukb5e8h2zU17z8CB3h2BRrWolY7ze/FP8wrhiyXWdxGtZ4uamKs+zUirgn2NpostKnU9+ueU8DHZMaUHkakyqSBRHGl+kHrjtLHWrO7A+n5PJ9bbydSfEX2DF8pJpUlVZcm2oahIaWKnX2ZPTSP3Wr2cV4Fau87qeiRzFpMqDyeXLXCE5lduSvwY1/a0+V/oZSvVZdomW/5xXcm2p8jQhlVw7UGPHVcMZXZ/Fdqy9SORqTKo8WHJatmT7cuQyx0tk5bWMkLb7z9ZnIYckXBCU07IplqeNqbIn6XXGO7/3/U0Y9t1enLiW5YS9EzmGSZUH23/xjmT7svdCV7a8WiEXSXeFaeua+3in+hWWsUdWvjSruyvkI5UFd6ZUPVuEWn2usueUPd8FzsgnDQKw7cwNDP5mD26zK5BkhkkVVeiexrUca6lSyAVYbnGGBHijeVhJS5VU16bTErZeeloLjNO4sZqc0ZVadpfFettdcc5861n5Oqw9dt2JRyCyH5MqqlA1X8emM5PrsiPluStOa7nJjEday7orzBk5lSfmae58Sxob509lW7LL7vPynXzbhZ38gX6z/QKy8nRYdfgqFu9MwYUbOU49HlFFFD35J7mOQ9d2+eYFsla229QVrUL23mHogfmPx3FGS1XZRF9fwa2AAoAaPgIyi5zzJXA9qwCPLNiBi7dKZnr31qjwxZBO6N2Kk4SSe7ClyoNJdaeXCva34pRNApRyM5fc4jRJqtwYhyUqqNj9J5I768nHS/qv+Bpl7ho0VPDe/jmeDm8nXmWKig3GhAooWT7pg3WnnXdAogowqfJg7z/W1m3HLvtdK+curLLcFae1i66rkzx7rv3FBgFHrmRKH4Ps0kfHufMdPWBjoHpleZeZU6GipOpWbhHyKzcRfaWdy8hBXpGLD0r0P+z+82CN6gTi9Qeb48N1yY7vzM4LfNkv24q6COTCXamftdopm+PJrVGIrQHiufOza1gzQPJ9lp3RXMyUUTnFrv/LUsp3DnketlR5uP/r0QRznohxeD/2NuKY/ILl91uluLrljB+Tc7ir9W1Uj8ZO+aFQNl+pqKXKXcpGpdMbcD0rHwU6vdvioaqDLVVUoWq+XnZ/OZf94g32V8hpJrN5qkzn95LnxYvkK9DXyynThJRNpGSbVBlKxlu9tHQ/tp65YdzeOTIEy17qqqj1P0lZ2FJVBTja4vFK90Z2v6bsl61KpULtQF+HYnAFd3X/eXtZPnLZrVL1ZoQHy3d9Q0/lrrxDrVI5ZZoQwSSpknz3khAg4LNNZ00SKqBkGol5G864KSqqCphUUYWahwXZnZiV/wX7Rv8WUobkFM7ubnusYz2zbS0jgjGgnfl2AKgXYn1NwMqa9nAr3N3I/K7QXk4Y0FwZ2QWeN8DYXXmHSuWcCW2V0P1nEIDVRy1PDLokKdW1wVCVwqSqCnD0e1Wlsv/3bvkBrEpYqsbZEQ7q0hBe5W7pe+6eKDzULgL+3qbdETH1q6NF+L/r/kl17erRvA4e7WCexA2wsM0dTlzTujsE6bmtpco5+z2d9u9nJNdpNQyCgJSbuRafK9BxQWZyHoUMdiF3C/CxbwyCXH/B2uLsvO+uqJpYNLwzliZdRF5RMR7rUB9P3dUAAPDji13w/c5UpN7KRefImhgf18yk5Uyqwc4BPl54+q6GKNIL+G3/ZajVKgy6qyEeaVcXhy5Jt1Yk/cud00Q445wum6zItWVREIBgPy9oJYpPEATcyClE7Wq+UMttQjuSFSZVVYAUX6yOdv8poaXKFXo0D0WP5uZdbZ0ia6JTpDSTtYox9O5IDL070mXHE6tVRLC7Q5BUkK8XCordc9dZcloO7mtSR/L9dmwYYvz3ou0pku9fCoIgoJqv5aSqmp0/EE9d12Lkjwdw8VYealbzwYePxyCOM7aTFez+qwLckc+UH8CqhJyqV0v5flEqsOGvUgZ2qOvuECQlwH2fXbq2wCn7Lfu3vePcTaccw1ECrM9VpbNjdL0gCHhp6X7jrO23c4swatkB3M4tkiJM8kBMqsgpyo+1UEJL1ROd6rs7BKukuC63a1BDgr04V50g+d8lag9BcO8c8c44ulzHUZW16/xN5BVZbiHU6Q2i38ORK1m4Um7RaJ1ewMpDVx2OkTwTk6oqwBm3VVek/C85JQxDaFS7mrtDsEqSC1kF+5DDpdId56ozlbRUua9mnXFoJYyXHP/zEeQUWh5PJQjiZ1w/fd3yjRObTmdUOjbybEyqSLQHW4eLLmv+nSX/i6VKpZLtmJ6iYuffsSSHa6UCGjTtIgjuTVbr1pB+Wg65zk1lD51e3JsQs4QUUVlMqqoAqb4AYhpUr/RrldBSBQD3Na3t7hAs0khQgUq4FpbeENFSpsmtvfJ1erclqyoVULOaj+T7VUJLVUWK9OJ+pJSOpSISi0kViXb6erbosp0iQ0weu3oduy5RlbuTTq7jRVyR7Plo3P91UHqWDGzvWQPW3cnHS9rP1ROSKp3IpGrh1vMWtythjCi5h/u/RUkx/jpyTXTZ8g0rrm6p+mxwh0q9rtAF3WyVERrk+PIyFV0LW9UNRg1/b4eP44jSa9WIe6PQp8xt601DA90UkfKN7tFE0v2VndhXrt3lFbGUVOn0Bkz5/Siipqwx/mdN3Rpc7oksY1JFTlG+ZcrVv+wqe7g4GU+r4OgFLMjP9rR0GrUKI7tHO3QMR5W2lvl6afD1sM5ImtoTCePvx4bx97s1LiULqSZtoly2pcpbo8wWG12x+S+MD/45jRX7Lot6fbCbf3yQfDGpqgJc3fUGWBiW7uIQKnsXmZy/LB29gA3q0rDCMi/cG4VRLd0zWSUARNYyvQMzoro/mv5v7cmY+pUf01eVSf2nZ7r2n8Q7dxFLY6rsWRPQFTeOkDJxRvUqIMNJkwDaUr5lSiktVUoZUG+vhjUDcH9TcbNrt6ghwM9b7fI10hrVqYbmZdY7LO//ejTGyB8PujAiDyHx397GU+nGfyt1fJVOb8DVzHz8tv8K7uQV4b4mtUXfEQgwqSLrmFRVAU3DrF+onEVdrg1UKbmKrAegVjK22Ea1MPepdqgeIL4V7r2BrTHh12OVOl5l1AnyxafP2B4H92CbCMx4uBVm/H3SRVF5Bmf8UBAEASqVShbTcFTGdztS8M/xNONcVot3pdr1ermOvST3Y1JVBdi7GLIUyne/ubylqpKvk3NSVZmL4+QHW2BUj8Z2v65HM+nXjLOkf0wEXuvZFE1CA0VNGzHi3mhoNGq8tfK4C6LzDM6YUDV66lrJ91mWr5caU/q2wEwnJdC/Hrji0OvZUkXWMKmqAtyRKJQ/pKtDqOw4svItbHJyT+NaOHQpU1TZ30fFollYEIL8KjdGLMjPC8F+lhekldLFW7k2u/wsKdS5b8yXEsn4d4JVHzwe45Yfg2JlF+jcHQLJlIwvISQVLzcMFCqf1Cjli93bwbmaqjtxoPsj7eqhmsgLTafImpVOqEoNjY106PViaCqRxUbVku9yQnJSemOC3P/0Zg1obfK4eVgQerYMlfVktZuTb+DEtSxkZBdgws+HETs7ES3e+geTfzvqtIWsSRnYUlUFODIbdws7WxFKlU/kKttadn+zOth25oZdr/lySMdKT+Lp6AX7yyEdHXq9Lc3Dg7D85bvxQ9JFpNzMxf6Ld5x2LADo2SIMCzZbnvxQKv7e9idV9zSpBR8vNbtgbAgN8sUDzUMByLdLW6UCZj/aFs90aYjGdQKx6XQG6tbwx2Md6iHYwR8ErtD/0x1m237efxk/77+ML4d0RN+2EaL2U6DTQ63UwWlkhklVFeBIUrVoeGfjv0fcEyV6QOfoB0wnHKxsBN8O74ymb/xj12seaBGK7Ep2W2nUKkRU98P1rMr92ryniXNnPo+pXwNznqwBADYnJ5RCx4Y1nLp/AHjmroqneSgvwMcL855qh3ErDqNYqff0O1GvFqH4b/+W8C9t1ZRnToXECd3RqE7JpK73NqmNe8v97Sg5z3hz5XH0aR2O61n5WLIrFdG1AzGgfV1U8/33krv66DWM+ekQAKBudT90q6VCP3cFTJJh918V4Ej3X/2QAOO/+7QWPzFm+wY1TB6rKxmDt0aNexrXEl1+++sPwM9b49ByMzsm96zUnEhn3+1b6WNKSapkyBXzm1V2+Z2HYuri0LTeeKmbeycrlZtOkSH4dsRdaFzn3xno5ZhTPd25gTGh8kS3cosw6JvduO+Dzfhmewr+++cxtJ6+HrP+PomUm7l4e/VJY0IFANeyCvDzBQ32pNx2Y9QkBSZVVYAUi/ECQO1A30of05EIJvRuVmGZEfdE4dSsB9GgZkkS6EgDhkatwpfPdrL7dY6Ox7LXyO6W7+rr20Zct4Mz3RUVUnEh2HdOlRfk543/xDev9Os9kaW/dTl2/2lETGRb0QoAcrfXQoL03c4UPPDRFny7I8Xia579bj/eWX0SS5NSRa9PSPKi7LOWRJEqqRK7lyBf89PKz9v+O3neeqgVAKBDwxD0j4nAmqPXLZbbPbUXwqubrsWld7DvIKAS8brakK4N8fO+S7iT9++dSDH1q+NFCVtvXuvZBJ9uOmf364bFRuGzQR1x9+xEyWKxxNdL/p+TK1n6O5NhToUcEd3zbepVzRn0F/0v4Zq26gSAksXFG9UJhAoln6VKpSr5P0r+r1YBBToDujWtjTpBJT9SSluZS19T8m9VmX/D+IVefru11wb6eUl2LfFkTKqqAKkuPKK/nC2Ua1CmG1GMVhHBeLxjPQAlSeH8p9tbTKp8NGqzhAoAagb4WNzvsLvFjeGpEeCNhjUDcOl2nqjyr3RvJKqclBrUDMBfY+7DL/svQ5uvw8Pt6qJzVE1JjzH8nqhKJVVdo2siNNgPx2b0wZdbzuOLLc4b8P5wu7r4247FvqXUrUktbD93y+Jz9pw/UrH0Y8Bfhj8QMvMrnpKgur+3XeM4PdXKw+LO7XkJZ5wcSYkGNf2hcVOmLghAbp4G85J3VHg9mvtUO3SKlPb7UAwmVVVAWHDlulj6x5h2I4UG+0GjVkFfQd9a50jzrp9AK035j3aoh9qBPliSdNF4N9eb/VtiUJeGJoM6vTRqDI+NxJKkiyavj28TbnG//j4axLUMxcZTGcZtapWAIV0a2Iy9lEqlwugHGmPy7//OKt40NBD3Nqlt8Ut+xD1RovYrtQY1AzCxj/O6wGoF+mJi72aYa8cXdkR1P4QGlyS6QX7e6NE81GJSVTvQcuJrr0FdGmD98TSL67mVV6+GP9K1BTYHuLepF4zjV7XGx4G+XsaZt8saGKnHnOGdMOqnwybnWalXezbBtztScDot22T7w+3qonuzOqhZzRtFxQZJl96xNEPF3Y1qQa2S1zp9Yucam/5wSWu1OxKr8GA/pHF6BDOXb+e7OQIVbhZU/GPF1ctslWJSVQXYGnAcEuBt0n1UqkV4kPELrVSwnzd6tQjFhpPpZuXLetrCHV0atQq9W4Uhodxrn7mrAbo2qoWJfZpDm68zXowtmfRgC1y8nYctySVTLHSJqomZj7S2Wn7uk+0x8dfD2Hb2JupW90Ov2tloVEf8lAlP39UQ9UMCsOl0BiKq++HRDvVQI8AHAT4aLNmVitwiPbo1rY3PB3W0awkYpRn9QBOcStNi7bG0Csv2aF4HCwabTivRPDzI4kX9nYFtJInvnsa1seylrvhk4xnstNJqVGrBkI4oKjZg1eGryC4oxl9lWriCfL2w+Pku6BQZAoNBwKHLd6DNL0a7BjWw+XQGJv56xFg2LNgXHWrlAihpzbOUVD3cri6e7NwAX2w5hw/XJcPHS42xvZpiVPfGxhs3cguL4eullmzZkxbhwWbbQqr54P3HY/Dmn8dFJZ5ldW9WBx88HiN5N67YqUtUKhVmPNIaR69k4qDIiW+l0CI8CL+NugcrD11F0oVbVoceEJWnEhy5TYpE02q1qF69OrKyshAcbP7F5widToe1a9eiX79+8Pa2fHF/d81JfLPddHDkV0M7oXfLMEz54yh+2V+ybINaBXz8dHs80q6uxWSsQKfHh+uS8d1OywMtYxvVwuLn77LY5ZiRXYCRPxzAwUuZCPDRYGyvpnjFymBrW27nFkFvEIzjBypSrDdAMOgrrCOyfS6dy8jB4l0p+HH3JbPXNa5TDd+NuAuRVi6Wo5cdxJpj/16Y6tXwx6b/dJd8TJStaSZ8vdRIfsf0Ds0CnR5JF27hVk4RujWtjTAbSf2W5AysP5GO2oE+eKx9BI4mbUa/fv2gUmvwzNe7TeYNGx/XDGPjmoqKOen8Lby24hBuZBeiZjUf3M4tMj7no1Hjk2fa4/+WiWvN2vKfHoiqbfkzuJ1bhGuZ+fDWqDF2xSGzFrTyzr3bF17/u/niqa+SLA68tuTDx2Pw+u9HbZb5Z2w3tIyw73sw6fwtrD+RhsZ1quHhdnWxNOmiSZdXeLAfFg3vjCcW7rK7leKexrXQPyYCu87fQuPa1fDcvdEIqfZvS2qGtgBd3jNNLP/TpxmeuzcaC7eex2eV6CIvy1ujsmtBZ6rYshe7mk3TUVn2XL+ZVLmIu5OqAp0e//3jGNYevw5/bw1eur8R/q/Hv3NJXbiRgzRtAdrVr2HS7WZLurYAuy/cQoFOj1u5RejUMAQdI0MqvAvuVk4hAv28XDrIWEwdkfh6yisqxq5zt3DuRg5Cg3zRu1WYzRncC3R6fL7pHJIu3ELjOtUwsU9zmwlMZRXo9Oj98VazLoq4lmH4ZlgnyaaJKF9P+UV6/HbwClJu5CK2cS30biV++hGgZIHizDwdagR440ZOIVYduoZ8nR5xLcPQqm4wTl7Tot+n223uY0LvZnitl7hELitfh/XH03Dpdh5iG9dC1+iamLX6JJYmXcSTnerj7YFtzAa9T1913Nj9Pj6uGV7r1QTFBgELNp/Dp4lncXejWvhsUAfUCvRF0vlbWHX4KgRBwO7Tl3Ex5996H9m9Mab0bWFX/dhiMAgmU7ZsOp2O15YfNnbZPtahHt55tA0++Oc0tp+7iWK9AG2BDoU6A/J1erRvUAMLn+1kcWxmWVl5Ovz3z2Pw99Hg/mZ18Ei7usbn0rUFmPDLYexPvWOz1fHroZ3QrWkdaNQq+Hj9+z1Zej61vrsHHl+4B1kixpyRbUyqPJy7kypjWb0BapWqyt3FwaRKHE+pp8JiPXw0atzJ0yHAR1Opu09tcVc96Q2CcVxjscGAomIDrmUWIKp2gCzvhCytp/gH+yK/uGRspSumHtHpDUhOy0bdGv6oWc3y2D29QUBOQbGkXfd6gwAV/p2Xr/TzKizW2/x8LJ1PgiBAW1AMQRAgCIDwv20CAMP/NggANp5KR1GxwThZaukFveylvaS4UObflrejzGtLH1+8nYfTaVqEBUn/I8heBsGAjIwMhIaGQq2yfR5N7NMcrepKc6215/rNMVVVjKvnUiJyh9ILmLULqlKV/hjSqFXQqDXw9dKgebj8k1+NWoWQaq6L01ujrnBKBo1aJflYyPI/VksfVybhValUotYSHdLV+Wt0ysW/yWdH2f7o4xWWiIiISAJMqoiIiIgkwKSKiIiISAJMqoiIiIgkwKSKiIiISAJMqoiIiIgkwKSKiIiISAJMqoiIiIgkwKSKiIiISAJMqoiIiIgkwKSKiIiISAJMqoiIiIgkwAWVXaR0xXCtViv5vnU6HfLy8qDVamW7yKS7sY7EYT2Jw3oSh/UkDutJHHfVU+l1u/Q6bguTKhfJzs4GADRo0MDNkRAREZG9srOzUb16dZtlVIKY1IscZjAYcO3aNQQFBUGlUkm6b61WiwYNGuDy5csIDg6WdN+egnUkDutJHNaTOKwncVhP4rirngRBQHZ2NurWrQu12vaoKbZUuYharUb9+vWdeozg4GD+QVaAdSQO60kc1pM4rCdxWE/iuKOeKmqhKsWB6kREREQSYFJFREREJAEmVR7A19cX06dPh6+vr7tDkS3WkTisJ3FYT+KwnsRhPYmjhHriQHUiIiIiCbClioiIiEgCTKqIiIiIJMCkioiIiEgCTKqIiIiIJMCkSuEWLFiAqKgo+Pn5oWvXrti7d6+7Q3Kabdu24eGHH0bdunWhUqmwcuVKk+cFQcC0adMQEREBf39/xMXF4ezZsyZlbt++jSFDhiA4OBg1atTACy+8gJycHJMyR48eRbdu3eDn54cGDRrgww8/dPZbk9Ts2bNx1113ISgoCKGhoRg4cCCSk5NNyhQUFGD06NGoVasWAgMD8fjjjyM9Pd2kzKVLl9C/f38EBAQgNDQUkyZNQnFxsUmZLVu2oGPHjvD19UWTJk2wePFiZ789yXz55ZeIiYkxTiQYGxuLf/75x/g868jc+++/D5VKhXHjxhm3sZ5KzJgxAyqVyuS/Fi1aGJ9nPf3r6tWrePbZZ1GrVi34+/ujbdu22L9/v/F5RX+XC6RYK1asEHx8fITvvvtOOHHihPDSSy8JNWrUENLT090dmlOsXbtWeOONN4Q//vhDACD8+eefJs+///77QvXq1YWVK1cKR44cER555BEhOjpayM/PN5Z58MEHhXbt2gm7d+8Wtm/fLjRp0kQYNGiQ8fmsrCwhLCxMGDJkiHD8+HFh+fLlgr+/v/DVV1+56m06LD4+Xvj++++F48ePC4cPHxb69esnNGzYUMjJyTGWGTlypNCgQQMhMTFR2L9/v3D33XcL99xzj/H54uJioU2bNkJcXJxw6NAhYe3atULt2rWFqVOnGstcuHBBCAgIECZMmCCcPHlS+OyzzwSNRiOsW7fOpe+3sv766y9hzZo1wpkzZ4Tk5GThv//9r+Dt7S0cP35cEATWUXl79+4VoqKihJiYGGHs2LHG7aynEtOnTxdat24tXL9+3fjfjRs3jM+znkrcvn1biIyMFEaMGCHs2bNHuHDhgrB+/Xrh3LlzxjJK/i5nUqVgXbp0EUaPHm18rNfrhbp16wqzZ892Y1SuUT6pMhgMQnh4uDBnzhzjtszMTMHX11dYvny5IAiCcPLkSQGAsG/fPmOZf/75R1CpVMLVq1cFQRCEL774QggJCREKCwuNZSZPniw0b97cye/IeTIyMgQAwtatWwVBKKkXb29v4ddffzWWOXXqlABASEpKEgShJIFVq9VCWlqascyXX34pBAcHG+vm9ddfF1q3bm1yrKefflqIj4939ltympCQEGHRokWso3Kys7OFpk2bCgkJCUL37t2NSRXr6V/Tp08X2rVrZ/E51tO/Jk+eLNx3331Wn1f6dzm7/xSqqKgIBw4cQFxcnHGbWq1GXFwckpKS3BiZe6SkpCAtLc2kPqpXr46uXbsa6yMpKQk1atRA586djWXi4uKgVquxZ88eY5n7778fPj4+xjLx8fFITk7GnTt3XPRupJWVlQUAqFmzJgDgwIED0Ol0JnXVokULNGzY0KSu2rZti7CwMGOZ+Ph4aLVanDhxwlim7D5Kyyjx/NPr9VixYgVyc3MRGxvLOipn9OjR6N+/v9l7YT2ZOnv2LOrWrYtGjRphyJAhuHTpEgDWU1l//fUXOnfujCeffBKhoaHo0KEDvvnmG+PzSv8uZ1KlUDdv3oRerzf5AwSAsLAwpKWluSkq9yl9z7bqIy0tDaGhoSbPe3l5oWbNmiZlLO2j7DGUxGAwYNy4cbj33nvRpk0bACXvw8fHBzVq1DApW76uKqoHa2W0Wi3y8/Od8XYkd+zYMQQGBsLX1xcjR47En3/+iVatWrGOylixYgUOHjyI2bNnmz3HevpX165dsXjxYqxbtw5ffvklUlJS0K1bN2RnZ7Oeyrhw4QK+/PJLNG3aFOvXr8eoUaPw2muvYcmSJQCU/13u5bQ9E5HbjR49GsePH8eOHTvcHYosNW/eHIcPH0ZWVhZ+++03DB8+HFu3bnV3WLJx+fJljB07FgkJCfDz83N3OLLWt29f479jYmLQtWtXREZG4pdffoG/v78bI5MXg8GAzp0747333gMAdOjQAcePH8fChQsxfPhwN0fnOLZUKVTt2rWh0WjM7h5JT09HeHi4m6Jyn9L3bKs+wsPDkZGRYfJ8cXExbt++bVLG0j7KHkMpxowZg9WrV2Pz5s2oX7++cXt4eDiKioqQmZlpUr58XVVUD9bKBAcHK+Yi4uPjgyZNmqBTp06YPXs22rVrh/nz57OO/ufAgQPIyMhAx44d4eXlBS8vL2zduhWffvopvLy8EBYWxnqyokaNGmjWrBnOnTvH86mMiIgItGrVymRby5YtjV2lSv8uZ1KlUD4+PujUqRMSExON2wwGAxITExEbG+vGyNwjOjoa4eHhJvWh1WqxZ88eY33ExsYiMzMTBw4cMJbZtGkTDAYDunbtaiyzbds26HQ6Y5mEhAQ0b94cISEhLno3jhEEAWPGjMGff/6JTZs2ITo62uT5Tp06wdvb26SukpOTcenSJZO6OnbsmMkXV0JCAoKDg41fiLGxsSb7KC2j5PPPYDCgsLCQdfQ/vXr1wrFjx3D48GHjf507d8aQIUOM/2Y9WZaTk4Pz588jIiKC51MZ9957r9kUL2fOnEFkZCQAD/gud+oweHKqFStWCL6+vsLixYuFkydPCi+//LJQo0YNk7tHPEl2drZw6NAh4dChQwIAYd68ecKhQ4eEixcvCoJQchtujRo1hFWrVglHjx4VBgwYYPE23A4dOgh79uwRduzYITRt2tTkNtzMzEwhLCxMGDp0qHD8+HFhxYoVQkBAgKKmVBg1apRQvXp1YcuWLSa3d+fl5RnLjBw5UmjYsKGwadMmYf/+/UJsbKwQGxtrfL709u4+ffoIhw8fFtatWyfUqVPH4u3dkyZNEk6dOiUsWLBAUbd3T5kyRdi6dauQkpIiHD16VJgyZYqgUqmEDRs2CILAOrKm7N1/gsB6KjVx4kRhy5YtQkpKirBz504hLi5OqF27tpCRkSEIAuup1N69ewUvLy/h3XffFc6ePSssW7ZMCAgIEH788UdjGSV/lzOpUrjPPvtMaNiwoeDj4yN06dJF2L17t7tDcprNmzcLAMz+Gz58uCAIJbfivvXWW0JYWJjg6+sr9OrVS0hOTjbZx61bt4RBgwYJgYGBQnBwsPDcc88J2dnZJmWOHDki3HfffYKvr69Qr1494f3333fVW5SEpToCIHz//ffGMvn5+cL//d//CSEhIUJAQIDw6KOPCtevXzfZT2pqqtC3b1/B399fqF27tjBx4kRBp9OZlNm8ebPQvn17wcfHR2jUqJHJMeTu+eefFyIjIwUfHx+hTp06Qq9evYwJlSCwjqwpn1Sxnko8/fTTQkREhODj4yPUq1dPePrpp03mXmI9/evvv/8W2rRpI/j6+gotWrQQvv76a5PnlfxdrhIEQXBeOxgRERFR1cAxVUREREQSYFJFREREJAEmVUREREQSYFJFREREJAEmVUREREQSYFJFREREJAEmVUREREQSYFJFREREJAEmVURELrBlyxaoVCrMmDHD3aEQkZMwqSIiWUpNTYVKpcKDDz5o3DZixAioVCqkpqa6LzAbVCoVevTo4e4wiMhNvNwdABFRVdClSxecOnUKtWvXdncoROQkTKqIiFwgICAALVq0cHcYRORE7P4jIkWIiorCkiVLAADR0dFQqVQWu9tSUlLw4osvomHDhvD19UVERARGjBiBixcvmu2z9PVXr17FsGHDEB4eDrVajS1btgAANm/ejOeffx7NmzdHYGAgAgMD0blzZ3z99dcm+ykdLwUAW7duNcamUqmwePFikzKWxlQdP34cTz31FEJDQ+Hr64vo6GiMGzcOt27dslgPUVFRyMnJwdixY1G3bl34+voiJiYGv/32m1n5rKwsTJs2Da1atUJgYCCCg4PRpEkTDB8+3GKdEFHlsaWKiBRh3LhxWLx4MY4cOYKxY8eiRo0aAEqSjFJ79uxBfHw8cnNz8dBDD6Fp06ZITU3FsmXL8M8//yApKQmNGjUy2e+tW7cQGxuLmjVr4plnnkFBQQGCg4MBAB988AHOnTuHu+++G48++igyMzOxbt06vPLKK0hOTsbcuXONMUyfPh0zZ85EZGQkRowYYdx/+/btbb6vHTt2ID4+HkVFRXjiiScQFRWFpKQkzJ8/H6tXr8bu3bvNugx1Oh369OmDO3fu4PHHH0deXh5WrFiBp556CuvWrUOfPn0AAIIgID4+Hnv27MG9996LBx98EGq1GhcvXsRff/2FoUOHIjIyshKfBhFZJBARyVBKSooAQIiPjzduGz58uABASElJMStfVFQkREVFCUFBQcLBgwdNntu+fbug0WiEhx56yGQ7AAGA8NxzzwnFxcVm+7xw4YLZNp1OJ/Tu3VvQaDTCxYsXzfbXvXt3i+9n8+bNAgBh+vTpxm16vV5o3LixAEBYt26dSflJkyYJAITnn3/eZHtkZKQAQBgwYIBQWFho3L5x40az+jp69KgAQBg4cKBZPAUFBUJ2drbFWImoctj9R0QeYfXq1UhNTcWkSZPQoUMHk+fuu+8+DBgwAGvXroVWqzV5zsfHBx9++CE0Go3ZPqOjo822eXl5YeTIkdDr9di8ebNDMe/cuRPnz59H3759ER8fb/LctGnTULNmTfz0008oKioye+3HH38MHx8f4+NevXohMjIS+/btMyvr7+9vts3X1xeBgYEOxU9Eptj9R0QeYffu3QCA5ORki+OW0tLSYDAYcObMGXTu3Nm4PTo62uodednZ2fjoo4+wcuVKnD9/Hrm5uSbPX7t2zaGYDx06BAAWp2EoHb+1YcMGJCcno23btsbnatSoYTHhq1+/PpKSkoyPW7ZsiZiYGCxfvhxXrlzBwIED0aNHD7Rv3x5qNX9TE0mNSRUReYTbt28DAJYtW2azXPnEKCwszGK5oqIi9OjRAwcPHkSHDh0wdOhQ1KpVC15eXkhNTcWSJUtQWFjoUMylrWbWYoiIiDApV6p69eoWy3t5ecFgMJg83rRpE2bMmIHff/8dEydOBADUqVMHY8aMwRtvvGGxhY6IKodJFRF5hNLB5X///Tceeugh0a8rvWuvvFWrVuHgwYN44YUXsGjRIpPnVqxYYbwT0RGlMaenp1t8Pi0tzaRcZdSqVQufffYZPv30U5w+fRqbNm3CZ599hunTp8Pb2xtTp06t9L6JyBTbf4lIMUpbVfR6vdlzXbt2BQCT7i9HnD9/HgAwYMAAs+e2b99u8TVqtdpibNaUjv0qncKhrNzcXOzfvx/+/v5o3ry56H1ao1Kp0LJlS4wePRoJCQkAgL/++svh/RLRv5hUEZFi1KxZEwBw+fJls+cGDBiAhg0bYt68edi2bZvZ8zqdDjt27BB9rNKpBsq/ZuvWrfjmm2+sxnflyhXRx7j33nvRuHFj/PPPP9i4caPJc++88w5u3bqFQYMGmQxIt0dqaqrFJX1KW8b8/PwqtV8isozdf0SkGD179sRHH32El19+GY8//jiqVauGyMhIDB06FL6+vvjtt9/Qt29fdO/eHT179kTbtm2hUqlw8eJFbN++HbVq1cLp06dFHevhhx9GVFQUPvzwQxw/fhxt2rRBcnIyVq9ejUcffdTiRJs9e/bEL7/8goEDB6JDhw7QaDR45JFHEBMTY/EYarUaixcvRnx8PPr164cnn3wSkZGRSEpKwpYtW9C4cWO8//77la6vw4cP47HHHkOXLl3QqlUrhIeH4+rVq1i5ciXUajXGjx9f6X0TkTkmVUSkGH379sWHH36Ib775BnPnzoVOp0P37t0xdOhQAMBdd92FI0eOYM6cOVi7di127twJX19f1KtXDwMHDsSgQYNEHyswMBCbNm3CpEmTsG3bNmzZsgWtW7fGsmXLEBYWZjGpmj9/PgBg06ZN+Pvvv2EwGFC/fn2rSRVQMt3D7t27MWvWLGzYsAFZWVmoW7cuxo4dizfffNOhtQI7d+6MyZMnY8uWLVizZg0yMzMRHh6OuLg4TJo0CXfffXel901E5lSCIAjuDoKIiIhI6TimioiIiEgCTKqIiIiIJMCkioiIiEgCTKqIiIiIJMCkioiIiEgCTKqIiIiIJMCkioiIiEgCTKqIiIiIJMCkioiIiEgCTKqIiIiIJMCkioiIiEgCTKqIiIiIJPD/yqR23/N/MMoAAAAASUVORK5CYII=", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "eplt = res.energies\n", + "plt.plot(res.energies[:], lw=4, label=\"QUBO Energy\")\n", + "plt.grid(which='both')\n", + "plt.ylabel('Energy', fontsize=14)\n", + "plt.xlabel('Iterations', fontsize=14)\n", + "plt.legend(fontsize=12)\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can also extract the price and pipe diameters obtained after the optimization" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "0.33815821889033915 [500. 500.]\n" + ] + } + ], + "source": [ + "price = data[4]\n", + "diameters = data[5]\n", + "print(price, diameters)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Plot the solution\n", + "\n", + "We can also plot the reference solution and the QUBO solution for visual inspection" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [], + "source": [ + "sol = data[2]\n", + "ref_values = solutions[tuple(diameters)][0]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "Text(0.5, 1.0, 'Pressure')" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "image/png": "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BJ6enlAoFNixY4fGekOY1x9VXx5Dem0nJibiueeeg729PVxdXREdHY1z585pjCktLcXkyZPRrl07tGnTBq+99hry8vJ0VPGTNSRPnz59ahyfSZMm6ajiui1btgzdunVTf7loeHg4du3apV6v1eMi1CgbN24UKysrWbVqlZw+fVri4+PFyclJ8vLyah3/888/i7m5uXz22Wdy5swZmTNnjlhaWsqpU6fUYz755BNxdHSUHTt2yK+//ipDhw4VPz8/KSkpaa1YT6SNzP/6179kwYIF8s9//lMASEZGRiulabiWzn3//n2JjIyUb7/9Vs6ePStpaWkSGhoqISEhrRnribRxrL/55hvZu3evXLhwQbKysmTChAni4OAgt27daq1Y9dJG7mrbtm2T7t27i6enp/z3f/+3lpM0nDYyx8XFyYABA+TmzZvqP3fv3m2tSCahscdNnyUkJEiXLl00fl9u376t67IaZOfOnTJ79mzZtm2bAJDt27drrNf3ef1x9eUxpNd2VFSUrF69WrKysiQzM1MGDRokHTp0kAcPHqjHTJo0SXx8fGT//v1y7Ngxef755+WFF17QYdV1a0ie3r17S3x8vMbxKSgo0GHVtfv+++8lOTlZ/u///k/OnTsnH3zwgVhaWkpWVpaIaPe4sOFppNDQUJk8ebL656qqKvH09JTExMRax8fExMjgwYM1loWFhcl//Md/iIiISqUSd3d3WbRokXr9/fv3RalUyoYNG7SQoPFaOvOjcnJy9Lbh0WbuakeOHBEAcvny5ZYpuplaI3NBQYEAkH379rVM0S1AW7mvXbsmXl5ekpWVJb6+vnrV8Ggjc1xcnLz66qtaqZd+19jjps8SEhKke/fuui6j2R5vEAxhXn+SuhoeQ31t37p1SwDIwYMHReT3Y2FpaSmbN29Wj/ntt98EgKSlpemqzAZ7PI/I7w3Pe++9p7uimsHZ2VlWrlyp9ePCS9oaoby8HMePH0dkZKR6mZmZGSIjI5GWllbrNmlpaRrjASAqKko9PicnB7m5uRpjHB0dERYWVuc+W5M2MhuC1spdUFAAhUIBJyenFqm7OVojc3l5OVasWAFHR0d079695YpvBm3lVqlUGDNmDKZPn44uXbpop/gm0uaxTk1NhaurK55++mm88847uHPnTssHMFFNOW76Ljs7G56envD398eoUaNw5coVXZfU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jo5Wfzv2418K98c//hHbtm3DsGHDMHjwYOTk5GD58uXo3LlzrRPxo2JjYzFjxgwMGzYM7777rvr2ph07dtT4YGpAQAA++ugjzJo1C5cuXUJ0dDTs7e2Rk5OD7du3Y+LEiZg2bRoOHDiAKVOmYMSIEejYsSMqKyuxdu1a9T8wiIiagvMK5xXOK0aidW8KR9Q81bcPPXr0aI11VVVVEhAQIAEBAVJZWSkiIhcuXJCxY8eKu7u7WFpaipeXl/zxj3+ULVu2qLer6/ahIiJ5eXkyefJk8fHxEUtLS3F3d5d+/frJihUr1GOqbx9a160rMzIyZPjw4dKuXTtRKpXi6+srMTExsn//fvWY6ttm3r59u9a8OTk5GstXrVolzz77rCiVSnF2dpbevXvL3r17NcakpKRIVFSUODo6irW1tQQEBMi4cePk2LFjdTy7NSUnJwsA8fDwqPV2pX/961/F19dXlEqlPPvss5KUlFTrrUHx2O1DRUT27NkjXbt2FSsrK3n66adl3bp1NW4fWm3r1q3Sq1cvsbOzEzs7O+nUqZNMnjxZzp07JyIiFy9elLfeeksCAgLE2tpa2rZtK3379pV9+/Y1OCsRmSbOK7/jvMJ5xZgpRBrxqTUiIiIiIiIDws/wEBERERGR0WLDQ0RERERERosNDxERERERGS02PEREREREZLTY8BARERERkdFiw0NEREREREaLDQ8RERERERktNjxERERERGS02PAQEREREZHRYsNDRERERERGiw0PEREREREZLTY8RERERERktNjwEBERERGR0fp/Q83dNraQs8YAAAAASUVORK5CYII=", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt \n", + "\n", + "fig = plt.figure(figsize = plt.figaspect(0.5))\n", + "ax1 = fig.add_subplot(121)\n", + "\n", + "ax1.axline((0, 0.0), slope=1.10, color=\"grey\", linestyle=(0, (2, 5)))\n", + "ax1.axline((0, 0.0), slope=1, color=\"black\", linestyle=(0, (2, 5)))\n", + "ax1.axline((0, 0.0), slope=0.90, color=\"grey\", linestyle=(0, (2, 5)))\n", + "ax1.grid()\n", + "\n", + "ax1.scatter(ref_values[:2], sol[:2], s=150, lw=1, edgecolors='w', label='Sampled solution')\n", + "\n", + "\n", + "ax1.set_xlabel('Reference Values', fontsize=12)\n", + "ax1.set_ylabel('QUBO Values', fontsize=12)\n", + "ax1.set_title('Flow Rate', fontsize=14)\n", + "\n", + "ax2 = fig.add_subplot(122)\n", + "\n", + "ax2.axline((0, 0.0), slope=1.10, color=\"grey\", linestyle=(0, (2, 5)))\n", + "ax2.axline((0, 0.0), slope=1, color=\"black\", linestyle=(0, (2, 5)))\n", + "ax2.axline((0, 0.0), slope=0.90, color=\"grey\", linestyle=(0, (2, 5)))\n", + "\n", + "\n", + "ax2.scatter(ref_values[2:], sol[2:], s=150, lw=1, edgecolors='w', label='Sampled solution')\n", + "ax2.grid()\n", + "\n", + "\n", + "ax2.set_xlabel('Reference Values', fontsize=12)\n", + "ax2.set_title('Pressure', fontsize=14)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "vitens_wntr_1", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.9.0" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/notebooks/qubo_polynomial_solver/Net0.ipynb b/docs/notebooks/qubo_polynomial_solver/Net0.ipynb new file mode 100644 index 0000000..90a3199 --- /dev/null +++ b/docs/notebooks/qubo_polynomial_solver/Net0.ipynb @@ -0,0 +1,477 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# QUBO Solution of the hydraulics equations\n", + "In this notebook we illustrate how to solve the hydraulics equations using a pure QUBO approach. \n", + "\n", + "## Hydraulics equations\n", + "In their most basic form the hydraulics equations read:\n", + "\n", + "$$\n", + " \\sum_j q_{ij} - D_i = 0 \\newline\n", + " h_{L_{ij}} \\equiv h_i - h_j = A |q_{ij}| q_{ij}^{B-1}\n", + "$$\n", + "\n", + "where $h_i$ is the head pressure at node $i$, $A$ the resistance coefficient and $B$ the flow exponent. \n", + "Several approximations have been developed for define $A$ and $B$. The popular Hazen-Williams (HW) approximation uses $B=1.852$. The HW is therefore not suited for a QUBO formulation that requires integer exponents in the formulation of the objective function. In contrast, the Chezy-Manning (CM) and Darcy-Weisbach (DW) approximation use $B=2$. We have implemented DW and CM hydraulics models that can found under `wntr_quantum/sim/models/`.\n", + "\n", + "\n", + "The presence of absolute values in the hydraulics equation makes it difficult to use the approach we just described. We therefore express the flow values as:\n", + "\n", + "$$\n", + " q_{ij} = s_{ij} |q_{ij}| \\equiv s_{ij} y_{ij}\n", + "$$\n", + "\n", + "This leads to the equations:\n", + "\n", + "$$\n", + " \\sum_j s_{ij} y_{ij} - D_i = 0 \\newline\n", + " h_{L_{ij}} \\equiv h_i - h_j = A s_{ij} y_{ij}^{B}\n", + "$$\n", + "\n", + "In these forms the hydraulics equation can be seen as a system of non-linear equations with integeer power of the unknown: \n", + "\n", + "$$\n", + "F(s_{ij}, y_{ij}, h_i)=0\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + " ## Solving non linear systems with a QUBO approach\n", + " \n", + " We closely following an approach developed in this [http://dx.doi.org/10.1038/s41598-019-46729-0](paper) to solve the non linear system. \n", + " \n", + " \n", + "The method proposes to solve a non-linear system, given by $F(X) = 0$ by first decomposing the system of equations as a sum of tensor products:\n", + "\n", + "$$\n", + " F_i = P_i^{(0)} + \\sum_j P_{ij}^{(1)}x_j + \\sum_{jk} P_{ijk}^{(2)}x_j x_k + \\sum_{jkl} P_{ijkl}^{(3)}x_j x_k x_l = 0 \n", + "$$\n", + "\n", + "To find the solution of the system one can then minimise the residual sum of squares\n", + "\n", + "$$\n", + "\\chi^2 = \\left[ P^{(0)} + P^{(1)} X + P^{(2)} X^2 + P^{(3)} X^3 + ... \\right]^2\n", + "$$\n", + "\n", + "By encoding all the variables as binary expansions we obtain a high order boolean polynomial. To solve this problem with a QUBO formalism, the high order terms have to be quadratized by introducing additional binary variables and appropriate terms in the loss function. The resulting QUBO problem can then be solved using either classical simulated annealing or quantum annealers alike." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Example\n", + "\n", + "We demonstrate in the following how to us our software to solve the hydraulics equations with a QUBO approach.\n", + "\n", + "### Reference Solution\n", + "\n", + "We first define the problem and solve it classically to obtain a benchmark solution" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": { + "metadata": {} + }, + "outputs": [], + "source": [ + "import wntr\n", + "inp_file = './networks/Net0.inp'\n", + "wn = wntr.network.WaterNetworkModel(inp_file)\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We solve the problem using the default `EPANET` simulator " + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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Drf9G5FfUsShZiLyDqKos5k8mU4nQOdjJekcC7wrVqzAzTffjKCgIISHhyMrKwsnTpwwKzNx4kQIgmCWFixY4FA9bht4k+K4pIiIqG2oWT55Mq1GPjli7969WLhwIfbv34/du3ejpaUFU6dORVNTk1m5+fPn4/z586b0pz/9yaF63Par0NCYftBoNGaHJLcrr6rGtevNCPD364aWEREpxyhqYRStLycyip49q1nrI0CnsfzlQis69qUjLy/P7PebNm1CeHg4ioqKMGHCBNP1wMBAREZGOt7YH7htj9fPzwdxgyw/uCRJOHHqrMItIiJSngS5iVUaSO77z7xd2iZRCVZSW5mGhgaz1NzcbNe96+vrAQB9+vQxu75lyxaEhYVhxIgRWLJkCa5evepYmx0qrTJJsZxgRUTezduHmu2Z1TxgwACEhISY0ooVK2zeVxRFPP744xg/fjxGjBhhun7ffffhnXfeweeff44lS5bg7bffxq9//WuH2uy2Q81A25Kif3x2wGIelxQRkTcQRS1EmaFm0cOHmn10Any0lr9c+BjbrldVVSE4ONh03c/P9mvIhQsX4tixY/jqq6/Mrj/44IOmX48cORJRUVGYMmUKysrKEBsba1eb3TvwcmYzEXk5SYJsr9bDN65qW05kJfBq0HY9ODjYLPDakpOTg48++ghffPEF+ve3PpEXAFJTUwEApaWl3hF4eVgCEXk7W8PJ3jLUbDHPwS8dkiThkUcewYcffoiCggIMHjzY5meKi4sBAFFRUXbX49bveBNlAu/JinMwGGyf2kFE5M5EUQOjTOrMlpHr1q1DTEwM/P39kZqaioMHD8qW37FjBxITE+Hv74+RI0di165dZvlz587tsPY1MzPT4r2am5sxevRoCIJgCmpytNbW8PoI0Dq4ZeTChQvxzjvvYOvWrQgKCoJer4der8e1a9cAAGVlZVi+fDmKiopQUVGBf/7zn5g9ezYmTJiAUaNG2V2PWwfeHoH+iOkfbjHPaBRRevq8wi0iIlKWBI3N5Ijt27cjNzcXy5Ytw+HDh5GcnIyMjAzU1NRYLL9v3z7MmjUL8+bNw5EjR5CVlYWsrCwcO3bMrFxmZqbZ2td3333X4v2efPJJREdb34v/RtZnNLclR7z22muor6/HxIkTERUVZUrbt28H0Ha272effYapU6ciMTERTzzxBO699178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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "# solve the problem\n", + "sim = wntr.sim.EpanetSimulator(wn)\n", + "reference_results = sim.run_sim()\n", + "\n", + "# Plot results on the network\n", + "pressure_at_5hr = reference_results.node['pressure'].loc[0, :]\n", + "flow_at_5hr = reference_results.link['flowrate'].loc[0, :]\n", + "wntr.graphics.plot_network(wn, link_attribute=flow_at_5hr, \n", + " node_attribute=pressure_at_5hr, \n", + " node_size=500, \n", + " link_width=5, \n", + " node_labels=True,\n", + " link_cmap=plt.cm.cividis)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We extract the values of the pressure and flows for future use" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "array([ 0.05 , 0.05 , 26.477, 22.954], dtype=float32)" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import numpy as np \n", + "ref_pressure = reference_results.node['pressure'].values[0][:2]\n", + "ref_rate = reference_results.link['flowrate'].values[0]\n", + "ref_values = np.append(ref_rate, ref_pressure)\n", + "ref_values" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### QUBO Polynomial Solver\n", + "\n", + "We now show how to solve the problem using the QUBO polynomial solver included in `wntr_quantum`. We start with redefining the water network." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "wn = wntr.network.WaterNetworkModel(inp_file)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The unknown of the problem can take continuous values and therefore must be encoded using several qubits before being used in a QUBO formulation. We use here the encoding implemented in our library `qubops`. We use these encoding schemes to instantiate the polynomial solver. " + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Head Encoding : 0.000000 => 200.000000 (res: 1.574803)\n", + "Flow Encoding : -4.000000 => -0.000000 | 0.000000 => 4.000000 (res: 0.031496)\n" + ] + } + ], + "source": [ + "from wntr_quantum.sim.solvers.qubo_polynomial_solver import QuboPolynomialSolver\n", + "from qubops.encodings import PositiveQbitEncoding\n", + "\n", + "nqbit = 7\n", + "step = (4./(2**nqbit-1))\n", + "flow_encoding = PositiveQbitEncoding(nqbit=nqbit, step=step, offset=+0, var_base_name=\"x\")\n", + "\n", + "nqbit = 7\n", + "step = (200/(2**nqbit-1))\n", + "head_encoding = PositiveQbitEncoding(nqbit=nqbit, step=step, offset=+0.0, var_base_name=\"x\")\n", + "\n", + "net = QuboPolynomialSolver(wn, flow_encoding=flow_encoding, head_encoding=head_encoding)\n", + "net.verify_encoding()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We then solve the QUBO equations classically. This gives us: a reference solution, the best possible encoded solution, the total encoded solution including all slack variables and the QUBO energy of the solution." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "/home/nico/QuantumApplicationLab/QuantumNewtonRaphson/quantum_newton_raphson/utils.py:74: SparseEfficiencyWarning: spsolve requires A be CSC or CSR matrix format\n", + " warn(\"spsolve requires A be CSC or CSR matrix format\", SparseEfficiencyWarning)\n" + ] + } + ], + "source": [ + "ref_sol, encoded_ref_sol, bin_rep_sol, eref, cvgd = net.classical_solution()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Initial sample for the QUBO optimization \n", + "\n", + "Before minimizing the energy of the QUBO problem we need to define the initial configuration of the binary variables in the QUBO problem. We have implemented two different ways to obtain an initial sample that respects all the conditions imposed by the quadratization constraings of the polynomial qubo solver. \n", + "\n", + "We can for example create a completely random sample that simply ensure that quadratization constraints are respected" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [], + "source": [ + "from wntr_quantum.sampler.simulated_annealing import generate_random_valid_sample\n", + "x = generate_random_valid_sample(net)\n", + "x0 = list(x.values())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alternatively we can modify the solution calculated in `.classical_solution()`. This can be useful when one wants to reuse exact values of the flows or pressure" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "from wntr_quantum.sampler.simulated_annealing import modify_solution_sample\n", + "x = modify_solution_sample(net, bin_rep_sol, modify=['flows', 'heads'])\n", + "x0 = list(x.values())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Temperature scheduling for the Simulated Annealing optimization\n", + "\n", + "One important parameters of the simulated Annealing process is the the so-called temperature schedule. This schdule defines the acceptance probability of the new samples that increase the QUBO energy. While high temperature that leads to accepting samples that increase energy is usefull to escape local minima the temperature must be decreased in order to converge towards a minima. \n", + "\n", + "The temperature schedule usually starts with high temperature values that allows to explore the energy landscape but progressively decrease the tempearture in order for the optimization to converge. " + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "num_temp = 2000\n", + "Tinit = 1E1\n", + "Tfinal = 1E-1\n", + "Tschedule = np.linspace(Tinit, Tfinal, num_temp)\n", + "Tschedule = np.append(Tschedule, Tfinal*np.ones(1000))\n", + "Tschedule = np.append(Tschedule, np.zeros(1000))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can then use the `solve()` method of the qubo polynomial solver to obtain a solution of the problem" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "100%|██████████| 4000/4000 [00:05<00:00, 675.39it/s]\n" + ] + } + ], + "source": [ + "net.step_func.optimize_values = np.arange(2,6)\n", + "_, _, sol, res = net.solve(init_sample=x0, Tschedule=Tschedule, save_traj=True, verbose=False)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can plot the evoluion of the QUBO energy along the optimization path" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "Text(0.5, 0, 'Iterations')" + ] + }, + "execution_count": 11, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "image/png": "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GoqZM2di7ty54nIKANC3b1989tln+OijjxASEoKtW7fi66+/xmOPPWaWWoiIiMj2mX1JhZMnT+Ljjz/Gxo0bcf36dbRo0QLPPfcccnNzsXLlSqxfvx5bt27FkCFDGn2usLAw7Ny5s842SqUSa9aswZo1a2ptExwcjL1799Z5nBdffBEvvvjiA/WzqXGZKiIiIuszy0jV7du38cknn6Bv377o0aMHkpOT8cgjjyAlJQWXLl3Chg0bcPz4caSmpqJly5Z44403zHFaug8BvP5HRERkKY0aqTpy5AhWr16NTZs24datW3BycsKrr76KKVOmoE+fPkbthwwZggkTJuC9995rzGmJiIiImp1GharevXsDuLtkwV//+le8+uqraN26dZ3v6dChAx555JHGnJbuwcfUEBERWV+jLv+98sor+OGHH5CXl4f/+Z//uW+gAoApU6agsLCwMaeleuLdf0RERJbTqJGq//3f/zVXP4iIiIhsmlmXVCDr4NU/IiIi62vUSFVAQMB928jlciiVSgQFBeG5557DSy+91JhTUgPw6h8REZHlNCpU6fV6VFVV4dKlS3cPZm8Pd3d3XLt2DVVVVQCAdu3a4cqVK8jNzcWWLVuwevVqbN++HY6Ojo3vPREREVEz0ajLf7m5ufDx8UFERAT279+PiooKXLp0CRUVFdi/fz8GDRqEdu3a4eLFizhz5gyGDh2KjIwMLF261Fz9J4C3/xERETUDjQpVb7zxBioqKpCeno4nn3xSfAadTCbDk08+ibS0NNy5cweJiYkIDAzEF198AT8/P2zatMksnae6Cbz9j4iIyGIaFaq2bduGoUOHQi43fRg7OzsMHToU27ZtAwA4OTkhIiICZ8+ebcxp6R4cpyIiIrK+RoUqrVYLrVZbZ5ubN2/i5s2b4mt3d/fGnJIagONUREREltOoUNWtWzd8/vnnOHfunMn9586dw6ZNm9CtWzdx28WLF+Hh4dGY0xIRERE1O426++/NN9/ECy+8gJ49e2LixIno168fPD09ceXKFfz4449Ys2YNSktL8eabbwIAKisrkZ6ejujoaLN0nu7iPHUiIiLra1So+vOf/4zVq1cjPj4eH3zwAZKTk8V9giCgZcuWWLVqFf785z8DAMrLy7FmzRp07969cb2meuE8dSIiIstpVKgCgPHjx+P555/Htm3bcOzYMWi1WiiV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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "plt.plot(res.energies[:], lw=4, label=\"QUBO Energy\")\n", + "plt.axline((0, eref[0]), slope=0, color=\"black\", lw=4, linestyle=(4, (1, 2)))\n", + "plt.grid(which='both')\n", + "plt.ylabel('Energy', fontsize=14)\n", + "plt.xlabel('Iterations', fontsize=14)\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can also plot the reference solution and the QUBO solution for visual inspection" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "Text(0.5, 1.0, 'Pressure')" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "image/png": "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QwcAQNWqVVGzZk0cOnQIhw8fho2NDZo0aaJznrNnz4anpyd+/vnnQktI3759GwDUK7EVEAShyJLaANQviPn5+UUeq1u3Luzs7HD27FkolUqdcyYiouKFhIQA+N9UME04OTkhLCwMmzZtQocOHXD16lXExcUVaWdra4uuXbti2bJlGD16NJKSknD69GkA/1uZs7jXvXPnzmmcU0F/Tp48qfG5RMVhwUMkslGjRkGpVGLWrFkQBEF9/OLFi1i1ahXs7e0RFhZW6JyCUZsvv/wSUqm00BLP7du3x6FDh/D333+jZcuWkMvlOudoZWWFmTNnQqlUYv78+erjBffmHD9+vFD7L774ApcvXy4Sx9HREQDw4MGDIo+ZmZnhnXfewf379zF9+vRii57Lly8jOTlZp74QEZm6d999F2ZmZpgyZQri4+OLPP7ixYtChceRI0cKvT4BgFKpVE8ls7S0BPByX5/iPtAqeN4uaGdnZ4fatWvj+PHjhYql9PR0zJo1S+P+9OnTB1WrVsV3332HqKioIo8rlcoir1NEr8MpbUQi++ijj7B3716sXbsW165dQ8eOHZGcnIxNmzYhLy8Pv/32W5EpB61atYJcLkdKSgoaNmyIypUrqx9r3749li9frv63WCZOnIgvv/wSa9aswezZs1GzZk28/fbbWLlyJfr3749BgwbByckJp06dQmxsLHr06IG9e/cWilGnTh14enpi48aNsLCwgJeXFyQSCaZMmQJ7e3vMmzcPsbGx+PHHH7F37160adMGrq6uePToES5duoQLFy7g5MmTcHV1Fa1fRESmJiAgAD///DPeeecd1K5dG927d0fNmjWRnp6OO3fu4OjRoxg9ejSWLl0KAAgLC4OdnR2aNWuGatWqQalUIiIiAlevXsWAAQPUH3699957SEhIQKtWreDj4wOJRILjx4/jzJkzaNasGVq1aqXO4cMPP8TEiRPRvHlzDBw4ECqVCn/++adWsxIsLCywZcsWdOvWDW3btkWHDh0QGBgIiUSC+/fv49ixY3BycuKiN1R6el4ljsigvG5PhOIUtyy1IAhCRkaG8Mknnwi1atVS773TrVs34dixYyXGatGihQBA+PDDDwsdT0hIUC+L/c99gHTty08//SQAEEaMGKE+dvjwYaFly5aCra2t4ODgIHTv3l2IiYkRPv30UwGAcPjw4UIxTp06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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt \n", + "\n", + "fig = plt.figure(figsize = plt.figaspect(0.5))\n", + "ax1 = fig.add_subplot(121)\n", + "\n", + "ax1.axline((0, 0.0), slope=1.10, color=\"grey\", linestyle=(0, (2, 5)))\n", + "ax1.axline((0, 0.0), slope=1, color=\"black\", linestyle=(0, (2, 5)))\n", + "ax1.axline((0, 0.0), slope=0.90, color=\"grey\", linestyle=(0, (2, 5)))\n", + "ax1.grid()\n", + "\n", + "ax1.scatter(ref_values[:2], encoded_ref_sol[:2], c='black', s=200, label='Best solution')\n", + "ax1.scatter(ref_values[:2], sol[:2], s=150, lw=1, edgecolors='w', label='Sampled solution')\n", + "\n", + "\n", + "ax1.set_xlabel('Reference Values', fontsize=12)\n", + "ax1.set_ylabel('QUBO Values', fontsize=12)\n", + "ax1.set_title('Flow Rate', fontsize=14)\n", + "\n", + "ax2 = fig.add_subplot(122)\n", + "\n", + "ax2.axline((0, 0.0), slope=1.10, color=\"grey\", linestyle=(0, (2, 5)))\n", + "ax2.axline((0, 0.0), slope=1, color=\"black\", linestyle=(0, (2, 5)))\n", + "ax2.axline((0, 0.0), slope=0.90, color=\"grey\", linestyle=(0, (2, 5)))\n", + "\n", + "\n", + "ax2.scatter(ref_values[2:], encoded_ref_sol[2:], c='black', s=200, label='Best solution')\n", + "ax2.scatter(ref_values[2:], sol[2:], s=150, lw=1, edgecolors='w', label='Sampled solution')\n", + "ax2.grid()\n", + "\n", + "\n", + "ax2.set_xlabel('Reference Values', fontsize=12)\n", + "ax2.set_title('Pressure', fontsize=14)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "vitens_wntr_1", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.9.0" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/notebooks/qubo_polynomial_solver/Net0_OptmizedSchedule.ipynb b/docs/notebooks/qubo_polynomial_solver/Net0_OptmizedSchedule.ipynb new file mode 100644 index 0000000..8a7da8c --- /dev/null +++ b/docs/notebooks/qubo_polynomial_solver/Net0_OptmizedSchedule.ipynb @@ -0,0 +1,455 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# QUBO Solution of the hydraulics equations\n", + "In this notebook we illustrate how to solve the hydraulics equations using a pure QUBO approach. \n", + "\n", + "## Hydraulics equations\n", + "In their most basic form the hydraulics equations read:\n", + "\n", + "$$\n", + " \\sum_j q_{ij} - D_i = 0 \\newline\n", + " h_{L_{ij}} \\equiv h_i - h_j = A |q_{ij}| q_{ij}^{B-1}\n", + "$$\n", + "\n", + "where $h_i$ is the head pressure at node $i$, $A$ the resistance coefficient and $B$ the flow exponent. \n", + "Several approximations have been developed for define $A$ and $B$. The popular Hazen-Williams (HW) approximation uses $B=1.852$. The HW is therefore not suited for a QUBO formulation that requires integer exponents in the formulation of the objective function. In contrast, the Chezy-Manning (CM) and Darcy-Weisbach (DW) approximation use $B=2$. We have implemented DW and CM hydraulics models that can found under `wntr_quantum/sim/models/`.\n", + "\n", + "\n", + "The presence of absolute values in the hydraulics equation makes it difficult to use the approach we just described. We therefore express the flow values as:\n", + "\n", + "$$\n", + " q_{ij} = s_{ij} |q_{ij}| \\equiv s_{ij} y_{ij}\n", + "$$\n", + "\n", + "This leads to the equations:\n", + "\n", + "$$\n", + " \\sum_j s_{ij} y_{ij} - D_i = 0 \\newline\n", + " h_{L_{ij}} \\equiv h_i - h_j = A s_{ij} y_{ij}^{B}\n", + "$$\n", + "\n", + "In these forms the hydraulics equation can be seen as a system of non-linear equations with integeer power of the unknown: \n", + "\n", + "$$\n", + "F(s_{ij}, y_{ij}, h_i)=0\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + " ## Solving non linear systems with a QUBO approach\n", + " \n", + " We closely following an approach developed in this [http://dx.doi.org/10.1038/s41598-019-46729-0](paper) to solve the non linear system. \n", + " \n", + " \n", + "The method proposes to solve a non-linear system, given by $F(X) = 0$ by first decomposing the system of equations as a sum of tensor products:\n", + "\n", + "$$\n", + " F_i = P_i^{(0)} + \\sum_j P_{ij}^{(1)}x_j + \\sum_{jk} P_{ijk}^{(2)}x_j x_k + \\sum_{jkl} P_{ijkl}^{(3)}x_j x_k x_l = 0 \n", + "$$\n", + "\n", + "To find the solution of the system one can then minimise the residual sum of squares\n", + "\n", + "$$\n", + "\\chi^2 = \\left[ P^{(0)} + P^{(1)} X + P^{(2)} X^2 + P^{(3)} X^3 + ... \\right]^2\n", + "$$\n", + "\n", + "By encoding all the variables as binary expansions we obtain a high order boolean polynomial. To solve this problem with a QUBO formalism, the high order terms have to be quadratized by introducing additional binary variables and appropriate terms in the loss function. The resulting QUBO problem can then be solved using either classical simulated annealing or quantum annealers alike." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Example\n", + "\n", + "We demonstrate in the following how to us our software to solve the hydraulics equations with a QUBO approach.\n", + "\n", + "### Reference Solution\n", + "\n", + "We first define the problem and solve it classically to obtain a benchmark solution" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": { + "metadata": {} + }, + "outputs": [], + "source": [ + "import wntr\n", + "import wntr_quantum\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "# Create a water network model\n", + "\n", + "inp_file = '../networks/Net0.inp'\n", + "wn = wntr.network.WaterNetworkModel(inp_file)\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Run with the original EPANET simulator" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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Drf9G5FfUsShZiLyDqKos5k8mU4nQOdjJekcC7wrVqzAzTffjKCgIISHhyMrKwsnTpwwKzNx4kQIgmCWFixY4FA9bht4k+K4pIiIqG2oWT55Mq1GPjli7969WLhwIfbv34/du3ejpaUFU6dORVNTk1m5+fPn4/z586b0pz/9yaF63Par0NCYftBoNGaHJLcrr6rGtevNCPD364aWEREpxyhqYRStLycyip49q1nrI0CnsfzlQis69qUjLy/P7PebNm1CeHg4ioqKMGHCBNP1wMBAREZGOt7YH7htj9fPzwdxgyw/uCRJOHHqrMItIiJSngS5iVUaSO77z7xd2iZRCVZSW5mGhgaz1NzcbNe96+vrAQB9+vQxu75lyxaEhYVhxIgRWLJkCa5evepYmx0qrTJJsZxgRUTezduHmu2Z1TxgwACEhISY0ooVK2zeVxRFPP744xg/fjxGjBhhun7ffffhnXfeweeff44lS5bg7bffxq9//WuH2uy2Q81A25Kif3x2wGIelxQRkTcQRS1EmaFm0cOHmn10Any0lr9c+BjbrldVVSE4ONh03c/P9mvIhQsX4tixY/jqq6/Mrj/44IOmX48cORJRUVGYMmUKysrKEBsba1eb3TvwcmYzEXk5SYJsr9bDN65qW05kJfBq0HY9ODjYLPDakpOTg48++ghffPEF+ve3PpEXAFJTUwEApaWl3hF4eVgCEXk7W8PJ3jLUbDHPwS8dkiThkUcewYcffoiCggIMHjzY5meKi4sBAFFRUXbX49bveBNlAu/JinMwGGyf2kFE5M5EUQOjTOrMlpHr1q1DTEwM/P39kZqaioMHD8qW37FjBxITE+Hv74+RI0di165dZvlz587tsPY1MzPT4r2am5sxevRoCIJgCmpytNbW8PoI0Dq4ZeTChQvxzjvvYOvWrQgKCoJer4der8e1a9cAAGVlZVi+fDmKiopQUVGBf/7zn5g9ezYmTJiAUaNG2V2PWwfeHoH+iOkfbjHPaBRRevq8wi0iIlKWBI3N5Ijt27cjNzcXy5Ytw+HDh5GcnIyMjAzU1NRYLL9v3z7MmjUL8+bNw5EjR5CVlYWsrCwcO3bMrFxmZqbZ2td3333X4v2efPJJREdb34v/RtZnNLclR7z22muor6/HxIkTERUVZUrbt28H0Ha272effYapU6ciMTERTzzxBO699178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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "sim = wntr.sim.EpanetSimulator(wn)\n", + "results = sim.run_sim()\n", + "# Plot results on the network\n", + "pressure_at_5hr = results.node['pressure'].loc[0, :]\n", + "flow_at_5hr = results.link['flowrate'].loc[0, :]\n", + "wntr.graphics.plot_network(wn, link_attribute=flow_at_5hr, \n", + " node_attribute=pressure_at_5hr, \n", + " node_size=500, \n", + " link_width=5, \n", + " node_labels=True,\n", + " link_cmap=plt.cm.cividis)" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "array([ 0.05 , 0.05 , 26.477, 22.954], dtype=float32)" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "ref_pressure = results.node['pressure'].values[0][:2]\n", + "ref_rate = results.link['flowrate'].values[0]\n", + "ref_values = np.append(ref_rate, ref_pressure)\n", + "ref_values" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Run with the QUBO Polynomial Solver" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [], + "source": [ + "wn = wntr.network.WaterNetworkModel(inp_file)" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Head Encoding : 0.000000 => 200.000000 (res: 1.574803)\n", + "Flow Encoding : -4.000000 => -0.000000 | 0.000000 => 4.000000 (res: 0.031496)\n" + ] + } + ], + "source": [ + "from wntr_quantum.sim.solvers.qubo_polynomial_solver import QuboPolynomialSolver\n", + "from qubops.solution_vector import SolutionVector_V2 as SolutionVector\n", + "from qubops.encodings import RangedEfficientEncoding, PositiveQbitEncoding\n", + "\n", + "nqbit = 7\n", + "step = (4./(2**nqbit-1))\n", + "flow_encoding = PositiveQbitEncoding(nqbit=nqbit, step=step, offset=+0, var_base_name=\"x\")\n", + "\n", + "nqbit = 7\n", + "step = (200/(2**nqbit-1))\n", + "head_encoding = PositiveQbitEncoding(nqbit=nqbit, step=step, offset=+0.0, var_base_name=\"x\")\n", + "\n", + "solver = QuboPolynomialSolver(wn, flow_encoding=flow_encoding, \n", + " head_encoding=head_encoding)\n", + "solver.verify_encoding()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We then solve the QUBO equations classically. This gives us: a reference solution, the best possible encoded solution, the total encoded solution including all slack variables and the QUBO energy of the solution." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "/home/nico/miniconda3/envs/vitens_wntr_1/lib/python3.9/site-packages/quantum_newton_raphson/utils.py:74: SparseEfficiencyWarning: spsolve requires A be CSC or CSR matrix format\n", + " warn(\"spsolve requires A be CSC or CSR matrix format\", SparseEfficiencyWarning)\n" + ] + } + ], + "source": [ + "ref_sol, encoded_ref_sol, bin_rep_sol, eref, cvgd = solver.classical_solution()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Initial sample for the QUBO optimization \n", + "\n", + "Before minimizing the energy of the QUBO problem we need to define the initial configuration of the binary variables in the QUBO problem. We have implemented two different ways to obtain an initial sample that respects all the conditions imposed by the quadratization constraings of the polynomial qubo solver. \n", + "\n", + "We can for example create a completely random sample that simply ensure that quadratization constraints are respected" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "from wntr_quantum.sampler.simulated_annealing import modify_solution_sample\n", + "x = modify_solution_sample(solver, bin_rep_sol, modify=['flows', 'heads'])\n", + "x0 = list(x.values())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Define the temperature schedule\n", + "\n", + "The simulated annealing sampling requires a temperature schedule that needs to be carefully controlled to accept or reject the moves. " + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [], + "source": [ + "num_sweeps = 2000\n", + "Tinit = 1E1\n", + "Tfinal = 1E-1\n", + "Tschedule = np.linspace(Tinit, Tfinal, num_sweeps)\n", + "Tschedule = np.append(Tschedule, Tfinal*np.ones(1000))\n", + "Tschedule = np.append(Tschedule, np.zeros(1000))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Define the variables to optimize\n", + "\n", + "We can select which variables a given optimizatio run changes to minimize the energy. In the example here, the first two variables are the signs of the flows, the two after that the absolute values of the flows and the last twos the head pressure. In the run below we first optimized all variables and then fine tune the values of the flows and then those of the head pressure." + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "100%|██████████| 4000/4000 [00:07<00:00, 561.00it/s]\n", + "100%|██████████| 4000/4000 [00:05<00:00, 746.56it/s]\n", + "100%|██████████| 4000/4000 [00:06<00:00, 664.99it/s]\n" + ] + } + ], + "source": [ + "\n", + "optimize_value = [np.arange(2,6), np.arange(2,4), np.arange(4,6)]\n", + "status, msg, solution, results = solver.solve(x0, Tschedule, optimize_values=optimize_value, save_traj=True, verbose=False)\n", + "solver.step_func.verify_quadratic_constraints(results[-1].res)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can plot the evolution of the QUBO energy and temperature to get an idea of the optimization process. " + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 23, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "image/png": "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wdi4caPOMtq2bYuUlBSt7Q+uQ2UoDm9vb3z00Uf46KOPtPapVCq7Jzfsc0NEREQuhckNERERuRQmN2Q17FBMRESOgMkNERGRmZYtW4aCggJ7h0EPYHJDRERELoXJDdmcGTOVExERmY3JDRGRizNnLSQie7DWb5XJDRGRi3JzcwMArdWjiRxVYWEhBEFQ/3bNxUn8yOb0rN9GRDYmlUrh7++PmzdvAiifWVbfgoqORKVSobS0FMXFxSYtLOksWD9NoiiirKwMeXl5yMvLg7+/v94V2Y3F5IaIyIWFhIQAgDrBcQaiKOLevXvw9PR0imTMVKyfblKpFKGhofDz87M4BiY3ZHN83E9kP4IgIDQ0FEFBQVAoFPYOxygKhQK7d+9G165dLX484YhYP20ymQxSqdRqyR6TGyKiakAqlVrc1F9VpFIpysrK4OHh4ZI3f9bP9lzvYR/Zj+u1rhIRkRNickNEREQuhckNERERuRQmN2Q97DhMREQOgMkNERERuRQmN2Q97FBMREQOgMkNERERuRQmN0RERORSmNwQERGRS2FyQzYnchgVERFVISY3RERE5FKY3JDNCRxGRUREVYjJDREREbkUJjdERETkUpjckM2xQzEREVUlJjdERETkUpjckNWw2zARETkCJjdERETkUpjckNWwZw0RETkCJjdERETkUpjcEBERkUthckNWww7FRETkCJjcEBERkUthckNEREQuhckN2ZzIYVRERFSFmNwQERGRS2FyQ0RERC6FyQ3ZnMBhVEREVIWY3BAREZFLYXJDNscOxUREVJWY3BAREZFLYXJDVsO+NURE5AiY3BAREZFLYXJDRERELoXJDVkNOw4TEZEjYHJDRERELoXJDREREbkUJjdkNRwtRUREjoDJDREREbkUJjdkc+xoTEREVYnJDREREbkUJjdERETkUpjcEBERkUthckM2x1FURERUlZjckM2xQzEREVUlh0tuFi9ejOjoaPj6+sLX1xcxMTHYsmWLen9xcTEmTJiAWrVqwdvbG4MHD0ZWVpYdIyYiIiJH4nDJTd26dfHxxx/j0KFDOHjwIHr06IEBAwbg5MmTAIBXX30VCQkJWL16NZKSknD9+nUMGjTIzlETERGRo5DZO4AHxcfHa7z/73//i8WLFyMlJQV169bF999/j5UrV6JHjx4AgKVLl6JZs2ZISUlB586d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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "eplt = results[-1].energies-eref[0]\n", + "\n", + "left, bottom, width, height = [0.55, 0.55, 0.3, 0.3]\n", + "\n", + "plt.plot(results[-1].energies[:]-eref, lw=4, label=\"QUBO Energy\")\n", + "plt.plot(Tschedule, lw=3, label='Temperature')\n", + "plt.grid(which='both')\n", + "\n", + "\n", + "plt.ylabel('Energy', fontsize=14)\n", + "plt.xlabel('Iterations', fontsize=14)\n", + "plt.legend(fontsize=12)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Finally we can plo the solution obtained with our QUBO solver against the one obtained with the reference values" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "Text(0.5, 1.0, 'Pressure')" + ] + }, + "execution_count": 24, + "metadata": {}, + "output_type": "execute_result" + }, + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt \n", + "\n", + "fig = plt.figure(figsize = plt.figaspect(0.5))\n", + "ax1 = fig.add_subplot(121)\n", + "\n", + "ax1.axline((0, 0.0), slope=1.10, color=\"grey\", linestyle=(0, (2, 5)))\n", + "ax1.axline((0, 0.0), slope=1, color=\"black\", linestyle=(0, (2, 5)))\n", + "ax1.axline((0, 0.0), slope=0.90, color=\"grey\", linestyle=(0, (2, 5)))\n", + "ax1.grid()\n", + "\n", + "ax1.scatter(ref_values[:2], encoded_ref_sol[:2], c='black', s=200, label='Best solution')\n", + "ax1.scatter(ref_values[:2], solution[:2], s=150, lw=1, edgecolors='w', label='Sampled solution')\n", + "\n", + "\n", + "ax1.set_xlabel('Reference Values', fontsize=12)\n", + "ax1.set_ylabel('QUBO Values', fontsize=12)\n", + "ax1.set_title('Flow Rate', fontsize=14)\n", + "\n", + "ax2 = fig.add_subplot(122)\n", + "\n", + "ax2.axline((0, 0.0), slope=1.10, color=\"grey\", linestyle=(0, (2, 5)))\n", + "ax2.axline((0, 0.0), slope=1, color=\"black\", linestyle=(0, (2, 5)))\n", + "ax2.axline((0, 0.0), slope=0.90, color=\"grey\", linestyle=(0, (2, 5)))\n", + "\n", + "\n", + "ax2.scatter(ref_values[2:], encoded_ref_sol[2:], c='black', s=200, label='Best solution')\n", + "ax2.scatter(ref_values[2:], solution[2:], s=150, lw=1, edgecolors='w', label='Sampled solution')\n", + "ax2.grid()\n", + "\n", + "\n", + "ax2.set_xlabel('Reference Values', fontsize=12)\n", + "ax2.set_title('Pressure', fontsize=14)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "vitens_wntr_1", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.9.0" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/notebooks/qubo_polynomial_solver/dw_approximation.ipynb b/docs/notebooks/qubo_polynomial_solver/dw_approximation.ipynb new file mode 100644 index 0000000..4ff99b1 --- /dev/null +++ b/docs/notebooks/qubo_polynomial_solver/dw_approximation.ipynb @@ -0,0 +1,128 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Approximation of the DW resistance coefficients\n", + "\n", + "The DW approximation uses a convoluted expression for the resistance factor given by:\n", + "\n", + "$$\n", + "A = 0.0252 \\, f(\\epsilon, d, q) \\, d^{-5} \\, L\n", + "$$\n", + "\n", + "where $d$ and $L$ are the diameter and length of the pipe. The friction factor $f(\\epsilon, d, q)$ is given by a non-linear function that depends on the friction coefficient, $\\epsilon$ as well as the diameter of the pipe and the flow rate. This non-linear function also depends also on the flow regime.\n", + "\n", + "This form is not well suited for a QUBO formulation of the hydraulics equations as it is not a polynomial expression. \n", + "\n", + "We consider here only the fully turbulent regime, where $f(\\epsilon, d, q)$ is usually computed by the Swamee-Jain (SJ) approximation to the Colebrook-White equation. While very accurate this approximation is to complicated to use directly in a QUBO reformulation. We therefore use here a simpler quadratic interpolation of the Colebrook-White equation:\n", + "\n", + "$$\n", + "f(\\epsilon, d, q) = \\alpha(\\epsilon, d) + \\beta(\\epsilon, d) |q|^{-1} + \\gamma(\\epsilon, d) |q|^{-2}\n", + "$$\n", + "\n", + "were the fitting coefficients $\\alpha$, $\\beta$ and $\\gamma$ can either be computed on the fly or tabulated. While less accurate that the full SJ approximation, the quadratic approximation stays close to it for a wide range of parameters. This approach leads to acceptable results for our current purpose." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Approximation used in wntr-quantum\n", + "\n", + "The approximation used in wntr_quantum is implemented in the function `dw_fit`. Given values for the roughness and the diameter of a pipe, this function returns the coefficients $\\alpha$, $\\beta$ and $\\gamma$ of the fitting function expressed above. It also returns the numeraical values of the approximation and true values for a range of the flow values. " + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "from wntr_quantum.sim.models.darcy_weisbach_fit import dw_fit\n", + "import matplotlib.pyplot as plt\n", + "import numpy as np" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "# define the parameters of the coefficents\n", + "roughness = 0.5 * 1e-3\n", + "DIAMS = np.arange(5, 20, 3) / 12\n", + "\n", + "BASELINE = []\n", + "APPROX = []\n", + "\n", + "# loop over the diameters\n", + "for d in DIAMS:\n", + "\n", + " # call the fit function provided by wntr_quantum\n", + " res, approx, baseline, qval = dw_fit(\n", + " roughness=roughness, diameter=d, plot=False, convert_to_us_unit=False, return_all_data=True\n", + " )\n", + " BASELINE.append(baseline)\n", + " APPROX.append(approx)\n", + "\n", + "# define color palette\n", + "colors = plt.cm.tab20(np.linspace(0, 1, 24))\n", + "\n", + "# plot the approximation\n", + "fig = plt.figure(figsize = plt.figaspect(0.5))\n", + "ax1 = fig.add_subplot(111)\n", + "\n", + "i = 0\n", + "for bl, ap in zip(BASELINE, APPROX):\n", + " ax1.loglog(qval, bl, \"--\", lw = 3, c=colors[i])\n", + " ax1.loglog(qval, ap, \"-\", lw = 2, c=colors[i])\n", + " i += 1\n", + "\n", + "ax1.grid(visible=True, which=\"both\")\n", + "ax1.set_xlabel(\"Flow velocity (|q|)\", fontsize=18)\n", + "ax1.set_ylabel(\"Friction Factor\", fontsize=18)\n", + "plt.xticks(fontsize=14)\n", + "plt.yticks(ticks=[1.6*1e-2, 1.7*1e-2, 1.8*1e-2, 1.9*1e-2, 2.0*1e-2, 2.1*1e-2], labels=['1.6', '', '1.8', '', '2.0', ''], fontsize=14)\n", + "ax1.annotate(r'$\\times$10$^{%i}$'%(-2), fontsize=12,\n", + " xy=(-.075, .96), xycoords='axes fraction')\n", + "\n", + "plt.show()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "vitens_wntr_1", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.9.0" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/examples/poly_qubo_examples.py b/examples/poly_qubo_examples.py new file mode 100644 index 0000000..7b729ef --- /dev/null +++ b/examples/poly_qubo_examples.py @@ -0,0 +1,144 @@ +import os +import matplotlib.pyplot as plt +import wntr +from dwave.samplers import SteepestDescentSolver +from qubops.encodings import PositiveQbitEncoding +import wntr_quantum + + +def get_ape_from_pd_series(quantum_pd_series, classical_pd_series): + """Helper function to evaluate absolute percentage error between classical and quantum results.""" + DELTA = 1.0e-12 + ape = ( + abs(quantum_pd_series - classical_pd_series) + * 100.0 + / abs(classical_pd_series + DELTA) + ) + return ape + + +def compare_results(classical_result, quantum_result): + """Helper function that compares the classical and quantum simulation results.""" + TOL = 10 # => per cent + DELTA = 1.0e-12 + classical_data = [] + quantum_data = [] + + def check_ape(classical_value, quantum_value): + """Checks if the absolute percentage error between classical and quantum results is within TOL.""" + ape = ( + abs(quantum_value - classical_value) * 100.0 / abs(classical_value + DELTA) + ) + is_close_to_classical = ape <= TOL + if is_close_to_classical: + print( + f"Quantum result {quantum_value} within {ape}% of classical result {classical_value}" + ) + quantum_data.append(quantum_value) + classical_data.append(classical_value) + return is_close_to_classical + + for link in classical_result.link["flowrate"].columns: + classical_value = classical_result.link["flowrate"][link].iloc[0] + quantum_value = quantum_result.link["flowrate"][link].iloc[0] + message = f"Flowrate {link}: {quantum_value} not within {TOL}% of classical result {classical_value}" + assert check_ape(classical_value, quantum_value), message + + for node in classical_result.node["pressure"].columns: + classical_value = classical_result.node["pressure"][node].iloc[0] + quantum_value = quantum_result.node["pressure"][node].iloc[0] + message = f"Pressure {node}: {quantum_value} not within {TOL}% of classical result {classical_value}" + assert check_ape(classical_value, quantum_value), message + + return classical_data, quantum_data + + +# set EPANET Quantum environment variables +os.environ["EPANET_TMP"] = "/Users/murilo/scratch_dir/.epanet_quantum" +os.environ["EPANET_QUANTUM"] = "/Users/murilo/Documents/NLeSC_Projects/Vitens/EPANET" + +# set input files +path = "../docs/notebooks/networks" +inputs = ["Net0.inp"] + + +for file in inputs: + + print("##################################") + print(f"Solving for {file} model") + print("##################################") + + # set up network model + input_file = f"{path}/{file}" + model_name = os.path.splitext(file)[0] + wn = wntr.network.WaterNetworkModel(input_file) + + # solve model using the classical EPANET simulator + sim_classical = wntr_quantum.sim.QuantumEpanetSimulator(wn) + results_classical = sim_classical.run_sim() + + nqbit = 9 + step = 0.5 / (2**nqbit - 1) + flow_encoding = PositiveQbitEncoding( + nqbit=nqbit, step=step, offset=+1.5, var_base_name="x" + ) + + nqbit = 9 + step = 50 / (2**nqbit - 1) + head_encoding = PositiveQbitEncoding( + nqbit=nqbit, step=step, offset=+50.0, var_base_name="x" + ) + + # solve model using FULL QUBOs + sim = wntr_quantum.sim.FullQuboPolynomialSimulator( + wn, flow_encoding=flow_encoding, head_encoding=head_encoding + ) + sampler = SteepestDescentSolver() + results_quantum = sim.run_sim(solver_options={"sampler": sampler}) + + # plot networt and absolute percent errors + wntr.graphics.plot_network( + wn, + node_attribute=get_ape_from_pd_series( + results_quantum.node["pressure"].iloc[0], + results_classical.node["pressure"].iloc[0], + ), + link_attribute=get_ape_from_pd_series( + results_quantum.link["flowrate"].iloc[0], + results_classical.link["flowrate"].iloc[0], + ), + node_colorbar_label="Pressures", + link_colorbar_label="Flows", + node_size=50, + title=f"{model_name}: Absolute Percent Error", + node_labels=False, + filename=f"{model_name}_wnm_qubo.png", + ) + + # checks if the quantum results are within 5% of the classical ones + classical_data, quantum_data = compare_results(results_classical, results_quantum) + + # plot all data + plt.close() + plt.scatter( + classical_data[:2], + quantum_data[:2], + label="Flowrates", + color="blue", + marker="o", + ) + plt.scatter( + classical_data[2:], + quantum_data[2:], + label="Pressures", + color="red", + marker="s", + facecolors="none", + ) + plt.axline((0, 0), slope=1, linestyle="--", color="gray", label="") + plt.xlabel("Classical EPANET results") + plt.ylabel("Quantum EPANET results") + plt.legend() + plt.title(f"{model_name}") + plt.savefig(f"{model_name}_results_qubo.png") + plt.close() diff --git a/pyproject.toml b/pyproject.toml index 36334c4..084a158 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,6 +22,8 @@ dependencies = [ "scipy", "wntr", "quantum_newton_raphson@git+https://github.com/QuantumApplicationLab/QuantumNewtonRaphson", + "qubols@git+https://github.com/QuantumApplicationLab/qubols", + "qubops@git+https://github.com/QuantumApplicationLab/qubops", ] description = "A quantum enabled water nework management tool" diff --git a/tests/networks/Net0_DW.inp b/tests/networks/Net0_DW.inp new file mode 100644 index 0000000..019b292 --- /dev/null +++ b/tests/networks/Net0_DW.inp @@ -0,0 +1,128 @@ +[TITLE] +File obtained via Mario of a 2 node sysem + + +[JUNCTIONS] +;ID Elev Demand Pattern + J1 0 0 ; + D1 0 50 ; + +[RESERVOIRS] +;ID Head Pattern + R1 30 ; + +[TANKS] +;ID Elevation InitLevel MinLevel MaxLevel Diameter MinVol VolCurve Overflow + +[PIPES] +;ID Node1 Node2 Length Diameter Roughness MinorLoss Status + P1 R1 J1 1000 250 0.05 0 Open ; + P2 J1 D1 1000 250 0.05 0 Open ; + +[PUMPS] +;ID Node1 Node2 Parameters + +[VALVES] +;ID Node1 Node2 Diameter Type Setting MinorLoss + +[TAGS] + +[DEMANDS] +;Junction Demand Pattern Category + +[STATUS] +;ID Status/Setting + +[PATTERNS] +;ID Multipliers + +[CURVES] +;ID X-Value Y-Value + +[CONTROLS] + +[RULES] + +[ENERGY] + Global Efficiency 75 + Global Price 0 + Demand Charge 0 + +[EMITTERS] +;Junction Coefficient + +[QUALITY] +;Node InitQual + +[SOURCES] +;Node Type Quality Pattern + +[REACTIONS] +;Type Pipe/Tank Coefficient + + +[REACTIONS] + Order Bulk 1 + Order Tank 1 + Order Wall 1 + Global Bulk 0 + Global Wall 0 + Limiting Potential 0 + Roughness Correlation 0 + +[MIXING] +;Tank Model + +[TIMES] + Duration 1 + Hydraulic Timestep 1:00 + Quality Timestep 0:05 + Pattern Timestep 1:00 + Pattern Start 0:00 + Report Timestep 1:00 + Report Start 0:00 + Start ClockTime 12 am + Statistic None + +[REPORT] + Status No + Summary No + Page 0 + +[OPTIONS] + Units LPS + Headloss D-W + Specific Gravity 1 + Viscosity 1 + Trials 50 + Accuracy 0.001 + CHECKFREQ 2 + MAXCHECK 10 + DAMPLIMIT 0 + Unbalanced Continue 10 + Pattern 1 + Demand Multiplier 1.0 + Emitter Exponent 0.5 + Quality None mg/L + Diffusivity 1 + Tolerance 0.01 + +[COORDINATES] +;Node X-Coord Y-Coord +J1 10.00000 60.00000 +D1 110.00000 60.00000 +R1 -11.72214 74.24023 + +[VERTICES] +;Link X-Coord Y-Coord + +[LABELS] +;X-Coord Y-Coord Label & Anchor Node + +[BACKDROP] + DIMENSIONS 0.000 0.000 10000.000 10000.000 + UNITS None + FILE + OFFSET 0.00 0.00 + +[END] diff --git a/tests/test_aml_quantum_newton_solver.py b/tests/test_aml_quantum_newton_solver.py index b561269..dd0be3b 100644 --- a/tests/test_aml_quantum_newton_solver.py +++ b/tests/test_aml_quantum_newton_solver.py @@ -9,7 +9,7 @@ from quantum_newton_raphson.vqls_solver import VQLS_SOLVER from qubols.encodings import EfficientEncoding from wntr.sim import aml -from wntr_quantum.sim.solvers import QuantumNewtonSolver +from wntr_quantum.sim.solvers.quantum_newton_solver import QuantumNewtonSolver TOL_RESULTS = 1e-2 diff --git a/tests/test_poly_qubo_network_simulator.py b/tests/test_poly_qubo_network_simulator.py new file mode 100644 index 0000000..306187b --- /dev/null +++ b/tests/test_poly_qubo_network_simulator.py @@ -0,0 +1,86 @@ +"""Tests WNTR quantum using a small network and different simulators and solvers.""" + +import pathlib +import numpy as np +import pytest +import wntr +from qubops.encodings import PositiveQbitEncoding +from wntr_quantum.sampler.simulated_annealing import generate_random_valid_sample +from wntr_quantum.sim.solvers.qubo_polynomial_solver import QuboPolynomialSolver + +NETWORKS_FOLDER = pathlib.Path(__file__).with_name("networks") +INP_FILE = NETWORKS_FOLDER / "Net0_DW.inp" # => toy wn model +DELTA = 1.0e-12 +TOL = 5 # => per cent + + +def calculate_small_differences(value1, value2): + """Helper function to calculate percentage difference between classical and quantum results.""" + return np.allclose([value1], [value2], atol=1e-1, rtol=1e-1) + + +def compare_results(original, new): + """Helper function that compares the classical and quantum simulation results.""" + for link in original.link["flowrate"].columns: + orig_value = original.link["flowrate"][link].iloc[0] + new_value = new.link["flowrate"][link].iloc[0] + message = f"Flowrate {link}: {new_value} not within tolerance of original {orig_value}" + assert calculate_small_differences(orig_value, new_value), message + + for node in original.node["pressure"].columns: + orig_value = original.node["pressure"][node].iloc[0] + new_value = new.node["pressure"][node].iloc[0] + message = f"Pressure {node}: {new_value} not within tolerance of original {orig_value}" + assert calculate_small_differences(orig_value, new_value), message + + +def run_classical_EPANET_simulation(): + """Runs WNTR using classical EPANET interface.""" + wn = wntr.network.WaterNetworkModel(INP_FILE) + sim = wntr.sim.EpanetSimulator(wn) + return sim.run_sim() + + +def run_FullQuboPolynomialSimulator(): + """Runs QuboPolynomialSolver.""" + wn = wntr.network.WaterNetworkModel(INP_FILE) + nqbit = 9 + step = 0.5 / (2**nqbit - 1) + flow_encoding = PositiveQbitEncoding( + nqbit=nqbit, step=step, offset=+1.5, var_base_name="x" + ) + + nqbit = 9 + step = 50 / (2**nqbit - 1) + head_encoding = PositiveQbitEncoding( + nqbit=nqbit, step=step, offset=+50.0, var_base_name="x" + ) + + sim = QuboPolynomialSolver( + wn, flow_encoding=flow_encoding, head_encoding=head_encoding + ) + + x = generate_random_valid_sample(sim) + x0 = list(x.values()) + + num_temp = 2000 + Tinit = 1e1 + Tfinal = 1e-1 + Tschedule = np.linspace(Tinit, Tfinal, num_temp) + Tschedule = np.append(Tschedule, Tfinal * np.ones(1000)) + Tschedule = np.append(Tschedule, np.zeros(1000)) + _, _, sol, res = sim.solve( + init_sample=x0, Tschedule=Tschedule, save_traj=True, verbose=False + ) + + +@pytest.fixture(scope="module") +def classical_EPANET_results(): + """Get the results from the classical NR solver.""" + return run_classical_EPANET_simulation() + + +def test_FullQuboPolynomialSimulator(classical_EPANET_results): + """Checks that the Quantum EPANET classical linear solver is equivalent with the classical result.""" + _ = run_FullQuboPolynomialSimulator() + # compare_results(classical_EPANET_results, qubopoly_results) diff --git a/wntr_quantum/design/__init__.py b/wntr_quantum/design/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/wntr_quantum/design/qubo_pipe_diam.py b/wntr_quantum/design/qubo_pipe_diam.py new file mode 100644 index 0000000..10c0900 --- /dev/null +++ b/wntr_quantum/design/qubo_pipe_diam.py @@ -0,0 +1,820 @@ +import itertools +from collections import OrderedDict +from copy import deepcopy +from typing import List +from typing import Tuple +import numpy as np +import sparse +from quantum_newton_raphson.newton_raphson import newton_raphson +from qubops.encodings import BaseQbitEncoding +from qubops.encodings import PositiveQbitEncoding +from qubops.mixed_solution_vector import MixedSolutionVector_V2 as MixedSolutionVector +from qubops.qubops_mixed_vars import QUBOPS_MIXED +from qubops.solution_vector import SolutionVector_V2 as SolutionVector +from wntr.epanet.util import FlowUnits +from wntr.epanet.util import HydParam +from wntr.epanet.util import from_si +from wntr.epanet.util import to_si +from wntr.network import WaterNetworkModel +from wntr.sim import aml +from wntr.sim.aml import Model +from wntr.sim.solvers import SolverStatus +from ..sampler.simulated_annealing import SimulatedAnnealing +from ..sampler.step.random_step import SwitchIncrementalStep +from ..sim.models.chezy_manning import cm_resistance_value +from ..sim.models.chezy_manning import get_pipe_design_chezy_manning_qubops_matrix +from ..sim.models.darcy_weisbach import dw_resistance_value +from ..sim.models.darcy_weisbach import get_pipe_design_darcy_wesibach_qubops_matrix +from ..sim.models.mass_balance import get_mass_balance_qubops_matrix +from ..sim.qubo_hydraulics import create_hydraulic_model_for_qubo + + +class QUBODesignPipeDiameter(object): + """Design problem solved using a QUBO approach.""" + + def __init__( + self, + wn: WaterNetworkModel, + flow_encoding: BaseQbitEncoding, + head_encoding: BaseQbitEncoding, + pipe_diameters: List, + head_lower_bound: float, + weight_cost: float = 1e-1, + weight_pressure: float = 1.0, + ): # noqa: D417 + """Initialize the designer object. + + Args: + wn (WaterNetworkModel): Water network + flow_encoding (BaseQbitEncoding): binary encoding for the flows + head_encoding (BaseQbitEncoding): binary encoding for the heads + pipe_diameters (List): List of pipe diameters in SI + head_lower_bound (float): minimum value for the head pressure values (US units) + weight_cost (float, optional): weight for the cost optimization. Defaults to 1e-1. + weight_pressure (float, optional): weight for the pressure optimization. Defaults to 1. + """ + # water network + self.wn = wn + + # pipe diameters (converts to meter) + self.pipe_diameters = [p / 1000 for p in pipe_diameters] + self.num_diameters = len(pipe_diameters) + + # create the encoding vectors for the sign of the flows + self.sign_flow_encoding = PositiveQbitEncoding( + nqbit=1, step=2, offset=-1, var_base_name="x" + ) + + # create the solution vector for the sign + self.sol_vect_signs = SolutionVector( + wn.num_pipes, encoding=self.sign_flow_encoding + ) + + # store the flow encoding and create solution vector + self.flow_encoding = flow_encoding + self.sol_vect_flows = SolutionVector(wn.num_pipes, encoding=flow_encoding) + if np.min(self.flow_encoding.get_possible_values()) < 0: + raise ValueError( + "The encoding of the flows must only take positive values." + ) + + # store the heqd encoding and create solution vector + self.head_encoding = head_encoding + self.sol_vect_heads = SolutionVector(wn.num_junctions, encoding=head_encoding) + + # one hot encoding for the pipe coefficients + self.num_hot_encoding = wn.num_pipes * self.num_diameters + self.pipe_encoding = PositiveQbitEncoding(1, "x_", offset=0, step=1) + self.sol_vect_pipes = SolutionVector(self.num_hot_encoding, self.pipe_encoding) + + # mixed solution vector + self.mixed_solution_vector = MixedSolutionVector( + [ + self.sol_vect_signs, + self.sol_vect_flows, + self.sol_vect_heads, + self.sol_vect_pipes, + ] + ) + + # basic hydraulic model + self.model, self.model_updater = create_hydraulic_model_for_qubo(wn) + + # valies of the pipe diameters/coefficients + self.get_pipe_data() + + # weight for the cost equation + self.weight_cost = weight_cost + + # weight for the pressure penalty + self.weight_pressure = weight_pressure + + # lower bound for the pressure + head_lower_bound = from_si(FlowUnits.CFS, head_lower_bound, HydParam.Length) + self.head_lower_bound = head_lower_bound + self.head_upper_bound = 1e3 # 10 * head_lower_bound # is that enough ? + self.target_pressure = head_lower_bound + + # set up the sampler + self.sampler = SimulatedAnnealing() + + # create the matrices + self.create_index_mapping() + self.matrices = self.initialize_matrices() + self.matrices = tuple(sparse.COO(m) for m in self.matrices) + + # create the QUBO MIXED instance + self.qubo = QUBOPS_MIXED(self.mixed_solution_vector, {"sampler": self.sampler}) + + # create the qubo dictionary + self.qubo.qubo_dict = self.qubo.create_bqm(self.matrices, strength=0) + + # add the constraints on the pipe diameter switch + # note that with our custom sampler and step this is not needed + # self.add_switch_constraints(strength=0) + + # add constraints on the pressuyre values + self.add_pressure_equality_constraints() + + self.var_names = sorted(self.qubo.qubo_dict.variables) + self.qubo.create_variables_mapping() + + # compute the indices of the pipe diameter switch variables + self.switch_variables = self.get_switch_variables_index() + + # create step function + self.step_func = SwitchIncrementalStep( + self.var_names, + self.qubo.mapped_variables, + self.qubo.index_variables, + step_size=10, + switch_variable_index=self.switch_variables, + ) + + def get_switch_variables_index(self): + """Computes the indices of the switch variables, i.e. the pipe diameter switch.""" + idx_init = self.wn.num_links * 2 + self.wn.num_junctions + idx_final = idx_init + self.num_diameters * self.wn.num_pipes + return ( + np.arange(idx_init, idx_final) + .reshape(self.wn.num_pipes, self.num_diameters) + .tolist() + ) + + def get_dw_pipe_coefficients(self, link): + """Get the pipe coefficients for a specific link with DW. + + Args: + link (_type_): _description_ + """ + values = [] + for diam in self.pipe_diameters: + + # convert values from SI to epanet internal + roughness_us = 0.001 * from_si( + FlowUnits.CFS, link.roughness, HydParam.Length + ) + diameter_us = from_si(FlowUnits.CFS, diam, HydParam.Length) + length_us = from_si(FlowUnits.CFS, link.length, HydParam.Length) + + # compute the resistance value fit coefficients + values.append( + dw_resistance_value( + self.model.dw_k, + roughness_us, + diameter_us, + self.model.dw_diameter_exp, + length_us, + ) + ) + return values + + def get_cm_pipe_coefficients(self, link): + """Get the pipe coefficients for a specific link with CM. + + Args: + link (_type_): _description_ + """ + values = [] + for diam in self.pipe_diameters: + + # convert values from SI to epanet internal + roughness_us = link.roughness + diameter_us = from_si(FlowUnits.CFS, diam, HydParam.Length) + length_us = from_si(FlowUnits.CFS, link.length, HydParam.Length) + + # compute the resistance value fit coefficients + values.append( + cm_resistance_value( + self.model.cm_k, + roughness_us, + self.model.cm_roughness_exp, + diameter_us, + self.model.cm_diameter_exp, + length_us, + ) + ) + return values + + def get_pipe_prices(self, link): + """Get the price of the pipe for the different diameters. + + Args: + link (wn.link): pipe info + """ + + def _compute_price(diameter, length): + """Price model of the pipe. + + Args: + diameter (float): diameter + length (float): length + + Returns: + float: price + """ + return np.pi * diameter * length / 1e5 + + prices = [] + for diam in self.pipe_diameters: + + # convert values from SI to epanet internal + diameter_us = from_si(FlowUnits.CFS, diam, HydParam.Length) + length_us = from_si(FlowUnits.CFS, link.length, HydParam.Length) + + # compute the price + prices.append(_compute_price(diameter_us, length_us)) + + return prices + + def get_pipe_data(self): + """Get the parameters of the AML model related to each pipe. + + Returns: + Dict: possible pipe coefficients for each coefficients + """ + if not hasattr(self.model, "pipe_coefficients"): + self.model.pipe_coefficients = aml.ParamDict() + + if not hasattr(self.model, "pipe_coefficients_indices"): + self.model.pipe_coefficients_indices = aml.ParamDict() + + if not hasattr(self.model, "pipe_prices"): + self.model.pipe_prices = aml.ParamDict() + + # select model + if self.wn.options.hydraulic.headloss == "C-M": + get_pipe_coeff_values = self.get_cm_pipe_coefficients + + elif self.wn.options.hydraulic.headloss == "D-W": + get_pipe_coeff_values = self.get_dw_pipe_coefficients + + # loop over pipes + idx_start = 0 + for link_name in self.wn.pipe_name_list: + + # get the link + link = self.wn.get_link(link_name) + + # compute the pipe coeffcient values + pipe_coeffs_values = get_pipe_coeff_values(link) + if link_name in self.model.pipe_coefficients: + self.model.pipe_coefficients[link_name].value = pipe_coeffs_values + else: + self.model.pipe_coefficients[link_name] = aml.Param(pipe_coeffs_values) + + # compute the pipe price + prices = self.get_pipe_prices(link) + if link_name in self.model.pipe_prices: + self.model.pipe_prices[link_name].value = prices + else: + self.model.pipe_prices[link_name] = aml.Param(prices) + + # compute the indices + idx_end = idx_start + len(pipe_coeffs_values) + indices = list(range(idx_start, idx_end)) + if link_name in self.model.pipe_coefficients_indices: + self.model.pipe_coefficients_indices[link_name].value = indices + else: + self.model.pipe_coefficients_indices[link_name] = aml.Param(indices) + idx_start = len(pipe_coeffs_values) + + def verify_encoding(self): + """Print info regarding the encodings.""" + hres = self.head_encoding.get_average_precision() + hvalues = np.sort(self.head_encoding.get_possible_values()) + fres = self.flow_encoding.get_average_precision() + fvalues = np.sort(self.flow_encoding.get_possible_values()) + print("Head Encoding : %f => %f (res: %f)" % (hvalues[0], hvalues[-1], hres)) + print( + "Flow Encoding : %f => %f | %f => %f (res: %f)" + % (-fvalues[-1], -fvalues[0], fvalues[0], fvalues[-1], fres) + ) + + def enumerates_classical_solutions(self, convert_to_si=True): + """Generates the classical solution.""" + encoding = [] + for idiam in range(self.num_diameters): + tmp = [0] * self.num_diameters + tmp[idiam] = 1 + encoding.append(tmp) + solutions = {} + print("price \t diameters \t variables\t energy") + for params in itertools.product(encoding, repeat=self.wn.num_pipes): + pvalues = [] + for p in params: + pvalues += p + price, diameters = self.get_pipe_info_from_hot_encoding(pvalues) + sol, encoded_sol, bin_rep_sol, energy, cvg = self.classical_solution( + pvalues, convert_to_si=convert_to_si + ) + print(price, diameters, sol, energy[0]) + solutions[tuple(diameters)] = (sol, encoded_sol, bin_rep_sol, energy, cvg) + return solutions + + def convert_solution_to_si(self, solution: np.ndarray) -> np.ndarray: + """Converts the solution to SI. + + Args: + solution (array): solution vectors in US units + + Returns: + Tuple: solution in SI + """ + num_heads = self.wn.num_junctions + num_pipes = self.wn.num_pipes + new_sol = np.zeros_like(solution) + for ip in range(num_pipes): + new_sol[ip] = to_si(FlowUnits.CFS, solution[ip], HydParam.Flow) + for ih in range(num_pipes, num_pipes + num_heads): + new_sol[ih] = to_si(FlowUnits.CFS, solution[ih], HydParam.Length) + return new_sol + + def convert_solution_from_si(self, solution: np.ndarray) -> np.ndarray: + """Converts the solution to SI. + + Args: + solution (array): solution vectors in SI + + Returns: + Tuple: solution in US units + """ + num_heads = self.wn.num_junctions + num_pipes = self.wn.num_pipes + new_sol = np.zeros_like(solution) + for ip in range(num_pipes): + new_sol[ip] = from_si(FlowUnits.CFS, solution[ip], HydParam.Flow) + for ih in range(num_pipes, num_pipes + num_heads): + new_sol[ih] = from_si(FlowUnits.CFS, solution[ih], HydParam.Length) + return new_sol + + def classical_solution( + self, parameters, max_iter: int = 100, tol: float = 1e-10, convert_to_si=True + ): + """Computes the classical solution for a values of the hot encoding parameters. + + Args: + parameters (List): list of the one hot encoding values e.g. [1,0,1,0] + max_iter (int, optional): number of iterations of the NR. Defaults to 100. + tol (float, optional): Toleracne of the NR. Defaults to 1e-10. + convert_to_si (bool): convert to si + + Returns: + np.mdarray : solution + """ + P0 = self.matrices[0].todense() + P1 = self.matrices[1].todense() + P2 = self.matrices[2].todense() + P3 = self.matrices[3].todense() + P4 = self.matrices[4].todense() + + num_heads = self.wn.num_junctions + num_signs = self.wn.num_pipes + num_pipes = self.wn.num_pipes + num_vars = num_heads + 2 * num_pipes + original_parameters = deepcopy(parameters) + if self.wn.options.hydraulic.headloss == "C-M": + p0 = P0[:-1].reshape(-1, 1) + p1 = P1[:-1, num_signs:num_vars] + P2.sum(1)[:-1, num_signs:num_vars] + p2 = P4.sum(1)[:-1, num_pipes:num_vars, num_pipes:num_vars].sum(-2) + parameters = np.array([0] * num_vars + parameters) + p2 = (parameters * p2).sum(-1) + + elif self.wn.options.hydraulic.headloss == "D-W": + + # P0 matrix + p0 = np.copy(P0[:-1]) + # add the k0 term without sgin to p0 + p0 += ( + (parameters * P2[:-1, :num_signs, num_vars:]) + .sum(-1) + .sum(-1) + .reshape(-1, 1) + ) + + # P1 matrix + p1 = P1[:-1, num_pipes:num_vars] + P2.sum(1)[:-1, num_pipes:num_vars] + + # add the terms in k1 + p1 += ( + (parameters * P3[:-1, :num_signs, num_signs:num_vars, num_vars:]) + .sum(1) + .sum(-1) + ) + + # P2 matrix + p2 = ( + ( + parameters + * P4[ + :-1, + :num_signs, + num_signs:num_vars, + num_signs:num_vars, + num_vars:, + ] + ) + .sum(1) + .sum(-1) + .sum(-1) + ) + + def func(input): + input = input.reshape(-1, 1) + sign = np.sign(input) + sol = p0 + p1 @ input + (p2 @ (sign * input * input)) + return sol.reshape(-1) + + initial_point = np.random.rand(num_pipes + num_heads) + res = newton_raphson(func, initial_point, max_iter=max_iter, tol=tol) + sol = res.solution + converged = np.allclose(func(sol), 0) + if not converged: + print("Warning solution not converged") + + # get the closest encoded solution and binary encoding + bin_rep_sol = [] + for i in range(num_pipes): + bin_rep_sol.append(int(sol[i] > 0)) + + encoded_sol = np.zeros_like(sol) + for idx, s in enumerate(sol): + val, bin_rpr = self.mixed_solution_vector.encoded_reals[ + idx + num_pipes + ].find_closest(np.abs(s)) + bin_rep_sol.append(bin_rpr) + encoded_sol[idx] = np.sign(s) * val + + # add the pipe parameter bnary variables + for p in original_parameters: + bin_rep_sol.append(p) + + if convert_to_si: + sol = self.convert_solution_to_si(sol) + encoded_sol = self.convert_solution_to_si(encoded_sol) + + # remove the height of the junctions + for i in range(self.wn.num_junctions): + sol[num_pipes + i] -= self.wn.nodes[ + self.wn.junction_name_list[i] + ].elevation + encoded_sol[num_pipes + i] -= self.wn.nodes[ + self.wn.junction_name_list[i] + ].elevation + + # compute the qubo energy of the solution + eref = self.qubo.energy_binary_rep(bin_rep_sol) + + return (sol, encoded_sol, bin_rep_sol, eref, converged) + + def get_cost_matrix(self, matrices): + """Add the equation that ar sued to maximize the pipe coefficiens and therefore minimize the diameter. + + Args: + matrices (tuple): The matrices + """ + P0, P1, P2, P3, P4 = matrices + + # loop over all the pipe coeffs + istart = 2 * self.sol_vect_flows.size + self.sol_vect_heads.size + index_over = self.wn.pipe_name_list + + # loop over all the pipe coeffs + for link_name in index_over: + for pipe_cost, pipe_idx in zip( + self.model.pipe_prices[link_name].value, + self.model.pipe_coefficients_indices[link_name].value, + ): + P1[-1, istart + pipe_idx] = self.weight_cost * pipe_cost + return P0, P1, P2, P3, P4 + + def initialize_matrices(self) -> Tuple: + """Creates the matrices of the polynomial system of equation. + + math :: + + + """ + num_equations = len(list(self.model.cons())) + 1 # +1 for cost equation + num_variables = ( + 2 * len(self.model.flow) + len(self.model.head) + self.num_hot_encoding + ) + + # must transform that to coo + P0 = np.zeros((num_equations, 1)) + P1 = np.zeros((num_equations, num_variables)) + P2 = np.zeros((num_equations, num_variables, num_variables)) + P3 = np.zeros((num_equations, num_variables, num_variables, num_variables)) + P4 = np.zeros( + (num_equations, num_variables, num_variables, num_variables, num_variables) + ) + + # get the mass balance matrix + (P0, P1, P2, P3) = get_mass_balance_qubops_matrix( + self.model, + self.wn, + (P0, P1, P2, P3), + self.flow_index_mapping, + convert_to_us_unit=True, + ) + + # shortcut + matrices = (P0, P1, P2, P3, P4) + + # get the headloss matrix contributions + if self.wn.options.hydraulic.headloss == "C-M": + matrices = get_pipe_design_chezy_manning_qubops_matrix( + self.model, + self.wn, + matrices, + self.flow_index_mapping, + self.head_index_mapping, + ) + elif self.wn.options.hydraulic.headloss == "D-W": + matrices = get_pipe_design_darcy_wesibach_qubops_matrix( + self.model, + self.wn, + matrices, + self.flow_index_mapping, + self.head_index_mapping, + ) + else: + raise ValueError("Calculation only possible with C-M or D-W") + + matrices = self.get_cost_matrix(matrices) + + return matrices + + @staticmethod + def combine_flow_values(solution: List) -> List: + """Combine the values of the flow sign*abs. + + Args: + solution (List): solution vector + + Returns: + List: solution vector + """ + flow = [] + for sign, abs in zip(solution[0], solution[1]): + flow.append(sign * abs) + return flow + solution[2] + + @staticmethod + def flatten_solution_vector(solution: Tuple) -> List: + """Flattens the solution vector. + + Args: + solution (tuple): tuple of ([flows], [heads]) + + Returns: + List: a flat list of all the variables + """ + sol_tmp = [] + for s in solution[:-1]: + sol_tmp += s + return sol_tmp, solution[-1] + + def get_pipe_info_from_hot_encoding(self, hot_encoding): + """_summary_. + + Args: + hot_encoding (_type_): _description_ + """ + hot_encoding = np.array(hot_encoding) + + pipe_prices = [] + for link_name in self.wn.pipe_name_list: + pipe_prices += self.model.pipe_prices[link_name].value + pipe_prices = np.array(pipe_prices) + total_price = (pipe_prices * hot_encoding).sum() + + pipe_diameters = 1000 * np.array(self.pipe_diameters * self.wn.num_pipes) + pipe_diameters = ( + (pipe_diameters * hot_encoding).reshape(-1, self.num_diameters).sum(-1) + ) + + return total_price, pipe_diameters + + def load_data_in_model(self, model: Model, data: np.ndarray): + """Loads some data in the model. + + Remark: + This routine replaces `load_var_values_from_x` without reordering the vector elements + + Args: + model (Model): AML model from WNTR + data (np.ndarray): data to load + """ + shift_head_idx = self.wn.num_links + for var in model.vars(): + if var.name in self.flow_index_mapping: + idx = self.flow_index_mapping[var.name]["sign"] + elif var.name in self.head_index_mapping: + idx = self.head_index_mapping[var.name] - shift_head_idx + var.value = data[idx] + + def extract_data_from_model(self, model: Model) -> np.ndarray: + """Loads some data in the model. + + Args: + model (Model): AML model from WNTR + + Returns: + np.ndarray: data extracted from model + """ + data = [None] * len(list(model.vars())) + shift_head_idx = self.wn.num_links + for var in model.vars(): + if var.name in self.flow_index_mapping: + idx = self.flow_index_mapping[var.name]["sign"] + elif var.name in self.head_index_mapping: + idx = self.head_index_mapping[var.name] - shift_head_idx + data[idx] = var.value + return data + + def create_index_mapping(self) -> None: + """Creates the index maping for qubops matrices.""" + # init the idx + idx = 0 + + # number of variables that are flows + num_flow_var = len(self.model.flow) + num_head_var = len(self.model.head) + + # get the indices for the sign/abs value of the flow + self.flow_index_mapping = OrderedDict() + for _, val in self.model.flow.items(): + if val.name not in self.flow_index_mapping: + self.flow_index_mapping[val.name] = { + "sign": None, + "absolute_value": None, + } + self.flow_index_mapping[val.name]["sign"] = idx + self.flow_index_mapping[val.name]["absolute_value"] = idx + num_flow_var + idx += 1 + + # get the indices for the heads + idx = 0 + self.head_index_mapping = OrderedDict() + for _, val in self.model.head.items(): + self.head_index_mapping[val.name] = 2 * num_flow_var + idx + idx += 1 + + # get the indices for the pipe diameters + idx = 0 + self.pipe_diameter_index_mapping = OrderedDict() + for _, val in self.model.flow.items(): + if val.name not in self.pipe_diameter_index_mapping: + self.pipe_diameter_index_mapping[val.name] = OrderedDict() + for idiam in range(self.num_diameters): + self.pipe_diameter_index_mapping[val.name][idiam] = ( + 2 * num_flow_var + num_head_var + idx + ) + idx += 1 + + def add_switch_constraints( + self, + strength: float = 1e6, + ): + """Add the conrains regarding the pipe diameter switch.""" + # add constraints on the hot encoding + # the sum of each hot encoding variable of a given pipe must equals 1 + istart = ( + self.sol_vect_signs.size + + self.sol_vect_flows.size + + self.sol_vect_heads.size + ) + for i in range(self.sol_vect_flows.size): + + # create the expression [(x0, 1), (x1, 1), ...] + expr = [] + iend = istart + self.num_diameters + for ivar in range(istart, iend): + expr.append( + ( + self.mixed_solution_vector.encoded_reals[ivar] + .variables[0] + .name, + 1, + ) + ) + # add the constraints + self.qubo.qubo_dict.add_linear_equality_constraint( + expr, lagrange_multiplier=strength, constant=-1 + ) + istart += self.num_diameters + + def add_pressure_equality_constraints(self): + """Add the conrains regarding the presure.""" + # add constraint on head pressures + istart = 2 * self.sol_vect_flows.size + for i in range(self.sol_vect_heads.size): + # print(tmp) + self.qubo.qubo_dict.add_linear_equality_constraint( + self.qubo.all_expr[istart + i], + lagrange_multiplier=self.weight_pressure, + constant=-self.target_pressure, + ) + # print(cst) + + def add_pressure_constraints(self, fractional_factor=100): + """Add the conrains regarding the presure.""" + # add constraint on head pressures + istart = 2 * self.sol_vect_flows.size + for i in range(self.sol_vect_heads.size): + tmp = [] + for k, v in self.qubo.all_expr[istart + i]: + tmp.append((k, int(fractional_factor * v))) + # print(tmp) + _ = self.qubo.qubo_dict.add_linear_inequality_constraint( + tmp, + lagrange_multiplier=self.weight_pressure, + label="head_%s" % i, + lb=fractional_factor * self.head_lower_bound, + ub=fractional_factor * self.head_upper_bound, + penalization_method="slack", + cross_zero=True, + ) + # print(cst) + + def solve( # noqa: D417 + self, init_sample, Tschedule, save_traj=False, verbose=False + ) -> Tuple: + """Sample the qubo problem. + + Args: + init_sample (list): initial sample for the optimization + Tschedule (list): temperature schedule for the optimization + save_traj (bool, optional): save the trajectory. Defaults to False. + verbose (bool, optional): print status. Defaults to False. + + Returns: + Tuple: Solver status, str, solution, SimulatedAnnealingResults + """ + res = self.sampler.sample( + self.qubo, + init_sample=init_sample, + Tschedule=Tschedule, + take_step=self.step_func, + save_traj=save_traj, + verbose=verbose, + ) + + # extract and decode the solution + idx_min = np.array([e for e in res.energies]).argmin() + # idx_min = -1 + sol = res.trajectory[idx_min] + sol = self.qubo.decode_solution(np.array(sol)) + + # extract the hot encoding of the pipe + pipe_hot_encoding = sol[3] + + # convert the solution to SI + sol = self.combine_flow_values(sol) + sol = self.convert_solution_to_si(sol) + + # remove the height of the junction + for i in range(self.wn.num_junctions): + sol[self.wn.num_pipes + i] -= self.wn.nodes[ + self.wn.junction_name_list[i] + ].elevation + + # load data in the AML model + self.model.set_structure() + self.load_data_in_model(self.model, sol) + + # get pipe info from one hot + self.total_price, self.optimal_diameters = self.get_pipe_info_from_hot_encoding( + pipe_hot_encoding + ) + + # returns + return ( + SolverStatus.converged, + "Solved Successfully", + sol, + res, + self.total_price, + self.optimal_diameters, + ) diff --git a/wntr_quantum/sampler/simulated_annealing.py b/wntr_quantum/sampler/simulated_annealing.py new file mode 100644 index 0000000..a77e53a --- /dev/null +++ b/wntr_quantum/sampler/simulated_annealing.py @@ -0,0 +1,239 @@ +from copy import deepcopy +from dataclasses import dataclass +import numpy as np +from tqdm import tqdm + + +def generate_random_valid_sample(net): + """Generate a random sample that respects quadratization. + + Args: + net (QuboPolynomialSolver): an instance of the QuboPolynomialSolver + """ + sample = {} + for iv, v in enumerate(sorted(net.qubo.qubo_dict.variables)): + sample[v] = np.random.randint(2) + + for v in net.qubo.mapped_variables[:7]: + sample[v] = 1 + sample[net.qubo.mapped_variables[7]] = 0 + + for v, _ in sample.items(): + if v not in net.qubo.mapped_variables: + var_tmp = v.split("*") + itmp = 0 + for vtmp in var_tmp: + if itmp == 0: + new_val = sample[vtmp] + itmp = 1 + else: + new_val *= sample[vtmp] + + sample[v] = new_val + return sample + + +def modify_solution_sample(net, solution, modify=["signs", "flows", "heads"]) -> list: + """Modiy the solution sample to change values of the signs/flows/heads. + + Args: + net (QuboPolynomialSolver): an instance of the QuboPolynomialSolver + solution (list): the sample that encoded the true solution + modify (list, optional): what to change. Defaults to ["signs", "flows", "heads"]. + + Returns: + List: new sample + """ + + def flatten_list(lst): + out = [] + for elmt in lst: + if not isinstance(elmt, list): + out += [elmt] + else: + out += elmt + return out + + from copy import deepcopy + + for m in modify: + if m not in ["signs", "flows", "heads"]: + raise ValueError("modify %s not recognized" % m) + + mod_bin_rep_sol = deepcopy(solution) + num_pipes = net.wn.num_pipes + num_heads = net.wn.num_junctions + + # modify sign + if "signs" in modify: + for i in range(num_pipes): + mod_bin_rep_sol[i] = np.random.randint(2) + + # modify flow value + if "flows" in modify: + for i in range(num_pipes, 2 * num_pipes): + mod_bin_rep_sol[i] = list( + np.random.randint(2, size=net.flow_encoding.nqbit) + ) + + # modify head values + if "heads" in modify: + for i in range(2 * num_pipes, 2 * num_pipes + num_heads): + mod_bin_rep_sol[i] = list( + np.random.randint(2, size=net.head_encoding.nqbit) + ) + + x = net.qubo.extend_binary_representation(flatten_list(mod_bin_rep_sol)) + return x + + +@dataclass +class SimulatedAnnealingResults: + """Result of the simulated anneling.""" + + res: list + energies: list + trajectory: list + + +class SimulatedAnnealing: # noqa: D101 + + def __init__(self): # noqa: D107 + self.Tschedule = None + self.init_sample = None + self.take_step = None + self.save_traj = False + + @property + def Tschedule(self): # noqa: D102 + return self._Tschedule + + @Tschedule.setter + def Tschedule(self, tschedule): + self._Tschedule = tschedule + + @property + def init_sample(self): # noqa: D102 + return self._init_sample + + @init_sample.setter + def init_sample(self, sample): + self._init_sample = sample + + @property + def take_step(self): # noqa: D102 + return self._take_step + + @take_step.setter + def take_step(self, step): + self._take_step = step + + def sample( + self, + qubo, + Tschedule=None, + init_sample=None, + take_step=None, + save_traj=False, + verbose=False, + ): + """Sample the problem. + + Args: + qubo (qubo solver): qubo solver + Tschedule (list, optional): The temperature schedule + init_sample (list, optional): initial sample for the optimzation. Defaults to None. + take_step (callable, optional): Callable to obtain new sample. Defaults to None. + save_traj (bool, optional): save the trajectory. Defaults to False + verbose (bool, optional): print stuff + """ + + def bqm_energy(qubo, input, var_names): + """Computes the energy of the sample. + + Args: + qubo (qubo_solver): qubo solver + input (list): sample + var_names (list): names of the variables + + + Returns: + float: qubo energy + """ + return qubo.energy_binary_rep( + np.array(input)[qubo.index_variables].tolist() + ) + + if Tschedule is not None: + self.Tschedule = Tschedule + + if init_sample is not None: + self.init_sample = init_sample + + if take_step is not None: + self.take_step = take_step + + self.save_traj = save_traj + + self.bqm = qubo.qubo_dict + + # check that take_step is callable + if not callable(self.take_step): + raise ValueError("take_step must be callable") + + # define the variable names + self.var_names = sorted(self.bqm.variables) + + # define the initial state + if self.init_sample is None: + current_sample = generate_random_valid_sample(self.bqm) + else: + current_sample = init_sample + + # init the traj + trajectory = [] + if self.save_traj: + trajectory.append(current_sample) + + # initialize the energy + energies = [] + e_current = bqm_energy(qubo, current_sample, self.var_names) + energies.append(e_current) + + # loop over the temp schedule + for T in tqdm(self.Tschedule): + + # new point + new_sample = self.take_step(deepcopy(current_sample), verbose=verbose) + e_new = bqm_energy(qubo, new_sample, self.var_names) + + # accept/reject + if e_new < e_current: + if verbose: + print("E : %f => %f" % (e_current, e_new)) + current_sample = deepcopy(new_sample) + e_current = e_new + + else: + if verbose: + print("E : %f => %f" % (e_current, e_new)) + + p = np.exp((e_current - e_new) / (T + 1e-12)) + eps = np.random.rand() + + if eps < p: + current_sample = deepcopy(new_sample) + e_current = e_new + + else: + if verbose: + print("rejected") + pass + + if self.save_traj: + trajectory.append(current_sample) + energies.append(e_current) + + if verbose: + print("-----------------") + return SimulatedAnnealingResults(current_sample, energies, trajectory) diff --git a/wntr_quantum/sampler/step/base_step.py b/wntr_quantum/sampler/step/base_step.py new file mode 100644 index 0000000..83f2f99 --- /dev/null +++ b/wntr_quantum/sampler/step/base_step.py @@ -0,0 +1,136 @@ +import numpy as np + + +class BaseStep: # noqa: D101 + def __init__( # noqa: D417 + self, + var_names, + single_var_names, + single_var_index, + step_size=1, + optimize_values=None, + ): + """Propose a new solution vector. + + Args: + var_names (list): names of the variables in the problem + single_var_names (_type_): list of the single variables names e.g. x_001_002 + single_var_index (_type_): index of the single variables + step_size (int, optional): size of the steps + optimize_values (list, optional): index of the values to optimize + """ + self.var_names = var_names + self.single_var_names = single_var_names + self.single_var_index = single_var_index + self.num_single_var = len(self.single_var_names) + self.high_order_terms_mapping = self.define_mapping() + + self.value_names = np.unique( + [self._get_variable_root_name(n) for n in single_var_names] + ) + self.index_values = {v: [] for v in self.value_names} + for n, idx in zip(self.single_var_names, self.single_var_index): + val = self._get_variable_root_name(n) + self.index_values[val].append(idx) + + self.step_size = step_size + self.optimize_values = optimize_values + if self.optimize_values is None: + self.optimize_values = list(np.arange(len(self.value_names))) + + @staticmethod + def _get_variable_root_name(var_name) -> str: + """Extract the root name of the variables. + + Args: + var_name (str): variable name + + Returns: + str: root name + """ + return "_".join(var_name.split("_")[:2]) + + def define_mapping(self): + """Define the mapping of the higher order terms. + + Returns: + list: mapping of the higher order terms + """ + high_order_terms_mapping = [] + + # loop over all the variables + for iv, v in enumerate(self.var_names): + + # if we have a cmomposite variables e.g. x_001 * x_002 we ignore it + if v not in self.single_var_names: + high_order_terms_mapping.append(None) + + # if the variables is a unique one e.g. x_011 + else: + high_order_terms_mapping.append({}) + # we loop over all the variables + for iiv, vv in enumerate(self.var_names): + if v != vv: + if v in vv: + + var_tmp = vv.split("*") + idx_terms = [] + for vtmp in var_tmp: + idx = self.single_var_index[ + self.single_var_names.index(vtmp) + ] + idx_terms.append(idx) + high_order_terms_mapping[-1][iiv] = idx_terms + + return high_order_terms_mapping + + def fix_constraint(self, x, idx): + """Ensure that the solution vectors respect quadratization. + + Args: + x (list): sample + idx (int): index of the element that has changed + + Returns: + list: new sampel that respects quadratization constraints + """ + fix_var = self.high_order_terms_mapping[idx] + for idx_fix, idx_prods in fix_var.items(): + x[idx_fix] = np.array([x[i] for i in idx_prods]).prod() + return x + + def verify_quadratic_constraints(self, data): + """Check if quadratic constraints are respected or not. + + Args: + data (list): sample + """ + for v, d in zip(self.var_names, data): + if v not in self.single_var_names: + var_tmp = v.split("*") + itmp = 0 + for vtmp in var_tmp: + idx = self.single_var_index[self.single_var_names.index(vtmp)] + if itmp == 0: + dcomposite = data[idx] + itmp = 1 + else: + dcomposite *= data[idx] + if d != dcomposite: + print("Error in the quadratic contraints") + print("%s = %d" % (v, d)) + for vtmp in var_tmp: + idx = self.single_var_index[self.single_var_names.index(vtmp)] + print("%s = %d" % (vtmp, data[idx])) + + def __call__(self, x, verbose=False): + """Call function of the method. + + Args: + x (list): sample + verbose (bool): print stuff + + Returns: + list: new sample + """ + raise NotImplementedError("Implement a __call__ method") diff --git a/wntr_quantum/sampler/step/random_step.py b/wntr_quantum/sampler/step/random_step.py new file mode 100644 index 0000000..53c1545 --- /dev/null +++ b/wntr_quantum/sampler/step/random_step.py @@ -0,0 +1,232 @@ +from copy import deepcopy +import numpy as np +from .base_step import BaseStep + + +class RandomStep(BaseStep): # noqa: D101 + + def __call__(self, x, verbose=False): + """Call function of the method. + + Args: + x (list): initial sample + verbose (bool): print stuff + + Returns: + list: proposed sample + """ + random_val_name = np.random.choice(self.value_names[self.optimize_values]) + idx = self.index_values[random_val_name] + vidx = np.random.choice(idx) + x[vidx] = int(not (x[vidx])) + self.fix_constraint(x, vidx) + return x + + +class IncrementalStep(BaseStep): # noqa: D101 + + def __call__(self, x, verbose=False): + """Call function of the method. + + Args: + x (list): initial sample + verbose (bool): print stuff + + Returns: + list: proposed sample + """ + num_var_changed = np.random.randint(len(self.optimize_values)) + random_val_name_list = np.random.choice( + self.value_names[self.optimize_values], size=num_var_changed + ) + + for random_val_name in random_val_name_list: + idx = self.index_values[random_val_name] + data = np.array(x)[idx] + width = len(data) + + # determine the max val + max_val = int("1" * width, base=2) + + # check if we reach min/max val + max_val_check = data.prod() == 1 + min_val_check = data.sum() == 0 + + # convert to int value + val = int("".join([str(i) for i in data[::-1]]), base=2) + + # determine sign of the displacement + if min_val_check: + sign = 1 + elif max_val_check: + sign = -1 + else: + sign = 2 * np.random.randint(2) - 1 + + # new value + if self.step_size <= 1: + delta = 1 + else: + delta = np.random.randint(self.step_size) + new_val = val + sign * delta + if new_val < 0: + new_val = 0 + if new_val > max_val: + new_val = max_val + new_val = np.binary_repr(new_val, width=width) + + # convert back to binary repr + new_data = np.array([int(i) for i in new_val])[::-1] + if verbose: + print(random_val_name, data, "=>", new_data) + + # inject in the x vector + for ix, nd in zip(idx, new_data): + x[ix] = nd + + # fix constraints + for vidx in idx: + self.fix_constraint(x, vidx) + + return x + + +class SwitchIncrementalStep(BaseStep): # noqa: D101 + + def __init__( # noqa: D417 + self, + var_names, + single_var_names, + single_var_index, + switch_variable_index, + step_size=1, + optimize_values=None, + ): + """Propose a new solution vector. + + Args: + var_names (list): names of the variables in the problem + single_var_names (_type_): list of the single variables names e.g. x_001_002 + single_var_index (_type_): index of the single variables + switch_variable_index (list): index of the variables we are switching over + step_size (int, optional): size of the steps + optimize_values (list, optional): index of the values to optimize + """ + super().__init__( + var_names, single_var_names, single_var_index, step_size, optimize_values + ) + self.switch_variable_index = switch_variable_index + self.switch_variable_index_map = self.create_switch_variable_index_map() + + def create_switch_variable_index_map(self): + """Create a map of the varialbes that we switch over. + + Args: + switch_variable_index (list): _description_ + """ + mapping = {} + for group in self.switch_variable_index: + for iel, el in enumerate(group): + tmp = deepcopy(group) + _ = tmp.pop(iel) + mapping[self.value_names[el]] = [self.value_names[itmp] for itmp in tmp] + return mapping + + def __call__(self, x, verbose=False): + """Call function of the method. + + Args: + x (list): initial sample + verbose (bool): print stuff + + Returns: + list: proposed sample + """ + num_var_changed = np.random.randint(len(self.optimize_values)) + random_val_name_list = np.random.choice( + self.value_names[self.optimize_values], size=num_var_changed + ) + + for random_val_name in random_val_name_list: + + idx = self.index_values[random_val_name] + + # switch variables + if random_val_name in self.switch_variable_index_map: + + # switch original + idx = idx[0] + + # if this variable is set to 1 + # we randomly among the other switch variables of the group + if x[idx] == 1: + # switch new one + new_var = np.random.choice( + self.switch_variable_index_map[random_val_name], size=1 + )[0] + idx_new = self.index_values[new_var][0] + + # if this variable is set to 0 + # we pick the switch variable in the group that is set to 1 + else: + for new_var in self.switch_variable_index_map[random_val_name]: + idx_new = self.index_values[new_var][0] + if x[idx_new] == 1: + break + # print(random_val_name, x[idx], new_var, x[idx_new]) + x[idx] = int(not (x[idx])) + x[idx_new] = int(not (x[idx_new])) + + self.fix_constraint(x, idx) + self.fix_constraint(x, idx_new) + + # other variables + else: + + data = np.array(x)[idx] + width = len(data) + + # determine the max val + max_val = int("1" * width, base=2) + + # check if we reach min/max val + max_val_check = data.prod() == 1 + min_val_check = data.sum() == 0 + + # convert to int value + val = int("".join([str(i) for i in data[::-1]]), base=2) + + # determine sign of the displacement + if min_val_check: + sign = 1 + elif max_val_check: + sign = -1 + else: + sign = 2 * np.random.randint(2) - 1 + + # new value + if self.step_size <= 1: + delta = 1 + else: + delta = np.random.randint(self.step_size) + new_val = val + sign * delta + if new_val < 0: + new_val = 0 + if new_val > max_val: + new_val = max_val + new_val = np.binary_repr(new_val, width=width) + + # convert back to binary repr + new_data = np.array([int(i) for i in new_val])[::-1] + if verbose: + print(random_val_name, data, "=>", new_data) + + # inject in the x vector + for ix, nd in zip(idx, new_data): + x[ix] = nd + + # fix constraints + for vidx in idx: + self.fix_constraint(x, vidx) + + return x diff --git a/wntr_quantum/sim/__init__.py b/wntr_quantum/sim/__init__.py index c4c2b13..8258be3 100644 --- a/wntr_quantum/sim/__init__.py +++ b/wntr_quantum/sim/__init__.py @@ -1,4 +1,9 @@ from .core import QuantumWNTRSimulator +from .core_qubo import FullQuboPolynomialSimulator from .epanet import QuantumEpanetSimulator -__all__ = ["QuantumWNTRSimulator", "QuantumEpanetSimulator"] +__all__ = [ + "QuantumWNTRSimulator", + "QuantumEpanetSimulator", + "FullQuboPolynomialSimulator", +] diff --git a/wntr_quantum/sim/core.py b/wntr_quantum/sim/core.py index 6825864..5c428bd 100644 --- a/wntr_quantum/sim/core.py +++ b/wntr_quantum/sim/core.py @@ -161,10 +161,9 @@ def run_sim( # Prepare for solve self._update_internal_graph() - ( - num_isolated_junctions, - num_isolated_links, - ) = self._get_isolated_junctions_and_links() + num_isolated_junctions, num_isolated_links = ( + self._get_isolated_junctions_and_links() + ) if not first_step and not resolve: wntr.sim.hydraulics.update_tank_heads(self._wn) wntr.sim.hydraulics.update_model_for_controls( diff --git a/wntr_quantum/sim/core_qubo.py b/wntr_quantum/sim/core_qubo.py new file mode 100644 index 0000000..5edae13 --- /dev/null +++ b/wntr_quantum/sim/core_qubo.py @@ -0,0 +1,327 @@ +import logging +import warnings +import wntr.sim.hydraulics +import wntr.sim.results +from wntr.sim.core import WNTRSimulator +from wntr.sim.core import _Diagnostics +from wntr.sim.core import _ValveSourceChecker +from .qubo_hydraulics import create_hydraulic_model_for_qubo +from .solvers.qubo_polynomial_solver import QuboPolynomialSolver + +logger = logging.getLogger(__name__) + + +class FullQuboPolynomialSimulator(WNTRSimulator): + """The quantum enabled NR slver.""" + + def __init__(self, wn, flow_encoding, head_encoding): # noqa: D417 + """WNTR simulator class. + The WNTR simulator uses a custom newton solver and linear solvers from scipy.sparse. + + Parameters + ---------- + wn : WaterNetworkModel object + Water network model + flow_encoding: binary encoding for the flow values + head_encoding: binary ncoding for the head values + + + .. note:: + The mode parameter has been deprecated. Please set the mode using Options.hydraulic.demand_model + + """ # noqa: D205 + super().__init__(wn) + self._head_encoding = head_encoding + self._flow_encoding = flow_encoding + self._solver = QuboPolynomialSolver( + self._wn, flow_encoding=flow_encoding, head_encoding=head_encoding + ) + + def run_sim( + self, + solver=QuboPolynomialSolver, + solver_options=None, + convergence_error=False, + diagnostics=False, + ): + """Run an extended period simulation (hydraulics only). + + Parameters + ---------- + solver: object + wntr.sim.solvers.NewtonSolver or Scipy solver + linear_solver: linear solver + Linear solver + solver_options: dict + Solver options are specified using the following dictionary keys: + * MAXITER: the maximum number of iterations for each hydraulic solve + (each timestep and trial) (default = 3000) + * TOL: tolerance for the hydraulic equations (default = 1e-6) + * BT_RHO: the fraction by which the step length is reduced at each iteration of the + line search (default = 0.5) + * BT_MAXITER: the maximum number of iterations for each line search (default = 100) + * BACKTRACKING: whether or not to use a line search (default = True) + * BT_START_ITER: the newton iteration at which a line search should start being used (default = 2) + * THREADS: the number of threads to use in constraint and jacobian computations + convergence_error: bool (optional) + If convergence_error is True, an error will be raised if the + simulation does not converge. If convergence_error is False, partial results are returned, + a warning will be issued, and results.error_code will be set to 0 + if the simulation does not converge. Default = False. + diagnostics: bool + If True, then run with diagnostics on + """ + logger.debug("creating hydraulic model") + self.mode = self._wn.options.hydraulic.demand_model + self._model, self._model_updater = create_hydraulic_model_for_qubo(wn=self._wn) + + if diagnostics: + diagnostics = _Diagnostics(self._wn, self._model, self.mode, enable=True) + else: + diagnostics = _Diagnostics(self._wn, self._model, self.mode, enable=False) + + self._setup_sim_options( + solver=solver, + backup_solver=None, + solver_options=solver_options, + backup_solver_options=None, + convergence_error=convergence_error, + ) + + self._valve_source_checker = _ValveSourceChecker(self._wn) + self._get_control_managers() + self._register_controls_with_observers() + + node_res, link_res = wntr.sim.hydraulics.initialize_results_dict(self._wn) + results = wntr.sim.results.SimulationResults() + results.error_code = None + results.time = [] + results.network_name = self._wn.name + + self._initialize_internal_graph() + self._change_tracker.set_reference_point("graph") + self._change_tracker.set_reference_point("model") + + if self._wn.sim_time == 0: + first_step = True + else: + first_step = False + trial = -1 + max_trials = self._wn.options.hydraulic.trials + resolve = False + self._rule_iter = 0 # this is used to determine the rule timestep + + if first_step: + wntr.sim.hydraulics.update_network_previous_values(self._wn) + self._wn._prev_sim_time = -1 + + logger.debug("starting simulation") + + logger.info( + "{0:<10}{1:<10}{2:<10}{3:<15}{4:<15}".format( + "Sim Time", "Trial", "Solver", "# isolated", "# isolated" + ) + ) + logger.info( + "{0:<10}{1:<10}{2:<10}{3:<15}{4:<15}".format( + "", "", "# iter", "junctions", "links" + ) + ) + while True: + if logger.getEffectiveLevel() <= logging.DEBUG: + logger.debug("\n\n") + + if not resolve: + if not first_step: + """ + The tank levels/heads must be done before checking the controls because the TankLevelControls + depend on the tank levels. These will be updated again after we determine the next actual timestep. + """ + wntr.sim.hydraulics.update_tank_heads(self._wn) + trial = 0 + self._compute_next_timestep_and_run_presolve_controls_and_rules( + first_step + ) + + self._run_feasibility_controls() + + # Prepare for solve + self._update_internal_graph() + num_isolated_junctions, num_isolated_links = ( + self._get_isolated_junctions_and_links() + ) + if not first_step and not resolve: + wntr.sim.hydraulics.update_tank_heads(self._wn) + wntr.sim.hydraulics.update_model_for_controls( + self._model, self._wn, self._model_updater, self._change_tracker + ) + wntr.sim.models.param.source_head_param(self._model, self._wn) + wntr.sim.models.param.expected_demand_param(self._model, self._wn) + + diagnostics.run( + last_step="presolve controls, rules, and model updates", + next_step="solve", + ) + + solver_status, mesg, iter_count = _solver_helper( + self._model, + self._solver, + self._wn, + self._flow_encoding, + self._head_encoding, + self._solver_options, + ) + + if solver_status == 0: + if self._convergence_error: + logger.error( + "Simulation did not converge at time " + + self._get_time() + + ". " + + mesg + ) + raise RuntimeError( + "Simulation did not converge at time " + + self._get_time() + + ". " + + mesg + ) + warnings.warn( + "Simulation did not converge at time " + + self._get_time() + + ". " + + mesg + ) + logger.warning( + "Simulation did not converge at time " + + self._get_time() + + ". " + + mesg + ) + results.error_code = wntr.sim.results.ResultsStatus.error + diagnostics.run(last_step="solve", next_step="break") + break + + logger.info( + "{0:<10}{1:<10}{2:<10}{3:<15}{4:<15}".format( + self._get_time(), + trial, + iter_count, + num_isolated_junctions, + num_isolated_links, + ) + ) + + # Enter results in network and update previous inputs + logger.debug("storing results in network") + wntr.sim.hydraulics.store_results_in_network(self._wn, self._model) + + diagnostics.run( + last_step="solve and store results in network", + next_step="postsolve controls", + ) + + self._run_postsolve_controls() + self._run_feasibility_controls() + if self._change_tracker.changes_made(ref_point="graph"): + resolve = True + self._update_internal_graph() + wntr.sim.hydraulics.update_model_for_controls( + self._model, self._wn, self._model_updater, self._change_tracker + ) + diagnostics.run( + last_step="postsolve controls and model updates", + next_step="solve next trial", + ) + trial += 1 + if trial > max_trials: + if convergence_error: + logger.error( + "Exceeded maximum number of trials at time " + + self._get_time() + + ". " + ) + raise RuntimeError( + "Exceeded maximum number of trials at time " + + self._get_time() + + ". " + ) + results.error_code = wntr.sim.results.ResultsStatus.error + warnings.warn( + "Exceeded maximum number of trials at time " + + self._get_time() + + ". " + ) + logger.warning( + "Exceeded maximum number of trials at time " + + self._get_time() + + ". " + ) + break + continue + + diagnostics.run( + last_step="postsolve controls and model updates", + next_step="advance time", + ) + + logger.debug( + "no changes made by postsolve controls; moving to next timestep" + ) + + resolve = False + if isinstance(self._report_timestep, (float, int)): + if self._wn.sim_time % self._report_timestep == 0: + wntr.sim.hydraulics.save_results(self._wn, node_res, link_res) + if ( + len(results.time) > 0 + and int(self._wn.sim_time) == results.time[-1] + ): + if int(self._wn.sim_time) != self._wn.sim_time: + raise RuntimeError( + "Time steps increments smaller than 1 second are forbidden." + + " Keep time steps as an integer number of seconds." + ) + else: + raise RuntimeError( + "Simulation already solved this timestep" + ) + results.time.append(int(self._wn.sim_time)) + elif self._report_timestep.upper() == "ALL": + wntr.sim.hydraulics.save_results(self._wn, node_res, link_res) + if len(results.time) > 0 and int(self._wn.sim_time) == results.time[-1]: + raise RuntimeError("Simulation already solved this timestep") + results.time.append(int(self._wn.sim_time)) + wntr.sim.hydraulics.update_network_previous_values(self._wn) + first_step = False + self._wn.sim_time += self._hydraulic_timestep + overstep = float(self._wn.sim_time) % self._hydraulic_timestep + self._wn.sim_time -= overstep + + if self._wn.sim_time > self._wn.options.time.duration: + break + + wntr.sim.hydraulics.get_results(self._wn, results, node_res, link_res) + + return results + + +def _solver_helper(model, solver, wn, flow_encoding, head_encoding, solver_options): + """Parameters + ---------- + model: wntr.aml.Model + solver: class or function + solver_options: dict + + Returns + ------- + solver_status: int + message: str + """ # noqa: D205 + logger.debug("solving") + model.set_structure() + if solver is QuboPolynomialSolver: + _solver = QuboPolynomialSolver(wn, flow_encoding, head_encoding) + return _solver.solve(model, options=solver_options) + else: + raise ValueError("Solver not recognized.") diff --git a/wntr_quantum/sim/models/__init__.py b/wntr_quantum/sim/models/__init__.py new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/wntr_quantum/sim/models/__init__.py @@ -0,0 +1 @@ + diff --git a/wntr_quantum/sim/models/chezy_manning.py b/wntr_quantum/sim/models/chezy_manning.py new file mode 100644 index 0000000..948d099 --- /dev/null +++ b/wntr_quantum/sim/models/chezy_manning.py @@ -0,0 +1,275 @@ +import numpy as np +import wntr +from wntr.epanet.util import FlowUnits +from wntr.epanet.util import HydParam +from wntr.epanet.util import from_si +from wntr.network import LinkStatus +from wntr.sim import aml +from wntr.sim.models.utils import Definition + + +def chezy_manning_constants(m): + """Add chezy manning constants to the model. + + Args: + m (aml.Model): Model of the netwwork + """ + m.cm_exp = 2 + m.cm_k = (4 / (1.49 * np.pi)) ** 2 * (1 / 4) ** -1.33 + m.cm_roughness_exp = 2 + m.cm_diameter_exp = -5.33 + + +def cm_resistance_prefactor(k, roughness, roughness_exp, diameter, diameter_exp): + """Computes the resistance prefactor. + + Args: + k (float): scaling parameter of the approximatioj + roughness (float): roughness pf the pipe + roughness_exp(int): exponent of the pip diameter in the approx (typically 2) + diameter (float): dimater of the pipe + diameter_exp (int): exponent of the pip diameter in the approx (typically -5.33) + + Returns: + float: resistance prefactor + """ + return k * roughness ** (roughness_exp) * diameter ** (diameter_exp) + + +def cm_resistance_value(k, roughness, roughness_exp, diameter, diameter_exp, length): + """Computes the resistance value. + + Args: + k (float): scaling parameter of the approximatioj + roughness (float): roughness pf the pipe + roughness_exp(int): exponent of the pip diameter in the approx (typically 2) + diameter (float): dimater of the pipe + diameter_exp (int): exponent of the pip diameter in the approx (typically -5.33) + length (float): length of the pipe + + Returns: + float: resistance value + """ + return ( + cm_resistance_prefactor(k, roughness, roughness_exp, diameter, diameter_exp) + * length + ) + + +class cm_resistance_param(Definition): # noqa: D101 + @classmethod + def build(cls, m, wn, updater, index_over=None): # noqa: D417 + """Add a CM resistance coefficient parameter to the model. + + Parameters + ---------- + m: wntr.aml.aml.aml.Model + wn: wntr.network.model.WaterNetworkModel + updater: ModelUpdater + index_over: list of str + list of pipe names + """ + if not hasattr(m, "cm_resistance"): + m.cm_resistance = aml.ParamDict() + + if index_over is None: + index_over = wn.pipe_name_list + + for link_name in index_over: + link = wn.get_link(link_name) + + # convert values from SI to epanet internal + roughness_us = link.roughness + diameter_us = from_si(FlowUnits.CFS, link.diameter, HydParam.Length) + length_us = from_si(FlowUnits.CFS, link.length, HydParam.Length) + + value = cm_resistance_value( + m.cm_k, + roughness_us, + m.cm_roughness_exp, + diameter_us, + m.cm_diameter_exp, + length_us, + ) + if link_name in m.cm_resistance: + m.cm_resistance[link_name].value = value + else: + m.cm_resistance[link_name] = aml.Param(value) + + updater.add(link, "roughness", cm_resistance_param.update) + updater.add(link, "diameter", cm_resistance_param.update) + updater.add(link, "length", cm_resistance_param.update) + + +class approx_chezy_manning_headloss_constraint(Definition): # noqa: D101 + @classmethod + def build(cls, m, wn, updater, index_over=None): # noqa: D417 + """Adds a mass balance to the model for the specified junctions. + + Parameters + ---------- + m: wntr.aml.aml.aml.Model + wn: wntr.network.model.WaterNetworkModel + updater: ModelUpdater + index_over: list of str + list of pipe names; default is all pipes in wn + """ + if not hasattr(m, "approx_hazen_williams_headloss"): + m.approx_chezy_manning_headloss = aml.ConstraintDict() + + if index_over is None: + index_over = wn.pipe_name_list + + for link_name in index_over: + if link_name in m.approx_chezy_manning_headloss: + del m.approx_chezy_manning_headloss[link_name] + + link = wn.get_link(link_name) + f = m.flow[link_name] + status = link.status + + if status == LinkStatus.Closed or link._is_isolated: + con = aml.Constraint(f) + else: + start_node_name = link.start_node_name + end_node_name = link.end_node_name + start_node = wn.get_node(start_node_name) + end_node = wn.get_node(end_node_name) + if isinstance(start_node, wntr.network.Junction): + start_h = m.head[start_node_name] + else: + start_h = m.source_head[start_node_name] + if isinstance(end_node, wntr.network.Junction): + end_h = m.head[end_node_name] + else: + end_h = m.source_head[end_node_name] + k = m.cm_resistance[link_name] + + con = aml.Constraint(expr=-k * f**m.cm_exp + start_h - end_h) + + m.approx_chezy_manning_headloss[link_name] = con + + updater.add(link, "status", approx_chezy_manning_headloss_constraint.update) + updater.add( + link, "_is_isolated", approx_chezy_manning_headloss_constraint.update + ) + + +def get_chezy_manning_qubops_matrix( + m, wn, matrices, flow_index_mapping, head_index_mapping +): # noqa: D417 + """Create the matrices for chezy manning headloss approximation. + + Args: + m (aml.Model): The AML model of the network + wn (WaternNetwork): th water network object + matrices (Tuple): The qubops matrices of the network + flow_index_mapping (Dict): A dict to map the flow model variables to the qubops matrices + head_index_mapping (Dict): A dict to map the head model variables to the qubops matrices + convert_to_us_unit (bool, optional): Convert the inut to US units. Defaults to False. + + Returns: + Tuple: The qubops matrices of the network + """ + P0, P1, P2, P3 = matrices + + for ieq0, link_name in enumerate(wn.pipe_name_list): + + # index of the pipe equation + ieq = ieq0 + len(wn.junction_name_list) + + # link info + link = wn.get_link(link_name) + + # get the start/end node info + start_node_name = link.start_node_name + end_node_name = link.end_node_name + start_node = wn.get_node(start_node_name) + end_node = wn.get_node(end_node_name) + + # linear term (start head values) of the headloss approximation + if isinstance(start_node, wntr.network.Junction): + start_node_index = head_index_mapping[m.head[start_node_name].name] + P1[ieq, start_node_index] += 1 + else: + start_h = m.source_head[start_node_name] + P0[ieq, 0] += from_si(FlowUnits.CFS, start_h.value, HydParam.Length) + + # linear term (end head values) of the headloss approximation + if isinstance(end_node, wntr.network.Junction): + end_node_index = head_index_mapping[m.head[end_node_name].name] + P1[ieq, end_node_index] -= 1 + else: + end_h = m.source_head[end_node_name] + P0[ieq, 0] -= from_si(FlowUnits.CFS, end_h.value, HydParam.Length) + + # non linear term (sign flow^2) of headloss approximation + k = m.cm_resistance[link_name] + sign_index = flow_index_mapping[m.flow[link_name].name]["sign"] + flow_index = flow_index_mapping[m.flow[link_name].name]["absolute_value"] + P3[ieq, sign_index, flow_index, flow_index] -= k.value + + return (P0, P1, P2, P3) + + +def get_pipe_design_chezy_manning_qubops_matrix( + m, wn, matrices, flow_index_mapping, head_index_mapping +): # noqa: D417 + """Create the matrices for chezy manning headloss approximation. + + Args: + m (aml.Model): The AML model of the network + wn (WaternNetwork): th water network object + matrices (Tuple): The qubops matrices of the network + flow_index_mapping (Dict): A dict to map the flow model variables to the qubops matrices + head_index_mapping (Dict): A dict to map the head model variables to the qubops matrices + convert_to_us_unit (bool, optional): Convert the inut to US units. Defaults to False. + + Returns: + Tuple: The qubops matrices of the network + """ + P0, P1, P2, P3, P4 = matrices + num_continuous_var = 2 * len(m.flow) + len(m.head) + + for ieq0, link_name in enumerate(wn.pipe_name_list): + + # index of the pipe equation + ieq = ieq0 + len(wn.junction_name_list) + + # link info + link = wn.get_link(link_name) + + # get start/end node info + start_node_name = link.start_node_name + end_node_name = link.end_node_name + start_node = wn.get_node(start_node_name) + end_node = wn.get_node(end_node_name) + + # linear term (start head value) of the headloss approximation + if isinstance(start_node, wntr.network.Junction): + start_node_index = head_index_mapping[m.head[start_node_name].name] + P1[ieq, start_node_index] += 1 + else: + start_h = m.source_head[start_node_name] + P0[ieq, 0] += from_si(FlowUnits.CFS, start_h.value, HydParam.Length) + + # linear term (end head values) of the headloss approximation + if isinstance(end_node, wntr.network.Junction): + end_node_index = head_index_mapping[m.head[end_node_name].name] + P1[ieq, end_node_index] -= 1 + else: + end_h = m.source_head[end_node_name] + P0[ieq, 0] -= from_si(FlowUnits.CFS, end_h.value, HydParam.Length) + + # non linear term (resistance sign flow^2) of the headloss approximation + sign_index = flow_index_mapping[m.flow[link_name].name]["sign"] + flow_index = flow_index_mapping[m.flow[link_name].name]["absolute_value"] + for pipe_coefs, pipe_idx in zip( + m.pipe_coefficients[link_name].value, + m.pipe_coefficients_indices[link_name].value, + ): + P4[ + ieq, sign_index, flow_index, flow_index, pipe_idx + num_continuous_var + ] = -pipe_coefs + + return (P0, P1, P2, P3, P4) diff --git a/wntr_quantum/sim/models/darcy_weisbach.py b/wntr_quantum/sim/models/darcy_weisbach.py new file mode 100644 index 0000000..087aa48 --- /dev/null +++ b/wntr_quantum/sim/models/darcy_weisbach.py @@ -0,0 +1,306 @@ +import wntr +from wntr.epanet.util import FlowUnits +from wntr.epanet.util import HydParam +from wntr.epanet.util import from_si +from wntr.network import LinkStatus +from wntr.sim import aml +from wntr.sim.models.utils import Definition +from .darcy_weisbach_fit import dw_fit + + +def darcy_weisbach_constants(m): + """Add darcy weisbach constants to the model. + + Args: + m (aml.Model): Model of the netwwork + """ + m.dw_k = 0.025173 # 16/64.4/pi^2 + m.dw_exp = 2 + m.dw_diameter_exp = -5 + + +def dw_resistance_prefactor(k, roughness, diameter, diameter_exp): + """Computes the resistance prefactor. + + Args: + k (float): scaling parameter of the approximatioj + roughness (float): roughness pf the pipe + diameter (float): dimater of the pipe + diameter_exp (int): exponent of the pip diameter in the approx (typically -5) + + Returns: + Tuple(float, float, float): value of the fit to the full DW formula + """ + return ( + k + * (diameter**diameter_exp) + * dw_fit(roughness, diameter, convert_to_us_unit=False) + ) + + +def dw_resistance_value(k, roughness, diameter, diameter_exp, length): + """_summary_. + + Args: + k (float): scaling parameter of the approximatioj + roughness (float): roughness pf the pipe + diameter (float): dimater of the pipe + diameter_exp (int): exponent of the pip diameter in the approx (typically -5) + length (float): length of the pipe + + Returns: + Tuple(float, float, float): value of the fit to the full DW formula + """ + return dw_resistance_prefactor(k, roughness, diameter, diameter_exp) * length + + +class dw_resistance_param(Definition): # noqa: D101 + @classmethod + def build(cls, m, wn, updater, index_over=None): # noqa: D417 + """Add a CM resistance coefficient parameter to the model. + + Parameters + ---------- + m: wntr.aml.aml.aml.Model + wn: wntr.network.model.WaterNetworkModel + updater: ModelUpdater + index_over: list of str + list of pipe names + """ + if not hasattr(m, "dw_resistance_0"): + m.dw_resistance_0 = aml.ParamDict() + if not hasattr(m, "dw_resistance_1"): + m.dw_resistance_1 = aml.ParamDict() + if not hasattr(m, "dw_resistance_2"): + m.dw_resistance_2 = aml.ParamDict() + + if index_over is None: + index_over = wn.pipe_name_list + + for link_name in index_over: + link = wn.get_link(link_name) + + # convert values from SI to epanet internal + roughness_us = 0.001 * from_si( + FlowUnits.CFS, link.roughness, HydParam.Length + ) + diameter_us = from_si(FlowUnits.CFS, link.diameter, HydParam.Length) + length_us = from_si(FlowUnits.CFS, link.length, HydParam.Length) + + # compute the resistance value fit coefficients + value = dw_resistance_value( + m.dw_k, + roughness_us, + diameter_us, + m.dw_diameter_exp, + length_us, + ) + if link_name in m.dw_resistance_0: + m.dw_resistance_0[link_name].value = value[0] + else: + m.dw_resistance_0[link_name] = aml.Param(value[0]) + + if link_name in m.dw_resistance_1: + m.dw_resistance_1[link_name].value = value[1] + else: + m.dw_resistance_1[link_name] = aml.Param(value[1]) + + if link_name in m.dw_resistance_2: + m.dw_resistance_2[link_name].value = value[2] + else: + m.dw_resistance_2[link_name] = aml.Param(value[2]) + + updater.add(link, "roughness", dw_resistance_param.update) + updater.add(link, "diameter", dw_resistance_param.update) + updater.add(link, "length", dw_resistance_param.update) + + +class approx_darcy_weisbach_headloss_constraint(Definition): # noqa: D101 + @classmethod + def build(cls, m, wn, updater, index_over=None): # noqa: D417 + """Adds a mass balance to the model for the specified junctions. + + Parameters + ---------- + m: wntr.aml.aml.aml.Model + wn: wntr.network.model.WaterNetworkModel + updater: ModelUpdater + index_over: list of str + list of pipe names; default is all pipes in wn + """ + if not hasattr(m, "approx_darcy_weisbach_headloss"): + m.approx_darcy_wesibach_headloss = aml.ConstraintDict() + + if index_over is None: + index_over = wn.pipe_name_list + + for link_name in index_over: + if link_name in m.approx_darcy_wesibach_headloss: + del m.approx_darcy_wesibach_headloss[link_name] + + link = wn.get_link(link_name) + f = m.flow[link_name] + status = link.status + + if status == LinkStatus.Closed or link._is_isolated: + con = aml.Constraint(f) + else: + start_node_name = link.start_node_name + end_node_name = link.end_node_name + start_node = wn.get_node(start_node_name) + end_node = wn.get_node(end_node_name) + if isinstance(start_node, wntr.network.Junction): + start_h = m.head[start_node_name] + else: + start_h = m.source_head[start_node_name] + if isinstance(end_node, wntr.network.Junction): + end_h = m.head[end_node_name] + else: + end_h = m.source_head[end_node_name] + k0 = m.dw_resistance_0[link_name] + k1 = m.dw_resistance_1[link_name] + k2 = m.dw_resistance_2[link_name] + + con = aml.Constraint(expr=-k0 - k1 * f - k2 * f**2 + start_h - end_h) + + m.approx_darcy_wesibach_headloss[link_name] = con + + updater.add( + link, "status", approx_darcy_weisbach_headloss_constraint.update + ) + updater.add( + link, "_is_isolated", approx_darcy_weisbach_headloss_constraint.update + ) + + +def get_darcy_weisbach_qubops_matrix( + m, wn, matrices, flow_index_mapping, head_index_mapping +): # noqa: D417 + """Create the matrices for chezy manning headloss approximation. + + Args: + m (aml.Model): The AML model of the network + wn (WaternNetwork): th water network object + matrices (Tuple): The qubops matrices of the network + flow_index_mapping (Dict): A dict to map the flow model variables to the qubops matrices + head_index_mapping (Dict): A dict to map the head model variables to the qubops matrices + convert_to_us_unit (bool, optional): Convert the inut to US units. Defaults to False. + + Returns: + Tuple: The qubops matrices of the network + """ + P0, P1, P2, P3 = matrices + + for ieq0, link_name in enumerate(wn.pipe_name_list): + + # index of the pipe equation + ieq = ieq0 + len(wn.junction_name_list) + + # get link info + link = wn.get_link(link_name) + + # get start/end node info + start_node_name = link.start_node_name + end_node_name = link.end_node_name + start_node = wn.get_node(start_node_name) + end_node = wn.get_node(end_node_name) + + # linear term (start head values) of the headloss approximation + if isinstance(start_node, wntr.network.Junction): + start_node_index = head_index_mapping[m.head[start_node_name].name] + P1[ieq, start_node_index] += 1 + else: + start_h = m.source_head[start_node_name] + P0[ieq, 0] += from_si(FlowUnits.CFS, start_h.value, HydParam.Length) + + # linear term (end head values) of the headloss approximation + if isinstance(end_node, wntr.network.Junction): + end_node_index = head_index_mapping[m.head[end_node_name].name] + P1[ieq, end_node_index] -= 1 + else: + end_h = m.source_head[end_node_name] + P0[ieq, 0] -= from_si(FlowUnits.CFS, end_h.value, HydParam.Length) + + # non linear term (sign flow^2) of headloss approximation + k0 = m.dw_resistance_0[link_name] + k1 = m.dw_resistance_1[link_name] + k2 = m.dw_resistance_2[link_name] + + sign_index = flow_index_mapping[m.flow[link_name].name]["sign"] + flow_index = flow_index_mapping[m.flow[link_name].name]["absolute_value"] + + P1[ieq, sign_index] -= k0.value + P2[ieq, sign_index, flow_index] -= k1.value + P3[ieq, sign_index, flow_index, flow_index] -= k2.value + + return (P0, P1, P2, P3) + + +def get_pipe_design_darcy_wesibach_qubops_matrix( + m, wn, matrices, flow_index_mapping, head_index_mapping +): # noqa: D417 + """Create the matrices for chezy manning headloss approximation. + + Args: + m (aml.Model): The AML model of the network + wn (WaternNetwork): th water network object + matrices (Tuple): The qubops matrices of the network + flow_index_mapping (Dict): A dict to map the flow model variables to the qubops matrices + head_index_mapping (Dict): A dict to map the head model variables to the qubops matrices + convert_to_us_unit (bool, optional): Convert the inut to US units. Defaults to False. + + Returns: + Tuple: The qubops matrices of the network + """ + P0, P1, P2, P3, P4 = matrices + num_continuous_var = 2 * len(m.flow) + len(m.head) + + for ieq0, link_name in enumerate(wn.pipe_name_list): + + # index of the pipe equation + ieq = ieq0 + len(wn.junction_name_list) + + # get link info + link = wn.get_link(link_name) + + # get start/end node info + start_node_name = link.start_node_name + end_node_name = link.end_node_name + start_node = wn.get_node(start_node_name) + end_node = wn.get_node(end_node_name) + + # linear term (start head value) of the headloss approximation + if isinstance(start_node, wntr.network.Junction): + start_node_index = head_index_mapping[m.head[start_node_name].name] + P1[ieq, start_node_index] = 1 + else: + start_h = m.source_head[start_node_name] + P0[ieq, 0] += from_si(FlowUnits.CFS, start_h.value, HydParam.Length) + + # linear term (end head value) of the headloss approximation + if isinstance(end_node, wntr.network.Junction): + end_node_index = head_index_mapping[m.head[end_node_name].name] + P1[ieq, end_node_index] = -1 + else: + end_h = m.source_head[end_node_name] + P0[ieq, 0] -= from_si(FlowUnits.CFS, end_h.value, HydParam.Length) + + # non linear terms (resistance sign flow ^2) of the approximation + sign_index = flow_index_mapping[m.flow[link_name].name]["sign"] + flow_index = flow_index_mapping[m.flow[link_name].name]["absolute_value"] + + # loop over the pipe diameters ofthe link + for pipe_coefs, pipe_idx in zip( + m.pipe_coefficients[link_name].value, + m.pipe_coefficients_indices[link_name].value, + ): + # P1[ieq, pipe_idx + num_continuous_var] -= pipe_coefs[0] + P2[ieq, sign_index, pipe_idx + num_continuous_var] -= pipe_coefs[0] + P3[ + ieq, sign_index, flow_index, pipe_idx + num_continuous_var + ] -= pipe_coefs[1] + P4[ + ieq, sign_index, flow_index, flow_index, pipe_idx + num_continuous_var + ] -= pipe_coefs[2] + + return (P0, P1, P2, P3, P4) diff --git a/wntr_quantum/sim/models/darcy_weisbach_fit.py b/wntr_quantum/sim/models/darcy_weisbach_fit.py new file mode 100644 index 0000000..f887590 --- /dev/null +++ b/wntr_quantum/sim/models/darcy_weisbach_fit.py @@ -0,0 +1,128 @@ +import matplotlib.pyplot as plt +import numpy as np +from wntr.epanet.util import FlowUnits +from wntr.epanet.util import HydParam +from wntr.epanet.util import from_si + + +def friction_factor(q, e, s): # noqa: D417 + """Computes the ground truth for the friction factor. + + Args: + q = |pipe flow| + e = pipe roughness / diameter + s = viscosity * pipe diameter + """ + A8 = 4.61841319859066668690e00 + A9 = -8.68588963806503655300e-01 + + w = q / s + + # if w >= A1: + y1 = A8 / pow(w, 0.9) + y2 = e / 3.7 + y1 + y3 = A9 * np.log(y2) + f = 1.0 / (y3 * y3) + return f + + +def dw_fit( + roughness, diameter, plot=False, convert_to_us_unit=False, return_all_data=False +): + """Fit the dw friction coefficient to a quadratic polynomial. + + Args: + roughness (float): roughness pf the pipe in meter + diameter (float): diamter of the pipe in meter + plot(bool): plot the solution for visual inspection + convert_to_us_unit(bool): convert to us unit + return_all_data (bool): return all data + """ + + def convert_to_USunit(roughness, diameter): + """Converts roughness and diameter to US units.""" + diameter_us = from_si(FlowUnits.CFS, diameter, HydParam.Length) + roughness_us = 0.001 * from_si(FlowUnits.CFS, roughness, HydParam.Length) + return roughness_us, diameter_us + + N = 250 + Q = np.logspace(0, 4, num=N) + if convert_to_us_unit: + roughness, diameter = convert_to_USunit(roughness, diameter) + viscosity = 0.000011 + e = roughness / diameter + s = viscosity * diameter + + factors = np.zeros(N) + for iq, q in enumerate(Q): + factors[iq] = friction_factor(q, e, s) + + res = np.polyfit(1 / Q, factors, 2) + + if plot: + approx = np.poly1d(res) + plt.loglog(Q, approx(1 / Q)) + plt.loglog(Q, factors) + plt.loglog(Q, res[0] * (1 / Q) ** 2 + res[1] * 1 / Q + res[2]) + plt.show() + + plt.semilogx(Q, 1 - np.abs((approx(1 / Q)) / factors)) + plt.show() + + print(res) + if return_all_data: + return np.array(res), np.poly1d(res)(1 / Q), factors, Q + else: + return np.array(res) + + +def evaluate_fit(coeffs, flow): + """Evaluate the fit. + + Args: + coeffs (_type_): _description_ + flow (_type_): _description_ + + Returns: + _type_: _description_ + """ + return coeffs[0] * (1 / flow) ** 2 + coeffs[1] * 1 / flow + coeffs[2] + + +if __name__ == "__main__": + # r = 0.000164 + # d = 0.820210 + # res = dw_fit(roughness=r, diameter=d, plot=True, convert_to_us_unit=False) + + # print(evaluate_fit(res, 1.766)) + + # roughness = 0.005 + roughness = 0.5 * 1e-3 + ndiams = 5 + DIAMS = np.arange(5, 20, 3) / 12 + + BASELINE = [] + APPROX = [] + for d in DIAMS: + print(d) + res, approx, baseline, qval = dw_fit( + roughness=roughness, diameter=d, plot=False, convert_to_us_unit=False + ) + BASELINE.append(baseline) + APPROX.append(approx) + + n = 24 + + colors = plt.cm.tab20(np.linspace(0, 1, n)) + + i = 0 + for bl, ap in zip(BASELINE, APPROX): + plt.loglog(qval, bl, "--", c=colors[i]) + plt.loglog(qval, ap, "-", c=colors[i]) + plt.grid(visible=True, which="both") + # plt.xlim(10, 1000) + plt.xlabel("Reynold Number") + plt.ylabel("Friction Factor") + # plt.yticks([0.01, 0.015, 0.02, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08, 0.09, 0.1]) + i += 1 + plt.show() diff --git a/wntr_quantum/sim/models/mass_balance.py b/wntr_quantum/sim/models/mass_balance.py new file mode 100644 index 0000000..229c797 --- /dev/null +++ b/wntr_quantum/sim/models/mass_balance.py @@ -0,0 +1,45 @@ +from wntr.epanet.util import FlowUnits +from wntr.epanet.util import HydParam +from wntr.epanet.util import from_si + + +def get_mass_balance_qubops_matrix( + m, wn, matrices, flow_index_mapping, convert_to_us_unit=False +): # noqa: D417 + """Create the matrices for the mass balance equation. + + Args: + m (aml.Model): The AML model of the network + wn (WaternNetwork): th water network object + matrices (Tuple): The qubops matrices of the network + flow_index_mapping (Dict): A dict to map the flow model variables to the qubops matrices + convert_to_us_unit (bool, optional): Convert the inut to US units. Defaults to False. + + Returns: + Tuple: The qubops matrices of the network + """ + P0, P1, P2, P3 = matrices + index_over = wn.junction_name_list + + for ieq, node_name in enumerate(index_over): + + node = wn.get_node(node_name) + if not node._is_isolated: + if convert_to_us_unit: + P0[ieq, 0] += from_si( + FlowUnits.CFS, m.expected_demand[node_name].value, HydParam.Flow + ) + else: + P0[ieq, 0] += m.expected_demand[node_name].value + + for link_name in wn.get_links_for_node(node_name, flag="INLET"): + sign_idx = flow_index_mapping[m.flow[link_name].name]["sign"] + flow_idx = flow_index_mapping[m.flow[link_name].name]["absolute_value"] + P2[ieq, sign_idx, flow_idx] -= 1 + + for link_name in wn.get_links_for_node(node_name, flag="OUTLET"): + sign_idx = flow_index_mapping[m.flow[link_name].name]["sign"] + flow_idx = flow_index_mapping[m.flow[link_name].name]["absolute_value"] + P2[ieq, sign_idx, flow_idx] += 1 + + return P0, P1, P2, P3 diff --git a/wntr_quantum/sim/qubo_hydraulics.py b/wntr_quantum/sim/qubo_hydraulics.py new file mode 100644 index 0000000..ba95de1 --- /dev/null +++ b/wntr_quantum/sim/qubo_hydraulics.py @@ -0,0 +1,93 @@ +from wntr.sim import aml +from wntr.sim.models import constants +from wntr.sim.models import constraint +from wntr.sim.models import param +from wntr.sim.models import var +from wntr.sim.models.utils import ModelUpdater +from .models.chezy_manning import approx_chezy_manning_headloss_constraint +from .models.chezy_manning import chezy_manning_constants +from .models.chezy_manning import cm_resistance_param +from .models.darcy_weisbach import approx_darcy_weisbach_headloss_constraint +from .models.darcy_weisbach import darcy_weisbach_constants +from .models.darcy_weisbach import dw_resistance_param + + +def create_hydraulic_model_for_qubo(wn): + """Create the aml. + + Args: + wn (wntr.WaterNetworkModel): The water network for which we want the aml model + + Raises: + ValueError: if pressure driven simulations is requested + ValueError: if H-W headloss approximation is requested + NotImplementedError: if PBV valves are part of the model + NotImplementedError: if GPV valves are part of the model + + Returns: + Tuple[wntr.aml.Model, wntr.models.utils.ModelUpdater]: The AML model and its updater + """ + if wn.options.hydraulic.demand_model in ["PDD", "PDA"]: + raise ValueError("Pressure Driven simulations not supported") + + if wn.options.hydraulic.headloss == "C-M": + import_constants = chezy_manning_constants + resistance_param = cm_resistance_param + approx_head_loss_constraint = approx_chezy_manning_headloss_constraint + elif wn.options.hydraulic.headloss == "D-W": + import_constants = darcy_weisbach_constants + resistance_param = dw_resistance_param + approx_head_loss_constraint = approx_darcy_weisbach_headloss_constraint + else: + raise ValueError( + "QUBO Hydraulic Simulations only supported for C-M and D-W simulations" + ) + + m = aml.Model() + model_updater = ModelUpdater() + + # Global constants + import_constants(m) + constants.head_pump_constants(m) + constants.leak_constants(m) + constants.pdd_constants(m) + + param.source_head_param(m, wn) + param.expected_demand_param(m, wn) + + param.leak_coeff_param.build(m, wn, model_updater) + param.leak_area_param.build(m, wn, model_updater) + param.leak_poly_coeffs_param.build(m, wn, model_updater) + param.elevation_param.build(m, wn, model_updater) + + resistance_param.build(m, wn, model_updater) + param.minor_loss_param.build(m, wn, model_updater) + param.tcv_resistance_param.build(m, wn, model_updater) + param.pump_power_param.build(m, wn, model_updater) + param.valve_setting_param.build(m, wn, model_updater) + + var.flow_var(m, wn) + var.head_var(m, wn) + var.leak_rate_var(m, wn) + + constraint.mass_balance_constraint.build(m, wn, model_updater) + + approx_head_loss_constraint.build(m, wn, model_updater) + + constraint.head_pump_headloss_constraint.build(m, wn, model_updater) + constraint.power_pump_headloss_constraint.build(m, wn, model_updater) + constraint.prv_headloss_constraint.build(m, wn, model_updater) + constraint.psv_headloss_constraint.build(m, wn, model_updater) + constraint.tcv_headloss_constraint.build(m, wn, model_updater) + constraint.fcv_headloss_constraint.build(m, wn, model_updater) + if len(wn.pbv_name_list) > 0: + raise NotImplementedError( + "PBV valves are not currently supported in the WNTRSimulator" + ) + if len(wn.gpv_name_list) > 0: + raise NotImplementedError( + "GPV valves are not currently supported in the WNTRSimulator" + ) + constraint.leak_constraint.build(m, wn, model_updater) + + return m, model_updater diff --git a/wntr_quantum/sim/results.py b/wntr_quantum/sim/results.py index 352f1fc..781a74a 100644 --- a/wntr_quantum/sim/results.py +++ b/wntr_quantum/sim/results.py @@ -1,4 +1,5 @@ """Quantum simulation results.""" + from wntr.sim.results import SimulationResults diff --git a/wntr_quantum/sim/solvers/__init__.py b/wntr_quantum/sim/solvers/__init__.py new file mode 100644 index 0000000..15da67b --- /dev/null +++ b/wntr_quantum/sim/solvers/__init__.py @@ -0,0 +1,7 @@ +from .quantum_newton_solver import QuantumNewtonSolver +from .qubo_polynomial_solver import QuboPolynomialSolver + +__all__ = [ + "QuantumNewtonSolver", + "QuboPolynomialSolver", +] diff --git a/wntr_quantum/sim/solvers.py b/wntr_quantum/sim/solvers/quantum_newton_solver.py similarity index 100% rename from wntr_quantum/sim/solvers.py rename to wntr_quantum/sim/solvers/quantum_newton_solver.py diff --git a/wntr_quantum/sim/solvers/qubo_polynomial_solver.py b/wntr_quantum/sim/solvers/qubo_polynomial_solver.py new file mode 100644 index 0000000..2db9ce2 --- /dev/null +++ b/wntr_quantum/sim/solvers/qubo_polynomial_solver.py @@ -0,0 +1,471 @@ +from collections import OrderedDict +from typing import List +from typing import Tuple +import numpy as np +import sparse +from quantum_newton_raphson.newton_raphson import newton_raphson +from qubops.encodings import BaseQbitEncoding +from qubops.encodings import PositiveQbitEncoding +from qubops.mixed_solution_vector import MixedSolutionVector_V2 as MixedSolutionVector +from qubops.qubops_mixed_vars import QUBOPS_MIXED +from qubops.solution_vector import SolutionVector_V2 as SolutionVector +from wntr.epanet.util import FlowUnits +from wntr.epanet.util import HydParam +from wntr.epanet.util import from_si +from wntr.epanet.util import to_si +from wntr.network import WaterNetworkModel +from wntr.sim.aml import Model +from wntr.sim.solvers import SolverStatus +from ...sampler.simulated_annealing import SimulatedAnnealing +from ...sampler.step.random_step import IncrementalStep +from ...sim.qubo_hydraulics import create_hydraulic_model_for_qubo +from ..models.chezy_manning import get_chezy_manning_qubops_matrix +from ..models.darcy_weisbach import get_darcy_weisbach_qubops_matrix +from ..models.mass_balance import get_mass_balance_qubops_matrix + + +class QuboPolynomialSolver(object): + """Solve the hydraulics equation following a QUBO approach.""" + + def __init__( + self, + wn: WaterNetworkModel, + flow_encoding: BaseQbitEncoding, + head_encoding: BaseQbitEncoding, + ): # noqa: D417 + """Init the solver. + + Args: + wn (WaterNetworkModel): water network + flow_encoding (qubops.encodings.BaseQbitEncoding): binary encoding for the absolute value of the flow + head_encoding (qubops.encodings.BaseQbitEncoding): binary encoding for the head + """ + self.wn = wn + + # create the encoding vectors for the sign of the flows + self.sign_flow_encoding = PositiveQbitEncoding( + nqbit=1, step=2, offset=-1, var_base_name="x" + ) + + # store the encoding of the flow + self.flow_encoding = flow_encoding + if np.min(self.flow_encoding.get_possible_values()) < 0: + raise ValueError( + "The encoding of the flows must only take positive values." + ) + + # store the encoding of the head + self.head_encoding = head_encoding + + # create the solution vectors + self.sol_vect_signs = SolutionVector( + wn.num_pipes, encoding=self.sign_flow_encoding + ) + self.sol_vect_flows = SolutionVector(wn.num_pipes, encoding=flow_encoding) + self.sol_vect_heads = SolutionVector(wn.num_junctions, encoding=head_encoding) + + # create the mixed solution vector + self.mixed_solution_vector = MixedSolutionVector( + [self.sol_vect_signs, self.sol_vect_flows, self.sol_vect_heads] + ) + + # create the hydraulics model + self.model, self.model_updater = create_hydraulic_model_for_qubo(wn) + + # set up the sampler + self.sampler = SimulatedAnnealing() + + # create the matrices + self.create_index_mapping(self.model) + self.matrices = self.initialize_matrices(self.model) + self.matrices = tuple(sparse.COO(m) for m in self.matrices) + + # create the QUBO MIXED instance + self.qubo = QUBOPS_MIXED(self.mixed_solution_vector, {"sampler": self.sampler}) + + # create the qubo dictionary + self.qubo.qubo_dict = self.qubo.create_bqm(self.matrices, strength=0) + + self.qubo.create_variables_mapping() + self.var_names = sorted(self.qubo.qubo_dict.variables) + + # create the step function + self.step_func = IncrementalStep( + self.var_names, + self.qubo.mapped_variables, + self.qubo.index_variables, + step_size=10, + ) + + def verify_encoding(self): + """Print info regarding the encodings.""" + hres = self.head_encoding.get_average_precision() + hvalues = np.sort(self.head_encoding.get_possible_values()) + fres = self.flow_encoding.get_average_precision() + fvalues = np.sort(self.flow_encoding.get_possible_values()) + print("Head Encoding : %f => %f (res: %f)" % (hvalues[0], hvalues[-1], hres)) + print( + "Flow Encoding : %f => %f | %f => %f (res: %f)" + % (-fvalues[-1], -fvalues[0], fvalues[0], fvalues[-1], fres) + ) + + def classical_solution(self, max_iter: int = 100, tol: float = 1e-10) -> np.ndarray: + """Computes the solution using a classical Newton Raphson approach. + + Args: + model (model): the model + max_iter (int, optional): number of iterations of the NR. Defaults to 100. + tol (float, optional): Toleracne of the NR. Defaults to 1e-10. + + Returns: + np.ndarray: _description_ + """ + P0, P1, P2, P3 = self.matrices + num_heads = self.wn.num_junctions + num_pipes = self.wn.num_pipes + num_signs = self.wn.num_pipes + num_vars = num_heads + num_pipes + + if self.wn.options.hydraulic.headloss == "C-M": + p0 = P0.reshape( + -1, + ) + p1 = P1[:, num_pipes:] + P2.sum(1)[:, num_pipes:] + p2 = P3.sum(1)[:, num_pipes:, num_pipes:].sum(-1) + + elif self.wn.options.hydraulic.headloss == "D-W": + p0 = P0.reshape( + -1, + ) + P1[ + :, :num_signs + ].sum(-1) + p1 = P1[:, num_pipes:] + P2.sum(1)[:, num_pipes:] + p2 = P3.sum(1)[:, num_pipes:, num_pipes:].sum(-1) + + def func(input): + sign = np.sign(input) + return p0 + p1 @ input + (p2 @ (sign * input * input)) + + initial_point = np.random.rand(num_vars) + res = newton_raphson(func, initial_point, max_iter=max_iter, tol=tol) + sol = res.solution + converged = np.allclose(func(sol), 0) + + # get the closest encoded solution and binary encoding + bin_rep_sol = [] + for i in range(num_pipes): + bin_rep_sol.append(int(sol[i] > 0)) + + encoded_sol = np.zeros_like(sol) + for idx, s in enumerate(sol): + val, bin_rpr = self.mixed_solution_vector.encoded_reals[ + idx + num_pipes + ].find_closest(np.abs(s)) + bin_rep_sol.append(bin_rpr) + encoded_sol[idx] = np.sign(s) * val + + # convert back to SI + sol = self.convert_solution_to_si(sol) + encoded_sol = self.convert_solution_to_si(encoded_sol) + + # remove the height of the junctions + for i in range(self.wn.num_junctions): + sol[num_pipes + i] -= self.wn.nodes[self.wn.junction_name_list[i]].elevation + encoded_sol[num_pipes + i] -= self.wn.nodes[ + self.wn.junction_name_list[i] + ].elevation + + # compute the qubo energy of the solution + eref = self.qubo.energy_binary_rep(bin_rep_sol) + + return (sol, encoded_sol, bin_rep_sol, eref, converged) + + def initialize_matrices(self, model: Model) -> Tuple: + """Initialize the matrices of the non linear system. + + Args: + model (Model): an AML model from WNTR + + Raises: + ValueError: if headloss approximation is not C-M or D-W + + Returns: + Tuple: Matrices of the on linear system + """ + num_equations = len(list(model.cons())) + num_variables = 2 * len(model.flow) + len(model.head) + + # must transform that to coo + P0 = np.zeros((num_equations, 1)) + P1 = np.zeros((num_equations, num_variables)) + P2 = np.zeros((num_equations, num_variables, num_variables)) + P3 = np.zeros((num_equations, num_variables, num_variables, num_variables)) + matrices = (P0, P1, P2, P3) + + # get the mass balance + matrices = get_mass_balance_qubops_matrix( + model, self.wn, matrices, self.flow_index_mapping, convert_to_us_unit=True + ) + + # get the headloss matrix contributions + if self.wn.options.hydraulic.headloss == "C-M": + matrices = get_chezy_manning_qubops_matrix( + model, + self.wn, + matrices, + self.flow_index_mapping, + self.head_index_mapping, + ) + elif self.wn.options.hydraulic.headloss == "D-W": + matrices = get_darcy_weisbach_qubops_matrix( + model, + self.wn, + matrices, + self.flow_index_mapping, + self.head_index_mapping, + ) + else: + raise ValueError("Calculation only possible with C-M or D-W") + return matrices + + def convert_solution_to_si(self, solution: np.ndarray) -> np.ndarray: + """Converts the solution to SI. + + Args: + solution (array): solution vectors in US units + + Returns: + Tuple: solution in SI + """ + num_heads = self.wn.num_junctions + num_pipes = self.wn.num_pipes + new_sol = np.zeros_like(solution) + for ip in range(num_pipes): + new_sol[ip] = to_si(FlowUnits.CFS, solution[ip], HydParam.Flow) + for ih in range(num_pipes, num_pipes + num_heads): + new_sol[ih] = to_si(FlowUnits.CFS, solution[ih], HydParam.Length) + return new_sol + + def convert_solution_from_si(self, solution: np.ndarray) -> np.ndarray: + """Converts the solution to SI. + + Args: + solution (array): solution vectors in SI + + Returns: + Tuple: solution in US units + """ + num_heads = self.wn.num_junctions + num_pipes = self.wn.num_pipes + new_sol = np.zeros_like(solution) + for ip in range(num_pipes): + new_sol[ip] = from_si(FlowUnits.CFS, solution[ip], HydParam.Flow) + for ih in range(num_pipes, num_pipes + num_heads): + new_sol[ih] = from_si(FlowUnits.CFS, solution[ih], HydParam.Length) + return new_sol + + @staticmethod + def combine_flow_values(solution: List) -> List: + """Combine the values of the flow sign*abs. + + Args: + solution (List): solution vector + + Returns: + List: solution vector + """ + flow = [] + for sign, abs in zip(solution[0], solution[1]): + flow.append(sign * abs) + return flow + solution[2] + + @staticmethod + def flatten_solution_vector(solution: Tuple) -> List: + """Flattens the solution vector. + + Args: + solution (tuple): tuple of ([flows], [heads]) + + Returns: + List: a flat list of all the variables + """ + sol_tmp = [] + for s in solution: + sol_tmp += s + return sol_tmp + + def load_data_in_model(self, model: Model, data: np.ndarray): + """Loads some data in the model. + + Remark: + This routine replaces `load_var_values_from_x` without reordering the vector elements + + Args: + model (Model): AML model from WNTR + data (np.ndarray): data to load + """ + shift_head_idx = self.wn.num_links + for var in model.vars(): + if var.name in self.flow_index_mapping: + idx = self.flow_index_mapping[var.name]["sign"] + elif var.name in self.head_index_mapping: + idx = self.head_index_mapping[var.name] - shift_head_idx + var.value = data[idx] + + def extract_data_from_model(self, model: Model) -> np.ndarray: + """Loads some data in the model. + + Args: + model (Model): AML model from WNTR + + Returns: + np.ndarray: data extracted from model + """ + data = [None] * len(list(model.vars())) + shift_head_idx = self.wn.num_links + for var in model.vars(): + if var.name in self.flow_index_mapping: + idx = self.flow_index_mapping[var.name]["sign"] + elif var.name in self.head_index_mapping: + idx = self.head_index_mapping[var.name] - shift_head_idx + data[idx] = var.value + return data + + def create_index_mapping(self, model: Model) -> None: + """Creates the index maping for qubops matrices. + + Args: + model (Model): the AML Model + """ + # init the idx + idx = 0 + + # number of variables that are flows + num_flow_var = len(model.flow) + + # get the indices for the sign/abs value of the flow + self.flow_index_mapping = OrderedDict() + for _, val in model.flow.items(): + if val.name not in self.flow_index_mapping: + self.flow_index_mapping[val.name] = { + "sign": None, + "absolute_value": None, + } + self.flow_index_mapping[val.name]["sign"] = idx + self.flow_index_mapping[val.name]["absolute_value"] = idx + num_flow_var + idx += 1 + + # get the indices for the heads + idx = 0 + self.head_index_mapping = OrderedDict() + for _, val in model.head.items(): + self.head_index_mapping[val.name] = 2 * num_flow_var + idx + idx += 1 + + def solve( # noqa: D417 + self, + init_sample, + Tschedule, + optimize_values=None, + save_traj=False, + verbose=False, + ) -> Tuple: + """Sample the qubo problem. + + Args: + init_sample (list): initial sample for the optimization + Tschedule (list): temperature schedule for the optimization + optimize_values (None, list): a list of variables to optimize (default to None-> all variables) + save_traj (bool, optional): save the trajectory. Defaults to False. + verbose (bool, optional): print status. Defaults to False. + + Returns: + Tuple: Solver status, str, solution, SimulatedAnnealingResults + """ + if optimize_values is None: + res = self.sampler.sample( + self.qubo, + init_sample=init_sample, + Tschedule=Tschedule, + take_step=self.step_func, + save_traj=save_traj, + verbose=verbose, + ) + + # extact the solution + idx_min = np.array([e for e in res.energies]).argmin() + sol = res.trajectory[idx_min] + + else: + res = [] + for opt_vals in optimize_values: + self.step_func.optimize_values = opt_vals + iter_res = self.sampler.sample( + self.qubo, + init_sample=init_sample, + Tschedule=Tschedule, + take_step=self.step_func, + save_traj=save_traj, + verbose=verbose, + ) + res.append(iter_res) + init_sample = iter_res.res + + # extact the solution a + idx_min = np.array([e for e in res[-1].energies]).argmin() + sol = res[-1].trajectory[idx_min] + + # decode the solution + sol = self.qubo.decode_solution(np.array(sol)) + + # convert the solution to SI + sol = self.combine_flow_values(sol) + sol = self.convert_solution_to_si(sol) + + # remove the height of the junction + for i in range(self.wn.num_junctions): + sol[self.wn.num_pipes + i] -= self.wn.nodes[ + self.wn.junction_name_list[i] + ].elevation + + # load data in the AML model + self.model.set_structure() + self.load_data_in_model(self.model, sol) + + # returns + return (SolverStatus.converged, "Solved Successfully", sol, res) + + def multisolve( # noqa: D417 + self, + init_sample, + Tschedule, + num_reads=10, + optimize_values=None, + save_traj=False, + verbose=False, + ) -> Tuple: + """Sample the qubo problem multiple times. + + Args: + init_sample (list): initial sample for the optimization + Tschedule (list): temperature schedule for the optimization + num_reads (int, default): number of reads (default 1) + optimize_values (None, list): a list of variables to optimize (default to None-> all variables) + save_traj (bool, optional): save the trajectory. Defaults to False. + verbose (bool, optional): print status. Defaults to False. + + Returns: + Tuple: Solver status, str, solution, SimulatedAnnealingResults + """ + sol, res = [], [] + for _ in range(num_reads): + _, _, isol, ires = self.solve( + init_sample=init_sample, + Tschedule=Tschedule, + optimize_values=optimize_values, + save_traj=save_traj, + verbose=verbose, + ) + sol.append(isol) + res.append(ires) + return sol, res