Target parameters#

Parameters of Target (one image through one coronagraph), read from toycoronagraph_para.toml.

This is the parameter reader of the older, flat configuration used by Target (main.py); the scene framework (toycoronagraph.observe) uses toycoronagraph.params directly.

Two layouts are read:

* the scene layout of toycoronagraph.params ([observation], [grid], [star], [[source]],
  [[coronagraph]], ...): checked there, then mapped onto the flat configuration below
  (one image source; the first coronagraph);
* the older layout ([target], [telescope], [coronagraph], [method], [compute]) in SCHEMA;
  its [coronagraph] type is "vortex" or "lazuli". A lazuli [coronagraph] has the keys of the
  scene layout's "lazuli" type and is checked with its declarations
  (toycoronagraph.params.CORONAGRAPHS); its own keys (LAZULI_KEYS) are refused under a vortex.

Every key is optional. Keys set to “auto” are filled from the input image and its FITS header (resolve(), called by inputs.read_target). The values actually used are written to <parameter file>_used.toml (write_used); the parameter file itself is not modified unless [run] write_back = true. An old-style toycoronagraph_para.py is still read (with a notice) when no .toml file exists. If there is no parameter file at all, a minimal one is created (toycoronagraph.params_docs.new_config).

toycoronagraph.config.example_text()[source]#

The text of a commented example toycoronagraph_para.toml in the older layout (all defaults).

Returns:: The file content: a header with USAGE_NOTE, then every SCHEMA section and key with its default and description (the LAZULI_KEYS commented out: the type is “vortex”).
Return type:: str

toycoronagraph.config.write_example(path='toycoronagraph_para.toml')[source]#

Create an example parameter file in the older layout (example_text); overwrites path.

Parameters:: path (str) – The file to write.

toycoronagraph.config.from_dict(data, source='parameters')[source]#

Validate a parsed TOML dict and return the flat configuration (not yet resolved).

Parameters:

data (dict) – {section: {key: value}}; a [resolved] section is ignored.
source (str) – Name used in messages (the file path).

Returns:

every parameter, flat (the two symmetric keys become image_symmetric and psf_symmetric, [coronagraph] type becomes coronagraph_type, fits_filename “” becomes None, diameter is also stored as D). “auto” values stay “auto” until resolve(). Also has source (str) and legacy (False).

Return type:

SimpleNamespace

Raises:

ValueError – For an unknown section or key, a lazuli-only key (LAZULI_KEYS) under another type, a value that does not match SCHEMA (lazuli: the declarations of that type), a vortex charge that is not positive and even, a lazuli charge that is not even, or a lazuli throughput without one weight per wavelength.

toycoronagraph.config.resolve(cfg, image_shape, header=None)[source]#

Fill the “auto” parameters from the input image and its header, check the explicit ones against the header, and compute the derived quantities (psf_scale, F_transfer, psf_range, rot_number).

Sets (in cfg): target_pixel, wavelength (m), visual_range (lambda/D across the image), psf_scale (arcsec/pixel), F_transfer (factor from nu F_nu in W/m^2/pixel to F_nu in Jy/arcsec^2), psf_range (lambda/D, half of visual_range), input_unit, rot_number (target_pixel if <= 0), sources ({parameter: where its value came from}) and notes. For a legacy (.py) configuration, wavelength, visual_range, psf_scale, F_transfer and psf_range are kept as read.

Parameters:

cfg (SimpleNamespace) – From load_config / from_dict; modified in place.
image_shape (tuple) – Shape of the (sliced) input image; must be square and 2-D.
header – The image’s FITS header (a dict-like), or None.

Returns:

Messages: a summary of the input (where each value came from), then any mismatch (WARNING lines). Also stored as cfg.notes, with cfg.sources.

Return type:

list

Raises:

ValueError – If the image is not square and 2-D, target_pixel does not match it, or input_unit is “auto” and the header has no known BUNIT.

toycoronagraph.config.used_path(cfg)[source]#

Where the values used are saved: <parameter file name>_used.toml next to it.

Parameters:: cfg (SimpleNamespace) – A configuration (uses cfg.source).
Returns:: The path; “toycoronagraph_para_used.toml” when cfg.source is not a .toml or .py file.
Return type:: str

toycoronagraph.config.write_used(cfg)[source]#

Save the values used (after resolve()) to used_path(cfg); with write_back, also into the parameter file.

Parameters:: cfg (SimpleNamespace) – A resolved configuration; cfg.write_back (if present and true) also writes the [resolved] section into cfg.source.
Returns:: The path written (used_path(cfg)).
Return type:: str

toycoronagraph.config.write_resolved(cfg, path=None)[source]#

Write the values used (after resolve()) into a [resolved] section at the end of a .toml file, replacing the previous one; the rest of the file is kept as is.

Parameters:

cfg (SimpleNamespace) – A resolved configuration.
path (str) – The .toml file; default cfg.source (skipped if it is not a .toml file).

toycoronagraph.config.from_params(params)[source]#

The old flat configuration (toycoronagraph.config) for Target, from new-layout parameters.

Only files with exactly one enabled component, a fits_image or mcfost source, can be mapped; Target uses the first [[coronagraph]] (a note is added to params.notes when there are several).

Parameters:: params (toycoronagraph.params.Params) – Checked new-layout parameters (params.load).
Returns:: The configuration (see from_dict), with params (the Params object) and write_back ([run] write_back) added.
Return type:: SimpleNamespace
Raises:: ParamError – When the file needs the scene framework (not exactly one image source).

toycoronagraph.config.load_config(path=None, verbose=True)[source]#

Load the parameters (not yet resolved against the input image; see resolve()).

With no path: toycoronagraph_para.toml in the current directory; if it does not exist, an old toycoronagraph_para.py (with a notice); if neither exists, a minimal new-layout .toml is created (params_docs.new_config) and used.

Parameters:

path (str) – A .toml (or legacy .py) parameter file.
verbose (bool) – Print notices.

Returns:

The configuration (see from_dict; from_params for a new-layout file).

Return type:

SimpleNamespace