Skip to content

Commit c0fecc0

Browse files
emstoudenmireemsflatironmtfishman
authored
Document interface of library (#346)
This PR adds documentation of which methods we may consider "interface", and thus should keep and add docstrings for, versus deprecated methods we may want to delete. Methods not in the two files `interface_methods.md` and `deprecated_methods.md` are considered internal, developer-facing methods. --------- Co-authored-by: Miles Stoudenmire <mstoudenmire@flatironinstitute.org> Co-authored-by: Matthew Fishman <mtfishman@users.noreply.github.com>
1 parent 2f4ab3d commit c0fecc0

6 files changed

Lines changed: 1453 additions & 1 deletion

File tree

‎Project.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
name = "ITensorNetworks"
22
uuid = "2919e153-833c-4bdc-8836-1ea460a35fc7"
3-
version = "0.19.6"
3+
version = "0.19.7"
44
authors = ["Matthew Fishman <mfishman@flatironinstitute.org>, Joseph Tindall <jtindall@flatironinstitute.org> and contributors"]
55

66
[workspace]

‎docs/make.jl‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,12 @@ makedocs(;
4242
"Computing Properties" => "computing_properties.md",
4343
"Solvers" => "solvers.md",
4444
],
45+
"Developer Reference" => [
46+
"Interface Methods" => "interface_methods.md",
47+
"Developer Methods" => "developer_methods.md",
48+
"Experimental Methods" => "experimental_methods.md",
49+
"Deprecated Methods" => "deprecated_methods.md",
50+
],
4551
"API Reference" => "reference.md",
4652
]
4753
)

‎docs/src/deprecated_methods.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Deprecated Methods
2+
3+
Suggestions of methods which could be deleted.
4+
5+
## ITensorNetwork Methods
6+
7+
#### ITensorNetwork Constructors
8+
9+
* Default constructor (`itensornetwork.jl`).
10+
```julia
11+
ITensorNetwork{V}()
12+
```
13+
14+
* (Only actually deprecate / delete this function if the more generic constructor `ITensorNetwork(tensors)` can also handle this case.)
15+
From a vector of `ITensor`s, with vertex labels auto-assigned to `eachindex(ts)`.
16+
Edges are inferred from shared indices (`itensornetwork.jl`):
17+
```julia
18+
ITensorNetwork(ts::AbstractVector{ITensor})
19+
```
20+
21+
* From a collection of ITensorNetworks. Merges (Kronecker or tensor product) of input networks (`itensornetwork.jl`):
22+
```julia
23+
ITensorNetwork(itns::Vector{ITensorNetwork})
24+
```
25+
26+
* From a named graph, forwards to construction from `IndsNetwork` (`itensornetwork.jl`):
27+
```julia
28+
ITensorNetwork{V}(g::NamedGraph)
29+
ITensorNetwork(eltype::Type, undef::UndefInitializer, graph::AbstractNamedGraph; kws...)
30+
ITensorNetwork(f, graph::AbstractNamedGraph; kwargs...)
31+
ITensorNetwork(graph::AbstractNamedGraph; kwargs...)
32+
```
33+
34+
* From a simple graph, forwards to construction from `IndsNetwork` (`itensornetwork.jl`):
35+
```julia
36+
ITensorNetwork(eltype::Type, undef::UndefInitializer, graph::AbstractSimpleGraph; kws...)
37+
ITensorNetwork(f, graph::AbstractSimpleGraph; kwargs...)
38+
ITensorNetwork(graph::AbstractSimpleGraph; kwargs...)
39+
```
40+
41+
* From a function over vertices or from a "value" (e.g. a string like `"Up"`,
42+
an `Op`, an array, or a per-vertex dict/array) that is converted to a callable and used
43+
to initialize each vertex tensor (`itensornetwork.jl`):
44+
```julia
45+
ITensorNetwork(value, is::IndsNetwork; kwargs...)
46+
ITensorNetwork(elt::Type, f, is::IndsNetwork; link_space = trivial_space(is), kws...)
47+
ITensorNetwork(itensor_constructor::Function, is::IndsNetwork; link_space = trivial_space(is), kwargs...)
48+
```
49+
50+
* From a single `ITensor`. Wraps the tensor in a single-vertex network (`itensornetwork.jl`):
51+
```julia
52+
ITensorNetwork(t::ITensor)
53+
```
54+
55+
* Construct an `ITensorNetwork` from an `IndsNetwork`. Initializes ITensors with `undef` storage on each vertex
56+
of the `IndsNetwork` with the corresponding indices (`itensornetwork.jl`):
57+
```julia
58+
ITensorNetwork(eltype::Type, undef::UndefInitializer, is::IndsNetwork; kwargs...)
59+
ITensorNetwork(eltype::Type, is::IndsNetwork; kwargs...)
60+
ITensorNetwork(undef::UndefInitializer, is::IndsNetwork; kwargs...)
61+
ITensorNetwork(is::IndsNetwork; kwargs...)
62+
```
63+
64+
#### Local Operations on ITensorNetworks
65+
66+
* Versions of `siteinds` taking a `vertex` argument. Each of these is just an alias for `uniqueinds`. Possibly the wrong design / implementation. (`abstractitensornetwork.jl`).
67+
```julia
68+
siteinds(tn::AbstractITensorNetwork, vertex) # abstractitensornetwork.jl:288
69+
siteinds(tn::AbstractITensorNetwork, vertex::Int) # abstractitensornetwork.jl:292
70+
```
71+
72+
73+
* Functions in `apply.jl` which are unused, even inside that file (`apply.jl`):
74+
```julia
75+
_gate_vertices(o::ITensor, ψ)
76+
_gate_vertices(o::AbstractEdge, ψ)
77+
_contract_gate(o::ITensor, ψv1, Λ, ψv2)
78+
_contract_gate(o::AbstractEdge, ψv1, Λ, ψv2)
79+
```
80+
81+
* Collection of tensors neighboring the given vertex (`abstractitensornetwork.jl`):
82+
```julia
83+
neighbor_tensors(tn::AbstractITensorNetwork, vertex)
84+
```
85+
86+
* Iterate over the tensors at the given vertices, default all vertices (`abstractitensornetwork.jl`):
87+
```julia
88+
eachtensor(tn::AbstractITensorNetwork, vertices = vertices(tn))
89+
```
90+
91+
* Indices on the source tensor of `edge` that are not shared with the destination tensor.
92+
(`abstractitensornetwork.jl`):
93+
```julia
94+
uniqueinds(tn::AbstractITensorNetwork, edge::AbstractEdge)
95+
uniqueinds(tn::AbstractITensorNetwork, edge::Pair)
96+
```
97+
98+
* Alias for `uniqueinds` (`abstractitensornetwork.jl`):
99+
```julia
100+
siteinds(tn::AbstractITensorNetwork, vertex)
101+
siteinds(tn::AbstractITensorNetwork, vertex::Int)
102+
```
103+
104+
* Indices common to the ITensors on the vertices connected by the edge (`abstractitensornetwork.jl`):
105+
(Use a set function like `intersection` instead.)
106+
```julia
107+
commoninds(tn::AbstractITensorNetwork, edge)
108+
linkinds(tn::AbstractITensorNetwork, edge)
109+
```
110+
111+
* Indices on `tn[vertex]` that aren't shared with any neighbor, i.e. the external/site
112+
indices of that vertex (`abstractitensornetwork.jl`).
113+
(Use a set function like `setdiff` instead.)
114+
```julia
115+
uniqueinds(tn::AbstractITensorNetwork, vertex)
116+
```
117+
118+
## Global Operations on ITensorNetworks
119+
120+
121+
## TreeTensorNetwork Constructors
122+
123+
* From `Op` and related types (`opsum_to_ttn.jl`):
124+
```julia
125+
ttn(o::Op, s::IndsNetwork; kws...)
126+
ttn(o::Scaled{C, Op}, s::IndsNetwork; kws...)
127+
ttn(o::Sum{Op}, s::IndsNetwork; kws...)
128+
ttn(o::Prod{Op}, s::IndsNetwork; kws...)
129+
ttn(o::Scaled{C, Prod{Op}}, s::IndsNetwork; kws...)
130+
ttn(o::Sum{Scaled{C, Op}}, s::IndsNetwork; kws...)
131+
```
132+
133+
## Miscellaneous Methods
134+
135+
* Methods in `partitioneditensornetwork.jl`.
136+
```julia
137+
linkinds(pitn::PartitionedGraph, edge::QuotientEdge)
138+
```
139+
To be revisited after Jack's work on NamedGraphs.
140+
141+
* Methods in `graphs.jl`.
142+
Just one methods which constructs a `SimpleGraph` from ITensors (`graphs.jl`).
143+
```julia
144+
SimpleGraphs.SimpleGraph(itensors::Vector{ITensor})
145+
```
146+
Not used anywhere in library.
147+
148+
* Methods in `update_observer.jl`. Not used anywhere in library.

0 commit comments

Comments
 (0)