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,466 @@
1
+ """
2
+ Serialization mix-in
3
+
4
+ .. todo ::
5
+
6
+ Currently, the ``openff-toolkit`` toolkit package requires a number
7
+ of dependencies to support all of these serialization protocols.
8
+ Instead, should we not include these by default, and instead raise
9
+ a helpful exception with installation instructions if one of the
10
+ serialization schemes is called but the requisite library is not
11
+ installed?
12
+
13
+ """
14
+
15
+ import abc
16
+ from typing import TypeVar
17
+
18
+ from openff.toolkit.utils.utils import requires_package
19
+
20
+ S = TypeVar("S", bound="Serializable")
21
+
22
+
23
+ class Serializable(abc.ABC):
24
+ """Mix-in to add serialization and deserialization support via JSON, YAML, BSON, TOML, MessagePack, and XML.
25
+
26
+ For more information on these formats, see: `JSON <https://www.json.org/>`_,
27
+ `BSON <http://bsonspec.org/>`_, `YAML <http://yaml.org/>`_, `TOML <https://github.com/toml-lang/toml>`_,
28
+ `MessagePack <https://msgpack.org/index.html>`_, and `XML <https://www.w3.org/XML/>`_.
29
+
30
+ To use this mix-in, the class inheriting from this class must have implemented ``to_dict()`` and ``from_dict()``
31
+ methods that utilize dictionaries containing only serialiable Python objects.
32
+
33
+ .. warning ::
34
+
35
+ The serialization/deserialiation schemes used here place some strict constraints on what kinds of ``dict``
36
+ objects can be serialized. No effort is made to add further protection to ensure serialization is possible.
37
+ Use with caution.
38
+
39
+ Examples
40
+ --------
41
+
42
+ Example class using :class:`Serializable` mix-in:
43
+
44
+ >>> from openff.toolkit.utils.serialization import Serializable
45
+ >>> class Thing(Serializable):
46
+ ... def __init__(self, description):
47
+ ... self.description = description
48
+ ...
49
+ ... def to_dict(self):
50
+ ... return { 'description' : self.description }
51
+ ...
52
+ ... @classmethod
53
+ ... def from_dict(cls, d):
54
+ ... return cls(d['description'])
55
+ ...
56
+ >>> # Create an example object
57
+ >>> thing = Thing('blorb')
58
+
59
+ Get `JSON <https://www.json.org/>`_ representation:
60
+
61
+ >>> json_thing = thing.to_json()
62
+
63
+ Reconstruct an object from its `JSON <https://www.json.org/>`_ representation:
64
+
65
+ >>> thing_from_json = Thing.from_json(json_thing)
66
+
67
+ Get `BSON <http://bsonspec.org/>`_ representation:
68
+
69
+ >>> bson_thing = thing.to_bson()
70
+
71
+ Reconstruct an object from its `BSON <http://bsonspec.org/>`_ representation:
72
+
73
+ >>> thing_from_bson = Thing.from_bson(bson_thing)
74
+
75
+ Get `YAML <http://yaml.org/>`_ representation:
76
+
77
+ >>> yaml_thing = thing.to_yaml()
78
+
79
+ Reconstruct an object from its `YAML <http://yaml.org/>`_ representation:
80
+
81
+ >>> thing_from_yaml = Thing.from_yaml(yaml_thing)
82
+
83
+ Get `MessagePack <https://msgpack.org/index.html>`_ representation:
84
+
85
+ >>> messagepack_thing = thing.to_messagepack()
86
+
87
+ Reconstruct an object from its `MessagePack <https://msgpack.org/index.html>`_ representation:
88
+
89
+ >>> thing_from_messagepack = Thing.from_messagepack(messagepack_thing)
90
+
91
+ Get `XML <https://www.w3.org/XML/>`_ representation:
92
+
93
+ >>> xml_thing = thing.to_xml()
94
+
95
+ """
96
+
97
+ @abc.abstractmethod
98
+ def to_dict(self) -> dict:
99
+ pass
100
+
101
+ @classmethod
102
+ @abc.abstractmethod
103
+ def from_dict(cls: type[S], d: dict) -> S:
104
+ pass
105
+
106
+ def to_json(self, indent=None) -> str:
107
+ """
108
+ Return a JSON serialized representation.
109
+
110
+ Specification: https://www.json.org/
111
+
112
+ Parameters
113
+ ----------
114
+ indent
115
+ If not None, will pretty-print with specified number of spaces for indentation
116
+
117
+ Returns
118
+ -------
119
+ serialized
120
+ A JSON serialized representation of the object
121
+
122
+ """
123
+ import json
124
+
125
+ d = self.to_dict()
126
+
127
+ if _contains_bytes(d):
128
+ d = _prep_numpy_data_for_json(d)
129
+
130
+ return json.dumps(d, indent=indent)
131
+
132
+ @classmethod
133
+ def from_json(cls, serialized: str):
134
+ """
135
+ Instantiate an object from a JSON serialized representation.
136
+
137
+ Specification: https://www.json.org/
138
+
139
+ Parameters
140
+ ----------
141
+ serialized
142
+ A JSON serialized representation of the object
143
+
144
+ Returns
145
+ -------
146
+ instance
147
+ An instantiated object
148
+
149
+ """
150
+ import json
151
+
152
+ d = json.loads(serialized)
153
+ return cls.from_dict(d)
154
+
155
+ @requires_package("bson")
156
+ def to_bson(self):
157
+ """
158
+ Return a BSON serialized representation.
159
+
160
+ Specification: http://bsonspec.org/
161
+
162
+ Returns
163
+ -------
164
+ serialized
165
+ A BSON serialized representation of the objecft
166
+
167
+ """
168
+ import bson
169
+
170
+ d = self.to_dict()
171
+ return bson.dumps(d)
172
+
173
+ @classmethod
174
+ @requires_package("bson")
175
+ def from_bson(cls, serialized):
176
+ """
177
+ Instantiate an object from a BSON serialized representation.
178
+
179
+ Specification: http://bsonspec.org/
180
+
181
+ Parameters
182
+ ----------
183
+ serialized
184
+ A BSON serialized representation of the object
185
+
186
+ Returns
187
+ -------
188
+ instance
189
+ An instantiated object
190
+
191
+ """
192
+ import bson
193
+
194
+ d = bson.loads(serialized)
195
+ return cls.from_dict(d)
196
+
197
+ @requires_package("toml")
198
+ def to_toml(self):
199
+ """
200
+ Return a TOML serialized representation.
201
+
202
+ Specification: https://github.com/toml-lang/toml
203
+
204
+ Returns
205
+ -------
206
+ serialized
207
+ A TOML serialized representation of the object
208
+
209
+ """
210
+ raise NotImplementedError()
211
+ # TODO: This implementation currently discards dict keys associated to the None value.
212
+ # See test_utils_serialization::TestUtilsSMIRNOFFSerialization::test_toml.
213
+ # import toml
214
+ # d = self.to_dict()
215
+ # return toml.dumps(d)
216
+
217
+ @classmethod
218
+ @requires_package("toml")
219
+ def from_toml(cls, serialized):
220
+ """
221
+ Instantiate an object from a TOML serialized representation.
222
+
223
+ Specification: https://github.com/toml-lang/toml
224
+
225
+ Parameters
226
+ ----------
227
+ serlialized
228
+ A TOML serialized representation of the object
229
+
230
+ Returns
231
+ -------
232
+ instance
233
+ An instantiated object
234
+
235
+ """
236
+ import toml
237
+
238
+ d = toml.loads(serialized)
239
+ return cls.from_dict(d)
240
+
241
+ @requires_package("yaml")
242
+ def to_yaml(self):
243
+ """
244
+ Return a YAML serialized representation.
245
+
246
+ Specification: http://yaml.org/
247
+
248
+ Returns
249
+ -------
250
+ serialized
251
+ A YAML serialized representation of the object
252
+
253
+ """
254
+ import yaml
255
+
256
+ d = self.to_dict()
257
+ return yaml.safe_dump(d, width=180)
258
+
259
+ @classmethod
260
+ @requires_package("yaml")
261
+ def from_yaml(cls, serialized):
262
+ """
263
+ Instantiate from a YAML serialized representation.
264
+
265
+ Specification: http://yaml.org/
266
+
267
+ Parameters
268
+ ----------
269
+ serialized
270
+ A YAML serialized representation of the object
271
+
272
+ Returns
273
+ -------
274
+ instance
275
+ Instantiated object
276
+
277
+ """
278
+ import yaml
279
+
280
+ d = yaml.safe_load(serialized)
281
+ return cls.from_dict(d)
282
+
283
+ @requires_package("msgpack")
284
+ def to_messagepack(self):
285
+ """
286
+ Return a MessagePack representation.
287
+
288
+ Specification: https://msgpack.org/index.html
289
+
290
+ Returns
291
+ -------
292
+ serialized
293
+ A MessagePack-encoded bytes serialized representation of the object
294
+
295
+ """
296
+ import msgpack
297
+
298
+ d = self.to_dict()
299
+ return msgpack.dumps(d, use_bin_type=True)
300
+
301
+ @classmethod
302
+ @requires_package("msgpack")
303
+ def from_messagepack(cls, serialized):
304
+ """
305
+ Instantiate an object from a MessagePack serialized representation.
306
+
307
+ Specification: https://msgpack.org/index.html
308
+
309
+ Parameters
310
+ ----------
311
+ serialized
312
+ A MessagePack-encoded bytes serialized representation
313
+
314
+ Returns
315
+ -------
316
+ instance
317
+ Instantiated object.
318
+
319
+ """
320
+ import msgpack
321
+
322
+ d = msgpack.loads(serialized, raw=False)
323
+ return cls.from_dict(d)
324
+
325
+ def to_xml(self, indent=2):
326
+ """
327
+ Return an XML representation.
328
+
329
+ Specification: https://www.w3.org/XML/
330
+
331
+ Parameters
332
+ ----------
333
+ indent
334
+ If not None, will pretty-print with specified number of spaces for indentation
335
+
336
+ Returns
337
+ -------
338
+ serialized
339
+ A MessagePack-encoded bytes serialized representation.
340
+
341
+ """
342
+ import xmltodict
343
+
344
+ # An XML document requires one and only one root node.
345
+ root_name = self.__class__.__name__
346
+ d = {root_name: self.to_dict()}
347
+ # Configure indentation level.
348
+ if indent is not None:
349
+ pretty = True
350
+ indent = " " * indent
351
+ else:
352
+ pretty = False
353
+ # Convert data from dictionary to XML format.
354
+ return xmltodict.unparse(d, pretty=pretty, indent=indent)
355
+
356
+ @classmethod
357
+ def from_xml(cls, serialized):
358
+ """
359
+ Instantiate an object from an XML serialized representation.
360
+
361
+ Specification: https://www.w3.org/XML/
362
+
363
+ Parameters
364
+ ----------
365
+ serialized
366
+ An XML serialized representation
367
+
368
+ Returns
369
+ -------
370
+ instance
371
+ Instantiated object.
372
+
373
+ """
374
+ raise NotImplementedError()
375
+ # TODO: This implementation currently loads numbers as strings.
376
+ # See test_utils_serialization::TestUtilsSerialization::test_xml.
377
+ # import xmltodict
378
+ # d = xmltodict.parse(serialized)
379
+ # root_name = cls.__name__
380
+ # return cls.from_dict(d[root_name])
381
+
382
+ def to_pickle(self):
383
+ """
384
+ Return a pickle serialized representation.
385
+
386
+ .. warning ::
387
+
388
+ This is not recommended for safe, stable storage since the pickle specification
389
+ may change between Python versions.
390
+
391
+ Returns
392
+ -------
393
+ serialized
394
+ A pickled representation of the object
395
+
396
+ """
397
+ import pickle
398
+
399
+ d = self.to_dict()
400
+ return pickle.dumps(d)
401
+
402
+ @classmethod
403
+ def from_pickle(cls, serialized):
404
+ """
405
+ Instantiate an object from a pickle serialized representation.
406
+
407
+ .. warning ::
408
+
409
+ This is not recommended for safe, stable storage since the pickle specification
410
+ may change between Python versions.
411
+
412
+ Parameters
413
+ ----------
414
+ serialized
415
+ A pickled representation of the object
416
+
417
+ Returns
418
+ -------
419
+ instance
420
+ An instantiated object
421
+
422
+ """
423
+ import pickle
424
+
425
+ d = pickle.loads(serialized)
426
+ return cls.from_dict(d)
427
+
428
+
429
+ def _contains_bytes(val) -> bool:
430
+ """Report if any values in list are bytes."""
431
+ if val is None:
432
+ return False
433
+ elif isinstance(val, bytes):
434
+ return True
435
+ elif isinstance(val, int | float | str | bool):
436
+ return False
437
+ elif isinstance(val, list | tuple):
438
+ return any([_contains_bytes(x) for x in val])
439
+ elif isinstance(val, dict):
440
+ return any([_contains_bytes(x) for x in val.values()])
441
+ else:
442
+ raise ValueError(f"type {val}")
443
+
444
+
445
+ def _prep_numpy_data_for_json(data: dict) -> dict:
446
+ """Recursively search through a dict and convert the bytes fields to lists"""
447
+ import numpy as np
448
+
449
+ big_endian_float = np.dtype("float").newbyteorder(">")
450
+
451
+ for key, val in data.items():
452
+ if isinstance(val, np.ndarray):
453
+ data[key] = val.tolist()
454
+ if isinstance(val, dict):
455
+ data[key] = _prep_numpy_data_for_json(val)
456
+ if isinstance(val, bytes):
457
+ data[key] = np.frombuffer(val, dtype=big_endian_float).tolist()
458
+ if isinstance(val, list | tuple):
459
+ for i, element in enumerate(val):
460
+ if isinstance(element, bytes):
461
+ # Handles case of list[np.array], like Molecule.conformers
462
+ data[key][i] = np.frombuffer(element, dtype=big_endian_float).tolist()
463
+ elif isinstance(element, dict):
464
+ # Handles case of list[Molecule], like Topology.molecules
465
+ data[key][i] = _prep_numpy_data_for_json(element)
466
+ return data