Add default units, update docs

Author: robbievanleeuwen

docs/examples/as3600.ipynb

@@ -27,7 +27,8 @@
     "    RectangularStressBlock,\n",
     ")\n",
     "from concreteproperties.design_codes import AS3600\n",
-    "from concreteproperties.results import MomentInteractionResults"
+    "from concreteproperties.post import si_kn_m, si_n_mm\n",
+    "from concreteproperties.results import BiaxialBendingResults, MomentInteractionResults"
    ]
   },
   {
@@ -68,8 +69,12 @@
    "source": [
     "print(concrete.name)\n",
     "print(f\"Density = {concrete.density} kg/mm^3\")\n",
-    "concrete.stress_strain_profile.plot_stress_strain(title=\"Service Profile\")\n",
-    "concrete.ultimate_stress_strain_profile.plot_stress_strain(title=\"Ultimate Profile\")\n",
+    "concrete.stress_strain_profile.plot_stress_strain(\n",
+    "    title=\"Service Profile\", eng=True, units=si_n_mm\n",
+    ")\n",
+    "concrete.ultimate_stress_strain_profile.plot_stress_strain(\n",
+    "    title=\"Ultimate Profile\", eng=True, units=si_n_mm\n",
+    ")\n",
     "print(\n",
     "    f\"Concrete Flexural Tensile Strength: {concrete.flexural_tensile_strength:.2f} MPa\"\n",
     ")"
@@ -92,7 +97,7 @@
    "source": [
     "print(steel.name)\n",
     "print(f\"Density = {steel.density} kg/mm^3\")\n",
-    "steel.stress_strain_profile.plot_stress_strain()"
+    "steel.stress_strain_profile.plot_stress_strain(eng=True, units=si_n_mm)"
    ]
   },
   {
@@ -240,7 +245,10 @@
    "outputs": [],
    "source": [
     "MomentInteractionResults.plot_multiple_diagrams(\n",
-    "    [f_mi_res, mi_res], [\"Factored\", \"Unfactored\"], fmt=\"-\"\n",
+    "    [mi_res, f_mi_res],\n",
+    "    [\"Unfactored\", \"Factored\"],\n",
+    "    fmt=\"-\",\n",
+    "    units=si_kn_m,\n",
     ")"
    ]
   },
@@ -294,7 +302,11 @@
     "n_cases = len(n_stars)\n",
     "\n",
     "# plot moment interaction diagram\n",
-    "ax = f_mi_res.plot_diagram(fmt=\"k-\", render=False)\n",
+    "ax = f_mi_res.plot_diagram(\n",
+    "    fmt=\"k-\",\n",
+    "    units=si_kn_m,\n",
+    "    render=False,\n",
+    ")\n",
     "\n",
     "# check to see if combination is within diagram and plot result\n",
     "for idx in range(n_cases):\n",
@@ -356,6 +368,7 @@
     "    [f_mi_res, f_mi_res_bil, f_mi_res_par],\n",
     "    [\"Rectangular\", \"Bilinear\", \"Parabolic\"],\n",
     "    fmt=\"-\",\n",
+    "    units=si_kn_m,\n",
     ")"
    ]
   },
@@ -400,15 +413,19 @@
    "outputs": [],
    "source": [
     "# plot case 1\n",
-    "ax = f_bb_res1.plot_diagram(fmt=\"x-\", render=False)\n",
-    "bb_res1.plot_diagram(fmt=\"o-\", ax=ax)\n",
-    "plt.show()\n",
+    "BiaxialBendingResults.plot_multiple_diagrams_2d(\n",
+    "    [bb_res1, f_bb_res1],\n",
+    "    labels=[\"Unfactored\", \"Factored\"],\n",
+    "    units=si_kn_m,\n",
+    ")\n",
     "print(f\"Average phi = {np.mean(phis1):.3f}\")\n",
     "\n",
     "# plot case 2\n",
-    "ax = f_bb_res2.plot_diagram(fmt=\"x-\", render=False)\n",
-    "bb_res2.plot_diagram(fmt=\"o-\", ax=ax)\n",
-    "plt.show()\n",
+    "BiaxialBendingResults.plot_multiple_diagrams_2d(\n",
+    "    [bb_res2, f_bb_res2],\n",
+    "    labels=[\"Unfactored\", \"Factored\"],\n",
+    "    units=si_kn_m,\n",
+    ")\n",
     "print(f\"Average phi = {np.mean(phis2):.3f}\")"
    ]
   },

docs/examples/nzs3101.ipynb

@@ -27,6 +27,7 @@
     "    RectangularStressBlock,\n",
     ")\n",
     "from concreteproperties.design_codes import NZS3101\n",
+    "from concreteproperties.post import si_kn_m, si_n_mm\n",
     "from concreteproperties.results import (\n",
     "    MomentCurvatureResults,\n",
     "    MomentInteractionResults,\n",
@@ -75,10 +76,16 @@
     "ult_comp = concrete_40.ultimate_stress_strain_profile.get_ultimate_compressive_strain()\n",
     "print(f\"Ultimate Compressive Strain: {ult_comp:.4f}\")\n",
     "concrete_40.stress_strain_profile.plot_stress_strain(\n",
-    "    title=\"Concrete Serviceability Stress-Strain Profile\", fmt=\"-r\"\n",
+    "    title=\"Concrete Serviceability Stress-Strain Profile\",\n",
+    "    fmt=\"-r\",\n",
+    "    eng=True,\n",
+    "    units=si_n_mm,\n",
     ")\n",
     "concrete_40.ultimate_stress_strain_profile.plot_stress_strain(\n",
-    "    title=\"Concrete Ultimate Stress-Strain Profile\", fmt=\"-r\"\n",
+    "    title=\"Concrete Ultimate Stress-Strain Profile\",\n",
+    "    fmt=\"-r\",\n",
+    "    eng=True,\n",
+    "    units=si_n_mm,\n",
     ")"
    ]
   },
@@ -103,7 +110,10 @@
     "print(f\"Ultimate Tensile Strain = {ult_strain}\")\n",
     "print(f\"Overstrength Factor = {steel_300e.phi_os}\")\n",
     "steel_300e.stress_strain_profile.plot_stress_strain(\n",
-    "    title=\"Steel Stress-Strain Profile\", fmt=\"-r\"\n",
+    "    title=\"Steel Stress-Strain Profile\",\n",
+    "    fmt=\"-r\",\n",
+    "    eng=True,\n",
+    "    units=si_n_mm,\n",
     ")"
    ]
   },
@@ -458,6 +468,7 @@
     "    fmt=\"or\",\n",
     "    render=False,\n",
     "    moment=\"m_xy\",\n",
+    "    units=si_kn_m,\n",
     ")\n",
     "plt.gca().lines[0].set_linestyle(\"solid\")\n",
     "plt.gca().lines[0].set_marker(\"\")\n",
@@ -490,7 +501,7 @@
     "n_cases = len(n_stars)\n",
     "\n",
     "# plot moment interaction diagram\n",
-    "ax = f_mi_res.plot_diagram(fmt=\"-r\", render=False)\n",
+    "ax = f_mi_res.plot_diagram(fmt=\"-r\", render=False, units=si_kn_m)\n",
     "\n",
     "# check to see if combination is within diagram and plot result\n",
     "for idx in range(n_cases):\n",
@@ -541,12 +552,12 @@
    "outputs": [],
    "source": [
     "# plot case 1\n",
-    "ax = f_bb_res1.plot_diagram(fmt=\"-r\", render=False)\n",
+    "ax = f_bb_res1.plot_diagram(fmt=\"-r\", render=False, units=si_kn_m)\n",
     "ax.plot(M_o_T, 0, \"sk\")\n",
     "plt.show()\n",
     "\n",
     "# plot case 2\n",
-    "ax = f_bb_res2.plot_diagram(fmt=\"-r\", render=False)\n",
+    "ax = f_bb_res2.plot_diagram(fmt=\"-r\", render=False, units=si_kn_m)\n",
     "ax.plot(M_o_C, 0, \"ok\")\n",
     "plt.show()"
    ]
@@ -703,7 +714,10 @@
     ")\n",
     "\n",
     "concrete_25_prob.stress_strain_profile.plot_stress_strain(\n",
-    "    title=\"Mander Unconfined Stress-Strain Profile\", fmt=\"-r\"\n",
+    "    title=\"Mander Unconfined Stress-Strain Profile\",\n",
+    "    fmt=\"-r\",\n",
+    "    eng=True,\n",
+    "    units=si_n_mm,\n",
     ")"
    ]
   },
@@ -801,7 +815,12 @@
     "fail_mat = moment_curvature_results.failure_geometry.material.name\n",
     "print(f\"The failure material is:-\\n{fail_mat}\")\n",
     "\n",
-    "MomentCurvatureResults.plot_results(moment_curvature_results, fmt=\"-r\")\n",
+    "MomentCurvatureResults.plot_results(\n",
+    "    moment_curvature_results,\n",
+    "    fmt=\"-r\",\n",
+    "    eng=True,\n",
+    "    units=si_kn_m,\n",
+    ")\n",
     "mcr = conc_sec.calculate_cracked_properties(theta=0).m_cr / 1e6\n",
     "print(f\"Cracking moment is M_cr = {mcr:.2f} kNm\")"
    ]

docs/examples/prestressed_section.ipynb

@@ -624,7 +624,7 @@
    "id": "42",
    "metadata": {},
    "source": [
-    "Another point of interest on the moment curvature diagram is around 8000 kN.m. At this magnitude of external moment, the section in the service analysis remains uncracked (just below the flexural tensile strenght). However, the section in the ultimate analysis has started to crack and the bending stiffness has begun to soften. Note also the resulting increase in concrete compressive stress to compensate."
+    "Another point of interest on the moment curvature diagram is around 8000 kN.m. At this magnitude of external moment, the section in the service analysis remains uncracked (just below the flexural tensile strength). However, the section in the ultimate analysis has started to crack and the bending stiffness has begun to soften. Note also the resulting increase in concrete compressive stress to compensate."
    ]
   },
   {

docs/user_guide/design_codes/as3600.rst

@@ -21,11 +21,14 @@ created it must be assigned to the design code::
 ..  automethod:: concreteproperties.design_codes.as3600.AS3600.assign_concrete_section
   :noindex:
 
-.. note::
+.. warning::
 
-  To maintain unit consistency, the cross-section dimensions should be entered in
-  *[mm]*.
+  To maintain unit consistency, length dimensions must be entered in *[mm]*, force
+  dimensions entered in *[N]* and density dimensions entered |dunits|.
 
+.. |dunits| raw:: html
+
+  <em>[kg/mm<sup>3</sup>]</em>
 
 Creating Material Properties
 ----------------------------

docs/user_guide/results.rst

@@ -40,9 +40,8 @@ attributes. The transformed gross area properties can be printed to the terminal
 calling the
 :meth:`~concreteproperties.results.TransformedGrossProperties.print_results` method.
 
-..  autoclass:: concreteproperties.results.TransformedGrossProperties()
+..  automethod:: concreteproperties.results.TransformedGrossProperties.print_results()
   :noindex:
-  :members:
 
 .. seealso::
   For an application of the above, see the example
@@ -68,7 +67,7 @@ returns a :class:`~concreteproperties.results.CrackedResults` object.
   bending.
 
 Calling
-:meth:`~concreteproperties.results.TransformedGrossProperties.calculate_transformed_properties`
+:meth:`~concreteproperties.results.CrackedResults.calculate_transformed_properties`
 on a :class:`~concreteproperties.results.CrackedResults` object stores the transformed
 cracked properties as attributes within the current object.
 
@@ -167,3 +166,49 @@ stress results.
 .. seealso::
   For an application of the above, see the example
   :ref:`/examples/stress_analysis.ipynb`.
+
+
+Units
+-----
+
+Most of the above methods take an optional ``units`` argument as a
+:class:`~concreteproperties.post.UnitDisplay()` object. This argument allows results to
+be scaled and unit labels applied to numbers/plot axes.
+
+..  autoclass:: concreteproperties.post.UnitDisplay()
+  :noindex:
+
+For example, if the model data is specified in ``[N]`` and ``[mm]``, results can be
+expressed using ``[kN]`` and ``[m]`` by creating an appropriate ``UnitDisplay`` object:
+
+.. code-block:: python
+
+  from concreteproperties.post import UnitDisplay
+
+  kn_m = UnitDisplay(si_kn_m = UnitDisplay(
+    length="m", force="kN", mass="kg", length_factor=1e3, force_factor=1e3
+  )
+
+Note that stresses will automatically be displayed as kilopascals using the above
+unit system as ``[kPa]`` is equivalent to |kpa|. Similarly, results in ``[N.mm]``,
+``[MPa]`` etc. can be automatically displayed by creating a ``UnitDisplay`` object that
+represents the base unit system:
+
+.. |kpa| raw:: html
+
+  <code class="docutils literal notranslate"><span class="pre">[kN/m<sup>2</sup>]</span></code>
+
+.. code-block:: python
+
+  from concreteproperties.post import UnitDisplay
+
+  n_mm = UnitDisplay(length="mm", force="N", mass="kg")
+
+Note that the above two unit systems are baked into ``concreteproperties`` in the
+``post`` module with the ``si_n_mm`` and ``si_kn_m`` objects:
+
+.. code-block:: python
+
+  from concreteproperties.post import si_kn_m, si_n_mm
+
+``concreteproperties`` welcomes the contribution of further unit systems!

pyproject.toml

@@ -59,6 +59,7 @@ docs = [
     "ipython==8.29.0",
     "nbsphinx==0.9.5",
     "nbconvert==7.16.4",
+    "sphinx-autobuild==2024.10.03",
     "sphinx-copybutton==0.5.2",
     "sphinxext-opengraph==0.9.1",
 ]