Installation - Entrenar - Training & Optimization Library
Description: A comprehensive guide to building neural network training systems with autograd, optimizers, LoRA/QLoRA, and quantization using EXTREME TDD methodology

# Installation

This guide will help you install Entrenar and set up your development environment for neural network training with autograd, optimizers, and LoRA/QLoRA fine-tuning.

## Prerequisites

Before installing Entrenar, ensure you have:

- Rust 1.70+: Install from rustup.rs
- Cargo: Comes bundled with Rust
- Git: For cloning the repository (optional)

    # Verify Rust installation
    rustc --version  # Should show 1.70 or higher
    cargo --version

## Installation Methods

### Method 1: Add as Cargo Dependency (Recommended)

Add Entrenar to your `Cargo.toml`:

    [dependencies]
    entrenar = "0.2"
    ndarray = "0.16"  # Required for tensor operations

Then run:

    cargo build

### Method 2: Clone and Build from Source

For development or to run examples:

    # Clone the repository
    git clone https://github.com/paiml/entrenar.git
    cd entrenar

    # Run tests to verify installation
    cargo test

    # Run quality gates
    cargo clippy -- -D warnings
    cargo fmt --check

    # Build in release mode for performance
    cargo build --release

## Verifying Installation

Create a simple test file `test_install.rs`:

    use entrenar::Tensor;

    fn main() {
        // Create a simple tensor
        let x = Tensor::from_vec(vec![1.0, 2.0, 3.0], true);
        println!("Tensor created: {:?}", x.data());

        // Test autograd
        let y = &x * &x;  // y = x²
        println!("Forward pass successful!");

        println!("✅ Entrenar is installed correctly!");
    }

Run it:

    cargo run --example test_install

Expected output:

    Tensor created: [1.0, 2.0, 3.0]
    Forward pass successful!
    ✅ Entrenar is installed correctly!

## Feature Flags

Entrenar supports optional features via Cargo feature flags:

    [dependencies]
    entrenar = { version = "0.2", features = ["simd", "quantization"] }

Available features:

Feature | Description | Default
--- | --- | ---
`simd` | SIMD-accelerated optimizer updates via Trueno | ✅ Enabled
`quantization` | 4-bit quantization for QLoRA | ✅ Enabled
`serde` | Serialization support for adapters | ✅ Enabled

## Development Dependencies

For contributing or running the full test suite:

    [dev-dependencies]
    proptest = "1.0"         # Property-based testing
    approx = "0.5"           # Floating-point comparisons
    serde_json = "1.0"       # JSON serialization
    criterion = "0.5"        # Benchmarking
    cargo-mutants = "24.0"   # Mutation testing

Install development tools:

    # Code coverage
    cargo install cargo-llvm-cov

    # Mutation testing
    cargo install cargo-mutants

    # Benchmarking
    cargo install cargo-criterion

## Platform-Specific Notes

### Linux

No special configuration required. SIMD acceleration works out of the box on x86_64 and ARM64.

### macOS

Apple Silicon (M1/M2) users get native ARM64 SIMD support:

    # Verify ARM64 build
    cargo build --release
    file target/release/entrenar
    # Should show: Mach-O 64-bit executable arm64

### Windows

Windows users should use the MSVC toolchain:

    rustup default stable-msvc
    cargo build

## IDE Setup

### Visual Studio Code

Recommended extensions:

- rust-analyzer: IntelliSense and code completion
- CodeLLDB: Debugging support
- Even Better TOML: Cargo.toml syntax highlighting

### RustRover / IntelliJ IDEA

The Rust plugin provides excellent support for Entrenar development.

## Troubleshooting

### Error: "cannot find crate `ndarray`"

Solution: Add `ndarray = "0.15"` to your `Cargo.toml` dependencies.

### Error: "SIMD operations not available"

Solution: Ensure you're compiling in release mode for SIMD optimizations:

    cargo build --release

### Tests Failing on Fresh Install

Solution: Run with increased stack size for gradient checking tests:

    RUST_MIN_STACK=8388608 cargo test

### Slow Compile Times

Solution: Enable parallel compilation:

    # Add to ~/.cargo/config.toml
    [build]
    jobs = 4  # Or number of CPU cores

## Next Steps

Now that Entrenar is installed:

1. Quick Start - Train your first neural network
2. First Training Loop - Build a complete training pipeline
3. Core Concepts - Understand Entrenar's architecture

## Getting Help

- Documentation: https://paiml.github.io/entrenar
- Issues: GitHub Issues
- Examples: See `examples/` directory in the repository
- Tests: See `src/*/tests.rs` for usage patterns

Ready to train? Continue to Quick Start →