README.md

---
# ========== Hub metadata (keep this section) ==========
#   See docs: https://huggingface.co/docs/hub/model-repos#model-card-metadata
license: apache-2.0          # e.g. apache-2.0, mit, cc-by-4.0
library_name: pytorch_lightning
tags:
  - medical-imaging
  - ct-reconstruction
datasets:
  - mayo-clinic-ct-fanbeam
model-index:
  - name: ⬚ MODEL_NAME
    results: []              # optional: add eval results later
# ======================================================
---

# ⬚ MODEL_NAME

Short, one-sentence overview of what the model does and why it matters.

---

## Table of Contents
1. [Model Details](#model-details)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Training & Evaluation](#training--evaluation)
5. [Results](#results)
6. [Limitations & Ethical Considerations](#limitations--ethical-considerations)
7. [Citation](#citation)
8. [Contact](#contact)


---
## 🔖 Pre-trained checkpoints

| Alias | Direct link | File in repo |
|-------|--------------|-------------|
| **LPD fan 360 angles** | [epoch 099](https://huggingface.co/trung-vt/ddct/tree/main/results/logs/mayo_ct_fan_beam_360_angles_full/learned/LPD/LPD_lr0.001/version_0/checkpoints/epoch=099.ckpt) | `results/logs/mayo_ct_fan_beam_360_angles_full/learned/LPD/LPD_lr0.001/version_0/checkpoints/epoch=099.ckpt` |
| **FBPConvNet fan 360 angles** | [epoch 024](https://huggingface.co/trung-vt/ddct/blob/main/results/logs/mayo_ct_fan_beam_360_angles_full/learned/FBPConvNet/csv/FBPConvNet/version_0/checkpoints/epoch%3D024.ckpt) | `results/logs/mayo_ct_fan_beam_360_angles_full/learned/FBPConvNet/csv/FBPConvNet/version_0/checkpoints/epoch%3D024.ckpt` |
| **AR fan 360 angles** | [epoch 099](https://huggingface.co/trung-vt/ddct/tree/main/results/logs/mayo_ct_fan_beam_360_angles_full/AR/csv/AR_reg_lr0.0001_lambda_gp10/version_0/checkpoints/epoch=099.ckpt) | `results/logs/mayo_ct_fan_beam_360_angles_full/AR/csv/AR_reg_lr0.0001_lambda_gp10/version_0/checkpoints/epoch=099.ckpt` |
| **UAR fan 360 angles (both λ)** | [epoch 049](https://huggingface.co/trung-vt/ddct/tree/main/results/logs/mayo_ct_fan_beam_360_angles_full/UAR/csv/UAR_reg_lr0.0001_gen_lr0.0001_lambda_gp10.0_lambda_vp0.1/version_0/checkpoints/epoch=049.ckpt) | `results/logs/mayo_ct_fan_beam_360_angles_full/UAR/csv/UAR_reg_lr0.0001_gen_lr0.0001_lambda_gp10.0_lambda_vp0.1/version_0/checkpoints/epoch=049.ckpt` |
| **AR parallel 200 angles** | [epoch 029](https://huggingface.co/trung-vt/ddct/tree/main/results/logs/mayo_ct_parallel_beam_200_angles_full/learned/AR/AR_reg_lr0.0001_lambda_gp1/version_1_20250601_good/checkpoints/epoch_epoch=029.ckpt) | `results/logs/mayo_ct_parallel_beam_200_angles_full/learned/AR/AR_reg_lr0.0001_lambda_gp1/version_1_20250601_good/checkpoints/epoch_epoch=029.ckpt` |
| **UAR parallel 200 angles** (learned both $\lambda_\text{primal}$ and $\lambda_\text{dual}$) | [epoch 059](https://huggingface.co/trung-vt/ddct/tree/main/results/logs/mayo_ct_parallel_beam_200_angles_full/learned/UAR/UAR_reg_lr0.0001_gen_lr0.0001_lambda_gp10.0_lambda_vp0.1/version_8_both_learned_lambdas_primal_dual_good_20250611/checkpoints/epoch_epoch=059.ckpt) | `results/logs/mayo_ct_parallel_beam_200_angles_full/learned/UAR/UAR_reg_lr0.0001_gen_lr0.0001_lambda_gp10.0_lambda_vp0.1/version_8_both_learned_lambdas_primal_dual_good_20250611/checkpoints/epoch_epoch=059.ckpt` |
| **UAR parallel 200 angles (single λ)** | [epoch 059](https://huggingface.co/trung-vt/ddct/tree/main/results/logs/mayo_ct_parallel_beam_200_angles_full/learned/UAR/UAR_reg_lr0.0001_gen_lr0.0001_lambda_gp10.0_lambda_vp0.1/version_3_single_fixed_lambda_primal_good_20250610/checkpoints/epoch_epoch=059.ckpt) | `results/logs/mayo_ct_parallel_beam_200_angles_full/learned/UAR/UAR_reg_lr0.0001_gen_lr0.0001_lambda_gp10.0_lambda_vp0.1/version_3_single_fixed_lambda_primal_good_20250610/checkpoints/epoch_epoch=059.ckpt` |

<details>
<summary>Python download snippets</summary>

```python
from huggingface_hub import hf_hub_download

# LPD fan 360°
path = hf_hub_download(
    repo_id="trung-vt/ddct",
    filename="epoch=099.ckpt",
    subfolder=(
        "results/logs/mayo_ct_fan_beam_360_angles_full/learned/"
        "LPD/LPD_lr0.001/version_0/checkpoints"
    ),
)
print(path)
```

<!-- duplicate / adapt for each checkpoint -->
</details>


---

## Model Details

| Item | Description |
|------|-------------|
| **Architecture** | ⬚ e.g. Learned Primal-Dual (LPD), 12 blocks |
| **Input** | ⬚ Sinogram (60 fan-beam angles, 512 × 512) |
| **Output** | ⬚ Reconstructed CT slice |
| **Params** | ⬚ # of parameters |
| **Training data** | Mayo Clinic Low-Dose CT fan-beam subset |
| **Checkpoint(s)** | `epoch=4-step=9999.ckpt`, best SSIM, etc. |

---


## Installation

```bash
pip install huggingface-hub pytorch-lightning                # core deps
pip install ⬚ any-extra-package-your-model-needs