Initial upload via tools/push_to_hf.py (architecture: ilex.models.synthmorph_deform.SynthMorphDeform)

README.md

@@ -0,0 +1,68 @@
+---
+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.

config.json

@@ -0,0 +1,65 @@
+{
+  "_ilex": {
+    "architecture": "ilex.models.synthmorph_deform.model.SynthMorphDeform",
+    "constructor_kwargs": {
+      "add_nf": [
+        256,
+        256,
+        256,
+        256
+      ],
+      "dec_nf": [
+        256,
+        256,
+        256,
+        256
+      ],
+      "enc_nf": [
+        256,
+        256,
+        256,
+        256
+      ],
+      "flow_nf": 3,
+      "nb_hyp_layers": 4,
+      "nb_hyp_params": 1,
+      "nb_hyp_units": 32,
+      "src_feats": 1,
+      "trg_feats": 1
+    },
+    "format": "ilex",
+    "framework_version": {
+      "equinox": "0.13.8",
+      "ilex": "0.0.0.dev0",
+      "jax": "0.10.0",
+      "jaxlib": "0.10.0",
+      "numpy": "2.4.4",
+      "safetensors": "0.7.0"
+    },
+    "has_state": false,
+    "origin": "ilex-native"
+  },
+  "authors": "Hoffmann M., Hoopes A., Greve D. N., Iglesias J. E., Fischl B., Dalca A. V.",
+  "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.",
+  "data_type": "nibabel",
+  "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.",
+  "equinox_version": "0.13.8",
+  "ilex_version": "0.0.0.dev0",
+  "image_classes": "Per-sample 3D medical-imaging volumes (moving + fixed). Intensity normalisation matches the upstream ``transform(..., normalize=True)`` step (clip to per-sample 99th percentile; rescale to ``[0, 1]``). Both volumes must be at the same spatial grid; the published checkpoint is trained at a conformed input shape and benefits from upstream-style padding when the caller's grid differs.",
+  "intended_use": "Deformable registration of two 3D medical-imaging volumes, hypernetwork-conditioned on the deformation regularization weight (the user picks any value in [0, 1] at inference time without retraining). The v0 ilex bundle returns the raw velocity field; the user composes integration + spatial-transform warp externally (a ``nimox.modules`` follow-up, mirroring the affine port's barycenter / fit_affine deferral).",
+  "jax_version": "0.10.0",
+  "network_data_format": {
+    "inputs": {},
+    "outputs": {}
+  },
+  "numpy_version": "2.4.4",
+  "pred_classes": "3-channel velocity field at the input spatial resolution. Each channel is the per-voxel displacement contribution along one spatial axis, in voxel units; the downstream integration step (squaring-and-scaling VecInt) converts the velocity field to the per-voxel diffeomorphic displacement, and the spatial-transform step then warps the source volume using the displacement field. Both of those downstream steps are parameter-free and out-of-scope at v0.",
+  "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."
+  ],
+  "schema": "https://github.com/Project-MONAI/MONAI-extra-test-data/releases/download/0.8.1/meta_schema_20240725.json",
+  "task": "Hypernetwork-conditioned deformable image-to-image registration",
+  "version": "0.0.0"
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3b3242f5f5827f5855741766f9413c5fcd82428249c2a4a036dc991b7d04e949
+size 3508541300