Skip to content

ALchemist v0.3.1

Choose a tag to compare

View all tags
@calebcoatney calebcoatney released this 13 Dec 00:50
· 89 commits to main since this release
v0.3.1
990e3ef

Release Notes - ALchemist v0.3.1

Release Date: December 12, 2025
Type: Production Release
Status: Stable

Summary

ALchemist v0.3.1 introduces critical bug fixes, comprehensive unit tests, enhanced documentation, and real-time WebSocket support for multi-client session management. This release improves stability, reliability, and developer experience while maintaining full backward compatibility with v0.3.0.

New Features

Real-Time Session Locking with WebSocket

  • Upgraded session locking to use WebSocket instead of HTTP polling
  • Instant lock status updates (< 100ms vs 5 second polling delay)
  • Automatic monitor mode switching when external controllers lock sessions
  • Reduced server load through event-driven architecture
  • Blue lock badge UI showing controller name and session status
  • Auto-reconnect with 5 second retry on disconnect

Session Locking for Programmatic Control

  • Lock/unlock REST endpoints with UUID token-based security
  • Automatic session locking when external applications connect
  • Clean single-controller workflow enforcement
  • Force unlock capability for recovery scenarios
  • Integration with Qt and Python script controllers

Comprehensive Unit Tests

  • New test suite covering core session API functionality
  • Tests for OptimizationSession with event system integration
  • SklearnModelExtended tests for contour data and calibration
  • AuditLog and session management test coverage
  • EventEmitter functionality validation
  • Example client and run API entry point tests
  • Initial test datasets for catalyst experiments

Bug Fixes

Critical Issues

  • Fixed multi-client iteration tracking: ExperimentManager now calculates iteration as max(existing) + 1 automatically

    • Prevents duplicate iteration numbers when multiple clients add experiments
    • Fully multi-client safe without manual iteration tracking

  • Fixed BoTorch/sklearn backend switching with incompatible transform types

    • Automatic transform type mapping in Session.train_model()
    • Maps BoTorch 'normalize'/'standardize' to sklearn 'minmax'/'standard'
    • Ensures proper data scaling when switching backends

  • Fixed sklearn GP numerical stability issues

    • Added safety checks for zero/negative predicted variances
    • Clamp predicted std to minimum 1e-6 to avoid division by zero
    • Validate calibration factors are finite before applying
    • Prevents NaN propagation and JSON serialization errors

Documentation

Comprehensive Restructuring

  • Added auto-generated Python API reference using mkdocstrings
    • Created python_overview.md landing page with API comparison table
    • Added detailed pages: session_class.md, search_space.md, models.md, acquisition.md
    • Configured mkdocstrings with Google-style docstrings

Navigation and Organization

  • Reorganized navigation structure for better UX
  • Added Python API section with usage guide and references
  • Consolidated REST API documentation under single overview
  • Added comprehensive session usage guide

Accuracy Corrections

  • Fixed variable type references (continuous → real throughout)
  • Corrected REST API endpoint paths (/api/v1 prefix, /model/ vs /models/)
  • Fixed parameter names (n_candidates → n_suggestions)
  • Updated acquisition strategy names (EI, PI, UCB vs spelled-out)
  • Removed non-existent endpoints, added missing documentation
  • Corrected cross-validation method documentation (k-fold only)

Content Consolidation

  • Removed redundancies (error_metrics.md merged into metrics_plot.md)
  • Consolidated API comparison tables
  • Removed duplicate installation instructions
  • Streamlined troubleshooting sections
  • Updated README.md with correct web app URL and cleaner formatting

Technical Improvements

Build and Tooling

  • Reorganized build tools for improved maintainability
  • Updated API run commands for consistency
  • Refined build hook configuration

Code Quality

  • Added comprehensive test coverage for core functionalities
  • Improved error handling and edge case validation
  • Enhanced logging for better debugging

Installation & Running

The installation and running instructions remain unchanged from v0.3.0:

# Install
pip install alchemist-nrel

# Run web application
alchemist-web

# Run desktop application
alchemist

For developers working in editable mode:

git clone https://github.com/NREL/ALchemist.git
cd ALchemist
pip install -e .

Backward Compatibility

All changes in v0.3.1 are fully backward compatible with v0.3.0. Existing session files, API calls, and client code will continue to work without modification.

Known Issues

None at this time.

Testing

Comprehensive unit test suite now included covering:

  • Core session API workflows
  • Model training and prediction
  • Event system integration
  • Audit logging and reproducibility
  • Multi-client scenarios
  • Error handling and recovery

Acknowledgments

This work is supported by the U.S. Department of Energy's Bioenergy Technologies Office (BETO) through the ChemCatBio Consortium.

License

BSD 3-Clause License

Links

Assets 2
Loading