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

.. _sect:cusr:

Cusr: User defined convolution model
====================================

The user model provides an interface to create a convolution model
component calculated by a user program. The interface is rather simple
and therefore very flexible. The interface uses a set of two ASCII
files: ``input-?-?.prm`` and ``output-?-?.spc``, where the ’?’ stands for the
sector and component number of the musr model component.

The ``input-?-?.prm`` is generated by the cusr model and contains the
parameter values and the energy grid that SPEX uses to calculate the
model. The file has a fixed structure:

-  The first line contains one integer number containing the number of
   parameters that the model needs to calculate (current maximum is 40).

-  On the second line the array of parameter values is listed (with the
   length indicated on the previous line.

-  On the third line, an integer value is shown which indicates the
   number of model bins SPEX has in its model grid.

-  On the following lines, the model grid points are shown in three
   columns. The first column contains the bin upper boundary (egb), the
   second column is the bin center (eg) and the third column is the full
   bin width (deg). The energy values are in keV.

The user program is supposed to read the input file and calculate the
convolve the input spectrum in a way defined by the user. The spectrum
array is called ``sener`` (or ``spectrum`` in Python) and has the same
length as the energy grid. In addition, it is also possible to calculate
the model for the emission weighted center of the bin. In that case the
spectrum calculation is a bit more complicated, but it leads to better
results. The user has the option of also calculating the weighted spectrum,
which is the average photon energy :math:`E_{\mathrm{aver}}` minus the bin centroid
:math:`E_{\mathrm{centroid}}` times the flux (F):

.. math:: W = (E_{\mathrm{aver}} - E_{\mathrm{centroid}}) * F

The :math:`W` values end up in the ``wener`` array (or ``spectrum_weights`` in Python)
array. If you do not use weighing by average photon energy, ``wener`` values can be 0.

The user program should create an output ASCII file named ``output-?-?.spc``
with the following structure:

-  On the first row, put the number of model bins. This should be the
   same number as written in the ``input-?-?.prm`` file.

-  Write the ``sener`` and ``wener`` values in two columns. The first column
   is the ``sener`` value that represents the multiplication factor and
   the second column is the ``wener`` value.

For Python programmers, we have a the :ref:`sec:python_user_class` and
an example program to help create user model scripts.

In :ref:`sect:howtouser` some example user
model programs can be found. The source code can be adapted to
accommodate the user’s wishes.

The equivalent of ``cusr`` for additive models is :ref:`sect:user`.

The parameters of the model are:

| ``exec`` : User executable, for example ’./model.py’ for a python
  script in the same directory where you run SPEX.
| ``npar`` : Number of free parameters in the model. Current maximum is
  40.
| ``p01...p40`` : Model parameters of the user model.