README.md

---
library_name: ilex
tags:
- jax
- equinox
- ilex
- neuroimaging
- hypernetwork-conditioned
license: other
license_name: freesurfer-research
license_link: https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferSoftwareLicense
---

# SynthMorph deformable (HyperMorph) -- Deformable variant v3 (FreeSurfer 8.x default)

## Description

SynthMorph deformable (Hoffmann et al. 2024, *Imaging Neuroscience* 2:1-33) ported to JAX / Equinox from the FreeSurfer-bundled VoxelMorph reference implementation. The network is a HyperMorph-style hypernetwork wrapped around a 5-level VxmDense U-Net -- a 4-layer dense MLP (32 units per layer) takes a single hyperparameter (the deformation regularization weight) and outputs the conv kernels + biases for all 13 conv layers of the embedded U-Net at forward time. The published ``synthmorph.deform.3.h5`` (~3.5 GB) carries the dense-projection weights that map the hypernet embedding to each conv layer's kernel + bias; the conv layers themselves hold no static weights. The v0 ilex bundle returns the raw 3-channel velocity field at the input spatial resolution; downstream integration (squaring-and-scaling VecInt) and spatial-transform warp are parameter-free pure numerics and live outside the v0 bundle, mirroring the affine port's barycenter / fit_affine deferral.

## Intended use

Hypernetwork-conditioned deformable registration of two 3D brain volumes. The user picks a regularization weight in [0, 1] at inference time without retraining. The bundle returns the raw 3-channel velocity field; downstream integration (squaring-and-scaling VecInt) and spatial-transform warp are parameter-free and live outside the v0 bundle.

## Usage

```python
from ilex.models.synthmorph_deform import SynthMorphDeform
model = SynthMorphDeform.from_pretrained('ilex-hub/synthmorph.deform.3')
```

## Authors

Hoffmann M., Hoopes A., Greve D. N., Iglesias J. E., Fischl B., Dalca A. V.

## Citation

Hoffmann M., Hoopes A., Greve D. N., Fischl B., Dalca A. V. (2024). Anatomy-aware and acquisition-agnostic joint registration with SynthMorph. Imaging Neuroscience, 2:1-33. doi:10.1162/imag_a_00197. Original HyperMorph framework: Hoopes A., Hoffmann M., Greve D. N., Fischl B., Guttag J., Dalca A. V. (2022). Learning the effect of registration hyperparameters with HyperMorph. Journal of Machine Learning for Biomedical Imaging, 1:1-30.

### References

- Hoffmann M., Billot B., Greve D. N., Iglesias J. E., Fischl B., Dalca A. V. (2022). SynthMorph: learning contrast-invariant registration without acquired images. IEEE Transactions on Medical Imaging, 41(3):543-558. doi:10.1109/TMI.2021.3116879.
- Hoffmann M., Hoopes A., Greve D. N., Fischl B., Dalca A. V. (2024). Anatomy-aware and acquisition-agnostic joint registration with SynthMorph. Imaging Neuroscience, 2:1-33. doi:10.1162/imag_a_00197.
- Hoopes A., Hoffmann M., Greve D. N., Fischl B., Guttag J., Dalca A. V. (2022). Learning the effect of registration hyperparameters with HyperMorph. Journal of Machine Learning for Biomedical Imaging, 1:1-30.

## License

HF Hub license tag: `other`
HF Hub license slug: `freesurfer-research`

**Effective terms:** Weights distributed by upstream as part of the FreeSurfer software bundle under the FreeSurfer Software License (FSLA), a permissive academic / non-commercial research offering. See license_url for the binding terms. Same license terms as the synthmorph_affine catalog entry; the deformable hypernetwork is a separately-trained downstream artefact of voxelmorph + SynthMorph synthetic-data training.

Upstream license reference: https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferSoftwareLicense

### Copyright

Network architecture, training code, and pretrained weights: copyright (c) the SynthMorph / VoxelMorph authors and the FreeSurfer maintainers, distributed via the FreeSurfer software distribution under the FreeSurfer Software License (FSLA; permissive academic / non-commercial research use). See https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferSoftwareLicense for the binding terms. The voxelmorph reference implementation itself is dual- Apache-2.0 / GPL-3.0; the SynthMorph weights are a downstream artefact of voxelmorph + synthetic-data training, distributed through the FreeSurfer bundle. JAX / Equinox port code: copyright (c) the ilex authors, released under the Apache-2.0 / GPL-3.0 dual license used by ilex itself; the ilex port covers only the original Equinox re-expression and does not override the upstream FreeSurfer / voxelmorph terms.

## Upstream source

Original weights / reference implementation: https://github.com/voxelmorph/voxelmorph

## Provenance

This artefact was produced by [ilex](https://github.com/hypercoil/ilex)'s
save/load pipeline. The architecture is implemented in
`ilex.models.synthmorph_deform.SynthMorphDeform` and the weights have been converted
from their upstream format. See the upstream source above
for the canonical reference.