Changelog
=========

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

Version 0.1.1 (2025-06-08)
---------------------------

Test Coverage & Quality Improvements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Comprehensive Test Suite Enhancement** ⭐
  - **Achieved 70.2% overall test coverage** (increased from 61%)
  - **214 passing tests** across all modules with 0 failures
  - **Zero regressions** - all existing functionality preserved
  - **Robust test architecture** with sophisticated mocking strategies

**Module-Specific Coverage Improvements**
  - **jaxabm/agentpy.py**: 20% → 68% (+48% improvement)
  - **jaxabm/api.py**: 0% → 93% (+93% improvement) 
  - **jaxabm/analysis.py**: 5% → 63% (+58% improvement)
  - **jaxabm/core.py**: 32% → 95% (+63% improvement)
  - **jaxabm/utils.py**: 16% → 99% (+83% improvement)
  - **jaxabm/agent.py**: 37% → 85% (+48% improvement)
  - **jaxabm/model.py**: 17% → 82% (+65% improvement)

**New Test Infrastructure**
  - Added ``tests/unit/test_agentpy.py`` (787 lines) - Complete AgentPy interface testing
  - Enhanced ``tests/unit/test_api.py`` - Public API comprehensive coverage
  - Enhanced ``tests/unit/test_utils.py`` - Utility functions near-complete testing
  - Enhanced ``tests/unit/test_core.py`` - Core framework near-complete testing

**Quality Assurance Features**
  - Comprehensive edge case testing and error handling validation
  - Integration tests for complex multi-component workflows
  - Sophisticated JAX array mocking and external dependency isolation
  - Property-based testing for dynamic attribute access

**Developer Experience Improvements**
  - Tests serve as living documentation with clear usage examples
  - Immediate feedback on code changes with comprehensive test coverage
  - Safe refactoring capabilities with robust regression detection
  - Enhanced collaboration confidence with validated API behavior

Version 0.1.0 (2025-06-08)
---------------------------

Major Updates
^^^^^^^^^^^^^

**Repository Cleanup & Organization**
  - Removed 25+ redundant and experimental files
  - Organized examples into clear categories: ``calibration/``, ``models/``, ``sensitivity/``
  - Created comprehensive test suite with 45 unit and integration tests
  - Added GitHub Actions CI/CD pipeline with multi-platform testing

**Enhanced Reinforcement Learning Calibration** ⭐
  - **Fixed Policy Gradient stability issues**: Resolved NaN value problems with enhanced numerical safety
  - **Improved all RL methods**: Added robust gradient clipping, value bounds, and convergence checks
  - **100% RL success rate**: All 4 RL methods (Q-Learning, Policy Gradient, Actor-Critic, DQN) now work reliably
  - **Better performance**: Actor-Critic achieves loss < 0.00001 on economic models

**Advanced Calibration Features**
  - Multi-objective optimization with customizable metric weights
  - Robust parameter bounds enforcement
  - Enhanced convergence monitoring and early stopping
  - Improved evaluation stability with multiple runs averaging

**Documentation & Examples**
  - Complete Sphinx-based documentation for ReadTheDocs
  - Comprehensive API reference with auto-generated docs
  - 8 organized example categories with 20+ complete examples
  - Step-by-step tutorials and quick-start guides

New Features
^^^^^^^^^^^^

**Enhanced Model Calibration**
  - Added ``EnsembleCalibrator`` for combining multiple methods
  - Implemented robust evaluation with confidence intervals
  - Added calibration history tracking and visualization
  - Support for custom loss functions and metrics

**Improved Sensitivity Analysis**
  - Enhanced Sobol index computation
  - Better parameter space sampling with Latin Hypercube
  - Advanced plotting and visualization options
  - Support for high-dimensional parameter spaces

**Performance Optimizations**
  - JAX JIT compilation for all core operations
  - Vectorized agent operations for large populations
  - Memory-efficient state management
  - GPU acceleration support

**Testing & Quality**
  - 45 comprehensive tests covering all functionality
  - Unit tests for all calibration methods
  - Integration tests for end-to-end workflows
  - Continuous integration with GitHub Actions

Bug Fixes
^^^^^^^^^^

**Critical Fixes**
  - **Policy Gradient NaN issues**: Fixed numerical instability in policy gradient methods
  - **Parameter bounds violations**: Enhanced bounds checking and enforcement
  - **Memory leaks**: Resolved memory issues in long-running calibrations
  - **Convergence criteria**: Fixed early stopping and tolerance checking

**Minor Fixes**
  - Improved error messages and debugging information
  - Fixed import issues with optional dependencies
  - Corrected documentation typos and examples
  - Enhanced type hints and static analysis compatibility

API Changes
^^^^^^^^^^^

**Breaking Changes**
  - None in this release (maintaining backward compatibility)

**Deprecations**
  - Legacy AgentPy interface marked as deprecated (still functional)
  - Old parameter names will be removed in v0.2.0

**New APIs**
  - ``ModelCalibrator.get_calibration_history()`` for training analysis
  - ``SensitivityAnalysis.plot_indices()`` for parameter importance visualization
  - Enhanced ``Model.run()`` with better progress tracking

Performance Improvements
^^^^^^^^^^^^^^^^^^^^^^^^^

**Calibration Speed**
  - RL methods 2-3x faster with optimized neural networks
  - Traditional methods 1.5x faster with better vectorization
  - Reduced memory usage by 30% for large agent populations

**Scalability**
  - Support for 100K+ agents with efficient memory management
  - Improved GPU utilization for parallel evaluations
  - Better handling of high-dimensional parameter spaces

Documentation
^^^^^^^^^^^^^

**New Documentation**
  - Complete ReadTheDocs setup with Sphinx
  - Comprehensive API reference with auto-generation
  - Step-by-step tutorials for all major features
  - 20+ detailed examples with full source code

**Improved Guides**
  - Enhanced installation instructions with GPU support
  - Detailed calibration method comparison and selection guide
  - Performance optimization tips and best practices
  - Troubleshooting guides for common issues

Migration Guide
^^^^^^^^^^^^^^^

From Previous Versions
"""""""""""""""""""""""

If you're upgrading from a previous version:

1. **No breaking changes** - all existing code should work
2. **Update imports** - some internal module paths may have changed
3. **Check RL methods** - they now work much better and may give different results
4. **Review examples** - many new examples available for reference

Recommended Updates
"""""""""""""""""""

- Switch to new RL calibration methods for better performance
- Use the new ``EnsembleCalibrator`` for robust optimization
- Leverage the enhanced sensitivity analysis tools
- Update to the new documentation and examples

Contributors
^^^^^^^^^^^^

Thanks to all contributors to this release:

- **Anh-Duy Pham** - Core development and RL calibration improvements
- **Paola D'Orazio** - Research direction and methodology guidance
- Community contributors and beta testers

Development Status
^^^^^^^^^^^^^^^^^^

**Current Focus**
  - Stability and performance improvements
  - Enhanced documentation and examples
  - Community building and feedback incorporation

**Next Release (v0.2.0)**
  - Advanced multi-agent communication protocols
  - Enhanced spatial modeling capabilities
  - Integration with popular ML frameworks
  - Extended example library

**Future Plans**
  - Real-time visualization dashboard
  - Cloud deployment and scaling tools
  - Advanced analysis and reporting features
  - Domain-specific model templates