.. SPDX-FileCopyrightText: 1992-2026 NWO-I/SRON Space Research Organisation Netherlands
..
.. SPDX-License-Identifier: CC-BY-4.0

Basic usage of PYSPEX
=====================

The PYSPEX python module offers a python interface to the SPEX program. This means that you can
use SPEX directly either in interactive python mode and in python scripts. In this short tutorial,
we assume you are using PYSPEX in interactive mode.

The structure of PYSPEX is chosen such that for many SPEX commands, there is an equivalent class
in PYSPEX. These classes contain the functions that copy the functionality of the SPEX command,
and if applicable, the classes contain also the output parameters of the SPEX command. This makes
it easy to incorporate the SPEX results inside your own program.

In addition to the classes, you can also simply send a SPEX command-line command using the
``command`` function (see Section below).

Before you start
----------------

Before we start PYSPEX, we need to make sure that the environment is set-up correctly. If
you installed SPEX through mamba/conda, then activating the mamba/conda environment should be
enough::

    (base) linux:~> mamba activate spex4
    (spex4) linux:~>

If you have installed SPEX from a tar file or Mac install package, then you also need to source
the SPEX environment::

    (spex4) linux:~> source /opt/spex/spexdist.sh

If you installed SPEX in another directory, then please replace ``/opt/spex`` with the path to your SPEX installatation.

Starting a PYSPEX session
-------------------------

For this example PYSPEX session in python, we use the interactive mode of python. We start
python from the Linux command line::

    (spex4) linux:~> python
    Python 3.11
    Type "help", "copyright", "credits" or "license" for more information.
    >>>

If the environment is correctly set, we should now be able to import Spex from pyspex::

    >>> from pyspex import Spex

From here, we can start a SPEX session easily::

    >>> s=Spex()
     Welcome user to SPEX version 3.99.00

     NEW in this version of SPEX:

    Currently using SPEXACT version 2.07.00. Type `help var calc` for details.
    >>>

The ``s`` object now contains all the functions and commands that are available to control
the SPEX session. For example, we can send SPEX the following command-line commands::

    >>> s.command('var calc new')
     Now using SPEXACT version 3.99.00
    0
    >>> s.com('cie')
     You have defined    1 component.
    0
    >>> s.calc()
    0

With these commands SPEX calculates a CIE spectrum for a temperature of 1 keV.

Although it is possible to call ``s.command('quit')``, the session will be terminated
automatically once python is closed or ``s`` is reassigned.

Using the ``command`` function only does not provide an advantage over the regular command line
of SPEX. To really benefit from PYSPEX, you need to use the additional classes which are described
in the next sections.

The command function
--------------------

The PYSPEX module contains a general function to send SPEX commands to the SPEX session. This
function is especially helpful for SPEX commands that have not been implemented (yet) in PYSPEX.
The function returns 0 when the command was successfully executed. If not a non-zero value is
returned.

.. automodule:: pyspex.spex

    .. automethod:: Spex.command

Please note that by using the ``s.command()`` function, the data on the pyspex part of the program
is not updated. If you need data from SPEX in Python, then please use the dedicated PYSPEX command.