Feature: allow setting named dimensionless units in a Field

src/ansys/dpf/core/field.py

@@ -620,9 +620,15 @@ def unit(self):
     def unit(self, value):
         """Change the unit for the field.
 
+        A single string is interpreted as a known physical unit with an associated homogeneity.
+
+        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
+        value : str | tuple(Homogeneity, str)
             Units for the field.
 
         Examples
@@ -635,6 +641,16 @@ def unit(self, value):
         >>> my_field.unit
         'm'
 
+
+        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 = (Homogeneity.dimensionless, "dollars")
+        >>> print(my_field.unit)
+        'dollars'
+
         """
         fielddef = self.field_definition
         fielddef.unit = value

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
@@ -205,7 +207,22 @@
 
     @unit.setter
     def unit(self, value):
-        self._api.csfield_definition_set_unit(self, value, None, 0, 0, 0)
+        # setter with explicit homogeneity: homogeneity is taken into account if it is dimensionless
+        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
+        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/entry/conftest.py

@@ -71,6 +71,9 @@ def _get_test_files_directory():
         "/tmp/test_files"
     )
 
+SERVERS_VERSION_GREATER_THAN_OR_EQUAL_TO_10_0 = meets_version(
+    get_server_version(core._global_server()), "10.0"
+)
 SERVERS_VERSION_GREATER_THAN_OR_EQUAL_TO_8_1 = meets_version(
     get_server_version(core._global_server()), "8.1"
 )

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,10 +30,16 @@
 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, running_docker
+from conftest import (
+    SERVERS_VERSION_GREATER_THAN_OR_EQUAL_TO_8_0,
+    SERVERS_VERSION_GREATER_THAN_OR_EQUAL_TO_10_0,
+    running_docker,
+)
 
 
 @pytest.fixture()
@@ -1417,3 +1424,26 @@ def test_deep_copy_big_field_remote(server_type, server_type_remote_process):
 
     out = dpf.core.core._deep_copy(field_a, server_type_remote_process)
     assert np.allclose(out.data, data)
+
+
+@pytest.mark.skipif(
+    not SERVERS_VERSION_GREATER_THAN_OR_EQUAL_TO_10_0, reason="Available for servers >=10.0"
+)
+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"
+
+    # use tuple(Homogeneity, string) setter
+    field.unit = (Homogeneity.dimensionless, "sones")
+    assert field.unit == "sones"
+
+    # use unrecognized string
+    with pytest.raises(DPFServerException):
+        field.unit = "sones"
+
+    # use wrong type of arguments
+    with pytest.raises(ArgumentError):
+        field.unit = 1.0