# varipeps/varipeps_python architecture

> Architecture diagram of the GitHub repository varipeps/varipeps_python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/varipeps/varipeps_python
- Repository: https://github.com/varipeps/varipeps_python

## Overview

variPEPS is a Python tensor-network library for variational ground-state simulations on two-dimensional lattices. The core workflow initializes a PEPS unit cell, evaluates its environment with corner-transfer-matrix renormalization (CTMRG), computes model expectation values, then optimizes tensor parameters; observables such as overlaps and correlation lengths provide additional analysis. Lattice mappings, triangular and structure-factor CTMRG variants, and configurable tensor contractions support distinct model geometries. Connections below are limited to relationships explicitly documented in the README or visible in indexed source references; unsampled subsystem links are omitted where their callers are not shown.

Main entry points: [`varipeps/ctmrg/routine.py`](https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/routine.py) (CTMRG routines), [`varipeps/contractions/definitions.py`](https://github.com/varipeps/varipeps_python/blob/main/varipeps/contractions/definitions.py) (Tensor contractions), [`varipeps/optimization/optimizer.py`](https://github.com/varipeps/varipeps_python/blob/main/varipeps/optimization/optimizer.py) (Optimizer), [`varipeps/expectation/one_site.py`](https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/one_site.py) (Site observables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_state["PEPS state"]
  node_unitcell["PEPS unit cell<br/>[unitcell.py]"]
  node_tensor["PEPS tensors<br/>[tensor.py]"]
  node_random["Random initialization<br/>[random.py]"]
  node_mapping["Lattice mappings"]
end

subgraph group_environment["CTMRG environment"]
  node_ctmrg["CTMRG routines<br/>[routine.py]"]
  node_absorption["Boundary absorption<br/>[absorption.py]"]
  node_projectors["Projector calculation<br/>[projectors.py]"]
  node_triangular_ctmrg["Triangular CTMRG"]
  node_structure_ctmrg["Structure-factor CTMRG"]
end

subgraph group_physics["Models and observables"]
  node_model["Expectation models<br/>[model.py]"]
  node_expectation["Site observables<br/>[one_site.py]"]
  node_multi_expectation["Multi-site observables<br/>[two_sites.py]"]
  node_triangular_expectation["Triangular observables"]
  node_spiral["Spiral gates<br/>[spiral_helpers.py]"]
  node_correlation["Correlation length"]
  node_overlap["State overlap<br/>[overlap.py]"]
end

subgraph group_optimization["Variational optimization"]
  node_optimizer["Optimizer<br/>[optimizer.py]"]
  node_inner["Optimization objective<br/>[inner_function.py]"]
  node_line_search["Line search<br/>[line_search.py]"]
  node_retraction["Tensor retraction<br/>[retraction.py]"]
end

subgraph group_numerics["Numerical core"]
  node_contractions["Tensor contractions<br/>[definitions.py]"]
  node_svd["Differentiable SVD<br/>[svd.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_researcher(("Simulation user"))

node_researcher -.->|"sets up"| node_unitcell
node_researcher -.->|"runs optimization"| node_optimizer
node_unitcell -->|"uses tensors"| node_tensor
node_unitcell -->|"initializes with"| node_random
node_mapping -->|"uses observables"| node_expectation
node_mapping -->|"uses observables"| node_multi_expectation
node_ctmrg -->|"runs absorption"| node_absorption
node_ctmrg -->|"runs absorption"| node_triangular_ctmrg
node_absorption -->|"calculates projectors"| node_projectors
node_absorption -->|"applies contractions"| node_contractions
node_projectors -->|"applies contractions"| node_contractions
node_projectors -->|"decomposes tensors"| node_svd
node_structure_ctmrg -.->|"extends CTMRG"| node_ctmrg
node_ctmrg -->|"supports evaluation"| node_expectation
node_expectation -->|"implements models"| node_model
node_multi_expectation -->|"implements models"| node_model
node_triangular_expectation -->|"implements models"| node_model
node_triangular_expectation -->|"rotates gates"| node_spiral
node_multi_expectation -->|"rotates gates"| node_spiral
node_expectation -->|"applies contractions"| node_contractions
node_triangular_expectation -->|"applies contractions"| node_contractions
node_optimizer -->|"evaluates objective"| node_inner
node_optimizer -->|"selects steps"| node_line_search
node_optimizer -->|"retracts updates"| node_retraction
node_inner -->|"runs CTMRG"| node_ctmrg
node_inner -->|"maps model"| node_mapping
node_inner -->|"evaluates expectations"| node_expectation
node_correlation -->|"applies contractions"| node_contractions
node_overlap -->|"uses environment"| node_ctmrg
node_contractions -->|"uses PEPS tensors"| node_tensor
node_svd -->|"reads options"| node_config
node_optimizer -->|"reads options"| node_config

click node_unitcell "https://github.com/varipeps/varipeps_python/blob/main/varipeps/peps/unitcell.py"
click node_tensor "https://github.com/varipeps/varipeps_python/blob/main/varipeps/peps/tensor.py"
click node_random "https://github.com/varipeps/varipeps_python/blob/main/varipeps/utils/random.py"
click node_mapping "https://github.com/varipeps/varipeps_python/tree/main/varipeps/mapping"
click node_ctmrg "https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/routine.py"
click node_absorption "https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/absorption.py"
click node_projectors "https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/projectors.py"
click node_triangular_ctmrg "https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/triangular_absorption.py"
click node_structure_ctmrg "https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/structure_factor_routine.py"
click node_model "https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/model.py"
click node_expectation "https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/one_site.py"
click node_multi_expectation "https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/two_sites.py"
click node_triangular_expectation "https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/triangular_two_sites.py"
click node_spiral "https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/spiral_helpers.py"
click node_correlation "https://github.com/varipeps/varipeps_python/tree/main/varipeps/corrlength"
click node_overlap "https://github.com/varipeps/varipeps_python/blob/main/varipeps/overlap/overlap.py"
click node_optimizer "https://github.com/varipeps/varipeps_python/blob/main/varipeps/optimization/optimizer.py"
click node_inner "https://github.com/varipeps/varipeps_python/blob/main/varipeps/optimization/inner_function.py"
click node_line_search "https://github.com/varipeps/varipeps_python/blob/main/varipeps/optimization/line_search.py"
click node_retraction "https://github.com/varipeps/varipeps_python/blob/main/varipeps/optimization/retraction.py"
click node_contractions "https://github.com/varipeps/varipeps_python/blob/main/varipeps/contractions/definitions.py"
click node_svd "https://github.com/varipeps/varipeps_python/blob/main/varipeps/utils/svd.py"
click node_config "https://github.com/varipeps/varipeps_python/blob/main/varipeps/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_unitcell,node_tensor,node_random,node_mapping,node_researcher toneBlue
class node_ctmrg,node_absorption,node_projectors,node_triangular_ctmrg,node_structure_ctmrg toneAmber
class node_model,node_expectation,node_multi_expectation,node_triangular_expectation,node_spiral,node_correlation,node_overlap toneMint
class node_optimizer,node_inner,node_line_search,node_retraction toneRose
class node_contractions,node_svd,node_config toneIndigo
```

## Components

### PEPS state

- [PEPS unit cell](https://github.com/varipeps/varipeps_python/blob/main/varipeps/peps/unitcell.py): `varipeps/peps/unitcell.py`
- [PEPS tensors](https://github.com/varipeps/varipeps_python/blob/main/varipeps/peps/tensor.py): `varipeps/peps/tensor.py`
- [Random initialization](https://github.com/varipeps/varipeps_python/blob/main/varipeps/utils/random.py): `varipeps/utils/random.py`
- [Lattice mappings](https://github.com/varipeps/varipeps_python/tree/main/varipeps/mapping): `varipeps/mapping`

### CTMRG environment

- [CTMRG routines](https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/routine.py): `varipeps/ctmrg/routine.py`
- [Boundary absorption](https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/absorption.py): `varipeps/ctmrg/absorption.py`
- [Projector calculation](https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/projectors.py): `varipeps/ctmrg/projectors.py`
- [Triangular CTMRG](https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/triangular_absorption.py): `varipeps/ctmrg/triangular_absorption.py`
- [Structure-factor CTMRG](https://github.com/varipeps/varipeps_python/blob/main/varipeps/ctmrg/structure_factor_routine.py): `varipeps/ctmrg/structure_factor_routine.py`

### Models and observables

- [Expectation models](https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/model.py): `varipeps/expectation/model.py`
- [Site observables](https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/one_site.py): `varipeps/expectation/one_site.py`
- [Multi-site observables](https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/two_sites.py): `varipeps/expectation/two_sites.py`
- [Triangular observables](https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/triangular_two_sites.py): `varipeps/expectation/triangular_two_sites.py`
- [Spiral gates](https://github.com/varipeps/varipeps_python/blob/main/varipeps/expectation/spiral_helpers.py): `varipeps/expectation/spiral_helpers.py`
- [Correlation length](https://github.com/varipeps/varipeps_python/tree/main/varipeps/corrlength): `varipeps/corrlength`
- [State overlap](https://github.com/varipeps/varipeps_python/blob/main/varipeps/overlap/overlap.py): `varipeps/overlap/overlap.py`

### Variational optimization

- [Optimizer](https://github.com/varipeps/varipeps_python/blob/main/varipeps/optimization/optimizer.py): `varipeps/optimization/optimizer.py`
- [Optimization objective](https://github.com/varipeps/varipeps_python/blob/main/varipeps/optimization/inner_function.py): `varipeps/optimization/inner_function.py`
- [Line search](https://github.com/varipeps/varipeps_python/blob/main/varipeps/optimization/line_search.py): `varipeps/optimization/line_search.py`
- [Tensor retraction](https://github.com/varipeps/varipeps_python/blob/main/varipeps/optimization/retraction.py): `varipeps/optimization/retraction.py`

### Numerical core

- [Tensor contractions](https://github.com/varipeps/varipeps_python/blob/main/varipeps/contractions/definitions.py): `varipeps/contractions/definitions.py`
- [Differentiable SVD](https://github.com/varipeps/varipeps_python/blob/main/varipeps/utils/svd.py): `varipeps/utils/svd.py`
- [Runtime configuration](https://github.com/varipeps/varipeps_python/blob/main/varipeps/config.py): `varipeps/config.py`

### Other components

- **Simulation user**

## Connections

- Simulation user → PEPS unit cell: sets up (evidence: `README.md`)
- Simulation user → Optimizer: runs optimization (evidence: `README.md`)
- PEPS unit cell → PEPS tensors: uses tensors (evidence: `varipeps/peps/unitcell.py`)
- PEPS unit cell → Random initialization: initializes with (evidence: `varipeps/peps/unitcell.py`)
- Lattice mappings → Site observables: uses observables (evidence: `varipeps/mapping/kagome.py`)
- Lattice mappings → Multi-site observables: uses observables (evidence: `varipeps/mapping/maple_leaf.py`)
- CTMRG routines → Boundary absorption: runs absorption (evidence: `varipeps/ctmrg/routine.py`)
- CTMRG routines → Triangular CTMRG: runs absorption (evidence: `varipeps/ctmrg/routine.py`)
- Boundary absorption → Projector calculation: calculates projectors (evidence: `varipeps/ctmrg/absorption.py`)
- Boundary absorption → Tensor contractions: applies contractions (evidence: `varipeps/ctmrg/absorption.py`)
- Projector calculation → Tensor contractions: applies contractions (evidence: `varipeps/ctmrg/projectors.py`)
- Projector calculation → Differentiable SVD: decomposes tensors (evidence: `varipeps/ctmrg/projectors.py`)
- Structure-factor CTMRG → CTMRG routines: extends CTMRG
- CTMRG routines → Site observables: supports evaluation
- Site observables → Expectation models: implements models (evidence: `varipeps/expectation/one_site.py`)
- Multi-site observables → Expectation models: implements models (evidence: `varipeps/expectation/two_sites.py`)
- Triangular observables → Expectation models: implements models (evidence: `varipeps/expectation/triangular_two_sites.py`)
- Triangular observables → Spiral gates: rotates gates (evidence: `varipeps/expectation/triangular_two_sites.py`)
- Multi-site observables → Spiral gates: rotates gates (evidence: `varipeps/expectation/two_sites.py`)
- Site observables → Tensor contractions: applies contractions (evidence: `varipeps/expectation/one_site.py`)
- Triangular observables → Tensor contractions: applies contractions (evidence: `varipeps/expectation/triangular_two_sites.py`)
- Optimizer → Optimization objective: evaluates objective (evidence: `varipeps/optimization/optimizer.py`)
- Optimizer → Line search: selects steps (evidence: `varipeps/optimization/optimizer.py`)
- Optimizer → Tensor retraction: retracts updates (evidence: `varipeps/optimization/optimizer.py`)
- Optimization objective → CTMRG routines: runs CTMRG (evidence: `varipeps/optimization/inner_function.py`)
- Optimization objective → Lattice mappings: maps model (evidence: `varipeps/optimization/inner_function.py`)
- Optimization objective → Site observables: evaluates expectations (evidence: `varipeps/optimization/inner_function.py`)
- Correlation length → Tensor contractions: applies contractions (evidence: `varipeps/corrlength/corrlength.py`)
- State overlap → CTMRG routines: uses environment (evidence: `varipeps/overlap/overlap.py`)
- Tensor contractions → PEPS tensors: uses PEPS tensors
- Differentiable SVD → Runtime configuration: reads options (evidence: `varipeps/utils/svd.py`)
- Optimizer → Runtime configuration: reads options (evidence: `varipeps/optimization/optimizer.py`)
