Source modules#

Source modules: each input of a scene (an image, an MCFOST model, a stellar wind, a CME, planets, or your own module) is one class following the Source interface.

A module declares, as class attributes:

kind      the name used in the parameter file ([[source]] kind = "...")
doc       one line describing it
family    "physical" (e.g. Jy/arcsec^2), "relative" (contrast: a fraction of the star's
          flux) or None (decided by the input, e.g. a FITS file's BUNIT)
params    its own parameters (toycoronagraph.params.Param); shared quantities such as
          the star's distance are never repeated here, they are listed in `requires`
requires  the shared quantities it needs, e.g. ("star.distance", "star.radius")
provides  the shared quantities it can supply, e.g. ("grid.pixel_scale",) from a header

and implements render(grid, star), returning its image centred on the star (pixel (N-1)/2 of the grid, or of its own grid with pixel_scale set); a module that wraps another code makes sure of this itself. Register a module with @register_source; a module outside the package is found from the parameter file’s module = "my_package.my_module" (imported, which registers it). tests/extra_sources.py (CmeBlob) is a documented example.

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

Bases: object

Base class of the source modules (see the module docstring).

Variables:

  • kind (str) – name in parameter files; must be set by every registered subclass.

  • doc (str) – one-line description.

  • family (str) – “physical”, “relative”, or None when the input decides.

  • params (tuple of Param) – the module’s own parameters.

  • requires (tuple of str) – shared quantities it needs, e.g. “star.distance”.

  • provides (tuple of str) – shared quantities it can supply (reported by inspect()).

  • settings (dict) – {param name: value} of every parameter, defaults filled in (set by __init__).

Check and store the module’s own parameters.

Parameters:

**settings – {param name: value}; each is converted with toycoronagraph.params.convert (units in text, “auto”, choices…); parameters not given take their default.

Raises:

ParamError – unknown parameter names (with a suggestion) or invalid values, all listed.

missing()[source]#

Required parameters (no default) that are not set.

Returns:

empty when the module can be rendered.

Return type:

list of Param

family_of()[source]#

The family of this source’s images, given its settings.

Returns:

“physical”, “relative”, or None when only the input decides (e.g. a file’s BUNIT).

Return type:

str

inspect()[source]#

Shared quantities this source supplies (e.g. from a file header); see provides.

Returns:

[(key, value, origin)], e.g. (“grid.pixel_scale”, 0.01, “header PIXSCALE of x.fits”); empty by default.

Return type:

list of tuple

point_sources(grid, star)[source]#

Unresolved sources, for modules that are not images (render() is then not called).

Parameters:
Returns:

[((radius arcsec, angle rad), flux)], the flux in Jy (family “physical”) or as a fraction of the star’s flux (“relative”); None for image modules (default).

Return type:

list or None

render(grid, star)[source]#

The image(s) of this source; every image module overrides it.

Parameters:
Returns:

a units.SourceImage centred on the star, or {name: SourceImage} for several components.

Return type:

SourceImage or dict

Raises:

NotImplementedError – in the base class.

symmetric()[source]#

Whether the image is circularly symmetric, from the “symmetric” setting if the module has one.

Returns:

True / False if known (by construction or set by the user); None: measure it.

Return type:

bool or None

toycoronagraph.sources.register_source(cls)[source]#

Class decorator: make a Source subclass available under its kind.

Parameters:

cls (type) – the Source subclass; registering a kind again replaces the previous class.

Returns:

cls itself.

Return type:

type

Raises:

ValueError – no kind, or two parameters with the same name.

toycoronagraph.sources.get_source(kind, module=None)[source]#

The Source class of a kind.

Parameters:

  • kind (str) – the registered kind, e.g. “wind”.

  • module (str) – Python module to import first if the kind is not registered yet (importing it registers its classes); None = none.

Returns:

the Source subclass.

Return type:

type

Raises:

KeyError – the kind is still not registered.

toycoronagraph.sources.source_kinds()[source]#

All registered kinds.

Returns:

the built-in ones first (in the order of BUILTIN_KINDS), then yours (in registration order).

Return type:

list of str