v3.1.1

What's Changed

• Feat: add Export HR action to generate and save updated HR files and bug fixes safeguards for mismatched or missing lambda inputs to avoid failures. by @QG-phy in #10
• DOC: revised installation guide with clearer separation between pre-built desktop app installation by @QG-phy in #11
• Version bumped to 3.1.1 by @QG-phy in #12

Full Changelog: v3.1.0...v3.1.1

v3.1.0

TBSOC v3.1.0 Release Notes

🎉 Overview

TBSOC v3.1.0 brings significant improvements to the user interface, enhanced data processing capabilities, and better user experience. This release focuses on GUI enhancements, improved parsing robustness, and better visualization.

✨ New Features

🎨 Enhanced User Interface

• Theme Support: Added comprehensive dark and light theme switching
• Light Default Theme: Changed default theme to light mode for better accessibility
• Improved Button Styling: Enhanced button design with theme-aware styling
• Standardized Layout: Consistent card styling and layout across all components

📊 Better Visualization

• Improved Band Plot Alignment: Enhanced y-axis range calculation for better band structure visualization
• MAE Display: Added Mean Absolute Error display in band plots
• Repositioned Annotations: Moved MAE annotation to top-right for better visibility

📚 Enhanced Documentation & Tutorials

• Interactive Tutorial Notebook: Added GaAs2 interactive tutorial notebook for SOC fitting
• GUI Screenshot: Added comprehensive GUI screenshot to documentation
• Enhanced Documentation: Updated README and feature descriptions

🔧 Improvements & Enhancements

Data Processing

• Improved Wannier90 Projection Parsing: Enhanced regex-based parsing for better robustness
• POSCAR Atom Filtering: Added filtering to match wannier90 projections automatically
• Better KPOINTS Parsing: Improved handling of missing symbols in KPOINTS files

Band Structure Analysis

• Band Alignment Shift: Added band alignment shift calculation to TB band computation
• Enhanced Visualization: Improved color schemes and visual consistency

User Experience

• Dark Theme Support: Complete dark mode implementation for low-light environments
• Responsive Design: Better layout consistency across different screen sizes
• Theme Persistence: Theme choice is saved between sessions

🐛 Bug Fixes

• Layout Consistency: Fixed card styling inconsistencies across the interface
• Button Styling: Resolved theme-related button styling issues
• Visualization Alignment: Fixed band plot alignment and y-axis calculation problems

📦 Installation

Desktop App (Recommended)

Download the installer for your platform:

• macOS: TBSOC-macOS.dmg
• Windows: TBSOC-Windows-Installer.exe

From Source

git clone https://github.com/qqgu/TBSOC.git
cd TBSOC
git checkout v3.1.0
uv sync
uv run python -m tbsoc.server.main

From PyPI

pip install tbsoc==3.1.0

🔄 Breaking Changes

None - this release is fully backward compatible with existing input files and workflows.

📊 Technical Details

Theme System

• Added complete theme infrastructure with CSS variables
• Light theme as default for better accessibility
• Theme persistence using localStorage
• Smooth theme switching without page reload

Data Processing Improvements

• Enhanced Wannier90 projection parsing with robust regex patterns
• Automatic POSCAR atom filtering to match projection requirements
• Improved KPOINTS file parsing with better error handling

Visualization Enhancements

• Improved band plot alignment algorithms
• Enhanced y-axis range calculation for optimal visualization
• MAE display integration with positioning optimization

🧪 Testing

• All existing tests pass
• Added new tests for theme functionality
• Enhanced test coverage for parsing improvements
• Cross-platform compatibility verified

🙏 Acknowledgments

Thanks to all contributors and users who provided feedback and suggestions during this release cycle!

📋 Full Changelog

Since v3.0.0:

• ece7233 feat: add GUI screenshot to documentation
• 1742205 docs: enhance GUI documentation with screenshot and updated features
• 21900ac feat: add GaAs2 interactive tutorial notebook for SOC fitting
• 556b73d feat: change default theme from dark to light
• 7447880 fix: standardize card styling and layout consistency
• 8adfff4 feat: enhance button styling with theme support
• c83f9dd feat: improve band plot alignment and y-axis range calculation
• cb87f60 feat: add theme support with dark and light modes
• 1bd0fd2 feat: improve wannier90 projection parsing with regex
• 3543ff5 feat: filter POSCAR atoms to match wannier90 projections
• 64f213d feat: update color scheme to dark theme in visualization components
• 20e54a7 feat: reposition MAE annotation to top-right of band plot
• 633dc6d feat: add MAE display and apply dark theme to BandPlot
• 94f821d feat: add band alignment shift to TB band calculation
• 54a9727 feat: improve KPOINTS parsing to handle missing symbols
• 82cfbf5 update readme

---

Previous Release: v3.0.0
Next Release: v3.2.0 (planned)

For detailed commit history, see the commit log.

v3.0.0

Release Notes

🎉 Major Features

Desktop GUI Application

• Modern Web-Based Interface: Interactive desktop application with real-time band structure visualization
• Live Parameter Tuning: Drag sliders to instantly preview SOC effects on band structures
• One-Click Fitting: JAX-accelerated optimization with progress tracking
• Visual Weight Function: Side-by-side display of Gaussian weighting window

Partial Band Fitting Support

• Robust Alignment: Handles cases where DFT calculations have fewer bands than TB model
• Smart Matching: Bottom-half band alignment heuristic for improved convergence
• Flexible Overlap: Automatically adjusts to available band overlap

Enhanced Fitting Algorithm

• Gaussian Weighting: Switched from exponential to Gaussian weight function for more physically meaningful energy windows
• Non-Negative Constraints: Enforces λ ≥ 0 during optimization for physical consistency
• Improved Alignment: Refined scan range and comparison window for better band matching

🚀 Performance Improvements

• JAX-Powered: Sub-second fitting times for typical systems
• Automatic Differentiation: Exact gradients for robust convergence
• Optimized Layout: Reduced margins and improved space utilization in GUI

🛠️ Developer Experience

CI/CD Workflows

• Automated Testing: Unit tests across Ubuntu, macOS, Windows with Python 3.9-3.12
• Automated Packaging:
  • macOS: DMG installer with drag-to-Applications
  • Windows: NSIS installer with Start Menu shortcuts
• Auto-Release: Automatic GitHub release creation on version tags

Application Branding

• Custom Icon: Professional logo integrated into installers
• Bundle Identifier: Proper macOS app identification (com.tbsoc.app)

📝 Documentation

• Updated README: Enhanced with logo, badges, and comprehensive feature list
• Icon Generator: Automated script to convert PNG logos to .icns and .ico formats
• Workflow Documentation: Clear instructions for building and releasing

🐛 Bug Fixes

• Fixed Vertical Resize: Plot now properly expands when window is resized vertically
• Restored TB Bands: Fixed regression where TB bands disappeared after UI changes
• NSIS Icon Path: Corrected Windows installer icon reference

📦 Installation

Desktop App (Recommended)

Download the installer for your platform:

• macOS: TBSOC-macOS.dmg
• Windows: TBSOC-Windows-Installer.exe

From Source

git clone https://github.com/qqgu/TBSOC.git
cd TBSOC
uv sync
uv run python -m tbsoc.server.main

🔄 Breaking Changes

None - this release is fully backward compatible with existing input files.

📊 Technical Details

Alignment Algorithm Updates

• Scan range: 0 to n_dft - n_tb/2 (previously limited when n_dft < n_tb)
• Comparison window: Bottom max(n_tb/2, 1) bands for robust matching
• Weight function: exp(-(E - E_f)² / (2σ²)) (Gaussian, previously exponential)

GUI Architecture

• Frontend: React + Vite + Plotly.js
• Backend: FastAPI + JAX
• Build: PyInstaller with platform-specific icons

🙏 Acknowledgments

Thanks to all contributors and users who provided feedback during development!

---

Full Changelog: QG-phy/TBSOC@v2.0.0...v3.0.0

v2.0.0

What's Changed

• Update README.md by @QG-phy in https://github.com/QG-phy/TBSOC/pull/4
• Update README.md by @shishirkrpandey in https://github.com/QG-phy/TBSOC/pull/5
• add command line tool by @QG-phy in https://github.com/QG-phy/TBSOC/pull/6
• add license by @QG-phy in https://github.com/QG-phy/TBSOC/pull/8

New Contributors

• @QG-phy made their first contribution in https://github.com/QG-phy/TBSOC/pull/4
• @shishirkrpandey made their first contribution in https://github.com/QG-phy/TBSOC/pull/5

Full Changelog: QG-phy/TBSOC@v0.1.0...v2.0.0

v0.1.1

Feature
Add on-site soc term on full p and d oribitals

Wannier_Add_onsite_SOC

v0.1.0

Update README.md