Release v0.8.0

Overview

This release focuses on improving the clarity and consistency of the JohansenModel API through systematic refactoring of variant names. All computational logic remains identical, ensuring full backward compatibility at the functional level while providing clearer, more descriptive naming conventions.

Breaking Changes

JohansenModel Variant Renaming

The following JohansenModel enum variants have been renamed for improved clarity and logical consistency:

Old Name	New Name	Model
InterceptNoTrendNoInterceptInCoint	InterceptNoTrendUnrestrictedIntercept	Model 2
InterceptTrendWithTrendInCoint	InterceptTrendUnrestrictedInterceptRestrictedTrend	Model 3
InterceptTrendNoTrendInCoint	InterceptTrendUnrestrictedBoth	Model 4

Migration Guide:

• Update all references to use the new variant names
• The numeric model identifiers (0-4) remain unchanged
• All computational behavior is identical

Improvements

Naming Convention Enhancements

Clearer Constraint Expression:

• Unrestricted indicates terms not fully explained by cointegration relationships
• Restricted indicates terms fully explained by cointegration relationships
• Removes logical contradictions in previous naming (e.g., models with trends no longer contain "NoTrend")

Enhanced Readability:

• Model 2: Now clearly shows it has unrestricted intercept terms
• Model 3: Explicitly indicates unrestricted intercept but restricted trend
• Model 4: Clearly states both intercept and trend are unrestricted

Documentation Updates

• Library Usage Documentation: Updated LIBRARY_USAGE.md with new variant names and corrected table references
• API Documentation: All inline documentation and comments updated to reflect new naming convention

Testing

• Comprehensive Test Updates: All 13 test cases updated to use new variant names
• Validation: All tests pass with identical assertions and logic
• Coverage: No reduction in test coverage; all functionality remains fully tested

Implementation Details

Files Modified

Core Implementation:

• src/johansen_models.rs - Primary enum variant definitions and implementations
• src/johansen_statistics.rs - F matrix construction logic references
• src/data_storage/thread_manager.rs - Eigenvalue counting logic references

Testing:

• src/tests/johansen_models_test.rs - Complete test suite updates

Documentation:

• LIBRARY_USAGE.md - Model variant reference table and examples

Commit History

This release includes 4 atomic commits following conventional commit standards:

1. refactor(johansen): Primary model variant naming improvements
2. test(johansen): Comprehensive test suite updates
3. refactor(statistics): Statistical computation module updates
4. docs(library): Library documentation updates

Stability Guarantees

• Functional Compatibility: All computational results remain identical
• Numeric Model IDs: Model numbers (0-4) unchanged for CLI compatibility
• Statistical Accuracy: No changes to underlying mathematical implementations
• Performance: Zero performance impact from naming changes

Technical Notes

• Compilation: Clean rebuild recommended to update all references
• Dependencies: No dependency changes
• Binary Compatibility: CLI interface unchanged (uses numeric model IDs)

Migration Path

For applications using the old variant names:

// Before (v0.7.0 and earlier)
JohansenModel::InterceptNoTrendNoInterceptInCoint

// After (v0.8.0+)  
JohansenModel::InterceptNoTrendUnrestrictedIntercept

// Numeric IDs remain the same
JohansenModel::from_number(2) // Still returns the same model functionality

---

Full Changelog: v0.7.0...v0.8.0

Release v0.7.0

Overview

Version 0.7.0 introduces significant improvements in project organization, documentation structure, and code quality. This release focuses on enhanced developer experience through modular documentation, test restructuring, and API refinements while maintaining full backward compatibility.

Major Improvements

Documentation & Project Structure

• Modular AI Agent Guidelines: Complete restructuring of project guidelines into specialized files:
  • Created .agents/ directory with task-specific guidance files
  • code-generation.md for programming standards and practices
  • testing.md for test strategies and statistical validation
  • git-workflow.md for version control and commit conventions
  • documentation.md for documentation writing standards
  • performance.md for optimization guidelines and benchmarking
• Enhanced Library Documentation: Added comprehensive LIBRARY_USAGE.md with detailed API usage examples
• Simplified README: Streamlined main README to focus on essential information while directing users to specialized documentation
• Example Improvements: Updated library_usage_example.rs with more practical parameters for faster testing

Code Organization & Architecture

• Centralized Test Structure: Moved all data_storage tests from embedded modules to centralized src/tests/ directory
  • Relocated append writer, uleb128, and integration tests
  • Improved test discoverability and maintenance
  • Better separation of test code from production modules
• Data Storage API Enhancement:
  • Simplified filename convention removing num_runs parameter: eigenvalues_model{}_dim{}_steps{}.dat
  • Added read_all_data() method for unrestricted data access
  • Enhanced read_data() with strict validation and actionable error messages

Code Quality & Maintenance

• Style Improvements: Applied Clippy suggestions for modern Rust formatting
  • Converted to inlined format arguments in display_utils.rs
  • Fixed clippy::uninlined_format_args warnings
• Cleanup: Removed redundant temporary files and consolidated example code

API Changes

Data Storage Module

• Filename Format Change: Simplified from eigenvalues_model{}_dim{}_steps{}_{}.dat to eigenvalues_model{}_dim{}_steps{}.dat
• New Method: read_all_data() - Retrieves all available records without validation
• Enhanced Method: read_data() - Now includes comprehensive validation with helpful error messages

Backward Compatibility

This release maintains full backward compatibility for the core statistical computation APIs. The data storage filename format change affects only new data files; existing files continue to work normally.

Migration Guide

For Library Users

• No code changes required for existing statistical computation functionality
• New data files will use the simplified filename format automatically
• Existing data files continue to work without modification

For Contributors

• Review the new modular documentation structure in .agents/ directory
• Follow updated guidelines for specific development tasks
• Tests are now centralized in src/tests/ directory

Technical Details

Dependencies

No changes to external dependencies. All existing dependencies remain unchanged:

• nalgebra and nalgebra-lapack for matrix operations
• rand ecosystem for random number generation
• rayon for parallel computation

Performance

No performance regressions. All optimizations from previous releases remain active:

• Link-time optimization (LTO) enabled
• Maximum optimization level (opt-level = 3)
• Single codegen unit for better optimization
• Panic abort strategy for reduced binary size

Testing

All existing tests continue to pass. The test restructuring improves maintainability without affecting functionality.

Contributors

Special thanks to all contributors who helped improve the project structure and documentation quality in this release.

Release v0.6.2

Overview

Version 0.6.2 is a maintenance release focused on code organization, documentation improvements, and enhanced developer experience. This release refactors the internal architecture while maintaining full backward compatibility with the public API.

Improvements

Code Organization & Architecture

• Modular Analysis System: Introduced a new simulation_analyzers module with functional approach replacing trait-based analyzers
• Enhanced API Boundaries: Improved module visibility with better encapsulation using pub(crate) and centralized public API exports through lib.rs
• Test Infrastructure Overhaul: Comprehensive test reorganization moving integration tests from tests/ to src/tests/ for better proximity to source code
• Module Visibility: Cleaner public API boundaries while maintaining internal accessibility for testing

Documentation & Examples

• Library Usage Example: Added examples/readme_example.rs demonstrating library integration
• README Updates: Updated usage examples to match the new API structure with corrected import paths
• Code Documentation: Improved inline documentation and converted problematic doctests to text examples
• API Documentation: Marked internal implementation details with #[doc(hidden)] for cleaner public documentation

Bug Fixes

• CLI Model Consistency: Fixed potential inconsistency in data reading demo where hardcoded model was replaced with user-selected model from CLI arguments

Developer Experience

• Better Test Organization: Split large integration test files into focused, modular test suites
• Improved Import Structure: Fixed import paths from external crate references to proper internal crate:: references
• Enhanced Code Quality: Better separation of concerns with functional approach in simulation analysis

Migration Guide

This release maintains full backward compatibility. No changes are required for existing users of the library or CLI tool.

For Library Users

• The core API (EigenvalueSimulation, JohansenModel) remains unchanged
• All existing functionality is preserved with improved internal organization

For CLI Users

• All command-line options and behavior remain identical
• Users will benefit from more consistent model handling in data reading operations

Technical Details

Refactoring Summary

• 21 commits since v0.6.1
• 2 pull requests merged for major refactoring efforts
• Files reorganized: Test files moved to improve code proximity and enable white-box testing
• API improvements: Better encapsulation without breaking changes

Conventional Commits Used

This release follows conventional commit standards with clear categorization:

• refactor: Internal code improvements and reorganization
• docs: Documentation and example improvements
• test: Test infrastructure and organization changes
• fix: Bug fixes for consistency issues

What's Next

This release establishes a solid foundation for future development with:

• Cleaner modular architecture ready for new features
• Improved test infrastructure supporting both unit and integration testing
• Better documentation structure for enhanced user experience
• Robust API boundaries enabling safer internal refactoring

---

Full Changelog: v0.6.1...v0.6.2

Release v0.6.1

Highlights

• API Refactoring
  • EigenvalueSimulation now takes a model argument and has an updated new() constructor with parameters reordered to specify the model first.
  • run_simulation() and run_simulation_quiet() only execute one model at a time; loop over models yourself if needed.
  • run_model_simulation() was restructured to follow SOLID principles and is now part of the parallel_compute module.
• Streamlined Statistics Workflow
  • Removed the statistics collection thread from parallel_compute; the main function now analyzes results directly.
  • analyze_simulation_statistics processes a single model and immediately prints statistics.
• Testing and Structure
  • All #[cfg(test)] unit tests originally under src/ have been moved to the tests/ directory following Rust conventions.
  • Functions in the data_storage sub-module were reorganized for clarity and future expansion.
• Tools and Documentation
  • analyze_dat_quality.sh has improved compression ratio calculations and messages for more accurate DAT file quality assessment.
  • Added a new F_MATRIX.md file and expanded the ``Theoretical Background'' section of the README to explain how each Johansen model builds its F matrix.
  • Updated the README to clarify the return type of read_data.

Notes

• Breaking Changes
  Existing code must adapt to the new API:
  • When creating EigenvalueSimulation, pass the model argument.
  • To simulate multiple models, call run_simulation() in a loop.

Release v0.6.0

Major Features

File Format V6 with ULEB128 Optimization

• Upgraded data storage format to V6 with variable-length integer encoding
• Implemented ULEB128 (Unsigned Little Endian Base 128) encoding for more efficient data storage
• Significantly reduced file sizes while maintaining data integrity

Enhanced DAT Analysis Tools

• New comprehensive DAT file encoding quality analysis script
• Added parallel compression capabilities with pure shell mathematics
• Improved data analysis efficiency for large-scale simulations

Code Quality Improvements

Modular Architecture Refactoring

• Split append_writer into modular components following SOLID principles
• Improved code maintainability and testability
• Enhanced separation of concerns in data storage modules

Code Quality Enhancements

• Fixed all clippy warnings for improved code quality
• Applied consistent formatting with cargo fmt
• Enhanced type safety and validation

Documentation & Development Experience

Comprehensive Documentation

• Added detailed DATA_FORMAT.md specification
• Enhanced README with updated CLI help
• Improved agent guidelines and development standards

Development Environment

• Enhanced Docker container with data analysis tools
• Optimized package installation process
• Added cargo fmt and clean to development setup

Development Workflow

• Enhanced git workflow with systematic command execution steps
• Consolidated agent guidelines for better consistency
• Improved development standards and best practices

Technical Details

• Compatibility: File format V6 maintains backward compatibility for reading older formats
• Performance: ULEB128 encoding provides variable-length integer storage optimization
• Quality: All code passes clippy linting and follows Rust best practices

Impact

This release focuses on data storage efficiency, code quality, and developer experience. The new file format provides significant space savings for large-scale Johansen cointegration test simulations while maintaining numerical precision and statistical accuracy.

Release v0.5.0

Major Features

Enhanced Data Storage with Format V5

• Upgraded file format from V4 to V5 with comprehensive parameter validation
• Added header metadata including model, dimension, and steps parameters for data integrity
• Intelligent file validation that automatically recreates incompatible files from previous versions
• Improved error handling with contextual information showing model/dim/steps mismatches

CLI Improvements

• New version flag: Added --version and -v options to display application version
• Better user experience for checking software version

Bug Fixes

• Fixed remaining time estimation in resume mode to use current session progress instead of total progress
• More accurate progress tracking when resuming interrupted simulations

Breaking Changes

• File format upgrade: Existing V4 data files will be automatically recreated when accessed
• API changes: AppendOnlyWriter::new() removed in favor of unified with_expected_size() API
• Return type change: read_append_file() now returns (data, model, dim, steps) tuple instead of just data

Migration Guide

• Automatic migration: Old V4 files will be automatically recreated when accessed
• No manual action required: The upgrade process is transparent to users
• Data preservation: All existing data will be preserved during the upgrade process

Testing & Quality

• Comprehensive test updates to validate new header parameters
• Enhanced error message clarity with contextual model/dimension/steps information
• Improved validation logic to prevent file misuse across different simulation parameters

Release v0.4.0

Key Highlights

• ~10% File Size Reduction: Combined storage optimizations reduce simulation file sizes significantly
• Enhanced Performance: Aggressive compiler optimizations for maximum runtime performance
• Improved UX: Better progress reporting with formatted numbers for large-scale simulations

Storage Optimizations

• Seed Storage Optimization: Reduced seed field from u64 to u32 (50% size reduction per field)
• Eigenvalue Count Optimization: Compressed from u32 to u8 (75% size reduction per field)
• Combined Impact: ~7.3% overall storage reduction for typical simulation files

Performance Improvements

• Aggressive Compiler Optimizations:
  • Link-time optimization (LTO) enabled
  • Maximum optimization level (opt-level = 3)
  • Reduced codegen units for better optimization
  • Overflow checks disabled for release builds
  • Panic strategy set to abort for smaller binaries

Type Safety & Reliability

• Enhanced Validation: Tightened eigenvalue count limits from 1000 to 255 (more realistic bounds)
• Overflow Protection: Added safeguards for eigenvalue_count exceeding u8::MAX
• Improved Error Handling: Better data integrity checks with panic on magic header mismatch
• Zero-Cost Conversions: Safe u32→u64 conversion maintains RNG compatibility

User Experience

• Formatted Progress Display: Added thousand separators to progress reporting (e.g., "1,000,000" instead of "1000000")
• Better Readability: Enhanced checkpoint resume information for large-scale simulations
• Consistent API: Updated all function signatures for improved type consistency

Development Infrastructure

• DevContainer Improvements: Added git auto-sync for consistent development environment
• Comprehensive Testing: Added boundary condition tests and overflow protection validation

Technical Details

• File Format: EIGENVALS_V2 → V3 → V4 (automatic migration)
• API Changes: Seed parameters changed from u64 to u32 across all functions
• Memory Footprint: Reduced per-record storage overhead

Migration Notes

• Automatic: Existing data files will be automatically migrated on first access
• No Action Required: All format upgrades happen transparently
• Performance: Zero-cost abstractions maintain computational efficiency

Release v0.3.0

Improvements

Complete --quiet Flag Implementation

• Fixed incomplete quiet mode: The --quiet flag now properly suppresses ALL progress output
• Enhanced output control: Thread configuration messages now respect the quiet parameter
• Consistent behavior: All user-facing messages are now controlled by the --quiet flag
• New conditional printing system: Added robust macros for better output management

What's Fixed

Previously, the --quiet flag only suppressed some output messages, leaving thread information and other progress details still visible. This release completes the implementation:

• Thread configuration messages now hidden in quiet mode
• All simulation progress output properly suppressed
• Only essential system messages remain visible
• Perfect for automation and scripting scenarios

Usage Examples

# Before: quiet mode still showed thread info and some progress
# After: truly quiet output suitable for scripts

johansen-null-eigenspectra --dim 5 --runs 100,000 --quiet
# Now produces minimal output perfect for automation

Backward Compatibility

All existing functionality remains unchanged. This is purely an enhancement to the existing --quiet flag behavior.

Release v0.2.9

Performance Improvements

• Implemented adaptive buffer sizing for better write performance
• Added file pre-allocation to reduce I/O wait times
• Enlarged append writer buffer for improved throughput

Technical Details

This release focuses primarily on data storage performance optimizations and reliability improvements.

Release v0.2.6

This is the initial public release of Johansen Null Eigenspectra.

Features

• High-performance Monte Carlo simulation for Johansen cointegration test eigenvalues
• Support for all 5 Johansen model types (0-4)
• Multi-threaded parallel computation using Rust and LAPACK
• Configurable simulation parameters (dimensions, steps, runs)
• Cross-platform binaries for Linux and macOS
• Data export to .dat files for further analysis
• Command-line interface with comprehensive options

Installation

Download the appropriate binary for your platform from the assets below.

Usage & Documentation

See the README for detailed usage instructions, examples, and documentation.

Requirements

For pre-compiled binaries:

• Linux: Requires system LAPACK/BLAS libraries (usually pre-installed or available via package manager)
• macOS: No additional dependencies (uses built-in Accelerate framework)

For building from source:

• Rust toolchain, C compiler, and LAPACK development libraries