.. _user-guide-getting-started:

.. _user-guide-quickstart:

Quickstart
==========

After :ref:`installing PyRETIS <user-guide-install>`, you
can run simulations by using a **text based input file**
or by using **the PyRETIS library explicitly**.

The former approach is perhaps the simplest, but you will
first have to learn how to create input files and this is
explained in the :ref:`input description <user-guide-input>`.

The latter option is more involved, but you are then
given more freedom in defining, running and interacting with
a simulation. In order to make use of the
library, you will have to read about the structure of the
|pyretis| library in the
:ref:`introduction to the library <user-guide-intro-api>`
and in the :ref:`detailed reference section <api-doc>`.

A more extensive overview can be found in
the :ref:`full user guide <user-guide-index>`.
Since version 2.4, |pyvisa| is automatically installed with
|pyretis|.
Here, we report some examples showing the use of |pyretis| and |pyvisa|.

|

Quickstart workflow
-------------------

If you want a short first run before diving into the full guide, the
following workflow is a good starting point:

1. Install |pyretis| in a Python 3.11+ environment:

   .. code-block:: bash

      python -m pip install pyretis

2. Check that the command-line tools are available:

   .. code-block:: bash

      pyretisrun --version
      pyretisanalyse --version

3. Pick a small internal example from the :ref:`example section <examples-index>`,
   such as :ref:`RETIS in a 1D potential <examples-retis-1d>` or
   :ref:`TIS in a 1D potential <examples-tis-1d>`.

4. Run the simulation from the directory containing your input file:

   .. code-block:: bash

      pyretisrun -i retis.rst -p

5. Analyse the results from the generated ``out.rst`` file:

   .. code-block:: bash

      pyretisanalyse -i out.rst

After a successful run, you should at least see a log file, an ``out.rst``
file, and a ``report/`` directory from the analysis step.