diff --git a/doc/source/conf.py b/doc/source/conf.py index 50fbbba5..c2aeffc2 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -89,8 +89,81 @@ metadata = Path(__file__).parent.parent.parent / "projects.yaml" +supported_python_versions_by_metapackage_version = [ + { + "version": "2023.1", + "python": {"lower": "3.7", "upper": "3.10"}, + "link": "https://pypi.org/project/pyansys/2023.1.3/", + }, + { + "version": "2023.2", + "python": {"lower": "3.8", "upper": "3.11"}, + "link": "https://pypi.org/project/pyansys/2023.2.11/", + }, + { + "version": "2024.1", + "python": {"lower": "3.9", "upper": "3.12"}, + "link": "https://pypi.org/project/pyansys/2024.1.8/", + }, + { + "version": "2024.2", + "python": {"lower": "3.9", "upper": "3.12"}, + "link": "https://pypi.org/project/pyansys/2024.2.2/", + }, + { + "version": "2025.1", + "python": {"lower": "3.10", "upper": "3.12"}, + "link": "https://pypi.org/project/pyansys/2025.1.0/", + }, + { + "version": "development", + "python": {"lower": "3.10", "upper": "3.12"}, + "link": "https://github.com/ansys/pyansys", + }, +] + + +def read_dependencies_from_pyproject(): + pyproject = Path(__file__).parent.parent.parent / "pyproject.toml" + if not pyproject.exists(): + raise ValueError(f"The file {pyproject} does not exist.") + + pyproject_content = toml.loads(pyproject.read_text(encoding="utf-8")) + dependencies = pyproject_content["project"]["dependencies"] + return {pkg.split("==")[0]: pkg.split("==")[1] for pkg in dependencies} + + +def read_optional_dependencies_from_pyproject(): + pyproject = Path(__file__).parent.parent.parent / "pyproject.toml" + if not pyproject.exists(): + raise ValueError(f"The file {pyproject} does not exist.") + + pyproject_content = toml.loads(pyproject.read_text(encoding="utf-8")) + exclude_targets = ["doc"] + optional_dependencies = { + target: {pkg.split("==")[0]: pkg.split("==")[1] for pkg in deps} + for target, deps in pyproject_content["project"]["optional-dependencies"].items() + if target not in exclude_targets + } + return optional_dependencies + + +jinja_globals = { + "VERSION": version, + "SUPPORTED_PYTHON_VERSIONS": ["3.10", "3.11", "3.12"], + "SUPPORTED_PLATFORMS": ["Windows", "macOS", "Linux"], +} jinja_contexts = { - "project_context": {"projects": yaml.safe_load(metadata.read_text(encoding="utf-8"))} + "project_context": {"projects": yaml.safe_load(metadata.read_text(encoding="utf-8"))}, + "releases": {"table_data": supported_python_versions_by_metapackage_version}, + "dependencies": {"dependencies": read_dependencies_from_pyproject()}, + "optional_dependencies": {"optional_dependencies": read_optional_dependencies_from_pyproject()}, + "wheelhouse": { + "wheelhouse": { + platform: icon + for platform, icon in zip(["Windows", "macOS", "Linux"], ["windows", "apple", "linux"]) + } + }, } html_context = { diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst new file mode 100644 index 00000000..1747475e --- /dev/null +++ b/doc/source/getting-started.rst @@ -0,0 +1,38 @@ +Getting started +=============== + +This page helps you quickly get started with PyAnsys. It lists all the +prerequisites and guides you step by step to install the project on your +platform. + +.. grid:: 1 1 3 3 + + .. grid-item-card:: :fa:`info-circle` About PyAnsys + :link: getting-started/about + :link-type: doc + :padding: 2 2 2 2 + + Learn more about PyAnsys and its ecosystem + + .. grid-item-card:: :fa:`tasks` Prerequisites + :link: getting-started/prerequisites + :link-type: doc + :padding: 2 2 2 2 + + What you need prior installing PyAnsys + + .. grid-item-card:: :fa:`download` Install + :link: getting-started/install + :link-type: doc + :padding: 2 2 2 2 + + Guidelines on how to install PyAnsys in your system + +.. toctree:: + :maxdepth: 3 + :hidden: + + About + Prerequisites + Install + diff --git a/doc/source/getting-started/about.rst b/doc/source/getting-started/about.rst new file mode 100644 index 00000000..0c335084 --- /dev/null +++ b/doc/source/getting-started/about.rst @@ -0,0 +1,39 @@ +About +##### + +PyAnsys is a collection of Python libraries and tools developed by `ANSYS, +Inc.`_ It provides access to `Ansys products`_ by using a Python interface, +enabling users to perform engineering simulations, data processing, and +automation tasks. + +To ease the installation of the libraries and tools, PyAnsys provides a Python +metapackage. This ensures compatibility between its projects. + +Key features of PyAnsys +======================= + +PyAnsys shines in the following areas: + +- **Automation of workflows:** PyAnsys enables users to automate repetitive or + complex simulation tasks. + +- **Integration with the Python ecosystem:** users can leverage the Python + ecosystem. + +- **Cross-product functionality:** PyAnsys provides Python APIs for various + Ansys services and products. By allowing users to interact with multiple + products in a single environment, PyAnsys enables users to streamline their + workflows. + +The PyAnsys ecosystem +===================== + +PyAnsys libraries can be classified into wrappers and tools. + +**Wrappers** are Python libraries that provide direct access to Ansys products. +Communication between the product and the library is performed via `gRPC +`_. Therefore, users can have the product installed remotely and connect +to that remote instance. + +**Tools** are Python libraries that provide additional functionality to the +wrappers. diff --git a/doc/source/getting-started/install.rst b/doc/source/getting-started/install.rst new file mode 100644 index 00000000..fbcc4c2b --- /dev/null +++ b/doc/source/getting-started/install.rst @@ -0,0 +1,158 @@ +Install PyAnsys +############### + +.. raw:: html + + + + + + +Installing the PyAnsys metapackage is as simple as installing any Python +library. However, you must have a licensed copy of `Ansys `_ to use it. + +Online installation +=================== + +Download and install PyAnsys from `PyPI`_: + +.. tab-set:: + + .. tab-item:: :fab:`windows` **Windows** + + .. code-block:: bash + + python -m pip install pyansys + + .. tab-item:: :fab:`apple` **MacOS** + + .. code-block:: bash + + python -m pip install pyansys + + .. tab-item:: :fab:`linux` **Linux** + + .. code-block:: bash + + python -m pip install pyansys + +The PyAnsys |version| metapackage includes the following projects: + +.. jinja:: dependencies + + .. raw:: html + + + + + + + + + + + + + + {% for project, version in dependencies.items() %} + + + + + {% endfor %} + +
PyAnsys projectVersion
{{ project }}{{ version }}
+ +Additional targets +------------------ + +The PyAnsys metapackage contains various targets for installing additional +libraries and tools. + +.. jinja:: optional_dependencies + + .. tab-set:: + + {% for target, dependencies in optional_dependencies.items() %} + + .. tab-item:: {{ target }} + + Install by running: + + .. code-block:: bash + + python -m pip install pyansys[{{ target }}] + + .. raw:: html + + + + + + + + + + + + + + {% for project, version in dependencies.items() %} + + + + + {% endfor %} + +
PyAnsys projectVersion
{{ project }}{{ version }}
+ + + + + {% endfor %} + + +Offline installation +==================== + +Start by downloading the wheelhouse artifact for your platform: + +.. jinja:: wheelhouse + + .. csv-table:: + :header-rows: 1 + :widths: 16, 28, 28, 28 + + :fas:`laptop` Platform, + {%- for python in SUPPORTED_PYTHON_VERSIONS -%} + :fab:`python` Python {{ python }} + {%- if not loop.last -%},{%- endif -%} + {% endfor %} + {% for platform, icon in wheelhouse.items() -%} + :fab:`{{ icon }}` {{ platform }}, + {%- for python in SUPPORTED_PYTHON_VERSIONS -%} + `Download wheelhouse `__ + {%- if not loop.last -%},{%- endif -%} + {% endfor %} + {% endfor %} + +Next, decompress the artifacts: + +.. code-block:: bash + + unzip wheelhouse + +Finally, install the PyAnsys metapackage using previously downloaded wheelhouse: + +.. code-block:: bash + + python -m pip install pyansys -f wheelhouse --no-index --upgrade --ignore-installed diff --git a/doc/source/getting-started/prerequisites.rst b/doc/source/getting-started/prerequisites.rst new file mode 100644 index 00000000..f4ef62f3 --- /dev/null +++ b/doc/source/getting-started/prerequisites.rst @@ -0,0 +1,94 @@ +Prerequisites +############# + +You need to have the following prerequisites to get started with PyAnsys: + +- A valid Python version +- A licensed version of Ansys + +Download and install Ansys +========================== + +Download Ansys software from the `Ansys Customer Portal`_. Ensure you have a +license to use the software. + +Download and install Python +=========================== + +Download and install the latest stable version of Python from the +`https://www.python.org/downloads `_. + +Suported Python versions +------------------------ + +The PyAnsys ecosystem follows `SPEC-0`_ for Python version support. This +implies that PyAnsys packages drop support for a Python version three years +after their initial release: + +.. mermaid:: + :caption: Python versions supported by SPEC-0 policy (red line) and PyAnsys Python versions supported (color coded) + :alt: Current Python versions supported by the PyAnsys metapackage + :align: center + + gantt + dateFormat YYYY-MM-DD + axisFormat %Y-%m + Python 3.7 :done, des1, 2018-06-27, 3y + Python 3.8 :done, des2, 2019-10-14, 3y + Python 3.9 :done, des3, 2020-10-05, 3y + Python 3.10 :active, des4, 2021-10-04, 3y + Python 3.11 :active, des5, 2022-10-24, 3y + Python 3.12 :active, des6, 2023-10-02, 3y + Python 3.13 : des7, 2024-10-01, 3y + +In previous diagram: + +* Python versions in gray are no longer supported +* Python versions in light blue are currently supported +* Python versions in dark blue will be supported in the future + +.. note:: + + Adoption and deprecation of Python versions in the PyAnsys ecosystem are + tentative. Delays may occur due to third party dependencies. + +Below you can find a list of the Python versions supported by each PyAnsys +metapackage release: + +.. jinja:: releases + + .. raw:: html + + + + + + + + + + + + + + + + + + + + + {% for release in table_data %} + + + + + + + {% endfor %} + +
PyAnsys versionMin. Python versionMax. Python versionDownload
{{ release.version }}{{ release.python.lower }}{{ release.python.upper }}{{ release.link }}
diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst deleted file mode 100644 index 41afef4e..00000000 --- a/doc/source/getting_started.rst +++ /dev/null @@ -1,136 +0,0 @@ -Getting started -=============== - -PyAnsys libraries fall into two categories: - -- Wrappers over products like `MAPDL `_, `Fluent `_, or `AEDT `_ -- Supporting libraries like `DPF `_ - -Most PyAnsys packages require a local installation of Ansys. The version -of Ansys installed dictates the interface and features available to -you. However, PyAnsys libraries use `gRPC `_ to communicate to the -products, you can have the product installed remotely and connect to that -remote instance. This still requires that you need a copy of Ansys installed on -the host machine. - -For more information on getting a licensed copy of Ansys, visit `Ansys -`_. If you are a student, consider installing a student version by -visiting `Ansys for Students `_. - - -************ -Installation -************ - -There are several ways of installing PyAnsys depending on your use case, but -the easiest is simply to run: - -.. code:: bash - - pip install pyansys - -This installs all the PyAnsys libraries for the latest released -version of Ansys, for example, v2023R1. - -You can always install libraries individually by visiting the install page for -each library. For example, for PyAEDT: - -.. code:: bash - - pip install pyaedt - - -User mode installation -^^^^^^^^^^^^^^^^^^^^^^ - -Before installing ``pyansys`` in user mode, ensure that you have the latest -version of `pip`_ with: - -.. code:: bash - - python -m pip install -U pip - -Then, install ``pyansys`` with: - -.. code:: bash - - python -m pip install pyansys - -If you are interested in **installing an extra target** such as ``fluent-all``: - -.. code:: bash - - python -m pip install pyansys[fluent-all] - -If you are interested in **installing a specific version** such as ``2023.1.0``: - -.. code:: bash - - python -m pip install pyansys==2023.1.0 - - -Offline mode installation -^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you lack an internet connection on your installation machine, the -recommended way of installing the ``pyansys`` metapackage is downloading the -wheelhouse archive from the `Releases Page `_ for your -corresponding machine architecture. - -Each wheelhouse archive contains all the Python wheels necessary to install -``pyansys`` metapackage from scratch on Windows, Linux, and MacOS from Python -3.10 to 3.12. You can install this on an isolated system with a fresh Python -installation or on a virtual environment. - -For example, on Linux with Python 3.10, unzip the wheelhouse archive and install -it with the following: - -.. code:: bash - - unzip pyansys-v2025.1.dev0-wheelhouse-Linux-3.10-core.zip wheelhouse - pip install pyansys -f wheelhouse --no-index --upgrade --ignore-installed - -If you're on Windows with Python 3.10, unzip to a wheelhouse directory and install using the same command as above. - -Consider installing using a `virtual environment `_. - - -Versioning system ------------------ - -The ``pyansys`` metapackage follows a semantic-like versioning system, though -it has been adapted to the Ansys product release mechanism. In that sense, the -following kind of versioning system is followed: - -.. code:: bash - - XXXX.Y.ZZ - -Where: - -- ``XXXX`` is the Ansys product release year (for example, 2022) -- ``Y`` is the Ansys product release within the same year (for example, 1, - which relates to R1) -- ``ZZ`` is the patched versions to the ``pyansys`` metapackage, if any. - -Consequently, the first ``pyansys`` metapackage compatible with the 2024 R2 -release would be: - -.. code:: bash - - 2024.2.0 - -And any subsequent patched version of that package would be: - -.. code:: bash - - 2024.2.1 - 2024.2.2 - 2024.2.3 - ... - -You can request for a specific version install when pip installing your package: - -.. code:: bash - - python -m pip install pyansys==2024.2.0 diff --git a/doc/source/index.rst b/doc/source/index.rst index 303189a6..e28d54dc 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,7 +9,7 @@ it is now a collection of many Python packages for using Ansys products through :hidden: :maxdepth: 3 - getting_started + getting-started user_guide api examples diff --git a/doc/source/links.rst b/doc/source/links.rst index db61cc7e..306cf55c 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -1,4 +1,4 @@ -.. #Getting started +.. Getting started .. _mapdl_course: https://www.ansys.com/training-center/course-catalog/structures/ansys-mechanical-advanced-use-of-mapdl-in-mechanical .. _ansys_fluent_page: https://www.ansys.com/products/fluids/ansys-fluent .. _ansys_aedt_page: https://www.ansys.com/products/electronics/ansys-maxwell @@ -9,3 +9,20 @@ .. _pip: https://pypi.org/project/pip/ .. _pyansys_releases: https://github.com/ansys/pyansys/releases .. _venv_docs: https://docs.python.org/3/library/venv.html + +.. ANSYS and products +.. _ANSYS, Inc.: https://ansys.com +.. _Ansys products: https://ansys.com/products +.. _Ansys Customer Portal: https://download.ansys.com + +.. Python libraries +.. _PyPI: https://pypi.org/ +.. _Numpy: https://numpy.org/ +.. _SciPy: https://www.scipy.org/ +.. _Pandas: https://pandas.pydata.org/ +.. _Matplotlib: https://matplotlib.org/ + +.. PEPs, NEPs, and SPECs +.. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html +.. _SPEC-0: https://scientific-python.org/specs/spec-0000/ + diff --git a/doc/source/supported_versions.rst b/doc/source/supported_versions.rst deleted file mode 100644 index 3aaa41c2..00000000 --- a/doc/source/supported_versions.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. _supported_versions: - -Python versions -=============== - -The PyAnsys ecosystem follows `SPEC-0`_ for Python version support, -which is also similar to `NEP 29`_. This means: - -* PyAnsys packages are expected to drop support for Python versions **3 years** after their - initial release. - -You can find below the timeline for the end of support for each Python version according to the SPEC-0 policy -as well as a table showing the Python versions supported by each PyAnsys metapackage, which might slightly -differ from the SPEC-0 policy but is always aligned with it. - -* Grayed out Python versions are no longer supported by the current version of the PyAnsys metapackage. -* Light blue Python versions are currently supported. -* Dark blue Python versions are upcoming Python releases for which support is expected in the future. - -Some extra remarks: - -* The length of the Python version boxes is indicative of the support duration according to the `SPEC-0`_ policy. -* The color of the Python version boxes is indicative of the PyAnsys metapackage current support. - -.. mermaid:: - :caption: Python versions supported by SPEC-0 policy (red line) and PyAnsys Python versions supported (color coded) - :alt: Python versions supported by SPEC-0 policy (red line) and PyAnsys Python versions supported (color coded) - :align: center - - gantt - dateFormat YYYY-MM-DD - axisFormat %Y-%m - Python 3.7 :done, des1, 2018-06-27, 3y - Python 3.8 :done, des2, 2019-10-14, 3y - Python 3.9 :done, des3, 2020-10-05, 3y - Python 3.10 :active, des4, 2021-10-04, 3y - Python 3.11 :active, des5, 2022-10-24, 3y - Python 3.12 :active, des6, 2023-10-02, 3y - Python 3.13 : des7, 2024-10-01, 3y - -Below you can find a list of the Python versions supported by each PyAnsys metapackage release: - -+-----------------+----------------------------+ -| Package version | Python versions supported | -+=================+============================+ -| `2023.1`_ | Python 3.7 - Python 3.10 | -+-----------------+----------------------------+ -| `2023.2`_ | Python 3.8 - Python 3.11 | -+-----------------+----------------------------+ -| `2024.1`_ | Python 3.9 - Python 3.12 | -+-----------------+----------------------------+ -| `2024.2`_ | Python 3.9 - Python 3.12 | -+-----------------+----------------------------+ -| `2025.1`_ | Python 3.10 - Python 3.12 | -+-----------------+----------------------------+ -| `development`_ | Python 3.10 - Python 3.12 | -+-----------------+----------------------------+ - - -.. LINKS -.. _SPEC-0: https://scientific-python.org/specs/spec-0000/ -.. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html -.. _2023.1: https://pypi.org/project/pyansys/2023.1.3/ -.. _2023.2: https://pypi.org/project/pyansys/2023.2.11/ -.. _2024.1: https://pypi.org/project/pyansys/2024.1.8/ -.. _2024.2: https://pypi.org/project/pyansys/2024.2.2/ -.. _2025.1: https://pypi.org/project/pyansys/2025.1.0/ -.. _development: https://github.com/ansys/pyansys