How To Programmatically Find Data

The instrument/model data used by ResINS is available in the documentation and comes packaged together with the library via the YAML files in resins/instrument_data. However, one may also obtain the data programmatically at runtime; this could be useful when accessing ResINS through other software to ensure the information is up-to-date with the code. This guide shows how to to this:

How To Find Data In Computer-compatible Format 

Most of the methods shown here return Python data objects such as lists, dictionaries, or strings. These are generally human-readable, but for some larger sets of data additional methods have been provided that format the information into nice-looking tables (see How To Find Data In Human-readable Format).

How To Find the Available Instruments 

The Instrument provides a method, available_instruments(), which lists all the available instruments:

>>> from resins import Instrument
>>> Instrument.available_instruments()
['ARCS', 'CNCS', 'HYSPEC', 'Lagrange', 'LET', 'MAPS', 'MARI', 'MERLIN', 'PANTHER', 'TFXA', 'TOSCA', 'VISION', 'SEQUOIA', 'TOSCA1']

Advanced 

An advanced way of interacting with available instruments is to access the INSTRUMENT_MAP dictionary directly:

>>> from resins.instrument import INSTRUMENT_MAP
>>> INSTRUMENT_MAP
{'ARCS': ('arcs.yaml', None), 'CNCS': ('cncs.yaml', None), 'HYSPEC': ('hyspec.yaml', None), 'Lagrange': ('lagrange.yaml', None), 'LET': ('let.yaml', None), 'MAPS': ('maps.yaml', None), 'MARI': ('mari.yaml', None), 'MERLIN': ('merlin.yaml', None), 'PANTHER': ('panther.yaml', None), 'TFXA': ('tosca.yaml', 'TFXA'), 'TOSCA': ('tosca.yaml', None), 'VISION': ('vision.yaml', None), 'SEQUOIA': ('sequoia.yaml', None), 'TOSCA1': ('tosca.yaml', 'TOSCA1')}

which maps the user-input instrument name to the instrument data file and version name. There should be no reason to access this object for normal use.

How To Find the Versions Available for an Instrument 

Once again, the Instrument provides a method, available_versions(), which lists all the versions available for an instruments:

>>> from resins import Instrument
>>> available_versions, default_version = Instrument.available_versions('TOSCA')
>>> available_versions
['TFXA', 'TOSCA1', 'TOSCA']
>>> default_version
'TOSCA'

This method returns both the list of versions available for the instrument, and the default version for that instrument. If the instrument being searched for is an alias for a particular version of an instrument, that version is returned instead of the default version:

>>> available_versions, default_version = Instrument.available_versions('TFXA')
>>> available_versions
['TFXA', 'TOSCA1', 'TOSCA']
>>> default_version
'TFXA'

How To Find the Models Available for an Instrument 

Given an instrument and its version, it is possible to query the list of available models by using the available_models() property:

>>> from resins import Instrument
>>> tosca = Instrument.from_default('TOSCA', 'TOSCA')
>>> tosca.available_models
['AbINS', 'book', 'vision']

The default model can similarly be accessed via an attribute:

>>> tosca.default_model
'AbINS'

Advanced 

The above property returns only the recommended (usually latest) version of each model. These “models” are actually aliases that each point to a versioned model which holds the data. These versioned models can be listed by using available_unique_models():

>>> tosca.available_unique_models
['AbINS_v1', 'book_v1', 'vision_v1']

Then, to round out the options, all models can be listed via all_available_models():

>>> tosca.all_available_models
['AbINS', 'AbINS_v1', 'book', 'book_v1', 'vision', 'vision_v1']

Important

Older versions of models may contain known bugs and/or inaccuracies - use at own risk.

How To Find the Configurations that Must be Chosen for a Model 

The configurations required by a given model can be retrieved using the possible_configurations_for_model() method:

>>> from resins import Instrument
>>> tosca = Instrument.from_default('TOSCA', 'TOSCA')
>>> tosca.possible_configurations_for_model('AbINS')
[]
>>> tosca.possible_configurations_for_model('book')
['detector_bank']

How To Find the Options Available for a Configuration 

To obtain the options as Python data, the model must already be known. (Humans can read the formatted table from otherwise.)

If the model and setting are known 

To list the possible options for a given configuration (how to find configurations) of a given model (how to find models), the possible_options_for_model_and_configuration() method is provided:

>>> from resins import Instrument
>>> tosca = Instrument.from_default('TOSCA', 'TOSCA')
>>> tosca.possible_options_for_model_and_configuration('book', 'detector_bank')
['Backward', 'Forward']

If only the model is known 

To list all the options for all configurations of a given model (how to find models), the possible_options_for_model() method is provided:

>>> from resins import Instrument
>>> tosca = Instrument.from_default('TOSCA', 'TOSCA')
>>> tosca.possible_options_for_model('book')
{'detector_bank': ['Backward', 'Forward']}

How To Find the Default Option for a Configuration 

Given the model name (how to find models) and the configuration (how to find configurations), the default option can be retrieved using the default_option_for_configuration() method:

>>> from resins import Instrument
>>> tosca = Instrument.from_default('TOSCA', 'TOSCA')
>>> tosca.default_option_for_configuration('book', 'detector_bank')
'Backward'

How To Find the Default Values for a Setting 

The default values for all settings associated with a model can be found using the default attribute of the model, which can be retrieved using the get_model_data() method:

>>> from resins import Instrument
>>> merlin = Instrument.from_default('MERLIN', 'MERLIN')
>>> model = merlin.get_model_data('PyChop_fit')
>>> type(model)
<class 'resins.models.pychop.PyChopModelDataFermi'>
>>> model.defaults
{'e_init': 400, 'chopper_frequency': 400}

Warning

For some models, the configurations may affect the default values of the settings.

How To Find the Restrictions on the Values of a Setting 

The restrictions on the values for all settings associated with a model can be found using the restrictions attribute of the model, which can be retrieved using the get_model_data() method:

>>> from resins import Instrument
>>> merlin = Instrument.from_default('MERLIN', 'MERLIN')
>>> model = merlin.get_model_data('PyChop_fit')
>>> type(model)
<class 'resins.models.pychop.PyChopModelDataFermi'>
>>> model.restrictions
{'chopper_frequency': [50, 601, 50], 'e_init': [0, 181]}

Warning

For some models, the configurations may affect the restrictions on the settings:

>>> model = merlin.get_model_data('PyChop_fit', chopper_package='S')
>>> type(model)
<class 'resins.models.pychop.PyChopModelDataFermi'>
>>> model.restrictions
{'chopper_frequency': [50, 601, 50], 'e_init': [7, 2000]}

How To Find Data In Human-readable Format 

Unlike the cases above, in some cases it might be more desirable to obtain comprehensive information in an easily legible format. The following are provided for that purpose:

How To Find the Models and Their Configurations 

All configurations for all the models can be displayed via the format_available_models_and_configurations() method:

>>> from resins import Instrument
>>> tosca = Instrument.from_default('TOSCA', 'TOSCA')
>>> print(tosca.format_available_models_and_configurations())
|--------------|--------------|-------------------|
| MODEL        | ALIAS FOR    | CONFIGURATIONS    |
|==============|==============|===================|
| AbINS        | AbINS_v1     |                   |
|--------------|--------------|-------------------|
| AbINS_v1     |              |                   |
|--------------|--------------|-------------------|
| book         | book_v1      |                   |
|--------------|--------------|-------------------|
| book_v1      |              | detector_bank     |
|--------------|--------------|-------------------|
| vision       | vision_v1    |                   |
|--------------|--------------|-------------------|
| vision_v1    |              | detector_bank     |
|--------------|--------------|-------------------|

How To Find the Models and Their Configurations and Their Options 

All the options for all the configurations of all models can be listed by the all_available_models_options() method:

>>> from resins import Instrument
>>> tosca = Instrument.from_default('TOSCA', 'TOSCA')
>>> print(tosca.format_available_models_options())
|--------------|--------------|-------------------|-----------------------|
| MODEL        | ALIAS FOR    | CONFIGURATIONS    | OPTIONS               |
|==============|==============|===================|=======================|
| AbINS        | AbINS_v1     |                   |                       |
|--------------|--------------|-------------------|-----------------------|
| AbINS_v1     |              |                   |                       |
|--------------|--------------|-------------------|-----------------------|
| book         | book_v1      |                   |                       |
|--------------|--------------|-------------------|-----------------------|
| book_v1      |              | detector_bank     | Backward (default)    |
|              |              |                   | Forward               |
|--------------|--------------|-------------------|-----------------------|
| vision       | vision_v1    |                   |                       |
|--------------|--------------|-------------------|-----------------------|
| vision_v1    |              | detector_bank     | Backward (default)    |
|              |              |                   | Forward               |
|--------------|--------------|-------------------|-----------------------|