.. _getting_started:

===============
Getting started
===============

PyTwin provides Pythonic access to twin runtimes that were generated using
`Ansys Twin Builder and Ansys Twin Deployer <https://www.ansys.com/products/digital-twin/ansys-twin-builder>`_.

PyTwin supports twin runtimes generated using 2023 R1 and later.

Licensing requirements
----------------------

For twin runtimes generated with 2023 R1, the Ansys License Manager must have a license file with the
``twin_builder_deployer`` feature available to use PyTwin.

For twin runtimes generated with 2023 R1 SP1 and later versions:

- if the TWIN file is exported as 'licensed', the Ansys License Manager must have a license file with the
  ``twin_runtime`` feature available to use PyTwin.
- if the TWIN file is exported as 'unlicensed', no license is needed to use PyTwin

Both the features ``twin_builder_deployer`` and ``twin_runtime`` are included in the
Twin Deployer license file. Here is how you define the environment variable for specifying the location of
Ansys License Manager:

.. code::

   ANSYSLMD_LICENSE_FILE={PORT_NUMBER}@{SERVER_NAME}


Twin runtime dependencies
-------------------------

The ``pytwin`` package allows you to execute deployment workflows based on TWIN files
generated by `Ansys Twin Builder <https://www.ansys.com/products/digital-twin/ansys-twin-builder>`_.
TWIN files are generally made up of several types of models, including system-level models, ROMs
(reduced order models), third-party models, and FMU (Functional Mock-up Unit) files. Each of these
models can have specific runtime dependencies. For example, Modelica models cross-compiled with
Twin Deployer on Ubuntu 20.04 have a dependency on libgfortran5.

When executing twin runtimes through PyTwin on a specific environment, all dependencies of the
twin runtimes, including the ones of their constitutive models, must be properly installed
and made available in that environment.

Install the package
-------------------

The ``pytwin`` package supports Python 3.9 through Python 3.12 on Windows and Linux.

Install the latest release from `PyPi <https://pypi.org/project/pytwin/>`_
with this command:

.. code::

   pip install pytwin


If you plan on doing local *development* of PyTwin with Git, install
the latest release with this code:

.. code::

   git clone https://github.com/ansys/pytwin.git
   cd pytwin
   pip install pip -U
   pip install -e .


Any changes that you make locally are reflected in your setup after you restart
the Python kernel.

Additional PyAnsys libraries
-----------------------------

You can install and use these additional PyAnsys libraries:

- `PyAEDT <https://aedt.docs.pyansys.com//>`_, which provides access to Ansys
  Twin Builder for model creation and the generation of twin runtimes.