Ansys Platform Instance Management (PyPIM)
raw JSON → 1.1.2 verified Thu Apr 16 auth: no python
PyPIM (ansys-platform-instancemanagement) is a Python wrapper that provides a Pythonic interface to communicate with the Ansys Product Instance Management (PIM) API. This library enables users to programmatically start Ansys products in remote environments and interact with their APIs. It's designed to simplify the management of service-oriented applications within the Ansys ecosystem. The library is currently at version 1.1.2 and maintains an active release cadence.
pip install ansys-platform-instancemanagement Common errors
error ansys.platform.instancemanagement.errors.NotConfiguredError: The environment is not configured to use PyPIM. ↓
cause The `ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG` environment variable is not set, or the path it points to is invalid/unreadable, or the configuration file itself is malformed.
fix
Create a valid JSON configuration file (e.g.,
pypim_config.json) with the PIM API URI. Set the ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG environment variable to the absolute path of this file before import ansys.platform.instancemanagement. error grpc._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with: status = StatusCode.UNAVAILABLE details = "Connect Failed" debug_error_string = "{"created":"@1678886400.000000000","description":"Failed to connect to remote host: Connection refused","file":"src/core/ext/filters/client_channel/client_channel.cc","file_line":1239,"grpc_status":14}"> ↓
cause PyPIM cannot establish a connection to the PIM API server. This can be due to the server not running, incorrect URI in the configuration, network issues (firewall), or TLS handshake failures if enabled.
fix
Verify that the PIM API server is running and accessible from your client machine. Double-check the
uri in your pypim_config.json for correctness. Ensure no firewalls are blocking the connection and that TLS settings ("tls": true/false) match the server's requirements. error ansys.platform.instancemanagement.errors.InstanceNotReadyError: The instance is not yet ready. ↓
cause An Ansys product instance requested via `create_instance()` has been created but has not finished its startup process and is not yet ready to accept commands.
fix
Ensure your code calls
instance.wait_for_ready() after client.create_instance() to block until the instance is fully initialized. Increase any timeouts if the startup process is expected to be long. Warnings
breaking The API was considered pre-production prior to `v1.0.0`. Version `1.0.0` marked the API as stable and committed to semantic versioning. Code written for versions prior to `1.0.0` may not be compatible with newer releases. ↓
fix Review the PyPIM documentation for `v1.0.0` and later to update any incompatible API calls. Ensure your code adheres to the stable API definitions.
gotcha PyPIM requires access to a running PIM API service. While the PyPIM client is published, the PIM API service itself is not publicly exposed and is still a work in progress by Ansys. Users need to ensure they have an available PIM API backend. ↓
fix Ensure you have access to and are correctly pointing to a deployed Ansys PIM API server instance. Without a running PIM service, PyPIM cannot function.
gotcha PyPIM's default configuration method relies on an external JSON file specified by the `ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG` environment variable. Failing to set this variable or providing an invalid file will result in a `NotConfiguredError` upon attempting to connect. ↓
fix Create a valid JSON configuration file with the PIM API URI and other settings (as shown in the quickstart). Set the `ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG` environment variable to the absolute path of this file before calling `pypim.connect()`.
gotcha Version `1.0.2` included an update to `ansys-api-platform-instancemanagement` to fix 'potential incompatible protobuf version being used'. This indicates a sensitivity to the `protobuf` library version and potential conflicts with other `grpcio` or `protobuf`-dependent packages. [cite: GitHub releases] ↓
fix Always use the latest stable version of `ansys-platform-instancemanagement` to benefit from dependency fixes. If conflicts arise, consider using a dedicated virtual environment or checking the `grpcio` and `protobuf` versions installed.
gotcha Initial support for TLS was introduced in `v1.1.0`. If your PIM API server is configured to require TLS, older PyPIM versions might not connect, or `v1.1.0+` might fail if TLS is misconfigured in your `pypim_config.json`. [cite: GitHub releases, 1] ↓
fix If your PIM API endpoint uses TLS, upgrade to `ansys-platform-instancemanagement==1.1.0` or newer. Ensure your `pypim_config.json` correctly sets `"tls": true` and provides necessary certificate paths if applicable (not shown in basic config, consult full docs).
Imports
- pypim
import ansys.platform.instancemanagement as pypim
Quickstart
import ansys.platform.instancemanagement as pypim
import os
# --- IMPORTANT: External configuration is required ---
# Create a JSON config file (e.g., 'pypim_config.json'):
# {
# "version": 1,
# "pim": {
# "uri": "dns:pim.svc.com:80", # Replace with your PIM API URI
# "headers": {"metadata-info": "value"}, # Optional headers
# "tls": false # Set to true if using TLS
# }
# }
# Set environment variable pointing to this file:
# export ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG="/path/to/pypim_config.json"
# os.environ['ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG'] = '/path/to/pypim_config.json' # For in-code setting
# Ensure the environment is configured before connecting
if pypim.is_configured():
try:
with pypim.connect() as client:
print("Successfully connected to PyPIM.")
# Example: Create an instance (requires compatible PyAnsys product library)
# with client.create_instance(product_name="mapdl", product_version="221") as instance:
# instance.wait_for_ready()
# print(f"MAPDL instance started with URI: {instance.uri}")
except pypim.errors.NotConfiguredError:
print("PyPIM environment not configured. Please set ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG.")
except Exception as e:
print(f"An error occurred: {e}")
else:
print("PyPIM is not configured. Please set the ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG environment variable.")