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

1""" 

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

3 

4Ellad B. Tadmor 

5Mingjian Wen 

6Daniel S. Karls 

7University of Minnesota 

8 

9This calculator functions as a wrapper that selects an appropriate 

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

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

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

13""" 

14 

15from . import kimpy_wrappers 

16from .calculators import (ASAPCalculator, KIMCalculator, LAMMPSLibCalculator, 

17 LAMMPSRunCalculator) 

18from .exceptions import KIMCalculatorError 

19 

20 

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

22 """Calculator wrapper for OpenKIM models 

23 

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

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

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

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

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

29 wrappers around native commands in a specific simulator (often 

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

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

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

33 

34 Parameters 

35 ---------- 

36 model_name : str 

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

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

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

40 

41 simulator : str, optional 

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

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

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

45 as follows: 

46 

47 - kimmodel (default for PMs) 

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

49 

50 - lammpsrun (PMs or LAMMPS SMs) 

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

52 

53 - lammpslib (default for LAMMPS SMs) 

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

55 

56 - asap (PMs) 

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

58 

59 - asap (ASAP SMs) 

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

61 

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

63 calculator compatible with the specified model will 

64 automatically be determined. 

65 

66 options : dict, optional 

67 Additional options passed to the initializer of the selected 

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

69 

70 - ase_neigh (bool) 

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

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

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

74 False) 

75 

76 - neigh_skin_ratio (float) 

77 : The skin distance used for neighbor list construction, 

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

79 

80 - release_GIL (bool) 

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

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

83 

84 See the ASE LAMMPS calculators doc page 

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

86 available options for the lammpslib and lammpsrun calculators. 

87 

88 debug : bool, optional 

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

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

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

92 

93 Returns 

94 ------- 

95 ase.calculators.calculator.Calculator 

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

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

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

99 OpenKIMcalculator or EMT defined in the asap3 codebase. 

100 

101 Raises 

102 ------ 

103 KIMCalculatorError 

104 Indicates an error occurred in initializing the calculator, 

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

106 """ 

107 

108 if options is None: 

109 options = {} 

110 

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

112 # support through a KIM-compliant simulator 

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

114 

115 if model_type == "pm": 

116 if simulator is None: # Default 

117 simulator = "kimmodel" 

118 

119 if simulator == "kimmodel": 

120 return KIMCalculator(model_name, options, debug) 

121 

122 elif simulator == "asap": 

123 return ASAPCalculator( 

124 model_name, model_type, options=options, verbose=debug 

125 ) 

126 

127 elif simulator == "lammpsrun": 

128 supported_species = get_model_supported_species(model_name) 

129 

130 # Return LAMMPS calculator 

131 return LAMMPSRunCalculator( 

132 model_name, model_type, supported_species, options, debug 

133 ) 

134 

135 elif simulator == "lammpslib": 

136 raise KIMCalculatorError( 

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

138 'Try using the "lammpsrun" calculator.' 

139 ) 

140 else: 

141 raise KIMCalculatorError( 

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

143 'Portable Model.'.format(simulator) 

144 ) 

145 

146 ####################################################### 

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

148 ####################################################### 

149 with kimpy_wrappers.SimulatorModel(model_name) as sm: 

150 

151 # Handle default behavior for 'simulator' 

152 if simulator is None: 

153 if sm.simulator_name == "ASAP": 

154 simulator = "asap" 

155 elif sm.simulator_name == "LAMMPS": 

156 simulator = "lammpslib" 

157 

158 if sm.simulator_name == "ASAP": 

159 

160 return ASAPCalculator( 

161 model_name, 

162 model_type, 

163 options=options, 

164 model_defn=sm.model_defn, 

165 verbose=debug, 

166 supported_units=sm.supported_units, 

167 ) 

168 

169 elif sm.simulator_name == "LAMMPS": 

170 

171 if simulator == "lammpsrun": 

172 

173 return LAMMPSRunCalculator( 

174 model_name, 

175 model_type, 

176 sm.supported_species, 

177 options, 

178 debug, 

179 atom_style=sm.atom_style, 

180 supported_units=sm.supported_units, 

181 ) 

182 

183 elif simulator == "lammpslib": 

184 return LAMMPSLibCalculator( 

185 model_name, sm.supported_species, sm.supported_units, 

186 options 

187 ) 

188 

189 else: 

190 raise KIMCalculatorError( 

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

192 ) 

193 

194 else: 

195 raise KIMCalculatorError( 

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

197 ) 

198 

199 

200def _is_portable_model(model_name): 

201 """ 

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

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

204 types of models in KIM) 

205 """ 

206 with kimpy_wrappers.ModelCollections() as col: 

207 model_type = col.get_item_type(model_name) 

208 

209 return model_type == kimpy_wrappers.collection_item_type_portableModel 

210 

211 

212def get_model_supported_species(model_name): 

213 if _is_portable_model(model_name): 

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

215 supported_species, _ = pm.get_model_supported_species_and_codes() 

216 else: 

217 with kimpy_wrappers.SimulatorModel(model_name) as sm: 

218 supported_species = sm.supported_species 

219 

220 return supported_species