pydcop.algorithms.AlgorithmDef¶

class AlgorithmDef(algo: str, params: Dict[str, Any], mode: str = 'min')¶

Full definition of an algorithm’s instance.

An AlgorithmDef represents a DCOP algorithm instance with all parameters needed to run it. These parameters depend on the considered algorithm (e.g. variant A, B or C for DSA and damping factor for maxsum) and are defined with AlgoParameterDef.

Notes

When using the constructor, params must already be a dict of valid parameters for this algorithm and no validity check is performed.

Most of the time, you should use the AlgorithmDef.build_with_default_param() static method to create an instance of AlgorithmDef, as it automatically uses default arguments for the requested algorithm.

Parameters

algo (str) – Name of the algorithm. It must be the name of a module in the pydcop.algorithms package.
params (dict) – Dictionary of algorithm-specific configuration and parameters
mode (str) – 'min' of 'max', defaults to 'min'

property algo¶

The name of the algorithm.

The name of the algorithm is the name of a module in the pydcop.algorithms package.

Returns: str
Return type: the name of the algorithm.

static build_with_default_param(algo: str, params: Dict[str, Any] = None, mode: str = 'min', parameters_definitions: List[pydcop.algorithms.AlgoParameterDef] = None)¶

Creates an AlgoDef instance with defaults parameter values.

Parameters passed as argument are checked for validity. If a value is not provided for some required parameters, the default value is used.

Parameters

algo (str) – Name of the algorithm. It must be the name of a module in the pydcop.algorithms package.
mode (str) – 'min' of 'max', defaults to 'min'
params (dict) – Dictionary of algorithm-specific parameters. If a value is not provided for some required parameters, their default value is used.
parameters_definitions (list of AlgoParameterDef) – Algorithms parameters definition. If not provided, their are automatically loaded form the algorithm’s module.

Returns

algodef – An instance with defaults parameter values.

Return type

AlgoDef

Raises

ValueError: – If an unknown parameter is passed or if a parameter value does not respect the parameter definition.

Examples

>>> algo_def = AlgorithmDef.build_with_default_param('dsa', {'variant': 'B'})
>>> algo_def.param_value('probability')
0.7
>>> algo_def.param_value('variant')
'B'

property mode¶

The mode, 'min' or 'max'.

Returns: str
Return type: The mode, ‘min or ‘max’.

param_names() → Iterable[str]¶

Names of the parameters for this algorithm.

Returns
Return type: An iterable of str.

param_value(param: str) → Any¶

The value of a parameter.

Parameters: param (str) – A parameter name
Returns
Return type: The value of the parameter
Raises: KeyError – if there is no parameter with this name.:

property params¶

A dictionary of parameters values.

The dictionary is a copy of the internal parameters and can be safely modified.

Returns
Return type: A dictionary of parameters values.

list_available_algorithms() → List[str]¶

The list of available DCOP algorithms.

Returns
Return type: a list of str

load_algorithm_module(algo_name: str)¶

Dynamically load an algorithm module.

This should be used instead of importlib.import_module as it adds default implementations for some methods, if they have not been defined for the algorithm.

Parameters: algo_name (str) – the name of the algorithm. It must be one of the name returned by list_available_algorithms().
Returns: The imported module for this algorithm.
Return type: module

class AlgoParameterDef¶

Definition of an algorithm’s parameter.

AlgoParameterDef instances are used to describe the parameters supported by an algorithms.

For example, dsa supports 3 parameters, which declared with a module-level variable in dsa.py

algo_params = [
  AlgoParameterDef('probability', 'float', None, 0.7),
  AlgoParameterDef('variant', 'str', ['A', 'B', 'C'], 'B'),
  AlgoParameterDef('stop_cycle', 'int', None, 0)]

property default_value¶: Default value of the parameter.

property name¶: Name of the parameter (str).

property type¶

Type of the parameter (str)

This must be either int, float or str

property values¶

List of valid values for this parameter.

Can be None if non-applicable (for a float paramater, for example).

prepare_algo_params(params: Dict[str, Any], parameters_definitions: List[pydcop.algorithms.AlgoParameterDef])¶

Ensure algorithm’s parameters are valid.

Check validity of algorithm parameters and add default value for missing parameters.

Parameters

params (Dict[str, Any]) – a dict containing name and values for parameters
parameters_definitions (list of AlgoParameterDef) – definition of parameters

Examples

>>> param_defs = [AlgoParameterDef('p1', 'str', ['1', '2'], '1'),                       AlgoParameterDef('p2', 'int', None, 5),                      AlgoParameterDef('p3', 'float', None, 0.5)]
>>> prepare_algo_params({}, param_defs)['p3']
0.5
>>> prepare_algo_params({'p2' : 2}, param_defs)['p2']
2
>>> prepare_algo_params({'p3' : 0.7}, param_defs)['p3']
0.7

Returns: params – a Dict with all algorithms parameters. If a parameter was not provided in the input dict, it is added with its default value.
Return type: dict
Raises: ValueError: – If an unknown parameter is passed or if a parameter value does not respect the parameter definition.

check_param_value(param_val: Any, param_def: pydcop.algorithms.AlgoParameterDef) → Any¶

Check if param_val is a valid value for a AlgoParameterDef

When a parameter is given as a str, and the definition expect an int or a float, a conversion is automatically attempted and the converted value is returned

Parameters

param_val (any) – a value
param_def (AlgoParameterDef) – a parameter definition

Returns

the parameter value if it is valid according to the definition (and potentially after conversion)

Return type

param_value

Raises

ValueError: – Raises a ValueError if the value does not satisfies the parameter definition.

Examples

>>> param_def = AlgoParameterDef('p', 'str', ['a', 'b'], 'b')
>>> check_param_value('b', param_def)
'b'

With automatic conversion from str to int >>> param_def = AlgoParameterDef(‘p’, ‘int’, None, None) >>> check_param_value(‘5’, param_def) 5