Skip to content

installation.md

Latest commit

 

History

History
246 lines (178 loc) · 6.09 KB

installation.md

File metadata and controls

246 lines (178 loc) · 6.09 KB
Raw

Installation

This page covers normal installation, optional extras, source installs, and development setup.

Contents

Requirements

  • Python 3.11 or newer
  • A virtual environment, usually named .venv
  • Windows PowerShell or a Linux shell

The distribution name is tensor-network-editor. The import package name is tensor_network_editor.

Normal editor use does not require Node.js. The browser UI is bundled in the Python package and served by a local Python process.

Install From PyPI

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

After activation, python and pip should point to the virtual environment. That keeps project dependencies separate from the rest of your machine.

The published source distribution and wheel include LICENSE and THIRD_PARTY_LICENSES. THIRD_PARTY_LICENSES documents bundled assets shipped inside this package. Optional extras installed from PyPI are not vendored into this package and keep their own upstream licenses.

Optional Extras

Install extras only when you need them.

Backend extras:

python -m pip install "tensor-network-editor[numpy]"
python -m pip install "tensor-network-editor[torch]"
python -m pip install "tensor-network-editor[quimb]"
python -m pip install "tensor-network-editor[tensornetwork]"
python -m pip install "tensor-network-editor[tensorkrowch]"

The numpy extra installs NumPy for generated einsum_numpy code. The torch extra installs PyTorch for generated einsum_torch code and is also useful before running PyTorch-backed examples. The base package now includes matplotlib for academic SVG/PNG/PDF exports and opt_einsum for automatic greedy contraction suggestions.

Desktop extra:

python -m pip install "tensor-network-editor[desktop]"

The desktop extra installs pywebview for environments that want a desktop webview dependency available. After installing it, you can launch the editor in its own native window with tensor-network-editor edit --ui pywebview or EditorLaunchOptions(ui_mode="pywebview"). The standard default workflow is still the local browser editor.

You can combine extras:

python -m pip install "tensor-network-editor[numpy,quimb]"

Use backend extras when you want generated code to run in the same environment. If you only want to generate source text, the editor can still do that without installing the backend package.

Install From Source

From a local checkout:

python -m pip install .

Use this when you want the repository version instead of the published PyPI version.

Development Setup

PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[dev]"

Bash:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"

Useful development checks:

python -m ruff check . --fix
python -m ruff format .
python -m ruff format --check .
python -m mypy
python -m pyright
python -m pytest
python -m build
python -m twine check dist/*

Optional backend checks used by CI:

PowerShell:

python -m pip install -e ".[dev,tensornetwork,quimb]"
$env:TNE_REQUIRE_OPTIONAL_BACKENDS = "1"
python -m pytest -q -m optional_backend
Remove-Item Env:\TNE_REQUIRE_OPTIONAL_BACKENDS

Bash:

python -m pip install -e ".[dev,tensornetwork,quimb]"
TNE_REQUIRE_OPTIONAL_BACKENDS=1 python -m pytest -q -m optional_backend

Browser smoke checks need Playwright and a browser install:

PowerShell:

python -m pip install playwright
python -m playwright install chromium
$env:TNE_RUN_BROWSER_SMOKE = "1"
python -m pytest -q -m browser
Remove-Item Env:\TNE_RUN_BROWSER_SMOKE

Bash:

python -m pip install playwright
python -m playwright install chromium
TNE_RUN_BROWSER_SMOKE=1 python -m pytest -q -m browser

If you change package metadata such as the version, rerun the editable install in the active .venv so the installed metadata stays aligned with the checkout:

python -m pip install -e ".[dev]"

If you work with git worktrees, remember that one shared .venv can only point its editable install at one checkout at a time. After switching to another worktree, rerun the editable install there if you want that checkout to be the one imported by python:

python -m pip install -e ".[dev]"
python -c "from pathlib import Path; import tensor_network_editor; print(Path(tensor_network_editor.__file__).resolve())"

Check the Installation

Check that the CLI is available:

tensor-network-editor --help

Check that Python can import the package:

python -c "import tensor_network_editor; print(tensor_network_editor.__version__)"

Check which checkout Python is importing:

python -c "from pathlib import Path; import tensor_network_editor; print(Path(tensor_network_editor.__file__).resolve())"

If you need more environment detail while debugging the CLI, enable logs:

tensor-network-editor --log-level debug --help

Launch the editor:

tensor-network-editor edit

If the browser does not open, see troubleshooting.md#the-browser-did-not-open-automatically.

If you prefer a native desktop window instead of the browser, install the desktop extra and launch:

tensor-network-editor edit --ui pywebview

Cleanup Scripts

The repository includes cleanup scripts for generated local artifacts:

  • Windows: .\scripts\clean.bat
  • Linux: ./scripts/clean.sh

They are useful during development, not required for normal package use.