resins.instrument

The main entry-point to the library - contains the Instrument class used for managing all data and computing resolution functions.

Bases: object

Instrument is a representation of a physical INS instrument, containing all its associated data.

To be precise, it holds all information about one version of an instrument (for more about instrument versions, see Instruments), which makes it the centrepiece of this library; the data is necessary for computing the resolution functions.

However, this information is static and curated by the library, which is why Instrument is a frozen data class. It should never be instantiated directly; instead the from_default constructor should be used. Similarly, it should not be inspected directly; a variety of methods and properties are provided for querying relevant information.

Regardless, the most important function of Instrument is to construct a resolution function, which can be done by using the get_resolution_function method.

Parameters:

name: The name of the INS instrument.
version: The name of a particular version of that INS instrument.
_models: A dictionary detailing all the models and their data available for this version of this instrument.
default_model: The default model for this version of this instrument.

Attributes:

name: The name of the INS instrument represented by this instance.
version: The version of the INS instrument represented by this instance.
default_model: The name of the model for this version of this INS instrument that is used by default.
available_models: A list of models available for this version of this instrument.
available_models_and_configurations
all_available_models_options

Methods

`available_instruments`()	Lists all INS instruments currently available.
`available_versions`(instrument_name)	Lists the names of all versions available for an INS instrument, as well as the default version.
`default_option_for_configuration`(model_name, ...)	Returns the default option for the `configuration` configuration of the `model_name` model of this instrument.
`format_available_models_and_configurations`()	Formats all available models and configurations into a table.
`format_available_models_options`()	Formats all available models, configurations, and options into a table.
`from_default`(name[, version])	Instantiates an `Instrument` class with the data of the `name` INS instrument and its `version`.
`from_file`(path[, version])	Instantiates an `Instrument` from the data loaded from the file found at `path`.
`get_model_data`([model_name])	Retrieves the physical parameters associated with the specified `model_name`.
`get_model_signature`([model_name])	Constructs a call signature for the `get_resolution_function` method with a specific model.
`get_resolution_function`([model_name])	Generates a resolution function, as modelled by the `model_name` model.
`possible_configurations_for_model`(model_name)	Returns all the configurations that the `model_name` model supports.
`possible_options_for_model`(model_name)	Returns a dictionary mapping all the configurations of the `model_name` model to their options.
`possible_options_for_model_and_configuration`(...)	Lists each option that can be chosen for a given configuration of the `model_name` model.

property all_available_models: list[str]

A list of all models available for this version of this instrument.

Includes both all the versions of all models (see Instrument.available_unique_models and the recommended versions (see Instrument.available_models).

Returns:

available_models: A list of all available models.

classmethod available_instruments() → list[str]

Lists all INS instruments currently available.

Returns:

instrument_list: A list of names of INS instruments supported by this library.

property available_models: list[str]

A list of models available for this version of this instrument.

Only includes the recommended version of each model - does not list all versions of all models.

Returns:

available_models: A list of available models.

property available_unique_models: list[str]

A list of all unique models available for this version of this instrument.

Only includes the versioned models, i.e. lists all versions of all models, but does not list the recommended models.

Returns:

available_models: A list of all available unique models.

classmethod available_versions(instrument_name: str) → tuple[list[str], str]

Lists the names of all versions available for an INS instrument, as well as the default version.

Parameters:

instrument_name: The name of the INS instrument whose versions to retrieve.

Returns:

available_versions: A list of the version names available for the instrument.
default_version: The version of the instrument that is used by default.

Warning

This method performs an I/O (read) operation.

See also

available_instruments: Lists the available instruments

default_option_for_configuration(model_name: str, configuration: str) → str

Returns the default option for the configuration configuration of the model_name model of this instrument.

Parameters:

model_name: The name of the model whose configuration to look up.
configuration: The name of the configuration whose default option to retrieve.

Returns:

default_option: The default option for the configuration configuration.

Raises:

InvalidModelError: If the provided model_name is not supported for this version of this instrument.
InvalidConfigurationError: If the provided configuration is not supported for the model_name model of this instrument.

format_available_models_and_configurations() → str

Formats all available models and configurations into a table.

The table shows each model and either which other model it is an alias for, or all the configurations required by that model.

Returns:

str: A string containing the nicely formatted table.

format_available_models_options() → str

Formats all available models, configurations, and options into a table.

The table shows each model and either which other model it is an alias for, or all the configurations required by that model. In the latter case, all the options for each configuration are also listed, and the default option is indicated.

Returns:

str: A string containing the nicely formatted table.

classmethod from_default(name: str, version: str | None = None) → Instrument

Instantiates an Instrument class with the data of the name INS instrument and its version.

This is the primary, recommended way of instantiating the Instrument class. It loads the instrument data as curated in this library for a particular version of an INS instrument.

Parameters:

name: The name of the INS instrument to instantiate.
version: The version of the name INS instrument to instantiate. If not provided, the default version of that instrument is instantiated.

Returns:

instrument: An instance of the Instrument class containing the data corresponding to name and version.

Raises:

InvalidInstrumentError: If the specified instrument name does not exist.
InvalidVersionError: If the specified version is not available for the specified instrument name.

See also

available_instruments: Lists the available instruments
available_versions: Lists the available versions of an instrument and its default version.

classmethod from_file(path: str, version: str | None = None) → Instrument

Instantiates an Instrument from the data loaded from the file found at path.

Please note that while this method is a part of the public API, it is marked as being for advanced use only. For most use cases, use the from_default method.

This method assumes that the data in the file follows the standard (please see … for more details). No validation is performed, so if there are any issues, either unhandled exceptions will be raised, or the errors will be silently propagated. For adding new instruments, versions, or models, please open an issue on our GitHub. For other purposes, please see … .

While the data file may contain multiple versions, only the one specified by version will be saved in memory. If the version parameter is not provided, the default version is read from the file.

Parameters:

path: The path to the file containing the instrument data.
version: The version of the instrument to load. If not provided, the default_version specified in the file will be used.

Returns:

instrument: An instance of the Instrument class containing the data found at path

Raises:

InvalidVersionError: If the file does not contain the provided version.
KeyError: If certain parts of the file are egregiously incorrect.

get_model_data(model_name: str | None = None, **kwargs) → ModelData

Retrieves the physical parameters associated with the specified model_name.

This method can be used for inspecting the parameters of a particular model, though it cannot be used to modify them. It returns a subclass of the ModelData class corresponding to the particular model.

Another use for this method is to inspect the default values for the model’s settings, as well as any restrictions that they might have, via the defaults and restrictions attributes.

Parameters:

model_name: The name of the model whose parameters to retrieve. If not provided, the parameters of the default_model will be retrieved.
**kwargs: Keyword arguments can be passed in to choose an option for each configuration specific to the model_name. If not provided, default values are used. These are mainly useful when checking the instrument parameters, but for some models, the options may also affect the defaults and restrictions.

Returns:

model_data: The data associated with model_name.

See also

default_model: The default model for this instrument.
available_models: List of models available for this instrument
possible_configurations_for_model: List of configurations that can be chosen for this model

get_model_signature(model_name: str | None = None) → Signature

Constructs a call signature for the get_resolution_function method with a specific model.

This method provides a programmatic way of inspecting the call signature of the get_resolution_function method required when calling it for the model_name model. This is useful because its default signature uses the **kwargs construct to provide a unified interface, but in fact different models require different sets of values that have to be passed in through the keyword arguments.

There are other methods and properties that can be used to inspect some of the options, but this method retrieves all the information and returns it as an inspect.Signature object that can be used to examine the signature in detail. The only other comprehensive source of this information is the documentation for the relevant model.

Parameters:

model_name: The name of the model whose signature to construct. If not provided, the signature of the default_model is constructed.

Returns:

signature: The call signature of the get_resolution_method for the model_name model.

Raises:

InvalidModelError: If the provided model_name is not available for this version of this instrument.

See also

available_models: List of models available for this version of this instrument.
get_model_data: Allows for checking the default values of and restrictions on model settings.
possible_options_for_model: Lists the configurations and their options for a model.

Examples

>>> maps = Instrument.from_default('MAPS')
>>> sig = maps.get_model_signature()
>>> sig
<Signature (model_name: Optional[str] = 'PyChop_fit', *, chopper_package: Literal['A', 'B', 'S'] = 'A', e_init: Annotated[ForwardRef('Optional[float]'), 'restriction=[0, 2000]'] = 500, chopper_frequency: Annotated[ForwardRef('Optional[int]'), 'restriction=[50, 601, 50]'] = 400, fitting_order: 'int' = 4, _) -> resins.models.pychop.PyChopModelFermi>
>>> sig.parameters['e_init']
<Parameter "e_init: Annotated[ForwardRef('Optional[float]'), 'restriction=[0, 2000]'] = 500">
>>> sig.parameters['e_init'].kind
<_ParameterKind.KEYWORD_ONLY: 3>

The inspect.Signature object provides easy inspection of a call signature.

get_resolution_function(model_name: str | None = None, **kwargs) → InstrumentModel

Generates a resolution function, as modelled by the model_name model.

This method is the main use case of the Instrument class. It generates a callable object that, when called, returns the resolution of the instrument at an energy and/or momentum value(s).

However, while a simple, common interface is provided, different models (and sometimes the same model for different instruments!) require different configurations to be selected and different settings to be provided. All of these have to be passed in as keyword arguments (though sensible defaults are provided). These keyword arguments correspond to physical user choices made when running an INS experiment on the corresponding instrument. For example, direct instruments have a tunable incident energy, so their models usually require an e_init setting.

For more information about a model, please see its corresponding documentation, or for programmatic querying, please see “How to programmatically query model”.

Parameters:

model_name: The name of the model to instantiate. If not provided, the Instrument.default_model is used.
**kwargs: Keyword arguments specifying the various configurations and settings of the model_name model

Returns:

model: An instance of the requested model_name model.

Raises:

InvalidModelError: If the provided model_name is not available for this version of this instrument.
InvalidInputError: If the model has restrictions on its inputs and these have been violated. The restrictions can be checked by using the get_model_data method and then viewing the restrictions attribute of the returned object.
Exception: Other model-specific exceptions may be raised.

Warning

If there are any mistakes in the model-specific parameters passed in as keyword arguments, they will be silently ignored and the default values for the missing parameters will be used.

See also

available_models: List of models available for this version of this instrument
get_model_signature: Constructs a call signature for calling this method for a particular model.

Examples

>>> from resins import Instrument
>>> tosca = Instrument.from_default('TOSCA', 'TOSCA')
>>> print(tosca.get_resolution_function())
PolynomialModel1D(citation="")

If a model is not provided, the default model will be used - this differs between versions and instruments.

>>> print(tosca.get_resolution_function('vision'))
VisionPaperModel(citation="https://doi.org/10.1016/j.nima.2009.03.204")

possible_configurations_for_model(model_name: str) → list[str]

Returns all the configurations that the model_name model supports.

Parameters:

model_name: The name of the model whose configurations to retrieve.

Returns:

configurations: A list of configurations available for the model_name model.

Raises:

InvalidModelError: If the provided model_name is not supported for this version of this instrument.

possible_options_for_model(model_name: str) → dict[str, list[str]]

Returns a dictionary mapping all the configurations of the model_name model to their options.

Parameters:

model_name: The name of the model whose configurations to retrieve.

Returns:

configurations_and_options: All the configurations available for the model_name model and all their possible options.

Raises:

InvalidModelError: If the provided model_name is not supported for this version of this instrument.

possible_options_for_model_and_configuration(model_name: str, configuration: str) → list[str]

Lists each option that can be chosen for a given configuration of the model_name model.

Parameters:

model_name: The name of the model to which the configuration belongs.
configuration: The name of the configuration whose options to retrieve.

Returns:

options: A list of options available for the configuration and model_name.

Raises:

InvalidModelError: If the provided model_name is not supported for this version of this instrument.
InvalidConfigurationError: If the provided configuration is not supported for the model_name model of this instrument.

exception resins.instrument.InvalidConfigurationError(provided_name: str, model_name: str, instrument: Instrument)

Bases: Exception

An Exception representing an invalid user input for the configuration of a model of an instrument.

This class does not support an arbitrary message; instead the message is constructed in here from the provided information.

Parameters:

provided_name: The invalid name for the configuration that the user provided.
model_name: The name of the model for which the provided_name was provided.
instrument: The instance of the Instrument object in which the provided_name was used.

exception resins.instrument.InvalidInstrumentError

Bases: Exception

An Exception representing an invalid user input for the instrument name.

exception resins.instrument.InvalidModelError(provided_name: str, instrument: Instrument)

Bases: Exception

An Exception representing an invalid user input for the model of an instrument.

This class does not support an arbitrary message; instead the message is constructed in here from the provided information.

Parameters:

provided_name: The invalid name for the model that the user provided.
instrument: The instance of the Instrument object in which the provided_name was used.

exception resins.instrument.InvalidVersionError

Bases: Exception

An Exception representing an invalid user input for the version of an instrument.

resins.instrument.INSTRUMENT_MAP: dict[str, tuple[str, None | str]]

A mapping of the name of an instrument to its data file and the version it’s aliasing, for all available instruments.

Has the form {'instrument_name': ('file_name.yaml', alias_for)} where instrument_name is the public, official name of the instrument that is used when creating it, file_name.yaml is the name of the YAML data file containing the data for that instrument (without the full path), and alias_for is either

a str containing the name of a version in that file; or
- In this case, when instrument_name is accessed, the specified version is returned.
a None.
- In this case,when instrument_name is accessed, the default version is returned.