feat: (PR 4122) adding OSRESULT command to the misc loads (#4131)

* Adding OSRESULT command to the misc loads

* ci: auto fixes from pre-commit.com hooks.

for more information, see https://pre-commit.ci

* chore: adding changelog file 4131.miscellaneous.md [dependabot-skip]

* chore: adding changelog file 4131.miscellaneous.md [dependabot-skip]

* feat: add osresult method to retrieve and format command output. Also adding tests

* feat: add test for osresult output to list and DataFrame using pandas

* fix: remove redundant outres call in test_osresult_presol

---------

Co-authored-by: Mehmet Baris Batukan <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: German <[email protected]>

Author: 4 people

doc/changelog.d/4131.miscellaneous.md

@@ -0,0 +1 @@
+Feat: (pr 4122) adding osresult command to the misc loads

src/ansys/mapdl/core/_commands/solution/miscellaneous_loads.py

@@ -1000,6 +1000,138 @@ def outres(self, item="", freq="", cname="", nsvar="", dsubres="", **kwargs):
         command = f"OUTRES,{item},{freq},{cname},{nsvar},{dsubres}"
         return self.run(command, **kwargs)
 
+    def osresult(self, item="", comp="", freq="", cname="", **kwargs):
+        """Controls the selected result data written to the database.
+
+        APDL Command: OSRESULT
+
+        Parameters
+        ----------
+        item
+            Item to output to the database:
+
+            ERASE - Erases all selected result output specifications
+
+            STATUS - Lists the current set of selected result output specifications
+
+            SVAR - State variable number
+
+            FLD - User-defined field variables
+
+            S - Component and derived (principal, intensity, equivalent) stresses
+
+            EPEL - Component and derived (principal, intensity, equivalent) elastic strains
+
+            EPPL - Component and derived (principal, intensity, equivalent) plastic strains
+
+            EPCR - Component and derived (principal, intensity, equivalent) creep strains
+
+            EPTH - Component and derived (principal, intensity, equivalent) thermal strains
+
+            CDM - Mullins effect damage variable and maximum previous strain energy
+
+            PMSV - Pore mechanics state variables for coupled pore-pressure-thermal elements
+
+            FFLX - Fluid flow flux components in poromechanics
+
+            FGRA - Fluid pore pressure gradient components in poromechanics
+
+            BKS - Total nonlinear kinematic backstress components
+
+            GDMG - Generalized and ductile damage values
+
+        comp
+            Component of Item to output to the database:
+
+            For S, EPEL, EPPL, EPCR, EPTH: X, Y, Z, XY, YZ, XZ, 1, 2, 3, INT, EQV
+
+            For SVAR: 1, 2, 3, ..., N (state variable number)
+
+            For FLD: UF01, UF02, ..., UF09 (user-defined field variables)
+
+            For CDM: DMG, LM
+
+            For PMSV: VRAT, PPRE, DSAT, RPER
+
+            For FFLX, FGRA: X, Y, Z
+
+            For BKS: X, Y, Z, XY, YZ, XZ
+
+            For GDMG: ETA, ETAC, IDRA, DUCT (or blank for generalized damage)
+
+        freq
+            Frequency to output to the database:
+
+            n - Writes every nth and last substep of each load step
+
+            -n - Writes up to n equally spaced substeps of each load step
+
+            ALL - Writes every substep
+
+            LAST - Writes the last substep of each load step (default)
+
+        cname
+            The name of an element component (CM) defining the set of elements
+            for which this specification is active. If not specified, the set
+            is all elements.
+
+        Notes
+        -----
+        OSRESULT controls output to the results database for the selected result
+        defined by the item and component combination. The command activates output
+        of the selected result for the specified substeps and elements. Multiple
+        commands for the same result are cumulative. No selected results are written
+        to the database unless specified via OSRESULT.
+
+        The saved selected quantities are accessible via standard postprocessing
+        commands (ANSOL, ETABLE, ESOL, PLESOL, PLNSOL, PRESOL, and PRNSOL).
+
+        OSRESULT,ERASE deletes the existing output specifications.
+
+        OSRESULT,STATUS lists the current set of selected result specifications.
+
+        The output of selected results is valid for static (ANTYPE,STATIC) and
+        transient (ANTYPE,TRANS) analysis types.
+
+        To select other results to output to the database, see OUTRES. (Element
+        quantities specified via OUTRES can be redundant to those specified via
+        OSRESULT. Avoid specifying redundant quantities, as they are stored and
+        processed separately.)
+
+        All OSRESULT results are in the solution coordinate system.
+
+        This command is also valid in PREP7.
+
+        Examples
+        --------
+        Enter solution
+
+        >>> mapdl.slashsolu()
+
+        Suppress all solution results output first
+
+        >>> mapdl.outres("ALL", "NONE")
+
+        Use OSRESULT to specify selected results
+
+        >>> mapdl.osresult("S", "Y", "ALL")        # Stress Y component
+        >>> mapdl.osresult("S", "EQV", "ALL")      # Equivalent stress
+        >>> mapdl.osresult("EPPL", "INT", "ALL")   # Plastic strain intensity
+
+        Enter postprocessor
+
+        >>> mapdl.post1()
+
+        Retrieve selected results using PRESOL and PRNSOL
+
+        >>> mapdl.presol("SRES", "SY")      # Print selected stress Y
+        >>> mapdl.presol("SRES", "SEQV")    # Print selected equivalent stress
+        >>> mapdl.prnsol("SRES", "EPPLINT") # Print selected plastic strain intensity
+
+        """
+        command = f"OSRESULT,{item},{comp},{freq},{cname}"
+        return self.run(command, **kwargs)
+
     def rescontrol(
         self,
         action="",

src/ansys/mapdl/core/mapdl_extended.py

@@ -23,6 +23,7 @@
 from functools import wraps
 import os
 import pathlib
+import re
 import tempfile
 from typing import Union
 import warnings
@@ -31,7 +32,7 @@
 from numpy.typing import DTypeLike, NDArray
 
 from ansys.mapdl.core import LOG as logger
-from ansys.mapdl.core.commands import CommandListingOutput
+from ansys.mapdl.core.commands import CommandListingOutput, CommandOutput
 from ansys.mapdl.core.errors import (
     CommandDeprecated,
     ComponentDoesNotExits,
@@ -2375,6 +2376,26 @@ def parain(
             **kwargs,
         )
 
+    @wraps(_MapdlCore.osresult)
+    def osresult(self, item="", comp="", freq="", cname="", **kwargs) -> CommandOutput:
+        result = super().osresult(item, comp, freq, cname, **kwargs)
+        if item.upper().strip() == "STATUS":
+            from ansys.mapdl.core.misc import expand_all_inner_lists
+
+            columns_names = ["ITEM", "FREQUENCY", "COMPONENT"]
+            result = CommandListingOutput(result)
+            table = re.search(
+                r"ITEM\s+FREQUENCY\s+COMPONENT(.*)", result, flags=re.DOTALL
+            ).group(1)
+            table = [each.split() for each in table.splitlines() if each.strip()]
+            table = expand_all_inner_lists(
+                table, target_length=len(columns_names), fill_value=""
+            )
+
+            result._columns_names = columns_names
+            result._cache = np.array(table)
+        return result
+
 
 class _MapdlExtended(_MapdlCommandExtended):
     """Extend Mapdl class with new functions"""

src/ansys/mapdl/core/misc.py

@@ -33,6 +33,7 @@
 import tempfile
 from threading import Thread
 from typing import (
+    Any,
     Callable,
     Dict,
     Iterable,
@@ -717,3 +718,13 @@ def get_ip_hostname(ip: str) -> Tuple[str, str]:
                 hostname = ip
 
     return ip, hostname
+
+
+def expand_all_inner_lists(
+    lst: list[list[Any]], target_length: int, fill_value: str = ""
+) -> list[list[Any]]:
+    for inner in lst:
+        missing = target_length - len(inner)
+        if missing > 0:
+            inner.extend([fill_value] * missing)
+    return lst

tests/test_mapdl.py

@@ -3172,3 +3172,74 @@ def test_rpsd(mapdl, psd_analysis):
     output = mapdl.rpsd(3, 2, "", 1, 2)
     assert isinstance(output, np.ndarray)
     assert output.shape == (64, 1)
+
+
+def test_osresult(mapdl, solved_box):
+    mapdl.solution()
+
+    mapdl.outres("ALL", "NONE")
+    mapdl.osresult("S", "Y", "ALL")  # Stress Y component
+    mapdl.osresult("S", "EQV", "ALL")  # Equivalent stress
+    mapdl.osresult("EPPL", "INT", "ALL")  # Plastic strain intensity
+
+    assert "S" in mapdl.osresult("STATUS")
+    assert "Y" in mapdl.osresult("STATUS")
+    assert "EQV" in mapdl.osresult("STATUS")
+    assert "EPPL" in mapdl.osresult("STATUS")
+    assert "INT" in mapdl.osresult("STATUS")
+
+
+@requires("pandas")
+def test_osresult_to_list_and_dataframe(mapdl, solved_box):
+    import pandas as pd
+
+    mapdl.solution()
+
+    mapdl.outres("ALL", "NONE")
+    mapdl.osresult("S", "Y", "ALL")  # Stress Y component
+    mapdl.osresult("S", "EQV", "ALL")  # Equivalent stress
+    mapdl.osresult("EPPL", "INT", "ALL")  # Plastic strain intensity
+
+    expected_list = [["SY", "ALL", ""], ["SEQV", "ALL", ""], ["EPPLINT", "ALL", ""]]
+    assert (
+        mapdl.osresult("STATUS").to_list() == expected_list
+    ), "Status should contain the requested results"
+
+    expected_df = pd.DataFrame(
+        data=expected_list, columns=["ITEM", "FREQUENCY", "COMPONENT"]
+    )
+    assert (
+        mapdl.osresult("STATUS").to_dataframe().equals(expected_df)
+    ), "DataFrame should match the expected results"
+
+
+@pytest.mark.xfail(
+    reason="Bug in v25R2, osresult lists results as many times as issued",
+    strict=True,
+)
+def test_osresult_multiple(mapdl, solved_box):
+    mapdl.solution()
+
+    mapdl.outres("ALL", "NONE")
+    for i in range(3):
+        mapdl.osresult("EPPL", "INT", "ALL")
+
+    assert (
+        mapdl.osresult("STATUS").count("EPPLINT") == 1
+    ), "EPPLINT should only be listed once in the status"
+
+
+@pytest.mark.xfail(
+    reason="Bug? PRESOL cannot retrieve osresult data",
+    strict=True,
+)
+def test_osresult_presol(mapdl, solved_box):
+    mapdl.solution()
+
+    mapdl.outres("ALL", "NONE")
+    mapdl.osresult("S", "Y", "ALL")  # Stress Y component
+
+    mapdl.solve()
+    mapdl.post1()
+
+    assert mapdl.presol("SRES", "SY")