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

The ``pygranta`` metapackage ensures compatibility between PyGranta packages and
provides a convenient method for installing packages compatible with a specific
release of Ansys Granta MI.

Most packages require access to an installation of Ansys Granta MI. For more
information on getting a licensed copy of Ansys products, visit the `Ansys website <https://www.ansys.com/>`_.

************
Installation
************

There are several ways of installing PyGranta depending on your use case, but
the easiest is simply to run this command:

.. code:: bash

   pip install pygranta

This installs all the PyGranta packages for the latest released version of Granta MI.

If you are interested in **installing a specific version**, such as ``2023.2.0``, you
can run a command like this one:

.. code:: bash

   pip install pygranta==2023.2.0

.. note::
   The versions of ansys-grantami-bomanalytics and ansys-grantami-bomanalytics-openapi included in the metapackage
   are compatible with that version of *BoM Analytics Services*, included with Granta MI Restricted
   Substances and Sustainability Reports. Multiple versions of BoM Analytics Services are compatible with a single
   version of Granta MI.

You can always install PyGranta packages individually by following the installation
instructions for each package. For example, the instructions for PyGranta
RecordLists have you install it by running this command:

.. code:: bash

   pip install ansys-grantami-recordlists


User mode installation
^^^^^^^^^^^^^^^^^^^^^^

Before installing the ``pygranta`` metapackage in user mode, ensure that you have the
latest version of `pip <https://pypi.org/project/pip/>`_ by running this command:

.. code:: bash

    python -m pip install -U pip

Then, install the ``pygranta`` metapackage with this command:

.. code:: bash

   python -m pip install pygranta

If you are interested in **installing a specific version**, such as ``2023.2.0``, you
can run a command like this one:

.. code:: bash

   python -m pip install pygranta==2023.2.0


Offline mode installation
^^^^^^^^^^^^^^^^^^^^^^^^^

If you lack an internet connection on your installation machine, the
recommended way of installing the ``pygranta`` metapackage is downloading the
wheelhouse archive for your corresponding machine
architecture from the repository's `Releases
<https://github.com/ansys/pygranta/releases>`_ page.

Each wheelhouse archive contains all the Python wheels necessary to install
the ``pygranta`` metapackage from scratch on Windows and Linux for all supported
Python versions. You can install this on an isolated system with a fresh Python
installation or on a virtual environment.

For example, on Linux with Python 3.12, unzip the wheelhouse archive and install
it with these commands:

.. code:: bash

    unzip pygranta-v2023.2.0-wheelhouse-Linux-3.12-core.zip wheelhouse
    pip install pygranta -f wheelhouse --no-index --upgrade --ignore-installed

If you're on Windows with Python 3.12, unzip to a wheelhouse directory and install
using the same command as for Linux.

Consider installing using a `virtual environment <https://docs.python.org/3/library/venv.html>`_.

Versioning system
-----------------

The ``pygranta`` metapackage follows a semantic-like versioning system, though
it has been adapted to the Ansys product release mechanism. In this sense, the
following versioning system is followed:

.. code:: bash

   XXXX.Y.ZZ

Where:

- ``XXXX`` is the Ansys product release year (for example, 2024).
- ``Y`` is the Ansys product release within the same year (for example, 1,
  which relates to R1).
- ``ZZ`` is the patched versions to the ``pygranta`` metapackage, if any.

Consequently, the first ``pygranta`` metapackage compatible with the 2024 R1
release would be:

.. code:: bash

   2024.1.0

Any subsequent patched version of this package would have these versions:

.. code:: bash

   2024.1.1
   2024.1.2
   2024.1.3
   ...

When using ``pip`` to install your package, you can install a specific version with a
command like this:

.. code:: bash

   python -m pip install pygranta==2024.1.0