ebbef2p-python 0.0.2.dev1__py3-none-any.whl → 1.0.0__py3-none-any.whl

ebbef2p/__init__.py

@@ -1,2 +1,24 @@
-__all__ = ["structure", "beam", "element"]
-#name = "ebbef2p"
+"""EBBEF2p: Euler-Bernoulli beams on two-parameter elastic foundations."""
+
+from .exceptions import ConvergenceError, EBBEF2pError, ModelError, UnstableModelError
+from .model import Model
+from .results import ElementEndValues, ReactivePressure, Solution
+from .solver import solve
+from .vlasov import VlasovResult, VlasovSoil, solve_vlasov
+
+__all__ = [
+    "ConvergenceError",
+    "EBBEF2pError",
+    "ElementEndValues",
+    "Model",
+    "ModelError",
+    "ReactivePressure",
+    "Solution",
+    "UnstableModelError",
+    "VlasovResult",
+    "VlasovSoil",
+    "solve",
+    "solve_vlasov",
+]
+
+__version__ = "1.0.0"

ebbef2p/elements.py

@@ -0,0 +1,117 @@
+"""Element matrices for an Euler-Bernoulli beam on a two-parameter foundation.
+
+Two-node element, degrees of freedom ``(w_i, theta_i, w_j, theta_j)`` with
+``theta = dw/dx``, cubic Hermite interpolation. All foundation and load
+quantities vary linearly along the element, so every matrix below is the
+exact Galerkin integral for that variation.
+
+The matrix functions accept scalars or arrays of element properties; for
+arrays of shape ``(n,)`` they return a stack of shape ``(n, 4, 4)`` (or
+``(n, 4)`` for load vectors).
+"""
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+
+def _stack(rows: list[list[ArrayLike]]) -> NDArray[np.float64]:
+    """Matrix (or stack of matrices) from a nested list of broadcastable entries."""
+    entries = np.broadcast_arrays(*(np.asarray(v, dtype=float) for row in rows for v in row))
+    m = np.stack(entries, axis=-1)
+    return m.reshape((*m.shape[:-1], len(rows), len(rows[0])))
+
+
+def _rows(*entries: ArrayLike) -> NDArray[np.float64]:
+    """Stack broadcastable entries along a new first axis."""
+    return np.stack(np.broadcast_arrays(*(np.asarray(v, dtype=float) for v in entries)))
+
+
+def shape_functions(xi: ArrayLike, l: ArrayLike) -> NDArray[np.float64]:
+    """Hermite shape functions at the local coordinate ``xi`` in [0, 1].
+
+    ``xi`` and ``l`` broadcast against each other; the result has the four
+    functions along the first axis.
+    """
+    xi, l = np.asarray(xi, dtype=float), np.asarray(l, dtype=float)
+    return _rows(
+        1 - 3*xi**2 + 2*xi**3,
+        l*xi*(1 - xi)**2,
+        3*xi**2 - 2*xi**3,
+        l*(xi**3 - xi**2),
+    )
+
+
+def shape_function_derivatives(xi: ArrayLike, l: ArrayLike, order: int) -> NDArray[np.float64]:
+    """Derivatives of the shape functions with respect to ``x``."""
+    xi, l = np.asarray(xi, dtype=float), np.asarray(l, dtype=float)
+    if order == 1:
+        return _rows(
+            (-6*xi + 6*xi**2)/l,
+            1 - 4*xi + 3*xi**2,
+            (6*xi - 6*xi**2)/l,
+            3*xi**2 - 2*xi,
+        )
+    if order == 2:
+        return _rows(
+            (-6 + 12*xi)/l**2,
+            (-4 + 6*xi)/l,
+            (6 - 12*xi)/l**2,
+            (-2 + 6*xi)/l,
+        )
+    if order == 3:
+        z = np.zeros_like(xi)
+        return _rows(12/l**3 + z, 6/l**2 + z, -12/l**3 + z, 6/l**2 + z)
+    raise ValueError("order must be 1, 2 or 3")
+
+
+def bending_stiffness(EI: ArrayLike, l: ArrayLike) -> NDArray[np.float64]:
+    """Flexural stiffness matrix, int EI N''^T N'' dx."""
+    EI, l = np.asarray(EI, dtype=float), np.asarray(l, dtype=float)
+    c = EI/l**3
+    return _stack([
+        [12*c, 6*l*c, -12*c, 6*l*c],
+        [6*l*c, 4*l**2*c, -6*l*c, 2*l**2*c],
+        [-12*c, -6*l*c, 12*c, -6*l*c],
+        [6*l*c, 2*l**2*c, -6*l*c, 4*l**2*c],
+    ])
+
+
+def winkler_stiffness(k_i: ArrayLike, k_j: ArrayLike, l: ArrayLike) -> NDArray[np.float64]:
+    """First-parameter foundation matrix, int k(x) N^T N dx, k linear."""
+    a, b, l = (np.asarray(v, dtype=float) for v in (k_i, k_j, l))
+    return _stack([
+        [l*(10*a + 3*b)/35, l**2*(15*a + 7*b)/420,
+         9*l*(a + b)/140, -l**2*(7*a + 6*b)/420],
+        [l**2*(15*a + 7*b)/420, l**3*(5*a + 3*b)/840,
+         l**2*(6*a + 7*b)/420, -l**3*(a + b)/280],
+        [9*l*(a + b)/140, l**2*(6*a + 7*b)/420,
+         l*(3*a + 10*b)/35, -l**2*(7*a + 15*b)/420],
+        [-l**2*(7*a + 6*b)/420, -l**3*(a + b)/280,
+         -l**2*(7*a + 15*b)/420, l**3*(3*a + 5*b)/840],
+    ])
+
+
+def shear_stiffness(g_i: ArrayLike, g_j: ArrayLike, l: ArrayLike) -> NDArray[np.float64]:
+    """Second-parameter foundation matrix, int g(x) N'^T N' dx, g linear.
+
+    ``g`` is the shear parameter of the foundation: 2t in Vlasov's notation,
+    G_p in Pasternak's.
+    """
+    a, b, l = (np.asarray(v, dtype=float) for v in (g_i, g_j, l))
+    return _stack([
+        [3*(a + b)/(5*l), b/10, -3*(a + b)/(5*l), a/10],
+        [b/10, l*(3*a + b)/30, -b/10, -l*(a + b)/60],
+        [-3*(a + b)/(5*l), -b/10, 3*(a + b)/(5*l), -a/10],
+        [a/10, -l*(a + b)/60, -a/10, l*(a + 3*b)/30],
+    ])
+
+
+def distributed_load_vector(q_i: ArrayLike, q_j: ArrayLike, l: ArrayLike) -> NDArray[np.float64]:
+    """Consistent nodal loads, int q(x) N dx, q linear."""
+    q_i, q_j, l = (np.asarray(v, dtype=float) for v in (q_i, q_j, l))
+    return _stack([[
+        l*(7*q_i + 3*q_j)/20,
+        l**2*(3*q_i + 2*q_j)/60,
+        l*(3*q_i + 7*q_j)/20,
+        -l**2*(2*q_i + 3*q_j)/60,
+    ]])[..., 0, :]

ebbef2p/exceptions.py

@@ -0,0 +1,23 @@
+"""Exceptions raised by EBBEF2p.
+
+Each one also derives from the built-in exception that describes it, so
+``except ValueError`` and the like keep working.
+"""
+
+import numpy as np
+
+
+class EBBEF2pError(Exception):
+    """Base class for all EBBEF2p errors."""
+
+
+class ModelError(EBBEF2pError, ValueError):
+    """The problem definition is invalid or inconsistent."""
+
+
+class UnstableModelError(EBBEF2pError, np.linalg.LinAlgError):
+    """The beam can move as a rigid body: the system matrix is singular."""
+
+
+class ConvergenceError(EBBEF2pError, RuntimeError):
+    """An iterative procedure (the gamma iteration) did not converge."""

ebbef2p/mesh.py

@@ -0,0 +1,116 @@
+"""Discretisation of a :class:`~ebbef2p.model.Model` into beam elements."""
+
+from dataclasses import dataclass
+from itertools import pairwise
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .exceptions import ModelError
+from .model import Model
+
+
+@dataclass(frozen=True)
+class Mesh:
+    """Nodes and per-element properties.
+
+    Attributes
+    ----------
+    nodes : (n+1,) array
+    EI : (n,) array
+    k, g : (n, 2) arrays
+        Foundation parameters at the start and end of every element.
+    q : (n, 2) array
+        Distributed load at the start and end of every element.
+    """
+    nodes: NDArray[np.float64]
+    EI: NDArray[np.float64]
+    k: NDArray[np.float64]
+    g: NDArray[np.float64]
+    q: NDArray[np.float64]
+
+    @property
+    def n_elements(self) -> int:
+        return len(self.nodes) - 1
+
+    @property
+    def lengths(self) -> NDArray[np.float64]:
+        return np.diff(self.nodes)
+
+    @property
+    def element_dofs(self) -> NDArray[np.intp]:
+        """Global degrees of freedom of every element, shape (n, 4)."""
+        return 2*np.arange(self.n_elements)[:, None] + np.arange(4)[None, :]
+
+    def node_index(self, x: float, tol: float = 1e-9) -> int:
+        """Index of the node at ``x`` (raises if there is none)."""
+        span = self.nodes[-1] - self.nodes[0]
+        i = int(np.argmin(np.abs(self.nodes - x)))
+        if abs(self.nodes[i] - x) > tol*max(1.0, span):
+            raise ModelError(f"no node at x = {x}")
+        return i
+
+    def element_at(self, x: float | NDArray[np.float64]) -> NDArray[np.intp]:
+        """Index of the element containing ``x`` (right-continuous)."""
+        i = np.searchsorted(self.nodes, x, side='right') - 1
+        return np.clip(i, 0, self.n_elements - 1)
+
+
+def end_spring_stiffness(mesh: Mesh) -> tuple[float, float]:
+    """Springs representing the foundation beyond each beam end.
+
+    For a two-parameter foundation extending to infinity, the surface
+    deflection outside the beam decays as w_end*exp(-sqrt(k/g)*s), and that
+    soil reacts on the beam end with a force sqrt(k*g)*w_end. Returns the
+    spring stiffnesses at the start and end of the beam.
+    """
+    return (float(np.sqrt(mesh.k[0, 0]*mesh.g[0, 0])),
+            float(np.sqrt(mesh.k[-1, 1]*mesh.g[-1, 1])))
+
+
+def _interp_segment(x, x0, x1, v0, v1):
+    return v0 + (v1 - v0)*(x - x0)/(x1 - x0)
+
+
+def build_mesh(model: Model, n_elements: int = 100) -> Mesh:
+    """Mesh the model with roughly ``n_elements`` elements.
+
+    Every key point of the model (segment ends, loads, supports) becomes a
+    node; each interval between key points is divided uniformly so that the
+    element size is close to ``beam length / n_elements``.
+    """
+    model.validate()
+    x_start, x_end = model.extent
+    h = (x_end - x_start)/max(int(n_elements), 1)
+
+    pts = model.key_points()
+    nodes = [pts[0]]
+    for a, b in pairwise(pts):
+        n = max(1, int(np.ceil((b - a)/h - 1e-9)))
+        nodes.extend(np.linspace(a, b, n + 1)[1:])
+    nodes = np.array(nodes)
+
+    n = len(nodes) - 1
+    xi, xj = nodes[:-1], nodes[1:]
+    xm = 0.5*(xi + xj)
+
+    EI = np.empty(n)
+    for b in model.beams:
+        inside = (xm > b.x0) & (xm < b.x1)
+        EI[inside] = b.EI
+
+    k = np.zeros((n, 2))
+    g = np.zeros((n, 2))
+    for f in model.foundation:
+        inside = (xm > f.x0) & (xm < f.x1)
+        for col, x in enumerate((xi, xj)):
+            k[inside, col] += _interp_segment(x[inside], f.x0, f.x1, *f.k)
+            g[inside, col] += _interp_segment(x[inside], f.x0, f.x1, *f.g)
+
+    q = np.zeros((n, 2))
+    for d in model.distributed_loads:
+        inside = (xm > d.x0) & (xm < d.x1)
+        for col, x in enumerate((xi, xj)):
+            q[inside, col] += _interp_segment(x[inside], d.x0, d.x1, d.q0, d.q1)
+
+    return Mesh(nodes=nodes, EI=EI, k=k, g=g, q=q)

ebbef2p/model.py

@@ -0,0 +1,189 @@
+"""Problem definition: beam segments, foundation, loads and supports.
+
+Conventions
+-----------
+* ``x`` runs along the beam axis; ``w`` is the transverse displacement,
+  positive downwards (i.e. a settlement is positive).
+* ``theta = dw/dx``.
+* Forces and distributed loads are positive downwards. A concentrated moment
+  is positive when it does positive work on a positive ``theta``.
+* No system of units is built in; use any consistent set.
+"""
+
+from dataclasses import dataclass, field
+from itertools import pairwise
+from typing import Self
+
+from .exceptions import ModelError
+
+Pair = tuple[float, float]
+
+
+@dataclass(frozen=True)
+class BeamSegment:
+    """Beam portion ``[x0, x1]`` with constant bending stiffness."""
+    x0: float
+    x1: float
+    E: float
+    I: float
+
+    @property
+    def EI(self) -> float:
+        return self.E*self.I
+
+
+@dataclass(frozen=True)
+class FoundationSegment:
+    """Two-parameter foundation acting on ``[x0, x1]``.
+
+    ``k`` is the first (Winkler) parameter and ``g`` the second (shear)
+    parameter, both given as ``(value at x0, value at x1)`` and varying
+    linearly in between. ``g`` equals 2t in Vlasov's notation and G_p in
+    Pasternak's. Overlapping segments add up.
+    """
+    x0: float
+    x1: float
+    k: Pair = (0.0, 0.0)
+    g: Pair = (0.0, 0.0)
+
+
+@dataclass(frozen=True)
+class PointLoad:
+    x: float
+    force: float = 0.0
+    moment: float = 0.0
+
+
+@dataclass(frozen=True)
+class DistributedLoad:
+    """Load per unit length on ``[x0, x1]``, varying linearly from q0 to q1."""
+    x0: float
+    x1: float
+    q0: float
+    q1: float
+
+
+@dataclass(frozen=True)
+class Support:
+    """Prescribed displacement and/or rotation at ``x``; ``None`` leaves it free."""
+    x: float
+    w: float | None = 0.0
+    theta: float | None = None
+
+
+def _pair(value: float | Pair) -> Pair:
+    if isinstance(value, (int, float)):
+        return (float(value), float(value))
+    a, b = value
+    return (float(a), float(b))
+
+
+def _optional_float(value: float | None) -> float | None:
+    return None if value is None else float(value)
+
+
+@dataclass
+class Model:
+    """A beam on a two-parameter elastic foundation.
+
+    Parameters
+    ----------
+    soil_beyond_ends : bool
+        If True, the foundation continues indefinitely beyond both beam ends.
+        Its effect is represented by an equivalent spring sqrt(k*g) at each
+        end, with k and g taken at that end (Vallabhan & Das, 1991).
+
+    Examples
+    --------
+    >>> m = Model()
+    >>> m.add_beam(0, 10, E=30e6, I=0.01)
+    >>> m.add_foundation(0, 10, k=5000, g=2000)
+    >>> m.add_point_load(5, force=100)
+    """
+    beams: list[BeamSegment] = field(default_factory=list)
+    foundation: list[FoundationSegment] = field(default_factory=list)
+    point_loads: list[PointLoad] = field(default_factory=list)
+    distributed_loads: list[DistributedLoad] = field(default_factory=list)
+    supports: list[Support] = field(default_factory=list)
+    soil_beyond_ends: bool = False
+
+    # -- building -------------------------------------------------------
+    def add_beam(self, x0: float, x1: float, E: float, I: float) -> Self:
+        """Add a beam segment with constant E and I."""
+        if x1 <= x0:
+            raise ModelError("beam segment must have x1 > x0")
+        if E <= 0 or I <= 0:
+            raise ModelError("E and I must be positive")
+        self.beams.append(BeamSegment(float(x0), float(x1), float(E), float(I)))
+        return self
+
+    def add_foundation(self, x0: float, x1: float, k: float | Pair = 0.0,
+                       g: float | Pair = 0.0) -> Self:
+        """Add a foundation segment; ``k`` and ``g`` are scalars or (start, end) pairs."""
+        if x1 <= x0:
+            raise ModelError("foundation segment must have x1 > x0")
+        k, g = _pair(k), _pair(g)
+        if min(k) < 0 or min(g) < 0:
+            raise ModelError("foundation parameters must be non-negative")
+        self.foundation.append(FoundationSegment(float(x0), float(x1), k, g))
+        return self
+
+    def add_point_load(self, x: float, force: float = 0.0, moment: float = 0.0) -> Self:
+        """Add a concentrated force and/or moment at ``x``."""
+        self.point_loads.append(PointLoad(float(x), float(force), float(moment)))
+        return self
+
+    def add_distributed_load(self, x0: float, x1: float, q0: float,
+                             q1: float | None = None) -> Self:
+        """Add a load varying from ``q0`` at ``x0`` to ``q1`` at ``x1`` (uniform if q1 is None)."""
+        if x1 <= x0:
+            raise ModelError("distributed load must have x1 > x0")
+        q1 = q0 if q1 is None else q1
+        self.distributed_loads.append(DistributedLoad(float(x0), float(x1), float(q0), float(q1)))
+        return self
+
+    def add_support(self, x: float, w: float | None = 0.0,
+                    theta: float | None = None) -> Self:
+        """Prescribe ``w`` and/or ``theta`` at ``x`` (``None`` = free).
+
+        Defaults to a simple support (w = 0, rotation free). Use
+        ``theta=0`` for a clamped end.
+        """
+        if w is None and theta is None:
+            raise ModelError("a support must constrain w, theta or both")
+        self.supports.append(Support(float(x), _optional_float(w), _optional_float(theta)))
+        return self
+
+    # -- queries ----------------------------------------------------------
+    @property
+    def extent(self) -> Pair:
+        """(x_start, x_end) of the beam."""
+        if not self.beams:
+            raise ModelError("the model has no beam")
+        return (min(b.x0 for b in self.beams), max(b.x1 for b in self.beams))
+
+    def key_points(self) -> list[float]:
+        """Coordinates that must coincide with mesh nodes."""
+        pts = set()
+        for b in self.beams:
+            pts.update((b.x0, b.x1))
+        for f in self.foundation:
+            pts.update((f.x0, f.x1))
+        for d in self.distributed_loads:
+            pts.update((d.x0, d.x1))
+        pts.update(p.x for p in self.point_loads)
+        pts.update(s.x for s in self.supports)
+        return sorted(pts)
+
+    def validate(self, tol: float = 1e-9) -> None:
+        """Check that beam segments tile the beam and everything lies on it."""
+        if not self.beams:
+            raise ModelError("the model has no beam")
+        segs = sorted(self.beams, key=lambda b: b.x0)
+        for a, b in pairwise(segs):
+            if abs(a.x1 - b.x0) > tol:
+                raise ModelError(f"beam segments leave a gap or overlap at x = {a.x1}")
+        x0, x1 = self.extent
+        for x in self.key_points():
+            if x < x0 - tol or x > x1 + tol:
+                raise ModelError(f"x = {x} lies outside the beam [{x0}, {x1}]")

ebbef2p/plotting.py

@@ -0,0 +1,36 @@
+"""Quick-look plots of a :class:`~ebbef2p.results.Solution` (needs matplotlib)."""
+
+import numpy as np
+
+from .results import ElementEndValues, Solution
+
+
+def plot_solution(solution: Solution, axes=None):
+    """Deflection, bending moment, shear force and soil pressure, stacked.
+
+    Returns the array of matplotlib axes.
+    """
+    import matplotlib.pyplot as plt
+
+    if axes is None:
+        _, axes = plt.subplots(4, 1, sharex=True, figsize=(7, 9))
+
+    xs = np.linspace(solution.x[0], solution.x[-1], 400)
+    panels = [
+        (xs, solution.deflection(xs), "w", True),
+        (*_pairs(solution.bending_moment()), "M", True),
+        (*_pairs(solution.shear_force()), "V", False),
+        (*_pairs(solution.reactive_pressure()), "p", True),
+    ]
+    for ax, (x, y, label, invert) in zip(axes, panels, strict=True):
+        ax.plot(x, y)
+        ax.axhline(0, color="0.6", lw=0.8)
+        ax.set_ylabel(label)
+        if invert:
+            ax.invert_yaxis()
+    axes[-1].set_xlabel("x")
+    return axes
+
+
+def _pairs(values: ElementEndValues):
+    return values.x, values.values