docs: Documenter.jl setup, tutorials, and API fixes

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+  statuses: write
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    name: Build and Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1.11'
+
+      - uses: julia-actions/cache@v2
+
+      - name: Install package and build Rust library
+        run: |
+          julia --project=docs -e '
+            using Pkg
+            Pkg.develop(PackageSpec(path=pwd()))
+            Pkg.instantiate()
+            Pkg.build("Tensor4all")
+          '
+
+      - name: Build and deploy documentation
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+        run: julia --project=docs docs/make.jl

AGENTS.md

@@ -1,5 +1,117 @@
 # AGENTS.md
 
+## API Design Principles
+
+Tensor4all.jl wraps tensor4all-rs (Rust) via C FFI. The API is layered:
+
+### C API layer (tensor4all-capi in Rust)
+- **General, multi-language primitives only.** If Python/C++ would also need it, put it here.
+- Examples: tensor contraction, TreeTN operations, index manipulation, TCI, quantics transforms
+- Do NOT add chain-specific or application-specific operations
+
+### Julia layer (this package)
+- **TreeTN-general.** Design APIs for arbitrary tree tensor networks, not just chains.
+- Chain-specific operations must include **runtime topology checks** (verify the TreeTN is a chain before proceeding).
+- **Build on C API primitives.** If an operation can be implemented using `ttn[v]` get/set + tensor contraction + index operations, implement it in Julia — do not add a new C API function.
+- Expose Rust functionality that isn't in C API yet only when it's general enough for multi-language use.
+
+### Type system: TensorTrain as the primary chain type
+`TensorTrain = TreeTensorNetwork{Int}` is the primary type for chain tensor networks. `MPS` and `MPO` are aliases for the same type — there is no type-level distinction.
+- MPS-like: each vertex has 1 site index
+- MPO-like: each vertex has 2 site indices (e.g., unprimed input + primed output)
+- `is_chain(ttn)`: runtime check that topology is a linear chain with vertices 1, 2, ..., n
+- `is_mps_like(tt)`: runtime check that each vertex has exactly 1 site index
+- `is_mpo_like(tt)`: runtime check that each vertex has exactly 2 site indices (unprimed + primed pair)
+- Operations that need a specific index structure check at runtime via these predicates.
+
+### Key available C API primitives for building Julia-level operations
+- `ttn[v]` / `ttn[v] = tensor` — get/set individual tensors at vertices
+- `siteinds(ttn, v)` — site indices at a vertex
+- `linkind(ttn, v1, v2)` — bond index between vertices
+- `vertices(ttn)`, `neighbors(ttn, v)` — topology queries
+- `contract(a, b)` — TreeTN-TreeTN contraction
+- `orthogonalize!`, `truncate!`, `inner`, `norm`, `to_dense`, `evaluate`
+
+### Known missing C API (should be added to tensor4all-rs)
+- **Tensor-Tensor contraction**: Exists in Rust (`TensorDynLen::contract`) but not exposed in C API. This is fundamental and multi-language useful.
+
+### Julia-level API to implement (using C API primitives)
+These should NOT go in the C API — they can be built from existing primitives once Tensor-Tensor contraction is exposed:
+- **Site summation**: Contract specific site indices on a TreeTN. Use `ttn[v]` + tensor contraction with sum vectors.
+- **Tensor diagonal embedding**: Create tensor diagonal in specific indices. Use Julia array operations + Tensor constructor.
+- **Partial site index replacement**: Replace specific site indices in TreeTN. Use `ttn[v]` get/set + index operations.
+- **Adding/removing site indices at a vertex**: For "MPO-like" structures — manipulate the tensor at a vertex to add primed copies of site indices. This is NOT a type conversion (MPS === MPO), just tensor manipulation.
+
+## Error Handling
+
+### Principle: fail early with actionable messages
+Users should never see a raw Rust panic or an opaque "Internal error". Errors must explain **what went wrong** and **how to fix it**.
+
+### Julia-side validation (prefer)
+Validate arguments in Julia **before** calling the C API. This produces familiar Julia stack traces and clear messages.
+- Check types, dimensions, and index compatibility before C calls
+- Use `ArgumentError` for invalid arguments, `DimensionMismatch` for shape mismatches
+- Include the actual vs expected values in the message: `"expected MPS with $n sites, got $(nv(ttn))"`
+- Runtime topology checks (`is_chain`, `is_mps_like`, `is_mpo_like`) must produce descriptive errors, not just `false`
+
+### Array contiguity check
+Julia arrays passed to the C API via pointer must be **contiguous in memory** (dense, column-major). Views, reshapes of non-contiguous data, `SubArray`, and `PermutedDimsArray` are NOT safe to pass directly.
+- Before any `ccall` that takes a `Ptr{T}` to array data, verify contiguity or convert: `data = collect(data)` if needed.
+- Use `Base.iscontiguous(A)` (Julia ≥ 1.11) or `stride(A,1) == 1 && strides match dense layout` to check.
+- Error message: `"Array must be contiguous in memory for C API. Got $(typeof(data)) with strides $(strides(data)). Use collect() to make a contiguous copy."`
+
+### Rust-side errors (propagate fully)
+When a C API call fails, `check_status` already retrieves `last_error_message()` from Rust. Rules:
+- **Never discard the Rust error message.** Always include it in the Julia exception.
+- If wrapping a C API call in a higher-level Julia function, add context: `"Failed to contract TTNs: $rust_msg"`
+- Rust error messages should describe the problem from the user's perspective, not internal Rust state.
+
+### Examples of good vs bad error messages
+```
+# Bad
+error("C API error: Internal error")
+error("Null pointer error")
+
+# Good
+error("Cannot apply Fourier operator: input MPS has $(nv(mps)) sites but operator expects $r sites")
+error("contract failed: input and operator have no common site indices. Did you call set_iospaces!() first?")
+```
+
+## Documentation Requirements
+
+### Docstring rules
+- Every exported type and function **must** have a docstring with a `# Examples` section.
+- Examples should be runnable `jldoctest` blocks where possible. Use `julia> ` prompts for testable examples.
+- For examples that require the Rust library or external state, use ` ```julia ... ``` ` fenced blocks (non-tested).
+- Module-level docstrings (`@doc` at the top of each module file) should include an end-to-end usage overview.
+
+### Documenter.jl site
+- Documentation is built with [Documenter.jl](https://documenter.juliadocs.org/) under `docs/`.
+- `docs/make.jl` generates the site; `docs/src/` contains manual pages.
+- PR checklist includes `julia --project=docs docs/make.jl` passing without errors.
+
+### Documentation structure
+- `docs/src/index.md` — overview, module dependency graph, and quick start
+- `docs/src/api.md` — auto-generated API reference via `@autodocs` (per-module sections)
+- `docs/src/modules.md` — module overview with dependency graph and data flow between modules
+- `docs/src/tutorials/` — pipeline-oriented guides that chain multiple modules:
+  - Quantics interpolation: QuanticsGrids → QuanticsTCI → SimpleTT → MPS
+  - Fourier analysis: QuanticsTCI → MPS → QuanticsTransform(fourier) → evaluate
+  - Affine transform on MPS: TreeTN → QuanticsTransform(affine) → TreeTN
+  - Tree TCI: TreeTCI → TreeTensorNetwork → operations
+
+### Module dependency graph
+```
+Core:  Index, Tensor, Algorithm (foundation types)
+         ↓
+SimpleTT ←→ TreeTN (bidirectional conversion)
+         ↓        ↓
+  QuanticsGrids   QuanticsTransform (operators on TreeTN)
+         ↓
+  QuanticsTCI     TreeTCI (outputs TreeTN)
+```
+Typical pipeline: **QuanticsGrids** (grid定義) → **QuanticsTCI** (関数補間→SimpleTT) → **TreeTN** (MPS変換・操作) → **QuanticsTransform** (Fourier/shift/affine演算) → **TreeTN** (結果評価)
+
 ## Known Issues
 
 ### Julia x64 segfault on AMD EPYC (primerose)
@@ -44,3 +156,4 @@ As of commit `ca97593` (PR #302), tensor4all-rs uses **column-major** storage fo
 ## PR Checklist
 
 - Before opening or updating a PR, review `README.md` and update user-facing examples and workflow notes if the API or expected commands changed.
+- Run `julia --project=docs docs/make.jl` and verify documentation builds without errors or missing docstring warnings.

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Tensor4all = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+
+[compat]
+Documenter = "1"

docs/make.jl

@@ -0,0 +1,36 @@
+using Documenter
+using Tensor4all
+
+makedocs(
+    sitename="Tensor4all.jl",
+    modules=[Tensor4all],
+    repo=Documenter.Remotes.GitHub("tensor4all", "Tensor4all.jl"),
+    pages=[
+        "Home" => "index.md",
+        "Modules" => "modules.md",
+        "API Reference" => [
+            "Core (Index, Tensor)" => "api/core.md",
+            "SimpleTT" => "api/simplett.md",
+            "TreeTN (MPS/MPO)" => "api/treetn.md",
+            "QuanticsGrids" => "api/quanticsgrids.md",
+            "QuanticsTCI" => "api/quanticstci.md",
+            "QuanticsTransform" => "api/quanticstransform.md",
+            "TreeTCI" => "api/treetci.md",
+        ],
+        "Tutorials" => [
+            "1D Quantics Interpolation" => "tutorials/quantics1d.md",
+            "1D Fourier Transform" => "tutorials/fourier1d.md",
+        ],
+    ],
+    format=Documenter.HTML(
+        prettyurls=get(ENV, "CI", "false") == "true",
+        canonical="https://tensor4all.github.io/Tensor4all.jl",
+    ),
+    warnonly=[:missing_docs],
+)
+
+deploydocs(
+    repo="github.com/tensor4all/Tensor4all.jl.git",
+    devbranch="main",
+    push_preview=true,
+)

docs/src/api/core.md

@@ -0,0 +1,56 @@
+# Core: Index, Tensor, Algorithm
+
+## Index
+
+```@docs
+Index
+dim
+tags
+id
+hastag
+plev
+sim
+prime
+noprime
+setprime
+hasind
+hasinds
+hascommoninds
+commoninds
+commonind
+common_inds
+uniqueinds
+uniqueind
+noncommoninds
+replaceinds
+replaceind
+onehot
+```
+
+## Tensor
+
+```@docs
+Tensor
+rank
+dims
+indices
+data
+storage_kind
+contract
+diag_embed
+diag_trace
+```
+
+## Storage Kinds
+
+```@docs
+StorageKind
+```
+
+## Algorithm
+
+```@docs
+Algorithm
+get_default_svd_rtol
+resolve_truncation_tolerance
+```

docs/src/api/quanticsgrids.md

@@ -0,0 +1,6 @@
+# QuanticsGrids
+
+```@autodocs
+Modules = [Tensor4all.QuanticsGrids]
+Order = [:type, :function]
+```

docs/src/api/quanticstci.md

@@ -0,0 +1,6 @@
+# QuanticsTCI
+
+```@autodocs
+Modules = [Tensor4all.QuanticsTCI]
+Order = [:type, :function]
+```

docs/src/api/quanticstransform.md

@@ -0,0 +1,6 @@
+# QuanticsTransform
+
+```@autodocs
+Modules = [Tensor4all.QuanticsTransform]
+Order = [:type, :function]
+```

docs/src/api/simplett.md

@@ -0,0 +1,6 @@
+# SimpleTT
+
+```@autodocs
+Modules = [Tensor4all.SimpleTT]
+Order = [:type, :function]
+```

docs/src/api/treetci.md

@@ -0,0 +1,6 @@
+# TreeTCI
+
+```@autodocs
+Modules = [Tensor4all.TreeTCI]
+Order = [:type, :function]
+```

docs/src/api/treetn.md

@@ -0,0 +1,6 @@
+# TreeTN (MPS / MPO / Tree Tensor Networks)
+
+```@autodocs
+Modules = [Tensor4all.TreeTN]
+Order = [:type, :function]
+```

docs/src/index.md

@@ -0,0 +1,47 @@
+# Tensor4all.jl
+
+A Julia wrapper for [tensor4all-rs](https://github.com/tensor4all/tensor4all-rs), providing tensor network operations via C FFI.
+
+## Features
+
+- **Index & Tensor**: Named indices with tags, prime levels, and automatic contraction
+- **SimpleTT**: Simple tensor trains with fixed site dimensions
+- **TreeTN (MPS/MPO)**: Tree tensor networks — MPS, MPO, and general tree topologies
+- **QuanticsGrids**: Coordinate transforms between physical grids and quantics (binary) representation
+- **QuanticsTCI**: Tensor cross interpolation in quantics representation
+- **QuanticsTransform**: Fourier, shift, flip, phase rotation, and affine operators on MPS
+- **TreeTCI**: TCI on arbitrary tree topologies
+
+## Quick Start
+
+```julia
+using Tensor4all
+using Tensor4all.QuanticsGrids
+using Tensor4all.QuanticsTCI
+using Tensor4all.TreeTN
+
+# Interpolate a function on a quantics grid
+R = 20  # 2^20 grid points
+grid = DiscretizedGrid{1}(R, 0.0, 1.0)
+f(x) = exp(-10x) * cos(100x)
+ci, ranks, errors = quanticscrossinterpolate(Float64, f, grid; tolerance=1e-8)
+
+# Convert to MPS for further operations
+tt = to_tensor_train(ci)
+mps = MPS(tt)
+```
+
+See the tutorials section in the sidebar for cross-module workflows.
+
+## Installation
+
+```julia
+using Pkg
+Pkg.add(url="https://github.com/tensor4all/Tensor4all.jl")
+```
+
+The Rust backend (`libtensor4all_capi`) is built automatically during `Pkg.build()`.
+
+## Module Overview
+
+See [Module Architecture](@ref) for the dependency graph and data flow.