pySlope Reference

Material

class pyslope.Material(unit_weight: float = 20, friction_angle: int = 35, cohesion: int = 2, depth_to_bottom: float = 5, name: str = '', color: str = '')

Class representing geological material unit.

Parameters

  • unit_weight (float) – material unit weight in kN/m3, by default 20

  • friction_angle (int) – material friction angle in degrees, by default 35

  • cohesion (int) – material cohesion in kPa, by default 2

  • depth_to_bottom (float) – depth to the bottom of the material strata from the top of the slope, by default 5. Note, materials assigned to a slope must have a unique depth_to_bottom or an error will be raised.

  • name (str (optional)) – name of the strata

  • color (str (optional)) – color to be used to represent the strata when plotting. Color may be provided as a string, standard 3 hex digit or 6 hex digit web compatible representation. If not provided color automatically assigned.

Examples

>>> Material(20,35,2,5)
Material:(uw=20,phi=35,c=2,d_bot=5)
>>> Material()
Material:(uw=20,phi=35,c=2,d_bot=5)
>>> a = Material()
>>> a.cohesion == 2
True

Uniform Distributed Load (Udl)

class pyslope.Udl(magnitude: float = 0, offset: float = 0, length: Optional[float] = None, color: str = 'red', dynamic_offset: bool = False)

Class representing uniformly distributed surface pressure in kPa

Parameters

  • magnitude (float) – magnitude of UDL force in kPa

  • offset (float) – offset of load from slope in m

  • length (float) – length of load in m, if 0 or None then assumed continuous. By default None.

  • color (str (optional)) – color to be used to represent the strata when plotting. Color may be provided as a string, standard 3 hex digit or 6 hex digit web compatible representation. If not provided color automatically assigned.

  • dynamic_offset (bool) – If True then the load offset will be dynamically moved if a “dynamic analysis” is run. (For a standard analysis the offset value is still used). By default False.

Examples

>>> Udl(magnitude = 10, offset = 1, length = 2, color = "pink")
UDL: 10 kPa, offset = 1 m, load length = 2 m
>>> Udl()
UDL: 0 kPa, offset = 0 m, load length continuous
>>> a = Udl()
>>> a.magnitude == 0
True

Line Load

class pyslope.LineLoad(magnitude: float = 0, offset: float = 0, color: str = 'blue', dynamic_offset: bool = False)

Class representing line load in kN/m

Parameters

  • magnitude (float) – magnitude of UDL force in kPa

  • offset (float) – offset of load from slope in m

  • length (float) – length of load in m, if 0 or None then assumed continuous. By default None.

  • color (str (optional)) – color to be used to represent the strata when plotting. Color may be provided as a string, standard 3 hex digit or 6 hex digit web compatible representation. If not provided color automatically assigned.

  • dynamic_offset (bool) – If True then the load offset will be dynamically moved if a “dynamic analysis” is run. (For a standard analysis the offset value is still used). By default False.

Examples

>>> LineLoad(magnitude = 10, offset = 1, color = "pink")
LineLoad: 10 kN/m, offset = 1 m
>>> LineLoad()
LineLoad: 0 kN/m, offset = 0 m
>>> a = LineLoad()
>>> a.magnitude == 0
True

Slope

class pyslope.Slope(height: float = 1, angle: int = 30, length: Optional[float] = None)

Slope object.

Parameters

  • height (float) – height of slope in metres, by default 2

  • angle (int, optional) – angle of slope (only used if length None), by default 30

  • length (float, optional) – length of slope in metres, by default None

Examples

>>> Slope(height = 1, angle = 50, length = None)
Slope: 1V : 0.839H
>>> Slope(height = 1, angle = 50, length = 2)
Slope: 1V : 2H
>>> Slope(height = 1, angle = None, length = 2)
Slope: 1V : 2H
>>> Slope()
Slope: 1V : 1.732H

Slope: Geometry

pyslope.Slope.set_external_boundary(self, height: float = 1, angle: int = 30, length: Optional[float] = None)

Set external boundary for model.

Parameters

  • height (float, optional) – height of slope in metres, by default 1

  • angle (int, optional) – angle of slope in degrees (may be left as none if slope is instead expressed by length of slope), by default 30

  • length (float, optional) – length of slope in metres (may be left as none if slope is instead expressed by angle of slope), by default None

Raises

ValueError – If input not in required range or of required type

Examples

>>> a = Slope(height = 1, angle = 45, length = None)
>>> a
Slope: 1V : 1.0H
>>> a.set_external_boundary(height = 2, length = 0.5)
>>> a
Slope: 2V : 0.5H
pyslope.Slope.get_top_coordinates(self)

Returns the top coordinate of the slope.

Returns

(x,y) coordinate of the top of the slope.

Return type

tuple

pyslope.Slope.get_bottom_coordinates(self)

Returns the bottom coordinate of the slope.

Returns

(x,y) coordinate of the bottom of the slope.

Return type

tuple

pyslope.Slope.get_external_y_intersection(self, x)

return y coordinate of intersection with boundary for a given x

pyslope.Slope.get_external_x_intersection(self, y)

return x coordinate of intersection with boundary for a given y

Slope: Initialising Parameters

pyslope.Slope.set_water_table(self, depth: float)

set water table value.

Parameters

depth (float) – depth of water from top of slope.

Examples

>>> s = Slope()
>>> s.set_water_table(1.2)
>>> s._water_depth
1.2
pyslope.Slope.remove_water_table(self)

Remove water table from model.

Examples

>>> s = Slope()
>>> s.set_water_table(1.2)
>>> s.remove_water_table()
>>> s._water_RL == s._water_depth == None
True
pyslope.Slope.set_udls(self, *udls)

set a surface surcharge on top of the slope.

Parameters

*udls (Udl objects) – Udl object to be assigned to the slope object.

Examples

>>> s = Slope()
>>> u1 = Udl(5)
>>> u2 = Udl(10)
>>> s.set_udls(u1, u2)
>>> len(s._udls) == 2
True
pyslope.Slope.remove_udls(self, *udls, remove_all=False)

Remove udl from model if associated with model.

Parameters

  • *udls (Udl objects) – Udl object to be removed from the slope object.

  • remove_all (bool, optional) – If true remove all udls, by default False

Examples

>>> s = Slope()
>>> u1, u2 = Udl(5), Udl(10)
>>> s.set_udls(u1, u2)
>>> s.remove_udls(u1)
>>> len(s._udls) == 1
True
>>> s.remove_udls(remove_all=True)
>>> len(s._udls) == 0
True
pyslope.Slope.set_lls(self, *lls)

set a surface surcharge on top of the slope

Parameters

*lls (LineLoad objects) – LineLoad object to be assigned to the slope object.

Examples

>>> s = Slope()
>>> ll1 = LineLoad(5)
>>> ll2 = LineLoad(10)
>>> s.set_lls(ll1, ll2)
>>> len(s._lls) == 2
True
pyslope.Slope.remove_lls(self, *lls, remove_all=False)

Remove udl from model if associated with model.

Parameters

  • *lls (LineLoad objects) – LineLoad object to be removed from the slope object.

  • remove_all (bool, optional) – if true remove all lls, by default False

Examples

>>> s = Slope()
>>> ll1 = LineLoad(5)
>>> ll2 = LineLoad(10)
>>> s.set_lls(ll1, ll2)
>>> s.remove_lls(ll1)
>>> len(s._lls) == 1
True
>>> s.remove_lls(remove_all=True)
>>> len(s._lls) == 0
True
pyslope.Slope.set_materials(self, *materials)

Assign material instances to the slope instance.

Parameters

*materials (Material (list), optional) – Material instances to be associated with slope.

Raises

  • ValueError – If material not instance of Material class error is raised.

  • ValueError – If non-unique material depths then error is raised.

Examples

>>> s = Slope()
>>> m1 = Material()
>>> m2 = Material(unit_weight = 18,cohesion=2, friction_angle = 30,depth_to_bottom = 1.32)
>>> s.set_materials(m1, m2)
>>> len(s._materials) == 2
True
>>> s.remove_material(m1)
>>> len(s._materials) == 1
True
>>> s.remove_material(remove_all=True)
>>> len(s._materials) == 0
True
pyslope.Slope.remove_material(self, material: Optional[Material] = None, depth: Optional[float] = None, remove_all=False)

Remove material from slope.

Parameters

  • material (Material, optional) – material object. If specified and exists in materials associated with slope then will be removed, by default None

  • depth (float, optional) – depth in metres of material object. If not None and material found at indicated depth then will remove the material, by default None

  • remove_all (Boolean, optional) – if true all materials removed, default false

Examples

>>> s = Slope()
>>> m1 = Material()
>>> m2 = Material(unit_weight = 18,cohesion=2,friction_angle = 30,depth_to_bottom = 1.32)
>>> s.set_materials(m1, m2)
>>> len(s._materials) == 2
True
>>> s.remove_material(m1)
>>> len(s._materials) == 1
True
>>> s.remove_material(remove_all=True)
>>> len(s._materials) == 0
True
pyslope.Slope.set_analysis_limits(self, left_x: Optional[float] = None, right_x: Optional[float] = None, left_x_right: Optional[float] = None, right_x_left: Optional[float] = None)

set limits on slope analysis search.

Parameters

  • left_x (float) – left x coordinate of search, defines outer edge of top of search

  • right_x (float) – right x coordinate search, defines outer edge of bottom of search

  • left_x_right (float, optional) – left x coordinate right hand limit of search, defines inner edge of top of search. If none ignored, by default None

  • right_x_left (float, optional) – right x coordinate left hand limit of search, defines inner edge of bottom of search. If none ignored, by default None

pyslope.Slope.remove_analysis_limits(self)

Reset analysis limits to default (no limits).

Slope: Options

pyslope.Slope.update_water_analysis_options(self, auto: bool = True, H: int = 1)

Update analysis options regarding how water is treated.

Parameters

  • auto (bool, optional) – If true calculates pressure head automatically (factor is cos(a)**2 where a is the angle of slope). If False takes manual factor (H). by default True

  • H (int, optional) – factor on water pressure. If 1 water head equals distance between water table and bottom of slice. If 0 no water pressure is considered. By default 1.

Examples

>>> s = Slope()
>>> s.update_water_analysis_options(auto=True)
>>> s.update_water_analysis_options(auto=False, H = 0.72)
pyslope.Slope.update_analysis_options(self, slices: Optional[int] = None, iterations: Optional[int] = None, min_failure_dist: Optional[int] = None, tolerance: Optional[float] = None, max_iterations: Optional[int] = None)

Function to update analysis modelling options.

Parameters

  • slices (int, optional) – Slices to take in calculation for each potential circular failure (between 10 and 500). If None doesnt update the parameter, by default None.

  • iterations (int, optional) – Approximate number of potential slopes to check (between 500 and 100000). If None doesnt update the parameter, by default None.

  • min_failure_dist (int, optional) – If specified only failure slopes with a distance greater than the min failure distance will be assessed, by default None.

  • tolerance (float, optional) – Convergance tolerance on bishops. Calculation will stop when change in factor of safety is less than the tolerance specified. By default None. Inialised as 0.005.

  • max_iterations (int, optional) – Maximum number of iterations for convergence on bishop factor of safety. By default None. Initialised as 15.

Examples

>>> s = Slope()
>>> s.update_analysis_options(slices = 25,iterations = 2500,min_failure_dist = 0.2)
>>> s.update_analysis_options(tolerance = 0.005,max_iterations = 50)
pyslope.Slope.update_boundary_options(self, MIN_EXT_L: Optional[float] = None, MIN_EXT_H: Optional[float] = None)

Function to update external boundary options.

Parameters

  • MIN_EXT_L (float, optional) – Minimum external boundary length. If None doesnt update the parameter, by default None

  • MIN_EXT_H (float, optional) – Minimum external boundary height. If None doesnt update the parameter, by default None.

Examples

>>> s = Slope()
>>> s.update_boundary_options(MIN_EXT_L = 100)
>>> s._external_length == 100
True
>>> s.update_boundary_options(MIN_EXT_H = 200)
>>> s._external_height == 200
True

Slope: Failure Planes

pyslope.Slope.add_single_circular_plane(self, c_x, c_y, radius)

Add failure plane to be analysed by specifying circle properties.

Parameters

  • c_x (float,) – centre of circle x coordinate.

  • c_y (float,) – centre of circle y coordinate.

  • radius (float) – radius of circle

pyslope.Slope.remove_individual_planes(self)

Remove individually added failure planes.

pyslope.Slope.add_single_entry_exit_plane(self, l_cx, r_cx, num_circles=5)

Add failure plane to be analysed be specifying start and exit point.

Parameters

  • l_c (float) – Left x coordinate which represents the top of the failure plane.

  • r_c (float) – Right x coordinate which represents the bottom of the failure plane.

  • num_circles (int, optional) – number of different circle radii to assess passing through the entry and exit points, by default 5

Slope: Analysing

pyslope.Slope.analyse_slope(self, max_fos=None)

Analyse many possible failure planes for a slope OR indivually added failure planes if added to slope.

pyslope.Slope.analyse_dynamic(self, critical_fos=1.3)

Analyse slope and offset dynamic loads until critical FOS is achieved

Parameters

critical_fos (float, optional) – minimum required factor of safety, by default 1.3

Slope: Results

pyslope.Slope.get_min_FOS(self)

Get min factor of safety for slope model.

Returns

critical factor of safety

Return type

float

pyslope.Slope.get_min_FOS_circle(self)

Get the properties of the circle that gave the critical factor of safety.

Returns

tuple containing (circle x coordinate, circle y coordinate, circle radius)

Return type

tuple

pyslope.Slope.get_min_FOS_end_points(self)

Get the external boundary intersection for the slope that gave the critical factor of safety.

Returns

tuple containing (left coordinate, right coordinate)

Return type

tuple

pyslope.Slope.get_dynamic_results(self)

Slope: Plotting

pyslope.Slope.plot_boundary(self, material_table=True, legend=False)

Plot external boundary, materials, limits, loading and water for model.

Return type

plotly figure

pyslope.Slope.plot_critical(self, material_table=True, legend=False)

Plot critical slope (i.e. slope with lowest FOS)

Return type

Plotly figure

pyslope.Slope.plot_all_planes(self, max_fos: float = 5, material_table=True, legend=True)

plot multiple failure planes in the same plot

Parameters

max_fos (float, optional) – maximum factor of safety to display for planes, by default 5.

Return type

plotly figure