Circular or spatial method#

Choosing between the circular and the spatial method.

The circular method (psf.cir_psf) is exact only when both the target and the PSFs are circularly symmetric about the star; the spatial method (spatial.spatial_psf) works for any target and PSFs. Either symmetry can be set by the user (“symmetric = true/false” in the parameter file) or, with “auto”, found here: the target’s by measuring it, the PSFs’ from the optics model (or, for a model that does not declare it, by measuring it).

toycoronagraph.selection.image_asymmetry(pre_img, bin_width=0.02)[source]#

How far a target is from being circularly symmetric about the star.

In a circularly symmetric image, pixels at the same distance from the star have the same value. Pixels are grouped in thin radius bins (bin_width pixels) and the asymmetry is the light by which they differ from their bin’s mean, relative to the target’s light (inside the inscribed circle). Near the star a bin holds only the pixels at exactly the same radius (mirror images of each other), so even a steep, barely resolved profile gives no false signal; further out a bin also mixes pixels at slightly different radii, testing the full rotational symmetry. No interpolation is involved. Inclined or off-centre disks, arcs, clumps and n-fold patterns show up; the value is about the error the circular method would make by assuming symmetry.

Light beyond the inscribed circle (the image corners) is reported separately: the circular method reads the target only out to the image edge.

Parameters:

  • pre_img (np.ndarray) – (n, n) target image, star at pixel (n-1)/2 (any unit; the absolute value is used).

  • bin_width (float) – Width of the radius bins, in pixels.

Returns:

  • asymmetry (float): Summed |pixel - its bin’s mean| inside the inscribed circle, relative to the light there (0 for an exactly symmetric target).

  • corner_fraction (float): Light beyond the inscribed circle relative to the total.

Both are 0 for an empty image.

Return type:

tuple

toycoronagraph.selection.measure_psf_symmetry(optics, kernel_size=None, radii_ld=(0.5, 1.0, 2.0, 4.0), angles_deg=(30.0, 75.0, 140.0), num_cores=-1)[source]#

Measure whether the PSFs are circularly symmetric.

For a few radii and angles, the PSF of a source at (r, phi) (propagated through the optics) is compared with the PSF of a source at (r, 0) rotated by phi (quintic spline), over a kernel_size window centred on the source. The reference PSF is computed on a window twice as wide, so the rotation never reads beyond it.

Parameters:

  • optics (Optics) – The optical system and image sampling.

  • kernel_size (int) – Comparison window, in pixels (odd); None: about +-3 lambda/D.

  • radii_ld (tuple) – Source radii, in lambda/D.

  • angles_deg (tuple) – Source angles, in degrees (the reference is at 0).

  • num_cores (int) – Number of CPU processes (joblib n_jobs; -1 uses all).

Returns:

The largest L1 difference, relative to the exact PSF’s light in the window.

Return type:

float

toycoronagraph.selection.psf_symmetry(optics, setting='auto', tol=0.01, num_cores=-1)[source]#

Whether the PSFs are circularly symmetric, and why.

Parameters:

  • optics (Optics) – The optical system and image sampling.

  • setting (bool or str) – True/False from the user, or “auto” (or None): the optics model’s declaration (backend attribute rotationally_symmetric), or, if the model does not declare it, a measurement (measure_psf_symmetry).

  • tol (float) – Largest measured relative difference still counted as symmetric.

  • num_cores (int) – Number of CPU processes (measurement only).

Returns:

  • symmetric (bool): Whether the PSFs are treated as circularly symmetric.

  • reason (str): One line saying why (for the method message).

Return type:

tuple

toycoronagraph.selection.image_symmetry(pre_img, setting='auto', tol=0.01)[source]#

Whether the target is circularly symmetric about the star, and why.

Parameters:

  • pre_img (np.ndarray) – (n, n) target image, star at pixel (n-1)/2.

  • setting (bool or str) – True/False from the user, or “auto” (or None): measured with image_asymmetry.

  • tol (float) – Largest asymmetry and corner fraction still counted as symmetric.

Returns:

  • symmetric (bool): Whether the target is treated as circularly symmetric.

  • reason (str): One line saying why (for the method message).

Return type:

tuple

toycoronagraph.selection.choose_method(method='auto', spatial_mode='auto', image_sym=True, psf_sym=True, rotate_allowed=True, reasons=())[source]#

Resolve the method from the parameter settings and the symmetries.

method “auto”: circular if the target and the PSFs are both symmetric, else spatial. spatial_mode “auto”: rotate if the PSFs are symmetric and the optics model allows it (rotationally symmetric with a known band limit), else direct. Explicit settings are kept, with a warning when they contradict the symmetries; ‘rotate’ for optics that cannot use it is an error.

Parameters:

  • method (str) – “auto”, “circular” or “spatial”.

  • spatial_mode (str) – “auto”, “rotate” or “direct”.

  • image_sym (bool) – Whether the target is circularly symmetric.

  • psf_sym (bool) – Whether the PSFs are circularly symmetric.

  • rotate_allowed (bool) – Whether the optics model supports mode ‘rotate’.

  • reasons (tuple) – Strings explaining image_sym and psf_sym (for the message).

Returns:

  • method (str): “circular” or “spatial”.

  • spatial_mode (str or None): “rotate” or “direct”; None for circular.

  • messages (list): Message lines: “Method: …” first, then any WARNING lines.

Return type:

tuple

Raises:

ValueError – For an unknown method or spatial_mode, or ‘rotate’ when not rotate_allowed.