feat: begin to handle *DEFINE_TRANSFORMATION when expanding include decks (#740)

Co-authored-by: Mohamed Koubaa <[email protected]>
Co-authored-by: pyansys-ci-bot <[email protected]>

Author: 3 people

doc/changelog/740.test.md

@@ -0,0 +1 @@
+feat: begin to handle *DEFINE_TRANSFORMATION when expanding include decks

pyproject.toml

@@ -32,7 +32,8 @@ dependencies = ["ansys-dpf-core>=0.7.2",
                 "hollerith>=0.6.0",
                 "numpy>=1",
                 "pandas>=2.0",
-                "appdirs>=1.4.4"
+                "appdirs>=1.4.4",
+                "transformations==2025.1.1",
 ]
 
 [project.optional-dependencies]

src/ansys/dyna/core/lib/transforms/node_transform.py

@@ -21,14 +21,47 @@
 # SOFTWARE.
 
 """Transformation handler for *NODE."""
+import warnings
+
+import numpy as np
+import pandas as pd
 
 from ansys.dyna.core import keywords as kwd
 from ansys.dyna.core.lib.transforms.base_transform import Transform
+from ansys.dyna.core.lib.transforms.utils.define_transformation import get_transform_matrix
+
+
+def apply_rigid_transform(mtx: np.ndarray, nodes: pd.DataFrame) -> None:
+    locations = nodes[["x", "y", "z"]]
+    locations = locations.fillna(0.0)
+    locations["w"] = 1.0
+    locs = locations.to_numpy()
+    for i, loc in enumerate(locs):
+        res = np.dot(mtx, loc)  # transform the point
+        locs[i] = res
+
+    locations[["x", "y", "z", "w"]] = locs
+    nodes[["x", "y", "z"]] = locations[["x", "y", "z"]]
 
 
 class TransformNode(Transform):
     def transform(self, keyword: kwd.Node) -> None:
+        self._apply_offset(keyword)
+        try:
+            self._apply_transform(keyword)
+        except Exception as e:
+            warnings.warn(f"Error applying transformation to *NODE: {e}")
+            raise e
+
+    def _apply_offset(self, keyword: kwd.Node) -> None:
         offset = self._xform.idnoff
         if offset is None or offset == 0:
             return
         keyword.nodes["nid"] = keyword.nodes["nid"] + offset
+
+    def _apply_transform(self, keyword: kwd.Node) -> None:
+        define_transform = self._xform.tranid_link
+        mtx = get_transform_matrix(define_transform)
+        if mtx is None:
+            return
+        apply_rigid_transform(mtx, keyword.nodes)

src/ansys/dyna/core/lib/transforms/utils/__init__.py

@@ -0,0 +1,104 @@
+# Copyright (C) 2021 - 2024 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Algorithms to compute 4x4 transformation matrices from a *DEFINE_TRANSFORMATION keyword."""
+
+import math
+import typing
+import warnings
+
+import numpy as np
+import pandas as pd
+import transformations as tfm
+
+from ansys.dyna.core.keywords.keyword_classes.auto.define_transformation import DefineTransformation
+
+
+def _get_translation_matrix(a1: float, a2: float, a3: float) -> np.ndarray:
+    return tfm.translation_matrix((a1, a2, a3))
+
+
+def _get_rotation_matrix(a1: float, a2: float, a3: float, a4: float, a5: float, a6: float, a7: float) -> np.ndarray:
+    if (a4, a5, a6) == (0.0, 0.0, 0.0):
+        if a7 != 0.0:
+            # simple rotation about an axis going through the origin
+            assert (a1, a2, a3) != (0.0, 0.0, 0.0), "Direction vector A1, A2, A3 cannot be all zero!"
+            return tfm.rotation_matrix(math.radians(a7), [a1, a2, a3])
+
+    parameters = (a1, a2, a3, a4, a5, a6, a7)
+    warnings.warn(f"DEFINE_TRANFORMATION ROTATE option with parameters {parameters} not handled yet by pydyna!")
+    return None
+
+
+def _get_row_transform_matrix(transform: pd.Series) -> np.ndarray:
+    """Transform is of a series of the form:
+
+    option    ROTATE
+    a1           0.0
+    a2           0.0
+    a3           1.0
+    a4           0.0
+    a5           0.0
+    a6           0.0
+    a7         -25.0
+
+    whose behavior is according to the rules of *DEFINE_TRANSFORM
+    """
+    mtx = tfm.identity_matrix()
+    xf = transform.fillna(0.0)
+    option, a1, a2, a3, a4, a5, a6, a7 = (
+        xf["option"],
+        xf["a1"],
+        xf["a2"],
+        xf["a3"],
+        xf["a4"],
+        xf["a5"],
+        xf["a6"],
+        xf["a7"],
+    )
+    if option == "TRANSL":
+        return _get_translation_matrix(a1, a2, a3)
+    elif option == "ROTATE":
+        return _get_rotation_matrix(a1, a2, a3, a4, a5, a6, a7)
+    else:
+        warnings.warn(f"DEFINE_TRANFORMATION option {option} not handled yet by pydyna!")
+        return None
+
+
+def _get_transform_matrix(transforms: pd.DataFrame) -> np.ndarray:
+    mtx = tfm.identity_matrix()
+    for index, transform in transforms.iterrows():
+        row_mtx = _get_row_transform_matrix(transform)
+        if row_mtx is None:
+            return None
+        mtx = tfm.concatenate_matrices(mtx, row_mtx)
+    return mtx
+
+
+def get_transform_matrix(kwd: typing.Optional[DefineTransformation]) -> typing.Optional[np.ndarray]:
+    if kwd is None:
+        return None
+    transforms = kwd.transforms
+    if len(transforms) == 0:
+        return None
+    mtx = _get_transform_matrix(transforms)
+    return mtx

src/ansys/dyna/core/lib/transforms/utils/define_transformation.py

@@ -21,6 +21,7 @@
 # SOFTWARE.
 
 import os
+import re
 
 import pandas as pd
 
@@ -460,6 +461,84 @@ def _transform_part_ids(self, elements: pd.DataFrame):
     assert deck.keywords[1].elements["pid"][0] == 44
     assert deck.keywords[1].elements["pid"][3] == 44
 
+
+@pytest.mark.keywords
+def test_deck_expand_with_define_transform(file_utils):
+    """Test using a custom transform handler as an override."""
+
+    # single translation
+    include_path = file_utils.get_asset_file_path("transform")
+    define_transform_kwd = kwd.DefineTransformation(tranid=1, option="TRANSL", a1=-100.0)
+    xform = kwd.IncludeTransform(filename = os.path.join(include_path, "test.k"))
+    xform.tranid_link = define_transform_kwd
+
+    deck = Deck()
+    deck.extend([define_transform_kwd, xform])
+    expanded = deck.expand()
+    assert len(expanded.keywords) == 4
+    assert expanded.keywords[3].nodes["x"][0] == -600
+
+    # error case
+    deck = Deck()
+    define_transform_kwd = kwd.DefineTransformation(tranid=1, option="ROTATE", a1=0.0, a2=0.0, a3=0.0, a7=45.0)
+    xform = kwd.IncludeTransform(filename = os.path.join(include_path, "test.k"))
+    xform.tranid_link = define_transform_kwd
+    deck.extend([define_transform_kwd, xform])
+    expected_warning = "Error applying transformation to *NODE: Direction vector A1, A2, A3 cannot be all zero!"
+    expected_warning_expression = re.escape(expected_warning)
+    with pytest.warns(UserWarning, match=expected_warning_expression):
+        deck.expand()
+
+    # unhandled case
+    deck = Deck()
+    define_transform_kwd = kwd.DefineTransformation(tranid=1, option="ROTATE", a4=1.0)
+    xform = kwd.IncludeTransform(filename = os.path.join(include_path, "test.k"))
+    xform.tranid_link = define_transform_kwd
+    deck.extend([define_transform_kwd, xform])
+    with pytest.warns(UserWarning, match="DEFINE_TRANFORMATION ROTATE option with parameters"):
+        deck.expand()
+
+    # multiple transforms
+    deck = Deck()
+    define_transform_kwd = kwd.DefineTransformation()
+    define_transform_kwd.transforms = pd.DataFrame(
+        {
+            "option": ["ROTATE", "TRANSL"],
+            "a1": [0.0, -100.0],
+            "a2": [0.0, 0.0],
+            "a3": [1.0, 0.0],
+            "a4": [0.0, 0.0],
+            "a5": [0.0, 0.0],
+            "a6": [0.0, 0.0],
+            "a7": [25.0, 0.0],
+        }
+    )
+    xform = kwd.IncludeTransform(filename = os.path.join(include_path, "test.k"))
+    xform.tranid_link = define_transform_kwd
+    deck.extend([define_transform_kwd, xform])
+    expanded = deck.expand()
+    assert len(expanded.keywords) == 4
+    print(expanded.keywords[3].nodes)
+    assert expanded.keywords[3].nodes["x"][0] == pytest.approx(-543.784672)
+    assert expanded.keywords[3].nodes["y"][0] == pytest.approx(-253.570957)
+
+
+@pytest.mark.keywords
+def test_deck_clear():
+    node = kwd.Node()
+    deck = Deck()
+    deck.append(node)
+    deck.clear()
+    # ok after clear
+    deck = Deck()
+    deck.append(node)
+
+    # not ok without clear
+    deck2 = Deck()
+    with pytest.raises(Exception):
+        deck2.append(node)
+
+
 @pytest.mark.keywords
 def test_deck_unprocessed(ref_string):
     deck = Deck()

tests/test_deck.py

@@ -0,0 +1,116 @@
+
+import math
+import re
+
+from ansys.dyna.core import keywords as kwd
+from ansys.dyna.core.lib.transforms.utils.define_transformation import get_transform_matrix
+
+import numpy as np
+import pandas as pd
+import pytest
+import transformations as tfm
+
+@pytest.mark.keywords
+def test_transform_none():
+    """Verify no transformation for no input."""
+    mtx = get_transform_matrix(None)
+    assert mtx is None
+
+@pytest.mark.keywords
+def test_transform_empty():
+    """Verify no transfomration matrix for an empty DEFINE_TRANFORMATION."""
+    define_transform_kwd = kwd.DefineTransformation()
+    mtx = get_transform_matrix(None)
+    assert mtx is None
+
+@pytest.mark.keywords
+def test_transform_rotation_1():
+    """Verify the transfomration matrix for single ROTATE."""
+
+    # The transformation of a rotation of 45 degrees about the X axis
+    define_transform_kwd = kwd.DefineTransformation(option="ROTATE", a1=1, a2=0, a3=0, a7=45)
+    mtx = get_transform_matrix(define_transform_kwd)
+    ref_45x = tfm.rotation_matrix(math.radians(45),[1,0,0])
+    assert np.allclose(mtx, ref_45x)
+
+    # not yet supported if a4-a7 are zero
+    define_transform_kwd = kwd.DefineTransformation(option="ROTATE", a1=1, a2=0, a3=0)
+    expected_warning = "DEFINE_TRANFORMATION ROTATE option with parameters (1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0) not handled yet by pydyna!"
+    expected_warning_expression = re.escape(expected_warning)
+    with pytest.warns(UserWarning, match=expected_warning_expression):
+        mtx = get_transform_matrix(define_transform_kwd)
+    assert mtx is None
+
+    # not yet supported if a4-a7 are zero
+    define_transform_kwd = kwd.DefineTransformation(option="ROTATE", a1=0, a2=0, a3=0, a7=0)
+    expected_warning = "DEFINE_TRANFORMATION ROTATE option with parameters (0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0) not handled yet by pydyna!"
+    expected_warning_expression = re.escape(expected_warning)
+    with pytest.warns(UserWarning, match=expected_warning_expression):
+        mtx = get_transform_matrix(define_transform_kwd)
+    assert mtx is None
+
+    # 360 degrees about any arbitrary axis is the identity matrix
+    define_transform_kwd = kwd.DefineTransformation(option="ROTATE", a1=0.4, a2=3.2, a3=1.1, a7=360.0)
+    mtx = get_transform_matrix(define_transform_kwd)
+    ref_i = tfm.identity_matrix()
+    assert np.allclose(mtx,ref_i)
+
+    # a1, a2, a3 cannot be zero if the angle of rotation is nonzero
+    define_transform_kwd = kwd.DefineTransformation(option="ROTATE", a1=0, a2=0, a3=0, a7=90)
+    with pytest.raises(AssertionError):
+        get_transform_matrix(define_transform_kwd)
+
+@pytest.mark.keywords
+def test_transform_matrix_two_translations():
+    """Verify the transformation matrix for multiple TRANSL"""
+    define_transform_kwd = kwd.DefineTransformation()
+    define_transform_kwd.transforms = pd.DataFrame(
+        {
+            "option": ["TRANSL", "TRANSL"],
+            "a1": [0.0, -100.0],
+            "a2": [0.0, 0.0],
+            "a3": [200.0, 0.0],
+        }
+    )
+    mtx = get_transform_matrix(define_transform_kwd)
+    ref = tfm.translation_matrix((-100,0,200))
+    assert np.allclose(mtx, ref)
+
+@pytest.mark.keywords
+def test_transform_matrix_one_translations():
+    """Verify the transformation matrix for a single TRANSL."""
+    define_transform_kwd = kwd.DefineTransformation(option="TRANSL", a1=-200, a2=0.0, a3=0.0)
+    mtx = get_transform_matrix(define_transform_kwd)
+    ref = tfm.translation_matrix((-200,0,0))
+    assert np.allclose(mtx, ref)
+
+@pytest.mark.keywords
+def test_transform_matrix_translation_rotation():
+    """Verify the transformation matrix for a single TRANSL."""
+    define_transform_kwd = kwd.DefineTransformation()
+    define_transform_kwd.transforms = pd.DataFrame(
+        {
+            "option": ["ROTATE", "TRANSL"],
+            "a1": [0.0, -100.0],
+            "a2": [0.0, 0.0],
+            "a3": [1.0, 0.0],
+            "a4": [0.0, 0.0],
+            "a5": [0.0, 0.0],
+            "a6": [0.0, 0.0],
+            "a7": [25.0, 0.0],
+        }
+    )
+    t_25z = tfm.rotation_matrix(math.radians(25),[0,0,1])
+    t_trans = tfm.translation_matrix((-100,0,0))
+    ref = tfm.concatenate_matrices(t_25z, t_trans)
+    mtx = get_transform_matrix(define_transform_kwd)
+    assert np.allclose(mtx, ref)
+
+@pytest.mark.keywords
+def test_transform_unhandled():
+    """Verify warning and no transformation when an unhandled DEFINE_TRANSFORMATION option is used."""
+    option = "TRANSL2ND"
+    define_transform_kwd = kwd.DefineTransformation(option=option)
+    with pytest.warns(UserWarning, match=f"DEFINE_TRANFORMATION option {option} not handled yet by pydyna!"):
+        mtx = get_transform_matrix(define_transform_kwd)
+    assert mtx is None