diff --git a/2025R2/dpf-framework-25-r2/getting-started/configuration.md b/2025R2/dpf-framework-25-r2/getting-started/configuration.md new file mode 100644 index 0000000000..48e93cec6b --- /dev/null +++ b/2025R2/dpf-framework-25-r2/getting-started/configuration.md @@ -0,0 +1,174 @@ +# Configuration + +This page covers the main configuration requirements for your DPF installation: +- Managing plugins: Configure your installation and control the list of plugins loaded by default. +- Setting plugin environments: Define the loading environment for each plugin individually. + +Both configurations are handled through XML files included in the DPF installation. + +Each XML file contains the configuration content for both operating systems. + +They are located alongside the **.dll** file on Windows or **.so** file on Linux of their associated plugin. + +> **CAUTION**: +> To ensure that DPF operates correctly, modify these XML files carefully. +> All paths specified in these XML files must adhere to the path +> conventions of the respective operating system: +> - for Linux paths, use forward slashes (/). +> - for Windows paths, use double backward slashes (\\). + + +## Configure your DPF installation + +The **DataProcessingCore.xml** file contains the configuration related to the plugins loaded by default, plugin search, and environment setup. + +In this XML file, some of the elements are optional, and many of the +elements have Linux-specific versus Windows-specific child elements. + +It follows the structure shown below: + +```html + + + + + + + + + + + + + $(ANSYS_ROOT_FOLDER)/dpf/bin/linx64:$(ANSYS_ROOT_FOLDER)/dpf/plugins + + + + $(ANSYS_ROOT_FOLDER)\dpf\bin\winx64;$(ANSYS_ROOT_FOLDER)\dpf\plugins + + + $(ANSYS_ROOT_FOLDER)\dpf\bin\winx64;$(ANSYS_ROOT_FOLDER)\dpf\plugins + + + + + + + $(ANSYS_ROOT_FOLDER)/dpf/bin/linx64/libAns.Dpf.Native.so + LoadOperators + false + + ... + + + + + $(ANSYS_ROOT_FOLDER)\dpf\bin\winx64\Ans.Dpf.NativeD.dll + LoadOperators + false + + + + + $(ANSYS_ROOT_FOLDER)\dpf\bin\winx64\Ans.Dpf.Native.dll + LoadOperators + false + + ... + + + + +``` + +The **** and **** elements are mandatory and specify the operating system each configuration option applies to. + +The **** and **** elements are optional and allow to differentiate configurations for debug and release versions of DPF. + + +### Environment configuration + +The **** element lets you set the **ANSYS_DPF_ACCEPT_LA** environment variable to **Y** to mark active acceptance of the DPF [license agreement](licensing.md#license-terms) and prevents from having to set it on your machine or at the beginning of every session. + + +### Plugin search path configuration + +The **** element lets you modify where DPF looks for plugins to load at the start of a session. + +To load plugins located outside of the standard DPF installation, prepend the path to the plugin folder to value of the **Path** element. + + +### Default plugins configuration + +The **** element defines the list of plugins to load automatically when the server starts. + +It contains a child element for each plugin, such as ****. + +The element name for a plugin is used as the **key** when loading it. + +Each plugin must have a unique element name/key. + +Each plugin must have the following child elements: + +- **** stores the location of the plugin to load. + The normal mechanism that the operating system uses to find a **.dll** or **.so** file is used. + The **.dll** file could be in the Windows path, or the **.so** file could be in the Linux **LD_LIBRARY_PATH** system environment variable. +- **** defines the entrypoint procedure name to call upon loading the plugin. + In practice this procedure is used to record operators, thus **LoadOperators** is the recommended name. +- **** defines whether to use the **.xml** file located next to it to configure the plugin. + This element is optional. The default value is **true**. + +To provide an absolute path to a plugin, you can use these predefined variables: + +- **ANSYS_ROOT_FOLDER** is the root folder of the Ansys or DPF installation. +- **THIS_XML_FOLDER** is the folder location of the current XML file (here the location of the **DataProcessingCore.xml** file). + +You can also use any other environment variable. For example, if you always have your +plugins in a folder defined by a **MY_PLUGINS** environment variable, you can use +it in the XML file. + +You specify environment variables in the same way as the **ANSYS_ROOT_FOLDER** +or **THIS_XML_FOLDER** variable. They are defined as **$(…)**. + +In the Ansys installation, the default **DataProcessingCore.xml** file is located +next to the **DataProcessingCore** **.dll** or **.so** file. +If you want to use a different one, you can initialize DPF using a specific **DataProcessingCore.xml** file. + + +## Configure a plugin + +Each plugin can define a **.xml** file to configure environment variables used when loading the plugin. + +The structure of the file is as follows: + +```html + + + + $(ANSYS_ROOT_FOLDER)/aisol/dll/linx64:$(ANSYS_ROOT_FOLDER)/aisol/lib/linx64:$(ANSYS_ROOT_FOLDER)/tp/IntelMKL/2020.0.166/linx64/lib/intel64:$(LD_LIBRARY_PATH) + + + $(ANSYS_ROOT_FOLDER)\aisol\bin\winx64;$(ANSYS_ROOT_FOLDER)\tp\IntelMKL\2020.0.166\winx64;$(ANSYS_ROOT_FOLDER)\tp\IntelCompiler\2019.5.281\winx64;$(PATH) + + +``` + +It only contains an **** element which is defined as [described previously](configuration.md#environment-configuration). + +The value of an environment variable is updated each time it is redefined, which means you can modify it in one go or in several elements: + +```html + + + + $(ANSYS_ROOT_FOLDER)/tp/IntelMKL/2020.0.166/linx64/lib/intel64:$(LD_LIBRARY_PATH) + $(ANSYS_ROOT_FOLDER)/aisol/lib/linx64:$(LD_LIBRARY_PATH) + $(ANSYS_ROOT_FOLDER)/aisol/dll/linx64:$(LD_LIBRARY_PATH) + + + $(ANSYS_ROOT_FOLDER)\tp\IntelCompiler\2019.5.281\winx64;$(PATH) + $(ANSYS_ROOT_FOLDER)\tp\IntelMKL\2020.0.166\winx64;$(PATH) + $(ANSYS_ROOT_FOLDER)\aisol\bin\winx64;$(PATH) + + +``` diff --git a/2025R2/dpf-framework-25-r2/getting-started/installation.md b/2025R2/dpf-framework-25-r2/getting-started/installation.md new file mode 100644 index 0000000000..0f56610f98 --- /dev/null +++ b/2025R2/dpf-framework-25-r2/getting-started/installation.md @@ -0,0 +1,69 @@ +# Installation + +DPF is available with the **Ansys installer** in Ansys 2021 R1 and later, or as a pre-release **DPF Server** standalone package for DPF 2023 R2 and later. + + +## Install with the **Ansys installer** + +To install DPF using the Ansys installer, download the standard Ansys installation using your preferred +distribution channel, and install any physics-based Ansys software following the installer instructions. + +Starting with Ansys 2021 R1, DPF is automatically installed along with **Ansys Workbench**. + +**Ansys Workbench** is included with all physics-based Ansys software bundles. + +Check the list of applications included with each product on the Ansys Help website to know which ones include **Ansys Workbench**: + +- [on Windows](https://ansyshelp.ansys.com/public/account/secured?returnurl=/Views/Secured/corp/v252/en/installation/win_product_table.html) +- [in Linux](https://ansyshelp.ansys.com/public/account/secured?returnurl=/Views/Secured/corp/v252/en/installation/lin_product_table.html) + +For information on getting a licensed copy of Ansys, visit the [Ansys website](https://www.ansys.com/). + + +## Install a standalone **DPF Server** + +### Get a **DPF Server** + +The **DPF Server** package provides pre-releases of DPF in the form of a Python package and is independent from the Ansys installer. + +It 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 a pre-release of DPF for Ansys 2023 R2 (_DPF v2023.2.pre0_). + +> Starting with **DPF Server v2023.2.pre1**, the **composites** plugin is also available for Linux. +> +> Starting with **DPF Server v2024.1.pre0**, the **composites** plugin is also available for Linux and Windows. +> +> Starting with **DPF Server v2024.2.pre0**, the **sound** plugin is also available for Windows. + +### Installation steps + +To install a standalone **DPF Server**: + +1. Download the **ansys_dpf_server_win_v20XX.Y.preZ.zip** or **ansys_dpf_server_lin_v20XX.Y.preZ.zip** file as appropriate. +2. Unzip the package. +3. 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_v20XX.Y.preZ.zip** and unzip the package in the same location as **ansys_dpf_server_lin_v20XX.Y.preZ.zip**. +4. Open a terminal and move to the root folder (**ansys_dpf_server_win_v20XX.Y.preZ**) of the unzipped package. +5. Activate your Python environment and run this command: + +```py +pip install -e . +``` + +### License agreement + +As detailed in [Licensing](licensing.md#license-terms), a standalone DPF Server is protected using the license terms specified in the +**DPFPreviewLicenseAgreement** 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: + +```sh +ANSYS_DPF_ACCEPT_LA=Y +``` + +## Licensing + +To use [licensed DPF capabilities](licensing.md#licensing-strategy) you must set the +**ANSYSLMD_LICENSE_FILE** environment variable to point to a valid local or remote license +following indications in [Configure licensing](licensing.md#configure-licensing). diff --git a/2025R2/dpf-framework-25-r2/getting-started/licensing.md b/2025R2/dpf-framework-25-r2/getting-started/licensing.md new file mode 100644 index 0000000000..ca6aadf408 --- /dev/null +++ b/2025R2/dpf-framework-25-r2/getting-started/licensing.md @@ -0,0 +1,162 @@ +# Licensing + +This section describes how to properly set up licensing, as well as limitations and license usage of operators. + + + + +## License terms + +When using the DPF Server from an Ansys installation, you have already agreed to the licensing +terms when installing Ansys. + +When using a standalone DPF Server, you must accept the **DPF Preview License Agreement** by following the indications below. + +Starting a DPF Server without agreeing to the **DPF Preview License Agreement** creates an exception. + +### DPF Preview License Agreement + +The standalone versions of **DPF Server** are protected using license terms specified in the +[DPFPreviewLicenseAgreement](https://download.ansys.com/-/media/dpf/dpfpreviewlicenseagreement.ashx?la=en&hash=CCFB07AE38C638F0D43E50D877B5BC87356006C9) +file that can be found on the [DPF Pre-Release page](https://download.ansys.com/Others/DPF%20Pre-Release) of the Ansys Customer Portal. + +The **DPFPreviewLicenseAgreement** file is a text file, which means that you can open it with a text editor, such as **Notepad**. + +To accept the terms of this license agreement, you must set the following environment variable: + +**`sh +ANSYS_DPF_ACCEPT_LA=Y +**` + +The **ANSYS_DPF_ACCEPT_LA** environment variable confirms your acceptance of the **DPF License Agreement**. + +By passing the value **Y** to this environment variable, you are indicating that you have a valid and +existing license for the edition and version of **DPF Server** that you intend to use. + +You can also [configure a DPF installation](configuration.md#environment-configuration) to mark explicit acceptance for every session. + + + +## Configure licensing + +If your machine does not have a local Ansys installation, you must define where DPF should look for a valid license. + +To use a local license file, set the **ANSYSLMD_LICENSE_FILE** environment +variable to point to an Ansys license file ****: + +**`sh +ANSYSLMD_LICENSE_FILE= +**` + +To use a remote license, set the **ANSYSLMD_LICENSE_FILE** environment +variable to point to an Ansys license server ****: + +**`sh +ANSYSLMD_LICENSE_FILE=1055@ +**` + +For DPF Docker container usage only, you can use the following code to set both the **ANSYS_DPF_ACCEPT_LA** +and **ANSYSLMD_LICENSE_FILE** environment variables. + +> For the **ANSYSLMD_LICENSE_FILE** environment variable, ensure that you replace **** to point to the Ansys license server. + +**`sh +docker run -e "ANSYS_DPF_ACCEPT_LA=Y" -e ANSYSLMD_LICENSE_FILE=1055@ -p 50052:50052 -e DOCKER_SERVER_PORT=50052 --expose=50052 dpf-core:v20XX_Y_preZ +**` + +The next section provides information on +the Ansys licensing strategy that is used with **DPF Server**. + + + +## Licensing strategy + +Some DPF operators require DPF to check for an existing license +and some require DPF to checkout a compatible license increment. + +DPF is by default allowed to checkout license increments as needed. +To change this behavior, see [here](licensing.md#server-context). + +To know if operators require a license increment checkout to run, check their **license** +attribute in the [Operator specifications reference](../operator-specifications/operator-specifications.md). + +To check which Ansys licensing increments correspond to **any_dpf_supported_increments**, +see [Compatible Ansys license increments](licensing.md#compatible-ansys-license-increments). + +Even if an operator does not require a license checkout to run, most DPF operators still require +DPF to check for a reachable license server or license file. + +Operators that do not perform any kind of license check are source operators (data extraction +operators). These operators do not perform any data transformation. + +For example, when considering result operators, they perform data transformation if the requested +location is not the native result location. In that case, averaging occurs which is considered +as data transformation (such as elemental to nodal, nodal to elemental, or any other location change). + + + +### Server context + +You can allow or prevent licensed operators from running and using a license with a +[server context](../user-guide/server-context.md) + +- **Premium:** This default context allows DPF to perform license checkouts, + making licensed DPF operators available. +- **Entry:** This context does not allow DPF to perform any license checkout, + meaning that licensed DPF operators fail. + +Check the documentation of your DPF client to learn how to set the server context. + + + +### Licensing errors + +The following user actions may fail due to licensing: + +- Starting a standalone DPF Server may fail due to the + **DPF Preview License Agreement** (see [here](licensing.md#dpf-preview-license-agreement)). +- Creating an operator may fail if the operator performs data transformation and no license server + or license file is found (see [here](licensing.md#licensing-strategy)). +- Running an operator requiring a license checkout may fail if no + [compatible license increment](licensing.md#compatible-ansys-license-increments) is available or if the DPF Server context is **Entry**, + preventing any license check-out (see [here](licensing.md#server-context)). + + + + +## Compatible Ansys license increments + + +The following Ansys licensing increments provide rights to use the licensed DPF capabilities: + +- **preppost** available in the **Ansys Mechanical Enterprise PrepPost** product +- **meba** available in the **ANSYS Mechanical Enterprise Solver** product +- **mech_2** available in the **ANSYS Mechanical Premium** product +- **mech_1** available in the **ANSYS Mechanical Pro** product +- **ansys** available in the **ANSYS Mechanical Enterprise** product +- **dynapp** available in the **ANSYS LS-DYNA PrepPost** product +- **dyna** available in the **ANSYS LS-DYNA** product +- **vmotion** available in the **Ansys Motion** product +- **acpreppost** available in the **Ansys Mechanical Enterprise** product +- **acdi_adprepost** available in the **Ansys AUTODYN** and **Ansys AUTODYN PrepPost** products +- **cfd_preppost** available in the **Ansys CFD Enterprise** product +- **cfd_preppost_pro** available in the **Ansys CFD Enterprise** product +- **vmotion_post** available in the **Ansys Motion Post** product +- **vmotion_pre** available in the **Ansys Motion Pre** product +- **advanced_meshing** available in the **Ansys CFD Enterprise** product +- **fluent_meshing_pro** available in the **Ansys CFD Enterprise** product +- **fluent_setup_post** available in the **Ansys CFD Enterprise** product +- **fluent_setup_post_pro** available in the **Ansys CFD Enterprise** product +- **acfx_pre** available in the **Ansys CFD Enterprise** product +- **cfd_base** available in the **Ansys CFD Enterprise** product +- **cfd_solve_level1** available in the **Ansys CFD Enterprise** product +- **cfd_solve_level2** available in the **Ansys CFD Enterprise** product +- **cfd_solve_level3** available in the **Ansys CFD Enterprise** product +- **fluent_meshing** available in the **Ansys CFD Enterprise** product +- **avrxp_snd_level1** available in the **Ansys Sound Pro** product +- **sherlock** available in the **Ansys Sherlock** product + +Each increment may be available in other products. + +On the Ansys Customer Portal, the [Licensing section](https://download.ansys.com/Installation%20and%20Licensing%20Help%20and%20Tutorials) +provides product/increment mapping. diff --git a/2025R2/dpf-framework-25-r2/index.md b/2025R2/dpf-framework-25-r2/index.md index cd8a1fdead..632aa7a63f 100644 --- a/2025R2/dpf-framework-25-r2/index.md +++ b/2025R2/dpf-framework-25-r2/index.md @@ -1,6 +1,15 @@ # Introduction -This documentation provides a comprehensive guide of the DPF framework as well as all DPF operators available in ANSYS-made DPF plugins. It is organized into key sections, including core concepts, getting started tutorials, and detailed documentation of available operators. Whether you are new to DPF or looking for information on operators, this guide offers the necessary resources to understand and use DPF effectively in your workflows. +This documentation provides a comprehensive guide of the DPF framework as well as all DPF operators available in Ansys-made DPF plugins. + +The content is organized into the following sections: + +- Getting started: Learn how to install, license, and configure DPF. +- User guide: Understand the server context, work with data containers and operators, and explore workflow examples. +- Core concepts: Review essential DPF concepts and available data types. +- Operator specifications: Access detailed reference documentation for all available operators. + +Whether you are setting up DPF for the first time or looking for in-depth operator details, this guide provides the resources needed to use DPF effectively in your workflows. ## Overview of DPF @@ -59,6 +68,7 @@ DPF is available with the **Ansys installer** in Ansys 2021 R1 and later, or as - The DPF Server package provides pre-releases of DPF and is independent of the Ansys installer. It is available on the [DPF Pre-Release page](https://download.ansys.com/Others/DPF%20Pre-Release) of the Ansys Customer Portal. +See [`Installation`](getting-started/installation.md) in the Getting started for more information. ### Operating system compatibility diff --git a/2025R2/dpf-framework-25-r2/operator-specifications/operator-specifications.md b/2025R2/dpf-framework-25-r2/operator-specifications/operator-specifications.md new file mode 100644 index 0000000000..495ea8c184 --- /dev/null +++ b/2025R2/dpf-framework-25-r2/operator-specifications/operator-specifications.md @@ -0,0 +1,2 @@ +# Operator specifications reference + diff --git a/2025R2/dpf-framework-25-r2/toc.yml b/2025R2/dpf-framework-25-r2/toc.yml index ebe55a6177..51727d2e62 100644 --- a/2025R2/dpf-framework-25-r2/toc.yml +++ b/2025R2/dpf-framework-25-r2/toc.yml @@ -2,12 +2,23 @@ href: index.md - name: Getting started items: + - name: Installation + href: getting-started/installation.md + - name: Licensing + href: getting-started/licensing.md + - name: Configuration + href: getting-started/configuration.md + items: +- name: User guide + items: + - name: The server context + href: user-guide/server-context.md - name: How to use data containers - href: getting-started/using-data-containers.md + href: user-guide/using-data-containers.md - name: How to use operators - href: getting-started/using-operators.md + href: user-guide/using-operators.md - name: Workflow examples for beginners - href: getting-started/workflow-examples.md + href: user-guide/workflow-examples.md - name: Core concepts items: - name: Available types @@ -16,6 +27,8 @@ href: core-concepts/operator.md - name: Operator specifications items: + - name: Operator specifications + href: operator-specifications/operator-specifications.md - name: averaging items: - name: elemental difference diff --git a/2025R2/dpf-framework-25-r2/user-guide/server-context.md b/2025R2/dpf-framework-25-r2/user-guide/server-context.md new file mode 100644 index 0000000000..98a0e0d40b --- /dev/null +++ b/2025R2/dpf-framework-25-r2/user-guide/server-context.md @@ -0,0 +1,19 @@ +# DPF server context + +The server context drives the licensing logic a DPF server uses. + +## Available licensing context + +Two main licensing context type capabilities are available: + +- **Premium:** This default context allows DPF to perform license checkouts, + making licensed DPF operators available. +- **Entry:** This context does not allow DPF to perform any license checkout, + meaning that licensed DPF operators fail. + +## Default context + +The default context for the server is **Premium**. You can change the default context using +the **ANSYS_DPF_SERVER_CONTEXT** environment variable. + +The **Entry** server context is only available in DPF 2023 R2 and later. diff --git a/2025R2/dpf-framework-25-r2/getting-started/using-data-containers.md b/2025R2/dpf-framework-25-r2/user-guide/using-data-containers.md similarity index 100% rename from 2025R2/dpf-framework-25-r2/getting-started/using-data-containers.md rename to 2025R2/dpf-framework-25-r2/user-guide/using-data-containers.md diff --git a/2025R2/dpf-framework-25-r2/getting-started/using-operators.md b/2025R2/dpf-framework-25-r2/user-guide/using-operators.md similarity index 100% rename from 2025R2/dpf-framework-25-r2/getting-started/using-operators.md rename to 2025R2/dpf-framework-25-r2/user-guide/using-operators.md diff --git a/2025R2/dpf-framework-25-r2/getting-started/workflow-examples.md b/2025R2/dpf-framework-25-r2/user-guide/workflow-examples.md similarity index 100% rename from 2025R2/dpf-framework-25-r2/getting-started/workflow-examples.md rename to 2025R2/dpf-framework-25-r2/user-guide/workflow-examples.md