xslope 0.1.7__tar.gz → 0.1.9__tar.gz

{xslope-0.1.7/xslope.egg-info → xslope-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: xslope
-Version: 0.1.7
+Version: 0.1.9
 Summary: Slope stability analysis (limit equilibrium and FEM) in Python.
 Author: Norman L. Jones
 Project-URL: Homepage, https://github.com/njones61/xslope

{xslope-0.1.7 → xslope-0.1.9}/xslope/_version.py

@@ -1,4 +1,4 @@
 __all__ = ["__version__"]
-__version__ = "0.1.7"
+__version__ = "0.1.9"
 
 

{xslope-0.1.7 → xslope-0.1.9}/xslope/plot_seep.py

@@ -217,20 +217,73 @@ def plot_seep_data(seep_data, figsize=(14, 6), show_nodes=False, show_bc=False,
     plt.show()
 
 
-def plot_seep_solution(seep_data, solution, figsize=(14, 6), levels=20, base_mat=1, fill_contours=True, phreatic=True, alpha=0.4, pad_frac=0.05, show_mesh=True):
+def plot_seep_solution(seep_data, solution, figsize=(14, 6), levels=20, base_mat=1, fill_contours=True, phreatic=True, alpha=0.4, pad_frac=0.05, mesh=True, variable="head", vectors=False, vector_scale=0.05, flowlines=True):
     """
-    Plots head contours and optionally overlays flowlines (phi) based on flow function.
-    Fixed version that properly handles mesh aspect ratio and doesn't clip the plot.
-    Supports both triangular and quadrilateral elements.
-
-    Arguments:
-        seep_data: Dictionary containing seepage data from import_seep2d
-        solution: Dictionary containing solution results from run_analysis
-        levels: number of head contour levels
-        base_mat: material ID (1-based) used to compute k for flow function
-        fill_contours: bool, if True shows filled contours, if False only black solid lines
-        phreatic: bool, if True plots phreatic surface (pressure head = 0) as thick red line
-        show_mesh: bool, if True overlays element edges in light gray
+    Plot seepage analysis results including head contours, flowlines, and phreatic surface.
+    
+    This function visualizes the results of a seepage analysis by plotting contours of various
+    nodal variables (head, pore pressure, velocity magnitude, or gradient magnitude). When
+    plotting head, flowlines are also overlaid. The plot properly handles mesh aspect ratios
+    and supports both linear and quadratic triangular and quadrilateral elements.
+    
+    Parameters:
+    -----------
+    seep_data : dict
+        Dictionary containing seepage mesh data from import_seep2d. Required keys include:
+        'nodes', 'elements', 'element_materials', 'element_types' (optional), and
+        'k1_by_mat' (optional, for flowline calculation).
+    solution : dict
+        Dictionary containing solution results from run_seepage_analysis. Required keys include:
+        'head' (array of total head values at nodes), 'velocity' (array of velocity vectors),
+        'gradient' (array of hydraulic gradient vectors). Optional keys: 'phi' (stream function),
+        'flowrate' (total flow rate), 'u' (pore pressure), 'v_mag' (velocity magnitude),
+        'i_mag' (gradient magnitude).
+    figsize : tuple of float, optional
+        Figure size in inches (width, height). Default is (14, 6).
+    levels : int, optional
+        Number of contour levels to plot. Default is 20.
+    base_mat : int, optional
+        Material ID (1-based) used to compute hydraulic conductivity for flow function
+        calculation. Default is 1. Only used when variable="head".
+    fill_contours : bool, optional
+        If True, shows filled contours with color map. If False, only black solid
+        contour lines are shown. Default is True.
+    phreatic : bool, optional
+        If True, plots the phreatic surface (where pressure head = 0) as a thick red line.
+        Default is True. Only plotted if pore pressure is negative somewhere in the domain.
+    alpha : float, optional
+        Transparency level (0-1) for material zone fill colors. Default is 0.4.
+    pad_frac : float, optional
+        Fraction of mesh extent to add as padding around the plot boundaries. Default is 0.05.
+    mesh : bool, optional
+        If True, overlays element edges in light gray. Default is True.
+    variable : str, optional
+        Nodal variable to contour. Options: "head" (default), "u" (pore pressure),
+        "v_mag" (velocity magnitude), "i_mag" (gradient magnitude). When "head" is selected,
+        flowlines can be overlaid if flowlines=True. Other variables do not include flowlines.
+    vectors : bool, optional
+        If True, plots velocity vectors as arrows at each node. Default is False.
+    vector_scale : float, optional
+        Scale factor for vector lengths. Maximum vector length will be x_range * vector_scale,
+        where x_range is the x-extent of the mesh. Default is 0.05.
+    flowlines : bool, optional
+        If True and variable="head", overlays flowlines (stream function contours) on the plot.
+        Default is True. Only applicable when variable="head".
+    
+    Returns:
+    --------
+    None
+        Displays the plot using matplotlib.pyplot.show().
+    
+    Notes:
+    ------
+    - The function automatically subdivides quadratic elements (tri6, quad8, quad9) for
+      proper visualization and contouring.
+    - Flowlines are only plotted when variable="head" and if 'phi' and 'flowrate' are present
+      in solution and 'k1_by_mat' is present in seep_data.
+    - The plot includes a colorbar for contours when fill_contours=True.
+    - The title includes flowrate information if available in the solution dictionary and
+      variable="head".
     """
     import matplotlib.pyplot as plt
     import matplotlib.tri as tri
@@ -238,15 +291,30 @@ def plot_seep_solution(seep_data, solution, figsize=(14, 6), levels=20, base_mat
     from matplotlib.patches import Polygon
     import numpy as np
 
+    # Validate variable parameter
+    valid_variables = ["head", "u", "v_mag", "i_mag"]
+    if variable not in valid_variables:
+        raise ValueError(f"variable must be one of {valid_variables}, got '{variable}'")
+    
     # Extract data from seep_data and solution
     nodes = seep_data["nodes"]
     elements = seep_data["elements"]
     element_materials = seep_data["element_materials"]
     element_types = seep_data.get("element_types", None)  # New field for element types
     k1_by_mat = seep_data.get("k1_by_mat")  # Use .get() in case it's not present
+    
+    # Extract the variable to plot
+    if variable not in solution:
+        raise ValueError(f"Variable '{variable}' not found in solution dictionary. Available keys: {list(solution.keys())}")
+    contour_data = solution[variable]
+    
+    # Extract head and flowline-related data (only needed for head plots)
     head = solution["head"]
     phi = solution.get("phi")
     flowrate = solution.get("flowrate")
+    
+    # Determine if we should plot flowlines (only for head and if flowlines=True)
+    plot_flowlines = (variable == "head" and flowlines)
 
 
     # Use constrained_layout for best layout
@@ -347,9 +415,9 @@ def plot_seep_solution(seep_data, solution, figsize=(14, 6), levels=20, base_mat
                 for sub_quad in sub_quads:
                     ax.fill(*zip(*sub_quad), edgecolor='none', facecolor=color, alpha=alpha)
 
-    vmin = np.min(head)
-    vmax = np.max(head)
-    hdrop = vmax - vmin
+    # Set up contour levels
+    vmin = np.min(contour_data)
+    vmax = np.max(contour_data)
     contour_levels = np.linspace(vmin, vmax, levels)
 
     # For contouring, subdivide tri6 elements into 4 subtriangles
@@ -374,24 +442,41 @@ def plot_seep_solution(seep_data, solution, figsize=(14, 6), levels=20, base_mat
             all_triangles_for_contouring.extend([tri1, tri2])
     triang = tri.Triangulation(nodes[:, 0], nodes[:, 1], all_triangles_for_contouring)
 
+    # Variable labels for colorbar and title
+    variable_labels = {
+        "head": "Total Head",
+        "u": "Pore Pressure",
+        "v_mag": "Velocity Magnitude",
+        "i_mag": "Hydraulic Gradient Magnitude"
+    }
+    variable_label = variable_labels[variable]
+
     # Filled contours (only if fill_contours=True)
     if fill_contours:
-        contourf = ax.tricontourf(triang, head, levels=contour_levels, cmap="Spectral_r", vmin=vmin, vmax=vmax, alpha=0.5)
-        cbar = plt.colorbar(contourf, ax=ax, label="Total Head", shrink=0.8, pad=0.02)
+        contourf = ax.tricontourf(triang, contour_data, levels=contour_levels, cmap="Spectral_r", vmin=vmin, vmax=vmax, alpha=0.5)
+        cbar = plt.colorbar(contourf, ax=ax, label=variable_label, shrink=0.8, pad=0.02)
         cbar.locator = MaxNLocator(nbins=10, steps=[1, 2, 5])
         cbar.update_ticks()
 
-    # Solid lines for head contours
-    ax.tricontour(triang, head, levels=contour_levels, colors="k", linewidths=0.5)
+    # Solid lines for contours
+    ax.tricontour(triang, contour_data, levels=contour_levels, colors="k", linewidths=0.5)
 
     # Phreatic surface (pressure head = 0)
+    # Check if phreatic surface exists (pore pressure must be negative somewhere)
+    has_phreatic = False
     if phreatic:
-        elevation = nodes[:, 1]  # y-coordinate is elevation
-        pressure_head = head - elevation
-        ax.tricontour(triang, pressure_head, levels=[0], colors="red", linewidths=2.0)
-
-    # Overlay flowlines if phi is available
-    if phi is not None and flowrate is not None and k1_by_mat is not None:
+        # Check if pore pressure goes negative (indicating a phreatic surface exists)
+        u = solution.get("u")
+        if u is not None and np.min(u) < 0:
+            elevation = nodes[:, 1]  # y-coordinate is elevation
+            pressure_head = head - elevation
+            ax.tricontour(triang, pressure_head, levels=[0], colors="black", linewidths=2.0)
+            has_phreatic = True
+
+    # Overlay flowlines if variable is head and phi is available
+    if plot_flowlines and phi is not None and flowrate is not None and k1_by_mat is not None:
+        # Compute head drop for flowline calculation
+        hdrop = vmax - vmin
         if base_mat > len(k1_by_mat):
             print(f"Warning: base_mat={base_mat} is larger than number of materials ({len(k1_by_mat)}). Using material 1.")
             base_mat = 1
@@ -406,8 +491,39 @@ def plot_seep_solution(seep_data, solution, figsize=(14, 6), levels=20, base_mat
         phi_contours = np.linspace(np.min(phi), np.max(phi), phi_levels)
         ax.tricontour(triang, phi, levels=phi_contours, colors="blue", linewidths=0.7, linestyles="solid")
 
+    # Plot velocity vectors if requested
+    if vectors:
+        velocity = solution.get("velocity")
+        if velocity is not None:
+            # Calculate x_range for scaling
+            x_min_vec = nodes[:, 0].min()
+            x_max_vec = nodes[:, 0].max()
+            x_range = x_max_vec - x_min_vec
+            max_vector_length = x_range * vector_scale
+            
+            # Get velocity magnitude
+            v_mag = solution.get("v_mag")
+            if v_mag is None:
+                # Calculate v_mag if not available
+                v_mag = np.linalg.norm(velocity, axis=1)
+            
+            # Find maximum velocity magnitude
+            max_v_mag = np.max(v_mag)
+            
+            # Scale vectors: if max_v_mag > 0, scale so max vector has length max_vector_length
+            if max_v_mag > 0:
+                scale_factor = max_vector_length / max_v_mag
+                velocity_scaled = velocity * scale_factor
+            else:
+                velocity_scaled = velocity
+            
+            # Plot vectors using quiver
+            ax.quiver(nodes[:, 0], nodes[:, 1], velocity_scaled[:, 0], velocity_scaled[:, 1],
+                     angles='xy', scale_units='xy', scale=1, width=0.002, headwidth=2.5,
+                     headlength=3, headaxislength=2.5, color='black', alpha=0.7)
+
     # Plot element edges if requested
-    if show_mesh:
+    if mesh:
         # Draw all element edges
         for element, elem_type in zip(elements, element_types if element_types is not None else [3]*len(elements)):
             if elem_type == 3:
@@ -444,13 +560,17 @@ def plot_seep_solution(seep_data, solution, figsize=(14, 6), levels=20, base_mat
     ax.set_xlim(x_min - x_pad, x_max + x_pad)
     ax.set_ylim(y_min - y_pad, y_max + y_pad)
 
-    title = "Flow Net: Head Contours"
-    if phi is not None:
-        title += " and Flowlines"
-    if phreatic:
-        title += " with Phreatic Surface"
-    if flowrate is not None:
-        title += f" — Total Flowrate: {flowrate:.3f}"
+    # Build title based on variable
+    if variable == "head":
+        title = f"Flow Net: {variable_label} Contours"
+        if plot_flowlines and phi is not None:
+            title += " and Flowlines"
+        if has_phreatic:
+            title += " with Phreatic Surface"
+        if flowrate is not None:
+            title += f" — Total Flowrate: {flowrate:.3f}"
+    else:
+        title = f"{variable_label} Contours"
     ax.set_title(title)
 
     # Set equal aspect ratio AFTER setting limits

{xslope-0.1.7 → xslope-0.1.9}/xslope/seep.py

@@ -1515,6 +1515,142 @@ def compute_velocity(nodes, elements, head, k1_vals, k2_vals, angles, kr0=None,
     velocity /= count[:, None]
     return velocity
 
+def compute_gradient(nodes, elements, head, element_types=None):
+    """
+    Compute nodal hydraulic gradient by averaging element-wise head gradients.
+    The hydraulic gradient i = -grad(h), where grad(h) is the gradient of head.
+    Supports both triangular and quadrilateral elements.
+    
+    Parameters:
+        nodes : (n_nodes, 2) array of node coordinates
+        elements : (n_elements, 3 or 4) triangle or quad node indices
+        head : (n_nodes,) nodal head solution
+        element_types : (n_elements,) array indicating 3 for triangles, 4 for quads
+    
+    Returns:
+        gradient : (n_nodes, 2) array of nodal hydraulic gradient vectors [ix, iy]
+    """
+    # If element_types is not provided, assume all triangles (backward compatibility)
+    if element_types is None:
+        element_types = np.full(len(elements), 3)
+
+    n_nodes = nodes.shape[0]
+    gradient = np.zeros((n_nodes, 2))
+    count = np.zeros(n_nodes)
+
+    for idx, element_nodes in enumerate(elements):
+        element_type = element_types[idx]
+        
+        if element_type == 3:
+            # Triangle: use first 3 nodes
+            i, j, k = element_nodes[:3]
+            xi, yi = nodes[i]
+            xj, yj = nodes[j]
+            xk, yk = nodes[k]
+
+            area = 0.5 * np.linalg.det([[1, xi, yi], [1, xj, yj], [1, xk, yk]])
+            if area <= 0:
+                continue
+
+            beta = np.array([yj - yk, yk - yi, yi - yj])
+            gamma = np.array([xk - xj, xi - xk, xj - xi])
+            grad = np.array([beta, gamma]) / (2 * area)
+
+            h_vals = head[[i, j, k]]
+            grad_h = grad @ h_vals
+            # Hydraulic gradient i = -grad(h)
+            i_elem = -grad_h
+
+            for node in element_nodes[:3]:
+                gradient[node] += i_elem
+                count[node] += 1
+        elif element_type == 4:
+            # Quadrilateral: use first 4 nodes
+            i, j, k, l = element_nodes[:4]
+            nodes_elem = nodes[[i, j, k, l], :]
+            h_elem = head[[i, j, k, l]]
+            
+            # 2x2 Gauss points and weights
+            gauss_pts = [(-1/np.sqrt(3), -1/np.sqrt(3)),
+                         (1/np.sqrt(3), -1/np.sqrt(3)),
+                         (1/np.sqrt(3), 1/np.sqrt(3)),
+                         (-1/np.sqrt(3), 1/np.sqrt(3))]
+            
+            for (xi, eta) in gauss_pts:
+                # Shape function derivatives w.r.t. natural coords
+                dN_dxi = np.array([-(1-eta), (1-eta), (1+eta), -(1+eta)]) * 0.25
+                dN_deta = np.array([-(1-xi), -(1+xi), (1+xi), (1-xi)]) * 0.25
+                # Jacobian
+                J = np.zeros((2,2))
+                for a in range(4):
+                    J[0,0] += dN_dxi[a] * nodes_elem[a,0]
+                    J[0,1] += dN_dxi[a] * nodes_elem[a,1]
+                    J[1,0] += dN_deta[a] * nodes_elem[a,0]
+                    J[1,1] += dN_deta[a] * nodes_elem[a,1]
+                detJ = np.linalg.det(J)
+                if detJ <= 0:
+                    continue
+                Jinv = np.linalg.inv(J)
+                # Shape function derivatives w.r.t. x,y
+                dN_dx = Jinv[0,0]*dN_dxi + Jinv[0,1]*dN_deta
+                dN_dy = Jinv[1,0]*dN_dxi + Jinv[1,1]*dN_deta
+                gradN = np.vstack((dN_dx, dN_dy))  # shape (2,4)
+                # Compute grad(h) at this Gauss point
+                grad_h = gradN @ h_elem
+                # Hydraulic gradient i = -grad(h)
+                i_gp = -grad_h
+                # Distribute/average to nodes
+                for node in element_nodes[:4]:
+                    gradient[node] += i_gp
+                    count[node] += 1
+        elif element_type == 6:
+            # 6-node triangle (quadratic): compute gradient using 3-point Gauss quadrature
+            nodes_elem = nodes[element_nodes[:6], :]
+            h_elem = head[element_nodes[:6]]
+            
+            # 3-point Gauss quadrature for triangles
+            gauss_pts = [(1/6, 1/6, 2/3), (1/6, 2/3, 1/6), (2/3, 1/6, 1/6)]
+            weights = [1/3, 1/3, 1/3]
+            
+            for (L1, L2, L3), w in zip(gauss_pts, weights):
+                # Shape function derivatives w.r.t. area coordinates
+                dN_dL1 = np.array([4*L1-1, 0, 0, 4*L2, 0, 4*L3])
+                dN_dL2 = np.array([0, 4*L2-1, 0, 4*L1, 4*L3, 0])
+                dN_dL3 = np.array([0, 0, 4*L3-1, 0, 4*L2, 4*L1])
+                
+                # Jacobian transformation
+                x0, y0 = nodes_elem[0]
+                x1, y1 = nodes_elem[1]
+                x2, y2 = nodes_elem[2]
+                
+                J = np.array([[x0 - x2, x1 - x2],
+                              [y0 - y2, y1 - y2]])
+                
+                detJ = np.linalg.det(J)
+                if abs(detJ) < 1e-10:
+                    continue
+                
+                Jinv = np.linalg.inv(J)
+                
+                # Transform derivatives to global coordinates
+                dN_dx = Jinv[0,0] * (dN_dL1 - dN_dL3) + Jinv[0,1] * (dN_dL2 - dN_dL3)
+                dN_dy = Jinv[1,0] * (dN_dL1 - dN_dL3) + Jinv[1,1] * (dN_dL2 - dN_dL3)
+                gradN = np.vstack((dN_dx, dN_dy))  # shape (2,6)
+                
+                # Compute grad(h) at this Gauss point
+                grad_h = gradN @ h_elem
+                # Hydraulic gradient i = -grad(h)
+                i_gp = -grad_h
+                
+                # Distribute gradient to all 6 nodes of tri6 element
+                for node in element_nodes[:6]:
+                    gradient[node] += i_gp * w  # Weight by Gauss weight
+                    count[node] += w
+
+    count[count == 0] = 1  # Avoid division by zero
+    gradient /= count[:, None]
+    return gradient
+
 def tri3_stiffness_matrix(nodes_elem, Kmat):
     """
     Compute the 3x3 local stiffness matrix for a 3-node triangular element.
@@ -1855,7 +1991,16 @@ def run_seepage_analysis(seep_data):
         seep_data: Dictionary containing all the seepage data 
     
     Returns:
-        Dictionary containing solution results
+        Dictionary containing solution results with the following keys:
+        - 'head': numpy array of hydraulic head values at each node
+        - 'u': numpy array of pore pressure values at each node
+        - 'velocity': numpy array of shape (n_nodes, 2) containing velocity vectors [vx, vy] at each node
+        - 'gradient': numpy array of shape (n_nodes, 2) containing hydraulic gradient vectors [ix, iy] at each node
+        - 'v_mag': numpy array of velocity magnitude at each node
+        - 'i_mag': numpy array of hydraulic gradient magnitude at each node
+        - 'q': numpy array of nodal flow vector
+        - 'phi': numpy array of stream function/flow potential values at each node
+        - 'flowrate': scalar total flow rate
     """
     # Extract data from seep_data
     nodes = seep_data["nodes"]
@@ -1920,6 +2065,13 @@ def run_seepage_analysis(seep_data):
         # Compute velocity, don't pass kr0 and h0
         velocity = compute_velocity(nodes, elements, head, k1, k2, angle, element_types=element_types)
 
+    # Compute hydraulic gradient i = -grad(h)
+    gradient = compute_gradient(nodes, elements, head, element_types)
+
+    # Compute velocity and gradient magnitudes
+    v_mag = np.linalg.norm(velocity, axis=1)
+    i_mag = np.linalg.norm(gradient, axis=1)
+
     gamma_w = unit_weight
     u = gamma_w * (head - nodes[:, 1])
 
@@ -1927,6 +2079,9 @@ def run_seepage_analysis(seep_data):
         "head": head,
         "u": u,
         "velocity": velocity,
+        "gradient": gradient,
+        "v_mag": v_mag,
+        "i_mag": i_mag,
         "q": q,
         "phi": phi,
         "flowrate": total_flow
@@ -1937,10 +2092,21 @@ def run_seepage_analysis(seep_data):
 def export_seep_solution(seep_data, solution, filename):
     """Exports nodal results to a CSV file.
     
+    The exported CSV file contains the following columns:
+    - node_id: Node identifier (1-based)
+    - head: Hydraulic head at each node
+    - u: Pore pressure at each node
+    - v_x, v_y: Velocity vector components
+    - v_mag: Velocity magnitude
+    - i_x, i_y: Hydraulic gradient vector components
+    - i_mag: Hydraulic gradient magnitude
+    - q: Nodal flow vector
+    - phi: Stream function/flow potential
+    
     Args:
         filename: Path to the output CSV file
         seep_data: Dictionary containing seepage data 
-        solution: Dictionary containing solution results from run_analysis
+        solution: Dictionary containing solution results from run_seepage_analysis
     """
     import pandas as pd
     n_nodes = len(seep_data["nodes"])
@@ -1950,7 +2116,10 @@ def export_seep_solution(seep_data, solution, filename):
         "u": solution["u"],
         "v_x": solution["velocity"][:, 0],
         "v_y": solution["velocity"][:, 1],
-        "v_mag": np.linalg.norm(solution["velocity"], axis=1),
+        "v_mag": solution["v_mag"],
+        "i_x": solution["gradient"][:, 0],
+        "i_y": solution["gradient"][:, 1],
+        "i_mag": solution["i_mag"],
         "q": solution["q"],
         "phi": solution["phi"]
     })

{xslope-0.1.7 → xslope-0.1.9/xslope.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: xslope
-Version: 0.1.7
+Version: 0.1.9
 Summary: Slope stability analysis (limit equilibrium and FEM) in Python.
 Author: Norman L. Jones
 Project-URL: Homepage, https://github.com/njones61/xslope