# Delzant Octagon Stability Search - User Guide

GNU General Public License v3.0

Copyright (C) 2026 Bijan Mohammadi

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.


## Introduction

This software investigates the stability of families of **Delzant octagons** arising in toric geometry by numerically and symbolically evaluating Donaldson's functional

\[
L_A(u)=\int_{\partial P}u\,d\sigma-\int_P A\,u\,d\mu.
\]

The program searches for piecewise-linear (PL) convex test functions that may destabilize a given toric polygon and verifies the resulting instability candidates using exact symbolic computations with SymPy.

---

# Installation

## Requirements

Recommended:

- Python 3.10+
- NumPy
- Pandas
- Matplotlib
- SciPy
- SymPy

Install dependencies:

```bash
pip install numpy pandas matplotlib scipy sympy
```

---

# Running the Program

Execute:

```bash
python delzant_octagon.py
```

The program automatically:

1. Creates the output directory.
2. Iterates over all Delzant octagon families.
3. Searches for destabilizing configurations.
4. Stores solutions in JSON format.
5. Performs symbolic verification.
6. Produces summary plots.

---

# Main Parameters

Located in the `__main__` section:

```python
kmin = 20
kmax = kmin + 1
analytical = False
```

## k Range

To test multiple values:

```python
kmin = 1
kmax = 100
```

This evaluates:

```text
k = 1 ... 99
```

---

## Analytical Mode

### Numerical Search

```python
analytical = False
```

Performs full Monte-Carlo instability exploration.

### Verification Mode

```python
analytical = True
```

Loads a previously stored best solution and performs exact symbolic validation.

---

# Delzant Polygon Families

The code currently implements **15 Delzant octagon families**.

```python
case = "1"
...
case = "15"
```

Each family includes:

- Dedicated vertex construction formulas
- Primitive edge directions
- Convexity constraints
- Feasible parameter sampling routines

Implemented through:

```python
build_vertices_1(...)
...
build_vertices_15(...)
```

and

```python
get_primitive_dirs(...)
```

---

# Search Strategy

The optimization uses a stochastic Monte-Carlo search.

Main parameters:

```python
mc_iter_max = 100
num_tests_lines = 100
step_size = 1
```

| Parameter | Meaning |
|------------|----------|
| `mc_iter_max` | Number of Monte-Carlo parameter updates |
| `num_tests_lines` | Number of random crease lines tested |
| `step_size` | Perturbation amplitude |

---

# Polygon Parameters

Each octagon depends on:

```text
l1, l2, l3, l4, l5
```

with fixed:

```text
l6 = 1
```

The variables are constrained to satisfy Delzant admissibility conditions.

Example (Case 1):

```math
(k+4)l_1+(k+3)l_2+(k+2)l_3+(k+1)l_4+k\,l_5 < 1
```

The code automatically rejects invalid samples.

---

# Affine Function A

For each polygon, the affine function

```math
A(x,y)=\alpha_0+\alpha_1x+\alpha_2y
```

is recovered from moment normalization conditions.

The coefficients are computed by

```python
solve_alpha_from_polygon_moments()
```

using:

```math
\int_P Af\,d\mu
=
\int_{\partial P}f\,d\sigma
```

for all affine functions \(f\).

---

# Donaldson Functional

For every candidate crease line, the code builds

```math
u(x,y)=\max(0,L(x,y))
```

where \(L\) is an affine function defining the crease.

Donaldson's functional is then evaluated:

```math
L_A(u)
=
\int_{\partial P}u\,d\sigma
-
\int_PA\,u\,d\mu .
```

Implemented in:

```python
compute_LA(...)
```

---

# Stability Interpretation

The quantity of interest is:

```python
min_L
```

Interpretation:

| Value | Interpretation |
|---------|----------------|
| `L_A > 0` | Stable candidate |
| `L_A ≈ 0` | Critical candidate |
| `L_A < 0` | Destabilizing candidate |

Negative values indicate potential instability.

---

# JSON Output Files

## Complete Search History

```text
Delzant_solution_case_X.json
```

Example:

```text
Delzant_solution_case_7.json
```

Stores all discovered admissible solutions.

---

## Best Solution

```text
Delzant_solution_case_X_kY_best.json
```

Example:

```text
Delzant_solution_case_7_k20_best.json
```

Stores:

- optimal parameter set
- affine coefficients
- minimum functional value
- crease geometry
- admissibility status

---

# JSON Schema

Example:

```json
{
  "case": "7",
  "k": 20,
  "min_L": "-0.001234",
  "constraints_ok": true,
  "alpha": [
    "1.23",
    "-0.45",
    "0.78"
  ]
}
```

---

# Symbolic Verification

After the numerical search, the best result is reconstructed symbolically.

The program:

1. Rebuilds the exact polygon.
2. Reconstructs the crease line.
3. Computes the positive region \(P_+\).
4. Evaluates boundary integrals exactly.
5. Evaluates area integrals exactly.
6. Recomputes \(L_A\) symbolically.

Expected output:

```text
Symbolic L_A   = ...
Numeric L_A    = ...
Relative error = ...
```

Small relative errors confirm numerical correctness.

---

# Plotting Options

## Single Polygon Display

Enable:

```python
plot_poly_and_stop = True
```

Displays the current polygon and exits.

## Plot All Test Families

Enable:

```python
plot_allpoly_and_stop = True
```

The program:

- draws all test crease lines
- colors stable and unstable configurations
- saves a figure

Output:

```text
output/test_families.png
```

---

# Reproducibility

Randomness is controlled using:

```python
SEED = 123
```

and

```python
rng = np.random.default_rng(SEED)
```

This guarantees reproducible experiments across runs.

---

# Typical Workflow

## Step 1 - Search

Run:

```python
analytical = False
```

and execute:

```bash
python delzant_octagon.py
```

## Step 2 - Identify Best Candidate

Locate:

```text
Delzant_solution_case_X_kY_best.json
```

## Step 3 - Verification

Set:

```python
analytical = True
kmin = Y
kmax = Y + 1
```

## Step 4 - Re-run

Execute:

```bash
python delzant_octagon.py
```

The program performs an exact symbolic verification of the stored instability candidate.

---

# Generated Outputs

The software provides:

- Optimal value of `k`
- Optimal parameters `(l1,...,l5)`
- Affine coefficients `α`
- Minimum Donaldson functional value
- Geometric instability configuration
- Symbolic validation report
- Summary plots

---

# Troubleshooting

## No Valid Polygon Found

Increase:

```python
mc_iter_max
```

or widen the search interval for `k`.

## Numerical Integration Slow

Reduce:

```python
num_tests_lines
```

or relax:

```python
INT_EPS
GEOM_EPS
```

## Reproducibility Issues

Verify that:

```python
SEED = 123
```

has not been modified.

---

# Author

**Bijan Mohammadi**

Created: April 2026

---

# Research Applications

This code is suitable for:

- Toric K-stability investigations
- Donaldson stability testing
- Extremal metric studies
- Delzant polygon classification
- Numerical-to-symbolic verification workflows
- Instability searches on toric surfaces