Target: one image, one coronagraph#

Target: the original one-image interface (one target image through one coronagraph).

target = Target()                         # toycoronagraph_para.toml in the working directory
target.plot_origin()                      # the input image -> origin.png
target.add_planet([0.5, 0.0], 5e-5, mode="cartesian")
final = target.plot_final(charge=6)       # the final image -> charge6_with_planets_final.png
target.contrast(charge=6)                 # planet and dust light in the planet's core (Jy)
target.planet_video(charge=6)             # a moving planet over one period -> planet_video.webm

The parameters come from the parameter file (toycoronagraph.config, either layout); the image is in Jy/arcsec^2 on target_pixel x target_pixel pixels of psf_scale arcsec, star at pixel (N-1)/2. The coronagraph is [coronagraph] type: a vortex (charge: positive, even) or the Lazuli telescope (toycoronagraph.lazuli; charge 0 = no coronagraph, or an even vortex charge; odd image size). The PSFs and final images are made and cached by toycoronagraph.observe’s Coronagraph (shared with observe()). Planet positions are (radius arcsec, angle rad from +x towards +y), with y increasing with the image row as in FITS and in scenes (tool.arcsec_to_pixel); plots show +y upwards (flip=False turns the y axis over). Planet brightnesses are stored per pixel area (Jy/arcsec^2 = Jy / psf_scale^2).

class toycoronagraph.main.Target(para_file=None)[source]#

Bases: object

A target: a dust ring, a debris disk, ice remains, … (not necessarily circularly symmetric).

The parameters come from toycoronagraph_para.toml (see toycoronagraph.config). The final image is made with the circular method when the target and the PSFs are both circularly symmetric, otherwise with the spatial method (see check_symmetry); the parameter file, or the method argument, can choose either.

Variables:

par (SimpleNamespace) – The parameters, resolved against the input image (target_pixel N, psf_scale in arcsec/pixel, wavelength in m, charge, method, …).
file_name (str) – The FITS file of the target.
scene (Scene or None) – The scene the image was read through (scene-layout parameter files only; see toycoronagraph.scene).
xpix (np.ndarray) – (N,) float64 pixel-centre offsets from the star along the columns, in arcsec (x).
ypix (np.ndarray) – (N,) float64 pixel-centre offsets from the star along the rows, in arcsec, in row order (equal to xpix; y increases with the row, see tool.arcsec_to_pixel).
extent (list) – [left, right, bottom, top] pixel edges in arcsec, for imshow.
pre_img (np.ndarray) – (N, N) float64 target image in Jy/arcsec^2.
planets (list) – Each planet’s position (radius arcsec, angle rad).
orbits (list) – Each planet’s orbit: np.ndarray [a (arcsec), e, pa (deg), inc (deg), t (orbital periods)] for moving planets, None for static ones.
planets_brightness (list) – Each planet’s brightness per pixel area in Jy/arcsec^2 (Jy / psf_scale^2).
output_prefix (str) – Prefix of saved figures and videos: “<target name>_”, “” for the example.

Initialization

Initializes the instance based on the parameter file and the target fits file; writes the values used to <parameter file>_used.toml (the parameter file is not modified).

Parameters:

para_file (str) – Parameter file; default toycoronagraph_para.toml in the working directory.

Raises:

ValueError – The image cannot be read or put in Jy/arcsec^2 (e.g. an unknown unit, or a contrast image without the star’s flux), or the coronagraph cannot work on it (lazuli: an even image size, too few pupil samples for its field, no light at its wavelengths, an OPD map that is not valid; see observe.optics_for).
OSError – A lazuli coronagraph’s OPD map cannot be read.
ImportError – A lazuli coronagraph without prysm or the Lazuli config packages.

radial_psfs_file(charge=None)[source]#

Radial PSF file

The file of the radial PSF series (sources along the +x axis) on frames larger than the image, calculated and saved in psf_cache_dir if it does not exist. Its name records the optics and sampling, so a cache made with other parameters is never reused.

Parameters:: charge (int) – Charge number (vortex; lazuli: 0 = the telescope alone); default from the parameters.
Returns:: The path of the .npy file (psf_cache_dir/radial_<tag>_frame<size>.npy, a ((N+1)//2, size, size) float32 array; see Coronagraph.radial_psfs_file).
Return type:: str

radial_psfs(charge=None)[source]#

The radial PSF series (see radial_psfs_file).

Parameters:: charge (int) – Charge number (vortex; lazuli: 0 = the telescope alone); default from the parameters.
Returns:: ((N+1)//2, size, size) float32 PSFs of sources along +x, size > N.
Return type:: np.ndarray

choose_method(charge=None, method=None, spatial_mode=None, verbose=True)[source]#

Method choice

The method for the final image: method / spatial_mode if given, else the parameter file’s; “auto” uses the circular method only when the target and the PSFs are both circularly symmetric ([target] / [coronagraph] symmetric, or measured / from the optics model).

Parameters:

charge (int) – Charge number (vortex; lazuli: 0 = the telescope alone); default from the parameters.
method (str) – “auto”, “circular” or “spatial”; default from the parameters.
spatial_mode (str) – “auto”, “rotate” or “direct”; default from the parameters.
verbose (bool) – Print the choice and why.

Returns:

method (str) and spatial_mode (str; None for the circular method).

Return type:

tuple

Raises:

ValueError – An unknown method / spatial_mode, or “rotate” for optics that do not allow it.

check_symmetry(charge=None)[source]#

Symmetry check

Print whether the target and the PSFs are circularly symmetric and which method the final image will use (see choose_method).

Parameters:: charge (int) – Charge number (vortex; lazuli: 0 = the telescope alone); default from the parameters.
Returns:: method (str) and spatial_mode (str; None for the circular method).
Return type:: tuple

spatial_model(charge=None, spatial_mode='rotate')[source]#

Spatial PSF model

The spatially-sampled PSFs for this target (built once per charge and mode): the kernel size and the grid are chosen so the final image meets [method] error_target; the runs along the x axis are cached in psf_cache_dir. Prints the error analysis.

Parameters:

charge (int) – Charge number (vortex; lazuli: 0 = the telescope alone); default from the parameters.
spatial_mode (str) – “rotate” or “direct”.

Returns:

The model (see psf.spatial_psf_calculation).

Return type:

dict

plot_origin(plot_planets=True, res=1000, plot_dpi=300, boundary=True, flip=True, file_name=None, log=False, log_range=5)[source]#

Plot original target

Plot the original image (Jy/arcsec^2) with or without planets: each planet is a coloured circle labelled with its brightness in Jy, with its orbit (dashed) if it moves. Planets outside the image are reported, greyed, and drawn only without boundary.

Parameters:

plot_planets (bool) – Whether to plot planets or not.
res (int) – Number of points used for orbit calculations.
plot_dpi (int) – Dots per inch (DPI) for the plot.
boundary (bool) – Whether to limit the axes to the image.
flip (bool) – True: +y upwards (row 0 at the bottom, as DS9 shows FITS); False: the y axis turned over.
file_name (str) – Save the figure exactly there: “name.png” or “folder/name.png” (the folder is created). The format follows the extension (PNG if there is none). None (default): origin.png / origin_with_planets.png (with the target’s name in front for your own targets).
log (bool) – Log colour scale (faint outer parts visible); else linear from 0.
log_range (float) – Log scale: decades shown below the image’s peak.

Returns:

The figure is saved (origin*.png, see file_name) and shown.

Return type:

None

add_planet(pos, brightness, mode='moving', res=1000)[source]#

Add a planet

Add a planet to the Target object (appended to planets, planets_brightness and orbits). Invalid input (a position that tool.is_planet_pos_allowed refuses, e.g. one with an entry that is not a number, a brightness that is not a positive number, an unknown mode) is reported with a message and nothing is added.

Parameters:

pos (array-like) – Planet position information (depends on mode); each entry a finite real number (Python or numpy int or float). For “moving” mode, pos = [a, e, pa, inc, t]: semi-major axis (arcsec), eccentricity (0 <= e < 1), position angle (deg), inclination (deg) and time (in orbital periods); for “polar” mode, pos = [r (arcsec), theta (deg, from +x towards +y)]; for “cartesian” mode, pos = [x, y] (arcsec).
brightness (numbers.Real) – Planet brightness in Jy (> 0): a Python or numpy int or float (not a bool).
mode (str) – Mode for specifying planet position coordinates (“moving”, “polar”, “cartesian”).
res (int) – Number of points used for orbit calculations.

Returns:

None

list_planets()[source]#

List planets

Print the planets present in the Target object with their order numbers (from 1), static or moving, position (x, y) in arcsec and brightness in Jy.

Returns:: None

delete_planet(order=1)[source]#

Delete planet

Deletes a planet from self.planets, self.orbits, and self.planets_brightness with a given order number, then prints the remaining planets.

Parameters:: order (int) – The order number of the planet to be deleted (from 1). Defaults to 1.
Returns:: None

planet_move(time, order=1, mode='cumulate', plot_pos=False, plot_dpi=300, res=1000, flip=True, message=True)[source]#

Planet moving

Move a moving planet along its orbit (static planets cannot move).

Parameters:

time (float) – The time, in orbital periods.
order (int) – The order number of the planet (from 1).
mode (str) – “cumulate”: time is added to the planet’s current time; “specific”: the planet’s time is set to time. Any other mode leaves the time unchanged.
plot_pos (bool) – Whether to plot the new planet’s position in its orbit (saved as oribit_planet<order>.png and shown, see planet.orbit_plot).
plot_dpi (int) – Dots per inch (DPI) for the plot.
res (int) – Number of points used for orbit calculations.
flip (bool) – True: +y upwards; False: the y axis turned over.
message (bool) – Whether to show the notification once job done (when not plotting).

Returns:

None

planet_video(charge=None, order=1, iwa_ignore=False, plot_dpi=300, length=3, fps=20, flip=True, method=None, spatial_mode=None)[source]#

Planet Video

Create a movie of the planet moving over one orbital period, starting from its current position; afterwards the planet is back at that position. The disk’s final image is made once; each frame adds the planet’s image at its new position.

The video is lossless (VP9 lossless in WebM, see toycoronagraph.video): every frame decodes to exactly the rendered pixels, so colours can be read against the colour bar. It stays small (about 100-200 kB for 60 frames) because the frames differ only around the planet. It plays in browsers, VS Code and VLC (not QuickTime). Needs ffmpeg with libvpx-vp9.

Parameters:

charge (int) – Charge number (vortex; lazuli: 0 = the telescope alone); default from the parameters.
order (int) – The order number of the planet, using self.list_planets() to look up the order.
iwa_ignore (bool) – Whether to ignore the dust inside IWA.
plot_dpi (int) – Dots per inch of the 10 x 8 inch frames (300: 3000 x 2400 pixels).
length (int) – The length of the movie in seconds.
fps (int) – The frames per second of the movie.
flip (bool) – True: +y upwards; False: the y axis turned over.
method (str) – “auto”, “circular” or “spatial”; default from the parameters.
spatial_mode (str) – “auto”, “rotate” or “direct”; default from the parameters.

Returns:

The video is saved as <prefix>planet_video[_iwa_ignore][_spatial].webm in the working directory (with the target’s name in front for your own targets).

Return type:

None

plot_orbit(order=1, plot_dpi=300, res=1000, flip=True)[source]#

Orbit plot

Plot the orbit of a moving planet, with its current position (planet.orbit_plot).

Parameters:

order (int) – The order number of the planet, using self.list_planets() to look up the order.
plot_dpi (int) – Dots per inch (DPI) for the plot.
res (int) – Number of points used for orbit calculations.
flip (bool) – True: +y upwards; False: the y axis turned over.

Returns:

The figure is saved as oribit_planet<order>.png (sic) and shown.

Return type:

None

contrast(charge=None, order=1, plot_contrast=True, plot_dpi=300, exozodi_limit=10, res=100, method=None, spatial_mode=None)[source]#

Contrast

Find the planet brightness and background brightness in the final image: the planet’s core (the pixels where its final image is above half its peak) is the aperture, and the planet and the dust (with and without the dust inside the IWA) are summed inside it.

Parameters:

charge (int) – Charge number (vortex; lazuli: 0 = the telescope alone); default from the parameters.
order (int) – The order number of the planet, using self.list_planets() to look up the order.
plot_contrast (bool) – Whether to plot the dust to planet light ratio in the planet’s core against a factor scaling the dust’s brightness (e.g. more exozodiacal dust; shown, not saved).
plot_dpi (int) – Dots per inch (DPI) for the plot.
exozodi_limit (float) – The largest dust brightness factor plotted.
res (int) – The number of points in the exozodi ratio range.
method (str) – “auto”, “circular” or “spatial”; default from the parameters.
spatial_mode (str) – “auto”, “rotate” or “direct”; default from the parameters.

Returns:

planet brightness, background brightness, and background brightness (ignored dust inside IWA), floats in Jy (also printed, and plotted if plot_contrast); None for an invalid order, or (circular method) a planet at or beyond the last radial PSF’s source, which the final image leaves out (see psf.cir_psf_planets).

Return type:

tuple or None

plot_final(charge=None, iwa_ignore=False, add_planet=True, plot_dpi=300, flip=True, method=None, spatial_mode=None, file_name=None, log=False, log_range=5)[source]#

Final image

Plots the target image after processing with the coronagraph, with the circular or the spatial method (see choose_method).

Parameters:

charge (int) – Charge number (vortex; lazuli: 0 = the telescope alone); default from the parameters.
iwa_ignore (bool) – Whether to ignore the target inside the IWA.
add_planet (bool) – Whether to include planets in the plot.
plot_dpi (int) – Dots per inch (DPI) for the final plot.
flip (bool) – True: +y upwards; False: the y axis turned over.
method (str) – “auto”, “circular” or “spatial”; default from the parameters.
spatial_mode (str) – “auto”, “rotate” or “direct”; default from the parameters.
file_name (str) – Save the figure exactly there: “name.png” or “folder/name.png” (the folder is created). The format follows the extension (PNG if there is none). None (default): charge<c>[_with_planets][_iwa_ignore][_spatial]_final.png (“lazuli_charge<c>…” for the Lazuli telescope; with the target’s name in front for your own targets).
log (bool) – Log colour scale (faint outer parts visible); else linear from 0.
log_range (float) – Log scale: decades shown below the image’s peak.

Returns:

The (N, N) float64 final image in Jy/arcsec^2 (also saved, see file_name, and shown).

Return type:

np.ndarray