Skip to content

feat: add SOAP-based symmetry-equivalent site detection#10

Merged
efako merged 3 commits intomainfrom
soap_similarity
Feb 25, 2026
Merged

feat: add SOAP-based symmetry-equivalent site detection#10
efako merged 3 commits intomainfrom
soap_similarity

Conversation

@sandipde
Copy link
Member

Add a second method for identifying symmetry non-equivalent adsorption sites using SOAP (Smooth Overlap of Atomic Positions) descriptors from the dscribe package with hierarchical clustering, as an alternative to ASE's SymmetryEquivalenceCheck.

Core implementation (autoadsorbate/utils.py):

  • _compute_soap_site_vectors(): compute SOAP descriptors for candidate sites
  • _soap_similarity_matrix(): pairwise cosine similarity matrix
  • _filter_unique_sites_by_soap(): cluster sites via hierarchical clustering or greedy merging, with configurable similarity_threshold (default 0.99)

Unified API (autoadsorbate/autoadsorbate.py):

  • Surface.get_nonequivalent_sites() accepts method="ase"|"soap"
  • Surface.sym_reduce() accepts method="ase"|"soap"
  • New methods: get_soap_similarity_matrix(), get_nonequivalent_sites_soap(), soap_reduce()

Tests (tests/test_all.py):

  • 13 tests covering SOAP similarity matrix, hcluster/greedy modes, soap_reduce, method switching, ASE vs SOAP comparison on Ni/Ru slab, timing benchmarks

Documentation (README.md):

  • SOAP method usage section with API examples
  • Threshold tuning guide
  • Dedicated ASE vs SOAP benchmark section with:
    • Method comparison table (ASE: 16 sites/8.4s vs SOAP: 8 sites/0.016s)
    • Detailed breakdown by site type (8 SOAP clusters)
    • Site comparison plot (site_comparison.png)
    • SOAP distance histogram (soap_histogram.png)
    • Discussion of why SOAP outperforms ASE on broken-symmetry surfaces

Scripts:

  • scripts/compare_sites.py: detailed ASE vs SOAP comparison
  • scripts/plot_sites.py: site visualization with color-coded SOAP clusters
  • scripts/site_comparison.png: generated comparison image
  • scripts/soap_histogram.png: SOAP distance distribution plot

On Ni(111) 3x3 slab with one Ru dopant:

  • ASE finds 16 unique sites in ~8.4 s
  • SOAP finds 8 unique sites in ~0.016 s (~525x speedup)

Sandip De added 3 commits February 25, 2026 00:45
Add a second method for identifying symmetry non-equivalent adsorption
sites using SOAP (Smooth Overlap of Atomic Positions) descriptors from
the dscribe package with hierarchical clustering, as an alternative to
ASE's SymmetryEquivalenceCheck.

Core implementation (autoadsorbate/utils.py):
- _compute_soap_site_vectors(): compute SOAP descriptors for candidate sites
- _soap_similarity_matrix(): pairwise cosine similarity matrix
- _filter_unique_sites_by_soap(): cluster sites via hierarchical clustering
  or greedy merging, with configurable similarity_threshold (default 0.99)

Unified API (autoadsorbate/autoadsorbate.py):
- Surface.get_nonequivalent_sites() accepts method="ase"|"soap"
- Surface.sym_reduce() accepts method="ase"|"soap"
- New methods: get_soap_similarity_matrix(), get_nonequivalent_sites_soap(),
  soap_reduce()

Tests (tests/test_all.py):
- 13 tests covering SOAP similarity matrix, hcluster/greedy modes,
  soap_reduce, method switching, ASE vs SOAP comparison on Ni/Ru slab,
  timing benchmarks

Documentation (README.md):
- SOAP method usage section with API examples
- Threshold tuning guide
- Dedicated ASE vs SOAP benchmark section with:
  - Method comparison table (ASE: 16 sites/8.4s vs SOAP: 8 sites/0.016s)
  - Detailed breakdown by site type (8 SOAP clusters)
  - Site comparison plot (site_comparison.png)
  - SOAP distance histogram (soap_histogram.png)
  - Discussion of why SOAP outperforms ASE on broken-symmetry surfaces

Scripts:
- scripts/compare_sites.py: detailed ASE vs SOAP comparison
- scripts/plot_sites.py: site visualization with color-coded SOAP clusters
- scripts/site_comparison.png: generated comparison image
- scripts/soap_histogram.png: SOAP distance distribution plot

On Ni(111) 3x3 slab with one Ru dopant:
- ASE finds 16 unique sites in ~8.4 s
- SOAP finds 8 unique sites in ~0.016 s (~525x speedup)
@efako efako merged commit 2d2da43 into main Feb 25, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants