Jvonrick/more doc improvements (#113)

* More doc improvements

* Rename criteria to criterion

* Fix sampling point test

doc/source/api/composite_model.rst

@@ -13,13 +13,16 @@ Composite Model
       CompositeScope
       ContinuousFiberCompositesFiles
       FailureMeasure
+      FailureResult
       MaterialOperators
       ResultDefinition
       SamplingPoint
       LayupProperty
       FailureOutput
+      SamplingPointFigure
       Sym3x3TensorComponent
       LayerProperty
 
 
 
+

doc/source/intro.rst

@@ -12,20 +12,20 @@ Since the module is not yet public, please install from github:
 
     pip install git+https://github.com/pyansys/pydpf-composites.git
 
-Whenever you call the function connect_to_or_start_server you have to pass the location of the 231 installer
+Whenever you call the function connect_to_or_start_server you have to pass the location of the 23.1 installer
 with the ansys_path argument:
 
 .. code::
 
     connect_to_or_start_server(ansys_path=os.environ["AWP_ROOT231"])
 
-Otherwise, the dpf server will be started with the latest installer it finds, which probably is 232.
+Otherwise, the dpf server will be started with the latest installer it finds, which probably is 23.2.
 
 
 Installation
 ^^^^^^^^^^^^
 
-ansys-dpf-composites supports Ansys version 23.1 and later. Make sure you have licensed copy of Ansys installed.
+ansys-dpf-composites supports Ansys version 2023 R1 and later. Make sure you have licensed copy of Ansys installed.
 Install the ansys-dpf-composites module from pip:
 
 .. code::
@@ -97,11 +97,10 @@ detailed output for a sampling point.
     # Show sampling point for element with id/label 1
     element_id = 1
     sampling_point = composite_model.get_sampling_point(
-        combined_criteria=combined_failure_criterion, element_id=element_id
+        combined_criterion=combined_failure_criterion, element_id=element_id
     )
 
-    fig, axes = sampling_point.get_result_plots()
-    fig.show()
+    sampling_point.get_result_plots()
 
 
 .. image:: _static/boat_irf.png

examples/1_failure_operator_example.py

@@ -63,15 +63,15 @@
 # %%
 # Failure evaluation for the entire model
 output_all_elements = composite_model.evaluate_failure_criteria(
-    combined_criteria=combined_fc,
+    combined_criterion=combined_fc,
 )
 irf_field = output_all_elements.get_field({"failure_label": FailureOutput.failure_value})
 irf_field.plot()
 
 # %%
 # Scope failure evaluation to a certain element scope
 output_two_elements = composite_model.evaluate_failure_criteria(
-    combined_criteria=combined_fc,
+    combined_criterion=combined_fc,
     composite_scope=CompositeScope(elements=[1, 3]),
 )
 irf_field = output_two_elements.get_field({"failure_label": FailureOutput.failure_value})
@@ -80,7 +80,7 @@
 # %%
 # Scope by plies
 output_woven_plies = composite_model.evaluate_failure_criteria(
-    combined_criteria=combined_fc,
+    combined_criterion=combined_fc,
     composite_scope=CompositeScope(plies=["P1L1__ud_patch ns1"]),
 )
 irf_field = output_woven_plies.get_field({"failure_label": FailureOutput.failure_value})

examples/2_sampling_point_example.py

@@ -58,25 +58,25 @@
 
 # %%
 # Create a sampling point
-sampling_point = composite_model.get_sampling_point(combined_criteria=combined_fc, element_id=3)
+sampling_point = composite_model.get_sampling_point(combined_criterion=combined_fc, element_id=3)
 
 # %%
 # Plot Results
 # """"""""""""
 #
 # Use pre-configured plots. See also :class:`~ansys.dpf.composites.SamplingPoint.get_result_plots`.
-fig, axes = sampling_point.get_result_plots(
+sampling_point_plot = sampling_point.get_result_plots(
     strain_components=[],  # do not plot strains
     core_scale_factor=0.1,
     spots=[Spot.bottom, Spot.top],
     show_failure_modes=True,
 )
-fig.set_figheight(8)
-fig.set_figwidth(12)
+sampling_point_plot.figure.set_figheight(8)
+sampling_point_plot.figure.set_figwidth(12)
 
 # %%
 # Plot polar properties
-fig, polar_plot = sampling_point.get_polar_plot(["E1", "G12"])
+sampling_point_plot = sampling_point.get_polar_plot(["E1", "G12"])
 
 # %%
 # Custom plots:
@@ -131,11 +131,11 @@
 #
 # The element id of the sampling point can be easily changed.
 sampling_point.element_id = 4
-fig, axes = sampling_point.get_result_plots(
+sampling_point_plot = sampling_point.get_result_plots(
     strain_components=[],  # do not plot strains
     core_scale_factor=0.1,
     spots=[Spot.bottom, Spot.top],
     show_failure_modes=True,
 )
-fig.set_figheight(8)
-fig.set_figwidth(12)
+sampling_point_plot.figure.set_figheight(8)
+sampling_point_plot.figure.set_figwidth(12)

examples/8_assembly_example.py

@@ -43,7 +43,7 @@
 # %%
 # Plot the max IRF per element
 #
-output_all_elements = composite_model.evaluate_failure_criteria(combined_criteria=combined_fc)
+output_all_elements = composite_model.evaluate_failure_criteria(combined_criterion=combined_fc)
 irf_field = output_all_elements.get_field({"failure_label": FailureOutput.failure_value})
 irf_field.plot()
 

src/ansys/dpf/composites/__init__.py

@@ -40,7 +40,7 @@
 )
 from .material_setup import MaterialOperators
 from .result_definition import ResultDefinition
-from .sampling_point import SamplingPoint
+from .sampling_point import FailureResult, SamplingPoint, SamplingPointFigure
 from .select_indices import (
     get_selected_indices,
     get_selected_indices_by_analysis_ply,
@@ -79,4 +79,6 @@
     "FailureOutput",
     "Sym3x3TensorComponent",
     "LayerProperty",
+    "FailureResult",
+    "SamplingPointFigure",
 ]

src/ansys/dpf/composites/composite_model.py

@@ -176,7 +176,7 @@ def get_layup_operator(self, composite_definition_label: Optional[str] = None) -
 
     def evaluate_failure_criteria(
         self,
-        combined_criteria: CombinedFailureCriterion,
+        combined_criterion: CombinedFailureCriterion,
         composite_scope: Optional[CompositeScope] = None,
         measure: FailureMeasure = FailureMeasure.inverse_reserve_factor,
         write_data_for_full_element_scope: bool = True,
@@ -189,7 +189,7 @@ def evaluate_failure_criteria(
 
         Parameters
         ----------
-        combined_criteria:
+        combined_criterion:
             Combined failure criterion to evaluate
         composite_scope:
             Composite scope on which the failure criteria are evaluated. If
@@ -239,7 +239,7 @@ def evaluate_failure_criteria(
             name="combined failure criteria",
             rst_file=self._composite_files.rst,
             material_file=self._composite_files.engineering_data,
-            combined_failure_criterion=combined_criteria,
+            combined_failure_criterion=combined_criterion,
             composite_scopes=scopes,
             time=time_in,
             measure=measure.value,
@@ -255,7 +255,7 @@ def evaluate_failure_criteria(
 
     def get_sampling_point(
         self,
-        combined_criteria: CombinedFailureCriterion,
+        combined_criterion: CombinedFailureCriterion,
         element_id: int,
         time: Optional[float] = None,
         composite_definition_label: Optional[str] = None,
@@ -264,7 +264,7 @@ def get_sampling_point(
 
         Parameters
         ----------
-        combined_criteria:
+        combined_criterion:
             Combined failure criterion to evaluate
         element_id:
             Element Id/Label of the sampling point
@@ -304,7 +304,7 @@ def get_sampling_point(
             name="combined failure criteria",
             rst_file=self._composite_files.rst,
             material_file=self._composite_files.engineering_data,
-            combined_failure_criterion=combined_criteria,
+            combined_failure_criterion=combined_criterion,
             time=time_in,
             composite_scopes=[scope],
         )

src/ansys/dpf/composites/connect_to_or_start_server.py

@@ -2,7 +2,7 @@
 import os
 from typing import Any, Callable, Dict, Optional, Union
 
-import ansys.dpf.core as dpf
+from ansys.dpf.core import connect_to_server, server, start_local_server
 
 from ansys.dpf.composites.load_plugin import load_composites_plugin
 
@@ -25,7 +25,7 @@ def _try_until_timeout(fun: Callable[[], Any], error_message: str, timeout: int
     raise TimeoutError(f"Timeout is reached: {error_message}")
 
 
-def _wait_until_server_is_up(server: dpf.server) -> Any:
+def _wait_until_server_is_up(server: server) -> Any:
     # Small hack to check if the server is up
     # The dpf server should check this in connect_to_server but that's currently not the case
     # https://github.com/pyansys/pydpf-core/issues/414
@@ -35,21 +35,24 @@ def _wait_until_server_is_up(server: dpf.server) -> Any:
 
 def connect_to_or_start_server(
     port: Optional[int] = None, ip: Optional[str] = None, ansys_path: Optional[str] = None
-) -> dpf.server:
+) -> Any:
     r"""Connect to or start a dpf server with the composites plugin loaded.
 
     Note: If port or ip are set, this function will try to
     connect to a server and the ansys_path is ignored.
-    I no arguments are passed a local server from the latest available installer
+    If no arguments are passed a local server from the latest available installer
     is started.
 
     Parameters
     ----------
     port:
     ip:
     ansys_path:
-        Ansys root path, for example C:\Program Files\ANSYS Inc\v231.
+        Ansys root path, for example C:\\Program Files\\ANSYS Inc\\v231.
         Ignored if either port or ip are set.
+    Returns
+    -------
+        dpf server
     """
     port_in_env = os.environ.get("PYDPF_COMPOSITES_DOCKER_CONTAINER_PORT")
     if port_in_env is not None:
@@ -62,9 +65,9 @@ def connect_to_or_start_server(
         connect_kwargs["ip"] = ip
 
     if len(list(connect_kwargs.keys())) > 0:
-        server = dpf.server.connect_to_server(**connect_kwargs)
+        server = connect_to_server(**connect_kwargs)
     else:
-        server = dpf.server.start_local_server(ansys_path=ansys_path)
+        server = start_local_server(ansys_path=ansys_path)
 
     server.check_version(
         "5.0",

src/ansys/dpf/composites/failure_criteria/puck.py

@@ -111,10 +111,10 @@ def _get_wf_pd(self) -> float:
     def _set_wf_pd(self, value: float) -> None:
         self._wf_pd = value
 
-    def _get_cfps(self) -> float:
+    def _get_cfps(self) -> bool:
         return self._cfps
 
-    def _set_cfps(self, value: float) -> None:
+    def _set_cfps(self, value: bool) -> None:
         self._cfps = value
 
     def _get_s(self) -> float:

src/ansys/dpf/composites/sampling_point.py

@@ -1,6 +1,5 @@
 """Wrapper for the Sampling Point Operator."""
-
-from collections import namedtuple
+import dataclasses
 import hashlib
 import json
 from typing import Any, Collection, Dict, List, Sequence, Union, cast
@@ -17,8 +16,23 @@
 from .load_plugin import load_composites_plugin
 from .result_definition import ResultDefinition
 
-SamplingPointFigure = namedtuple("SamplingPointFigure", ("figure", "axes"))
-FailureResult = namedtuple("FailureResult", "mode irf rf mos")
+
+@dataclasses.dataclass(frozen=True)
+class SamplingPointFigure:
+    """Sampling Point Figure and Axes."""
+
+    figure: Any
+    axes: Any
+
+
+@dataclasses.dataclass(frozen=True)
+class FailureResult:
+    """Components of a failure result."""
+
+    mode: str
+    irf: float
+    rf: float
+    mos: float
 
 
 def _check_result_definition_has_single_scope(result_definition: ResultDefinition) -> None:
@@ -474,7 +488,9 @@ def get_ply_wise_critical_failures(self) -> List[FailureResult]:
 
         return result
 
-    def get_polar_plot(self, components: Sequence[str] = ("E1", "E2", "G12")) -> Any:
+    def get_polar_plot(
+        self, components: Sequence[str] = ("E1", "E2", "G12")
+    ) -> SamplingPointFigure:
         """Create a standard polar plot to visualize the polar properties of the laminate.
 
         Parameters
@@ -599,7 +615,7 @@ def get_result_plots(
         create_laminate_plot: bool = True,
         core_scale_factor: float = 1.0,
         spots: Collection[Spot] = (Spot.bottom, Spot.middle, Spot.top),
-    ) -> Any:
+    ) -> SamplingPointFigure:
         """Generate a figure with a grid of axes (plot) for each selected result entity.
 
         Parameters

tests/composite_model_test.py

@@ -91,7 +91,7 @@ def test_basic_functionality_of_composite_model(dpf_server):
     )
 
     failure_output = composite_model.evaluate_failure_criteria(
-        combined_criteria=combined_failure_criterion,
+        combined_criterion=combined_failure_criterion,
         composite_scope=CompositeScope(),
     )
     irf_field = failure_output.get_field({"failure_label": FailureOutput.failure_value})
@@ -133,7 +133,7 @@ def test_basic_functionality_of_composite_model(dpf_server):
     assert composite_model.get_mesh() is not None
     assert composite_model.data_sources is not None
     sampling_point = composite_model.get_sampling_point(
-        combined_criteria=combined_failure_criterion, element_id=1
+        combined_criterion=combined_failure_criterion, element_id=1
     )
 
     assert [ply["id"] for ply in sampling_point.analysis_plies] == analysis_ply_ids
@@ -164,7 +164,7 @@ def test_assembly_model(dpf_server):
     )
 
     failure_output = composite_model.evaluate_failure_criteria(
-        combined_criteria=combined_failure_criterion,
+        combined_criterion=combined_failure_criterion,
         composite_scope=CompositeScope(),
     )
     timer.add("After get failure output")
@@ -259,7 +259,7 @@ def test_assembly_model(dpf_server):
     assert composite_model.get_mesh(solid_label) is not None
     assert composite_model.data_sources is not None
     sampling_point = composite_model.get_sampling_point(
-        combined_criteria=combined_failure_criterion,
+        combined_criterion=combined_failure_criterion,
         element_id=shell_element_id,
         composite_definition_label=shell_label,
     )
@@ -305,7 +305,7 @@ def test_failure_measures(dpf_server):
 
     for v in FailureMeasure:
         failure_output = composite_model.evaluate_failure_criteria(
-            combined_criteria=combined_failure_criterion,
+            combined_criterion=combined_failure_criterion,
             composite_scope=CompositeScope(),
             measure=v,
         )

tests/getting_started_test.py

@@ -52,13 +52,13 @@ def test_getting_started(dpf_server: dpf.server):
 
     irf_field = failure_result.get_field({"failure_label": FailureOutput.failure_value})
     # Commented because it blocks execution. Uncomment this
-    # line when you copy this code the the getting started example
+    # line when you copy this code the getting started example
     # irf_field.plot()
 
     # Show sampling point for element with id/label 1
     element_id = 1
     sampling_point = composite_model.get_sampling_point(
-        combined_criteria=combined_failure_criterion, element_id=element_id
+        combined_criterion=combined_failure_criterion, element_id=element_id
     )
 
-    fig, axes = sampling_point.get_result_plots()
+    sampling_point.get_result_plots()