README.md

---
license: cc-by-4.0
library_name: scitomo
tags: [cryo-electron-tomography, denoising, missing-wedge, safetensors, scitomo]
---

# DeepDeWedge tutorial checkpoint for scitomo

This repository contains the official DeepDeWedge tutorial checkpoint converted
to a scitomo-native, non-executable Safetensors package. It reinstantiates the
scitomo `UNet3D` used by the `deepdewedge` restoration method. It is not a
PyTorch Lightning trainer-resume checkpoint and does not contain optimizer,
scheduler, callback, random-number-generator, or dataloader state.

Package identity:

- scitomo catalog name: `deepdewedge_tutorial`
- native package id: `deepdewedge_tutorial`
- package revision: `1`
- minimum scitomo version: `0.5.4`
- learned-checkpoint format: `1`
- method: restoration / `deepdewedge`
- construction fingerprint:
  `sha256:c9da7decd489f0f4f893dce565f37db25abc63d0d3efcacad9835305ffd97cb2`
- inference fingerprint:
  `sha256:c2c5eba72579510265258dcfce3a5be2f851f9276c7e53d92330d78eb37720dd`

## Source and attribution

The original checkpoint is part of **DeepDeWedge Tutorial Data**, authored by
Simon Wiedemann and published on Figshare under CC BY 4.0:

- DOI: <https://doi.org/10.6084/m9.figshare.25043435.v1>
- Figshare file id: `45582309`
- archive: `tutorial_data.zip`
- archive member: `tutorial_data/fitted_model.ckpt`
- archive SHA-256:
  `7c871342e51f5a66a773fe427d72944b5d2cc8ff41c5b7415ab38dbfc9ac6d58`
- original checkpoint SHA-256:
  `5262f6c11e85fd662b02e59efe936fa7b69913758e841235be2683f7bd03ec76`

The method and upstream implementation are described by:

> Simon Wiedemann and Reinhard Heckel. “A deep learning method for
> simultaneous denoising and missing wedge reconstruction in cryogenic
> electron tomography.” Nature Communications 15, 8255 (2024).
> <https://doi.org/10.1038/s41467-024-51438-y>

Upstream code:
<https://github.com/MLI-lab/DeepDeWedge/tree/072075692a44a8f17394214369e6e762abe52bc3>

The conversion changed the serialization, state names, and executable
construction mechanism. It did not intentionally alter tensor values. Two
learned normalization values that upstream stored as non-trainable parameters
are native scitomo buffers with identical values. See `ATTRIBUTION.md`,
`conversion/conversion-record.json`, and `LICENSES/`.

## Native construction and inference

`construction.json` specifies a residual single-input/single-output 3D U-Net
with 64 initial channels, three downsampling blocks, strided-convolution
downsampling, transposed-convolution upsampling, leaky-ReLU activations, and
the learned input-normalization location and scale from the tutorial
checkpoint.

Volume tensors use scitomo's canonical trailing-axis layout `(..., Z, Y, X)`.
The network layout is `(..., C, Z, Y, X)`, with one scalar volume channel.
The canonical rotation axis is `Z`; at theta zero the beam axis is `Y`, and
detector `(V, U)` corresponds to `(Z, X)`.

The frozen DeepDeWedge inference profile requires:

- paired half-tomograms, refined separately and averaged;
- a 50-degree full-width missing-wedge Fourier mask on each half;
- `96 x 96 x 96` patches with overlap `32 x 32 x 32`;
- trailing reflection padding for full coverage;
- patch-statistic normalization and network denormalization;
- linear-ramp weighted patch reassembly; and
- no full-tomogram standardization.

The package was converted from the tutorial's fitted network. It assumes the
same scientific meaning, preprocessing, normalization, missing-wedge
convention, and paired-half workflow. It is not a general-purpose cryo-ET
foundation model.

## Files and identities

| File | Bytes | SHA-256 |
| --- | ---: | --- |
| `construction.json` | 2,175 | `d4c7eced057042438827de168d47b7900311fba742ce52445675be7f40343432` |
| `inference.json` | 968 | `217636919d17d9332aa49474e893064ed1dfb29f016a468cf22d439cf16887a0` |
| `weights.safetensors` | 109,294,940 | `2a34aeb61dba5da5c7b78f4cc26de9b8a9134ac12dc08876a8e93bf02776c795` |
| `conversion/conversion-record.json` | 13,953 | `e55c35f9e233e0ba04ea1332306b179b96db12158b4eb0cd8d5dcd3609ac8e54` |
| `validation/validation-record.json` | 1,946 | `eb2f9153d49e7124a8aeb1951230b6124f5fdc18ea1f53b2c9e28db55273cc3f` |

`manifest.json` binds these files plus this model card, attribution, and
license resources by exact size and SHA-256. The immutable Hugging Face commit
and scitomo learned-weight catalog bind the complete distribution, including
the manifest and documentation resources, without a self-referential checksum
inside this README.

## Validation

All 56 source tensors were mapped one-to-one and exactly matched after native
assignment.

Predetermined CPU float32 checks:

| Case | Tolerance | Result |
| --- | --- | --- |
| Synthetic forward parity | `atol=1e-6`, `rtol=1e-5` | bit-exact; max absolute error `0`; relative L2 `0` |
| Real tutorial-volume crop | relative L2 `<=1e-4` | max absolute error `7.152557373046875e-7`; relative L2 `1.2612566990810592e-7` |

The real-data case used a centered `32 x 32 x 32` crop from
`tutorial_data/tomo_even_frames.rec`. Vendor and native outputs were finite,
had identical shapes, and had the same absolute-peak spatial landmark at
`(Z, Y, X) = (25, 13, 0)`.

The evidence proves native network-state and reviewed forward parity for the
frozen inputs. It does not establish accuracy on every microscope, specimen,
acquisition protocol, missing-wedge angle, or preprocessing pipeline, nor does
it replace validation of a complete user workflow.

## Safe loading

The repository contains declared data files only. Loading does not execute
remote code, import the vendor project, or use Python pickle. scitomo requires
the exact catalog commit and verifies every declared size and SHA-256 before
opening `weights.safetensors`. Hugging Face `trust_remote_code` is never used.

Install the learned and catalog extras before resolving the catalog package:

```text
pip install "scitomo[learned,catalog]"
```

Normal runtime loading is owned by scitomo's central learned-checkpoint API.
Do not load the original Lightning checkpoint in an ordinary runtime.

## Licenses

- Converted weights and their source tutorial dataset: CC BY 4.0. See
  `LICENSES/DeepDeWedge-Tutorial-Data-CC-BY-4.0.txt`.
- Upstream DeepDeWedge code and behavior used for construction/conversion:
  BSD 2-Clause. See `LICENSES/DeepDeWedge-Code-BSD-2-Clause.txt`.

The CC BY 4.0 attribution and modification notice are provided in
`ATTRIBUTION.md`. No endorsement by the original authors or rights holders is
implied.