API Reference Manual

`libpyvinyl.BaseCalculator`	class: Base class of all calculators.
`libpyvinyl.Parameter`	Description of a single parameter.
`libpyvinyl.CalculatorParameters`	Collection of parameters related to a single calculator
`libpyvinyl.Instrument`	class: Class collecting the parameters and calculators representing an entire instrument at a facility
`libpyvinyl.BaseData`	class: The abstract data class.
`libpyvinyl.BaseFormat`

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

Class:: Base class of all calculators.

This class is 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

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/filename
calculator_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/filename
parameters (Optional[CalculatorParameters]) – The parameters for this calculator.

abstract backengine()[source]

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

property data: The alias of output. It’s not recommended to use this variable name due to it’s ambiguity.

dump(fname=None)[source]

Dump class instance to file.

Parameters:: fname (Optional[str]) – Filename (path) of the file to write.
Return type:: str
Returns:: The filename of the dumpfile

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

property instrument_base_dir: str

property name: str

property output: The output of this calculator

property output_data_types: list

property output_file_paths: The final output file paths considering base_dir

property output_filenames: list

property output_keys: list

property parameters: CalculatorParameters

reset_parameters(value)[source]: Resets the calculator parameters

set_calculator_base_dir(value)[source]: Set the calculator base directory

set_input(value)[source]: Set the calculator input data. It can be a DataCollection, list or BaseData object.

set_instrument_base_dir(value)[source]: Set the instrument base directory

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.

set_output_keys(value)[source]: Set the calculator output keys. It can be a list of str or a single str.

set_parameters(args_as_dict=None, **kwargs)[source]: Sets parameters contained in this calculator using dict or kwargs

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

add(parameter)[source]: Adds parameters to this parameters object, either single or list

check_list_type(parameter_list)[source]: Checks given list of parameters is a list and contains only parameter objects

check_type(parameter)[source]: Checks given parameter is of type Parameter

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.

new_parameter(*args, **kwargs)[source]: Creates a new parameter with given arguments and adds to this Parameters object

print_indented(indents)[source]: returns string describing this object, can optionally be indented

to_dict()[source]

to_json(fname)[source]

Save this parameters class to a human readable json file.

Parameters:: fname (str) – Write to this 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.

classmethod from_json(fname)[source]

Initialize an instance from a json file.

Parameters:: fname (str) – The filename (path) of the json file.

to_dict()[source]

to_json(fname)[source]

Save this parameters class to a human readable json file.

Parameters:: fname (str) – Write to this 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

add_links(links)[source]: Links is a dict with key being reference to calculator and name of parameter to overwrite

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:

name (str) – name of the parameter
unit (str) – physical units returning the parameter value
comment (Optional[str]) – brief description of the parameter

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 infinity
max_value (Union[str, bool, int, float, Quantity, None]) – maximum value of the interval, None for infinity
intervals_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:

None

add_option(option, options_are_legal)[source]

Sets allowed values for this parameter

Parameters:

option (Any) – a discrete allowed or forbidden value
options_are_legal (bool) – defines if the given option is for a legal or illegal discrete value

Return type:

None

clear_intervals()[source]

Clear the intervals of this parameter.

Return type:: None

clear_options()[source]

Clear the option values of this parameter.

Return type:: None

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

get_intervals()[source]

get_intervals_are_legal()[source]

get_options()[source]

get_options_are_legal()[source]

is_legal(values=None)[source]

Checks whether or not given or contained value is legal given constraints.

Return type:: bool

property pint_value: Quantity: Returning the value as a pint object if available, an error otherwise

print_line()[source]

returns string with one line description of parameter

Return type:: str

print_parameter_constraints()[source]

Print the legal and illegal intervals of this parameter. FIXME

Return type:: None

property unit: str: Returning the units as a string

property value: str | bool | int | float | Quantity: Returns the magnitude of a Quantity or the stored value otherwise

property value_no_conversion: str | bool | int | float | Quantity: Returning the object stored in value with no conversions

module Instrument:: Module hosting the Instrument class

class libpyvinyl.Instrument.Instrument(name, calculators=None, instrument_base_dir='./')[source]

Bases: object

Class:: Class collecting the parameters and calculators representing an entire instrument at a facility

Instrument object initialization:

Parameters:

name (str) – The name of this instrument
calculators (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:: None

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.

Parameters:

name (str) – name of the master parameter
links (Dict[str, str]) – dictionary with the names of the calculators and calculator parameters that represent the same quantity and hence can be changed all at once modifying the master parameter”

Return type:

None

property calculators: Dict[str, BaseCalculator]: The list of calculators. It’s modified either when constructing the class instance or using the add_calculator() function.

property instrument_base_dir: str

list_calculators()[source]

Print the list of all defined calculators for this instrument

Return type:: None

list_parameters()[source]

Print the list of all calculator parameters

Return type:: None

property master: MasterParameters: Return the master parameters

property name: str: The name of this instrument.

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

Parameters:: calculator_name (str) – name of one calculator already added to the list
Return type:: None

run()[source]

Run the entire simulation, i.e. all the calculators in the order they have been provided

Return type:: None

set_instrument_base_dir(base)[source]

Set each calculator’s instrument_base_dir to ‘base. Each calculator’s data file ouput directory will be “instrument_base_dir/calculator_base_dir”.

Parameters:: base (str) – The base directory to be set.
Return type:: None

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

Class:: 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

property filename: str | None: The filename of the file to map by this DataClass.

classmethod from_dict(data_dict, key)[source]

Create a Data Object mapping a data dict.

Parameters:

data_dict (dict) – The dict to map by this DataClass. It has to be None if a file mapping was already set, defaults to None.
key (str) – The key to identify the Data Object.

Returns:

A Data Object

Return type:

BaseData

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:

BaseData

get_data(**kwargs)[source]: Return the data in a dictionary

property key: str: The key of the class instance for calculator usage

classmethod list_formats()[source]: Print supported formats

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

abstract classmethod supported_formats()[source]

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:

filename (str) – The filename of the file to be written.
file_format_class (class) – The FormatClass to write the file.
key (Optional[str]) – The identification key of the new Data Object. When it’s None, a new key will

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

add_data(*args)[source]: Add data objects to the data colletion

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

to_list()[source]: Return a list of the data objects in the data collection

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. It’s the interface of a certain data format.

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

abstract static direct_convert_formats()[source]

abstract classmethod format_register()[source]

abstract classmethod read(filename, **kwargs)[source]

Read the data from the file with the filename to a dictionary. The dictionary will be used by its corresponding data class.

Return type:: dict

abstract classmethod write(object, filename, key, **kwargs)[source]: Save the data with the filename.