> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.conductorquantum.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.conductorquantum.com/_mcp/server.

# Using the Resonator Dip Finder

> Learn how to detect resonator dips in spectroscopy magnitude traces

The Resonator Dip Finder detects resonator dips in 1D spectroscopy magnitude traces. It works with any input scale (dB, linear, or arbitrary units) through automatic normalization.

This model is useful during quantum device characterization when measuring resonator transmission to identify resonance frequencies. It accepts magnitude data from any scattering parameter measurement (e.g. S11, S21, S12, S22) and returns the indices of detected dips in the input data.

## Installation

We recommend using pip, poetry, or uv to install the package.

**`pip`**

```bash title="pip"
pip install conductorquantum
```

**`poetry`**

```bash title="poetry"
poetry add conductorquantum
```

**`uv`**

```bash title="uv"
uv add conductorquantum
```

## Authentication

The SDK requires an API key for authentication. [Sign in and create a new API key](/control/getting-started/api-keys). Remember, your API key is your access secret - keep it safe
with environment variables.

Using environment variables:

**`Python`**

```python title="Python"
from dotenv import load_dotenv
import os
from conductorquantum import ConductorQuantum

# Load API key from .env file
load_dotenv()
TOKEN = os.getenv("CONDUCTOR_API_KEY")

# Initialize client
client = ConductorQuantum(token=TOKEN)
```

Or provide the API key directly:

**`Python`**

```python title="Python"
from conductorquantum import ConductorQuantum

# Initialize client with API key
client = ConductorQuantum(token="YOUR_API_KEY")
```

## Input Format

The detector expects a **1D numpy array** of shape `(n,)` where `n ≥ 10`:

| Property   | Value                                                     |
| ---------- | --------------------------------------------------------- |
| **Type**   | 1D numpy array                                            |
| **Shape**  | `(n,)` where `n ≥ 10`                                     |
| **Values** | Magnitude data in any scale (dB, linear, arbitrary units) |

> **Tip**
>
> The model accepts magnitude data from **any scattering parameter measurement** (S11, S21, S12, S22, etc.). Input values must not contain NaN and must not be constant (all identical values).

## Output Format

| Key           | Type        | Description                                                                                       |
| ------------- | ----------- | ------------------------------------------------------------------------------------------------- |
| `dip_indices` | `list[int]` | Indices into the input array where resonator dips were detected. Empty list if no dips are found. |

## Usage Example

You can [download](https://storage.googleapis.com/conductor-docs-example-files/resonator-dip-finder-v0.npy) an example file to follow along with the example:

**`Python`**

```python title="Python"
from dotenv import load_dotenv
import os
import numpy as np
from conductorquantum import ConductorQuantum


# Load API key from .env file
load_dotenv()
TOKEN = os.getenv("CONDUCTOR_API_KEY")

# Initialize client
client = ConductorQuantum(token=TOKEN)

# Load spectroscopy magnitude data
data = np.load("resonator-dip-finder-v0.npy")  # shape (n,)

# Detect resonator dips
result = client.control.models.run(
    model="resonator-dip-finder-v0",
    data=data,
)

# Access the detected dip indices
dip_indices = result.output["dip_indices"]
print(f"Detected {len(dip_indices)} dips at indices: {dip_indices}")
```

**`Output`**

```python title="Output"
Detected 3 dips at indices: [13, 68, 114]
```

### Plotting the Results

**`Python`**

```python title="Python"
import matplotlib.pyplot as plt

plt.figure(figsize=(10, 5))
plt.plot(data, 'k-', linewidth=0.8, label='Magnitude')

for i, idx in enumerate(dip_indices):
    if i == 0:
        plt.axvline(x=idx, color='red', linestyle='--', alpha=0.7, label='Detected Dips')
    else:
        plt.axvline(x=idx, color='red', linestyle='--', alpha=0.7)

plt.xlabel('Index')
plt.ylabel('Magnitude (a.u.)')
plt.title('Resonator Dip Finder v0')
plt.legend()
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()
```

![Resonator Dip Finder v0 Output](/_fern-img/5e0cf53d27e89fd03bc43c1344c0ae761c9d614f9e24ac83239f89aa69ed3856.webp)

### Using Physical Units

To plot with real frequency values, map the indices back to your frequency axis:

**`Python`**

```python title="Python"
import matplotlib.pyplot as plt
import numpy as np

# Your physical frequency axis
frequencies_ghz = np.linspace(6.8, 7.2, len(data))

plt.figure(figsize=(10, 5))
plt.plot(frequencies_ghz, data, 'k-', linewidth=0.8, label='Magnitude')

for i, idx in enumerate(dip_indices):
    if i == 0:
        plt.axvline(x=frequencies_ghz[idx], color='red', linestyle='--', alpha=0.7, label='Detected Dips')
    else:
        plt.axvline(x=frequencies_ghz[idx], color='red', linestyle='--', alpha=0.7)

plt.xlabel('Frequency (GHz)')
plt.ylabel('Magnitude (a.u.)')
plt.title('Resonator Dip Finder v0')
plt.legend()
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()
```

## Important Notes

* The model accepts **any scattering parameter measurement** (S11, S21, S12, S22, etc.) - it is not specific to any single scattering parameter.
* Works with any input scale: dB, linear, or arbitrary units.
* No fixed input size is required - any 1D array with 10 or more data points is accepted.
* Returns only dip **indices**, not frequencies. To convert indices to frequencies, map them back to your frequency axis.
* Input data must not contain NaN values and must not be constant (all identical values).