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 antiphase 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, custom=None, image_order_limit=None, **kwargs)[source]¶ Bases:
xpsi.ParameterSubspace.ParameterSubspace
A photospheric hot region that is contiguously radiating.
Instances of this class can take the following forms:
 a circular, simplyconnected region;
 a ceding region with a nonradiating 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 counterintuitive. These settings produce a superseding region with a nonradiating omission region, which is equivalent to a ceding region with a nonradiating 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 nonsuperseded subset of the ceding region is then simplyconnected (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 keysvalue 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 keyvalue 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 hardcoded bound.  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.  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 squareroot 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 noncongruence 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 4vector 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) phaseshifting applied near the end of the likelihood evaluation is related to this choice and thus phaseshift 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 (superseding region or an omission 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 2surface (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:  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 highestorder 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 quasinaturally 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). Higherorder images generally contribute less and less due to geometric projection effects (higherorder 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 sourcereceiver 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

_HotRegion__compute_cellParamVecs
()¶ Precompute photospheric source radiation field parameter vectors cellbycell. 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.

_HotRegion__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.
 st – Instance of

_HotRegion__construct_cellMesh
(st, fast_total_counts, threads)¶ Call a lowlevel routine to construct a mesh representation.
Parameters:  st – Instance of
Spacetime
.  threads (int) – Number of
OpenMP
threads for mesh construction.
 st – Instance of

cede
¶ Does the hot region have a ceding member?

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 timedependent component arising from the presence of the hot region.

integrate
(st, energies, threads, hot_atmosphere, elsewhere_atmosphere)[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 onedimensional
numpy.ndarray
of energies in keV.  threads (int) – Number of
OpenMP
threads for pulse integration.
 st – Instance of

leaves
¶ Get the leaves of the photospheric foliation.

num_cells
¶ Get the total number of cells in the mesh.

num_rays
¶ Get the number of rays integrated per parallel.

phases
¶ Get the leaves of the photospheric foliation.

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 yaxis 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.

sqrt_num_cells
¶ Get the number of cell parallels.