> 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.

# stanza.analysis.fitting



## Module Contents

### Classes

| Name | Description |
|------|-------------|
| [`PinchoffFitResult`](#stanzaanalysisfittingpinchofffitresult) | Result of pinchoff curve fitting. |

### Functions

| Name | Description |
|------|-------------|
| [`pinchoff_curve`](#stanzaanalysisfittingpinchoff_curve) | Smooth pinchoff curve with coefficients a, b, c |
| [`derivative_extrema_indices`](#stanzaanalysisfittingderivative_extrema_indices) | Return the indices of key voltages for pinchoff curves. |
| [`_compute_initial_params`](#stanzaanalysisfitting_compute_initial_params) | Compute initial parameter estimates from normalized data. |
| [`_compute_parameter_bounds`](#stanzaanalysisfitting_compute_parameter_bounds) | Compute robust parameter bounds from normalized data. |
| [`_map_index_to_voltage`](#stanzaanalysisfitting_map_index_to_voltage) | Map an array index to the corresponding voltage value. |
| [`compute_indices_from_threshold`](#stanzaanalysisfittingcompute_indices_from_threshold) | Find cutoff and saturation indices based on threshold percentages. |
| [`fit_pinchoff_parameters`](#stanzaanalysisfittingfit_pinchoff_parameters) | Fit the pinchoff parameters a, b, c of the pinchoff curve, and returns the cut-off, transition, and conducting voltages. |

### Data

`DEFAULT_C_MARGIN`
`DEFAULT_BOUNDS`

### API

```python
stanza.analysis.fitting.DEFAULT_C_MARGIN
```

**Value**: `10.0`


```python
stanza.analysis.fitting.DEFAULT_BOUNDS
```

**Value**: `[(1e-08, 1.0), (), ()]`


```python
class stanza.analysis.fitting.PinchoffFitResult
```

Result of pinchoff curve fitting.

Attributes:
    v_cut_off: Cut-off voltage (where current flowing through the device approaches a near-zero value)
    v_transition: Transition voltage (midpoint of transition from cut-off to saturation)
    v_saturation: Conducting voltage (where current flowing through the device approaches a saturated state)
    popt: Fitted parameters `[a, b, c]` for pinchoff_curve in normalized space
    pcov: Covariance matrix of fitted parameters
    v_min: Minimum voltage value used for normalization
    v_max: Maximum voltage value used for normalization
    i_min: Minimum current value used for normalization
    i_max: Maximum current value used for normalization

Note:
    popt parameters are fitted in normalized `[0,1]` space. To generate the
    fitted curve in original space, use the fit_curve() method or manually
    normalize voltages before applying pinchoff_curve().

```python
v_cut_off: float | None
```

**Value**: `None`


```python
v_transition: float | None
```

**Value**: `None`


```python
v_saturation: float | None
```

**Value**: `None`


```python
popt: numpy.ndarray
```

**Value**: `None`


```python
pcov: numpy.ndarray
```

**Value**: `None`


```python
v_min: float
```

**Value**: `0.0`


```python
v_max: float
```

**Value**: `1.0`


```python
i_min: float
```

**Value**: `0.0`


```python
i_max: float
```

**Value**: `1.0`


```python
fit_curve(voltages: numpy.ndarray) -> numpy.ndarray
```

Generate fitted curve in original voltage/current space.

**Parameters:**

<ParamField path="voltages" type="numpy.ndarray">
  Voltage array in original space
</ParamField>

**Returns:**

Fitted current values in original space


```python
stanza.analysis.fitting.pinchoff_curve(
    x: numpy.ndarray,
    a: float,
    b: float,
    c: float
) -> numpy.ndarray
```

Smooth pinchoff curve with coefficients a, b, c

From: Darulová, J. et al. Autonomous tuning and charge state
    detection of gate defined quantum dots. Physical Review,
    Applied 13, 054005 (2019).

**Parameters:**

**Returns:**

np.ndarray: Pinchoff current f(x) output


```python
stanza.analysis.fitting.derivative_extrema_indices(
    x: numpy.ndarray, y: numpy.ndarray
) -> tuple[int, int, int]
```

Return the indices of key voltages for pinchoff curves.

v_cut_off corresponds to the cut-off state (low current)
v_saturation corresponds to the saturated state (high current)
v_transition corresponds to the transition from cut-off to saturation (steepest slope)

**Parameters:**

**Returns:**

Tuple[int, int, int]:
(transition_v_ind, saturation_v_ind, cut_off_v_ind)


```python
stanza.analysis.fitting._compute_initial_params(
    v_norm: numpy.ndarray, i_norm: numpy.ndarray
) -> numpy.ndarray
```

Compute initial parameter estimates from normalized data.

For inverted curves (decreasing with voltage), we use negative b values
to represent the inversion while keeping amplitude positive.


```python
stanza.analysis.fitting._compute_parameter_bounds(
    v_norm: numpy.ndarray, i_norm: numpy.ndarray
) -> tuple[numpy.ndarray, numpy.ndarray]
```

Compute robust parameter bounds from normalized data.

Calculates appropriate lower and upper bounds for the three parameters
[a, b, c] of the pinchoff_curve function based on the characteristics
of the input data. The bounds are designed to constrain the optimization
while allowing for both normal and inverted pinchoff curves.

**Parameters:**

<ParamField path="v_norm" type="numpy.ndarray">
  Normalized voltage array (typically in [0, 1] range)
</ParamField>

<ParamField path="i_norm" type="numpy.ndarray">
  Normalized current array (typically in [0, 1] range)
</ParamField>

**Returns:**

Tuple of (lower_bounds, upper_bounds) where each is a numpy array
of shape (3,) containing bounds for parameters [a, b, c]:
- a (amplitude): Positive value, typically 0.01\*i_range to 2.0\*i_range
- b (slope): Can be negative for inverted curves, `|b| <= 20.0/v_range`
- c (offset): Computed to ensure curve spans the voltage range
If computed bounds are invalid (lower >= upper), falls back to
DEFAULT_BOUNDS for that parameter.


```python
stanza.analysis.fitting._map_index_to_voltage(
    index: int, voltages: numpy.ndarray
) -> float | None
```

Map an array index to the corresponding voltage value.

**Parameters:**

<ParamField path="index" type="int">
  Array index
</ParamField>

<ParamField path="voltages" type="numpy.ndarray">
  Array of voltage values
</ParamField>

**Returns:**

Voltage at the given index, or None if index is out of bounds


```python
stanza.analysis.fitting.compute_indices_from_threshold(
    fitted_current: numpy.ndarray,
    percent_threshold: float,
    original_current: numpy.ndarray | None = None
) -> tuple[int, int]
```

Find cutoff and saturation indices based on threshold percentages.

Computes two thresholds: a lower threshold (min + percent_threshold * range)
and an upper threshold (max - percent_threshold * range). Returns the indices
where the fitted current first crosses these thresholds.

For normal curves (increasing current), returns where current rises above each threshold.
For inverted curves (decreasing current), returns where current falls below each threshold.

**Parameters:**

<ParamField path="fitted_current" type="numpy.ndarray">
  Fitted current values (normalized or unnormalized)
</ParamField>

<ParamField path="percent_threshold" type="float">
  Percentage (0 to 1) defining distance from min/max.
</ParamField>

<ParamField path="original_current" type="numpy.ndarray | None">
  Optional original current values before normalization.
</ParamField>

**Returns:**

Tuple of (cutoff_index, saturation_index) where:
- cutoff_index: Index where current enters the transition region from cutoff
- saturation_index: Index where current enters the saturation region
<Note> saturation_index is always >= cutoff_index (saturation occurs later in the voltage sweep) </Note>


```python
stanza.analysis.fitting.fit_pinchoff_parameters(
    voltages: numpy.ndarray,
    currents: numpy.ndarray,
    sigma: float = 2.0,
    percent_threshold: float | None = None
) -> stanza.analysis.fitting.PinchoffFitResult
```

Fit the pinchoff parameters a, b, c of the pinchoff curve, and returns
the cut-off, transition, and conducting voltages.

**Parameters:**

<ParamField path="voltages" type="numpy.ndarray">
  Input voltages
</ParamField>

<ParamField path="currents" type="numpy.ndarray">
  Input currents
</ParamField>

<ParamField path="sigma" type="float">
  Gaussian filter bandwidth for smoothing
</ParamField>

<ParamField path="percent_threshold" type="float">
  If provided, use threshold-based cutoff
  instead of derivative-based. Value between 0 and 1 representing
  percentage above baseline tail of the fitted curve.
</ParamField>

**Returns:**

PinchoffFitResult containing fitted voltages and parameters