Skip to content

Add fine-tuning guidance and a MACE fine-tuning tutorial - #1707

Open
vue1999 wants to merge 1 commit into
docsfrom
finetuning-guidance-tutorial
Open

Add fine-tuning guidance and a MACE fine-tuning tutorial#1707
vue1999 wants to merge 1 commit into
docsfrom
finetuning-guidance-tutorial

Conversation

@vue1999

@vue1999 vue1999 commented Sep 1, 2026

Copy link
Copy Markdown
Collaborator

This PR adds practical guidance for fine-tuning MACE foundation models and a
worked tutorial based on the results from Fine-tuning MLIP foundation models:
strategies for accuracy and transferability
.

  • adds a new Fine-tuning Guidance page covering:
    • foundation-model selection;
    • atomic reference energies (E0s);
    • method-specific optimiser settings;
    • choosing between naive fine-tuning, layer freezing, LoRA and replay;
    • validation beyond held-out energy and force errors;
  • adds the Reliable fine-tuning of MACE foundation models notebook;
  • adds the fine-tuning-method schematic to the guide and notebook;
  • updates the main fine-tuning examples with safer defaults;
  • adds the new guide and tutorial to the documentation navigation;
  • documents MACE's LoRA implementation and cites the original LoRA work, ELoRA,
    and the MACE fine-tuning paper;

Tutorial

The default notebook path:

  • downloads less than 10 MB of pinned supplementary data;
  • runs its diagnostic plots on CPU;
  • demonstrates how incorrect E0s can distort interaction-energy curves;
  • provides commands for naive, layer-freeze, LoRA and pseudolabel-replay
    fine-tuning;
  • shows method-specific learning-rate behaviour;
  • illustrates why changing loss weights during Stage Two can destabilise
    fine-tuning;
  • leaves GPU training as an explicit opt-in.

The notebook is version-controlled under docs/examples and opened in Colab
through GitHub.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant