Added RG tree API and visualization support

[Alphaharrius]

See #4

Summary

This change introduces qrg.tree.Node as a first-class tree abstraction for
renormalization group workflows and establishes the initial public tree API for
growth, navigation, structural inspection, path-based addressing, subtree
manipulation, transform access, and visualization.

The commit is foundational rather than incremental. It creates the tree module,
adds the package export surface, declares the plotting dependencies needed by
the new backends, adds typed-package metadata, and lands a large test suite
covering the new behavior.

Motivation

Before this change, the package did not expose a dedicated RG tree abstraction
that could:

• represent parent/child RG structure explicitly,
• address descendants by stable path expressions,
• detach and inspect subtrees,
• retrieve stepwise transforms between nodes,
• or visualize the tree directly with supported plotting backends.

This commit establishes that base layer so higher-level RG workflows can be
implemented against a coherent tree API instead of ad hoc data structures.

Main Changes

1. Introduce qrg.tree.Node

Add a new Node type in src/qrg/tree.py with:

• mapping-style tensor storage,
• root-owned growth method registration,
• child materialization through grow(),
• parent/leaf bookkeeping via _LeavePath,
• path-based navigation and subtree manipulation helpers.

2. Add foundational tree APIs

The new tree API includes:

• growth and registration:
  • register_method()
  • register_methods()
  • growth()
  • grow()
• tensor access:
  • target()
  • compute()
• navigation and addressing:
  • leaf()
  • branches()
  • parent()
  • root()
  • is_root()
  • is_leaf()
  • trace()
  • path()
• mutation:
  • cut()
• querying:
  • find()
• transform access:
  • get_transform()

These APIs make the tree usable as an operational RG object, not just a
container for tensors.

3. Add tree visualization backends

The plotting layer now supports tree rendering through:

• networkx
• matplotlib
• plotly

Important behavior:

• plot("tree") defaults to the matplotlib backend.
• plot("tree", backend="networkx") returns a structural graph view.
• plot("tree", backend="plotly") returns a real Plotly figure rather than a
  silent redirect.

4. Expose Node at package top level

Update src/qrg/__init__.py so users can write:

from qrg import Node

instead of importing only from qrg.tree.

5. Declare dependencies and typing metadata

Update project metadata to reflect the new plotting support:

• add matplotlib
• add plotly

Also add:

• src/qrg/py.typed

so mypy treats qrg as a typed package.

6. Add comprehensive tests

Introduce tests/test_tree.py covering:

• growth and parent-link behavior,
• root-registry method lookup,
• target and compute helpers,
• cut() behavior,
• branches(), is_root(), is_leaf(),
• trace() and path() round-tripping,
• explicit trace failure formatting,
• subtree search through find(),
• transform retrieval and composition through get_transform(),
• pickle round-trip behavior,
• method loading from annotated scripts,
• networkx, matplotlib, and plotly tree plotting behavior.

Design Notes

Addressing model

The tree uses parent leaf keys, not node.name, as the canonical structural
address. This is why:

• trace() consumes dot-delimited leaf-key paths,
• path() returns leaf-key paths,
• root.trace(node.path()) is node is a valid round-trip.

Transform semantics

get_transform() can return either:

• a composed transform tensor, or
• the stepwise transform list via composed=False.

The docstring explicitly warns that inverse/backward use may create very large
intermediates, especially for momentum-block tensors. The intended safer usage
for actual transport workflows is staged application via the stepwise list.

Plotting choice

matplotlib remains the default for plot("tree") to preserve a stable,
always-available static rendering path. plotly is supported explicitly rather
than through a misleading fallback.

Files Changed

• .gitignore
• pyproject.toml
• src/qrg/__init__.py
• src/qrg/py.typed
• src/qrg/tree.py
• tests/test_tree.py

Verification

The change was verified with:

uv run ruff check src tests
uv run --active mypy --no-incremental src
uv run --active mypy --no-incremental tests
uv run tox

Final status at the end of the work:

• ruff check: passed
• mypy src: passed
• mypy tests: passed
• tox: passed

Reviewer Notes

Reviewers should treat this as a foundational API introduction, not a narrow
follow-up patch. The most important review points are:

• whether the public tree API surface is coherent for RG workflows,
• whether leaf-key path addressing is the right canonical model,
• whether get_transform() exposes the correct exact semantics,
• whether the default plotting/backend behavior is appropriate,
• whether the current API is a good base for future staged transport helpers.

[Copilot]

Pull request overview

This PR introduces a foundational qrg.tree.Node API for RG tree construction, navigation, subtree operations, transform retrieval, and visualization, while exposing it at the package top level.

Changes:

• Adds the new Node tree abstraction with growth, traversal, mutation, search, transform, and plotting support.
• Adds plotting dependencies and typed-package metadata.
• Adds a comprehensive tree test suite and updates ignore rules.

Reviewed changes

Copilot reviewed 4 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/qrg/tree.py	Implements the new tree API and visualization backends.
src/qrg/__init__.py	Exposes Node as a top-level package export.
src/qrg/py.typed	Marks the package as typed.
pyproject.toml	Adds plotting dependencies.
tests/test_tree.py	Adds coverage for tree behavior and plotting.
.gitignore	Ignores notebooks.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.