Macaulay2 / Macaulay2/M2

track and trackHomotopy disagree on what the documented NumberOfSteps counts: one records the steps, the other the points minus one

Open
#4,614 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bugs directory
Dominant language
Macaulay2
Stars
435
Forks
297
Avg merge
4d 20h
Merged PRs (30d)
11

Description

This issue was triaged from [`bugs/anton/NumericalAG/track-predictor.m2`](https://github.com/Macaulay2/M2/blob/388c1ff0ce30d83751dea7bc7eac77fdc1305dd7/bugs/anton/NumericalAG/track-predictor.m2), one of the 857 files removed from the pre-GitHub `bugs/` tree by [`d2c8d27826`](https://github.com/Macaulay2/M2/commit/d2c8d27826) and catalogued in [#36](https://github.com/Macaulay2/M2/issues/36). **The commentary below was written by Claude (Claude Opus 5, via Claude Code)**, not by @d-torrance, whose account posted it -- please weigh it accordingly.

### The original file, verbatim

```m2
restart
debug needsPackage "NumericalAlgebraicGeometry"
n = 2; d = 2;
R=QQ[x_0..x_(n-1)]
eps = 10^-3
T = apply(n, i->if i==0 then x_i^d-eps^d else (x_i-i)^d-eps^(d-1)*x_i)
(S,solsS) = totalDegreeStartSystem T
H = segmentHomotopy(S,T,gamma=>1+pi*ii)

sols = trackHomotopy(H,solsS,tStepMin=>minimalStepSize 53,CorrectorTolerance=>1e-8,Precision=>infinity,EndZoneFactor=>0)
peek sols

sols' = track(S,T,solsS,tStepMin=>minimalStepSize 53,CorrectorTolerance=>1e-8,EndZoneFactor=>0.)
peek sols'

-- NOTE THE DISCREPANCY in the number of steps reported
```

### Where it stands today

`track` and `trackHomotopy` both record a `NumberOfSteps` in each solution's cache, and
[the documentation](https://github.com/Macaulay2/M2/blob/development/M2/Macaulay2/packages/NumericalAlgebraicGeometry/doc.m2#L445)
gives it one meaning for both — *"number of steps taken on the corresponding homotopy path"*. The two
compute it by different conventions.

`trackHomotopyM2engine` records the count itself:

https://github.com/Macaulay2/M2/blob/development/M2/Macaulay2/packages/NumericalAlgebraicGeometry/track.m2#L677-L682

`track`'s own loops subtract one, in two places, and say why:

https://github.com/Macaulay2/M2/blob/development/M2/Macaulay2/packages/NumericalAlgebraicGeometry/track.m2#L578-L582

https://github.com/Macaulay2/M2/blob/development/M2/Macaulay2/packages/NumericalAlgebraicGeometry/track.m2#L1019-L1023

So one reports the number of steps and the other the number of points minus one. Whichever is
intended, both cannot be, and a caller reading `NumberOfSteps` gets a quantity that depends on which
entry point produced the solution.

### Reproducing

```m2
debug needsPackage "NumericalAlgebraicGeometry"
n = 2; d = 2;
R = QQ[x_0..x_(n-1)]
eps = 10^-3
T = apply(n, i -> if i == 0 then x_i^d - eps^d else (x_i-i)^d - eps^(d-1)*x_i)
(S, solsS) = totalDegreeStartSystem T
H = segmentHomotopy(S, T, gamma => 1+pi*ii)
tsm = minimalStepSize 53
sols = trackHomotopy(H, solsS, tStepMin => tsm, CorrectorTolerance => 1e-8, EndZoneFactor => 0)
sols' = track(S, T, solsS, tStepMin => tsm, CorrectorTolerance => 1e-8, EndZoneFactor => 0.)
apply(sols, p -> p.cache.NumberOfSteps) -- {22, 23, 22, 23}
apply(sols', p -> p.cache.NumberOfSteps) -- {23, 23, 23, 23}
```

Both return the same four solutions. The two solution records differ in shape as well, which is how
you can tell which branch produced each: `trackHomotopy` gives
`{H, LastIncrement, LastT, NumberOfSteps, SolutionStatus}` and `track` gives
`{ConditionNumber, LastT, NumberOfSteps, SolutionStatus, SolutionSystem, Tracker}`.

### What fixing the convention would not do

It would not make those two lists agree, and the issue should not be read as claiming otherwise.
`trackHomotopy` reports *fewer* steps here, where the off-by-one alone would make it report one more,
so the underlying iteration counts differ too — these are genuinely separate steppers that happen to
land on the same solutions. Only the naming is being reported here: the same documented field means
two things.

`Precision` is not involved. `trackHomotopy` gives `{22, 23, 22, 23}` with or without
`Precision => infinity`, and `track` does not accept the option at all.

`open` · disposition `issue` · source of truth: [`bug-triage/catalog.tsv`](https://github.com/d-torrance/M2/blob/bug-triage/bug-triage/catalog.tsv)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with M2/Macaulay2/packages/NumericalAlgebraicGeometry/track.m2, especially the NumberOfSteps assignments around lines 578-582, 677-682, and 1019-1023, and read the package documentation around line 445. Reproduce the discrepancy with the M2 script in the issue, determine the intended counting convention, and make the two entry points and documentation consistent.

Written by the indexing model from the issue text.

Assessment

Domain
backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.