Deployment and Usage Guide: MatrixAlgebraKit.jl

1. Prerequisites

Required Software

Julia: Version 1.6 or higher (recommended: latest stable release)
- Download from julialang.org/downloads/
- Verify installation: julia --version
Git: For cloning the repository (optional if installing via package manager)

System Requirements

Operating Systems: Linux, macOS, Windows (with WSL2 recommended for Windows)
Architecture: x86_64, ARM64 (Apple Silicon supported)
Memory: Minimum 2 GB RAM (4+ GB recommended for large matrix operations)
Disk Space: ~200 MB for package + dependencies

Optional Tools

JET.jl: For type stability analysis (] add JET)
Aqua.jl: For QA checks (] add Aqua)

2. Installation

Standard Installation (Julia Package Manager)

Start Julia REPL:
```
julia
```
Enter package mode by pressing ] (right bracket)
Add the package:
```
add https://github.com/QuantumKitHub/MatrixAlgebraKit.jl
```
Note: Package may not be registered in General registry, so use full URL
Return to Julia mode by pressing Backspace or Ctrl+C

Development Installation (for contributors)

# Clone repository
git clone https://github.com/QuantumKitHub/MatrixAlgebraKit.jl.git
cd MatrixAlgebraKit.jl

# In Julia REPL:
julia> using Pkg
julia> Pkg.activate(".")  # activates local environment
julia> Pkg.instantiate()  # installs all dependencies
julia> Pkg.test()         # runs test suite

Verification

julia> using MatrixAlgebraKit
julia> ?MatrixAlgebraKit  # should show documentation

3. Configuration

Environment Variables

No required environment variables. Optional:

Variable	Purpose	Default
`JULIA_DEBUG`	Enable debug logging	`MatrixAlgebraKit`
`MATRIXALGEBRAKIT_BACKEND`	Override default backend	Auto-detected

Project Configuration

Create a Project.toml in your project:

[deps]
MatrixAlgebraKit = "github.com/QuantumKitHub/MatrixAlgebraKit.jl"

Backend Selection

The package automatically selects optimal backends. To manually specify:

using MatrixAlgebraKit
MatrixAlgebraKit.set_backend(:cuBLAS)  # for CUDA, if available
# Supported: :CPU, :cuBLAS, :oneAPI, :MKL

4. Build & Run

Local Development Workflow

Activate environment:

julia> Pkg.activate("/path/to/MatrixAlgebraKit.jl")

Run tests:
```
julia> Pkg.test()
```
Runs full test suite with coverage

Run benchmarks (if benchmark suite exists):

julia> using PkgBenchmark
julia> @benchgroup MatrixAlgebraKit

Run examples:

julia> include("examples/basic_operations.jl")

Interactive Usage

# Start Julia with project environment
julia --project=. 

# In REPL:
using MatrixAlgebraKit
using LinearAlgebra  # for comparison

# Example: Matrix multiplication with pre-allocated output
A = rand(1000, 1000)
B = rand(1000, 1000)
C = similar(A)
mul!(C, A, B)  # in-place operation (MatrixAlgebraKit style)

Building Documentation

# From repository root
julia --project=docs -e 'using Pkg; Pkg.instantiate()'
julia --project=docs docs/make.jl

# Output in docs/build/

5. Deployment

As a Dependency in Your Project

Add to Project.toml:

[deps]
MatrixAlgebraKit = "github.com/QuantumKitHub/MatrixAlgebraKit.jl"

Deploy your application:

# Package your application with PackageCompiler.jl
julia -e 'using PackageCompiler; create_app("my_app", ["MatrixAlgebraKit"])'

CI/CD Integration

GitHub Actions (example workflow):

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: julia-actions/setup-julia@v1
        with:
          version: '1.9'
      - run: julia --project=. -e 'using Pkg; Pkg.instantiate(); Pkg.test()'

Docker Deployment

# Dockerfile
FROM julia:1.9-bullseye
WORKDIR /app
COPY Project.toml .
RUN julia -e 'using Pkg; Pkg.add("MatrixAlgebraKit"); Pkg.instantiate()'
COPY . .
CMD ["julia", "--project=.", "my_script.jl"]

Production Considerations

Precompilation: Enable with julia --pkg=precompile for faster startup
GPU Support: Ensure CUDA/oneAPI drivers installed for GPU backends
Threading: Set JULIA_NUM_THREADS environment variable for multi-threading

6. Troubleshooting

Common Issues & Solutions

1. "Package MatrixAlgebraKit not found"

Cause: Package not in registry or incorrect URL. Fix:

julia> Pkg.add(url="https://github.com/QuantumKitHub/MatrixAlgebraKit.jl")

2. Precompilation failures

Cause: Incompatible Julia version or dependency conflicts. Fix:

julia> Pkg.resolve()  # resolves dependencies
julia> Pkg.precompile()

3. GPU backend not loading

Cause: Missing CUDA/oneAPI drivers or Julia GPU packages. Fix:

# Install GPU stack first
julia> Pkg.add("CUDA")  # for NVIDIA GPUs
julia> using CUDA
julia> MatrixAlgebraKit.set_backend(:cuBLAS)

4. Performance not as expected

Diagnose:

using JET
@report_opt MatrixAlgebraKit.mul!(C, A, B)  # check type stability

Fix: Ensure all arrays are concrete types (avoid AbstractArray in hot loops).

5. AD (Automatic Differentiation) issues

Cause: Pullback rules not loaded for your AD system. Fix: Load appropriate AD package before MatrixAlgebraKit:

using Zygote  # or Enzyme, ReverseDiff, etc.
using MatrixAlgebraKit  # now pullbacks are properly registered

Debug Mode

Enable verbose logging:

export JULIA_DEBUG=MatrixAlgebraKit
julia --project=. my_script.jl 2>&1 | grep MatrixAlgebraKit

Getting Help

Documentation: stable | dev
Issues: GitHub Issues
Discussions: GitHub Discussions

Performance Tips

Use mul! (bang functions) for in-place operations to avoid allocations
Pre-allocate output arrays with similar or MatrixAlgebraKit.similar
For large matrices, ensure BLAS.set_num_threads(Sys.CPU_THREADS) is called

Benchmark with BenchmarkTools.jl:

using BenchmarkTools
@benchmark MatrixAlgebraKit.mul!($C, $A, $B)

Note: This package is a conscious alternative to LinearAlgebra.jl with a focus on extensibility and AD compatibility. Always refer to the official documentation for the most current API details and examples.

How to Deploy & Use MatrixAlgebraKit.jl