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 and cede=False. For the third option, set omit=False and cede=True.

For the second option, set omit=True and cede=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 and cede=True ignores the omission setting.

The concentric setting defines whether the superseding region is concentric with the ceding region or a omission region, supposing either omit=True or cede=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 and values 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 the bounds dictionary with value None, 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, a numpy.ndarray of phases for a discrete representation of the specific flux pulses on the interval \([0,1]\). If None (default), the num_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. If False, the hot region at phase zero is aligned with the observer meridian. If True, 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 an omit 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 a Prior 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.

print_settings()[source]: Print numerical settings.

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, a numpy.ndarray of phases for a discrete representation of the specific flux pulses on the interval \([0,1]\). If None (default), the num_phases argument is utilised.

property sqrt_num_cells: Get the number of cell parallels.

class xpsi.HotRegion.RayError[source]

Bases: xpsiError

Raised if a problem was encountered during ray integration.

class xpsi.HotRegion.PulseError[source]

Bases: xpsiError

Raised if a problem was encountered during signal integration.