Getting started#

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.

Warning

The simulations described in this documentation require an Additive Suite license. To obtain a license, contact your Ansys sales representative or contact Ansys.

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.

PyAdditive Version	Ansys Release Version
0.19.x	2025 R1
0.18.x	2024 R2
0.17.x	2024 R1

Starting a session#

There are multiple ways to start a session with the PyAdditive client.

Starting a local session#

Instantiating an Additive object starts the local installation of the Additive server.

import ansys.additive.core as pyadditive
additive = pyadditive.Additive()

Starting a remote session#

You can start a remote session by specifying the host name and port of the server.

import ansys.additive.core as pyadditive
additive = pyadditive.Additive(host="additiveserver.mydomain.com", port=12345)

Alternative startup methods#

For additional session startup methods, see the documentation for the Additive class.

Run simulations#

For examples of the types of simulations possible with PyAdditive, see Examples.

User installation#

There are multiple sources for installing the latest stable version of PyAdditive. These include pip and GitHub.

Public PyPI

python -m pip install ansys-additive-core

Ansys PyPI

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

GitHub

python -m pip install git+https://github.com/ansys/pyadditive.git@v0.20.dev5

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:

git clone git@github.com:ansys/pyadditive

Move inside the project and create a new Python environment:

Windows

CMD

py -m venv <venv>

PowerShell

py -m venv <venv>

Linux/UNIX

python -m venv <venv>

Activate previous environment:

Windows

CMD

<venv>\Scripts\activate.bat

PowerShell

<venv>\Scripts\Activate.ps1

Linux/UNIX

source <venv>/bin/activate

Install the required build system tools:

python -m pip install -U pip tox

Verify your development installation:

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.

python -m pip install --editable .

When finished, you can exit the virtual environment:

deactivate

Install in offline mode#

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. 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.12, unzip then install the wheelhouse archive with these commands:

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, 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 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 commands are provided:

tox -e style: Checks for coding style quality.
tox -e py: Checks for and runs unit tests.
tox -e py-coverage: Checks for and runs unit tests, generating code coverage reports.
tox -e doc: Checks for building the documentation successfully.

Raw testing#

If required, from the command line, you can call style commands like ruff 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 tests dependencies.

python -m pip install -e .[tests]
python -m pip install pytest-coverage

Then, run this command from the root folder of the project:

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#

System testing can be done on localhost using the startup method described in Starting a local session within a Python script or Jupyter notebook. The examples folder of the PyAdditive repository contains script files that can be used for testing or converted to Jupyter notebooks using Jupytext.

To test with a notebook, you need to install and run JupyterLab:

python -m venv jupyter_venv​

jupyter_venv\Scripts\activate.bat​

pip install jupyterlab​

pip install jupyterlab

jupyter lab

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.

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:

pip install pre-commit
pre-commit run --all-files

You can also install this as a pre-commit hook by running this command:

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 build twine
python -m build
python -m twine check dist/*

Releasing#

The Additive server is only released with the Ansys unified installation. In between Ansys releases, updates to PyAdditive are released as beta versions with version numbers X.Y.0bZ, where X is the major release, Y is the minor release, and Z is the beta release number. Using beta releases prevents users of pypi.org from inadvertently getting updates that won’t work with the released version of the server. When a new version of Ansys is released, PyAdditive is released with a version number of X.Y.0.

To create a release of PyAdditive, follow the Releasing and publishing instructions in the PyAnsys Developer’s guide.