---
name: unit-distance-artifacts
type: reference
title: "Unit Distance Research — Scripts and Tools"
description: "Complete inventory of the 18 PEP 723 scripts used in the unit distance research, organized by purpose."
tags: [unit-distance, scripts, tools, PEP723, uv]
timestamp: 2026-07-20
---

# Unit Distance Research — Scripts and Tools

## Overview

The unit distance research used 18 PEP 723 Python scripts for computation, verification, and analysis. All scripts are located in the `scripts/` directory of the `unit-distance-csfita` repository and are executed via `uv run scripts/<name>.py`.

The scripts fall into five categories: optimizers (hypothesis-specific), prime sieves, PDF readers, analysis tools, and verification scripts.

---

## Technical Specifications

- **Package Manager:** `uv` (NOT pip)
- **Script Standard:** PEP 723 inline metadata
- **Script Location:** `scripts/` directory only
- **Execution:** `uv run scripts/<name>.py`
- **Hardware:** Apple M3 Pro, 24GB Unified VRAM
- **Acceleration:** NumPy vectorized, Apple MLX, Metal tensors
- **Python:** Latest stable via uv

---

## Optimizers (Hypothesis-Specific)

These scripts verify and optimize specific hypotheses. Each script implements the full mathematical construction for one hypothesis.

### H15: Central Imaginary Quadratic CM Tower

**Script:** `optimize_central_cm_tower.py`
**Command:** `uv run scripts/optimize_central_cm_tower.py`
**Purpose:** Verifies the H15 construction -- the central 2-tower over an imaginary quadratic base field achieving delta = 0.013769.
**Dependencies:** numpy, scipy
**What it does:**
- Constructs the base field F = Q(sqrt(-D)) with D = product of 151 primes
- Computes the 2-class rank d = 150
- Calculates the GS capacity: 2t = floor(150^2/4) - 150 - 1 = 5474
- Verifies the central tower restriction (complex conjugation commutes with Gal)
- Computes the exponent delta = 1477.21 / 107287.87 = 0.013769
**Created:** 2026-07-04 (commit 3463ed1)
**Supports:** H15 (Central CM Tower)

### H16: Multi-Quadratic CM Degree 16

**Script:** `optimize_multiquadratic_degree16.py`
**Command:** `uv run scripts/optimize_multiquadratic_degree16.py`
**Purpose:** Verifies the H16 construction -- the degree 16 multi-quadratic CM field achieving delta = 0.019603.
**Dependencies:** numpy, scipy
**What it does:**
- Constructs the base field F = Q(sqrt(-2), sqrt(3), sqrt(5), sqrt(7))
- Computes the 2-class rank d = 2^4 - 1 = 15
- Identifies the 17 unramified split primes via quadratic reciprocity
- Verifies the GS inequality: 22 + 34 = 56 < 56.25
- Computes the exponent delta = 9.1099 / 464.7310 = 0.019603
**Created:** 2026-07-04 (commit 3463ed1)
**Supports:** H16 (Multi-Quadratic CM16)

---

## Prime Sieves

These scripts identify and verify primes that satisfy specific splitting conditions.

### H16 Prime Verification

**Script:** `fix_h16_primes.py`
**Command:** `uv run scripts/fix_h16_primes.py`
**Purpose:** Calculates the exact unramified split primes in the H16 base field F = Q(sqrt(-2), sqrt(3), sqrt(5), sqrt(7)).
**Dependencies:** sympy
**What it does:**
- For each candidate prime q, checks if q splits completely in F
- Verifies (-2/q) = (3/q) = (5/q) = (7/q) = 1 via Legendre symbols
- Excludes ramified primes {2, 3, 5, 7}
- Returns the first 17 unramified split primes: {59, 131, 251, ..., 2411}
**Created:** 2026-07-04 (commit e88c570)
**Supports:** H16 (Multi-Quadratic CM16)

### Base Field Prime Sieve

**Script:** `engineer_p_base.py`
**Command:** `uv run scripts/engineer_p_base.py`
**Purpose:** High-scale sieve script verifying Dirichlet density bounds for prime selection.
**Dependencies:** numpy, sympy
**What it does:**
- Computes Dirichlet density of primes splitting in multi-quadratic fields
- Verifies density bounds for various base field configurations
- Helps identify optimal prime sets for GS inequality satisfaction
**Created:** 2026-07-04 (commit e88c570)
**Supports:** H15, H16 (prime selection)

---

## PDF Readers

These scripts extract and analyze content from the OpenAI PDFs. They are read-only tools that do not perform mathematical computation.

### Chain-of-Thought Keyword Search

**Script:** `search_cot_ideas.py`
**Command:** `uv run scripts/search_cot_ideas.py`
**Purpose:** Searches the OpenAI chain-of-thought PDF for keywords related to the proof structure.
**Dependencies:** none
**What it does:**
- Reads `wiki/raw/unit-distance-cot.txt` (extracted from the PDF)
- Searches for keywords: "Golod", "Shafarevich", "class number", "exponent", "delta", "epsilon", "Minkowski", "bounded window", "polydisc"
- Reports frequency and locations of each keyword
**Created:** 2026-07-03 (early session)
**Supports:** H1-H3 (initial exploration)

### Remarks Lemma Extraction

**Script:** `read_middle_remarks.py`
**Command:** `uv run scripts/read_middle_remarks.py`
**Purpose:** Extracts the middle section of the Remarks PDF, focusing on Lemma 2.1 and Lemma 2.2.
**Dependencies:** none
**What it does:**
- Reads `wiki/raw/unit-distance-remarks.txt`
- Extracts text around Lemma 2.1 and Lemma 2.2
- Prints the relevant mathematical content
**Created:** 2026-07-03 (early session)
**Supports:** H1-H4 (Lemma 2.2 analysis)

### Proposition 2.3 Reader

**Script:** `read_prop_2_3.py`
**Command:** `uv run scripts/read_prop_2_3.py`
**Purpose:** Extracts Proposition 2.3 from the Remarks PDF.
**Dependencies:** none
**What it does:**
- Reads `wiki/raw/unit-distance-remarks.txt`
- Locates and extracts Proposition 2.3
- Prints the proposition text
**Created:** 2026-07-03 (early session)
**Supports:** H1-H4 (proposition analysis)

### Remarks 2.3 Reader

**Script:** `read_remarks_2_3.py`
**Command:** `uv run scripts/read_remarks_2_3.py`
**Purpose:** Extracts the remarks following Proposition 2.3.
**Dependencies:** none
**What it does:**
- Reads `wiki/raw/unit-distance-remarks.txt`
- Locates the remarks after Proposition 2.3
- Prints the remark text
**Created:** 2026-07-03 (early session)
**Supports:** H1-H4 (remark analysis)

### Sawin-Tsimerman Reader

**Script:** `read_sawin_tsimerman.py`
**Command:** `uv run scripts/read_sawin_tsimerman.py`
**Purpose:** Extracts references to Sawin and Tsimerman from the OpenAI materials.
**Dependencies:** none
**What it does:**
- Reads the OpenAI PDF text files
- Searches for mentions of "Sawin" and "Tsimerman"
- Reports context around each mention
**Created:** 2026-07-03 (early session)
**Supports:** Anti-contamination protocol (identifying external references)

### Section 7 Reader

**Script:** `read_section_7.py`
**Command:** `uv run scripts/read_section_7.py`
**Purpose:** Extracts Section 7 from the OpenAI proof PDF.
**Dependencies:** none
**What it does:**
- Reads `wiki/raw/unit-distance-proof.txt`
- Locates and extracts Section 7
- Prints the section text
**Created:** 2026-07-03 (early session)
**Supports:** H1-H4 (proof structure analysis)

---

## Analysis Tools

These scripts perform mathematical analysis on the proof structure and hypothesis parameters.

### Exponent Analysis

**Script:** `analyze_exponent.py`
**Command:** `uv run scripts/analyze_exponent.py`
**Purpose:** Analyzes the exponent calculation in the OpenAI proof.
**Dependencies:** none
**What it does:**
- Reads `wiki/raw/unit-distance-remarks.txt`
- Extracts Lemma 2.1 and Lemma 2.2 text
- Analyzes the exponent formula: delta = gamma / (4B)
- Helps understand the relationship between entropy (gamma) and packing (B)
**Created:** 2026-07-03 (early session)
**Supports:** H1-H4 (exponent understanding)

### Reflection Analysis

**Script:** `analyze_reflections.py`
**Command:** `uv run scripts/analyze_reflections.py`
**Purpose:** Analyzes the reflection principles used in the OpenAI proof.
**Dependencies:** none
**What it does:**
- Reads the OpenAI PDF text files
- Identifies reflection-related content
- Helps understand the geometric interpretation of the construction
**Created:** 2026-07-03 (early session)
**Supports:** H1-H4 (geometric understanding)

### Remarks Analysis

**Script:** `analyze_remarks.py`
**Command:** `uv run scripts/analyze_remarks.py`
**Purpose:** Comprehensive analysis of the Remarks PDF structure.
**Dependencies:** none
**What it does:**
- Reads `wiki/raw/unit-distance-remarks.txt`
- Identifies all lemmas, propositions, and remarks
- Creates a structural map of the Remarks document
**Created:** 2026-07-03 (early session)
**Supports:** H1-H4 (document navigation)

### H1-H3 Quantification

**Script:** `quantify_h1_h2_h3.py`
**Command:** `uv run scripts/quantify_h1_h2_h3.py`
**Purpose:** Quantifies the parameter optimization space for hypotheses H1-H3.
**Dependencies:** numpy, scipy
**What it does:**
- Implements the H1 valuation optimization formula
- Implements the H2 polydisc radius optimization
- Maps the parameter space for H3 (pro-3 towers)
- Computes optimal parameters for each hypothesis
**Created:** 2026-07-03 (early session)
**Supports:** H1-H3 (parameter optimization)

### Parameter Optimization

**Script:** `optimize_parameters.py`
**Command:** `uv run scripts/optimize_parameters.py`
**Purpose:** General-purpose parameter optimization for tower constructions.
**Dependencies:** numpy, scipy
**What it does:**
- Implements the delta(ell, t, k) function
- Uses scipy.optimize to find the global maximum
- Handles constraints: GS inequality, density bounds, CM involution
- Returns optimal parameters and the corresponding exponent
**Created:** 2026-07-03 (Session 1)
**Supports:** H5-H8 (global optimization)

---

## Verification Scripts

These scripts verify specific mathematical claims or check the integrity of the research infrastructure.

### Epsilon-U Validity Check

**Script:** `verify_epsilon_u_valid.py`
**Command:** `uv run scripts/verify_epsilon_u_valid.py`
**Purpose:** Verifies the validity of the epsilon-U construction in the OpenAI proof.
**Dependencies:** numpy
**What it does:**
- Implements the epsilon-U packing bound
- Verifies that the bound holds for various parameter choices
- Checks consistency with the OpenAI proof
**Created:** 2026-07-03 (early session)
**Supports:** H1-H4 (validity check)

### Subagent Log Checker

**Script:** `check_subagent_log.py`
**Command:** `uv run scripts/check_subagent_log.py`
**Purpose:** Checks the subagent invocation logs for contamination events.
**Dependencies:** none
**What it does:**
- Reads the Antigravity transcript JSONL files
- Searches for subagent invocations
- Identifies any searches for external sources (potential contamination)
- Reports contamination events if found
**Created:** 2026-07-03 (post-H3 contamination event)
**Supports:** Anti-contamination protocol

### Wiki Link Auditor

**Script:** `wiki_link_auditor.py`
**Command:** `uv run scripts/wiki_link_auditor.py`
**Purpose:** Audits the wiki for broken links, missing index entries, and OKF compliance.
**Dependencies:** none
**What it does:**
- Scans all `.md` and `.mdx` files in the `wiki/` directory
- Checks that all wiki links (``) resolve to existing pages
- Verifies that all pages in the wiki are indexed in `wiki/index.md`
- Checks OKF frontmatter compliance (required fields: type, title, description, timestamp)
- Reports broken links, missing index entries, and OKF violations
**Created:** 2026-07-04 (commit 5ddf8de)
**Supports:** WIKI-MAINTAINER sub-agent

---

## Scripts by Hypothesis

| Hypothesis | Scripts Used | Purpose |
|---|---|---|
| H1-H3 | search_cot_ideas.py, read_middle_remarks.py, read_prop_2_3.py, read_remarks_2_3.py, read_sawin_tsimerman.py, read_section_7.py, analyze_exponent.py, analyze_reflections.py, analyze_remarks.py, quantify_h1_h2_h3.py | Initial exploration, PDF analysis |
| H4 | quantify_h1_h2_h3.py, optimize_parameters.py | Pro-3 tower optimization |
| H5-H6 | optimize_parameters.py | Global parameter tuning |
| H7 | optimize_parameters.py | Multivariate optimization |
| H8 | optimize_parameters.py | Imaginary quadratic optimization |
| H9-H10 | (no dedicated scripts) | Unproven, disqualified before scripting |
| H11 | optimize_parameters.py | Formal proof verification |
| H12-H14 | optimize_parameters.py | Completeness failure analysis |
| H15 | optimize_central_cm_tower.py | Central CM tower verification |
| H16 | optimize_multiquadratic_degree16.py, fix_h16_primes.py, engineer_p_base.py | Multi-quadratic CM16 verification |
| Infrastructure | wiki_link_auditor.py, check_subagent_log.py | Wiki integrity, contamination detection |

---

## Scripts by Creation Date

| Date | Scripts | Session |
|---|---|---|
| 2026-07-03 (early) | search_cot_ideas.py, read_middle_remarks.py, read_prop_2_3.py, read_remarks_2_3.py, read_sawin_tsimerman.py, read_section_7.py, analyze_exponent.py, analyze_reflections.py, analyze_remarks.py, quantify_h1_h2_h3.py | Session 1 (initial exploration) |
| 2026-07-03 (mid) | optimize_parameters.py, verify_epsilon_u_valid.py, check_subagent_log.py | Session 1 (optimization) |
| 2026-07-04 (early) | optimize_central_cm_tower.py, optimize_multiquadratic_degree16.py | Session 2 (H15-H16 verification) |
| 2026-07-04 (mid) | wiki_link_auditor.py, fix_h16_primes.py, engineer_p_base.py | Session 2 (infrastructure) |

---

## Execution Examples

```bash
# Verify H16 construction
uv run scripts/optimize_multiquadratic_degree16.py

# Verify H15 construction
uv run scripts/optimize_central_cm_tower.py

# Verify H16 split primes
uv run scripts/fix_h16_primes.py

# Audit wiki integrity
uv run scripts/wiki_link_auditor.py

# Search CoT for keywords
uv run scripts/search_cot_ideas.py

# Check for contamination events
uv run scripts/check_subagent_log.py
```

---

## Technical Notes

### PEP 723 Inline Metadata

All scripts use PEP 723 inline metadata to declare dependencies:

```python
# /// script
# dependencies = ["numpy", "scipy"]
# ///
```

This allows `uv run` to automatically install dependencies without a separate `requirements.txt` file.

### Apple Silicon Acceleration

The optimization scripts (optimize_parameters.py, optimize_central_cm_tower.py, optimize_multiquadratic_degree16.py) use NumPy vectorized operations that benefit from Apple Silicon's unified memory architecture. Future scripts may use MLX for Metal tensor acceleration.

### Anti-Contamination Design

The `check_subagent_log.py` script was created specifically in response to the H3 contamination event. It scans the Antigravity transcript logs for any searches for external sources, providing an automated check against contamination.

---

## References

- [[unit-distance-development-journey]] — Full session-by-session chronology
- [[unit-distance-seasons]] — Research seasons and hypothesis progression
- [[unit-distance-dead-ends]] — Analysis of failed hypotheses and lessons learned
- [[unit-distance]] — Mathematical background and current status