feat: use Homogeneity enum. Rework documentation

Author: anshlachamb

src/ansys/dpf/core/field.py

@@ -620,15 +620,15 @@ def unit(self):
     def unit(self, value):
         """Change the unit for the field.
 
-        If the value is a single string, then it will be interpreted to a physical meaning (homogeneity).
+        A single string is interpreted as a known physical unit with an associated homogeneity.
 
-        If the value is a tuple, then it must contain an homogeneity and a string.
-            If homogeneity is "dimensionless", then the unit string is kept as is.
-            Otherwise, homogeneity is ignored, and unit string is interpreted to a physical meaning.
+        A tuple of two strings is interpreted as a homogeneity and a unit name.
+            If the homogeneity is Homogeneity.dimensionless, then the unit string is kept as a name.
+            Otherwise, the homogeneity is ignored, and the unit string is interpreted as a known physical unit with an associated homogeneity.
 
         Parameters
         ----------
-        value : str | tuple(str, str)
+        value : str | tuple(Homogeneity, str)
             Units for the field.
 
         Examples
@@ -645,8 +645,9 @@ def unit(self, value):
         Named dimensionless unit.
 
         >>> from ansys.dpf import core as dpf
+        >>> from ansys.dpf.core.available_result import Homogeneity
         >>> my_field = dpf.Field(10)
-        >>> my_field.unit = ("dimensionless", "dollars")
+        >>> my_field.unit = (Homogeneity.dimensionless, "dollars")
         >>> print(my_field.unit)
         'dollars'
 

src/ansys/dpf/core/field_definition.py

@@ -22,10 +22,12 @@
 
 """FieldDefinition."""
 
+from argparse import ArgumentError
 import traceback
 import warnings
 
 from ansys.dpf.core import server as server_module
+from ansys.dpf.core.available_result import Homogeneity
 from ansys.dpf.core.check_version import version_requires
 from ansys.dpf.core.common import natures, shell_layers
 from ansys.dpf.core.dimensionality import Dimensionality
@@ -206,15 +208,21 @@ def is_of_quantity_type(self, quantity_type):
     @unit.setter
     def unit(self, value):
         # setter with explicit homogeneity: homogeneity is taken into account if it is dimensionless
-        if isinstance(value, tuple):
-            if value[0] == "dimensionless":
-                # 117 corresponds to dimensionless
-                self._api.csfield_definition_set_unit(self, value[1], None, 117, 0, 0)
-            else:
-                self._api.csfield_definition_set_unit(self, value[1], None, 0, 0, 0)
+        if (
+            isinstance(value, tuple)
+            and len(value) == 2
+            and isinstance(value[0], Homogeneity)
+            and isinstance(value[1], str)
+        ):
+            # csfield_definition_set_unit will ignore the homogeneity if it is not dimensionless
+            self._api.csfield_definition_set_unit(self, value[1], None, value[0].value, 0, 0)
         # standard unit setter, using string interpreter
-        else:
+        elif isinstance(value, str):
             self._api.csfield_definition_set_unit(self, value, None, 0, 0, 0)
+        else:
+            raise ArgumentError(
+                None, message="Unit setter supports either string or tuple(Homogeneity, str)"
+            )
 
     @location.setter
     def location(self, value):

tests/test_field.py

@@ -20,6 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+from argparse import ArgumentError
 import copy
 import gc
 
@@ -29,8 +30,10 @@
 from ansys import dpf
 from ansys.dpf import core
 from ansys.dpf.core import FieldDefinition, operators as ops
+from ansys.dpf.core.available_result import Homogeneity
 from ansys.dpf.core.check_version import server_meet_version
 from ansys.dpf.core.common import locations, shell_layers
+from ansys.dpf.gate.errors import DPFServerException
 import conftest
 from conftest import (
     SERVERS_VERSION_GREATER_THAN_OR_EQUAL_TO_8_0,
@@ -1429,11 +1432,18 @@ def test_deep_copy_big_field_remote(server_type, server_type_remote_process):
 def test_set_units():
     data = np.random.random(100)
     field = dpf.core.field_from_array(data)
+    # use string setter with recognized string
     field.unit = "m"
     assert field.unit == "m"
 
-    field.unit = ("dimensionless", "sones")
+    # use tuple(Homogeneity, string) setter
+    field.unit = (Homogeneity.dimensionless, "sones")
     assert field.unit == "sones"
 
-    with pytest.raises(Exception):
+    # use unrecognized string
+    with pytest.raises(DPFServerException):
         field.unit = "sones"
+
+    # use wrong type of arguments
+    with pytest.raises(ArgumentError):
+        field.unit = 1.0