Observe: a scene through coronagraphs#

A scene through one or more coronagraphs.

result = observe(scene)                              # the parameter file's coronagraphs and settings
result = observe(scene, ["vortex:2", "vortex:6"], combine="together")
result.final("vortex_c6")                            # the total; result.final("vortex_c6", "wind"): one component
result.save()                                        # results/<run>/: FITS per coronagraph, params_used.toml, plots

combine = “separate” (default): each component goes through each coronagraph with its own method (symmetric ones on the exact circular method, the others on the spatial one), and the final images are summed, each one kept. “together”: the components are summed first and go through each coronagraph once. Planets (point sources) always get their exact PSF. components=[…] restricts a run to some components (the spatial kernel size still comes from the whole scene, so separate runs add up to the combined one).

A Coronagraph holds one optical system on one grid: its PSFs (radial series and spatial models, cached on disk and in memory) and the final images it has made (cached by image), so only what changed is computed again. Coronagraph.get returns the same object for the same optics and settings, so Target (toycoronagraph.main) and observe() share these caches. optics_for turns a [[coronagraph]] table into its Optics, one builder per type (OPTICS_BUILDERS): “vortex” (hcipy) and “lazuli” (the Lazuli telescope computed with prysm, toycoronagraph.lazuli).

A Result holds the final images in the scene’s internal unit (“Jy/arcsec^2” or “contrast_pixel”); Result.save writes a run folder that Result.load reads back. Conventions: (N, N) images with the star at pixel (N-1)/2; rows are +y (as in FITS).

class toycoronagraph.observe.Coronagraph(optics, name, num_cores=-1, error_target=0.02, max_kernel_gb=4.0, use_gpu=False, cache_dir='', symmetric='auto', rot_number=0, symmetry_tol=0.01)[source]#

Bases: object

One coronagraph on one grid: its PSFs and the final images of the images given to it.

Variables:

optics (Optics) – The optical system and image sampling (img_pixel N, psf_range in lambda/D).
name (str) – Name in outputs, e.g. “vortex_c6”.
num_cores,error_target,max_kernel_gb,use_gpu,cache_dir,symmetric,symmetry_tol – See __init__.
rot_number (int) – Circular method: number of rotations (N when 0 was given).
computed (list) – (what, key) of everything actually calculated, e.g. (“radial PSFs”, name), (“spatial model”, (mode, kernel_size)), (“final image”, first 8 characters of the image’s digest); what is not listed came from the caches.

Parameters:

optics (Optics) – The optical system and image sampling.
name (str) – Name in outputs and messages.
num_cores (int) – CPU cores for the PSF calculations (joblib: -1 = all).
error_target (float) – Target relative error of spatial-method final images (0.02 = 2%).
max_kernel_gb (float) – Memory limit of the spatial PSF kernels, in GB.
use_gpu (bool) – Spatial method: use CuPy for the FFT convolutions.
cache_dir (str) – Folder of the PSF cache files; “”: the working directory.
symmetric (bool or str) – Whether the PSFs are circularly symmetric; “auto”: from the optics model (or measured), see selection.psf_symmetry.
rot_number (int) – Circular method: number of rotations of the radial PSFs; 0: N.
symmetry_tol (float) – Largest measured image asymmetry still counted as symmetric.

classmethod get(optics, name, **settings)[source]#

The same object for the same optics and settings (so its PSFs and final images are reused).

Parameters:

optics (Optics) – The optical system and image sampling.
name (str) – Name in outputs.
settings – The other __init__ arguments (keywords; values must be hashable).

Returns:

The cached instance, created on first use.

Return type:

Coronagraph

property tag#

Part of the cache file names: everything the PSFs depend on, e.g. “vortex_c6_N512_range16_lyot0.95” for the vortex (and backends with its parameters), else “<kind>_N<N>_range<psf_range>_<digest>” with the first 12 hex characters of the SHA-1 of the optics’ params, e.g. “lazuli_N101_range3.16_0123456789ab”.

Type:: str

radial_psfs_file()[source]#

The radial PSF series, computed once and cached on disk.

PSFs of sources along +x at psf.radial_source_positions, on frames larger than the image (psf.extended_frame_size) so that rotated about the star they still cover the image corners.

Returns:: Path of the .npy file, cache_dir/radial_<tag>_frame<size>.npy, holding a ((N+1)//2, size, size) float32 array.
Return type:: str

radial_psfs()[source]#

The radial PSF series (radial_psfs_file), memory-mapped once: the circular method and the planets read only the frames they use, from the file (or the system’s file cache), not the whole file every time (552 MB at 512 px).

Returns:: ((N+1)//2, size, size) float32 PSFs, read-only.
Return type:: np.memmap

spatial_model(mode, weight)[source]#

The spatial PSF model whose kernel size meets the error target for an image.

The kernel size is chosen for weight (psf.choose_kernel_size; in ‘rotate’ mode from the cached radial PSFs, without new propagations) and cached per image, in memory and on disk (cache_dir/kernel_<tag>_<16 hex characters>.json, keyed by the image, mode and error target); a model already built with a larger kernel is reused (it is more accurate). The model itself (kernels, sample grid, blend weights, transmission map and error report) is cached on disk, cache_dir/model_<tag>_<mode>_K<kernel_size>_<16 hex characters>.npz, keyed by everything it is made from (_model_description, also stored in the file and compared when it is read: a file made from anything else is built again). Building one also caches the x-axis PSF runs and the error report (psf.spatial_error_report) on disk (cache_dir/axis_<tag>_K<kernel_size>.npz, cache_dir/error_<tag>_<mode>_K<kernel_size>_t<target>.npz), so a new session estimates nothing again.

Parameters:

mode (str) – “rotate” or “direct” (see psf.spatial_psf_calculation).
weight (np.ndarray) – (N, N) image whose light sets the kernel size.

Returns:

The model (see psf.spatial_psf_calculation; “kernel_size” is its kernel width in pixels).

Return type:

dict

property peak_norm#

The peak of the star’s unocculted PSF (the backend’s unocculted(): the optics without the starlight-suppression element, the Lyot stop kept), as a fraction of the star’s light per pixel: the contrast_peak reference. It is the intensity at the star’s position, so it does not depend on where the pixels fall (for an even N the star is between four pixels). Computed once; None if the backend has no unocculted().

Type:: float or None

property iwa#

The inner working angle, in lambda/D: the distance from the star at which a point source’s throughput (its light leaving the system relative to the same source without the starlight-suppression element, so 1 far from the star) reaches 0.5. It depends on the optics only, not on the image: it is searched along +x beyond the image’s edge if needed (to 64 lambda/D), by bisection to 0.01 lambda/D (about 15 sources, assuming the throughput rises with the distance); computed once. None when a source on the star already passes half (no coronagraph: e.g. the Lazuli telescope alone, charge = 0), or none reaches it by 64 lambda/D.

Type:: float or None

psf_symmetry()[source]#

Whether the PSFs are circularly symmetric (selection.psf_symmetry, computed once).

Returns:: (bool, reason str).
Return type:: tuple

choose(image, symmetry=None, method='auto', spatial_mode='auto')[source]#

The method for an image (see selection.choose_method).

Parameters:

image (np.ndarray) – (N, N) image (only used to measure its symmetry when symmetry is None).
symmetry (tuple) – (bool, reason str) if the image’s symmetry is known; None: measured.
method (str) – “auto”, “circular” or “spatial”.
spatial_mode (str) – “auto”, “rotate” or “direct”.

Returns:

(method str, spatial_mode str or None for circular, messages: list of str, the first one the summary).

Return type:

tuple

Raises:

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

image(image, method, spatial_mode=None, weight=None, iwa_ignore=False, report=True)[source]#

The final image of an image, with the circular or the spatial method (cached).

The coronagraph is linear, so the image may be in any unit; the final image is in the same one.

Parameters:

image (np.ndarray) – (N, N) image, star at pixel (N-1)/2.
method (str) – “circular” (exact for symmetric images and PSFs) or “spatial”.
spatial_mode (str) – Spatial method: “rotate” or “direct” (ignored for circular).
weight (np.ndarray) – (N, N) image setting the spatial kernel size; None: image.
iwa_ignore (bool) – Leave out the light inside the inner working angle.
report (bool) – Spatial method: print the estimated error of this image.

Returns:

(final image: (N, N) float64 in the unit of image, estimated typical relative error: float, 0 for the exact circular method).

Return type:

tuple

point_sources(pixels, values)[source]#

Point sources through the coronagraph, each with its exact PSF (psf.exact_point_sources).

Parameters:

pixels (list) – (row, column) of each source (floats; rows = +y in a scene, see Grid.pixel).
values (list) – Each source’s flux per pixel area (e.g. Jy/arcsec^2 = Jy / pixel_scale^2).

Returns:

(N, N) image of the sources, in the unit of values. Sources outside the image are left out (with a message).

Return type:

np.ndarray

interpolated_point_sources(positions, values, pixel_scale)[source]#

Point sources from the radial PSFs, interpolated in radius and rotated (Target’s circular method).

Parameters:

positions (list) – (radius arcsec, angle rad) of each source; the orientation of tool.arcsec_to_pixel (y increases with the row, as in FITS).
values (list) – Each source’s flux per pixel area (e.g. Jy/arcsec^2).
pixel_scale (float) – Pixel size in arcsec.

Returns:

(N, N) image of the sources. Sources beyond the radial PSFs are left out silently.

Return type:

np.ndarray

toycoronagraph.observe.optics_for(ctype, values, img_pixel, psf_range, wavelength, diameter, size_fix='set [grid] size = %d or %d (the image is resampled onto it)')[source]#

The Optics of a coronagraph of any type (used by coronagraph_for and by Target).

Parameters:

ctype (str) – The coronagraph type (a key of toycoronagraph.params.CORONAGRAPHS and OPTICS_BUILDERS).
values (dict) – Its parameters, every key of its declaration present (defaults filled in).
img_pixel (int) – Number of pixels on one edge of the image.
psf_range (float) – Half-width of the image, in lambda/D of the scene.
wavelength (float) – The scene’s wavelength in m.
diameter (float) – The scene’s telescope diameter in m.
size_fix (str) – How the user makes the image size odd, for optics that need it (two %d for the odd sizes around img_pixel); the default names [grid] size.

Returns:

The optical system and image sampling.

Return type:

Optics

Raises:

ParamError – The optics cannot work on this image (a lazuli coronagraph on an even size, or with too few pupil samples for its field).
ValueError, OSError, ImportError – A lazuli coronagraph’s settings cannot be resolved (see _lazuli_optics).

toycoronagraph.observe.coronagraph_for(grid, table, params)[source]#

The Coronagraph of a [[coronagraph]] table on a grid.

Parameters:

grid (Grid) – The scene grid (size, field, wavelength and diameter set the Optics).
table (dict, str or SimpleNamespace) – A [[coronagraph]] table as a dict, a string “<type>:<charge>” (e.g. “vortex:6”, “lazuli:0”; “” type: vortex, no charge: the type’s default), or a table already checked by toycoronagraph.params.
params (Params) – The scene’s parameters ([compute] and [method] settings).

Returns:

(the checked table: SimpleNamespace with type, name, values; the Coronagraph).

Return type:

tuple

Raises:

ParamError – The table is not valid, or its optics cannot work on the grid (see optics_for).
ValueError, OSError, ImportError – A lazuli coronagraph’s settings cannot be resolved (see optics_for).

toycoronagraph.observe.observe(scene, coronagraphs=None, combine=None, method=None, components=None, iwa_ignore=False, verbose=True)[source]#

The final images of a scene through one or more coronagraphs.

Parameters:

scene (Scene) – Rendered here if it is not yet.
coronagraphs (list) – [[coronagraph]] tables (dicts or checked tables), or strings like “vortex:6”; None: the scene’s parameters (a charge-2 vortex if they have none).
combine (str) – “separate” or “together”; None: [method] combine.
method (str) – “auto”, “circular” or “spatial” for every component; None: each component’s own method, else [method] method.
components (list) – Only these components (names, images or point sources), e.g. one for an individual analysis; None: all. The spatial kernel size still comes from the whole scene, so individual runs add up exactly to the combined one.
iwa_ignore (bool) – Leave out the light inside the inner working angle (images only).
verbose (bool) – Print the method chosen for each image (and the scene’s notes if it is rendered here).

Returns:

finals[coronagraph name][component name, or “total” for the images with combine = “together”], in scene.internal_unit.

Return type:

Result

Raises:

ParamError – An unknown combine, components that are not in the scene, or a coronagraph that cannot work on the scene grid (e.g. “lazuli” on an even size); before any PSF is computed.

toycoronagraph.observe.video(scene, coronagraph, component, frames, path=None, fps=10, unit='contrast_peak', log=None, log_range=None, axis=None, dpi=None, iwa_ignore=False, difference=False, **kwargs)[source]#

A video of a scene through one coronagraph while one component changes, e.g. a CME moving outwards.

The scene is observed once, every component on its own with its current settings (combine = “separate”, whatever [method] combine says). Then, per frame, the component gets that frame’s settings (checked by its module), the scene is rendered again and only the component is observed again, with the method chosen the first time and the spatial kernel chosen for the first scene (its model comes from the caches: about one convolution per frame); the other components’ final images are reused. The colour scale is fixed by the first frame. The component gets its own settings back at the end. The video is lossless (toycoronagraph.video). A faint component (e.g. a CME against a stellar wind) shows with difference=True: each frame minus the other components’ final images, like the base-difference images (minus a pre-event image) that reveal solar CMEs against the corona.

Parameters:

scene (Scene) – The scene.
coronagraph (str or dict) – One coronagraph, as in observe() (e.g. “vortex:6”).
component (str) – The component that changes (an image, not a point source).
frames (list) – One dict per frame: the component’s settings in it, e.g. {“horizontal_height_factor”: 2.0}.
path (str) – The .webm file; None: <component>_<coronagraph name>.webm in the working directory.
fps (int) – Frames per second.
unit (str) – Output unit (see Result.in_unit; “contrast_peak”: relative to the coronagraph’s own peak).
log (bool) – Log colour scale. None here and below: the [display] setting.
log_range (float) – Log scale: decades shown below the first frame’s top.
axis (str) – Axis unit (see Grid.axis).
dpi (int) – Dots per inch of the 6.4 x 5 inch frames.
iwa_ignore (bool) – Leave out the light inside the inner working angle.
difference (bool) – Show only the component’s final image (the frame minus the others’).
**kwargs – Passed to matplotlib’s imshow, e.g. cmap=”magma”.

Returns:

(path, list of the (N, N) images shown, in unit, one per frame: the final image of all components summed, or with difference=True of the component alone).

Return type:

tuple

class toycoronagraph.observe.Result(grid, unit, star, star_flux, combine, inputs, points=None, params=None)[source]#

Bases: object

The final images of a scene, and what made them.

Variables:

grid (Grid) – The scene grid.
unit (str) – The unit of every image: the scene’s internal unit (“Jy/arcsec^2” or “contrast_pixel”).
star (Star) – The scene’s star.
star_flux (float or None) – The star’s flux density in Jy (None: unknown).
combine (str) – “separate” or “together”.
inputs (dict) – {component name: (N, N) input image} (the images of this run, not the point sources).
points (dict) – {name: (positions, fluxes)}: point sources, positions a list of (radius arcsec, angle rad), fluxes a 1-D array of each one’s flux per pixel area in unit.
params (Params or None) – The scene’s parameters (display defaults, run folder settings).
finals (dict) – {coronagraph name: {component name (or “total” for the images with combine = “together”): (N, N) float64 final image in unit}}.
methods (dict) – {(coronagraph name, component name): (method, spatial_mode or None, why str, estimated typical relative error)}; method “exact” for point sources.
coronagraphs (dict) – {coronagraph name: Coronagraph} (empty after load()).
peak_norms (dict) – {coronagraph name: the peak of the star’s unocculted PSF through it, as a fraction of the star’s light per pixel (Coronagraph.peak_norm; None: unknown)}: the contrast_peak references.
iwas (dict) – {coronagraph name: its inner working angle in arcsec, or None}, filled as iwa() is asked.
tables (list) – The [[coronagraph]] tables used (for params_used.toml).
method_used (dict) – The [method] settings given to observe() (for params_used.toml).
folder (str) – The run folder, once saved.

Parameters:

grid (Grid) – The scene grid.
unit (str) – The images’ unit (“Jy/arcsec^2” or “contrast_pixel”).
star (Star) – The star.
star_flux (float or None) – The star’s flux density in Jy.
combine (str) – “separate” or “together”.
inputs (dict) – {component name: (N, N) input image in unit}.
points (dict) – {name: (positions, fluxes per pixel area)}; None: no point sources.
params (Params) – The parameters; None: no display / run defaults.

final(coronagraph=None, component=None, unit=None, star_flux=None)[source]#

The total final image, or one component’s, of a coronagraph.

Parameters:

coronagraph (str) – Coronagraph name; None: the first.
component (str) – Component name (or “total” with combine = “together”); None: the sum of all of them (images and point sources; zero for a run without components).
unit (str) – Output unit (see in_unit); None / “auto”: self.unit.
star_flux (float or Star) – See in_unit.

Returns:

(N, N) final image in unit.

Return type:

np.ndarray

Raises:

KeyError – An unknown coronagraph or component.

in_unit(image, unit, star_flux=None, coronagraph=None)[source]#

An image of this result in another unit (units.convert_image).

Parameters:

image (np.ndarray) – (N, N) image in self.unit.
unit (str) – “Jy/arcsec^2”, “Jy/pixel”, “contrast_pixel” or “contrast_peak”; None or “auto”: unchanged.
star_flux (float or Star) – The star’s flux in Jy, or a Star (its flux at the grid’s wavelength), to turn a contrast result into a brightness (and back); None: self.star_flux.
coronagraph (str) – contrast_peak: the coronagraph whose final image it is (relative to the peak of the star’s PSF through it without its mask, peak_norms); None: an input image (relative to the ideal aperture’s PSF peak, Grid.peak_norm).

Returns:

(N, N) image in unit (the same array if no conversion is needed).

Return type:

np.ndarray

Raises:

UnitError – The conversion needs the star’s flux, or the coronagraph’s peak, and it is unknown.

contributions(coronagraph=None)[source]#

Each component’s fractional contribution to the final image, pixel by pixel.

Parameters:: coronagraph (str) – Coronagraph name; None: the first.
Returns:: {component name: (N, N) float64 fraction of the total final image (0 where the total is 0)}; empty for a run without components.
Return type:: dict

contrast(planet, coronagraph=None)[source]#

The light of every component inside a planet’s core.

The core is the set of pixels where the planet’s final image is above half its peak; each component’s final image is summed over it and multiplied by the pixel area.

Parameters:

planet (str) – The planet’s component name.
coronagraph (str) – Coronagraph name; None: the first.

Returns:

{component name (the planet included): float}, in self.unit x arcsec^2 (Jy for “Jy/arcsec^2”).

Return type:

dict

plot(unit=None, log=None, axis=None, path=None, show=True, dpi=None, log_range=None, star_flux=None, coronagraphs=None, components=None, input=True, shared=True, **kwargs)[source]#

Plot the input and the final images.

Rows: the input (input=True) and each coronagraph; columns: each component and the total (when there are several components or none, or combine = “together”; zero without components). A single column is drawn as one row of panels: components=[“total”] compares the coronagraphs side by side. Point sources are marked on the input row (their panel there is blank: they have no input image), with their flux in the plot’s unit family. With unit = “contrast_peak” each row is relative to its own peak (see in_unit). Each column has one colour scale (shared=True), so the rows compare directly.

Parameters:

unit (str) – Output unit (see in_unit); “auto”: self.unit. None here and below: the [display] setting.
log (bool) – Log colour scale.
axis (str) – Axis unit (see Grid.axis).
path (str) – Save the figure there; None: not saved.
show (bool) – Show the figure (else it is closed).
dpi (int) – Resolution of the saved file.
log_range (float) – Log scale: decades shown below the top of the scale.
star_flux (float or Star) – See in_unit.
coronagraphs (str or list) – The coronagraphs shown; None: all.
components (list) – The columns (component names, “total”); None: all, see above.
input (bool) – Show the input row.
shared (bool) – One colour scale per column, set by its brightest panel (log: the 99.99th percentile, see scene.show_image); False: one per panel.
**kwargs – Passed to matplotlib’s imshow for every image, e.g. cmap=”magma”.

Returns:

The figure.

Return type:

matplotlib.figure.Figure

iwa(coronagraph)[source]#

A coronagraph’s inner working angle (Coronagraph.iwa: where a source’s throughput reaches half), in arcsec.

Computed when first asked (a few seconds) and kept in iwas; save() writes it and load() reads it back.

Parameters:: coronagraph (str) – The coronagraph’s name.
Returns:: None without a coronagraph (e.g. the Lazuli telescope alone), or when it is not known (a run loaded from files written without it).
Return type:: float or None

plot_profiles(components=False, unit=None, log=None, axis=None, path=None, show=True, dpi=None, star_flux=None, extra=None, coronagraphs=None, iwa=True, log_range=None, **kwargs)[source]#

Azimuthal mean against the distance from the star (see scene.plot_profiles).

components=False: one panel, the summed input and each coronagraph’s total final image. components=True: one panel per coronagraph (shared axes), each component’s input (dashed) and final image (solid, same colour), and the totals (thick).

Parameters:

components (bool) – One panel per coronagraph with each component (see above).
unit (str) – Output unit (see in_unit); “auto”: self.unit. None here and below: the [display] setting.
log (bool) – Log-log axes (else linear, both from 0).
axis (str) – Distance unit (see Grid.axis).
path (str) – Save the figure there; None: not saved.
show (bool) – Show the figure (else it is closed).
dpi (int) – Resolution of the saved file.
star_flux (float or Star) – See in_unit.
extra (dict) – More curves {label: (radius in arcsec, values in unit)}, dashed, on every panel.
coronagraphs (str or list) – The coronagraphs shown; None: all.
iwa (bool) – Mark each coronagraph’s inner working angle (see iwa) with a dotted vertical line, in its curve’s colour (components=False) or grey (one panel per coronagraph).
log_range (float) – Log axes show log_range + scene.PROFILE_DECADES decades below the highest point.
**kwargs – Passed to matplotlib’s plot for every curve, over the plot’s own styles, e.g. lw=2.

Returns:

The figure.

Return type:

matplotlib.figure.Figure

plot_contributions(coronagraphs=None, input=True, axis=None, path=None, show=True, dpi=None, **kwargs)[source]#

Each component’s share of the image, pixel by pixel: before and after each coronagraph.

Rows: the input (input=True) and each coronagraph; columns: each component’s fraction of that row’s total image (see contributions; one colour scale, 0 to 1), titled with its share of the row’s light, and a last panel colouring each pixel by the component that dominates it. Point sources have no input image: their input panel is blank, with their position.

Parameters:

coronagraphs (str or list) – The coronagraphs shown; None: all.
input (bool) – Show the input row.
axis (str) – Axis unit (see Grid.axis); None: [display] axis.
path (str) – Save the figure there; None: not saved.
show (bool) – Show the figure (else it is closed).
dpi (int) – Resolution of the saved file; None: [display] dpi.
**kwargs – Passed to matplotlib’s imshow for every share map, e.g. cmap=”magma”.

Returns:

The figure.

Return type:

matplotlib.figure.Figure

plot_compare(first, second, component=None, unit=None, log=None, axis=None, path=None, show=True, dpi=None, log_range=None, star_flux=None, **kwargs)[source]#

Compare two coronagraphs (two sets of PSFs) on the same image.

Panels: each one’s final image (one colour scale); their relative difference, (second - first) / first, where the first is within log_range decades of its peak (elsewhere grey), titled with its median and 99th percentile in absolute value; and the azimuthal means of the input and of both final images.

Parameters:

first (str) – Coronagraph names.
second (str) – Coronagraph names.
component (str) – Component name; None: the total.
unit (str) – Output unit (see in_unit); “auto”: self.unit. None here and below: the [display] setting.
log (bool) – Log colour scale and log-log profiles.
axis (str) – Axis / distance unit (see Grid.axis).
path (str) – Save the figure there; None: not saved.
show (bool) – Show the figure (else it is closed).
dpi (int) – Resolution of the saved file.
log_range (float) – Decades shown below the top of the colour scale, and kept in the difference.
star_flux (float or Star) – See in_unit.
**kwargs – Passed to matplotlib’s imshow for the two final images, e.g. cmap=”magma”.

Returns:

The figure.

Return type:

matplotlib.figure.Figure

save(folder=None, overwrite=None)[source]#

Save to a run folder (needs self.params).

Files written in the folder:

params_used.toml: the parameters used (Params.used_toml, with the coronagraphs and [method] settings).
scene.fits: the inputs (see scene.write_scene; primary header also STARFLUX in Jy, 0 if
    unknown, and PARHASH), and a POINTS binary table of the point sources (NAME, RADIUS
    arcsec, ANGLE rad, FLUX per pixel area in self.unit) if there are any.
<coronagraph>.fits: one per coronagraph; primary header CORONAG, OPTICS and the optics
    parameters (keywords cut to 8 characters, lists such as the wavelengths as comma-separated
    text), COMBINE, BUNIT, STARFLUX, PEAKNORM (peak_norms; 0 if unknown), IWA (arcsec, iwa(); 0: none),
    PARHASH (first 16 hex characters of the SHA-1 of params_used.toml); then FINAL_TOTAL (the sum of the others) and FINAL_<COMPONENT> images
    (with METHOD, MODE, ERRTYP and WHY, cut to 68 characters); with combine = "together", the
    final image of the summed images (component "total") is TOGETHER (TOGETHER_EXTENSION).
quicklook/finals.png (see plot), and quicklook/contributions.png when there are several
    components (see plot_contributions).

Parameters:

folder (str) – The run folder; None: [run] output_dir / [run] name (“auto”: the parameter file’s name, else “scene”).
overwrite (bool) – Write into an existing folder; else the new one gets _2, _3, …; None: [run] overwrite.

Returns:

The folder written (also self.folder).

Return type:

str

classmethod load(folder)[source]#

A saved result (for plots, contributions, other units), without computing anything again.

Reads scene.fits, params_used.toml and every other .fits file of the folder (one per coronagraph). Component names come back in lower case (from the FITS extension names; TOGETHER of a combine = “together” run is “total”); coronagraphs stays empty and tables / method_used are not restored.

Parameters:: folder (str) – A run folder written by save().
Returns:: The result; None if the folder has no coronagraph FITS file.
Return type:: Result or None