docs: Update to use objects. (#4295)

Updated the user guide replacing strings and low-level data with
object-based alternatives

---------

Co-authored-by: pyansys-ci-bot <[email protected]>

Author: prmukherj

doc/changelog.d/4295.documentation.md

@@ -0,0 +1 @@
+Update to use objects.

doc/source/user_guide/fields/field_data.rst

@@ -44,9 +44,10 @@ To obtain surface vertex coordinates for a given surface, create a
 .. code-block:: python
 
   >>> from ansys.fluent.core import SurfaceDataType, SurfaceFieldDataRequest
+  >>> from ansys.fluent.core.solver import VelocityInlet
 
   >>> vertices_request = SurfaceFieldDataRequest(
-  >>>     surfaces=["inlet"],
+  >>>     surfaces=[VelocityInlet(settings_source=solver_session, name="inlet")],
   >>>     data_types=[SurfaceDataType.Vertices],
   >>> )
   >>> vertices_data = field_data.get_field_data(vertices_request)
@@ -64,8 +65,6 @@ in the ``data_types`` list.
 
 .. code-block:: python
 
-  >>> from ansys.fluent.core.solver import VelocityInlet
-
   >>> faces_normal_and_centroid_request = SurfaceFieldDataRequest(
   >>>     surfaces=[VelocityInlet(settings_source=solver_session, name="inlet")],
   >>>     data_types=[SurfaceDataType.FacesNormal, SurfaceDataType.FacesCentroid],
@@ -127,7 +126,12 @@ To retrieve scalar field data, such as absolute pressure, use ``ScalarFieldDataR
 .. code-block:: python
 
   >>> from ansys.fluent.core import ScalarFieldDataRequest
-  >>> absolute_pressure_request = ScalarFieldDataRequest(field_name="absolute-pressure", surfaces=["inlet"])
+  >>> from ansys.units import VariableCatalog
+
+  >>> absolute_pressure_request = ScalarFieldDataRequest(
+  >>>     field_name=VariableCatalog.ABSOLUTE_PRESSURE,
+  >>>     surfaces=[VelocityInlet(settings_source=solver_session, name="inlet")],
+  >>> )
   >>> absolute_pressure_data = field_data.get_field_data(absolute_pressure_request)
 
   # Shape: (389,) - A single scalar value (e.g., pressure) for each of the 389 vertices.
@@ -144,7 +148,12 @@ To obtain vector field data, such as velocity vectors, use ``VectorFieldDataRequ
 .. code-block:: python
 
   >>> from ansys.fluent.core import VectorFieldDataRequest
-  >>> velocity_request = VectorFieldDataRequest(field_name="velocity", surfaces=["inlet", "inlet1"])
+  >>> from ansys.fluent.core.solver import VelocityInlets
+
+  >>> velocity_request = VectorFieldDataRequest(
+  >>>     field_name=VariableCatalog.VELOCITY,
+  >>>     surfaces=VelocityInlets(settings_source=solver_session),
+  >>> )
   >>> velocity_vector_data = field_data.get_field_data(velocity_request)
   # Shape: (262, 3) - Velocity vectors for 262 faces, each with components (vx, vy, vz) for 'inlet'.
   >>> velocity_vector_data["inlet"].shape
@@ -161,7 +170,7 @@ To obtain pathlines field data, use ``PathlinesFieldDataRequest``:
 
   >>> from ansys.fluent.core import PathlinesFieldDataRequest
   >>> velocity_pathlines_request = PathlinesFieldDataRequest(
-  >>>           field_name="x-velocity",
+  >>>           field_name=VariableCatalog.VELOCITY_X,
   >>>           surfaces=[VelocityInlet(settings_source=solver_session, name="inlet")]
   >>>           flatten_connectivity=True,
   >>>       )
@@ -193,9 +202,17 @@ Add multiple requests using ``add_requests`` and access the data with ``get_resp
 
 .. code-block:: python
 
-  >>> vertices_and_centroid_request = SurfaceFieldDataRequest(surfaces=[1], data_types=[SurfaceDataType.Vertices, SurfaceDataType.FacesCentroid])
-  >>> pressure_request = ScalarFieldDataRequest(surfaces=[1, 2], field_name="pressure", node_value=True, boundary_value=True)
-  >>> velocity_request = VectorFieldDataRequest(surfaces=[1, 2], field_name="velocity")
+  >>> vertices_and_centroid_request = SurfaceFieldDataRequest(
+  >>>     surfaces=[1],
+  >>>     data_types=[SurfaceDataType.Vertices, SurfaceDataType.FacesCentroid],
+  >>> )
+  >>> pressure_request = ScalarFieldDataRequest(
+  >>>     surfaces=[1, 2],
+  >>>     field_name=VariableCatalog.PRESSURE,
+  >>>     node_value=True,
+  >>>     boundary_value=True,
+  >>> )
+  >>> velocity_request = VectorFieldDataRequest(surfaces=[1, 2], field_name=VariableCatalog.VELOCITY)
 
   >>> payload_data = batch.add_requests(vertices_and_centroid_request, pressure_request, velocity_request).get_response()
 

doc/source/user_guide/fields/reduction.rst

@@ -50,9 +50,10 @@ Here's how to set up a simple example:
 .. code-block:: python
 
   >>> from ansys.fluent.core.solver import VelocityInlets
+  >>> from ansys.units import VariableCatalog
   >>> # Compute the minimum of absolute pressure across multiple solvers
   >>> reduction.minimum(
-    ...     expression="AbsolutePressure",
+    ...     expression=VariableCatalog.ABSOLUTE_PRESSURE,
     ...     locations=VelocityInlets(settings_source=solver1) + VelocityInlets(settings_source=solver2),
     ... )
     101343.2241809384
@@ -69,7 +70,7 @@ To use reduction functions within a specific solver instance, initialize the sol
 .. code-block:: python
 
   >>> solver_session.fields.reduction.area_average(
-  ...     expression="AbsolutePressure",
+  ...     expression=VariableCatalog.ABSOLUTE_PRESSURE,
   ...     locations=solver_session.settings.setup.boundary_conditions.velocity_inlet,
   ... )
   101957.2452989816
@@ -78,7 +79,8 @@ For convenience, context-aware reductions are also supported:
 
 .. code-block:: python
 
-  >>> solver_session.fields.reduction.area(locations=["inlet1"])
+  >>> from ansys.fluent.core.solver import VelocityInlet
+  >>> solver_session.fields.reduction.area(locations=[VelocityInlet(settings_source=solver_session, name="inlet1")])
   0.002555675491754098
 
   >>> reduction.area(locations=["inlet1"], ctxt=solver_session)
@@ -248,7 +250,7 @@ Functional:
 .. code-block:: python
 
   >>> reduction.area_average(
-  ...     expression="AbsolutePressure",
+  ...     expression=VariableCatalog.ABSOLUTE_PRESSURE,
   ...     locations=solver_session.setup.boundary_conditions.velocity_inlet,
   ... )
   101957.2452989816
@@ -258,7 +260,7 @@ Object-Oriented:
 .. code-block:: python
 
   >>> solver_session.fields.reduction.area_average(
-  ...     expression="AbsolutePressure",
+  ...     expression=VariableCatalog.ABSOLUTE_PRESSURE,
   ...     locations=solver_session.settings.setup.boundary_conditions.velocity_inlet,
   ... )
   101957.2452989816
@@ -268,7 +270,7 @@ Object-Oriented:
 .. code-block:: python
 
   >>> reduction.minimum(
-  ...     expression="AbsolutePressure",
+  ...     expression=VariableCatalog.ABSOLUTE_PRESSURE,
   ...     locations=solver1.setup.boundary_conditions.pressure_outlet
   ...     + solver2.setup.boundary_conditions.pressure_outlet,
   ... )
@@ -279,7 +281,7 @@ Object-Oriented:
 .. code-block:: python
 
   >>> reduction.minimum(
-  ...     expression="AbsolutePressure",
+  ...     expression=VariableCatalog.ABSOLUTE_PRESSURE,
   ...     locations=VelocityInlets(solver1) + VelocityInlets(solver2),
   ... )
   101343.2241809384
@@ -310,9 +312,9 @@ Object-Oriented:
 .. code-block:: python
 
   >>> reduction.sum(
-  >>>   expression="AbsolutePressure",
+  >>>   expression=VariableCatalog.ABSOLUTE_PRESSURE,
   >>>   locations=solver_session.settings.setup.boundary_conditions.velocity_inlet,
-  >>>   weight="Area"
+  >>>   weight=reduction.weight.AREA
   >>> )
   80349034.56621933
 
@@ -321,10 +323,10 @@ Object-Oriented:
 .. code-block:: python
 
   >>> reduction.sum_if(
-  >>>   expression="AbsolutePressure",
+  >>>   expression=VariableCatalog.ABSOLUTE_PRESSURE,
   >>>   condition="AbsolutePressure > 0[Pa]",
   >>>   locations=solver_session.settings.setup.boundary_conditions.velocity_inlet,
-  >>>   weight="Area"
+  >>>   weight=reduction.weight.AREA
   >>> )
   80349034.56621933
 

doc/source/user_guide/offline/file_session.rst

@@ -31,12 +31,13 @@ Single-phase
   >>>   SurfaceFieldDataRequest,
   >>>   VectorFieldDataRequest,
   >>> )
+  >>> from ansys.units import VariableCatalog
 
   >>> case_file_name = examples.download_file("elbow1.cas.h5", "pyfluent/file_session")
   >>> data_file_name = examples.download_file("elbow1.dat.h5", "pyfluent/file_session")
   >>> file_session = FileSession(case_file_name, data_file_name)
 
-  >>> file_session.fields.field_data.scalar_fields.range("SV_T")
+  >>> file_session.fields.field_data.scalar_fields.range(VariableCatalog.TEMPERATURE)
   [0.0, 313.1515948109515]
   >>> file_session.fields.field_data.surfaces()
   {'wall': {'surface_id': [3],
@@ -73,8 +74,8 @@ Single-phase
    >>>      surfaces=[3, 4],
    >>>      flatten_connectivity=True,
    >>> )
-   >>> solution_variable_temperature_request = ScalarFieldDataRequest(field_name="SV_T", surfaces=[3, 4], node_value=False, boundary_value=False)
-   >>> velocity_request = VectorFieldDataRequest(field_name="velocity", surfaces=[3, 4])
+   >>> solution_variable_temperature_request = ScalarFieldDataRequest(field_name=VariableCatalog.TEMPERATURE, surfaces=[3, 4], node_value=False, boundary_value=False)
+   >>> velocity_request = VectorFieldDataRequest(field_name=VariableCatalog.VELOCITY, surfaces=[3, 4])
    >>> batch.add_requests(vertices_and_faces_connectivity_request, solution_variable_temperature_request, velocity_request)
    >>> data = batch.get_response()
    >>> data.get_field_data(vertices_and_faces_connectivity_request)[3].vertices
@@ -101,11 +102,11 @@ Single-phase
    (3810, 3)
    >>> file_session.fields.field_data.get_field_data(vertices_request)[3][1500][0]
    0.12405861914157867
-   >>> file_session.fields.field_data.get_field_data(ScalarFieldDataRequest(field_name="SV_T", surfaces=["wall"]))["wall"].shape
+   >>> file_session.fields.field_data.get_field_data(ScalarFieldDataRequest(field_name=VariableCatalog.TEMPERATURE, surfaces=["wall"]))["wall"].shape
    (3630,)
-   >>> file_session.fields.field_data.get_field_data(ScalarFieldDataRequest(field_name="SV_T", surfaces=["wall"]))["wall"][1500]
+   >>> file_session.fields.field_data.get_field_data(ScalarFieldDataRequest(field_name=VariableCatalog.TEMPERATURE, surfaces=["wall"]))["wall"][1500]
    293.18071329432047
-   >>> velocity_request = VectorFieldDataRequest(field_name="velocity", surfaces=["symmetry"])
+   >>> velocity_request = VectorFieldDataRequest(field_name=VariableCatalog.VELOCITY, surfaces=["symmetry"])
    >>> file_session.fields.field_data.get_field_data(velocity_request)["symmetry"].shape
    (2018, 3)
    >>> file_session.fields.field_data.get_field_data(velocity_request)["symmetry"][1000][0]

src/ansys/fluent/core/file_session.py

@@ -508,14 +508,14 @@ def add_requests(
                 )
             elif isinstance(req, ScalarFieldDataRequest):
                 self._add_scalar_fields_request(
-                    field_name=req.field_name,
+                    field_name=_to_scalar_field_name(req.field_name),
                     surfaces=req.surfaces,
                     node_value=req.node_value,
                     boundary_value=req.boundary_value,
                 )
             elif isinstance(req, VectorFieldDataRequest):
                 self._add_vector_fields_request(
-                    field_name=req.field_name,
+                    field_name=_to_vector_field_name(req.field_name),
                     surfaces=req.surfaces,
                 )
             elif isinstance(req, PathlinesFieldDataRequest):
@@ -1221,7 +1221,7 @@ def _get_surface_ids(
     surface_ids = []
     for surf in surfaces:
         if isinstance(surf, str):
-            surface_ids.extend(field_info.get_surfaces_info()[surf]["surface_id"])
+            surface_ids.extend(field_info._get_surfaces_info()[surf]["surface_id"])
         else:
             surface_ids.append(surf)
     return surface_ids
@@ -1232,5 +1232,5 @@ class Fields:
 
     def __init__(self, _session: FileSession):
         """Initialize Fields."""
-        self.field_info = FileFieldInfo(_session)
+        self.field_info = _FileFieldInfo(_session)
         self.field_data = FileFieldData(_session, self.field_info)

src/ansys/fluent/core/services/reduction.py

@@ -37,6 +37,7 @@
     GrpcErrorInterceptor,
     TracingInterceptor,
 )
+from ansys.fluent.core.solver.function.reduction import Weight
 from ansys.fluent.core.variable_strategies import (
     FluentExprNamingStrategy as naming_strategy,
 )
@@ -315,12 +316,17 @@ def _make_request(
         if expression is not None:
             request.expression = self._to_str(expression)
         if weight is not None:
-            request.weight = weight
+            request.weight = Weight(weight).value
         if condition is not None:
             request.condition = condition
         request.locations.extend(self._get_location_string(locations, ctxt))
         return request
 
+    @property
+    def weight(self):
+        """Weight for calculating sum."""
+        return Weight
+
     def area(self, locations, ctxt=None) -> Any:
         """Get area."""
         request = self._make_request("AreaRequest", locations, ctxt)
@@ -445,13 +451,15 @@ def moment(self, expression, locations, ctxt=None) -> Any:
         response = self.service.moment(request)
         return (response.value.x, response.value.y, response.value.z)
 
-    def sum(self, expression, locations, weight, ctxt=None) -> Any:
+    def sum(self, expression, locations, weight: str | Weight, ctxt=None) -> Any:
         """Get sum."""
         request = self._make_request("SumRequest", locations, ctxt, expression, weight)
         response = self.service.sum(request)
         return _convert_variant_to_value(response.value)
 
-    def sum_if(self, expression, condition, locations, weight, ctxt=None) -> Any:
+    def sum_if(
+        self, expression, condition, locations, weight: str | Weight, ctxt=None
+    ) -> Any:
         """Compute the weighted sum of the expression at locations where the given condition is satisfied."""
         request = self._make_request(
             "SumIfRequest", locations, ctxt, expression, weight, condition

src/ansys/fluent/core/solver/function/reduction.py

@@ -80,11 +80,28 @@
 19.28151
 """
 from collections.abc import Iterable
+from enum import Enum
 
 import numpy as np
 from numpy import array
 
 from ansys.fluent.core.exceptions import DisallowedValuesError
+from ansys.fluent.core.variable_strategies import (
+    FluentExprNamingStrategy as naming_strategy,
+)
+
+
+class Weight(Enum):
+    """Weight for sum."""
+
+    AREA = "Area"
+    VOLUME = "Volume"
+    MASS = "Mass"
+    MASS_FLOW_RATE = "MassFlowRate"
+    ABS_MASS_FLOW_RATE = "AbsMassFlowRate"
+
+    def __str__(self):
+        return self.value
 
 
 class BadReductionRequest(Exception):
@@ -194,7 +211,7 @@ def _eval_reduction(
         weight = "Weight=" + str(weight)
         locations = str(locations) + ", " + weight
 
-    expr_str = _expr_to_expr_str(expr)
+    expr_str = _expr_to_expr_str(naming_strategy().to_string(expr))
     if condition:
         expr_str = expr_str + ", " + condition
     return _eval_expr(
@@ -298,6 +315,10 @@ def _limit(limit, expr, locations, ctxt):
     return limit_val
 
 
+# Weight for sum
+weight = Weight
+
+
 def area_average(expression, locations, ctxt=None):
     """Compute the area averaged value of the specified expression over the specified
     locations.
@@ -586,14 +607,14 @@ def mass_flow(locations, ctxt=None):
     return _extent("MassFlow", locations, ctxt)
 
 
-def sum(expression, locations, weight, ctxt=None):
+def sum(expression, locations, weight: str | Weight, ctxt=None):
     """Compute the sum of the specified expression over the specified locations.
 
     Parameters
     ----------
     expression : Any
     locations : Any
-    weight: str
+    weight: str | Weight
     ctxt : Any, optional
     Returns
     -------
@@ -602,7 +623,7 @@ def sum(expression, locations, weight, ctxt=None):
     return _extent_expression("Sum", "Sum", expression, locations, ctxt, weight=weight)
 
 
-def sum_if(expression, condition, locations, weight, ctxt=None):
+def sum_if(expression, condition, locations, weight: str | Weight, ctxt=None):
     """Compute the sum of the specified expression over the specified locations if a
     condition is satisfied.
 
@@ -611,7 +632,7 @@ def sum_if(expression, condition, locations, weight, ctxt=None):
     expression : Any
     condition: str
     locations : Any
-    weight: str
+    weight: str | Weight
     ctxt : Any, optional
     Returns
     -------