Ansys Platform Instance Management (PyPIM)

1.1.2 · active · verified Thu Apr 16

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.

Common errors

```
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`.
```
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.
```
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).

Install

pip install ansys-platform-instancemanagement Install PyPIM

Imports

pypim

import ansys.platform.instancemanagement as pypim

Quickstart

This quickstart demonstrates how to connect to the Ansys PIM API using PyPIM. A crucial step is configuring the environment externally via a JSON file and the `ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG` environment variable, as PyPIM is not self-configuring. The example includes checking if the environment is configured and establishing a connection.

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.")

view raw JSON →