Feat/material names into v0.3 (#355)

* Feat/exposure of material names (#353)

* add `material_names` as property to the CompositeModel which returns a dict[dpf mat id, material name].

* add unit test

* apply pre-commit patch

* Update documentation

---------

Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com>

* Fix broken link, and port changes from 0.3.1 back to develop (#350)

# Conflicts:
#	doc/source/index.rst

---------

Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com>

README.rst

@@ -34,13 +34,13 @@ PyDPF Composites
 
 
 PyDPF Composites enables the post-processing of composite structures based on
-`Ansys DPF`_ and the DPF Composites plugin. It implements classes on top of
-DPF Composites operators and data accessors for short fiber and layered
-composites (layered shell and solid elements). This module can be used to
-postprocess fiber reinforced plastics and layered composites, and to implement
-custom failure criteria and computation. For information demonstrating
-the behavior and usage of PyDPF Composites, see `Examples`_ in the DPF Composite
-documentation.
+`Ansys DPF`_ and the DPF Composites plugin. So it is a Python wrapper which
+implements classes on top of DPF Composites operators and data accessors for
+short fiber and layered composites (layered shell and solid elements). This
+module can be used to postprocess fiber reinforced plastics and layered
+composites, and to implement custom failure criteria and computation. For
+information demonstrating the behavior and usage of PyDPF Composites,
+see `Examples`_ in the DPF Composite documentation.
 
 .. START_MARKER_FOR_SPHINX_DOCS
 
@@ -195,6 +195,6 @@ released versions.
 .. _pytest: https://docs.pytest.org/en/stable/
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
 .. _tox: https://tox.wiki/
-.. _Examples: https://composites.dpf.docs.pyansys.com/dev/examples/index.html
+.. _Examples: https://composites.dpf.docs.pyansys.com/version/stable/examples/index.html
 .. _Getting The DPF Server Docker Image: https://composites.dpf.docs.pyansys.com/version/stable/intro.html#getting-the-dpf-server-docker-image
 .. _Ansys DPF: https://dpf.docs.pyansys.com/version/stable/

doc/source/index.rst

@@ -74,4 +74,4 @@ Limitations
 .. _Ansys Workbench: https://download.ansys.com/Current%20Release
 .. _Import of Legacy Mechanical APDL Composite Models: https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v231/en/acp_ug/acp_import_legacy_APDL_comp.html
 .. _Compatibility: https://dpf.docs.pyansys.com/version/stable/getting_started/compatibility.html
-.. _Ansys DPF: https://dpf.docs.pyansys.com/version/stable/
+.. _Ansys DPF: https://dpf.docs.pyansys.com/version/stable/

examples/006_filter_composite_data_example.py

@@ -27,7 +27,7 @@
 from ansys.dpf.composites.layup_info import (
     AnalysisPlyInfoProvider,
     get_all_analysis_ply_names,
-    get_dpf_material_id_by_analyis_ply_map,
+    get_dpf_material_id_by_analysis_ply_map,
 )
 from ansys.dpf.composites.select_indices import (
     get_selected_indices,
@@ -123,7 +123,7 @@
 # Note: It is not possible to get a DPF material ID for a
 # given material name. It is only possible to get a DPF material
 # ID from an analysis ply.
-material_map = get_dpf_material_id_by_analyis_ply_map(
+material_map = get_dpf_material_id_by_analysis_ply_map(
     composite_model.get_mesh(), data_source_or_streams_provider=composite_model.data_sources.rst
 )
 ud_material_id = material_map["P1L1__ud_patch ns1"]

src/ansys/dpf/composites/_composite_model_impl.py

@@ -144,6 +144,34 @@ def material_operators(self) -> MaterialOperators:
         """Material operators."""
         return self._material_operators
 
+    @property
+    def material_names(self) -> Dict[str, int]:
+        """
+        Material name to DPF material ID map.
+
+        This property can be used to filter analysis plies
+        or element layers.
+        """
+        try:
+            helper_op = dpf.Operator("composite::materials_container_helper")
+        except Exception as exc:
+            raise RuntimeError(
+                f"Operator composite::materials_container_helper doesn't exist. "
+                f"This could be because the server version is 2024 R1-pre0. The "
+                f"latest preview or the unified installer can be used instead. "
+                f"Error: {exc}"
+            ) from exc
+
+        helper_op.inputs.materials_container(self._material_operators.material_provider.outputs)
+        string_field = helper_op.outputs.material_names()
+        material_ids = string_field.scoping.ids
+
+        names = {}
+        for mat_id in material_ids:
+            names[string_field.data[string_field.scoping.index(mat_id)]] = mat_id
+
+        return names
+
     @_deprecated_composite_definition_label
     def get_mesh(self, composite_definition_label: Optional[str] = None) -> MeshedRegion:
         """Get the underlying DPF meshed region.

src/ansys/dpf/composites/_composite_model_impl_2023r2.py

@@ -143,7 +143,7 @@ def __init__(
             warn(
                 "The post-processing of composite models with multiple lay-up"
                 " definitions (assemblies) is deprecated with DPF servers older than 7.0"
-                " (2024 R1). Please use DPF server 7.0 or later.",
+                " (2024 R1). DPF server 7.0 or later should be used instead.",
                 DeprecationWarning,
                 stacklevel=2,
             )
@@ -193,6 +193,15 @@ def material_operators(self) -> MaterialOperators:
         """Material operators."""
         return self._material_operators
 
+    @property
+    def material_names(self) -> Dict[str, int]:
+        """Get material name to DPF material ID map."""
+        raise NotImplementedError(
+            "material_names is not implemented"
+            " for this version of DPF. DPF server 7.0 (2024 R1)"
+            " or later should be used instead."
+        )
+
     def get_layup_operator(self, composite_definition_label: Optional[str] = None) -> Operator:
         """Get the lay-up operator.
 
@@ -550,8 +559,9 @@ def get_all_layered_element_ids(self) -> Sequence[int]:
         """Get all layered element IDs."""
         raise NotImplementedError(
             "get_all_layered_element_ids is not implemented"
-            " for this version of DPF. Please upgrade to 7.0 (2024 R1)"
-            " or later. Use get_all_layered_element_ids_for_composite_definition_label"
+            " for this version of DPF. DPF server 7.0 (2024 R1)"
+            " or later should be used instead. Use "
+            "get_all_layered_element_ids_for_composite_definition_label"
             " instead."
         )
 

src/ansys/dpf/composites/composite_model.py

@@ -106,6 +106,11 @@ def material_operators(self) -> MaterialOperators:
         """Material operators."""
         return self._implementation.material_operators
 
+    @property
+    def material_names(self) -> Dict[str, int]:
+        """Get material name to DPF material ID map."""
+        return self._implementation.material_names
+
     def get_mesh(self, composite_definition_label: Optional[str] = None) -> MeshedRegion:
         """Get the underlying DPF meshed region.
 

src/ansys/dpf/composites/layup_info/__init__.py

@@ -11,6 +11,7 @@
     get_all_analysis_ply_names,
     get_analysis_ply_index_to_name_map,
     get_dpf_material_id_by_analyis_ply_map,
+    get_dpf_material_id_by_analysis_ply_map,
     get_element_info_provider,
 )
 
@@ -25,6 +26,7 @@
     "get_all_analysis_ply_names",
     "get_analysis_ply_index_to_name_map",
     "get_dpf_material_id_by_analyis_ply_map",
+    "get_dpf_material_id_by_analysis_ply_map",
     "get_element_info_provider",
     "material_properties",
     "material_operators",

src/ansys/dpf/composites/layup_info/_layup_info.py

@@ -2,6 +2,7 @@
 
 from dataclasses import dataclass
 from typing import Any, Collection, Dict, List, Optional, Sequence, Union, cast
+from warnings import warn
 
 import ansys.dpf.core as dpf
 from ansys.dpf.core import DataSources, MeshedRegion, Operator, PropertyField
@@ -200,6 +201,38 @@ def get_dpf_material_id_by_analyis_ply_map(
     data_source_or_streams_provider:
         DPF data source with rst file or streams_provider. The streams provider is
         available from :attr:`.CompositeModel.core_model` (under metadata.streams_provider).
+
+    Note
+    ----
+    Cache the output because the computation can be performance-critical.
+    """
+    warn(
+        "`get_dpf_material_id_by_analyis_ply_map` is deprecated. "
+        " and was replaced by `get_dpf_material_id_by_analysis_ply_map`.",
+        category=DeprecationWarning,
+        stacklevel=2,
+    )
+    return get_dpf_material_id_by_analysis_ply_map(mesh, data_source_or_streams_provider)
+
+
+def get_dpf_material_id_by_analysis_ply_map(
+    mesh: MeshedRegion,
+    data_source_or_streams_provider: Union[DataSources, Operator],
+) -> Dict[str, np.int64]:
+    """Get the dictionary that maps analysis ply names to DPF material IDs.
+
+    Parameters
+    ----------
+    mesh
+        DPF Meshed region enriched with lay-up information
+    data_source_or_streams_provider:
+        DPF data source with RST file or streams provider. The streams provider is
+        available from the :attr:`.CompositeModel.core_model` attribute
+        (under ``metadata.streams_provider``).
+
+    Note
+    ----
+    Cache the output because the computation can be performance-critical.
     """
     # Note: The stream_provider_or_data_source is not strictly needed for this workflow
     # We just need it because get_element_info_provider provider needs it (which needs

src/ansys/dpf/composites/unit_system.py

@@ -41,9 +41,8 @@ def get_unit_system(
         if default_unit_system is None:
             raise RuntimeError(
                 "The result file does not specify a unit system."
-                " Please define a default unit system. "
-                "A default unit system can be passed when "
-                "creating a CompositeModel."
+                " A default unit system must be defined.. "
+                "It can be passed when creating a CompositeModel."
             )
         return default_unit_system
     else:

tests/composite_model_test.py

@@ -14,7 +14,7 @@
 from ansys.dpf.composites.layup_info import LayerProperty, get_analysis_ply_index_to_name_map
 from ansys.dpf.composites.layup_info.material_properties import MaterialProperty
 from ansys.dpf.composites.result_definition import FailureMeasureEnum
-from ansys.dpf.composites.server_helpers import version_older_than
+from ansys.dpf.composites.server_helpers import version_equal_or_later, version_older_than
 
 from .helper import Timer
 
@@ -83,6 +83,18 @@ def test_basic_functionality_of_composite_model(dpf_server, data_files, distribu
 
     assert [ply["id"] for ply in sampling_point.analysis_plies] == analysis_ply_ids
 
+    if version_equal_or_later(dpf_server, "7.0"):
+        ref_material_names = [
+            "Epoxy Carbon UD (230 GPa) Prepreg",
+            "Epoxy Carbon Woven (230 GPa) Wet",
+            "Honeycomb",
+            "Structural Steel",
+        ]
+        mat_names = composite_model.material_names
+        assert len(mat_names) == len(ref_material_names)
+        for mat_name in ref_material_names:
+            assert mat_name in mat_names.keys()
+
     timer.add("After getting properties")
 
     timer.summary()

tests/material_properties_test.py

@@ -7,7 +7,7 @@
     AnalysisPlyInfoProvider,
     get_all_analysis_ply_names,
     get_analysis_ply_index_to_name_map,
-    get_dpf_material_id_by_analyis_ply_map,
+    get_dpf_material_id_by_analysis_ply_map,
     get_element_info_provider,
 )
 from ansys.dpf.composites.layup_info.material_operators import get_material_operators
@@ -26,7 +26,7 @@ def test_get_analysis_ply_material_id_map(dpf_server):
     files = get_basic_shell_files()
     setup_result = setup_operators(dpf_server, files)
 
-    material_map = get_dpf_material_id_by_analyis_ply_map(
+    material_map = get_dpf_material_id_by_analysis_ply_map(
         setup_result.mesh, setup_result.streams_provider
     )