Auto3D 3.1.1__tar.gz → 3.2.0__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 (243) hide show
  1. {auto3d-3.1.1/src/Auto3D.egg-info → auto3d-3.2.0}/PKG-INFO +2 -1
  2. {auto3d-3.1.1 → auto3d-3.2.0}/pyproject.toml +4 -2
  3. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/__init__.py +3 -0
  4. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/domain/clash_relief.py +13 -8
  5. auto3d-3.2.0/src/Auto3D/domain/embedding.py +481 -0
  6. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/domain/filtering.py +3 -1
  7. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/domain/ranking.py +42 -8
  8. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/batch_opt/batchopt.py +130 -53
  9. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/batch_opt/fire_optimizer.py +25 -20
  10. auto3d-3.2.0/src/Auto3D/engines/batch_opt/model_wrapper.py +531 -0
  11. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/batch_opt/optimization_engine.py +145 -28
  12. auto3d-3.2.0/src/Auto3D/engines/batch_opt/padding.py +206 -0
  13. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/isomers/factory.py +10 -2
  14. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/isomers/rdkit_sdf.py +20 -12
  15. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/isomers/rdkit_smi.py +54 -30
  16. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/model_factory.py +109 -14
  17. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/models/__init__.py +8 -5
  18. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/models/adapter.py +418 -242
  19. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/models/ani2xt.py +14 -3
  20. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/models/contract.py +56 -15
  21. auto3d-3.2.0/src/Auto3D/engines/models/policy.py +276 -0
  22. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/models/preflight.py +126 -11
  23. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/models/species.py +0 -1
  24. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/entry/ASE/geometry.py +71 -77
  25. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/entry/ASE/thermo/calculator.py +6 -4
  26. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/entry/ASE/thermo/driver.py +200 -124
  27. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/entry/ASE/thermo/properties.py +51 -10
  28. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/entry/ASE/thermo/vibrations.py +373 -20
  29. auto3d-3.2.0/src/Auto3D/entry/SPE.py +116 -0
  30. auto3d-3.2.0/src/Auto3D/entry/_run_setup.py +228 -0
  31. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/entry/auto3D.py +86 -6
  32. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/entry/tautomer.py +83 -28
  33. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/config.py +176 -84
  34. auto3d-3.2.0/src/Auto3D/foundation/constants.py +319 -0
  35. auto3d-3.2.0/src/Auto3D/foundation/process_lifecycle.py +106 -0
  36. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/results.py +11 -3
  37. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/torch_config.py +3 -5
  38. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/utils/__init__.py +2 -9
  39. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/utils/connectivity.py +43 -1
  40. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/utils/convergence.py +10 -1
  41. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/utils/energy.py +0 -1
  42. auto3d-3.2.0/src/Auto3D/foundation/utils/geometry.py +66 -0
  43. auto3d-3.2.0/src/Auto3D/foundation/utils/molprops.py +115 -0
  44. auto3d-3.2.0/src/Auto3D/foundation/utils/output_names.py +48 -0
  45. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/utils/reconciliation.py +8 -8
  46. auto3d-3.2.0/src/Auto3D/foundation/utils/sdf_io.py +469 -0
  47. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/utils/smi_io.py +38 -0
  48. auto3d-3.2.0/src/Auto3D/foundation/utils/stereo_check.py +387 -0
  49. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/orchestration/chunk_manager.py +42 -18
  50. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/orchestration/pipeline/input_checks.py +160 -43
  51. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/orchestration/processors.py +8 -5
  52. auto3d-3.2.0/src/Auto3D/orchestration/workflow.py +1100 -0
  53. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/orchestration/workflow_workers.py +196 -109
  54. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/app.py +12 -1
  55. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/commands/config.py +0 -1
  56. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/commands/models.py +16 -14
  57. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/commands/properties.py +12 -22
  58. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/commands/run.py +6 -4
  59. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/commands/validate.py +0 -1
  60. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/config_schema.py +0 -1
  61. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/errors.py +29 -8
  62. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/progress.py +0 -1
  63. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/results.py +0 -1
  64. {auto3d-3.1.1 → auto3d-3.2.0/src/Auto3D.egg-info}/PKG-INFO +2 -1
  65. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D.egg-info/SOURCES.txt +18 -0
  66. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D.egg-info/requires.txt +1 -0
  67. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_SPE.py +35 -1
  68. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_adapter_atom_mask.py +39 -0
  69. auto3d-3.2.0/tests/test_adapter_template.py +159 -0
  70. auto3d-3.2.0/tests/test_ase_geometry.py +296 -0
  71. auto3d-3.2.0/tests/test_available_cpu_count.py +53 -0
  72. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_batchopt.py +39 -11
  73. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_chunk_manager.py +17 -0
  74. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli.py +3 -3
  75. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli_app.py +54 -19
  76. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli_config_schema.py +5 -0
  77. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli_errors.py +75 -1
  78. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli_exit_codes.py +60 -0
  79. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli_property_commands.py +96 -36
  80. auto3d-3.2.0/tests/test_compile_values.py +155 -0
  81. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_config.py +235 -10
  82. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_config_parity.py +45 -3
  83. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_conftest_isolation_guards.py +6 -0
  84. auto3d-3.2.0/tests/test_docs_compile_figures.py +13 -0
  85. auto3d-3.2.0/tests/test_docs_reproducibility.py +12 -0
  86. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_durability.py +52 -14
  87. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_e_tot_units.py +1 -0
  88. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_embed_params.py +7 -0
  89. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_fire_optimizer.py +135 -16
  90. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_hessian_invocation_contract.py +4 -3
  91. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_import_boundaries.py +41 -0
  92. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_isomer_engine.py +7 -2
  93. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_isomer_engine_hardening.py +150 -28
  94. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_isomers.py +124 -3
  95. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_model_adapter.py +264 -22
  96. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_model_factory.py +72 -25
  97. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_model_preflight.py +74 -5
  98. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_model_wrapper.py +163 -0
  99. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_mp_start_method.py +7 -5
  100. auto3d-3.2.0/tests/test_non_finite_rows.py +145 -0
  101. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_optimization_engine_indexing.py +46 -6
  102. auto3d-3.2.0/tests/test_output_names.py +51 -0
  103. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_padding.py +107 -3
  104. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_padding_invariance.py +21 -14
  105. auto3d-3.2.0/tests/test_parallel_embed.py +731 -0
  106. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_pipeline_e2e.py +55 -0
  107. auto3d-3.2.0/tests/test_policy.py +154 -0
  108. auto3d-3.2.0/tests/test_preflight_registry_offline.py +184 -0
  109. auto3d-3.2.0/tests/test_public_api.py +135 -0
  110. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_ranking_by_gibbs.py +92 -15
  111. auto3d-3.2.0/tests/test_record_policy_agreement.py +245 -0
  112. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_results.py +18 -0
  113. auto3d-3.2.0/tests/test_run_setup.py +395 -0
  114. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_sdf_isomer_enumeration.py +52 -0
  115. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_smiles_stereo_warning.py +38 -9
  116. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_spe_energy_only.py +52 -25
  117. auto3d-3.2.0/tests/test_stereo_identity.py +504 -0
  118. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_stereo_postopt.py +117 -2
  119. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_suite_hygiene.py +25 -0
  120. auto3d-3.2.0/tests/test_tautomer_select.py +278 -0
  121. auto3d-3.2.0/tests/test_thermo_conventions.py +105 -0
  122. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_thermo_helpers.py +11 -49
  123. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_thermo_imaginary_mode_inversion.py +5 -2
  124. auto3d-3.2.0/tests/test_thermo_linearity.py +163 -0
  125. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_thermo_projection.py +333 -1
  126. auto3d-3.2.0/tests/test_thermo_record_assertions.py +268 -0
  127. auto3d-3.2.0/tests/test_thermo_temperature_validation.py +94 -0
  128. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_thermo_transition_state.py +1 -0
  129. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_utils_connectivity.py +64 -0
  130. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_utils_energy_constants.py +1 -4
  131. auto3d-3.2.0/tests/test_utils_geometry.py +61 -0
  132. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_utils_molprops.py +1 -36
  133. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_utils_reconciliation.py +36 -0
  134. auto3d-3.2.0/tests/test_utils_sdf_io.py +576 -0
  135. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_utils_smi_io.py +43 -0
  136. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_validation.py +241 -2
  137. auto3d-3.2.0/tests/test_worker_lifecycle.py +255 -0
  138. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_workflow.py +785 -19
  139. auto3d-3.1.1/src/Auto3D/domain/embedding.py +0 -229
  140. auto3d-3.1.1/src/Auto3D/engines/batch_opt/model_wrapper.py +0 -336
  141. auto3d-3.1.1/src/Auto3D/engines/batch_opt/padding.py +0 -96
  142. auto3d-3.1.1/src/Auto3D/engines/models/policy.py +0 -142
  143. auto3d-3.1.1/src/Auto3D/entry/SPE.py +0 -182
  144. auto3d-3.1.1/src/Auto3D/foundation/constants.py +0 -168
  145. auto3d-3.1.1/src/Auto3D/foundation/utils/geometry.py +0 -112
  146. auto3d-3.1.1/src/Auto3D/foundation/utils/molprops.py +0 -75
  147. auto3d-3.1.1/src/Auto3D/foundation/utils/sdf_io.py +0 -207
  148. auto3d-3.1.1/src/Auto3D/foundation/utils/stereo_check.py +0 -166
  149. auto3d-3.1.1/src/Auto3D/orchestration/workflow.py +0 -672
  150. auto3d-3.1.1/tests/test_ase_geometry.py +0 -76
  151. auto3d-3.1.1/tests/test_parallel_embed.py +0 -263
  152. auto3d-3.1.1/tests/test_public_api.py +0 -67
  153. auto3d-3.1.1/tests/test_stereo_identity.py +0 -242
  154. auto3d-3.1.1/tests/test_tautomer_select.py +0 -108
  155. auto3d-3.1.1/tests/test_thermo_record_assertions.py +0 -85
  156. auto3d-3.1.1/tests/test_utils_geometry.py +0 -143
  157. auto3d-3.1.1/tests/test_utils_sdf_io.py +0 -315
  158. {auto3d-3.1.1 → auto3d-3.2.0}/LICENSE +0 -0
  159. {auto3d-3.1.1 → auto3d-3.2.0}/MANIFEST.in +0 -0
  160. {auto3d-3.1.1 → auto3d-3.2.0}/README.md +0 -0
  161. {auto3d-3.1.1 → auto3d-3.2.0}/setup.cfg +0 -0
  162. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/domain/__init__.py +0 -0
  163. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/domain/id_mapping.py +0 -0
  164. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/__init__.py +0 -0
  165. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/batch_opt/__init__.py +0 -0
  166. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/isomers/__init__.py +0 -0
  167. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/isomers/base.py +0 -0
  168. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/isomers/omega.py +0 -0
  169. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/isomers/tautomers.py +0 -0
  170. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/models/ani2xt_no_repulsion.pt +0 -0
  171. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/models/availability.py +0 -0
  172. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/engines/models/loading.py +0 -0
  173. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/entry/ASE/__init__.py +0 -0
  174. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/entry/ASE/thermo/__init__.py +0 -0
  175. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/entry/__init__.py +0 -0
  176. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/__init__.py +0 -0
  177. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/exceptions.py +0 -0
  178. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/registry.py +0 -0
  179. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/utils/atomic_io.py +0 -0
  180. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/utils/logging_config.py +0 -0
  181. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/utils/output_guard.py +0 -0
  182. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/foundation/utils/stereochemistry.py +0 -0
  183. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/orchestration/__init__.py +0 -0
  184. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/orchestration/job_layout.py +0 -0
  185. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/orchestration/pipeline/__init__.py +0 -0
  186. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/__init__.py +0 -0
  187. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/auto3Dcli.py +0 -0
  188. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/__init__.py +0 -0
  189. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/commands/__init__.py +0 -0
  190. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/presentation/cli/console.py +0 -0
  191. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D/py.typed +0 -0
  192. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D.egg-info/dependency_links.txt +0 -0
  193. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D.egg-info/entry_points.txt +0 -0
  194. {auto3d-3.1.1 → auto3d-3.2.0}/src/Auto3D.egg-info/top_level.txt +0 -0
  195. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_adapter_fp64_contract.py +0 -0
  196. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_ani2xt_atom_energies.py +0 -0
  197. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_ase_torch_config.py +0 -0
  198. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_atomic_io.py +0 -0
  199. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_auto3D.py +0 -0
  200. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_auto3Dcli.py +0 -0
  201. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli_commands_config.py +0 -0
  202. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli_console.py +0 -0
  203. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli_models_command.py +0 -0
  204. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli_results.py +0 -0
  205. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_cli_security.py +0 -0
  206. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_custom_nnp_contract.py +0 -0
  207. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_custom_nnp_eager.py +0 -0
  208. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_element_sets.py +0 -0
  209. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_filtering.py +0 -0
  210. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_filtering_thermo_failed.py +0 -0
  211. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_helpers_pipeline_output.py +0 -0
  212. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_id_mapping.py +0 -0
  213. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_job_layout.py +0 -0
  214. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_layer_boundaries.py +0 -0
  215. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_lazy_torchani_import.py +0 -0
  216. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_legacy_yaml_parity.py +0 -0
  217. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_logging_config.py +0 -0
  218. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_model_caching.py +0 -0
  219. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_no_aimnet.py +0 -0
  220. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_notebook_properties.py +0 -0
  221. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_optimization_engine.py +0 -0
  222. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_optimization_engine_validation.py +0 -0
  223. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_output_overwrite_gates.py +0 -0
  224. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_packaging_metadata.py +0 -0
  225. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_processors.py +0 -0
  226. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_progress.py +0 -0
  227. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_ranking.py +0 -0
  228. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_registry.py +0 -0
  229. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_species_conversion.py +0 -0
  230. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_species_module.py +0 -0
  231. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_stereochemistry_validation.py +0 -0
  232. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_tauto.py +0 -0
  233. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_tautomer_stereo.py +0 -0
  234. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_thermo.py +0 -0
  235. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_thermo_etot_sync.py +0 -0
  236. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_thermo_reference.py +0 -0
  237. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_thermo_relative_energies.py +0 -0
  238. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_torch_config.py +0 -0
  239. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_utils.py +0 -0
  240. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_utils_stereochemistry.py +0 -0
  241. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_utils_validation.py +0 -0
  242. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_validate_run_parity.py +0 -0
  243. {auto3d-3.1.1 → auto3d-3.2.0}/tests/test_validation_errors.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: Auto3D
3
- Version: 3.1.1
3
+ Version: 3.2.0
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>
@@ -45,6 +45,7 @@ Requires-Dist: ase>=3.23.0; extra == "ase"
45
45
  Provides-Extra: dev
46
46
  Requires-Dist: pytest>=7.0; extra == "dev"
47
47
  Requires-Dist: pytest-cov>=4.0; extra == "dev"
48
+ Requires-Dist: pytest-timeout>=2.3; extra == "dev"
48
49
  Requires-Dist: mypy>=1.0; extra == "dev"
49
50
  Requires-Dist: types-requests; extra == "dev"
50
51
  Requires-Dist: ruff==0.15.9; extra == "dev"
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "Auto3D"
7
- version = "3.1.1"
7
+ version = "3.2.0"
8
8
  description = "Generating Low-energy 3D Conformers from SMILES/SDF"
9
9
  readme = "README.md"
10
10
  license = {text = "MIT"}
@@ -70,6 +70,7 @@ ase = [
70
70
  dev = [
71
71
  "pytest>=7.0",
72
72
  "pytest-cov>=4.0",
73
+ "pytest-timeout>=2.3",
73
74
  "mypy>=1.0",
74
75
  # requests ships no inline types; without the stubs mypy reports
75
76
  # `import-untyped` at models/preflight.py's download path.
@@ -242,9 +243,10 @@ testpaths = ["tests"]
242
243
  python_files = "test_*.py"
243
244
  python_classes = "Test*"
244
245
  python_functions = "test_*"
245
- addopts = "-v --tb=short -m 'not slow'"
246
+ addopts = "-v --tb=short -m 'not slow' --strict-markers"
246
247
  markers = [
247
248
  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
249
+ "timeout: per-test wall-clock limit (pytest-timeout)",
248
250
  ]
249
251
  filterwarnings = [
250
252
  "error::pytest.PytestUnraisableExceptionWarning",
@@ -65,6 +65,8 @@ __all__ = [
65
65
  # Tautomers
66
66
  "get_stable_tautomers",
67
67
  "select_tautomers",
68
+ # Progress reporting
69
+ "ProgressEvent",
68
70
  ]
69
71
 
70
72
  # name -> (module, attribute) for lazy public-API imports. generate_conformers is
@@ -82,6 +84,7 @@ _LAZY_API: dict[str, tuple[str, str]] = {
82
84
  "calc_thermo": ("Auto3D.entry.ASE.thermo", "calc_thermo"),
83
85
  "get_stable_tautomers": ("Auto3D.entry.tautomer", "get_stable_tautomers"),
84
86
  "select_tautomers": ("Auto3D.entry.tautomer", "select_tautomers"),
87
+ "ProgressEvent": ("Auto3D.orchestration.workflow_workers", "ProgressEvent"),
85
88
  }
86
89
 
87
90
 
@@ -48,7 +48,7 @@ def relieve_clash(
48
48
 
49
49
  Known limitation: the "before" snapshot is read while the conformer is
50
50
  still in violation of ``min_distance`` — by definition, since that is the
51
- only way execution reaches this branch. CIP perception on a geometry that
51
+ only way execution reaches this branch. Tag perception on a geometry that
52
52
  is itself clashing is not a trustworthy baseline, unlike the equivalent
53
53
  check in ``batch_opt/batchopt.py``, whose "before" reading is always
54
54
  taken from a valid, non-clashing conformer. This matters only when the
@@ -59,13 +59,18 @@ def relieve_clash(
59
59
  artificially forced clashes, this guard rejected 96 conformers, and about
60
60
  56% of those rejections had a post-relaxation configuration that actually
61
61
  matched the molecule's true configuration -- spurious rejections caused
62
- by the unreliable baseline rather than a real inversion. The known
63
- improvement is to compare against the molecule's graph-encoded stereo
64
- tags instead of a 3D read of the clashing geometry, but that needs its
65
- own measurement first: RDKit's graph ``AssignStereochemistry`` and
66
- ``AssignStereochemistryFrom3D`` label pseudoasymmetric centers
67
- differently (``r``/``s`` vs ``R``/``S``), which could introduce a
68
- systematic false positive.
62
+ by the unreliable baseline rather than a real inversion. Both rates were
63
+ measured against the pre-3.2.0 ``_CIPCode`` descriptor; re-measuring them
64
+ against the chiral-tag descriptor that replaced it changed nothing at this
65
+ seam (0 of 105 clean relaxations and 10 of 420 noised ones flip under
66
+ either reading, molecule by molecule), so the two figures still describe
67
+ what happens here. The known improvement is to compare against the
68
+ molecule's graph-encoded stereo tags instead of a 3D read of the clashing
69
+ geometry, and that is now a measurement rather than a research question:
70
+ a tag carried on the graph and a tag derived from the coordinates are the
71
+ same ``CHI_TETRAHEDRAL_CW``/``CCW`` alphabet, so the two are directly
72
+ comparable -- what still has to be measured is how often a record
73
+ reaching this branch carries a graph tag to compare against at all.
69
74
 
70
75
  Args:
71
76
  mol: RDKit molecule holding the conformer.
@@ -0,0 +1,481 @@
1
+ """Parallel conformer embedding using multiprocessing.
2
+
3
+ Lives at the top level rather than under ``Auto3D.engines.isomers`` because
4
+ ``isomer_engine`` is its only caller and ``isomers`` is the package that
5
+ *wraps* ``isomer_engine``: with this module inside ``isomers``, the two
6
+ packages imported each other (``isomers.factory``/the adapters reached into
7
+ ``isomer_engine``, and ``isomer_engine._run_parallel_embedding`` reached back
8
+ into ``isomers.parallel_embed``), a cycle that only stayed latent because
9
+ every edge of it was a function-scope import. Moving this module out is what
10
+ removes the cycle rather than deferring it.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import math
16
+ import multiprocessing
17
+ import os
18
+ import time
19
+ from collections.abc import Iterator
20
+ from concurrent.futures import ProcessPoolExecutor
21
+ from concurrent.futures.process import BrokenProcessPool
22
+
23
+ #: The context :func:`embed_conformers_parallel`'s pool starts workers from.
24
+ #:
25
+ #: Explicit, rather than the default context, for two reasons -- neither of them
26
+ #: "this code needs spawn". Nothing in this module touches CUDA; it is RDKit
27
+ #: work, and fork would serve it fine in isolation.
28
+ #:
29
+ #: 1. A default-context pool *locks the interpreter's global start method* to the
30
+ #: platform default the first time it is created. This pool runs during the
31
+ #: isomer stage, before the optimization workers -- which do run PyTorch, and
32
+ #: which get a broken CUDA context if forked. That ordering is why ``main()``
33
+ #: had to call ``set_start_method("spawn", force=True)`` rather than the
34
+ #: best-effort form. Taking an explicit context means this pool no longer
35
+ #: touches the global method at all, and nothing downstream has to fight it.
36
+ #: 2. Under ``main()`` this pool has always in fact run under spawn, because that
37
+ #: global force preceded it. Leaving it on the default context would have
38
+ #: quietly switched it to fork in a process where torch may already hold
39
+ #: threads and a CUDA context -- a behavior change disguised as a cleanup.
40
+ #:
41
+ #: ``get_context("spawn")`` returns a context object; unlike ``get_context()``
42
+ #: with no argument, it does not read or set the global start method.
43
+ EMBEDDING_MP_CONTEXT = multiprocessing.get_context("spawn")
44
+ from typing import Any
45
+
46
+ from rdkit import Chem
47
+ from rdkit.Chem import AllChem, rdDistGeom
48
+
49
+ from Auto3D.domain.clash_relief import relieve_clash
50
+ from Auto3D.foundation.constants import (
51
+ CONFORMER_RANDOM_SEED,
52
+ EMBED_TIMEOUT_S,
53
+ PARALLEL_EMBED_MAX_WORKERS,
54
+ )
55
+ from Auto3D.foundation.process_lifecycle import _exit_when_parent_dies
56
+ from Auto3D.foundation.utils.logging_config import get_logger
57
+ from Auto3D.foundation.utils.molprops import calculate_conformer_count, has_dummy_atoms
58
+
59
+ logger = get_logger(__name__)
60
+
61
+
62
+ class SpeciesSkipped(Exception): # noqa: N818 - a skip signal, not a failure
63
+ """A species the embedding worker refused before embedding anything.
64
+
65
+ No ``Error`` suffix, unlike ``Auto3D.foundation.exceptions``'s members: this
66
+ is not a failure the run has to recover from but the worker's way of saying
67
+ "not this one" across a process boundary. The batch continues, the species is
68
+ reported, and nothing upstream treats it as an error -- naming it
69
+ ``SpeciesSkippedError`` would describe the mechanism and misdescribe the
70
+ meaning.
71
+
72
+ Carries the reason back to the parent instead of logging it in the worker.
73
+ Under ``spawn`` the pool children have no run-log handler of their own
74
+ (``workflow_workers._attach_run_log_handlers`` wires up the optimizer
75
+ workers, not this pool), so a warning emitted in a worker fell through to
76
+ ``logging.lastResort``: raw on stderr, carrying no level or logger prefix,
77
+ ungoverned by Auto3D's logging configuration -- and absent from the run log,
78
+ which recorded only that the species had vanished. The parent is already
79
+ wired into that configuration, so it logs the single line.
80
+
81
+ One argument, always a plain string, and no custom ``__init__``: the
82
+ instance is pickled across the pool boundary, and a signature that differs
83
+ from ``Exception``'s does not survive the round trip.
84
+ """
85
+
86
+
87
+ def _embedding_worker_init() -> None:
88
+ """Prepare one pool worker. Passed as the executor's ``initializer``.
89
+
90
+ Two jobs, both of which only make sense inside a worker:
91
+
92
+ * ``_exit_when_parent_dies`` -- the same arming every other process Auto3D
93
+ starts gets (the isomer worker, the optimizers, the logger process, the
94
+ Manager servers). Without it this pool was the one that outlived a
95
+ parent-only signal: under ``spawn`` each child holds a dup of the call
96
+ queue's *write* end as well as its read end, so the parent's death never
97
+ produces EOF, and SIGTERM/SIGKILL to the parent runs none of the ``with``
98
+ block's shutdown sentinels either. An idle worker then blocks on
99
+ ``get()`` forever and a busy one keeps burning a core on ETKDG (P-C2).
100
+ A no-op when there is no parent process, and every failure path inside it
101
+ is caught and logged at DEBUG, so it cannot break the pool.
102
+ * ``CoordsAsDouble`` -- RDKit pickles conformer coordinates as float32
103
+ unless asked otherwise, and the worker's result travels back by pickle. At
104
+ SDF write precision that flipped the last digit of one coordinate of one
105
+ species in a 28-species comparison, which made toggling
106
+ ``--parallel-embedding`` change the bytes of the output.
107
+
108
+ Set here rather than at module import, deliberately: the pickle properties
109
+ are process-global, this is the process where the pickling happens, and
110
+ every spawned worker runs the initializer. Importing
111
+ ``Auto3D.domain.embedding`` must not reconfigure RDKit for a caller that
112
+ never starts a pool -- the same stance the module takes on
113
+ ``set_start_method`` (see ``EMBEDDING_MP_CONTEXT``).
114
+ """
115
+ _exit_when_parent_dies()
116
+ Chem.SetDefaultPickleProperties(
117
+ Chem.GetDefaultPickleProperties() | Chem.PropertyPickleOptions.CoordsAsDouble
118
+ )
119
+
120
+
121
+ def available_cpu_count() -> int:
122
+ """CPUs this process may run on: the affinity mask where the platform has one, else ``os.cpu_count()``.
123
+
124
+ ``os.cpu_count()`` is the machine's count; a 2-CPU cgroup on a 128-core host
125
+ reports 128 and ``resolve_embedding_workers`` would start 32 workers for two
126
+ cores. The affinity mask is what the scheduler will actually give this
127
+ process (taskset, slurm, Kubernetes with cpuset). A cgroup CPU quota
128
+ (``cpu.max``) without a cpuset is still invisible here; pass
129
+ ``parallel_workers`` explicitly in that case.
130
+ """
131
+ getter = getattr(os, "sched_getaffinity", None)
132
+ if getter is not None:
133
+ try:
134
+ return max(1, len(getter(0)))
135
+ except OSError:
136
+ pass
137
+ return os.cpu_count() or 1
138
+
139
+
140
+ def resolve_embedding_workers(
141
+ requested: int | None, n_species: int, *, threads_per_worker: int = 1
142
+ ) -> int:
143
+ """Worker-process count for parallel conformer embedding.
144
+
145
+ ``None`` -- the default -- resolves to
146
+ ``min(cores // threads per worker, species, PARALLEL_EMBED_MAX_WORKERS)``,
147
+ where ``cores`` is :func:`available_cpu_count` -- the process's CPU
148
+ affinity mask (``os.sched_getaffinity``), not the machine's raw core
149
+ count, so a run confined to a cgroup/cpuset cap does not oversubscribe
150
+ the cores it was actually given. A fixed default of 4 left 124 of 128
151
+ cores idle on the 2026-09-21 bench (P-C3), and no class default can do
152
+ better, because the useful number depends on the box, on how many
153
+ species this particular run enumerated, and on how many threads each
154
+ worker will use. So the resolution happens here, called at dispatch by
155
+ whoever is about to start the pool.
156
+
157
+ The division is what keeps the box from being oversubscribed: each worker
158
+ hands ``threads_per_worker`` to ``EmbedMultipleConfs`` (the isomer engine
159
+ passes its ``np``/``mpi_np``, default 4), so one worker per core would put
160
+ ``cores x threads`` runnable threads on ``cores`` cores. ``threads_per_worker``
161
+ is floored at 1 before dividing: the engine's direct callers bypass
162
+ ``Auto3DOptions``'s ``mpi_np >= 1`` bound, and a 0 there would be a
163
+ ``ZeroDivisionError``.
164
+
165
+ An explicit ``requested`` is obeyed as given -- cap, cores and thread count
166
+ all bypassed, since a caller who names a number has a reason -- and only
167
+ floored at 1, because a pool cannot be started with zero workers.
168
+ ``Auto3DOptions`` already refuses a ``parallel_workers`` below 1; the floor
169
+ is here for the engine's direct callers, which go through no such
170
+ validation.
171
+
172
+ The floor can still overshoot the box: one worker handing RDKit
173
+ ``threads_per_worker`` threads is ``threads_per_worker`` runnable threads
174
+ wherever there are fewer cores than that -- 2 cores with ``mpi_np=4``
175
+ measured 2x oversubscribed. Closing it would mean overriding the caller's
176
+ own ``mpi_np``, which is their choice to make, so it is named here instead.
177
+
178
+ Args:
179
+ requested: Explicit worker count, or None to scale to the machine.
180
+ n_species: How many species this dispatch has to embed.
181
+ threads_per_worker: RDKit threads each worker will use for embedding.
182
+
183
+ Returns:
184
+ A worker count of at least 1.
185
+ """
186
+ if requested is not None:
187
+ return max(1, requested)
188
+ # Called unqualified so a test (and a caller measuring on a different
189
+ # machine shape) can substitute `available_cpu_count` via
190
+ # `monkeypatch.setattr(embedding_module, "available_cpu_count", ...)`.
191
+ usable_cores = max(1, available_cpu_count() // max(1, threads_per_worker))
192
+ return max(1, min(usable_cores, n_species, PARALLEL_EMBED_MAX_WORKERS))
193
+
194
+
195
+ def embed_params(
196
+ *, n_threads: int, prune_rms_thresh: float, timeout_s: int = EMBED_TIMEOUT_S
197
+ ) -> Any:
198
+ """The ETKDG settings every Auto3D embedding uses, in one place.
199
+
200
+ ``EmbedMultipleConfs``'s keyword form cannot express two of these:
201
+ ``onlyHeavyAtomsForRMS`` and ``useSymmetryForPruning`` exist only on the
202
+ parameters object. Left to their defaults, the size of the pool that
203
+ ``pruneRmsThresh`` leaves behind depends on **which RDKit is installed** --
204
+ both default True on 2025.09 but have not always, and ``pyproject.toml``
205
+ floors at ``rdkit>=2022.9.5`` with no upper bound. Stating them makes the
206
+ conformer pool a property of this code, in the same way
207
+ ``CONFORMER_RANDOM_SEED`` does.
208
+
209
+ With ``useSymmetryForPruning=True`` RDKit prunes on heavy atoms whatever
210
+ ``onlyHeavyAtomsForRMS`` says (measured: glycerol keeps 9 conformers with
211
+ either RMS flag, 206 with symmetry pruning off and all-atom RMS), so the
212
+ pool holds one hydroxyl / amine orientation per heavy-atom skeleton; the
213
+ optimizer, not the embedding, decides where those hydrogens end up.
214
+ ``onlyHeavyAtomsForRMS`` is still stated so the intent survives a future
215
+ ``useSymmetryForPruning=False``.
216
+
217
+ ``ETKDGv3()`` rather than a bare ``EmbedParameters()``: it is exactly the
218
+ parameterization the keyword form applied. Verified field by field --
219
+ ``useExpTorsionAnglePrefs``, ``useBasicKnowledge``, ``useMacrocycleTorsions``
220
+ and ``useMacrocycle14config`` are the four a bare object gets wrong, and
221
+ ``ETversion`` is 2 in both -- so this switch changes no geometry. A bare
222
+ object would silently disable the torsion knowledge ETKDG is named for.
223
+ """
224
+ # Typed `Any` rather than `EmbedParameters`, and deliberately: RDKit's
225
+ # stubs declare this class's attributes as `EmbedParameters` rather than as
226
+ # their value types, so every assignment below is a false positive and the
227
+ # honest return type is unknowable from the stubs. Confining that to this
228
+ # one function is better than scattering per-line ignores across four call
229
+ # sites; the returned object is only ever handed straight to
230
+ # `EmbedMultipleConfs`.
231
+ params: Any = rdDistGeom.ETKDGv3()
232
+ params.randomSeed = CONFORMER_RANDOM_SEED
233
+ params.numThreads = n_threads
234
+ params.pruneRmsThresh = prune_rms_thresh
235
+ params.onlyHeavyAtomsForRMS = True
236
+ params.useSymmetryForPruning = True
237
+ if hasattr(params, "timeout"):
238
+ params.timeout = timeout_s
239
+ else:
240
+ logger.warning(
241
+ "This RDKit has no EmbedParameters.timeout; a species that cannot embed may run long."
242
+ )
243
+ return params
244
+
245
+
246
+ def embed_with_retry(
247
+ mol: Chem.Mol,
248
+ *,
249
+ n_conformers: int,
250
+ n_threads: int,
251
+ prune_rms_thresh: float,
252
+ timeout_s: int = EMBED_TIMEOUT_S,
253
+ ) -> int:
254
+ """Embed up to ``n_conformers`` conformers; retry once with random
255
+ coordinates if none embed, within the time the first attempt left over.
256
+ Returns the number embedded.
257
+
258
+ ETKDG's default initial coordinates can fail on strained systems that
259
+ random initial coordinates still solve, which is what the retry recovers
260
+ (N-m2). That is a statement about the *starting geometry*, not about time:
261
+ an attempt that produced nothing because it burned the whole cap says the
262
+ species is slow, and random coordinates would get no more time than the
263
+ first attempt had.
264
+
265
+ So the retry runs on the remainder of the budget -- ``timeout_s`` minus
266
+ attempt 1's measured wall clock -- and is skipped outright when under a
267
+ second of it is left. **Both attempts together are bounded by
268
+ ``timeout_s``** (plus up to a second, since RDKit's ``timeout`` is whole
269
+ seconds and the remainder is rounded up). Given a full cap each instead,
270
+ the per-species worst case was ``2 * timeout_s``: 120 s at the shipped
271
+ default, against the ~67 s one impossible stereoisomer measured serially on
272
+ the 2026-09-21 bench set -- the number the cap exists to bound (P-C3), and
273
+ spent twice on exactly the species that triggers the retry.
274
+ """
275
+ params = embed_params(
276
+ n_threads=n_threads, prune_rms_thresh=prune_rms_thresh, timeout_s=timeout_s
277
+ )
278
+ started = time.monotonic()
279
+ ids = AllChem.EmbedMultipleConfs(mol, numConfs=n_conformers, params=params)
280
+ if len(ids) == 0:
281
+ remaining = timeout_s - (time.monotonic() - started)
282
+ if remaining < 1:
283
+ logger.debug(
284
+ "First ETKDG attempt embedded nothing and used its whole %d s budget; "
285
+ "not retrying, since random initial coordinates would have no more "
286
+ "time than the first attempt had.",
287
+ timeout_s,
288
+ )
289
+ return 0
290
+ logger.debug(
291
+ "First ETKDG attempt embedded nothing; retrying with random initial "
292
+ "coordinates and the %d s the first attempt left.",
293
+ math.ceil(remaining),
294
+ )
295
+ # Guarded like the assignment in `embed_params`, and for the same RDKit:
296
+ # `params.timeout = ...` on a Boost.Python object without that attribute
297
+ # raises rather than creating it. On such an RDKit neither attempt was
298
+ # capped in the first place, so there is no budget to hand on.
299
+ if hasattr(params, "timeout"):
300
+ params.timeout = math.ceil(remaining)
301
+ params.useRandomCoords = True
302
+ ids = AllChem.EmbedMultipleConfs(mol, numConfs=n_conformers, params=params)
303
+ return len(ids)
304
+
305
+
306
+ def _embed_single(
307
+ smi: str,
308
+ name: str,
309
+ n_conformers: int | None,
310
+ threshold: float,
311
+ np_threads: int,
312
+ ) -> list[tuple[Chem.Mol, int, str]]:
313
+ """Embed conformers for a single SMILES. Worker function.
314
+
315
+ This function generates multiple 3D conformers for a SMILES string,
316
+ filters out invalid conformers (those with atom clashes), and returns
317
+ the valid conformers with their indices.
318
+
319
+ Args:
320
+ smi: SMILES string of the molecule.
321
+ name: Name/ID of the molecule.
322
+ n_conformers: Maximum number of conformers to generate.
323
+ If None, uses a dynamic formula based on molecular properties.
324
+ threshold: RMSD threshold for duplicate removal during embedding.
325
+ np_threads: Number of threads for RDKit conformer generation.
326
+
327
+ Returns:
328
+ List of (mol, conf_idx, conf_id) tuples where:
329
+ - mol: RDKit Mol object with conformers
330
+ - conf_idx: Index of the conformer in the molecule
331
+ - conf_id: Unique identifier string (name_idx format)
332
+
333
+ Raises:
334
+ SpeciesSkipped: The SMILES cannot be parsed, or carries a dummy atom.
335
+ Raised rather than logged here: see ``SpeciesSkipped`` for why a
336
+ warning from a pool worker is the wrong place for the reason.
337
+ """
338
+ # Validate SMILES first to avoid unpicklable Boost.Python errors
339
+ mol_noh = Chem.MolFromSmiles(smi)
340
+ if mol_noh is None:
341
+ # Same reason the serial path reports (isomer_engine._run_serial_embedding).
342
+ # This branch returned [] in silence, so a molecule dropped for an
343
+ # unparseable SMILES was reported by the parallel path and not by the
344
+ # serial one -- a switch documented as a performance option decided how
345
+ # much the user was told.
346
+ raise SpeciesSkipped(f"failed to parse {smi!r}")
347
+ if has_dummy_atoms(mol_noh):
348
+ # N-M3: an R-group placeholder is not a species. Clash relief happens
349
+ # to reject every conformer of such a molecule today (neither MMFF nor
350
+ # UFF can type atom `*`), so it already disappeared -- but silently and
351
+ # for an unrelated reason. Named and skipped here instead, before any
352
+ # embedding work, so the same rule holds whatever the force fields do.
353
+ raise SpeciesSkipped("it contains a dummy atom (atomic number 0)")
354
+ mol = Chem.AddHs(mol_noh)
355
+
356
+ if n_conformers is None:
357
+ # calculate_conformer_count counts rotatable bonds on the heavy-atom
358
+ # graph (Chem.RemoveAllHs internally), so it returns the same budget
359
+ # whether it is handed this H-complete (AddHs) mol or the serial/SDF
360
+ # paths' own representation -- the parallel path agrees with them
361
+ # regardless of which hydrogen state each one happens to pass in.
362
+ n_conformers = calculate_conformer_count(mol)
363
+
364
+ embed_with_retry(
365
+ mol, n_conformers=n_conformers, n_threads=np_threads, prune_rms_thresh=threshold
366
+ )
367
+
368
+ results = []
369
+ for i in range(mol.GetNumConformers()):
370
+ # Relieve atom clashes (MMFF, with UFF fallback for elements lacking
371
+ # MMFF params) and keep only conformers that end up clash-free.
372
+ if relieve_clash(mol, i):
373
+ conf_id = f"{name}_{i}"
374
+ results.append((mol, i, conf_id))
375
+
376
+ return results
377
+
378
+
379
+ def embed_conformers_parallel(
380
+ smiles_names: list[tuple[str, str]],
381
+ n_conformers: int | None = None,
382
+ threshold: float = 0.3,
383
+ np_threads: int = 1,
384
+ n_workers: int = 4,
385
+ ) -> Iterator[tuple[Chem.Mol, int, str]]:
386
+ """Embed conformers for multiple SMILES in parallel.
387
+
388
+ Uses ProcessPoolExecutor for parallel execution across multiple molecules.
389
+ Each molecule is processed independently in a separate worker process.
390
+
391
+ Args:
392
+ smiles_names: List of (smiles, name) tuples to process.
393
+ n_conformers: Maximum conformers per molecule. None for dynamic calculation.
394
+ threshold: RMSD threshold for duplicate removal during embedding.
395
+ np_threads: Number of threads per worker for RDKit operations.
396
+ n_workers: Number of parallel worker processes.
397
+
398
+ Yields:
399
+ (mol, conf_idx, conf_id) tuples for each valid conformer where:
400
+ - mol: RDKit Mol object with conformers
401
+ - conf_idx: Index of the conformer in the molecule
402
+ - conf_id: Unique identifier string (name_idx format)
403
+
404
+ Example:
405
+ >>> smiles_names = [("C", "methane"), ("CC", "ethane")]
406
+ >>> for mol, idx, name in embed_conformers_parallel(smiles_names):
407
+ ... print(f"{name}: {mol.GetNumAtoms()} atoms")
408
+ """
409
+ if not smiles_names:
410
+ return
411
+
412
+ with ProcessPoolExecutor(
413
+ max_workers=n_workers,
414
+ mp_context=EMBEDDING_MP_CONTEXT,
415
+ initializer=_embedding_worker_init,
416
+ ) as executor:
417
+ futures = {
418
+ executor.submit(_embed_single, smi, name, n_conformers, threshold, np_threads): (
419
+ smi,
420
+ name,
421
+ )
422
+ for smi, name in smiles_names
423
+ }
424
+
425
+ # Iterate in submission order (not as_completed) so the emitted molecule
426
+ # order is deterministic and matches the serial path; all futures are
427
+ # already running concurrently, so this costs no parallelism.
428
+ for future in futures:
429
+ smi, name = futures[future]
430
+ try:
431
+ conformers = future.result()
432
+ except BrokenProcessPool as exc:
433
+ # A worker died (e.g. OOM-killed): the pool is broken and EVERY
434
+ # remaining future will also raise this. Surface it loudly --
435
+ # the broad except below would otherwise swallow it per-future
436
+ # and silently drop the whole tail of the batch as warnings.
437
+ #
438
+ # The other common cause is not a dead worker at all: under the
439
+ # spawn context each child re-imports the caller's `__main__`,
440
+ # and an unguarded script raises there before embedding anything,
441
+ # breaking the pool. The user's only clue was a child-process
442
+ # traceback about freeze_support, so attach the two ways out.
443
+ # A note rather than a new exception type: an OOM kill must keep
444
+ # surfacing as the BrokenProcessPool everything upstream expects.
445
+ exc.add_note(
446
+ "Parallel embedding spawns worker processes that re-import "
447
+ "the calling script. Guard the script's entry point with "
448
+ 'if __name__ == "__main__":, or embed serially '
449
+ "(use_parallel_embedding=False for main(); smiles2mols is "
450
+ "serial unless called with parallel_embedding=True)."
451
+ )
452
+ raise
453
+ except SpeciesSkipped as skipped:
454
+ # The worker refused this species and said why. One warning, from
455
+ # here -- the process that owns the run log -- and no second line:
456
+ # the `continue` is also what keeps the generic "produced no
457
+ # conformers" branch below from firing for a species whose reason
458
+ # is already on the record.
459
+ logger.warning("Skipping molecule %r: %s", name, skipped)
460
+ continue
461
+ except Exception as e:
462
+ # Per-molecule boundary: a single molecule's failure (including
463
+ # RDKit's Boost.Python.ArgumentError, which is a TypeError and so
464
+ # escaped the previous narrow except) must not abort the whole
465
+ # batch and silently drop every remaining molecule.
466
+ logger.warning(f"Failed to embed {name}: {type(e).__name__}: {e}")
467
+ continue
468
+ if not conformers:
469
+ # The counterpart to the serial path's `n_written == 0` warning,
470
+ # which this path had no equivalent of. A species that embeds
471
+ # nothing -- unparseable SMILES, or every conformer rejected by
472
+ # clash relief -- is absent from the output and never reaches
473
+ # ranking, so not even "No structure converged" appears for it.
474
+ # Warned here, in the parent, because a message from a
475
+ # ProcessPoolExecutor worker depends on that child's logging
476
+ # configuration, while this one does not.
477
+ logger.warning(
478
+ f"{name!r} produced no conformers; this species is absent from the output."
479
+ )
480
+ continue
481
+ yield from conformers
@@ -324,7 +324,9 @@ def _filter_within_cluster(
324
324
  ``rmsd_threshold`` AND the energies agree within this tolerance. The
325
325
  energy term preserves conformers that differ only in an O-H / N-H
326
326
  rotor orientation (RMSD~=0 on heavy atoms but distinct minima with
327
- different energies); the compound term preserves distinct
327
+ different energies), which arise when the optimizer settles the hydrogens
328
+ differently on one skeleton (the embedding stage does not sample them;
329
+ see ``Auto3D.domain.embedding.embed_params``); the compound term preserves distinct
328
330
  stereoisomers, which arrive here in one group and whose heavy-atom
329
331
  RMSD can fall below the default threshold
330
332
  (:func:`Auto3D.foundation.utils.stereo_check.species_key`).