### Install from source

Source: https://pybimstab.readthedocs.io/en/latest/installation.html

Execute the setup script to install the package after downloading the source files.

```bash
$ python setup.py install
```

--------------------------------

### Astar Example Script

Source: https://pybimstab.readthedocs.io/en/latest/astar.html

A complete script example demonstrating pathfinding and plotting for different heuristics.

```python
>>> from numpy import array
>>> from pybimstab.astar import Astar
>>> grid = array([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                  [0, 0, 0, 1, 0, 0, 1, 1, 0, 0],
                  [1, 1, 0, 0, 1, 0, 1, 0, 0, 0],
                  [0, 0, 0, 1, 1, 0, 1, 0, 0, 1],
                  [0, 0, 1, 1, 0, 1, 1, 1, 0, 0],
                  [0, 0, 0, 1, 1, 0, 1, 0, 0, 1],
                  [0, 0, 0, 0, 1, 0, 0, 1, 0, 0],
                  [0, 0, 0, 1, 1, 0, 0, 0, 0, 0],
                  [0, 0, 0, 0, 0, 1, 0, 0, 0, 1],
                  [0, 0, 1, 0, 0, 1, 0, 0, 0, 0]])
>>> for heuristic in ['manhattan', 'euclidean']:
>>>     astar = Astar(grid, startNode=(0, 0), goalNode=(9, 9),
>>>                   heuristic=heuristic, reverseLeft=True,
>>>                   reverseUp=True, preferredPath=None)
>>>     fig = astar.plot()
```

--------------------------------

### Configure Astar with PreferredPath

Source: https://pybimstab.readthedocs.io/en/latest/astar.html

Example of initializing an Astar instance with a grid and a preferred path constraint.

```python
>>> from numpy import array
>>> from pybimstab.astar import PreferredPath, Astar
>>> grid = array([[ 0,  0,  0,  0,  1,  0,  0,  0,  0,  0],
>>>               [ 0,  0,  0,  0,  1,  1,  0,  0,  0,  0],
>>>               [ 0,  0,  0,  1,  1,  0,  1,  0,  1,  0],
>>>               [ 0,  1,  1,  0,  0,  0,  0,  1,  0,  0],
>>>               [ 0,  0,  0,  1,  0,  0,  0,  1,  1,  1],
>>>               [ 0,  0,  1,  0,  1,  1,  0,  0,  0,  0],
>>>               [ 0,  0,  1,  0,  1,  0,  1,  0,  0,  0],
>>>               [ 1,  1,  0,  1,  0,  0,  0,  0,  1,  1],
>>>               [ 1,  0,  0,  0,  0,  0,  0,  0,  0,  0],
>>>               [ 0,  0,  0,  0,  1,  0,  1,  0,  0,  1],
>>>               [ 0,  1,  0,  0,  0,  1,  0,  0,  0,  0],
>>>               [ 1,  0,  0,  0,  0,  0,  0,  0,  0,  0],
>>>               [ 0,  0,  0,  0,  0,  0,  0,  0,  1,  0],
>>>               [ 1,  0,  0,  0,  1,  0,  0,  0,  0,  0]
>>>               ])
>>> coordsIdx = array([[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13,
>>>                     13, 13, 13, 13, 13, 13, 13, 13, 13, 13],
>>>                    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1,
>>>                     2, 3, 4, 5, 6, 7, 8, 9]])
>>> preferredPath = PreferredPath(coordsIdx, factor=1)
>>> astar = Astar(grid, startNode=(0, 0), goalNode=(13, 9),
>>>               heuristic='manhattan', reverseLeft=True,
>>>               reverseUp=True, preferredPath=preferredPath)
>>> astar.__dict__.keys()
dict_keys(['grid', 'startNode', 'goalNode', 'heuristic', 'reverseLeft',
           'reverseUp', 'preferredPath', 'mazeStr', 'optimumPath'])
```

--------------------------------

### Perform Slope Stability Analysis

Source: https://pybimstab.readthedocs.io/en/latest/slopestabl.html

Example demonstrating the setup of slope geometry, slip surface, material parameters, and the execution of the stability analysis.

```python
>>> from numpy import array
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.slipsurface import CircularSurface
>>> from pybimstab.watertable import WaterTable
>>> from pybimstab.slices import MaterialParameters, Slices
>>> from pybimstab.slopestabl import SlopeStabl
>>> slope = AnthropicSlope(slopeHeight=40, slopeDip=[2, 1],
>>>                        crownDist=60, toeDist=30, depth=20)
>>> surface = CircularSurface(slopeCoords=slope.coords,
>>>                           dist1=45.838, dist2=158.726, radius=80)
>>> material = MaterialParameters(
>>>     cohesion=600, frictAngle=20, unitWeight=120, wtUnitWeight=62.4)
>>> watertable = WaterTable(slopeCoords=slope.coords,
                            watertabDepths=array([[0, 140], [20, 0]]))
>>> slices = Slices(
>>>     material=material, slipSurfCoords=surface.coords,
>>>     slopeCoords=slope.coords, numSlices=50,
>>>     watertabCoords=watertable.coords, bim=None)
>>> stabAnalysis = SlopeStabl(slices, seedFS=1, Kh=0)
>>> stabAnalysis.__dict__.keys()
dict_keys(['slices', 'Kh', 'seedFS', 'maxIter', 'tol', 'interSlcFunc',
           'minLambda', 'maxLambda', 'nLambda', 'fsBishop',
           'fsJanbu', 'fsMoment', 'fsForces', 'lambda_',
           'adjustment', 'FS'])
```

--------------------------------

### Initialize TortuousSurface

Source: https://pybimstab.readthedocs.io/en/latest/_modules/slipsurface.html

Example demonstrating the instantiation of a TortuousSurface object and inspection of its internal attributes.

```python
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.bim import BlocksInMatrix
>>> from pybimstab.slipsurface import TortuousSurface
>>> slope = AnthropicSlope(slopeHeight=12, slopeDip=[1, 1.5],
>>>                        crownDist=10, toeDist=10)
>>> bim = BlocksInMatrix(slopeCoords=slope.coords, blockProp=0.25,
>>>                      tileSize=0.25, seed=123)
>>> surface = TortuousSurface(
>>>     bim, dist1=0, dist2=17, heuristic='manhattan',
>>>     reverseLeft=False, reverseUp=False, smoothFactor=0,
>>>     preferredPath=None, prefPathFact=None)
>>> surface.__dict__.keys()
dict_keys(['bim', 'dist1', 'dist2', 'heuristic', 'reverseLeft',
           'reverseUp', 'smoothFactor', 'preferredPath',
           'prefPathFact', 'terrainSurfLS', 'point1', 'end1', 'point2',
           'end2', 'startIdx', 'goalIdx', 'coords'])
```

--------------------------------

### Full WaterTable Workflow Example

Source: https://pybimstab.readthedocs.io/en/latest/watertable.html

Complete workflow including imports, definition of terrain coordinates, slope creation, and water table visualization.

```python
>>> from numpy import array
>>> from pybimstab.slope import NaturalSlope
>>> from pybimstab.watertable import WaterTable
>>> terrainCoords = array(
>>>     [[-2.49, 0.1, 1.7, 3.89, 5.9, 8.12, 9.87, 13.29, 20.29,
>>>       21.43, 22.28, 23.48, 24.65, 25.17],
>>>      [18.16, 17.88, 17.28, 15.73, 14.31, 13.58, 13, 3.61, 3.61,
>>>       3.32, 2.71, 2.23, 1.21, 0.25]])
>>> slope = NaturalSlope(terrainCoords)
>>> watertabDepths = array([[0, 5, 10, 15, 20, 25, 27.66],
>>>                         [8, 7, 6, 3, 1, 1, 0.5]])
>>> watertable = WaterTable(slopeCoords=slope.coords,
>>>                         watertabDepths=watertabDepths,
>>>                         smoothFactor=3)
>>> fig = watertable.plot()
```

```python
>>> from numpy import array
>>> from pybimstab.slope import NaturalSlope
>>> from pybimstab.watertable import WaterTable
>>> terrainCoords = array(
>>>     [[-2.49, 0.1, 1.7, 3.89, 5.9, 8.12, 9.87, 13.29, 20.29,
>>>       21.43, 22.28, 23.48, 24.65, 25.17],
>>>      [18.16, 17.88, 17.28, 15.73, 14.31, 13.58, 13, 3.61, 3.61,
>>>       3.32, 2.71, 2.23, 1.21, 0.25]])
>>> slope = NaturalSlope(terrainCoords)
>>> watertabDepths = array([[0, 5, 10, 15],
>>>                         [8, 7, 3, 0]])
>>> watertable = WaterTable(slopeCoords=slope.coords,
>>>                         watertabDepths=watertabDepths,
>>>                         smoothFactor=3)
>>> fig = watertable.plot()
```

--------------------------------

### Initialize and Plot WaterTable Example 4

Source: https://pybimstab.readthedocs.io/en/latest/_modules/watertable.html

Creates a WaterTable instance with a different set of depth data and generates a plot.

```python
>>> from numpy import array
>>> from pybimstab.slope import NaturalSlope
>>> from pybimstab.watertable import WaterTable
>>> terrainCoords = array(
>>>     [[-2.49, 0.1, 1.7, 3.89, 5.9, 8.12, 9.87, 13.29, 20.29,
>>>       21.43, 22.28, 23.48, 24.65, 25.17],
>>>      [18.16, 17.88, 17.28, 15.73, 14.31, 13.58, 13, 3.61, 3.61,
>>>       3.32, 2.71, 2.23, 1.21, 0.25]])
>>> slope = NaturalSlope(terrainCoords)
>>> watertabDepths = array([[0, 5, 10, 15],
>>>                         [8, 7, 3, 0]])
>>> watertable = WaterTable(slopeCoords=slope.coords,
>>>                         watertabDepths=watertabDepths,
>>>                         smoothFactor=3)
>>> fig = watertable.plot()
```

--------------------------------

### Install pyBIMstab via pip

Source: https://pybimstab.readthedocs.io/en/latest/installation.html

Use this command to install the most recent stable release of the package.

```bash
$ pip install pybimstab
```

--------------------------------

### Initialize and Plot WaterTable Example 3

Source: https://pybimstab.readthedocs.io/en/latest/_modules/watertable.html

Creates a WaterTable instance using specific terrain coordinates and depth data, then generates a plot.

```python
>>> from numpy import array
>>> from pybimstab.slope import NaturalSlope
>>> from pybimstab.watertable import WaterTable
>>> terrainCoords = array(
>>>     [[-2.49, 0.1, 1.7, 3.89, 5.9, 8.12, 9.87, 13.29, 20.29,
>>>       21.43, 22.28, 23.48, 24.65, 25.17],
>>>      [18.16, 17.88, 17.28, 15.73, 14.31, 13.58, 13, 3.61, 3.61,
>>>       3.32, 2.71, 2.23, 1.21, 0.25]])
>>> slope = NaturalSlope(terrainCoords)
>>> watertabDepths = array([[0, 5, 10, 15, 20, 25, 27.66],
>>>                         [8, 7, 6, 3, 1, 1, 0.5]])
>>> watertable = WaterTable(slopeCoords=slope.coords,
>>>                         watertabDepths=watertabDepths,
>>>                         smoothFactor=3)
>>> fig = watertable.plot()
```

--------------------------------

### Get BIM indexes for slip surface ends

Source: https://pybimstab.readthedocs.io/en/latest/_modules/slipsurface.html

Retrieves the array indexes corresponding to the start and end points of the slip surface.

```python
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.bim import BlocksInMatrix
>>> from pybimstab.slipsurface import TortuousSurface
>>> slope = AnthropicSlope(slopeHeight=12, slopeDip=[1, 1.5],
>>>                        crownDist=10, toeDist=10)
>>> bim = BlocksInMatrix(slopeCoords=slope.coords, blockProp=0.25,
>>>                      tileSize=0.25, seed=123)
>>> surface = TortuousSurface(bim, dist1=0, dist2=17)
>>> surface.getIndexesAtEnds()
((66, 0), (23, 68))
```

--------------------------------

### Example script for curve smoothing

Source: https://pybimstab.readthedocs.io/en/latest/smoothcurve.html

Demonstrates smoothing a noisy sine wave with different interpolation orders.

```python
>>> import numpy as np
>>> from pybimstab.smoothcurve import SmoothCurve
>>> x = np.linspace(0, 2*np.pi, 50)
>>> y = np.sin(x) + np.random.random(50) * 0.5
>>> for k in [0, 2, 15]:
>>>     curve = SmoothCurve(x, y, k)
>>>     fig = curve.plot()
```

--------------------------------

### Plotting a Slice with BIM

Source: https://pybimstab.readthedocs.io/en/latest/_modules/slices.html

Example of plotting a slice object that includes BIM data.

```python
>>> from shapely.geometry import LineString
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.bim import BlocksInMatrix
>>> from pybimstab.slices import MaterialParameters, SliceStr
>>> material = MaterialParameters(cohesion=15, frictAngle=23,
>>>                               unitWeight=17)
>>> slope = AnthropicSlope(slopeHeight=7.5, slopeDip=[1, 1.5],
>>>                        crownDist=5, toeDist=5, depth=2)
>>> bim = BlocksInMatrix(slopeCoords=slope.coords, blockProp=0.2,
>>>                      tileSize=0.5, seed=123)
>>> terrainLS = LineString([(6, 8), (7, 6.5)])
>>> slipSurfLS = LineString([(6, 3.395), (7, 2.837)])
>>> watertabLS = LineString([(6, 5), (7, 4)])
>>> slice_ = SliceStr(material, terrainLS, slipSurfLS, watertabLS,
>>>                   bim=bim)
>>> fig = slice_.plot()
```

--------------------------------

### Instantiate and Inspect BlocksInMatrix

Source: https://pybimstab.readthedocs.io/en/latest/bim.html

Example of initializing the class with an AnthropicSlope and inspecting the resulting object attributes.

```python
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.bim import BlocksInMatrix
>>> slope = AnthropicSlope(slopeHeight=12, slopeDip=[1, 1.5],
>>>                        crownDist=10, toeDist=10)
>>> bim = BlocksInMatrix(slopeCoords=slope.coords, blockProp=0.25,
>>>                      tileSize=0.25)
>>> bim.__dict__.keys()
dict_keys(['slopeCoords', 'blockProp', 'tileSize', 'seed', 'grid',
           'xCells', 'yCells'])
```

--------------------------------

### Execute A* Pathfinding Logic

Source: https://pybimstab.readthedocs.io/en/latest/_modules/astar.html

Core implementation of the A* algorithm, managing open and closed lists to find the optimal path between start and goal nodes.

```python
        # Check possible errors in the goal and start cells.
        self.__checkerrors()
        # Required lists
        openList = list()  # open nodes for potential paths
        closeList = list()  # open nodes that have been ruled out
        openList.append(self.mazeStr[self.startNode])
        continueWhile = True
        # Main loop
        while continueWhile:
            # If there is not a solution, stop the program.
            if len(openList) == 0:
                raise ValueError('There is not a path between the start ' +
                                 'and goal nodes')
            # Get the cost of openList
            costList = [node.getGcost(fatherNode=self.mazeStr[node.father]) +
                        node.getHcost(goalNode=self.mazeStr[self.goalNode],
                                      heuristic=self.heuristic,
                                      preferredPath=self.preferredPath)
                        for node in openList]
            # Extract tail-node of current optimum path (currentNode)
            minCostIdx = costList.index(min(costList))  # Index in the list
            currentNode = openList[minCostIdx]  # index of the current node
            openList.pop(minCostIdx)  # delete currentNode from openList
            closeList.append(currentNode)  # add currentNode to closeList
            neighbours = self.getNeighbours(currentNode)  # get the neighbours
            # working on the neighbours of the current node
            for neighbour in neighbours:
                neighbourStr = self.mazeStr[neighbour]
                if (neighbourStr.gCost is not None and
                        np.isinf(neighbourStr.gCost)) or \
                        neighbourStr in closeList:
                    continue
                # verifying if some neighbour is the goal point
                if neighbour == self.goalNode:
                    self.mazeStr[self.goalNode].father = currentNode.pos
                    self.mazeStr[neighbour].getGcost(
                        fatherNode=self.mazeStr[currentNode.pos])
                    self.mazeStr[neighbour].getHcost(
                        goalNode=self.mazeStr[self.goalNode],
                        heuristic=self.heuristic,
                        preferredPath=self.preferredPath)
                    continueWhile = False
                    break
                # If any neighbour is the goal node, A Star continues.
                else:
                    # If the neighbour is in openList: if true, compare the
                    # old gCost (from the previous father) and new gCost (from
                    # the current point which could be the new father) if new
                    # cost is bigger than the old one, leave the original
                    # father, else, change it to the new one.
                    if neighbourStr in openList:
                        oldGcost = neighbourStr.gCost
                        oldFather = neighbourStr.father
                        # changing the attributes: father is current node.
                        self.mazeStr[neighbour].father = currentNode.pos
                        newGcost = self.mazeStr[neighbour].getGcost(
                                fatherNode=self.mazeStr[currentNode.pos])
                        if newGcost > oldGcost:
                            # Coming back to the previous attributes.
                            self.mazeStr[neighbour].father = oldFather
                            self.mazeStr[neighbour].getGcost(
                                    fatherNode=self.mazeStr[oldFather])
                    # If the neighbour is not in the closeList, put it in the
                    # openList.
                    elif neighbourStr not in closeList:
                        self.mazeStr[neighbour].father = currentNode.pos
                        self.mazeStr[neighbour].getGcost(
                            fatherNode=self.mazeStr[currentNode.pos])
                        self.mazeStr[neighbour].getHcost(
                                goalNode=self.mazeStr[self.goalNode],
                                heuristic=self.heuristic,
                                preferredPath=self.preferredPath)
                        openList.append(self.mazeStr[neighbour])
        optimumPath = self.getWayBack(self.mazeStr[self.goalNode])
        setattr(self, 'optimumPath', optimumPath)
        return optimumPath
```

--------------------------------

### Example: defineStructre Method

Source: https://pybimstab.readthedocs.io/en/latest/slipsurface.html

Calculates the geometric properties of the slip surface arc, returning center coordinates and intersection angles.

```python
>>> from numpy import array
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.slipsurface import CircularSurface
>>> slope = AnthropicSlope(slopeHeight=7.5, slopeDip=[1, 1.5],
>>>                        crownDist=5, toeDist=5)
>>> surface = CircularSurface(slopeCoords=slope.coords,
>>>                           dist1=2, dist2=10, radius=9)
>>> surface.defineStructre()
{'center': (10.881322862689261, 10.831744386868543),
 'endAngle': -1.668878272858519,
 'initAngle': -2.979016942655663,
 'point1': array([2.   , 9.375]),
 'point2': array([10.   ,  1.875])}
```

--------------------------------

### Plotting a Circular Slip Surface

Source: https://pybimstab.readthedocs.io/en/latest/_modules/slipsurface.html

Examples demonstrating how to initialize a CircularSurface with different slope types and generate a plot.

```python
>>> from numpy import array
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.slipsurface import CircularSurface
>>> slope = AnthropicSlope(slopeHeight=7.5, slopeDip=[1, 1.5],
>>>                        crownDist=5, toeDist=5)
>>> surface = CircularSurface(slopeCoords=slope.coords,
>>>                           dist1=2, dist2=10, radius=9)
>>> fig = surface.plot()
```

```python
>>> from numpy import array
>>> from pybimstab.slope import NaturalSlope
>>> from pybimstab.slipsurface import CircularSurface
>>> terrainCoords = array(
>>>     [[-2.49, 0.1 , 1.7 , 3.89, 5.9 , 8.12, 9.87, 13.29, 20.29,
>>>       21.43, 22.28, 23.48, 24.65, 25.17],
>>>      [18.16, 17.88, 17.28, 15.73, 14.31, 13.58, 13, 3.61, 3.61,
>>>       3.32, 2.71, 2.23, 1.21, 0.25]])
>>> slope = NaturalSlope(terrainCoords)
>>> surface = CircularSurface(slopeCoords=slope.coords,
>>>                           dist1=7, dist2=20, radius=13)
>>> fig = surface.plot()
```

--------------------------------

### Retrieve wayback path in Astar

Source: https://pybimstab.readthedocs.io/en/latest/_modules/astar.html

Demonstrates how to use the getWayBack method to trace the path from a node back to the start. Note that calling this on a block node raises a ValueError.

```python
>>> import numpy as np
>>> from pybimstab.astar import PreferredPath, Node, Astar
>>> grid = np.zeros((3,3))
>>> grid[1:3, 0:2] = 1
>>> astar = Astar(grid, startNode=(0, 0), goalNode=(2, 2),
>>>               heuristic='manhattan', reverseLeft=True,
>>>               reverseUp=True, preferredPath=None)
>>> # returning the way back
>>> astar.getWayBack(astar.mazeStr[2, 2])
array([[2, 1, 0, 0],
       [2, 1, 1, 0]])
>>> astar.getWayBack(astar.mazeStr[1, 2])
array([[1, 0, 0],
       [2, 1, 0]])
>>> astar.getWayBack(astar.mazeStr[1, 1])
ValueError: Input node is a block. It doesn't have a wayback
```

```python
import numpy as np

if node.val == -1:
    raise ValueError("Input node is outside the allowed cells")
elif node.val == 1:
    raise ValueError(
            "Input node is a block. It doesn't have a wayback")
pathX = list()
pathY = list()
if node.father is not None:
    while node.father != node.pos:
        pathX.append(node.pos[1])
        pathY.append(node.pos[0])
        node = self.mazeStr[node.father]
    pathX.append(self.startNode[1])
    pathY.append(self.startNode[0])
else:
    pathX = []
    pathY = []
wayBack = np.array([pathY, pathX])
return wayBack
```

--------------------------------

### Initialize and Plot Astar Path

Source: https://pybimstab.readthedocs.io/en/latest/astar.html

Demonstrates setting up the Astar solver with specific grid parameters and plotting the resulting path.

```python
>>> from numpy import array
>>> from pybimstab.bim import BlocksInMatrix
>>> from pybimstab.astar import Astar
>>> seed = 111  # for repeatibilty
>>> boundary = array([[-5, 0, 5, 0, -5], [0, 10, 0, -10, 0]])
>>> bim = BlocksInMatrix(slopeCoords=boundary, blockProp=0.2,
>>>                      tileSize=0.4, seed=seed)
>>> astar = Astar(bim.grid, startNode=(0, 12), goalNode=(49, 12),
>>>               heuristic='manhattan', reverseLeft=True,
>>>               reverseUp=True, preferredPath=None)
>>> fig = astar.plot()
```

--------------------------------

### Get Path Backtracking

Source: https://pybimstab.readthedocs.io/en/latest/astar.html

Retrieve the path taken to reach a specific node. Note that attempting to get a path for a blocked node will raise a ValueError.

```python
>>> import numpy as np
>>> from pybimstab.astar import PreferredPath, Node, Astar
>>> grid = np.zeros((3,3))
>>> grid[1:3, 0:2] = 1
>>> astar = Astar(grid, startNode=(0, 0), goalNode=(2, 2),
>>>               heuristic='manhattan', reverseLeft=True,
>>>               reverseUp=True, preferredPath=None)
>>> # returning the way back
>>> astar.getWayBack(astar.mazeStr[2, 2])
array([[2, 1, 0, 0],
       [2, 1, 1, 0]])
>>> astar.getWayBack(astar.mazeStr[1, 2])
array([[1, 0, 0],
       [2, 1, 0]])
>>> astar.getWayBack(astar.mazeStr[1, 1])
ValueError: Input node is a block. It doesn't have a wayback
```

--------------------------------

### getIndexesAtEnds()

Source: https://pybimstab.readthedocs.io/en/latest/_modules/slipsurface.html

Retrieves the array indexes for the start and end points of the slip surface.

```APIDOC
## getIndexesAtEnds()

### Description
Returns the BIM grid-graph array indexes corresponding to the ends of the slip surface.

### Returns
- **tuple** - A tuple containing the indexes for the two ends of the surface.
```

--------------------------------

### Calculate paths using Astar with different heuristics

Source: https://pybimstab.readthedocs.io/en/latest/_modules/astar.html

Demonstrates initializing the Astar class with a grid and calculating paths using Manhattan and Euclidean heuristics.

```python
>>> from numpy import array
>>> from pybimstab.astar import PreferredPath, Astar
>>> grid = array([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                  [0, 0, 0, 1, 0, 0, 1, 1, 0, 0],
                  [1, 1, 0, 0, 1, 0, 1, 0, 0, 0],
                  [0, 0, 0, 1, 1, 0, 1, 0, 0, 1],
                  [0, 0, 1, 1, 0, 1, 1, 1, 0, 0],
                  [0, 0, 0, 1, 1, 0, 1, 0, 0, 1],
                  [0, 0, 0, 0, 1, 0, 0, 1, 0, 0],
                  [0, 0, 0, 1, 1, 0, 0, 0, 0, 0],
                  [0, 0, 0, 0, 0, 1, 0, 0, 0, 1],
                  [0, 0, 1, 0, 0, 1, 0, 0, 0, 0]])
>>> astar = Astar(grid, startNode=(0, 0), goalNode=(9, 9),
>>>               heuristic='manhattan', reverseLeft=True,
>>>               reverseUp=True, preferredPath=None)
>>> astar.getPath()
array([[9, 8, 7, 6, 5, 4, 3, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0],
       [9, 8, 8, 8, 8, 8, 8, 8, 8, 7, 6, 5, 4, 3, 2, 1, 0]])
>>> astar = Astar(grid, startNode=(0, 0), goalNode=(9, 9),
>>>               heuristic='euclidean', reverseLeft=True,
>>>               reverseUp=True, preferredPath=None)
>>> astar.getPath()
array([[9, 8, 7, 6, 5, 4, 3, 2, 1, 0, 0, 0, 0],
       [9, 8, 7, 6, 5, 4, 5, 5, 4, 3, 2, 1, 0]])
```

```python
import numpy as np
```

--------------------------------

### Initialize and Test Polygon with Python

Source: https://pybimstab.readthedocs.io/en/latest/_modules/polygon.html

Demonstrates creating a Polygon instance from coordinates and performing an inclusion test on a set of random points.

```python
>>> import numpy as np
>>> from pybimstab.polygon import Polygon
>>> xC = [np.cos(theta) for theta in np.linspace(0, 2*np.pi, 100)]
>>> yC = [np.sin(theta) for theta in np.linspace(0, 2*np.pi, 100)]
>>> coords = np.array([xC, yC])
>>> np.random.seed(123)
>>> x = np.random.uniform(-1, 1, 100)
>>> y = np.random.uniform(-1, 1, 100)
>>> polygon = Polygon(coordinates=coords)
>>> polygon.isinside(x=x, y=y, meshgrid=False, want2plot=True);
```

--------------------------------

### Initialize Node Object

Source: https://pybimstab.readthedocs.io/en/latest/_modules/astar.html

Demonstrates the initialization of a Node object and inspection of its attributes.

```python
>>> node = Node(pos=(6, 7), father=(5, 7), gCost=5, hCost=10, val=1)
>>> node.__dict__
{'father': (5, 7), 'gCost': 5, 'hCost': 10, 'pos': (6, 7), 'val': 1}
```

--------------------------------

### Node.getGcost

Source: https://pybimstab.readthedocs.io/en/latest/astar.html

Calculates the cumulated cost g(n) from the start node to the current node.

```APIDOC
## Node.getGcost(fatherNode)

### Description
Obtains the cumulated cost g(n) of the traveled path from the start node to the current node n.

### Parameters
- **fatherNode** (Node object) - Required - Object with the structure of the current node's father.

### Returns
- (int or float) - Traveled-path length from the start node to the current node.
```

--------------------------------

### Initialize PreferredPath for A* algorithm

Source: https://pybimstab.readthedocs.io/en/latest/_modules/astar.html

Demonstrates creating a PreferredPath object to influence the A* pathfinding cost function with a polyline and a multiplier factor.

```python
>>> from numpy import array
>>> from pybimstab.astar import PreferredPath
>>> coordsIdx = array([[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13,
                        13, 13, 13, 13, 13, 13, 13, 13, 13, 13],
                       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1,
                        2, 3, 4, 5, 6, 7, 8, 9]])
>>> preferredPath = PreferredPath(coordsIdx, factor=1)
>>> preferredPath.__dict__
{'coordsIdx': array([[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 13,
                      13, 13, 13, 13, 13, 13, 13, 13, 13],
                     [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1,
                      2, 3, 4, 5, 6, 7, 8, 9]]),
 'factor': 1}
```

--------------------------------

### Plotting a Slice without BIM

Source: https://pybimstab.readthedocs.io/en/latest/_modules/slices.html

Example of plotting a slice object that does not contain BIM data.

```python
>>> from shapely.geometry import LineString
>>> from pybimstab.slices import MaterialParameters, SliceStr
>>> material = MaterialParameters(cohesion=15, frictAngle=23,
>>>                               unitWeight=17)
>>> terrainLS = LineString([(6, 8), (7, 6.5)])
>>> slipSurfLS = LineString([(6, 3.395), (7, 2.837)])
>>> watertabLS = LineString([(6, 5), (7, 4)])
>>> slice_ = SliceStr(material, terrainLS, slipSurfLS, watertabLS,
>>>                   bim=None)
>>> fig = slice_.plot()
```

--------------------------------

### Initialize Slices class

Source: https://pybimstab.readthedocs.io/en/latest/slices.html

Demonstrates the instantiation of the Slices class with material parameters and slope geometry.

```python
>>> from numpy import array
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.slipsurface import CircularSurface
>>> from pybimstab.slices import MaterialParameters, Slices
>>> slope = AnthropicSlope(slopeHeight=7.5, slopeDip=[1, 1.5],
>>>                        crownDist=5, toeDist=5)
>>> surface = CircularSurface(slopeCoords=slope.coords,
>>>                           dist1=2, dist2=10, radius=9)
>>> material = MaterialParameters(
>>>     cohesion=15, frictAngle=23, unitWeight=17,
>>>     blocksUnitWeight=21, wtUnitWeight=9.8)
>>> slices = Slices(
>>>     material=material, slipSurfCoords=surface.coords,
>>>     slopeCoords=slope.coords, numSlices=10,
>>>     watertabCoords=None, bim=None)
>>> slices.__dict__.keys()
dict_keys(['material', 'numSlices', 'slipSurfCoords', 'slopeCoords',
           'watertabCoords', 'bim', 'rotationPt', 'slices'])
```

--------------------------------

### Initialize SmoothCurve

Source: https://pybimstab.readthedocs.io/en/latest/_modules/smoothcurve.html

Demonstrates creating an instance of the SmoothCurve class with coordinate lists.

```python
>>> from pybimstab.smoothcurve import SmoothCurve
>>> x = [9, 9, 8, 7, 6, 5, 4, 3, 2, 1, 1, 1, 0, 0, 0, 0]
>>> y = [9, 8, 7, 7, 8, 8, 8, 8, 7, 6, 5, 4, 3, 2, 1, 0]
>>> curve = SmoothCurve(x=x, y=y)
>>> curve.__dict__.keys()
dict_keys(['x', 'y', 'k', 'n', 'smoothing'])
```

--------------------------------

### tools.cutLine(line, distance)

Source: https://pybimstab.readthedocs.io/en/latest/tools.html

Cuts a line in two parts at a distance measured from its starting point.

```APIDOC
## tools.cutLine(line, distance)

### Description
Cuts a line in two parts at a distance measured from its starting point.

### Parameters
- **line** (LineString) - Required - Any line or polyline from the shapely module.
- **distance** (int or float) - Required - The absolute distance measured from the starting point of the line.

### Returns
- **tuple** - Two lines that merged at the common point conform the original input line.
```

--------------------------------

### Initialize WaterTable

Source: https://pybimstab.readthedocs.io/en/latest/watertable.html

Constructor signature for creating a WaterTable instance.

```python
WaterTable(slopeCoords, watertabDepths, smoothFactor=0)
```

--------------------------------

### CircularSurface Validation Errors

Source: https://pybimstab.readthedocs.io/en/latest/slipsurface.html

Examples of ValueError exceptions raised when defining a CircularSurface with invalid geometric parameters.

```python
>>> from numpy import array
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.slipsurface import CircularSurface
>>> slope = AnthropicSlope(slopeHeight=7.5, slopeDip=[1, 1.5],
>>>                        crownDist=5, toeDist=5)
>>> surface = CircularSurface(slopeCoords=slope.coords,
>>>                           dist1=2, dist2=10, radius=1)
>>> surface.defineStructre()
ValueError: separation of points > diameter
```

```python
>>> from numpy import array
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.slipsurface import CircularSurface
>>> slope = AnthropicSlope(slopeHeight=7.5, slopeDip=[1, 1.5],
>>>                        crownDist=5, toeDist=5)
>>> surface = CircularSurface(slopeCoords=slope.coords,
>>>                           dist1=2, dist2=10, radius=6)
>>> surface.defineStructre()
ValueError: Radius too short. Increase at least 1.516
```

--------------------------------

### Initialize Astar Class

Source: https://pybimstab.readthedocs.io/en/latest/astar.html

Shows the constructor signature for the Astar class.

```python
Astar(grid, startNode, goalNode, heuristic='manhattan',
      reverseLeft=True, reverseUp=True, preferredPath=None)
```

--------------------------------

### Initialize SlopeStabl and Perform Stability Analysis

Source: https://pybimstab.readthedocs.io/en/latest/_modules/slopestabl.html

Demonstrates the instantiation of the SlopeStabl class using a prepared Slices object and the subsequent inspection of the analysis results.

```python
>>> from numpy import array
>>> from pybimstab.slope import AnthropicSlope
>>> from pybimstab.slipsurface import CircularSurface
>>> from pybimstab.watertable import WaterTable
>>> from pybimstab.slices import MaterialParameters, Slices
>>> from pybimstab.slopestabl import SlopeStabl
>>> slope = AnthropicSlope(slopeHeight=40, slopeDip=[2, 1],
>>>                        crownDist=60, toeDist=30, depth=20)
>>> surface = CircularSurface(slopeCoords=slope.coords,
>>>                           dist1=45.838, dist2=158.726, radius=80)
>>> material = MaterialParameters(
>>>     cohesion=600, frictAngle=20, unitWeight=120, wtUnitWeight=62.4)
>>> watertable = WaterTable(slopeCoords=slope.coords,
                                    watertabDepths=array([[0, 140], [20, 0]]))
>>> slices = Slices(
>>>     material=material, slipSurfCoords=surface.coords,
>>>     slopeCoords=slope.coords, numSlices=50,
>>>     watertabCoords=watertable.coords, bim=None)
>>> stabAnalysis = SlopeStabl(slices, seedFS=1, Kh=0)
>>> stabAnalysis.__dict__.keys()
dict_keys(['slices', 'Kh', 'seedFS', 'maxIter', 'tol', 'interSlcFunc',
           'minLambda', 'maxLambda', 'nLambda', 'fsBishop',
           'fsJanbu', 'fsMoment', 'fsForces', 'lambda_',
           'adjustment', 'FS'])
```

--------------------------------

### cutLine(line, distance)

Source: https://pybimstab.readthedocs.io/en/latest/_modules/tools.html

Cuts a shapely LineString into two parts at a specified distance from its starting point.

```APIDOC
## cutLine(line, distance)

### Description
Cuts a line in two parts at a distance measured from its starting point.

### Parameters
- **line** (LineString) - Required - Any line or polyline from the shapely module
- **distance** (int or float) - Required - The absolute distance measured from the starting point of the line

### Returns
- **tuple** - Two lines that merged at the common point conform the original input line
```

--------------------------------

### Split Line at Distance

Source: https://pybimstab.readthedocs.io/en/latest/_modules/tools.html

Divides a shapely LineString into two segments at a specified distance from the start point.

```python
[docs]def cutLine(line, distance):
    '''Cuts a line in two parts at a distance measured from its starting point.

    Args:
        line (`LineString`): Any line or polyline from the ``shapely`` module.
        distance (`int` or `float`): The absolute distance measured from the
            starting point of the line.

    Returns:
        (`tuple`): Two lines that merged at the common point conform the
            original input line.

    Examples:
        >>> from shapely.geometry import LineString
        >>> from pybimstab.tools import cutLine
        >>> line = LineString([(0, 0), (5, 0)])
        >>> line1, line2 = cutLine(line, 2.5)
        >>> list(line1.coords)
        [(0.0, 0.0), (2.5, 0.0)]
        >>> list(line2.coords)
        [(2.5, 0.0), (5.0, 0.0)]
    '''
    coords = list(line.coords)
    for i, pt in enumerate(coords):
        distAtPt = line.project(Point(pt))
        if distAtPt == distance:
            return LineString(coords[:i+1]), LineString(coords[i:])
        if distAtPt > distance:
            interpPt = line.interpolate(distance)
            line1 = LineString(coords[:i] + [(interpPt.x, interpPt.y)])
            line2 = LineString([(interpPt.x, interpPt.y)] + coords[i:])
            return line1, line2
```