Auto3D 3.2.0__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 (262) hide show
  1. {auto3d-3.2.0/src/Auto3D.egg-info → auto3d-3.2.2}/PKG-INFO +7 -7
  2. {auto3d-3.2.0 → auto3d-3.2.2}/README.md +3 -3
  3. {auto3d-3.2.0 → auto3d-3.2.2}/pyproject.toml +31 -6
  4. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/__init__.py +3 -9
  5. auto3d-3.2.2/src/Auto3D/domain/clash_relief.py +176 -0
  6. auto3d-3.2.2/src/Auto3D/domain/conformer_budget.py +115 -0
  7. {auto3d-3.2.0/src/Auto3D/foundation/utils → auto3d-3.2.2/src/Auto3D/domain}/connectivity.py +54 -36
  8. {auto3d-3.2.0/src/Auto3D/foundation/utils → auto3d-3.2.2/src/Auto3D/domain}/convergence.py +2 -16
  9. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/domain/embedding.py +98 -82
  10. {auto3d-3.2.0/src/Auto3D/foundation/utils → auto3d-3.2.2/src/Auto3D/domain}/energy.py +127 -68
  11. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/domain/filtering.py +96 -54
  12. auto3d-3.2.2/src/Auto3D/domain/geometry.py +137 -0
  13. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/domain/id_mapping.py +26 -14
  14. auto3d-3.2.2/src/Auto3D/domain/multiplicity.py +241 -0
  15. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/domain/ranking.py +383 -202
  16. {auto3d-3.2.0/src/Auto3D/foundation/utils → auto3d-3.2.2/src/Auto3D/domain}/stereo_check.py +16 -7
  17. auto3d-3.2.2/src/Auto3D/domain/stereochemistry.py +238 -0
  18. auto3d-3.2.2/src/Auto3D/domain/stereochemistry_smiles.py +300 -0
  19. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/batchopt.py +259 -124
  20. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/fire_optimizer.py +108 -24
  21. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/model_wrapper.py +241 -71
  22. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/optimization_engine.py +155 -41
  23. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/padding.py +55 -26
  24. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/isomers/factory.py +57 -36
  25. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/isomers/omega.py +64 -19
  26. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/isomers/rdkit_sdf.py +32 -34
  27. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/isomers/rdkit_smi.py +47 -37
  28. auto3d-3.2.2/src/Auto3D/engines/isomers/tautomers.py +692 -0
  29. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/model_factory.py +100 -30
  30. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/models/__init__.py +3 -6
  31. auto3d-3.2.2/src/Auto3D/engines/models/adapter/__init__.py +38 -0
  32. auto3d-3.2.2/src/Auto3D/engines/models/adapter/aimnet2.py +350 -0
  33. auto3d-3.2.2/src/Auto3D/engines/models/adapter/ani.py +221 -0
  34. auto3d-3.2.2/src/Auto3D/engines/models/adapter/base.py +398 -0
  35. auto3d-3.2.2/src/Auto3D/engines/models/adapter/compiling.py +187 -0
  36. auto3d-3.2.2/src/Auto3D/engines/models/adapter/custom.py +120 -0
  37. auto3d-3.2.2/src/Auto3D/engines/models/adapter/validation.py +94 -0
  38. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/models/ani2xt.py +22 -47
  39. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/models/availability.py +2 -2
  40. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/models/contract.py +218 -67
  41. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/models/loading.py +17 -3
  42. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/models/policy.py +136 -66
  43. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/models/preflight.py +35 -35
  44. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/models/species.py +7 -16
  45. {auto3d-3.2.0/src/Auto3D/foundation → auto3d-3.2.2/src/Auto3D/engines}/torch_config.py +6 -6
  46. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/ASE/geometry.py +62 -28
  47. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/ASE/thermo/__init__.py +6 -2
  48. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/ASE/thermo/calculator.py +136 -47
  49. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/ASE/thermo/driver.py +460 -319
  50. auto3d-3.2.2/src/Auto3D/entry/ASE/thermo/properties.py +234 -0
  51. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/ASE/thermo/vibrations.py +58 -36
  52. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/SPE.py +29 -16
  53. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/_run_setup.py +22 -25
  54. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/auto3D.py +67 -56
  55. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/tautomer.py +43 -28
  56. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/config.py +208 -131
  57. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/constants.py +168 -51
  58. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/exceptions.py +23 -10
  59. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/process_lifecycle.py +11 -11
  60. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/results.py +44 -11
  61. auto3d-3.2.2/src/Auto3D/foundation/utils/__init__.py +39 -0
  62. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/utils/atomic_io.py +49 -19
  63. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/utils/logging_config.py +58 -0
  64. auto3d-3.2.2/src/Auto3D/foundation/utils/molprops.py +61 -0
  65. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/utils/output_guard.py +35 -27
  66. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/utils/output_names.py +2 -6
  67. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/utils/reconciliation.py +20 -10
  68. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/utils/sdf_io.py +98 -53
  69. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/utils/smi_io.py +81 -15
  70. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/orchestration/chunk_manager.py +132 -44
  71. auto3d-3.2.2/src/Auto3D/orchestration/finalize.py +242 -0
  72. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/orchestration/job_layout.py +34 -9
  73. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/orchestration/pipeline/input_checks.py +150 -94
  74. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/orchestration/processors.py +5 -0
  75. auto3d-3.2.2/src/Auto3D/orchestration/run_logging.py +187 -0
  76. auto3d-3.2.2/src/Auto3D/orchestration/supervisor.py +220 -0
  77. auto3d-3.2.2/src/Auto3D/orchestration/workflow.py +663 -0
  78. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/orchestration/workflow_workers.py +115 -49
  79. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/auto3Dcli.py +11 -28
  80. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/app.py +106 -59
  81. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/config.py +23 -31
  82. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/models.py +56 -33
  83. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/properties.py +8 -2
  84. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/run.py +147 -105
  85. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/validate.py +3 -3
  86. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/config_schema.py +37 -84
  87. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/console.py +2 -2
  88. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/errors.py +75 -19
  89. {auto3d-3.2.0 → auto3d-3.2.2/src/Auto3D.egg-info}/PKG-INFO +7 -7
  90. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D.egg-info/SOURCES.txt +37 -14
  91. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D.egg-info/requires.txt +3 -3
  92. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_SPE.py +3 -2
  93. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_adapter_atom_mask.py +23 -13
  94. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_adapter_fp64_contract.py +13 -3
  95. auto3d-3.2.2/tests/test_adapter_package_layout.py +38 -0
  96. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_ani2xt_atom_energies.py +2 -2
  97. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_ase_geometry.py +111 -17
  98. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_atomic_io.py +93 -6
  99. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_auto3Dcli.py +3 -1
  100. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_batchopt.py +190 -67
  101. auto3d-3.2.2/tests/test_bench_scripts.py +520 -0
  102. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_chunk_manager.py +270 -95
  103. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli.py +2 -2
  104. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli_app.py +101 -4
  105. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli_config_schema.py +56 -4
  106. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli_errors.py +18 -0
  107. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli_exit_codes.py +91 -32
  108. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli_property_commands.py +12 -0
  109. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_compile_values.py +98 -6
  110. auto3d-3.2.2/tests/test_config.py +355 -0
  111. auto3d-3.2.2/tests/test_config_bounds.py +204 -0
  112. auto3d-3.2.2/tests/test_config_parallel_embedding.py +251 -0
  113. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_config_parity.py +28 -19
  114. auto3d-3.2.0/tests/test_utils_molprops.py → auto3d-3.2.2/tests/test_conformer_budget.py +49 -2
  115. auto3d-3.2.0/tests/test_utils_connectivity.py → auto3d-3.2.2/tests/test_connectivity.py +74 -11
  116. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_custom_nnp_contract.py +148 -3
  117. auto3d-3.2.2/tests/test_docs_reproducibility.py +23 -0
  118. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_durability.py +213 -16
  119. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_e_tot_units.py +22 -29
  120. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_embed_params.py +1 -1
  121. auto3d-3.2.2/tests/test_energy_constants.py +76 -0
  122. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_filtering.py +81 -5
  123. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_filtering_thermo_failed.py +1 -1
  124. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_fire_optimizer.py +41 -3
  125. auto3d-3.2.2/tests/test_geometry.py +112 -0
  126. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_helpers_pipeline_output.py +30 -2
  127. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_hessian_invocation_contract.py +13 -9
  128. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_id_mapping.py +24 -5
  129. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_import_boundaries.py +41 -10
  130. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_isomer_engine.py +2 -2
  131. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_isomer_engine_hardening.py +110 -21
  132. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_isomers.py +39 -16
  133. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_job_layout.py +31 -0
  134. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_layer_boundaries.py +67 -23
  135. auto3d-3.2.2/tests/test_legacy_names.py +27 -0
  136. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_legacy_yaml_parity.py +3 -1
  137. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_logging_config.py +74 -0
  138. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_model_adapter.py +73 -1
  139. auto3d-3.2.2/tests/test_model_caching.py +230 -0
  140. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_model_factory.py +29 -6
  141. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_model_preflight.py +2 -2
  142. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_model_wrapper.py +188 -50
  143. auto3d-3.2.2/tests/test_molprops.py +30 -0
  144. auto3d-3.2.2/tests/test_multiplicity.py +236 -0
  145. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_no_aimnet.py +13 -1
  146. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_non_finite_rows.py +13 -8
  147. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_notebook_properties.py +14 -4
  148. auto3d-3.2.2/tests/test_nse_multiplicity.py +478 -0
  149. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_optimization_engine.py +140 -1
  150. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_optimization_engine_indexing.py +100 -2
  151. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_output_overwrite_gates.py +3 -3
  152. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_packaging_metadata.py +3 -3
  153. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_padding.py +18 -15
  154. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_padding_invariance.py +2 -2
  155. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_parallel_embed.py +67 -5
  156. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_pipeline_e2e.py +2 -2
  157. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_policy.py +48 -4
  158. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_processors.py +4 -1
  159. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_public_api.py +33 -4
  160. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_ranking.py +405 -39
  161. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_ranking_by_gibbs.py +28 -2
  162. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_record_policy_agreement.py +5 -4
  163. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_results.py +38 -0
  164. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_run_setup.py +5 -4
  165. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_sdf_isomer_enumeration.py +88 -7
  166. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_smiles_stereo_warning.py +48 -43
  167. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_spe_energy_only.py +21 -21
  168. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_species_conversion.py +4 -4
  169. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_species_module.py +11 -1
  170. auto3d-3.2.2/tests/test_stereo_check_positions.py +18 -0
  171. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_stereo_identity.py +12 -20
  172. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_stereo_postopt.py +138 -4
  173. auto3d-3.2.0/tests/test_utils_stereochemistry.py → auto3d-3.2.2/tests/test_stereochemistry.py +24 -58
  174. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_stereochemistry_validation.py +1 -110
  175. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_suite_hygiene.py +36 -0
  176. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_tauto.py +2 -2
  177. auto3d-3.2.2/tests/test_tautomer_mirror_images.py +506 -0
  178. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_tautomer_select.py +40 -3
  179. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_tautomer_stereo.py +26 -10
  180. auto3d-3.2.2/tests/test_thermo_conventions.py +196 -0
  181. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo_etot_sync.py +1 -1
  182. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo_helpers.py +63 -216
  183. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo_imaginary_mode_inversion.py +77 -3
  184. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo_relative_energies.py +133 -55
  185. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_torch_config.py +15 -15
  186. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_utils.py +12 -12
  187. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_utils_reconciliation.py +90 -0
  188. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_utils_sdf_io.py +65 -7
  189. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_utils_smi_io.py +66 -0
  190. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_utils_validation.py +21 -21
  191. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_validate_run_parity.py +1 -1
  192. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_validation.py +47 -12
  193. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_validation_errors.py +8 -8
  194. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_workflow.py +461 -48
  195. auto3d-3.2.2/tests/test_workflow_package_layout.py +129 -0
  196. auto3d-3.2.0/src/Auto3D/domain/clash_relief.py +0 -108
  197. auto3d-3.2.0/src/Auto3D/engines/isomers/tautomers.py +0 -146
  198. auto3d-3.2.0/src/Auto3D/engines/models/adapter.py +0 -1025
  199. auto3d-3.2.0/src/Auto3D/entry/ASE/thermo/properties.py +0 -379
  200. auto3d-3.2.0/src/Auto3D/foundation/utils/__init__.py +0 -53
  201. auto3d-3.2.0/src/Auto3D/foundation/utils/geometry.py +0 -66
  202. auto3d-3.2.0/src/Auto3D/foundation/utils/molprops.py +0 -115
  203. auto3d-3.2.0/src/Auto3D/foundation/utils/stereochemistry.py +0 -566
  204. auto3d-3.2.0/src/Auto3D/orchestration/workflow.py +0 -1100
  205. auto3d-3.2.0/tests/test_config.py +0 -739
  206. auto3d-3.2.0/tests/test_docs_reproducibility.py +0 -12
  207. auto3d-3.2.0/tests/test_model_caching.py +0 -108
  208. auto3d-3.2.0/tests/test_thermo_conventions.py +0 -105
  209. auto3d-3.2.0/tests/test_utils_energy_constants.py +0 -64
  210. auto3d-3.2.0/tests/test_utils_geometry.py +0 -61
  211. {auto3d-3.2.0 → auto3d-3.2.2}/LICENSE +0 -0
  212. {auto3d-3.2.0 → auto3d-3.2.2}/MANIFEST.in +0 -0
  213. {auto3d-3.2.0 → auto3d-3.2.2}/setup.cfg +0 -0
  214. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/domain/__init__.py +0 -0
  215. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/__init__.py +0 -0
  216. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/batch_opt/__init__.py +0 -0
  217. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/isomers/__init__.py +0 -0
  218. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/isomers/base.py +0 -0
  219. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/engines/models/ani2xt_no_repulsion.pt +0 -0
  220. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/ASE/__init__.py +0 -0
  221. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/entry/__init__.py +0 -0
  222. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/__init__.py +0 -0
  223. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/foundation/registry.py +0 -0
  224. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/orchestration/__init__.py +0 -0
  225. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/orchestration/pipeline/__init__.py +0 -0
  226. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/__init__.py +0 -0
  227. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/__init__.py +0 -0
  228. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/commands/__init__.py +0 -0
  229. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/progress.py +0 -0
  230. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/presentation/cli/results.py +0 -0
  231. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D/py.typed +0 -0
  232. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D.egg-info/dependency_links.txt +0 -0
  233. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D.egg-info/entry_points.txt +0 -0
  234. {auto3d-3.2.0 → auto3d-3.2.2}/src/Auto3D.egg-info/top_level.txt +0 -0
  235. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_adapter_template.py +0 -0
  236. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_ase_torch_config.py +0 -0
  237. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_auto3D.py +0 -0
  238. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_available_cpu_count.py +0 -0
  239. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli_commands_config.py +0 -0
  240. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli_console.py +0 -0
  241. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli_models_command.py +0 -0
  242. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli_results.py +0 -0
  243. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_cli_security.py +0 -0
  244. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_conftest_isolation_guards.py +0 -0
  245. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_custom_nnp_eager.py +0 -0
  246. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_docs_compile_figures.py +0 -0
  247. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_element_sets.py +0 -0
  248. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_lazy_torchani_import.py +0 -0
  249. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_mp_start_method.py +0 -0
  250. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_optimization_engine_validation.py +0 -0
  251. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_output_names.py +0 -0
  252. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_preflight_registry_offline.py +0 -0
  253. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_progress.py +0 -0
  254. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_registry.py +0 -0
  255. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo.py +0 -0
  256. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo_linearity.py +0 -0
  257. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo_projection.py +0 -0
  258. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo_record_assertions.py +0 -0
  259. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo_reference.py +0 -0
  260. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo_temperature_validation.py +0 -0
  261. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_thermo_transition_state.py +0 -0
  262. {auto3d-3.2.0 → auto3d-3.2.2}/tests/test_worker_lifecycle.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: Auto3D
3
- Version: 3.2.0
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
@@ -105,12 +105,12 @@ and ANI2xt engines and ASE thermochemistry working out of the box; add the
105
105
  default AIMNet2 engine with one pip command inside the environment:
106
106
 
107
107
  ```bash
108
- conda install -c conda-forge auto3d # once the 3.1.1 feedstock update lands
108
+ conda install -c conda-forge auto3d # 3.2.0 on conda-forge
109
109
  pip install aimnet # adds the AIMNet2 engines
110
110
  ```
111
111
 
112
- If conda-forge still shows an older version, install with pip inside a conda
113
- environment instead — `installation.yml` sets up the supported combination:
112
+ To install with pip inside a conda environment instead, `installation.yml`
113
+ sets up the supported combination:
114
114
 
115
115
  ```bash
116
116
  conda env create --file installation.yml --name auto3D
@@ -44,12 +44,12 @@ and ANI2xt engines and ASE thermochemistry working out of the box; add the
44
44
  default AIMNet2 engine with one pip command inside the environment:
45
45
 
46
46
  ```bash
47
- conda install -c conda-forge auto3d # once the 3.1.1 feedstock update lands
47
+ conda install -c conda-forge auto3d # 3.2.0 on conda-forge
48
48
  pip install aimnet # adds the AIMNet2 engines
49
49
  ```
50
50
 
51
- If conda-forge still shows an older version, install with pip inside a conda
52
- environment instead — `installation.yml` sets up the supported combination:
51
+ To install with pip inside a conda environment instead, `installation.yml`
52
+ sets up the supported combination:
53
53
 
54
54
  ```bash
55
55
  conda env create --file installation.yml --name auto3D
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "Auto3D"
7
- version = "3.2.0"
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]",
@@ -129,9 +136,7 @@ select = [
129
136
  ]
130
137
  ignore = [
131
138
  "E501", # line too long (handled by formatter)
132
- "E402", # module level import not at top (needed for sys.path manipulation)
133
139
  "E741", # ambiguous variable name (scientific notation l, I, O)
134
- "N801", # class name should use CapWords (legacy code compatibility)
135
140
  "N802", # function name should be lowercase (legacy API compatibility)
136
141
  "N803", # argument name should be lowercase (scientific computing conventions)
137
142
  "N806", # variable name should be lowercase (scientific computing conventions)
@@ -177,6 +182,9 @@ ignore = [
177
182
  # one commit, sorting 34 files' imports was no longer the disruptive change it
178
183
  # had been the argument against. The code is enabled for tests/ again.
179
184
  "tests/*" = [
185
+ "N801", # class name should use CapWords (e.g. `userNNP1`/`userNNP2` fixtures
186
+ # mimicking a real user-provided NNP class; unrelated to this PR's
187
+ # three renames, so left as pre-existing debt here too)
180
188
  "F401", # unused imports (legacy test scaffolding, e.g. optional-dep guards)
181
189
  "E712", # `== True`/`== False` comparisons (common in older tests)
182
190
  "E702", # multiple statements on one line (semicolons in legacy tests)
@@ -254,6 +262,23 @@ filterwarnings = [
254
262
  # must stay visible so tests can assert them (audit M34).
255
263
  "default::DeprecationWarning:Auto3D.*",
256
264
  "default::UserWarning:Auto3D.*",
265
+ # A `module` selector matches the frame a warning is ATTRIBUTED to (per
266
+ # stacklevel), not the frame that raised it; both of these are raised
267
+ # from Auto3D with a stacklevel that deliberately attributes them to the
268
+ # caller's own module, so `Auto3D.*` above cannot gate either one -- only
269
+ # a message-based filter keeps "no production path uses this" enforced.
270
+ "error:Auto3DOptions is not a dict:DeprecationWarning",
271
+ # Same reasoning as the filter above, for the ensemble_opt legacy-key path.
272
+ "error:The optimizer parameter key opttol:DeprecationWarning",
273
+ # Same reasoning again, for the three retired-name module __getattr__ hooks:
274
+ # a caller-attributed stacklevel means only a message-based filter can
275
+ # enforce "no production path imports an old name".
276
+ "error:Legacy name:DeprecationWarning",
277
+ # Same reasoning again, for Auto3DOptions' mpi_np/enumerate_isomer ->
278
+ # isomer_threads/enumerate_isomers aliases (P-m15): "error" so the suite
279
+ # fails if any production path still constructs a config with an old
280
+ # option name instead of the renamed one.
281
+ "error:Option name:DeprecationWarning",
257
282
  # Third-party noise we do not control.
258
283
  "ignore:.*pkg_resources is deprecated.*:DeprecationWarning",
259
284
  "ignore:.*Importing 'parser.split_arg_string' is deprecated.*:DeprecationWarning",
@@ -31,20 +31,14 @@ __version__ = _detect_version()
31
31
  # --help`, a build script reading `__version__`, a tool that merely lists
32
32
  # installed distributions -- and none of them need torch or rdkit.
33
33
  #
34
- # This file used to end with three eager optional-dependency probes (openeye,
35
- # torchani, and `from Auto3D.engines.batch_opt.ANI2xt_no_rep import ANI2xt`) wrapped in
36
- # `warnings.catch_warnings()`. Nothing consumed any of them, and the third one
37
- # defeated the `_LAZY_API` mechanism below outright: it reached ANI2xt_no_rep ->
38
- # the Auto3D.foundation.utils barrel -> utils.validation -> Auto3D.engines.models.* + torch, which
39
- # turned `import Auto3D` into 1175 modules and 1.35 s and eagerly loaded 20
40
- # Auto3D submodules. Every probe is already duplicated where it is load-bearing
41
- # and where its result is actually used:
34
+ # Each optional dependency is checked where it is load-bearing and where
35
+ # its result is actually used, not here:
42
36
  # * openeye -> isomers/omega.py and isomers/tautomers.py (names used at
43
37
  # call time) and pipeline/input_checks.py (raises
44
38
  # DependencyError with a hint)
45
39
  # * torchani -> pipeline/input_checks.py (same) and models/ani2xt.py
46
40
  # * ANI2xt -> constructed only through model_factory / models.adapter
47
- # Do not reintroduce a probe here. A dependency is checked where it is needed.
41
+ # Do not add a probe here. A dependency is checked where it is needed.
48
42
 
49
43
  __all__ = [
50
44
  "__version__",
@@ -0,0 +1,176 @@
1
+ #!/usr/bin/env python
2
+ """Force-field relief of a clashing embedded conformer.
3
+
4
+ A domain operation, not a generic helper: it runs MMFF (with a UFF fallback),
5
+ it can change the molecule it is handed, and it makes a keep/reject decision
6
+ about stereochemistry. That is why it sits beside the embedding code rather
7
+ than under ``Auto3D.foundation.utils``, whose modules are leaves that neither optimize nor
8
+ judge.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import logging
14
+
15
+ import numpy as np
16
+ from rdkit import Chem
17
+ from rdkit.Chem import AllChem
18
+
19
+ from Auto3D.domain.connectivity import UFF_BOND_RADII
20
+ from Auto3D.domain.geometry import min_pairwise_distance
21
+ from Auto3D.domain.stereo_check import stereo_descriptors_from_3d
22
+ from Auto3D.foundation.constants import MIN_ATOM_DISTANCE, MIN_BONDED_FRACTION
23
+
24
+ logger = logging.getLogger("auto3d")
25
+
26
+ __all__ = ["relieve_clash"]
27
+
28
+
29
+ def _shortest_bonded_ratio(
30
+ mol: Chem.Mol, positions: np.ndarray, bonded_pairs: set[frozenset[int]]
31
+ ) -> float:
32
+ """Minimum, over every bonded pair, of distance / UFF reference length.
33
+
34
+ The radius-scaled form of the bonded floor: each bond
35
+ is judged against ITS OWN reference length (``r_i + r_j`` from
36
+ ``domain.connectivity.UFF_BOND_RADII``), not a single flat distance, so
37
+ a bond between heavier elements -- whose reference length is longer --
38
+ is not under-covered relative to a light one.
39
+
40
+ A pair whose element is outside ``UFF_BOND_RADII`` (e.g. an alkali/
41
+ alkaline-earth counterion or a transition-metal coordination bond) has
42
+ no reference length to scale by and is skipped -- "no opinion", the same
43
+ policy ``check_connectivity`` uses for the same elements.
44
+
45
+ Returns:
46
+ The minimum ratio, or ``inf`` if ``bonded_pairs`` is empty or every
47
+ pair in it involves an untabulated element.
48
+ """
49
+ ratios = []
50
+ for pair in bonded_pairs:
51
+ i, j = tuple(pair)
52
+ r_i = UFF_BOND_RADII.get(mol.GetAtomWithIdx(i).GetAtomicNum())
53
+ r_j = UFF_BOND_RADII.get(mol.GetAtomWithIdx(j).GetAtomicNum())
54
+ if r_i is None or r_j is None:
55
+ continue
56
+ distance = float(np.linalg.norm(positions[i] - positions[j]))
57
+ ratios.append(distance / (r_i + r_j))
58
+ return min(ratios) if ratios else float("inf")
59
+
60
+
61
+ def relieve_clash(
62
+ mol: Chem.Mol,
63
+ conf_id: int,
64
+ min_distance: float = MIN_ATOM_DISTANCE,
65
+ ) -> bool:
66
+ """Optimize a clashing conformer in place and report whether it is usable.
67
+
68
+ A conformer is considered "clashing" when its minimum pairwise
69
+ NON-BONDED interatomic distance is below ``min_distance``, or when any
70
+ BONDED pair's distance is below ``MIN_BONDED_FRACTION`` of that bond's
71
+ own UFF reference length -- bonded pairs are excluded from the
72
+ first test but still need a floor of their own, scaled per bond
73
+ rather than flat, or a physically impossible bond length (a crushed
74
+ embedding) would pass through unchecked. Such conformers are relaxed
75
+ with MMFF; when the molecule lacks full MMFF parameters (elements like
76
+ B, Se or some Si valences, where ``MMFFOptimizeMolecule`` returns -1 and
77
+ does nothing), the function falls back to UFF so the conformer is not
78
+ discarded for lack of a force field.
79
+
80
+ The force-field relaxation can itself invert a stereocenter or rotate a
81
+ double bond. This runs before the enumerated SDF is written, so the
82
+ downstream post-optimization stereochemistry check would otherwise read an
83
+ already-changed geometry as its own "before" reference and never notice.
84
+ Stereochemistry is therefore checked before and after the relaxation, on
85
+ this same molecule object, and a conformer whose configuration changed is
86
+ rejected here rather than passed downstream.
87
+
88
+ Known limitation: the "before" snapshot is read while the conformer is
89
+ still in violation of ``min_distance`` — by definition, since that is the
90
+ only way execution reaches this branch. Tag perception on a geometry that
91
+ is itself clashing is not a trustworthy baseline, unlike the equivalent
92
+ check in ``batch_opt/batchopt.py``, whose "before" reading is always
93
+ taken from a valid, non-clashing conformer. This matters only when the
94
+ branch is actually reached: across roughly 650 conformers sampled from
95
+ Auto3D's real ``EmbedMultipleConfs`` output (glucose, cholesterol, a
96
+ tripeptide, macrocycles, a cage compound, and molecules with B/Se/
97
+ hypervalent Si), none ever fell below the clash threshold. Under 196
98
+ artificially forced clashes, this guard rejected 96 conformers, and about
99
+ 56% of those rejections had a post-relaxation configuration that actually
100
+ matched the molecule's true configuration -- spurious rejections caused
101
+ by the unreliable baseline rather than a real inversion. Both rates were
102
+ measured against the pre-3.2.0 ``_CIPCode`` descriptor; re-measuring them
103
+ against the chiral-tag descriptor that replaced it changed nothing at this
104
+ seam (0 of 105 clean relaxations and 10 of 420 noised ones flip under
105
+ either reading, molecule by molecule), so the two figures still describe
106
+ what happens here. The known improvement is to compare against the
107
+ molecule's graph-encoded stereo tags instead of a 3D read of the clashing
108
+ geometry, and that is now a measurement rather than a research question:
109
+ a tag carried on the graph and a tag derived from the coordinates are the
110
+ same ``CHI_TETRAHEDRAL_CW``/``CCW`` alphabet, so the two are directly
111
+ comparable -- what still has to be measured is how often a record
112
+ reaching this branch carries a graph tag to compare against at all.
113
+
114
+ Args:
115
+ mol: RDKit molecule holding the conformer.
116
+ conf_id: Index of the conformer to check/optimize.
117
+ min_distance: Minimum acceptable interatomic distance (Angstroms).
118
+
119
+ Returns:
120
+ True if the (possibly optimized) conformer passes BOTH tests --
121
+ its minimum pairwise NON-BONDED distance is >= ``min_distance`` AND
122
+ every BONDED pair's distance is at least ``MIN_BONDED_FRACTION`` of
123
+ that bond's own UFF reference length -- and its stereochemistry
124
+ survived unchanged; False if it still fails either test or if the
125
+ relaxation changed its configuration.
126
+ """
127
+ # A bonded pair is not a NON-BONDED clash candidate: H2's
128
+ # equilibrium bond length (0.741 A) sits below MIN_ATOM_DISTANCE and is
129
+ # not a clash. But excluding bonded pairs outright would leave them with
130
+ # no floor at all, and a bonded pair at a physically impossible length
131
+ # (a crushed embedding) is exactly the geometry this guard exists to
132
+ # catch -- so a bonded pair still has its own floor, scaled by its
133
+ # own UFF reference length (MIN_BONDED_FRACTION) and tested
134
+ # alongside the non-bonded one. The exclusion set is read off the
135
+ # molecular graph once per call rather than cached, since relieve_clash
136
+ # can be called again after the force field has changed the geometry
137
+ # (but not the connectivity) between calls.
138
+ bonded_pairs = {frozenset((b.GetBeginAtomIdx(), b.GetEndAtomIdx())) for b in mol.GetBonds()}
139
+
140
+ def _survives(positions) -> bool:
141
+ return (
142
+ min_pairwise_distance(positions, exclude=bonded_pairs) >= min_distance
143
+ and _shortest_bonded_ratio(mol, positions, bonded_pairs) >= MIN_BONDED_FRACTION
144
+ )
145
+
146
+ positions = mol.GetConformer(conf_id).GetPositions()
147
+ # Closing the dead band: a conformer exactly AT the bonded threshold is
148
+ # kept (0.6 and the UFF radii involved are all exactly representable).
149
+ # The non-bonded comparison is not exact the same way:
150
+ # min_pairwise_distance casts to float32, so an exact 0.9 A separation
151
+ # comes back as 0.8999999761581421 -- just under min_distance -- and
152
+ # goes to the force field rather than being kept outright. Harmless in
153
+ # practice (one extra force-field call on a measure-zero geometry), but
154
+ # worth stating correctly rather than claiming both thresholds behave
155
+ # the same at their exact boundary.
156
+ if _survives(positions):
157
+ return True
158
+
159
+ # Clashing conformer: try MMFF, fall back to UFF when MMFF is unavailable.
160
+ before = stereo_descriptors_from_3d(mol, conf_id=conf_id)
161
+ if AllChem.MMFFHasAllMoleculeParams(mol):
162
+ AllChem.MMFFOptimizeMolecule(mol, confId=conf_id)
163
+ else:
164
+ AllChem.UFFOptimizeMolecule(mol, confId=conf_id)
165
+
166
+ # Clash relief is a force-field relaxation and can invert a center just as
167
+ # the neural network optimization can. It runs before the enumerated SDF is
168
+ # written, so the post-optimization check downstream would read an already
169
+ # inverted geometry as its reference and never notice. Reject the conformer
170
+ # here instead; the embedder simply keeps the ones that survive.
171
+ if stereo_descriptors_from_3d(mol, conf_id=conf_id) != before:
172
+ logger.warning("Discarding a conformer whose stereochemistry changed during clash relief.")
173
+ return False
174
+
175
+ positions = mol.GetConformer(conf_id).GetPositions()
176
+ return _survives(positions)
@@ -0,0 +1,115 @@
1
+ #!/usr/bin/env python
2
+ """The conformer budget: how many conformers to embed per molecule.
3
+
4
+ The conformer budget is the policy that decides how many conformers to embed
5
+ per molecule; it is domain logic, so it lives here and not beside the file
6
+ I/O helpers in ``Auto3D.foundation.utils``.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from rdkit import Chem
12
+ from rdkit.Chem import rdMolDescriptors
13
+
14
+ from Auto3D.foundation.constants import (
15
+ CONFORMER_MIN_REQUEST,
16
+ CONFORMER_MULTIPLIER,
17
+ CONFORMER_ROTATABLE_COEFF,
18
+ CONFORMER_ROTATABLE_EXP,
19
+ MAX_CONFORMERS_CAP,
20
+ )
21
+
22
+ __all__ = ["calculate_conformer_count"]
23
+
24
+
25
+ def calculate_conformer_count(mol: Chem.Mol) -> int:
26
+ """Calculate the number of conformers to generate for a molecule.
27
+
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).
33
+
34
+ Rotatable bonds are counted on the heavy-atom graph (``Chem.RemoveAllHs``,
35
+ which also drops isotope-labeled hydrogens) using RDKit's default
36
+ (strict) definition, which does not count amide C-N rotors -- not on
37
+ whatever hydrogen state ``mol`` happens to carry: with explicit
38
+ hydrogens, RDKit's ``CalcNumRotatableBonds`` also counts C-O-H / C-N-H
39
+ torsions (glycerol requests 238 conformers with explicit Hs, 52 without),
40
+ for hydroxyl/amine orientations that heavy-atom symmetry pruning collapses
41
+ to one per skeleton (see ``Auto3D.domain.embedding.embed_params``) -- the
42
+ larger with-H request bought nothing for those orientations, only more
43
+ ETKDG attempts, which did leave more distinct skeletons for polyols after
44
+ pruning (measured with those same embedding settings at
45
+ ``CONFORMER_RANDOM_SEED``, ``pruneRmsThresh=0.3``,
46
+ ``useSymmetryForPruning=True``: glycerol, ``OCC(O)CO``, keeps 9 conformers
47
+ whether 52 or 238 are requested, under RDKit 2025.09.6 and under 2026.9.1
48
+ alike; alpha-D-glucopyranose,
49
+ ``C([C@@H]1[C@H]([C@@H]([C@H]([C@H](O1)O)O)O)O)O``, keeps 12 of 16
50
+ requested at the new heavy-atom budget vs. 69 of 321 requested at the old
51
+ with-H budget under RDKit 2025.09.6, and 14 of 16 vs. 83 of 321 under
52
+ 2026.9.1 -- the installed RDKit changes how many of the requested pool
53
+ survive pruning, not which budget is smaller; see
54
+ ``benchmarks/results-notes/2026-10-09-rdkit-2026-09-kept-counts.md``).
55
+ Computing the budget on the heavy-atom
56
+ graph makes the SMILES path (no-H) and the SDF/parallel paths (with-H)
57
+ agree on the same request; a caller that wants the larger pool back asks
58
+ for it explicitly with ``max_confs``.
59
+
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`.
87
+
88
+ Args:
89
+ mol: RDKit molecule object (with or without hydrogens).
90
+
91
+ Returns:
92
+ Number of conformers to generate (always >= 1).
93
+
94
+ Example:
95
+ >>> from rdkit import Chem
96
+ >>> mol = Chem.MolFromSmiles("CCCCCC") # hexane
97
+ >>> count = calculate_conformer_count(mol)
98
+ >>> 1 <= count <= 1000
99
+ True
100
+ """
101
+ # RemoveAllHs, not RemoveHs: the latter keeps isotope-labeled hydrogens
102
+ # (D, T), so a deuterated hydroxyl would still count its C-O-H torsion and
103
+ # a labeled analog would get a larger budget than its protium parent.
104
+ num_rotatable = rdMolDescriptors.CalcNumRotatableBonds(Chem.RemoveAllHs(mol))
105
+ num_heavy = sum(1 for atom in mol.GetAtoms() if atom.GetAtomicNum() > 1)
106
+
107
+ formula_count = int(
108
+ CONFORMER_MULTIPLIER * CONFORMER_ROTATABLE_COEFF * (num_rotatable**CONFORMER_ROTATABLE_EXP)
109
+ )
110
+
111
+ # Floor at 1: a heavy-atom-free species (e.g. [H+]) or a single atom must
112
+ # still receive at least one conformer instead of being silently dropped.
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)
@@ -18,10 +18,54 @@ from rdkit.Chem import rdMolTransforms
18
18
 
19
19
  logger = logging.getLogger("auto3d")
20
20
 
21
- __all__ = ["check_connectivity", "amend_mol", "get_mol_connectivity"]
21
+ __all__ = ["UFF_BOND_RADII", "check_connectivity", "amend_mol", "get_mol_connectivity"]
22
+
23
+ #: UFF bond radii (Rappe et al. JACS 1992, Table 1), in angstroms. These
24
+ #: radii neglect the bond-order and electronegativity corrections in the
25
+ #: original paper. Where several types exist for the same element, the
26
+ #: largest of the types reachable from ordinary organic input was used --
27
+ #: not the largest in the table outright. Hydrogen is the one place that
28
+ #: distinction matters: UFF also tabulates ``H_b`` (bridging hydrogen, the
29
+ #: three-center B-H-B bond) at 0.460 A, larger than the ``H_`` 0.354 A used
30
+ #: here, but ``H_b`` is irrelevant to druglike input and adopting it would
31
+ #: loosen every X-H broken-bond threshold by 0.13 A (the hydrogen
32
+ #: qualification). Every other tabulated element's value here
33
+ #: already is its largest type (verified against an independent
34
+ #: transcription of Table 1): C_3 > C_R, N_3 > N_R, O_R > O_3, S_R > S_3+2,
35
+ #: P_3+3 > P_3+5, B_3 > B_2, and F/Cl/Br/I/Ge/As/Se/Sb/Te have one type each.
36
+ #: Consequence of the selection rule itself: a single bond-order-blind
37
+ #: reference length makes the broken-bond (1.25x) check lenient and the
38
+ #: formed-bond (1.1x) check strict, so a stretched aromatic/conjugated bond
39
+ #: or a short multiple bond can be mis-judged. The molecular graph already
40
+ #: carries bond orders (see get_mol_connectivity); a bond-order-aware
41
+ #: reference would be more accurate but is intentionally not used here.
42
+ #:
43
+ #: Exposed at module level (rather than local to check_connectivity) so
44
+ #: clash_relief.relieve_clash can scale its own bonded-pair floor by the
45
+ #: same per-element reference length instead of
46
+ #: carrying a second, independently-maintained copy of these numbers.
47
+ UFF_BOND_RADII: dict[int, float] = {
48
+ 1: 0.354,
49
+ 5: 0.838,
50
+ 6: 0.757,
51
+ 7: 0.700,
52
+ 8: 0.680, # UFF O_R (resonant/aromatic oxygen); was 0.658 (O_3), not the largest.
53
+ 9: 0.668,
54
+ 14: 1.117,
55
+ 15: 1.101, # UFF P_3+3 (trivalent phosphorus); was 1.117, a copy of Si's radius.
56
+ 16: 1.077, # UFF S_R (aromatic sulfur); was 1.064 (S_3+2), not the largest.
57
+ 17: 1.044,
58
+ 32: 1.197,
59
+ 33: 1.211,
60
+ 34: 1.190,
61
+ 35: 1.192,
62
+ 51: 1.407,
63
+ 52: 1.386,
64
+ 53: 1.382,
65
+ }
22
66
 
23
67
  #: Atomic numbers already named by :func:`check_connectivity`'s untabulated-element
24
- #: warning in this process (N-m27).
68
+ #: warning in this process.
25
69
  #:
26
70
  #: Module state, deliberately: the skip lives in an O(n^2) atom-pair loop, and a
27
71
  #: run optimizes the same species thousands of times, so a per-pair -- or even
@@ -75,35 +119,9 @@ def check_connectivity(mol: Chem.Mol) -> bool:
75
119
  are NOT validated -- such pairs are skipped ("no opinion"), so the
76
120
  dissociation of an M-L bond will not be flagged as invalid connectivity.
77
121
  """
78
- # Initialize UFF bond radii (Rappe et al. JACS 1992)
79
- # Units of angstroms
80
- # These radii neglect the bond-order and electronegativity corrections in the
81
- # original paper. Where several values exist for the same atom, the largest
82
- # was used. Consequence: a single bond-order-blind reference length makes the
83
- # broken-bond (1.25x) check lenient and the formed-bond (1.1x) check strict,
84
- # so a stretched aromatic/conjugated bond or a short multiple bond can be
85
- # mis-judged. The molecular graph already carries bond orders (see
86
- # get_mol_connectivity); a bond-order-aware reference would be more accurate
87
- # but is intentionally not used here.
88
- Radii = {
89
- 1: 0.354,
90
- 5: 0.838,
91
- 6: 0.757,
92
- 7: 0.700,
93
- 8: 0.658,
94
- 9: 0.668,
95
- 14: 1.117,
96
- 15: 1.117,
97
- 16: 1.064,
98
- 17: 1.044,
99
- 32: 1.197,
100
- 33: 1.211,
101
- 34: 1.190,
102
- 35: 1.192,
103
- 51: 1.407,
104
- 52: 1.386,
105
- 53: 1.382,
106
- }
122
+ # UFF bond radii: see the module-level UFF_BOND_RADII docstring for the
123
+ # selection rule and its one qualification (hydrogen).
124
+ Radii = UFF_BOND_RADII
107
125
 
108
126
  atoms = [atom for atom in mol.GetAtoms()]
109
127
  n = len(atoms)
@@ -123,7 +141,7 @@ def check_connectivity(mol: Chem.Mol) -> bool:
123
141
  # salts/metal complexes) have no reference radius. Skip such pairs
124
142
  # ("no opinion") rather than indexing the dict blindly, which would
125
143
  # raise KeyError and crash the whole filtering pass -- but say so
126
- # once per element (N-m27), because "no opinion" on every pair means
144
+ # once per element, because "no opinion" on every pair means
127
145
  # this function returns True for a geometry it never checked.
128
146
  if atomic_num_i not in Radii or atomic_num_j not in Radii:
129
147
  for z in (atomic_num_i, atomic_num_j):
@@ -197,10 +215,10 @@ def amend_mol(
197
215
  except (ValueError, RuntimeError, KeyError) as e:
198
216
  # ValueError: from RDKit SanitizeMol validation errors
199
217
  # RuntimeError: from RDKit internal errors during molecule processing
200
- # KeyError: defensive only. check_connectivity no longer raises KeyError
201
- # for unknown elements (it now skips them); retained to swallow any
202
- # stray dict-lookup error from RDKit internals rather than crash the
203
- # amendment of a single molecule.
218
+ # KeyError: `check_connectivity` never raises `KeyError`; this `except`
219
+ # is defensive-only, to swallow any stray dict-lookup error from
220
+ # RDKit internals rather than crash the amendment of a single
221
+ # molecule.
204
222
  logger.debug(f"Molecule amendment failed: {type(e).__name__}: {e}")
205
223
  return None
206
224
 
@@ -5,20 +5,6 @@ it optimizes -- ``"True"`` or ``"False"`` -- and read by the three filters that
5
5
  decide which conformers survive (:class:`Auto3D.domain.ranking.ConformerRanker`,
6
6
  :func:`Auto3D.domain.filtering.filter_conformers`).
7
7
 
8
- All three used to read it as::
9
-
10
- try:
11
- converged = mol.GetProp('Converged').lower() == 'true'
12
- except KeyError:
13
- converged = False
14
-
15
- which silently deletes every record of any SDF **not** produced by
16
- ``batchopt``: an ``opt_geometry`` output, an ORCA/Gaussian export, a
17
- hand-built conformer set. ``ConformerRanker`` is public and documented, so
18
- pointing it at such a file returned ``[]``, wrote a **0-byte** SDF, and exited
19
- 0. The only message was an INFO line on a logger tree that has no handler
20
- outside ``main()``.
21
-
22
8
  A record that never claimed to be the output of an optimization is not a
23
9
  record that failed one. Absence of the property therefore means "not filtered
24
10
  on convergence" -- the record is kept, and the other filters (connectivity,
@@ -48,8 +34,8 @@ CONVERGED_PROP = "Converged"
48
34
  #: without importing ase and torch, the same reason ``CONVERGED_PROP`` lives
49
35
  #: here rather than in ``batch_opt``.
50
36
  THERMO_FAILED_PROP = "Thermo_failed"
51
- #: Written by ``Auto3D.engines.batch_opt.batchopt.optimizing.run`` for a record
52
- #: whose energy went non-finite mid-optimization (R38): ``"non_finite_energy"``,
37
+ #: Written by ``Auto3D.engines.batch_opt.batchopt.Optimizer.run`` for a record
38
+ #: whose energy went non-finite mid-optimization: ``"non_finite_energy"``,
53
39
  #: the only reason today. No setter, same as ``THERMO_FAILED_PROP`` above --
54
40
  #: that property has none either, and its callers (``ASE/thermo``) just
55
41
  #: ``mol.SetProp`` directly. A record carrying this always also carries an