Auto3D 3.2.1__tar.gz → 3.2.2__tar.gz

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 (252) hide show
  1. {auto3d-3.2.1/src/Auto3D.egg-info → auto3d-3.2.2}/PKG-INFO +4 -4
  2. {auto3d-3.2.1 → auto3d-3.2.2}/pyproject.toml +11 -4
  3. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/conformer_budget.py +36 -13
  4. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/energy.py +30 -9
  5. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/filtering.py +22 -7
  6. auto3d-3.2.2/src/Auto3D/domain/multiplicity.py +241 -0
  7. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/ranking.py +105 -35
  8. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/stereochemistry.py +2 -2
  9. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/batchopt.py +72 -12
  10. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/fire_optimizer.py +99 -12
  11. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/model_wrapper.py +64 -20
  12. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/optimization_engine.py +91 -5
  13. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/padding.py +47 -17
  14. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/isomers/factory.py +6 -0
  15. auto3d-3.2.2/src/Auto3D/engines/isomers/tautomers.py +692 -0
  16. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/model_factory.py +1 -1
  17. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/adapter/aimnet2.py +98 -8
  18. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/adapter/ani.py +36 -4
  19. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/adapter/base.py +54 -2
  20. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/adapter/custom.py +5 -1
  21. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/contract.py +111 -3
  22. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/policy.py +19 -10
  23. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/ASE/thermo/__init__.py +6 -2
  24. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/ASE/thermo/calculator.py +107 -19
  25. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/ASE/thermo/driver.py +113 -37
  26. auto3d-3.2.2/src/Auto3D/entry/ASE/thermo/properties.py +234 -0
  27. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/ASE/thermo/vibrations.py +17 -4
  28. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/SPE.py +16 -2
  29. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/auto3D.py +15 -2
  30. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/config.py +29 -10
  31. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/constants.py +84 -31
  32. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/utils/molprops.py +19 -2
  33. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/pipeline/input_checks.py +3 -3
  34. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/processors.py +5 -0
  35. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/workflow_workers.py +17 -1
  36. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/models.py +2 -1
  37. {auto3d-3.2.1 → auto3d-3.2.2/src/Auto3D.egg-info}/PKG-INFO +4 -4
  38. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D.egg-info/SOURCES.txt +4 -0
  39. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D.egg-info/requires.txt +3 -3
  40. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_SPE.py +1 -0
  41. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_adapter_atom_mask.py +15 -8
  42. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_batchopt.py +13 -19
  43. auto3d-3.2.2/tests/test_bench_scripts.py +520 -0
  44. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli_app.py +1 -1
  45. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_compile_values.py +5 -3
  46. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_config.py +12 -1
  47. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_config_parity.py +1 -1
  48. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_conformer_budget.py +47 -0
  49. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_custom_nnp_contract.py +78 -2
  50. auto3d-3.2.2/tests/test_docs_reproducibility.py +23 -0
  51. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_durability.py +2 -1
  52. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_filtering.py +46 -0
  53. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_fire_optimizer.py +39 -0
  54. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_isomer_engine_hardening.py +4 -2
  55. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_model_adapter.py +68 -0
  56. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_model_wrapper.py +11 -12
  57. auto3d-3.2.2/tests/test_multiplicity.py +236 -0
  58. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_notebook_properties.py +14 -4
  59. auto3d-3.2.2/tests/test_nse_multiplicity.py +478 -0
  60. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_optimization_engine.py +62 -5
  61. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_optimization_engine_indexing.py +94 -3
  62. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_padding.py +18 -15
  63. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_padding_invariance.py +2 -2
  64. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_processors.py +4 -1
  65. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_public_api.py +33 -4
  66. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_ranking.py +221 -0
  67. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_ranking_by_gibbs.py +24 -0
  68. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_record_policy_agreement.py +1 -0
  69. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_run_setup.py +1 -0
  70. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_smiles_stereo_warning.py +16 -37
  71. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_species_conversion.py +3 -3
  72. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_species_module.py +2 -2
  73. auto3d-3.2.2/tests/test_tautomer_mirror_images.py +506 -0
  74. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_tautomer_stereo.py +26 -10
  75. auto3d-3.2.2/tests/test_thermo_conventions.py +196 -0
  76. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo_helpers.py +9 -246
  77. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo_imaginary_mode_inversion.py +12 -1
  78. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo_relative_energies.py +22 -1
  79. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_utils_reconciliation.py +2 -2
  80. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_workflow.py +129 -1
  81. auto3d-3.2.1/src/Auto3D/engines/isomers/tautomers.py +0 -145
  82. auto3d-3.2.1/src/Auto3D/entry/ASE/thermo/properties.py +0 -398
  83. auto3d-3.2.1/tests/test_bench_scripts.py +0 -38
  84. auto3d-3.2.1/tests/test_docs_reproducibility.py +0 -12
  85. auto3d-3.2.1/tests/test_thermo_conventions.py +0 -105
  86. {auto3d-3.2.1 → auto3d-3.2.2}/LICENSE +0 -0
  87. {auto3d-3.2.1 → auto3d-3.2.2}/MANIFEST.in +0 -0
  88. {auto3d-3.2.1 → auto3d-3.2.2}/README.md +0 -0
  89. {auto3d-3.2.1 → auto3d-3.2.2}/setup.cfg +0 -0
  90. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/__init__.py +0 -0
  91. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/__init__.py +0 -0
  92. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/clash_relief.py +0 -0
  93. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/connectivity.py +0 -0
  94. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/convergence.py +0 -0
  95. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/embedding.py +0 -0
  96. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/geometry.py +0 -0
  97. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/id_mapping.py +0 -0
  98. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/stereo_check.py +0 -0
  99. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/domain/stereochemistry_smiles.py +0 -0
  100. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/__init__.py +0 -0
  101. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/__init__.py +0 -0
  102. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/isomers/__init__.py +0 -0
  103. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/isomers/base.py +0 -0
  104. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/isomers/omega.py +0 -0
  105. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/isomers/rdkit_sdf.py +0 -0
  106. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/isomers/rdkit_smi.py +0 -0
  107. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/__init__.py +0 -0
  108. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/adapter/__init__.py +0 -0
  109. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/adapter/compiling.py +0 -0
  110. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/adapter/validation.py +0 -0
  111. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/ani2xt.py +0 -0
  112. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/ani2xt_no_repulsion.pt +0 -0
  113. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/availability.py +0 -0
  114. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/loading.py +0 -0
  115. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/preflight.py +0 -0
  116. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/models/species.py +0 -0
  117. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/engines/torch_config.py +0 -0
  118. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/ASE/__init__.py +0 -0
  119. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/ASE/geometry.py +0 -0
  120. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/__init__.py +0 -0
  121. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/_run_setup.py +0 -0
  122. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/entry/tautomer.py +0 -0
  123. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/__init__.py +0 -0
  124. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/exceptions.py +0 -0
  125. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/process_lifecycle.py +0 -0
  126. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/registry.py +0 -0
  127. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/results.py +0 -0
  128. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/utils/__init__.py +0 -0
  129. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/utils/atomic_io.py +0 -0
  130. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/utils/logging_config.py +0 -0
  131. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/utils/output_guard.py +0 -0
  132. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/utils/output_names.py +0 -0
  133. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/utils/reconciliation.py +0 -0
  134. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/utils/sdf_io.py +0 -0
  135. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/foundation/utils/smi_io.py +0 -0
  136. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/__init__.py +0 -0
  137. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/chunk_manager.py +0 -0
  138. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/finalize.py +0 -0
  139. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/job_layout.py +0 -0
  140. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/pipeline/__init__.py +0 -0
  141. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/run_logging.py +0 -0
  142. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/supervisor.py +0 -0
  143. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/orchestration/workflow.py +0 -0
  144. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/__init__.py +0 -0
  145. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/auto3Dcli.py +0 -0
  146. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/__init__.py +0 -0
  147. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/app.py +0 -0
  148. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/__init__.py +0 -0
  149. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/config.py +0 -0
  150. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/properties.py +0 -0
  151. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/run.py +0 -0
  152. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/validate.py +0 -0
  153. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/config_schema.py +0 -0
  154. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/console.py +0 -0
  155. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/errors.py +0 -0
  156. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/progress.py +0 -0
  157. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/presentation/cli/results.py +0 -0
  158. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D/py.typed +0 -0
  159. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D.egg-info/dependency_links.txt +0 -0
  160. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D.egg-info/entry_points.txt +0 -0
  161. {auto3d-3.2.1 → auto3d-3.2.2}/src/Auto3D.egg-info/top_level.txt +0 -0
  162. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_adapter_fp64_contract.py +0 -0
  163. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_adapter_package_layout.py +0 -0
  164. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_adapter_template.py +0 -0
  165. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_ani2xt_atom_energies.py +0 -0
  166. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_ase_geometry.py +0 -0
  167. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_ase_torch_config.py +0 -0
  168. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_atomic_io.py +0 -0
  169. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_auto3D.py +0 -0
  170. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_auto3Dcli.py +0 -0
  171. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_available_cpu_count.py +0 -0
  172. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_chunk_manager.py +0 -0
  173. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli.py +0 -0
  174. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli_commands_config.py +0 -0
  175. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli_config_schema.py +0 -0
  176. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli_console.py +0 -0
  177. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli_errors.py +0 -0
  178. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli_exit_codes.py +0 -0
  179. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli_models_command.py +0 -0
  180. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli_property_commands.py +0 -0
  181. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli_results.py +0 -0
  182. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_cli_security.py +0 -0
  183. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_config_bounds.py +0 -0
  184. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_config_parallel_embedding.py +0 -0
  185. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_conftest_isolation_guards.py +0 -0
  186. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_connectivity.py +0 -0
  187. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_custom_nnp_eager.py +0 -0
  188. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_docs_compile_figures.py +0 -0
  189. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_e_tot_units.py +0 -0
  190. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_element_sets.py +0 -0
  191. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_embed_params.py +0 -0
  192. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_energy_constants.py +0 -0
  193. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_filtering_thermo_failed.py +0 -0
  194. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_geometry.py +0 -0
  195. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_helpers_pipeline_output.py +0 -0
  196. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_hessian_invocation_contract.py +0 -0
  197. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_id_mapping.py +0 -0
  198. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_import_boundaries.py +0 -0
  199. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_isomer_engine.py +0 -0
  200. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_isomers.py +0 -0
  201. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_job_layout.py +0 -0
  202. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_layer_boundaries.py +0 -0
  203. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_lazy_torchani_import.py +0 -0
  204. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_legacy_names.py +0 -0
  205. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_legacy_yaml_parity.py +0 -0
  206. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_logging_config.py +0 -0
  207. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_model_caching.py +0 -0
  208. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_model_factory.py +0 -0
  209. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_model_preflight.py +0 -0
  210. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_molprops.py +0 -0
  211. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_mp_start_method.py +0 -0
  212. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_no_aimnet.py +0 -0
  213. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_non_finite_rows.py +0 -0
  214. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_optimization_engine_validation.py +0 -0
  215. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_output_names.py +0 -0
  216. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_output_overwrite_gates.py +0 -0
  217. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_packaging_metadata.py +0 -0
  218. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_parallel_embed.py +0 -0
  219. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_pipeline_e2e.py +0 -0
  220. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_policy.py +0 -0
  221. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_preflight_registry_offline.py +0 -0
  222. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_progress.py +0 -0
  223. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_registry.py +0 -0
  224. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_results.py +0 -0
  225. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_sdf_isomer_enumeration.py +0 -0
  226. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_spe_energy_only.py +0 -0
  227. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_stereo_check_positions.py +0 -0
  228. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_stereo_identity.py +0 -0
  229. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_stereo_postopt.py +0 -0
  230. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_stereochemistry.py +0 -0
  231. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_stereochemistry_validation.py +0 -0
  232. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_suite_hygiene.py +0 -0
  233. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_tauto.py +0 -0
  234. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_tautomer_select.py +0 -0
  235. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo.py +0 -0
  236. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo_etot_sync.py +0 -0
  237. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo_linearity.py +0 -0
  238. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo_projection.py +0 -0
  239. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo_record_assertions.py +0 -0
  240. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo_reference.py +0 -0
  241. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo_temperature_validation.py +0 -0
  242. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_thermo_transition_state.py +0 -0
  243. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_torch_config.py +0 -0
  244. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_utils.py +0 -0
  245. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_utils_sdf_io.py +0 -0
  246. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_utils_smi_io.py +0 -0
  247. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_utils_validation.py +0 -0
  248. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_validate_run_parity.py +0 -0
  249. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_validation.py +0 -0
  250. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_validation_errors.py +0 -0
  251. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_worker_lifecycle.py +0 -0
  252. {auto3d-3.2.1 → auto3d-3.2.2}/tests/test_workflow_package_layout.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: Auto3D
3
- Version: 3.2.1
3
+ Version: 3.2.2
4
4
  Summary: Generating Low-energy 3D Conformers from SMILES/SDF
5
5
  Author-email: Zhen Liu <liu5@andrew.cmu.edu>, Tetiana Zubatiuk <tetiana@zubatyuk.com>, Adrian Roitberg <roitberg@ufl.edu>, Olexandr Isayev <olexandr@olexandrisayev.com>
6
6
  Maintainer-email: Olexandr Isayev <olexandr@olexandrisayev.com>
@@ -50,11 +50,11 @@ Requires-Dist: mypy>=1.0; extra == "dev"
50
50
  Requires-Dist: types-requests; extra == "dev"
51
51
  Requires-Dist: ruff==0.15.9; extra == "dev"
52
52
  Requires-Dist: pre-commit>=3.0; extra == "dev"
53
+ Requires-Dist: nbmake>=1.5; extra == "dev"
53
54
  Provides-Extra: docs
54
- Requires-Dist: sphinx>=7.0; extra == "docs"
55
- Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
55
+ Requires-Dist: sphinx>=7.1.0; extra == "docs"
56
+ Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
56
57
  Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
57
- Requires-Dist: myst-parser>=2.0; extra == "docs"
58
58
  Provides-Extra: all
59
59
  Requires-Dist: Auto3D[ani,ase,dev,docs]; extra == "all"
60
60
  Dynamic: license-file
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "Auto3D"
7
- version = "3.2.1"
7
+ version = "3.2.2"
8
8
  description = "Generating Low-energy 3D Conformers from SMILES/SDF"
9
9
  readme = "README.md"
10
10
  license = {text = "MIT"}
@@ -82,12 +82,19 @@ dev = [
82
82
  # `>=0.1.0` was the old floor, spanning every formatting style ruff has had.
83
83
  "ruff==0.15.9",
84
84
  "pre-commit>=3.0",
85
+ # Runs the one executed notebook in the slow CI job; installed with the
86
+ # rest so a resolver failure shows at install time, not seven minutes into
87
+ # the job.
88
+ "nbmake>=1.5",
85
89
  ]
90
+ # The floors the documentation build was actually resolved against, taken from
91
+ # the `docs/requirements.txt` this extra replaces. `myst-parser` is gone: it is
92
+ # not in `extensions` in docs/source/conf.py and no Markdown source is reached
93
+ # from docs/source/index.rst, so nothing ever loaded it.
86
94
  docs = [
87
- "sphinx>=7.0",
88
- "sphinx-rtd-theme>=1.3.0",
95
+ "sphinx>=7.1.0",
96
+ "sphinx-rtd-theme>=2.0.0",
89
97
  "nbsphinx>=0.9.0",
90
- "myst-parser>=2.0",
91
98
  ]
92
99
  all = [
93
100
  "Auto3D[ani,ase,dev,docs]",
@@ -12,6 +12,7 @@ from rdkit import Chem
12
12
  from rdkit.Chem import rdMolDescriptors
13
13
 
14
14
  from Auto3D.foundation.constants import (
15
+ CONFORMER_MIN_REQUEST,
15
16
  CONFORMER_MULTIPLIER,
16
17
  CONFORMER_ROTATABLE_COEFF,
17
18
  CONFORMER_ROTATABLE_EXP,
@@ -24,10 +25,11 @@ __all__ = ["calculate_conformer_count"]
24
25
  def calculate_conformer_count(mol: Chem.Mol) -> int:
25
26
  """Calculate the number of conformers to generate for a molecule.
26
27
 
27
- Uses a formula based on the number of rotatable bonds, with a minimum
28
- of the heavy atom count and a maximum cap. The result is floored at 1 so
29
- a molecule never gets 0 conformers (which would silently drop tiny species
30
- such as ``[H+]`` or a lone atom from the pipeline).
28
+ Uses a formula based on the number of rotatable bonds, with a minimum of
29
+ 16 for a molecule with two or more heavy atoms (or the heavy-atom count,
30
+ if larger) and a maximum cap. The result is floored at 1 so a molecule
31
+ never gets 0 conformers (which would silently drop tiny species such as
32
+ ``[H+]`` or a lone atom from the pipeline).
31
33
 
32
34
  Rotatable bonds are counted on the heavy-atom graph (``Chem.RemoveAllHs``,
33
35
  which also drops isotope-labeled hydrogens) using RDKit's default
@@ -55,14 +57,33 @@ def calculate_conformer_count(mol: Chem.Mol) -> int:
55
57
  agree on the same request; a caller that wants the larger pool back asks
56
58
  for it explicitly with ``max_confs``.
57
59
 
58
- Formula: min(max(1, num_heavy, 2 * 8.481 * (num_rotatable ** 1.642)), 1000)
59
- The formula is Auto3D's own rule, adapted from Chan, Morris and Hutchison
60
- (J. Chem. Theory Comput. 2021, 17, 2099-2106): the rotatable-bond
61
- coefficient and exponent are cited to that work, the factor of 2 and the
62
- heavy-atom floor are Auto3D's choices. None of the three has been checked
63
- against the paper's text (a conformational-entropy study).
64
-
65
- Reference: https://doi.org/10.1021/acs.jctc.0c01213
60
+ Formula: `min(max(1, 16 if num_heavy >= 2 else 1, num_heavy, 2 * 8.481 *
61
+ (num_rotatable ** 1.642)), 1000)`. The rotatable-bond coefficient 8.481 and
62
+ exponent 1.642 are the fitted constants of Chan, Morris and Hutchison (*J.
63
+ Chem. Theory Comput.* 2021, 17, 2099-2106,
64
+ `https://doi.org/10.1021/acs.jctc.0c01213`), whose published text is
65
+ paywalled. Checked against that work's deposited dataset
66
+ (`github.com/ghutchis/molecular-entropies`, 117,229 molecules from the COD,
67
+ ZINC, curated and peptide sets): a power-law least-squares fit over every
68
+ molecule with at least one rotatable bond returns 8.608 and 1.618 for the
69
+ mean number of distinct conformers retained within the widest energy window
70
+ that deposit records (about 5-6 units, almost certainly kcal/mol), counted
71
+ against RDKit's default (strict) rotatable-bond definition, the same count
72
+ used here. So the published expression estimates **how many low-energy
73
+ conformers a molecule has**, not how many embedding attempts recover them.
74
+ The factor of 2 is Auto3D's: against that same deposited data it turns the
75
+ fit's mean into a cover of roughly the 90th percentile of the per-molecule
76
+ spread (86-91% of molecules at 2-12 rotors), and it is canceled by the 1000
77
+ cap from 12 rotatable bonds up, where the cap alone decides the budget; the
78
+ unmultiplied fit itself exceeds the cap at 19 rotatable bonds. The constant
79
+ minimum of 16 is the budget the expression already gives a one-rotor
80
+ molecule, extended down to the rotor-free case because ring puckering is
81
+ not a rotatable bond: in that deposited data a molecule with no rotatable
82
+ bonds averages 25 retained conformers, more than a one-rotor molecule's 15.
83
+ The heavy-atom term is Auto3D's too and keeps large rigid polycyclics above
84
+ the constant floor. The 1000 cap is an operational ceiling, not a chemical
85
+ one; pass `max_confs` for a larger pool. The refit is recorded in
86
+ `benchmarks/results-notes/2026-10-14-conformer-budget-provenance.md`.
66
87
 
67
88
  Args:
68
89
  mol: RDKit molecule object (with or without hydrogens).
@@ -89,4 +110,6 @@ def calculate_conformer_count(mol: Chem.Mol) -> int:
89
110
 
90
111
  # Floor at 1: a heavy-atom-free species (e.g. [H+]) or a single atom must
91
112
  # still receive at least one conformer instead of being silently dropped.
92
- return min(max(1, num_heavy, formula_count), MAX_CONFORMERS_CAP)
113
+ # The constant minimum applies from two heavy atoms up (see constants.py).
114
+ minimum = CONFORMER_MIN_REQUEST if num_heavy >= 2 else 1
115
+ return min(max(1, minimum, num_heavy, formula_count), MAX_CONFORMERS_CAP)
@@ -19,9 +19,12 @@ twice.
19
19
  The fix is one unit for the property and one conversion boundary. Writers call
20
20
  :func:`set_e_tot_from_ev` (models produce eV); readers call :func:`e_tot_ev` /
21
21
  :func:`try_e_tot_ev` and get eV back, so every in-package energy tolerance
22
- (``DEFAULT_DUPLICATE_ENERGY_TOL``, ``DEFAULT_ENERGY_CLUSTER_WINDOW``, the
23
- kcal/mol -> eV window conversion in ``ranking``) keeps its documented eV
24
- meaning. Writers additionally set :data:`E_TOT_HARTREE_PROP`, the unit-labeled
22
+ (``DEFAULT_DUPLICATE_ENERGY_TOL``, ``DEFAULT_ENERGY_CLUSTER_WINDOW``) keeps
23
+ its documented eV meaning. The ranker is the one deliberate exception: it
24
+ reads the stored Hartree values through :func:`e_tot_hartree` /
25
+ :func:`gibbs_hartree`, forms each relative energy as a Hartree difference and
26
+ converts that difference, so its kcal/mol window is compared in kcal/mol.
27
+ Writers additionally set :data:`E_TOT_HARTREE_PROP`, the unit-labeled
25
28
  sibling, so a file states its own unit.
26
29
  """
27
30
 
@@ -60,6 +63,7 @@ __all__ = [
60
63
  "e_tot_ev",
61
64
  "try_e_tot_ev",
62
65
  "try_gibbs_ev",
66
+ "gibbs_hartree",
63
67
  # Conversion factors
64
68
  "HARTREE_TO_EV",
65
69
  "HARTREE_TO_KCAL_PER_MOL",
@@ -151,15 +155,26 @@ def try_e_tot_ev(mol: Chem.Mol) -> float | None:
151
155
  def try_gibbs_ev(mol: Chem.Mol) -> float | None:
152
156
  """``G_hartree`` in eV, or None when the record has no usable one.
153
157
 
154
- eV, not Hartree, so a caller can compare it against the same thresholds it
155
- already applies to :func:`e_tot_ev` -- the kcal/mol energy window in
156
- ``ranking`` converts to eV once and must not care which basis it is
157
- measuring. ``Auto3D.entry.ASE.thermo`` writes the underlying property.
158
+ Kept as a public name. Nothing in the package calls it since the ranker
159
+ started reading Gibbs energies in Hartree (:func:`gibbs_hartree`); a
160
+ caller that compares Gibbs energies against the eV thresholds it applies
161
+ to :func:`e_tot_ev` can still use it. ``Auto3D.entry.ASE.thermo`` writes
162
+ the underlying property.
158
163
  """
159
164
  value = _try_float_prop(mol, G_HARTREE_PROP)
160
165
  return None if value is None else value * HARTREE_TO_EV
161
166
 
162
167
 
168
+ def gibbs_hartree(mol: Chem.Mol) -> float:
169
+ """Return ``G_hartree`` in Hartree, the unit it is stored in.
170
+
171
+ Raises:
172
+ KeyError: The molecule has no ``G_hartree`` property.
173
+ ValueError: The property is not a number.
174
+ """
175
+ return float(mol.GetProp(G_HARTREE_PROP))
176
+
177
+
163
178
  def set_relative_energies(mols: Sequence[Chem.Mol]) -> None:
164
179
  """Write ``E_rel(kcal/mol)`` per conformer group, against the group minimum.
165
180
 
@@ -205,16 +220,22 @@ def set_relative_energies(mols: Sequence[Chem.Mol]) -> None:
205
220
  group member, and must not be the reference either.
206
221
  """
207
222
  for group in _comparable_groups(mols, E_REL_KCAL_PROP):
208
- with_energy = [(mol, try_e_tot_ev(mol)) for mol in group]
223
+ with_energy = [(mol, _try_float_prop(mol, E_TOT_PROP)) for mol in group]
209
224
  usable = [(mol, e) for mol, e in with_energy if e is not None]
210
225
  # A record with no readable E_tot cannot carry a relative one either.
211
226
  _clear_prop((mol for mol, e in with_energy if e is None), E_REL_KCAL_PROP)
212
227
  if not usable:
213
228
  continue
214
229
 
230
+ # Formed in Hartree, the stored unit, and converted once: two stored
231
+ # energies within a factor of two of each other subtract exactly in
232
+ # binary floating point, so the only rounding is the final product.
233
+ # Converting each absolute energy to eV first lost about ten digits to
234
+ # cancellation (the terms are the size of the absolute energy, the
235
+ # difference a few hundredths of an eV).
215
236
  reference = min(e for _, e in usable)
216
237
  for mol, energy in usable:
217
- mol.SetProp(E_REL_KCAL_PROP, str((energy - reference) * EV_TO_KCAL_PER_MOL))
238
+ mol.SetProp(E_REL_KCAL_PROP, str((energy - reference) * HARTREE_TO_KCAL_PER_MOL))
218
239
 
219
240
 
220
241
  def set_relative_gibbs_energies(mols: Sequence[Chem.Mol]) -> None:
@@ -182,6 +182,7 @@ def filter_conformers(
182
182
  *,
183
183
  rmsd_threshold: float = DEFAULT_RMSD_THRESHOLD,
184
184
  energy_cluster_window: float = DEFAULT_ENERGY_CLUSTER_WINDOW,
185
+ energy_tol: float = DEFAULT_DUPLICATE_ENERGY_TOL,
185
186
  ) -> FilterResult:
186
187
  """Remove duplicate conformers, skipping RMSD comparisons that cannot match.
187
188
 
@@ -194,8 +195,8 @@ def filter_conformers(
194
195
  A pair counts as a duplicate only when all three of these agree: the two are
195
196
  the same compound (:func:`Auto3D.domain.stereo_check.species_key`), their
196
197
  heavy-atom RMSD is under ``rmsd_threshold``, and their energies agree within
197
- ``DEFAULT_DUPLICATE_ENERGY_TOL`` (or at least one of them has no usable
198
- energy, in which case that term cannot apply and RMSD alone decides).
198
+ ``energy_tol`` (or at least one of them has no usable energy, in which case
199
+ that term cannot apply and RMSD alone decides).
199
200
 
200
201
  Args:
201
202
  mols: List of RDKit Mol objects with 'E_tot' (Hartree) and, optionally,
@@ -212,6 +213,17 @@ def filter_conformers(
212
213
  that tolerance is the floor at which a pair can still be a duplicate.
213
214
  The stored Hartree energies are converted to eV on read
214
215
  (``Auto3D.domain.energy``), so the unit is as documented.
216
+ energy_tol: Energy tolerance (eV) for the duplicate test, used both by
217
+ that test and as the lower bound on the run split below. How far
218
+ two optimizations of one minimum can land apart is a property of
219
+ the engine that produced the energies, so the value lives on that
220
+ engine's adapter (``Auto3D.engines.models.adapter``'s
221
+ ``duplicate_energy_tol``, which the orchestrator passes down);
222
+ this layer cannot know which engine that was and must not import
223
+ upward to find out, so the number arrives as a parameter. Every
224
+ adapter Auto3D ships carries the default below. Defaults to
225
+ ``Auto3D.foundation.constants.DEFAULT_DUPLICATE_ENERGY_TOL``, for
226
+ a caller with no adapter to ask.
215
227
 
216
228
  Returns:
217
229
  A :class:`FilterResult` whose ``kept`` list is sorted by energy (lowest
@@ -261,8 +273,8 @@ def filter_conformers(
261
273
  # survived, which is how a k=5 request came back with five slots holding two
262
274
  # distinct structures.
263
275
  #
264
- # A pair can only be a duplicate if its energies agree within
265
- # DEFAULT_DUPLICATE_ENERGY_TOL (`_filter_within_cluster` requires it). So a
276
+ # A pair can only be a duplicate if its energies agree within `energy_tol`
277
+ # (`_filter_within_cluster` requires it, with the same value). So a
266
278
  # run may end wherever the gap to the PREVIOUS molecule exceeds that
267
279
  # tolerance, and nowhere else: a gap that large proves no pair straddling it
268
280
  # can be a duplicate, and conversely, for any duplicate pair every gap
@@ -288,7 +300,7 @@ def filter_conformers(
288
300
  if any(energy is None for energy in energies):
289
301
  clusters: list[list[Chem.Mol]] = [valid_mols]
290
302
  else:
291
- split_gap = max(DEFAULT_DUPLICATE_ENERGY_TOL, energy_cluster_window)
303
+ split_gap = max(energy_tol, energy_cluster_window)
292
304
  clusters = []
293
305
  current_cluster: list[Chem.Mol] = [valid_mols[0]]
294
306
  previous_e = energies[0]
@@ -305,7 +317,7 @@ def filter_conformers(
305
317
  # Filter unique within each cluster
306
318
  unique_mols: list[Chem.Mol] = []
307
319
  for cluster in clusters:
308
- unique_in_cluster = _filter_within_cluster(cluster, rmsd_threshold)
320
+ unique_in_cluster = _filter_within_cluster(cluster, rmsd_threshold, energy_tol)
309
321
  unique_mols.extend(unique_in_cluster)
310
322
 
311
323
  n_duplicates = len(valid_mols) - len(unique_mols)
@@ -318,12 +330,14 @@ def filter_unique_optimized(
318
330
  mols: list[Chem.Mol],
319
331
  rmsd_threshold: float = DEFAULT_RMSD_THRESHOLD,
320
332
  energy_cluster_window: float = DEFAULT_ENERGY_CLUSTER_WINDOW,
333
+ energy_tol: float = DEFAULT_DUPLICATE_ENERGY_TOL,
321
334
  ) -> list[Chem.Mol]:
322
335
  """The surviving molecules from :func:`filter_conformers`, nothing else.
323
336
 
324
337
  Kept as the public name it has always been, for callers that want the list
325
338
  and not the drop counts. Prefer :func:`filter_conformers` when the reason
326
- something is missing has to reach a user.
339
+ something is missing has to reach a user. ``energy_tol`` means what it
340
+ means there, and is forwarded unchanged.
327
341
 
328
342
  Returns:
329
343
  List of unique molecules, sorted by energy (lowest first); records with
@@ -333,6 +347,7 @@ def filter_unique_optimized(
333
347
  mols,
334
348
  rmsd_threshold=rmsd_threshold,
335
349
  energy_cluster_window=energy_cluster_window,
350
+ energy_tol=energy_tol,
336
351
  ).kept
337
352
 
338
353
 
@@ -0,0 +1,241 @@
1
+ """The spin state the energy engines and the thermochemistry use for a molecule:
2
+ an explicit `multiplicity` property when it is valid, otherwise the high-spin
3
+ value from the radical-electron count.
4
+
5
+ Both callers resolve it per record -- the optimizer when it pads a bucket, the
6
+ thermochemistry when it stamps a record -- so the value a spin-aware model is
7
+ evaluated at and the value the electronic entropy is built from are the same
8
+ number read the same way.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from rdkit import Chem
14
+ from rdkit.Chem import rdmolops
15
+
16
+ from Auto3D.foundation.utils.logging_config import get_logger
17
+ from Auto3D.foundation.utils.molprops import record_name
18
+
19
+ logger = get_logger(__name__)
20
+
21
+ __all__ = ["resolve_multiplicity", "electron_count", "drawn_closed_shell_but_open_shell"]
22
+
23
+ _OPEN_SHELL_DRAWN_CLOSED = ("O=O",)
24
+ # Canonicalized once at import, not once per call: the predicate below is asked
25
+ # about every record of a bucket until the optimizer's notice has fired, and
26
+ # rebuilding this set each time parsed and canonicalized the same SMILES again
27
+ # for about 0.1 ms per record. The inputs are this module's own literals, so
28
+ # there is nothing here that can fail at import without the constant above
29
+ # being wrong.
30
+ _OPEN_SHELL_DRAWN_CLOSED_CANONICAL = frozenset(
31
+ Chem.MolToSmiles(Chem.MolFromSmiles(s)) for s in _OPEN_SHELL_DRAWN_CLOSED
32
+ )
33
+
34
+
35
+ def drawn_closed_shell_but_open_shell(mol: Chem.Mol) -> bool:
36
+ """True for known species whose closed-shell drawing hides an open shell.
37
+
38
+ Public because two callers need it: :func:`resolve_multiplicity` drives its
39
+ own per-record warning from it, and the optimizer asks it about a whole
40
+ bucket so a run over such species is flagged once rather than per record.
41
+ The resolver still returns 1 for them -- nothing in the graph says
42
+ otherwise -- so an explicit 'multiplicity' property is the only way to get
43
+ the ground state.
44
+
45
+ Caveat: singlet O2 (a real, if short-lived, excited state) is written with
46
+ the identical closed-shell SMILES/graph as ground-state triplet O2, so
47
+ this predicate cannot tell them apart -- the warning it drives may not
48
+ apply if the input was actually meant to represent singlet O2.
49
+ """
50
+ try:
51
+ canonical = Chem.MolToSmiles(Chem.RemoveHs(mol))
52
+ except (ValueError, RuntimeError):
53
+ return False
54
+ return canonical in _OPEN_SHELL_DRAWN_CLOSED_CANONICAL
55
+
56
+
57
+ def electron_count(mol: Chem.Mol) -> int:
58
+ """Total electron count: sum of atomic numbers minus the formal charge.
59
+
60
+ Sums over ``Chem.AddHs(mol)`` rather than ``mol`` directly: a mol built
61
+ without explicit hydrogens (e.g. straight from ``MolFromSmiles``, no
62
+ ``AddHs`` call) stores them only as an implicit-H count on each heavy
63
+ atom, not as their own ``Atom`` objects, so summing ``GetAtomicNum()``
64
+ over ``mol.GetAtoms()`` would silently skip every implicit hydrogen and
65
+ undercount electrons. ``Chem.AddHs`` returns a new mol (the input is not
66
+ mutated) and is idempotent when hydrogens are already explicit, so this
67
+ is correct either way.
68
+ """
69
+ return sum(a.GetAtomicNum() for a in Chem.AddHs(mol).GetAtoms()) - rdmolops.GetFormalCharge(mol)
70
+
71
+
72
+ def resolve_multiplicity(mol: Chem.Mol, *, warn_open_shell: bool = True) -> int:
73
+ """Spin multiplicity (2S+1): the spin state the energy engines and the thermochemistry use.
74
+
75
+ The thermochemistry reads it as IdealGasThermo's electronic-degeneracy
76
+ term; the optimizer and the single-point paths hand it to the model.
77
+
78
+ ``warn_open_shell=False`` silences the three open-shell warnings (the
79
+ high-spin assumption, the parity check on a derived value, the closed-shell
80
+ drawing of an open-shell species), for a caller that resolves every
81
+ conformer record of a run and reports once itself; the invalid-property
82
+ warning always fires because it names a defect in that record.
83
+
84
+ Resolving a record also CLEARS an invalid 'multiplicity' property from it,
85
+ a side effect both callers now share. The optimizer clears the invalid
86
+ property, warns once and writes the record without it, so a
87
+ thermochemistry run on the optimizer's output uses the derived value
88
+ silently; only a caller handing the same in-memory molecules to both paths
89
+ sees the warning twice.
90
+
91
+ Uses an explicit integer 'multiplicity' molecule property when present
92
+ and valid. An invalid one (unparseable, out of bounds, or the wrong
93
+ parity for the record's electron count) is dropped from ``mol`` with a
94
+ warning rather than left in place, so the record never advertises a
95
+ multiplicity that was not the one actually used. Otherwise derives it
96
+ from the radical-electron count (multiplicity = unpaired electrons + 1),
97
+ instead of silently assuming a closed-shell singlet -- which would zero
98
+ the electronic entropy term for every radical. This assumes high-spin
99
+ coupling of those radical electrons: an open-shell singlet (the same
100
+ radical count, but paired into S = 0, e.g. some diradicals) needs an
101
+ explicit 'multiplicity' property to override the high-spin default. The
102
+ derived value is returned but not written back onto ``mol``: no energy
103
+ engine reads the property, so recording it would only be a value a
104
+ re-run recomputes anyway. A spin-aware AIMNet2 model receives this value;
105
+ a model without a spin input ignores it and evaluates the molecule as a
106
+ closed shell.
107
+
108
+ The property is parsed with plain Python ``int()`` rather than RDKit's
109
+ ``GetUnsignedProp``: the latter parses as an *unsigned* C++ integer, so a
110
+ negative string like "-1" silently wraps around to 4294967295 (2**32 - 1)
111
+ and "0" parses cleanly to 0 -- neither of those failure modes raises, so a
112
+ try/except around ``GetUnsignedProp`` cannot catch them, and both then
113
+ flow into IdealGasThermo's ``R*ln(multiplicity)`` electronic-entropy term
114
+ as nonsense (spin = 2147483647.0 and -0.5, respectively). ``int()`` on the
115
+ same string preserves the sign, so both are correctly rejected as
116
+ multiplicities below the physically valid minimum of 1 (2S+1 for S >= 0).
117
+
118
+ The lower bound alone is not sufficient: ``int("4294967295")`` parses
119
+ cleanly (no wraparound -- that only afflicts ``GetUnsignedProp``) to a
120
+ huge but nominally ">= 1" value, which passed the lower-bound check
121
+ unchanged and fed spin = 2147483647.0 into ``R*ln(multiplicity)`` with no
122
+ warning, shifting Gibbs energy by 13.1 kcal/mol at 298.15 K. A
123
+ multiplicity is also bounded above: a molecule with ``n_electrons``
124
+ electrons cannot exceed multiplicity ``n_electrons + 1`` (every electron
125
+ unpaired), and 2S+1 must have parity opposite the electron count --
126
+ integer S (odd multiplicity) for an even-electron species, half-integer S
127
+ (even multiplicity) for an odd-electron one. Both the too-large and the
128
+ wrong-parity cases are rejected the same way as the too-small case:
129
+ warn and fall back to the radical-derived value.
130
+ """
131
+ if mol.HasProp("multiplicity"):
132
+ try:
133
+ value = int(mol.GetProp("multiplicity"))
134
+ except (ValueError, TypeError):
135
+ logger.warning(
136
+ "Molecule %s has an unparseable 'multiplicity' property; "
137
+ "deriving it from the radical-electron count instead and "
138
+ "dropping the property from the output record.",
139
+ record_name(mol),
140
+ )
141
+ mol.ClearProp("multiplicity")
142
+ else:
143
+ n_electrons = electron_count(mol)
144
+ max_multiplicity = n_electrons + 1
145
+ if value < 1:
146
+ logger.warning(
147
+ "Molecule %s has an invalid 'multiplicity' property (%d); "
148
+ "multiplicity must be >= 1 (2S+1 for spin S >= 0). "
149
+ "Deriving it from the radical-electron count instead and "
150
+ "dropping the property from the output record.",
151
+ record_name(mol),
152
+ value,
153
+ )
154
+ mol.ClearProp("multiplicity")
155
+ elif value > max_multiplicity:
156
+ logger.warning(
157
+ "Molecule %s has an invalid 'multiplicity' property (%d); "
158
+ "a %d-electron species cannot exceed multiplicity %d "
159
+ "(2S+1 with every electron unpaired). Deriving it from "
160
+ "the radical-electron count instead and dropping the "
161
+ "property from the output record.",
162
+ record_name(mol),
163
+ value,
164
+ n_electrons,
165
+ max_multiplicity,
166
+ )
167
+ mol.ClearProp("multiplicity")
168
+ elif value % 2 == n_electrons % 2:
169
+ logger.warning(
170
+ "Molecule %s has an invalid 'multiplicity' property (%d); "
171
+ "its parity is inconsistent with a %d-electron species "
172
+ "(2S+1 requires odd multiplicity for an even-electron "
173
+ "species, even multiplicity for an odd-electron one). "
174
+ "Deriving it from the radical-electron count instead and "
175
+ "dropping the property from the output record.",
176
+ record_name(mol),
177
+ value,
178
+ n_electrons,
179
+ )
180
+ mol.ClearProp("multiplicity")
181
+ else:
182
+ return value
183
+ n_radical = sum(a.GetNumRadicalElectrons() for a in mol.GetAtoms())
184
+ multiplicity = n_radical + 1
185
+ # The derived value gets the same parity check the supplied one gets.
186
+ # Both the bounds and parity checks above sit inside the `HasProp` branch, so
187
+ # a multiplicity Auto3D derived itself was returned unchecked -- and 2S+1
188
+ # requires odd multiplicity for an even-electron species and even for an
189
+ # odd-electron one, which the radical count can violate when the drawing is
190
+ # wrong (a valence-satisfied structure hiding an open shell). Getting it wrong
191
+ # is worth at least RT ln((m+1)/m) in T*S_elec -- 0.41 kcal/mol at 298 K
192
+ # for a doublet taken for a singlet.
193
+ #
194
+ # Warn-only, and deliberately so: unlike the supplied-value branch, there is
195
+ # no further fallback to take -- this IS the fallback. Silently substituting a
196
+ # parity-consistent guess would replace a wrong number the user can see with a
197
+ # wrong number they cannot.
198
+ #
199
+ # The electron count is computed inside the guard, not above it: it feeds
200
+ # only this warning here (the supplied-value branch above has its own
201
+ # call), and `electron_count` copies the molecule through `AddHs`, which a
202
+ # caller resolving every conformer record of a run quietly should not pay
203
+ # for a message it has silenced.
204
+ if warn_open_shell:
205
+ n_electrons = electron_count(mol)
206
+ if multiplicity % 2 == n_electrons % 2:
207
+ logger.warning(
208
+ "Molecule %s: the multiplicity derived from its radical-electron "
209
+ "count (%d) has a parity inconsistent with a %d-electron species "
210
+ "(2S+1 requires odd multiplicity for an even-electron species, even "
211
+ "for an odd-electron one). The drawing may hide an open shell. Set "
212
+ "the 'multiplicity' property explicitly; the electronic entropy term "
213
+ "is otherwise wrong by at least RT ln((m+1)/m) in T*S, "
214
+ "0.41 kcal/mol at 298 K for a doublet taken for a singlet.",
215
+ record_name(mol),
216
+ multiplicity,
217
+ n_electrons,
218
+ )
219
+ if n_radical > 0:
220
+ if warn_open_shell:
221
+ logger.warning(
222
+ "Molecule %s: open-shell species (%d unpaired electron(s)); "
223
+ "resolved to multiplicity %d, the high-spin value. Set the "
224
+ "'multiplicity' property to override it.",
225
+ record_name(mol),
226
+ n_radical,
227
+ multiplicity,
228
+ )
229
+ elif warn_open_shell and drawn_closed_shell_but_open_shell(mol):
230
+ # O=O draws as a closed-shell double bond and carries zero radical
231
+ # electrons, but its ground state is a triplet. Nothing in the graph
232
+ # distinguishes it, so the electronic entropy term is silently wrong
233
+ # unless the caller sets 'multiplicity' explicitly.
234
+ logger.warning(
235
+ "%s matches a species whose ground state is open-shell but whose "
236
+ "drawing is closed-shell; multiplicity 1 is assumed, a spin-aware "
237
+ "model evaluates the singlet state and the electronic entropy term "
238
+ "will be wrong. Set the 'multiplicity' property explicitly.",
239
+ record_name(mol),
240
+ )
241
+ return multiplicity