feat: improved backend, union handling, tensor creation APIs

[yxlao]

Overview

This pull request introduces refactoring and enhancements to the camtools backend module, focusing on improved type handling, backend compatibility, and streamlined operations across NumPy and PyTorch. The changes aim to enhance maintainability, performance, and usability.

Key Changes

• Renaming of Backend Decorators:

  • Renamed @tensor_to_auto_backend to @tensor_backend_auto to clarify its automatic backend selection functionality.
  • Renamed @tensor_to_numpy_backend to @tensor_backend_numpy and @tensor_to_torch_backend to @tensor_backend_torch, making their specific backend operations more explicit.

• Enhanced Type Hints and Tensor Operations:

  • Updated the handling of tensor type hints to support Union types, allowing more versatile function signatures.
  • Introduced new utility functions such as create_array, create_ones, create_zeros, and create_empty. These functions standardize tensor creation across different backends and are explicitly tied to the specified backend literal.

• Advanced Tensor Type and Shape Checks:

  • Improved _assert_tensor_hint to handle Union types effectively, enhancing the robustness of type and shape verifications.
  • Updated error handling to provide more specific ValueError exceptions related to tensor shapes and dtypes, standardizing error messages across the module.

• Backend Handling Improvements:

  • Optimized @tensor_backend_auto decorator for more efficient backend determination and tensor conversion.
  • Added explicit backend specification via a Literal["numpy", "torch"] parameter to manage backend-dependent tensor operations better.

• Documentation and Code Clean-Up:

  • Conducted a major clean-up in the backend module to remove deprecated functions related to direct backend management.
  • Enhanced docstrings for improved clarity and detailed usage information.
  • Revised internal utility functions for backend conversions to reduce redundancy and enhance performance.

Testing and Compatibility

• Expanded the test suite in test_backend.py to cover new scenarios introduced by Union type hints and new tensor creation functions.
• Adapted all existing tests to the refactored backend handling and type checks to ensure comprehensive coverage and reliability.