# `vllm_mlx.optimizations`

Hardware detection and system information for vllm-mlx.

[View the complete module source at #L1-L209](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L1-L209).

## API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

::: vllm_mlx.optimizations
    options:
      members:
        - logger
        - HardwareInfo
        - HARDWARE_PROFILES
        - get_system_memory_gb
        - detect_hardware
        - benchmark_memory_bandwidth
        - get_optimization_status
      filters: []
      show_if_no_docstring: true

## Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

<details class="api-contract" id="contract-vllm_mlx.optimizations.HardwareInfo" markdown="1">
<summary><code>vllm_mlx.optimizations.HardwareInfo</code> · class</summary>

```python
vllm_mlx.optimizations.HardwareInfo(chip_name: str, total_memory_gb: float, memory_bandwidth_gbs: float, gpu_cores: int)
```

Hardware information for Apple Silicon.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `chip_name` | `str` | `yes` | `none` | Required constructor field. |
| `total_memory_gb` | `float` | `yes` | `none` | Required constructor field. |
| `memory_bandwidth_gbs` | `float` | `yes` | `none` | Required constructor field. |
| `gpu_cores` | `int` | `yes` | `none` | Required constructor field. |

**Returns**

- Constructs: `vllm_mlx.optimizations.HardwareInfo`

**Exceptions and behavior**

Class `HardwareInfo` declares 0 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L34-L40](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L34-L40).

</details>

<details class="api-contract" id="contract-vllm_mlx.optimizations.get_system_memory_gb" markdown="1">
<summary><code>vllm_mlx.optimizations.get_system_memory_gb</code> · function</summary>

```python
vllm_mlx.optimizations.get_system_memory_gb() -> float
```

Get actual system memory in GB.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `float`
- Direct return expressions: `mem_bytes / 1024 ** 3`; `device_info['memory_size'] / 1024 ** 3`; `16.0`

**Exceptions and behavior**

Function `get_system_memory_gb` calls `subprocess.run`, `int`, `result.stdout.strip`, `mx.device_info`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L68-L94](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L68-L94).

</details>

<details class="api-contract" id="contract-vllm_mlx.optimizations.detect_hardware" markdown="1">
<summary><code>vllm_mlx.optimizations.detect_hardware</code> · function</summary>

```python
vllm_mlx.optimizations.detect_hardware() -> HardwareInfo
```

Detect Apple Silicon hardware and return info.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `HardwareInfo`
- Direct return expressions: `HardwareInfo(chip_name=chip_name, total_memory_gb=actual_memory_gb, memory_bandwidth_gbs=profile['bandwidth'], gpu_core…`; `HardwareInfo(chip_name='Unknown', total_memory_gb=actual_memory_gb, memory_bandwidth_gbs=200, gpu_cores=16)`; `HardwareInfo(chip_name='Unknown', total_memory_gb=get_system_memory_gb(), memory_bandwidth_gbs=200, gpu_cores=16)`

**Exceptions and behavior**

Function `detect_hardware` calls `mx.device_info`, `device_info.get`, `get_system_memory_gb`, `sorted`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L97-L141](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L97-L141).

</details>

<details class="api-contract" id="contract-vllm_mlx.optimizations.benchmark_memory_bandwidth" markdown="1">
<summary><code>vllm_mlx.optimizations.benchmark_memory_bandwidth</code> · function</summary>

```python
vllm_mlx.optimizations.benchmark_memory_bandwidth() -> dict
```

Benchmark actual memory bandwidth achieved.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `dict`
- Direct return expressions: `results`

**Exceptions and behavior**

Function `benchmark_memory_bandwidth` calls `mx.random.normal`, `mx.eval`, `time.perf_counter`, `range`; returns `results`.
No direct `raise` statement appears in this definition.

[View source #L144-L174](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L144-L174).

</details>

<details class="api-contract" id="contract-vllm_mlx.optimizations.get_optimization_status" markdown="1">
<summary><code>vllm_mlx.optimizations.get_optimization_status</code> · function</summary>

```python
vllm_mlx.optimizations.get_optimization_status() -> dict
```

Get current hardware and MLX status.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `dict`
- Direct return expressions: `{'hardware': {'chip': hw.chip_name, 'total_memory_gb': hw.total_memory_gb, 'memory_bandwidth_gbs': hw.memory_bandwidth_…`

**Exceptions and behavior**

Function `get_optimization_status` calls `detect_hardware`, `mx.device_info`, `hasattr`, `device_info.get`; returns `{'hardware': {'chip': hw.chip_name, 'total_memory_gb': hw.total_memory_gb, 'memory_bandwidth_gbs': hw.memory_bandwidth_…`.
No direct `raise` statement appears in this definition.

[View source #L177-L209](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L177-L209).

</details>

## Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

| Symbol | Kind | Signature and inputs | What it does | Source |
| --- | --- | --- | --- | --- |
| [`HardwareInfo`](#contract-vllm_mlx.optimizations.HardwareInfo) | class | `HardwareInfo(chip_name: str, total_memory_gb: float, memory_bandwidth_gbs: float, gpu_cores: int)` | Hardware information for Apple Silicon. | [#L34-L40](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L34-L40) |
| [`get_system_memory_gb`](#contract-vllm_mlx.optimizations.get_system_memory_gb) | function | `get_system_memory_gb() -> float` | Get actual system memory in GB. | [#L68-L94](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L68-L94) |
| [`detect_hardware`](#contract-vllm_mlx.optimizations.detect_hardware) | function | `detect_hardware() -> HardwareInfo` | Detect Apple Silicon hardware and return info. | [#L97-L141](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L97-L141) |
| [`benchmark_memory_bandwidth`](#contract-vllm_mlx.optimizations.benchmark_memory_bandwidth) | function | `benchmark_memory_bandwidth() -> dict` | Benchmark actual memory bandwidth achieved. | [#L144-L174](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L144-L174) |
| [`get_optimization_status`](#contract-vllm_mlx.optimizations.get_optimization_status) | function | `get_optimization_status() -> dict` | Get current hardware and MLX status. | [#L177-L209](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/optimizations.py#L177-L209) |