Add coincident load effects to Envelopes (#128)

* Add coincident load effects to Envelopes (#122)

Track the co-existing value of the other effect (V or M) at the truck
position that caused each envelope extreme. New attributes: Vco_Mmax,
Vco_Mmin, Mco_Vmax, Mco_Vmin. Also adds coincident values to
critical_values() output and updates zero_like()/augment().

Closes #122

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add documentation for coincident load effects

Update Envelopes class docstring with all attributes including new
coincident arrays. Update critical_values() and augment() docstrings.
Add coincident effects demonstration to bridge analysis notebook.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add CHANGELOG entry for coincident load effects (#122)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: ccaprani

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 ### Features
+- Add coincident load effects to `Envelopes` (#122). New attributes `Vco_Mmax`, `Vco_Mmin`, `Mco_Vmax`, `Mco_Vmin` track the co-existing value of the other effect (V or M) at the truck position that caused each envelope extreme. `critical_values()` output now includes `"Vco"` and `"Mco"` keys. Coincident values are preserved through `augment()` and `zero_like()`.
 - Add trapezoidal (linearly varying) distributed load type (#101). Load type 5 supports both full-span `[span, 5, w1, w2]` and partial coverage `[span, 5, w1, w2, a, c]` where w1/w2 are intensities at positions a and a+c respectively. Also adds `BeamAnalysis.add_trap()` convenience method with optional `a` and `c` parameters.
 - Add `pos_start` and `pos_end` parameters to `BridgeAnalysis.run_vehicle()` to restrict the vehicle traverse range (#53). Useful for transverse deck analyses where the vehicle is confined to specific lanes.
 - Add `Envelopes.sum()` method for element-wise addition of compatible envelopes (#92). This enables superimposing load effects from different sources, e.g. a patterned UDL envelope with a moving vehicle envelope.

docs/source/notebooks/bridge.ipynb

@@ -303,6 +303,34 @@
     "bridge_analysis.static_vehicle(pos, True);"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "92ycitwmq6m",
+   "source": "### Coincident Load Effects\n\nIn bridge design it is important to know not just the extreme value of one load effect, but also the value of the *other* effect at the same vehicle position. For example, when checking combined stresses at a section, we need the shear force that co-exists with the maximum bending moment. The `Envelopes` object provides these as the `Vco_Mmax`, `Vco_Mmin`, `Mco_Vmax`, and `Mco_Vmin` attributes.\n\nThe `critical_values` dictionary also includes coincident values via the `\"Vco\"` key (for moment entries) and `\"Mco\"` key (for shear entries):",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "592cinf69eo",
+   "source": "Vco = cvals[\"Mmax\"][\"Vco\"]\nprint(f\"At {at:.2f} m, Mmax = {val:.1f} kNm with coincident V = {Vco:.1f} kN\")",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d5ang668mz",
+   "source": "The full coincident arrays are available on the envelope for plotting or further analysis. For example, to plot the coincident shear alongside the moment envelope:",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "hfm883qskp",
+   "source": "fig, (ax1, ax2) = plt.subplots(2, 1, sharex=True, figsize=(9, 6))\n\nax1.plot(env.x, env.Mmax, \"r\", label=\"Mmax\")\nax1.plot(env.x, env.Mmin, \"b\", label=\"Mmin\")\nax1.plot(env.x, env.Mco_Vmax, \"r--\", alpha=0.5, label=\"M co. Vmax\")\nax1.plot(env.x, env.Mco_Vmin, \"b--\", alpha=0.5, label=\"M co. Vmin\")\nax1.invert_yaxis()\nax1.grid()\nax1.legend()\nax1.set_ylabel(\"Bending Moment (kNm)\")\n\nax2.plot(env.x, env.Vmax, \"r\", label=\"Vmax\")\nax2.plot(env.x, env.Vmin, \"b\", label=\"Vmin\")\nax2.plot(env.x, env.Vco_Mmax, \"r--\", alpha=0.5, label=\"V co. Mmax\")\nax2.plot(env.x, env.Vco_Mmin, \"b--\", alpha=0.5, label=\"V co. Mmin\")\nax2.grid()\nax2.legend()\nax2.set_ylabel(\"Shear Force (kN)\")\nax2.set_xlabel(\"Distance along beam (m)\");",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
   {
    "cell_type": "markdown",
    "id": "71f1bd0f-1a7e-442f-9bcd-d6aa5044e07b",
@@ -1429,4 +1457,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

src/pycba/bridge.py

@@ -286,7 +286,11 @@ def critical_values(
     ) -> Dict[str, Dict[str, Union[float, np.ndarray]]]:
         """
         From the envelopes output, returns the extreme values, their locations,
-        and the position of the vehicle for each in a dictionary of dictionaries
+        and the position of the vehicle for each in a dictionary of dictionaries.
+
+        Each moment entry (``Mmax``, ``Mmin``) also contains a ``"Vco"`` key with
+        the coincident shear at the critical location. Each shear entry (``Vmax``,
+        ``Vmin``) contains a ``"Mco"`` key with the coincident moment.
 
         Parameters
         ----------
@@ -304,7 +308,8 @@ def critical_values(
         -------
         crit_values : Dict[str, Dict[str, Union[float, np.ndarray]]]
             A dictionary of dictionaries containing the critical values (i.e. extremes)
-            of each of the load effects, both maximum and minimum.
+            of each of the load effects, both maximum and minimum, along with
+            coincident values of the other effect.
         """
 
         crit_values = {}
@@ -346,21 +351,25 @@ def critical_values(
             "val": Mmax,
             "at": env.x[env.Mmax.argmax()],
             "pos": [self.pos[i] for i in indx["Mmax"]],
+            "Vco": env.Vco_Mmax[env.Mmax.argmax()],
         }
         crit_values["Mmin"] = {
             "val": Mmin,
             "at": env.x[env.Mmin.argmin()],
             "pos": [self.pos[i] for i in indx["Mmin"]],
+            "Vco": env.Vco_Mmin[env.Mmin.argmin()],
         }
         crit_values["Vmax"] = {
             "val": Vmax,
             "at": env.x[env.Vmax.argmax()],
             "pos": [self.pos[i] for i in indx["Vmax"]],
+            "Mco": env.Mco_Vmax[env.Vmax.argmax()],
         }
         crit_values["Vmin"] = {
             "val": Vmin,
             "at": env.x[env.Vmin.argmin()],
             "pos": [self.pos[i] for i in indx["Vmin"]],
+            "Mco": env.Mco_Vmin[env.Vmin.argmin()],
         }
         crit_values["nsup"] = env.nsup
         for i in range(env.nsup):

src/pycba/results.py

@@ -188,13 +188,35 @@ def _member_values(
 
 class Envelopes:
     """
-    Envelopes load effects from a vector of BeamResults
+    Envelopes load effects from a vector of BeamResults.
+
+    Attributes
+    ----------
+    x : np.ndarray
+        Coordinates along the beam.
+    Vmax, Vmin : np.ndarray
+        Maximum and minimum shear force envelopes.
+    Mmax, Mmin : np.ndarray
+        Maximum and minimum bending moment envelopes.
+    Vco_Mmax : np.ndarray
+        Shear coincident with the moment maximum at each point.
+    Vco_Mmin : np.ndarray
+        Shear coincident with the moment minimum at each point.
+    Mco_Vmax : np.ndarray
+        Moment coincident with the shear maximum at each point.
+    Mco_Vmin : np.ndarray
+        Moment coincident with the shear minimum at each point.
+    Rmax, Rmin : np.ndarray
+        Reaction history matrices (nsup x nres).
+    Rmaxval, Rminval : np.ndarray
+        Maximum and minimum reaction per support.
     """
 
     def __init__(self, vResults: List[MemberResults]):
         """
         Constructs the envelope of each load effect given a vector of results for
-        the beam.
+        the beam. Also tracks coincident (co-existing) load effects: the value of
+        the other effect (V or M) at the analysis that caused each envelope extreme.
 
         Parameters
         ----------
@@ -212,57 +234,67 @@ def __init__(self, vResults: List[MemberResults]):
         self.nres = len(vResults)
         self.nsup = len(vResults[0].R)
 
-        self.Vmax, self.Vmin = self._get_envelope_V()
-        self.Mmax, self.Mmin = self._get_envelope_M()
+        (
+            self.Vmax, self.Vmin,
+            self.Mmax, self.Mmin,
+            self.Vco_Mmax, self.Vco_Mmin,
+            self.Mco_Vmax, self.Mco_Vmin,
+        ) = self._get_envelopes_VM()
         self.Rmax, self.Rmin = self._get_envelope_R()
         self.Rmaxval = self.Rmax.max(axis=1)
         self.Rminval = self.Rmin.min(axis=1)
 
-    def _get_envelope_V(self) -> Tuple[np.ndarray, np.ndarray]:
+    def _get_envelopes_VM(self) -> Tuple[
+        np.ndarray, np.ndarray, np.ndarray, np.ndarray,
+        np.ndarray, np.ndarray, np.ndarray, np.ndarray,
+    ]:
         """
-        Creates the envelopes for shear.
-
-        Parameters
-        ----------
-        None
+        Creates the envelopes for shear and moment, and tracks the coincident
+        (co-existing) value of the other effect at the truck position that
+        caused each extreme.
 
         Returns
         -------
-        Vmax : np.ndarray
-            The vector of enveloped maximum values.
-        Vmin : np.ndarray
-            The vector of enveloped minimum values.
+        Vmax, Vmin : np.ndarray
+            Enveloped maximum and minimum shear.
+        Mmax, Mmin : np.ndarray
+            Enveloped maximum and minimum moment.
+        Vco_Mmax, Vco_Mmin : np.ndarray
+            Shear coincident with the moment extreme at each point.
+        Mco_Vmax, Mco_Vmin : np.ndarray
+            Moment coincident with the shear extreme at each point.
         """
         Vmax = np.zeros(self.npts)
         Vmin = np.zeros(self.npts)
+        Mmax = np.zeros(self.npts)
+        Mmin = np.zeros(self.npts)
+
+        Vco_Mmax = np.zeros(self.npts)
+        Vco_Mmin = np.zeros(self.npts)
+        Mco_Vmax = np.zeros(self.npts)
+        Mco_Vmin = np.zeros(self.npts)
 
         for res in self.vResults:
-            Vmax = np.maximum(Vmax, res.results.V)
-            Vmin = np.minimum(Vmin, res.results.V)
-        return (Vmax, Vmin)
+            V = res.results.V
+            M = res.results.M
 
-    def _get_envelope_M(self) -> Tuple[np.ndarray, np.ndarray]:
-        """
-        Creates the envelopes for moment.
+            mask = M > Mmax
+            Vco_Mmax = np.where(mask, V, Vco_Mmax)
+            Mmax = np.where(mask, M, Mmax)
 
-        Parameters
-        ----------
-        None
+            mask = M < Mmin
+            Vco_Mmin = np.where(mask, V, Vco_Mmin)
+            Mmin = np.where(mask, M, Mmin)
 
-        Returns
-        -------
-        Mmax : np.ndarray
-            The vector of enveloped maximum values.
-        Mmin : np.ndarray
-            The vector of enveloped minimum values.
-        """
-        Mmax = np.zeros(self.npts)
-        Mmin = np.zeros(self.npts)
+            mask = V > Vmax
+            Mco_Vmax = np.where(mask, M, Mco_Vmax)
+            Vmax = np.where(mask, V, Vmax)
 
-        for res in self.vResults:
-            Mmax = np.maximum(Mmax, res.results.M)
-            Mmin = np.minimum(Mmin, res.results.M)
-        return (Mmax, Mmin)
+            mask = V < Vmin
+            Mco_Vmin = np.where(mask, M, Mco_Vmin)
+            Vmin = np.where(mask, V, Vmin)
+
+        return (Vmax, Vmin, Mmax, Mmin, Vco_Mmax, Vco_Mmin, Mco_Vmax, Mco_Vmin)
 
     def _get_envelope_R(self) -> Tuple[np.ndarray, np.ndarray]:
         """
@@ -318,6 +350,10 @@ def zero_like(cls, env: Envelopes) -> Envelopes:
         zero_env.Vmin = np.zeros(env.npts)
         zero_env.Mmax = np.zeros(env.npts)
         zero_env.Mmin = np.zeros(env.npts)
+        zero_env.Vco_Mmax = np.zeros(env.npts)
+        zero_env.Vco_Mmin = np.zeros(env.npts)
+        zero_env.Mco_Vmax = np.zeros(env.npts)
+        zero_env.Mco_Vmin = np.zeros(env.npts)
         for i in range(env.nsup):
             zero_env.Rmax[i] = np.zeros(env.nres)
             zero_env.Rmin[i] = np.zeros(env.nres)
@@ -328,7 +364,8 @@ def zero_like(cls, env: Envelopes) -> Envelopes:
     def augment(self, env: Envelopes):
         """
         Augments this set of envelopes with another compatible set, making this the
-        envelopes of the two sets of envelopes.
+        envelopes of the two sets of envelopes. Coincident values are updated to
+        match whichever envelope governs at each point.
 
         All envelopes must be from the same :class:`pycba.bridge.BridgeAnalysis` object.
 
@@ -353,12 +390,24 @@ def augment(self, env: Envelopes):
 
         if self.npts != env.npts or self.nsup != env.nsup:
             raise ValueError("Cannot augment with an inconsistent envelope")
+
+        # Track where envelope values will change BEFORE updating them
+        vmax_update = env.Vmax > self.Vmax
+        vmin_update = env.Vmin < self.Vmin
+        mmax_update = env.Mmax > self.Mmax
+        mmin_update = env.Mmin < self.Mmin
+
         self.Vmax = np.maximum(self.Vmax, env.Vmax)
         self.Vmin = np.minimum(self.Vmin, env.Vmin)
-
         self.Mmax = np.maximum(self.Mmax, env.Mmax)
         self.Mmin = np.minimum(self.Mmin, env.Mmin)
 
+        # Update coincident values where the envelope changed
+        self.Vco_Mmax = np.where(mmax_update, env.Vco_Mmax, self.Vco_Mmax)
+        self.Vco_Mmin = np.where(mmin_update, env.Vco_Mmin, self.Vco_Mmin)
+        self.Mco_Vmax = np.where(vmax_update, env.Mco_Vmax, self.Mco_Vmax)
+        self.Mco_Vmin = np.where(vmin_update, env.Mco_Vmin, self.Mco_Vmin)
+
         self.Rmaxval = np.maximum(self.Rmaxval, env.Rmaxval)
         self.Rminval = np.minimum(self.Rminval, env.Rminval)