Add section cut export methods (#850)

Add methods `export` and `export_becas_input` to the `SectionCut` class.

The two export types (CDB / BECAS) are implemented as separate methods to mirror the API, rather than in the same method like in ACP scripting.
Combining them would be tricky because their signatures are completely different:
- the `path` argument is expected to be a filename for CDB export, and a directory for BECAS export
- their effect is also distinct: CDB export creates one file, BECAS export creates multiple
- they have distinct _additional_ keyword arguments (this alone would be manageable)

To enable the multiple-file export, an additional parameter `is_directory` is added to the `FileTransferStrategy.to_export_path` interface.

The `auto_download` context manager cannot be used in the multi-file export context. Its logic is reimplemented / adapted directly in `export_becas_input`. If / once there are multiple such cases, we may want to either extend `auto_download`, or add an alternative context manager which directly supports it.

Closes #770.

Author: greschd

doc/source/api/enum_types.rst

@@ -47,6 +47,7 @@ Enumeration data types
     RosetteSelectionMethod
     RosetteType
     SectionCutType
+    SectionCutCDBExportType
     SensorType
     SnapToGeometryOrientationType
     SolidModelExportFormat

src/ansys/acp/core/__init__.py

@@ -126,6 +126,7 @@
     RosetteType,
     SamplingPoint,
     SectionCut,
+    SectionCutCDBExportType,
     SectionCutType,
     Sensor,
     SensorType,
@@ -259,6 +260,7 @@
     "RosetteType",
     "SamplingPoint",
     "SectionCut",
+    "SectionCutCDBExportType",
     "SectionCutType",
     "Sensor",
     "SensorType",

src/ansys/acp/core/_server/acp_instance.py

@@ -51,7 +51,7 @@ def upload_file(self, local_path: _PATH) -> pathlib.PurePath: ...
 
     def download_file(self, remote_path: _PATH, local_path: _PATH) -> None: ...
 
-    def to_export_path(self, path: _PATH) -> _PATH: ...
+    def to_export_path(self, path: _PATH, is_directory: bool = False) -> pathlib.Path: ...
 
 
 class LocalFileTransferStrategy(FileTransferStrategy):
@@ -70,7 +70,7 @@ def download_file(self, remote_path: _PATH, local_path: _PATH) -> None:
             return
         shutil.copyfile(remote_path_aslocal, local_path)
 
-    def to_export_path(self, path: _PATH) -> _PATH:
+    def to_export_path(self, path: _PATH, is_directory: bool = False) -> pathlib.Path:
         return self._get_remote_path(path)
 
     def _get_remote_path(self, path: _PATH) -> pathlib.Path:
@@ -125,9 +125,11 @@ def download_file(self, remote_path: _PATH, local_path: _PATH) -> None:
             remote_filename=str(remote_path), local_filename=str(local_path)
         )
 
-    def to_export_path(self, path: _PATH) -> _PATH:
+    def to_export_path(self, path: _PATH, is_directory: bool = False) -> pathlib.Path:
         # Export to the working directory of the server
-        return pathlib.Path(path).name
+        if is_directory:
+            return pathlib.Path(".")
+        return pathlib.Path(pathlib.Path(path).name)
 
 
 class FileTransferHandler:
@@ -150,9 +152,9 @@ def download_file_if_autotransfer(self, remote_path: _PATH, local_path: _PATH) -
             # same as the local path. Otherwise, this is a bug in our code.
             assert remote_path == local_path
 
-    def to_export_path(self, path: _PATH) -> _PATH:
+    def to_export_path(self, path: _PATH, is_directory: bool = False) -> _PATH:
         if self._auto_transfer_files:
-            return self._filetransfer_strategy.to_export_path(path)
+            return self._filetransfer_strategy.to_export_path(path, is_directory=is_directory)
         return path
 
     def upload_file(self, local_path: _PATH) -> pathlib.PurePath:

src/ansys/acp/core/_tree_objects/__init__.py

@@ -78,6 +78,7 @@
     ReinforcingBehavior,
     RosetteSelectionMethod,
     RosetteType,
+    SectionCutCDBExportType,
     SectionCutType,
     SensorType,
     SnapToGeometryOrientationType,
@@ -290,6 +291,7 @@
     "SamplingPoint",
     "ScalarData",
     "SectionCut",
+    "SectionCutCDBExportType",
     "SectionCutType",
     "Sensor",
     "SensorType",

src/ansys/acp/core/_tree_objects/enums.py

@@ -80,6 +80,7 @@
     "ReinforcingBehavior",
     "RosetteSelectionMethod",
     "RosetteType",
+    "SectionCutCDBExportType",
     "SectionCutType",
     "SensorType",
     "SnapToGeometryOrientationType",
@@ -472,6 +473,13 @@
     doc="Determines how the intersection is computed for wireframe section cuts.",
 )
 
+SectionCutCDBExportType, section_cut_cdb_export_type_to_pb, _ = wrap_to_string_enum(
+    "SectionCutCDBExportType",
+    section_cut_pb2.CDBExportType,
+    module=__name__,
+    doc="Determines the type of section cut model to be exported to ANSYS Mechanical APDL.",
+)
+
 (ExtrusionMethod, extrusion_method_type_to_pb, extrusion_method_type_from_pb) = wrap_to_string_enum(
     "ExtrusionMethod",
     solid_model_pb2.ExtrusionMethodType,

src/ansys/acp/core/_tree_objects/section_cut.py

@@ -23,11 +23,16 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
+import pathlib
+import typing
 
 from ansys.api.acp.v0 import section_cut_pb2, section_cut_pb2_grpc
 
 from .._utils.array_conversions import to_1D_double_array, to_tuple_from_1D_array
+from .._utils.path_to_str import path_to_str_checked
 from .._utils.property_protocols import ReadOnlyProperty, ReadWriteProperty
+from .._utils.typing_helper import PATH as _PATH
+from ._grpc_helpers.exceptions import wrap_grpc_errors
 from ._grpc_helpers.linked_object_list import define_linked_object_list
 from ._grpc_helpers.property_helper import (
     grpc_data_property,
@@ -39,11 +44,13 @@
 from .enums import (
     ExtrusionType,
     IntersectionType,
+    SectionCutCDBExportType,
     SectionCutType,
     extrusion_type_from_pb,
     extrusion_type_to_pb,
     intersection_type_from_pb,
     intersection_type_to_pb,
+    section_cut_cdb_export_type_to_pb,
     section_cut_type_from_pb,
     section_cut_type_to_pb,
     status_type_from_pb,
@@ -225,3 +232,81 @@ def _create_stub(self) -> section_cut_pb2_grpc.ObjectServiceStub:
     number_of_interpolation_points: ReadWriteProperty[int, int] = grpc_data_property(
         "properties.number_of_interpolation_points"
     )
+
+    def export(
+        self,
+        path: _PATH,
+        *,
+        export_type: SectionCutCDBExportType = "mesh_only",
+    ) -> None:
+        """Export the section cut to a CDB file.
+
+        Parameters
+        ----------
+        path :
+            Path to the file where the section cut is saved.
+        export_type :
+            Determines what is exported to the CDB file. Options are:
+
+            - ``"mesh_only"``: Only the mesh (elements and nodes) is exported.
+            - ``"solid_model"``: The section cut is expanded into a slice of
+              solid elements. In addition, the material properties are exported
+              and the element coordinate systems are aligned with the fiber
+              direction. This model can be used to compute the equivalent
+              beam properties of the section cut.
+
+        """
+        with self._server_wrapper.auto_download(path) as export_path:
+            with wrap_grpc_errors():
+                self._get_stub().ExportToCDB(  # type: ignore
+                    section_cut_pb2.ExportToCDBRequest(
+                        resource_path=self._resource_path,
+                        path=export_path,
+                        export_type=typing.cast(
+                            typing.Any, section_cut_cdb_export_type_to_pb(export_type)
+                        ),
+                    )
+                )
+
+    def export_becas_input(
+        self,
+        path: _PATH,
+        *,
+        export_strength_limits: bool = True,
+    ) -> None:
+        """Export the section cut to BECAS input files.
+
+        Parameters
+        ----------
+        path :
+            Path to the directory where the input files are saved.
+        export_strength_limits :
+            Determines whether strength limits are exported to the
+            BECAS input files.
+
+        """
+        # The 'auto_download' context manager cannot be directly used here
+        # because the export path is not a file but a directory. The BECAS
+        # export produces multiple files, which we all need to download.
+        # Currently (May '25), this is the only export that produces multiple
+        # files at once. If there are more, we should either extend 'auto_download',
+        # or create a new context manager for this purpose.
+        export_path = pathlib.Path(
+            self._server_wrapper.filetransfer_handler.to_export_path(path, is_directory=True)
+        )
+        expected_filenames = ["E2D.in", "EMAT.in", "MATPROPS.in", "N2D.in"]
+        if export_strength_limits:
+            expected_filenames.append("FAILMAT.in")
+
+        with wrap_grpc_errors():
+            self._get_stub().ExportToBECAS(  # type: ignore
+                section_cut_pb2.ExportToBECASRequest(
+                    resource_path=self._resource_path,
+                    path=path_to_str_checked(export_path),
+                    export_strength_limits=export_strength_limits,
+                )
+            )
+        for filename in expected_filenames:
+            self._server_wrapper.filetransfer_handler.download_file_if_autotransfer(
+                export_path / filename, pathlib.Path(path) / filename
+            )

tests/unittests/test_section_cut.py

@@ -21,6 +21,9 @@
 # SOFTWARE.
 
 import math
+import os
+import pathlib
+import tempfile
 
 from packaging.version import parse as parse_version
 import pytest
@@ -109,3 +112,100 @@ def object_properties(parent_object):
                 ("locked", True),
             ],
         )
+
+
+@pytest.mark.parametrize("export_type", ["mesh_only", "solid_model"])
+def test_section_cut_export(parent_object, export_type):
+    """Test the export to CDB. Only the presence of the file is checked."""
+
+    model = parent_object
+    section_cut = model.create_section_cut()
+    section_cut.normal = (1, 0, 0)
+    section_cut.extrusion_type = ExtrusionType.SURFACE_NORMAL
+    section_cut.section_cut_type = SectionCutType.ANALYSIS_PLY_WISE
+    model.update()
+
+    with tempfile.TemporaryDirectory() as tempdir:
+        path = pathlib.Path(tempdir) / "section_cut.cdb"
+        section_cut.export(path=path, export_type=export_type)
+        assert path.exists()
+        assert path.is_file()
+        assert os.stat(path).st_size > 0
+
+
+def test_section_cut_export_outofdate(parent_object):
+    """Test that the CDB export fails for an out-of-date section cut."""
+
+    model = parent_object
+    section_cut = model.create_section_cut()
+    section_cut.normal = (1, 0, 0)
+    section_cut.extrusion_type = ExtrusionType.SURFACE_NORMAL
+    section_cut.section_cut_type = SectionCutType.ANALYSIS_PLY_WISE
+
+    with tempfile.TemporaryDirectory() as tempdir:
+        path = pathlib.Path(tempdir) / "section_cut.cdb"
+        with pytest.raises(RuntimeError):
+            # without update, the export should fail
+            section_cut.export(path=path)
+
+        # after update, the export should work
+        model.update()
+        section_cut.export(path=path)
+
+
+@pytest.fixture(params=[True, False])
+def use_pathlib_path(request):
+    return request.param
+
+
+@pytest.fixture(params=[True, False])
+def export_strength_limits(request):
+    return request.param
+
+
+def test_section_cut_becas_export(parent_object, export_strength_limits, use_pathlib_path):
+    """Test the export to CDB. Only the presence of the file is checked."""
+
+    model = parent_object
+    section_cut = model.create_section_cut()
+    section_cut.normal = (1, 0, 0)
+    section_cut.extrusion_type = ExtrusionType.SURFACE_NORMAL
+    section_cut.section_cut_type = SectionCutType.ANALYSIS_PLY_WISE
+    model.update()
+
+    expected_filename = ["E2D.in", "EMAT.in", "MATPROPS.in", "N2D.in"]
+    if export_strength_limits:
+        expected_filename.append("FAILMAT.in")
+
+    with tempfile.TemporaryDirectory() as tempdir:
+        tempdir_path = pathlib.Path(tempdir)
+        if use_pathlib_path:
+            section_cut.export_becas_input(
+                path=tempdir_path, export_strength_limits=export_strength_limits
+            )
+        else:
+            section_cut.export_becas_input(
+                path=tempdir, export_strength_limits=export_strength_limits
+            )
+
+        assert sorted(tempdir_path.iterdir()) == sorted(
+            [tempdir_path / filename for filename in expected_filename]
+        )
+
+
+def test_section_cut_becas_export_outofdate(parent_object):
+    """Test that the BECAS export fails for an out-of-date section cut."""
+
+    model = parent_object
+    section_cut = model.create_section_cut()
+    section_cut.normal = (1, 0, 0)
+    section_cut.extrusion_type = ExtrusionType.SURFACE_NORMAL
+    section_cut.section_cut_type = SectionCutType.ANALYSIS_PLY_WISE
+
+    with tempfile.TemporaryDirectory() as tempdir:
+        with pytest.raises(RuntimeError):
+            # without update, the export should fail
+            section_cut.export_becas_input(path=tempdir)
+        # after update, the export should work
+        model.update()
+        section_cut.export_becas_input(path=tempdir)