Metadata-Version: 2.1
Name: ansys-systemcoupling-core
Version: 0.1.0
Summary: A Python wrapper for Ansys MAPDL.
Author-email: "ANSYS, Inc." <pyansys.support@ansys.com>
Maintainer-email: PyAnsys developers <pyansys.maintainers@ansys.com>
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Dist: ansys-api-systemcoupling==0.1.0
Requires-Dist: grpcio>=1.30.0
Requires-Dist: grpcio-status>=1.30.0,<1.51.2
Requires-Dist: googleapis-common-protos>=1.50.0
Requires-Dist: protobuf>=3.20.1,<4.0.0
Requires-Dist: psutil>=5.7.0
Requires-Dist: pyyaml
Requires-Dist: appdirs>=1.4.0
Requires-Dist: importlib-metadata>=4.0
Requires-Dist: build ; extra == "build"
Requires-Dist: black==23.1.0 ; extra == "classesgen"
Requires-Dist: isort==5.12.0 ; extra == "classesgen"
Requires-Dist: ansys-sphinx-theme==0.8.2 ; extra == "doc"
Requires-Dist: jupyter_sphinx==0.4.0 ; extra == "doc"
Requires-Dist: matplotlib ; extra == "doc"
Requires-Dist: numpydoc==1.5.0 ; extra == "doc"
Requires-Dist: pypandoc==1.10 ; extra == "doc"
Requires-Dist: pytest-sphinx==0.5.0 ; extra == "doc"
Requires-Dist: Sphinx==5.3.0 ; extra == "doc"
Requires-Dist: sphinx-autobuild==2021.3.14 ; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints==1.22 ; extra == "doc"
Requires-Dist: sphinx-copybutton==0.5.1 ; extra == "doc"
Requires-Dist: sphinx-gallery==0.11.1 ; extra == "doc"
Requires-Dist: sphinx-notfound-page==0.8.3 ; extra == "doc"
Requires-Dist: sphinxcontrib-websupport==1.2.4 ; extra == "doc"
Requires-Dist: sphinxemoji==0.2.0 ; extra == "doc"
Requires-Dist: ansys-fluent-core ; extra == "doc"
Requires-Dist: ansys-dpf-core ; extra == "doc"
Requires-Dist: codespell==2.2.2 ; extra == "style"
Requires-Dist: flake8==6.0.0 ; extra == "style"
Requires-Dist: pytest ; extra == "tests"
Requires-Dist: pytest-cov ; extra == "tests"
Requires-Dist: psutil>=5.7.0 ; extra == "tests"
Project-URL: Documentation, https://systemcoupling.docs.pyansys.com/
Project-URL: Homepage, https://github.com/pyansys/pysystem-coupling/
Project-URL: Source, https://github.com/pyansys/pysystem-coupling/
Project-URL: Tracker, https://github.com/pyansys/pysystem-coupling/issues
Provides-Extra: build
Provides-Extra: classesgen
Provides-Extra: doc
Provides-Extra: style
Provides-Extra: tests

PySystemCoupling
================
.. TODO : add codecov badge once public

|pyansys| |GH-CI| |MIT| |black|

.. |pyansys| image:: https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC
   :target: https://docs.pyansys.com/

.. |GH-CI| image:: https://github.com/pyansys/pysystem-coupling/actions/workflows/ci.yml/badge.svg
   :target: https://github.com/pyansys/pysystem-coupling/actions/workflows/ci.yml

.. |codecov| image:: https://codecov.io/gh/pysystem-coupling/branch/main/graph/badge.svg
   :target: https://codecov.io/gh/pyansys/pysystem-coupling

.. |MIT| image:: https://img.shields.io/badge/License-MIT-yellow.svg
   :target: https://opensource.org/licenses/MIT

.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat
  :target: https://github.com/psf/black
  :alt: black

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:

.. code::

   pip install ansys-systemcoupling-core


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

.. code::

   git clone https://github.com/pyansys/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 <https://systemcoupling.docs.pyansys.com>`_ page.

Use the `PySystemCoupling Issues <https://github.com/pyansys/pysystem-coupling/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.

The System Coupling installation is found by examining the following environment variables
in this order:

* ``SYSC_ROOT``
* ``AWP_ROOT``
* ``AWP_ROOT231``

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

In a standard user installation, the expectation is that only ``AWP_ROOT231`` is set.

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.

.. code:: python

   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.

While the preceding example uses the ``pysystemcoupling.launch()`` method to start the
System Coupling server, alternatively, the server can be started in advance by calling
command line arguments ``-m cosimgui --grpcport=<host:port>`` and
``pysystemcoupling.connect(host, port)``.

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.

.. code:: python

   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 <https://www.ansys.com/>`_.

