:class:`Result`
===============

.. py:class:: ansys.dpf.core.results.Result(connector, mesh_by_default, result_info, server)

   Helps with using DPF's result providers.

   This class helps to connect common inputs to the operator and
   recover its fields container output. 'Result' is created by the model.

   .. rubric:: Examples

   Create a displacement result from the model and choose its time and mesh scopings

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.find_msup_transient())
   >>> disp = model.results.displacement.on_last_time_freq.on_named_selection('_CONSTRAINEDNODES')
   >>> last_time_disp = disp.eval()

   Create a stress result from the model and split the result by element shapes (solid,
   shell, and beam).

   >>> model = dpf.Model(examples.download_all_kinds_of_complexity())
   >>> stress = model.results.stress
   >>> stress_split = stress.split_by_shape.eval()
   >>> solid_stress = stress_split.solid_field()

   Create a strain result from the model on all time sets and recover the
   operator to connect it to other operators.

   >>> model = dpf.Model(examples.find_msup_transient())
   >>> strain = model.results.elastic_strain.on_all_time_freqs()
   >>> eqv = dpf.operators.invariant.von_mises_eqv_fc(strain)
   >>> strain_eqv = eqv.outputs.fields_container()




.. py:currentmodule:: Result

Overview
--------

.. tab-set::



   .. tab-item:: Methods

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

          * - :py:attr:`~eval`
            - Evaluate the result provider with the previously specified inputs and return the result fields container.
          * - :py:attr:`~on_time_scoping`
            - Set the time scoping to a given one.
          * - :py:attr:`~on_named_selection`
            - Set the mesh scoping to a given named selection.
          * - :py:attr:`~on_mesh_scoping`
            - Set the mesh scoping to a given mesh scoping.
          * - :py:attr:`~on_location`
            - Set the requested location of the provider.


   .. tab-item:: Properties

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

          * - :py:attr:`~on_all_time_freqs`
            - Sets the time scoping to all the time frequencies of the time frequency support.
          * - :py:attr:`~on_first_time_freq`
            - Sets the time scoping to the first time frequency of the time frequency support.
          * - :py:attr:`~on_last_time_freq`
            - Sets the time scoping to the last time frequency available in the time frequency support.
          * - :py:attr:`~split_by_body`
            - Set the mesh scoping to a scopings container where each scoping is a body.
          * - :py:attr:`~split_by_shape`
            - Set the mesh scoping to a scopings container where each scoping is an element shape.




   .. tab-item:: Special methods

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

          * - :py:attr:`~__call__`
            - Provide for Result instances to be callable for operator retrieval.




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

.. code-block:: python

    from ansys.dpf.core.results import Result

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

.. py:property:: on_all_time_freqs

   Sets the time scoping to all the time frequencies of the time frequency support.

   :returns: **self**
   :rtype: Result

   .. rubric:: Examples

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.find_msup_transient())
   >>> disp = model.results.displacement
   >>> disp.on_all_time_freqs.eval().get_label_scoping("time").ids
   <BLANKLINE>
   ...1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]...

.. py:property:: on_first_time_freq

   Sets the time scoping to the first time frequency of the time frequency support.

   :returns: **self**
   :rtype: Result

   .. rubric:: Examples

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.find_msup_transient())
   >>> disp = model.results.displacement
   >>> disp.on_first_time_freq.eval().get_label_scoping("time").ids
   <BLANKLINE>
   ...[1]...

.. py:property:: on_last_time_freq

   Sets the time scoping to the last time frequency available in the time frequency support.

   :returns: **self**
   :rtype: Result

   .. rubric:: Examples

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.find_msup_transient())
   >>> disp = model.results.displacement
   >>> disp.on_last_time_freq.eval().get_label_scoping("time").ids
   <BLANKLINE>
   ...[20]...

.. py:property:: split_by_body

   Set the mesh scoping to a scopings container where each scoping is a body.

   :returns: **self**
   :rtype: Result

   .. rubric:: Examples

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.download_all_kinds_of_complexity())
   >>> disp = model.results.displacement
   >>> fc_disp = disp.split_by_body.eval()
   >>> len(fc_disp)
   13
   >>> fc_disp.get_mat_scoping().ids
   <BLANKLINE>
   ...1, 5, 6, 10, 2, 7, 8, 13, 4, 12, 15, 16, 17]...
   >>> disp_mat_10 = fc_disp.get_field_by_mat_id(10)

.. py:property:: split_by_shape

   Set the mesh scoping to a scopings container where each scoping is an element shape.

   The evaluated fields container will have one field on 'solid',
   one on 'shell', one on 'beam' and one on 'unknown_shape'.

   :returns: **self**
   :rtype: Result

   .. rubric:: Examples

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.download_all_kinds_of_complexity())
   >>> disp = model.results.displacement
   >>> fc_disp = disp.split_by_shape.eval()
   >>> len(fc_disp)
   4

   >>> shell_disp = fc_disp.shell_field()
   >>> solid_disp = fc_disp.solid_field()




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

.. py:method:: __call__(time_scoping=None, mesh_scoping=None)

   Provide for Result instances to be callable for operator retrieval.


.. py:method:: eval()

   Evaluate the result provider with the previously specified inputs and return the result fields container.

   :returns: **fields_container** -- If ``split_by_body`` is used, a ``BodyFieldsContainer`` is returned.
             if ``split_by_shape`` is used, an ``ElShapeFieldsContainer`` is returned.
   :rtype: FieldsContainer, ElShapeFieldsContainer, BodyFieldsContainer

   .. rubric:: Examples

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.find_msup_transient())
   >>> disp = model.results.displacement
   >>> fc = disp.on_all_time_freqs.eval()


.. py:method:: on_time_scoping(time_scoping)

   Set the time scoping to a given one.

   :param time_scoping: One or more times or frequencies.
   :type time_scoping: float, list[float], int, list[int], Scoping

   :returns: **self**
   :rtype: Result

   .. rubric:: Examples

   Choose time sets.

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.find_msup_transient())
   >>> stress = model.results.stress
   >>> fc = stress.on_time_scoping([1,2,3,19]).eval()
   >>> len(fc)
   4

   Choose times. If the times chosen are not in the time frequency support,
   results are extrapolated.

   >>> fc = stress.on_time_scoping([0.115,0.125]).eval()
   >>> len(fc)
   2
   >>> fc.time_freq_support.time_frequencies.data
   DPFArray([0.115, 0.125]...


.. py:method:: on_named_selection(named_selection)

   Set the mesh scoping to a given named selection.

   :param named_selection: Name of the named selection or component in upper case.
   :type named_selection: str

   :returns: **self**
   :rtype: Result

   .. rubric:: Examples

   Add a requested location to the average result on the nodes.

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.find_msup_transient())
   >>> stress = model.results.stress
   >>> fc = stress.on_first_time_freq.on_named_selection('_CONSTRAINEDNODES').eval()
   >>> len(fc[0].scoping)
   40


.. py:method:: on_mesh_scoping(mesh_scoping)

   Set the mesh scoping to a given mesh scoping.

   :param mesh_scoping:
   :type mesh_scoping: Scoping, list[int]

   :returns: **self**
   :rtype: Result

   .. rubric:: Examples

   Use a list of nodes.

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.find_complex_rst())
   >>> disp = model.results.displacement
   >>> fc = disp.on_mesh_scoping([1,2,3]).eval()
   >>> len(fc[0].scoping)
   3

   Use a scoping to specify a list of entity IDs with their locations.

   >>> stress = model.results.stress
   >>> scop = dpf.Scoping(ids=[3,4,5], location= dpf.locations.nodal)
   >>> fc = stress.on_mesh_scoping(scop).eval()
   >>> len(fc[0].scoping)
   3
   >>> fc[0].location
   'Nodal'


.. py:method:: on_location(location)

   Set the requested location of the provider.

   Elemental nodal fields can be averaged to a nodal or elemental location.

   :param location:
   :type location: str, locations

   :returns: **self**
   :rtype: Result

   .. rubric:: Examples

   Add a requested location to the average result on the nodes.

   >>> from ansys.dpf import core as dpf
   >>> from ansys.dpf.core import examples
   >>> model = dpf.Model(examples.find_complex_rst())
   >>> stress = model.results.stress
   >>> fc = stress.eval()
   >>> fc[0].location
   'ElementalNodal'

   >>> fc = stress.on_location(dpf.locations.nodal).eval()
   >>> fc[0].location
   'Nodal'