---
title: "Ouro DFT now holds gadolinium's 4f shell: what was wrong, and how we built a basis that fixes it"
description: "Rare-earth runs on Ouro DFT converged cleanly and were wrong: hcp Gd came out at 0.06 μB instead of 7.6. The pseudopotential was fine; the orbital basis had no room for 4f electrons. We generated a matched basis, validated it against plane waves, and Gd now gives 7.71 μB, 2.65 T, and the right ferri"
url: "https://ouro.foundation/posts/mmoderwell/ouro-dft-now-holds-gadoliniums-4f-shell-what-was-wrong-and-how-we-built-a-basis-that-fixes-it"
id: "01a0ee84-5c55-782a-b785-0112ea1f6662"
type: "post"
---

# Ouro DFT now holds gadolinium's 4f shell: what was wrong, and how we built a basis that fixes it

Post by @mmoderwell in #permanent-magnets (all) · 2026-09-29

- Asset id: `01a0ee84-5c55-782a-b785-0112ea1f6662`
- Page: https://ouro.foundation/posts/mmoderwell/ouro-dft-now-holds-gadoliniums-4f-shell-what-was-wrong-and-how-we-built-a-basis-that-fixes-it

[Ouro DFT (ABACUS)](https://ouro.foundation/services/mmoderwell/ouro-dft-abacus) could run rare-earth structures, and the runs converged. They were also wrong. This post covers how we found that, why no off-the-shelf fix existed, what it took to build one, and where rare-earth DFT on Ouro stands now. Gadolinium is done. Neodymium and samarium are in progress.

## The symptom

While following up the [gadolinium literature check](https://ouro.foundation/posts/mmoderwell/gadoliniums-big-moment-doesnt-make-a-permanent-magnet-a-literature-check), we ran [Magnetic moments](https://ouro.foundation/routes/mmoderwell/magnetic-moments) on hcp Gd ([mp-155](https://ouro.foundation/files/mmoderwell/gd-metal-mp-155-p6-3-mmc)). It converged normally and reported **0.055 μB per Gd**. The measured value is 7.55–7.63 μB. The Mulliken breakdown showed why: −0.05 electrons in the 4f channel and 9.48 in 5d. Gd has seven 4f electrons and about one 5d electron.

## The cause: a pseudopotential and a basis that don't belong together

ABACUS runs in a localized basis of numerical atomic orbitals, and each orbital set is generated for one specific pseudopotential. The service paired:

- **Pseudopotential:** the jingslaw PseudoDojo fully relativistic lanthanide set, with **4f in valence** (18 electrons for Gd).
- **Orbitals:** ABACUS's `Dojo-NC-SR_La-Series`. We checked the upstream generation inputs: they were built from a scalar-relativistic pseudopotential with **4f frozen in the core**. Their one f function is a polarization shell, not a 4f orbital.

A basis with no 4f orbital cannot hold 4f electrons, so SCF pushed them into 5d and the moment collapsed. Nothing crashed and nothing warned. Every lanthanide from Ce to Yb was affected, so the Nd and Sm moments were wrong in the same way. The first thing we shipped was a guard: until a matched basis exists, the service refuses lanthanides with an explanation ([example](https://ouro.foundation/actions/01a0eb35-41c3-7322-95ea-bf3dd00206e8)).

## Why this isn't a download

The ABACUS ecosystem only distributes lanthanide orbitals with 4f in core: the La-series set above, and the tested APNS bundle, whose lanthanide file is literally named `lanthanides-f--core`. The 4f-in-core approach is standard and useful, but it has no 4f moment and no 4f anisotropy, which are the two things rare-earth magnets are made of. So we generated our own basis with [ABACUS-CSW-NAO](https://github.com/MCresearch/ABACUS-CSW-NAO). It fits contracted orbitals to reference calculations of Gd dimers at six bond lengths (1.80–5.00 Å) plus the isolated atom, all using the same pseudopotential.

## What we learned getting it right

**1. Converge the primitive basis before fitting anything.** CSW-NAO contracts a large set of primitive spherical waves, and no fit can beat its primitive. We started from the upstream Nd example's 60 Ry primitive cutoff. The first basis held the moment at one volume but had no E(V) minimum and sat 131 eV/atom above plane waves. The isolated atom showed the cause immediately:

| Isolated Gd atom | Energy (eV) | vs plane waves |
| ---------------- | ----------- | -------------- |
| Plane waves, 100 / 150 / 200 Ry | −4837.52 / −4851.38 / −4851.45 | — |
| Primitive, 60 Ry | −4701.96 | +135.6 eV |
| Primitive, 100 Ry | −4839.85 | +11.5 eV |
| Primitive, 120 Ry | −4848.30 | +3.1 eV |
| **Primitive, 150 Ry** | **−4851.15** | **+0.30 eV** |

Gd's 4f shell is compact, and a coarse primitive can't resolve it:

> Embedded dataset: [Gd basis validation: plane waves vs atomic orbitals, same PP](https://ouro.foundation/datasets/mmoderwell/gd-basis-validation-plane-waves-vs-atomic-orbitals-same-pp)

**2. The pseudopotential itself needs 150 Ry.** The plane-wave column shows it: the atom moves 13.9 eV from 100 to 150 Ry and 0.06 eV from 150 to 200. The service default of 100 Ry is fine for 3d metals but not here. Lanthanide cells now default to 150 Ry, and explicit lower values are refused.

**3. The small basis isn't enough.** Checked against plane waves with the same pseudopotential on hcp Gd across a ±6% lattice range:

| hcp Gd, 150 Ry | V₀ (ų/atom) | B₀ (GPa) | Moment at V₀ | Worst moment error |
| -------------- | ------------ | -------- | ------------ | ------------------ |
| Plane waves (reference) | 32.99 | 34.6 | 7.73 μB | — |
| **4s3p3d3f (shipped)** | **32.63 (−1.1%)** | **34.7 (+0.3%)** | **7.71 μB** | **0.09 μB** |
| 3s2p2d2f (rejected) | 33.29 (+0.9%) | 25.2 (−27%) | 7.41 μB | 0.38 μB |

The plane-wave reference lands on experiment (V₀ ≈ 33.1 ų). The shipped basis carries about 7.4 f electrons with about 7.1 μB of 4f moment. The energy offset to plane waves is 0.18–0.21 eV/atom and drifts about 5 meV/atom rms near V₀, which is normal for an atomic-orbital basis. With each curve shifted to its own minimum, the shipped basis follows the plane-wave E(V) and the rejected one is visibly too soft:

> Embedded dataset: [Gd basis validation: plane waves vs atomic orbitals, same PP](https://ouro.foundation/datasets/mmoderwell/gd-basis-validation-plane-waves-vs-atomic-orbitals-same-pp)

The moment tells the same story at every volume (the dataset has every number, including the 4f occupations and the rejected 60 Ry fit):

> Embedded dataset: [Gd basis validation: plane waves vs atomic orbitals, same PP](https://ouro.foundation/datasets/mmoderwell/gd-basis-validation-plane-waves-vs-atomic-orbitals-same-pp)

## Results on the live service

Same route, same CIF as the failing run ([run](https://ouro.foundation/actions/01a0ee72-1afc-70f3-82ac-3cdcae9e3b35)):

| hcp Gd | Before | Now | Experiment |
| ------ | ------ | --- | ---------- |
| Moment per Gd | 0.055 μB | **7.71 μB** | 7.55–7.63 μB |
| μ₀Mₛ | 0.019 T | **2.65 T** | 2.66 T |
| 4f electrons | −0.05 | **7.38** | 7 |

**GdCo₅ comes out ferrimagnetic.** Heavy rare earths align antiparallel to Fe and Co, and this is exactly where [Prophet fails](https://ouro.foundation/posts/mmoderwell/on-rare-earth-magnets-prophet-models-the-iron-and-cobalt-not-the-rare-earth): it couples Gd parallel to Co and overstates the magnetization about tenfold. Running [GdCo₅](https://ouro.foundation/files/mmoderwell/gdco5-mp-1077071-p6-mmm) from both seeds at identical settings:

| GdCo₅ | Ferromagnetic seed ([run](https://ouro.foundation/actions/01a0ee77-f911-794e-a940-2d20fbb6ede0)) | Ferrimagnetic seed ([run](https://ouro.foundation/actions/01a0ee77-ffbb-774b-a3f9-8629d6f1e23a)) |
| ----- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Energy | −25676.208 eV | **−25676.439 eV (0.23 eV/f.u. lower)** |
| Gd / Co moments | +6.14 / +1.60 μB | **−7.87 / +1.59 μB** |
| Net | 14.2 μB/f.u. | 0.08 μB/f.u. |

The order is right. The net moment is lower than the measured ~1.7 μB/f.u., and we know why: these runs are collinear and spin-only. Cobalt carries an orbital moment of about 0.2–0.3 μB per atom in experiment, roughly 1–1.5 μB per formula unit in total. Capturing it needs spin–orbit coupling.

## What this means if you run rare-earth DFT on Ouro

- **Gd is supported.** Other lanthanides are refused until each has a validated basis. Nd and Sm are being generated now.
- **Gd cells run at 150 Ry by default**, with a basis of 49 orbitals per Gd. Expect them to cost more than an equivalent 3d cell.
- **Collinear, plain PBE only for now.** No Hubbard U on the 4f shell yet, and 4f magnetocrystalline anisotropy isn't validated. Gd has almost no 4f anisotropy anyway (L = 0), but Nd and Sm are the whole point, and they'll need spin–orbit coupling, DFT+U and control over the 4f occupation. That's the next phase.
- **Cached results can't mix bases.** Lanthanide cache keys now carry a basis-library revision, so the old 0.06 μB result can never be served again.

## Notes for anyone generating bases

- Run the reference geometries **in parallel**. CSW-NAO runs them one after another. Laying out the folders first, running each geometry in its own container and then fitting cut wall time from 3–5 hours to about 30 minutes, plus about an hour for the fit.
- Pin threads to 1 per MPI rank (`OMP_NUM_THREADS`, `OPENBLAS_NUM_THREADS`). Modal sets `OMP_NUM_THREADS` to the core count at runtime, and 32 ranks × 32 threads ran about 12× slower.
- CSW-NAO needs ABACUS ≥3.7.5 and <3.9.0.6. ABACUS 3.9 renamed `OUT.*/kpoints` to `KPT.info`, which CSW-NAO doesn't read. The layout is identical, so a one-line fallback fixes it.
- Keep scratch work on a persistent volume and only resume geometries whose SCF actually converged. Our jobs were preempted five times, and a half-written folder looks finished to a naive resume check.

The generation and validation tools (`orbgen_app.py`, `validate_basis.py`) are in the ouro-dft repo. The shipped orbitals sit next to their generation inputs, spillage curves and validation data, so the next element follows the same recipe.

## Assets in this post

- [Gd basis validation: plane waves vs atomic orbitals, same PP](https://ouro.foundation/datasets/mmoderwell/gd-basis-validation-plane-waves-vs-atomic-orbitals-same-pp) (dataset, id `01a0ee83-95e7-7e69-8fd8-ef10e540886c`)
- [Ouro DFT (ABACUS)](https://ouro.foundation/services/mmoderwell/ouro-dft-abacus) (service, id `accd2d6f-baa1-4094-86ef-76057444b0a3`)
- [Gadolinium's big moment doesn't make a permanent magnet: a literature check](https://ouro.foundation/posts/mmoderwell/gadoliniums-big-moment-doesnt-make-a-permanent-magnet-a-literature-check) (post, id `01a0ea50-029c-7c01-8345-dfd8fe5ece38`)
- [Magnetic moments](https://ouro.foundation/routes/mmoderwell/magnetic-moments) (route, id `0a23817e-af47-485a-9c56-5f2df0178b80`)
- [Gd metal (mp-155, P6_3/mmc)](https://ouro.foundation/files/mmoderwell/gd-metal-mp-155-p6-3-mmc) (file, id `0dbec8bc-b711-4e64-b419-86d9bfe03e69`)
- [On rare-earth magnets, Prophet models the iron and cobalt, not the rare earth](https://ouro.foundation/posts/mmoderwell/on-rare-earth-magnets-prophet-models-the-iron-and-cobalt-not-the-rare-earth) (post, id `01a0d45e-4386-7e3d-b10b-087d7e6f21d4`)
- [GdCo5 (mp-1077071, P6/mmm)](https://ouro.foundation/files/mmoderwell/gdco5-mp-1077071-p6-mmm) (file, id `890ddfc5-4e0e-45d7-8657-56b4f379f549`)