Coronal mass ejection#

The CME module: a coronal mass ejection seen in starlight scattered by its electrons.

The CME’s shape is the model of astro_toolbox’s cme_imaging (by iveydavis, iveydavis/astro_toolbox; ported here with the author’s agreement): cme_mass_fraction() builds the share of the CME’s mass in each pixel of a dim x dim box (dim odd, the star at pixel dim // 2), a crescent-shaped shell pointing along +x. Its electrons (mass / (mu_e x atomic mass unit)) scatter the starlight they receive at their projected distance r from the star, so each pixel’s contrast (a fraction of the star’s flux) is

N_e sigma_T / (4 pi r^2),

zero for pixels inside the star. Thomson scattering is grey: the contrast holds in any band.

With dim and extent “auto”, the box is the scene’s own grid (no resampling); otherwise its dim pixels span extent au and the image is resampled onto the scene grid.

Newer cme_imaging versions (e.g. the halo/toroidal model) can be used directly instead: set toolbox_path (the model is then built by cme_imaging with cme_args), or pass an existing cme_imaging.Star with Cme.from_object(). Its contrast is read as grid_cme_photons * pix_res^2 over the star’s photon output, taken from the model’s own stellar flux grid (flux(r) x 4 pi r^2). (cme_imaging’s luminosity is 4 pi R^2 x radiance, without the factor pi of the surface flux, so its luminosity / photon_energy is pi too small; a note says so when the two differ.)

toycoronagraph.sources.cme.cme_mass_fraction(dim, dR_factor=0.2, vertical_height_factor=1.0, horizontal_height_factor=0.0, smear=False, smear_sig=3.0)[source]#

The share of the CME’s mass in each pixel: cme_imaging’s CME.build_cme_normalized_grid, ported line by line (the same results, including its integer rounding).

The CME is a shell between the radii Rmin and Rmax (in pixels; they grow with dR_factor and shift outwards with horizontal_height_factor), spanning +-45 degrees around +x, squeezed vertically by vertical_height_factor; its upper half is mirrored to the lower half.

Method (on the upper-right quarter, rc = dim // 2 + 1 pixels on a side, dr = rc dR_factor): for each layer j < int(dr / 2), the edges r(phi) = R cos(2 phi), phi in [0, 45 deg], with R = Rmin_j = dr (1 + horizontal_height_factor) + j and Rmax_j = dr (2 + horizontal_height_factor) - j, are rounded to integer pixels; each column x = i is filled between the inner and outer edge (from y = 0 beyond the inner edge’s reach; a column without an edge point takes the mean of the last edge sample found and the next one), each pixel holding the column’s height, and the layer is added with the weight sqrt(|Rmin_j - Rmax_j| xmax) j (xmax: the outer edge’s x samples, broadcast along the columns, as in cme_imaging; layer 0 has weight 0). Columns whose edges are not defined yet (or beyond the box) are skipped; y edges left from the previous column (or layer) are reused, as in cme_imaging.

Do not restructure: tests/scene_stage4_cme.py checks it against cme_imaging bit for bit.

Parameters:

dim (int) – Pixels on a side; an even dim is made odd (+1), as in cme_imaging. The box must hold some mass: at least 2 ceil(4 / dR_factor) - 1 px (39 at dR_factor = 0.2), so that int(dr / 2) >= 2 and layer 1 exists; a thin shell (small dR_factor) can need more, when all its filled columns get the weight 0 (xmax = 0).
dR_factor (float) – Shell thickness as a fraction of the half box (0 < dR_factor < 1).
vertical_height_factor (float) – Vertical stretch of the shell.
horizontal_height_factor (float) – Outward shift of the shell, in units of its thickness.
smear (bool) – Smooth the result with a Gaussian of smear_sig pixels.
smear_sig (float) – The Gaussian’s sigma, in pixels.

Returns:

(dim, dim) float64 array summing to 1; rows = y, columns = x, the star at pixel (dim // 2, dim // 2).

Return type:

np.ndarray

Raises:

ParamError – dR_factor is not between 0 and 1, or the box holds no mass (dim too small for dR_factor; cme_imaging then gives NaN everywhere): the message names a lower bound for dim (a thin shell can need more).

toycoronagraph.sources.cme.cme_contrast(fraction, mass_g, pixel_au, radius_au, mu_e=1.0)[source]#

Each pixel’s contrast: N_e sigma_T / (4 pi r^2), r the projected distance from the star.

N_e = fraction x mass_g / (mu_e m_u) electrons per pixel, all at the distance r of the pixel centre (the electrons are taken in the plane of the sky).

Parameters:

fraction (np.ndarray) – (n, n) share of the mass per pixel (cme_mass_fraction), n odd, the star at pixel (n // 2, n // 2).
mass_g (float) – The CME’s mass in g.
pixel_au (float) – Pixel size in au.
radius_au (float) – The star’s radius in au; pixels whose centre is inside it are 0.
mu_e (float) – Mass per electron in atomic mass units (cme_imaging: 1).

Returns:

(n, n) float64 contrast per pixel (a fraction of the star’s flux).

Return type:

np.ndarray

toycoronagraph.sources.cme.load_cme_imaging(toolbox_path='')[source]#

The cme_imaging module of astro_toolbox.

Parameters:

toolbox_path (str) – Folder holding cme_imaging.py (~ expanded; added to the front of sys.path); “” = importable as it is.

Returns:

cme_imaging (imported with its warnings silenced).

Return type:

module

Raises:

FileNotFoundError – no cme_imaging.py in toolbox_path.
ImportError – cme_imaging cannot be imported.

toycoronagraph.sources.cme.model_arguments(args)[source]#

cme_args for cme_imaging’s make_cme.

Parameters:: args (dict) – {name: value}; text with a unit (“1e19 g”, matched by params._QUANTITY) becomes an astropy Quantity; other values are passed as they are.
Returns:: the arguments, ready to pass as make_cme(**arguments).
Return type:: dict

toycoronagraph.sources.cme.star_photons(model)[source]#

The star’s photon output (photons/s) of a cme_imaging.Star, from its stellar flux grid: flux(r) x 4 pi r^2, the same at every r (the median of the finite values is taken).

Parameters:: model – a cme_imaging.Star after particle_to_photon_flux().
Returns:: photons per second.
Return type:: float

toycoronagraph.sources.cme.contrast_of(model)[source]#

The CME’s contrast per pixel of a cme_imaging.Star.

Parameters:: model – a cme_imaging.Star after particle_to_photon_flux().
Returns:: (dim, dim) float64 contrast per pixel (grid_cme_photons x pix_res^2 / the star’s photon output); NaN where cme_imaging has no stellar flux (inside the star).
Return type:: np.ndarray

class toycoronagraph.sources.cme.Cme(**settings)[source]#

Bases: Source

A CME in Thomson-scattered starlight, as a contrast (family “relative”, valid in any band).

Three ways to build it (see the module docstring): the ported geometry (default; uses the GEOMETRY parameters, extent and dim), cme_imaging itself with cme_args (toolbox_path set; then also requires the star’s temperature), or an existing cme_imaging.Star (from_object(); requires nothing, its distance, radius, temperature and grid are provided).

Check the parameters; with toolbox_path set, also require the star’s temperature.

Parameters:: **settings – the module’s parameters (see params).

classmethod from_object(star)[source]#

The module for an existing cme_imaging.Star (any version).

Parameters:: star (cme_imaging.Star) – with its CME made (particle_to_photon_flux() is called if it was not, its output silenced).
Returns:: the module, with default settings and no requirements.
Return type:: Cme

inspect()[source]#

With a cme_imaging.Star (from_object): its distance, radius, temperature and grid.

Returns:: [(key, value, origin)] for star.distance (pc), grid.pixel_scale (arcsec), star.radius (R_sun) and star.temperature (K) when they are Quantities, grid.size; [] without a cme_imaging.Star.
Return type:: list of tuple

render(grid, star)[source]#

The CME’s contrast per pixel.

Parameters:

grid (toycoronagraph.scene.Grid) – The scene grid (size, pixel_scale in arcsec).
star (toycoronagraph.scene.Star) – The star (distance pc, radius R_sun; with toolbox_path also the temperature K); not used with from_object().

Returns:

(dim, dim) contrast_pixel on the model box (pixel_scale set in arcsec; resampled by the scene when it differs from the grid), with notes on unused parameters, cme_imaging’s luminosity and NaN pixels.

Return type:

SourceImage

Raises:

ParamError – A model box too small to hold the shell’s mass (dim, or the grid size with dim “auto”: < 39 px at dR_factor = 0.2), with the ported geometry or cme_imaging’s; with the ported geometry, dR_factor = 1; with toolbox_path, make_cme rejects cme_args.