symtenet 0.1.0__tar.gz

symtenet-0.1.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+# Keep the GitHub Actions pins fresh: one grouped PR per month, after a 7-day
+# cooldown on each release. Python deps are deliberately absent -- uv resolves
+# fresh on every CI run, so a dependency bump PR would duplicate that signal.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    cooldown:
+      default-days: 7
+    groups:
+      actions:
+        patterns: ["*"]

symtenet-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# A superseded push to the same PR cancels the run it replaced; pushes to main
+# always run to completion so every merge commit keeps its own green check.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    # `uv run pytest` is the whole job: everything else -- both syncs, the doctests,
+    # the torch subset and the docs build -- totals 45 s measured. The suite runs on
+    # xdist workers (see `addopts`), which measured 517 s -> 139 s locally; the
+    # runner is ~2x slower still, so warm runs land well inside 10 min; 30 is the cap
+    # a cold cache and a slow runner still have to fit in.
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      # Before pytest so a type error fails in seconds, not minutes. Measured
+      # 0.2 s locally on the warm uvx cache (#166); ty is a single static binary
+      # resolved by uvx, so no new dependency group. Unpinned deliberately: ty is
+      # alpha and its fixes land fast; if an upgrade ever breaks the gate, pin
+      # with `uvx ty@<version> check`.
+      - run: uvx ty check src/tenet
+      - run: uv run pytest
+      # The docstring examples plus the Getting started / guide pages and the
+      # tutorials whose problems run in seconds (#167). A separate step, not part of
+      # the suite: testpaths stays ["tests"]. The md paths are explicit — the remaining tutorial and example
+      # pages carry code blocks that are not doctests, so the glob reaches only the
+      # ones named here.
+      - run: uv run pytest --doctest-modules src/tenet --doctest-glob='*.md' docs/getting-started.md docs/guide docs/tutorials/symmetric-tensors.md docs/tutorials/dmrg.md docs/tutorials/fermions.md docs/tutorials/su2.md
+      # Appended to the same job, not a matrix axis: the torch-relevant subset is a
+      # few dozen tests and the suite is minutes, so running everything twice
+      # buys nothing. The step above is unchanged, so a torch failure can never
+      # redden the primary suite. CPU wheels; see [tool.uv.sources] (#95).
+      - run: uv sync --extra torch
+      - run: uv run pytest tests/backends/test_torch.py
+      # Same reasoning: one appended step, not a job. --strict turns every unresolved
+      # nav entry and internal link into a failure, which is the whole check (#118).
+      # A broken docs build reddens CI; the deploy lives in docs.yml and cannot.
+      - run: uv run --group docs mkdocs build --strict
+
+  # A separate job, not a step in `test` (#145): coverage instrumentation measured
+  # +63% on the suite locally, which the primary job should not pay.
+  # Non-blocking: a hiccup here never reddens the primary suite, and there is no
+  # --cov-fail-under gate — the percentage is published (badge via docs.yml), not
+  # enforced.
+  coverage:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv run pytest -q --cov=src/tenet --cov-report=xml
+      # docs.yml downloads this to render the README's coverage badge on Pages.
+      - uses: actions/upload-artifact@v7
+        with:
+          name: coverage-xml
+          path: coverage.xml
+      # Codecov beside the self-hosted badge: the Pages badge is the
+      # dependency-free number; codecov adds per-PR coverage diffs and history.
+      # Tokenless upload (public repo); non-fatal like the rest of this job.
+      - uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

symtenet-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Docs
+
+# Deploy only. The build *check* is a step in ci.yml's test job, so a broken docs
+# build reddens a PR; this workflow only ever runs after main already moved (#118).
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read # download ci.yml's coverage artifact for the badge (#145)
+  pages: write
+  id-token: write
+
+# One live site: let a running deploy finish rather than cancelling it mid-publish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv run --group docs mkdocs build --strict
+      # The coverage badge (#145): rendered from the newest successful CI run on
+      # main rather than re-running the suite here — measuring belongs to ci.yml,
+      # publishing to Pages belongs here. On the very first deploy (or if CI for
+      # this push is still running) the newest artifact can lag one commit or be
+      # absent; a missing badge 404s in the README until the next deploy, which
+      # is why the step is non-fatal.
+      - name: Coverage badge
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          run_id=$(gh run list --workflow ci.yml --branch main --status success \
+            --limit 1 --json databaseId -q '.[0].databaseId')
+          if [ -n "$run_id" ] && gh run download "$run_id" -n coverage-xml -D cov; then
+            uvx --from 'genbadge[coverage]' genbadge coverage \
+              -i cov/coverage.xml -o site/coverage-badge.svg
+          else
+            echo "no coverage artifact yet; badge deferred to the next deploy"
+          fi
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

symtenet-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+# Trusted publishing (OIDC, no tokens): a v* tag dry-runs the artifact through
+# TestPyPI; publishing a GitHub release ships the same artifact to PyPI. Pure
+# Python, so `uv build` replaces the cibuildwheel matrix C-extension projects need.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - run: uvx twine check --strict dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - if: github.event_name == 'push'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - if: github.event_name == 'release'
+        uses: pypa/gh-action-pypi-publish@release/v1

symtenet-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+site/
+.coverage
+coverage.xml
+benchmarks/.cache/
+.claude/

symtenet-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

symtenet-0.1.0/AGENTS.md

@@ -0,0 +1,96 @@
+# AGENTS.md
+
+Guide for coding agents (and humans) working in this repository.
+
+## What this project is
+
+`symtenet`: non-Abelian symmetric tensors with ndarray-style Python APIs and
+backend-native numerical execution. **`docs/design.md` is the design document.**
+Read the relevant section of it before implementing anything; it defines the
+architecture, milestones, and invariants. `REPOSITORY_RULES.md` defines
+process rules.
+
+Three-layer architecture (never blur these):
+
+```text
+mathematical model   TensorMap semantics  (Hom(D,C), duality, fusion, F/R)
+programming model    SymmetricTensor      (ordered ndarray-like legs)
+execution model      backend-native reduced arrays (NumPy / JAX / PyTorch via autoray)
+```
+
+## Commands
+
+```bash
+uv sync                  # install (creates .venv, includes dev deps)
+uv run pytest            # run tests
+uv run ruff check .      # lint
+uv run ruff format .     # format
+```
+
+CI runs exactly: `ruff check`, `ruff format --check`, `pytest`. All must pass.
+
+## Layout
+
+```text
+src/tenet/       library code (src layout; see "Proposed package structure" in docs/design.md)
+tests/           pytest tests, mirroring src/tenet/ structure
+```
+
+## Design invariants (condensed from docs/design.md — full list there is authoritative)
+
+1. Every `SymmetricTensor` has exact TensorMap semantics: `domain`/`codomain`
+   derived from leg metadata.
+2. `side` (IN/OUT) and `dual` are independent. Never identify input with dual.
+3. Public axis order is independent of domain/codomain grouping.
+4. Fusion trees / intermediate sectors / multiplicities are tensor-level
+   structure, never stored on individual `Leg`s.
+5. Categorical operations are never *defined* by backend array operations;
+   backend ops only implement lowered plans.
+6. Reduced blocks contain only degeneracy indices; sector labels are metadata.
+7. Reduced block axis order follows public tensor axis order, not
+   codomain × domain.
+8. Numerical leaves are backend-native arrays: the tensor holds
+   `data: tuple[Array, ...]`, one dense matrix per coupled sector, and
+   `blocks: tuple[Array, ...]` ordered by `structure.block_order` is the public
+   view of it. Every operation reads `data`; `blocks` is for interop and for
+   reading a tensor apart, and reading it cuts every block out of the matrices.
+   `TensorStructure` is immutable, hashable, and array-free — F/R and other coefficient arrays never go in
+   structural fields. Do not subclass `numpy.ndarray` / `jax.Array` /
+   `torch.Tensor`.
+9. No implicit densification. Dense expansion only via explicit `to_dense()`.
+10. Structural planning (categorical analysis) is separated from numerical
+    execution; plans are static and cacheable. Structural logic runs in
+    Python on static metadata (so JAX tracing / torch AD see only array
+    ops); structure-changing operations (truncation, sector selection) live
+    outside JIT/compile boundaries or use static shapes/masks.
+11. Expose an ndarray-style operation only when its categorical meaning is
+    defined; unsupported operations fail loudly.
+12. Never invent an implicit braid convention. If an expression does not
+    uniquely specify a braid, require explicit input.
+
+## Coding rules
+
+- Symmetry-specific math goes through capability protocols — `FusionRules` for
+  structure, the `*Data` protocols (`FMatrixData`, `BendingCoefficients`, ...)
+  for the coefficients a category is defined by, `*Provider` for a concrete
+  symmetry. No `if symmetry == "su2":` branching in core code.
+- Test non-Abelian behavior with SU(2) from the start; Abelian-only tests can
+  hide wrong assumptions (external sectors ≠ complete fusion basis).
+- Where feasible, validate numerical operations against explicit dense
+  expansion in tests.
+- A PR that adds a symmetry provider or a public operation updates
+  `tests/COVERAGE.md` in the same diff: a provider names its column and the
+  cells it fills; an operation names its row and the providers and modes it
+  runs under. Any cell left empty carries one of the four classifications —
+  genuine gap (with a follow-up), structurally redundant (with the argument),
+  out of contract (with the refusal test), or blocked (with what blocks it) —
+  in one line.
+- Structural/categorical types are immutable (frozen dataclasses or similar).
+- Backend abstraction is `autoray` only; keep it thin, don't build a second
+  numerical framework. Framework-specific optimization (`jit`, `grad`,
+  `torch.compile`) is application-level (symmray/quimb model).
+- Integration surface: `get_params`/`set_params` (quimb-compatible) is core;
+  JAX PyTree registration is opt-in via `tenet.pytree` (import-guarded, core
+  never imports jax/torch).
+- Follow the milestone order in docs/design.md ("Initial implementation strategy")
+  unless told otherwise.

symtenet-0.1.0/CITATION.cff

@@ -0,0 +1,15 @@
+cff-version: 1.2.0
+message: "If you use symtenet in your research, please cite it as below."
+title: "symtenet: a Python library for symmetric tensor networks — a NumPy-style API on the surface, category theory under the hood"
+type: software
+authors:
+  - family-names: "Watanabe"
+    given-names: "Ryo"
+repository-code: "https://github.com/Ryo-wtnb11/symtenet"
+url: "https://ryo-wtnb11.github.io/symtenet/"
+license: Apache-2.0
+abstract: >-
+  A symmetric tensor Python library for tensor networks with Abelian,
+  fermionic and non-Abelian symmetries: graded tensors over U(1), Z2,
+  fermionic Z2, SU(2) and SU(N), differentiable through JAX, with
+  automatic MPO construction, DMRG and CTMRG.

symtenet-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Ryo Watanabe
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

symtenet-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: symtenet
+Version: 0.1.0
+Summary: Non-Abelian symmetric tensors with ndarray-style Python APIs and backend-native numerical execution
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: autoray>=0.10.1
+Requires-Dist: numpy>=2.0
+Requires-Dist: opt-einsum>=3.4.0
+Requires-Dist: racah-py>=0.1.2
+Provides-Extra: jax
+Requires-Dist: jax>=0.10; extra == 'jax'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# symtenet
+
+[![tests](https://github.com/Ryo-wtnb11/symtenet/actions/workflows/ci.yml/badge.svg)](https://github.com/Ryo-wtnb11/symtenet/actions/workflows/ci.yml)
+[![coverage](https://ryo-wtnb11.github.io/symtenet/coverage-badge.svg)](https://github.com/Ryo-wtnb11/symtenet/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Ryo-wtnb11/symtenet/graph/badge.svg)](https://codecov.io/gh/Ryo-wtnb11/symtenet)
+[![docs](https://img.shields.io/badge/docs-online-blue.svg)](https://ryo-wtnb11.github.io/symtenet/)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/Ryo-wtnb11/symtenet/blob/main/LICENSE)
+[![python](https://img.shields.io/badge/python-%E2%89%A53.12-blue.svg)](https://github.com/Ryo-wtnb11/symtenet/blob/main/pyproject.toml)
+
+**A Python library for symmetric tensor networks: NumPy-ish API on the surface, category theory under the hood.**
+
+`tenet` gives you block-sparse tensors that carry a symmetry exactly — SU(N), SU(2),
+U(1), Z2, fermion parity and their products — through exact recoupling coefficients.
+A tensor carries legs, contracts with `tenet.einsum` and factorizes with `tenet.linalg`,
+the way an ndarray does. Blocks live in NumPy, JAX or PyTorch arrays through
+[`autoray`](https://github.com/jcmgray/autoray), so the same tensor runs under
+`jax.jit` and `jax.grad` with its symmetry structure intact. On top of the tensor layer,
+`tenet.network` ships finite DMRG and CTMRG.
+
+## Install
+
+```sh
+uv add symtenet         # or: pip install symtenet
+```
+
+The core install pulls `numpy`, `autoray`, `opt-einsum` and `racah-py`, and every
+symmetry works on it. Two optional extras:
+
+```sh
+uv add "symtenet[jax]"      # jax>=0.10 — pytrees, jit, grad
+uv add "symtenet[torch]"    # torch>=2.0 — eager blocks
+```
+
+## Quickstart
+
+A 20-site spin-1/2 Heisenberg chain, U(1)-graded by `2 S^z`, to its ground state:
+
+```python
+from tenet.models import spin_half
+from tenet.network import MPO, MPS, dmrg_
+from tenet.symmetry import U1Sector
+
+site, n = spin_half(), 20
+terms = []
+for i in range(n - 1):
+    terms.append((1.0, [(site.ops["Sz"], i), (site.ops["Sz"], i + 1)]))
+    terms.append((0.5, [(site.ops["S+"], i), (site.ops["S-"], i + 1)]))
+    terms.append((0.5, [(site.ops["S-"], i), (site.ops["S+"], i + 1)]))
+
+h = MPO.from_terms(n, terms)
+psi = MPS.product(site.phys, [U1Sector(1 if i % 2 else -1) for i in range(n)])
+out = dmrg_(psi, h, chi=64)
+
+print(out.sweeps, out.energy)          # 6 -8.682473334398...
+print(out.psi.entanglement_entropy())  # {bond: S}, in nats
+```
+
+The Néel product state's own charges put the run in the `S^z_tot = 0` sector, and the
+site tensors' invariance keeps it there — no projector, no penalty term.
+[Getting started](https://ryo-wtnb11.github.io/symtenet/getting-started/) reads this
+example line by line.
+
+With the `jax` extra, the same tensors are JAX pytrees: `jit`, `grad` and `vmap` reach
+through to the blocks while the symmetry structure stays static.
+
+```python
+import jax
+import tenet
+
+tenet.enable_jax()
+
+t = out.psi[0].to_backend("jax")
+g = jax.jit(jax.grad(lambda x: tenet.norm(x) ** 2))(t)
+assert g.legs == t.legs
+```
+
+## What it supports
+
+- **Symmetries.** SU(N), SU(2), U(1), Z2, fermion parity (`fZ2`) and Deligne products
+  of any of them. Non-Abelian sectors are multiplets with exact Clebsch-Gordan,
+  F- and R-symbols; fermionic wires carry their Koszul signs.
+- **Tensors.** `SymmetricTensor` over a flat tuple of `Leg`s, one reduced block per
+  allowed fusion channel. `einsum`, `tensordot`, `compose`, `transpose`, `fuse`,
+  `repartition`, `trace`, and `tenet.linalg`'s `svd`, `qr`, `lq`, `eigh`, `eig`,
+  `polar`, `expm`, `left_null`, plus the truncating `svd_truncated` / `eigh_truncated`.
+- **Algorithms.** Finite two-site DMRG (`dmrg_`, schedules, noise, excited states) with
+  MPS/MPO containers, environment caches and measurement; CTMRG on the directional
+  `EnvCTM` and its C4v specialization `EnvCTMc4v`, with a differentiable fixed-bond move.
+- **Backends.** NumPy, JAX and PyTorch blocks through `autoray`. `tenet.enable_jax()`
+  registers `SymmetricTensor` as a JAX pytree, so `jit`, `grad` and `vmap` reach the
+  blocks while the structure stays static metadata.
+
+## Docs
+
+- [Getting started](https://ryo-wtnb11.github.io/symtenet/getting-started/) — install and the first example.
+- [User guide](https://ryo-wtnb11.github.io/symtenet/guide/tensors-legs-spaces/) — tensors, symmetries, contraction, Hamiltonians, DMRG, truncation, JAX, files.
+- [Tutorials](https://ryo-wtnb11.github.io/symtenet/tutorials/dmrg/) — DMRG, fermions, SU(2), quantum chemistry, CTMRG, VMC.
+- [Examples](https://ryo-wtnb11.github.io/symtenet/examples/) — runnable files with their committed output.
+- [API reference](https://ryo-wtnb11.github.io/symtenet/api/tenet/) — every public name.
+- [`docs/design.md`](https://ryo-wtnb11.github.io/symtenet/design/) — the categorical model underneath.
+- [`REPOSITORY_RULES.md`](https://github.com/Ryo-wtnb11/symtenet/blob/main/REPOSITORY_RULES.md) — process rules for contributing.
+
+## Citation
+
+If you use symtenet in your research, please cite it:
+
+```bibtex
+@software{symtenet,
+  author  = {Watanabe, Ryo},
+  title   = {{symtenet}: a {Python} library for symmetric tensor networks
+             --- a {NumPy}-style {API} on the surface, category theory under
+             the hood},
+  url     = {https://github.com/Ryo-wtnb11/symtenet},
+  license = {Apache-2.0},
+  year    = {2026}
+}
+```
+
+The same metadata lives in
+[`CITATION.cff`](https://github.com/Ryo-wtnb11/symtenet/blob/main/CITATION.cff) —
+GitHub's "Cite this repository" button renders it as BibTeX or APA.
+
+## License
+
+Apache License 2.0 — see [`LICENSE`](https://github.com/Ryo-wtnb11/symtenet/blob/main/LICENSE).