HotRegion
Instances of HotRegion
are objects representing radiatively
intense regions of the source photosphere.
Representation of the HotRegion
class instantiation options omit
and cede
. The image also shows the prefixes used for the instance attributes associated with each type of region constituting a HotRegion
object.
Representation of a HotRegion
instance configuration, when omit
or cede
are set to True
. A description of these parameters is also presented below. If is_antiphased = True
, the parameter phase_shift
is added to \(\pi\) radians. For example, if phase_shift = 0
, the omission or the superseding region (respectively on the left and right side of the image) is in anti-phase with the observer meridian (i.e., its azimuth is \(\pi\)).
- class xpsi.HotRegion.HotRegion(bounds, values, symmetry=True, omit=False, cede=False, concentric=False, sqrt_num_cells=32, min_sqrt_num_cells=10, max_sqrt_num_cells=80, num_rays=200, num_leaves=64, num_phases=None, phases=None, do_fast=False, fast_sqrt_num_cells=16, fast_min_sqrt_num_cells=4, fast_max_sqrt_num_cells=16, fast_num_rays=100, fast_num_leaves=32, fast_num_phases=None, fast_phases=None, is_antiphased=False, atm_ext='BB', beam_opt=0, split=False, custom=None, image_order_limit=None, **kwargs)[source]
Bases:
ParameterSubspace
A photospheric hot region that is contiguously radiating.
Instances of this class can take the following forms:
a circular, simply-connected region;
a ceding region with a non-radiating superseding region;
a ceding region with a radiating superseding region.
For the first option, set
omit=False
andcede=False
. For the third option, setomit=False
andcede=True
.For the second option, set
omit=True
andcede=False
. Yes, this is counter-intuitive. These settings produce a superseding region with a non-radiating omission region, which is equivalent to a ceding region with a non-radiating superseding region. The omission region may not strictly always be a hole, because it behaves as a superseding region that does not radiate. A superseding region can exist partially outside its relative ceding region, so the non-superseded subset of the ceding region is then simply-connected (i.e., does not have a hole).Note
Setting
omit=True
andcede=True
ignores the omission setting.The
concentric
setting defines whether the superseding region is concentric with the ceding region or a omission region, supposing eitheromit=True
orcede=True
.These helper settings simply set up the optional parameter definitions so you do not have to do so more manually by providing keys-value pairs in the
bounds
andvalues
dictionaries (see below).- Parameters:
bounds (dict) –
Hard prior parameter bounds for the free parameters. The dictionary keys must match the required parameter names, at least. If a required name is omitted as a key, the parameter is interpreted as fixed or derived. A key-value pair can take the following forms:
'name': None
'name': (None, None)
,(None, x)
,(x, None)
'name': (x, y)
where if a bound is
None
that bound is set equal to a strict hard-coded bound. We note that the bounds for parameters used in the atmosphere model should be restricted (by the user) to be within the tabulated values, in case a numerical atmosphere extension is used.values (dict) – Initial values of free parameters, fixed values of fixed parameters, and callables for derived parameters. If a key is omitted for a free parameter, the initial value is
None
by default. A key cannot be omitted for a required name that appears in thebounds
dictionary with valueNone
, or a required name that is omitted from the bounds dictionary.split (bool) – If True, a
CellMesh
integrator compatible with 3+2 dimensional atmosphere interpolation is deployed. This option is currently only effective if setting symmetry=True. When used, it also ignores the atmosphere choices made using the atm_ext and beam_opt arguments.symmetry (bool) – Is the radiation field axisymmetric (w.r.t the stellar rotation axis) within superseding (and ceding) member regions? This determines which
CellMesh
integrator to deploy based on this safety check.sqrt_num_cells (int) – Number of cells in both colatitude and azimuth which form a regular mesh over a subset of the surface spanning a hot region. This is the square-root of the approximate number of cells whose centres should lie within a hot region. The total number of cells is approximately the square of this argument value. The mesh suffers from squeezing in the polar regions, leading to a high degree of non-congruence in cell shape for meshes that extend from a polar region to the equatorial region.
min_sqrt_num_cells – Sets the minimum number of cells per subregion, discretised to the same degree in colatitude and azimuth. This setting has an effect only when the hot region has two temperature components, in the form of a superseding region and a ceding region.
max_sqrt_num_cells – Sets the maximum number of cells per subregion, discretised to the same degree in colatitude and azimuth. This setting has an effect even when there is only one temperature component.
num_rays – Number of rays to trace (integrate) at each colatitude, distributed in angle subtended between ray tangent 4-vector and radial outward unit vector w.r.t a local orthonormal tetrad.
num_leaves (int) – Number of leaves mesh motion is discretised into.
num_phases (int) – Number of phases in a discrete representation of the specific flux pulses on the interval \([0,1]\).
phases – If not
None
, anumpy.ndarray
of phases for a discrete representation of the specific flux pulses on the interval \([0,1]\). IfNone
(default), thenum_phases
argument is utilised.do_fast (bool) – Activate fast precomputation to guide cell distribution between two radiating regions at distinct temperatures.
Note
For each of the resolution parameters listed above, there is a corresponding parameter whose value is respected if the fast precomputation mode is activated.
- Parameters:
is_antiphased (bool) – If
True
, shifts the cell mesh by \(\pi\) radians about the stellar rotation axis for pulse integration. This is merely a choice that can be made, and is not crucial. Note that the (fast) phase-shifting applied near the end of the likelihood evaluation is related to this choice and thus phase-shift parameter prior support can be chosen accordingly. IfFalse
, the hot region at phase zero is aligned with the observer meridian. IfTrue
, the hot region at phase zero is aligned with the meridian on which the observer’s antipode lies. Alignment also depends on the structure of the hot region. As a rule, if the hot region has a superseding region (super
region or anomit
region) then the centre of that region is the point that is aligned to a meridian.is_secondary (bool) – Deprecated. You can use or the
is_antiphased
keyword argument instead, which has precisely the same effect.
Note
The parameters are as follows:
super colatitude
super angular radius
cede or omit colatitude
cede or omit angular radius
cede or omit relative azimuth
parameters controlling the local comoving radiation field over the photospheric 2-surface (entirely the user’s responsibility unless defaulting with
custom is None
.
If the ceding region or the omission region are concentric with the superseding region, the colatitude and relative azimuth of the ceding region or omission region are not parameters.
These bounds might not be actually used, depending the user’s implementation of the joint prior, and the user can in that case specify
(None,None)
for bounds pertaining to the ceding region or the omission region. These bounds will be set to strict bounds, and the user can implement more complicated prior support boundaries in aPrior
subclass instance.- Parameters:
atm_ext (str) – Used to determine which atmospheric extension to use. Options at the moment: “BB”: Analytical blackbody (default), “Num4D”: Numerical atmosphere using 4D-interpolation from the provided atmosphere data, “Pol_BB_burst”: Polarized analytical blackbody+burst approximation, “Pol_Num2D”: Polarized numerical atmosphere using 2D-interpolation from the provided atmosphere data, “user”: A user-provided extension which can be set up by replacing the contents of the file hot_user.pyx (and elsewhere_user.pyx if needed) and re-installing X-PSI (if not changed, “user” is the same as “BB”).
beam_opt (int) – Used to determine which atmospheric beaming modification model to use. Options at the moment: 0: No modification (default), 1: Original*beaming_correction without re-normalization, 2: Original*beaming_correction with analytical re-normalization estimate, 3: Original*beaming_correction with numerical re-normalization.
custom (iterable) – Iterable over
Parameter
instances. If you supply custom parameter definitions, you need to overwrite the__compute_cellParamVecs()
method to handle your custom behaviour. This custom behaviour can only target the radiation field within the hot regions as defined above.image_order_limit (int) – The highest-order image to sum over. A value of one means primary images only (deflections \(<\pi\)) whilst a value of two means primary and secondary images (deflections \(<2pi\)) where visible, and so on. If
None
(the default), there is no hard limit. In this case the limit is determined quasi-naturally for each mesh element, meaning that images will be summed over until higher order images are not visible or the visibility limit is truncated due to lack of numerical precision (e.g. for rays that orbit very close to the Schwarzschild photon sphere three times or more). Higher-order images generally contribute less and less due to geometric projection effects (higher-order images become more tangential), and the images of elements get squeezed in solid angle at the stellar limb. In principle, effects such as relativistic beaming can counter this effect to a degree for certain source-receiver configurations, by increasing brightness whilst solid angle decreases, and thus the flux contribution relative to that from a primary image can be greater than suggested simply by geometric project effects. Nevertheless, inclusion of these images is more computationally expensive. If, when iterating through image orders, an image is not visible because the deflection required is greater than the highest deflection permitted at a given colatitude on a surface (accounting for the surface tilt due to rotation), then the iteration over image orders terminates.
- Required parameter names:
super_colatitude
super_radius
phase_shift
super_temperature (if no custom specification)
- Optional parameter names:
omit_colatitude
omit_radius
omit_azimuth
cede_colatitude
cede_radius
cede_azimuth
cede_temperature
- __compute_cellParamVecs()
Precompute photospheric source radiation field parameter vectors cell-by-cell. Free model parameters and derived (fixed) variables can be transformed into local comoving radiation field variables.
Subclass and overwrite with custom functionality if you desire.
Designed here simply for uniform effective temperature superseding and ceding regions.
- __compute_rays(st, photosphere, threads)
Integrate rays.
These rays represent a null mapping from photosphere to a point at some effective infinity.
- Parameters:
st – Instance of
Spacetime
.threads (int) – Number of
OpenMP
threads for ray integration.
- __construct_cellMesh(st, fast_total_counts, threads)
Call a low-level routine to construct a mesh representation.
- Parameters:
st – Instance of
Spacetime
.threads (int) – Number of
OpenMP
threads for mesh construction.
- property cede
Does the hot region have a ceding member?
- property concentric
Is the superseding region concentric with ceding member?
If not, is the superseding region concentric with an omission member?
- embed(spacetime, photosphere, fast_total_counts, threads, *args)[source]
Embed the hot region of the photosphere into the ambient spacetime.
- Parameters:
args (tuple) – Correct the integral over the radiation field elsewhere by accounting for the time-dependent component arising from the presence of the hot region.
- integrate(st, energies, threads, hot_atmosphere, elsewhere_atmosphere, atm_ext_else)[source]
Integrate over the photospheric radiation field.
Calls the CellMesh integrator, with or without exploitation of azimuthal invariance of the radiation field of the hot region.
- Parameters:
st – Instance of
Spacetime
.energies – A one-dimensional
numpy.ndarray
of energies in keV.threads (int) – Number of
OpenMP
threads for pulse integration.
- integrate_stokes(st, energies, threads, hot_atmosphere_I, hot_atmosphere_Q, elsewhere_atmosphere, atm_ext_else)[source]
Integrate Stokes parameters over the photospheric radiation field.
Calls the CellMesh Stokes integrators, with or without exploitation of azimuthal invariance of the radiation field of the hot region.
- Parameters:
st – Instance of
Spacetime
.energies – A one-dimensional
numpy.ndarray
of energies in keV.threads (int) – Number of
OpenMP
threads for pulse integration.
- property leaves
Get the leaves of the photospheric foliation.
- property num_cells
Get the total number of cells in the mesh.
- property num_rays
Get the number of rays integrated per parallel.
- property phases
Get the leaves of the photospheric foliation.
- property phases_in_cycles
Get the phases (in cycles) the pulse is interpolated at.
- static psi(theta, phi, colatitude)[source]
Coordinates of cell centres in rotated spherical coordinate system.
Transformation is anticlockwise rotation about y-axis of Cartesian basis.
- set_phases(num_leaves, num_phases=None, phases=None, fast_num_leaves=None, fast_num_phases=None, fast_phases=None)[source]
Construct the set of interpolation phases and foliation leaves.
- Parameters:
num_leaves (int) – Number of leaves mesh motion is discretised into.
num_phases (int) – Number of phases in a discrete representation of the specific flux pulses on the interval \([0,1]\). If
None
, the number of phases interpolated at is set equal to the number of leaves.phases – If not
None
, anumpy.ndarray
of phases for a discrete representation of the specific flux pulses on the interval \([0,1]\). IfNone
(default), thenum_phases
argument is utilised.
- property sqrt_num_cells
Get the number of cell parallels.