README.md 13.2 KB
Newer Older
Michal Dovčiak's avatar
Michal Dovčiak committed
1
2
3
4
5
Table of contents
=================

* [Model description](#model-description)
* [Reference](#reference)
Michal Dovčiak's avatar
Michal Dovčiak committed
6
* [Model parameters](#model-parameters)
Michal Dovčiak's avatar
Michal Dovčiak committed
7
8
* [Further output of the model](#further-output-of-the-model)
* [Required files](#required-files)
Michal Dovčiak's avatar
Michal Dovčiak committed
9
* [Installation and usage in XSPEC](#installation-and-usage-in-xspec)
Michal Dovčiak's avatar
Michal Dovčiak committed
10
11


Michal Dovčiak's avatar
Michal Dovčiak committed
12
Model description
Michal Dovčiak's avatar
Michal Dovčiak committed
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
=================

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. 

Michal Dovčiak's avatar
Michal Dovčiak committed
53
54
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 
Michal Dovčiak's avatar
Michal Dovčiak committed
55
56
57
58
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
Michal Dovčiak's avatar
Michal Dovčiak committed
59
60
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 
Michal Dovčiak's avatar
Michal Dovčiak committed
61
spectrum are computed with high precision while X-ray reflection contains a lot
Michal Dovčiak's avatar
Michal Dovčiak committed
62
of noise. For very good resolution of X-ray reflection, par16=300 and par17=180
Michal Dovčiak's avatar
Michal Dovčiak committed
63
are a very good choice. For excelent resolution of X-ray reflection one needs 
Michal Dovčiak's avatar
Michal Dovčiak committed
64
par16=500 and par17=360. On the other hand values above par16=1000 and par17=720
Michal Dovčiak's avatar
Michal Dovčiak committed
65
66
67
68
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
Michal Dovčiak's avatar
Michal Dovčiak committed
69
computation by the par18 parameter. However, it is not advised to define higher 
Michal Dovčiak's avatar
Michal Dovčiak committed
70
71
72
73
74
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.

Michal Dovčiak's avatar
Michal Dovčiak committed
75
For any issues regarding the use of KYNSED, please, contact M. Dovčiak at 
Michal Dovčiak's avatar
Michal Dovčiak committed
76
[michal.dovciak@asu.cas.cz](mailto:michal.dovciak@asu.cas.cz).
Michal Dovčiak's avatar
Michal Dovčiak committed
77

Michal Dovčiak's avatar
Michal Dovčiak committed
78
79
80
81

Reference
=========

Michal Dovčiak's avatar
Michal Dovčiak committed
82
Dovčiak M., Papadakis I.E. & Kammoun E.S. (2022) A&A [[arXiv:2110.01249](https://arxiv.org/abs/2110.01249)]
Michal Dovčiak's avatar
Michal Dovčiak committed
83
84


Michal Dovčiak's avatar
Michal Dovčiak committed
85
86
Model parameters
================
Michal Dovčiak's avatar
Michal Dovčiak committed
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

* **par1 ... M**
  - black hole mass in units of 10<sup>8</sup> solar masses
* **par2 ... spin**
  - black hole angular momentum (-1 &le; a/M &le; 1)
* **par3 ... incl**
  - observer inclination in degrees (0&deg;-pole, 90&deg;-disc)
* **par4 ... arate**
  - accretion rate in units of L<sub>Edd</sub> 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 &lt; 3x10<sup>4</sup> K  
    f_col = [ 72 keV / ( kb * Tmax ) ]<sup>1/9</sup> for Tmax &gt; 10<sup>5</sup> K  
    f_col = [ ( Tmax / 3x10<sup>4</sup> K ) ]<sup>0.82</sup>  in all other cases
* **par6 ... Ltransf**
  - defines how much energy is transferred to the corona, i.e. energy 
    transferred to the corona = Ltransf&times;L_bol, where L_bol is the the total 
    accretion luminosity of the NT accretion disc.
  - &gt;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 &lt; Ltransf &lt; 0.9
  - &lt;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 &lt; 0
Michal Dovčiak's avatar
Michal Dovčiak committed
114
  - =0: in this case the X-ray normalisation is zero, there is no X-ray 
Michal Dovčiak's avatar
Michal Dovčiak committed
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
         emission and thus no disc thermalisation and the code gives NT full 
         disc emission
* **par7 ... rout**
  - outer edge of the disc (in GM/c<sup>2</sup>)
* **par8 ... density**
  - accretion disc density in 10<sup>15</sup> cm<sup>-3</sup> 
  - 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 10<sup>15</sup>-10<sup>19</sup> cm<sup>-3</sup>, 
        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/c<sup>2</sup>)
* **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/D<sup>2</sup>, 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 L<sub>Edd</sub>
* **KYLXOBS**
  - total observed primary X-ray luminosity in L<sub>Edd</sub>
* **KYRTRANS**
  - transition radius in rg=GM/c<sup>2</sup>
* **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/c<sup>2</sup>
* **KYTAU**
  - optical thickness of the corona
* **KYNE**
  - electron density in the corona in cm<sup>-3</sup>
* **KYRH**
  - black hole event horizon in rg=GM/c<sup>2</sup>
* **KYRMS**
  - ISCO radius in rg=GM/c<sup>2</sup>
* **KYRIN**
  - inner edge of the disc in rg=GM/c<sup>2</sup>
* **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
==============

Michal Dovčiak's avatar
Michal Dovčiak committed
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
* **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)  
Michal Dovčiak's avatar
Michal Dovčiak committed
235
236
237
238
239


Installation and usage in XSPEC
===============================

Michal Dovčiak's avatar
Michal Dovčiak committed
240
241
242
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/'
Michal Dovčiak's avatar
Michal Dovčiak committed
243
   
Michal Dovčiak's avatar
Michal Dovčiak committed
244
2. **Uncompress the source code files**, e.g. by the command:
Michal Dovčiak's avatar
Michal Dovčiak committed
245

Michal Dovčiak's avatar
Michal Dovčiak committed
246
   `tar -xzf kynsed-main.tar.gz`
Michal Dovčiak's avatar
Michal Dovčiak committed
247

Michal Dovčiak's avatar
Michal Dovčiak committed
248
249
250
251
252
253
254
255
256
257
258
259
   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):
Michal Dovčiak's avatar
Michal Dovčiak committed
260
261

   The code is compiled inside XSPEC with the following command (assuming all 
Michal Dovčiak's avatar
Michal Dovčiak committed
262
263
   the source files and FITS tables are in the directory 
   '/path/to/models/kynsed-main'):
Michal Dovčiak's avatar
Michal Dovčiak committed
264

Michal Dovčiak's avatar
Michal Dovčiak committed
265
   `initpackage kynsed lmodel-kynsed.dat /path/to/models/kynsed-main`
Michal Dovčiak's avatar
Michal Dovčiak committed
266

Michal Dovčiak's avatar
Michal Dovčiak committed
267
   **Note**:
Michal Dovčiak's avatar
Michal Dovčiak committed
268
269
270
271
   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.

Michal Dovčiak's avatar
Michal Dovčiak committed
272
5. **Load the KYNSED model** into XSPEC:
Michal Dovčiak's avatar
Michal Dovčiak committed
273
274
275
276

   To use the KYNSED model inside XSPEC, first the model package needs to be 
   loaded and directory containing the KYNSED set:

Michal Dovčiak's avatar
Michal Dovčiak committed
277
278
   `lmod kynsed /path/to/models/kynsed-main`  
   `xset KYDIR /path/to/models/kynsed-main`
Michal Dovčiak's avatar
Michal Dovčiak committed
279

Michal Dovčiak's avatar
Michal Dovčiak committed
280
6. Then the **KYNSED model may be used** in the usual way, e.g.:
Michal Dovčiak's avatar
Michal Dovčiak committed
281
282
283

   `mo kynsed`

Michal Dovčiak's avatar
Michal Dovčiak committed
284
   **Note**:
Michal Dovčiak's avatar
Michal Dovčiak committed
285
286
287
288
289
290
291
292
   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`