# MLX Erlang 🚀

[![Hex.pm](https://img.shields.io/hexpm/v/mlx.svg)](https://hex.pm/packages/mlx)
[![Documentation](https://img.shields.io/badge/docs-hexdocs-blue.svg)](https://hexdocs.pm/mlx/)
[![CI](https://github.com/ml-explore/mlx-erlang/workflows/CI/badge.svg)](https://github.com/ml-explore/mlx-erlang/actions)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

**State-of-the-Art Machine Learning Framework for Erlang/OTP**

MLX Erlang brings the power of Apple's MLX framework to the Erlang ecosystem, providing a comprehensive, high-performance machine learning library optimized for Erlang's concurrent and fault-tolerant architecture.

## Features

- **Native Apple Silicon Performance**: Direct access to MLX's optimized operations for Apple Silicon
- **Dirty Scheduler Integration**: CPU-intensive operations run on dirty schedulers to avoid blocking the Erlang VM
- **Unified Memory Model**: Leverages MLX's unified memory architecture for efficient data handling
- **Lazy Evaluation**: Computations are performed lazily, only materializing when needed
- **Multi-device Support**: Switch between CPU and GPU execution seamlessly
- **Type Safety**: Comprehensive type specifications and validation

## Supported Operations

### Array Creation
- `mlx:zeros/1,2` - Create arrays filled with zeros
- `mlx:ones/1,2` - Create arrays filled with ones  
- `mlx:random/1,2` - Create arrays with random values

### Array Operations
- `mlx:add/2` - Element-wise addition
- `mlx:multiply/2` - Element-wise multiplication
- `mlx:matmul/2` - Matrix multiplication

### Array Information
- `mlx:shape/1` - Get array dimensions
- `mlx:eval/1` - Force evaluation of lazy arrays

### Device Management
- `mlx:use_cpu/0` - Switch to CPU execution
- `mlx:use_gpu/0` - Switch to GPU execution
- `mlx:set_default_device/1` - Set default device

## Supported Data Types

- `float32` (default)
- `float16`
- `bfloat16`
- `int32`, `int16`, `int8`
- `uint32`, `uint16`, `uint8`
- `bool`

## Installation

### Prerequisites

1. **MLX Library**: Install MLX C++ library
   ```bash
   # Using Homebrew (recommended)
   brew install mlx
   
   # Or build from source
   git clone https://github.com/ml-explore/mlx.git
   cd mlx && mkdir build && cd build
   cmake .. -DCMAKE_BUILD_TYPE=Release
   make -j && sudo make install
   ```

2. **Erlang/OTP**: Version 24+ with dirty scheduler support
   ```bash
   brew install erlang
   ```

3. **Rebar3**: Erlang build tool
   ```bash
   brew install rebar3
   ```

### Building

```bash
git clone <this-repo>
cd mlx.erl
rebar3 compile
```

## Usage

### Basic Example

```erlang
% Start the application
application:start(mlx).

% Create arrays
{ok, A} = mlx:zeros([3, 3]),          % 3x3 zeros (float32)
{ok, B} = mlx:ones([3, 3], int32),    % 3x3 ones (int32)

% Basic operations
{ok, Sum} = mlx:add(A, B),
{ok, Product} = mlx:multiply(A, B),

% Matrix operations
{ok, A} = mlx:ones([3, 4]),
{ok, B} = mlx:ones([4, 2]),
{ok, C} = mlx:matmul(A, B),           % 3x2 result

% Force evaluation
mlx:eval(C),

% Check array properties
{ok, Shape} = mlx:shape(C),           % [3, 2]

% Device management
mlx:use_gpu(),                        % Switch to GPU
{ok, GpuArray} = mlx:zeros([1000, 1000]),
mlx:use_cpu().                        % Switch back to CPU
```

### Running Examples

```erlang
% Compile and run basic examples
rebar3 shell
1> basic_usage:demo().
```

## Architecture

### NIF Implementation
- **C++ Backend**: Uses MLX C++ API directly for maximum performance
- **Resource Management**: Automatic memory management through Erlang resources
- **Error Handling**: Comprehensive error handling with descriptive messages
- **Dirty Schedulers**: All compute-intensive operations use `ERL_NIF_DIRTY_JOB_CPU_BOUND`

### Module Structure
- `mlx` - High-level user API with convenience functions
- `mlx_nif` - Low-level NIF interface
- `mlx_app` - OTP application behavior
- `mlx_sup` - OTP supervisor

## Performance Considerations

1. **Lazy Evaluation**: Operations build computation graphs; call `mlx:eval/1` to execute
2. **Memory Sharing**: Arrays use MLX's unified memory model - no copying between CPU/GPU
3. **Dirty Schedulers**: Heavy operations don't block the Erlang scheduler
4. **Device Optimization**: Use GPU for large arrays, CPU for small ones

## Error Handling

All operations return `{ok, Result}` or `{error, Reason}` tuples:

```erlang
case mlx:zeros([3, 3]) of
    {ok, Array} -> 
        % Use array
        ok;
    {error, Reason} ->
        % Handle error
        io:format("Error: ~p~n", [Reason])
end.
```

## Limitations

- **Apple Silicon Only**: Requires Apple Silicon Mac (M1/M2/M3+)
- **MLX Dependency**: Requires MLX library installation
- **Basic Operations**: Currently implements core operations; more functions coming
- **No Data Extraction**: Arrays remain in MLX format (future: data extraction functions)

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Acknowledgments

- [MLX Team](https://github.com/ml-explore/mlx) for the excellent ML framework
- Erlang/OTP team for dirty scheduler support
- Apple for Apple Silicon architecture