Hamiltonian

Hamiltonian is a JavaScript library and web playground for drawing finite groups and Cayley-style graphs from a Hamiltonian cycle.

The idea is simple:

1. Choose a graph whose vertices are group elements, states, or words.
2. Order the vertices along a Hamiltonian cycle.
3. Draw the generators as chords inside the circle.

Why

Large Cayley graphs are hard to inspect with force-directed layouts. Those layouts often hide the algebraic construction that created the graph.

Hamiltonian-cycle layouts keep one invariant fixed: the vertex order. Once the cycle is fixed, every generator becomes a family of chords. The drawing is deterministic, exportable, and comparable across graph families.

This repository aims to make that method reusable and citable for academic work on large finite graphs.

What

• A small SVG renderer with no runtime framework dependency.
• A plugin API for specialized graph modes.
• Cayley-style examples from the graph explorer:
  • Complete graph
  • Complete Cayley graph of S_n
  • Star graph
  • Permutohedron graph
  • Cyclic adjacent graph
  • Transposition graph
  • Asymmetric tree Cayley graph
  • Kaleidoscope graph
  • Lexicographic graph
  • Hypercube
  • Simplex
  • Sierpinski graph S(n, 3)
• A Vite playground for interactive exploration and SVG export.

Install

npm install hamiltonian

During local development:

npm install
npm run dev

Use

import { buildCayleyExample, renderHamiltonianSvg } from "hamiltonian";

const graph = buildCayleyExample("hypercube", 6);

const svg = renderHamiltonianSvg(graph, {
  edgeOpacity: 0.18,
  showVertices: true,
});

document.querySelector("#figure").innerHTML = svg;

Custom Graphs

You can provide your own vertices, Hamiltonian order, and generator functions.

import { createHamiltonianGraph, renderHamiltonianSvg } from "hamiltonian";

const vertices = ["e", "a", "b", "ab"];

const graph = createHamiltonianGraph({
  title: "A four-state example",
  vertices,
  order: vertices,
  edges: [
    { source: "e", target: "a", generator: "x" },
    { source: "a", target: "ab", generator: "y" },
    { source: "ab", target: "b", generator: "x" },
    { source: "b", target: "e", generator: "y" },
  ],
});

const svg = renderHamiltonianSvg(graph);

For Cayley graphs, pass generators instead of explicit edges:

import { createHamiltonianGraph } from "hamiltonian";

const graph = createHamiltonianGraph({
  vertices,
  order: vertices,
  generators: [
    {
      id: "x",
      apply: (vertex) => multiply(vertex, "x"),
    },
  ],
});

Playground

Run:

npm run dev

Then open the local Vite URL. The playground lets you choose a graph family, change n, and download SVG output.

Citation

This repository includes CITATION.cff so GitHub can expose citation metadata.

For a persistent academic identifier, connect the public GitHub repository to Zenodo, then create a GitHub release. Zenodo will archive that release and issue a DOI. GitHub documents the workflow here: Referencing and citing content.

Suggested citation before the first DOI:

Viebel. Hamiltonian: SVG layouts of finite groups from Hamiltonian cycles. Version 0.1.0, 2026.

After the first Zenodo archive, cite the DOI for the exact release used.

Scope

Hamiltonian is a visualization toolkit, not a theorem prover. If an example uses a known Hamiltonian cycle, the preset says so. If you pass a custom cyclic order, the renderer preserves that order and draws the corresponding chord diagram.

License

MIT