Coverage for /builds/ase/ase/ase/calculators/kim/kim.py: 36.96%

1# fmt: off 

2 

3""" 

4Knowledgebase of Interatomic Models (KIM) Calculator for ASE written by: 

5 

6Ellad B. Tadmor 

7Mingjian Wen 

8Daniel S. Karls 

9University of Minnesota 

10 

11This calculator functions as a wrapper that selects an appropriate 

12calculator for a given KIM model depending on whether it supports the 

13KIM application programming interface (API) or not. For more information 

14on KIM, visit https://openkim.org. 

15""" 

16 

17from . import kimpy_wrappers 

18from .calculators import ( 

19 ASAPCalculator, 

20 KIMCalculator, 

21 LAMMPSLibCalculator, 

22 LAMMPSRunCalculator, 

23) 

24from .exceptions import KIMCalculatorError 

25 

26 

27def KIM(model_name, simulator=None, options=None, debug=False): 

28 """Calculator wrapper for OpenKIM models 

29 

30 Returns a suitable calculator that can be used with any model 

31 archived in the Open Knowledgebase of Interatomic Models (OpenKIM) 

32 at https://openkim.org. There are two kinds of models in KIM: 

33 Portable Models (PMs), which can be used with any KIM API-compliant 

34 simulator, and Simulator Models (SMs), which are essentially just 

35 wrappers around native commands in a specific simulator (often 

36 combined with values for the model parameters). PMs published on 

37 openkim.org contain the string '__MO_' in their name, while SMs 

38 published on openkim.org contain the string '__SM_' in their name. 

39 

40 Parameters 

41 ---------- 

42 model_name : str 

43 The name of the KIM model installed on your system. KIM models 

44 published on openkim.org follow a specific naming scheme (see 

45 https://openkim.org/doc/schema/kim-ids). 

46 

47 simulator : str, optional 

48 Used to identify the ASE calculator that will be used. 

49 Currently supported values include 'kimmodel', 'lammpslib', 

50 'lammpsrun' and 'asap', and correspond to different calculators 

51 as follows: 

52 

53 - kimmodel (default for PMs) 

54 : :py:mod:`ase.calculators.kim.kimmodel.KIMModelCalculator` 

55 

56 - lammpsrun (PMs or LAMMPS SMs) 

57 : :py:mod:`ase.calculators.lammpsrun.LAMMPS` 

58 

59 - lammpslib (default for LAMMPS SMs) 

60 : :py:mod:`ase.calculators.lammpslib.LAMMPSlib` 

61 

62 - asap (PMs) 

63 : :py:mod:`asap3.Internal.OpenKIMcalculator.OpenKIMcalculator` 

64 

65 - asap (ASAP SMs) 

66 : :py:mod:`asap3.Internal.BuiltinPotentials.EMT` 

67 

68 In general, this argument should be omitted, in which case a 

69 calculator compatible with the specified model will 

70 automatically be determined. 

71 

72 options : dict, optional 

73 Additional options passed to the initializer of the selected 

74 calculator. If ``simulator`` == 'kimmodel', possible options are: 

75 

76 - ase_neigh (bool) 

77 : Whether to use the kimpy neighbor list library (False) or 

78 use ASE's internal neighbor list mechanism (True). Usually 

79 kimpy's neighbor list library will be faster. (Default: 

80 False) 

81 

82 - neigh_skin_ratio (float) 

83 : The skin distance used for neighbor list construction, 

84 expressed as a fraction of the model cutoff (Default: 0.2) 

85 

86 - release_GIL (bool) 

87 : Whether to release python GIL. Releasing the GIL allows a KIM 

88 model to run with multiple concurrent threads. (Default: False) 

89 

90 See the ASE LAMMPS calculators doc page 

91 (https://wiki.fysik.dtu.dk/ase/ase/calculators/lammps.html) for 

92 available options for the lammpslib and lammpsrun calculators. 

93 

94 debug : bool, optional 

95 If True, detailed information is printed to stdout. If the 

96 lammpsrun calculator is being used, this also serves as the 

97 value of the ``keep_tmp_files`` option. (Default: False) 

98 

99 Returns 

100 ------- 

101 ase.calculators.calculator.Calculator 

102 An ASE-compatible calculator. Currently, this will be an instance of 

103 KIMModelCalculator, LAMMPS (the lammpsrun calculator), or LAMMPSlib, 

104 which are all defined in the ASE codebase, or an instance of either 

105 OpenKIMcalculator or EMT defined in the asap3 codebase. 

106 

107 Raises 

108 ------ 

109 KIMCalculatorError 

110 Indicates an error occurred in initializing the calculator, 

111 e.g. due to incompatible combinations of argument values 

112 """ 

113 

114 if options is None: 

115 options = {} 

116 

117 # If this is a KIM Portable Model (supports KIM API), return 

118 # support through a KIM-compliant simulator 

119 model_type = "pm" if _is_portable_model(model_name) else "sm" 

120 

121 if model_type == "pm": 

122 if simulator is None: # Default 

123 simulator = "kimmodel" 

124 

125 if simulator == "kimmodel": 

126 return KIMCalculator(model_name, options, debug) 

127 

128 elif simulator == "asap": 

129 return ASAPCalculator( 

130 model_name, model_type, options=options, verbose=debug 

131 ) 

132 

133 elif simulator == "lammpsrun": 

134 supported_species = get_model_supported_species(model_name) 

135 

136 # Return LAMMPS calculator 

137 return LAMMPSRunCalculator( 

138 model_name, model_type, supported_species, options, debug 

139 ) 

140 

141 elif simulator == "lammpslib": 

142 raise KIMCalculatorError( 

143 '"lammpslib" calculator does not support KIM Portable Models. ' 

144 'Try using the "lammpsrun" calculator.' 

145 ) 

146 else: 

147 raise KIMCalculatorError( 

148 'Unsupported simulator "{}" requested to run KIM ' 

149 'Portable Model.'.format(simulator) 

150 ) 

151 

152 ####################################################### 

153 # If we get to here, the model is a KIM Simulator Model 

154 ####################################################### 

155 with kimpy_wrappers.SimulatorModel(model_name) as sm: 

156 

157 # Handle default behavior for 'simulator' 

158 if simulator is None: 

159 if sm.simulator_name == "ASAP": 

160 simulator = "asap" 

161 elif sm.simulator_name == "LAMMPS": 

162 simulator = "lammpslib" 

163 

164 if sm.simulator_name == "ASAP": 

165 

166 return ASAPCalculator( 

167 model_name, 

168 model_type, 

169 options=options, 

170 model_defn=sm.model_defn, 

171 verbose=debug, 

172 supported_units=sm.supported_units, 

173 ) 

174 

175 elif sm.simulator_name == "LAMMPS": 

176 

177 if simulator == "lammpsrun": 

178 

179 return LAMMPSRunCalculator( 

180 model_name, 

181 model_type, 

182 sm.supported_species, 

183 options, 

184 debug, 

185 atom_style=sm.atom_style, 

186 supported_units=sm.supported_units, 

187 ) 

188 

189 elif simulator == "lammpslib": 

190 return LAMMPSLibCalculator( 

191 model_name, sm.supported_species, sm.supported_units, 

192 options 

193 ) 

194 

195 else: 

196 raise KIMCalculatorError( 

197 f'Unknown LAMMPS calculator: "{simulator}".' 

198 ) 

199 

200 else: 

201 raise KIMCalculatorError( 

202 f'Unsupported simulator: "{sm.simulator_name}".' 

203 ) 

204 

205 

206def _is_portable_model(model_name): 

207 """ 

208 Returns True if the model specified is a KIM Portable Model (if it 

209 is not, then it must be a KIM Simulator Model -- there are no other 

210 types of models in KIM) 

211 """ 

212 with kimpy_wrappers.ModelCollections() as col: 

213 model_type = col.get_item_type(model_name) 

214 

215 return (model_type == 

216 kimpy_wrappers.wrappers.collection_item_type_portableModel) 

217 

218 

219def get_model_supported_species(model_name): 

220 if _is_portable_model(model_name): 

221 with kimpy_wrappers.PortableModel(model_name, debug=False) as pm: 

222 supported_species, _ = pm.get_model_supported_species_and_codes() 

223 else: 

224 with kimpy_wrappers.SimulatorModel(model_name) as sm: 

225 supported_species = sm.supported_species 

226 

227 return supported_species