From 46e8aa615c7e9b62b5dafbd95e430e8c1591f08b Mon Sep 17 00:00:00 2001 From: afernand Date: Thu, 26 Jun 2025 10:29:18 +0200 Subject: [PATCH 1/8] feat: Migrate report tool --- .../config/vocabularies/ANSYS/accept.txt | 3 +- pyproject.toml | 1 + .../common/path/applications/__init__.py | 2 +- src/ansys/tools/common/path/path.py | 2 +- src/ansys/tools/{ => common}/py.typed | 0 src/ansys/tools/common/report.py | 255 ++++++++++++++++ tests/test_report.py | 274 ++++++++++++++++++ 7 files changed, 534 insertions(+), 3 deletions(-) rename src/ansys/tools/{ => common}/py.typed (100%) create mode 100644 src/ansys/tools/common/report.py create mode 100644 tests/test_report.py diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 071cc075..bd7bd3f4 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -1,2 +1,3 @@ (?i)Ansys -pytest \ No newline at end of file +pytest +ANS \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 61367160..c38bd3db 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -25,6 +25,7 @@ classifiers = [ dependencies = [ "platformdirs>=3.6.0", "click>=8.1.3", # for CLI interface + "scooby>=0.5.12", ] [project.optional-dependencies] diff --git a/src/ansys/tools/common/path/applications/__init__.py b/src/ansys/tools/common/path/applications/__init__.py index 3f8e812c..dfee9a2e 100644 --- a/src/ansys/tools/common/path/applications/__init__.py +++ b/src/ansys/tools/common/path/applications/__init__.py @@ -34,7 +34,7 @@ class ApplicationPlugin: """Class for application plugins.""" def is_valid_executable_path(self, exe_loc: str) -> bool: - r"""Check if the executable path is valid for the application. + """Check if the executable path is valid for the application. Parameters ---------- diff --git a/src/ansys/tools/common/path/path.py b/src/ansys/tools/common/path/path.py index 8f65e3fb..7c634124 100644 --- a/src/ansys/tools/common/path/path.py +++ b/src/ansys/tools/common/path/path.py @@ -189,7 +189,7 @@ def _get_default_windows_base_path() -> Optional[str]: # pragma: no cover def _is_float(input_string: str) -> bool: - r"""Return true when a string can be converted to a float. + """Return true when a string can be converted to a float. Parameters ---------- diff --git a/src/ansys/tools/py.typed b/src/ansys/tools/common/py.typed similarity index 100% rename from src/ansys/tools/py.typed rename to src/ansys/tools/common/py.typed diff --git a/src/ansys/tools/common/report.py b/src/ansys/tools/common/report.py new file mode 100644 index 00000000..36c5b0be --- /dev/null +++ b/src/ansys/tools/common/report.py @@ -0,0 +1,255 @@ +# Copyright (C) 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + +""" +PyAnsys Tools Report. + +Module containing the standardized Report class for PyAnsys projects. +""" + +import os +import sys + +import scooby + +__ANSYS_VARS_PREFIX__ = ( + "AWP", + "ACP", + "ANS", + "FLUENT", + "MAPDL", + "DPF", + "SIMPLORER", + "SIWAVE", + "CADOE", +) + +__PYANSYS_LIBS__ = ( + "ansys_sphinx_theme", + "ansys.acp.core", + "ansys.dpf.composites", + "ansys.dpf.core", + "ansys.dpf.post", + "ansys.fluent.core", + "ansys.fluent.visualization", + "ansys.fluent.parametric", + "ansys.geometry.core", + "ansys.hps.client", + "ansys.mapdl.core", + "ansys.mapdl.reader", + "ansys.math.core", + "ansys.mechanical.core", + "ansys.meshing.prime", + "ansys.modelcenter.workflow", + "ansys.motorcad.core", + "ansys.openapi.common", + "ansys.optislang.core", + "ansys.platform.instancemanagement", + "ansys.pyensight.core", + "ansys.rocky.core", + "ansys.seascape", + "ansys.simai.core", + "ansys.systemcoupling.core", + "ansys.turbogrid.core", + "ansys.tools.report", + "ansys.tools.versioning", + "pyaedt", + "pyedb", + "pygranta", + "pytwin", +) + + +class Report(scooby.Report): + """Generate a :class:`scooby.Report` instance. + + Parameters + ---------- + additional : list(ModuleType), list(str), optional + List of packages or package names to add to output information. + Defaults to ``None``. + ncol : int, optional + Number of package-columns in html table; only has effect if + ``mode='HTML'`` or ``mode='html'``. Defaults to 3. + text_width : int, optional + The text width for non-HTML display modes. Defaults to 80. + sort : bool, optional + Alphabetically sort the packages. Defaults to ``False``. + gpu : bool, optional + Gather information about the GPU. Defaults to ``True`` but if + experiencing rendering issues, pass ``False`` to safely generate + a report. + ansys_vars : list of str, optional + List containing the Ansys environment variables to be reported. + (e.g. ["MYVAR_1", "MYVAR_2" ...]). Defaults to ``None``. + ansys_libs : dict {str : str}, optional + Dictionary containing the Ansys libraries and versions to be reported. + (e.g. {"MyLib" : "v1.2", ...}). Defaults to ``None``. + """ + + def __init__( + self, + additional=None, + ncol=3, + text_width=80, + sort=False, + gpu=True, + ansys_vars=None, + ansys_libs=None, + ): + """Report class constructor.""" + # Mandatory packages + core = [ + "appdirs", + "google.protobuf", # protobuf library + "grpc", # grpcio + "matplotlib", + "numpy", + "pyiges", + "pyvista", + "scipy", + "tqdm", + ] + + if os.name == "posix": + core.extend(["pexpect"]) + + # Optional packages + optional = ["matplotlib"] + if sys.version_info[1] < 9: + optional.append("ansys_corba") + + # PyAnsys packages + additional ones + if additional: + additional.extend(__PYANSYS_LIBS__) + else: + additional = __PYANSYS_LIBS__ + + # Information about the GPU - bare except in case there is a rendering + # bug that the user is trying to report. + if gpu: + try: + try: + from pyvista.report import GPUInfo + except ImportError: + from pyvista.utilities.errors import GPUInfo # deprecated in PyVista 0.40 + + extra_meta = [(t[0], t[1]) for t in GPUInfo().get_info()] + except Exception: + extra_meta = ("GPU Details", "error") + else: + extra_meta = ("GPU Details", "None") + + # Store the ANSYS vars and libs + self._ansys_vars = ansys_vars + self._ansys_libs = ansys_libs + + scooby.Report.__init__( + self, + additional=additional, + core=core, + optional=optional, + ncol=ncol, + text_width=text_width, + sort=sort, + extra_meta=extra_meta, + ) + + def project_info(self): + """Return information regarding the Ansys environment and installation. + + Returns + ------- + str + The project information (env variables and installation) + """ + # List installed Ansys + lines = ["", "Ansys Environment Report", "-" * 79, "\n"] + lines.append("\n".join(["Ansys Installation", "******************"])) + if not self._ansys_libs: + lines.append("No Ansys installations provided") + else: + lines.append("Version Location") + lines.append("------------------") + for key in sorted(self._ansys_libs.keys()): + lines.append(f"{key} {self._ansys_libs[key]}") + install_info = "\n".join(lines) + + env_info_lines = [ + "\n\n\nAnsys Environment Variables", + "***************************", + ] + n_var = 0 + if self._ansys_vars is not None: + for key, value in os.environ.items(): + if key in self._ansys_vars: + env_info_lines.append(f"{key:<30} {value}") + n_var += 1 + + # Loop over all environment variables + for key, value in os.environ.items(): + # Now, check if it is an Ansys default variable + if self._is_ansys_var(key): + # If found, check if it is already available or not + if (self._ansys_vars is None) or (key not in self._ansys_vars): + env_info_lines.append(f"{key:<30} {value}") + n_var += 1 + + # Finally, if no env vars were found, just append None + if not n_var: + env_info_lines.append("None") + env_info = "\n".join(env_info_lines) + + return install_info + env_info + + def _is_ansys_var(self, env_var): + """ + Determine if an env. variable belongs to the set of ANSYS default env. variables. + + Parameters + ---------- + env_var : str + The environment variable to be evaluated. + + Returns + ------- + bool + ``True`` when successful, ``False`` when failed. + """ + # Loop over the Ansys default variables prefixes + for prefix in __ANSYS_VARS_PREFIX__: + # Check if the "prefix" substring is found + if env_var.startswith(prefix): + return True + + def __repr__(self): + """Print out the report. + + Returns + ------- + str + Report statement. + """ + add_text = "-" * 79 + "\nPyAnsys Software and Environment Report" + + report = add_text + super().__repr__() + self.project_info() + return report.replace("-" * 80, "-" * 79) # hotfix for scooby diff --git a/tests/test_report.py b/tests/test_report.py new file mode 100644 index 00000000..d1871853 --- /dev/null +++ b/tests/test_report.py @@ -0,0 +1,274 @@ +# Copyright (C) 2025 ANSYS, Inc. and/or its affiliates. +# SPDX-License-Identifier: MIT +# +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. +"""Report tool testing.""" + +import multiprocessing +import os +import platform + +import ansys.tools.common.report as report + + +def test_create_ansys_report_empty(): + """Test the creation of a Report and its correct output.""" + # Instantiate a "default" Report + rep = report.Report() + + # Assert some of its information + # + # CPU Count + assert rep.cpu_count == multiprocessing.cpu_count() + # Architecture + assert rep.architecture == platform.architecture()[0] + # OS + assert platform.system() in rep.system + # Machine + assert rep.machine == platform.machine() + + # Assert the output of the project info (the one we can control) + str_empty = """ +Ansys Environment Report +------------------------------------------------------------------------------- + + +Ansys Installation +****************** +No Ansys installations provided + + +Ansys Environment Variables +*************************** +None""" + + # Assert that the empty report is properly generated + assert rep.project_info() == str_empty + + +def test_create_ansys_report_with_libs(): + """Test the creation of a Report and its correct output. + + Test the creation of a Report and its correct output + when imaginary Ansys libraries are provided. + """ + # Let us imagine some ansys libraries + my_ansys_libs = { + "MyLib1": "v1.2", + "MyLib2": "v1.3", + } + + # Instantiate a Report object + rep = report.Report(ansys_libs=my_ansys_libs) + + # Assert the output of the project info (the one we can control) + str_report = """ +Ansys Environment Report +------------------------------------------------------------------------------- + + +Ansys Installation +****************** +Version Location +------------------ +MyLib1 v1.2 +MyLib2 v1.3 + + +Ansys Environment Variables +*************************** +None""" + + # Assert that the report is properly generated + assert rep.project_info() == str_report + + +def test_create_ansys_report_with_vars(): + """Test the creation of a Report and its correct output. + + Test the creation of a Report and its correct output + when imaginary Ansys variables are provided. + """ + # Let us imagine some ansys variables + os.environ["MYVAR_1"] = "VAL_1" + os.environ["MYVAR_2"] = "VAL_2" + my_ansys_vars = ["MYVAR_1", "MYVAR_2"] + + # Instantiate a Report object + rep = report.Report(ansys_vars=my_ansys_vars) + + # Assert the output of the project info (the one we can control) + str_report = """ +Ansys Environment Report +------------------------------------------------------------------------------- + + +Ansys Installation +****************** +No Ansys installations provided + + +Ansys Environment Variables +*************************** +MYVAR_1 VAL_1 +MYVAR_2 VAL_2""" + + # Assert that the report is properly generated + assert rep.project_info() == str_report + + +def test_create_ansys_report_with_libs_and_vars(): + """Test the creation of a Report and its correct output. + + Test the creation of a Report and its correct output + when imaginary Ansys libraries and variables are provided. + """ + # Let us imagine some ansys libraries + my_ansys_libs = { + "MyLib1": "v1.2", + "MyLib2": "v1.3", + } + + # Let us imagine some ansys variables + os.environ["MYVAR_1"] = "VAL_1" + os.environ["MYVAR_2"] = "VAL_2" + my_ansys_vars = ["MYVAR_1", "MYVAR_2"] + + # Instantiate a Report object + rep = report.Report(ansys_libs=my_ansys_libs, ansys_vars=my_ansys_vars) + + # Assert the output of the project info (the one we can control) + str_report = """ +Ansys Environment Report +------------------------------------------------------------------------------- + + +Ansys Installation +****************** +Version Location +------------------ +MyLib1 v1.2 +MyLib2 v1.3 + + +Ansys Environment Variables +*************************** +MYVAR_1 VAL_1 +MYVAR_2 VAL_2""" + + # Assert that the report is properly generated + assert rep.project_info() == str_report + + +def test_create_ansys_repr(): + """Test the creation of a Report and its correct output when directly calling the object.""" + # Let us start by creating a "default" Report + str_rep = report.Report().__repr__() + + # Define the comparison strings + str_start = "-" * 79 + "\nPyAnsys Software and Environment Report" + str_end = """ +Ansys Environment Variables +*************************** +None""" + + # Validate the start and end of the report + assert str_rep.startswith(str_start) + assert str_rep.endswith(str_end) + + +def test_create_ansys_report_with_def_vars(): + """Test the creation of a Report and its correct output. + + Test the creation of a Report and its correct output + when imaginary Ansys variables are provided. In this case, + default vars are expected. And it is also testing when a + default var is provided specifically, if it is not printed twice. + + Also, gpu set to False is tested, for coverage reasons. + """ + # Let us imagine some ansys variables + os.environ["MYVAR_1"] = "VAL_1" + os.environ["MYVAR_2"] = "VAL_2" + os.environ["FLUENT_VAR1"] = "FL_VAL_1" + os.environ["FLUENT_VAR2"] = "FL_VAL_2" + my_ansys_vars = ["MYVAR_1", "MYVAR_2", "FLUENT_VAR2"] + + # Instantiate a Report object + rep = report.Report(ansys_vars=my_ansys_vars, gpu=False) + + # Assert the output of the project info (the one we can control) + str_report = """ +Ansys Environment Report +------------------------------------------------------------------------------- + + +Ansys Installation +****************** +No Ansys installations provided + + +Ansys Environment Variables +*************************** +MYVAR_1 VAL_1 +MYVAR_2 VAL_2 +FLUENT_VAR2 FL_VAL_2 +FLUENT_VAR1 FL_VAL_1""" + + # Assert that the report is properly generated + assert rep.project_info() == str_report + + +def test_create_ansys_report_with_no_vars(): + """Test the creation of a Report. + + Test the creation of a Report and its correct output + when no Ansys variables are provided. In this case, + default vars are expected, even though none are provided. + """ + # Let us imagine "default" ansys variables + os.environ["FLUENT_VAR1"] = "FL_VAL_1" + os.environ["FLUENT_VAR2"] = "FL_VAL_2" + os.environ["FLUENT_ANS_VAR1"] = "FL_VAL_1" + os.environ["FLUENT_ANS_VAR2"] = "FL_VAL_2" + + # Instantiate a Report object + rep = report.Report() + + # Assert the output of the project info (the one we can control) + str_report = """ +Ansys Environment Report +------------------------------------------------------------------------------- + + +Ansys Installation +****************** +No Ansys installations provided + + +Ansys Environment Variables +*************************** +FLUENT_VAR1 FL_VAL_1 +FLUENT_VAR2 FL_VAL_2 +FLUENT_ANS_VAR1 FL_VAL_1 +FLUENT_ANS_VAR2 FL_VAL_2""" + + # Assert that the report is properly generated + assert rep.project_info() == str_report From 94a7029cd05d2d5d6fb67f48e6c4d491f921680d Mon Sep 17 00:00:00 2001 From: afernand Date: Fri, 27 Jun 2025 10:05:09 +0200 Subject: [PATCH 2/8] fix: Ansys local env var --- tests/test_report.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tests/test_report.py b/tests/test_report.py index d1871853..0643ab5c 100644 --- a/tests/test_report.py +++ b/tests/test_report.py @@ -107,6 +107,7 @@ def test_create_ansys_report_with_vars(): when imaginary Ansys variables are provided. """ # Let us imagine some ansys variables + os.environ.pop("ANSYS_LOCAL", None) # Remove the ANSYS_LOCAL env var if it exists os.environ["MYVAR_1"] = "VAL_1" os.environ["MYVAR_2"] = "VAL_2" my_ansys_vars = ["MYVAR_1", "MYVAR_2"] @@ -147,6 +148,7 @@ def test_create_ansys_report_with_libs_and_vars(): } # Let us imagine some ansys variables + os.environ.pop("ANSYS_LOCAL", None) # Remove the ANSYS_LOCAL env var if it exists os.environ["MYVAR_1"] = "VAL_1" os.environ["MYVAR_2"] = "VAL_2" my_ansys_vars = ["MYVAR_1", "MYVAR_2"] @@ -205,6 +207,7 @@ def test_create_ansys_report_with_def_vars(): Also, gpu set to False is tested, for coverage reasons. """ # Let us imagine some ansys variables + os.environ.pop("ANSYS_LOCAL", None) # Remove the ANSYS_LOCAL env var if it exists os.environ["MYVAR_1"] = "VAL_1" os.environ["MYVAR_2"] = "VAL_2" os.environ["FLUENT_VAR1"] = "FL_VAL_1" @@ -244,6 +247,7 @@ def test_create_ansys_report_with_no_vars(): default vars are expected, even though none are provided. """ # Let us imagine "default" ansys variables + os.environ.pop("ANSYS_LOCAL", None) # Remove the ANSYS_LOCAL env var if it exists os.environ["FLUENT_VAR1"] = "FL_VAL_1" os.environ["FLUENT_VAR2"] = "FL_VAL_2" os.environ["FLUENT_ANS_VAR1"] = "FL_VAL_1" From 99fb559e2a5bc6b8bdde438bf2a0f556fd23b626 Mon Sep 17 00:00:00 2001 From: afernand Date: Fri, 27 Jun 2025 10:13:58 +0200 Subject: [PATCH 3/8] fix: remove env var --- tests/test_report.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/test_report.py b/tests/test_report.py index 0643ab5c..05c46fa4 100644 --- a/tests/test_report.py +++ b/tests/test_report.py @@ -36,6 +36,7 @@ def test_create_ansys_report_empty(): # Assert some of its information # # CPU Count + os.environ.pop("ANSYS_LOCAL", None) # Remove the ANSYS_LOCAL env var if it exists assert rep.cpu_count == multiprocessing.cpu_count() # Architecture assert rep.architecture == platform.architecture()[0] @@ -70,6 +71,7 @@ def test_create_ansys_report_with_libs(): when imaginary Ansys libraries are provided. """ # Let us imagine some ansys libraries + os.environ.pop("ANSYS_LOCAL", None) # Remove the ANSYS_LOCAL env var if it exists my_ansys_libs = { "MyLib1": "v1.2", "MyLib2": "v1.3", From 627489eaf126962e1ee05f24897ac551ffc8d240 Mon Sep 17 00:00:00 2001 From: afernand Date: Fri, 27 Jun 2025 10:17:47 +0200 Subject: [PATCH 4/8] fix: Report tests with installation --- tests/test_report.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tests/test_report.py b/tests/test_report.py index 05c46fa4..3fc55933 100644 --- a/tests/test_report.py +++ b/tests/test_report.py @@ -36,7 +36,10 @@ def test_create_ansys_report_empty(): # Assert some of its information # # CPU Count - os.environ.pop("ANSYS_LOCAL", None) # Remove the ANSYS_LOCAL env var if it exists + ans_local = os.environ.pop("ANSYS_LOCAL", None) # Remove the ANSYS_LOCAL env var if it exists + if ans_local is not None: + os.environ.pop("ANSYS_VERSION") + os.environ.pop("AWP_ROOT222") assert rep.cpu_count == multiprocessing.cpu_count() # Architecture assert rep.architecture == platform.architecture()[0] From 5ad654cda59883e7a70cead59f525e32482864b6 Mon Sep 17 00:00:00 2001 From: afernand Date: Fri, 27 Jun 2025 10:22:11 +0200 Subject: [PATCH 5/8] fix: env vars --- tests/test_report.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/test_report.py b/tests/test_report.py index 3fc55933..fde449ea 100644 --- a/tests/test_report.py +++ b/tests/test_report.py @@ -37,9 +37,9 @@ def test_create_ansys_report_empty(): # # CPU Count ans_local = os.environ.pop("ANSYS_LOCAL", None) # Remove the ANSYS_LOCAL env var if it exists - if ans_local is not None: - os.environ.pop("ANSYS_VERSION") - os.environ.pop("AWP_ROOT222") + if ans_local: + os.environ.pop("ANSYS_VERSION", None) + os.environ.pop("AWP_ROOT222", None) assert rep.cpu_count == multiprocessing.cpu_count() # Architecture assert rep.architecture == platform.architecture()[0] From 4bad0a4a3224c5cec2fd891ec6933df91a393f66 Mon Sep 17 00:00:00 2001 From: afernand Date: Fri, 27 Jun 2025 10:29:25 +0200 Subject: [PATCH 6/8] doc: Add documentation for report tool --- doc/source/user_guide/index.rst | 17 +++- doc/source/user_guide/report.rst | 147 +++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+), 1 deletion(-) create mode 100644 doc/source/user_guide/report.rst diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst index e94e42de..54d8e565 100644 --- a/doc/source/user_guide/index.rst +++ b/doc/source/user_guide/index.rst @@ -31,6 +31,20 @@ your own code. Learn how to use the common exceptions. + .. grid-item-card:: Ansys versioning tool + :padding: 2 2 2 2 + :link: versioning + :link-type: doc + + Learn how to use the versioning tool. + + .. grid-item-card:: Ansys report tool + :padding: 2 2 2 2 + :link: report + :link-type: doc + + Learn how to use the report tool. + .. toctree:: :hidden: :maxdepth: 3 @@ -38,4 +52,5 @@ your own code. ansys_tools_path ansys_downloader ansys_exceptions - versioning \ No newline at end of file + versioning + report \ No newline at end of file diff --git a/doc/source/user_guide/report.rst b/doc/source/user_guide/report.rst new file mode 100644 index 00000000..592f44a1 --- /dev/null +++ b/doc/source/user_guide/report.rst @@ -0,0 +1,147 @@ +.. _ref_user_guide: + +User guide +============ + +This section explains how to use ``pyansys-tools-report`` and its features. + +Using PyAnsys Tools Report +-------------------------- + +Once the ``pyansys-tools-report`` package is installed in your own personal environment (if not, please proceed +to :ref:`ref_getting_started`), you can start importing the package and using it. + +In order to import the package, please run: + +.. code:: python + + import ansys.tools.report as pyansys_report + +The ``pyansys-tools-report`` contains a main class called ``Report``. This class is basically an extension of the +``scooby.Report``, but customized for showing Ansys libraries and variables in a common format. + +The possible arguments that the ``Report`` class accepts can be found in the :ref:`ref_index_api`. PLease, have a look +at it to understand the arguments you may use. A simple example of Ansys variables and libraries is shown below. + +.. code:: python + + # After defining my_ansys_libs and my_ansys_vars with the needed format (see API Reference) + # we can start the instantiation of the report + # + # Instantiate a Report object + rep = report.Report(ansys_libs=my_ansys_libs, ansys_vars=my_ansys_vars) + + # For printing the report + rep + +The typical output of a ``Report`` would look as follows: + +.. code-block:: text + + >>> ------------------------------------------------------------------------------- + >>> PyAnsys Software and Environment Report + >>> ------------------------------------------------------------------------------- + >>> Date: Wed Nov 30 14:54:58 2022 Romance Standard Time + >>> + >>> OS : Windows + >>> CPU(s) : 16 + >>> Machine : AMD64 + >>> Architecture : 64bit + >>> Environment : Python + >>> GPU Vendor : Intel + >>> GPU Renderer : Intel(R) UHD Graphics + >>> GPU Version : 4.5.0 - Build 30.0.100.9955 + >>> + >>> Python 3.10.4 (tags/v3.10.4:9d38120, Mar 23 2022, 23:13:41) [MSC v.1929 64 bit (AMD64)] + >>> + >>> ansys-mapdl-core : X.Y.Z + >>> ansys-dpf-core : X.Y.Z + >>> ansys-dpf-post : X.Y.Z + >>> ansys-dpf-gate : X.Y.Z + >>> ansys-fluent-core : X.Y.Z + >>> pyaedt : X.Y.Z + >>> ansys-platform-instancemanagement : X.Y.Z + >>> ansys-grantami-bomanalytics : X.Y.Z + >>> ansys-openapi-common : X.Y.Z + >>> ansys-mapdl-reader : X.Y.Z + >>> ansys-fluent-visualization : X.Y.Z + >>> ansys-fluent-parametric : X.Y.Z + >>> ansys-sphinx-theme : X.Y.Z + >>> ansys-seascape : X.Y.Z + >>> pyansys-tools-report : X.Y.Z + >>> pyansys-tools-versioning : X.Y.Z + >>> matplotlib : X.Y.Z + >>> numpy : X.Y.Z + >>> pyvista : X.Y.Z + >>> appdirs : X.Y.Z + >>> tqdm : X.Y.Z + >>> pyiges : X.Y.Z + >>> scipy : X.Y.Z + >>> grpc : X.Y.Z + >>> google.protobuf : X.Y.Z + >>> + >>> + >>> ------------------------------------------------------------------------------- + >>> Ansys Environment Report + >>> ------------------------------------------------------------------------------- + >>> + >>> + >>> Ansys Installation + >>> ****************** + >>> Version Location + >>> ------------------ + >>> MyLib1 v1.2 + >>> MyLib2 v1.3 + >>> + >>> + >>> Ansys Environment Variables + >>> *************************** + >>> MYVAR_1 VAL_1 + >>> MYVAR_2 VAL_2 + + +By default, the ``Report`` class would look for a certain set of environment variables. The following +strings are searched for in the available environment variables. If any match is found, they are included +in the report: + +* ``AWP_ROOT`` +* ``ANS`` +* ``MAPDL`` +* ``FLUENT`` +* ``AEDT`` +* ``DPF`` + +Also, several Python packages are reported by default. The set of reported packages always includes +the following list: + +* ``ansys-mapdl-core`` +* ``ansys-dpf-core`` +* ``ansys-dpf-post`` +* ``ansys-dpf-gate`` +* ``ansys-fluent-core`` +* ``pyaedt`` +* ``ansys-platform-instancemanagement`` +* ``ansys-grantami-bomanalytics`` +* ``ansys-openapi-common`` +* ``ansys-mapdl-reader`` +* ``ansys-fluent-visualization`` +* ``ansys-fluent-parametric`` +* ``ansys-sphinx-theme`` +* ``ansys-seascape`` +* ``pyansys-tools-report`` +* ``pyansys-tools-versioning`` +* ``matplotlib`` +* ``numpy`` +* ``pyvista`` +* ``appdirs`` +* ``tqdm`` +* ``pyiges`` +* ``scipy`` +* ``grpc`` +* ``google.protobuf`` + +If you want the ``Report`` class to look for some extra environment variables by default, please +`raise an issue `_. + +Enjoy its use. If you have any doubts, please raise a question/issue in the +`PyAnsys Tools Report Issues `_ site. \ No newline at end of file From 5f3bdc6aba66dcf3ea92c8b4f30a12d753fd169f Mon Sep 17 00:00:00 2001 From: afernand Date: Fri, 27 Jun 2025 10:42:40 +0200 Subject: [PATCH 7/8] fix: API reference reference --- doc/source/user_guide/report.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/user_guide/report.rst b/doc/source/user_guide/report.rst index 592f44a1..e959bb60 100644 --- a/doc/source/user_guide/report.rst +++ b/doc/source/user_guide/report.rst @@ -1,4 +1,4 @@ -.. _ref_user_guide: +.. _ref_report: User guide ============ @@ -20,7 +20,7 @@ In order to import the package, please run: The ``pyansys-tools-report`` contains a main class called ``Report``. This class is basically an extension of the ``scooby.Report``, but customized for showing Ansys libraries and variables in a common format. -The possible arguments that the ``Report`` class accepts can be found in the :ref:`ref_index_api`. PLease, have a look +The possible arguments that the ``Report`` class accepts can be found in the `API reference <../api/index.html>`_. Please, have a look at it to understand the arguments you may use. A simple example of Ansys variables and libraries is shown below. .. code:: python From efef387bfbca41c407c0b20667115c42c3e2222b Mon Sep 17 00:00:00 2001 From: afernand Date: Fri, 27 Jun 2025 10:55:41 +0200 Subject: [PATCH 8/8] fix: Titles and links --- doc/source/getting_started/index.rst | 2 +- doc/source/user_guide/report.rst | 6 +++--- doc/source/user_guide/versioning.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 7824733b..b34f10f2 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -8,7 +8,7 @@ quickly begin using it. If you are interested in contributing to theAnsys tools see :ref:`contribute` for information on installing in developer mode. Installation -============ +------------ To use `pip `_ to install the Ansys tools common project, run this command: diff --git a/doc/source/user_guide/report.rst b/doc/source/user_guide/report.rst index e959bb60..cd35de10 100644 --- a/doc/source/user_guide/report.rst +++ b/doc/source/user_guide/report.rst @@ -1,7 +1,7 @@ .. _ref_report: User guide -============ +========== This section explains how to use ``pyansys-tools-report`` and its features. @@ -141,7 +141,7 @@ the following list: * ``google.protobuf`` If you want the ``Report`` class to look for some extra environment variables by default, please -`raise an issue `_. +`raise an issue `_. Enjoy its use. If you have any doubts, please raise a question/issue in the -`PyAnsys Tools Report Issues `_ site. \ No newline at end of file +`PyAnsys Tools Report Issues `_ site. \ No newline at end of file diff --git a/doc/source/user_guide/versioning.rst b/doc/source/user_guide/versioning.rst index 3a00ebfb..b24e8eec 100644 --- a/doc/source/user_guide/versioning.rst +++ b/doc/source/user_guide/versioning.rst @@ -1,7 +1,7 @@ .. ref_versioning: User guide -########## +========== The fundamental object provided by ``ansys.tools.versioning`` is a decorator named :meth:`ansys.tools.versioning.requires_version` which accepts: @@ -14,7 +14,7 @@ named :meth:`ansys.tools.versioning.requires_version` which accepts: How to use -========== +---------- The ``requires_version`` decorator is expected to be used in all the desired methods of a class containing a ``_server_version`` attribute. If the class in which it is used does not contain this attribute, an ``AttributeError`` is