tensor-network-editor 0.4.0

Interactive local editor for building tensor networks and generating Python code.

Tensor Network Editor

tensor-network-editor is a local Python package for drawing tensor networks, saving them as versioned JSON, and generating readable Python code for several backends.

It is useful when you want a visual editor without losing the things that make scientific Python workflows practical: plain data objects, files you can version, offline use, and generated code you can inspect.

Screenshots

Why This Project

• Draw tensor-network diagrams in a local browser session.
• Save and reload backend-independent JSON designs.
• Generate code for tensornetwork, quimb, tensorkrowch, einsum_numpy, and einsum_torch.
• Import supported Python network layouts from generated exports plus simple quimb, tensornetwork, and einsum / opt_einsum source files, or run explicit live imports for quimb and tensornetwork objects in a subprocess.
• Edit tensor initializers in the sidebar with generated zeros, ones, fill values, or explicit numeric JSON literals that round-trip through saved designs and supported generated Python.
• Create first-class hyperedges in normal mode, reposition their virtual hubs in the editor, and let exports lower them automatically into copy tensors plus binary edges for backend code.
• Use built-in templates for MPS, MPO, PEPS, MERA, and binary-tree layouts.
• Save reusable subnetworks into project or shared catalogs and reinsert them later with fresh ids, tags, and quick previews.
• Annotate tensors and indices with tags, guided metadata, and free-form JSON, then use metadata filters to inspect larger designs.
• Edit dimensions for one index or a multi-index selection from the sidebar or compact context menus.
• Work with linear, grid, and tree periodic modes and export them with any bundled backend.
• Reflow the current selection or the whole graph with Auto layout when imported or irregular networks need a cleaner arrangement.
• Inspect manual contraction paths and optional planner suggestions.
• Benchmark manual and automatic contraction variants from the editor or the CLI, with reproducible CSV/TXT/LaTeX-style tables.
• Use shortcut-driven editing for common actions such as adding tensors, adding indices, opening Reflow, moving between periodic cells, saving subnetworks, and confirming the session.
• Get structural analysis with FLOP and MAC cost summaries.
• Use the package from the CLI or directly from Python.

The editor opens in your browser, but the server runs locally on your own machine. No Node runtime or cloud service is needed for normal use.

Minimal Installation

The PyPI package name is tensor-network-editor. The Python import package is tensor_network_editor.

PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install tensor-network-editor

Bash:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install tensor-network-editor

For backend extras, planner support, source installs, and development setup, read docs/installation.md.

Basic Use

Launch the visual editor:

tensor-network-editor edit

This command starts a local server and waits until you press Done or Cancel in the browser session.

Open an existing design and save generated code when the session is confirmed:

tensor-network-editor edit --load my_network.json --engine quimb --save-code generated_network.py

Generate a reproducible benchmark table from one saved design:

tensor-network-editor benchmark my_network.json
tensor-network-editor benchmark my_network.json --dtype float32 --format csv --output benchmark.csv

Use the editor from Python:

from tensor_network_editor import open_editor


def main() -> None:
    result = open_editor()
    if result is None:
        print("Editor cancelled.")
        return

    print(f"Design name: {result.spec.name}")
    if result.codegen is not None:
        print(result.codegen.code)


if __name__ == "__main__":
    main()

Generate code without opening the editor:

from tensor_network_editor import EngineName, generate_code, load_spec


spec = load_spec("my_network.json")
result = generate_code(spec, engine=EngineName.EINSUM_NUMPY)
print(result.code)

Load a live quimb or tensornetwork object from Python source:

from tensor_network_editor import PythonLoadOptions, load_python_spec


spec = load_python_spec(
    python_source,
    python=PythonLoadOptions(
        import_mode="live",
        object_name="network",
    ),
)

This live mode executes the source in a subprocess with the active Python interpreter from your .venv, auto-detects one supported runtime object when possible, and falls back to python_object_name when several compatible globals exist.

Python imports also expose an explicit reconstruction contract through PythonLoadOptions(reconstruction_level="auto" | "simple" | "best_available"):

• auto keeps the richest supported result for the selected profile
• generated resolves auto to best_available, which preserves supported manual contraction steps
• external static profiles and live imports resolve auto to simple, which rebuilds only the portable network structure

When import_mode="live" is requested for generated source but the generated backend package is missing from the active .venv, the loader falls back to the static parser and reports that fallback as a warning instead of failing the whole load immediately.

Documentation

• Documentation index: where to go for each topic.
• Installation: full setup instructions.
• Getting started: first useful workflow.
• User guide: editor workflow, templates, reusable subnetworks, auto layout, planner, tips, benchmark mode, periodic modes, and limits.
• Python API: public functions and practical examples.
• Data models: NetworkSpec, tensors, edges, hyperedges, groups, notes, contraction plans, and periodic-mode payloads.
• CLI: terminal commands, subnetwork catalogs, benchmark/export workflows, and JSON output.
• Troubleshooting: common problems and fixes.

Current Limits

• Hyperedges are supported only in normal mode. They are lowered to generated copy tensors for export, re-imported generated Python stays in that lowered binary form, and planner/manual contraction editing plus benchmark mode are disabled while hyperedges exist in the design.
• Python import is intentionally conservative. It supports the package's own generated exports plus static AST patterns for simple quimb, tensornetwork, and einsum / opt_einsum sources. It also offers an explicit live-import mode for quimb and tensornetwork runtime objects, with static-parser fallback for generated sources when live imports fail because backend modules are unavailable. External and live imports still do not recover editor layout/groups/notes, rebuild manual contraction plans, or load periodic-mode Python back into editable specs.
• PythonLoadOptions(reconstruction_level="best_available") is currently only supported for the package's own generated Python profile. External static profiles and live imports use the portable simple reconstruction contract instead.
• Browser-based live import from the editor works best for self-contained scripts or imports already resolvable from the active .venv. If a Python file depends on sibling modules or path-sensitive imports, prefer the Python API or CLI with the real file path.
• Tensor values in the visual editor are currently limited to generated zeros, ones, fill values, and explicit numeric JSON literals. Symbolic initializers, random initializers, and direct .npy / .pt imports are not supported yet.
• TenPy code generation is not included.
• Linear, grid, and tree periodic code generation work with all bundled backends.
• Manual outer-product steps still cannot be exported safely to tensorkrowch.
• Planner/manual contraction editing is more limited in For bidimensional and For Tree than in normal or linear-periodic workflows.

Project Links

• Source code: github.com/DOKOS-TAYOS/Tensor-Network-Editor
• Changelog: CHANGELOG.md
• Example script: examples/basic_usage.py
• Issue tracker: github.com/DOKOS-TAYOS/Tensor-Network-Editor/issues
• License: LICENSE
• Third-party notices: THIRD_PARTY_LICENSES