openff-toolkit 0.18.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (231) hide show
  1. devtools/scripts/build_cookiecutter_json.py +22 -0
  2. docs/conf.py +296 -0
  3. docs/conftest.py +23 -0
  4. examples/conformer_energies/conformer_energies.py +143 -0
  5. examples/deprecated/SMIRNOFF_comparison/compare_molecule_energies.py +48 -0
  6. examples/deprecated/SMIRNOFF_comparison/compare_set_energies.py +58 -0
  7. examples/deprecated/liquid_box/create_mol2_pdb/create_mol2_pdb.py +193 -0
  8. examples/deprecated/liquid_box/openff_simulation.py +72 -0
  9. examples/deprecated/mixedFF_structure/generate_mixedFF_complex.py +56 -0
  10. examples/deprecated/testing/test_impropers/tleap_tools.py +120 -0
  11. examples/examples_helper.py +61 -0
  12. openff/toolkit/__init__.py +101 -0
  13. openff/toolkit/_tests/__init__.py +0 -0
  14. openff/toolkit/_tests/_stale_tests.py +146 -0
  15. openff/toolkit/_tests/conftest.py +108 -0
  16. openff/toolkit/_tests/create_molecules.py +494 -0
  17. openff/toolkit/_tests/mocking.py +145 -0
  18. openff/toolkit/_tests/molecule/__init__.py +1 -0
  19. openff/toolkit/_tests/molecule/test_state_enumeration.py +302 -0
  20. openff/toolkit/_tests/test_energies.py +136 -0
  21. openff/toolkit/_tests/test_examples.py +109 -0
  22. openff/toolkit/_tests/test_forcefield.py +3864 -0
  23. openff/toolkit/_tests/test_interchange.py +19 -0
  24. openff/toolkit/_tests/test_io.py +19 -0
  25. openff/toolkit/_tests/test_links.py +73 -0
  26. openff/toolkit/_tests/test_mm_molecule.py +404 -0
  27. openff/toolkit/_tests/test_molecule.py +4246 -0
  28. openff/toolkit/_tests/test_nagl.py +169 -0
  29. openff/toolkit/_tests/test_parameter_plugins.py +89 -0
  30. openff/toolkit/_tests/test_parameters.py +2898 -0
  31. openff/toolkit/_tests/test_toolkit_io.py +1088 -0
  32. openff/toolkit/_tests/test_toolkits.py +4418 -0
  33. openff/toolkit/_tests/test_topology.py +2485 -0
  34. openff/toolkit/_tests/test_utils.py +101 -0
  35. openff/toolkit/_tests/test_utils_callback.py +178 -0
  36. openff/toolkit/_tests/test_utils_collections.py +263 -0
  37. openff/toolkit/_tests/test_utils_serialization.py +168 -0
  38. openff/toolkit/_tests/utils.py +1747 -0
  39. openff/toolkit/data/README.md +8 -0
  40. openff/toolkit/data/molecules/AlkEthOH_test_filt1_ff.mol2 +2026 -0
  41. openff/toolkit/data/molecules/AlkEthOH_test_filt1_tripos.mol2 +2026 -0
  42. openff/toolkit/data/molecules/AlkEthOH_tripos.tar.gz +0 -0
  43. openff/toolkit/data/molecules/CID20742535_anion.sdf +50 -0
  44. openff/toolkit/data/molecules/CID20742535_neutral.sdf +51 -0
  45. openff/toolkit/data/molecules/FreeSolv.tar.gz +0 -0
  46. openff/toolkit/data/molecules/MiniDrugBank.sdf +33988 -0
  47. openff/toolkit/data/molecules/MiniDrugBank_tripos.mol2 +35462 -0
  48. openff/toolkit/data/molecules/PT2385.sdf +90 -0
  49. openff/toolkit/data/molecules/QL8.sdf +401 -0
  50. openff/toolkit/data/molecules/README.md +21 -0
  51. openff/toolkit/data/molecules/benzene.crd +8 -0
  52. openff/toolkit/data/molecules/benzene.mol2 +34 -0
  53. openff/toolkit/data/molecules/benzene.top +166 -0
  54. openff/toolkit/data/molecules/butane_multi.sdf +231 -0
  55. openff/toolkit/data/molecules/cyclohexane.mol2 +44 -0
  56. openff/toolkit/data/molecules/ethanol.mol2 +25 -0
  57. openff/toolkit/data/molecules/ethanol.sdf +23 -0
  58. openff/toolkit/data/molecules/ethanol_partial_charges.sdf +26 -0
  59. openff/toolkit/data/molecules/ethanol_reordered.mol2 +25 -0
  60. openff/toolkit/data/molecules/ethanol_reordered.sdf +23 -0
  61. openff/toolkit/data/molecules/ethene_rdkit.sdf +17 -0
  62. openff/toolkit/data/molecules/laromustine_ff.mol2 +71 -0
  63. openff/toolkit/data/molecules/laromustine_tripos.mol2 +71 -0
  64. openff/toolkit/data/molecules/methane_multiconformer.sdf +32 -0
  65. openff/toolkit/data/molecules/methane_multiconformer_properties.sdf +45 -0
  66. openff/toolkit/data/molecules/nh4.pdb +7 -0
  67. openff/toolkit/data/molecules/po4_phenylphosphate.pdb +46 -0
  68. openff/toolkit/data/molecules/ruxolitinib_conformers.sdf +910 -0
  69. openff/toolkit/data/molecules/toluene.mol2 +38 -0
  70. openff/toolkit/data/molecules/toluene.mol2.gz +0 -0
  71. openff/toolkit/data/molecules/toluene.pdb +30 -0
  72. openff/toolkit/data/molecules/toluene.sdf +36 -0
  73. openff/toolkit/data/molecules/toluene_charged.mol2 +38 -0
  74. openff/toolkit/data/molecules/z_3_hydroxy_propenal.sdf +23 -0
  75. openff/toolkit/data/proteins/5tbm_complex_solv.pdb +1928 -0
  76. openff/toolkit/data/proteins/5tbm_complex_solv_box.pdb +19563 -0
  77. openff/toolkit/data/proteins/CTerminal_ALA.pdb +20 -0
  78. openff/toolkit/data/proteins/CTerminal_ALA.sdf +43 -0
  79. openff/toolkit/data/proteins/CTerminal_ALA_ALA.pdb +30 -0
  80. openff/toolkit/data/proteins/CTerminal_ALA_ALA_misnamedH.pdb +30 -0
  81. openff/toolkit/data/proteins/CTerminal_ARG.pdb +34 -0
  82. openff/toolkit/data/proteins/CTerminal_TRP.pdb +34 -0
  83. openff/toolkit/data/proteins/MainChain_ALA.pdb +25 -0
  84. openff/toolkit/data/proteins/MainChain_ALA.sdf +52 -0
  85. openff/toolkit/data/proteins/MainChain_ALA_ALA.pdb +35 -0
  86. openff/toolkit/data/proteins/MainChain_ALA_ALA.sdf +69 -0
  87. openff/toolkit/data/proteins/MainChain_ALA_ALA_icodes.pdb +35 -0
  88. openff/toolkit/data/proteins/MainChain_ALA_ALA_no_hydrogens.pdb +17 -0
  89. openff/toolkit/data/proteins/MainChain_ARG.pdb +39 -0
  90. openff/toolkit/data/proteins/MainChain_ARG.sdf +81 -0
  91. openff/toolkit/data/proteins/MainChain_CYM.pdb +25 -0
  92. openff/toolkit/data/proteins/MainChain_CYS.pdb +26 -0
  93. openff/toolkit/data/proteins/MainChain_CYX.pdb +48 -0
  94. openff/toolkit/data/proteins/MainChain_CYX.sdf +96 -0
  95. openff/toolkit/data/proteins/MainChain_GLH.sdf +64 -0
  96. openff/toolkit/data/proteins/MainChain_GLU.sdf +63 -0
  97. openff/toolkit/data/proteins/MainChain_HID.pdb +32 -0
  98. openff/toolkit/data/proteins/MainChain_HIE.pdb +32 -0
  99. openff/toolkit/data/proteins/MainChain_HIE.sdf +67 -0
  100. openff/toolkit/data/proteins/MainChain_HIP.pdb +33 -0
  101. openff/toolkit/data/proteins/MainChain_HIP.sdf +70 -0
  102. openff/toolkit/data/proteins/MainChain_PRO.pdb +29 -0
  103. openff/toolkit/data/proteins/MainChain_TRP.pdb +39 -0
  104. openff/toolkit/data/proteins/NTerminal_ALA.pdb +21 -0
  105. openff/toolkit/data/proteins/NTerminal_ALA.sdf +45 -0
  106. openff/toolkit/data/proteins/NTerminal_ALA_ALA.pdb +31 -0
  107. openff/toolkit/data/proteins/NTerminal_ARG.pdb +35 -0
  108. openff/toolkit/data/proteins/NTerminal_TRP.pdb +35 -0
  109. openff/toolkit/data/proteins/T4-protein-unprocessed-4w51.pdb +1892 -0
  110. openff/toolkit/data/proteins/T4-protein.mol2 +5461 -0
  111. openff/toolkit/data/proteins/T4-protein.pdb +2637 -0
  112. openff/toolkit/data/proteins/T4-protein.sdf +5318 -0
  113. openff/toolkit/data/proteins/T4_protein_waters.pdb +2965 -0
  114. openff/toolkit/data/proteins/TwoMol_SER_CYS.pdb +50 -0
  115. openff/toolkit/data/proteins/aa_residues_substructures_explicit_bond_orders_with_caps.json +6435 -0
  116. openff/toolkit/data/proteins/aa_residues_substructures_explicit_bond_orders_with_caps_explicit_connectivity.json +6675 -0
  117. openff/toolkit/data/proteins/aa_residues_substructures_with_caps.json +6297 -0
  118. openff/toolkit/data/proteins/ace-ZZZ-gly-nme.pdb +78 -0
  119. openff/toolkit/data/proteins/ace-ZZZ-gly-nme.sdf +98 -0
  120. openff/toolkit/data/proteins/ace-a10-nme.sdf +229 -0
  121. openff/toolkit/data/proteins/ace-ala-nh2.pdb +21 -0
  122. openff/toolkit/data/proteins/fluoresceine_dyed_helix_capped.pdb +338 -0
  123. openff/toolkit/data/proteins/neutral_arginine.pdb +31 -0
  124. openff/toolkit/data/proteins/split_chain.pdb +74 -0
  125. openff/toolkit/data/proteins/split_chain_reordered.pdb +74 -0
  126. openff/toolkit/data/reference_energies/README.md +6 -0
  127. openff/toolkit/data/reference_energies/reference_0.8.0.json +1 -0
  128. openff/toolkit/data/reference_energies/reference_0.8.0.json.txt +180 -0
  129. openff/toolkit/data/reference_energies/reference_after_1007.json +1 -0
  130. openff/toolkit/data/reference_energies/reference_after_1007.json.txt +350 -0
  131. openff/toolkit/data/reference_energies/reference_after_802.json +1 -0
  132. openff/toolkit/data/reference_energies/reference_after_802.json.txt +291 -0
  133. openff/toolkit/data/systems/README.md +3 -0
  134. openff/toolkit/data/systems/amber/cyclohexane_ethanol_0.4_0.6.inpcrd +1511 -0
  135. openff/toolkit/data/systems/amber/cyclohexane_ethanol_0.4_0.6.prmtop +13367 -0
  136. openff/toolkit/data/systems/monomers/butanol.mol2 +38 -0
  137. openff/toolkit/data/systems/monomers/butanol.sdf +88 -0
  138. openff/toolkit/data/systems/monomers/cyclohexane.mol2 +45 -0
  139. openff/toolkit/data/systems/monomers/cyclohexane.sdf +105 -0
  140. openff/toolkit/data/systems/monomers/ethanol.mol2 +26 -0
  141. openff/toolkit/data/systems/monomers/ethanol.sdf +58 -0
  142. openff/toolkit/data/systems/monomers/methane.mol2 +18 -0
  143. openff/toolkit/data/systems/monomers/methane.sdf +38 -0
  144. openff/toolkit/data/systems/monomers/propane.mol2 +30 -0
  145. openff/toolkit/data/systems/monomers/propane.sdf +68 -0
  146. openff/toolkit/data/systems/monomers/tip3p_water.mol2 +14 -0
  147. openff/toolkit/data/systems/monomers/water.mol2 +14 -0
  148. openff/toolkit/data/systems/monomers/water.sdf +28 -0
  149. openff/toolkit/data/systems/packmol_boxes/cyclohexane_ethanol_0.4_0.6.pdb +6272 -0
  150. openff/toolkit/data/systems/packmol_boxes/cyclohexane_water.pdb +5524 -0
  151. openff/toolkit/data/systems/packmol_boxes/ethanol_water.pdb +5174 -0
  152. openff/toolkit/data/systems/packmol_boxes/propane_methane_butanol_0.2_0.3_0.5.pdb +7959 -0
  153. openff/toolkit/data/systems/test_systems/1_cyclohexane_1_ethanol.pdb +61 -0
  154. openff/toolkit/data/systems/test_systems/1_ethanol.pdb +24 -0
  155. openff/toolkit/data/systems/test_systems/1_ethanol_no_conect.pdb +15 -0
  156. openff/toolkit/data/systems/test_systems/1_ethanol_reordered.pdb +24 -0
  157. openff/toolkit/data/systems/test_systems/PE.pdb +67 -0
  158. openff/toolkit/data/systems/test_systems/README.md +3 -0
  159. openff/toolkit/data/systems/test_systems/T4_lysozyme_water_ions.pdb +29240 -0
  160. openff/toolkit/data/test_forcefields/Frosst_AlkEthOH.offxml +61 -0
  161. openff/toolkit/data/test_forcefields/Frosst_AlkEthOH_GBSA.offxml +78 -0
  162. openff/toolkit/data/test_forcefields/Frosst_AlkEthOH_MDL.offxml +62 -0
  163. openff/toolkit/data/test_forcefields/Frosst_AlkEthOH_parmAtFrosst.offxml +64 -0
  164. openff/toolkit/data/test_forcefields/GBSA_HCT-1.0.offxml +21 -0
  165. openff/toolkit/data/test_forcefields/GBSA_OBC1-1.0.offxml +18 -0
  166. openff/toolkit/data/test_forcefields/GBSA_OBC2-1.0.offxml +18 -0
  167. openff/toolkit/data/test_forcefields/README.md +23 -0
  168. openff/toolkit/data/test_forcefields/ammonia_minimal.offxml +27 -0
  169. openff/toolkit/data/test_forcefields/benzene_minimal.offxml +29 -0
  170. openff/toolkit/data/test_forcefields/chargeincrement-test.offxml +16 -0
  171. openff/toolkit/data/test_forcefields/frcmod.Frosst_AlkEthOH_withIDs +85 -0
  172. openff/toolkit/data/test_forcefields/ion_charges.offxml +18 -0
  173. openff/toolkit/data/test_forcefields/mangled.offxml +9 -0
  174. openff/toolkit/data/test_forcefields/old/README.md +9 -0
  175. openff/toolkit/data/test_forcefields/old/hbonds.offxml +11 -0
  176. openff/toolkit/data/test_forcefields/old/test_ff_0_0_2_spec_0_1.offxml +332 -0
  177. openff/toolkit/data/test_forcefields/old/test_ff_0_0_2_spec_0_2.offxml +338 -0
  178. openff/toolkit/data/test_forcefields/old/test_ff_0_0_2_spec_0_3.offxml +329 -0
  179. openff/toolkit/data/test_forcefields/old/test_ff_0_0_4_fixed_spec_0_1.offxml +342 -0
  180. openff/toolkit/data/test_forcefields/old/test_ff_0_0_4_fixed_spec_0_2.offxml +348 -0
  181. openff/toolkit/data/test_forcefields/old/test_ff_0_0_4_fixed_spec_0_3.offxml +337 -0
  182. openff/toolkit/data/test_forcefields/old/test_ff_0_0_4_spec_0_1.offxml +340 -0
  183. openff/toolkit/data/test_forcefields/old/test_ff_0_0_4_spec_0_2.offxml +346 -0
  184. openff/toolkit/data/test_forcefields/old/test_ff_0_0_4_spec_0_3.offxml +337 -0
  185. openff/toolkit/data/test_forcefields/smirff99Frosst_reference_0_1_spec.offxml +349 -0
  186. openff/toolkit/data/test_forcefields/smirnoff99Frosst_experimental.offxml +343 -0
  187. openff/toolkit/data/test_forcefields/smirnoff99Frosst_reference_0_1_spec.offxml +349 -0
  188. openff/toolkit/data/test_forcefields/smirnoff99Frosst_reference_0_2_spec.offxml +356 -0
  189. openff/toolkit/data/test_forcefields/test_forcefield.offxml +346 -0
  190. openff/toolkit/data/test_forcefields/tip3p.offxml +22 -0
  191. openff/toolkit/data/test_forcefields/unsupported_smirnoff_version.offxml +9 -0
  192. openff/toolkit/topology/__init__.py +43 -0
  193. openff/toolkit/topology/_mm_molecule.py +663 -0
  194. openff/toolkit/topology/molecule.py +6102 -0
  195. openff/toolkit/topology/topology.py +2555 -0
  196. openff/toolkit/typing/__init__.py +1 -0
  197. openff/toolkit/typing/engines/__init__.py +1 -0
  198. openff/toolkit/typing/engines/smirnoff/__init__.py +31 -0
  199. openff/toolkit/typing/engines/smirnoff/forcefield.py +1440 -0
  200. openff/toolkit/typing/engines/smirnoff/io.py +234 -0
  201. openff/toolkit/typing/engines/smirnoff/parameters.py +3839 -0
  202. openff/toolkit/typing/engines/smirnoff/plugins.py +91 -0
  203. openff/toolkit/utils/__init__.py +57 -0
  204. openff/toolkit/utils/_viz.py +104 -0
  205. openff/toolkit/utils/ambertools_wrapper.py +507 -0
  206. openff/toolkit/utils/base_wrapper.py +268 -0
  207. openff/toolkit/utils/builtin_wrapper.py +136 -0
  208. openff/toolkit/utils/callback.py +187 -0
  209. openff/toolkit/utils/collections.py +247 -0
  210. openff/toolkit/utils/constants.py +18 -0
  211. openff/toolkit/utils/exceptions.py +766 -0
  212. openff/toolkit/utils/nagl_wrapper.py +164 -0
  213. openff/toolkit/utils/openeye_wrapper.py +2750 -0
  214. openff/toolkit/utils/rdkit_wrapper.py +3302 -0
  215. openff/toolkit/utils/serialization.py +466 -0
  216. openff/toolkit/utils/toolkit_registry.py +509 -0
  217. openff/toolkit/utils/toolkits.py +217 -0
  218. openff/toolkit/utils/utils.py +805 -0
  219. openff_toolkit-0.18.0.dist-info/METADATA +109 -0
  220. openff_toolkit-0.18.0.dist-info/RECORD +231 -0
  221. openff_toolkit-0.18.0.dist-info/WHEEL +5 -0
  222. openff_toolkit-0.18.0.dist-info/licenses/LICENSE +21 -0
  223. openff_toolkit-0.18.0.dist-info/top_level.txt +5 -0
  224. utilities/deprecated/convert_frosst/convert_frcmod_0.1.py +251 -0
  225. utilities/deprecated/convert_frosst/convert_frcmod_0.2.py +249 -0
  226. utilities/deprecated/convert_frosst/convert_frcmod_0.3.py +249 -0
  227. utilities/make_substructure_dict/_cif_to_substructure_dict.py +955 -0
  228. utilities/make_substructure_dict/_make_chemical_substructures.py +46 -0
  229. utilities/make_substructure_dict/_make_metadata_assignment_substructures.py +35 -0
  230. utilities/test_plugins/custom_plugins/handler_plugins.py +48 -0
  231. utilities/test_plugins/setup.py +19 -0
@@ -0,0 +1,268 @@
1
+ """
2
+ Base class for toolkit wrappers. Defines the public API and some shared methods
3
+ """
4
+
5
+ __all__ = ("ToolkitWrapper",)
6
+
7
+ from functools import wraps
8
+ from typing import TYPE_CHECKING, TypedDict
9
+
10
+ from openff.toolkit.utils.constants import DEFAULT_AROMATICITY_MODEL
11
+ from openff.toolkit.utils.exceptions import (
12
+ IncorrectNumConformersError,
13
+ IncorrectNumConformersWarning,
14
+ ToolkitUnavailableException,
15
+ )
16
+
17
+ if TYPE_CHECKING:
18
+ from openff.toolkit.topology.molecule import Molecule
19
+
20
+
21
+ class _ChargeSettings(TypedDict, total=False):
22
+ n_conformers: int
23
+ rec_confs: int
24
+ min_confs: int
25
+ max_confs: int # OpenEyeToolkitWrapper sometimes defines this as None
26
+ antechamber_keyword: str
27
+ oe_charge_method: str
28
+
29
+
30
+ def _mol_to_ctab_and_aro_key(self, molecule: "Molecule", aromaticity_model=DEFAULT_AROMATICITY_MODEL) -> str:
31
+ return f"{molecule.ordered_connection_table_hash()}-{aromaticity_model}"
32
+
33
+
34
+ class ToolkitWrapper:
35
+ """
36
+ Base class for wrappers around external software toolkits.
37
+
38
+ .. warning :: This API is experimental and subject to change.
39
+
40
+ See also
41
+ ========
42
+ ToolkitRegistry, OpenEyeToolkitWrapper, RDKitToolkitWrapper,
43
+ AmberToolsToolkitWrapper, NAGLToolkitWrapper, BuiltInToolkitWrapper
44
+
45
+ """
46
+
47
+ _is_available: bool | None = None # True if toolkit is available
48
+ _toolkit_version: str | None = None
49
+ _toolkit_name: str | None = None # Name of the toolkit
50
+ _toolkit_installation_instructions: str | None = None # Installation instructions for the toolkit
51
+ _supported_charge_methods: dict[str, _ChargeSettings] = dict()
52
+ _toolkit_file_read_formats: list[str] = list()
53
+ _toolkit_file_write_formats: list[str] = list()
54
+
55
+ # @staticmethod
56
+ # TODO: Right now, to access the class definition, I have to make this a classmethod
57
+ # and thereby call it with () on the outermost decorator. Is this wasting time? Are we caching
58
+ # the is_available results?
59
+ @classmethod
60
+ def requires_toolkit(cls): # remember cls is a ToolkitWrapper subclass here
61
+ def decorator(func):
62
+ @wraps(func)
63
+ def wrapped_function(*args, **kwargs):
64
+ if not cls.is_available():
65
+ msg = f"This function requires the {cls._toolkit_name} toolkit"
66
+ raise ToolkitUnavailableException(msg)
67
+ value = func(*args, **kwargs)
68
+ return value
69
+
70
+ return wrapped_function
71
+
72
+ return decorator
73
+
74
+ @property
75
+ def toolkit_name(self):
76
+ """
77
+ Return the name of the toolkit wrapped by this class as a str
78
+
79
+ .. warning :: This API is experimental and subject to change.
80
+
81
+ Returns
82
+ -------
83
+ toolkit_name
84
+ The name of the wrapped toolkit
85
+
86
+ """
87
+ return self.__class__._toolkit_name
88
+
89
+ @property
90
+ def toolkit_installation_instructions(self):
91
+ """
92
+ Instructions on how to install the wrapped toolkit.
93
+ """
94
+ return self._toolkit_installation_instructions
95
+
96
+ @property
97
+ def toolkit_file_read_formats(self):
98
+ """
99
+ List of file formats that this toolkit can read.
100
+ """
101
+ return self._toolkit_file_read_formats
102
+
103
+ @property
104
+ def toolkit_file_write_formats(self) -> list[str]:
105
+ """
106
+ List of file formats that this toolkit can write.
107
+ """
108
+ return self._toolkit_file_write_formats
109
+
110
+ @property
111
+ def supported_charge_methods(self) -> list[str]:
112
+ return [*self._supported_charge_methods.keys()]
113
+
114
+ @classmethod
115
+ def is_available(cls):
116
+ """
117
+ Check whether the corresponding toolkit can be imported
118
+
119
+ Returns
120
+ -------
121
+ is_installed
122
+ True if corresponding toolkit is installed, False otherwise.
123
+
124
+ """
125
+ return NotImplementedError
126
+
127
+ @property
128
+ def toolkit_version(self):
129
+ """
130
+ Return the version of the wrapped toolkit as a str
131
+
132
+ .. warning :: This API is experimental and subject to change.
133
+
134
+ Returns
135
+ -------
136
+ toolkit_version
137
+ The version of the wrapped toolkit
138
+
139
+ """
140
+ return self._toolkit_version
141
+
142
+ def from_file(self, file_path, file_format, allow_undefined_stereo=False):
143
+ """
144
+ Return an openff.toolkit.topology.Molecule from a file using this toolkit.
145
+
146
+ Parameters
147
+ ----------
148
+ file_path
149
+ The file to read the molecule from
150
+ file_format
151
+ Format specifier, usually file suffix (eg. 'MOL2', 'SMI')
152
+ Note that not all toolkits support all formats. Check
153
+ ToolkitWrapper.toolkit_file_read_formats for details.
154
+ allow_undefined_stereo
155
+ If false, raises an exception if any molecules contain undefined stereochemistry.
156
+ _cls
157
+ Molecule constructor
158
+ Returns
159
+ -------
160
+ molecules
161
+ a list of Molecule objects is returned.
162
+
163
+ """
164
+ return NotImplementedError
165
+
166
+ def from_file_obj(self, file_obj, file_format, allow_undefined_stereo=False, _cls=None):
167
+ """
168
+ Return an openff.toolkit.topology.Molecule from a file-like object (an object with
169
+ a ".read()" method using this toolkit.
170
+
171
+
172
+ Parameters
173
+ ----------
174
+ file_obj
175
+ The file-like object to read the molecule from
176
+ file_format
177
+ Format specifier, usually file suffix (eg. 'MOL2', 'SMI')
178
+ Note that not all toolkits support all formats. Check
179
+ ToolkitWrapper.toolkit_file_read_formats for details.
180
+ allow_undefined_stereo
181
+ If false, raises an exception if any molecules contain undefined stereochemistry.
182
+ If false, the function skips loading the molecule.
183
+ _cls
184
+ Molecule constructor
185
+
186
+ Returns
187
+ -------
188
+ molecules
189
+ a list of Molecule objects is returned.
190
+ """
191
+ return NotImplementedError
192
+
193
+ def _check_n_conformers(
194
+ self,
195
+ molecule: "Molecule",
196
+ partial_charge_method: str | None = None,
197
+ min_confs: int | None = None,
198
+ max_confs: int | None = None,
199
+ strict_n_conformers: bool = False,
200
+ ):
201
+ """
202
+ Private method for validating the number of conformers on a molecule prior to partial
203
+ charge calculation
204
+
205
+ Parameters
206
+ ----------
207
+ molecule
208
+ Molecule for which partial charges are to be computed
209
+ partial_charge_method
210
+ The name of the charge method being used
211
+ min_confs
212
+ The minimum number of conformers required to use this charge method
213
+ max_confs
214
+ The maximum number of conformers required to use this charge method
215
+ strict_n_conformers
216
+ Whether to raise an exception if an invalid number of conformers is provided.
217
+ If this is False and an invalid number of conformers is found, a warning will be raised.
218
+
219
+ Raises
220
+ ------
221
+ IncorrectNumConformersError
222
+ If the wrong number of conformers is attached to the input molecule, and
223
+ strict_n_conformers is True.
224
+ """
225
+ import warnings
226
+
227
+ n_confs = molecule.n_conformers
228
+ wrong_confs_msg = (
229
+ f"Molecule '{molecule}' has {n_confs} conformers, but charge method '{partial_charge_method}' expects"
230
+ )
231
+ exception_suffix = (
232
+ "You can disable this error by setting `strict_n_conformers=False' "
233
+ "when calling 'molecule.assign_partial_charges'."
234
+ )
235
+ # If there's no n_confs filter, then this molecule automatically passes
236
+ if min_confs is None and max_confs is None:
237
+ return
238
+ # If there's constraints on both ends, check both limits
239
+ elif min_confs is not None and max_confs is not None:
240
+ if not (min_confs <= n_confs <= max_confs):
241
+ if min_confs == max_confs:
242
+ wrong_confs_msg += f" exactly {min_confs}."
243
+ else:
244
+ wrong_confs_msg += f" between {min_confs} and {max_confs}."
245
+
246
+ else:
247
+ return
248
+ # If there's only a max constraint, check that
249
+ elif min_confs is not None and max_confs is None:
250
+ if not (min_confs <= n_confs):
251
+ wrong_confs_msg += f" at least {min_confs}."
252
+ else:
253
+ return
254
+ # If there's only a maximum constraint, check that
255
+ elif min_confs is None and max_confs is not None:
256
+ if not (n_confs <= max_confs):
257
+ wrong_confs_msg += f" at most {max_confs}."
258
+ else:
259
+ return
260
+ # If we've made it this far, the molecule has the wrong number of conformers
261
+ if strict_n_conformers:
262
+ wrong_confs_msg += exception_suffix
263
+ raise IncorrectNumConformersError(wrong_confs_msg)
264
+ else:
265
+ warnings.warn(wrong_confs_msg, IncorrectNumConformersWarning, stacklevel=2)
266
+
267
+ def __repr__(self):
268
+ return f"ToolkitWrapper around {self.toolkit_name} version {self.toolkit_version}"
@@ -0,0 +1,136 @@
1
+ """
2
+ Built-in ToolkitWrapper for very basic functionality. Intended for testing and not much more.
3
+ """
4
+
5
+ __all__ = ("BuiltInToolkitWrapper",)
6
+
7
+ from typing import TYPE_CHECKING
8
+
9
+ from openff.toolkit import Quantity, unit
10
+ from openff.toolkit.utils import base_wrapper
11
+ from openff.toolkit.utils.exceptions import ChargeMethodUnavailableError
12
+ from openff.toolkit.utils.utils import inherit_docstrings
13
+
14
+ if TYPE_CHECKING:
15
+ from openff.toolkit.topology.molecule import FrozenMolecule
16
+
17
+
18
+ @inherit_docstrings
19
+ class BuiltInToolkitWrapper(base_wrapper.ToolkitWrapper):
20
+ """
21
+ Built-in ToolkitWrapper for very basic functionality. Intended for testing and not much more.
22
+
23
+ .. warning :: This API is experimental and subject to change.
24
+ """
25
+
26
+ _toolkit_name = "Built-in Toolkit"
27
+ _toolkit_installation_instructions = (
28
+ "This toolkit is installed with the Open Force Field Toolkit and does not require additional dependencies."
29
+ )
30
+ _supported_charge_methods = {
31
+ "zeros": {"rec_confs": 0, "min_confs": 0, "max_confs": 0},
32
+ "formal_charge": {"rec_confs": 0, "min_confs": 0, "max_confs": 0},
33
+ }
34
+
35
+ PARTIAL_CHARGE_METHODS = _supported_charge_methods
36
+
37
+ def __init__(self):
38
+ super().__init__()
39
+
40
+ def assign_partial_charges(
41
+ self,
42
+ molecule: "FrozenMolecule",
43
+ partial_charge_method: str | None = None,
44
+ use_conformers: Quantity | None = None,
45
+ strict_n_conformers: bool = False,
46
+ normalize_partial_charges: bool = True,
47
+ _cls: type | None = None,
48
+ ):
49
+ """
50
+
51
+ Compute partial charges with the built-in toolkit using simple arithmetic operations,
52
+ and assign the new values to the partial_charges attribute.
53
+
54
+
55
+ .. warning :: This API is experimental and subject to change.
56
+
57
+ Parameters
58
+ ----------
59
+ molecule
60
+ Molecule for which partial charges are to be computed
61
+ partial_charge_method
62
+ The charge model to use. One of ['zeros', 'formal_charge']. If None, 'formal_charge'
63
+ will be used.
64
+ use_conformers
65
+ (n_atoms, 3) and dimension of distance. Optional, default = None
66
+ Coordinates to use for partial charge calculation. If None, an appropriate number
67
+ of conformers will be generated.
68
+ strict_n_conformers
69
+ Whether to raise an exception if an invalid number of conformers is provided for the
70
+ given charge method.
71
+ If this is False and an invalid number of conformers is found, a warning will be raised
72
+ instead of an Exception.
73
+ normalize_partial_charges
74
+ Whether to offset partial charges so that they sum to the total formal charge of the molecule.
75
+ This is used to prevent accumulation of rounding errors when the partial charge generation method has
76
+ low precision.
77
+ _cls
78
+ Molecule constructor
79
+
80
+ Raises
81
+ ------
82
+ ChargeMethodUnavailableError if this toolkit cannot handle the requested charge method
83
+
84
+ IncorrectNumConformersError if strict_n_conformers is True and use_conformers is provided
85
+ and specifies an invalid number of conformers for the requested method
86
+
87
+ ChargeCalculationError if the charge calculation is supported by this toolkit, but fails
88
+ """
89
+
90
+ if partial_charge_method is None:
91
+ partial_charge_method = "formal_charge"
92
+
93
+ if _cls is None:
94
+ from openff.toolkit.topology.molecule import Molecule
95
+
96
+ _cls = Molecule
97
+
98
+ # Make a temporary copy of the molecule, since we'll be messing with its conformers
99
+ mol_copy = _cls(molecule)
100
+
101
+ partial_charge_method = partial_charge_method.lower()
102
+ if partial_charge_method not in self._supported_charge_methods:
103
+ raise ChargeMethodUnavailableError(
104
+ f'Partial charge method "{partial_charge_method}"" is not supported by '
105
+ f"the Built-in toolkit. Available charge methods are "
106
+ f"{self._supported_charge_methods}"
107
+ )
108
+
109
+ if use_conformers is None:
110
+ # Note that this refers back to the GLOBAL_TOOLKIT_REGISTRY by default, since
111
+ # BuiltInToolkitWrapper can't generate conformers
112
+ mol_copy.generate_conformers(
113
+ n_conformers=self._supported_charge_methods[partial_charge_method]["rec_confs"]
114
+ )
115
+ else:
116
+ mol_copy._conformers = None
117
+ for conformer in use_conformers: # type: ignore[attr-defined]
118
+ mol_copy._add_conformer(conformer)
119
+ self._check_n_conformers(
120
+ mol_copy,
121
+ partial_charge_method=partial_charge_method,
122
+ min_confs=0,
123
+ max_confs=0,
124
+ strict_n_conformers=strict_n_conformers,
125
+ )
126
+
127
+ if partial_charge_method == "zeros":
128
+ partial_charges = [0.0] * molecule.n_atoms
129
+
130
+ elif partial_charge_method == "formal_charge":
131
+ partial_charges = [float(atom.formal_charge.m) for atom in molecule.atoms] # type: ignore
132
+
133
+ molecule.partial_charges = Quantity(partial_charges, unit.elementary_charge)
134
+
135
+ if normalize_partial_charges:
136
+ molecule._normalize_partial_charges()
@@ -0,0 +1,187 @@
1
+ """
2
+ Utility classes and functions to create objects supporting callback registration.
3
+
4
+ """
5
+
6
+ __all__ = [
7
+ "Callbackable",
8
+ "callback_method",
9
+ ]
10
+
11
+
12
+ import functools
13
+ import inspect
14
+
15
+ from openff.toolkit.utils.exceptions import CallbackRegistrationError
16
+
17
+
18
+ def callback_method(func=None, events=()):
19
+ """Decorator used to mark a method as callbackable.
20
+
21
+ This decorator is designed to be used by ``Callbackable`` children
22
+ classes. Usage examples can be found in the documentation of ``Callbackable``.
23
+
24
+ Parameters
25
+ ----------
26
+ func : MethodType
27
+ The instance method to decorate. Static and class methods are
28
+ currently not supported.
29
+ events : Iterable[str]
30
+ The name of the callback events associated to this method.
31
+
32
+ See Also
33
+ --------
34
+ Callbackable
35
+
36
+ """
37
+
38
+ if func is None and len(events) > 0:
39
+ # Decorator called with @callback_method(events=[...]).
40
+ return functools.partial(callback_method, events=events)
41
+
42
+ @functools.wraps(func)
43
+ def callbacked_func(self, *args, **kwargs):
44
+ # Store the returned value.
45
+ returned_value = func(self, *args, **kwargs)
46
+ # Invoke callbacks that must be run after the function is executed.
47
+ self._raise_callback_events(func.__name__, *args, **kwargs)
48
+ return returned_value
49
+
50
+ # Assign an attribute so that we can distinguish between
51
+ # callbackable and not callbackable methods.
52
+ callbacked_func._callback_events = set(events)
53
+
54
+ return callbacked_func
55
+
56
+
57
+ class Callbackable:
58
+ """A base class for registering and handling callbacks.
59
+
60
+ The class allows easy implementation of classes that support the
61
+ registration of callback function when some instance methods are
62
+ called. Callback registered to static and class methods are currently
63
+ not supported.
64
+
65
+ The class allows callbacks to be registered to single methods or to
66
+ an event, which essentially provides a way to register the same callback
67
+ to multiple methods with a single line.
68
+
69
+ Callbacks are called after the function has been executed, and they
70
+ must have the signature
71
+
72
+ callback(callbackable, function_name, *args, **kwargs)
73
+
74
+ where ``callbackable`` is the ``Callbackable`` instance that raised
75
+ the event, ``function_name`` is the name of the function of ``callbackable``
76
+ that was called, and ``*args`` and ``**kwargs`` are the arguments that
77
+ were passed to the function.
78
+
79
+ Examples
80
+ --------
81
+
82
+ We define a callbackable list that allows registering callback
83
+ functions to methods that change the list. The first four methods
84
+ summarize the different ways in which the ``callback_method``
85
+ decorator can be used to mark a method for callback registration.
86
+
87
+ >>> class CallbackableList(Callbackable, list):
88
+ ...
89
+ ... @callback_method
90
+ ... def pop(self, *args, **kwargs):
91
+ ... super().pop(*args, **kwargs)
92
+ ...
93
+ ... @callback_method(events=['new_element'])
94
+ ... def extend(self, *args, **kwargs):
95
+ ... super().extend(*args, **kwargs)
96
+ ...
97
+ ... remove = callback_method(list.remove)
98
+ ... append = callback_method(list.append, events=['new_element'])
99
+ ...
100
+ ... insert = callback_method(list.insert, events=['new_element'])
101
+ ... __iadd__ = callback_method(list.__iadd__, events=['new_element'])
102
+ ... __setitem__ = callback_method(list.__setitem__, events=['new_element'])
103
+ ... __imul__ = callback_method(list.__imul__)
104
+ ... __delitem__ = callback_method(list.__delitem__)
105
+ ...
106
+
107
+ We can now register a callback to any of the callback methods.
108
+
109
+ >>> def callback(callbackable, func_name, *args, **kwargs):
110
+ ... print(f'callback: {func_name}{args}')
111
+ ...
112
+ >>> l = CallbackableList([1, 2, 3])
113
+ >>> l.register_callback('__delitem__', callback=callback)
114
+ >>> del l[2]
115
+ callback: __delitem__(2,)
116
+
117
+ We can also register a callback to a generic event associated to one
118
+ or more methods.
119
+
120
+ >>> l.register_callback('new_element', callback=callback)
121
+ >>> l.append(5)
122
+ callback: append(5,)
123
+ >>> l.insert(1, 5)
124
+ callback: insert(1, 5)
125
+
126
+ """
127
+
128
+ def __init__(self, *args, **kwargs):
129
+ # Map event_name -> list of callbacks.
130
+ self._callbacks = {}
131
+ # Forward arguments to the next class of the MRO to support multiple inheritance.
132
+ super().__init__(*args, **kwargs)
133
+
134
+ def register_callback(self, event_name, callback):
135
+ # Check if a callback can be registered for this function. Methods
136
+ # that are not decorated by @callback_method raise an error.
137
+ try:
138
+ attr = getattr(self, event_name)
139
+ except AttributeError:
140
+ # event_name may be an event name. This raises an exception
141
+ # if no method associated to this event is found.
142
+ self._check_event_exist(event_name)
143
+ else:
144
+ # Check if the attribute has been decorated.
145
+ try:
146
+ attr._callback_events
147
+ except AttributeError:
148
+ raise CallbackRegistrationError(
149
+ f"{self.__class__}.{event_name} is not tagged with the @callback_method decorator"
150
+ )
151
+
152
+ # Update the instance callbacks dictionary.
153
+ try:
154
+ self._callbacks[event_name].append(callback)
155
+ except KeyError:
156
+ self._callbacks[event_name] = [callback]
157
+
158
+ def _check_event_exist(self, event_name):
159
+ for member in inspect.getmembers(self):
160
+ # If this is not a callback_method, skip.
161
+ try:
162
+ events = member[1]._callback_events
163
+ except AttributeError:
164
+ continue
165
+
166
+ # If the event exist, return.
167
+ if event_name in events:
168
+ return
169
+
170
+ # The event wasn't found.
171
+ raise CallbackRegistrationError(
172
+ f'No method of {self.__class__} is associated to the callback event "{event_name}".'
173
+ )
174
+
175
+ def _raise_callback_events(self, func_name, *args, **kwargs):
176
+ events = getattr(self, func_name)._callback_events
177
+
178
+ # Retrieve all the callbacks associated to the function and its events.
179
+ for event_name in [func_name, *events]:
180
+ for callback in self._callbacks.get(event_name, ()):
181
+ callback(self, func_name, *args, **kwargs)
182
+
183
+
184
+ if __name__ == "__main__":
185
+ import doctest
186
+
187
+ doctest.run_docstring_examples(Callbackable, globals())