Coverage for moptipy / api / encoding.py: 100%

1""" 

2The base class for implementing encodings. 

3 

4Sometimes, in optimization, the search space and the space of possible 

5solutions are different. For example, in the Job Shop Scheduling Problem 

6(JSSP), the search operators of the optimization algorithm may process 

7permutations with repetitions 

8(:class:`~moptipy.spaces.permutations.Permutations`) while the objective 

9function rates :class:`~moptipy.examples.jssp.gantt.Gantt` charts. The 

10Gantt charts are the solutions that the user wants, but they are harder to 

11deal with for search operators. However, we can easily develop search 

12operators for permutations and permutations can be mapped to Gantt charts 

13(see :class:`~moptipy.examples.jssp.ob_encoding.OperationBasedEncoding`). 

14A combination of search space, solution space, and encoding can be configured 

15when setting up an experiment :class:`~moptipy.api.execution.Execution`, which 

16then takes care of showing the search space to the optimization algorithm 

17while providing the objective function and user with the elements of the 

18solution spaces. 

19 

20All encodings inherit from the class :class:`~moptipy.api.encoding.Encoding`. 

21If you implement a new such encoding, you may want to test it using the 

22pre-defined unit test routine 

23:func:`~moptipy.tests.encoding.validate_encoding`. 

24""" 

25from typing import Any 

26 

27from pycommons.types import type_error 

28 

29from moptipy.api.component import Component 

30 

31 

32# start book 

33class Encoding(Component): 

34 """The encoding translates from a search space to a solution space.""" 

35 

36 def decode(self, x, y) -> None: 

37 """ 

38 Translate from search- to solution space. 

39 

40 Map a point `x` from the search space to a point `y` 

41 in the solution space. 

42 

43 :param x: the point in the search space, remaining unchanged. 

44 :param y: the destination data structure for the point in the 

45 solution space, whose contents will be overwritten 

46 """ 

47 # end book 

48 

49 

50def check_encoding(encoding: Any, none_is_ok: bool = True) -> Encoding | None: 

51 """ 

52 Check whether an object is a valid instance of :class:`Encoding`. 

53 

54 :param encoding: the object 

55 :param none_is_ok: is it ok if `None` is passed in? 

56 :return: the object 

57 :raises TypeError: if `encoding` is not an instance of :class:`Encoding` 

58 

59 >>> check_encoding(Encoding()) 

60 Encoding 

61 >>> check_encoding(Encoding(), True) 

62 Encoding 

63 >>> check_encoding(Encoding(), False) 

64 Encoding 

65 >>> try: 

66 ... check_encoding('A') 

67 ... except TypeError as te: 

68 ... print(te) 

69 encoding should be an instance of moptipy.api.encoding.\ 

70Encoding but is str, namely 'A'. 

71 >>> try: 

72 ... check_encoding('A', True) 

73 ... except TypeError as te: 

74 ... print(te) 

75 encoding should be an instance of moptipy.api.encoding.\ 

76Encoding but is str, namely 'A'. 

77 >>> try: 

78 ... check_encoding('A', False) 

79 ... except TypeError as te: 

80 ... print(te) 

81 encoding should be an instance of moptipy.api.encoding.\ 

82Encoding but is str, namely 'A'. 

83 >>> print(check_encoding(None)) 

84 None 

85 >>> print(check_encoding(None, True)) 

86 None 

87 >>> try: 

88 ... check_encoding(None, False) 

89 ... except TypeError as te: 

90 ... print(te) 

91 encoding should be an instance of moptipy.api.encoding.\ 

92Encoding but is None. 

93 """ 

94 if isinstance(encoding, Encoding): 

95 return encoding 

96 if none_is_ok and (encoding is None): 

97 return None 

98 raise type_error(encoding, "encoding", Encoding)