refactor(unity): apply coding standards to unity module and reorganize scripts

[ryanmccann1024]

Related Issue(s):
N/A - Part of ongoing coding standards refactoring initiative

Description:
This PR applies comprehensive coding standards to the Unity cluster management module and reorganizes bash scripts for better maintainability. The Unity module manages SLURM job execution and result fetching for the FUSION project on the Unity cluster at UMass Amherst.

🔧 Type of Change

Primary Change Type:

• 🐛 Bug Fix - Non-breaking change that fixes an issue
• ✨ New Feature - Non-breaking change that adds functionality
• 💥 Breaking Change - Change that would cause existing functionality to break
• 🔄 Refactor - Code change that neither fixes a bug nor adds a feature
• 📚 Documentation - Documentation only changes
• 🧪 Tests - Adding missing tests or correcting existing tests
• 🏗️ Build/CI - Changes to build process or CI configuration
• 🎨 Style - Code style changes (formatting, missing semicolons, etc.)
• ⚡ Performance - Performance improvements
• 🔒 Security - Security vulnerability fixes

Component(s) Affected:

• CLI Interface (fusion/cli/)
• Configuration System (fusion/configs/)
• Simulation Core (fusion/core/)
• ML/RL Modules (fusion/modules/rl/, fusion/modules/ml/)
• Routing Algorithms (fusion/modules/routing/)
• Spectrum Assignment (fusion/modules/spectrum/)
• SNR Calculations (fusion/modules/snr/)
• Visualization (fusion/visualization/)
• GUI Interface (fusion/gui/)
• Unity/HPC Integration (fusion/unity/)
• Testing Framework (tests/)
• Documentation
• GitHub Workflows (.github/)
• Build/Dependencies

🧪 Testing

Test Coverage:

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• Existing tests still pass
• Performance impact assessed

Test Details:
Created comprehensive unit test suite for Unity module:

• test_unity_fetch_results.py - 12 tests covering path manipulation and file operations
• test_unity_make_manifest.py - 24 tests covering manifest creation and validation
• test_unity_submit_manifest.py - 11 tests covering job submission functionality
• Total: 47 tests, all passing

Test Configuration Used:

# Standard test configuration
[general_settings]
# Tests use mock data and temporary files

Commands to Reproduce Testing:

# Run Unity module tests
python -m pytest tests/test_unity_fetch_results.py tests/test_unity_make_manifest.py tests/test_unity_submit_manifest.py -v

# Quick test run
python -m pytest tests/test_unity_fetch_results.py tests/test_unity_make_manifest.py tests/test_unity_submit_manifest.py -q

Test Results:

• Operating System: macOS (Darwin 25.0.0)
• Python Version: 3.11.9
• Test Environment: Local development
• Test Status: 47 passed in 0.08s

📊 Impact Analysis

Performance Impact:

• No performance impact
• Performance improved
• Minor performance decrease (acceptable)
• Significant performance impact (needs discussion)

Memory Usage:

• No change in memory usage
• Memory usage optimized
• Minor increase in memory usage
• Significant memory impact

Backward Compatibility:

• Fully backward compatible
• Minor breaking changes with migration path
• Major breaking changes (requires version bump)

Dependencies:

• No new dependencies
• New dependencies added (list in Additional Notes)
• Dependencies removed/updated

🔄 Migration Guide

Breaking Changes (if any):
None - All changes are backward compatible

Migration Steps:
No migration required - all existing functionality preserved

Before/After Examples:

# Function names updated for clarity (internal changes only)
# Before (old internal function names)
# twin_input_path(path) 

# After (new descriptive function names)  
# convert_output_path_to_input_path(path)

✅ Code Quality Checklist

Architecture & Design:

• Follows established architecture patterns
• Code is modular and follows separation of concerns
• Interfaces are well-defined and documented
• Error handling is comprehensive
• Logging is appropriate and informative

Code Standards:

• Code follows project style guidelines
• Variable and function names are descriptive
• Code is properly commented
• Complex logic is documented
• No dead code or unused imports

Configuration & CLI:

• CLI arguments follow established patterns
• Configuration validation updated (if needed)
• Schema updated for new config options
• Backward compatibility maintained for configs

Security:

• No sensitive information hardcoded
• Input validation performed where needed
• No security vulnerabilities introduced
• Dependencies scanned for vulnerabilities

📚 Documentation

Documentation Updates:

• Code comments added/updated
• API documentation updated
• User guide/tutorial updated
• Configuration reference updated
• CHANGELOG.md updated
• README updated (if needed)

Examples Added:

• Usage examples in docstrings
• Configuration examples
• CLI usage examples
• Integration examples

🚀 Deployment

Deployment Considerations:

• Safe to deploy to all environments
• Requires environment-specific configuration
• Needs database migration (if applicable)
• Requires manual steps (document below)

Manual Steps Required:
None - All changes are code-level improvements

🔍 Review Guidelines

For Reviewers:

• PR description is clear and complete
• Code changes align with described functionality
• Tests are comprehensive and pass
• Documentation is adequate
• No obvious security issues
• Performance impact is acceptable

Review Focus Areas:

• Review the new script organization in tools/scripts/ vs fusion/unity/scripts/
• Validate the comprehensive test coverage for Unity module
• Check the enhanced error handling and logging in fetch_results.py
• Verify bash script improvements follow the new coding standards

📝 Additional Notes

Key Improvements Made:

1. Enhanced Unity Module Structure:

   • Refactored fetch_results.py with improved naming, comprehensive docstrings, and proper logging
   • Enhanced make_unity_venv.sh with better error handling and status reporting
   • Applied FUSION coding standards consistently throughout

2. Comprehensive Test Suite:

   • Created 47 unit tests covering all Unity module functionality
   • Tests include path manipulation, manifest processing, and job submission
   • Ensures no regressions during future changes

3. Script Organization:

   • Separated Unity-specific infrastructure scripts from general-purpose tools
   • Unity-specific scripts remain in fusion/unity/scripts/
   • General-purpose scripts moved to tools/scripts/ for broader reusability

4. Documentation:

   • Added bash script coding standards to CODING_STANDARDS.md
   • Created comprehensive README files for both script directories
   • Enhanced all docstrings with Sphinx format

Open Questions:
None - Implementation is complete and tested

Future Work:

• Continue applying coding standards to remaining modules in the codebase
• Consider adding integration tests for Unity cluster workflow

Related PRs:
This is part of the ongoing coding standards refactoring initiative across the FUSION codebase

---

🏁 Final Checklist

Before submitting this PR, confirm:

• I have followed the contributing guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published