Elsewhere

Instances of Elsewhere represent the region of the photosphere in which smaller radiative features (such as spots) are embedded.

class xpsi.Elsewhere.Elsewhere(sqrt_num_cells=64, num_rays=1000, bounds=None, values=None, atm_ext='BB', custom=None, image_order_limit=None)

The photospheric radiation field elsewhere.

This means the radiation field exterior to the hot regions. The local comoving radiation field properties are assumed (for now) to be azimuthally invariant but can in principle vary colatitudinally.

Parameters:

• sqrt_num_cells (int) – Number of cells in both colatitude and azimuth which form a regular mesh on the surface. Must be an even number such that half of the cells are exactly in one hemisphere. The total number of cells is the square argument value. The mesh suffers from squeezing in the polar regions, leading to a high degree of non-congruence in cell shape over the surface.

• num_rays (int) – 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.

• bounds (dict) – If custom is None, these bounds are supplied for instantiation of a temperature parameter. The parameter name 'elsewhere_temperature' must be a key in the dictionary unless the parameter is fixed or derived. 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) – Either the fixed value of the temperature elsewhere, a callable if the temperature is derived, or a value upon initialisation if the temperature is free. The dictionary must have a key with name 'elsewhere_temperature' if it is fixed or derived.

• 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, “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”).

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

• 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:

• elsewhere_temperature (if no custom specification)

Show-inheritance:

_compute_cellParamVecs(*args)

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.

Parameters:

args (tuple) – An ndarray[n,n] of mesh-point colatitudes.

_compute_rays(st, threads)

Trace (integrate) a set of 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, 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.

embed(spacetime, threads)

Embed the photosphere elsewhere.

integrate(st, energies, threads, *atmosphere)

Integrate over the photospheric radiation field.

Parameters:

• st – Instance of Spacetime.

• energies – A one-dimensional numpy.ndarray of energies in keV.

• threads (int) – Number of OpenMP threads the integrator is permitted to spawn.

property num_cells

Get the total number of cells in the mesh.

property num_rays

Get the number of rays integrated per colatitude.

print_settings()

Print numerical settings.

property sqrt_num_cells

Get the number of cell colatitudes.

class xpsi.Elsewhere.RayError

Bases: xpsiError

Raised if a problem was encountered during ray integration.

class xpsi.Elsewhere.IntegrationError

Bases: xpsiError

Raised if a problem was encountered during signal integration.