Coverage for src/amisc/__init__.py: 96%

1"""Efficient framework for building surrogates of multidisciplinary systems using the adaptive multi-index stochastic 

2collocation (AMISC) technique. 

3 

4- Author - Joshua Eckels (eckelsjd@umich.edu) 

5- License - GPL-3.0 

6 

7The `amisc` package takes an object-oriented approach to building a surrogate of a multidisciplinary system. From the 

8bottom up, you have: 

9 

10- **variables** that serve as inputs and outputs for the models, 

11- **interpolators** that define a specific input → output mathematical relationship to approximate a function, 

12- **components** that wrap a model for a single discipline, and a 

13- **system** that defines the connections between components in a multidisciplinary system. 

14 

15The **system** is ultimately independent of the specific models, interpolation methods, or underlying variables. 

16As such, the primary top-level object that users of the `amisc` package will interact with is the `System`. 

17 

18Variables additionally use `Transform`, `Distribution`, and `Compression` interfaces to manage normalization, PDFs, 

19and field quantity compression, respectively. 

20 

21Currently, only Lagrange polynomial interpolation and Linear regression are implemented as the underlying surrogate 

22methods with a sparse grid data structure. SVD is also the only currently implemented method for compression. However, 

23interfaces are provided for `Interpolator`, `TrainingData`, and `Compression` to allow for easy extension to other 

24methods. 

25 

26Here is a class diagram summary of this workflow: 

27 

28``` mermaid 

29classDiagram 

30 namespace Core { 

31 class System { 

32 +list[Component] components 

33 +TrainHistory train_history 

34 +fit() 

35 +predict(x) 

36 } 

37 class Component { 

38 +callable model 

39 +list[Variable] inputs 

40 +list[Variable] outputs 

41 +Interpolator interpolator 

42 +TrainingData training_data 

43 +activate_index(alpha, beta) 

44 +predict(x) 

45 } 

46 class Variable { 

47 +str name 

48 +tuple domain 

49 +Distribution dist 

50 +Transform norm 

51 +Compression comp 

52 +sample() 

53 +normalize() 

54 +compress() 

55 } 

56 } 

57 class Interpolator { 

58 <<abstract>> 

59 + refine() 

60 + predict(x) 

61 } 

62 class TrainingData { 

63 <<abstract>> 

64 +get() 

65 +set() 

66 +refine() 

67 } 

68 class Transform { 

69 <<abstract>> 

70 +transform(values) 

71 } 

72 class Distribution { 

73 <<abstract>> 

74 +sample(size) 

75 +pdf(x) 

76 } 

77 class Compression { 

78 <<abstract>> 

79 +compress(values) 

80 +reconstruct(values) 

81 } 

82 System --o "1..n" Component 

83 Component --o "1..n" Variable 

84 direction TD 

85 Component --* Interpolator 

86 Component --* TrainingData 

87 Variable --o Transform 

88 Variable --o Distribution 

89 Variable --o Compression 

90``` 

91 

92Note how the `System` aggregates the `Component`, which aggregates the `Variable`. In other 

93words, variables can act independently of components, and components can act independently of systems. Components 

94make use of `Interpolator` and `TrainingData` interfaces to manage the underlying surrogate method 

95and training data, respectively. Similarly, `Variables` use `Transform`, `Distribution`, and `Compression` 

96interfaces to manage normalization, PDFs, and field quantity compression, respectively. 

97 

98The `amisc` package also includes a `FileLoader` interface for loading and dumping `amisc` objects to/from file. 

99We recommend using the built-in `YamlLoader` for this purpose, as it includes custom YAML tags for reading/writing 

100`amisc` objects from file. 

101""" 

102from abc import ABC as _ABC 

103from abc import abstractmethod as _abstractmethod 

104from pathlib import Path as _Path 

105from typing import Any as _Any 

106 

107import yaml as _yaml 

108 

109from amisc.component import Component 

110from amisc.system import System 

111from amisc.utils import to_model_dataset, to_surrogate_dataset 

112from amisc.variable import Variable, VariableList 

113 

114__version__ = "0.7.3" 

115__all__ = ['System', 'Component', 'Variable', 'VariableList', 'FileLoader', 'YamlLoader', 

116 'to_model_dataset', 'to_surrogate_dataset'] 

117 

118 

119class FileLoader(_ABC): 

120 """Common interface for loading and dumping `amisc` objects to/from file.""" 

121 

122 @classmethod 

123 @_abstractmethod 

124 def load(cls, stream: str | _Path | _Any, **kwargs): 

125 """Load an `amisc` object from a stream. If a file path is given, will attempt to open the file.""" 

126 raise NotImplementedError 

127 

128 @classmethod 

129 @_abstractmethod 

130 def dump(cls, obj, stream: str | _Path | _Any, **kwargs): 

131 """Save an `amisc` object to a stream. If a file path is given, will attempt to write to the file.""" 

132 raise NotImplementedError 

133 

134 

135class YamlLoader(FileLoader): 

136 """YAML file loader for `amisc` objects.""" 

137 

138 @staticmethod 

139 def _yaml_loader(): 

140 """Custom YAML loader that includes `amisc` object tags.""" 

141 loader = _yaml.Loader 

142 loader.add_constructor(Variable.yaml_tag, Variable._yaml_constructor) 

143 loader.add_constructor(VariableList.yaml_tag, VariableList._yaml_constructor) 

144 loader.add_constructor(Component.yaml_tag, Component._yaml_constructor) 

145 loader.add_constructor(System.yaml_tag, System._yaml_constructor) 

146 return loader 

147 

148 @staticmethod 

149 def _yaml_dumper(): 

150 """Custom YAML dumper that includes `amisc` object tags.""" 

151 dumper = _yaml.Dumper 

152 dumper.add_representer(Variable, Variable._yaml_representer) 

153 dumper.add_representer(VariableList, VariableList._yaml_representer) 

154 dumper.add_representer(Component, Component._yaml_representer) 

155 dumper.add_representer(System, System._yaml_representer) 

156 return dumper 

157 

158 @classmethod 

159 def load(cls, stream, **kwargs): 

160 """Extra kwargs ignored for YAML loading (since they are not used by `yaml.load`).""" 

161 try: 

162 p = _Path(stream).with_suffix('.yml') 

163 except (TypeError, ValueError): 

164 pass 

165 else: 

166 with open(p, 'r', encoding='utf-8') as fd: 

167 return _yaml.load(fd, Loader=cls._yaml_loader()) 

168 

169 return _yaml.load(stream, Loader=cls._yaml_loader()) 

170 

171 @classmethod 

172 def dump(cls, obj, stream, **kwargs): 

173 """Extra kwargs get passed to `yaml.dump`.""" 

174 kwargs['allow_unicode'] = kwargs.get('allow_unicode', True) 

175 kwargs['sort_keys'] = kwargs.get('sort_keys', False) 

176 try: 

177 p = _Path(stream).with_suffix('.yml') 

178 except (TypeError, ValueError): 

179 pass 

180 else: 

181 with open(p, 'w', encoding='utf-8') as fd: 

182 return _yaml.dump(obj, fd, Dumper=cls._yaml_dumper(), **kwargs) 

183 

184 return _yaml.dump(obj, stream, Dumper=cls._yaml_dumper(), **kwargs)