4. The Field Chooser

4.1. Introduction

The chooser is a sub-object of the Field object permitting to select or rather choose among the various solution data enumerators that may be present in the Model object's database. The chooser can be understood as a sequence of key-value pairs, with the keys being the Field enumerators, and the values being the selected enumerator values. It permits to select which field should be loaded.

The keys-value pairs are arranged in a sequence to represent a desired hierarchy (for instance, first the NAME, then the (load-)CASE, then the (computational-)CYCLE. This will allow to enumerate the different fields in that order. Usually, the default hierarchy is sufficient.

4.2. The Graphical User Interface

The chooser widget, which is found on the "Load" page of the Field editor is the graphical interface to the chooser sub-object.

The chooser widget allows for defining the enumerator hierarchy and for selecting enumerator values.

Depending on

  • The datasets present in the database,

  • The current settings for the Model object,

  • And the enumerator hierarchy,

the possible enumerator values are determined by the chooser. These values are available in the drop-down combo boxes. The chooser will always allow to select any of the currently possible enumerator values. However, it is not possible to select a non-existent enumerator value. Thus, the choice presented and allowed by the chooser will always be a valid one.

The display level can be set using the drop-down combo box at the upper right of the widget. There are the following display levels:

  • Level 1: Only display those enumerators that allow for choosing between multiple values. This level is the default.

  • Level 2: Additionally display those enumerators allowing for a single value which is not "None".

  • Level 3: Display all enumerators.

4.3. The Python Interface of the Field Chooser

We assume that the variable "f" references a Field object. To obtain the current hierarchy and enumerator values of the chooser sub-object, enter 

>>> f.ch
[('NAME', 'DISP'), ('COMPUTATION', None), ('CASE', 1), 
 ('CYCLE', 249), ('SUBCYCLE', None), ('MODE', None)]

or 

for item in f.ch:
    print item.name   # The enumerator name (key).
    print item.value  # The enumerator value.
    print item.names  # The list of possible names at this level.
    print item.values # The list of possible values.

Thus, the chooser consists of a sequence of so-called items. These items can be accessed

  • By index: 

    >>> print f.ch[3]
('CYCLE', 249)

    and 

    >>> for i in range(len(f.ch)):
...    print f.ch[i]
... 
('NAME', 'DISP')
('COMPUTATION', None)
('CASE', 1)
('CYCLE', 249)
('SUBCYCLE', None)
('MODE', None)

  • By name: 

    >>> print f.ch['CYCLE']
('CYCLE', 249)

On an item, the name and value can be changed:

  • Setting the value can be done: 

    >>> f.ch['CYCLE'].value = 100

    If the value of 100 is not a valid one, an exception will be raised.

    For enumerators known to baspl++, there is a shortcut: 

    >>> f.ch.cycle = 100

    To set an enumerator to the first valid value 

    >>> f.ch['CYCLE'].value = f.ch['CYCLE'].values[0]

    The "values" attribute is always non-empty. Again, this can be done more elegantly 

    >>> f.ch.cycle = f.ch.cycles[0]

    Likewise for the "CASE" enumerator: 

    >>> f.ch.case = f.ch.cases[0]

    To set an enumerator to the last valid value, use the index -1: 

    f.ch.cycle = f.ch.cycles[-1]

  • By setting the name, the hierarchy is changed: 

    >>> f.ch['CYCLE'].name = 'NAME'
>>> f.ch
[('CYCLE', None), ('COMPUTATION', None), ('CASE', None), ('NAME', 'ETAB'), 
('SUBCYCLE', None), ('MODE', None)]

    In this case, the enumerators "CYCLE" and "NAME" are exchanged with each other. When the hierarchy is changed, the enumerator values are re-set to the first valid choice. Hence, it is best to first define the hierarchy and then the enumerator values.

4.4. Re-Loading

When a change is made to the chooser, this change is by default not immediately reflected on the Field object's data (for performance reasons). It is thus possible to reset the chooser to the previously selected values by pressing the "Reset" button. To make the changes take effect, the "Apply" button in the chooser widget must be pressed, or in the Python environment, assuming that "f" references the field object, 

f.load()

has the same effect.

When stepping through the computational cycles, it is convenient to have the Field object re-loading automatically when the cycle changes. This can be achieved by ticking the Synchronized check box in the chooser widget. From the Python environment: 

f.ch.synchronized = True

The Field object will now be re-loaded automatically each time a value of the chooser's enumerators is changed, and it is no longer necessary to call the load() function.