> ## Documentation Index
> Fetch the complete documentation index at: https://dynex.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Dynex SDK and configure your environment

## System Requirements

| Component | Minimum               | Recommended |
| --------- | --------------------- | ----------- |
| Python    | 3.11                  | 3.11+       |
| RAM       | 4 GB                  | 8 GB+       |
| Storage   | 2 GB                  | 10 GB+      |
| OS        | Linux, macOS, Windows | —           |

## Install

<Tabs>
  <Tab title="uv (recommended)">
    [uv](https://docs.astral.sh/uv/) is a fast Python package manager. If you don't have it:

    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```

    Then:

    ```bash theme={null}
    uv add dynex
    ```

    Or in a new project:

    ```bash theme={null}
    uv init my-project && cd my-project
    uv add dynex
    uv run python main.py
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install dynex
    ```
  </Tab>
</Tabs>

For development or latest features, install from source:

```bash theme={null}
git clone https://github.com/Dynex-Development/py-sdk.git
cd py-sdk
uv sync --group dev   # or: pip install -e .
```

### With optional dependencies

<Tabs>
  <Tab title="uv">
    ```bash theme={null}
    uv add dynex python-dotenv
    uv add dynex pennylane
    uv add dynex torch
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install dynex python-dotenv   # .env file support
    pip install dynex pennylane       # gate circuits
    pip install dynex torch           # PyTorch neuromorphic layers
    ```
  </Tab>
</Tabs>

## Core dependencies

The SDK automatically installs:

* **grpcio** ≥ 1.60.0 — gRPC communication
* **protobuf** ≥ 4.25.0 — protocol buffer serialization
* **dimod** ≥ 0.12.0 — quadratic model framework
* **numpy** ≥ 1.24.0 — numerical computing
* **pydantic** ≥ 2.0.0 — data validation

## Configuration

### Environment variables

```bash theme={null}
export DYNEX_SDK_KEY="your_sdk_key"
export DYNEX_GRPC_ENDPOINT="quantum-router-engine-grpc.hz.dynex.co:3000"
```

### .env file (recommended)

Create `.env` in your project root and install `python-dotenv`:

```bash theme={null}
# .env
DYNEX_SDK_KEY=your_sdk_key
DYNEX_GRPC_ENDPOINT=quantum-router-engine-grpc.hz.dynex.co:3000

# Optional
DYNEX_COMPUTE_BACKEND=cpu
DYNEX_DEFAULT_TIMEOUT=300.0
```

```bash theme={null}
pip install python-dotenv
```

The SDK automatically discovers `.env` files in the current directory and up to 3 parent directories.

### Verify installation

```python theme={null}
import dynex
print(dynex.__version__)

from dynex import DynexConfig, ComputeBackend
import dimod

bqm = dimod.BinaryQuadraticModel({0: 1, 1: -1}, {(0, 1): 0.5}, 0.0, 'BINARY')
config = DynexConfig(compute_backend=ComputeBackend.LOCAL)
model = dynex.BQM(bqm)
sampler = dynex.DynexSampler(model, config=config)
sampleset = sampler.sample(num_reads=10)
print(f"Test passed. Best energy: {sampleset.first.energy}")
```

## Platform notes

<Tabs>
  <Tab title="Linux">
    No additional setup required. All features work out of the box.
  </Tab>

  <Tab title="macOS">
    Install Xcode command line tools if not present:

    ```bash theme={null}
    xcode-select --install
    ```

    Apple Silicon (M1/M2/M3) is fully supported.
  </Tab>

  <Tab title="Windows">
    * Install [Microsoft Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) if compilation errors occur
    * WSL (Windows Subsystem for Linux) recommended for production use
    * PowerShell and Command Prompt both supported
  </Tab>
</Tabs>

## Docker

```dockerfile theme={null}
FROM python:3.11-slim

RUN pip install dynex python-dotenv

ENV DYNEX_SDK_KEY=${DYNEX_SDK_KEY}
ENV DYNEX_GRPC_ENDPOINT=${DYNEX_GRPC_ENDPOINT}

COPY . /app
WORKDIR /app
CMD ["python", "main.py"]
```

```bash theme={null}
docker build -t my-dynex-app .
docker run -e DYNEX_SDK_KEY=your_key -e DYNEX_GRPC_ENDPOINT=quantum-router-engine-grpc.hz.dynex.co:3000 my-dynex-app
```

## Jupyter notebooks

```bash theme={null}
pip install dynex jupyter   # or: uv add dynex jupyter
jupyter notebook
```

Add this boilerplate at the top of your notebooks:

```python theme={null}
import dynex
from dynex import DynexConfig, ComputeBackend, QPUModel
import dimod
import numpy as np

config = DynexConfig(
    compute_backend=ComputeBackend.GPU,
    use_notebook_output=True
)
print(f"Dynex SDK {dynex.__version__} ready")
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="ImportError: No module named 'grpc'">
    ```bash theme={null}
    pip install grpcio
    ```
  </Accordion>

  <Accordion title="ModuleNotFoundError: No module named 'dynex'">
    Check that you are using the correct Python environment. Try:

    ```bash theme={null}
    pip uninstall dynex && pip install dynex
    ```
  </Accordion>

  <Accordion title="Connection errors (CPU/GPU/QPU backends)">
    * Verify credentials: `DYNEX_SDK_KEY` and `DYNEX_GRPC_ENDPOINT`
    * Check that port 443 is not blocked by a firewall
    * Test connectivity: `grpcurl quantum-router-engine-grpc.hz.dynex.co:3000 list`
  </Accordion>

  <Accordion title="ValueError: qpu_model is required when compute_backend='qpu'">
    QPU backend requires an explicit model. Use:

    ```python theme={null}
    config = DynexConfig(
        compute_backend=ComputeBackend.QPU,
        qpu_model='apollo_rc1'
    )
    ```
  </Accordion>

  <Accordion title="FileNotFoundError: Solver file not found in testnet mode">
    LOCAL backend requires the `dynexcore` binary in a `testnet/` directory. Download it from the releases page or switch to `ComputeBackend.CPU`.
  </Accordion>
</AccordionGroup>

## Upgrading from legacy SDK

```bash theme={null}
pip uninstall dynex
pip install dynex
```

Notable changes from legacy SDK:

* Replace `mainnet=True/False` with explicit `DynexConfig(compute_backend=...)`
* Remove `v2=True` parameter from sampler calls
* Communication is now gRPC-based instead of REST