diff --git a/.ci/azure-pipelines.yml b/.ci/azure-pipelines.yml index 198e7b56f92..1564a5347af 100644 --- a/.ci/azure-pipelines.yml +++ b/.ci/azure-pipelines.yml @@ -20,7 +20,6 @@ pr: exclude: - '*' - jobs: - job: Windows variables: @@ -130,7 +129,7 @@ jobs: docker pull $(DPF_IMAGE) docker run --restart always --name dpf -v `pwd`:/dpf -v /tmp:/dpf/_cache -p $(DPF_PORT):50054 $(DPF_IMAGE) > log.txt & grep -q 'server started on ip' <(timeout 60 tail -f log.txt) - python -c "from ansys.dpf import core; core.connect_to_server(port=$(DPF_PORT)); print('Python Connected')" + python -c "from ansys.dpf import core as dpf; dpf.connect_to_server(port=$(DPF_PORT)); print('Python Connected')" displayName: Pull, launch, and validate DPF service - script: | @@ -140,44 +139,13 @@ jobs: pytest -v --junitxml=junit/test-results.xml --cov ansys.dpf.core --cov-report=xml --cov-report=html displayName: Test Core API - -# - script: | -# .ci/setup_headless_display.sh -# pip install -r .ci/requirements_test_xvfb.txt -# python .ci/display_test.py -# displayName: Install and start a virtual framebuffer - - -# - script: | -# set -ex -# echo $(PAT) | docker login -u $(GH_USERNAME) --password-stdin docker.pkg.github.com -# docker pull $(MAPDL_IMAGE) -# docker run -e ANSYSLMD_LICENSE_FILE=1055@$(LICENSE_SERVER) --restart always --name mapdl -p $(PYMAPDL_PORT):50052 $(MAPDL_IMAGE) -smp & -# python -c "from ansys.mapdl import launch_mapdl; print(launch_mapdl())" -# displayName: Pull, launch, and validate MAPDL service - -# - script: | -# pip install -r requirements_test.txt -# pip install pytest-azurepipelines -# pytest -v --junitxml=junit/test-results.xml --cov --cov-report=xml --cov-report=html -# displayName: 'Test Core API' - - # - template: build_documentation.yml # path is relative - - # - script: | - # bash <(curl -s https://codecov.io/bash) - # displayName: 'Upload coverage to codecov.io' - # condition: eq(variables['python.version'], '3.7') - - # - script: | - # pip install twine - # python setup.py sdist - # twine upload --skip-existing dist/pyvista* - # displayName: 'Upload to PyPi' - # condition: and(eq(variables['python.version'], '3.7'), contains(variables['Build.SourceBranch'], 'refs/tags/')) - # env: - # TWINE_USERNAME: $(twine.username) - # TWINE_PASSWORD: $(twine.password) - # TWINE_REPOSITORY_URL: "https://upload.pypi.org/legacy/" - - + - script: | + pip install twine + python setup.py sdist + twine upload --skip-existing dist/* + displayName: 'Upload to PyPi' + condition: contains(variables['Build.SourceBranch'], 'refs/tags/') + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: $(PYPI_TOKEN) + TWINE_REPOSITORY_URL: "https://upload.pypi.org/legacy/" diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml index 9277deb1fb0..553784808fe 100644 --- a/.github/workflows/ci-build.yml +++ b/.github/workflows/ci-build.yml @@ -3,8 +3,8 @@ name: Documentation Build on: [push, pull_request, workflow_dispatch] + jobs: - # This workflow contains a single job called "build" build: runs-on: ubuntu-20.04 @@ -50,13 +50,13 @@ jobs: env: GH_USERNAME: ${{ secrets.GH_USERNAME }} PAT: ${{ secrets.REPO_DOWNLOAD_PAT }} - - + - name: Build Documentation run: | sudo apt install pandoc -qy pip install -r requirements_docs.txt make -C docs html + touch docs/build/html/.nojekyll - name: Upload Documentation uses: actions/upload-artifact@v2.2.1 @@ -64,3 +64,12 @@ jobs: name: Documentation path: docs/build/html retention-days: 7 + + - name: Deploy + uses: JamesIves/github-pages-deploy-action@3.7.1 + if: startsWith(github.ref, 'refs/tags/') + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BRANCH: gh-pages + FOLDER: docs/build/html + CLEAN: true diff --git a/README.md b/README.md index 2e47fea739c..2185ec38b24 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,89 @@ -# DPF - ANSYS Data Processing Framework +# DPF - Ansys Data Processing Framework + +The Data Processing Framework (DPF) is designed to provide numerical +simulation users/engineers with a toolbox for accessing and +transforming simulation data. DPF can access data from solver result +files as well as several neutral formats (csv, hdf5, vtk, +etc.). Various operators are available allowing the manipulation and +the transformation of this data. + +DPF is a workflow-based framework which allows simple and/or complex +evaluations by chaining operators. The data in DPF is defined based on +physics agnostic mathematical quantities described in a +self-sufficient entity called field. This allows DPF to be a modular +and easy to use tool with a large range of capabilities. It's a +product designed to handle large amount of data. + +The Python ``ansys.dpf.core`` module provides a Python interface to +the powerful DPF framework enabling rapid post-processing of a variety +of Ansys file formats and physics solutions without ever leaving a +Python environment. ## Installation -Clone and install this repository with: +Install this repository with: ``` -git clone https://github.com/pyansys/DPF-Core -cd DPF-Core -pip install . --user +pip install ansys-dpf-core ``` -Install any missing libraries from Artifactory with: +You can also clone and install this repository with: ``` -pip install --extra-index-url=http://canartifactory.ansys.com:8080/artifactory/api/pypi/pypi/simple --trusted-host canartifactory.ansys.com ansys-grpc-dpf +git clone https://github.com/pyansys/DPF-Core +cd DPF-Core +pip install . --user ``` -This step will be eliminated once DPF is live on PyPi. - ## Running DPF +### Brief Demo Provided you have ANSYS 2021R1 installed, a DPF server will start -automatically once you start using DPF: +automatically once you start using DPF. +Opening a result file generated from Ansys workbench or MAPDL is as easy as: -```py -from ansys.dpf import core +``` +>>> from ansys.dpf.core import Model +>>> model = Model('file.rst') +>>> print(model) +DPF Model +------------------------------ +Static analysis +Unit system: Metric (m, kg, N, s, V, A) +Physics Type: Mecanic +Available results: + - displacement + - element_nodal_forces + - volume + - energy_stiffness_matrix + - hourglass_energy + - thermal_dissipation_energy + - kinetic_energy + - co_energy + - incremental_energy + - temperature +``` + +Open up an result with: -norm = core.Operator('norm_fc') +```py +>>> model.displacement +``` -# or open up a model -model = core.Model('file.rst') +Then start linking operators with: +```py +>>> norm = core.Operator('norm_fc') ``` -The `ansys.dpf.core` module takes care of starting your local server -for you so you don't have to. If you need to connect to a remote DPF -instance, use the ``connect_to_server`` function: +### Starting the Service + +The `ansys.dpf.core` automatically starts the DPF service in the +background and connects to it. If you need to connect to an existing +remote DPF instance, use the ``connect_to_server`` function: ```py from ansys.dpf import core @@ -48,26 +93,3 @@ connect_to_server('10.0.0.22, 50054) Once connected, this connection will remain for the duration of the module until you exit python or connect to a different server. - -## Unit Testing - -Unit tests can be run by first installing the testing requirements with `pip install -r requirements_test.txt` and then running pytest with: - -``` -pytest -``` - -If you have ANSYS v2021R1 installed locally, the unit tests will -automatically start up the DPF server and run the tests. If you need -to disable this and have the unit tests run against a remote server, -setup the following environment variables: - -``` -set DPF_START_SERVER=False -set DPF_IP= -set DPF_PORT= -``` - - -## Examples -See the example scripts in the examples folder for some basic examples. diff --git a/ansys/dpf/core/data_sources.py b/ansys/dpf/core/data_sources.py index 64418392dc6..9437d05b981 100644 --- a/ansys/dpf/core/data_sources.py +++ b/ansys/dpf/core/data_sources.py @@ -9,8 +9,8 @@ class DataSources: """Represent the file sources of a model. Initialize the data_sources with either optional data_sources - message, or by connecting to a stub A Result path can be - directly set + message, or by connecting to a stub. Result path can also be + directly set. Parameters ---------- diff --git a/ansys/dpf/core/operators_helper.py b/ansys/dpf/core/operators_helper.py index 87ef39c0b90..d8dde6523bd 100644 --- a/ansys/dpf/core/operators_helper.py +++ b/ansys/dpf/core/operators_helper.py @@ -1,4 +1,8 @@ -"""Wrappers for operators""" +"""Wrappers for DPF operators. + +These operators are available as functions from ``dpf.operators`` and +simplify the creation of new chained operators. +""" from ansys import dpf from ansys.dpf.core.common import types as dpf_types diff --git a/ansys/dpf/core/plotter.py b/ansys/dpf/core/plotter.py index 324d434f031..3620e955dd8 100644 --- a/ansys/dpf/core/plotter.py +++ b/ansys/dpf/core/plotter.py @@ -1,6 +1,7 @@ """Dpf plotter class is contained in this module. -Allows to plot a mesh and a fields container -using pyvista.""" + +Allows to plot a mesh and a fields container using pyvista. +""" import tempfile import pyvista as pv @@ -16,6 +17,8 @@ class Plotter: + """Internal class used by DPF-Core to plot fields and meshed regions""" + def __init__(self, mesh): self._mesh = mesh diff --git a/docker/env.sh b/docker/env.sh new file mode 100644 index 00000000000..d6ab447005b --- /dev/null +++ b/docker/env.sh @@ -0,0 +1,5 @@ +# Setup the testing environment using docker +# run with: +# source env.sh +export DPF_START_SERVER=FALSE +export DPF_DOCKER=True diff --git a/docs/source/api/data_sources.rst b/docs/source/api/data_sources.rst new file mode 100644 index 00000000000..7cd175cb6d7 --- /dev/null +++ b/docs/source/api/data_sources.rst @@ -0,0 +1,6 @@ +****************** +Data Sources Class +****************** +.. autoclass:: ansys.dpf.core.data_sources.DataSources + :members: + :private-members: diff --git a/docs/source/api/element.rst b/docs/source/api/element.rst new file mode 100644 index 00000000000..3806c3c809b --- /dev/null +++ b/docs/source/api/element.rst @@ -0,0 +1,5 @@ +************* +Element Class +************* +.. autoclass:: ansys.dpf.core.meshed_region.Element + :members: diff --git a/docs/source/api/elements.rst b/docs/source/api/elements.rst new file mode 100644 index 00000000000..88034ec4664 --- /dev/null +++ b/docs/source/api/elements.rst @@ -0,0 +1,5 @@ +************** +Elements Class +************** +.. autoclass:: ansys.dpf.core.meshed_region.Elements + :members: diff --git a/docs/source/api/field.rst b/docs/source/api/field.rst new file mode 100644 index 00000000000..934e4c826df --- /dev/null +++ b/docs/source/api/field.rst @@ -0,0 +1,5 @@ +*********** +Field Class +*********** +.. autoclass:: ansys.dpf.core.field.Field + :members: diff --git a/docs/source/api/fieldscontainer.rst b/docs/source/api/fieldscontainer.rst new file mode 100644 index 00000000000..a68c639ce5e --- /dev/null +++ b/docs/source/api/fieldscontainer.rst @@ -0,0 +1,5 @@ +********************* +FieldsContainer Class +********************* +.. autoclass:: ansys.dpf.core.fields_container.FieldsContainer + :members: diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst index b95ca25636d..11c50dac8ba 100644 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.rst @@ -1,79 +1,21 @@ -.. _dpf_model_functions_ref: +.. _ref_api_index: ============= API Reference ============= -Details of the DPF API. +This section gives an overview of the API of several public DPF-Core +classes and functions. .. toctree:: - :maxdepth: 2 - :hidden: + :maxdepth: 1 - operators - - -Model Class ------------ -The model class encapsulates several operators and methods and is used to streamline reading and plotting result files. - -.. autoclass:: ansys.dpf.core.model.Model - :members: - :private-members: - - -Operator Class --------------- -The ``dpf.Operator`` class used to represent an Operator which is an -elementary operation. - -.. autoclass:: ansys.dpf.core.dpf_operator.Operator - :members: - - -FieldsContainer Class ---------------------- -.. autoclass:: ansys.dpf.core.fields_container.FieldsContainer - :members: - - -Field Class ------------ -.. autoclass:: ansys.dpf.core.field.Field - :members: - - -Wrapped Operators ------------------ -These operators are available as functions from ``dpf.operators`` and -simplify the creation of new chained operators. - - .. automodule:: ansys.dpf.core.operators_helper - :members: - - -.. - Plotting - -------- - The ``ansys.dpf.plotting`` module contains several plotting functions to simplify the creation of plots within Jupyter notebooks. - - .. automodule:: ansys.dpf.plotting - :members: - - -MeshedRegion Class ------------------- -.. autoclass:: ansys.dpf.core.meshed_region.MeshedRegion - :members: - :noindex: elements - - -Elements Class --------------- -.. autoclass:: ansys.dpf.core.meshed_region.Elements - :members: - - -Element Class --------------- -.. autoclass:: ansys.dpf.core.meshed_region.Element - :members: + data_sources + element + elements + field + fieldscontainer + meshed_region + model + operator + plotting + wrapped_operators diff --git a/docs/source/api/meshed_region.rst b/docs/source/api/meshed_region.rst new file mode 100644 index 00000000000..32e7eacb2fb --- /dev/null +++ b/docs/source/api/meshed_region.rst @@ -0,0 +1,5 @@ +MeshedRegion Class +------------------ +.. autoclass:: ansys.dpf.core.meshed_region.MeshedRegion + :members: + :noindex: elements diff --git a/docs/source/api/model.rst b/docs/source/api/model.rst new file mode 100644 index 00000000000..fd5385c3935 --- /dev/null +++ b/docs/source/api/model.rst @@ -0,0 +1,9 @@ +*********** +Model Class +*********** +The model class encapsulates several operators and methods and is used +to streamline reading and plotting result files. + +.. autoclass:: ansys.dpf.core.model.Model + :members: + :private-members: diff --git a/docs/source/api/operator.rst b/docs/source/api/operator.rst new file mode 100644 index 00000000000..9fe20666746 --- /dev/null +++ b/docs/source/api/operator.rst @@ -0,0 +1,8 @@ +************** +Operator Class +************** +The ``dpf.Operator`` class used to represent an Operator which is an +elementary operation. + +.. autoclass:: ansys.dpf.core.dpf_operator.Operator + :members: diff --git a/docs/source/api/plotting.rst b/docs/source/api/plotting.rst new file mode 100644 index 00000000000..a7bc51f4543 --- /dev/null +++ b/docs/source/api/plotting.rst @@ -0,0 +1,6 @@ +************* +Plotter Class +************* + + .. automodule:: ansys.dpf.core.plotter.Plotter + :members: diff --git a/docs/source/api/wrapped_operators.rst b/docs/source/api/wrapped_operators.rst new file mode 100644 index 00000000000..81b624791cc --- /dev/null +++ b/docs/source/api/wrapped_operators.rst @@ -0,0 +1,5 @@ +***************** +Wrapped Operators +***************** + .. automodule:: ansys.dpf.core.operators_helper + :members: diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst index ecb9bcb1994..8f73fd201b5 100644 --- a/docs/source/getting_started/index.rst +++ b/docs/source/getting_started/index.rst @@ -5,7 +5,6 @@ To use the native DPF server, you need to have a local installation of Ansys 2021R1. Visit https://www.ansys.com/ for more information on getting a licensed copy of Ansys. - .. toctree:: :hidden: :maxdepth: 2 diff --git a/docs/source/index.rst b/docs/source/index.rst index c7c72fc7406..661d040834d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -82,3 +82,4 @@ framework. api/index examples/index contributing + woa diff --git a/docs/source/user_guide/model.rst b/docs/source/user_guide/model.rst index 218c516a125..5d7699d23fe 100644 --- a/docs/source/user_guide/model.rst +++ b/docs/source/user_guide/model.rst @@ -1,6 +1,5 @@ .. _user_guide_model: - ************* The DPF Model ************* diff --git a/testing.md b/testing.md new file mode 100644 index 00000000000..67d465bb8df --- /dev/null +++ b/testing.md @@ -0,0 +1,20 @@ + + +## Unit Testing + +Unit tests can be run by first installing the testing requirements with `pip install -r requirements_test.txt` and then running pytest with: + +``` +pytest +``` + +If you have ANSYS v2021R1 installed locally, the unit tests will +automatically start up the DPF server and run the tests. If you need +to disable this and have the unit tests run against a remote server, +setup the following environment variables: + +``` +set DPF_START_SERVER=False +set DPF_IP= +set DPF_PORT= +```