API Reference Manual
Base class of all calculators. |
|
Description of a single parameter. |
|
Collection of parameters related to a single calculator |
|
Class collecting the parameters and calculators representing an entire instrument at a facility |
|
The abstract data class. |
|
- module BaseCalculator:
Module hosting the BaseCalculator class.
- class libpyvinyl.BaseCalculator.BaseCalculator(name, input, output_keys, output_data_types, output_filenames=None, instrument_base_dir='./', calculator_base_dir=None, parameters=None)[source]
Bases:
AbstractBaseClass
Base class of all calculators.
This class provides the libpyvinyl API. It defines all methods through which a user interacts with the simulation backengines.
This class is to be used as a base class for all calculators that implement a special simulation module, such as a photon diffraction calculator. Such a specialized Calculator has the same interface to the simulation backengine as all other ViNYL Calculators.
A complete example including a instrument and calculators can be found in
test/integration/plusminus
Constructs this class.
- Parameters:
name (
str
) – The name of this calculator.input (
Union
[DataCollection
,List
[BaseData
],BaseData
]) – The input of this calculator. It can be a DataCollection, a list of `BaseData`s or a single Data Object.output_keys (
Union
[list
,str
]) – The key(s) of this calculator’s output data.output_data_types (
Union
[list
,BaseData
]) – The data type(s), i.e., classes, of each output. It’s a list of the data classes or a single data class. The available data classes are based on BaseData.output_filenames (
Union
[list
,str
,None
]) – The name(s) of the output file(s). It can be a str of a filename or a list of filenames. If the mapping is dict mapping, the name is None. Defaults to None.instrument_base_dir (
str
) – The base directory for the instrument to which this calculator belongs. The final exact output file path depends on instrument_base_dir and calculator_base_dir: instrument_base_dir/calculator_base_dir/filenamecalculator_base_dir (
Optional
[str
]) – The base directory for this calculator. The final exact output file path depends on instrument_base_dir and calculator_base_dir: instrument_base_dir/calculator_base_dir/filenameparameters (
Optional
[CalculatorParameters
]) – The parameters for this calculator.
- property base_dir
The base path for the output files of this calculator in consideration of instrument_base_dir and calculator_base_dir
- property calculator_base_dir: str
The base directory for this calculator. The final exact output file path depends on instrument_base_dir and calculator_base_dir: instrument_base_dir/calculator_base_dir/filename
- property data
The alias of output. It’s not recommended to use this variable name due to it’s ambiguity.
- classmethod from_dump(dumpfile)[source]
Load a dill dump from a dumpfile.
- Parameters:
dumpfile (
str
) – The file name of the dumpfile.- Returns:
The calculator object restored from the dumpfile.
- abstract init_parameters()[source]
Virtual method to initialize all parameters. Must be implemented on the specialized class.
- property input: DataCollection
The input of this calculator. A collection or a single Data Object(s).
- property instrument_base_dir: str
The base directory for the instrument to which this calculator belongs.
- property output
The output of this calculator
- property output_file_paths
The final output file paths considering base_dir
- property output_filenames: list
The name(s) of the output file(s). It can be a str of a filename or a list of filenames. If the mapping is dict mapping, the name is None.
- property parameters: CalculatorParameters
The parameters of this calculator.
- set_input(value)[source]
Set the calculator input data. It can be a DataCollection, list or BaseData object.
- set_output_data_types(value)[source]
Set the calculator output data type. It can be a list of DataClass or a single DataClass.
- set_output_filenames(value)[source]
Set the calculator output filenames. It can be a list of filenames or just a single str.
- class libpyvinyl.Parameters.Collections.CalculatorParameters(parameters=None)[source]
Bases:
AbstractBaseClass
Collection of parameters related to a single calculator
Parameters are stored in a dict using their name as key
Creates a Parameters object, optionally with list of parameter objects
- check_list_type(parameter_list)[source]
Checks given list of parameters is a list and contains only parameter objects
- classmethod from_dict(params_dict)[source]
Initialize an instance from a dict.
- Parameters:
fname (str) – The filename (path) of the json file.
- classmethod from_json(fname)[source]
Initialize an instance from a json file.
- Parameters:
fname (str) – The filename (path) of the json file.
- class libpyvinyl.Parameters.Collections.InstrumentParameters[source]
Bases:
AbstractBaseClass
Object intended for use as instrument parameters
This object holds Parameters objects for a number of calculators and can have master parameters which control parameters for a number of calculators at once.
Create an empty ParametersCollection instance
- add(key, parameters)[source]
Here key could be a calculator object or a reference to such an object, like its name
- add_master_parameter(name, links, **kwargs)[source]
link: dict with keys and parameters for which this parameter should override
- classmethod from_dict(instrument_dict)[source]
Initialize an instance from a dict.
- Parameters:
fname (str) – The filename (path) of the json file.
- class libpyvinyl.Parameters.Collections.MasterParameter(*args, **kwargs)[source]
Bases:
Parameter
The master parameters need to affect multiple Parameters objects, and for this reason it is expanded on the basis of the Parameter class. A link system is added that contains information on which Parameters objects this master parameter should control parameters from.
Create MasterParameter with uninitialized links
- class libpyvinyl.Parameters.Collections.MasterParameters(parameters_dict, *args, **kwargs)[source]
Bases:
CalculatorParameters
Master Parameters object that contain all master parameters with the additional ability to set values for the other parameters this master should control.
Create MasterParameters object with given parameters dict
The parameters_dict contains all the Parameters objects in the ParametersCollection, and provides the access for the master parameters so they can control the other Parameters objects of which they are responsible.
- libpyvinyl.Parameters.Collections.quantity_decode(dct)[source]
Function to decode pint.Quantity object from json
- libpyvinyl.Parameters.Collections.quantity_encode(obj, primitives=False)[source]
Function to encode pint.Quantity and pint.Unit objects in json
It returns obj if the encoding was not possible.
- class libpyvinyl.Parameters.Parameter.Parameter(name, unit='', comment=None)[source]
Bases:
AbstractBaseClass
Description of a single parameter.
- The parameter is defined by:
name: when added to a parameter collection, it can be accessed by this name
value: can be a boolean, a string, a pint.Quantity, an int or float (the latter internally converted to pint.Quantity)
unit: a string that is internally converted into a pint.Unit
comment: a string with a brief description of the parameter and additional informations
Creates parameter with given name, optionally unit and comment
- Parameters:
- add_interval(min_value, max_value, intervals_are_legal)[source]
Sets an interval for this parameter: [min_value, max_value] The interval is closed on both sides: min_value and and max_value are included.
- Parameters:
min_value (
Union
[str
,bool
,int
,float
,Quantity
,None
]) – minimum value of the interval, None for infinitymax_value (
Union
[str
,bool
,int
,float
,Quantity
,None
]) – maximum value of the interval, None for infinityintervals_are_legal (
bool
) – if not done previously, it defines if all the intervals of this parameter should be considered as allowed or forbidden intervals.
- Return type:
- classmethod from_dict(param_dict)[source]
- Helper class method creating a new object from a dictionary providing
name: str MANDATORY
unit: str
comment: str
…
This class method is mainly used to allow dumping and loading the class from json
- is_legal(values=None)[source]
Checks whether or not given or contained value is legal given constraints.
- Return type:
- property pint_value: Quantity
Returning the value as a pint object if available, an error otherwise
- print_parameter_constraints()[source]
Print the legal and illegal intervals of this parameter. FIXME
- Return type:
- module Instrument:
Module hosting the Instrument class
- class libpyvinyl.Instrument.Instrument(name, calculators=None, instrument_base_dir='./')[source]
Bases:
object
Class collecting the parameters and calculators representing an entire instrument at a facility
Instrument object initialization:
- Parameters:
name (
str
) – The name of this instrumentcalculators (
Optional
[Dict
[str
,BaseCalculator
]]) – a collection of Calculator objects.
- add_calculator(calculator)[source]
Append one calculator to the list of calculators.
N.B. calculators are executed in the same order as they are provided
- Parameters:
calculator (
BaseCalculator
) – calculator- Return type:
- add_master_parameter(name, links, **kwargs)[source]
Add a new parameter with the given name as master parameter. The goal is to link parameters in multiple calculators that represent the same quantity and that should be all changed at the same time when any of them is changed. This is obtained creating the link and by changing the value of the newly created master parameter.
- property calculators: Dict[str, BaseCalculator]
The list of calculators. It’s modified either when constructing the class instance or using the
add_calculator()
function.
- list_calculators()[source]
Print the list of all defined calculators for this instrument
- Return type:
- property master: MasterParameters
Return the master parameters
- property output: DataCollection
Return the output of the last calculator
- property parameters: InstrumentParameters
The parameter collection of each calculator in the instrument. These parameters are links to the exact parameters of each calculator.
- remove_calculator(calculator_name)[source]
Remove the calculator with the given name from the list of calculators
- module BaseData:
Module hosts the BaseData class.
- class libpyvinyl.BaseData.BaseData(key, expected_data, data_dict=None, filename=None, file_format_class=None, file_format_kwargs=None)[source]
Bases:
AbstractBaseClass
The abstract data class. Inheriting classes represent simulation input and/or output data and provide a harmonized user interface to simulation data of various kinds rather than a data format. Their purpose is to provide a harmonized user interface to common data operations such as reading/writing from/to disk.
- Parameters:
key (
str
) – The key to identify the Data Object.expected_data (
dict
) – A placeholder dict for expected data. The keys of this dict are expected to be found during the execution of get_data(). The value for each key can be None.data_dict (
Optional
[dict
]) – The dict to map by this DataClass. It has to be None if a file mapping was already set, defaults to None.filename (
Optional
[str
]) – The filename of the file to map by this DataClass. It has to be None if a dict mapping was already set, defaults to None.file_format_class (class, optional) – The FormatClass to map the file by this DataClass, It has to be None if a dict mapping was already set, defaults to None
file_format_kwargs (
Optional
[dict
]) – The kwargs needed to map the file, defaults to None.
- property data_dict
The data_dict of the class instance for calculator usage
- property expected_data
The expected_data of the class instance for calculator usage
- property file_format_class
The FormatClass to map the file by this DataClass
- property file_format_kwargs
The kwargs needed to map the file
- classmethod from_file(filename, format_class, key, **kwargs)[source]
Create a Data Object mapping a file.
- Parameters:
filename (str, optional) – The filename of the file to map by this DataClass. It has to be None if a dict mapping was already set, defaults to None.
file_format_class (class, optional) – The FormatClass to map the file by this DataClass, It has to be None if a dict mapping was already set, defaults to None
file_format_kwargs (dict, optional) – The kwargs needed to map the file, defaults to None.
key (str) – The key to identify the Data Object.
- Returns:
A Data Object
- Return type:
- property mapping_content
Returns an overview of the keys of the mapped dict or the filename of the mapped file
- property mapping_type
If this data class is a file mapping or python dict mapping.
- set_dict(data_dict)[source]
Set a mapping dict for this DataClass.
- Parameters:
data_dict (dict) – The data dict to map
- set_file(filename, format_class, **kwargs)[source]
Set a mapping file for this DataClass.
- Parameters:
filename (
str
) – The filename of the file to map.format_class (class) – The FormatClass to map the file
- write(filename, format_class, key=None, **kwargs)[source]
Write the data mapped by the Data Object into a file and return a Data Object mapping the file. It converts either a file or a python object to a file The behavior related to a file will always be handled by the format class. If it’s a python dictionary mapping, write with the specified format_class directly.
- Parameters:
be generated with a suffix added to the previous identification key by the FormatClass. Defaults to None. :type key: str, optional :return: A Data Object :rtype: BaseData
- class libpyvinyl.BaseData.DataCollection(*args)[source]
Bases:
object
A collection of Data Objects
- get_data()[source]
Get the data of the data object(s). When there is only one item in the DataCollection, it returns the data dict, When there are more then one items, it returns a dictionary of the data dicts
- get_data_object(key)[source]
Get one data object by its key
- Parameters:
key (str) – The key of the data object to get.
- Returns:
A data object
- Return type:
DataClass
- write(filename, format_class, key=None, **kwargs)[source]
Write the data object(s) to the file(s). When there is only one item in the DataCollection, it returns the data object mapping the file which was wirttern, When there are more then one items, it returns a dictionary of the data objects.
- Parameters:
filename (
Union
[str
,dict
]) – The name(s) of the file(s) to write. When there are multiple items, they are expected in
a dict where the keys corresponding to the data in this collection. :type filename: str or dict :type format_class: :param format_class: The format class of the file(s). When there are multiple items, they are expected in a dict where the keys corresponding to the data in this collection. :type format_class: class or dict :type key:
Union
[str
,dict
,None
] :param key: The key(s) of the data object(s) mapping the written file(s), defaults to None. :type key: str or dict, optional :return: A data object or a dict of data objects. :rtype: DataClass or dict
- class libpyvinyl.BaseFormat.BaseFormat[source]
Bases:
AbstractBaseClass
The abstract format class which serves as the common interface for derived format classes.
- abstract classmethod convert(obj, output, output_format_class, key, **kwargs)[source]
Direct convert method, if the default converting would be too slow or not suitable for the output_format