Options

Introduction

The AMUSE framework provides a generic way to handle optional attributes for any class. When an optional attribute is requested the class can read the value from an configuration file or return a default value when nothing is found in the file. The values for all options are stored in one configuration file.

Configuration file location

The AMUSE framework will search for the configuration file in following locations:

  1. First, the framework tries to find a file named amuserc in the current working directory

  2. Second, the framework tries to find a hidden file named .amuserc in the home directory.

  3. Last, the framework tries to find a file named amuserc in the amuse installation directory

When no file is found all options will refer to the default-values.

Configuration file format

The configuration file is formatted similar to Microsoft Windows INI files. The configuration file consists of sections, led by a [section] header and followed by name: value entries.

For example:

[channel]
redirection=none
debugger=xterm

Option values

Values for optional attributes are determined in four different ways:

  • the attribute is set on an instance of the object:

    channel.debugger = "ddd"
    
  • given when creating an object of the class:

    channel = MessageChannnel(debugger = "ddd")
    
  • given in the ini file:

    [channel]
    debugger = ddd
    
  • set as default value:

    @option
    def debugger(self):
        return "ddd"
    

Sections lookup

Options can be set in different sections. To determine the value of an option the framework first searches the sections of a class and then the sections of the option.

Use

class amuse.support.options.option(function=None, type='string', name=None, sections=(), choices=(), global_options=None)

Decorator to define an option

Parameters
  • type – Type of the value, used when reading from the configuration file. Can be “string”, “int”, “float” or “boolean”. Defaults to “string”

  • sections – Sections in the configuration file to search for the option value, must be an array of strings

  • choices – When given will check if the value of the option is in the array (must be a list or set of objects)

  • name – By default the name of the option in the configuration file is the same as the name of the function, use this argument to use a different name (not recommended)

Options can only be defined on subclasses of OptionalAttributes

class amuse.support.options.OptionalAttributes(**optional_keyword_arguments)

Abstract superclass for all classes supporting optional attributes.

To support optional attributes a class must inherit (directly or indirectly) from this class.

To support setting the attributes when an object is created the class must define a catch-all keyword argument in the __init__ function and send this argument to the __init__ of the superclass.

The values of options are first searched for in the sections given in the option_sections attribute of the class (empty by default). Next the sections of the option are searched.

For example:

class MyInterface(OptionalAttributes):
    option_sections = ('mysection',)

    def __init__(self, **options):
        OptionalAttributes.__init__(self, **options)

    @option(type="int", choices=(5,10,15), sections=('try',))
    def number_of_tries(self):
        "number of times to try to connect"
        return 5

To code will first search for the value of the option in the mysection, if no value is found the try section is searched. For the following configuration file the number_of_tries attribute will be 10 as the mysection section is searched first.

:: ini

[mysection] number_of_tries = 10 [try] number_of_tries = 5

The value of the option can be overriden by specifying it when creating an object of the class.

:: python

x = MyInterface(number_of_tries = 15) print x.number_of_tries 15