From 046c42770041cc7fa2efc5703701bf34981ba60b Mon Sep 17 00:00:00 2001
From: AmiraliE1380 <60638047+AmiraliE1380@users.noreply.github.com>
Date: Fri, 29 Oct 2021 21:43:05 +0330
Subject: [PATCH 01/32] Delete notebooks/5_local_search directory
---
notebooks/5_local_search/README.md | 5 ----
notebooks/5_local_search/index.ipynb | 1 -
notebooks/5_local_search/metadata.yml | 40 ---------------------------
3 files changed, 46 deletions(-)
delete mode 100644 notebooks/5_local_search/README.md
delete mode 100644 notebooks/5_local_search/index.ipynb
delete mode 100644 notebooks/5_local_search/metadata.yml
diff --git a/notebooks/5_local_search/README.md b/notebooks/5_local_search/README.md
deleted file mode 100644
index c40215c9..00000000
--- a/notebooks/5_local_search/README.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Local Search
-
-- Mahsa Amani
-- Mobina Poornemant
-- Arman Zarei
diff --git a/notebooks/5_local_search/index.ipynb b/notebooks/5_local_search/index.ipynb
deleted file mode 100644
index 520b3eaf..00000000
--- a/notebooks/5_local_search/index.ipynb
+++ /dev/null
@@ -1 +0,0 @@
-{"nbformat":4,"nbformat_minor":0,"metadata":{"kernelspec":{"display_name":"Python 3.8.1 64-bit","language":"python","name":"python38164bitdac97052df6b4ee89acbe124d3b23037"},"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.8.1"},"colab":{"name":"AI_project.ipynb","provenance":[],"collapsed_sections":[]}},"cells":[{"cell_type":"markdown","metadata":{"id":"MQGEDm7VyXRs"},"source":["# Local Search"]},{"cell_type":"markdown","metadata":{"id":"TYrJbpD7-uI9"},"source":["local search is a heuristic method for solving computationally hard optimization problems. Local search can be used on problems that can be formulated as finding a solution maximizing a criterion among a number of candidate solutions. Local search algorithms move from solution to solution in the space of candidate solutions (the search space) by applying local changes, until a solution deemed optimal is found or a time bound is elapsed."]},{"cell_type":"markdown","metadata":{"id":"rysdjagC_Pxg"},"source":["As you can see, in local search, the path to the goal is not important to us and we're only trying to find the state of the goal. In many problems our purpose is to find that goal state rather than the path that takes us there. "]},{"cell_type":"markdown","metadata":{"id":"4wFRqgEmAQrr"},"source":["#### 1. Path to goal is important\n","\n","- 8-Puzzle\n","- Chess\n","- Theorem proving\n","- Route finding"]},{"cell_type":"markdown","metadata":{"id":"z5kv_-44C1ME"},"source":["##### 1.1. Goal state itself is important\n","\n","- 8 Queens\n","- TSP\n","- Job-Shop Scheduling\n","- Automatic program generation\n","- VLSI Layout"]},{"cell_type":"markdown","metadata":{"id":"AiLqmzapD5Ns"},"source":["### 2. Partial state formulation vs. Complete state formulation"]},{"cell_type":"markdown","metadata":{"id":"Ekz71MvDEALY"},"source":["In partial state formulation, each path represent a solution to the problem (as we have seen the systematic exploration of search graph) but in complete state formulation each state represent a solution to the problem."]},{"cell_type":"markdown","metadata":{"id":"zcXO5q9hEgXy"},"source":["#### 2.1. Time and memory complexity \n","As you have seen previously, In Systematic exploration of search space, the memory was exponential. But here it's reduced to O(1) instead and the computational time complexity reduced from exponential to O(T) where we choose such T to limit the number of iterations."]},{"cell_type":"markdown","metadata":{"id":"DFtHu8WvIhtY"},"source":["## 3. Constraint Satisfaction vs. Constraint Optimization"]},{"cell_type":"markdown","metadata":{"id":"T7p_SQQsIpEF"},"source":["In constraint satisfaction problems, we look for states that satisfy some constraints (e.g. in-queens problem, where the constraints are: no two queens can attack each other). In the other hand, in constraint optimization, beside satisfying some constraints, we are looking for optimizing an objective function (whether minimizing or maximizing) (e.g. TSP where the objective function is to minimize the total weight of the edges)"]},{"cell_type":"markdown","metadata":{"id":"m5Ds2YEzJ0R3"},"source":["We can convert a constraint satisfaction problem to a constraint optimization problem. for example consider the n-queens problem. we can set our objective function \n","> h = # pairs of queens that attack each other\n","\n","or\n","\n","> h = # constraints that are violated\n","\n","and then we can solve the optimization version of the problem."]},{"cell_type":"markdown","metadata":{"id":"y6z_J1VLLqVw"},"source":["We also can convert a constraint optimization problem to **some** constraint satisfaction problems (Can do something like a binary search or we can do it in linear time. e.g. for minimizing function *f* we set a constraint *f=a* (for some reasonable a) and at each step we solve the constraint satisfaction version of the problem and decrease *a* by one)"]},{"cell_type":"markdown","metadata":{"id":"_CBxdaYDNLo8"},"source":["## 4. Trivial Algorithms"]},{"cell_type":"markdown","metadata":{"id":"fGsx6b0iNPZV"},"source":["* ### Random Sampling\n","Generate a state randomly at each step and keep the optimal one and update it at each iteration"]},{"cell_type":"markdown","metadata":{"id":"RhiBaUpDNiUL"},"source":["* ### Random Walk\n","Randonmly pick a **neighbor** of the current state"]},{"cell_type":"markdown","metadata":{"id":"8-G8UDGVPI25"},"source":["Both algorithms are asymptotically complete (If the state space is finite, each state is visited at a fixed rate asymptotically)"]},{"cell_type":"markdown","metadata":{"id":"NjlIY7GSF8DI"},"source":["## 5. Hill Climbing"]},{"cell_type":"markdown","metadata":{"id":"3-rMWzUqLJF2"},"source":["a better solution is to use a local search algorithm that continuously moves in the direction of increasing elevation/value to find the peak of the mountain or the best solution to the problem. **Hill-climbing algorithm** terminates when it reaches a peak value where no neighbor has a higher value.\n","Note that, in this algorithm nodes only contain the state and the value of the objective function in that state (not path) so may see previous states. \n","It is also called **greedy local search** as it only looks to its good immediate neighbor state and not beyond that. This may seem like a good thing, but it's not: hill climbing can get stuck in a local optimum easily so its convergence depends on the **initial state**.\n"]},{"cell_type":"markdown","metadata":{"id":"2v42PwhCU7bI"},"source":[""]},{"cell_type":"markdown","metadata":{"id":"3nVVXDhFVATk"},"source":["### 5.1. Example: 8-queens problem:\n","States: 8 queens on the board, one per column (88 ≈ 17 𝑚𝑖𝑙𝑙𝑖𝑜𝑛) \n","Successors(s): all states resulted from 𝑠 by moving a single queen to another square of the same column (8 × 7 = 56) \n","Cost function ℎ(s): number of queen pairs that are attacking each other, directly or indirectly. \n","Global minimum: ℎ(s) = 0 \n"]},{"cell_type":"markdown","metadata":{"id":"1JJlgV2HVdzn"},"source":[""]},{"cell_type":"markdown","metadata":{"id":"vlbmRuQxVq4b"},"source":["in the above example, the hill-climbing algorithm converges to h = 1 and it can't do any action to improve h, so it stuck at the local minimum. \n","### 5.2. 8-queens statistics:\n","*\tState-space of size ≈17 million \n","*\tStarting from a random state, steepest-ascent hill-climbing solves **14%** of the problem instances and 86% of the time getting stuck. \n","*\tIt takes **4 steps** on average when it succeeds, 3 when it gets stuck. \n"]},{"cell_type":"markdown","metadata":{"id":"a48zgD-nWEhx"},"source":["### 5.3. Hill-climbing properties: \n","\n","*\t**Not complete**: because doesn't have memory and may see **repetitive states** and also has issues with **local optimal**. \n","* In the worst case has a terrible running time. \n","*\tThe space complexity of O(1). \n","*\tSimple and often very fast. \n","\n","So the solutions to improve the Hill-climbing algorithm take into account **recurring states** and **local optimal**. \n"]},{"cell_type":"markdown","metadata":{"id":"yujfGOjCWiPH"},"source":["For **convex** or **concave** functions, like the examples below, the hill-climbing algorithm gets the optimal solution, because the local optimal is the **same** as global optimal. \n",""]},{"cell_type":"markdown","metadata":{"id":"KxbalXziXbUk"},"source":["### 5.4. Hill-climbing search problems:\n","*\t**Local optimal** (except convex/concave functions that mentioned before)\n","*\t**Plateau**: a flat area (flat local optima, shoulder) \n"," \n","\n"," \n"," \n"," \n","\n"]},{"cell_type":"markdown","metadata":{"id":"3VXU8UOMZ-rh"},"source":["* **Diagonal ridges**: From each local maximum all the available actions point downhill, but there is an uphill path! \n","\n"," \n",""]},{"cell_type":"markdown","metadata":{"id":"kGOGmNmjaYUg"},"source":["### 5.5. Sideway moves\n","In some problems, like n-queens, converging to local optimal isn't acceptable and should find some better solutions. \n","A solution that may help is to use **sideway moves**: If no downhill (uphill) moves, allow sideways moves in hope that the algorithm can escape shoulders. There might be a limit to the number of sideway moves allowed to avoid infinite loops. \n","For the 8-queens problem, if set 100 for the sideway moves limit, the percentage of problems solved raises from 14 to **94%**, and 21 steps are needed for every successful solution, 64 for each failure. So using sideway moves the probability of convergence to optimal solution increases but the converge time increases too. \n","When **sideway moves** are allowed, performance improves ...\n"]},{"cell_type":"markdown","metadata":{"id":"q_llp1uUa2qK"},"source":["### 5.6. Stochastic Variations\n","Another solution that helps hill-climbing to be complete, is **Stochastic Variations**. When the state-space landscape has local optima, any search that moves only in the greedy direction cannot be complete. \n","the idea of stochastic variations is to combine **random-walk** and **greedy hill-climbing**. \n","At each step do one of the following: \n","*\t**Greedy**: With probability, p moves to the neighbor with the largest value.\n","*\t**Random**: With probability, 1-p moves to a random neighbor.\n"]},{"cell_type":"markdown","metadata":{"id":"BNE0DnHFbQsm"},"source":["### 5.7. Random-restart Hill-climbing\n","All previous versions are **incomplete** because of getting stuck on local optima, but the **random-restart hill-climbing** gives a complete algorithm. \n","In random-restart hill-climbing, start with the **initial random state**, and if terminates with the failure, choose another initial random state, and so on... \n"," If **p** be the probability of success in each hill-climbing search, then the **expected number of restarts will be 1/p**. \n","When multiple restarts are allowed, performance improves...\n"]},{"cell_type":"markdown","metadata":{"id":"0-QbYjdabslA"},"source":["### 5.8. Hill-Climbing with both Random Walk & Random Sampling\n","If we want to increase the randomness we can combine ideas of **greedy local search**, **random walk**, and **random restart**.\n","At each step do one of the three with the same probability:\n","*\t**Greedy**: move to the neighbor with the largest value\n","*\t**Random Walk**: move to a random neighbor\n","*\t**Random Restart**: Start over from a new, random state\n","\n"]},{"cell_type":"markdown","metadata":{"id":"BY3kkElJb-DZ"},"source":["### 5.9. Tabu search:\n","**Tabu Search** works like hill-Climbing, but it maintains a **tabu list** of constant size, like k, to avoid getting stuck in local optima. The tabu list holds k recent used objects that are taboo to use for now. Moves that involve an object in the tabu list, are not accepted.\n","Tabu search raises the space complexity from O(1) to O(k) but in many problems that use sideway moves, it improves the performance of hill-climbing.\n"]},{"cell_type":"markdown","metadata":{"id":"6sz3ve2cyXSi"},"source":["## 6. Simulated annealing"]},{"cell_type":"markdown","metadata":{"id":"01FRBl3ayXSm"},"source":["__Simulating annealing (SA)__ is one the search algorithms.The idea which is used for SA is close to random walking in other search algorithms. SA uses physical concepts for escaping local optimas by allowing some bad moves and gradually decreasing their size and frequency because if these bad moves go on and the answer be somewhere near global optima, it will get far from global optima.This method proposed in 1983 by IBM researchers for solving VLSI layout problems."]},{"cell_type":"markdown","metadata":{"id":"1TRskALeyXSp"},"source":["Let's have a look at a physical analogy:\n","- Imagine letting a ball roll downhill on the function surface\n","- Now shake the surface, while the ball rolls\n","- Gradually reduce the amount of shaking"]},{"cell_type":"markdown","metadata":{"id":"c_c1aLqHyXSr"},"source":["The picture below demonstraits the places where ball probably will be and the next state is getting closer to goal state which is global optima:\n",""]},{"cell_type":"markdown","metadata":{"id":"_U52mJKmyXSt"},"source":["Simulated annealing refers to the process of cooling a liquid until it form crystalline shape. This physiacal process must be done slowly to form better crystalline shapes.At first molecules of liquid have too much kinetic energy and are moving so fast with brownian motions, by cooling it slowly seems that the energy is getting less and less. In this process due to the fact that we are reducing the temperature gradually, number of bad moves or moves with too much energy will decrease until it converges to global optima."]},{"cell_type":"markdown","metadata":{"id":"yIv8xVsWyXSw"},"source":["Based on this intuition:\n","- Define a variable named T for the temperature.\n","- The value of T is high at first.\n","- According to temperature schedule, reduce this value.\n"," - In high temperature probability of \"locally bad\" moves is higher.\n"," - In low temperature probability of \"locally bad\" moves is lower."]},{"cell_type":"markdown","metadata":{"id":"SadVzy29yXSy"},"source":["### 6.1. Pseudocode"]},{"cell_type":"markdown","metadata":{"id":"2-eWnSM4yXSz"},"source":["The following pseudocode presents the simulated annealing heuristic as described above:"]},{"cell_type":"markdown","metadata":{"id":"lmApoYIryXS1"},"source":[""]},{"cell_type":"markdown","metadata":{"id":"zFq3pNm5yXS3"},"source":["### 6.2. Effect of temperature"]},{"cell_type":"markdown","metadata":{"id":"jrTdqq_eyXS6"},"source":["This picture illustrates 2 points:\n","- At first, the high temprature causes more bad moves and the acceptation probability drops slowly(low slope).\n","- As the temperature decreases, the bad moves' probability converges to zero so fast(high slope)."]},{"cell_type":"markdown","metadata":{"id":"7ErvIyi9yXS7"},"source":["\n"]},{"cell_type":"markdown","metadata":{"id":"Uoh4c_-pyXS8"},"source":["In this exmaple, SA is searching for a maximum. By cooling the temperature slowly, the global maximum is found. "]},{"cell_type":"markdown","metadata":{"id":"dzrxlYXNyXS-"},"source":[""]},{"cell_type":"markdown","metadata":{"id":"vyuR-PhAyXS_"},"source":["### 6.3. Simulated Annealing in practice"]},{"cell_type":"markdown","metadata":{"id":"iFT5AY68yXTC"},"source":["__How to define this schedulability?__\n","
\n","There is only one theorem about this.\n","
\n","_Theorem_: If T is decreased sufficiently slow, global optima will be found approximately with probability of 1.\n","
\n","__Is this rate same for all problems?__\n","
\n","No, it depends on the problem.\n","
\n","__Now, Is this theorem a useful guarantee?__\n","
\n","Convergence can be guaranteed if at each step, T drops no more quickly than $\\frac{C}{log n}$, where C is a constant and problem dependent and n is the number of steps so far.In practice different Cs are used to find the best choice for problem."]},{"cell_type":"markdown","metadata":{"id":"8h3Uy0C8yXTF"},"source":["### 6.4. Other applications"]},{"cell_type":"markdown","metadata":{"id":"sFC7Qy5vyXTH"},"source":["- [Traveling salesman](https://en.wikipedia.org/wiki/Travelling_salesman_problem)\n","- [Graph partitioning](https://en.wikipedia.org/wiki/Graph_partition)\n","- [Graph coloring](https://en.wikipedia.org/wiki/Graph_coloring)\n","- [Scheduling](https://en.wikipedia.org/wiki/Scheduling_(computing))\n","- [Facility layout](https://www.managementstudyguide.com/facility-layout.htm)\n","- [Image processing](https://en.wikipedia.org/wiki/Digital_image_processing)\n","- ..."]},{"cell_type":"markdown","metadata":{"id":"pKk-vJqZyXTL"},"source":["## 7. Local beam search"]},{"cell_type":"markdown","metadata":{"id":"eg3tHaSA4IG3"},"source":["Keeping only one node in memory is an extreme reaction to memory problems.\n","
\n","__Local beam search__ is another algorithm which keeps track of k states instead of keeping only one node in memory."]},{"cell_type":"markdown","metadata":{"id":"-eg2kNln88KD"},"source":["**Now, How?**\n","
\n","- Initially: Select k states randomly. \n","- Next: Determine all successors of k states.\n","- If any successor is goal, search has finished.\n","- Else select k best from successors and repeat."]},{"cell_type":"markdown","metadata":{"id":"BtK27rSv-6_d"},"source":["This is an example of **Local Beam Search** when k = 3:"]},{"cell_type":"markdown","metadata":{"id":"r39NLpIb59Zw"},"source":["\n"]},{"cell_type":"markdown","metadata":{"id":"5gjLKGoYFCzp"},"source":["$\\star$ Note that this algorithm is not the same as k random-start searches run in parallel. In Beam search, searches that find good states recruit other searches to join them.\n"]},{"cell_type":"markdown","metadata":{"id":"V9F_sDsgMtGI"},"source":["### 7.1. Stochastic Beam Search"]},{"cell_type":"markdown","metadata":{"id":"NxVbZIVbMvtu"},"source":["Quite often, all k states end up on same local hill.\n","
\n","__So, What should be done?__\n","
\n","The idea is to use **Stochastic beam search** which chooses k successors randomly,biased towards good ones."]},{"cell_type":"markdown","metadata":{"id":"ITypdfm7AQCd"},"source":["### 7.2. Uses"]},{"cell_type":"markdown","metadata":{"id":"N58yi-AvAWLU"},"source":["This algorithm has many uses in:\n","- MT ([Machine Translation](https://en.wikipedia.org/wiki/Machine_translation))\n","- NLP ([Natural Language Processing](https://en.wikipedia.org/wiki/Natural_language_processing))"]},{"cell_type":"markdown","metadata":{"id":"qsar3LpvjjlT"},"source":["## 8. Genetic Algorithms"]},{"cell_type":"markdown","metadata":{"id":"f2RXmJtmjm-3"},"source":["- ### A variant of stochastic beam search\n","Successors can be generated by combining two parent states rather than modifying a single state\n"]},{"cell_type":"markdown","metadata":{"id":"Xy3_XnsZj67K"},"source":["### 8.1. Algorithm"]},{"cell_type":"markdown","metadata":{"id":"cFUrtth1kFkb"},"source":["- A State (solution) is represented as a string over a finite alphabet (e.g. a chromosome containing genes)\n","\n","- Start with *k* randomly generated states (**Population**)\n","\n","- Evaluation function to evaluate states (Higher values for better states) (**Fitness function**)\n","\n","- Combining two parent states and getting offsprings (**Cross-over**)\n"," - Cross-over point can be selected randomly\n","\n","- Reproduced states can be slightly modified with a probability of *P* (**mutation**)\n","\n","- The next generation of states is produces by selection (based on fitness function), crossover and mutation \n"]},{"cell_type":"markdown","metadata":{"id":"Gw4E2VAVlghB"},"source":["Keeping all these in mind, we will go into more detail in the below example"]},{"cell_type":"markdown","metadata":{"id":"Ez9hAQqyln4_"},"source":["### 8.2. Example: 8-Queens\n"]},{"cell_type":"markdown","metadata":{"id":"9ZRp1X8Ilq-Z"},"source":["- Describe the state as a string\n","\n"," "]},{"cell_type":"markdown","metadata":{"id":"-AE68ZMGmSQS"},"source":["- **Fitness function** : number of non-attacking pairs of queens (24 for above figure)"]},{"cell_type":"markdown","metadata":{"id":"vtpXLBZxmeop"},"source":["- **Cross-over** : To select some part of the state from one parent and the rest from another\n","\n"," "]},{"cell_type":"markdown","metadata":{"id":"jMLjQKI0m9hT"},"source":["- **Mutation** : To change a small part of one state with a small probability \n","\n"," "]},{"cell_type":"markdown","metadata":{"id":"gmv2GHeBnkiU"},"source":["- **Selection** : We can also have a selection step that selects from the population and the probability of the selection of each individual in population is with respect to it's fitness value (See example below)"]},{"cell_type":"markdown","metadata":{"id":"5qSmgLTSoFyk"},"source":["### 8.3. Another variant of genetic algorithm for 8-Queens"]},{"cell_type":"markdown","metadata":{"id":"x2xfQjxBoqqu"},"source":[""]},{"cell_type":"markdown","metadata":{"id":"Se5LpXkGoswV"},"source":["And in the picture below you can see the way we calculated the fitness function"]},{"cell_type":"markdown","metadata":{"id":"c8d4FFOboMpo"},"source":[""]},{"cell_type":"markdown","metadata":{"id":"N52Mb_yQoi2O"},"source":["### 8.4. Pros. and Cons."]},{"cell_type":"markdown","metadata":{"id":"q0QnVxXKpIpE"},"source":["- **Positive points**\n"," - Random exploration can find solutions that local search can't (via crossover primarily)\n","\n"," - Appealing connection to human evaluation (\"neural\" networks, and \"genetic\" algorithms are metaphors!)\n","\n","- **Negative points**\n"," - Large number of \"tunable\" parameters\n"," - Lack of good empirical studies comparing to simpler methods\n"," - Useful on some (small?) set of problems but no convincing evidence that GAs are better than hill-climbing with random restarts in general"]},{"cell_type":"markdown","metadata":{"id":"sEackcKB82NI"},"source":["## 9. Summary"]},{"cell_type":"markdown","metadata":{"id":"9eMLSNE8858v"},"source":["All the introduced methods are related to the search problems which are computationally hard. These algorithms move from solution to solution in the space of candidate solutions (the search space) by applying local changes, until a solution deemed optimal is found or a time bound is elapsed.\n","\n","As mentioned before, in the exploration of search space, the space complexity was exponential; But using these local algorithms, it is reduced to O(1) instead, and the computational time complexity, which was exponential, is reduced to O(T) where T is the number of iterations.\n","\n","\n"]},{"cell_type":"markdown","metadata":{"id":"D4TZ11yp7YyK"},"source":["## 10. References"]},{"cell_type":"markdown","metadata":{"id":"Wjid5Lxb7h9y"},"source":["\n","\n","* [AI course at Sharif University of Technology](http://ce.sharif.edu/courses/99-00/1/ce417-2/index.php/section/resources/file/resources)\n","* https://en.wikipedia.org/wiki/Simulated_annealing\n"]},{"cell_type":"code","metadata":{"id":"0QkTU_BU7pqA"},"source":[""],"execution_count":null,"outputs":[]}]}
\ No newline at end of file
diff --git a/notebooks/5_local_search/metadata.yml b/notebooks/5_local_search/metadata.yml
deleted file mode 100644
index bbd941b8..00000000
--- a/notebooks/5_local_search/metadata.yml
+++ /dev/null
@@ -1,40 +0,0 @@
-title: LN | Local Search
-
-header:
- title: Local Search
-
-authors:
- label:
- position: top
- text: Authors
- kind: people
- content:
- - name: Mahsa Amani
- role: Author
- contact:
- - icon: fab fa-github
- link: https://github.com/mahsaama
- - icon: fas fa-envelope
- link: mailto:mahsa.ama1391@gmail.com
-
- - name: Mobina Poornemant
- role: Author
- contact:
- - icon: fab fa-github
- link: https://github.com/mbinapournemat
- - icon: fas fa-envelope
- link: mailto:Mobina.poornemat@gmail.com
-
- - name: Arman Zarei
- role: Author
- contact:
- - icon: fab fa-github
- link: https://github.com/armanzarei
- - icon: fas fa-envelope
- link: mailto:armanzarei1378@gmail.com
-
- - name: Hossein Aghamohammadi
- role: Supervisor
- contact:
- - icon: fas fa-envelope
- link: mailto:hsnam861@gmail.com
From 7c3ae3eaefd1d84970461e3e53305cd49d7e1914 Mon Sep 17 00:00:00 2001
From: AmiraliE1380 <60638047+AmiraliE1380@users.noreply.github.com>
Date: Fri, 29 Oct 2021 21:43:19 +0330
Subject: [PATCH 02/32] Create 5_local_search
---
notebooks/5_local_search | 1 +
1 file changed, 1 insertion(+)
create mode 100644 notebooks/5_local_search
diff --git a/notebooks/5_local_search b/notebooks/5_local_search
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/notebooks/5_local_search
@@ -0,0 +1 @@
+
From b857a28531dea22c84d0fdc2508f9f7817f7396c Mon Sep 17 00:00:00 2001
From: AmiraliE1380 <60638047+AmiraliE1380@users.noreply.github.com>
Date: Fri, 29 Oct 2021 21:43:46 +0330
Subject: [PATCH 03/32] Delete 5_local_search
---
notebooks/5_local_search | 1 -
1 file changed, 1 deletion(-)
delete mode 100644 notebooks/5_local_search
diff --git a/notebooks/5_local_search b/notebooks/5_local_search
deleted file mode 100644
index 8b137891..00000000
--- a/notebooks/5_local_search
+++ /dev/null
@@ -1 +0,0 @@
-
From 35d7a3b666d56e93605e504b6f8fe3c654320ae0 Mon Sep 17 00:00:00 2001
From: AmiraliE1380 <60638047+AmiraliE1380@users.noreply.github.com>
Date: Fri, 29 Oct 2021 21:46:25 +0330
Subject: [PATCH 04/32] Create index.md
---
notebooks/5_local_search/index.md | 1 +
1 file changed, 1 insertion(+)
create mode 100644 notebooks/5_local_search/index.md
diff --git a/notebooks/5_local_search/index.md b/notebooks/5_local_search/index.md
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/notebooks/5_local_search/index.md
@@ -0,0 +1 @@
+
From 1e200d78f745adb058b87ef1706d33e3a180f03c Mon Sep 17 00:00:00 2001
From: AmiraliE1380 <60638047+AmiraliE1380@users.noreply.github.com>
Date: Fri, 29 Oct 2021 21:51:00 +0330
Subject: [PATCH 05/32] Update index.md
---
notebooks/5_local_search/index.md | 467 ++++++++++++++++++++++++++++++
1 file changed, 467 insertions(+)
diff --git a/notebooks/5_local_search/index.md b/notebooks/5_local_search/index.md
index 8b137891..efcbc292 100644
--- a/notebooks/5_local_search/index.md
+++ b/notebooks/5_local_search/index.md
@@ -1 +1,468 @@
+# Local Search
+## Contents
+
+- Introduction
+ - What is Local Search?
+ - Advantages
+- Methods
+ - Hill Climbing
+ - Tabu Search
+ - Local Beam Search
+ - Simulated Annealing
+ - Genetic Algorithms
+ - Large Neighborhood Search
+- Summary
+- References
+
+## 1. Introduction
+
+### 1.1. What is Local Search?
+
+Local Search is a heuristic method for solving computationally hard contraint satisfaction or optimization problems. The family of local search methods are typically used is search problems where the search space is either very huge or infinite. In such Problems classical search algorithms do not work efficiently.
+
+Usually local search is used for problems which have a state as its solution, and for many problems the path to the final solution is irrelevent. The procedure of this method is quite simple, at first the algorithm starts from a solution which may not be optimal, or may not satisfy all the constraints, and by every step or iteration, the algorithm tries to find a slightly better solution. This gradual improvement of the solution is done by examining different neighbors of the current state, and chosing the best neighbor as the next state of the search.
+
+An example of the applications of local search is solving the TSP problem. In each step we may try to replace two edges by two other edges which may result in a shorter cycle in the graph.
+
+
+### 1.2. Advantages
+
+Local search has a memory complexity of O(1) which is very efficient. This is the case because only the current state of the program is saved in memory. The time complexity of local search is O(T) which T is the number of iterations.
+
+
+## 2. Methods
+
+### 2.1. Hill Climbing
+Imagine you want to climb a mountain and you need to find a path that leads to the peak. And ofcourse you want to do this as fast as possible. What would you do if you were in this situation?
+The first inituitive idea that comes to mind is roughly simple, in each step try to go as high as possible, done. This is what '*Hill Climbing*' algorithm do. This iterative algorithm starts with a random state and in each iteartion tries to do the best, which means chossing a neighbor that has the highset value among all other neighbors. This algorithm continues till we reach a local maximum.
+
+```
+function Hill-Climbing(problem) returns a state
+ current <- make_node(problem.initial-state)
+ while (True):
+ neighbor <- highest-valued successor of current
+ if neighbor.value <= current.value:
+ return current
+ current <- neighbor
+```
+
+
+
+###### Example 2.1.1 (8-queens Problem)
+This is one of the problmes which can be formulated as a *'local search'* problem. Our goal is to place 8 queen on a chess board in a way that no queen attacks the others. Each state is a placing of queens on board and the value of each state is 'the number of attacking queens'. This problem is a minimization version of local search and our goal is to find a state that has the least cost(value). The successor of each state comes from moving just one queen in her column.
+
+Using *'hill climbing'* to solve this problem leads to following results:
+
+- (Probability of sucesse for a random initial state) $p = 0.14$
+- Average number of moves to terminate per trial:
+ - $4$ when succeeding
+ - $3$ when getting stuck
+- Expected total number of moves for an instance:
+ - $3\frac{(1-p)}{p} + 4 \approx 22$ moves needs
+
+
+
+#### 2.1.1 Hill Climbing Pros and Cons
+This greedy algorithm is simple enough to implement, it just consists of a loop and a search to find best neighbor. Also it doesn't require any special data structure cause in each state we just need current state and its neighbores. But this simplisity comes with costs. Unfortunately *'hill climbing'* will not work well in the following situations:
+
+- **Local Maxima**: First of all, by using this algorithm we might stuck in local maxima! A local maxima is an state which has higher value than all of its neighbors. If algorithm starts from near this states, it will stuck in this points and will not find global maxima. so this version of 'hill climbing' is *incomplete*.(Figure-2)
+- **Ridges**: Ridges are situations that there exist some local maxima but they are not connected directly to each other and its hard for algorithm to choise where to go when reachs this points. (Figure-2)
+- **Plateaus**: This is a situation that there exist a flat area or flat maxima in space. In case of flat maxima again we stuck in local maxima, and in case of flat area (shoulders) algorithm will terminate cause current value is equal to or greather than all other its neighbors, but it hasn't find any maximal point.
+
+
+
+To solve above problme of *'hill climbing'*, different versions of this algorithm have been developed. In the next section we are going to briefly talk about this versions.
+#### 2.1.2 Versions of Hill Climbing
+##### 2.1.2.1 Using Sideway Moves
+This version has been invented to solve *'Plateaus'* problem. The only different is that in this version, algorithm is allowed to move along plateaus in hope to get out of shuolders. But if we use sideway moves without any consideration, it might get stuck in a flat maxima cause it will go back and forth between this region states. To solve this problem we add a limitation on the number of consecutive sideway moves to prevent algorithm from getting stuck in infinite loops.
+
+###### Example 2.1.2 (8-queens)
+If we run 'hill climbing with sideway moves' on 8-queens problem, the results get much better but it comes with a cost. The number of moves for algorithm increase.
+
+- (Probability of success) $p = 0.94$
+- Average number of moves to terminate per trial:
+ - 21 when succeeding
+ - 65 when getting stuck
+- Expected total number of moves for an instance:
+ - $65\frac{(1-p)}{p} + 21 \approx 25$ moves needs
+
+##### 2.1.2.2 Stochastic hill climbing
+This version has been developed to solve *'incompletness*' of hill climbing, but does not completely solve this problem. It only helps to have chance to escape from local maximas. The different of this version and original *'hill climbing*', comes from 'choosing neighbors' step. This algorithm doesn't always choose the best neighbor, however with probability $p$ does so, and with probability $1-p$ choose a random neighbor. This stochastic neighbor selection helps algorithm to be able to escape from getting stuck in local maxials. But as said before, this approach doesn't completely solve *'incompleteness'* problem of *'hill climbing'*
+
+##### 2.1.2.3 Random-restart hill climbing
+This version has been developed to solve *'local maxima'* problem. In this version we don't change the core of 'hill climbing', but we just run the original algorithm many times till we find the optimal goal. This version of *'hill climbing'* is complete with probability approaching 1, cause it will eventually generate a goal state as the initial state. If each run of *'hill climbing'* success with probabilty $p$, then the expected number of restarts we need will be $\frac{1}{p}$.
+
+###### Example 2.1.3 (8-queens)
+Running 8-queens problem with this algorithm results as follow:
+- Without sideway moves: ($p = 0.14$)
+ - Expected number of iterations: $\frac{1}{p} \approx 7$
+- With sideway moves: ($p = 0.94$)
+ - Expected number of iterations: $\frac{1}{0.94} \approx 1.04$
+
+### 2.2 Tabu Search
+This algorithm is similar to *'hill climbing'* but uses a trick to prevent from stucking in local maxima. This is actualy a meta-heuristic algorithm that means it helps to guide and control actual heuristic. But how this strategy helps us to find global optimal?
+First of all, it has a list called 'tabu list' which has some states. Like hill climbing, from each state we are going to find its neighbors and choose one of them. But here we are not allowed to choose those states that are in tabu list, they are taboo. Also we don't stop if the best neighbor is not as good as current state, if it was so, we update best solution and move to that state and if it wasn't, we just move to the new state. The termination creteria can be a limitation on number of iterations. Below you can find a flowchart of this algorithm steps.
+
+
+
+Here we suppose to have a strategy to determine which states should be added to tabu list and which should take out of this list.
+
+### 2.3 Local Beam Search
+Imagine you are living on Kepler-442b (which is an Earth-like exoplanet) and you've found a wide plain that consists of treasure. But you don't know where the treasure is, and you just know how probable is a cell of this field to have treasure beneath it. What strategy do you adopt to find the most probable cell to have treasure?
+
+
+
+Ofcourse using *'hill climbing'* will be one of the answers but it might find local maxiam while you want to find global maxima. What about calling your friends and searching the field together? (and may or may not divide treasure with them)
+This will be a good strategy to search the field together (you and $k-1$ of your friends), in a way that each of you broadcasts the list of neighbors of his current cell to others, and you all have a shared list which consists of all neighbors all of you currently see. Then choose the best $k$ neighbors and each of you visit one of these neighbors and again broadcast new neighbors and $\cdots$ . Continue this approach till the best of $k$ neighbors you choose is less than or equal probable to the best of your current cells.
+The strategy you adopt to find treasure is called *'Beam Search'*. The different of this algorithm and $k$ run of parallel *'hill climbing'* is clear. In this algorithm you might continue searching by one of your friends neighbor cell but, in parallel *'hill climbing'* you just follow your path and starts from different part of the field.
+
+```
+function Local-Beam-Search(problem) return state
+ current[k] <- k-initial state
+ while True:
+ neighbors[k] <- k-best neighbors of all state in current[k]
+ if best_of(neighbor[k]) <= best_of(current[k]):
+ return best_of(current[k])
+ current[k] <- neighbors[k]
+```
+
+### 2.4 Simulated Annealing
+
+The Simulated Annealing (SA) algorithm is based upon Physical Annealing in real life. Physical Annealing is the process of heating up a material until it reaches an annealing temperature and then it will be cooled down slowly in order to change the material to a desired structure. When the material is hot, the molecular structure is weaker and is more susceptible to change. When the material cools down, the molecular structure is harder and is less susceptible to change.
+
+Simulated Annealing (SA) mimics the Physical Annealing process but is used for optimizing parameters in a model. This process is very useful for situations where there are a lot of local minima algorithms would be stuck at.
+
+
+
+In problems like the one above, if a local minima algorithm like Gradient Descent started at the starting point indicated, it would be stuck at the local minima and not be able to reach the global minima.
+
+#### 2.4.1 Algorithm
+
+0. Preparation
+ * Temperature reduction function
+1. Start with an initial solution s = S₀. This can be any solution that fits the criteria for an acceptable solution. We also start with an initial temperature T = t₀.
+2. Select a neighbour randomly among neighbourhood of the current solution. The neighbourhood of a solution are all solutions that are close to the solution. For example, the neighbourhood of a set of 5 parameters might be if we were to change one of the five parameters but kept the remaining four the same.
+3. Decide whether to move to the neighbour found in step 2. Mostly by calculating the difference in cost between the current solution and the new neighbour solution. if the difference in cost between the current and new solution is greater than 0 (the new solution is better), then accept the new solution. If the difference in cost is less than 0 (the old solution is better), then accept it by the probabilty function respected to the difference and T.
+4. Decrease the temperature according to temperature reduction function.
+5. Repeat steps 2, 3, 4 until the termination conditions are reached.
+
+
+
+##### Psudocode
+
+```
+ Simulated_Annealing(problem, schedule) returns a solution state
+
+ current = make_node(problem.initial_state)
+ for t = 1 to +INF:
+ T = schedule(t)
+ if T=0 then return current
+ next = a randomly selected successor of current
+ delta = next.value - current.value
+ if delta > 0 then current = next
+ else current = next only with probability of e^(delta/T)
+```
+
+#### 2.4.2 Temperature reduction function
+
+temperature reduction function determines how to reduce the temerature in each iteration. there are usually 3 main types of temperature reduction rules: (there are some arbitrary constants in most of temperature reduction functions which should be tuned)
+
+- Linear Reduction Rule: t = t - alpha
+- Geometric Reduction Rule: t = t * alpha
+- Slow-Decrease Rule: t = t/(1 + beta * t)
+
+The mapping of time to temperature and how fast the temperature decreases is called the Annealing Schedule.
+
+#### 2.4.3 Probabilty function
+
+Probabilty function determines chance of going to new neighbour. The equation has been altered to the following:
+
+
+
+Where the delta c is the change in cost and the t is the current temperature.
+
+#### 2.4.4 High vs. Low temperature
+
+Due to the way the probability is calculated, when the temperature is higher, is it more likely that the algorithm accepts a worse solution. This promotes Exploration of the search space and allows the algorithm to more likely travel down a sub-optimal path to potentially find a global maximum.
+
+
+
+When the temperature is lower, the algorithm is less likely or will not to accept a worse solution. This promotes Exploitation which means that once the algorithm is in the right search space, there is no need to search other sections of the search space and should instead try to converge and find the global maximum.
+
+
+
+So at first, the high temprature causes more bad moves and the acceptation probability drops slowly(low slope). and as the temperature decreases, the bad moves' probability converges to zero so fast(high slope).
+
+In this exmaple, SA is searching for a maximum. By cooling the temperature slowly, the global maximum is found.
+
+
+
+#### 2.4.5 Simulated Annealing in practice
+
+- Defining the schedulability
+There is only one theorem about this.
+
+- **Theorem:** If T is decreased sufficiently slow, global optima will be found approximately with probability of 1.
+
+- Convergence can be guaranteed if at each step, T drops no more quickly than C/logn, where C is a constant and problem dependent and n is the number of steps so far. In practice different Cs are used to find the best choice for problem.
+
+#### 2.4.6 Pros and Cons
+
+- **Positive points:**
+ - Easy to implement and use
+ - Provides optimal solutions to a wide range of problems
+
+
+- **Negative points:**
+ - Can take a long time to run if the annealing schedule is very long
+ - There are a lot of "tuneable" parameters in this algorithm
+
+#### 2.4.7 Applications:
+
+- [Traveling salesman](https://en.wikipedia.org/wiki/Travelling_salesman_problem)
+- [Graph partitioning](https://en.wikipedia.org/wiki/Graph_partition)
+- [Graph coloring](https://en.wikipedia.org/wiki/Graph_coloring)
+- [Scheduling](https://en.wikipedia.org/wiki/Scheduling_(computing))
+- [Facility layout](https://www.managementstudyguide.com/facility-layout.htm)
+- [Image processing](https://en.wikipedia.org/wiki/Digital_image_processing)
+- ...
+
+### 2.5 Genetic algorithms
+
+Genetic algorithms is a group of algorithms which are search heuristic that are inspired by Charles Darwin’s theory of natural evolution. These algorithms reflect the process of natural selection where the fittest individuals are selected for reproduction in order to produce offspring of the next generation.
+
+
+
+In a genetic algorithm, a population of candidate solutions (called individuals, creatures, or phenotypes) to an optimization problem is evolved toward better solutions. Each candidate solution has a set of properties (its chromosomes or genotype) which can be mutated and altered; traditionally, solutions are represented in binary as strings of 0s and 1s, but other encodings are also possible.
+
+The evolution usually starts from a population of randomly generated individuals, and is an iterative process, with the population in each iteration called a generation. In each generation, the fitness of every individual in the population is evaluated; the fitness is usually the value of the objective function in the optimization problem being solved. The more fit individuals are stochastically selected from the current population, and each individual's genome is modified (recombined and possibly randomly mutated) to form a new generation. The new generation of candidate solutions is then used in the next iteration of the algorithm. Commonly, the algorithm terminates when either a maximum number of generations has been produced, or a satisfactory fitness level has been reached for the population.
+
+#### 2.5.1 Algorithm
+
+0. Preparation
+ - Genetic representation
+ - Fitness function
+1. Initial population
+2. Selection
+3. Genetic operators
+ - Crossover
+ - Mutation
+4. Repeat 2 and 3 until Termination
+
+#### Psudocode
+
+ Genetic-Algorithm(population, Fitness-Fn) returns individual
+
+ repeat
+ new_population = empty_set
+ for i = 1 to Size(population) do
+ x = Random_Selection(population, Fitness_Fn)
+ y = Random_Selection(population, Fitness_Fn)
+ child = Reproduce(x, y)
+ if(small random probabilty) then child = Mutate(child)
+ add child to new_population
+ population = new_population
+ until some individual is fit enough, or enough time has elapsed
+ return the best individual in population, according to Fitness_Fn
+
+ Reproduce(x, y) returns an individual
+
+ n = length(x); c = random between 1 to n
+ return append(substring(x,1,c),substring(y, c+1, n))
+
+##### 2.5.1.1 Preparation
+
+###### Genetic representation
+In the genetic algorithms, An individual is characterized by a set of parameters (variables) known as Genes. Genes are joined into a string to form a Chromosome (solution). The genetic representation is the way that the individuals are modeled to be used in the algorithm. The most standard one which is used in the genetic algorithms is an array of bits. other representations can be true in some questions but the crossover or mutation will be more complex than array of bits.
+
+
+
+###### Fitness function
+The fitness function determines how fit an individual is (the ability of an individual to compete with other individuals). It gives a fitness score to each individual. The probability that an individual will be selected for reproduction is based on its fitness score.
+
+
+##### 2.5.1.2 Initial population
+
+The process begins with a set of individuals which is called a Population. The population size depends on the nature of the problem and often the initial population is generated randomly, allowing the entire range of possible solutions (the search space).
+
+##### 2.5.1.3 Selection
+
+The idea of selection phase is to select the fittest individuals and let them pass their genes to the next generation. Two pairs of individuals (parents) are selected based on their fitness scores. Individuals with high fitness have more chance to be selected for reproduction.
+Note that there exist both asexual and sexual reproduction which in asexual reproduction, the parents are not limited but in sexual reproduction, a child has a mother and a father so a woman can not be a child's father. thus the genetic operators of sexual reproduction is different. And also there are more selection methods which for more information you can follow link below:
+
+- [Roulette Wheel Selection](https://en.wikipedia.org/wiki/Fitness_proportionate_selection)
+- [Scaling Selection](https://link.springer.com/referenceworkentry/10.1007%2F978-0-387-31439-6_242)
+- [Tournament Selection](https://en.wikipedia.org/wiki/Tournament_selection)
+- [Rank Selection](https://en.wikipedia.org/wiki/Selection_(genetic_algorithm))
+- [Hierarchical Selection](https://link.springer.com/article/10.1007/BF00130162)
+
+
+##### 2.5.1.4 Genetic operators
+
+- ***Crossover***
+Crossover is the most significant phase in a genetic algorithm. For each pair of parents to be mated, a number of crossover points are chosen at random from within the genes. Offspring are created by exchanging the genes of parents among themselves until the crossover points are reached. The new offspring are added to the population and replace their parents.(population size must be fixed)
+
+
+
+
+
+- ***Mutation***
+In certain new offspring formed, some of their genes can be subjected to a mutation with a low random probability. This implies that some of the bits in the bit string can be flipped. Mutation occurs to maintain diversity within the population and prevent premature convergence.
+
+
+
+
+
+##### 2.5.1.5 Termination
+
+This generational process is repeated until the population converge or termination condition has been reached.
+
+##### Example 2.5.1: 8-Queens
+Put 8 queens in 8 * 8 board which queens cannot attack eachother.
+
+ 
+
+##### Preparations
+- **Genetic representation**: 8 byte array is used which indices of array show the columns and the values in the array show the rows(1 <= values <= 8) which queens exist. for example, array[i] = j means that a queen exists in (j, i) of the chess board. ([2, 4, 7, 4, 8, 5, 5, 2] for above figure)
+- **Fitness function**: Number of non-attacking pairs of queens. (24 for above figure)
+
+
+##### Initial population
+randomly POPULATION_SIZE individuals are created.
+
+
+##### Selection
+Each individuals have the probabilty according to their fitness((fitness of x) / total fitness of population). Then the parents are selected (number of popualtion should be fixed).
+
+
+
+##### Crossover
+New offspring are generated by selecting some genes from one parent and the rest from another.
+
+ 
+
+
+ ##### Mutation
+ With the propabilty of P, some genes of new children change.
+
+ 
+
+
+In the picture below overview of the solution has shown:
+
+
+
+#### 2.5.2 Pros and Cons
+
+- **Positive Points:**
+ - Random exploration can find solutions that local search can't (via crossover primarily)
+ - Appealing connection to human evaluation ("neural" networks, and "genetic" algorithms are metaphors!)
+
+
+- **Negative Points:**
+ - Large number of "tunable" parameters
+ - Lack of good empirical studies comparing to simpler methods
+ - Useful on some (small?) set of problems but no convincing evidence that GAs are better than hill-climbing with random restarts in general
+
+#### 2.5.3 Applications
+
+It has wide variety of applications in:
+- [Automotive Design](https://en.wikipedia.org/wiki/Automotive_design) ([Relation to simulated annealing](https://www.researchgate.net/publication/221182599_Application_of_Genetic_Algorithms_for_the_Design_of_Large-Scale_Reverse_Logistic_Networks_in_Europe's_Automotive_Industry))
+- [Finance and Investment Strategies](https://en.wikipedia.org/wiki/Investment_strategy) ([Relation to simulated annealing](https://www.wiley.com/en-us/Genetic+Algorithms+and+Investment+Strategies-p-9780471576792))
+- Encryption and Code Breaking ([Relation to simulated annealing](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.324.5081&rep=rep1&type=pdf))
+
+
+### 2.6 Large Neighbourhood Search
+
+Large Neighbourhood Search (LNS) is an iterative local search method for solving optimization problems using Contraint Programming(CP). The algorithm is as follows:
+
+- Start from initial solution S (obtained by CP search)
+- At each iteration of LNS:
+ - Randomly freeze some variables to take their value as in the current S.
+ - Perform CP search on the non-frozen variables in order to find a better solution, replacing S if found.
+ - Repeat from step 2 until a good enough solution is found.
+
+Since LNS requires an initial solution to start from, LNS cannot be directly applied to satisfaction problems, as the initial solution would be final solution. Therefore we have to soften some constraints in order to use LNS for satisfaction problems, so that an initial soft solution can be found and then improved gradually into an actual solution via LNS.
+
+#### 2.6.1 Softening constraints by penalties
+
+A generic way of softening is to replace some constraints by penalty functions, and try to minimize the total penalty. for example:
+
+- Hard constraint: x + y = z
+- Penalty: p = |x + y - z|
+
+##### Example 2.6.1: Sum Of Subsets Problem
+
+Given a set of positive integers a1, a2,…., an upto n integers. Is there a non-empty subset such that the sum of the subset is given as M integer? For example, the set is given as [5, 2, 1, 3, 9], and the sum of the subset is 9; the answer is YES as the sum of the subset [5, 3, 1] is equal to 9.
+
+
+Imagine the set is {10, 7, 5, 18, 12, 20, 15} and the sum is 30.
+
+##### Formulate the problem
+
+ - **Constraints**:
+ - x1 * a1 + x2 * a2 + .... + xn * an = M
+ - for each i, xi = {0, 1}
+
+ - **Softening constraints by penalties**:
+
+ - p = | x1 * a1 + x2 * a2 + .... + xn * an - M | => p = | x1 * 10 + x2 * 7 + x3 * 5 + x4 * 18 + x5 * 12 + x6 * 20 + x7 * 15 - 30|
+
+ - for each i, xi = {0, 1}
+
+##### Find an initial solution using softened constraints:
+
+- Because in our search there is no constraints to cause backtrack, the answer "for each i, xi = 1", is chosen.
+- the penalty is 57
+
+##### Freeze some variables randomly and repeat the constraint search to find lower(better) penalty than current penalty. when it is found, break and go to the next iteration.
+
+- Freeze {x1, x2, x3, x5, x7}
+- Constraint search for non-frozen variables ({x4, x6})
+
+
+
+So as you see, the lower penalty is found, so we update {x1, x2, x3, x4, x5, x6, x7} and p. Then go to the next iteration.
+
+We continue the second step until we reach a good enough penalty and the return the answer.
+
+#### 2.6.2 Pros and Cons:
+
+- **Positive points:**
+ - As shown in figure below for a problem like [car sequencing](https://perso.ensta-paris.fr/~diam/ro/online/cplex/cplex1271/OPL_Studio/opllanguser/topics/opl_languser_app_areas_CP_carpb.html), LNS can solve more instances in compare to hard constraint attitude.
+ - LNS can be quickly put together from existing components. an existing construction heuristic or exact method can be turned into a repair heuristic and a destroy method based on random selection is easy to implement. Therefore we see a potential for using simple LNS for benchmark purposes when developing more sophisticated methods.
+
+
+- **Negative points:**
+ - As shown in figure below, LNS takes longer runtime than hard constraint attitude.
+ - It seems that the initial solution found by LNS is very insufficent and moreover maybe the choices for better neighbourhoods are not well enough. It can be better if we combine some atrributes of backtrack and LNS in each step to reach the better condition. There is a version called Non-failing LNS which has done this and you can look for more details in this link. (https://www.youtube.com/watch?v=VKUxuBaBAkc)
+
+
+
+
+#### 2.6.3 Applications
+
+- [Routing problems](https://en.wikipedia.org/wiki/Vehicle_routing_problem) ([Relation to LNS](https://link.springer.com/chapter/10.1007/3-540-49481-2_30))
+- [Scheduling problems](https://www.quinyx.com/blog/scheduling-problems) ([Relation to LNS](http://kth.diva-portal.org/smash/record.jsf?pid=diva2%3A1530574&dswid=9745))
+
+## 3. Summary
+As mentioned before, local search methods can be used widely in search problems with very big search spaces. In such spaces classic search algoritms cannot work efficiently due to their exponential usage of either memory or time. In contrast, local search methods have a very low memory usage of O(1) which is becuase of the unrelevence of the path to the current solution, and also the time complexity of these methods are O(T) which T is the number of iterations.
+
+Many local search algorithms have been introduced above, and many have been proved to be very efficient for optimization problems, Hill climing for instance was a method to solve such problems. An important challenge for these optimization algorithms was the possibilty of getting stuck in a local optimum, other methods like Simulated Annealing was proposed to face this chalenge and have been shown to be effective.
+
+## 4. References
+
+- https://towardsdatascience.com/optimization-techniques-simulated-annealing-d6a4785a1de7
+
+- https://www.geeksforgeeks.org/genetic-algorithms/
+
+- https://github.com/chengxi600/RLStuff/blob/master/Genetic%20Algorithms/8Queens_GA.ipynb
+
+- https://en.wikipedia.org/wiki/Genetic_algorithm#Optimization_problems
+
+- https://www.youtube.com/watch?v=VKUxuBaBAkc
+
+- AI course at Sharif University of Technology (Fall 1400)
From 201f288aa9076a0284734493cd122e87d456c322 Mon Sep 17 00:00:00 2001
From: AmiraliE1380 <60638047+AmiraliE1380@users.noreply.github.com>
Date: Fri, 29 Oct 2021 21:52:26 +0330
Subject: [PATCH 06/32] Add files via upload
---
notebooks/5_local_search/8-queene-problem.png | Bin 0 -> 23954 bytes
notebooks/5_local_search/8Queens_Genetics.jpg | Bin 0 -> 95959 bytes
notebooks/5_local_search/Genetic_psudocode.jpg | Bin 0 -> 170996 bytes
notebooks/5_local_search/LNS2.png | Bin 0 -> 259631 bytes
notebooks/5_local_search/LNS_ex.jpg | Bin 0 -> 31121 bytes
.../Simulated_Annealing_psudocode.jpg | Bin 0 -> 87542 bytes
notebooks/5_local_search/hc.png | Bin 0 -> 62434 bytes
notebooks/5_local_search/hill-climbing.png | Bin 0 -> 653170 bytes
notebooks/5_local_search/local-beam.jpg | Bin 0 -> 44878 bytes
notebooks/5_local_search/tabu.png | Bin 0 -> 104154 bytes
10 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 notebooks/5_local_search/8-queene-problem.png
create mode 100644 notebooks/5_local_search/8Queens_Genetics.jpg
create mode 100644 notebooks/5_local_search/Genetic_psudocode.jpg
create mode 100644 notebooks/5_local_search/LNS2.png
create mode 100644 notebooks/5_local_search/LNS_ex.jpg
create mode 100644 notebooks/5_local_search/Simulated_Annealing_psudocode.jpg
create mode 100644 notebooks/5_local_search/hc.png
create mode 100644 notebooks/5_local_search/hill-climbing.png
create mode 100644 notebooks/5_local_search/local-beam.jpg
create mode 100644 notebooks/5_local_search/tabu.png
diff --git a/notebooks/5_local_search/8-queene-problem.png b/notebooks/5_local_search/8-queene-problem.png
new file mode 100644
index 0000000000000000000000000000000000000000..f848365dfd0b16d880817c1edcb6a7a6ab5b0743
GIT binary patch
literal 23954
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
z
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