How To Add a Version To an Instrument

ResINS strives to model all versions of any given INS instrument - old, new, and planned - but it is inevitable that some will not be natively supported yet. Fortunately, while not as straightforward as creating a new instrument, ResINS aims to make adding new versions as simple as possible:

How to add a version for personal use

Adding a version to an instrument only locally (without submitting to ResINS) is the more difficult task since ResINS does not have an extension/add-ons mechanism. Therefore, to create a version, it is necessary to resort to either creating an entire instrument or working with Python dictionaries instead of YAML files:

Using YAML files

It is currently impossible to dynamically append a new version to an existing instrument. It is necessary to create a new instrument YAML file into which the new version can be placed. This can be done in two ways:

  • Copy the YAML data file of the relevant instrument from ResINS

    • The ResINS data files can be found at resins/instrument_data

    • The file should be copied to a different location and the new path saved

  • Create a new YAML file (see How To Add an Instrument)

    • The top-level information can be the same as in the original instrument or it can be gibberish

Warning

While it is possible to add a new version by modifying the instrument’s YAML data file that comes with ResINS in-place (without copying), this file may be overwritten when updating ResINS with pip, resulting in data loss.

With an instrument file present, all that is required is to add the data for the new version to the the YAML file, which can be done by adding a new key to the version dictionary of the YAML file. The corresponding value to this key should be a dictionary containing the data for the version. See YAML Data File Specification for more information on how to structure the YAML data file. Then, ResINS can be leveraged to do the rest without additional code:

>>> from resins import Instrument
>>> new_instrument_path = '~/instrument/instrument.yaml'
>>> version = 'version'  # If the created YAML file contains multiple versions
>>> new_instrument = Instrument.from_file(new_instrument_path, version)
>>> new_instrument.name
'new_instrument'
>>> new_instrument.version
'version'

Given that the YAML file specifies a model already implemented in ResINS, and that its parameters have been all included, the resolution function can be computed:

>>> model = new_instrument.get_resolution_function('PyChop_fit', chopper_package='A', e_init=100, chopper_frequency=300)
>>> print(model)
PyChopModelFermi(citation=[''])

However, if a new model was created for the new instrument, more work will be required, see How To Add A New Model.

Using a dictionary

An Instrument can be constructed directly from a dictionary containing the data for a particular version. In this case, the process is identical to creating a new instrument using a dictionary.

How to add a version to ResINS

If you would like to contribute a new version to ResINS (which we do appreciate!), do open an issue on our GitHub so that we can help. Either way, the process to do so is similar to but simpler than creating a version using YAML files. The crux of the difference is that now there is no need to worry about creating files - all that is required is to edit the relevant instrument’s YAML file (found at resins/src/resins/instrument_data) in-place (of course working on a new branch of your own fork, see Contributing Guidelines). The data will have to be correctly formatted according to the spec by adding a new entry to the version dictionary with a unique (version) name and the correct data.

There is no need to edit any Python code.