Model related commands

A SPEX model is organised in sectors and components. Sectors are groups of components that model a particular source of radiation. Below, the basic commands for building the model and change its parameters are listed.

Abundance

The solar abundance table used is set in SPEX using the abundance command. In PYSPEX, this is abbreviated to abun. The desired abundance table should be loaded by providing the abbreviation for the table (abunset):

Spex.abun(abunset)

Set the abundance table in SPEX. The abunset parameter is one of ‘reset’, ‘ag’, ‘allen’, ‘asplund’, ‘ra’, ‘grevesse’, ‘gs’, ‘lodders’, and ‘solar’.

Parameters:

abunset (str) – String representing the abundance set used in SPEX.

Returns:

Object containing the abundance class.

Return type:

pyspex.model.Abundance

The possible abundance tables are:

• reset: Lodders et al. (2009)

• allen: Allen (1973)

• ra: Ross & Aller (1976)

• grevesse: Grevesse et al. (1992)

• gs: Grevesse & Sauval (1998)

• lodders: Lodders proto-Solar (2003)

• solar: Lodders Solar Photospheric (2003)

• ag: Anders & Grevesse (1989)

• asplund: Asplund et al. (2009)

The abun command returns an object with the abundance information, which can optionally be assigned to a parameter and be accessed through Python. See the advanced class descriptions for details.

For example:

>>> a = s.abun('asplund')
>>> dir(a)
['__doc__', '__init__', '__module__', 'get', 'index', 'list', 'ref', 'set', 'update']

Abundance show

To show the current abundance table, use the abun_show method:

Spex.abun_show()

Show the current ionisation balance.

Returns:

Reference to the used ionisation balance.

Return type:

str

The method returns the reference as a text string:

>>> ab = s.abun_show()
Lodders et al. (2009)
>>> print(ab)
Lodders et al. (2009)

Aerror

Calculate the uncertainties for several parameters of a model component due to the uncertainties in the atomic data.

Spex.aerror(isect, icomp, name, shell=0)

Command to calculate the uncertainty in a model parameter due to the uncertainties in the atomic data.

Parameters:

• isect (int) – Sector number of the component.

• icomp (int) – Component number.

• name (str) – Parameter name.

• shell (int) – Shell number for calculation (L-shell = 1, K-shell = 2)

Returns:

The atomic uncertainty for the selected parameter.

Return type:

float

Example:

>>> aerr = s.aerror(1,1,'norm')
>>> aerr = s.aerror(1,1,'26',shell=1)

Calculate

Once the model sectors and components are set-up and the parameters are set, the model spectrum can be calculated using the SPEX calculate command. For convenience, this command has been abbreviated to calc in PYSPEX.

Spex.calc()

Calculate the current model.

Example:

>>> s.calc()

Components

Spectral components, like power laws, thermal and absorption models are loaded using the SPEX comp command. Since the command is often typed simply as com in practice, the PYSPEX command is also com:

Spex.com(name, isect=1)

Add model component.

Parameters:

• name (str) – Name of the model component, for example ‘reds’, ‘hot’, ‘cie’, etc.

• isect (int) – Sector number to add component to (default is sector 1).

The command adds a component by default to sector 1. If the component should be added to a different sector, then please use the optional isect parameter to specify the target sector.

For example:

>>> s.com('cie')
>>> s.com('po', isect=2)

See the SPEX reference manual for a list of spectral components.

Component delete

Deleting a component from the model is done using the sector and component number of the component.

Spex.com_del(isect, icomp)

Delete component from model.

Parameters:

• isect (int) – Sector number of the component to delete.

• icomp (int) – Component number to delete.

For example:

>>> s.com_del(1,1)

The command above deletes the first component in sector number 1.

Component relate

The relation between the additive and multiplicative components is set with a com rel command in SPEX. In PYSPEX this is:

Spex.com_rel(isect, icomp, rel)

Relate model components.

Parameters:

• isect (int) – Sector number of the component to relate.

• icomp (int) – Component number to relate.

• rel (numpy.ndarray) – Array containing the multiplicative component numbers counted from the source to the observer.

The relations are set per component (so no ranges, unfortunately) and the related multiplicative models should be entered (in the right order) using a numpy array. For example:

>>> s.com('reds')
>>> s.com('hot')
>>> s.com('cie')
>>> s.com_rel(1, 3, numpy.array([1,2]))

Distance

To calculate fluxes and luminosities, SPEX needs an assumed distance of the source. In SPEX this is done with the distance command. In PYSPEX this is abbreviated to dist for convenience.

The distance can be set with the dist command:

Spex.dist(isect, dist, unit)

Set the distance in SPEX.

Parameters:

• isect (int) – Sector number.

• dist (float) – Distance value.

• unit (str) – The unit of the distance value, for example: ‘m’, ‘au’, ‘ly’, ‘pc’, ‘kpc’, ‘mpc’, ‘z’, ‘cz’

where isect is the sector number, dist the distance (float) and unit the unit of the distance that is put in. The function returns an object containing the distance in all available units.

Examples:

>>> d = s.dist(1,0.5,'z')     # Redshift of z=0.5
>>> d = s.dist(1,2.0,'kpc')   # Distance of 2 kiloparsec
>>> dir(d)
['__doc__', '__init__', '__module__', 'age', 'au', 'cz', 'get', 'h0', 'kpc', 'ly', 'm', 'mpc', 'omega_l', 'omega_m', 'omega_r', 'pc', 'set', 'set_cosmo', 'z']

If you do not want to set the distance, but just get the current parameters, the dist_get command can be used:

Spex.dist_get(isect)

Get the current distances in SPEX.

Parameters:

isect (int) – Sector number.

Like the dist command, this method returns an object with the distances in all available units.

Cosmology

Next to the distance, the cosmology used by SPEX can also be specified. In SPEX all parameters should be provided through seperate lines, but in PYSPEX this has been combined in one command:

Spex.dist_cosmo(h0, omega_m, omega_l, omega_r)

Set the cosmology for the distance calculation.

Parameters:

• h0 (float) – Hubble constant (km/s/Mpc).

• omega_m (float) – Omega matter.

• omega_l (float) – Omega lambda.

• omega_r (float) – Omega R.

The commands needs values for the Hubble constant h0 (70 km/s/Mpc), Omega Matter omega_m (0.3), Omega Lambda omega_l (0.7) and Omega R omega_r (0.0). For example:

>>> s.dist_cosmo(75,0.33,0.67,0.0)

(The command will write the distances 4 times to the terminal since in the background all SPEX commands are executed separately…)

Energy grid

The model energy grid can be manipulated with the SPEX egrid command. In PYSPEX, this command has been splitted into two varieties:

Spex.egrid(elow, ehigh, nbins, unit, log)

Egrid command when the number of desired bins is known.

Parameters:

• elow (float) – Lowest energy/wavelength for energy grid.

• ehigh (float) – Highest energy/wavelength for energy grid.

• nbins (int) – Number of bins for energy grid.

• unit (str) – Unit of the energy/wavelength range, for example: ‘kev’, ‘ev’, ‘ryd’, ‘j’, ‘hz’, ‘ang’, ‘nm’

• log (bool) – Make the energy grid logarithmic (True or False)

Spex.egrid_step(elow, ehigh, step, unit, log)

Egrid command when the stepsize for the grid is known.

Parameters:

• elow (float) – Lowest energy/wavelength for energy grid.

• ehigh (float) – Highest energy/wavelength for energy grid.

• step (float) – Step size for the energy grid.

• unit (str) – Unit of the energy/wavelength range, for example: ‘kev’, ‘ev’, ‘ryd’, ‘j’, ‘hz’, ‘ang’, ‘nm’

• log (bool) – Make the energy grid logarithmic (True or False)

For the first method, egrid, the number of spectral bins nbins is known, while for egrid_step the step size (step) is an input value. The lowest and highest energy of the grid needs to be provided using the elow and ehigh input values. The unit is a text string and the grid can be logarithmic if the log parameter is set to True.

Examples:

>>> s.egrid(0.1,10.,9990,'kev',True)
>>> s.egrid_step(0.1,10.,0.01,'kev',False)

Reading & saving grids

Grids can also be save and read from a text file. The two methods below save and read a .egr file, respectively:

Spex.egrid_save(savefile)

Save energy grid to file.

Parameters:

savefile (str) – Filename to save the energy grid to (including .egr extension)

Spex.egrid_read(readfile)

Read energy grid from file.

Parameters:

readfile (str) – Filename to read the energy grid from (including .egr extension)

The savefile or readfile parameter should provide the method with the filename to save or read, including the .egr extension! If necessary, the full path to the file can be included.

Examples:

>>> s.egrid_save('mygrid.egr')
>>> s.egrid_read('mygrid.egr')

Get & set custom grids

If the grid needs to be transfered from or to Python memory, then the get and set methods can be used:

Spex.egrid_get()

Get the energy grid and return the grid as an object.

Returns:

An Egrid object from pyspex.

Return type:

pyspex.model.Egrid

Spex.egrid_set(ebounds)

Provide a grid to SPEX by providing a numpy array with the bin boundaries. Please note that the length of this array is the number of bins + 1!

Parameters:

ebounds (numpy.ndarray) – Array containing the energy boundaries of the new energy grid.

The get routine returns a Python object with the egrid arrays. The set routine requires an ebounds numpy array containing the energies of the bin boundaries. Note that the number of elements of this array would be of length n + 1, where n is the number of bins in the array.

Examples:

>>> grid = s.egrid_get()
>>> ebounds = 0.1 + 0.01 * numpy.arange(9991, dtype=float)
>>> s.egrid_set(ebounds)

Flux & Luminosity

For each component, the fluxes and luminosities are calculated using the set distance and energy boundaries. These energy limits for the flux and luminosity can be set using the elim command:

Spex.elim(elow, ehigh, unit)

Set the energy limits for flux output.

Parameters:

• elow (float) – Lowest energy/wavelength for energy interval.

• ehigh (float) – Highest energy/wavelength for energy interval.

• unit (str) – Unit of the energy/wavelength interval, for example: ‘kev’, ‘ev’, ‘ryd’, ‘j’, ‘hz’, ‘ang’, ‘nm’.

where elow is the lower boundary of the flux and ehigh the higher boundary. The unit determines the units of the input values, for example ‘kev’ for keV.

Examples:

>>> s.elim(13.6E-3,13.6,'kev')

Get flux

The fluxes and luminosities calculated in SPEX can be extracted using the flux_get method.

Spex.flux_get(isect, icomp)

Get the fluxes and luminosities for component icomp in sector isect.

Parameters:

• isect (int) – Sector number of the component to obtain the flux from.

• icomp (int) – Component number to obtain the flux from.

Return flux:

A Flux object from pyspex.

Rtype flux:

pyspex.model.Flux

The values are returned in a python object so that they can be accessed easily:

>>> flx = s.flux_get(1,1)
>>> print flx.enerflux
1.51011622912e-18

For the details about the contents of the object, see the advanced class description of the Fluxes class.

Ionisation balance

There are several ionisation balances available in SPEX. The Urdampilleta ionisation balance is the current default set.

The ionisation balance can be set using the ibal method:

Spex.ibal(ref)

Set the ionisation balance.

Parameters:

ref (str) – Abbreviation of the reference to the ionisation balance.

The ref is the short text string describing the paper reference for the ionisation balance:

• ar92: Arnaud & Raymond (1992) for Fe, Arnaud & Rothenflug (1985) for other elements.

• ar85: Arnaud & Rothenflug (1985).

• oldbryans: Old Bryans et al. data (NOT recommended).

• bryans09: Bryans et al. (2009).

• u17: Urdampilleta et al. (2017).

Examples:

>>> s.ibal('u17')

Show

To show the current ionisation balance, the ibal_show method can be used:

Spex.ibal_show()

Show the current ionisation balance.

Returns:

Reference to the used ionisation balance.

Return type:

str

This method returns the reference of the ionisation balance as a string.

Example:

>>> ib = s.ibal_show()
Urdampilleta et al. (2017)

Ion selection

In original SPEX models that use the SPEX atomic data, ions can be turned on or off, or can be calculated using the old SPEX version 2 or the new SPEX version 3. In addition, the maximum principle quantum number (nmax) and the maximum angular momentum (lmax) can be set.

The functions have been created such that each function selects the ions either by atomic number, iso-electronic sequence or ion.

Spex.ions_all(par, value)

Set parameter for all values.

Parameters:

• par (str) – Parameter name to set, e.g.: ‘use’, ‘new’, ‘nmax’, ‘lmax’.

• value (bool or int) – Value to set.

Spex.ions_iso(iso, par, value)

Set parameter for an iso-electronic sequence.

Parameters:

• iso (int) – Iso-electronic sequence number

• par (str) – Parameter name to set, e.g.: ‘use’, ‘new’, ‘nmax’, ‘lmax’.

• value (bool or int) – Value to set.

Spex.ions_z(z, par, value)

Set parameter for an atom.

Parameters:

• z (int) – Atomic number of the element.

• par (str) – Parameter name to set, e.g.: ‘use’, ‘new’, ‘nmax’, ‘lmax’.

• value (bool or int) – Value to set.

Spex.ions_ion(z, i, par, value)

Set parameter for a specific ion.

Parameters:

• z (int) – Atomic number of the element.

• i (int) – Ionisation stage (in astrophysical notation, e.g. 1, 2, 3, etc.)

• par (str) – Parameter name to set, e.g.: ‘use’, ‘new’, ‘nmax’, ‘lmax’.

• value (bool or int) – Value to set.

Show

The ion selections can be shown by calling the ions_show function below:

Spex.ions_show()

Show the ions in use and with which parameters.

Line selection

Up to 10 specific lines can be ‘muted’ using the ions_line function below:

Spex.ions_line(z, ion, lid, add)

Mutes or unmutes a spectral line from an emission spectrum.

Parameters:

• z (int) – Atomic number of the element.

• ion (int) – Ionisation stage (in astrophysical notation, e.g. 1, 2, 3, etc.)

• lid – Line ID number (see ascdump_line for the line ID number).

• add – If False, the line is not added to the spectrum. True will add the line to the spectrum again.

Setting parameters

Model parameters in SPEX are set using the par command. Since this command has subcommands, there are a number of methods to cover most of the functionality in PYSPEX. The most basic function is to set a parameter value and determine whether it should be free in the fit or thawn. These functions have been combined into one:

Spex.par(isect, icomp, name, value, thawn=False)

Set parameter value and status.

Parameters:

• isect (int) – Sector number of the parameter.

• icomp (int) – Component number of the parameter.

• name (str) – Parameter name.

• value (float) – New value of the parameter.

• thawn (bool) – (Optional) Should the parameter be free (True) or frozen (False).

Spex.par_text(isect, icomp, name, value)

Set text type parameter value.

Parameters:

• isect (int) – Sector number of the parameter.

• icomp (int) – Component number of the parameter.

• name (str) – Parameter name.

• value (str) – New value of the parameter.

The par method is used for setting numerical values. It needs the sector number (isect), component number (icomp) and the name of the parameter (name) to set. Optionally, the parameter can be set free by setting thawn to True.

For text values, like filenames of model input files, the par_text method is used. The usage is very similar to the par method, but just with the difference a text string is passed instead of a value. Text parameters cannot be free parameters as well.

Examples:

>>> s.par(1, 1, 'norm', 1E+8, thawn=True)
>>> s.par_text(1, 1, 'file', 'dist.dat')

Fix & Free parameters

Many times, we want to fix and free parameters without changing the values. For this purpose, two convenience functions have been created:

Spex.par_fix(isect, icomp, name)

Fix a model parameter during the fit.

Parameters:

• isect (int) – Sector number of the parameter.

• icomp (int) – Component number of the parameter.

• name (str) – Parameter name.

Spex.par_free(isect, icomp, name)

Free a model parameter during the fit.

Parameters:

• isect (int) – Sector number of the parameter.

• icomp (int) – Component number of the parameter.

• name (str) – Parameter name.

par_fix and par_free fix and free the parameter with name (name) in sector (isect) and component (icomp).

Examples:

>>> s.par_free(1,1,'26')
>>> s.par_fix(1,1,'t')

Parameter range

Parameters have ranges in which they can be safely varied without causing undesired errors or unphysical results. These ranges can be set using the par_range method:

Spex.par_range(isect, icomp, name, rlow, rupp)

Set parameter range.

Parameters:

• isect (int) – Sector number of the parameter.

• icomp (int) – Component number of the parameter.

• name (str) – Parameter name.

• rlow (float) – Lower limit of the parameter range.

• rupp (float) – Upper limit of the parameter range.

In addition to the sector number (isect), component number (icomp), and the parameter name (name), this function needs the lower (rlow) and upper range (rupp) limits of the parameter.

Example:

>>> s.par_range(1,1,'t',0.1,10.)

Couple parameters

Parameters can be coupled to each other such they have the same values in the fit. Or, optionally, remain coupled with a given multiplication factor. The PYSPEX method for this is par_couple:

Spex.par_couple(isect, icomp, iname, csect, ccomp, cname, factor)

Couple one parameter to another with a given multiplication factor.

Parameters:

• isect (int) – Sector number of the parameter.

• icomp (int) – Component number of the parameter.

• iname (str) – Parameter name.

• csect (int) – Sector number of the parameter to couple to.

• ccomp (int) – Component number of the parameter to couple to.

• cname (str) – Parameter name of the parameter to couple to.

• factor (float) – Multiplication factor (value(name) = factor * value(cname)).

The parameter located in isect, icomp and with iname will be coupled to the parameter in csect, ccomp, and cname. The factor sets the multiplication factor for the coupling.

To decouple a parameter again, simply use:

Spex.par_decouple(isect, icomp, name)

Decouple a parameter.

Parameters:

• isect (int) – Sector number of the parameter.

• icomp (int) – Component number of the parameter.

• name (str) – Parameter name.

Examples:

>>> s.par_couple(1, 2, 't', 1, 1, 't', 0.5)  # Couple the temperature in component 2 to 0.5 times the temperature in component 1
>>> s.par_decouple(1, 2, 't')

Set instrument normalisation

With SPEX the instrument normalisations can be set with the par command, but then with negative sector numbers. Since that can be confusing, there is a separate command to set the instrument normalisation, which has a similar syntax as the par method:

Spex.par_norm(ins, reg, value, thawn)

Set an instrument normalisation.

Parameters:

• ins (int) – Instrument number.

• reg (int) – Region number.

• value (float) – New value of the instrument normalisation.

• thawn (bool) – (Optional) Should the parameter be free (True) or frozen (False).

This methods sets the instrument normalisation to value for the instrument with number ins and region number reg. The status parameter is a logical/boolean where True means thawn or free and False frozen.

Example:

>>> s.par_norm(1,2, 0.95, True)

Show parameters

Show the model parameters in the terminal (or Jupyter Notebook). One can specify a couple of options to show more or less information:

Spex.par_show(option='')

Display parameter overview in terminal. Options include:

• all: Show all information.

• free: Show only free parameters.

• couple: Show coupled parameters.

• flux: Show summary of the fluxes of each emission component.

Parameters:

option (str) – Select which information should be shown (free/couple/flux/all)

Example:

>>> s.par_show('free')

The models can also be shown through the Fortran backend, but then the output will be shown in the terminal only (not in the Jupyter notebook).

Spex.par_show_classic(option='')

Display parameter overview in terminal through the Fortran backend.

Parameters:

option (str) – Select which information should be shown (free/couple/flux/stat/corr/all)

Example:

>>> s.par_show_classic('flux')

See also the SPEX documentation for par_show.

Write parameters to .com file

The current parameter settings can be saved to a command file (.com) and be loaded later by the log_exe command. The par_write method in pyspex is called like this:

Spex.par_write(comfile, overwrite=False)

Write parameters to a .com file.

Parameters:

• comfile (str) – Output file name (with .com extension!)

• overwrite (bool) – (Optional) Overwrite existing files if necessary (True/False).

Example:

>>> s.par_write('myparam.com', overwrite=True)

Sectors

Sectors group spectral components to form the model for a particular source or phenomenon. If the sectors need a different response, the sectors should also be defined in the .spo and .res files. When starting SPEX, the number of sectors is 1 by default, even if loaded data files contain more sectors. Sectors can be added to SPEX with the sector command.

In PYSPEX a new sector is created easily with the sector method:

Spex.sector()

Create a new sector.

This creates an empty sector. Sometimes, the new sector needs to have the same components as a previous one. In this case, the sector can be copied:

Spex.sector_copy(isect)

Copy sector with number isect.

Parameters:

isect (int) – Sector number.

If a sector is no longer needed, it can be deleted:

Spex.sector_del(isect)

Delete sector with number isect.

Parameters:

isect (int) – Sector number.

Examples:

>>> s.sector()
There are 2 sectors
>>> s.sector_copy(1)
 You have defined    1 component.
There are 3 sectors
>>> s.sector_del(2)

Plasma model parameters

There are a number of settings for the SPEX plasma models that can be changed by the user. In SPEX these are done using the var command. The var commands have been implemented in pyspex through the methods below. The current settings can be obtained using the Var class which is referenced in the SPEX session as s.mod_var.

Free-bound accuracy

Spex.var_gacc(value)

Set the free-bound emission accuracy.

Parameters:

value (float) – Free-bound emission accuracy.

Example:

>>> s.var_gacc(1.0E-2)

Line emission contributions

Spex.var_line(ltype, status)

Set a line emission contribution on or off.

Parameters:

• ltype (str) – Line emission contribution (‘ex’, ‘px’, ‘rr’, ‘dr’, ‘ds’, ‘ii’, ‘reset’)

• status (bool) – Boolean indicator whether contribution is on (True) or off (False).

Example:

>>> s.var_line('ex', False)

Doppler broadening

Spex.var_doppler(value)

Doppler broadening.

Parameters:

value (int) – Doppler broadening type.

Example:

>>> s.var_doppler(1)

SPEXACT version 3 calculations

Spex.var_calc(status)

Perform SPEXACT 3 line calculations.

Parameters:

status (str) – Use SPEXACT 2 (old), Quick SPEXACT 3 (qc), or SPEXACT 3 (new)

Example:

>>> s.var_calc(True)

Occupation numbers starting values

Spex.var_occstart(otype)

At which occupation level to start.

Parameters:

otype (str) – Occupation level (‘ground’, ‘boltz’, ‘last’)

Example:

>>> s.var_occstart('ground')

SPEXACT version 2 settings (MEKAL)

Spex.var_mekal(utype, status)

Switch old Mekal updates on/off.

Parameters:

• utype (str) – Update type (‘wav’, ‘fe17’, ‘update’, ‘all’)

• status (bool) – On (True) or off (False)

Examples:

>>> s.var_mekal('wav', False)
>>> s.var_mekal('fe17', False)

Multi-Maxwellians for the ionisation balance

Spex.var_ibalmaxw(status)

Switch the Multi-Maxwellians for the ionisation balance on/off (True/False).

Parameters:

status (bool) – On (True) or off (False)

Example:

>>> s.var_ibalmaxw(False)

SPEXACT version 3 cooling

Spex.var_newcoolexc(status)

Cooling by collisional excitation by Stofanova (SPEXACT 3) on/off (True/False).

Parameters:

status (bool) – On (True) or off (False)

Example:

>>> s.var_newcoolexc(False)

And for the cooling by di-electronic recombination:

Spex.var_newcooldr(status)

Cooling by dielectronic recombination (SPEXACT 3) on/off (True/False).

Parameters:

status (bool) – On (True) or off (False)

Example:

>>> s.var_newcooldr(False)

Charge exchange recombination and ionization

Set the origin of the charge exchange recombination and ionization rates.

Spex.var_cxcon(value)

Set charge exchange recombination and ionization rates according to either 1 = Arnaud & Rothenflug (1985) or 2 = Kingdon & Ferland (1996). Default is 2.

Parameters:

value (int) – Recombination and ionisation rateset. 1 = Arnaud & Rothenflug, 2 = Kingdon & Ferland.

Example:

>>> s.var_cxcon(1)