struct_utils 0.0.1__py3-none-any.whl

struct_utils/structural_utils/bolt_pattern_elastic_method.py

@@ -0,0 +1,755 @@
+"""
+Bolt Pattern Force Distribution
+================================
+Implements the methodology from:
+https://mechanicalc.com/reference/bolt-pattern-force-distribution
+
+Given a bolt pattern (positions + areas) and applied loads at arbitrary
+locations, this module computes the axial and shear force on each bolt.
+
+Coordinate system
+-----------------
+  X, Y  - in-plane axes (the plane of the bolt pattern)
+  Z      - out-of-plane axis (bolt axis direction)
+
+Applied load / moment sign convention follows the right-hand rule.
+
+Usage example at the bottom of this file.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Sequence
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+_bolt_counter = 0
+
+@dataclass
+class Bolt:
+    """A single bolt in the pattern.
+
+    Parameters
+    ----------
+    x, y : float
+        In-plane position of the bolt.
+    area : float
+        Tensile stress area of the bolt (default 1.0 for equal-size bolts).
+    label : str
+        Auto-assigned as B1, B2, ... if not provided.
+    """
+    x: float
+    y: float
+    area: float = 1.0
+    label: str = ""
+
+    def __post_init__(self):
+        global _bolt_counter
+        if not self.label:
+            _bolt_counter += 1
+            self.label = f"B{_bolt_counter}"
+
+
+@dataclass
+class AppliedLoad:
+    """A force/moment applied at a specific point.
+
+    Parameters
+    ----------
+    Fx, Fy, Fz : float
+        Force components (Fz is axial / out-of-plane).
+    Mx, My, Mz : float
+        Moment components about each axis (right-hand rule).
+    x, y, z : float
+        Location at which the load is applied.
+        The moments are transferred to the pattern centroid automatically.
+    """
+    Fx: float = 0.0
+    Fy: float = 0.0
+    Fz: float = 0.0
+    Mx: float = 0.0
+    My: float = 0.0
+    Mz: float = 0.0
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+
+
+@dataclass
+class BoltResult:
+    """Forces resolved onto a single bolt."""
+    bolt: Bolt
+    # Axial (Z-direction) components
+    Fz_direct: float = 0.0      # due to direct Fz at centroid
+    Fz_Mcx: float = 0.0         # due to centroidal moment about X
+    Fz_Mcy: float = 0.0         # due to centroidal moment about Y
+    # Shear components
+    Fxy_direct_x: float = 0.0   # direct Fx distributed by area
+    Fxy_direct_y: float = 0.0   # direct Fy distributed by area
+    Fxy_Mcz_x: float = 0.0      # torsional moment – X component
+    Fxy_Mcz_y: float = 0.0      # torsional moment – Y component
+
+    @property
+    def Fz_total(self) -> float:
+        """Total axial force on this bolt."""
+        return self.Fz_direct + self.Fz_Mcx + self.Fz_Mcy
+
+    @property
+    def Fx_total(self) -> float:
+        return self.Fxy_direct_x + self.Fxy_Mcz_x
+
+    @property
+    def Fy_total(self) -> float:
+        return self.Fxy_direct_y + self.Fxy_Mcz_y
+
+    @property
+    def F_shear(self) -> float:
+        """Resultant shear magnitude."""
+        return math.hypot(self.Fx_total, self.Fy_total)
+
+    @property
+    def F_total(self) -> float:
+        """Total resultant force magnitude."""
+        return math.sqrt(self.Fx_total**2 + self.Fy_total**2 + self.Fz_total**2)
+
+
+# ---------------------------------------------------------------------------
+# Core computation
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BoltPatternAnalysis:
+    """Analyse force distribution over a bolt pattern.
+
+    Parameters
+    ----------
+    bolts : list[Bolt]
+        The bolt pattern.
+    loads : list[AppliedLoad]
+        All applied loads (can be at arbitrary locations).
+    """
+    bolts: list[Bolt]
+    loads: list[AppliedLoad] = field(default_factory=list)
+
+    # ---- Pattern properties (computed lazily) ----
+
+    @property
+    def total_area(self) -> float:
+        """Sum of bolt areas."""
+        return sum(b.area for b in self.bolts)
+
+    @property
+    def centroid(self) -> tuple[float, float]:
+        """(xc, yc) – area-weighted centroid of the bolt pattern."""
+        A = self.total_area
+        xc = sum(b.area * b.x for b in self.bolts) / A
+        yc = sum(b.area * b.y for b in self.bolts) / A
+        return xc, yc
+
+    @property
+    def Ic_x(self) -> float:
+        """Second moment of area about the centroidal X-axis (bending about X)."""
+        xc, yc = self.centroid
+        return sum(b.area * (b.y - yc)**2 for b in self.bolts)
+
+    @property
+    def Ic_y(self) -> float:
+        """Second moment of area about the centroidal Y-axis (bending about Y)."""
+        xc, yc = self.centroid
+        return sum(b.area * (b.x - xc)**2 for b in self.bolts)
+
+    @property
+    def Ic_p(self) -> float:
+        """Polar moment of area about the centroid (torsion about Z)."""
+        xc, yc = self.centroid
+        return sum(b.area * ((b.x - xc)**2 + (b.y - yc)**2) for b in self.bolts)
+
+    # ---- Translate all loads to the centroid ----
+
+    def centroidal_loads(self) -> tuple[float, float, float, float, float, float]:
+        """Return (Fc_x, Fc_y, Fc_z, Mc_x, Mc_y, Mc_z) at the pattern centroid.
+
+        Each applied load is moved to the centroid using the cross-product
+        transfer rule:  M_new = M_applied + R x F
+        where R is the vector from the centroid to the load application point.
+        """
+        xc, yc = self.centroid
+
+        Fc_x = Fc_y = Fc_z = 0.0
+        Mc_x = Mc_y = Mc_z = 0.0
+
+        for load in self.loads:
+            # Direct force sums
+            Fc_x += load.Fx
+            Fc_y += load.Fy
+            Fc_z += load.Fz
+
+            # Moment transfer: R = (load.x - xc, load.y - yc, load.z - 0)
+            rx = load.x - xc
+            ry = load.y - yc
+            rz = load.z  # centroid is at z=0 by convention
+
+            # Cross product  R × F  (right-hand rule)
+            cross_x = ry * load.Fz - rz * load.Fy
+            cross_y = rz * load.Fx - rx * load.Fz
+            cross_z = rx * load.Fy - ry * load.Fx
+
+            Mc_x += load.Mx + cross_x
+            Mc_y += load.My + cross_y
+            Mc_z += load.Mz + cross_z
+
+        return Fc_x, Fc_y, Fc_z, Mc_x, Mc_y, Mc_z
+
+    # ---- Distribute to individual bolts ----
+
+    def solve(self) -> list[BoltResult]:
+        """Compute and return the force on each bolt."""
+        xc, yc = self.centroid
+        A = self.total_area
+        Ic_x = self.Ic_x
+        Ic_y = self.Ic_y
+        Ic_p = self.Ic_p
+
+        Fc_x, Fc_y, Fc_z, Mc_x, Mc_y, Mc_z = self.centroidal_loads()
+
+        results = []
+        for b in self.bolts:
+            r = BoltResult(bolt=b)
+
+            # Distance of bolt from centroid
+            dx = b.x - xc   # rc_y component (distance in X from centroid)
+            dy = b.y - yc   # rc_x component (distance in Y from centroid)
+
+            # ------------------------------------------------------------------
+            # Axial forces  (Z direction)
+            # ------------------------------------------------------------------
+            # 1. Direct Fz distributed proportional to bolt area
+            r.Fz_direct = (b.area / A) * Fc_z
+
+            # 2. Moment Mc_x about X-axis → tensile/compressive along Z
+            #    F = (Mc_x * rc_x,i / Ic_x) * A_i
+            #    rc_x,i = dy  (distance from centroid in Y direction)
+            if abs(Ic_x) > 0:
+                r.Fz_Mcx = (Mc_x * dy / Ic_x) * b.area
+            else:
+                r.Fz_Mcx = 0.0
+
+            # 3. Moment Mc_y about Y-axis → tensile/compressive along Z
+            #    rc_y,i = dx  (distance from centroid in X direction)
+            #    Note: sign convention – positive Mc_y acts in -Z for bolts at +X
+            if abs(Ic_y) > 0:
+                r.Fz_Mcy = -(Mc_y * dx / Ic_y) * b.area
+            else:
+                r.Fz_Mcy = 0.0
+
+            # ------------------------------------------------------------------
+            # Shear forces  (X-Y plane)
+            # ------------------------------------------------------------------
+            # 1. Direct shear distributed proportional to bolt area
+            r.Fxy_direct_x = (b.area / A) * Fc_x
+            r.Fxy_direct_y = (b.area / A) * Fc_y
+
+            # 2. Torsional moment Mc_z – shear perpendicular to radius vector
+            #    F_i = (Mc_z * r_i / Ic_p) * A_i  (magnitude)
+            #    Direction: perpendicular to (dx, dy), i.e. (-dy, dx) normalized
+            if abs(Ic_p) > 0:
+                scale = (Mc_z / Ic_p) * b.area
+                r.Fxy_Mcz_x = -scale * dy
+                r.Fxy_Mcz_y =  scale * dx
+            else:
+                r.Fxy_Mcz_x = 0.0
+                r.Fxy_Mcz_y = 0.0
+
+            results.append(r)
+
+        return results
+
+
+# ---------------------------------------------------------------------------
+# Convenience function
+# ---------------------------------------------------------------------------
+
+def bolt_pattern_force_distribution(
+    bolt_positions: Sequence[tuple[float, float]],
+    applied_loads: Sequence[dict],
+    bolt_areas: Sequence[float] | None = None,
+    bolt_labels: Sequence[str] | None = None,
+) -> list[BoltResult]:
+    """High-level helper function.
+
+    Parameters
+    ----------
+    bolt_positions : list of (x, y)
+        In-plane coordinates of each bolt.
+    applied_loads : list of dicts
+        Each dict may contain keys: Fx, Fy, Fz, Mx, My, Mz, x, y, z.
+        Missing keys default to 0.
+    bolt_areas : list of float, optional
+        Tensile stress area of each bolt. Defaults to 1.0 for all bolts
+        (equal-size bolts, which simplifies area-weighted sums).
+    bolt_labels : list of str, optional
+        Human-readable names for the bolts.
+
+    Returns
+    -------
+    list[BoltResult]
+        One entry per bolt with decomposed and total forces.
+    """
+    n = len(bolt_positions)
+    if bolt_areas is None:
+        bolt_areas = [1.0] * n
+    if bolt_labels is None:
+        bolt_labels = [f"Bolt {i+1}" for i in range(n)]
+
+    bolts = [
+        Bolt(x=pos[0], y=pos[1], area=a, label=lbl)
+        for pos, a, lbl in zip(bolt_positions, bolt_areas, bolt_labels)
+    ]
+
+    loads = [
+        AppliedLoad(
+            Fx=ld.get("Fx", 0.0),
+            Fy=ld.get("Fy", 0.0),
+            Fz=ld.get("Fz", 0.0),
+            Mx=ld.get("Mx", 0.0),
+            My=ld.get("My", 0.0),
+            Mz=ld.get("Mz", 0.0),
+            x=ld.get("x", 0.0),
+            y=ld.get("y", 0.0),
+            z=ld.get("z", 0.0),
+        )
+        for ld in applied_loads
+    ]
+
+    analysis = BoltPatternAnalysis(bolts=bolts, loads=loads)
+    return analysis.solve()
+
+# ---------------------------------------------------------------------------
+# Interactive 3-D HTML visualisation (Plotly)
+# ---------------------------------------------------------------------------
+
+
+
+def plot_bolt_pattern_3d(
+    analysis: BoltPatternAnalysis,
+    results: list[BoltResult],
+    title: str = "Bolt Pattern Force Distribution",
+    show: bool = False,
+    save_dir: str | None = None,   # folder to save into; defaults to cwd
+) -> "plotly.graph_objects.Figure":
+    """Render an interactive 3-D visualisation and save as a self-contained HTML file.
+
+    The HTML filename is derived automatically from *title* by lowercasing,
+    replacing spaces and special characters with underscores, and appending
+    ".html".  For example "XM Bracket load case 3" becomes
+    "xm_bracket_load_case_3.html".
+
+    Arrow colour convention
+    -----------------------
+    Blue   – shear resultant (in-plane)
+    Green  – axial tension   (+Z)
+    Red    – axial compression (−Z)
+    Orange – resultant force vector
+    Purple – applied load arrows
+
+    Parameters
+    ----------
+    analysis  : BoltPatternAnalysis
+    results   : list[BoltResult]   from analysis.solve()
+    title     : str                figure title; also used as the filename stem
+    show      : bool               open the figure in the default browser
+    save_dir  : str | None         folder to write the HTML file into;
+                                   defaults to the current working directory
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    import re, os
+    import plotly.graph_objects as go
+
+    slug = re.sub(r"[^\w\s]", "", title)
+    slug = re.sub(r"\s+", "_", slug.strip()).lower() or "bolt_pattern"
+    folder = save_dir if save_dir is not None else "."
+    os.makedirs(folder, exist_ok=True)
+    save_path = os.path.join(folder, slug + ".html")
+
+    xc, yc = analysis.centroid
+    Fc_x, Fc_y, Fc_z, Mc_x, Mc_y, Mc_z = analysis.centroidal_loads()
+
+    # ── Scale arrows to ~40 % of pattern span ────────────────────────────────
+    bolt_xs = [b.bolt.x for b in results]
+    bolt_ys = [b.bolt.y for b in results]
+    span = max(max(bolt_xs) - min(bolt_xs), max(bolt_ys) - min(bolt_ys), 1e-6)
+    max_mag = max((r.F_total for r in results), default=1.0) or 1.0
+    arrow_scale = span * 0.40 / max_mag
+    cyl_h = span * 0.06          # bolt cylinder half-height
+
+    # ── Colour scale for bolt markers (total force magnitude) ─────────────────
+    ft_vals = [r.F_total for r in results]
+
+    traces = []
+
+    # ── Bolt plate (semi-transparent rectangle at Z=0) ────────────────────────
+    pad = span * 0.18
+    px = [min(bolt_xs)-pad, max(bolt_xs)+pad, max(bolt_xs)+pad, min(bolt_xs)-pad, min(bolt_xs)-pad]
+    py = [min(bolt_ys)-pad, min(bolt_ys)-pad, max(bolt_ys)+pad, max(bolt_ys)+pad, min(bolt_ys)-pad]
+    traces.append(go.Scatter3d(
+        x=px, y=py, z=[0]*5,
+        mode="lines",
+        line=dict(color="#58a6ff", width=2),
+        name="Plate outline",
+        showlegend=False,
+    ))
+    # Filled surface via Mesh3d (two triangles)
+    traces.append(go.Mesh3d(
+        x=[min(bolt_xs)-pad, max(bolt_xs)+pad, max(bolt_xs)+pad, min(bolt_xs)-pad],
+        y=[min(bolt_ys)-pad, min(bolt_ys)-pad, max(bolt_ys)+pad, max(bolt_ys)+pad],
+        z=[0, 0, 0, 0],
+        i=[0, 0], j=[1, 2], k=[2, 3],
+        color="#58a6ff", opacity=0.10,
+        name="Plate", showlegend=False, hoverinfo="skip",
+    ))
+
+    # ── Bolt cylinders (markers) ───────────────────────────────────────────────
+    traces.append(go.Scatter3d(
+        x=[r.bolt.x for r in results],
+        y=[r.bolt.y for r in results],
+        z=[cyl_h    for r in results],
+        mode="markers+text",
+        marker=dict(
+            size=10,
+            color=ft_vals,
+            colorscale="Plasma",
+            cmin=0, cmax=max_mag,
+            colorbar=dict(
+                title=dict(text="|F_total|", font=dict(color="#e6edf3")),
+                thickness=14, len=0.55, x=1.01,
+                tickfont=dict(color="#e6edf3"),
+            ),
+            line=dict(color="#30363d", width=1),
+        ),
+        text=[r.bolt.label for r in results],
+        textposition="top center",
+        textfont=dict(color="#e6edf3", size=11),
+        name="Bolts",
+        customdata=[[r.Fz_total, r.Fx_total, r.Fy_total, r.F_shear, r.F_total]
+                    for r in results],
+        hovertemplate=(
+            "<b>%{text}</b><br>"
+            "Fz = %{customdata[0]:.2f}<br>"
+            "Fx = %{customdata[1]:.2f}<br>"
+            "Fy = %{customdata[2]:.2f}<br>"
+            "|F_shear| = %{customdata[3]:.2f}<br>"
+            "|F_total| = %{customdata[4]:.2f}<extra></extra>"
+        ),
+    ))
+
+    # ── Helper: add a cone (arrow) trace ──────────────────────────────────────
+    def _arrow(ox, oy, oz, ux, uy, uz, color, name, legendgroup, showlegend=True):
+        mag = math.sqrt(ux**2 + uy**2 + uz**2)
+        if mag < 1e-9:
+            return
+        # Stem
+        traces.append(go.Scatter3d(
+            x=[ox, ox+ux], y=[oy, oy+uy], z=[oz, oz+uz],
+            mode="lines",
+            line=dict(color=color, width=4),
+            name=name, legendgroup=legendgroup,
+            showlegend=showlegend,
+            hoverinfo="skip",
+        ))
+        # Arrowhead cone
+        traces.append(go.Cone(
+            x=[ox+ux], y=[oy+uy], z=[oz+uz],
+            u=[ux*0.25], v=[uy*0.25], w=[uz*0.25],
+            colorscale=[[0, color], [1, color]],
+            showscale=False,
+            sizemode="absolute", sizeref=span*0.04,
+            name=name, legendgroup=legendgroup,
+            showlegend=False,
+            hoverinfo="skip",
+        ))
+
+    # ── Per-bolt force arrows ─────────────────────────────────────────────────
+    for i, r in enumerate(results):
+        bx, by = r.bolt.x, r.bolt.y
+        oz = cyl_h
+        first = (i == 0)   # only first bolt contributes legend entry per group
+
+        # Shear
+        fs = r.F_shear
+        if fs > 1e-9:
+            _arrow(bx, by, oz,
+                   r.Fx_total * arrow_scale, r.Fy_total * arrow_scale, 0,
+                   "#388bfd", "Shear", "shear", showlegend=first)
+
+        # Axial
+        fz = r.Fz_total
+        if abs(fz) > 1e-9:
+            color = "#3fb950" if fz > 0 else "#f85149"
+            name  = "Axial +Z (tension)" if fz > 0 else "Axial −Z (compression)"
+            group = "axial_pos" if fz > 0 else "axial_neg"
+            _arrow(bx, by, oz, 0, 0, fz * arrow_scale,
+                   color, name, group, showlegend=first)
+
+        # Resultant
+        ft = r.F_total
+        if ft > 1e-9:
+            _arrow(bx, by, oz,
+                   r.Fx_total * arrow_scale,
+                   r.Fy_total * arrow_scale,
+                   r.Fz_total * arrow_scale,
+                   "#ffa657", "Resultant", "resultant", showlegend=first)
+
+    # ── Applied load arrows (from their 3-D application point) ───────────────
+    app_mags = [math.sqrt(l.Fx**2 + l.Fy**2 + l.Fz**2) for l in analysis.loads]
+    app_max  = max(app_mags, default=1.0) or 1.0
+    app_scale = span * 0.35 / app_max
+    for i, (ld, mag) in enumerate(zip(analysis.loads, app_mags)):
+        if mag < 1e-9:
+            continue
+        _arrow(ld.x, ld.y, ld.z,
+               ld.Fx * app_scale, ld.Fy * app_scale, ld.Fz * app_scale,
+               "#bc8cff", "Applied load", "applied", showlegend=(i == 0))
+
+    # ── Applied moment arcs ───────────────────────────────────────────────────
+    # Each moment vector M = (Mx, My, Mz) is drawn as a 270° circular arc in
+    # the plane whose normal is M̂, centred at the load application point.
+    # A cone arrowhead at the arc tip shows the right-hand-rule direction.
+    def _moment_arc(ox, oy, oz, mx, my, mz, color, name, legendgroup, showlegend=True):
+        mag = math.sqrt(mx**2 + my**2 + mz**2)
+        if mag < 1e-9:
+            return
+
+        # Unit moment axis (right-hand rule: curl fingers → rotation direction)
+        ax_hat = (mx / mag, my / mag, mz / mag)
+
+        # Build two orthogonal vectors in the plane perpendicular to ax_hat
+        # Use a helper vector that is not parallel to ax_hat
+        helper = (0.0, 0.0, 1.0) if abs(ax_hat[2]) < 0.9 else (1.0, 0.0, 0.0)
+        # u1 = helper × ax_hat  (in-plane basis vector 1)
+        u1 = (
+            helper[1]*ax_hat[2] - helper[2]*ax_hat[1],
+            helper[2]*ax_hat[0] - helper[0]*ax_hat[2],
+            helper[0]*ax_hat[1] - helper[1]*ax_hat[0],
+        )
+        n1 = math.sqrt(u1[0]**2 + u1[1]**2 + u1[2]**2)
+        u1 = tuple(c / n1 for c in u1)
+        # u2 = ax_hat × u1  (in-plane basis vector 2)
+        u2 = (
+            ax_hat[1]*u1[2] - ax_hat[2]*u1[1],
+            ax_hat[2]*u1[0] - ax_hat[0]*u1[2],
+            ax_hat[0]*u1[1] - ax_hat[1]*u1[0],
+        )
+
+        # Arc radius proportional to pattern span; 270° sweep (leave gap to read direction)
+        r_arc   = span * 0.22
+        n_pts   = 48
+        sweep   = 1.5 * math.pi   # 270°
+        angles  = [sweep * k / (n_pts - 1) for k in range(n_pts)]
+
+        arc_x = [ox + r_arc * (math.cos(a)*u1[0] + math.sin(a)*u2[0]) for a in angles]
+        arc_y = [oy + r_arc * (math.cos(a)*u1[1] + math.sin(a)*u2[1]) for a in angles]
+        arc_z = [oz + r_arc * (math.cos(a)*u1[2] + math.sin(a)*u2[2]) for a in angles]
+
+        traces.append(go.Scatter3d(
+            x=arc_x, y=arc_y, z=arc_z,
+            mode="lines",
+            line=dict(color=color, width=4),
+            name=name, legendgroup=legendgroup,
+            showlegend=showlegend,
+            hovertemplate=f"M=({mx:.2f}, {my:.2f}, {mz:.2f})<extra>{name}</extra>",
+        ))
+
+        # Arrowhead cone tangent to the arc at its tip
+        # Tangent direction = d/da [cos(a)*u1 + sin(a)*u2] at a=sweep
+        #                   = -sin(sweep)*u1 + cos(sweep)*u2
+        tx = -math.sin(sweep)*u1[0] + math.cos(sweep)*u2[0]
+        ty = -math.sin(sweep)*u1[1] + math.cos(sweep)*u2[1]
+        tz = -math.sin(sweep)*u1[2] + math.cos(sweep)*u2[2]
+        cone_size = span * 0.06
+        traces.append(go.Cone(
+            x=[arc_x[-1]], y=[arc_y[-1]], z=[arc_z[-1]],
+            u=[tx * cone_size], v=[ty * cone_size], w=[tz * cone_size],
+            colorscale=[[0, color], [1, color]],
+            showscale=False,
+            sizemode="absolute", sizeref=cone_size,
+            name=name, legendgroup=legendgroup,
+            showlegend=False,
+            hoverinfo="skip",
+        ))
+
+        # Centre dot at application point
+        traces.append(go.Scatter3d(
+            x=[ox], y=[oy], z=[oz],
+            mode="markers",
+            marker=dict(symbol="circle", size=5, color=color),
+            name=name, legendgroup=legendgroup,
+            showlegend=False, hoverinfo="skip",
+        ))
+
+    mom_mags = [math.sqrt(l.Mx**2 + l.My**2 + l.Mz**2) for l in analysis.loads]
+    first_moment = True
+    for ld, mmag in zip(analysis.loads, mom_mags):
+        if mmag < 1e-9:
+            continue
+        _moment_arc(ld.x, ld.y, ld.z,
+                    ld.Mx, ld.My, ld.Mz,
+                    "#ff9f43", "Applied moment", "applied_m",
+                    showlegend=first_moment)
+        first_moment = False
+
+    # ── Centroid marker ───────────────────────────────────────────────────────
+    traces.append(go.Scatter3d(
+        x=[xc], y=[yc], z=[0],
+        mode="markers+text",
+        marker=dict(symbol="cross", size=8, color="#d2a8ff",
+                    line=dict(color="#d2a8ff", width=2)),
+        text=["centroid"], textposition="top center",
+        textfont=dict(color="#d2a8ff", size=9),
+        name="Centroid", showlegend=True,
+        hovertemplate=f"Centroid ({xc:.3f}, {yc:.3f})<extra></extra>",
+    ))
+
+    # ── Layout ────────────────────────────────────────────────────────────────
+    # Build subtitle with centroidal loads
+    subtitle = (f"Centroid ({xc:.3f}, {yc:.3f})  |  "
+                f"Fc=({Fc_x:.1f}, {Fc_y:.1f}, {Fc_z:.1f})  |  "
+                f"Mc=({Mc_x:.1f}, {Mc_y:.1f}, {Mc_z:.1f})")
+
+    fig = go.Figure(data=traces)
+    fig.update_layout(
+        title=dict(
+            text=f"<b>{title}</b><br><sup>{subtitle}</sup>",
+            font=dict(color="#e6edf3", size=14),
+            x=0.5, xanchor="center",
+        ),
+        scene=dict(
+            xaxis=dict(title="X", backgroundcolor="#161b22",
+                       gridcolor="#21262d", showbackground=True,
+                       tickfont=dict(color="#8b949e")),
+            yaxis=dict(title="Y", backgroundcolor="#161b22",
+                       gridcolor="#21262d", showbackground=True,
+                       tickfont=dict(color="#8b949e")),
+            zaxis=dict(title="Z (axial)", backgroundcolor="#161b22",
+                       gridcolor="#21262d", showbackground=True,
+                       tickfont=dict(color="#8b949e")),
+            bgcolor="#0d1117",
+            camera=dict(eye=dict(x=1.4, y=-1.6, z=1.0)),
+            aspectmode="data",
+        ),
+        paper_bgcolor="#0d1117",
+        plot_bgcolor="#0d1117",
+        font=dict(color="#e6edf3"),
+        legend=dict(
+            bgcolor="#161b22", bordercolor="#30363d", borderwidth=1,
+            font=dict(color="#e6edf3", size=11),
+            x=0.01, y=0.99, xanchor="left", yanchor="top",
+        ),
+        margin=dict(l=0, r=0, t=80, b=0),
+    )
+
+    fig.write_html(save_path, include_plotlyjs="cdn", full_html=True)
+    print(f"  [bolt_pattern] HTML saved → {os.path.abspath(save_path)}")
+
+    if show:
+        fig.show()
+
+    return fig
+
+
+# ---------------------------------------------------------------------------
+# Console results printer
+# ---------------------------------------------------------------------------
+
+def print_results(results: list[BoltResult], analysis: BoltPatternAnalysis) -> None:
+    xc, yc = analysis.centroid
+    Fc_x, Fc_y, Fc_z, Mc_x, Mc_y, Mc_z = analysis.centroidal_loads()
+    max_tension  = max(results_1, key=lambda r: r.Fz_total)
+    min_tension  = min(results_1, key=lambda r: r.Fz_total)
+    max_shear    = max(results_1, key=lambda r: r.F_shear)
+    min_shear    = min(results_1, key=lambda r: r.F_shear)
+
+    
+    print("=" * 60)
+    print("BOLT PATTERN PROPERTIES")
+    print(f"  Total area  A    = {analysis.total_area:.4f}")
+    print(f"  Centroid         = ({xc:.4f}, {yc:.4f})")
+    print(f"  Ic_x             = {analysis.Ic_x:.4f}")
+    print(f"  Ic_y             = {analysis.Ic_y:.4f}")
+    print(f"  Ic_p (polar)     = {analysis.Ic_p:.4f}")
+    print()
+    print("CENTROIDAL LOADS")
+    print(f"  Fc_x={Fc_x:.3f}  Fc_y={Fc_y:.3f}  Fc_z={Fc_z:.3f}")
+    print(f"  Mc_x={Mc_x:.3f}  Mc_y={Mc_y:.3f}  Mc_z={Mc_z:.3f}")
+    print()
+    print("SUMMARY")
+    print(f"  {'Max fastener tensile load':<28}  {max_tension.bolt.label:>6}  Fz = {max_tension.Fz_total:>+8.2f}")
+    print(f"  {'Min fastener tensile load':<28}  {min_tension.bolt.label:>6}  Fz = {min_tension.Fz_total:>+8.2f}")
+    print(f"  {'Max fastener shear load':<28}  {max_shear.bolt.label:>6}  Fs =  {max_shear.F_shear:>8.2f}")
+    print(f"  {'Min fastener shear load':<28}  {min_shear.bolt.label:>6}  Fs =  {min_shear.F_shear:>8.2f}")
+    print()
+    print("BOLT FORCES")
+    hdr = (f"{'Bolt':<10} {'Fz_total':>10} {'Fx_total':>10} "
+           f"{'Fy_total':>10} {'F_shear':>10} {'F_total':>10}")
+    print(hdr)
+    print("-" * 60)
+    for r in results:
+        label = r.bolt.label or f"({r.bolt.x},{r.bolt.y})"
+        print(f"{label:<10} {r.Fz_total:>10.4f} {r.Fx_total:>10.4f} "
+              f"{r.Fy_total:>10.4f} {r.F_shear:>10.4f} {r.F_total:>10.4f}")
+    print("=" * 60)
+
+
+# ---------------------------------------------------------------------------
+# Demo / self-test
+# ---------------------------------------------------------------------------
+
+
+if __name__ == "__main__":
+    import os
+    HERE = os.path.dirname(os.path.abspath(__file__))
+
+    positions_1 = [(-3.5, 15), (3.5, 15), (-3.5, -15), (3.5, -15)
+                   , (10, -15), (18.82, -12.14), (24.27, -4.635)
+                   , (24.27, 4.635), (18.82, 12.14), (10, 15)
+                   , (-10, 15), (-18.82, 12.14), (-24.27, 4.635)
+                   , (-24.27, -4.635), (-18.82, -12.14), (-10, -15)] #[x,y]
+
+    # ------------------------------------------------------------------
+    # Example 1: 4-bolt rectangular pattern, in-plane eccentric shear
+    # A 1000 N force applied in X at (y=5) – creates torsion about Z
+    # ------------------------------------------------------------------
+    print("\nEXAMPLE 1 – General 3-D loading")
+    title="bolt_pattern_ex1"
+    analysis_1 = BoltPatternAnalysis(
+        bolts=[Bolt(x, y) for (x, y) in positions_1],
+        loads=[AppliedLoad(Fx=1500.0, Fy=500.0, Fz=5000.0, z=15.0),
+               AppliedLoad(Mz=1000.0)],
+    )
+    save_dir=os.path.join(HERE)
+    results_1 = analysis_1.solve()
+    print_results(results_1, analysis_1)
+    plot_bolt_pattern_3d(
+        analysis_1, results_1,
+        title=title,
+        show=False,
+        save_dir=save_dir,
+    )
+ 
+
+
+
+
+
+
+
+
+
+
+