:class:`Faces`
==============

.. py:class:: ansys.dpf.core.faces.Faces(mesh)

   Contains faces belonging to a meshed region.

   :param mesh: Name of the meshed region.
   :type mesh: str

   .. rubric:: Examples

   >>> import ansys.dpf.core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.fluid_axial_model())
   >>> faces = model.metadata.meshed_region.faces
   >>> faces.n_faces
   44242

   .. rubric:: Notes

   Class available with server's version starting at 7.0 (2024 R1 pre0).







.. py:currentmodule:: Faces

Overview
--------

.. tab-set::



   .. tab-item:: Methods

      .. list-table::
          :header-rows: 0
          :widths: auto

          * - :py:attr:`~face_by_id`
            - Retrieve a face by face ID.
          * - :py:attr:`~face_by_index`
            - Retrieve a face using its index.
          * - :py:attr:`~map_scoping`
            - Retrieve the indices to map the scoping of these faces to the scoping of a field.


   .. tab-item:: Properties

      .. list-table::
          :header-rows: 0
          :widths: auto

          * - :py:attr:`~scoping`
            - Scoping of the faces.
          * - :py:attr:`~faces_type_field`
            - Field of all faces types.
          * - :py:attr:`~faces_nodes_connectivity_field`
            - Field containing for each face ID the node indices connected to the face.
          * - :py:attr:`~n_faces`
            - Number of faces.
          * - :py:attr:`~mapping_id_to_index`
            - Mapping between the IDs and indices of the entity.




   .. tab-item:: Special methods

      .. list-table::
          :header-rows: 0
          :widths: auto

          * - :py:attr:`~__str__`
            - Provide custom string representation.
          * - :py:attr:`~__getitem__`
            - Retrieve face based on an index.
          * - :py:attr:`~__len__`
            - Retrieve the number of faces.
          * - :py:attr:`~__iter__`
            - Provide for iterating in loops.




Import detail
-------------

.. code-block:: python

    from ansys.dpf.core.faces import Faces

Property detail
---------------

.. py:property:: scoping
   :type: ansys.dpf.core.scoping.Scoping


   Scoping of the faces.

   :rtype: :class:`ansys.dpf.core.scoping.Scoping`

   .. rubric:: Examples

   >>> import ansys.dpf.core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.fluid_axial_model())
   >>> faces = model.metadata.meshed_region.faces
   >>> my_scoping = faces.scoping

.. py:property:: faces_type_field

   Field of all faces types.

   :returns: Field of all faces types.
   :rtype: :class:`ansys.dpf.core.field.Field`

   .. rubric:: Examples

   >>> import ansys.dpf.core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.fluid_axial_model())
   >>> faces = model.metadata.meshed_region.faces
   >>> field = faces.faces_type_field
   >>> print(field.data)
   [16 16 16 ... 16 16 16]

.. py:property:: faces_nodes_connectivity_field

   Field containing for each face ID the node indices connected to the face.

   :returns: Field containing for each face ID the node indices connected to the face.
   :rtype: :class:`ansys.dpf.core.field.Field`

   .. rubric:: Examples

   >>> import ansys.dpf.core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.fluid_axial_model())
   >>> faces = model.metadata.meshed_region.faces
   >>> field = faces.faces_nodes_connectivity_field
   >>> field.get_entity_data(1)
   DPFArray([11415, 11347, 11387, 11454])

.. py:property:: n_faces
   :type: int


   Number of faces.

.. py:property:: mapping_id_to_index
   :type: dict


   Mapping between the IDs and indices of the entity.

   This property is useful for mapping scalar results from a field to the meshed region.

   .. rubric:: Examples

   >>> import ansys.dpf.core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.fluid_axial_model())
   >>> meshed_region = model.metadata.meshed_region
   >>> map = meshed_region.faces.mapping_id_to_index




Method detail
-------------

.. py:method:: __str__()

   Provide custom string representation.


.. py:method:: __getitem__(index)

   Retrieve face based on an index.


.. py:method:: __len__()

   Retrieve the number of faces.


.. py:method:: __iter__()

   Provide for iterating in loops.


.. py:method:: face_by_id(id) -> Face

   Retrieve a face by face ID.

   :param id: Number (ID) of the face.
   :type id: int

   :returns: Face object.
   :rtype: Face


.. py:method:: face_by_index(index) -> Face

   Retrieve a face using its index.

   :param index: Zero-based index.
   :type index: int

   :returns: Yield face.
   :rtype: Face

   .. rubric:: Examples

   faces.face_by_index(0)

   .. rubric:: Notes

   This is equivalent to ``faces[0]``


.. py:method:: map_scoping(external_scope)

   Retrieve the indices to map the scoping of these faces to the scoping of a field.

   :param external_scope: Scoping to map to.
   :type external_scope: :class:`ansys.dpf.core.scoping.Scoping`

   :returns: * **indices** (*numpy.ndarray*) -- List of indices to map from the external scope to the
               scoping of these faces.
             * **mask** (*numpy.ndarray*) -- Members of the external scope that are in the face scoping.

   .. rubric:: Examples

   Return the indices that map a field to a faces collection.

   >>> import ansys.dpf.core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.fluid_axial_model())
   >>> faces = model.metadata.meshed_region.faces
   >>> m = model.results.mass_flow_rate()
   >>> field = m.outputs.fields_container()[0]
   >>> ind, mask = faces.map_scoping(field.scoping)