Changelog

All notable changes to Surfacia will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

  • Comprehensive Sphinx documentation framework

  • Interactive SHAP visualization dashboard

  • Machine learning analysis pipeline

  • Complete CLI interface with workflow management

  • Intelligent workflow resumption capabilities

  • Molecular structure viewer and drawer utilities

  • Custom CSS styling with enhanced typography

  • Multi-scale molecular descriptor framework

Changed

  • Refactored CLI architecture for better modularity

  • Improved error handling and logging throughout

  • Enhanced workflow step validation and dependency checking

  • Optimized font and image sizing (30% increase)

  • Updated documentation structure and navigation

Fixed

  • Resolved ZhipuAI import warnings

  • Fixed workflow file dependency chain issues

  • Corrected CLI parameter mismatches

  • Addressed Sphinx build warnings and formatting issues

  • Fixed title underline length problems in RST files

[3.0.3] - 2026-05-14

Added

  • Introduced a packaged SPES-C candidate-prioritization layer in surfacia.ml.spes.

  • Added automatic SPES_Test_Set_Detailed_*.csv and metadata JSON outputs when ML analysis includes an external test set.

  • Added SHAP dashboard overlay switching between the raw test set and the SPES layer.

  • Added CLI and MCP support for --spes-csv.

  • Expanded documentation and homepage guidance for SPES usage.

Changed

  • Updated package version metadata to 3.0.3.

  • Updated documentation release/version metadata to 3.0.3.

Fixed

  • Aligned workflow auto-discovery so SPES overlay files can be picked up automatically by the final SHAP visualization step.

[3.0.2] - 2026-04-08

Changed

  • Pinned machine-learning dependency compatibility range: xgboost>=2.1.4,<3.0.0 and shap>=0.48.0,<0.49.0.

  • Updated package version metadata to 3.0.2.

  • Updated documentation release/version metadata to 3.0.2.

  • Added MCP server packaging entrypoint surfacia-mcp and integration docs.

Fixed

  • Documented and mitigated ml-analysis failures with errors like could not convert string to float: '[-3.xxxE0]' caused by incompatible xgboost/shap combinations.

  • Added explicit troubleshooting guidance for remote Linux/SSH workflow reruns of Step-7 (machine learning only).

[1.0.0] - 2024-XX-XX

Added

  • Initial release of Surfacia

  • Core molecular surface analysis functionality

  • Basic workflow implementation

  • Fundamental descriptor calculations

  • Jupyter notebook integration

  • Basic CLI interface

Features

  • Workflow Management: Complete 8-step analysis pipeline

  • Descriptor Calculation: Size/shape, electronic, and surface descriptors

  • Machine Learning: Feature selection, model training, and validation

  • Visualization: SHAP-based interpretable visualizations

  • CLI Tools: Command-line interface for all major functions

  • Utilities: Molecular viewer, drawer, and Gaussian rerun tools

Technical Details

  • Python 3.8+ compatibility

  • Integration with quantum chemistry software

  • Support for multiple molecular file formats

  • Extensible descriptor framework

  • Web-based interactive dashboards

Documentation

  • Complete API reference

  • User guides and tutorials

  • Command-line documentation

  • Theoretical background materials

  • Practical examples and use cases

Known Issues

  • Large molecular systems may require significant memory

  • Some advanced features require additional dependencies

  • Performance optimization ongoing for complex workflows

Migration Guide

This is the initial release, so no migration is required.

Deprecations

None in this release.

Security

No security issues identified in this release.

Contributors

  • Development Team

  • Community Contributors

  • Documentation Contributors

  • Testing and QA Team

Acknowledgments

Special thanks to: - The scientific computing community - Open source contributors - Beta testers and early adopters - Academic collaborators

Future Roadmap

Planned features for upcoming releases: - Enhanced parallel processing capabilities - Additional machine learning algorithms - Extended visualization options - Performance optimizations - Cloud computing integration - Mobile-friendly interfaces

Support

For support with this release: - Check the documentation at https://surfacia.readthedocs.io - Report issues on GitHub - Join community discussions - Contact the development team

Release Notes Format

Each release includes: - Added: New features and capabilities - Changed: Modifications to existing functionality - Deprecated: Features marked for future removal - Removed: Features removed in this release - Fixed: Bug fixes and corrections - Security: Security-related changes

Version Numbering

Surfacia follows semantic versioning: - Major (X.0.0): Breaking changes or major new features - Minor (0.X.0): New features, backward compatible - Patch (0.0.X): Bug fixes and minor improvements

Release Schedule

  • Major releases: Annually or for significant features

  • Minor releases: Quarterly for new features

  • Patch releases: As needed for critical fixes

  • Pre-releases: Available for testing new features

Compatibility

  • Python: 3.8, 3.9, 3.10, 3.11

  • Operating Systems: Windows, macOS, Linux

  • Dependencies: See requirements.txt for details

  • Hardware: Minimum 8GB RAM recommended

Installation

Install the latest version:

pip install surfacia

For development installation:

git clone https://github.com/username/surfacia.git
cd surfacia
pip install -e .[dev]