{"id":8827,"library":"ansys-platform-instancemanagement","title":"Ansys Platform Instance Management (PyPIM)","description":"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.","status":"active","version":"1.1.2","language":"en","source_language":"en","source_url":"https://github.com/pyansys/pypim","tags":["Ansys","PIM","gRPC","automation","simulation","platform"],"install":[{"cmd":"pip install ansys-platform-instancemanagement","lang":"bash","label":"Install PyPIM"}],"dependencies":[{"reason":"Provides the auto-generated gRPC Python interface files for the PIM API, which PyPIM wraps.","package":"ansys-api-platform-instancemanagement","optional":false},{"reason":"PyPIM is built on and relies on gRPC for communication with the PIM API.","package":"grpcio","optional":false}],"imports":[{"symbol":"pypim","correct":"import ansys.platform.instancemanagement as pypim"}],"quickstart":{"code":"import ansys.platform.instancemanagement as pypim\nimport os\n\n# --- IMPORTANT: External configuration is required ---\n# Create a JSON config file (e.g., 'pypim_config.json'):\n# {\n#   \"version\": 1,\n#   \"pim\": {\n#     \"uri\": \"dns:pim.svc.com:80\", # Replace with your PIM API URI\n#     \"headers\": {\"metadata-info\": \"value\"}, # Optional headers\n#     \"tls\": false # Set to true if using TLS\n#   }\n# }\n# Set environment variable pointing to this file:\n# export ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG=\"/path/to/pypim_config.json\"\n# os.environ['ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG'] = '/path/to/pypim_config.json' # For in-code setting\n\n# Ensure the environment is configured before connecting\nif pypim.is_configured():\n    try:\n        with pypim.connect() as client:\n            print(\"Successfully connected to PyPIM.\")\n            # Example: Create an instance (requires compatible PyAnsys product library)\n            # with client.create_instance(product_name=\"mapdl\", product_version=\"221\") as instance:\n            #     instance.wait_for_ready()\n            #     print(f\"MAPDL instance started with URI: {instance.uri}\")\n    except pypim.errors.NotConfiguredError:\n        print(\"PyPIM environment not configured. Please set ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG.\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\nelse:\n    print(\"PyPIM is not configured. Please set the ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG environment variable.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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]","severity":"gotcha","affected_versions":"All versions, specifically pre-1.0.2 with certain `protobuf` versions"},{"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).","message":"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]","severity":"gotcha","affected_versions":"<1.1.0 might lack TLS; 1.1.0+ sensitive to TLS config"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"ansys.platform.instancemanagement.errors.NotConfiguredError: The environment is not configured to use PyPIM."},{"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.","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.","error":"grpc._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with:\n\tstatus = StatusCode.UNAVAILABLE\n\tdetails = \"Connect Failed\"\n\tdebug_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}\">"},{"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.","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.","error":"ansys.platform.instancemanagement.errors.InstanceNotReadyError: The instance is not yet ready."}]}