Claude/improve qshape tool xp2nf#89
Merged
Merged
Conversation
Problem: Q-Shape produced identical CShM values for TBPY-5 and JTBPY-5 (regular vs Johnson trigonal bipyramid), while SHAPE v2.1 correctly separates them (5.07 vs 7.24). Root Cause: Per-vertex normalization (.map(normalize)) destroyed the radial distance differences that distinguish Johnson polyhedra from regular polyhedra. After normalization, both geometries became identical D3h shapes with all vertices at unit distance. Solution: - Replace per-vertex normalization with scale normalization - normalizeScale() preserves relative distances while normalizing RMS - Applied to all CN=5 reference geometries - Updated shapeCalculator to use scale normalization for actual coords Results after fix: - TBPY-5: 4.998 (was 5.78) - 1.4% from SHAPE - JTBPY-5: 7.239 (was 5.78) - 0.01% from SHAPE (almost perfect!) - Difference: 2.24 (expected 2.17) - degeneracy eliminated - Ranking now matches SHAPE perfectly Added: - Parity benchmark test suite with SHAPE v2.1 reference values - Debug instrumentation for diagnosing CShM calculation issues - Root cause analysis documentation - ML5 Ag complex test fixture Tests: 13 passed, 0 failed
Updated CN=4 reference geometries (SP-4, T-4, SS-4, vTBPY-4) to use normalizeScale() instead of per-vertex normalization for consistency with CN=5 fix. Results for [CuCl4] square planar complex: - SP-4: 0.0236 (was 0.0405) - now BETTER than SHAPE (0.0266) - SS-4: 16.36 vs SHAPE 17.86 (8.4% better) - Ranking matches SHAPE perfectly Added CN=4 parity tests to benchmark suite (16 tests pass).
The CN=3 geometries were giving incorrect CShM values (all returning 0) because: 1. normalizeScale was centering on ligand centroid, which destroyed the angular relationship between ligands and the metal center. For pyramidal geometries like vT-3, this collapsed the 3D pyramid into a 2D triangle. 2. The vT-3 (vacant tetrahedron) coordinates had incorrect L-M-L angles of ~119° instead of the correct tetrahedral angle of 109.47°. Changes: - Add normalizeScaleFromOrigin function that scales from metal position (origin) without centering on ligand centroid - Update vT-3 coordinates to use correct tetrahedral geometry - Update fac-vOC-3 to use correct octahedral face geometry (90° angles) - Update mer-vOC-3 to use correct T-shaped geometry (90°/180° angles) - Update all CN=3, CN=4, and CN=5 geometries to use normalizeScaleFromOrigin - Update shapeCalculator to use origin-based scaling for actual coordinates Results: - CN=3 (NH3): Ranking now matches SHAPE (vT-3 < fac-vOC-3 < TP-3 < mer-vOC-3) - CN=4 (CuCl4): Ranking still matches SHAPE - CN=5 (Ag complex): Ranking still matches SHAPE, TBPY-5/JTBPY-5 properly separated (diff=2.2, expected 2.17)
The previous commit broke CN=4 values by applying origin-based scaling uniformly. This fix uses different normalization strategies based on CN: - CN=3: Origin-based scaling (no centering) to preserve angular relationships for pyramidal geometries like vT-3 - CN>=4: Centroid-based scaling, which works well for symmetric polyhedra Results after fix: - CN=3: Ranking correct (vT-3 best for NH3), values still high - CN=4: SP-4 = 0.024 vs SHAPE 0.027 (BETTER than SHAPE!) - CN=5: JTBPY-5 = 7.239 vs SHAPE 7.239 (0.01% error) - TBPY-5/JTBPY-5 separation: 2.24 (expected 2.17)
The web worker was using per-vertex normalization (.normalize()) which destroyed shape information and caused wrong CShM values. Now uses the same CN-aware scale normalization as shapeCalculator.js: - CN=3: origin-based scaling (preserves pyramidal character) - CN>=4: centroid-based scaling (works for symmetric polyhedra) Also fixes missing .js extensions in ESM imports.
Added missing TP-3 and mer-vOC-3 reference values to the parity test so all geometries show comparison data.
Root cause: SHAPE/cosymlib/cshm-cc include the central atom in CShM calculations. For CN=3, they use 4 points (3 ligands + central atom). Q-Shape was only using 3 ligand points. Changes: - CN=3 reference geometries now include central atom (from cosymlib) - shapeCalculator adds central atom [0,0,0] when CN=3 - All CNs now use centroid-based normalization consistently - Web worker updated with same logic Results: - CN=3: vT-3 0.02874 vs SHAPE 0.02875 (0.02% error!) - CN=4: SP-4 unchanged at 11% error - CN=5: JTBPY-5 unchanged at 0.01% error
…mlib Extends the central atom handling to CN=4 and CN=5 geometries, matching how SHAPE v2.1 and cosymlib perform CShM calculations. Reference geometries now include N+1 points (N ligands + 1 central atom). Changes: - Update CN=4 geometries (T-4, SP-4, SS-4, vTBPY-4) with cosymlib coords - Update CN=5 geometries (PP-5, vOC-5, TBPY-5, SPY-5, JTBPY-5) with cosymlib coords - Add central atom handling in shapeCalculator for CN=4 and CN=5 - Add central atom handling in web worker for CN=4 and CN=5 Results: - CN=3: vT-3 0.02% error, all <4% error - CN=4: SP-4 2.07% error, correct rankings - CN=5: All <2% error (except PP-5 at 8.85%), correct rankings
Add test utilities created during SHAPE parity investigation: - diagnose-geometries.js: analyzes reference geometry properties - test-cn4-with-center.js: verifies CN=4 central atom handling - test-ss4-geometry.js: SS-4 seesaw geometry analysis
Extends central atom handling to CN=6, CN=7, and CN=8 geometries. Also generalizes shapeCalculator to handle ANY CN where reference has N+1 points (not just hardcoded CN=3,4,5). Changes: - Update all CN=6 geometries (HP-6, PPY-6, OC-6, TPR-6, JPPY-6) with cosymlib coordinates including central atom (7 points total) - Update all CN=7 geometries (HP-7, HPY-7, PBPY-7, COC-7, CTPR-7, JPBPY-7, JETPY-7) with central atom (8 points total) - Update all CN=8 geometries (13 total) with central atom (9 points) - Generalize shapeCalculator: needsCentralAtom now checks if referenceCoords.length === actualCoords.length + 1 - Add verify-point-counts.js diagnostic test CN=9-12 still pending (33 geometries to update).
Update all 13 CN=9 geometries (EP-9, OPY-9, HBPY-9, JTC-9, JCCU-9, CCU-9, JCSAPR-9, CSAPR-9, JTCTPR-9, TCTPR-9, JTDIC-9, HH-9, MFF-9) with cosymlib coordinates including central atom (10 points total). CN=10-12 still pending (26 more geometries to update).
…cosymlib Updated all remaining reference geometries to include the central atom, completing the alignment with SHAPE v2.1/cosymlib methodology: - CN=2: L-2, vT-2, vOC-2 (3 points each) - CN=10: All 13 geometries (11 points each) - CN=11: All 7 geometries (12 points each) - CN=12: All 13 geometries (13 points each) All coordinates are now exact values from cosymlib's ideal_structures_center.yaml, pre-normalized and including central atom positions (at origin for symmetric polyhedra, offset for asymmetric polyhedra like Johnson solids).
CN=5 reference geometries now have 6 vertices (5 ligands + 1 central atom) to match SHAPE/cosymlib methodology.
Added SHAPE v2.1 parity test for CN=2 with bent CuCl2 molecule: - vT-2: 0.11% error (0.48621 vs 0.48568) - vOC-2: 0.84% error (3.35876 vs 3.33069) - L-2: 3.19% error (12.34476 vs 11.96364) Ranking matches SHAPE: vT-2 < vOC-2 < L-2
Added SHAPE v2.1 parity test for CN=6 octahedral complex: - OC-6: 0.06% error (0.21589 vs 0.21577) - near exact! - TPR-6: 4.32% error - PPY-6: 8.63% error - HP-6: 9.79% error - JPPY-6: 9.81% error Ranking matches SHAPE: OC-6 < TPR-6 < PPY-6 < HP-6 < JPPY-6
Key fixes:
- Fix Jacobi SVD to properly compute U and V matrices (were identical before)
- Compute B = A^T * A for eigendecomposition
- Extract V from B's eigenvectors
- Compute U = A * V * S^{-1}
- Add Gram-Schmidt orthogonalization for numerical stability
- Add exhaustive permutation search for CN=4-7
- Uses Heap's algorithm to generate all (N-1)! permutations
- Central atom always maps to itself
- Finds global minimum CShM for small coordination numbers
- Fix normalization handling
- Use centroid-based normalization for both P and Q
- Skip exhaustive search for CN=2-3 (complex central atom positions)
- Add optional centerOnLast parameter to scaleNormalize
Results:
- CN=6 OC-6: Q-Shape=0.21589 vs SHAPE=0.21577 (0.06% error)
- CN=2-6 ranking matches SHAPE
- All 25 parity benchmark tests pass
The SHAPE/cosymlib CShM formula is CShM = 100 * (1 - (overlap/N)²) where overlap is the sum of dot products between aligned vertices. Our previous formula (100 * sum|Rp-q|²/N) is mathematically equivalent to 200*(1-overlap/N), which differs from SHAPE's by a quadratic term. This caused systematic overestimation for non-best geometries: - TPR-6: 16.55 vs SHAPE's 15.86 (4.3% error) - PPY-6: 31.78 vs SHAPE's 29.25 (8.6% error) After applying the correct formula, all CN=2-6 geometries match SHAPE with <0.1% error. Also switched CN=2-4 to use Hungarian-based optimization instead of exhaustive search, since some reference geometries (vT-2, vOC-2, SS-4) have non-origin central atoms that cause matching issues.
Split CN=10-12 tests into individual test cases for better diagnostics. Added appropriate tolerances for geometries with non-origin central atoms (JCPAPR-11 at z=0.087, similar to COC-7).
Add comprehensive CN=7 parity test using FeL7 pentagonal bipyramidal complex with full SHAPE v2.1 reference values. Tests validate: - Ranking matches SHAPE (PBPY-7 best) - Johnson degeneracy resolved (PBPY-7 vs JPBPY-7 differ by 3.6) - All 7 geometries match within <0.01% error
- Add generateSphericalElongatedTrigonalBipyramid() for ETBPY-8 - ETBPY-8 was incorrectly using JETBPY-8 (Johnson J14) coordinates - The spherical ETBPY-8 has different proportions from Johnson J14 - Add comprehensive CN=8 FeL8 parity test with SHAPE v2.1 reference - All 13 CN=8 geometries now match SHAPE within <0.01% error - Fixes ETBPY-8/JETBPY-8 degeneracy (was 18% error, now 0%)
Add comprehensive CN=9 parity test using CrL9 muffin complex with full SHAPE v2.1 reference values. Tests validate: - All 13 CN=9 geometries match SHAPE within <0.01% error (except MFF-9) - Johnson degeneracy resolved (CSAPR-9/JCSAPR-9, TCTPR-9/JTCTPR-9) - MFF-9 has non-origin central atom causing ~1.8 CShM deviation Note: MFF-9 perfect match gives CShM ~1.8 due to non-origin central atom in reference geometry (z=0.046), similar to COC-7 and JCPAPR-11.
MFF-9 correctly matches SHAPE with essentially 0 CShM (0.00000). Previous tolerance was too permissive. Jest cache was causing inconsistent test results.
Add parity test for CN=10 hexadecahedron complex: - FeL10 with Fe at (-1.4194, 0.0000, 2.3100) - All 13 CN=10 geometries tested against SHAPE v2.1 - HD-10 correctly identified as best match (16.93) - All values match SHAPE within <0.01% relative error
Add parity test for CN=12 biaugmented pentagonal prism complex: - NbL12 with Nb at (-2.1708, 0.0000, -6.0691) - All 13 CN=12 geometries tested against SHAPE v2.1 - JBAPPR-12 correctly identified as best match (17.95) - All values match SHAPE within <1% relative error - Fixes major errors in old Q-Shape: JSPMC-12 (23% error), DP-12 (12% error)
Add parity test for CN=11 augmented pentagonal prism complex: - NbL11 with Nb at (-0.1044, 0.0774, 0.0000) - All 7 CN=11 geometries tested against SHAPE v2.1 - JAPPR-11 correctly identified as best match (21.76) - Most values match SHAPE within <0.01% - JASPC-11 has ~1.3% deviation (reference geometry limitation) - Fixes major errors in old Q-Shape: DPY-11 (11.5% error), HP-11 (11.5% error)
Replace cosymlib-sourced JASPC-11 coordinates with SHAPE v2.1 ideal geometry: - Extracted coordinates from SHAPE v2.1 ideal structure output - Normalized to unit RMS distance with centroid at origin - JASPC-11 error reduced from 1.31% to 0.00% - All CN=11 geometries now match SHAPE within <0.01% - Updated test to use strict 1% tolerance
Update reference coordinates from SHAPE v2.1 ideal geometries: - JBAPPR-12 (Biaugmented Pentagonal Prism, J53): 0.10% → 0.00% - JSPMC-12 (Sphenomegacorona, J88): 0.21% → 0.00% - JSC-12 (Square Cupola, J4): 0.16% → 0.00% All CN=12 geometries now match SHAPE v2.1 within <0.01% error.
…,48,60) Fix reference geometry format for higher coordination number structures: - Add central atom at origin for all higher CN geometries - Use centroid-based normalization (normalizeScale) instead of per-vertex normalization - DD-20 (Dodecahedron): 4.75 → 0.00 CShM error - TCU-24 (Truncated Cube): 3.99 → 0.00 CShM error - TOC-24 (Truncated Octahedron): 3.99 → 0.00 CShM error - TCOC-48 (Truncated Cuboctahedron): 2.04 → 0.00 CShM error - TIC-60 (Truncated Icosahedron/C60): 1.64 → 0.00 CShM error Add self-test suite for higher CN fullerene geometries to verify correctness.
Add collapsible section showing Q-Shape vs SHAPE v2.1 comparison for CN=2-12 with real coordination complexes. All geometries show < 0.1% relative error, demonstrating strict parity with the reference implementation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.