Field data doc.

doc/source/api/core/solver/fielddata.rst

@@ -0,0 +1,164 @@
+.. _ref_field_data:
+
+Field Data
+==========
+FieldData module provides access to Fluent surface, scalar and vector field
+data. Client can get multiple fields in a single request. 
+
+* Request
+
+  Multiple requests for  fields can be appended in a single request with 
+  `add_get_<field>_requests` APIs. 
+
+  * add_get_surfaces_request
+        To add surfaces request
+  * add_get_scalar_fields_request
+        To add scalar fields request
+  * add_get_vector_fields_request
+        To add vector fields request 
+
+* Response
+
+  All requested fields are returned in a single response with `get_fields` API
+
+  * get_fields
+      It provides the dictionary containing the requested fields as numpy array 
+      in the following order
+
+      * tag_id [int]-> surface_id [int] -> field_name [str] -> field_data[np.array]
+
+
+Tag Id
+^^^^^^^ 
+
+Tag id is generated by applying `bitwise or` on all tags for a request. following
+is the list of supported tags and their values:   
+
+*  OVERSET_MESH: 1,
+*  ELEMENT_LOCATION: 2,
+*  NODE_LOCATION: 4,
+*  BOUNDARY_VALUES: 8,
+
+So if scalar field data is requested for element location[2] then tag_id in 
+dictionary will be 2. Similarly if boundary values[8] are requested for 
+node location[4] then tag_id will be (4|8) i.e. 12.
+
+Surface Id
+^^^^^^^^^^^
+
+Surface ids are the one passed in the request.
+
+Field Name
+^^^^^^^^^^^
+
+For a request multiple fields are returned. Number of fields depends upon the request type.
+
+* Surface request 
+
+  Response will contain any of the following fields depending upon the request arguments.
+
+  * faces 
+      Contains faces connectivity    
+  * vertices
+      Contains node coordinates
+  * centroid
+      Contains faces centroid    
+  * face-normal
+      Contains faces Normal
+
+* Scalar field request
+
+  Response will contain a single field with name same as scalar field name passed in the request.
+
+* vector field request
+
+  Response will contain two fields 
+
+  * Vector field, with name same as vector field name passed in the request. 
+  * vector-scale.
+
+
+.. code-block:: python
+
+    #Get field data 
+    field_data = session.field_data
+
+    #Add requests
+        
+    #Data for surfaces for following requests will be returned in tag_id 0. As there is no tag.
+    
+    field_data.add_get_surfaces_request(surface_ids=[1], provide_vertices=True, 
+                                        provide_faces=False, provide_faces_centroid=True
+                                       )
+                                       
+    field_data.add_get_surfaces_request(surface_ids=[2], provide_vertices=True, 
+                                       provide_faces=True                                        
+                                       )                                       
+    
+    #Data for tempaeraure for following request will be returned in tag_id 12 i.e. 4|8.
+    field_data.add_get_scalar_fields_request(surface_ids=[1,2], field_name="temperature", 
+                                            node_value=True, boundary_value=True
+                                            )
+    
+    #Data for tempaeraure for following request will be returned in tag_id 4.
+    field_data.add_get_scalar_fields_request(surface_ids=[3], field_name="temperature", 
+                                             node_value=True, boundary_value=False
+                                             )
+    
+    #Data for pressure for following request will be returned in tag_id 2. 
+    field_data.add_get_scalar_fields_request(surface_ids=[1,4], field_name="pressure",
+                                            node_value=False, boundary_value=False
+                                            )
+    
+    #Get fields
+    
+    scalar_field_payload_data = field_data.get_fields()
+    
+    
+    #Data will be returned in dictionary with order 
+    #`tag_id [int]-> surface_id [int] -> field_name [str] -> field_data [np.array]`
+    {
+      0:{
+         1:{
+           "vertices": np.array #for vertices.
+           "centroid": np.array #for faces centroid.
+           },
+         2:{
+           "vertices": np.array #for vertices.
+           "faces": np.array #for faces connectivity.
+           },           
+        },    
+      12:{
+         1:{
+           "temperature": np.array #for temperature at node location with boundary values.
+           },
+         2:{
+           "temperature": np.array #for temperature at node location with boundary values.
+           },           
+        }, 
+      4:{
+         3:{
+           "temperature": np.array #for temperature at node location.
+           }         
+        },       
+      2:{
+         1:{
+           "pressure": np.array #for pressure at element location.
+           },
+         4:{
+           "pressure": np.array #for pressure at element location.
+           },           
+        },           
+    }
+        
+
+.. currentmodule:: ansys.fluent.core.services
+
+.. autosummary::
+   :toctree: _autosummary
+
+
+.. automethod:: ansys.fluent.core.services.field_data.FieldData.add_get_surfaces_request
+.. automethod:: ansys.fluent.core.services.field_data.FieldData.add_get_scalar_fields_request
+.. automethod:: ansys.fluent.core.services.field_data.FieldData.add_get_vector_fields_request
+.. automethod:: ansys.fluent.core.services.field_data.FieldData.get_fields   

doc/source/api/core/solver/index.rst

@@ -12,4 +12,5 @@ Solver
    :hidden:
 
    settings
-   tui
+   tui
+   fielddata

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

@@ -114,40 +114,7 @@ def get_surfaces_info(self) -> dict:
 
 
 class FieldData:
-    """Provides access to Fluent field data on surfaces.
-
-    Methods
-    -------
-    add_get_surfaces_request(
-        surface_ids: List[int],
-        overset_mesh: bool = False,
-        provide_vertices=True,
-        provide_faces=True,
-        provide_faces_centroid=False,
-        provide_faces_normal=False,
-    ) -> None
-        Add request to get surfaces data i.e. vertices, faces connectivity,
-        centroids and normals.
-
-    add_get_scalar_fields_request(
-        surface_ids: List[int],
-        scalar_field: str,
-        node_value: Optional[bool] = True,
-        boundary_value: Optional[bool] = False,
-    ) -> None
-        Add request to get scalar field data on surfaces.
-
-    add_get_vector_fields_request(
-        surface_ids: List[int],
-        vector_field: Optional[str] = "velocity"
-    ) -> None
-        Add request to get vector field data on surfaces.
-
-    get_fields(self) -> Dict[int, Dict]
-        Provide data for previously added requests.
-        Data is returned as dictionary of dictionaries in following structure:
-            tag_id [int]-> surface_id [int] -> field_name [str] -> field_data
-    """
+    """Provides access to Fluent field data on surfaces."""
 
     # data mapping
     _proto_field_type_to_np_data_type = {
@@ -239,12 +206,35 @@ def _get_fields_request(self):
     def add_get_surfaces_request(
         self,
         surface_ids: List[int],
-        overset_mesh: bool = False,
-        provide_vertices=True,
-        provide_faces=True,
-        provide_faces_centroid=False,
-        provide_faces_normal=False,
+        overset_mesh: Optional[bool] = False,
+        provide_vertices: Optional[bool] = True,
+        provide_faces: Optional[bool] = True,
+        provide_faces_centroid: Optional[bool] = False,
+        provide_faces_normal: Optional[bool] = False,
     ) -> None:
+        """Add request to get surfaces data i.e. vertices, faces connectivity,
+        centroids and normals.
+
+        Parameters
+        ----------
+        surface_ids : List[int]
+            List of surface ids, for surface data.
+
+        overset_mesh : bool, optional
+            If set to True overset mesh will be provided.
+
+        provide_vertices : bool, optional
+            if set to True vertices i.e. node coordinates will be provided.
+
+        provide_faces : bool, optional
+            if set to True faces connectivity will be provided.
+
+        provide_faces_centroid : bool, optional
+            if set to True faces centroid will be provided.
+
+        provide_faces_normal : bool, optional
+            if set to True faces normal will be provided.
+        """
         self._get_fields_request().surfaceRequest.extend(
             [
                 FieldDataProtoModule.SurfaceRequest(
@@ -266,6 +256,23 @@ def add_get_scalar_fields_request(
         node_value: Optional[bool] = True,
         boundary_value: Optional[bool] = False,
     ) -> None:
+        """Add request to get scalar field data on surfaces.
+
+        Parameters
+        ----------
+        surface_ids : List[int]
+            List of surface ids, for scalar field data.
+
+        field_name : str
+            Scalar field name.
+
+        node_value : bool, optional
+            if set to True data will be provided for nodal location otherwise
+            data will be provided for element location.
+
+        boundary_value : bool, optional
+            if set to True, no slip velocity will be provided at wall boundaries.
+        """
         self._get_fields_request().scalarFieldRequest.extend(
             [
                 FieldDataProtoModule.ScalarFieldRequest(
@@ -285,6 +292,16 @@ def add_get_vector_fields_request(
         surface_ids: List[int],
         vector_field: Optional[str] = "velocity",
     ) -> None:
+        """Add request to get vector field data on surfaces.
+
+        Parameters
+        ----------
+        surface_ids : List[int]
+            List of surface ids, for vector field data.
+
+        vector_field : str, optional
+            Vector field name.
+        """
         self._get_fields_request().vectorFieldRequest.extend(
             [
                 FieldDataProtoModule.VectorFieldRequest(
@@ -296,6 +313,14 @@ def add_get_vector_fields_request(
         )
 
     def get_fields(self) -> Dict[int, Dict]:
+        """Provide data for previously added requests.
+
+        Returns
+        -------
+        Dict
+            Data is returned as dictionary of dictionaries in following structure:
+            tag_id [int]-> surface_id [int] -> field_name [str] -> field_data[np.array]
+        """
         request = self._get_fields_request()
         self._fields_request = None
         return self._extract_fields(self.__service.get_fields(request))