Skip to content

Commit d66bb8d

Browse files
hyperpolymathhyperpolymath
authored
Merge pull request #1 from hyperpolymath/claude/knot-diagram-julia-package-45tWA
Add KnotDiagrams module for fragment-count distribution analysis
2 parents ddd9231 + 7016899 commit d66bb8d

12 files changed

Lines changed: 1241 additions & 0 deletions

File tree

‎KnotDiagrams/Project.toml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name = "KnotDiagrams"
2+
uuid = "a7e3c1f0-5d4b-4e8a-9f1c-2b3d4e5f6a7b"
3+
version = "0.1.0"
4+
5+
[deps]
6+
DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
7+
8+
[extras]
9+
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
10+
CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
11+
12+
[targets]
13+
test = ["Test"]
14+
15+
[compat]
16+
DataFrames = "1"
17+
julia = "1.9"

‎KnotDiagrams/docs/narrative.txt‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
Fraying-Model Fragment-Count Distribution Predictions
2+
=====================================================
3+
4+
This document states testable predictions about the fragment-count
5+
distribution L_D(k) for knot diagrams, derived from the combinatorics
6+
of Kauffman bracket state sums.
7+
8+
Definitions
9+
-----------
10+
11+
For an n-crossing knot diagram D, the 2^n global resolution states are
12+
obtained by choosing one of two smoothings at each crossing. Each state
13+
yields a collection of k disjoint simple closed curves ("fragments").
14+
15+
L_D(k) = |{ states s : s produces exactly k fragments }|
16+
17+
The tropical summary is:
18+
support(L_D) = { k : L_D(k) > 0 }
19+
min, max = extrema of support
20+
|support| = cardinality
21+
class = "spread" if |support| > 1, "collapse" if |support| = 1
22+
23+
Prediction 1 — No Collapse for Nontrivial Knots
24+
------------------------------------------------
25+
26+
Every prime knot with crossing number >= 3 has |support| > 1 (is "spread").
27+
28+
Rationale: For an alternating prime knot, the all-A state (Seifert state)
29+
produces a number of circles related to the genus, while the all-B state
30+
produces a different count. The minimum and maximum circle counts in
31+
the state sum always differ for nontrivial knots.
32+
33+
Prediction 2 — Trefoil (3_1) Has Support {1, 2, 3}
34+
---------------------------------------------------
35+
36+
The trefoil should produce states with 1, 2, or 3 circles.
37+
38+
L_{3_1}(1) = 3 (three states yield 1 circle)
39+
L_{3_1}(2) = 4 (four states yield 2 circles)
40+
L_{3_1}(3) = 1 (one state yields 3 circles)
41+
42+
Verification: the all-0 state (smoothing 0 at every crossing) gives 2
43+
circles, and the all-1 state gives 3 circles. Three mixed states give
44+
1 circle each. This matches the Kauffman bracket structure for the
45+
trefoil.
46+
47+
Prediction 3 — Topology Predicts the Distribution
48+
--------------------------------------------------
49+
50+
Diagrams of different knot types at the same crossing number should
51+
produce different fragment-count histograms L_D(k). Specifically:
52+
53+
5_1 vs 5_2 — different histograms, likely different supports
54+
6_1 vs 6_2 — different histograms
55+
6_1 vs 6_3 — different histograms
56+
6_2 vs 6_3 — different histograms
57+
7_i vs 7_j — different histograms for i ≠ j (all 21 pairs)
58+
59+
This is the central testable claim: the fragment-count distribution is a
60+
topological invariant of the diagram (up to diagram equivalence), and
61+
distinct knot types generally have distinct distributions.
62+
63+
Prediction 4 — Torus Knots Have Wider Support
64+
----------------------------------------------
65+
66+
Torus knots T(2, 2k+1) have wider support (larger |support|) than
67+
non-torus knots at the same crossing number.
68+
69+
5_1 (torus) — wider support than 5_2 (twist knot)
70+
7_1 (torus) — wider support than 7_2, ..., 7_7
71+
72+
Rationale: the Seifert state of a torus knot produces the minimum
73+
number of Seifert circles (k+1 for T(2,2k+1)), while the all-opposite
74+
state produces a larger count. The spread between min and max is
75+
maximised for torus knots among alternating knots at a given crossing
76+
number.
77+
78+
Prediction 5 — Support Range Grows with Crossing Number
79+
--------------------------------------------------------
80+
81+
For the torus knot series T(2, 2k+1):
82+
3_1: |support| around 3
83+
5_1: |support| around 4-5
84+
7_1: |support| around 5-6
85+
86+
The support range (max - min + 1) grows roughly linearly with crossing
87+
number for torus knots.
88+
89+
Prediction 6 — The Distribution Refines the Jones Polynomial
90+
-------------------------------------------------------------
91+
92+
Two knots can share the same Jones polynomial but have different
93+
fragment-count distributions. The L_D(k) histogram retains state-level
94+
information that the polynomial (which sums over states with signs and
95+
weights) discards. This makes L_D(k) a finer invariant in some cases.
96+
97+
Expected Outcomes
98+
-----------------
99+
100+
Running the analysis on all prime knots up to 7 crossings should show:
101+
- 14 diagrams, all classified as "spread"
102+
- 25 pairwise comparisons (1 + 3 + 21 for n=5,6,7)
103+
- Majority of pairs have different supports
104+
- All pairs have different histograms (stronger claim)
105+
- Torus knots (3_1, 5_1, 7_1) have the widest support at each cn

‎KnotDiagrams/scripts/plot_distributions.jl‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
#!/usr/bin/env julia
2+
# SPDX-License-Identifier: PMPL-1.0-or-later
3+
#
4+
# Generate histogram plots for fragment-count distributions.
5+
# Requires CairoMakie.
6+
#
7+
# Usage:
8+
# julia --project=. scripts/plot_distributions.jl
9+
10+
using KnotDiagrams
11+
using CairoMakie
12+
13+
function plot_all(fds::AbstractVector{FragmentDistribution};
14+
output_dir::String = joinpath(@__DIR__, "..", "plots"))
15+
mkpath(output_dir)
16+
17+
# Group by crossing number
18+
groups = Dict{Int,Vector{FragmentDistribution}}()
19+
for fd in fds
20+
cn = fd.diagram.crossing_number
21+
push!(get!(Vector{FragmentDistribution}, groups, cn), fd)
22+
end
23+
24+
# Per-crossing-number overlaid histograms
25+
for cn in sort(collect(keys(groups)))
26+
group = groups[cn]
27+
plot_group(group, cn, output_dir)
28+
end
29+
30+
# Per-diagram individual plots
31+
for fd in fds
32+
plot_single(fd, output_dir)
33+
end
34+
35+
n_group = length(groups)
36+
n_single = length(fds)
37+
println("Saved $(n_group + n_single) plots to $output_dir")
38+
end
39+
40+
function plot_group(group::Vector{FragmentDistribution}, cn::Int, output_dir::String)
41+
all_k = Set{Int}()
42+
for fd in group
43+
union!(all_k, keys(fd.histogram))
44+
end
45+
k_range = minimum(all_k):maximum(all_k)
46+
47+
fig = Figure(size = (800, 500))
48+
ax = Axis(fig[1, 1],
49+
title = "Fragment-count distribution — $(cn)-crossing knots",
50+
xlabel = "Fragment count k",
51+
ylabel = "Number of states",
52+
xticks = collect(k_range),
53+
)
54+
55+
n_diagrams = length(group)
56+
bar_width = 0.8 / n_diagrams
57+
offsets = range(-0.4 + bar_width / 2, step = bar_width, length = n_diagrams)
58+
59+
for (i, fd) in enumerate(group)
60+
ks = collect(k_range)
61+
counts = [get(fd.histogram, k, 0) for k in ks]
62+
barplot!(ax, ks .+ offsets[i], counts,
63+
width = bar_width,
64+
label = fd.diagram.name,
65+
color = Cycled(i),
66+
)
67+
end
68+
69+
axislegend(ax, position = :rt)
70+
save(joinpath(output_dir, "distribution_n$(cn).png"), fig, px_per_unit = 2)
71+
end
72+
73+
function plot_single(fd::FragmentDistribution, output_dir::String)
74+
k_range = fd.summary.min_k:fd.summary.max_k
75+
ks = collect(k_range)
76+
counts = [get(fd.histogram, k, 0) for k in ks]
77+
78+
fig = Figure(size = (600, 400))
79+
ax = Axis(fig[1, 1],
80+
title = "L_D(k) — $(fd.diagram.name)",
81+
xlabel = "Fragment count k",
82+
ylabel = "Number of states",
83+
xticks = ks,
84+
)
85+
barplot!(ax, ks, counts, color = :steelblue)
86+
87+
save(joinpath(output_dir, "distribution_$(fd.diagram.name).png"), fig, px_per_unit = 2)
88+
end
89+
90+
# Main
91+
results = analyse_all(verbose = false)
92+
plot_all(results.distributions)

‎KnotDiagrams/scripts/run_analysis.jl‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
#!/usr/bin/env julia
2+
# SPDX-License-Identifier: PMPL-1.0-or-later
3+
#
4+
# Full analysis pipeline: compute fragment-count distributions for all
5+
# prime knots up to 7 crossings and compare within crossing numbers.
6+
#
7+
# Usage:
8+
# julia --project=. scripts/run_analysis.jl
9+
#
10+
# For plots, run separately:
11+
# julia --project=. scripts/plot_distributions.jl
12+
13+
using KnotDiagrams
14+
using DataFrames
15+
16+
function main()
17+
println("=" ^ 72)
18+
println(" Knot Diagram Fragment-Count Distribution Analysis")
19+
println("=" ^ 72)
20+
println()
21+
22+
# Run full analysis
23+
results = analyse_all(verbose = true)
24+
println()
25+
26+
# Print summary table
27+
println("=" ^ 72)
28+
println("SUMMARY TABLE")
29+
println("=" ^ 72)
30+
show(stdout, results.summary_table; allrows = true, allcols = true)
31+
println("\n")
32+
33+
# Print comparison table
34+
println("=" ^ 72)
35+
println("COMPARISON TABLE")
36+
println("=" ^ 72)
37+
show(stdout, results.comparison_table; allrows = true, allcols = true)
38+
println("\n")
39+
40+
# Validate against narrative predictions
41+
validate_narrative(results)
42+
43+
return results
44+
end
45+
46+
"""
47+
validate_narrative(results)
48+
49+
Check results against the narrative predictions in docs/narrative.txt.
50+
"""
51+
function validate_narrative(results)
52+
println("=" ^ 72)
53+
println("NARRATIVE VALIDATION")
54+
println("=" ^ 72)
55+
56+
passed = 0
57+
failed = 0
58+
59+
# Prediction 1: All prime knots are "spread"
60+
print(" [1] All prime knots have |support| > 1 (spread): ")
61+
all_spread = all(fd -> fd.summary.classification == :spread, results.distributions)
62+
if all_spread
63+
println("PASS")
64+
passed += 1
65+
else
66+
collapsed = filter(fd -> fd.summary.classification == :collapse, results.distributions)
67+
println("FAIL — collapsed: $(join([fd.diagram.name for fd in collapsed], ", "))")
68+
failed += 1
69+
end
70+
71+
# Prediction 2: Trefoil support includes at least {1,2} or {2,3}
72+
print(" [2] Trefoil support contains multiple values: ")
73+
trefoil = first(filter(fd -> fd.diagram.name == "3_1", results.distributions))
74+
if trefoil.summary.support_size >= 2
75+
println("PASS (support = $(trefoil.summary.support))")
76+
passed += 1
77+
else
78+
println("FAIL (support = $(trefoil.summary.support))")
79+
failed += 1
80+
end
81+
82+
# Prediction 3: Figure-eight has different distribution from trefoil
83+
print(" [3] Figure-eight distribution differs from trefoil: ")
84+
fig8 = first(filter(fd -> fd.diagram.name == "4_1", results.distributions))
85+
if fig8.histogram != trefoil.histogram
86+
println("PASS")
87+
passed += 1
88+
else
89+
println("FAIL")
90+
failed += 1
91+
end
92+
93+
# Prediction 4: 5_1 and 5_2 have different distributions
94+
print(" [4] 5_1 vs 5_2 histograms differ: ")
95+
cn5 = filter(r -> r.crossing_number == 5, results.comparisons)
96+
if !isempty(cn5) && first(cn5).histograms_differ
97+
println("PASS")
98+
passed += 1
99+
else
100+
println("FAIL")
101+
failed += 1
102+
end
103+
104+
# Prediction 5: Most pairs at same crossing number have differing supports
105+
print(" [5] Majority of same-cn pairs have differing supports: ")
106+
n_total = length(results.comparisons)
107+
n_differ = count(r -> r.supports_differ, results.comparisons)
108+
ratio = n_total > 0 ? n_differ / n_total : 0.0
109+
if ratio > 0.5
110+
println("PASS ($n_differ / $n_total = $(round(ratio * 100, digits=1))%)")
111+
passed += 1
112+
else
113+
println("FAIL ($n_differ / $n_total = $(round(ratio * 100, digits=1))%)")
114+
failed += 1
115+
end
116+
117+
# Prediction 6: Torus knots have wider support
118+
print(" [6] Torus knots tend to have wider support: ")
119+
fd51 = first(filter(fd -> fd.diagram.name == "5_1", results.distributions))
120+
fd52 = first(filter(fd -> fd.diagram.name == "5_2", results.distributions))
121+
fd71 = first(filter(fd -> fd.diagram.name == "7_1", results.distributions))
122+
other_7 = filter(fd -> fd.diagram.crossing_number == 7 && fd.diagram.name != "7_1",
123+
results.distributions)
124+
avg_other = isempty(other_7) ? 0.0 :
125+
sum(fd.summary.support_size for fd in other_7) / length(other_7)
126+
127+
torus_wider = fd51.summary.support_size >= fd52.summary.support_size &&
128+
fd71.summary.support_size >= avg_other
129+
if torus_wider
130+
println("PASS (5_1: $(fd51.summary.support_size) vs 5_2: $(fd52.summary.support_size), " *
131+
"7_1: $(fd71.summary.support_size) vs avg others: $(round(avg_other, digits=1)))")
132+
passed += 1
133+
else
134+
println("INCONCLUSIVE (5_1: $(fd51.summary.support_size) vs 5_2: $(fd52.summary.support_size), " *
135+
"7_1: $(fd71.summary.support_size) vs avg others: $(round(avg_other, digits=1)))")
136+
end
137+
138+
println()
139+
println(" Passed: $passed / $(passed + failed)")
140+
end
141+
142+
main()

0 commit comments

Comments
 (0)