Table of contents ================= * [Model description](#model-description) * [Reference](#reference) * [Model parameters](#model-parameters) * [Further output of the model](#further-output-of-the-model) * [Required files](#required-files) * [Installation and usage in XSPEC](#installation-and-usage-in-xspec) Model description ================= This model computes the emission from an acrretion disc that is illuminated by the X-ray corona (point-like) located on the axis above the central black hole (lamp-post geometry). The output spectrum includes the thermal disc emission, primary X-ray emission as well as the X-ray reflection in a self-consistent way. Part of the illuminating flux that is not reflected is absorbed and thermalised thus increases the temperature of the disc (we assume, on average, the same thermalisation due to illumination of the disc by corona on each side of the accretion disc). The disc is assumed to be Keplerian, extending from ISCO to a given outer radius. The disc consists of two regions. Above a transition radius all energy produced by accretion is released in the form of thermal radiation (i.e. similar to Novikov-Thorn disc but including also the thermalised absorption due to illumination), while below the transition radius all energy released by accretion is somehow channeled to the corona and fully used to heat the electrons in the corona that Comptonize the seed photons from the accretion disc. The thermal radiation of the disc below the transition radius is only due to the thermalisation of the absorbed part of the X-ray illumination. The low energy cut-off in the X-ray spectrum is computed by integrating the thermal disc photons over all disc arriving at the corona to give the average seed photon energy at the corona. The total X-ray luminosity of the corona is given by the energy of incoming photons plus the energy disipated by accretion of the Keplerian disc below the transition radius (half is used by corona on each side of the disc). The computation is iterative since the disc emission influences the corona Comptonised emission while the disc illumination by corona influences the disc emission. In the end the code calculates self-consistently the low energy cut-off and total X-ray luminosity. The number of scattered photons is conserved. In this way the size of the corona is also estimated. The optical depth is estimated from the power-law index of the primary X-ray radiation. The X-ray reflection is computed for the whole disc, i.e. always from the ISCO upwards. The X-ray reflection is taken from Garcia et al. XILLVER tables for reflection from ionised discs. All relativistic effects are taken into account (in all parts of the light path - from the disc to the corona, from the corona to the observer and back to the disc and from the disc to the observer). Note that the speed of the code heavily depends on the required computational precision that is defined by the grid in radial and azimuthal coordinates on the accretion disc (par16 and par17). For the SED the default values should be sufficient in most cases (par16=80 and par17=45) when thermal and primary X-ray spectrum are computed with high precision while X-ray reflection contains a lot of noise. For very good resolution of X-ray reflection, par16=300 and par17=180 are a very good choice. For excelent resolution of X-ray reflection one needs par16=500 and par17=360. On the other hand values above par16=1000 and par17=720 are already unnecessarily high. To speed up the code on computational servers with many CPU cores, it is advised to use paralelisation of the code by defining the number of cores to be used in computation by the par18 parameter. However, it is not advised to define higher number then the number of CPU cores available. **IMPORTANT**: X-ray and optical/UV spectra should be in different pha files. X-ray spectra should be at energies above 0.1 keV. For any issues regarding the use of KYNSED, please, contact M. Dovčiak at [michal.dovciak@asu.cas.cz](mailto:michal.dovciak@asu.cas.cz). Reference ========= Dovčiak M., Papadakis I.E. & Kammoun E.S. (2022) A&A [[arXiv:2110.01249](https://arxiv.org/abs/2110.01249)] Model parameters ================ * **par1 ... M** - black hole mass in units of 108 solar masses * **par2 ... spin** - black hole angular momentum (-1 ≤ a/M ≤ 1) * **par3 ... incl** - observer inclination in degrees (0°-pole, 90°-disc) * **par4 ... arate** - accretion rate in units of LEdd if positive or in Solar mass per Julian year (365.25days) if negative * **par5 ... f_col** - spectral hardening factor; if f_col=-1 then the value is computed according to Done et al. (2012) MNRAS 420, 1848, i.e. f_col = 1 for Tmax < 3x104 K f_col = [ 72 keV / ( kb * Tmax ) ]1/9 for Tmax > 105 K f_col = [ ( Tmax / 3x104 K ) ]0.82 in all other cases * **par6 ... Ltransf** - defines how much energy is transferred to the corona, i.e. energy transferred to the corona = Ltransf×L_bol, where L_bol is the the total accretion luminosity of the NT accretion disc. - >0: par6 is the energy that is transferred from the disc to the corona from below the transition radius, r_trans; the computed value of r_trans is available via XSPEC "xset" command (see below); in this case 0 < Ltransf < 0.9 - <0: par6 is power given to the corona from an external source; in this case the transition radius is set at ISCO and Ltransf can take any value < 0 - =0: in this case the X-ray normalisation is zero, there is no X-ray emission and thus no disc thermalisation and the code gives NT full disc emission * **par7 ... rout** - outer edge of the disc (in GM/c2) * **par8 ... density** - accretion disc density in 1015 cm-3 - this parameter should be fixed to the default value (1.) and the par9 should be fixed at par9=8, - one can fix par8 to other values or let it free to vary only if the density dependent XILLVER tables are used, i.e. par9=12, and the high energy cut-off, par13, is fixed to 300 KeV; in this case, the model is not fully self-consistent since relativistic effects change the value of the high energy cut-off for the spectra illuminating the disc at different radii * **par9 ... tab** - which XILLVER table to use - 8: xillver-a-Ec5.fits, angle dependent with free high energy cut-off, this is the table to be used when par13 (E_cut) is let free (or fixed to any value), and par8 is fixed to 1 - 12: xillverD-5.fits, angle dependent with cut-off energy at 300 keV, and with the disc density between 1015-1019 cm-3, i.e. if par9=12 then the par13 must be frozen to 300 keV * **par10 ... abun** - Fe abundance (in solar abundance) * **par11 ... height** - height at which the primary X-ray source is located; it is measured from the centre, on the system axis (in GM/c2) * **par12 ... PhoIndex** - photon index of the primary power-law X-ray flux * **par13 ... E_cut** - the observed (if positive) or intrinsic (local at the source, if negative) cut-off energy of the primary X-ray radiation * **par14 ... sw** - defines the output of the model: - 0: the default value, which should be used during fitting the data; in this case, for data with all energy bins below 0.1 keV, the thermal disc emission is computed; for data at energies above 0.1 keV, both the disc X-ray reflection and the disc thermal flux are computed; in both cases the X-ray primary emission is included - 1: for plotting purposes only; only the disc X-ray reflection is given - 2: for plotting purposes only; only the thermal disc emission (including X-ray thermalisation) is given - 3: for plotting purposes only; only the X-ray continuum spectrum is given - to check the importance of the thermalisation due to disc illumination by corona, it is possible to show the model components when the absorbed flux is set to zero; to do this a negative sign of par14 should be used, i.e.: - -1: for the X-ray reflection - -2: for the thermal disc emission (without X-ray absorption) - -3: for the X-ray continuum spectrum * **par15 ... zshift** - overall Doppler shift * **par16 ... nrad** - number of radial grid points on the disc for computations * **par17 ... nphi** - number of azimuthal grid points for computations * **par18 ... nthreads** - number of CPU cores to be used for computations * **par19 ... norm** - equal to 1/D2, where D is the luminosity distance in Mpc; it must be frozen unless there is an uncertainity in the source distance Further output of the model =========================== When the fit is finished the XSPEC command xset can be used to see the following additional information of the model: * **KYLXLAMP** - total intrinsic primary X-ray luminosity in LEdd * **KYLXOBS** - total observed primary X-ray luminosity in LEdd * **KYRTRANS** - transition radius in rg=GM/c2 * **KYLEXT** - fraction of the total released accretion flow energy that is transferred (extracted) from the disc to the corona (Ltransf, positive value) or ratio of the external energy given to the corona (Lext, negative value) to the total released accretion flow energy * **KYRC** - radius of the corona in rg=GM/c2 * **KYTAU** - optical thickness of the corona * **KYNE** - electron density in the corona in cm-3 * **KYRH** - black hole event horizon in rg=GM/c2 * **KYRMS** - ISCO radius in rg=GM/c2 * **KYRIN** - inner edge of the disc in rg=GM/c2 * **KYE0** - observed low energy cut-off of X-ray primary radiation in keV * **KYXIIN** - ionisation parameter at the inner edge of the accretion disc * **KYXIOUT** - ionisation parameter at the outer edge of the accretion disc * **KYREFL** - reflection ratio, i.e. ratio of the observed X-ray reflection to the observed X-ray primary radiation in the energy range given by the data Required files ============== * **Source code files** (in [kynsed-main.tar.gz](https://projects.asu.cas.cz/dovciak/kynsed/-/archive/main/kynsed-main.tar.gz)): - xsKYNsed.c - xscutoffpl.cxx - xside.c - xside_threads.c - lmodel-kynsed.dat * **KY tables**: - [KBHtables80.fits](https://owncloud.asu.cas.cz/index.php/s/WP8aLN168MJgcB9) - [KBHlamp80.fits](https://owncloud.asu.cas.cz/index.php/s/abuFcygHKEKFiSa) * **XILLVER tables** for local re-processing of photons in the accretion disc (Garcia & Kallman 2010, ApJ, 718, 695, Garcia et al. 2013, ApJ, 768, 2 and Garcia et al. 2016, MNRAS, 462, 751, see also [XILLVER web page](http://www.srl.caltech.edu/personnel/javier/xillver/index.html)): - [xillver-a-Ec5.fits](http://www.srl.caltech.edu/personnel/javier/xillver/tables/xillver-a-Ec5.fits) - [xillverD-5.fits](http://www.srl.caltech.edu/personnel/javier/xillver/tables/xillverD-5.fits) Installation and usage in XSPEC =============================== 1. **Download the source code files** ([kynsed-main.tar.gz](https://projects.asu.cas.cz/dovciak/kynsed/-/archive/main/kynsed-main.tar.gz)) into a directory where you want to install the model, e.g. '/path/to/models/' 2. **Uncompress the source code files**, e.g. by the command: `tar -xzf kynsed-main.tar.gz` This will create a new directory 'kynsed-main' in the '/path/to/models/' directory with the KYNSED source code files. 3. **Download the four FITS files** ([KBHtables80.fits](https://owncloud.asu.cas.cz/index.php/s/WP8aLN168MJgcB9), [KBHlamp80.fits](https://owncloud.asu.cas.cz/index.php/s/abuFcygHKEKFiSa), [xillver-a-Ec5.fits](http://www.srl.caltech.edu/personnel/javier/xillver/tables/xillver-a-Ec5.fits) and [xillverD-5.fits](http://www.srl.caltech.edu/personnel/javier/xillver/tables/xillverD-5.fits)) with the tables into the directory with KYNSED, i.e. '/path/to/models/kynsed-main'. 4. **Compile the code** inside XSPEC (needed to be done only once): The code is compiled inside XSPEC with the following command (assuming all the source files and FITS tables are in the directory '/path/to/models/kynsed-main'): `initpackage kynsed lmodel-kynsed.dat /path/to/models/kynsed-main` **Note**: Your XSPEC installation must have been originally installed from the source code distribution. Local models, like KYNSED, cannot be used if the XSPEC was originally installed from the pre-compiled binary distribution. 5. **Load the KYNSED model** into XSPEC: To use the KYNSED model inside XSPEC, first the model package needs to be loaded and directory containing the KYNSED set: `lmod kynsed /path/to/models/kynsed-main` `xset KYDIR /path/to/models/kynsed-main` 6. Then the **KYNSED model may be used** in the usual way, e.g.: `mo kynsed` **Note**: In case of segmentation fault, one may need to increase the stack size before launching XSPEC, e.g. with the command: `ulimit -s unlimited` or `ulimit -s 65532`