.. _ref_getting_started:

===============
Getting started
===============

The Data Processing Framework (DPF) provides numerical simulation users and engineers with a toolbox
for accessing and transforming simulation data. DPF can access data from Ansys solver
result files as well as from several neutral (see :ref:`ref_main_index`).

This **workflow-based** framework allows you to perform complex preprocessing and
postprocessing operations on large amounts of simulation data.

PyDPF-Core is a Python client API communicating with a **DPF Server**, either
through the network using gRPC or directly in the same process.


Install PyDPF-Core
------------------

To install PyDPF-Core, in a Python environment, run this command:

.. code::

   pip install ansys-dpf-core

For more installation options, see :ref:`Installation section <installation>`.


Install DPF Server
------------------

* DPF Server is packaged within the **Ansys installer** in Ansys 2021 R1 and later.
  To use it, download the standard installation using your preferred distribution channel, 
  and install Ansys following the installer instructions. If you experience problems,
  see :ref:`Environment variable <target_environment_variable_with_dpf_section>`. For information on getting
  a licensed copy of Ansys, visit the `Ansys website <https://www.ansys.com/>`_.

* DPF Server is available as a **standalone** package (independent of the Ansys installer) on the 
  `DPF Pre-Release page <https://download.ansys.com/Others/DPF%20Pre-Release>`_ of the Ansys Customer Portal.
  As explained in :ref:`Ansys licensing <target_to_ansys_license_mechanism>`,
  DPF Server is protected by an Ansys license mechanism. Once you have access to an
  Ansys license, install DPF Server:

.. card::

    * Download the ``ansys_dpf_server_win_v2023.2.pre1.zip`` or ``ansys_dpf_server_lin_v2023.2.pre1.zip``
      file as appropriate.
    * Unzip the package and go to its root folder (``ansys_dpf_server_win_v2023.2.pre1`` or
       ``ansys_dpf_server_lin_v2023.2.pre1``).
    * In a Python environment, run this command:

    .. code::

        pip install -e .

    * DPF Server is protected using the license terms specified in the
      `DPFPreviewLicenseAgreement <https://download.ansys.com/-/media/dpf/dpfpreviewlicenseagreement.ashx?la=en&hash=CCFB07AE38C638F0D43E50D877B5BC87356006C9>`_
      file, which is available on the `DPF Pre-Release page <https://download.ansys.com/Others/DPF%20Pre-Release>`_
      of the Ansys Customer Portal. To accept these terms, you must set this
      environment variable:

    .. code::

        ANSYS_DPF_ACCEPT_LA=Y

For more information about the license terms, see :ref:`DPF Preview License Agreement<target_to_license_terms>`.

To use a remote license, set the ``ANSYSLMD_LICENSE_FILE`` environment
variable to point to the Ansys license server ``<license_server_to_use>``:

.. code::

    ANSYSLMD_LICENSE_FILE=1055@<license_server_to_use>

For installation methods that do not use `pip <https://pypi.org/project/pip/>`_,
such as using **Docker containers**, see :ref:`ref_getting_started_with_dpf_server`.

Use PyDPF-Core
--------------

To use PyDPF-Core, in the same Python environment, run this command:

.. code-block:: python

    from ansys.dpf import core as dpf
    from ansys.dpf.core import examples
    model = dpf.Model(examples.download_crankshaft())
    print(model)


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    DPF Model
    ------------------------------
    Static analysis
    Unit system: MKS: m, kg, N, s, V, A, degC
    Physics Type: Mechanical
    Available results:
         -  displacement: Nodal Displacement
         -  velocity: Nodal Velocity
         -  acceleration: Nodal Acceleration
         -  reaction_force: Nodal Force
         -  stress: ElementalNodal Stress
         -  elemental_volume: Elemental Volume
         -  stiffness_matrix_energy: Elemental Energy-stiffness matrix
         -  artificial_hourglass_energy: Elemental Hourglass Energy
         -  thermal_dissipation_energy: Elemental thermal dissipation energy
         -  kinetic_energy: Elemental Kinetic Energy
         -  co_energy: Elemental co-energy
         -  incremental_energy: Elemental incremental energy
         -  elastic_strain: ElementalNodal Strain
         -  structural_temperature: ElementalNodal Temperature
    ------------------------------
    DPF  Meshed Region:
      69762 nodes
      39315 elements
      Unit: m
      With solid (3D) elements
    ------------------------------
    DPF  Time/Freq Support:
      Number of sets: 3
    Cumulative     Time (s)       LoadStep       Substep
    1              1.000000       1              1
    2              2.000000       1              2
    3              3.000000       1              3



.. code-block:: python

    over_time_disp = model.results.displacement().eval()
    over_time_disp[0].plot()


.. figure:: ../images/plotting/crankshaft_disp.png


.. toctree::
   :hidden:
   
   compatibility
   install
   dependencies