PyWorkbench

https://workbench.docs.pyansys.com/version/stable
Admin
PyWorkbench is a Python client library for Ansys Workbench that enables programmatic automation,...
Tokens:14,587
Snippets:181
Trust Score:5.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start PyFluent Server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Starts a PyFluent server and returns the path to the server information file required for client connection.

```python
>>> import ansys.fluent.core as pyfluent
>>> server_info_file=wb.start_fluent_server(system_name=fluent_sys_name)
>>> fluent=pyfluent.connect_to_fluent(server_info_file_name=server_info_file)
```

--------------------------------

### Start PySherlock Server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Starts a PySherlock server and connects a client using the returned port.

```python
>>> from ansys.sherlock.core import pysherlock
>>> server_port=wb.start_sherlock_server(system_name=sherlock_system_name)
>>> sherlock = pysherlock.connect_grpc_channel(port=server_port)
>>> sherlock.common.check()
```

--------------------------------

### POST /start_fluent_server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Starts the PyFluent server for a specified system in the Workbench project.

```APIDOC
## POST /start_fluent_server

### Description
Start the PyFluent server for the given system in the Workbench project.

### Parameters
#### Request Body
- **system_name** (str) - Required - Name of the system in the Workbench project.

### Response
#### Success Response (200)
- **file_path** (str) - Path to the local file containing the PyFluent server information.
```

--------------------------------

### Install PyWorkbench artifacts

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/linux.rst.txt

Commands to install downloaded wheel or source distribution files.

```text
python -m pip install {{ wheels }}
```

```text
python -m pip install {{ source }}
```

--------------------------------

### POST /start_sherlock_server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Starts the PySherlock server for a specified system in the Workbench project.

```APIDOC
## POST /start_sherlock_server

### Description
Start the PySherlock server for the given system in the Workbench project.

### Parameters
#### Request Body
- **system_name** (str) - Required - Name of the system in the Workbench project.

### Response
#### Success Response (200)
- **port** (int) - Port of the PySherlock server to use to start a PySherlock client.
```

--------------------------------

### Start Mechanical Server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Starts the PyMechanical server for a given system in the Workbench project.

```APIDOC
## POST /start_mechanical_server

### Description
Start the PyMechanical server for the given system in the Workbench project.

### Method
POST

### Endpoint
/start_mechanical_server

### Parameters
#### Request Body
- **system_name** (string) - Required - The name of the system to start the server for.
- **port** (integer) - Optional - The port number to start the server on. Default: 0 (auto-assign)

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the server has started.

#### Response Example
{
  "message": "PyMechanical server started for system 'System 1' on port 5000."
}
```

--------------------------------

### Upload file from example repository

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Uploads a data file directly to the Workbench server from the example-data repository.

```python
client.upload_file_from_example_repo("pymechanical-integration/agdb/two_pipes.agdb")
```

--------------------------------

### POST /start_mechanical_server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Starts a PyMechanical server for a specified system in the Workbench project.

```APIDOC
## POST /start_mechanical_server

### Description
Starts a PyMechanical server for the given system in the Workbench project.

### Parameters
#### Request Body
- **system_name** (str) - Required - Name of the system in the Workbench project.
- **port** (int) - Optional - Port to use for mechanical server if possible.

### Response
#### Success Response (200)
- **port** (int) - Port of the PyMechanical server to use to start the PyMechanical client.
```

--------------------------------

### Verify PyWorkbench Installation

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/windows.rst.txt

Run this Python code to verify that PyWorkbench has been successfully installed. This code imports the launch_workbench function and executes it.

```python
from ansys.workbench.core import launch_workbench

launch_workbench()
```

--------------------------------

### Launch a Workbench server

Source: https://workbench.docs.pyansys.com/version/stable/user-guide.html

Starts a Workbench server instance locally or on a remote machine.

```python
from ansys.workbench.core import launch_workbench

wb = launch_workbench()
```

```python
from ansys.workbench.core import launch_workbench

host = "server_machine_name_or_ip"
username = "your_username_on_server_machine"
password = "your_password_on_server_machine"
wb = launch_workbench(host=host, username=username, password=password)
```

```python
from ansys.workbench.core import launch_workbench

wb = launch_workbench(
    show_gui=False,
    version="251",
    server_workdir="path_to_a_dir_on_server",
    client_workdir="path_to_a_dir_on_client",
)
```

--------------------------------

### Install PyWorkbench from Source Artifact

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/windows.rst.txt

Install PyWorkbench using pip after downloading the source artifact. Ensure the source file is in the current directory or provide the correct path.

```text
python -m pip install {{ source }}
```

--------------------------------

### Start PyMechanical Server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Initializes a PyMechanical server session for a specified system and connects a client.

```python
>>> from ansys.mechanical.core import connect_to_mechanical
>>> server_port=wb.start_mechanical_server(system_name=mech_system_name)
>>> mechanical = connect_to_mechanical(port=server_port)
```

--------------------------------

### Install PyWorkbench from PyPI

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/windows.rst.txt

Use this pip command to install the PyWorkbench package from the Python Package Index.

```shell
python -m pip install ansys-workbench-core
```

--------------------------------

### Verify PyWorkbench Installation

Source: https://workbench.docs.pyansys.com/version/stable/getting-started/installing/windows.html

Run this Python code to verify that PyWorkbench has been installed successfully and can be launched.

```python
from ansys.workbench.core import launch_workbench

launch_workbench()

```

--------------------------------

### Connect to Fluent

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Connect to a Fluent server instance using server information. The server info file is obtained from starting the Fluent server.

```python
import ansys.fluent.core as pyfluent
server_info_file=wb.start_fluent_server(system_name=fluent_sys_name)
fluent=pyfluent.connect_to_fluent(server_info_file_name=server_info_file)
```

--------------------------------

### Upload File from Example Repository

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Uploads a file from the Ansys example-data repository to the server.

```APIDOC
## POST /upload_file_from_example_repo

### Description
Upload a file from the Ansys ``example-data`` repository to the server.

### Method
POST

### Endpoint
/upload_file_from_example_repo

### Parameters
#### Request Body
- **relative_file_path** (string) - Required - File path relative to the ``pyworkbench`` folder in the ``example-data`` repository.
- **show_progress** (boolean) - Optional - Whether to show a progress bar during the upload. Default: true

### Response
#### Success Response (200)
- **uploaded_file** (string) - Name of the uploaded file.

#### Response Example
{
  "uploaded_file": "example_data.iges"
}
```

--------------------------------

### Install PyWorkbench from Wheel Artifact

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/windows.rst.txt

Install PyWorkbench using pip after downloading the wheel artifact. Ensure the wheel file is in the current directory or provide the correct path.

```text
python -m pip install {{ wheels }}
```

--------------------------------

### Launch Ansys Workbench Session

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/development.rst.txt

Launch an Ansys Workbench server session locally to verify the PyWorkbench installation. Ensure Ansys Workbench is installed locally.

```python
from ansys.workbench.core import launch_workbench

workbench = launch_workbench()
```

--------------------------------

### Install PyWorkbench in Editable Mode

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/development.rst.txt

Install the PyWorkbench project in editable mode. This allows changes to the source code to be reflected immediately without reinstallation.

```bash
python -m pip install --editable .
```

--------------------------------

### Install PyWorkbench from Source Artifact

Source: https://workbench.docs.pyansys.com/version/stable/getting-started/installing/windows.html

Use this pip command to install PyWorkbench using a downloaded source artifact. Ensure the tar.gz file is in your current directory or provide the correct path.

```bash
python -m pip install ansys_workbench_core-0.11.0.tar.gz

```

--------------------------------

### Start and stop PyFluent service

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Initializes a Fluent system and connects the PyFluent service, or stops it for a specific system.

```python
import ansys.fluent.core as pyfluent

sys_name = wb.run_script_string(
    r"""import json
wb_script_result=json.dumps(GetTemplate(TemplateName="FLUENT").CreateSystem().Name)
"""
)
server_info_file = wb.start_fluent_server(system_name=sys_name)
fluent = pyfluent.connect_to_fluent(server_info_file_name=server_info_file)
```

```python
wb.stop_fluent_server(system_name=sys_name)
```

--------------------------------

### Fluent Server Management

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Methods to start and stop a PyFluent server for a specific system.

```APIDOC
## POST /start_fluent_server

### Description
Starts the PyFluent server for the given system in the Workbench project.

### Parameters
#### Request Body
- **system_name** (str) - Required - Name of the system in the Workbench project.

### Response
#### Success Response (200)
- **server_info_file** (str) - Path to the local file containing the PyFluent server information.

## POST /stop_fluent_server

### Description
Stops the Fluent server for the given system in the Workbench project.

### Parameters
#### Request Body
- **system_name** (str) - Required - Name of the system in the Workbench project.
```

--------------------------------

### Install PyWorkbench from Wheel Artifact

Source: https://workbench.docs.pyansys.com/version/stable/getting-started/installing/windows.html

Use this pip command to install PyWorkbench using a downloaded wheel artifact. Ensure the wheel file is in your current directory or provide the correct path.

```bash
python -m pip install ansys_workbench_core-0.11.0-py3-none-any.whl

```

--------------------------------

### Upload Files to Workbench Server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Upload files from the client to the server. This example uploads part files with a specific prefix, AGDB files, and another file outside the working directory.

```python
wb.upload_file("model?.prt", "*.agdb", "/path/to/some/file")
```

--------------------------------

### PyMechanical Server Control

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Methods for starting and managing PyMechanical server instances.

```APIDOC
## WorkbenchClient.start_mechanical_server()

### Description
Start the PyMechanical server for the given system in the Workbench project.

### Method
start_mechanical_server

### Endpoint
N/A

### Parameters
#### Request Body
- **system_name** (str) - Required - Name of the system in the Workbench project.
- **port** (int) - Optional - Port to use for mechanical server if possible.

### Response
#### Success Response (200)
- **port** (int) - Port of the PyMechanical server to use to start the PyMechanical client.
```

--------------------------------

### Mechanical Server Management

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Methods to start and stop a PyMechanical server for a specific system.

```APIDOC
## POST /start_mechanical_server

### Description
Starts the PyMechanical server for the given system in the Workbench project.

### Parameters
#### Request Body
- **system_name** (str) - Required - Name of the system in the Workbench project.

### Request Example
{
  "system_name": "mech_system_name"
}

## POST /stop_mechanical_server

### Description
Stops the PyMechanical server for the given system in the Workbench project.

### Parameters
#### Request Body
- **system_name** (str) - Required - Name of the system in the Workbench project.

### Request Example
{
  "system_name": "mech_system_name"
}
```

--------------------------------

### Connect to Mechanical

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Connect to an existing Mechanical server instance. Requires the server port obtained from starting the server.

```python
from ansys.mechanical.core import connect_to_mechanical
server_port=wb.start_mechanical_server(system_name=mech_system_name)
mechanical = connect_to_mechanical(port=server_port)
```

--------------------------------

### Sherlock Server Management

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Methods to start and stop a PySherlock server for a specific system.

```APIDOC
## POST /start_sherlock_server

### Description
Starts the PySherlock server for the given system in the Workbench project.

### Parameters
#### Request Body
- **system_name** (str) - Required - Name of the system in the Workbench project.

### Response
#### Success Response (200)
- **port** (int) - Port of the PySherlock server to use to start a PySherlock client.

## POST /stop_sherlock_server

### Description
Stops the Sherlock server for the given system in the Workbench project.

### Parameters
#### Request Body
- **system_name** (str) - Required - Name of the system in the Workbench project.
```

--------------------------------

### Start and stop PySherlock service

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Initializes a Sherlock system and connects the PySherlock service, or stops it for a specific system.

```python
from ansys.sherlock.core import launcher as pysherlock

sys_name = wb.run_script_string(
    r"""import json
wb_script_result=json.dumps(GetTemplate(TemplateName="SherlockPre").CreateSystem().Name)
"""
)
server_port = wb.start_sherlock_server(system_name=sys_name)
sherlock = pysherlock.connect_grpc_channel(port=server_port)
```

```python
wb.stop_sherlock_server(system_name=sys_name)
```

--------------------------------

### Start and stop PyMechanical service

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Initializes a Mechanical system and connects the PyMechanical service, or stops it for a specific system.

```python
from ansys.mechanical.core import connect_to_mechanical

sys_name = wb.run_script_string(
    r"""import json
wb_script_result=json.dumps(GetTemplate(TemplateName="Static Structural (ANSYS)").CreateSystem().Name)
"""
)
server_port = wb.start_mechanical_server(system_name=sys_name)
mechanical = connect_to_mechanical(ip="localhost", port=server_port)
```

```python
wb.stop_mechanical_server(system_name=sys_name)
```

--------------------------------

### Connect to Sherlock

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Connect to a PySherlock gRPC channel using the server port. The port is obtained after starting the Sherlock server.

```python
from ansys.sherlock.core import pysherlock
server_port=wb.start_sherlock_server(system_name=sherlock_system_name)
sherlock = pysherlock.connect_grpc_channel(port=server_port)
sherlock.common.check()
```

--------------------------------

### Launch a local Workbench server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/public_api/index.rst.txt

Initializes a new Workbench server instance on the local machine and returns a client object.

```python
>>> from ansys.workbench.core import launch_workbench
>>> wb = launch_workbench()
```

--------------------------------

### Launch Workbench Server with Options

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Launch a Workbench server with additional options such as specifying the Workbench version, UI mode, and working directories for the server and client.

```python
from ansys.workbench.core import launch_workbench

wb = launch_workbench(
    show_gui=False,
    version="251",
    server_workdir="path_to_a_dir_on_server",
    client_workdir="path_to_a_dir_on_client",
)
```

--------------------------------

### Create a Python virtual environment

Source: https://workbench.docs.pyansys.com/version/stable/getting-started/installing/development.html

Commands to initialize a clean Python virtual environment for different operating systems.

```cmd
py -m venv <venv>
```

```powershell
py -m venv <venv>
```

```bash
python -m venv <venv>
```

--------------------------------

### Launch Workbench Server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_launcher/Launcher.rst.txt

Details on how to launch a Workbench server with various configuration options.

```APIDOC
## POST /launch

### Description

Launch PyWorkbench server on the local or a remote computer. Supports specifying Workbench version, GUI display, server working directory, connection port, security settings, and remote host details.

### Method

POST

### Endpoint

/launch

### Parameters

#### Query Parameters

- **version** (str) - Optional - Workbench version to launch. It must be a three-digit version, such as ``242`` or later. The latest version available will be used if None.
- **show_gui** (bool) - Optional - Whether to launch Workbench in UI mode. Defaults to True.
- **server_workdir** (str) - Optional - Path to a writable directory on the server. The default is None, in which case the user preference for the Workbench temporary file folder is used.
- **port_to_use** (int) - Optional - The port to use for the server connection. Defaults to -1 (automatic selection).
- **use_insecure_connection** (bool) - Optional - Whether to use insecure connection between the server and clients. Defaults to False.
- **host** (str) - Optional - Name or IP address of the server. The default is None, which launches Workbench on the local computer.
- **username** (str) - Optional - User's login name on the server. The default is None, which launches Workbench on the local computer.
- **password** (str) - Optional - User's password on the server. The default is None, which launches Workbench on the local computer.

### Raises

- Exception: If the Ansys version string is invalid.
- Exception: If the host is given but the username or password is missing.
- Exception: If remote launching is attempted from or onto a Linux machine.
- Exception: If the wmi service on the remote Windows machine fails.
- Exception: If the Ansys installation is not found.
```

--------------------------------

### Launcher.launch

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_launcher/Launcher.html

Launches a PyWorkbench server on a local or remote computer.

```APIDOC
## Launcher.launch

### Description
Launch PyWorkbench server on the local or a remote computer.

### Parameters
#### Request Body
- **version** (str) - Optional - Workbench version to launch (e.g., '242'). Defaults to latest.
- **show_gui** (bool) - Optional - Whether to launch Workbench in UI mode. Defaults to True.
- **server_workdir** (str) - Optional - Path to a writable directory on the server.
- **port_to_use** (int) - Optional - Port to use for the server.
- **use_insecure_connection** (bool) - Optional - Whether to use insecure connection. Defaults to False.
- **host** (str) - Optional - Name or IP address of the server.
- **username** (str) - Optional - User login name on the server.
- **password** (str) - Optional - User password on the server.
```

--------------------------------

### Import WorkbenchClient

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Import the WorkbenchClient class to begin interacting with the Workbench server.

```python
from ansys.workbench.core.workbench_client import WorkbenchClient
```

--------------------------------

### launch_workbench

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/public_api/index.rst.txt

Launches a PyWorkbench server on the local or a remote Windows machine and returns a client instance.

```APIDOC
## launch_workbench

### Description
Launch a Workbench server on the local machine or a remote Windows machine and create a PyWorkbench client that connects to the server.

### Parameters
- **show_gui** (bool) - Optional - Whether to launch Workbench in UI mode. Default: True.
- **version** (str) - Optional - Workbench version to launch (e.g., '242'). Default: None.
- **client_workdir** (str) - Optional - Path to a writable directory on the client computer. Default: None.
- **server_workdir** (str) - Optional - Path to a writable directory on the server computer. Default: None.
- **port** (int) - Optional - Port to use for the launched server.
- **use_insecure_connection** (bool) - Optional - Whether to use insecure connection. Default: False.
- **host** (str) - Optional - Server computer's name or IP address.
- **username** (str) - Optional - User's login name on the server.
- **password** (str) - Optional - User's password on the server.

### Response
- **WorkbenchClient** (object) - Instance of the PyWorkbench client connected to the server.
```

--------------------------------

### launch_workbench

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/public_api/index.html

Launches a PyWorkbench server on the local or a remote Windows machine and returns a connected client instance.

```APIDOC
## launch_workbench

### Description
Launch PyWorkbench server on the local machine or a remote Windows machine and create a client connection.

### Parameters
- **show_gui** (bool) - Optional - Whether to launch Workbench in UI mode. Default: True
- **version** (str) - Optional - Workbench version to launch (e.g., '242' or later). Default: None
- **client_workdir** (str) - Optional - Path to a writable directory on the client computer. Default: None
- **server_workdir** (str) - Optional - Path to a writable directory on the server computer. Default: None
- **port** (int) - Optional - Port to use for the launched server.
- **use_insecure_connection** (bool) - Optional - Whether to use insecure connection. Default: False
- **host** (str) - Optional - Server computer name or IP address. Default: None
- **username** (str) - Optional - User login name on the server. Default: None
- **password** (str) - Optional - User password on the server. Default: None

### Response
- **WorkbenchClient** (object) - Instance of the PyWorkbench client connected to the server.
```

--------------------------------

### Create Python Virtual Environment (Linux/UNIX)

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/development.rst.txt

Create a Python virtual environment on Linux or UNIX systems.

```bash
python -m venv <venv>
```

--------------------------------

### WorkbenchClient Initialization

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Initializes the WorkbenchClient to connect to a Workbench server. It requires specifying the local working directory and server connection details.

```APIDOC
## WorkbenchClient Initialization

### Description
Initializes the WorkbenchClient to connect to a Workbench server. It requires specifying the local working directory and server connection details.

### Parameters
#### Path Parameters
- **local_workdir** (string) - Required - Local working directory for the client.
- **server_host** (string) - Required - Hostname or IP address of the server.
- **server_port** (integer) - Required - Port number of the server.
- **server_security** (string) - Required - Security mode of the server. Options are: "insecure", "uds", "wnua", "mtls"
```

--------------------------------

### Launcher.exit

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_launcher/Launcher.html

Terminates the currently running Workbench server instance.

```APIDOC
## Launcher.exit

### Description
End the launched Workbench server.
```

--------------------------------

### Launcher Class Overview

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_launcher/Launcher.rst.txt

Provides an overview of the Launcher class and its primary methods.

```APIDOC
## Launcher Class

### Description

The Launcher class is used to manage the lifecycle of an Ansys Workbench server instance, allowing you to launch and exit servers on local or remote machines.

### Import Detail

```python
from ansys.workbench.core.workbench_launcher import Launcher
```

### Methods

- **launch**: Launch PyWorkbench server on the local or a remote computer.
- **exit**: End the launched Workbench server.
```

--------------------------------

### Activate Virtual Environment (Linux/UNIX)

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/development.rst.txt

Activate the created virtual environment on Linux or UNIX systems.

```bash
source <venv>/bin/activate
```

--------------------------------

### Connect to an existing Workbench server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/public_api/index.rst.txt

Establishes a connection to a running Workbench server instance using a specified port.

```python
>>> from ansys.workbench.core import connect_workbench
>>> wb = connect_workbench(port = 32588)
```

--------------------------------

### Launch Workbench Server Locally

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Launch a Workbench server on a local Windows or Linux machine for development or debugging purposes.

```python
from ansys.workbench.core import launch_workbench

wb = launch_workbench()
```

--------------------------------

### Activate the virtual environment

Source: https://workbench.docs.pyansys.com/version/stable/getting-started/installing/development.html

Commands to activate the created virtual environment based on the host operating system.

```cmd
<venv>\Scripts\activate.bat
```

```powershell
<venv>\Scripts\Activate.ps1
```

```bash
source <venv>/bin/activate
```

--------------------------------

### Download project archive

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Saves, archives, and downloads the current Workbench project.

```python
wb.download_project_archive(
    archive_name="my_project_archive", include_solution_result_files=False
)
```

--------------------------------

### Run a Workbench script string

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Executes a provided string as a Workbench script on the server. The script should return the desired output as a string.

```python
>>> wb.run_script_string(r'''import json
wb_script_result=json.dumps(GetTemplate(TemplateName="FLUENT").CreateSystem().Name)
''')
```

--------------------------------

### connect_workbench

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/public_api/index.rst.txt

Creates a PyWorkbench client that connects to an already running Workbench server.

```APIDOC
## connect_workbench

### Description
Create a PyWorkbench client that connects to an already running Workbench server.

### Parameters
- **port** (int) - Required - Port used by the server.
- **client_workdir** (str) - Optional - Path to a writable directory on the client computer. Default: None.
- **host** (str) - Optional - Server computer's name or IP address. Default: None.
- **security** (str) - Optional - Transport mode ('mtls', 'wnua', 'insecure'). Default: 'mtls'.

### Response
- **WorkbenchClient** (object) - Instance of the PyWorkbench client connected to the server.
```

--------------------------------

### Launch Workbench Server

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_launcher/Launcher.html

Launch a Workbench server on a local or remote computer. Specify Workbench version, whether to show the GUI, server working directory, port, connection security, and remote host credentials if applicable. Note that remote launching to or from Linux is not supported.

```python
Launcher.launch(_version =None_, _show_gui =True_, _server_workdir =None_, _port_to_use =-1_, _use_insecure_connection =False_, _host =None_, _username =None_, _password =None_)
```

--------------------------------

### Create Python Virtual Environment (Windows)

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/development.rst.txt

Create a Python virtual environment on Windows using either CMD or PowerShell. Replace `<venv>` with your desired environment name.

```text
py -m venv <venv>
```

--------------------------------

### WorkbenchClient Initialization

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Initializes a WorkbenchClient to connect to the Ansys Workbench server. It requires local working directory, server host, port, and security mode.

```APIDOC
## WorkbenchClient Initialization

### Description
Initializes a WorkbenchClient to connect to the Ansys Workbench server. It requires local working directory, server host, port, and security mode.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```python
WorkbenchClient(_local_workdir_: str, _server_host_: str, _server_port_: int, _server_security_: str)
```

### Parameters
- **_local_workdir_** (str) - Required - Local working directory for the client.
- **_server_host_** (str) - Required - Hostname or IP address of the server.
- **_server_port_** (int) - Required - Port number of the server.
- **_server_security_** (str) - Required - Security mode of the server. Options are: "insecure", "uds", "wnua", "mtls"

### Request Example
```python
from ansys.workbench.core.workbench_client import WorkbenchClient

client = WorkbenchClient(local_workdir="/path/to/local/workdir", server_host="localhost", server_port=5000, server_security="insecure")
```

### Response
None (Constructor does not return a value directly, but initializes the client object.)

### Error Handling
Potential errors include invalid server host/port, incorrect security mode, or network connectivity issues.
```

--------------------------------

### Context Management

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Explains how to use the WorkbenchClient within a Python context manager for automatic connection and disconnection.

```APIDOC
## Context Management

### Description
Explains how to use the WorkbenchClient within a Python context manager for automatic connection and disconnection.

### Methods

#### `__enter__()`
Connect to the server when entering a context.

#### `__exit__(exc_type, exc_value, traceback)`
Disconnect from the server when exiting a context.
```

--------------------------------

### Activate Virtual Environment (Windows CMD)

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/development.rst.txt

Activate the created virtual environment in Windows Command Prompt. Replace `<venv>` with your environment's name.

```batch
<venv>\Scripts\activate.bat
```

--------------------------------

### Connect to Workbench Server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Connect to a running Workbench server on the cloud by providing the port number and server name or IP address. The client-side working directory can also be specified.

```python
from ansys.workbench.core import connect_workbench

host = "server_machine_name_or_IP"
port = server_port_number
wb = connect_workbench(host=host, port=port)
```

--------------------------------

### Download Project Archive

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Creates and downloads the project archive from the server.

```APIDOC
## GET /download_project_archive

### Description
Create and download the project archive.

### Method
GET

### Endpoint
/download_project_archive

### Parameters
#### Query Parameters
- **archive_name** (string) - Required - Name of the project archive to use, without the file extension.
- **include_solution_result_files** (boolean) - Optional - Whether to include solution and result files in the archive. Default: true
- **show_progress** (boolean) - Optional - Whether to show a progress bar during the download. Default: true

### Response
#### Success Response (200)
- **archive_name** (string) - Name of the downloaded project archive.

#### Response Example
{
  "archive_name": "MyProject.wbpj.zip"
}
```

--------------------------------

### Launcher Class

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_launcher/index.rst.txt

The Launcher class is used to manage the lifecycle of a Workbench server instance.

```APIDOC
## CLASS Launcher

### Description
Provides functionality to launch a Workbench server on a local or remote machine.

### Module
ansys.workbench.core.workbench_launcher
```

--------------------------------

### WorkbenchClient Methods

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Provides details on the various methods available in the WorkbenchClient class for managing logs, running scripts, and handling files.

```APIDOC
## WorkbenchClient Methods

### Description
Provides details on the various methods available in the WorkbenchClient class for managing logs, running scripts, and handling files.

### Methods

#### `set_console_log_level(log_level)`
Set the log filter level for the client console.

- **log_level** (string) - Optional, default: "error" - Level of logging. Options are "critical", "debug", "error", "info", and "warning".

#### `set_log_file(log_file)`
Set a local log file for the Workbench server log. Create a local log file if one does not exist and append it to the existing log file.

- **log_file** (string) - Required - Path to a local file to use for logging.

#### `reset_log_file()`
No longer use the current log file for the Workbench server log.

#### `run_script_string(script_string)`
Run a script as given in the input string on the server.

#### `run_script_file(script_file_path)`
Run a script file on the server.

#### `upload_file(local_file_paths, remote_directory)`
Upload one or more files from the client to the server.

- **local_file_paths** (list of strings) - Required - Paths to the local files to upload.
- **remote_directory** (string) - Optional - The directory on the server to upload the files to.

#### `upload_file_from_example_repo(file_name, remote_directory)`
Upload a file from the Ansys ``example-data`` repository to the server.

- **file_name** (string) - Required - The name of the file to upload from the example repository.
- **remote_directory** (string) - Optional - The directory on the server to upload the file to.

#### `download_file(remote_file_paths, local_directory)`
Download one or more files from the server.

- **remote_file_paths** (list of strings) - Required - Paths to the remote files to download.
- **local_directory** (string) - Optional - The local directory to download the files to.

#### `download_project_archive(archive_path)`
Create and download the project archive.

- **archive_path** (string) - Required - The path where the project archive will be saved locally.

#### `start_mechanical_server(system_name)`
Start the PyMechanical server for the given system in the Workbench project.

- **system_name** (string) - Required - The name of the system in the Workbench project.

#### `stop_mechanical_server(system_name)`
Stop the PyMechanical server for the given system in the Workbench project.

- **system_name** (string) - Required - The name of the system in the Workbench project.

#### `start_fluent_server(system_name)`
Start the PyFluent server for the given system in the Workbench project.

- **system_name** (string) - Required - The name of the system in the Workbench project.

#### `stop_fluent_server(system_name)`
Stop the PyFluent server for the given system in the Workbench project.

- **system_name** (string) - Required - The name of the system in the Workbench project.

#### `start_sherlock_server(system_name)`
Start the PySherlock server for the given system in the Workbench project.

- **system_name** (string) - Required - The name of the system in the Workbench project.

#### `stop_sherlock_server(system_name)`
Stop the Sherlock server for the given system in the Workbench project.

- **system_name** (string) - Required - The name of the system in the Workbench project.
```

--------------------------------

### Context Management

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Methods for managing the connection context with the Workbench server.

```APIDOC
## WorkbenchClient.__enter__()

### Description
Connect to the server when entering a context.

### Method
__enter__

### Endpoint
N/A (Context Manager)

### Parameters
None

## WorkbenchClient.__exit__()

### Description
Disconnect from the server when exiting a context.

### Method
__exit__

### Endpoint
N/A (Context Manager)

### Parameters
- **_exc_type_** (type) - Description
- **_exc_value_** (type) - Description
- **_traceback_** (type) - Description
```

--------------------------------

### Import Launcher Class

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_launcher/Launcher.html

Import the Launcher class from the ansys.workbench.core.workbench_launcher module. This is required before instantiating the Launcher.

```python
from ansys.workbench.core.workbench_launcher import Launcher
```

--------------------------------

### Launch Workbench Server Remotely

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Launch a Workbench server on a remote Windows machine using valid user credentials. Specify the host, username, and password.

```python
from ansys.workbench.core import launch_workbench

host = "server_machine_name_or_ip"
username = "your_username_on_server_machine"
password = "your_password_on_server_machine"
wb = launch_workbench(host=host, username=username, password=password)
```

--------------------------------

### WorkbenchClient Properties and Special Methods

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Details the properties and special methods of the WorkbenchClient, including accessing the server version and managing the client's connection context.

```APIDOC
## WorkbenchClient Properties and Special Methods

### Description
Details the properties and special methods of the WorkbenchClient, including accessing the server version and managing the client's connection context.

### Properties

- **`server_version`**: The Workbench version of the connected server.
- **`workdir`**: The working directory of the client on the server.

### Special Methods

- **`__enter__`**: Connect to the server when entering a context.
- **`__exit__`**: Disconnect from the server when exiting a context.

### Property Detail

#### `server_version`
_property _WorkbenchClient.server_version#

The Workbench version of the connected server.

### Attribute Detail

#### `workdir`
WorkbenchClient.workdir#

### Example Usage

#### Accessing Server Version
```python
server_version = client.server_version
print(f"Connected to Workbench version: {server_version}")
```

#### Using Context Manager
```python
with WorkbenchClient(local_workdir="/path/to/workdir", server_host="localhost", server_port=5000, server_security="insecure") as client:
    # Operations within the context
    print(client.server_version)
# Client is automatically disconnected upon exiting the 'with' block
```

### Response
- **`server_version`**: (str) - The version string of the connected Workbench server.
- **`workdir`**: (str) - The path to the working directory on the server.
```

--------------------------------

### Activate Virtual Environment (Windows PowerShell)

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/installing/development.rst.txt

Activate the created virtual environment in Windows PowerShell. Replace `<venv>` with your environment's name.

```powershell
<venv>\Scripts\Activate.ps1
```

--------------------------------

### Script Execution

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Methods for running scripts on the Workbench server, either from a string or a file.

```APIDOC
## WorkbenchClient.run_script_string()

### Description
Run a script as given in the input string on the server.

### Method
run_script_string

### Endpoint
N/A

### Parameters
#### Request Body
- **script_string** (str) - Required - String containing the content of the script to run.
- **args** (dictionary) - Optional - Variables in the script specified as $$varname%%50%% will be converted to variable values or use the default value - 50 in the example.
- **log_level** (str) - Optional - Level of logging. Options are “critical”, “debug”, “error”, “info”, and “warning”.

### Response
#### Success Response (200)
- **Output** (str) - Output defined in the script.

### Request Example
```python
{
  "script_string": "import json\nwb_script_result=json.dumps(GetTemplate(TemplateName=\"FLUENT\").CreateSystem().Name)"
}
```

## WorkbenchClient.run_script_file()

### Description
Run a script file on the server.

### Method
run_script_file

### Endpoint
N/A

### Parameters
#### Request Body
- **script_file_name** (str) - Required - Name of the script file to run. The script file should be located in the client working directory.
- **args** (dictionary) - Optional - Variables in the script specified as $$varname%%50%% will be converted to variable values or use the default value - 50 in the example.
- **log_level** (str) - Optional - Level of logging. Options are “critical”, “debug”, “error”, “info”, and “warning”.

### Response
#### Success Response (200)
- **Output** (str) - Output defined in the script.
```

--------------------------------

### Connect PyWorkbench to Local Ansys Workbench

Source: https://workbench.docs.pyansys.com/version/stable/_sources/getting-started/connection.rst.txt

Use this snippet to connect PyWorkbench to a local Ansys Workbench session. Ensure Ansys Workbench is running and `StartServer()` has been executed in its command window.

```python
from ansys.workbench.core import connect_workbench

workbench = connect_workbench(port=port)
```

--------------------------------

### Copy Mechanical solver output file on server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Uses a server-side script to copy the solve.out file to the server's working directory.

```python
wb.run_script_string(
    r"""import os
import shutil
work_dir = GetServerWorkingDirectory()
mechanical_dir = mechanical.project_directory
out_file_src = os.path.join(mechanical_dir, "solve.out")
out_file_des = os.path.join(work_dir, "solve.out")
shutil.copyfile(out_file_src, out_file_des)
"""
)
```

--------------------------------

### Run Script File

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Executes a Python script from a specified file on the server.

```APIDOC
## POST /run_script_file

### Description
Run a script file on the server.

### Method
POST

### Endpoint
/run_script_file

### Parameters
#### Request Body
- **script_file_name** (string) - Required - Name of the script file to run. The script file should be located in the client working directory.
- **args** (dictionary) - Optional - Variables in the script specified as $$varname%%50%% will be converted to variable values or use the default value - 50 in the example.
- **log_level** (string) - Optional - Level of logging. Options are "critical", "debug", "error", "info", and "warning". Default: "error"

### Response
#### Success Response (200)
- **output** (string) - Output defined in the script.

#### Response Example
{
  "output": "Script execution output"
}
```

--------------------------------

### File Management

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Methods for uploading and downloading files between the client and the Workbench server.

```APIDOC
## WorkbenchClient.upload_file()

### Description
Upload one or more files from the client to the server.

### Method
upload_file

### Endpoint
N/A

### Parameters
#### Request Body
- **file_list** (list[str]) - Required - List of paths to the one or more local files to upload. The wildcard characters “?” and “*” are supported.
- **show_progress** (bool) - Optional - Whether to show a progress bar during the upload.

### Response
#### Success Response (200)
- **uploaded_files** (list[str]) - Names of the uploaded files.

## WorkbenchClient.upload_file_from_example_repo()

### Description
Upload a file from the Ansys `example-data` repository to the server.

### Method
upload_file_from_example_repo

### Endpoint
N/A

### Parameters
#### Request Body
- **relative_file_path** (str) - Required - File path relative to the `pyworkbench` folder in the `example-data` repository.
- **show_progress** (bool) - Optional - Whether to show a progress bar during the upload.

### Response
#### Success Response (200)
- **uploaded_file** (str) - Name of the uploaded file.

## WorkbenchClient.download_file()

### Description
Download one or more files from the server.

### Method
download_file

### Endpoint
N/A

### Parameters
#### Request Body
- **file_name** (str) - Required - Name of the file. File must be located in the server’s working directory. The wildcard characters “?” and “*” are supported. A ZIP file is automatically generated and downloaded when multiple files are specified.
- **show_progress** (bool) - Optional - Whether to show a progress bar during the download.
- **target_dir** (str) - Optional - Path to a local directory to download the files to. The default is `None`, in which case the client working directory is used.

### Response
#### Success Response (200)
- **downloaded_file** (str) - Name of the downloaded file.

## WorkbenchClient.download_project_archive()

### Description
Create and download the project archive.

### Method
download_project_archive

### Endpoint
N/A

### Parameters
#### Request Body
- **archive_name** (str) - Required - Name of the project archive to use, without the file extension.
- **include_solution_result_files** (bool) - Optional - Whether to include solution and result files in the archive.
- **show_progress** (bool) - Optional - Whether to show a progress bar during the download.
```

--------------------------------

### Logging Configuration

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/WorkbenchClient.html

Methods for configuring the log level and log file for the Workbench client.

```APIDOC
## WorkbenchClient.set_console_log_level()

### Description
Set the log filter level for the client console.

### Method
set_console_log_level

### Endpoint
N/A

### Parameters
#### Query Parameters
- **log_level** (str) - Required - Level of logging. Options are “critical”, “debug”, “error”, “info”, and “warning”.

## WorkbenchClient.set_log_file()

### Description
Set a local log file for the Workbench server log. Create a local log file if one does not exist and append it to the existing log file.

### Method
set_log_file

### Endpoint
N/A

### Parameters
#### Query Parameters
- **log_file** (str) - Required - Path to a local file to use for logging.

## WorkbenchClient.reset_log_file()

### Description
No longer use the current log file for the Workbench server log.

### Method
reset_log_file

### Endpoint
N/A

### Parameters
None
```

--------------------------------

### Ansys Workbench Core API Overview

Source: https://workbench.docs.pyansys.com/version/stable/api/index.html

General reference for the ansys.workbench.core module and its capabilities.

```APIDOC
## Ansys Workbench Core API

### Description
The ansys.workbench.core module provides the primary interface for interacting with Ansys Workbench programmatically. This version includes support for secure transport modes.

### Namespace
ansys.workbench.core
```

--------------------------------

### Run Script String

Source: https://workbench.docs.pyansys.com/version/stable/_sources/api/ansys/workbench/core/workbench_client/WorkbenchClient.rst.txt

Executes a Python script provided as a string on the server.

```APIDOC
## POST /run_script_string

### Description
Run a script as given in the input string on the server.

### Method
POST

### Endpoint
/run_script_string

### Parameters
#### Request Body
- **script_string** (string) - Required - String containing the content of the script to run.
- **args** (dictionary) - Optional - Variables in the script specified as $$varname%%50%% will be converted to variable values or use the default value - 50 in the example.
- **log_level** (string) - Optional - Level of logging. Options are "critical", "debug", "error", "info", and "warning". Default: "error"

### Request Example
{
  "script_string": "import json\nwb_script_result=json.dumps(GetTemplate(TemplateName=\"FLUENT\").CreateSystem().Name)"
}

### Response
#### Success Response (200)
- **output** (string) - Output defined in the script.

#### Response Example
{
  "output": "SystemName"
}
```

--------------------------------

### Run Workbench Script from File

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Run an IronPython-based Workbench script from a file located in the client working directory. Specify the log level to control output.

```python
wb.run_script_file("a_script_file_name", log_level="info")
```

--------------------------------

### Load geometry file on server

Source: https://workbench.docs.pyansys.com/version/stable/user-guide.html

Loads an uploaded geometry file into a new Workbench system using a server-side script.

```python
wb.run_script_string(
    r"""import os
work_dir = GetServerWorkingDirectory()
geometry_file = os.path.join(work_dir, "two_pipes.agdb")
template = GetTemplate(TemplateName="Static Structural", Solver="ANSYS")
system = CreateSystemFromTemplate(Template=template, Name="Static Structural (ANSYS)")
system.GetContainer(ComponentName="Geometry").SetFile(FilePath=geometry_file)
"""
)
```

--------------------------------

### Download files from server

Source: https://workbench.docs.pyansys.com/version/stable/_sources/user-guide.rst.txt

Downloads files from the server's working directory. Progress bars can be disabled via the show_progress argument.

```python
wb.download_file("*.out")
```

```python
wb.download_file("solve.out", show_progress=False)
```

--------------------------------

### WorkbenchClient Class

Source: https://workbench.docs.pyansys.com/version/stable/api/ansys/workbench/core/workbench_client/index.html

The WorkbenchClient class provides the main interface for interacting with a PyWorkbench client.

```APIDOC
## WorkbenchClient

### Description
Functions of a PyWorkbench client.

### Class
`ansys.workbench.core.workbench_client.WorkbenchClient`

### Methods
(No specific methods detailed in the provided text)

### Parameters
(No specific parameters detailed in the provided text)

### Request Example
(No request examples provided)

### Response
(No response examples provided)
```
Tokens:
Raw