\
# Alexander–Gröbner Computations 0.4.1

This Python package performs exact computations of Alexander Fitting ideals and reduced Alexander–Gröbner normal forms over `QQ`. It accompanies the paper **“Gröbner Bases for Alexander Fitting Ideals of Links.”**

The package accepts either:

- an oriented Knot Atlas-style PD code, converted to a Wirtinger presentation; or
- a finite presentation together with an epimorphism to `Z^ell`.

No floating-point arithmetic is used.

## Choose a bundle

- **Quickstart bundle:** intended for users who want to install the wheel and reproduce examples on Windows with minimal setup.
- **Developer/reimplementation bundle:** includes the complete source tree, tests, wheel, examples, and an implementation specification.
- **Source archive:** intended for inspection, modification, and conventional Python development.

Open `START_HERE.html` first. On Windows, the recommended entry point is `START_HERE_WINDOWS.bat`.

## Mathematical pipeline

Let `A` be the abelianized Fox matrix, with relators as rows and `n` presentation generators as columns. The package uses

```text
relative Alexander module = Coker(A.T)
E_k = I_{n-k}(A)
```

in the Laurent ring `Lambda = QQ[t1^±1,...,tell^±1]`.

Each row of `A` is multiplied by one Laurent monomial unit so that the row becomes polynomial. This preserves the Laurent determinantal ideal. If `J` is the polynomial ideal generated by the resulting minors and `T=t1*...*tell`, the contraction to `P=QQ[t1,...,tell]` is computed as

```text
(J Lambda) intersect P = J:T^infinity = (J, 1-z*T) intersect P.
```

The final output is the reduced Gröbner basis in lexicographic order

```text
t1 > ... > tell.
```

The output is therefore relative to the coefficient field, the ordered basis of the free abelian target, and the chosen monomial order.

## Windows quick start

1. Extract the Quickstart ZIP to a normal folder. Do not run files inside the ZIP viewer.
2. Double-click `START_HERE_WINDOWS.bat`.
3. Double-click `RUN_DEMO_WINDOWS.bat`.
4. To reproduce the bundled paper examples, run `VERIFY_PAPER_EXAMPLES_WINDOWS.bat`.
5. To compute your own JSON input, drag it onto `COMPUTE_INPUT_WINDOWS.bat` and enter `k`.

Equivalent PowerShell commands are:

```powershell
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install alexander_grobner-0.4.1-py3-none-any.whl
.\.venv\Scripts\python.exe -m alexander_grobner doctor
.\.venv\Scripts\python.exe -m alexander_grobner demo L8n5
.\.venv\Scripts\python.exe -m alexander_grobner verify -o section3_reproduction.json
```

The wheel depends on SymPy 1.14.0. A first-time installation normally requires internet access.

## Compute an oriented PD code

```powershell
.\.venv\Scripts\python.exe -m alexander_grobner compute-pd `
  --pd "X_{4,1,3,2} X_{2,3,1,4}" `
  --name Hopf -k 1 --save-input Hopf.json
```

Then reuse the saved input:

```powershell
.\.venv\Scripts\python.exe -m alexander_grobner compute Hopf.json -k 1
.\.venv\Scripts\python.exe -m alexander_grobner compute Hopf.json -k 1 --format json -o Hopf_AG1.json
.\.venv\Scripts\python.exe -m alexander_grobner compute Hopf.json -k 1 --format latex
```

The PD orientation convention and component order are mathematical input. By default, components are ordered by their smallest edge label; use `component_order` to override that order explicitly.

## Finite-presentation input

```json
{
  "format": "presentation",
  "name": "commutator",
  "generators": ["x1", "x2"],
  "relators": [[1, 2, -1, -2]],
  "images": [[1, 0], [0, 1]],
  "variables": ["t1", "t2"]
}
```

In a relator, `j` means the `j`-th generator and `-j` means its inverse. The row `images[j-1]` is the exponent vector of the `j`-th generator in `Z^ell`. The package checks that the map is onto and that every relator maps to zero.

## Inspect before a large computation

```powershell
.\.venv\Scripts\python.exe -m alexander_grobner inspect INPUT.json -k 2
```

The number of candidate `r`-minors is

```text
binomial(rows,r) * binomial(columns,r),  r=n-k.
```

The CLI refuses more than 100,000 candidate minors by default. Raise `--max-minors` or use `--force` only after checking the expected cost.

## What `verify` does—and does not do

`verify` recomputes sixteen frozen inputs in fresh Python processes and compares their reduced bases with archived expected values. Selected collision examples also compare normalized common divisors.

It does **not** independently verify:

- the association between an external link-table label and a frozen PD code;
- equivalence of two link diagrams;
- the complete scan of all links through ten crossings;
- the fourteen additional pairs named but not fully archived in the paper;
- the mathematical proofs in the paper.

See `docs/REPRODUCIBILITY.md` and `docs/MANUSCRIPT_CROSSWALK.md`.

## Internal checks

A normal computation checks:

- the abelianized Fox fundamental identity;
- containment of determinantal generators in the reported saturated ideal;
- stability under a fresh reduced-lex recomputation;
- monicity, reducedness, and Buchberger’s criterion using a separate polynomial-division routine.

These are substantial internal checks, but they are not a completely independent second-CAS implementation.

## Documentation

- `QUICKSTART_WINDOWS.md`: Windows installation and first calculations;
- `docs/WHAT_IS_COMPUTED.md`: mathematical meaning of the output;
- `docs/REIMPLEMENTATION_GUIDE.md`: specification for an independent implementation;
- `docs/INPUT_FORMAT.md`: JSON and PD input conventions;
- `docs/OUTPUT_FORMAT.md`: output record;
- `docs/MANUSCRIPT_CROSSWALK.md`: correspondence with Section 3 of the paper;
- `docs/REPRODUCIBILITY.md`: precise scope of `verify`;
- `docs/TROUBLESHOOTING.md`: common installation and runtime problems;
- `AUDIT_REPORT.md`: release audit and known limitations.

The package is distributed under the BSD 3-Clause License. Citation metadata is provided in `CITATION.cff`.