Settings Tree

class oskar.SettingsTree(app=None, settings_file='')

This class provides a Python interface to the OSKAR settings tree.

The oskar.SettingsTree class holds parameters used to set up other OSKAR Python classes, and is the recommended way of setting up oskar.Interferometer and oskar.Imager. It is analogous to the settings files required to run the corresponding OSKAR application binaries, and offers a convenient Python interface. The constructor requires the name of an OSKAR application binary so that it can validate the settings keys, and an exception will be raised if a key is not known.

The complete list of settings keys used by OSKAR applications is available in the settings file documentation and these can also be viewed in the OSKAR GUI.

After creating an instance of oskar.SettingsTree, it can be used much like a standard Python dictionary: data access is provided using the square-bracket [] dereference operator using the key name, and values can be assigned or read from this. Note that all parameter values are stored as strings, and will be converted using Python’s str() function as needed.

Use the from_dict() and to_dict() methods to convert between a Python dictionary and a oskar.SettingsTree if required.

Examples

To set a parameter value:

settings = oskar.SettingsTree('oskar_sim_interferometer')
settings['observation/start_frequency_hz'] = 100e6

To create a oskar.SettingsTree from a Python dictionary (note that keys can be either flat or nested: for a flat dictionary, each key must be the fully-qualified name, whereas nested keys are automatically prefixed by their parent names):

settings = oskar.SettingsTree('oskar_sim_interferometer')
python_dict = {
    'simulator': {
        'double_precision': 'true',
        'use_gpus': 'true',
        'max_sources_per_chunk': 23000
    },
    'observation' : {
        'length': 14400.0,
        'start_frequency_hz': 132e6,
        'frequency_inc_hz': 100e3,
        'num_channels': 160,
        'num_time_steps': 240
    },
    'telescope': {
        'input_directory': '/path/to/telescope/model',
        'pol_mode': 'Scalar'
    },
    'interferometer': {
        'channel_bandwidth_hz': 100e3,
        'time_average_sec': 1.0,
        'max_time_samples_per_block': 4
    }
}
settings.from_dict(python_dict)

To get all current parameters (including default values) as a Python dictionary:

settings = oskar.SettingsTree('oskar_sim_interferometer')
python_dict = settings.to_dict(include_defaults=True)

__init__(app=None, settings_file='')

Constructs a settings tree, optionally for the given application.

If loading a settings file, the application name must also be specified.

Parameters:

• app (Optional[str]) – Name of the OSKAR application.
• settings_file (Optional[str]) – Path of the settings file to load.

from_dict(dictionary)

Sets the current settings from a Python dictionary.

Parameters:dictionary (dict) – Dictionary containing key-value pairs to set.

set_value(key, value, write=True)

Sets the value of the setting with the given key.

Parameters:

• key (str) – Settings key.
• value (str) – Settings value.
• write (boolean) – If true, also write the value to the file. Default True.

to_dict(include_defaults=False)

Returns a Python dictionary containing the current settings.

Parameters:include_defaults (boolean) – If true, also return default values. Returns:Dictionary of key, value pairs. Return type:dict

value(key)

Returns the value of the setting with the given key.

Parameters:key (str) – Settings key. Returns:Value of the setting with the given key. Return type:str

__getitem__(key)

Returns the value of the setting with the given key.

Parameters:key (str) – Settings key. Returns:Value of the setting with the given key. Return type:str

__setitem__(key, value)

Sets the value of the setting with the given key.

Parameters:

• key (str) – Settings key.
• value (str) – Settings value.