Add display transformed results, update docs

Author: robbievanleeuwen

docs/examples/materials/composite_analysis.ipynb

@@ -345,7 +345,7 @@
    "id": "29",
    "metadata": {},
    "source": [
-    "A plastic analysis for composite sections will calculate plastic moments rather than plastic section moduli. The plastic moment assumes all geometry fibres reach the yield strength."
+    "Further, we can display the transformed results with respect to an elastic modulus by calling the `display_transformed_results()` method. Here we print the transformed section properties with respect to the timber."
    ]
   },
   {
@@ -354,14 +354,32 @@
    "id": "30",
    "metadata": {},
    "outputs": [],
+   "source": [
+    "sec.display_transformed_results(e_ref=timber)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "31",
+   "metadata": {},
+   "source": [
+    "A plastic analysis for composite sections will calculate plastic moments rather than plastic section moduli. The plastic moment assumes all geometry fibres reach the yield strength."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "32",
+   "metadata": {},
+   "outputs": [],
    "source": [
     "mp_xx, _ = sec.get_mp()\n",
     "print(f\"Mp = {mp_xx / 1e6:.1f} kN.m\")"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "31",
+   "id": "33",
    "metadata": {},
    "source": [
     "### Stress Analysis"
@@ -370,7 +388,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "32",
+   "id": "34",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -380,7 +398,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "33",
+   "id": "35",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -390,7 +408,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "34",
+   "id": "36",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -399,7 +417,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "35",
+   "id": "37",
    "metadata": {},
    "source": [
     "We can plot only a specific list of materials by including the `material_list` argument. In the above plot it is difficult to see the stress in the timber so we set `material_list=[timber]`."
@@ -408,7 +426,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "36",
+   "id": "38",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -432,7 +450,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.17"
+   "version": "3.14.0"
   }
  },
  "nbformat": 4,

docs/examples/results/display_results.ipynb

@@ -114,7 +114,7 @@
    "id": "11",
    "metadata": {},
    "source": [
-    "Because we have not specified any material properties, the displayed properties are purely geometric. If we assign a steel material to the CHS, we will see some results change to material property weighted values (see [here](../../user_guide/results.rst#how-material-properties-affect-results) for more information on how material properties affect results)."
+    "Because we have not specified any material properties, the displayed properties are purely geometric. If we assign a steel material to the CHS, we will see some results change to material property weighted values (see [here](../../user_guide/results.rst#how-material-properties-affect-results) for more information on how material properties affect results). We can also print the transformed results using the `display_transformed_results()` method."
    ]
   },
   {
@@ -145,7 +145,8 @@
     "sec.calculate_geometric_properties()\n",
     "sec.calculate_warping_properties()\n",
     "sec.calculate_plastic_properties()\n",
-    "sec.display_results(fmt=\".3e\")"
+    "sec.display_results(fmt=\".3e\")\n",
+    "sec.display_transformed_results(e_ref=steel, fmt=\".3e\")"
    ]
   }
  ],
@@ -165,7 +166,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.17"
+   "version": "3.14.0"
   }
  },
  "nbformat": 4,

docs/examples/results/get_results.ipynb

@@ -270,6 +270,24 @@
    "source": [
     "print(f\"I_rect = {300 * 600**3 / 12:.3e} mm4\")"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "21",
+   "metadata": {},
+   "source": [
+    "Finally, we can print the transformed section properties using the `display_transformed_results()` method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "22",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sec.display_transformed_results(e_ref=concrete, fmt=\".3e\")"
+   ]
   }
  ],
  "metadata": {
@@ -288,7 +306,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.17"
+   "version": "3.14.0"
   }
  },
  "nbformat": 4,

docs/user_guide/results.rst

@@ -7,11 +7,19 @@ Displaying the Results
 A list of cross-section properties that have been calculated by the performed analyses
 can be printed to the terminal using the
 :meth:`~sectionproperties.analysis.section.Section.display_results` method that belongs
-to every  :class:`~sectionproperties.analysis.section.Section` object.
+to every :class:`~sectionproperties.analysis.section.Section` object.
 
 ..  automethod:: sectionproperties.analysis.section.Section.display_results
     :noindex:
 
+If a composite analysis has been performed, the transformed properties can be printed to
+the terminal using the
+:meth:`~sectionproperties.analysis.section.Section.display_transformed_results` method
+that belongs to every :class:`~sectionproperties.analysis.section.Section` object.
+
+..  automethod:: sectionproperties.analysis.section.Section.display_transformed_results
+    :noindex:
+
 Retrieving Section Properties
 -----------------------------
 

src/sectionproperties/analysis/section.py

@@ -1873,6 +1873,36 @@ def display_results(
         """
         post.print_results(section=self, fmt=fmt)
 
+    def display_transformed_results(
+        self,
+        e_ref: float | pre.Material,
+        fmt: str = "8.6e",
+    ) -> None:
+        """Prints the transformed results that have been calculated to the terminal.
+
+        All results that are scaled by the elastic modulus in ``display_results()``
+        (e.g. ``e.ixx_c``) are divided by ``e_ref``.
+
+        This is a composite only method, as such this can only be called if material
+        properties have been applied to the cross-section.
+
+        Args:
+            e_ref: Reference elastic modulus or material property by which to transform
+                the results.
+            fmt: Number formatting string, see
+                https://docs.python.org/3/library/string.html. Defaults to ``"8.6e"``.
+
+        Raises:
+            RuntimeError: If material properties have *not* been applied
+        """
+        if not self.is_composite():
+            msg = "Attempting to call a composite only method for a geometric analysis"
+            msg += " (material properties have not been applied). Consider using"
+            msg += " display_results()."
+            raise RuntimeError(msg)
+
+        post.print_transformed_results(section=self, e_ref=e_ref, fmt=fmt)
+
     def is_composite(self) -> bool:
         """Returns whether or not a composite section is being analysed.