Field data doc.

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

@@ -0,0 +1,248 @@
+.. _ref_field_data:
+
+Field Data
+==========
+The ``FieldData`` module provides access to Fluent surface, scalar and vector field
+data. It provides two sets of APIs.
+
+#. APIs to get multiple fields in a single request. 
+#. APIs to get one field per request. 
+
+
+++++++++++++++++++++++++++++
+Muliple fields in a request
+++++++++++++++++++++++++++++
+In this approach, requests for multiple fields are combined in a single request and
+data for all fields is received in a single response. 
+
+* Request
+
+  Requests for multiple fields can be combined in a single request via 
+  `add_get_<items>_request` 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. 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 
+the 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
+^^^^^^^^^^^
+
+The Surface ID is the same one as 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 face centroids    
+
+  * face-normal
+
+    *  Contains face normals
+
+* Scalar field request
+
+  Response will contain a single field with the same name as the 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.
+
+
+Example
+^^^^^^^
+
+.. 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
+    
+    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.
+           },           
+        },           
+    }
+
+++++++++++++++++++++++++++++
+One field per request
+++++++++++++++++++++++++++++
+In this approach, one field is received for each request. For each field i.e. surface, scalar 
+and vector there is a separate API. 
+
+#. ``get_surface_data``
+
+   *  To get surface data.
+
+#. ``get_scalar_field_data``
+
+   *  To get scalar field data.
+
+#. ``get_vector_field_data``
+
+   *  To get vector field data.
+
+For surface and scalar field, response contains dictionary of surface ID and numpy array of 
+the requested field. 
+
+* surface_id [int] -> field[np.array]
+
+For vector field, response is dictionary of surface ID and Tuple of numpy array of vector field 
+and vector scale. 
+
+* surface_id [int] -> (vector field [np.array],  vector-scale [float])  
+
+It is important to note that in Fluent, a surface name can be associated with multiple surface 
+IDs. So response contains surface ID as key of returned dictionary. 
+
+Example
+^^^^^^^
+
+.. code-block:: python
+
+    from ansys.fluent.core.services.field_data import SurfaceDataType
+
+    #Get field data object
+    field_data = session.field_data
+    
+    #wall surface is associated with two IDs i.e. id1 and id2
+    
+    #Get surface data 
+    vertices = field_data.get_surface_data("wall", SurfaceDataType.Vertices)
+    #return value>> {id1: np.array, id2: np.array}
+    normals = field_data.get_surface_data("wall", SurfaceDataType.FacesNormal)
+    #return value>> {id1: np.array, id2: np.array}
+    
+    #Get scalar field data 
+    scalar_field_data = field_data.get_scalar_field_data("wall", "temperature")
+    #return value>> {id1: np.array, id2: np.array}
+    
+    #Get vector field data 
+    vector_field_data = field_data.get_vector_field_data("wall", "velocity")
+    #return value>> {id1: (np.array, float), id2: (np.array, float)}
+
+    
+.. 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
+
+.. automethod:: ansys.fluent.core.services.field_data.FieldData.get_surface_data
+.. automethod:: ansys.fluent.core.services.field_data.FieldData.get_scalar_field_data
+.. automethod:: ansys.fluent.core.services.field_data.FieldData.get_vector_field_data
+

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

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