diff --git a/src/resolution_functions/instrument.py b/src/resolution_functions/instrument.py index 6cb3ce6..2f68715 100644 --- a/src/resolution_functions/instrument.py +++ b/src/resolution_functions/instrument.py @@ -1,119 +1,6 @@ """ -This module is the main part of the library, containing the :py:cls:`Instrument` object, which is -used as a starting point for all functionality, as it represents a physical INS instrument and all -its data. To get started, you will need to know which instrument and which version of that -instrument you want to use (for more information about versions, please see :py:cls:`Instrument`), -all of which can be found in this documentation of programmatically: - -``` ->>> from resolution_functions import Instrument ->>> Instrument.available_instruments() -['ARCS', 'CNCS', 'HYSPEC', 'Lagrange', 'LET', 'MAPS', 'MARI', 'MERLIN', 'PANTHER', 'TFXA', 'TOSCA', 'VISION', 'SEQUOIA'] ->>> Instrument.available_versions('TOSCA') -['TFXA', 'TOSCA1', 'TOSCA'] -``` - -With this information, it is possible to instantiate the relevant instrument: - -``` ->>> tfxa = Instrument.from_default('TOSCA', 'TFXA') ->>> tfxa.name -'TOSCA' ->>> tfxa.version -'TFXA' ->>> tfxa.default_model -'book' -``` - -However, even if we don't know the exact version of an instrument to use, a reasonable default is -provided (usually the most recent version of that instrument): - -``` ->>> tosca = Instrument.from_default('TOSCA') ->>> tosca.name -'TOSCA' ->>> tosca.version -'TOSCA' ->>> tosca.default_model -'AbINS' -``` - -A lower level API is also provided for advanced use cases (see Advanced Useage). - -Once we have the instrument, the next step is to get a model of that instrument. Models describe the -widening (i.e. resolution) of a given instrument at different energy transfers - there are many -ways of modeling this behaviour, which is why most instruments have multiple models. For more -information see :py:mod:`models`. The important part here is that different models include different -levels of detail and so may require different information. If we know all the information for our -model (or wish to use the defaults), we can skip to getting the model, but there are programmatic -ways to query all the various information. - -All the things you will need to consider can be obtained in progressive levels by using the -properties: - -``` ->>> # Reveal all the models that we can use with the TOSCA instrument ->>> tosca.available_models -['AbINS', 'book', 'vision'] ->>> # Reveal all the models, and which parameters we will need to pass in to each one ->>> tosca.available_models_and_settings -{'AbINS': [], 'book': ['detector_bank'], 'vision': ['detector_bank']} ->>> # Reveal all the models, which parameters we will need to pass in to each one, and what the options are for each of the parameters ->>> tosca.all_available_models_options -{'AbINS': {}, 'book': {'detector_bank': ['Backward', 'Forward']}, 'vision': {'detector_bank': ['Backward', 'Forward']}} -``` - -It is also possible to make more precise queries: - -``` ->>> tosca.possible_settings_for_model('book') -['detector_bank'] ->>> tosca.possible_options_for_model('book') -{'detector_bank': ['Backward', 'Forward']} ->>> tosca.possible_options_for_model_and_setting('book', 'detector_bank') -['Backward', 'Forward'] ->>> tosca.default_option_for_setting('book', 'detector_bank') -'Backward' -``` - -However, the most comphrehensive way to prepare for getting a model, once we knowh which model we -want, is to get its signature: - -``` ->>> maps = Instrument.from_default('MAPS', 'MAPS') ->>> signature = maps.get_model_signature('PyChop_fit') ->>> signature - -``` - -This function returns a `inspect.Signature` object from the standard library, which can be further -queried and contains all the information required for getting the model. - -``` ->>> # For the MAPS instrument and its PyChop_fit model: ->>> # The first parameter, called model name, is a string with the name of the model. The default is 'PyChop_fit' ->>> signature.parameters['model_name'] - ->>> # The parameter chopper_package is one of the Fermi chopper options on the MAPS instrument. ->>> # It can be one of 'A', 'B', or 'S'. The default is 'A' ->>> signature.parameters['chopper_package'] - ->>> # The parameter e_init (initial energy) is a float with a default value of 500 meV and the ->>> # restriction that it must be within 0 < e < 2000 ->>> signature.parameters['e_init'] - ->>> # The parameter chopper_frequency specifies the frequency of the Fermi chopper. ->>> # The default is 400 Hz with the restriction that it must be one of the ints between 50 and 600 with a period of 50. ->>> signature.parameters['chopper_frequency'] - ->>> # The fitting_order parameter is an int with a default of 4, specifying the order of the polynomial used in fitting. ->>> signature.parameters['fitting_order'] ->>> # We can also check whether each of the parameters is positional or keyword argument ->>> [parameter.kind for parameter in signature.parameters.values()] -[<_ParameterKind.POSITIONAL_OR_KEYWORD: 1>, <_ParameterKind.KEYWORD_ONLY: 3>, <_ParameterKind.KEYWORD_ONLY: 3>, <_ParameterKind.KEYWORD_ONLY: 3>, <_ParameterKind.KEYWORD_ONLY: 3>, <_ParameterKind.KEYWORD_ONLY: 3>] -``` - - +The main entry-point to the library - contains the `Instrument` class used for managing all data ond +computing resolution functions. """ from __future__ import annotations