Switch to TD-pos-only as default recommendation in docs

README.md

@@ -25,7 +25,31 @@ uv pip install .[aiida]
 
 ### Model checkpoints for retrained versions of MatterGen
 
-Model checkpoints for the retrained versions of MatterGen used in our work can be downloaded from [Hugging Face](https://huggingface.co/t-reents/XtalPaint). Currently, the repository contains the `pos-only` and `TD-pos-only` models discussed in the paper.
+Model checkpoints for the retrained versions of MatterGen used in our work are hosted on [Hugging Face](https://huggingface.co/t-reents/XtalPaint). Currently, the repository contains the `pos-only` and `TD-pos-only` models discussed in the paper.
+
+> [!IMPORTANT]
+> **The example below uses the `TD-pos-only` model — the core model of XtalPaint — which we recommend for accurate inpainting**, together with the time-dependent (`TD`) predictor-corrector. See the [documentation](https://psi-lms.github.io/XtalPaint/configuration/) for the available model and predictor-corrector combinations.
+
+Just like MatterGen's own checkpoints, the XtalPaint models are **downloaded automatically** the first time you select them by name — simply set `pretrained_name` to `"TD-pos-only"` (or `"pos-only"`):
+
+```python
+config = InpaintingConfig(
+    pretrained_name="TD-pos-only",   # auto-downloaded & cached from Hugging Face
+    predictor_corrector="TD",        # time-dependent predictor-corrector
+    N_steps=50,
+    coordinates_snr=0.2,
+    n_corrector_steps=1,
+    batch_size=100,
+)
+```
+
+You can also download a checkpoint explicitly and point `model_path` at it:
+
+```python
+from xtalpaint.models import download_pretrained_model
+
+model_path = download_pretrained_model("TD-pos-only")
+```
 
 ## Example
 
@@ -65,10 +89,13 @@ from xtalpaint.inpainting.inpainting_process import (
     run_inpainting_pipeline,
 )
 
-# Parameters for the inpainting, please adjust to reasonable values
+# Parameters for the inpainting, please adjust to reasonable values.
+# This uses our recommended `TD-pos-only` model, which is downloaded
+# automatically from Hugging Face the first time it is selected. See the
+# documentation for the available model/predictor-corrector combinations.
 config = InpaintingConfig(
-    pretrained_name="mattergen_base",
-    predictor_corrector="baseline",
+    pretrained_name="TD-pos-only",
+    predictor_corrector="TD",
     N_steps=50,
     coordinates_snr=0.2,
     n_corrector_steps=1,

docs/configuration.md

@@ -111,11 +111,11 @@ The core diffusion stage. All sampling parameters live in one flat block.
 ```python
 inpainting=InpaintingConfig(
     # Model — provide exactly one of these:
-    pretrained_name="mattergen_base",   # use a bundled pretrained checkpoint
-    # model_path="/path/to/checkpoint", # or point to a local file
+    pretrained_name="TD-pos-only",      # XtalPaint model (auto-downloaded) or a MatterGen checkpoint
+    # model_path="/path/to/model_dir",  # or point to a local checkpoint directory
 
     # Sampling
-    predictor_corrector="baseline",     # see supported keys below
+    predictor_corrector="TD",           # see supported combinations below
     N_steps=5,
     coordinates_snr=0.2,
     n_corrector_steps=1,
@@ -128,7 +128,27 @@ inpainting=InpaintingConfig(
 )
 ```
 
-**Supported `predictor_corrector` values:**
+!!! tip "Recommended model: `TD-pos-only`"
+    `pretrained_name` accepts the XtalPaint models hosted on
+    [Hugging Face](https://huggingface.co/t-reents/XtalPaint) (`TD-pos-only`,
+    `pos-only`) as well as MatterGen's own checkpoints. The XtalPaint models are
+    downloaded automatically and cached the first time they are selected. For
+    accurate inpainting we **recommend the `TD-pos-only` model** — the core
+    model of XtalPaint — with the time-dependent (`TD`) predictor-corrector.
+
+    Alternatively, download a checkpoint explicitly and pass it as `model_path`:
+
+    ```python
+    from xtalpaint.models import download_pretrained_model
+
+    model_path = download_pretrained_model("TD-pos-only")
+    ```
+
+    Selecting `predictor_corrector="TD"` without the `TD-pos-only` model (or
+    pointing `model_path` at a checkpoint that has not been downloaded) raises
+    an error with these instructions.
+
+**Supported `predictor_corrector` values** — the `TD` variant requires the `TD-pos-only` model; the others are used with the `pos-only` model or a MatterGen checkpoint:
 
 | Key | Description |
 |---|---|
@@ -137,7 +157,7 @@ inpainting=InpaintingConfig(
 | `baseline-store-scores` | Records score function outputs |
 | `repaint-v1` | RePaint resampling (legacy) |
 | `repaint-v2` | RePaint resampling (v2) |
-| `TD` | Time-dependent (TD-Paint) variant |
+| `TD` | Time-dependent (TD-Paint) variant — requires the `TD-pos-only` model |
 
 !!! note "Repaint variants"
     When using `repaint-v1` or `repaint-v2`, you must also set `n_resample_steps` and `jump_length`:
@@ -245,8 +265,8 @@ from xtalpaint.utils.relaxation_utils import relax_structures
 config = XtalPaintConfig(
     candidate_generation=CandidateGenerationConfig(n_inp=2, element="H"),
     inpainting=InpaintingConfig(
-        model_path="/path/to/checkpoint.ckpt",
-        predictor_corrector="baseline",
+        pretrained_name="TD-pos-only",   # auto-downloaded from Hugging Face
+        predictor_corrector="TD",
         N_steps=5,
         coordinates_snr=0.2,
         n_corrector_steps=1,
@@ -376,8 +396,8 @@ wg.submit()
             element="H",
         ),
         inpainting=InpaintingConfig(
-            pretrained_name="mattergen_base",
-            predictor_corrector="baseline",
+            pretrained_name="TD-pos-only",
+            predictor_corrector="TD",
             N_steps=5,
             coordinates_snr=0.2,
             n_corrector_steps=1,
@@ -437,8 +457,8 @@ wg.submit()
             element="H",
         ),
         inpainting=InpaintingConfig(
-            pretrained_name="mattergen_base",
-            predictor_corrector="baseline",
+            pretrained_name="TD-pos-only",
+            predictor_corrector="TD",
             N_steps=5,
             coordinates_snr=0.2,
             n_corrector_steps=1,

docs/index.md

@@ -39,7 +39,24 @@ uv pip install .[aiida]
 
 ### Model checkpoints for retrained versions of MatterGen
 
-Model checkpoints for the retrained versions of MatterGen used in our work can be downloaded from [Hugging Face](https://huggingface.co/t-reents/XtalPaint). Currently, the repository contains the `pos-only` and `TD-pos-only` models discussed in the paper.
+Model checkpoints for the retrained versions of MatterGen used in our work are hosted on [Hugging Face](https://huggingface.co/t-reents/XtalPaint). Currently, the repository contains the `pos-only` and `TD-pos-only` models discussed in the paper.
+
+!!! tip "Recommended model: `TD-pos-only`"
+    The examples use the **retrained `TD-pos-only` model** — the core model of XtalPaint — together with the time-dependent (`TD`) predictor-corrector, which we recommend for accurate inpainting. See the [Configuration Guide](configuration.md) for the available model and predictor-corrector combinations.
+
+    Like MatterGen's own checkpoints, the XtalPaint models are downloaded automatically the first time you select them by name:
+
+    ```python
+    InpaintingConfig(
+        pretrained_name="TD-pos-only",   # auto-downloaded & cached from Hugging Face
+        predictor_corrector="TD",
+        ...,
+    )
+    ```
+
+    You can also download a checkpoint explicitly with
+    `xtalpaint.models.download_pretrained_model("TD-pos-only")` and pass the
+    returned path as `model_path`.
 
 ## Acknowledgements
 

examples/README.md

@@ -3,8 +3,9 @@
 
 ## Without using AiiDA
 
-To be added.
+The `running-wo-AiiDA.ipynb` notebook shows how to use the XtalPaint package without AiiDA. It is a good starting point for users who want to get familiar with the package and its functionality. All the methods that are otherwise wrapped in the AiiDA WorkGraphs are just executed serially in this notebook.
+The latest symmetry refinement and uniqueness analysis steps are not included. However, they are not specific to this package and can easily be integrated by the user if needed.
 
 ## Using AiiDA
 
-To be added.
+The `running-with-AiiDA.ipynb` notebook shows how to use the XtalPaint package with AiiDA. The advantage of using AiiDA is that it keeps track of the data and also enables remote submission to different HPC clusters from your local machine. Moreover, WorkGraphs are already predefined with several optional steps.