A python wrapper for Ansys Geometry service
Project description
PyAnsys Geometry is a Python client library for the Ansys Geometry service.
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.
Using the GitHub Container Registry image
First, bear in mind that you have to be authenticated to ghcr.io. Once authenticated, please proceed to download the Geometry service Docker image:
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.
Launching the Geometry service image
Next, you will be ready to run the Geometry service directly from PyAnsys Geometry:
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:
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:
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
export ANSRV_GEO_HOST=127.0.0.1
export ANSRV_GEO_PORT=50051
On Windows Powershell
$env:ANSRV_GEO_HOST="127.0.0.1"
$env:ANSRV_GEO_PORT=50051
On Windows CMD
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:
python -m pip install -U pip
Then, install PyAnsys Geometry with:
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.
To install PyAnsys Geometry in developer mode, perform these steps:
Clone the pyansys-geometry repository:
git clone https://github.com/ansys/pyansys-geometry
Access the pyansys-geometry directory where the repository has been cloned:
cd pyansys-geometry
Create a clean Python virtual environment and activate it:
# 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:
python -m pip install -U pip tox
Install the project in editable mode:
# 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 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:
unzip ansys-geometry-core-v0.3.0-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.
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.
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:
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:
make -C doc/ html && your_browser_name doc/html/index.html
However, the recommended way of checking documentation integrity is to use tox:
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:
python -m pip install -U pip
python -m build
python -m twine check dist/*
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ansys_geometry_core-0.3.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 535df43eb0758c7f04fe3908f890d6338da9f65d32c062b52cc0e35bc45e686b |
|
MD5 | e75d4b2ea1cc1c1706b283216b0c530a |
|
BLAKE2b-256 | 9192f4646080f5ec7385aa304b3cfa50bd76445cc787c0c4b6ce901d05b5c7d5 |
Hashes for ansys_geometry_core-0.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 74e94d8096f231e4d4871c0b3921c03342fe5ab3f4432f02c7741c0873f2de52 |
|
MD5 | 7604f2225551c6755e74766c2e630e74 |
|
BLAKE2b-256 | 89b0e3997ab112b76aa6ad5c4ab54a095b7a08ffa30f5552cc800f00a3b756cc |