Everywhere

Instances of Everywhere represents the global photosphere.

class xpsi.Everywhere.Everywhere(time_invariant, bounds=None, values=None, sqrt_num_cells=64, num_rays=200, num_leaves=100, num_phases=None, phases=None, atm_ext='BB', beam_opt=0, custom=None, image_order_limit=None, _integrator_toggle=False)

Bases: ParameterSubspace

The photospheric radiation field represented by a global mesh.

An instance of this class cannot be used in conjuction with hot region objects nor with an elsewhere instance.

The local comoving radiation field properties are not assumed to be azimuthally invariant, so a time-dependent signal can be generated upon integration over the image.

However, if you want to generate a time-dependent signal, you need to customise the parameters that control the radiation field w.r.t. surface local comoving frames. By default a single temperature parameter is defined which is globally invariant and thus the radiation field is azimuthally invariant and the image subtended on a distant observer’s sky is phase-invariant.

Parameters:

• time_invariant (bool) – See above. Is the radiation field azimuthally invariant, thus generating a phase-invariant signal? Although the default configuration is simple and azimuthally invariant, we do not provide a default value for this argument to force the user to verify their intentions.

• bounds (dict) – If custom is None, these bounds are supplied for instantiation of a temperature parameter. The parameter name '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, 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 'temperature' if it is fixed or derived.

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

• num_leaves (int) – Number of stellar rotation phases to rotate a moving mesh through during signal integration.

• num_phases (int) – Number of phases to resolve the signal at if the signal is time- dependent.

• ndarray[m] – Array of phases to resolve a time-dependent signal at.

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

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

• _integrator_toggle (bool) – For testing purposes, toggle the integrator for time-dependent signals. If left as the default (False) the general-purpose integrator is called. If toggled, an integrator is called that assumes the surface radiation field is azimuthally invariant, which combined with the default global mesh (i.e., no subclassing) results in a time-invariant signal.

Required parameter names:

• temperature (if no custom specification)

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

_compute_rays(st, photosphere, 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, photosphere, threads)

Embed the photosphere everywhere.

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.

property phases_in_cycles

Get the phases (in cycles) the pulse is interpolated at.

print_settings()

Print numerical settings.

set_phases(num_leaves, num_phases=None, phases=None)

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

class xpsi.Everywhere.RayError

Bases: xpsiError

Raised if a problem was encountered during ray integration.

class xpsi.Everywhere.IntegrationError

Bases: xpsiError

Raised if a problem was encountered during signal integration.