Photosphere

Instances of Photosphere represent a photosphere embedded in an ambient Schwarzschild spacetime.

class xpsi.Photosphere.Photosphere(hot=None, elsewhere=None, everywhere=None, bounds=None, values=None, stokes=False, custom=None, **kwargs)

Bases: ParameterSubspace

A photosphere embedded in an ambient Schwarzschild spacetime.

Parameters:

• hot (obj) – An instance of HotRegion (or a derived class). This objects represents the hot regions of the surface that in most use-cases will be assumed to contain radiating material that is hotter than that elsewhere.

• elsewhere (obj) – An instance of Elsewhere (or a derived class).

• everywhere (obj) – An instance of Everywhere (or a derived class).

Note

You cannot specify the surface radiation field everywhere if you use hot regions (the latter usage may also include specification of the radiation field elsewhere).

Parameters:

• bounds (dict) – Bounds are supplied for instantiation of a frequency parameter. The parameter name 'mode_frequency' 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. If None, lock the coordinate rotation frequency of a mode of asymmetry in the photosphere to a fixed frequency, e.g., the stellar rotation frequency. If bounds are passed, the frequency is interpreted as a free parameter.

• values (dict) – Either the fixed value of the mode frequency, a callable if the frequency is derived, or a value upon initialisation if the frequency is free. The dictionary must have a key with name 'mode_frequency' if it is fixed or derived. If the asymmetry is locked to the stellar spin, then you need to pass the spin frequency. If fixed but different to the spin frequency, this value needs to be passed instead. In the hot region base class this mode frequency is applied to normalise the ray lags instead of the stellar rotation frequency.

• stokes (boolean) – A Boolean that determines whether the signals for all the Stokes I, Q, and U parameters are calculated. If False, only Stokes I is calculated.

• custom (iterable) – A Parameter instance or iterable over such instances. Might be useful for calling image plane extensions and passing global variables, without having to instantiate surface-discretisation classes and without having to handle global variable values at compile time or from disk for runtime access.

Note

In basic modelling patterns the frequency is the spin frequency, and thus you only need to explicitly pass the spin as value whilst leaving bounds to default. If the spin frequency happens to be a free parameter (perhaps with informative prior information), then pass a callable instead that can be used to get the spin frequency dynamically when the derived mode frequency variable is called for.

property elsewhere

Get the instance of Elsewhere.

property elsewhere_atmosphere

Get the numerical atmosphere buffers for elsewhere if used.

To preload a numerical atmosphere into a buffer, subclass and overwrite the setter. The underscore attribute set by the setter must be an \(n\)-tuple whose \(n^{th}\) element is an \((n-1)\)-dimensional array flattened into a one-dimensional numpy.ndarray. The first \(n-1\) elements of the \(n\)-tuple must each be an ordered one-dimensional numpy.ndarray of parameter values for the purpose of multi-dimensional interpolation in the \(n^{th}\) buffer. The first \(n-1\) elements must be ordered to match the index arithmetic applied to the \(n^{th}\) buffer. An example would be self._hot_atmosphere = (logT, logg, mu, logE, buf), where: logT is a logarithm of local comoving effective temperature; logg is a logarithm of effective surface gravity; mu is the cosine of the angle from the local surface normal; logE is a logarithm of the photon energy; and buf is a one-dimensional buffer of intensities of size given by the product of sizes of the first \(n-1\) tuple elements.

It is highly recommended that buffer preloading is used, instead of loading from disk in the customisable radiation field extension module, to avoid reading from disk for every signal (likelihood) evaluation. This can be a non-negligible waste of compute resources. By preloading in Python, the memory is allocated and references to that memory are not in general deleted until a sampling script exits and the kernel stops. The likelihood callback accesses the same memory upon each call without I/O.

embed(fast_total_counts, threads)

Embed the photosphere in an ambient Schwarzschild spacetime.

In other words, generate a discrete representation of the photospheric radiation field and the null mapping from the photosphere to infinity, for use in flux integrators called by distant observers.

property everywhere

Get the instance of Everywhere.

property hot

Get the instance of HotRegion.

property hot_atmosphere

Get the numerical atmosphere buffers for hot regions if used.

To preload a numerical atmosphere into a buffer, subclass and overwrite the setter. The underscore attribute set by the setter must be an \(n\)-tuple whose \(n^{th}\) element is an \((n-1)\)-dimensional array flattened into a one-dimensional numpy.ndarray. The first \(n-1\) elements of the \(n\)-tuple must each be an ordered one-dimensional numpy.ndarray of parameter values for the purpose of multi-dimensional interpolation in the \(n^{th}\) buffer. The first \(n-1\) elements must be ordered to match the index arithmetic applied to the \(n^{th}\) buffer. An example would be self._hot_atmosphere = (logT, logg, mu, logE, buf), where: logT is a logarithm of local comoving effective temperature; logg is a logarithm of effective surface gravity; mu is the cosine of the angle from the local surface normal; logE is a logarithm of the photon energy; and buf is a one-dimensional buffer of intensities of size given by the product of sizes of the first \(n-1\) tuple elements.

It is highly recommended that buffer preloading is used, instead of loading from disk in the customisable radiation field extension module, to avoid reading from disk for every signal (likelihood) evaluation. This can be a non-negligible waste of compute resources. By preloading in Python, the memory is allocated and references to that memory are not in general deleted until a sampling script exits and the kernel stops. The likelihood callback accesses the same memory upon each call without I/O.

integrate(energies, threads)

Integrate over the photospheric radiation field.

Parameters:

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

• threads (int) – Number of OpenMP threads to spawn for signal integration.

• stokes (bool) – If activated, a full Stokes vector is computed and stored in signal, signalQ, and signalU.

property signal

Get the stored signal (Stokes I).

Returns:

A tuple of tuples of ndarray[m,n]. Here \(m\) is the number of energies, and \(n\) is the number of phases. Units are photon/s/keV; the distance is a fast parameter so the areal units are not yet factored in. If the signal is a spectrum because the signal is time-invariant, then \(n=1\).

property signalQ

Get the stored Stokes Q signal.

Returns:

A tuple of tuples of ndarray[m,n]. Here \(m\) is the number of energies, and \(n\) is the number of phases. Units are photon/s/keV; the distance is a fast parameter so the areal units are not yet factored in. If the signal is a spectrum because the signal is time-invariant, then \(n=1\).

property signalU

Get the stored Stokes U signal.

Returns:

A tuple of tuples of ndarray[m,n]. Here \(m\) is the number of energies, and \(n\) is the number of phases. Units are photon/s/keV; the distance is a fast parameter so the areal units are not yet factored in. If the signal is a spectrum because the signal is time-invariant, then \(n=1\).

property spacetime

Return instance of Spacetime.