v1.5.0 - Multi-Structure Batch Analysis

Q-Shape v1.5.0 - Multi-Structure Batch Analysis

This major release introduces Multi-Structure Batch Analysis - analyze multiple structures from a single XYZ or CIF file with comprehensive reporting.

✨ New Features

Multi-Structure Batch Analysis

• Batch Processing - Load and analyze multi-structure XYZ/CIF files
• Batch Summary Table - Visual overview of all analyzed structures at a glance
• Structure Navigator - Switch between structures with instant 3D visualization updates
• Parallel Analysis - Run intensive analysis on all structures with progress tracking

Enhanced Reporting

• Batch PDF Reports - Comprehensive reports with per-structure sections including:
  • Q-Shape analysis overview
  • Quality Metrics & Bond Statistics
  • Coordinating Atoms tables
  • Ligand Groups Analysis
• CSV Export Options:
  • Wide summary (one row per structure)
  • Detailed export (all geometries for all structures)

UI/UX Improvements

• TrackballControls - Unrestricted 360° 3D rotation (replaces OrbitControls)
• Context-Aware Buttons - Actions adapt to batch vs single mode
• Improved Color Scheme - Softer blue tones for selected rows

Developer Experience

• Centralized Metadata - Single source of truth for version info (src/constants/appMetadata.js)

🐛 Bug Fixes

• Fixed crash: Cannot read properties of undefined (reading 'x') in 3D viewer
• Fixed batch report missing coordinating atoms and quality metrics
• Fixed 3D rotation limitations (gimbal lock issues)

📊 Statistics

Metric	Value
Files Changed	24
Lines Added	+3,819
Lines Removed	-187
Net Change	+3,632
Commits	9

🆕 New Files

• src/constants/appMetadata.js - Centralized version/citation metadata
• src/components/BatchModePanel.jsx - Structure selector and batch controls
• src/components/BatchSummaryTable.jsx - Visual summary table
• src/components/ManualOverridePanel.jsx - Per-structure parameter overrides
• src/hooks/useBatchAnalysis.js - Batch analysis orchestration
• src/types/structureTypes.js - TypeScript-style type definitions
• src/utils/parseInput.js - Unified multi-format parser
• src/utils/parseInput.test.js - Parser test suite

📖 Documentation

• Updated README with batch analysis features and workflow
• Updated CHANGELOG with comprehensive v1.5.0 notes
• Updated all citation files (CITATION.cff, .zenodo.json)

🔗 Links

• Live Demo: https://henriquecsj.github.io/q-shape
• Documentation: https://github.com/HenriqueCSJ/q-shape#readme
• DOI: https://doi.org/10.5281/zenodo.17717110

---

Full Changelog: v1.4.0...v1.5.0

Q-Shape v1.4.0

[1.4.0] - 2025-11-25

🎯 Overview

Publication-Ready Refactoring Release - This release transforms Q-Shape into publication-quality scientific software through comprehensive refactoring, proper algorithm implementation, and extensive testing. All 4 publication blockers identified in code review have been resolved.

🏗️ Major Refactoring

App.js Decomposition (1,809 → 416 lines, -77%)

• Extracted 5 new React components:
  • src/components/AnalysisControls.jsx (185 lines) - Analysis mode and settings
  • src/components/CoordinationSummary.jsx (351 lines) - Coordination sphere display
  • src/components/FileUploadSection.jsx (26 lines) - File upload handling
  • src/components/ResultsDisplay.jsx (192 lines) - Shape analysis results
  • src/components/Visualization3D.jsx (100 lines) - 3D molecular viewer
• Extracted report generator service:
  • src/services/reportGenerator.js (711 lines) - PDF generation logic
• Benefits:
  • Clean separation of concerns
  • Improved testability
  • Better maintainability
  • Follows React best practices

🐛 Critical Algorithm Fix

Hungarian Algorithm Replacement (CRITICAL)

• Problem: Previous implementation only used greedy matching with incomplete Hungarian fallback
• Impact: Could produce suboptimal atom-vertex assignments for coordination numbers > 3
• Fix: Replaced with munkres-js library - industry-standard, well-tested implementation
• Result: Guarantees optimal assignment in O(n³) time
• File: src/services/algorithms/hungarian.js
• References:
  • Kuhn, H. W. (1955). "The Hungarian Method for the assignment problem"
  • munkres-js: https://github.com/addaleax/munkres-js

🔧 Code Quality Improvements

Magic Numbers Extraction

• Created: src/constants/algorithmConstants.js (517 lines)
• Centralized configuration for:
  • Kabsch algorithm parameters (convergence thresholds, tolerances)
  • Shape measure quality score ranges
  • Numerical stability constants
  • Ring detection parameters
  • Gap detection thresholds
• Benefits:
  • No more hardcoded values scattered in code
  • Single source of truth for all constants
  • Better maintainability and documentation
• Files modified: 5 algorithm files updated to use centralized constants

🧪 Comprehensive Testing

Added 5 New Test Suites (142 additional tests)

• src/services/algorithms/kabsch.test.js (604 lines, 40+ tests)

  • Rotation matrix alignment correctness
  • Orthogonality verification
  • RMSD calculations
  • Edge cases (collinear points, numerical stability)

• src/services/shapeAnalysis/shapeCalculator.test.js (557 lines, 50+ tests)

  • Shape measure calculations
  • Perfect geometry validation (S ≈ 0)
  • Distorted geometry detection
  • Edge cases (duplicate atoms, degenerate cases)

• src/services/coordination/ringDetector.test.js (499 lines, 30+ tests)

  • Cyclopentadienyl ring detection
  • Ferrocene analysis (staggered/eclipsed)
  • Bond connectivity
  • Ring planarity validation

• src/utils/fileParser.test.js (366 lines, 25+ tests)

  • XYZ file format parsing
  • Coordinate validation
  • Error handling
  • Edge cases (malformed files, special characters)

• src/services/algorithms/hungarian.test.js (271 lines, 20+ tests)

  • Assignment optimality verification
  • Cost matrix handling
  • munkres-js integration testing

Test Statistics

• Total tests: 258 (was 116, +122%)
• Test files: 7 (was 2, +250%)
• All tests passing: ✅
• Coverage: Critical algorithms 100%

📖 Documentation

Publication Readiness Assessment

• Added: docs/development/CODE_REVIEW_PUBLICATION_READINESS.md (440 lines)
• Contents:
  • Comprehensive code quality assessment
  • Identified 4 publication blockers
  • Detailed remediation plan
  • All blockers now resolved

Updated Files

• README.md - v1.4.0 release highlights
• CITATION.cff - Version and date updated
• .zenodo.json - Version metadata updated
• package.json - Version bump

📊 Statistics

• Files changed: 23 files
• Lines added: +5,043
• Lines removed: -1,612
• Net change: +3,431 lines
• Commits: 6 refactoring commits
• Build time: 6.4 seconds
• Bundle size: 193.16 kB (gzipped)

✅ Quality Assurance

• All 258 tests passing
• Production build successful
• No console errors or warnings
• Code follows ESLint guidelines
• Breaking changes: None
• Backward compatible: Yes

🔬 Publication Impact

This release resolves all publication blockers:

1. ✅ Hungarian algorithm - Now properly implemented with proven library
2. ✅ App.js monolith - Decomposed into modular, testable components
3. ✅ Test coverage - Comprehensive tests for all critical algorithms
4. ✅ Magic numbers - Centralized in dedicated constants file

The codebase is now ready for peer-reviewed journal submission.

🚀 Migration Guide

No breaking changes. Update by:

git pull origin main
npm install  # munkres-js added as dependency
npm test     # Verify all 258 tests pass
npm run build  # Build for production

---

[1.3.0] - 2025-01-05

🐛 Critical Bug Fixes

Fixed: ALL_METALS Incorrectly Included Nonmetals (CRITICAL)

• Problem: The filter data.type.toLowerCase().includes('metal') matched 'Nonmetal' and 'Metalloid'
• Impact: H, C, N, O, P, S and 13 other nonmetals were classified as metals
• Fix: Changed to data.type.endsWith(' Metal') to match only actual metals
• Result: ALL_METALS reduced from 99 (incorrect) to 85 (correct) elements
• File: src/constants/atomicData.js

Fixed: Metal Detection Selected Ligands Over Metals (CRITICAL)

• Problem: Highly-coordinated nitrogen atoms could be selected over transition metals, lanthanides, and actinides
• Impact: User's La complex selected N instead of La; any bridging ligand could outscore the metal
• Fix: Implemented weighted scoring system (metals: base 1000 + neighbors; non-metals: 0 + neighbors)
• Result: Metals ALWAYS selected unless structure contains no metals
• File: src/services/coordination/metalDetector.js

Fixed: Polyhedron Vanishing After Intensive Analysis (CRITICAL)

• Problem: Intensive analysis results didn't include refCoords property required for rendering
• Impact: Ideal geometry overlay disappeared after running intensive analysis
• Fix: Added refCoords to all result objects in pattern geometry builders
• Result: Polyhedron persists correctly after intensive analysis
• Files: src/services/coordination/patterns/geometryBuilder.js

Fixed: State Cleanup on File Upload

• Problem: Intensive analysis metadata lingered when loading new structures
• Fix: Added reset for intensiveMetadata and intensiveProgress on file upload
• File: src/App.js

✨ New Features

Comprehensive Test Suite

• Added 116 automated tests covering critical functionality
• 88 tests for atomicData.js and ALL_METALS bug fix
• 28 tests for metalDetector.js and scoring system
• All tests passing ✅
• Tests ensure bugs stay fixed forever

GitHub Actions CI/CD

• Automated testing on every commit
• Tests run on Node.js 18 and 20
• Build verification before merging
• Prevents regressions and ensures code quality

Enhanced PDF Reports

• Added intensive analysis metadata section
• Shows detected structural patterns (sandwich, piano stool, macrocycle)
• Displays ligand group details and ring information
• Highlights sandwich structures with explanatory text

📖 Documentation

• Added comprehensive publication roadmap (docs/development/PUBLICATION_ROADMAP.md)
• Documented all bug fixes in detail (docs/development/BUGFIX_FERROCENE_20250105.md)
• Created session progress reports
• Organized development documentation in docs/development/

🔧 Improvements

• Fixed two-column grid layout for intensive analysis metadata
• Improved metal detection logging with detailed scores
• Better edge case handling (NaN, Infinity coordinates)

📦 Internal

• Reorganized development documentation
• Simplified CI/CD workflows for reliability
• Removed Node 16 support (EOL)

🧪 Testing

Run the test suite:

npm test

All 116 tests pass ✅

📊 Statistics

• Bugs fixed: 3 critical
• Tests added: 116
• Files modified: 11
• Lines of code added: ~1,400
• Test coverage: Critical paths 100%

---

[1.2.1] - 2024-10-27

Fixed

• Critical infinite loops in coordination sphere detection
• Auto-radius toggle state management
• Button states that broke functionality in v1.1.0

Improved

• Modular architecture with clean separation of concerns
• Comprehensive inline documentation

Added

• Precise radius control with text input
• Adjustable step size (±0.50, ±0.10, ±0.05, ±0.01 Å)
• Find Radius by CN feature with gap detection algorithm
• Official Zenodo DOI: 10.5281/zenodo.17448252

---

[1.1.0] - 2024-10-20

Added

• Enhanced radius control system
• Find optimal radius by coordination number
• Step size selector for fine-tuned adjustments
• Modular codebase architecture

---

[1.0.0] - 2024-09-15

Added

• Initial release
• 87 reference geometries (CN 2-12)
• Continuous Shape Measure (CShM) analysis
• Interactive 3D visualization
• Automatic metal detection
• PDF report generation
• Real-time geometry analysis
• Dual analysis modes (standard/intensive)

---

Links

• Repository: https://github.com/HenriqueCSJ/q-shape
• Live Demo: https://henriquecsj.github.io/q-shape
• DOI: https://doi.org/10.5281/zeno...

Q-Shape v1.3.0

🎉 Release v1.3.0

This release fixes 3 critical bugs and adds professional test infrastructure.

🐛 Critical Bug Fixes

1. ALL_METALS included nonmetals (H, C, N, O) - FIXED ✅

   • Fundamental chemistry error
   • 99 elements incorrectly classified → fixed to 85 correct metals

2. Metal detection selected ligands over metals - FIXED ✅

   • La complexes selected N instead of La
   • New weighted scoring: metals always win

3. Polyhedron vanishing after intensive analysis - FIXED ✅

   • Missing refCoords property
   • Ideal geometry overlay now persists

✨ New Features

• ✅ 116 comprehensive tests (all passing)
• ✅ GitHub Actions CI/CD (automated testing)
• ✅ Enhanced PDF reports (intensive analysis metadata)
• ✅ Clean documentation (organized in docs/development/)

📊 Statistics

• Bugs fixed: 3 critical
• Tests added: 116
• Test coverage: 100% of critical paths
• CI/CD: Automated testing on every commit

📖 Full Changelog

See CHANGELOG.md for complete details.

---

All tests passing ✅
Ready for release! 🚀

Q-Shape v1.2.1

Privacy statement added.
Link to Zenodo.

v1.2.0 - Modular Architecture & Critical Fixes

🎉 Version 1.2.0 - Major Update

This release represents a significant architectural improvement while maintaining 100% algorithm compatibility with v1.1.0.

🐛 Critical Bug Fixes

• Fixed infinite loop in useRadiusControl (atoms dependency issue)
• Fixed infinite loop in useShapeAnalysis (callback dependencies)
• Fixed auto-radius toggle not working properly
• Fixed buttons staying greyed out (Intensive Analysis, Generate Report)
• Fixed ideal polyhedra not displaying in 3D view
• Fixed warning floods causing CPU usage spikes
• Fixed slider being unresponsive in auto mode

🏗️ Architecture Improvements

• Refactored 4044-line monolithic App.js into clean modular architecture
• Created 7 custom React hooks for better separation of concerns
• Extracted services layer (algorithms, coordination, shape analysis)
• Separated constants and utilities into dedicated modules
• Added comprehensive JSDoc documentation
• Improved code maintainability and testability

🎨 UI Enhancements

• Updated tagline: "Advanced Coordination Geometry Analysis"
• Added version and build information to header

✅ What's Preserved

• All 80 reference geometries (CN 2-12)
• All optimization parameters (100% identical to v1.1.0)
• All algorithms (Kabsch, Hungarian, Shape Measure)
• Same user interface and workflows
• Same analysis accuracy and capabilities

📦 Technical Stats

• Net code change: +971 lines
• Files added: 13 new modular files
• Files cleaned: 7 development docs removed
• Build: Compiled successfully, no warnings

Full Changelog: v1.1.0...v1.2.0

v1.1.0 - Advanced Radius Controls

🎉 Q-Shape v1.1.0 - Advanced Radius Controls

This release introduces powerful new features for precise coordination radius control and automatic radius optimization.

✨ New Features

1. Precise Radius Control

• Text input field for direct radius entry with real-time synchronization
• Adjustable step size selector (±0.50, ±0.10, ±0.05, ±0.01 Å)
• Increment (+) and decrement (−) buttons for fine-tuned adjustments
• Auto-disable when "Auto" mode is enabled

2. Find Radius by Coordination Number

• Input field for target coordination number (2-24 range)
• Automated gap detection algorithm finds optimal radius
• Automatically calculates the best radius to achieve desired CN
• Provides helpful feedback via warning system with details about gap detection

3. Enhanced Warning Management

• Added "Clear" button to warning alerts
• Prevents warning accumulation for better UX

🔧 Technical Details

• Added state variables: radiusInput, radiusStep, targetCNInput
• Implemented sync effect between radiusInput (string) and coordRadius (number)
• Gap detection algorithm analyzes neighbor distances to find optimal CN boundaries
• Input validation for CN range (2-24)
• Preserved responsive layout architecture from v1.0.0 ✅

📦 Build Information

• Bundle size: 177.37 kB (gzipped)
• Build status: ✅ Success
• No errors or warnings
• Fully responsive on mobile, tablet, and desktop

🔗 Related Pull Requests

• #10 - feat: Add advanced radius controls for v1.1.0
• #11 - chore: Bump version to 1.1.0

📝 Upgrade Notes

No breaking changes. This is a feature release that's fully backward compatible with v1.0.0.

---

Full Changelog: v1.0.0...v1.1.0

v1.0.0 - Complete Responsive Layout Redesign

Q-Shape v1.0.0 - Complete Responsive Layout Redesign

🎉 Major Release

This is the first official release of Q-Shape (Quantitative Shape Analyzer), featuring a complete responsive layout redesign and comprehensive SHAPE 2.1 implementation.

✨ Major Features

Coordination Geometry Analysis

• Complete SHAPE 2.1 Coverage: All 82 reference geometries from coordination numbers 1-12
• Advanced Algorithms: Kabsch alignment, Hungarian algorithm for optimal atom matching
• Comprehensive Metrics: Shape measures, quality scores, bond statistics, angular distortion
• Intensive Analysis Mode: Exhaustive permutation testing for maximum accuracy

3D Visualization

• Interactive Molecular Viewer: Real-time 3D visualization powered by Three.js
• Orbital Controls: Rotate, zoom, and pan to examine structures from any angle
• Overlay Comparison: Show ideal geometry overlaid with actual structure
• Auto-rotation: Optional automatic rotation for presentations
• Atom Labels: Toggle labels for better structure identification

Modern Responsive Design

• Mobile-First Layout: Beautiful design that works on phones, tablets, and desktops
• Responsive Breakpoints: Optimized layouts at 640px, 768px, 1024px, and 1200px
• Card-Based UI: Clean, modern card system with consistent spacing
• Indigo/Purple Theme: Professional gradient color scheme
• Smooth Animations: Polished transitions and hover effects

🔧 Technical Improvements

Architecture

• React 18: Modern functional components with hooks (useState, useEffect, useCallback, useMemo)
• CSS Architecture: Migrated from inline styles to maintainable CSS file (590 lines)
• Performance: Optimized rendering with proper dependency management
• Three.js Integration: Hardware-accelerated 3D graphics with shadow mapping

Layout Fixes

• ✅ Replaced fixed grid layouts with responsive CSS Grid
• ✅ Main layout collapses from 2-column to single-column on smaller screens
• ✅ Eliminated large empty spaces and misaligned blocks
• ✅ Proper spacing and alignment at all breakpoints
• ✅ Consistent card styling throughout the application

Code Quality

• Maintainable CSS: Semantic class names (.app-container, .card, .button-primary, etc.)
• Reduced Code: Net reduction of 42 lines while adding features
• Better Organization: Separated concerns (logic vs. styling)
• Normalized Spacing: Consistent whitespace throughout codebase

📊 File Statistics

• Total Lines: ~4,000 lines of React code
• CSS: 590 lines of responsive styling
• Reference Geometries: 82 geometries across 12 coordination numbers
• Bundle Size (gzipped):
  • JavaScript: 176.59 kB
  • CSS: 2.16 kB

🚀 Deployment

• GitHub Pages: https://HenriqueCSJ.github.io/q-shape/
• Automatic CI/CD: GitHub Actions workflow for continuous deployment
• Browser Support: Modern browsers (Chrome, Firefox, Safari, Edge)

📝 Usage

1. Visit the deployed application
2. Load a molecular structure file (.xyz format)
3. Select the central metal atom
4. Adjust coordination radius (or use auto-detection)
5. Run standard or intensive analysis
6. Visualize results in interactive 3D viewer
7. Generate PDF report with detailed analysis

🙏 Citation

If you use Q-Shape in your research, please cite:

Junior, H. C. S. Q-Shape (Quantitative Shape Analyzer). 2025.

📜 License

See LICENSE file for details.

🔗 Links

• Live Demo: https://HenriqueCSJ.github.io/q-shape/
• Repository: https://github.com/HenriqueCSJ/q-shape
• Issues: https://github.com/HenriqueCSJ/q-shape/issues

---

Built with ❤️ using React, Three.js, and modern web technologies