Initial commit as Claude developed it

2025-06-22 12:50:10 +02:00
parent 270c540556
commit d6dc083a5a
38 changed files with 10197 additions and 6 deletions
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -0,0 +1,537 @@
+# Development Guide
+
+This guide provides comprehensive information for developers who want to contribute to the SVM Classifier C++ project.
+
+## Table of Contents
+
+- [Development Environment Setup](#development-environment-setup)
+- [Project Structure](#project-structure)
+- [Building from Source](#building-from-source)
+- [Testing](#testing)
+- [Code Style and Standards](#code-style-and-standards)
+- [Contributing Guidelines](#contributing-guidelines)
+- [Debugging and Profiling](#debugging-and-profiling)
+- [Documentation](#documentation)
+- [Release Process](#release-process)
+
+## Development Environment Setup
+
+### Prerequisites
+
+**Required:**
+- C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2019+)
+- CMake 3.15+
+- Git
+- libtorch (PyTorch C++)
+- pkg-config
+
+**Optional (but recommended):**
+- Doxygen (for documentation)
+- Valgrind (for memory checking)
+- lcov/gcov (for coverage analysis)
+- clang-format (for code formatting)
+- clang-tidy (for static analysis)
+
+### Quick Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/svm-classifier.git
+cd svm-classifier
+
+# Run the automated setup
+chmod +x install.sh
+./install.sh --build-type Debug
+
+# Or use the validation script for comprehensive testing
+chmod +x validate_build.sh
+./validate_build.sh --verbose --performance --memory-check
+```
+
+### Docker Development Environment
+
+```bash
+# Build development image
+docker build --target development -t svm-dev .
+
+# Run development container
+docker run --rm -it -v $(pwd):/workspace svm-dev
+
+# Inside container:
+cd /workspace
+mkdir build && cd build
+cmake .. -DCMAKE_PREFIX_PATH=/opt/libtorch -DCMAKE_BUILD_TYPE=Debug
+make -j$(nproc)
+```
+
+## Project Structure
+
+```
+svm-classifier/
+├── include/svm_classifier/     # Public header files
+│   ├── svm_classifier.hpp      # Main classifier interface
+│   ├── data_converter.hpp      # Tensor conversion utilities
+│   ├── multiclass_strategy.hpp # Multiclass strategies
+│   ├── kernel_parameters.hpp   # Parameter management
+│   └── types.hpp               # Common types and enums
+├── src/                        # Implementation files
+│   ├── svm_classifier.cpp
+│   ├── data_converter.cpp
+│   ├── multiclass_strategy.cpp
+│   └── kernel_parameters.cpp
+├── tests/                      # Test suite
+│   ├── test_main.cpp           # Test runner
+│   ├── test_svm_classifier.cpp # Integration tests
+│   ├── test_data_converter.cpp # Unit tests
+│   ├── test_multiclass_strategy.cpp
+│   ├── test_kernel_parameters.cpp
+│   └── test_performance.cpp    # Performance benchmarks
+├── examples/                   # Usage examples
+│   ├── basic_usage.cpp
+│   └── advanced_usage.cpp
+├── external/                   # Third-party dependencies
+├── cmake/                      # CMake configuration files
+├── .github/workflows/          # CI/CD configuration
+├── docs/                       # Documentation (generated)
+├── CMakeLists.txt              # Main build configuration
+├── Doxyfile                    # Documentation configuration
+├── Dockerfile                  # Container configuration
+├── README.md                   # Project overview
+├── QUICK_START.md              # Getting started guide
+├── DEVELOPMENT.md              # This file
+└── LICENSE                     # License information
+```
+
+### Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SVMClassifier                            │
+│  ┌─────────────────┐  ┌──────────────────────────────────┐  │
+│  │ KernelParameters│  │      MulticlassStrategy          │  │
+│  │                 │  │  ┌─────────────┐┌─────────────┐   │  │
+│  │ - JSON config   │  │  │OneVsRest    ││OneVsOne     │   │  │
+│  │ - Validation    │  │  │Strategy     ││Strategy     │   │  │
+│  │ - Defaults      │  │  └─────────────┘└─────────────┘   │  │
+│  └─────────────────┘  └──────────────────────────────────┘  │
+│           │                         │                       │
+│           └─────────┬───────────────┘                       │
+│                     │                                       │
+│  ┌─────────────────────────────────────────────────────────┐  │
+│  │              DataConverter                              │  │
+│  │  ┌─────────────────┐  ┌─────────────────────────────┐   │  │
+│  │  │ Tensor → libsvm │  │ Tensor → liblinear          │   │  │
+│  │  │ Tensor → liblinear│ Results → Tensor            │   │  │
+│  │  └─────────────────┘  └─────────────────────────────┘   │  │
+│  └─────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+           │                              │
+    ┌─────────────┐              ┌─────────────┐
+    │   libsvm    │              │  liblinear  │
+    │             │              │             │
+    │ - RBF       │              │ - Linear    │
+    │ - Polynomial│              │ - Fast      │
+    │ - Sigmoid   │              │ - Scalable  │
+    └─────────────┘              └─────────────┘
+```
+
+## Building from Source
+
+### Debug Build
+
+```bash
+mkdir build-debug && cd build-debug
+cmake .. \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DCMAKE_PREFIX_PATH=/path/to/libtorch \
+  -DCMAKE_CXX_FLAGS="-g -O0 -Wall -Wextra"
+make -j$(nproc)
+```
+
+### Release Build
+
+```bash
+mkdir build-release && cd build-release
+cmake .. \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_PREFIX_PATH=/path/to/libtorch \
+  -DCMAKE_CXX_FLAGS="-O3 -DNDEBUG"
+make -j$(nproc)
+```
+
+### Build Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `CMAKE_BUILD_TYPE` | Build configuration | `Release` |
+| `CMAKE_PREFIX_PATH` | PyTorch installation path | Auto-detect |
+| `CMAKE_INSTALL_PREFIX` | Installation directory | `/usr/local` |
+| `BUILD_TESTING` | Enable testing | `ON` |
+| `BUILD_EXAMPLES` | Build examples | `ON` |
+
+### Cross-Platform Building
+
+#### Windows (MSVC)
+
+```cmd
+mkdir build && cd build
+cmake .. -G "Visual Studio 16 2019" -A x64 ^
+  -DCMAKE_PREFIX_PATH=C:\libtorch ^
+  -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake
+cmake --build . --config Release
+```
+
+#### macOS
+
+```bash
+# Install dependencies with Homebrew
+brew install cmake pkg-config openblas
+
+# Build
+mkdir build && cd build
+cmake .. -DCMAKE_PREFIX_PATH=/opt/libtorch
+make -j$(sysctl -n hw.ncpu)
+```
+
+## Testing
+
+### Test Categories
+
+- **Unit Tests** (`[unit]`): Test individual components
+- **Integration Tests** (`[integration]`): Test component interactions
+- **Performance Tests** (`[performance]`): Benchmark performance
+
+### Running Tests
+
+```bash
+cd build
+
+# Run all tests
+ctest --output-on-failure
+
+# Run specific test categories
+./svm_classifier_tests "[unit]"
+./svm_classifier_tests "[integration]"
+./svm_classifier_tests "[performance]"
+
+# Run with verbose output
+./svm_classifier_tests "[unit]" --reporter console
+
+# Run specific test
+./svm_classifier_tests "SVMClassifier Construction"
+```
+
+### Coverage Analysis
+
+```bash
+# Build with coverage
+cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS="--coverage"
+make -j$(nproc)
+
+# Run tests
+./svm_classifier_tests
+
+# Generate coverage report
+make coverage
+
+# View HTML report
+open coverage_html/index.html
+```
+
+### Memory Testing
+
+```bash
+# Run with Valgrind
+valgrind --tool=memcheck --leak-check=full --show-leak-kinds=all \
+  ./svm_classifier_tests "[unit]"
+
+# Or use the provided target
+make test_memcheck
+```
+
+### Adding New Tests
+
+1. **Unit Tests**: Add to appropriate `test_*.cpp` file
+2. **Integration Tests**: Add to `test_svm_classifier.cpp`
+3. **Performance Tests**: Add to `test_performance.cpp`
+
+Example test structure:
+
+```cpp
+TEST_CASE("Feature Description", "[category][subcategory]") {
+    SECTION("Specific behavior") {
+        // Arrange
+        auto svm = SVMClassifier(KernelType::LINEAR);
+        auto X = torch::randn({100, 10});
+        auto y = torch::randint(0, 2, {100});
+        
+        // Act
+        auto metrics = svm.fit(X, y);
+        
+        // Assert
+        REQUIRE(svm.is_fitted());
+        REQUIRE(metrics.status == TrainingStatus::SUCCESS);
+    }
+}
+```
+
+## Code Style and Standards
+
+### C++ Standards
+
+- **Language Standard**: C++17
+- **Naming Convention**: `snake_case` for functions/variables, `PascalCase` for classes
+- **File Naming**: `snake_case.hpp` and `snake_case.cpp`
+- **Indentation**: 4 spaces (no tabs)
+
+### Code Formatting
+
+Use clang-format with the provided configuration:
+
+```bash
+# Format all source files
+find src include tests examples -name "*.cpp" -o -name "*.hpp" | \
+  xargs clang-format -i
+
+# Check formatting
+find src include tests examples -name "*.cpp" -o -name "*.hpp" | \
+  xargs clang-format --dry-run --Werror
+```
+
+### Static Analysis
+
+```bash
+# Run clang-tidy
+clang-tidy src/*.cpp include/svm_classifier/*.hpp \
+  -- -I include -I /opt/libtorch/include
+```
+
+### Documentation Standards
+
+- Use Doxygen-style comments for public APIs
+- Include `@brief`, `@param`, `@return`, `@throws` as appropriate
+- Provide usage examples for complex functions
+
+Example:
+
+```cpp
+/**
+ * @brief Train the SVM classifier on the provided dataset
+ * @param X Feature tensor of shape (n_samples, n_features)
+ * @param y Target tensor of shape (n_samples,) with class labels
+ * @return Training metrics including timing and convergence info
+ * @throws std::invalid_argument if input data is invalid
+ * @throws std::runtime_error if training fails
+ * 
+ * @code
+ * auto X = torch::randn({100, 4});
+ * auto y = torch::randint(0, 3, {100});
+ * SVMClassifier svm(KernelType::RBF, 1.0);
+ * auto metrics = svm.fit(X, y);
+ * @endcode
+ */
+TrainingMetrics fit(const torch::Tensor& X, const torch::Tensor& y);
+```
+
+### Error Handling
+
+- Use exceptions for error conditions
+- Provide meaningful error messages
+- Validate inputs at public API boundaries
+- Use RAII for resource management
+
+### Performance Guidelines
+
+- Minimize memory allocations in hot paths
+- Use move semantics where appropriate
+- Prefer algorithms from STL
+- Profile before optimizing
+
+## Contributing Guidelines
+
+### Workflow
+
+1. **Fork** the repository
+2. **Create** a feature branch: `git checkout -b feature/amazing-feature`
+3. **Implement** your changes
+4. **Add** tests for new functionality
+5. **Run** the validation script: `./validate_build.sh`
+6. **Commit** with descriptive messages
+7. **Push** to your fork
+8. **Create** a Pull Request
+
+### Commit Message Format
+
+```
+type(scope): short description
+
+Longer description if needed
+
+- Bullet points for details
+- Reference issues: Fixes #123
+```
+
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `ci`
+
+### Pull Request Requirements
+
+- [ ] All tests pass
+- [ ] Code follows style guidelines
+- [ ] New features have tests
+- [ ] Documentation is updated
+- [ ] Performance impact is considered
+- [ ] Breaking changes are documented
+
+### Code Review Process
+
+1. Automated checks must pass (CI/CD)
+2. At least one maintainer review required
+3. Address all review comments
+4. Ensure branch is up-to-date with main
+
+## Debugging and Profiling
+
+### Debugging Builds
+
+```bash
+# Debug build with symbols
+cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS="-g -O0"
+
+# Run with GDB
+gdb ./svm_classifier_tests
+(gdb) run "[unit]"
+```
+
+### Common Debugging Scenarios
+
+```cpp
+// Enable verbose logging (if implemented)
+torch::set_num_threads(1);  // Single-threaded for reproducibility
+
+// Print tensor information
+std::cout << "X shape: " << X.sizes() << std::endl;
+std::cout << "X dtype: " << X.dtype() << std::endl;
+std::cout << "X device: " << X.device() << std::endl;
+
+// Check for NaN/Inf values
+if (torch::any(torch::isnan(X)).item<bool>()) {
+    throw std::runtime_error("X contains NaN values");
+}
+```
+
+### Performance Profiling
+
+```bash
+# Build with profiling
+cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
+
+# Profile with perf
+perf record ./svm_classifier_tests "[performance]"
+perf report
+
+# Profile with gprof
+g++ -pg -o program program.cpp
+./program
+gprof program gmon.out > analysis.txt
+```
+
+## Documentation
+
+### Building Documentation
+
+```bash
+# Generate API documentation
+doxygen Doxyfile
+
+# View documentation
+open docs/html/index.html
+```
+
+### Documentation Structure
+
+- **README.md**: Project overview and quick start
+- **QUICK_START.md**: Step-by-step getting started guide
+- **DEVELOPMENT.md**: This development guide
+- **API Reference**: Generated from source code comments
+
+### Contributing to Documentation
+
+- Keep documentation up-to-date with code changes
+- Use clear, concise language
+- Include practical examples
+- Test all code examples
+
+## Release Process
+
+### Version Numbering
+
+We follow [Semantic Versioning](https://semver.org/):
+- **MAJOR.MINOR.PATCH**
+- **MAJOR**: Incompatible API changes
+- **MINOR**: Backward-compatible new features
+- **PATCH**: Backward-compatible bug fixes
+
+### Release Checklist
+
+1. **Update version** in CMakeLists.txt
+2. **Update CHANGELOG.md** with new features/fixes
+3. **Run full validation**: `./validate_build.sh --performance --memory-check`
+4. **Update documentation** if needed
+5. **Create release tag**: `git tag -a v1.0.0 -m "Release 1.0.0"`
+6. **Push tag**: `git push origin v1.0.0`
+7. **Create GitHub release** with release notes
+8. **Update package managers** (if applicable)
+
+### Continuous Integration
+
+Our CI/CD pipeline runs on every PR and includes:
+
+- **Build testing** on multiple platforms (Ubuntu, macOS, Windows)
+- **Compiler compatibility** (GCC, Clang, MSVC)
+- **Code quality** checks (formatting, static analysis)
+- **Test execution** (unit, integration, performance)
+- **Coverage analysis**
+- **Memory leak detection**
+- **Documentation generation**
+- **Package creation**
+
+### Branch Strategy
+
+- **main**: Stable releases
+- **develop**: Integration branch for features
+- **feature/***: Individual feature development
+- **hotfix/***: Critical bug fixes
+- **release/***: Release preparation
+
+## Getting Help
+
+### Resources
+
+- 📖 [Project Documentation](README.md)
+- 🐛 [Issue Tracker](https://github.com/your-username/svm-classifier/issues)
+- 💬 [Discussions](https://github.com/your-username/svm-classifier/discussions)
+- 📧 Email: svm-classifier@example.com
+
+### Reporting Issues
+
+When reporting issues, please include:
+
+1. **Environment**: OS, compiler, library versions
+2. **Reproduction**: Minimal code example
+3. **Expected vs Actual**: What should happen vs what happens
+4. **Logs**: Error messages, stack traces
+5. **Investigation**: What you've tried already
+
+### Feature Requests
+
+For new features:
+
+1. **Check existing issues** to avoid duplicates
+2. **Describe the use case** and motivation
+3. **Propose an API** if applicable
+4. **Consider implementation** complexity
+5. **Offer to contribute** if possible
+
+---
+
+**Thank you for contributing to SVM Classifier C++! 🎯**