visiter 0.15.0

Build and visualize orbit graphs for discrete iterations under guarded rules.

VisIter

See what a discrete iteration actually does — as a graph.

The simplest case

Integers 1–9. Case: divisible by 3 → divide by 3. Default (everything else) → add 2. Where does each value end up?

#!/usr/bin/env viter
(viter(range(1, 10))
 .case(lambda x: x % 3 == 0, lambda x: x // 3)
 .default(lambda x: x + 2)
 .render())

Save as descent.vit, run with viter descent.vit > out.svg. The #!/usr/bin/env viter shebang also lets you chmod +x descent.vit and execute the file directly.

.render() is the shortcut terminal — it builds the graph, converts to Graphviz, and writes SVG to stdout in one call.

Install

pip install visiter

Graphviz must be available on PATH (brew install graphviz / apt install graphviz).

Optional extras: pip install "visiter[storage]" adds the columnar .vitgraph format, [validate] the JSON-Schema validator, [analytics] the NetworkX bridge. The optional native engine is built separately with make native (needs a Rust toolchain). See Performance & storage below.

Going further

.render() is convenient for the common case. For anything more — cropping, custom colors, side-effects, filters — materialize the Graph explicitly via .build() and keep chaining:

#!/usr/bin/env viter
(viter(range(1, 10))
 .case(lambda x: x % 3 == 0, lambda x: x // 3)
 .default(lambda x: x + 2)
 .build()
 .to_dot(anchor=1, radius=8, direction="backward")
 .render())

Save intermediate results with .tap():

(viter(...).case(...).default(...).build()
 .tap(write(file="graph.json"))
 .to_dot()
 .render(file="out.svg"))

Use NetworkX for graph analysis via .filter():

import networkx as nx
(viter(...).case(...).default(...).build()
 .filter(NxFilter(nx.condensation))
 .to_dot()
 .render())

If-elif-else semantics (first matching case wins) via match=Match.FIRST:

(viter(range(1, 17), match=Match.FIRST)
 .case(lambda x: x % 2 == 0, lambda x: x // 2)
 .case(lambda x: x % 3 == 0, lambda x: x // 3)
 .default(lambda x: x * 5 + 7)
 .render())

Use the Python API directly (outside .vit files):

from visiter import viter

graph = (viter(range(1, 10))
         .case(lambda x: x % 3 == 0, lambda x: x // 3)
         .default(lambda x: x + 2)
         .build())
graph.to_dot().render(file="descent.svg")

Per-call edge labels via OpResult — for when the static label= is not enough and each step's edge should carry its own annotation:

from visiter import OpResult, viter

def odd_step(x):
    increased = 3 * x + 1
    div = (increased & -increased).bit_length() - 1
    return OpResult(increased >> div, label=f"3x+1, ÷2×{div}")

(viter([27])
 .case(lambda x: x % 2 == 0, lambda x: x // 2, label="÷2")
 .default(odd_step, label="3x+1")
 .render())

Performance & storage (optional)

Pure Python with JSON is the default and needs no toolchain. For large state spaces, three optional, additive features kick in — all producing the same graph, byte-for-byte:

• Native engine (engine="auto", the default once built). make native builds an optional Rust extension that runs the BFS bookkeeping natively for unbounded builds while keeping your Python callbacks. Falls back to pure Python when absent.

• Inline Rust callbacks (lang="rust") — for when the callbacks are the bottleneck. .case() takes Rust expression strings (value bound to s), compiled on the fly with rustc and run natively:

  (viter(10, lang="rust")
   .case("s >= 1", "s - 1", label="take 1")
   .case("s >= 2", "s - 2", label="take 2")
   .render())
  

• Columnar storage (pip install "visiter[storage]") — .vitgraph files (graph.to_vitgraph(...) / Graph.from_vitgraph(...)) are ~10–25× smaller than JSON and far faster to load for large graphs.

Details in the manual.

Why VisIter?

Free, scriptable, Graphviz-native orbit-graph rendering for discrete iterations under guarded rules — with cutoff boundaries (bounds, depth limits, render crops) as a first-class visual primitive, not silent truncation.

Full honest comparison against NetworkX, NestGraph (Mathematica), Maude, LoLA, and continuous-dynamics tooling: docs/comparison.md.

Documentation

• docs/tutorial.md — gentle introduction: what problem the tool solves, smallest example, what each piece does, what the dashed arrows mean. Start here.
• docs/manual.md — reference: every parameter, every data field, the rendering model in full, design decisions.
• docs/comparison.md — how VisIter relates to other tools in the ecosystem, and when to pick something else.
• demos/ — runnable .vit examples organized by topic (basics/, rendering/, integration/, applications/, rust/).

License

MIT