Apple's Machine Learning Framework for Apple Silicon - Made Simple

This project is your complete guide to MLX, Apple's blazing-fast machine learning framework optimized for Apple Silicon. From zero to neural networks in minutes!

# Jump in and see MLX magic
cd mlx-101
source mlx-env/bin/activate
python mlx_demo.py        # 🚀 See MLX in action!

What just happened? You just ran machine learning operations on Apple Silicon GPU using unified memory! 🤯

🎯 Hands-on Examples - Working code for arrays, neural networks, and computer vision
🚀 Apple Silicon Power - Harness the full potential of M1/M2/M3+ chips
🐍 Python & Swift - Learn both language interfaces
🧠 Real Neural Networks - Build and train models from scratch
📊 Interactive Learning - Jupyter notebooks ready to go
🔧 Modern Setup - Fast dependency management with uv

MLX is an array framework for machine learning research on Apple Silicon. It's designed to be user-friendly, efficient, and flexible, with a Python API that closely follows NumPy and a C++ API. MLX is particularly optimized for Apple Silicon (M1, M2, M3+ chips) and provides unified memory that allows arrays to live in shared memory accessible to both CPU and GPU.

• Hardware: Apple Silicon Mac (M1, M2, M3+)
• OS: macOS 13.5+ (macOS 14+ recommended)
• Python: 3.9+ (native arm64, not x86 via Rosetta)
• Swift: 5.7+ (for Swift examples)

mlx-101/
├── README.md                 # This file
├── pyproject.toml           # Project configuration and dependencies
├── requirements.txt         # Frozen dependency versions
├── .gitignore              # Git ignore rules
├── examples/               # Python examples
│   ├── 01_basic_operations.py
│   ├── 02_linear_algebra.py
│   ├── 03_neural_networks.py
│   └── 04_image_processing.py
├── swift-examples/         # Swift examples (coming soon)
└── notebooks/              # Jupyter notebooks

# Clone the repository
git clone https://github.com/suh4s/mlx-101.git
cd mlx-101

# Create isolated environment using uv (faster than pip)
uv venv mlx-env

# Activate the environment
source mlx-env/bin/activate

# Install MLX and related packages
uv pip install mlx numpy matplotlib jupyter pillow

# Or install from requirements.txt
uv pip install -r requirements.txt

python -c "import mlx.core as mx; print(f'MLX version: {mx.__version__}'); print('MLX is working!')"

# Activate environment (run this each time you start)
source mlx-env/bin/activate

# Deactivate when done
deactivate

# Install new packages
uv pip install package_name

# Update requirements after installing new packages
uv pip freeze > requirements.txt

Ready to dive in? Here's your fast track to MLX awesomeness:

# 1. Jump into your environment
cd mlx-101
source mlx-env/bin/activate

# 2. See MLX in action (30 seconds)
python mlx_demo.py

# 3. Explore detailed examples
python examples/01_basic_operations.py

# 4. Start experimenting
jupyter lab

# Start every session
source mlx-env/bin/activate

# Run examples
python examples/01_basic_operations.py    # 🎯 Arrays & basics
python examples/03_neural_networks.py     # 🧠 Neural networks
python mlx_demo.py                        # ⚡ Quick overview

# Interactive development
jupyter lab                               # 🎪 Modern interface
jupyter notebook                          # 📊 Classic interface

# When finished
deactivate

# Install new packages (fast with uv!)
uv pip install transformers torch

# Keep track of dependencies
uv pip freeze > requirements.txt

# Reproduce environment elsewhere
uv pip install -r requirements.txt

# What you'll see in 30 seconds:
• MLX vs NumPy speed comparison
• GPU acceleration in action  
• Unified memory demonstration
• Basic neural network forward pass

# Core concepts covered:
• Array creation (zeros, ones, random, linspace)
• Mathematical operations (+, -, *, /, power)
• Array indexing and slicing
• Broadcasting rules and examples
• MLX ↔ NumPy interoperability
• Memory model and device management

# Advanced math operations:
• Matrix multiplication and transposes
• Linear system solving (Ax = b)
• Matrix decompositions (QR, SVD)
• Vector operations and norms
• Geometric transformations
• CPU stream usage for unsupported GPU ops

# Neural network essentials:
• Activation functions (ReLU, Sigmoid, Tanh)
• Loss functions (MSE, Cross-entropy, MAE)
• Gradient computation and backpropagation
• Simple linear regression training
• Multi-layer perceptron (MLP) example
• Best practices for neural network training

# Computer vision fundamentals:
• Image creation and manipulation
• Convolution operations and kernels
• CNN building blocks (Conv2D, ReLU, MaxPool)
• Image transformations (flip, rotate, resize)
• Color space operations (RGB ↔ Grayscale)
• Hybrid MLX-NumPy techniques for complex ops

# Building intelligent agents with LangGraph + MLX:
• Agent workflow orchestration with LangGraph
• Local LLM inference with MLX-LM
• MLX-powered mathematical reasoning tools
• Computer vision capabilities for agents
• Privacy-first, Apple Silicon-optimized AI workflows
• Real-world use cases and performance benefits

# Curated examples that always work:
• Robust linear algebra operations
• Reliable image processing patterns
• Neural network components
• Performance benchmarks
• Best practices for real applications

After working through this repository, you now understand:

• Unified Memory Architecture: CPU and GPU share the same memory space - no costly transfers!
• Lazy Evaluation: Operations are automatically fused for maximum efficiency
• Apple Silicon Optimization: Native Metal Performance Shaders provide blazing speed
• NumPy Compatibility: Easy migration path from existing NumPy-based workflows

• Array Operations: Creation, indexing, slicing, and broadcasting in MLX
• Linear Algebra: Matrix operations, decompositions, and solving linear systems
• Neural Networks: Building networks from scratch with proper gradients
• Computer Vision: Image processing, convolutions, and CNN architectures
• Performance Optimization: When to use CPU vs GPU streams for different operations

• Environment Management: Isolated development with uv and virtual environments
• Dependency Tracking: Proper pyproject.toml and requirements.txt management
• Error Handling: Graceful fallbacks for GPU-unsupported operations
• Hybrid Approaches: Combining MLX with NumPy for complex operations
• Best Practices: Code patterns that work reliably across different MLX versions

During the development of this repository, we encountered and solved several important MLX compatibility issues:

• Problem: Some linear algebra operations (mx.linalg.inv, mx.linalg.qr, mx.linalg.solve) not yet supported on GPU
• Solution: Use CPU streams with proper evaluation: with mx.stream(mx.cpu): result = operation(); mx.eval(result)
• Impact: All linear algebra examples now work reliably across MLX versions

• Problem: MLX's .at[].set() method causing 'ArrayAt' object has no attribute 'set' errors
• Solution: Hybrid approach using NumPy for complex assignments, converting back to MLX
• Impact: Image processing operations like max pooling and resizing now work perfectly

• Problem: Operations like mx.rot90() don't exist in current MLX versions
• Solution: Use NumPy equivalents and convert: mx.array(np.rot90(np.array(mlx_array)))
• Impact: All image transformation examples work seamlessly

• Unified Memory: True zero-copy between CPU and GPU operations
• Lazy Evaluation: Operations are automatically fused for better performance
• Broadcasting: MLX's broadcasting rules closely follow NumPy for familiar behavior
• Vectorization: Always prefer vectorized operations over Python loops

# ✅ MLX Strengths: Fast unified memory operations
result = mlx_array @ other_array  # GPU-accelerated, no memory transfers

# ⚠️ MLX Limitations: Some linalg ops need CPU streams
with mx.stream(mx.cpu):
    inv_matrix = mx.linalg.inv(matrix)  # Fallback to CPU when needed

# ✅ Hybrid MLX-NumPy approach for complex operations
mlx_data = mx.array(input_data)      # Use MLX for computation
numpy_data = np.array(mlx_data)      # Convert for complex assignments
result = mx.array(processed_numpy)   # Back to MLX for further processing

1. Start Simple: Use working_examples.py for guaranteed-working patterns
2. Understand Limitations: Know when to use CPU streams vs GPU
3. Leverage Strengths: Use MLX for heavy computation, NumPy for complex indexing
4. Test Incrementally: Build up from basic operations to complex models

# Always handle GPU/CPU compatibility
try:
    result = mx.linalg.solve(A, b)  # Try GPU first
except:
    with mx.stream(mx.cpu):         # Fallback to CPU
        result = mx.linalg.solve(A, b)
        mx.eval(result)

# Leverage broadcasting and vectorization
processed = (data - mean) / std     # Vectorized normalization
result = mx.sum(processed * weights, axis=1)  # Efficient reductions

# Clean, extensible neural network patterns
def layer_forward(x, weights, bias):
    return mx.maximum(0, x @ weights + bias)  # ReLU activation

# Gradient-ready operations
loss = mx.mean((predictions - targets) ** 2)  # MSE loss

✅ Environment Mastery: Professional development setup with uv and virtual environments
✅ Core Understanding: Deep knowledge of MLX's unified memory and lazy evaluation
✅ Practical Skills: Real examples that work across different MLX versions
✅ Performance Awareness: Know when to use GPU vs CPU streams
✅ Production Patterns: Robust code that handles edge cases gracefully
✅ Multi-Language Ready: Both Python and Swift MLX interfaces understood
✅ Computer Vision Capable: Image processing and CNN implementation skills
✅ Debugging Skills: Can identify and fix common MLX compatibility issues

You're now equipped to build serious machine learning applications on Apple Silicon! 🎉

• 🍎 Apple Silicon Optimized: Native Metal Performance Shaders for maximum performance
• 🧠 Unified Memory: CPU and GPU share memory seamlessly - no transfers needed!
• ⚡ Lazy Evaluation: Operations are fused automatically for efficiency
• 🐍 NumPy Compatible: Easy migration from existing NumPy code
• 🦎 Swift Native: Type-safe, performant Swift integration
• 🔧 Auto Differentiation: Ready for gradient-based learning out of the box

• 🚀 Fast Package Management: Using uv instead of slow pip
• 🔒 Isolated Environment: No conflicts with system Python packages
• 📊 Rich Examples: Working code you can learn from immediately
• 🎯 Multi-language: Both Python and Swift ready to go
• 📝 Comprehensive Docs: Everything documented and explained
• 🎪 Jupyter Ready: Interactive development environment set up

# ✅ Good - Vectorized operations
result = a * 2 + b

# ❌ Avoid - Python loops
result = [a[i] * 2 + b[i] for i in range(len(a))]

• Always activate: source mlx-env/bin/activate before starting
• Quick test: Run python mlx_demo.py to verify everything works
• Interactive dev: Use jupyter lab for experimentation
• Keep updated: uv pip freeze > requirements.txt after installing packages

1. Start simple: Begin with 01_basic_operations.py
2. Understand by doing: Modify examples and see what happens
3. Read the outputs: Examples are heavily commented for learning
4. Build incrementally: Start with arrays, then move to neural networks

• MLX arrays live in unified memory - accessible by both CPU and GPU
• Use mx.array() instead of np.array() for MLX operations
• Leverage broadcasting for element-wise operations
• Take advantage of lazy evaluation - operations are fused when possible
• Convert between MLX and NumPy easily: np.array(mlx_array)

• MLX Documentation
• MLX GitHub Repository
• MLX Examples
• Apple Silicon ML Guide
• Swift for TensorFlow → MLX Migration