Installation

Get ArqonHPO running on your system in minutes.

Whether you're optimizing your first hyperparameter or building production-grade ML pipelines, this guide has you covered.

Choose Your Path¶

Python (Recommended)¶

The fastest way to get started with ArqonHPO:

pip install arqonhpo

That's it. You're ready to optimize.

The pip package includes pre-built binaries for all major platforms. You only need Rust if building from source.

Requirements¶

Verify Installation¶

python -c "from arqonhpo import ArqonSolver; print('✓ ArqonHPO installed successfully')"

Upgrade to Latest¶

pip install --upgrade arqonhpo

Install Specific Version¶

pip install arqonhpo==0.3.0

Conda¶

For reproducible environments and scientific workflows:

conda install -c conda-forge arqonhpo

Create a Dedicated Environment¶

# Create environment with ArqonHPO
conda create -n hpo python=3.11 arqonhpo -c conda-forge

# Activate it
conda activate hpo

# Verify
python -c "from arqonhpo import ArqonSolver; print('✓ Ready')"

With Other ML Libraries¶

conda create -n ml-tuning python=3.11 arqonhpo pytorch scikit-learn -c conda-forge -c pytorch

From Source (Rust)¶

Build ArqonHPO from source for development, customization, or to use the bleeding-edge version.

Building from source requires exactly Rust 1.82. This version is frozen due to specific language features and API dependencies used in the codebase.

Prerequisites¶

Before you begin, ensure you have the following installed:

1. Rust Toolchain (1.82 — Pinned)¶

# Install Rust via rustup (recommended)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Update to latest stable
rustup update stable

# Verify version
rustc --version  # Must show exactly 1.82.x

On Windows, download and run rustup-init.exe instead. You may also need to install the Visual Studio Build Tools.

2. Protobuf Compiler¶

ArqonHPO uses Protocol Buffers for efficient serialization.

bash sudo apt update && sudo apt install -y protobuf-compiler

bash brew install protobuf

bash sudo dnf install -y protobuf-compiler

bash sudo pacman -S protobuf

```powershell # Using Chocolatey choco install protoc

# Or using Scoop
scoop install protobuf
```

Verify protobuf installation:

protoc --version  # Should show libprotoc 3.x or higher

3. Just (Task Runner)¶

We use Just as our task runner for consistent developer experience.

bash cargo install just

bash brew install just

bash sudo apt install just # Or use cargo install just if not available

```powershell # Using Chocolatey choco install just

# Using Scoop
scoop install just
```

4. Git¶

git --version  # Should show 2.x or higher

Build Steps¶

# 1. Clone the repository
git clone https://github.com/novelbytelabs/ArqonHPO.git
cd ArqonHPO

# 2. Build all crates in release mode
cargo build --workspace --release

# 3. Run the test suite to verify everything works
cargo test --workspace

If all tests pass, you've successfully built ArqonHPO from source!

Install the CLI¶

The ArqonHPO CLI provides interactive optimization via the terminal:

# Install the CLI binary
cargo install --path crates/cli --bin arqonhpo-cli

# Verify installation
arqonhpo-cli --version

The binary will be installed to ~/.cargo/bin/. Ensure this is in your PATH.

Development Build (Debug Mode)¶

For faster compilation during development:

cargo build --workspace
cargo test --workspace

Python Bindings (Maturin)¶

Build Python bindings from source when contributing to the Python API or testing unreleased features.

Prerequisites¶

• Rust 1.82 (see above)
• Python 3.10+ with a virtual environment
• maturin (Python-Rust build tool)

Setup¶

# 1. Clone the repository
git clone https://github.com/novelbytelabs/ArqonHPO.git
cd ArqonHPO

# 2. Create a virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# Or: venv\Scripts\activate  # Windows

# 3. Install maturin
pip install maturin

# 4. Build and install the bindings in development mode
cd bindings/python
maturin develop --release

Verify¶

python -c "from arqonhpo import ArqonSolver, ArqonProbe; print('✓ Bindings installed')"

Build Distributable Wheels¶

To create wheel files for distribution:

# Build wheels for your platform
maturin build --release -m bindings/python/Cargo.toml

# Wheels are output to target/wheels/
ls target/wheels/

Docker¶

Containerized ArqonHPO for isolated environments and CI/CD pipelines.

Quick Start¶

# Pull the official image
docker pull novelbytelabs/arqonhpo:latest

# Run interactively
docker run -it novelbytelabs/arqonhpo:latest python
>>> from arqonhpo import ArqonSolver
>>> print("Ready!")

Mount Your Project¶

docker run -it -v $(pwd):/workspace novelbytelabs/arqonhpo:latest bash

Docker Compose¶

For complex setups:

# docker-compose.yml
version: "3.8"
services:
  optimizer:
    image: novelbytelabs/arqonhpo:latest
    volumes:
      - ./experiments:/workspace
    command: python /workspace/run_hpo.py

Build Custom Image¶

FROM novelbytelabs/arqonhpo:latest

# Add your dependencies
RUN pip install torch transformers

# Copy your code
COPY . /app
WORKDIR /app

CMD ["python", "optimize.py"]

Docker images are published starting from v0.4. For earlier versions, build from source using the Dockerfile in the repository.

Platform Support¶

Officially Supported¶

Community Supported¶

These platforms may work but are not actively tested:

Virtual Environment Best Practices¶

We strongly recommend using virtual environments to isolate ArqonHPO from other projects.

Option 1: venv (Built-in)¶

# Create environment
python -m venv arqon-env

# Activate
source arqon-env/bin/activate  # Linux/macOS
arqon-env\Scripts\activate     # Windows

# Install
pip install arqonhpo

Option 2: conda¶

conda create -n arqon python=3.11
conda activate arqon
pip install arqonhpo

Option 3: uv (Fast & Modern)¶

uv is a blazing-fast Python package manager:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create environment and install
uv venv
source .venv/bin/activate
uv pip install arqonhpo

Troubleshooting¶

Installation Issues¶

Cause: Your Python version or platform is not supported.

**Solution**:
```bash
# Check Python version (need 3.10+)
python --version

# Check architecture
python -c "import platform; print(platform.machine())"
```

If you're on an unsupported platform, [build from source](#from-source-rust).

Error: Could not find protoc installation

**Solution**: Install protobuf compiler for your platform:
```bash
# Ubuntu/Debian
sudo apt install protobuf-compiler

# macOS
brew install protobuf

# Verify
protoc --version
```

Cause: Python version mismatch between build and runtime.

**Solution**:
```bash
# Ensure you're using the same Python that built the bindings
which python

# Rebuild in a clean environment
pip uninstall arqonhpo
pip install arqonhpo --no-cache-dir
```

Solution: Use a virtual environment instead of system Python: bash python -m venv venv source venv/bin/activate pip install arqonhpo

Cause: Rust not in PATH after installation.

**Solution**:
1. Close and reopen your terminal
2. Or manually add `%USERPROFILE%\.cargo\bin` to your PATH

Runtime Issues¶

Checklist:

- [ ] Using release build? (`cargo build --release`)
- [ ] Not running under debugger?
- [ ] CPU not throttled? (check power settings on laptops)
- [ ] No other heavy processes competing for resources?

Solutions:

1. Reduce population size in strategies
2. Use streaming evaluation for large datasets
3. Increase system swap space
4. Consider using chunked optimization

Getting More Help¶

If your issue isn't listed above:

1. Search existing issues: GitHub Issues
2. Ask in discussions: GitHub Discussions
3. Open a new issue with:
4. Your OS and version
5. Python version
6. ArqonHPO version
7. Full error message/stack trace

Uninstalling¶

Python Package¶

pip uninstall arqonhpo

Rust CLI¶

cargo uninstall arqonhpo-cli

# Or manually remove
rm ~/.cargo/bin/arqonhpo-cli

Complete Cleanup¶

# Remove pip cache
pip cache purge

# Remove cargo artifacts (if built from source)
cd ArqonHPO && cargo clean

Next Steps¶

You're all set! Here's where to go next:

Having trouble? Open an issue or ask in discussions.

Found ArqonHPO useful? Consider starring the repo