Build Your Own Shell Model

A shell model calculation answers a blunt question: given a nucleus, what are its energy levels — exactly? The trick that makes an exact answer possible is brutal economy. Declare the closed inner core of the nucleus frozen (for ¹⁸O, the 16 particles of the ¹⁶O core never move), keep only the few valence particles left over, confine them to a handful of orbitals — the quantum states a single particle can occupy — just above the core. The confinement is physical, not convenient: below, the core's filled orbitals are barred by the Pauli principle; above, the next shell sits a magic-number energy gap away and barely mixes in. Their interactions come from a small table of numbers fit directly to experimental data — and the fit absorbs what little the confinement leaves out. Inside that small world, nothing is approximated: every allowed configuration is enumerated and the Hamiltonian — the matrix of energies and couplings between configurations — is diagonalized in full. This approach is called configuration interaction (CI): the answer is exact within the chosen space, and the art is choosing the space.

It is the opposite bargain from the mean-field tutorial: there, every nucleon participates but each feels only the average of the others; here, almost every nucleon is frozen but the survivors are treated with every correlation intact. The two tutorials bracket how nuclear structure is actually computed.

Six chapters, each a complete Python program (numpy and scipy only) that runs in seconds and prints its own checks. The destination is real: the final program reproduces the validated mini-CI, whose ²⁴Mg spectrum matches two independent production codes run on this same machine.

1. Step 1 — The valence space Freeze the core, keep a few particles in a few orbitals — 12 seats, and 18O is a 14-state problem.
2. Step 2 — The basis as bitstrings One integer per many-body state, one bit per seat. Occupation, creation, and signs become machine instructions.
3. Step 3 — Read the interaction The whole force is 63 numbers in a text file, fit to experiment — plus a mass scaling with a story.
4. Step 4 — One matrix element, by hand Fermionic signs as bit counts, and the pair-swap phase measured numerically — including what breaks without it.
5. Step 5 — 18O, complete A 14 × 14 matrix, diagonalized exactly. Every level matches a production code to every printed digit.
6. Step 6 — 24Mg at scale 28,503 determinants, sparse storage, Lanczos — and agreement with two independent production codes.

The production codes this tutorial learned from

The mini-CI was built by studying four real shell-model codes, each of which answers "where do you spend memory versus compute?" differently: CENS (Engeland & Hjorth-Jensen) stores the basis as 64-bit bitstrings and runs Lanczos — the representation this tutorial copies. cosmo (Volya) prunes impossible branches while enumerating the basis — the idea step 6 needs. OpenFCI (Kvaal) organizes the two-body machinery around "which orbitals differ, with what sign" — the bookkeeping of step 4. And BIGSTICK (Johnson) never stores the Hamiltonian at all, reconstituting every element from factorized lookup tables — the design that reaches dimensions the others cannot. Steps 5 and 6 validate against cosmo and BIGSTICK directly.

Start with Step 1 ▸