---
library_name: ilex
tags:
- jax
- equinox
- ilex
- neuroimaging
- spherical
license: other
license_name: sugar-research-only
license_link: https://github.com/NingAnMe/SUGAR
gated: auto
extra_gated_prompt: |
  The SUGAR pretrained weights are distributed by the upstream
  authors (NingAnMe/SUGAR) under a non-OSI Research-Only
  notice (academic research use is free; commercial use
  requires separate authorization from the upstream authors).
  The ilex bundle preserves these terms verbatim. Access is
  granted solely for non-commercial academic research and
  educational use. The GATv2Conv-based architecture is
  itself Apache-2.0 (upstream code); the JAX / Equinox
  re-expression in ilex.models.sugar inherits that
  architecture under Apache-2.0 but does NOT override the
  SUGAR Research-Only terms governing the trained weights.
  Please confirm your use case is non-commercial academic
  research below.
extra_gated_fields:
  Name: text
  Affiliation: text
  Email: text
  Intended use: text
  I confirm non-commercial academic research use only: checkbox
extra_gated_button_content: Acknowledge and download
---

# SUGAR (cortical-surface registration) -- Left-hemisphere non-rigid (fsaverage4)

## Description

SUGAR (Spherical Ultrafast Graph Attention Registration) is a GATv2-based spherical UNet for fast cortical-surface registration that DeepPrep pins for its surface-registration stage. The architecture is a Generic_GatUNet parameterised by the finest FreeSurfer fsaverage level: an encoder of ResEncodingBlocks (each is two stacked GATv2Conv layers with a LeakyReLU between and an optional residual add) pooling down through fsaverage{N..0}, a bottom block at fsaverage0 (12 vertices), a decoder mirroring the encoder with mid-edge unpooling + skip-concat, and a 3-channel output head producing per-vertex XYZ-Euler rotations. The rigid variant mean-reduces the per-vertex Euler field to a single (1, 3) global rotation. Ten variants (per hemisphere rigid + 4 per-hemisphere non-rigid at fsaverage{3,4,5,6}) compose into a coarse-to-fine cascade. The trained checkpoints were saved as full nn.Module pickles against PyTorch Geometric 2.2.0; ilex stages them via a transitional unpickle env, dumps state_dict, and ships canonical safetensors. Architecture consumes per-vertex sulc features (z-scored against the bundled training-set per-vertex stats); cascade driver applies barycentric resampling between the subject sphere and fsaverage at each stage.

## Intended use

fsaverage4-resolution non-rigid refinement (642 vertices); takes the upsampled fsaverage3 output as input.

## Usage

```python
from ilex.models.sugar import SUGAR
model = SUGAR.from_pretrained('ilex-hub/sugar.lh.norigid.fsaverage4.1')
```

## Authors

Ren J., An N., Lin C., Zhang Y., Sun Z., Zhang W., Li S., Guo N., Cui W., Hu Q., Wang W., Wu X., Wang Y., Jiang T., Satterthwaite T. D., Wang D., Liu H.

## Citation

Ren J., An N., Lin C., Zhang Y., Sun Z., Zhang W., Li S., Guo N., Cui W., Hu Q., Wang W., Wu X., Wang Y., Jiang T., Satterthwaite T. D., Wang D., Liu H. (2023). SUGAR: spherical ultrafast graph attention framework for cortical surface registration. arXiv:2307.00511.

### References

- Ren J., An N., Lin C., Zhang Y., Sun Z., Zhang W., Li S., Guo N., Cui W., Hu Q., Wang W., Wu X., Wang Y., Jiang T., Satterthwaite T. D., Wang D., Liu H. (2023). SUGAR: spherical ultrafast graph attention framework for cortical surface registration. arXiv:2307.00511. https://arxiv.org/abs/2307.00511
- Brody S., Alon U., Yahav E. (2022). How Attentive are Graph Attention Networks? ICLR 2022. arXiv:2105.14491. (The GATv2 attention primitive SUGAR builds on.)

## License

HF Hub license tag: `other`
HF Hub license slug: `sugar-research-only`

**Effective terms:** SUGAR Research-Only License (per the upstream README at https://github.com/NingAnMe/SUGAR). Academic research use free; commercial use of the pretrained weights requires separate authorization from the upstream authors. The network architecture and training code are Apache-2.0 (the NingAnMe/SUGAR upstream); the FreeSurfer fsaverage topology files bundled inside the package (auxi_data/fsaverage*.sphere + _upsample_neighbors.npz) ship from the upstream's utils/auxi_data/ under the same Apache-2.0 terms. The ilex JAX / Equinox port code is separately licensed under Apache-2.0 / GPL-3.0 for the port code itself, but the ilex license does NOT override the upstream Research-Only terms governing the pretrained weights.

Upstream license reference: https://github.com/NingAnMe/SUGAR

### Copyright

Network architecture and training code: copyright (c) the SUGAR contributors, distributed under Apache-2.0 at https://github.com/NingAnMe/SUGAR (with the DeepPrep fork at https://github.com/pBFSLab/SUGAR). Pretrained weights distributed by the SUGAR authors carry a non-OSI Research-Only notice in line with the upstream README; commercial use of the weights requires separate authorization from the upstream authors. The ilex JAX / Equinox port code is separately licensed under Apache-2.0 / GPL-3.0 for the port code itself, but the ilex license does NOT override or re-license the upstream Research-Only terms governing the pretrained weights. The bundled FreeSurfer fsaverage topology files (.sphere binaries + _upsample_neighbors.npz) ship from the upstream SUGAR repo's utils/auxi_data/ directory under the same Apache-2.0 terms as the SUGAR code.

## Upstream source

Original weights / reference implementation: https://github.com/NingAnMe/SUGAR

## Provenance

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