PySystemCoupling

Overview

PySystemCoupling provides Pythonic access to Ansys System Coupling. Although this Ansys product exposes its own Python-based scripting and command line interface, it is embedded and based on a specific version of Python. In contrast, PySystemCoupling enables seamless use of System Coupling within the Python ecosystem, providing additional capabilities, including:

• Ability to launch System Coupling using a local Ansys installation
• Access to APIs to set up and solve coupled analyses
• Full access to the System Coupling data model via a convenient and Pythonic interface

Installation

Install PySystemCoupling with this command:

pip install ansys-systemcoupling-core

Alternatively, clone and install PySystemCoupling in development mode with this code:

git clone https://github.com/ansys/pysystem-coupling.git
cd pysystem-coupling
python -m pip install --upgrade pip
pip install -e .
pip install .[classesgen]
python scripts\generate_datamodel.py

Documentation and Issues

For more information, see the Documentation page.

Use the PySystemCoupling Issues page to post bug reports, questions and feature requests.

Usage

It is assumed that an Ansys installation is available and that this installation includes System Coupling and the participant products needed for the coupled analysis.

For most users, the default behavior of PySystemCoupling is to automatically locate System Coupling from a standard Ansys installation by examining the environment. If multiple Ansys installations are present, the latest release is used. If you want to use an earlier installed release, you can specify the version as an argument to the launch() function. See the API documentation for more information.

For more specialized use cases, the above behavior can be overridden by setting certain environment variables. The System Coupling installation is found by examining the following environment variables in this order:

• SYSC_ROOT - this is assumed to point directly to a root System Coupling folder.
• AWP_ROOT - this is assumed to point to a root Ansys folder, under which a SystemCoupling folder is present.
• AWP_ROOT<NNN> - these are standard environment variables that are automatically set by Ansys installations, where <NNN> is a version number, such as 252 for Ansys 25 R2. As noted above, if multiple such variables are set, the one with the highest recognized version number is used.

If SYSC_ROOT or AWP_ROOT is set but does not refer to a valid installation, PySystemCoupling fails at that point, rather than attempting to use the next variable.

NOTE

Releases of 0.11.0 and later of PySystemCoupling define the launch() function so that its default behavior is consistent with service pack releases of Ansys as follows:

• 24 R2 - Service Pack 5 and later
• 25 R1 - Service Pack 4 and later
• 25 R2 - Service Pack 3 and later

You can still use earlier releases and service packs of Ansys System Coupling, but to do so you must specify a new connection_type argument to the launch() function with value ConnectionType.LOCAL_INSECURE. See the API documentation for more information.

Note that the following applies only to the 25 R1 release of Ansys System Coupling.

There was an issue with 25 R1, earlier than the Service Pack 3 release, that prevented it from working in the gRPC server mode on which PySystemCoupling depends. A small patch was made available in this repository to address this issue. As this issue has now been officially fixed in the Service Pack 3 release of 25 R1, the patch has been removed and you are recommended to install Service Pack 3 of 25 R1 or the latest service pack of a later release.

The System Coupling API is exposed to PySystemCoupling in two forms:

• A documented interface based on concrete Python classes, following Pythonic conventions
• A dynamic interface, undocumented in PySystemCoupling, that replicates the native System Coupling API

Both forms are strongly related to each other. A key difference in the Pythonic API is that naming is adjusted, in a generally predictable manner, to follow Python conventions. If you are already familiar with System Coupling, adjusting to this form, which is the recommended API, should be easy. However, if you are transitioning existing scripts, the native System Coupling API is made available as a convenience.

Note

While most commands should work as expected via the native System Coupling API, no guarantees can be given because of the nature of how it is exposed.

This example shows how to set up and solve an oscillating plate example in the Pythonic API. It uses Ansys Fluent as the CFD solver.

import ansys.systemcoupling.core as pysystemcoupling

syc = pysystemcoupling.launch()
setup = syc.setup
setup.add_participant(input_file="mapdl.scp")
setup.add_participant(input_file="fluent.scp")

## Create interfaces and data transfers by specifying participant regions

interface_name = "interface-1"
interface = setup.coupling_interface.create(interface_name)
interface.side["One"].coupling_participant = "MAPDL-1"
interface.side["One"].region_list = ["FSIN_1"]
interface.side["Two"].coupling_participant = "FLUENT-2"
interface.side["Two"].region_list = ["wall_deforming"]

# Use commands to add data transfers
force_transfer_name = setup.add_data_transfer(
    interface=interface_name,
    target_side="One",
    side_one_variable="FORC",
    side_two_variable="force",
)

disp_transfer_name = setup.add_data_transfer(
    interface=interface_name,
    target_side="Two",
    side_one_variable="INCD",
    side_two_variable="displacement",
)

# Change analysis duration and step size
setup.solution_control.time_step_size = "0.1 [s]"
setup.solution_control.end_time = "1.0 [s]"

# Set output control settings
setup.output_control.option = "StepInterval"
setup.output_control.output_frequency = 2

# Start streaming standard output from server
syc.start_output()

# Solve
solution = syc.solution
solution.solve()

The Pythonic API partitions commands via three high-level root attributes of the Session class: setup, solution, and case. The preceding example uses both the setup and solution attributes.

• The setup attribute is the largest part of the API. It is where you find all commands related to populating the settings that define a coupled analysis. This attribute also provides direct access to the hierarchical data model.
• The solution attribute is home to commands related to solving an analysis and examining the solution.
• The case attribute, which is not used in the preceding example, provides all commands related to case file management and persistence.

This next example shows how to set up the same analysis using the native System Coupling API. While the code here is less complete than the code shown previously, it should sufficiently illustrate the differences and connections between the two API forms.

import ansys.systemcoupling.core as pysystemcoupling

syc = pysystemcoupling.launch()
native_api = syc._native_api

native_api.AddParticipant(InputFile="mapdl.scp")
native_api.AddParticipant(InputFile="fluent.scp")

interface = native_api.CouplingInterface["interface-1"]
interface.Side["One"].CouplingParticipant = "MAPDL-1"
...

native_api.SolutionControl.TimeStepSize = "0.1 [s]"
...
syc.start_output()
native_api.Solve()

License

PySystemCoupling is licensed under the MIT license.

The ansys-systemcoupling-core package makes no commercial claim over Ansys whatsoever. It extends the functionality of Ansys System Coupling by adding a Python interface to the System Coupling service without changing the core behavior or license of the original software. Interactively controlling System Coupling via PySystemCoupling requires a local copy of System Coupling and licenses for all Ansys products involved in your coupled analysis.

To get a copy of Ansys, visit Ansys.