Initial commit

Author: JessicaMulein

.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: Test
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: macos-latest
+    
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+    
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+    
+    - name: Install dependencies
+      run: npm install
+    
+    - name: Build addon
+      run: npm run build
+    
+    - name: Run tests
+      run: npm test
+    
+    - name: Run benchmarks
+      run: npm run benchmark

.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+build/
+*.node
+*.log
+.DS_Store
+package-lock.json
+yarn.lock

.npmignore

@@ -0,0 +1,8 @@
+node_modules/
+build/
+*.log
+.DS_Store
+test.js
+benchmark.js
+.git/
+.github/

.nvmrc

@@ -0,0 +1 @@
+18

CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-12-30
+
+### Added
+- Initial release
+- Matrix operations:
+  - Matrix multiplication (BLAS GEMM) with 283x speedup
+  - Matrix-vector multiplication (BLAS GEMV)
+  - AXPY operation (y = alpha*x + y)
+- Vector arithmetic (vDSP):
+  - Dot product (5x speedup)
+  - Addition, subtraction, multiplication, division
+  - Scalar multiplication
+- Vector functions (vDSP):
+  - Absolute value
+  - Square, square root
+  - Normalize to unit length
+- Reductions (vDSP):
+  - Sum (7.6x speedup)
+  - Mean, max, min
+  - Root Mean Square (RMS)
+- Distance metrics:
+  - Euclidean distance
+- Signal processing:
+  - Fast Fourier Transform (FFT)
+- Full TypeScript definitions
+- Comprehensive test suite (26 tests)
+- Performance benchmarks
+- Complete documentation
+
+### Performance
+- Matrix multiply (500×500): 93ms → 0.33ms (283x faster)
+- Vector dot product (1M): 0.66ms → 0.13ms (5x faster)
+- Vector sum (1M): 0.59ms → 0.08ms (7.6x faster)
+- Vector add (1M): 0.74ms → 0.20ms (3.7x faster)
+
+### Requirements
+- macOS (Apple Silicon or Intel)
+- Node.js >= 18.0.0
+- Xcode Command Line Tools
+
+## [Unreleased]
+
+### Planned
+- Float32 support for single-precision operations
+- Additional BLAS operations (GEMV, triangular solve)
+- Additional vDSP operations (convolution, correlation)
+- Improved error handling and validation
+- More comprehensive benchmarks
+- CI/CD pipeline
+
+---
+
+[1.0.0]: https://github.com/Digital-Defiance/node-accelerate/releases/tag/v1.0.0

CONTRIBUTING.md

@@ -0,0 +1,225 @@
+# Contributing to node-accelerate
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to node-accelerate.
+
+## Development Setup
+
+### Prerequisites
+
+- macOS (Apple Silicon or Intel)
+- Node.js >= 18.0.0
+- Xcode Command Line Tools
+- Git
+
+### Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/Digital-Defiance/node-accelerate.git
+   cd node-accelerate
+   ```
+
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+4. Build the addon:
+   ```bash
+   npm run build
+   ```
+
+5. Run tests:
+   ```bash
+   npm test
+   ```
+
+## Project Structure
+
+```
+node-accelerate/
+├── accelerate.cc      # C++ implementation
+├── binding.gyp        # Build configuration
+├── index.js           # JavaScript wrapper
+├── index.d.ts         # TypeScript definitions
+├── test.js            # Test suite
+├── benchmark.js       # Performance benchmarks
+└── README.md          # Documentation
+```
+
+## Making Changes
+
+### Code Style
+
+**C++ Code:**
+- Follow Google C++ Style Guide
+- Use 2-space indentation
+- Add comments for complex operations
+- Include error handling
+
+**JavaScript Code:**
+- Use 2-space indentation
+- Use `const` and `let`, not `var`
+- Add JSDoc comments for functions
+- Follow Node.js best practices
+
+### Adding New Functions
+
+1. **Add C++ implementation** in `accelerate.cc`:
+   ```cpp
+   Napi::Value YourFunction(const Napi::CallbackInfo& info) {
+     Napi::Env env = info.Env();
+     
+     // Validate arguments
+     if (info.Length() < 1) {
+       Napi::TypeError::New(env, "Expected 1 argument").ThrowAsJavaScriptException();
+       return env.Null();
+     }
+     
+     // Your implementation using Accelerate framework
+     
+     return result;
+   }
+   ```
+
+2. **Export the function** in `Init()`:
+   ```cpp
+   exports.Set("yourFunction", Napi::Function::New(env, YourFunction));
+   ```
+
+3. **Add TypeScript definition** in `index.d.ts`:
+   ```typescript
+   export function yourFunction(arg: Float64Array): number;
+   ```
+
+4. **Add tests** in `test.js`:
+   ```javascript
+   console.log('Testing your function...');
+   const result = accelerate.yourFunction(testData);
+   assertClose(result, expectedValue, 1e-10, 'Your function test');
+   ```
+
+5. **Update documentation** in `README.md`
+
+### Testing
+
+Run the test suite:
+```bash
+npm test
+```
+
+Add tests for:
+- Correct results with known inputs
+- Edge cases (empty arrays, single elements)
+- Large inputs (performance validation)
+- Error handling (invalid arguments)
+
+### Benchmarking
+
+Run benchmarks:
+```bash
+npm run benchmark
+```
+
+When adding new functions, include benchmarks comparing:
+- Pure JavaScript implementation
+- Accelerate-based implementation
+- Speedup factor
+
+## Pull Request Process
+
+1. **Create a branch** for your feature:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following the code style guidelines
+
+3. **Add tests** for new functionality
+
+4. **Run tests** to ensure everything works:
+   ```bash
+   npm test
+   npm run benchmark
+   ```
+
+5. **Commit your changes** with clear messages:
+   ```bash
+   git commit -m "Add feature: description"
+   ```
+
+6. **Push to your fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. **Create a Pull Request** with:
+   - Clear description of changes
+   - Test results
+   - Benchmark results (if applicable)
+   - Documentation updates
+
+## What to Contribute
+
+### High Priority
+
+- **More BLAS operations**: Matrix-vector multiply, triangular solve, etc.
+- **More vDSP operations**: Convolution, correlation, windowing
+- **Float32 support**: Add single-precision variants
+- **Error handling**: Improve validation and error messages
+- **Documentation**: More examples and use cases
+
+### Medium Priority
+
+- **Performance optimizations**: Reduce overhead, optimize memory usage
+- **Additional tests**: Edge cases, stress tests
+- **CI/CD**: GitHub Actions for automated testing
+- **Benchmarks**: More comprehensive performance tests
+
+### Low Priority
+
+- **Additional platforms**: Explore other ARM64 platforms
+- **Advanced features**: Sparse matrices, complex numbers
+- **Utilities**: Helper functions for common patterns
+
+## Code Review
+
+All submissions require review. We'll look for:
+
+- **Correctness**: Does it work as intended?
+- **Performance**: Does it maintain or improve performance?
+- **Tests**: Are there adequate tests?
+- **Documentation**: Is it well-documented?
+- **Style**: Does it follow the style guide?
+
+## Reporting Issues
+
+When reporting issues, include:
+
+1. **Environment**:
+   - macOS version
+   - Node.js version
+   - Chip (M1/M2/M3/M4/Intel)
+
+2. **Description**: Clear description of the issue
+
+3. **Reproduction**: Minimal code to reproduce
+
+4. **Expected vs Actual**: What you expected vs what happened
+
+5. **Logs**: Any error messages or logs
+
+## Questions?
+
+- Open an issue for questions
+- Check existing issues first
+- Be respectful and constructive
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+## Acknowledgments
+
+Thank you for contributing to node-accelerate! Your efforts help make high-performance numerical computing accessible to the Node.js community.