Can Claude organize old research code? A black hole test

Some years ago, I wrote code to calculate black-hole shadows inn a scientific paper. The code worked. But it was not easy to read: dozens of files, thousands of lines, many copies of the same functions, almost no comments, and a lot of old code inside comments.

So I asked a simple question: if I give this code to Claude, can Claude organize it again?

What does the code do?

A black hole does not let light escape. When you look at a black hole, you see a dark area: what is called the Black Hole shadow.

The black hole also bends the light from the stars behind it. This effect is gravitational lensing. The sky around the shadow looks stretched and folded.

The code calculates and ray-traces these images. The result of the calculations can be as follows:

the ray falls into the black hole,
the ray hits a disk of matter around the black hole, or
the ray goes to the celestial sphere.

The code considers two types of black holes:

A black hole that does not rotate (Schwarzschild), with or without a thin disk of matter around it.
A black hole that rotates (Kerr).

The image at the top shows a Kerr black hole that turns quickly (spin a = 0.9). The background is a photo of the center of the Milky Way, and the black hole bends that photo.

The initial idea

The test was simple. I gave Claude Code the original code and one prompt. I did not explain the physics. I told Claude what was wrong with the code and what I wanted.

The prompt described the code like this:

Characteristics of the code: desorganized, have duplicated code, not commented

It gave these goals:

Analyze the code and make a plan. One agent (the architect) makes the plan. Other agents make the changes.
Create a uv project for the code.
Add comments where they are missing.
Remove duplicated code.

It also told Claude what must not change. The slow parts of the code use numba to run fast:

The compute heavy parts of the code are decorated with numba functions. This behavior should be maintained

Thus, Claude had only the code in the folder. The test shows if Claude can find the structure and the physics from the code alone.

Results form the first iteration

The first pass removed approximately 4,900 lines. It put the physics of each black hole type in its own module. It put the plots in a different module. The fast numba functions stayed, and both modes (black hole only, and black hole with disk) stayed.

What I learned

Claude can read old scientific code. It found the structure in the code, without help on the physics.
A clear prompt is important. Tell Claude what is wrong. Tell Claude what must not change.
Use small tests. A full run takes a long time. The prompt told Claude to test with small cases only.
Check the physics. Clean code is not enough. The validation tests compare the results with the theory.

More information

For a longer description of the code, see the project page: Black Hole Shadows.

The code is open source on GitHub. The physics is in the paper on arXiv.

Nelson Eiró

Senior Data Engineer

Nelson Eiró