Skip to content

Commit

Permalink
Refactor Getting Started and add Licensing (#1423)
Browse files Browse the repository at this point in the history 
* Add a licensing section

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Add a licensing section

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Add a licensing section

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Add a licensing section

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Allow for local build

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Fix doc

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Fix doc

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Fix link

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Update compatibility.rst

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Update description of licensed operators in licensing.rst

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Move and rename getting_started_with_dpf_server.rst to dpf_server.rst

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Update the getting started index.rst

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Refactor licensing.rst

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Refactor dpf_server.rst

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Fixes

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Fixes

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Fixes

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Update mentions to ansys_dpf_server

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

* Mark 'dyna' as a valid license increment

Signed-off-by: paul.profizi <paul.profizi@ansys.com>

---------

Signed-off-by: paul.profizi <paul.profizi@ansys.com>
  • Loading branch information
@PProfizi
PProfizi authored Feb 21, 2024
1 parent b59499e commit e13c72f
Show file tree
Hide file tree
Showing 9 changed files with 355 additions and 250 deletions.
2 changes: 1 addition & 1 deletion doc/source/concepts/waysofusing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ These capabilities can be accessed through client APIs, as shown here:
.. image:: ../images/drawings/apis_2.png


1. DPF server application can be accessed using Ansys Inc product, or DPF Server package (see :ref:`ref_getting_started_with_dpf_server`) available on the Customer portal.
1. DPF server application can be accessed using Ansys Inc product, or DPF Server package (see :ref:`ref_dpf_server`) available on the Customer portal.

2. Several client APIs are available (CPython, IronPython, C++, and so on).

Expand Down
3 changes: 2 additions & 1 deletion doc/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -319,7 +319,8 @@ def verify_meilisearch_is_active(app):
MEILISEARCH_PUBLIC_API_KEY = os.getenv("MEILISEARCH_PUBLIC_API_KEY", None)
if not MEILISEARCH_PUBLIC_API_KEY:
sys.stderr.write("Could not find MEILISEARCH_PUBLIC_API_KEY")
sys.exit(1)
# sys.exit(1)


def setup(app):
app.connect("builder-inited", verify_meilisearch_is_active)
24 changes: 11 additions & 13 deletions doc/source/getting_started/compatibility.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ more information, see `Ansys Platform Support <https://www.ansys.com/solutions/s
Client-server
-------------

The DPF server version depends on your installed Ansys version.
The DPF server version depends on your installed Ansys version or your installed standalone DPF Server pre-release version.
The following table shows client-server compatibility for supported
Ansys versions. With Ansys 2022 R2 and later, you can use PyDPF-Core ``0.10`` and later.
With Ansys 2021 R2 and 2022 R1, you can use PyDPF-Core
Expand Down Expand Up @@ -48,6 +48,16 @@ package should also be synchronized with the server version.
- ``ansys.grpc.dpf`` Python module version
- ``ansys.dpf.gatebin`` binaries Python module version
- ``ansys.dpf.gate`` Python module version
* - 8.0 (Ansys 2024 R2 pre0)
- 0.11.0 and later
- None
- None
- None
* - 7.1 (Ansys 2024 R1)
- 0.10.1 and later
- None
- None
- None
* - 7.0 (Ansys 2024 R1 pre0)
- | 0.10.0 and later
| 0.9.0
Expand Down Expand Up @@ -135,15 +145,3 @@ To get a specific version of the ``ansys-dpf-core`` package, such as 0.7.0, use
.. code::
pip install --force-reinstall ansys-dpf-core==0.7.0
.. _target_environment_variable_with_dpf_section:

Environment variable
--------------------

The ``start_local_server()`` method uses the ``Ans.Dpf.Grpc.bat`` file or
``Ans.Dpf.Grpc.sh`` file to start the server. Ensure that the ``AWP_ROOT{VER}``
environment variable is set to your installed Ansys version. For example, if Ansys
2022 R2 is installed, ensure that the ``AWP_ROOT222`` environment
variable is set to the path for this Ansys installation.

123 changes: 123 additions & 0 deletions doc/source/getting_started/dpf_server.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
.. _ref_dpf_server:

==========
DPF Server
==========

DPF provides numerical simulation users and engineers with a toolbox for accessing and transforming
simulation data. With DPF, you can perform complex preprocessing or postprocessing of large amounts of simulation data within a
simulation workflow.

The DPF Server is packaged within the **Ansys installer** in Ansys 2021 R1 and later.

It is also available as a standalone package that contains all the necessary files to run, enabling DPF capabilities.
The standalone DPF Server is available on the `DPF Pre-Release page <https://download.ansys.com/Others/DPF%20Pre-Release>`_ of the Ansys Customer Portal.
The first standalone version of DPF Server available is 6.0 (2023 R2).

The sections on this page describe how to install and use a standalone DPF Server.

* For a quick start on using PyDPF, see :ref:`ref_getting_started`.
* For more information on DPF and its use, see :ref:`ref_user_guide`.


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

.. _target_installing_server:

#. Download the ``ansys_dpf_server_win_v2024.2.pre0.zip`` or ``ansys_dpf_server_lin_v2024.2.pre0.zip`` file as appropriate.
#. Unzip the package.
#. Optional: download any other plugin ZIP file as appropriate and unzip the package. For example, to access the ``composites`` plugin for Linux,
download ``ansys_dpf_composites_lin_v2024.2.pre0.zip`` and unzip the package in the same location as ``ansys_dpf_server_lin_v2024.2.pre0.zip``.
#. Change to the root folder (``ansys_dpf_server_win_v2024.2.pre0``) of the unzipped package.
#. In a Python environment, run this command:

.. code::
pip install -e .
As detailed in :ref:`licensing`, a standalone 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
To use :ref:`licensed DPF capabilities <target_to_ansys_license_mechanism>` you must set the
``ANSYSLMD_LICENSE_FILE`` environment variable to point to a valid local or remote license
following indications in :ref:`configure_licensing`.


Use DPF Server
--------------

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.

Run DPF Server with PyDPF
~~~~~~~~~~~~~~~~~~~~~~~~~

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

Both PyDPF-Core and PyDPF-Post can be used with DPF Server. Installation instructions
for PyDPF-Core are available in the PyDPF-Core `Getting started <https://dpf.docs.pyansys.com/version/stable/getting_started/install.html>`_.
Installation instructions for PyDPF-Post are available in the PyDPF-Post `Getting started <https://post.docs.pyansys.com/version/stable/getting_started/install.html>`_.

With PyDPF-Core and PyDPF-Post, the first creation of most DPF entities starts a DPF Server with the current default configuration and context.
For example, the following code automatically starts a DPF Server behind the scenes:

.. code::
from ansys.dpf import core as dpf
data_sources = dpf.DataSources()
With PyDPF-Core, you can also explicitly start a DPF Server using this code:

.. code::
from ansys.dpf import core as dpf
server = dpf.start_local_server()
To start a DPF Server from outside a Python environment, you can also use the execution script provided with your DPF Server package.
On Windows, start the DPF Server by running the ``Ans.Dpf.Grpc.bat`` file in the unzipped package.
On Linux, start the DPF Server by running the ``Ans.Dpf.Grpc.sh`` file in the unzipped package.

Manage multiple DPF Server installations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PyDPF automatically starts a local instance of a DPF Server when you run a method requiring a
connection to a server, or when you use the ``start_local_server()`` method.
The ``start_local_server()`` method allows to choose, if necessary, which DPF Server installation
to use thanks to its ``ansys_path`` argument.
PyDPF otherwise follows the logic below to automatically detect and choose which locally installed
version of DPF Server to run:

- it uses the ``ANSYS_DPF_PATH`` environment variable in priority if set and targeting a valid path to a DPF Server installation.
- it then checks the currently active Python environment for any installed standalone DPF Server, and uses the latest version available.
- it then checks for ``AWP_ROOTXXX`` environment variables, which are set by the **Ansys installer**, and uses the latest version available.
- if then raises an error if all of the steps above failed to return a valid path to a DPF Server installation.

Run DPF Server in a Docker container
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DPF Server can be run in a Docker container.

#. Along with the ``ansys_dpf_server_lin_v2024.2.pre0.zip`` file mentioned earlier
in :ref:`Install DPF Server <target_installing_server>`, download the ``Dockerfile`` file.
#. Optional: download any other plugin ZIP file as appropriate. For example, to access the ``composites`` plugin for Linux,
download ``ansys_dpf_composites_lin_v2024.2.pre0.zip``.
#. Copy all the ZIP files and ``Dockerfile`` file in a folder and navigate into that folder.
#. To build the DPF Docker container, run the following command:

.. code::
docker build . -t dpf-core:v2024.2.pre0 --build-arg DPF_VERSION=242
5. To run the DPF Docker container, license it. For more information, see :ref:`DPF Preview License Agreement<target_to_license_terms>`.
70 changes: 22 additions & 48 deletions doc/source/getting_started/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,66 +15,38 @@ 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
------------------

To use PyDPF-Core, you need access to a 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/>`_.
To use it, download the standard installation using your preferred distribution channel,
and install Ansys following the installer instructions.
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 Server pre-releases are also available as **standalone** packages (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::
As explained in :ref:`ref_licensing`, the standalone DPF Server is still protected by an Ansys license mechanism
and requires accepting the :ref:`DPF Preview License Agreement<target_to_license_terms>`.
Once you have access to an Ansys license, follow the guidelines to :ref:`install a standalone DPF Server <target_installing_server>`.

* 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:
For more information regarding installing, managing and running DPF servers, see :ref:`ref_dpf_server`.

.. 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::
Install PyDPF-Core
------------------

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

For more information about the license terms, see :ref:`DPF Preview License Agreement<target_to_license_terms>`.
.. code::
To use a remote license, set the ``ANSYSLMD_LICENSE_FILE`` environment
variable to point to the Ansys license server ``<license_server_to_use>``:
pip install ansys-dpf-core
.. code::
Be sure to check the :ref:`compatibility guidelines <ref_compatibility>` to know if your
DPF Server version is compatible with the latest version of PyDPF-Core.

ANSYSLMD_LICENSE_FILE=1055@<license_server_to_use>
For more installation options, see :ref:`Installation section <installation>`.

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
--------------
Expand Down Expand Up @@ -140,8 +112,10 @@ To use PyDPF-Core, in the same Python environment, run this command:

.. toctree::
:hidden:

compatibility

install
dpf_server
compatibility
licensing
dependencies

Loading

0 comments on commit e13c72f

Please sign in to comment.