Documentation: Add ServerContext, ServerConfiguration and GettingStartedWithDPFServer sections

ansys/dpf/core/server_context.py

@@ -16,9 +16,9 @@
 
 class LicensingContextType(Enum):
     premium = 1
-    """Allows capabilities requiring Licenses check out."""
+    """Allows capabilities requiring Licenses checkout."""
     entry = 4
-    """Loads minimum capabilities without requiring any Licenses check out."""
+    """Loads minimum capabilities without requiring any Licenses checkout."""
 
     def __int__(self):
         return self.value
@@ -52,7 +52,7 @@ def __init__(self, context_type=LicensingContextType.premium, xml_path=""):
 
     @property
     def licensing_context_type(self):
-        """Whether capabilities requiring Licenses check out should be allowed.
+        """Whether capabilities requiring Licenses checkout should be allowed.
 
         Returns
         -------
@@ -87,6 +87,8 @@ def __ne__(self, other):
 
 
 class AvailableServerContexts:
+    """Defines available server contexts.
+    """
     pre_defined_environment = ServerContext(0)
     """DataProcessingCore.xml that is next to DataProcessingCore.dll/libDataProcessingCore.so will
     be taken"""

docs/source/index.rst

@@ -48,7 +48,7 @@ Here is how you plot displacement results:
 .. code:: python
 
     >>> disp = model.results.displacement().X()
-    model.metadata.meshed_region.plot(disp.outputs.fields_container())
+    >>> model.metadata.meshed_region.plot(disp.outputs.fields_container())
 
 For comprehensive demos, see :ref:`gallery`.
 

docs/source/user_guide/getting_started_with_dpf_server.rst

@@ -0,0 +1,152 @@
+.. _ref_getting_started_with_dpf_server:
+
+===============================
+Getting Started with DPF Server
+===============================
+
+What is DPF Server
+------------------
+
+The Data Processing Framework (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.
+
+DPF Server is a package that contains all the necessary files to run the DPF Server, enabling DPF capabilities. It is available 
+on the Ansys Customer Portal. DPF Server first available version is 6.0 (2023 R2).
+
+For more information about DPF and its use, see :ref:`ref_user_guide`. 
+
+The following section details how to use DPF Server package. For a quick start with DPF Server, see :ref:`ref_getting_started`. 
+
+Installing DPF Server
+---------------------
+
+.. _target_installing_server:
+
+#. Download the ansys_dpf_server_win_v2023.2.pre0.zip or ansys_dpf_server_lin_v2023.2.pre0.zip file as appropriate.
+#. Unzip the package.
+#. Change to the root folder (ansys_dpf_server_win_v2023.2.pre0) of the unzipped package. 
+#. In a Python environment, run the following command:
+
+.. code::
+
+    pip install -e . 
+
+PyDPF-Core and PyDPF-Post python modules can now be used. The instructions to install and get started with PyDPF-Core 
+(ansys-dpf-core module) can be found at `Getting Started section <https://dpf.docs.pyansys.com/getting_started/install.html>`_. 
+
+Using DPF Server
+----------------
+
+Running the DPF Server with PyDPF
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With PyDPF-Core and PyDPF-Post, the first creation of most DPF entities will start a DPF Server with the current default configuration and context.
+For example, the following code will automatically start 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:
+
+.. 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.
+
+Running the DPF Server in a Docker container
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Along with the ansys_dpf_server_lin_v2023.2.pre0.zip archive mentioned in :ref:`Installing DPF Server <target_installing_server>`, download the Dockerfile.
+2. Copy both the archive and Dockerfile in a folder and navigate into that folder.
+3. To build the DPF Docker container, run the following commands:
+
+.. code::
+
+    docker build . -t dpf-core:v2023_2_pre0 --build-arg DPF_VERSION=232 --build-arg DPF_SERVER_FILE=ansys_dpf_server_lin_v2023.2.pre0.zip
+
+4. To run the DPF Docker container, see the :ref:`License terms<target_to_license_terms>` section.
+
+License terms
+-------------
+
+DPF Preview License Agreement 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _target_to_license_terms:
+
+DPF Server is protected using license terms specified in the DPFPreviewLicenseAgreement file that 
+can be found on the Ansys Customer Portal.
+
+To accept the DPF User Licensing Agreement terms, the following environment flag must be set: 
+
+.. code::
+
+    "ANSYS_DPF_ACCEPT_LA=Y"
+
+ANSYS_DPF_ACCEPT_LA confirms your acceptance of the DPF User Licensing Agreement. By passing the value "Y" to the environment variable 
+"ANSYS_DPF_ACCEPT_LA", you are expressing that you have a valid and existing license for the edition and version of DPF server you intend to use.
+
+For a DPF Docker container usage, it can be set using:
+
+.. code::
+
+    docker run -e "ANSYS_DPF_ACCEPT_LA=Y" -e ANSYSLMD_LICENSE_FILE=1055@<license_server_to_use> -p 50052:50052 -e DOCKER_SERVER_PORT=50052 --expose=50052 dpf-core:v2023_2_pre0
+
+For any other case, set "ANSYS_DPF_ACCEPT_LA" as an environment variable with "Y" value.
+
+Replace "<license_server_to_use>" mention that ANSYSLMD_LICENSE_FILE environment variable points to the Ansys license server.
+For more information about Ansys license mechanism use with DPF Server, see :ref:`Ansys licensing section<target_to_ansys_license_mechanism>`.
+
+
+Ansys licensing
+~~~~~~~~~~~~~~~
+
+.. _target_to_ansys_license_mechanism:
+
+DPF Server is protected by Ansys licensing mechanism.
+
+DPF capabilities are available through the following main services: 
+- Entry: Loads the minimum number of plugins for basic use. It is the default. It will only check if an Ansys License is available. 
+- Premium: Loads the entry and the premium capabilities that require a license checkout. 
+
+To update the context, apply a new server context:
+
+.. code::
+
+    dpf.apply_server_context(dpf.AvailableServerContexts.premium)
+
+The following Ansys licensing increments currently provide rights to use DPF Server: 
+
+- "preppost" available in Ansys Mechanical Enterprise PrepPost product
+- "meba" available in ANSYS Mechanical Enterprise Solver product
+- "mech_2" availale in ANSYS Mechanical Premium product
+- "mech_1" availale in ANSYS Mechanical Pro product
+- "ansys" available in ANSYS Mechanical Enterprise product
+- "dynapp" available in ANSYS LS-DYNA PrepPost product
+- "vmotion" available in Ansys Motion product
+- "acpreppost" available in Ansys Mechanical Enterprise product
+- "acdi_adprepost" available in Ansys AUTODYN and Ansys AUTODYN PrepPost products
+- "cfd_preppost" available in Ansys CFD Enterprise product
+- "cfd_preppost_pro" available in Ansys CFD Enterprise product
+- "vmotion_post" available in Ansys Motion Post product
+- "vmotion_pre" available in Ansys Motion Pre product
+- "advanced_meshing" available in Ansys CFD Enterprise product
+- "fluent_meshing_pro" available in Ansys CFD Enterprise product
+- "fluent_setup_post" available in Ansys CFD Enterprise product
+- "fluent_setup_post_pro" available in Ansys CFD Enterprise product
+- "acfx_pre" available in Ansys CFD Enterprise product
+- "cfd_base" available in Ansys CFD Enterprise product
+- "cfd_solve_level1" available in Ansys CFD Enterprise product
+- "cfd_solve_level2" available in Ansys CFD Enterprise product
+- "cfd_solve_level3" available in Ansys CFD Enterprise product
+- "fluent_meshing" available in Ansys CFD Enterprise product
+
+Each increment may be available in other products. The product/increment mapping can be found in the Licensing section of the Ansys Customer Portal:
+`<https://download.ansys.com/Installation%20and%20Licensing%20Help%20and%20Tutorials>`_. 

docs/source/user_guide/how_to.rst

@@ -8,6 +8,9 @@ How-tos
 
     plotting.rst
     custom_operators.rst
+    getting_started_with_dpf_server.rst
+    server_types.rst
+    server_context.rst
     xmlfiles.rst
 
 
@@ -22,6 +25,7 @@ How-tos
        .. image:: ../images/plotting/pontoon.png
        .. image:: ../images/plotting/pontoon_strain.png
 
+
     .. card:: Create Custom Operators
        :link: user_guide_custom_operators
        :link-type: ref
@@ -30,12 +34,40 @@ How-tos
 
        .. image:: ../images/drawings/plugin-logo.png
           :width: 50%
+
+
+    .. card:: Use DPF Server package
+       :link: ref_getting_started_with_dpf_server
+       :link-type: ref
+       :width: 25%
+       :text-align: center
+
+       .. image:: ../images/drawings/dpf_server_client.png
+
+
+.. card-carousel:: 2
+
+    .. card:: Switch between local and remote server
+       :link: user_guide_server_types
+       :link-type: ref
+       :width: 25%
+       :text-align: center
+
+       .. image:: ../images/drawings/remote_machines.png
+
+    .. card:: Access Entry and Premium capabilities
+       :link: user_guide_server_context
+       :link-type: ref
+       :width: 25%
+       :text-align: center
+
+       .. image:: ../images/drawings/entry_premium.png
+
 
     .. card:: Use DPF XML Files
        :link: user_guide_xmlfiles
        :link-type: ref
        :width: 25%
        :text-align: center
 
-       .. image:: ../images/drawings/xml.png
-
+       .. image:: ../images/drawings/xml.png

docs/source/user_guide/index.rst

@@ -15,7 +15,7 @@ This section has the following goals:
  - Provide simple how-tos for tackling most common use cases.
 
 Other sections of this guide include :ref:`ref_api_section`, :ref:`ref_dpf_operators_reference`,
-and :ref:`sphx_glr_examples`.
+and :ref:`gallery`.
 
 .. include::
    dpf_concepts.rst

docs/source/user_guide/server_context.rst

@@ -0,0 +1,123 @@
+.. _user_guide_server_context:
+
+==============
+Server context
+==============
+
+What is server context
+----------------------
+
+The :class:`ServerContext <ansys.dpf.core.server_context.ServerContext>` class drives the
+default capabilities a server will be started with. 
+
+The server context is composed of the following information:
+
+- context_type, a :class:`LicensingContextType <ansys.dpf.core.server_context.LicensingContextType>`
+  class object that defines if a License checkout is required or not.
+- the xml_path that sets DPF default operators capabilities.
+
+For more information,
+see :class:`AvailableServerContexts <ansys.dpf.core.server_context.AvailableServerContexts>`
+and :ref:`user_guide_xmlfiles`.
+
+Two main licensing context type capabilities are available: 
+
+- Entry (default): Loads the minimum capabilities without requiring any license checkout.
+- Premium: Enables the entry capabilities and the capabilities that requires a license checkout.
+  More operators are available.
+
+The operators list for each licensing context type is available at
+:ref:`ref_dpf_operators_reference`.
+
+Getting started with Entry capabilities
+---------------------------------------
+
+Find the list of operators available when the context is Entry at :ref:`ref_dpf_operators_reference`.
+This won't check out any license.
+
+.. code-block::
+
+    from ansys.dpf import core as dpf
+    entry_server = dpf.start_local_server()
+    entry_server.context
+
+Getting started with Premium capabilities
+-----------------------------------------
+
+Find the list of operators available when the context is Premium at :ref:`ref_dpf_operators_reference`.
+This will check out a license.
+
+.. code-block::
+
+    from ansys.dpf import core as dpf
+    premium_server_context = dpf.AvailableServerContexts.premium
+    premium_server = dpf.start_local_server(
+        context=premium_server_context
+    )
+    print(premium_server.context)
+
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
+
+    Server Context of type LicensingContextType.premium with no xml path
+
+Changing server context from Entry to Premium
+---------------------------------------------
+
+Once an Entry server is started, it can be upgraded to Premium:
+
+.. code-block::
+
+    from ansys.dpf import core as dpf
+    # start a server with entry capabilities
+    server = dpf.start_local_server()
+    print(server.context)
+
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
+
+    Server Context of type LicensingContextType.entry with no xml path
+
+.. code-block::
+
+    # apply a premium context on the server
+    server.apply_context(dpf.AvailableServerContexts.premium)
+    print(server.context)
+
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
+
+    Server Context of type LicensingContextType.premium with no xml path
+
+
+Changing the default server context
+-----------------------------------
+
+Entry is the default server context. This can be changed either using the ANSYS_DPF_SERVER_CONTEXT
+environment variable (see `<ansys.dpf.core.server_context>`) or writing:
+
+.. code-block::
+
+    from ansys.dpf import core as dpf
+    dpf.set_default_server_context(dpf.AvailableServerContexts.premium)
+    print(dpf.server_context.SERVER_CONTEXT)
+
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
+
+    Server Context of type LicensingContextType.premium with no xml path
+
+
+Release History
+---------------
+
+The Entry server context is available starting with server version 6.0 
+(Ansys 2023 R2). 
+
+With a server version lower than 6.0, Premium will be the default server 
+context and all the Premium operators at :ref:`ref_dpf_operators_reference` 
+will be available (depending only on their release date).