diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst deleted file mode 100644 index da6af87b0..000000000 --- a/doc/source/getting-started.rst +++ /dev/null @@ -1,20 +0,0 @@ -Getting started -############### - -To run PyAdditive, you must have a licensed copy of `Ansys Additive`_. - -.. grid:: 2 - - .. grid-item-card:: Installing PyAdditive :fab:`python` - :link: getting-started/installation - :link-type: doc - - Learn how to download and install PyAdditive in your development - environment from various official sources including PyPI and official - Ansys repositories. - -.. toctree:: - :maxdepth: 3 - :hidden: - - getting-started/installation diff --git a/doc/source/getting-started/index.rst b/doc/source/getting-started/index.rst index ea8d2969f..17f39bad6 100644 --- a/doc/source/getting-started/index.rst +++ b/doc/source/getting-started/index.rst @@ -10,13 +10,30 @@ PyAdditive is a Python client library for the Ansys Additive server. The Ansys Additive server is distributed with the Additive option of the Structures package in the Ansys unified installation. -.. note:: - PyAdditive requires Ansys 2024 R1 or later. - .. warning:: The simulations described in this documentation require an Additive Suite license. To obtain a license, contact your Ansys sales representative or see https://www.ansys.com/contact-us. +Compatibility +============= + +To use all the features of PyAdditive, you must have a compatible version of Ansys installed. +The following table lists the compatibility between PyAdditive and Ansys releases. + +.. list-table:: + :header-rows: 1 + :width: 50% + :align: left + + * - PyAdditive Version + - Ansys Release Version + * - 0.19.x + - 2025 R1 + * - 0.18.x + - 2024 R2 + * - 0.17.x + - 2024 R1 + Starting a session ================== @@ -60,140 +77,163 @@ For examples of the types of simulations possible with PyAdditive, see -Installation -============ - -Package dependencies --------------------- +User installation +================= -PyAdditive is supported on Python version 3.10 and later. Previous versions of Python are -no longer supported. +There are multiple sources for installing the latest stable version of +PyAdditive. These include ``pip`` and ``GitHub``. -PyAdditive dependencies are automatically checked when packages are installed. Included -in these dependencies are these projects: -* `ansys-api-additive `_: Python package containing the auto-generated - gRPC Python interface files for the Additive service -* `NumPy `_: Fundamental package for scientific computing with Python, providing - data array access for PyAdditive -* `PyVista `_: 3D visualization library for interactive 3D plotting of - PyAdditive results. -* `Panel `_: Web app framework used for interactive visualization - of PyAdditive results. +.. jinja:: install_guide + .. tab-set:: -Install the package -------------------- + .. tab-item:: Public PyPI -PyAdditive has three installation modes: user, developer, and offline. + .. code-block:: -Install in user mode -^^^^^^^^^^^^^^^^^^^^ + python -m pip install ansys-additive-core -Install `Python `_ if it is not already installed. + .. tab-item:: Ansys PyPI -Before installing PyAdditive in user mode, run this command to make sure that you have the latest version -of `pip `_: + .. code-block:: -.. code:: bash + export PIP_EXTRA_INDEX_URL="https://${PYANSYS_PYPI_PRIVATE_PAT}@pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi/simple/" + python -m pip install ansys-additive-core - python -m pip install -U pip + .. tab-item:: GitHub -Then, run this command to install PyAdditive: + .. code-block:: -.. code:: bash + python -m pip install git+https://github.com/ansys/pyadditive.git@{{ version }} - python -m pip install ansys-additive-core .. _ref_install_in_developer_mode: -Install in developer mode -^^^^^^^^^^^^^^^^^^^^^^^^^ +Developer installation +====================== + +Developer installation is specifically intended for project maintainers. +This specialized installation is tailored to equip developers with the essential +tools and resources required for effective contribution to the project's +development and maintenance. The developer installation assumes a certain level +of technical expertise and familiarity with the project's codebase, rendering it +most suitable for individuals actively engaged in its continuous development and +maintenance. + +Start by cloning the repository: + +.. code-block:: + + git clone git@github.com:ansys/pyadditive + + +Move inside the project and create a new Python environment: + +.. tab-set:: + + .. tab-item:: Windows -Installing PyAdditive in developer mode allows you to modify the source code and enhance it. + .. tab-set:: -.. note:: - Before contributing to PyAdditive, see the `Contributing `_ topic - in the *PyAnsys Developer's Guide*. You should be thoroughly familiar with this guide. + .. tab-item:: CMD -To install PyAdditive in developer mode, perform these steps: + .. code-block:: text -#. Clone the repository and access the directory where it has been cloned: + py -m venv - .. code:: bash + .. tab-item:: PowerShell - git clone https://github.com/ansys/pyadditive - cd pyadditive + .. code-block:: text -#. Create a clean Python virtual environment and activate it: + py -m venv - .. code:: bash + .. tab-item:: Linux/UNIX - # Create a virtual environment - python -m venv .venv + .. code-block:: text - # Activate it in a POSIX system - source .venv/bin/activate + python -m venv - # Activate it in Windows CMD shell - .venv\Scripts\activate.bat +Activate previous environment: - # Activate it in Windows Powershell - .venv\Scripts\Activate.ps1 +.. tab-set:: - If you require additional information on virtual environments, see `Creation of virtual environments - `_ in the Python documentation. + .. tab-item:: Windows -#. Install the required build system tools: + .. tab-set:: - .. code:: bash + .. tab-item:: CMD - python -m pip install -U pip tox + .. code-block:: text -#. Verify your development installation: + \Scripts\activate.bat - .. code:: bash + .. tab-item:: PowerShell - tox -e py + .. code-block:: text -#. Optionally, install the project in editable mode: + \Scripts\Activate.ps1 - .. code:: bash + .. tab-item:: Linux/UNIX - python -m pip install -e . + .. code-block:: text -#. When finished, you can exit the virtual environment: + source /bin/activate - .. code:: bash +Install the required build system tools: - deactivate +.. code-block:: + + python -m pip install -U pip tox + +Verify your development installation: + +.. code-block:: + + tox -e py + +Install the project in editable mode. This means that any changes you make to +the package's source code immediately reflect in your project without requiring you +to reinstall it. + +.. code-block:: + + python -m pip install --editable . + + +When finished, you can exit the virtual environment: + +.. code-block:: + + deactivate Install in offline mode -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- -If you lack an internet connection on your installation machine (or you do not have access to the -private Ansys PyPI packages repository), you should install PyAdditive by downloading the wheelhouse -archive from the `Releases `_ page for your +If you lack an internet connection on your installation machine, you should install +PyAdditive by downloading the wheelhouse archive from the +`Releases `_ page for your corresponding machine architecture. Each wheelhouse archive contains all the Python wheels necessary to install PyAdditive from scratch on Windows, -Linux, and MacOS from Python 3.10 to 3.12. You can unzip and install the wheelhouse archive on an isolated +Linux, and MacOS. You can unzip and install the wheelhouse archive on an isolated system with a fresh Python installation or in a virtual environment. -For example, on Linux with Python 3.10, unzip then install the wheelhouse archive with these commands: +For example, on Linux with Python 3.12, unzip then install the wheelhouse archive with these commands: -.. code:: bash +.. code-block:: - unzip ansys-additive-core-v0.1.dev0-wheelhouse-Linux-3.10.zip wheelhouse + unzip ansys-additive-core-v0.1.0-wheelhouse-Linux-3.12.zip wheelhouse pip install ansys-additive-core -f wheelhouse --no-index --upgrade --ignore-installed -If you're on Windows with Python 3.10, unzip the wheelhouse archive to a wheelhouse directory and +If you're on Windows, unzip the wheelhouse archive to a wheelhouse directory and then install using the preceding ``pip`` command. Consider using a virtual environment for the installation. Testing +======= This project takes advantage of `tox`_. This tool automates common development tasks (similar to Makefile), but it is oriented towards Python @@ -225,21 +265,27 @@ and `flake8`_ and call unit testing commands like `pytest`_. However, this does not guarantee that your project is being tested in an isolated environment, which is the reason why tools like ``tox`` exist. -To run unit tests without using ``tox``, first install the ``pytest-cov`` package in -editable mode: +To run unit tests without using ``tox``, first install the ``tests`` dependencies. -.. code:: bash +.. code-block:: - python -m pip install pytest-cov - - python -m pip install -e . + python -m pip install -e .[tests] Then, run this command from the root folder of the project: -.. code:: bash +.. code-block:: python -m pytest +Debugging with Visual Studio Code +--------------------------------- + +Support for Python debugging is built into Visual Studio Code. However, +to stop on break points in unit tests, you must +comment out the ``addopts`` line in ``pyproject.toml``. The coverage flags +for ``pytest`` prevent the debugger from stopping at breakpoints. Restore +the ``addopts`` line when you are finished debugging. + System testing on localhost --------------------------- @@ -253,7 +299,7 @@ converted to Jupyter notebooks using To test with a notebook, you need to install and run `JupyterLab `_: -.. code:: bash +.. code-block:: python -m venv jupyter_venv​ @@ -269,15 +315,22 @@ To test with a notebook, you need to install and run The URL for opening JupyterLab in your browser is ``http://localhost:8888/lab``. Note that the port number may be different, but the port number is listed in the JupyterLab startup messages. -A note on ``pre-commit`` -^^^^^^^^^^^^^^^^^^^^^^^^ +Adhere to code style +-------------------- + +PyAdditive follows the PEP8 standard as outlined in +`PEP 8 `_ in +the *PyAnsys Developer's Guide* and implements style checking using +`pre-commit `_. + +To ensure your code meets minimum code styling standards, run these commands:: -The style checks take advantage of `pre-commit`_. Developers are not forced but -encouraged to install this tool by running this command: + pip install pre-commit + pre-commit run --all-files -.. code:: bash +You can also install this as a pre-commit hook by running this command:: - python -m pip install pre-commit && pre-commit install + pre-commit install Documentation @@ -286,13 +339,13 @@ Documentation For building documentation, you can run the usual rules provided in the `Sphinx`_ Makefile, such as: -.. code:: bash +.. code-block:: make -C doc/ html && your_browser_name doc/html/index.html However, the recommended way of checking documentation integrity is to use ``tox``: -.. code:: bash +.. code-block:: tox -e doc && your_browser_name .tox/doc_out/index.html @@ -303,7 +356,7 @@ Distributing If you would like to create either source or wheel files, start by installing the building requirements and then executing the build module: -.. code:: bash +.. code-block:: python -m pip install -U pip build twine python -m build diff --git a/doc/source/getting-started/installation.rst b/doc/source/getting-started/installation.rst deleted file mode 100644 index 77fc759ea..000000000 --- a/doc/source/getting-started/installation.rst +++ /dev/null @@ -1,114 +0,0 @@ -Installing PyAdditive -##################### - -Installing PyAdditive is as simple as installing a Python library. However, a -running instance of `Ansys Additive`_ is required to use PyAdditive. - -User installation -================= - -There are multiple sources for installing the latest stable version of -PyAdditive. These include ``pip`` and ``GitHub``. - - -.. jinja:: install_guide - - .. tab-set:: - - .. tab-item:: Public PyPI - - .. code-block:: - - python -m pip install ansys-additive-core - - .. tab-item:: Ansys PyPI - - .. code-block:: - - export PIP_EXTRA_INDEX_URL="https://${PYANSYS_PYPI_PRIVATE_PAT}@pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi/simple/" - python -m pip install ansys-additive-core - - .. tab-item:: GitHub - - .. code-block:: - - python -m pip install git+https://github.com/ansys/pyadditive.git@{{ version }} - - -Developer installation -====================== - -Developer installation is specifically intended for project maintainers. -This specialized installation is tailored to equip developers with the essential -tools and resources required for effective contribution to the project's -development and maintenance. The developer installation assumes a certain level -of technical expertise and familiarity with the project's codebase, rendering it -most suitable for individuals actively engaged in its continuous development and -maintenance. - -Start by cloning the repository: - -.. code-block:: - - git clone git@github.com:ansys/pyadditive - - -Move inside the project and create a new Python environment: - -.. tab-set:: - - .. tab-item:: Windows - - .. tab-set:: - - .. tab-item:: CMD - - .. code-block:: text - - py -m venv - - .. tab-item:: PowerShell - - .. code-block:: text - - py -m venv - - .. tab-item:: Linux/UNIX - - .. code-block:: text - - python -m venv - -Activate previous environment: - -.. tab-set:: - - .. tab-item:: Windows - - .. tab-set:: - - .. tab-item:: CMD - - .. code-block:: text - - \Scripts\activate.bat - - .. tab-item:: PowerShell - - .. code-block:: text - - \Scripts\Activate.ps1 - - .. tab-item:: Linux/UNIX - - .. code-block:: text - - source /bin/activate - -Install the project in editable mode. This means that any changes you make to -the package's source code immediately reflect in your project without requiring you -to reinstall it. - -.. code-block:: - - python -m pip install --editable . diff --git a/doc/source/index.rst b/doc/source/index.rst index 725dc1047..ebd036d3c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,14 +1,16 @@ PyAdditive documentation |version| ################################### -PyAdditive provides a Python API to interact with `Ansys Additive`_. +PyAdditive provides a Python API to interact with the Ansys Additive server. +The Additive server is included in the Additive option of the Structures package +of the Ansys release. .. grid:: 2 .. grid-item-card:: Getting started :fa:`person-running` - :link: getting-started - :link-type: doc + :link: ref_getting_started + :link-type: ref Step-by-step guidelines on how to set up your environment to work with PyAdditive. @@ -53,7 +55,7 @@ PyAdditive provides a Python API to interact with `Ansys Additive`_. :hidden: :maxdepth: 2 - getting-started + getting-started/index {% if build_api %} api/index {% endif %} diff --git a/examples/11_advanced_parametric_study.py b/examples/11_advanced_parametric_study.py index b8ab11b56..ccb2d740c 100644 --- a/examples/11_advanced_parametric_study.py +++ b/examples/11_advanced_parametric_study.py @@ -78,7 +78,7 @@ class provides data management features that make the work easier. Also, the ############################################################################### # Create a single bead evaluation # ------------------------------- -# Parametric studies often start with single bead simulations in order to +# Parametric studies often start with single bead simulations to # determine melt pool statistics. Here, the # :meth:`~ParametricStudy.generate_single_bead_permutations` method is used to # generate single bead simulation permutations. The parameters diff --git a/pyproject.toml b/pyproject.toml index c21de6a2e..4f651dcf8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "flit_core.buildapi" [project] # Check https://flit.readthedocs.io/en/latest/pyproject_toml.html for all available sections name = "ansys-additive-core" -version = "0.20.dev2" +version = "0.20.dev3" description = "A Python client for the Ansys Additive service" readme = "README.rst" requires-python = ">=3.10,<4"