scopesim.commands.user_commands module

Contains the UserCommands class and some helper functions.

class scopesim.commands.user_commands.UserCommands(*maps, **kwargs)[source]

Bases: NestedChainMap

Contains all the setting a user may wish to alter for an optical train.

Most of the important settings are kept in the internal nested dictionary. Setting can be accessed by using the alias names. Currently these are:

  • ATMO: atmospheric and observatory location settings

  • TEL: telescope related settings

  • RO: relay optics settings, i.e. between telescope and instrument

  • INST: instrument optics settings

  • DET: detector settings

  • OBS: observation settings, and

  • SIM: simulation settings

All of the settings are contained in a special SystemDict dictionary that allows the user to access all the settings via a bang-string (!). E.g:

cmds = UserCommands()
cmds["!SIM.file.local_packages_path]

Note

To use this format for accessing hierarchically-stored values, the bang string must always begin with a “!”

Alternatively the same value can be accessed via the normal dictionary format. E.g:

cmds["SIM"]["file"]["local_packages_path"]
Parameters:
use_instrumentstr, optional

The name of the main instrument to use

packageslist, optional

list of package names needed for the optical system, so that ScopeSim can find the relevant files. E.g. [“Armazones”, “ELT”, “MICADO”]

yamlslist, optional

list of yaml filenames that are needed for the combined optical system E.g. [“MICADO_Standalone_RO.yaml”, “MICADO_H4RG.yaml”, “MICADO_.yaml”]

mode_yamlslist of yamls, optional

list of yaml docs (“OBS” docs) that are applicable only to specific operational modes of the instrument. Further yaml files can be specified in the recursive doc entry: “yamls”

set_modeslist of strings, optional

A list of default mode yamls to load. E.g. [“SCAO”, “IMG_4mas”]

propertiesdict, optional

Any extra “OBS” properties that should be added

ignore_effectslist

Not yet implemented

add_effectslist

Not yet implemented

override_effect_valuesdict

Not yet implemented

Notes

Attention

We track your IP address when ScopeSim checks for updates

When initialising a UserCommands object via use_instrument=, ScopeSim checks on the database whether there are updates to the instrument package. Our server records the IP address of each query for out own statistics only.

WE DO NOT STORE OR TRACK PERSONAL DATA. THESE STATISTICS ARE NEEDED FOR GETTING MORE FUNDING TO CONTINUE DEVELOPING THIS PROJECT.

We are doing this solely as a way of showing the austrian funding agency that people are indeed using this software (or not). Your participation in this effort greatly helps our chances of securing the next grant.

However, if you would still like to avoid your IP address being stored, you can run scopesim 100% anonymously by setting:

>>> scopsim.rc.__config__["!SIM.reports.ip_tracking"] = True

at the beginning of each session. Alternatively you can also pass the same bang keyword when generating a UserCommand object:

>>> from scopesim import UserCommands
>>> UserCommands(use_instrument="MICADO",

… properties={“!SIM.reports.ip_tracking”: False})

If you use a custom yaml configuration file, you can also add this keyword to the properties section of the yaml file.

Changed in version v0.8.0.

This now inherits from (a subclass of) collections.ChainMap.

Examples

Here we use a combination of the main parameters: packages, yamls, and properties. When not using the use_instrument key, packages and yamls must be specified, otherwise scopesim will not know where to look for yaml files (only relevant if reading in yaml files):

>>> from scopesim.server.database import download_package
>>> from scopesim.commands import UserCommands
>>>
>>> download_package("test_package")
>>> cmd = UserCommands(packages=["test_package"],

… yamls=[“test_telescope.yaml”, … {“alias”: “ATMO”, … “properties”: {“pwv”: 9001}}], … properties={“!ATMO.pwv”: 8999})

Attributes:
cmdsRecursiveNestedMapping

Built from the properties dictionary of a yaml dictionary. All values here are accessible globally by all Effects objects in an OpticalTrain once the UserCommands has been passed to the OpticalTrain.

yaml_dictslist of dicts

Where all the effects dictionaries are stored

list_modes() → Iterable[tuple[str, ...]][source]

Yield tuples of length >= 2 with mode names and descriptions.

Changed in version v0.8.0.

This used to return the formatted string. For a broader range of use cases, it now returns a generator of tuples of strings.

property modes: None

Print all modes, if any.

set_modes(*modes) → None[source]

Reload with the specified modes.

Changed in version v0.8.0.

This used to take a single list-like argument, now used a “*args” approach to deal with multiple modes.

update(other=None, /, **kwargs)[source]

Update the current parameters with a yaml dictionary.

See the UserCommands main docstring for acceptable kwargs

static update_alias(mapping: MutableMapping, new_dict: Mapping) → None[source]

Update a dict-like according to the alias-properties syntax.

This used to be part of astar_utils.NestedMapping, but is specific to ScopeSim and thus belongs somewhere here. It should only be used in the context of YAML-dicts loaded by UserCommands, hence it was put here.