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

.. _sec:python_user_class:

User class
==========

The SPEX user models are used to enable external models to be used inside SPEX. The
script acts as an interface between the SPEX user model (``user``, ``cusr``, and ``musr``)
and the external model.

For users who want to use the SPEX user models, we have a Python module available
to make the interaction with SPEX easier. The ``User`` class can be imported into
the Python script (prepared by the user) that the SPEX user model will execute.

Example script
--------------

The user model takes a parameter called ``exec``, which holds the path to the
user script that calculates the (external) model. This can be a Python script,
or a program in other compatible languages (must be able to take command-line
arguments and read text files).

The script below is also available in the file ``python/examples/usermodel.py``
in the SPEX source directory::

    import sys
    from pyspex import User
    # from scipy import signal  # For cusr model example

    def main():
        """This is an example script for the SPEX user models. Users can copy
        this script and alter it to compute their desired model. Please
        select the required user model from the User class (either
        'user' (additive model), 'musr' (multiplicative model), or
        'cusr' (convolutional model).

        Notes for the different models:

        Musr: The user.spectrum array needs to be filled with the transmission
        as a function of energy. SPEX will multiply this transmission with the
        spectrum internally.

        Cusr: The spectrum is already available in the user.spectrum array.
        Users can replace this array with the convolved spectrum, provided
        that the energy grid remains the same.
        """

        # Read input filename from command line (first entry)
        input_file = sys.argv[1]

        # Read output filename from command file (second entry)
        output_file = sys.argv[2]

        # Load the User class for interaction with the SPEX user models
        user = User('user')
        #user = User('musr')  # use for multiplicative user model
        #user = User('cusr')  # use for convolution user model

        # Read input from the SPEX ASCII file
        user.read_from_spex(input_file)

        # Calculate an emission spectrum (user), 'user.spectrum',
        # for each bin (the spectrum weights are kept at 0 in this example)
        user.spectrum = user.model_param[0] * user.e_centroid**(-user.model_param[1])

        # Calculate a transmission for a multiplicative model (musr).
        # In this case the user.spectrum variable contains the transmission:
        # user.spectrum = 1. - user.model_param[0] * numpy.exp(-user.model_param[1] * user.e_centroid)

        # Calculate a convolution for a convolution model (cusr).
        # gauss_kernel = signal.windows.gaussian(50, user.model_param[0])
        # user.spectrum = signal.fftconvolve(user.spectrum,gauss_kernel,'same')

        # Write the result to the output file in the proper format
        user.write_to_spex(output_file)

    if __name__ == "__main__":
        main()


User class
----------

The example script makes use of the ``User`` class. This is a class to read and
write the SPEX input and output files.

.. autoclass:: pyspex.user.user.User
   :members: