Metadata-Version: 2.1
Name: ansys-geometry-core
Version: 0.3.1
Summary: A python wrapper for Ansys Geometry service
Author-email: "ANSYS, Inc." <pyansys.core@ansys.com>
Maintainer-email: "ANSYS, Inc." <pyansys.core@ansys.com>
Requires-Python: >=3.8,<4
Description-Content-Type: text/x-rst
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: ansys-api-geometry==0.2.16
Requires-Dist: ansys-tools-path>=0.3
Requires-Dist: beartype>=0.11.0
Requires-Dist: google-api-python-client>=1.7.11
Requires-Dist: googleapis-common-protos>=1.52.0
Requires-Dist: grpcio>=1.35.0
Requires-Dist: grpcio-health-checking>=1.45.0
Requires-Dist: importlib-metadata>=4.0,<5; python_version<='3.8'
Requires-Dist: numpy>=1.20.3
Requires-Dist: Pint>=0.18
Requires-Dist: protobuf~=3.20.2
Requires-Dist: pyvista>=0.37.0
Requires-Dist: scipy>=1.7.3
Requires-Dist: six>=1.16.0
Requires-Dist: vtk>=9
Requires-Dist: ansys-platform-instancemanagement>=1.0.3 ; extra == "all"
Requires-Dist: docker>=6.0.1 ; extra == "all"
Requires-Dist: pyvista[trame]>=0.38.1,<0.42 ; extra == "all"
Requires-Dist: ansys-sphinx-theme==0.11.1 ; extra == "doc"
Requires-Dist: docker==6.1.3 ; extra == "doc"
Requires-Dist: ipyvtklink==0.2.3 ; extra == "doc"
Requires-Dist: jupyter_sphinx==0.4.0 ; extra == "doc"
Requires-Dist: jupytext==1.15.1 ; extra == "doc"
Requires-Dist: myst-parser==2.0.0 ; extra == "doc"
Requires-Dist: nbconvert==7.8.0 ; extra == "doc"
Requires-Dist: nbsphinx==0.9.3 ; extra == "doc"
Requires-Dist: notebook==7.0.3 ; extra == "doc"
Requires-Dist: numpydoc==1.5.0 ; extra == "doc"
Requires-Dist: panel==1.2.2 ; extra == "doc"
Requires-Dist: pyvista[trame]==0.41.1 ; extra == "doc"
Requires-Dist: requests==2.31.0 ; extra == "doc"
Requires-Dist: sphinx==7.2.5 ; extra == "doc"
Requires-Dist: sphinx-autoapi==2.1.1 ; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints==1.24.0 ; extra == "doc"
Requires-Dist: sphinx-copybutton==0.5.2 ; extra == "doc"
Requires-Dist: sphinx_design==0.5.0 ; extra == "doc"
Requires-Dist: sphinx-jinja==2.0.2 ; extra == "doc"
Requires-Dist: vtk==9.2.6 ; extra == "doc"
Requires-Dist: ansys-platform-instancemanagement==1.1.2 ; extra == "tests"
Requires-Dist: ansys-tools-path==0.3.1 ; extra == "tests"
Requires-Dist: beartype==0.15.0 ; extra == "tests"
Requires-Dist: docker==6.1.3 ; extra == "tests"
Requires-Dist: google-api-python-client==2.98.0 ; extra == "tests"
Requires-Dist: googleapis-common-protos==1.60.0 ; extra == "tests"
Requires-Dist: grpcio==1.50.0 ; extra == "tests"
Requires-Dist: grpcio-health-checking==1.48.2 ; extra == "tests"
Requires-Dist: numpy==1.25.2 ; extra == "tests"
Requires-Dist: Pint==0.22 ; extra == "tests"
Requires-Dist: protobuf==3.20.3 ; extra == "tests"
Requires-Dist: pytest==7.4.2 ; extra == "tests"
Requires-Dist: pytest-cov==4.1.0 ; extra == "tests"
Requires-Dist: pytest-pyvista==0.1.8 ; extra == "tests"
Requires-Dist: pytest-xvfb==3.0.0 ; extra == "tests"
Requires-Dist: pyvista[trame]==0.41.1 ; extra == "tests"
Requires-Dist: requests==2.31.0 ; extra == "tests"
Requires-Dist: scipy==1.11.2 ; extra == "tests"
Requires-Dist: six==1.16.0 ; extra == "tests"
Requires-Dist: vtk==9.2.6 ; extra == "tests"
Project-URL: Discussions, https://github.com/ansys/pyansys-geometry/discussions
Project-URL: Documentation, https://geometry.docs.pyansys.com
Project-URL: Issues, https://github.com/ansys/pyansys-geometry/issues
Project-URL: Releases, https://github.com/ansys/pyansys-geometry/releases
Project-URL: Source, https://github.com/ansys/pyansys-geometry
Provides-Extra: all
Provides-Extra: doc
Provides-Extra: tests

PyAnsys Geometry
================
|pyansys| |python| |pypi| |GH-CI| |codecov| |MIT| |black| |pre-commit|

.. |pyansys| image:: https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC
   :target: https://docs.pyansys.com/
   :alt: PyAnsys

.. |python| image:: https://img.shields.io/pypi/pyversions/ansys-geometry-core?logo=pypi
   :target: https://pypi.org/project/ansys-geometry-core/
   :alt: Python

.. |pypi| image:: https://img.shields.io/pypi/v/ansys-geometry-core.svg?logo=python&logoColor=white
   :target: https://pypi.org/project/ansys-geometry-core
   :alt: PyPI

.. |codecov| image:: https://codecov.io/gh/ansys/ansys-geometry-core/branch/main/graph/badge.svg
   :target: https://codecov.io/gh/ansys/pyansys-geometry
   :alt: Codecov

.. |GH-CI| image:: https://github.com/ansys/pyansys-geometry/actions/workflows/ci_cd.yml/badge.svg
   :target: https://github.com/ansys/pyansys-geometry/actions/workflows/ci_cd.yml
   :alt: GH-CI

.. |MIT| image:: https://img.shields.io/badge/License-MIT-yellow.svg
   :target: https://opensource.org/licenses/MIT
   :alt: MIT

.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat
   :target: https://github.com/psf/black
   :alt: Black

.. |pre-commit| image:: https://results.pre-commit.ci/badge/github/ansys/pyansys-geometry/main.svg
   :target: https://results.pre-commit.ci/latest/github/ansys/pyansys-geometry/main
   :alt: pre-commit.ci

PyAnsys Geometry is a Python client library for the Ansys Geometry service.

.. contents::

Usage
-----

There are two different ways of getting started with the Geometry service and its client-library, PyAnsys Geometry.

Using PyAnsys Geometry launcher
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

PyAnsys Geometry is provided with an internal launcher that is capable of handling the specifics of
launching the Geometry service locally. The only requirements are that:

* Docker is installed on your machine.
* You have access to the Geometry service image.

.. note::

   The Geometry service is mainly available as a Windows Docker image. The development
   team is working on getting the Linux Docker container available as soon as possible. In the meantime,
   make sure that your Docker engine is configured to run Windows Docker images.

Using the GitHub Container Registry image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

First, bear in mind that you have to be `authenticated to ghcr.io
<https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry>`_.
Once authenticated, please proceed to download the Geometry service Docker image:

.. code:: bash

   docker pull ghcr.io/ansys/geometry:<tag>

The following OS-dependent tags are available:

* ``windows-latest``
* ``windows-latest-unstable``
* ``linux-latest``
* ``linux-latest-unstable``

Build your own Geometry service image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Access the ``docker`` folder in this repository and go through the instructions
presented in the `main README file <https://github.com/ansys/pyansys-geometry/blob/main/docker/README.rst>`_.

Launching the Geometry service image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Next, you will be ready to run the Geometry service directly from PyAnsys Geometry:

.. code:: python

   from ansys.geometry.core.connection import launch_modeler

   modeler = launch_modeler()

The previous ``launch_modeler()`` method will launch the Geometry service under the default
conditions. For more configurability, please use ``launch_local_modeler()``.

Manual service launch
^^^^^^^^^^^^^^^^^^^^^

First, start the Geometry service locally. If you have Docker installed and have
`authenticated to ghcr.io`_, you can start the service locally using Docker with:

.. code:: bash

   docker run --name ans_geo -e LICENSE_SERVER=<LICENSE-SERVER> -p 50051:50051 ghcr.io/ansys/geometry:<TAG>

The Geometry service has a set of environment variables that are **mandatory**:

* ``LICENSE_SERVER``: the license server (IP, DNS) to which the Geometry service shall connect. For example, ``127.0.0.1``.

Other optional environment variables are:

* ``ENABLE_TRACE``: whether to set up the trace level for debugging purposes. Expects either ``1`` or ``0``.
  By default, ``0`` (which means it is not activated).
* ``LOG_LEVEL``: sets the Geometry service logging level. By default, ``2``.

Next, connect to the service with:

.. code:: python

   from ansys.geometry.core import Modeler

   modeler = Modeler()

By default ``Modeler`` connects to ``127.0.0.1`` (``'localhost'``) on
port ``50051``. You can change this by modifying the ``host`` and ``port``
parameters of ``Modeler``, but note that you must also modify
your ``docker run`` command by changing ``<HOST-PORT>:50051``.

If you want to change the defaults, modify the following environment variables:

**On Linux/Mac OS**

.. code::

   export ANSRV_GEO_HOST=127.0.0.1
   export ANSRV_GEO_PORT=50051

**On Windows Powershell**

.. code::

   $env:ANSRV_GEO_HOST="127.0.0.1"
   $env:ANSRV_GEO_PORT=50051

**On Windows CMD**

.. code::

   SET ANSRV_GEO_HOST=127.0.0.1
   SET ANSRV_GEO_PORT=50051


Install the package
-------------------

PyAnsys Geometry has three installation modes: user, developer, and offline.

Install in user mode
^^^^^^^^^^^^^^^^^^^^

Before installing PyAnsys Geometry in user mode, make sure you have the latest version of
`pip`_ with:

.. code:: bash

   python -m pip install -U pip

Then, install PyAnsys Geometry with:

.. code:: bash

   python -m pip install ansys-geometry-core


Install in developer mode
^^^^^^^^^^^^^^^^^^^^^^^^^

Installing PyAnsys Geometry in developer mode allows
you to modify the source and enhance it.

.. note::

    Before contributing to the project, ensure that you are thoroughly familiar
    with the `PyAnsys Developer's Guide`_.

To install PyAnsys Geometry in developer mode, perform these steps:

#. Clone the ``pyansys-geometry`` repository:

   .. code:: bash

      git clone https://github.com/ansys/pyansys-geometry

#. Access the ``pyansys-geometry`` directory where the repository has been cloned:

   .. code:: bash

      cd pyansys-geometry

#. Create a clean Python virtual environment and activate it:

   .. code:: bash

      # Create a virtual environment
      python -m venv .venv

      # Activate it in a POSIX system
      source .venv/bin/activate

      # Activate it in Windows CMD environment
      .venv\Scripts\activate.bat

      # Activate it in Windows Powershell
      .venv\Scripts\Activate.ps1

#. Make sure you have the latest required build system tools:

   .. code:: bash

      python -m pip install -U pip tox

#. Install the project in editable mode:

   .. code:: bash

      # Install the minimum requirements
      python -m pip install -e .

      # Install the minimum + tests requirements
      python -m pip install -e .[tests]

      # Install the minimum + doc requirements
      python -m pip install -e .[doc]

      # Install all requirements
      python -m pip install -e .[tests,doc]

Install in offline mode
^^^^^^^^^^^^^^^^^^^^^^^

If you lack an internet connection on your installation machine, you should install PyAnsys Geometry
by downloading the wheelhouse archive from the `Releases <https://github.com/ansys/pyansys-geometry/releases>`_
page for your corresponding machine architecture.

Each wheelhouse archive contains all the Python wheels necessary to install PyAnsys Geometry from scratch on Windows,
Linux, and MacOS from Python 3.8 to 3.11. 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.8, unzip the wheelhouse archive and install it with:

.. code:: bash

    unzip ansys-geometry-core-v0.3.1-wheelhouse-Linux-3.8.zip wheelhouse
    pip install ansys-geometry-core -f wheelhouse --no-index --upgrade --ignore-installed

If you're on Windows with Python 3.9, unzip to a wheelhouse directory and install using the preceding command.

Consider installing using a `virtual environment <https://docs.python.org/3/library/venv.html>`_.

Testing
-------

This project takes advantage of `tox`_. This tool automate common
development tasks (similar to Makefile), but it is oriented towards Python
development.

Using ``tox``
^^^^^^^^^^^^^

While Makefile has rules, `tox`_ has environments. In fact, ``tox`` creates its
own virtual environment so that anything being tested is isolated from the project
to guarantee the project's integrity.

The following environments commands are provided:

- **tox -e style**: Checks for coding style quality.
- **tox -e py**: Checks for unit tests.
- **tox -e py-coverage**: Checks for unit testing and code coverage.
- **tox -e doc**: Checks for documentation building process.

 .. admonition:: pyvista-pytest plugin

   This plugin facilitates the comparison of the images produced in PyAnsys Geometry for testing the plots.
   If you are changing the images, use flag ``--reset_image_cache`` which is not recommended except
   for testing or for potentially a major or minor release. For more information, see `pyvista-pytest`_.

Raw testing
^^^^^^^^^^^

If required, from the command line, you can call style commands, including
`black`_, `isort`_, and `flake8`_, and 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.


Using ``pre-commit``
^^^^^^^^^^^^^^^^^^^^

The style checks take advantage of `pre-commit`_. Developers are not forced but
encouraged to install this tool with:

.. code:: bash

    python -m pip install pre-commit && pre-commit install


Documentation
-------------

For building documentation, you can run the usual rules provided in the
`Sphinx`_ Makefile, such as:

.. code:: bash

    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

    tox -e doc && your_browser_name .tox/doc_out/index.html


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

    python -m pip install -U pip
    python -m build
    python -m twine check dist/*


.. LINKS AND REFERENCES
.. _black: https://github.com/psf/black
.. _flake8: https://flake8.pycqa.org/en/latest/
.. _isort: https://github.com/PyCQA/isort
.. _pip: https://pypi.org/project/pip/
.. _pre-commit: https://pre-commit.com/
.. _PyAnsys Developer's Guide: https://dev.docs.pyansys.com/
.. _pytest: https://docs.pytest.org/en/stable/
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _tox: https://tox.wiki/
.. _pyvista-pytest: https://github.com/pyvista/pytest-pyvista

