> For the complete documentation index, see [llms.txt](https://infinitode-docs.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://infinitode-docs.gitbook.io/documentation/package-documentation/deepdefend-package-documentation/migration-from-0.1.x.md).

# Migration from 0.1.x

Breaking changes and corrective steps when upgrading DeepDefend from 0.1.x to 0.2.0.

0.2.0 fixes attacks and defenses that were broken or silently wrong in 0.1.x. Some of the fixes necessarily change numerical output, defaults and the public API. Work through this page before trusting any existing result or artifact.

{% hint style="danger" %}
**Results produced with `cw`, `deepfool`, `ead`, `spsa` or `jsma` under 0.1.x are invalid and should be re-run.** In 0.1.x `jsma` and `spsa` raised on every call, `ead` returned the input unchanged with its default arguments, `cw` ignored `c` and `kappa`, and `deepfool` returned out-of-range images. A report that says "the model resisted EAD" because the output equalled the input is not a robustness result.
{% endhint %}

## Checklist

1. Remove every use of `gradient_masking()`.
2. Re-run any `cw`, `deepfool`, `ead`, `spsa` or `jsma` evaluation.
3. Re-check `alpha` in `pgd`, `bim` and `mim` calls if you relied on the old fixed step size.
4. Re-check `cw` calls for the new `epsilon` default and meaning.
5. Retrain or re-wrap models that were saved with a 0.1.x preprocessing defense.
6. Drop any `y.argmax(-1)` → one-hot conversion you added purely to satisfy the attacks.
7. Upgrade to Python 3.9 or newer.

## Breaking changes

### `gradient_masking()` no longer exists

The function — and the `GradientMaskingModel` wrapper — were removed. `hasattr(deepdefend, "gradient_masking")` is `False`, so any import or call site fails immediately.

```python
# 0.1.x
from deepdefend.defenses import gradient_masking
defended = gradient_masking(model, mask_threshold=0.1)

# 0.2.0 — delete the call. It never changed attack gradients.
```

If you want gradient regularisation as a *training* technique, implement it in your own `train_step`. Do not report it as robustness. See [Gradient masking is not a defense](https://infinitode-docs.gitbook.io/documentation/package-documentation/deepdefend-package-documentation/limitations-and-responsible-use.md#gradient-masking-is-not-a-defense).

### `cw`: `epsilon` is now optional and means an L2 budget

The first positional argument after `y` is still `epsilon`, but its default is now `None`, which means unconstrained C\&W that minimises the distortion needed to change the label. If you set `epsilon`, it is an L2 budget expressed as an L-infinity equivalent: the L2 radius is `epsilon * sqrt(num_features)`.

```python
# 0.1.x
adv = cw(model, x, y, 0.01, c=1, kappa=0, num_steps=10, alpha=0.01)

# 0.2.0 — unconstrained (recommended starting point)
adv = cw(model, x, y, c=10.0, num_steps=100, alpha=0.01)

# 0.2.0 — optional L2 budget
adv = cw(model, x, y, epsilon=0.01, c=10.0, num_steps=100)
```

Positional calls keep working, but the fourth positional value now means something different from what it did in 0.1.x. Prefer keyword arguments.

### `pgd` / `bim` / `mim`: `alpha` defaults to `epsilon / 4`

Previously `alpha=0.01`, which equalled `epsilon` for the default settings. Pass `alpha` explicitly to keep the old step size:

```python
adv = pgd(model, x, y, epsilon=0.01, alpha=0.01, num_steps=10)
```

`pgd` also gained `random_start=True` (and a `seed` for it), so it is no longer identical to `bim`. For a deterministic PGD run:

```python
adv = pgd(model, x, y, epsilon=0.01, random_start=False)
```

### `jsma`: `theta` now defaults to `0.0`

Raw saliency values are products of two gradients and are therefore tiny, so the old default of `0.1` selected no features. With `theta=0.0` the attack always picks the most salient feature. If you relied on the old threshold, pass `theta=` explicitly.

### `spsa`: no batch-size or rank restriction

`spsa` used to raise on every call. It now accepts any batch size and any input rank, and its defaults changed: `num_steps=50`, `learning_rate=0.05`, `spsa_samples=32`, `delta=epsilon/5`.

### Attacks accept sparse labels

You no longer need to convert `y.argmax(-1)` to one-hot. One-hot `(batch, classes)`, sparse integer `(batch,)` and binary `(batch, 1)` targets are all accepted, and `from_logits` is auto-detected:

```python
y_sparse = np.array([3, 7, 1, 0])
adv = pgd(model, x, y_sparse, epsilon=0.01)   # works in 0.2.0
```

### Defended models saved with 0.1.x cannot be loaded

Preprocessing defenses in 0.1.x defined their layer classes inside the function body, so the saved graph referenced classes that could not be reconstructed. Loading such a file fails regardless of `custom_objects`. Retrain or re-wrap the base model with the 0.2.0 defense:

```python
defended = gaussian_blur(base_model, kernel_size=3, sigma=1.0)
defended.save("defended.keras")
restored = tf.keras.models.load_model("defended.keras")   # works in 0.2.0
```

### `input_transformation` requires a transformation

The `transformation_function` argument is now mandatory. In 0.1.x omitting it returned an undefended model that looked defended.

```python
defended = input_transformation(model, tf.keras.layers.Rescaling(1.0 / 255))
```

### Image-only defenses raise on non-image input

`gaussian_blur`, `median_smoothing`, `spatial_smoothing`, `jpeg_compression`, `pixel_deflection`, `total_variation_minimization` and `feature_denoising` now raise `ValueError` on non-4-D inputs instead of silently returning the input. JPEG additionally requires 1 or 3 channels.

### Python 3.9+ is required

`python_requires` is now `>=3.9`, and the supported range is 3.9–3.12. TensorFlow does not publish wheels for 3.6–3.8, so 0.1.x's claimed support for those interpreters was never usable.

## Behaviour changes that are not errors

These will not crash your code but change what it produces:

* `fgsm` clips its output to the valid data range (it used to overshoot).
* `deepfool` respects `epsilon` and the clip range.
* `ead` performs a real elastic-net attack (`beta` defaults to `0.001`).
* `mim` normalises momentum per sample rather than across the batch.
* Targeted attacks now perturb instead of freezing at step 0.
* `word_swap` / `char_swap` preserve whitespace, newlines and punctuation exactly.
* `adversarial_training` returns a **new** cloned model, generates examples in batches and keeps your optimiser and loss.
* `gaussian_blur` actually uses `sigma`; `median_smoothing` is a real median filter.
* All preprocessing defenses keep a usable gradient, so gradient attacks against a defended model no longer crash or silently no-op.

## Unchanged

* Module layout: `deepdefend.attacks` and `deepdefend.defenses`.
* Attack and defense function names (except the removed `gradient_masking`).
* `deepdefend.attacks.<fn>(model, x, y, ...)` calling convention.
* MIT (Modified) licence terms.
