Recompute matched circles in a toy three-torus

Read the chapter on telling a real match from a lucky one first. It derives every formula used below.

Get the three files

Download the script, the saved inputs and the expected output into one empty folder. The script imports only json, math, random and sys. The expected output was produced with Python 3.9.6 and reproduced with Python 3.14.3. The two runs agree in every number and differ only in the recorded version string. A run takes about 20 seconds on a laptop.

From that folder, run:

python3 -I recompute_matched_circles.py tutorial-inputs.json my-output.json

The flag -I keeps Python from loading modules from the current folder or your environment, so the run uses only the standard library.

Read the inputs and their units

The inputs file holds four runs. Each sets the same quantities:

{"boxSide": 1.2, "bumpWidth": 0.08, "bumpCount": 3000, "seed": 86, "noiseRatio": 0.5, "circleSamples": 64, "falsePairTrials": 300, "falsePairRadiiDegrees": [10, 20, 30, 40, 50, 60, 70, 80]}

Lengths are in units of $\chi_{\mathrm{rec}}$, the comoving distance to the last-scattering surface, so the sphere we see has radius 1. The box edge is $L$ = boxSide. Angles are in degrees. Temperatures are in units of the signal's standard deviation on the sphere, so noiseRatio is $\sigma_n/\sigma_s$, the inverse of the signal-to-noise ratio $\xi$.

The sky is a sum of 3000 Gaussian bumps of width $s$ = bumpWidth, at random positions in the box, each with a random Gaussian weight. Every bump is copied onto all lattice images $L\mathbf{n}$ that can reach the sphere, which is what makes the field periodic. Two points a distance $r$ apart are then correlated in proportion to $e^{-r^2/4s^2}$, summed over images. The Lab builds its sky differently, from Fourier modes, so the two give different skies with the same kind of spots. Compare the behaviour, not the digits.

The four runs are wrapped-box with $L = 1.2$, near-the-limit with $L = 1.93$, larger-than-the-view with $L = 2.2$, and noisy-sky, which repeats wrapped-box with noise at twice the signal.

Step 1: check that the box really wraps

Open my-output.json at runs, then wrapped-box. The first number to read is periodicityDifference. It compares the field at a point and at the same point moved by one box edge. It must be exactly zero. A non-zero value means some lattice images were left out of the sum, and every circle score after it would be wrong.

Step 2: score the predicted pairs

The list predictedPairs has one entry for each pair of images $\pm\mathbf{g}$ closer than 2. For $L = 1.2$ there are nine: three with separation $1.2$ and radius $53.13^\circ$, six with separation $1.6971$ and radius $31.948^\circ$. These radii come from $\cos\alpha = |\mathbf{g}|/2$.

For each pair the script samples 64 points on the circle around $\hat{\mathbf{g}}$ and the same 64 physical points moved by $-\mathbf{g}$, which lie on the circle around $-\hat{\mathbf{g}}$. Without noise, statisticAtZeroShift is $1.0$ for all nine, and bestShiftSamples is 0. The two circles carry identical temperatures, point by point. If you see a best shift other than zero here, the two circles were sampled with different starting directions.

The value noisyStatisticAtZeroShift adds independent noise to each circle. Equation 5 of the 1998 paper predicts $\xi^2/(1+\xi^2) = 0.8$ for noise at half the signal, and the output records that prediction as css1998Equation5. The nine noisy values average $0.795$.

Step 3: build the false-pair threshold

A blind search cannot score only the true pairs. It must try every centre and radius, and keep the best rotation of each. The block falsePairs does this for 300 back-to-back pairs on random axes, at radii drawn from 10 to 80 degrees, with the same noise as the noisy true pairs.

Read two numbers. singleShift.standardDeviation is the spread at a fixed rotation: $0.197$, wider than the independent-sample value $1/\sqrt{65} = 0.124$ that the output stores next to it. Neighbouring samples share spots, so the circle carries fewer independent values than 64. bestOverShifts.percentile99 is the false level that 1 percent of random pairs exceed after choosing their best rotation: $0.674$. With 300 trials it is the fourth-largest value.

In wrapped-box every true pair clears the false level. That is a detection in this toy sky.

Four ways the test fails

A box larger than the view. In larger-than-the-view the list predictedPairs is empty, because no image is closer than 2. Yet the best false pair still scores $0.771$. A search that reported its top score without a threshold would announce circles in a sky that has none. This is the unidentifiable limit: the circle test gives the same answer here as for infinite flat space.

Noise that drowns the match. In noisy-sky the prediction falls to $0.2$ at the correct rotation. After choosing the best rotation the true pairs score $0.27$ to $0.51$, and only one of nine exceeds the false level $0.431$. The topology is still there, but this map cannot show it.

Small circles near the limit. In near-the-limit the circles have radius $15.2^\circ$. Their samples are packed closely and share spots, so the false level rises to $0.745$ and one of the three true pairs, at $0.725$, falls below it. This is the same mechanism that sets the smallest circle radius in the Planck search.

A wrong orientation. The value mirroredBestStatistic compares each true circle with its partner read in the opposite direction. It is not a match, yet after choosing the best rotation it scores $0.47$ to $0.89$. Two traces of a smooth sky can line up well over part of a circle by accident. So the search must fix the orientation the topology predicts, and judge the best score against false pairs searched the same way.

Errors and what the numbers can support

The scores are rounded to four decimals. The 1 percent false level comes from the fourth-largest of 300 values, so its own uncertainty is a few hundredths: with noise at half the signal, the three runs give $0.674$, $0.708$ and $0.745$. A real analysis uses far more simulations and the exact pipeline of the data. Planck used 300 full simulations of its maps.

The noise model adds independent Gaussian noise to every sample. Real maps have noise that varies across the sky, regions removed by a Galactic mask, and contributions from gas velocity and from changing gravitational potentials that differ between the two paths. None of those is in this script, so its results describe how the method behaves.

Compare with the Lab

In the Lab, choose a preset, then use the export button in the data row. The exported record lists the predicted pairs, their radii and the box-axis score with its chance level. Check that the pair count and radii agree exactly with predictedPairs for the same box edge. The scores will differ in detail because the two skies differ, but true pairs should sit near 1 without noise and sink towards the chance band as noise grows.

A checklist for any circle search

1. Confirm the periodicity of the simulated sky before scoring anything.
2. Write down the predicted radii and centres from the geometry before looking at scores.
3. Score false pairs with the same sampling, noise and search freedom as the real search.
4. Quote the false level with the number of simulations behind it.
5. Test small circles separately, because their false level is higher.
6. Fix the orientation the topology predicts before taking the best rotation.

Sources: Cornish, Spergel and Starkman 1998, equations 5, 6 and 8, Planck 2015 results XVIII, sections 4.2 and 5.1.1, COMPACT collaboration preprint on noise sources for the circle signal.

Export the Lab record and compare its circle scores with your script output.