Add ordinal representation generator for closed Hamiltonian tours

[Naman-Vasudev]

Describe your change:

This pull request adds a new algorithm that converts a closed Hamiltonian
tour (path) into its ordinal representation based on a fixed reference
order of cities. Each position in the resulting list represents the
1-indexed position of the corresponding city in the reference list,
which shrinks as each city is removed — ensuring a unique and reversible
representation.

Key Features:

• Implements ordinal_representation_closed() with descriptive variable names
• Handles closed tours (last city conceptually connects back to the first)
• Fully PEP-8 compliant (≤ 79 chars per line)
• Includes doctests verified via python -m doctest -v
• Uses modern Python type hints (list[str], int)
• Includes a reference URL for background context

---

• Add an algorithm?
• Fix a bug or typo in an existing algorithm?
• Add or change doctests?
• Documentation change?

---

Checklist:

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized.
• I know that pull requests will not be merged if they fail the automated tests.
• This PR only changes one algorithm file.
• All new Python files are placed inside an existing directory.
• All filenames are in all lowercase characters with no spaces or dashes.
• All function and variable names follow Python naming conventions.
• All function parameters and return values are annotated with Python type hints.
• All functions have doctests that pass the automated testing.
• All new algorithms include at least one URL that points to Wikipedia or another similar explanation.
• If this pull request resolves one or more open issues then the description above includes the issue number(s) with a closing keyword: "Fixes #ISSUE-NUMBER".

[priya-sundaram-dev]

Thanks @Naman-Vasudev — the shrinking-reference ordinal encoding is correct and the doctests demonstrate it well.

Two small things:

1. reference.index(city) will raise a bare ValueError if a path city isn't in nodes. Consider validating set(path) == set(nodes) at the top with an explicit message, so the failure mode is clear.
2. The module docstring is a bit thinner than its sibling #13645 — adding a reference link and a note about the inverse operation (reconstructing the path from the ordinal vector) would round it out.

Nice pair of contributions.

[cclauss]

@priya-sundaram-dev, please review. Is this code useful for genetic algorithms?

[priya-sundaram-dev]

Reviewed locally on 3.12 — the two functional doctests reproduce exactly ([7, 11, 1, 3, 1, 5, 6, 2, 3, 3, 2, 1] and [1, 11, 6, 2, 4, 6, 4, 3, 4, 3, 1, 1]), and the ValueError path fires as documented. The math is correct: each yielded value is the 1-based position in a reference list that shrinks as cities are consumed.

On "is this useful for genetic algorithms?" — yes, but only half of it is here. Ordinal representation is a genuine, well-known GA encoding for the TSP. Its whole point is that an ordinary fixed-point crossover on two ordinal vectors always produces a valid tour (no repair, no PMX/OX bookkeeping). That's exactly why it belongs under genetic_algorithm/ rather than, say, conversions/.

But usefulness in a GA needs the round trip, and only the encode direction is implemented. After you cross two ordinal vectors you're left with an ordinal vector that has to be decoded back to a tour. The inverse is symmetric and tiny:

def tour_from_ordinal(ordinal: list[int], nodes: list[str]) -> list[str]:
    reference = nodes.copy()
    return [reference.pop(i - 1) for i in ordinal]

I verified tour_from_ordinal(encode(path), nodes) == path roundtrips on the doctest input.

Suggestions to make this land as a GA contribution rather than a standalone transform:

1. Add the decode function above, with a doctest asserting the roundtrip.
2. Add one short __main__ (or doctest) that takes two tours, encodes both, does a one-point crossover, decodes the children, and shows both children are valid permutations — that demonstrates the reason the encoding exists.
3. Minor: the function name says _closed but nothing here treats the tour as closed (no wrap to the start city); either drop the suffix or document what "closed" adds.

With the inverse + a crossover demo I'd be happy to see this merged; as-is it's a correct but one-directional utility. Nice, clean generator style otherwise.

[cclauss]

@priya-sundaram-dev, please add a few GitHub suggestions that would enable us to have a mergeable pull request,

[priya-sundaram-dev]

Two suggestions to get this merge-ready (checks are already green; these are about completeness/house-style).

1. See the inline suggestion below — it adds the inverse tour_from_ordinal with a round-trip doctest and switches __main__ to doctest.testmod().

2. Naming nit (not a one-click suggestion since it touches the def and every doctest call): the name ordinal_representation_closed promises a closed tour, but nothing here wraps the last city back to the first — the logic is identical for an open path. I'd either drop the _closed suffix, or genuinely close the tour (append path[0]) and say so in the docstring. Your call, but the name and the behaviour should agree.

[priya-sundaram-dev]

Thanks for iterating, @Naman-Vasudev! The doctests all reproduce and CI is green. Here are three small, one-click suggestions that close a real correctness gap and make it merge-ready.

There's a latent crash: the type hints say list[str], but the third doctest passes plain strings ("ABC", "DCBA"). That case only survives today because it short-circuits on the ValueError. Pass a valid string tour (equal sets) and nodes.copy() blows up, since str has no .copy():

>>> list(ordinal_representation_closed("ABC", "ABC"))
AttributeError: 'str' object has no attribute 'copy'

The fix is to accept any Sequence[str] and copy via list(nodes), which works for lists, tuples, and strings alike. Three coordinated suggestions below.