OMEinsum.jl

https://under-peter.github.io/OMEinsum.jl/dev/
Admin
OMEinsum.jl is a Julia package that provides the einsum notation, similar to numpy's einsum, and...
Tokens:25,386
Snippets:325
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Setting the cuTENSOR Backend

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Example of how to enable the cuTENSOR backend for OMEinsum. Ensure CUDA.jl and cuTENSOR are installed and configured.

```julia
using CUDA, cuTENSOR, OMEinsum

# Enable cuTENSOR backend
set_einsum_backend!(CuTensorBackend())
```

--------------------------------

### Example Usage of @ein_str Macro

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Shows an example of using the `@ein_str` macro for a sequence of tensor contractions, demonstrating the equivalence of different parenthesizations and the numpy-style string macro.

```julia
julia> a, b, c = rand(10,10), rand(10,10), rand(10,1)

julia> ein"ij,jk,kl -> il"(a,b,c) ≈ ein"(ij,jk),kl -> il"(a,b,c) ≈ a * b * c
true
```

--------------------------------

### Construct Diagonal Matrix Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Shows how to construct a diagonal matrix from a vector using Einsum notation. Input is i, and the output is ii.

```text
i->ii
```

--------------------------------

### Define Tensors for Einsum Examples

Source: https://under-peter.github.io/OMEinsum.jl/dev/basic

Initializes scalar, vector, matrix, and 3D tensor variables used in subsequent Einsum examples. Requires the OMEinsum package.

```julia
using OMEinsum
s = fill(1)
 w, v = [1, 2], [4, 5]
A, B = [1 2; 3 4], [5 6; 7 8]
T1, T2 = reshape(1:8, 2, 2, 2), reshape(9:16, 2, 2, 2)
```

--------------------------------

### Example Usage of EinCode

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Illustrates the creation and inspection of an `EinCode` object for matrix multiplication, showing how to retrieve input and output indices.

```julia
julia> code = OMEinsumContractionOrders.EinCode([[1,2], [2, 3]], [1, 3])
1∘2, 2∘3 -> 1∘3

julia> OMEinsumContractionOrders.getixsv(code)
2-element Vector{Vector{Int64}}:
 [1, 2]
 [2, 3]

julia> OMEinsumContractionOrders.getiyv(code)
2-element Vector{Int64}:
 1
 3
```

--------------------------------

### Element-wise Product Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Illustrates element-wise product of two tensors using Einsum notation. Input tensors are ij and ij, resulting in an output of ij.

```text
ij,ij->ij
```

--------------------------------

### Example Usage of @ein Macro

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Demonstrates the usage of the `@ein` macro for tensor contractions, showing equivalence to standard matrix multiplication and the `ein` string macro.

```julia
julia> a, b = rand(2,2), rand(2,2)

julia> @ein c[i,k] := a[i,j] * b[j,k]

julia> c ≈ a * b
true

julia> c ≈ ein"ij,jk -> ik"(a,b)
true
```

--------------------------------

### Check CUDA Artifacts and cuTENSOR Detection

Source: https://under-peter.github.io/OMEinsum.jl/dev/cuda

Prints detailed information about the CUDA installation, including whether cuTENSOR is detected and its version. Useful for troubleshooting installation issues.

```julia
using CUDA
CUDA.versioninfo()
```

--------------------------------

### Batched Matrix Multiplication Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Illustrates batched matrix multiplication with Einsum notation. Input tensors are ijl and jkl, resulting in an output of ikl.

```text
ijl,jkl->ikl
```

--------------------------------

### EinArray Constructor Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Constructs an EinArray from an EinCode, input tensors, and a size dictionary. It represents an intermediate result of an einsum operation.

```julia
julia> using OMEinsum: get_size_dict

julia> a, b = rand(2,2), rand(2,2);

julia> sd = get_size_dict((('i','j'),('j','k')), (a, b));

julia> ea = OMEinsum.einarray(Val((('i','j'),('j','k'))),Val(('i','k')), (a,b), sd);

julia> dropdims(sum(ea, dims=1), dims=1) ≈ a * b
true
```

--------------------------------

### Matrix Multiplication Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Demonstrates matrix multiplication using Einsum notation. The input tensors are A{i,j} and B{j,k}, and the output is {i,k}.

```text
ij,jk->ik
```

--------------------------------

### Trace Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Illustrates how to compute the trace of a tensor using Einsum notation. Input tensor is ii, and the output is an empty string, signifying a scalar result.

```text
ii->
```

--------------------------------

### Outer Product Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Shows how to compute the outer product of two tensors using Einsum notation. Input tensors are ij and kl, resulting in an output of ijkl.

```text
ij,kl->ijkl
```

--------------------------------

### Tensor Dimension Permutation Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Illustrates permuting the dimensions of a tensor using Einsum notation. Input tensor is ijkl, and the output is ilkj.

```text
ijkl->ilkj
```

--------------------------------

### Star Contraction Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Demonstrates a star contraction using Einsum notation with input tensors ij, ik, and il, resulting in an output of jkl.

```text
ij,ik,il->jkl
```

--------------------------------

### Diagonal Part Extraction Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Demonstrates how to extract the diagonal part of a matrix using Einsum notation. Input tensor is ii, and the output is i.

```text
ii->i
```

--------------------------------

### Summation Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Shows how to perform a summation over all elements of a tensor using Einsum notation. Input tensor is ij, and the output is an empty string, signifying a scalar result.

```text
ij->
```

--------------------------------

### Example Usage of @ein! Macro

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Illustrates the usage of the `@ein!` macro for inplace tensor contractions, including assignment, addition, and subtraction, with verification against standard multiplication and the `ein` string macro.

```julia
julia> a, b, c, d = rand(2,2), rand(2,2), rand(2,2), zeros(2,2)

julia> cc = copy(c)

julia> @ein! d[i,k] := a[i,j] * b[j,k]

julia> d ≈ a * b
true

julia> d ≈ ein"ij,jk -> ik"(a,b)
true

julia> @ein! c[i,k] += a[i,j] * b[j,k]

julia> c ≈ cc + a * b
true

julia> @ein! c[i,k] -= a[i,j] * b[j,k]

julia> c ≈ cc
true
```

--------------------------------

### loop_einsum! Method Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

An inplace version of loop_einsum that stores the result in a pre-allocated tensor 'y'. It performs the core tensor contraction logic.

```julia
julia> # Example usage for loop_einsum! would go here, but is not provided in the source.
```

--------------------------------

### Matrix Vector Multiplication Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Shows matrix-vector multiplication using Einsum notation. Input tensors are ij and j, producing an output of i.

```text
ij,j->i
```

--------------------------------

### einsum! Function Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Inplace version of einsum that stores the result in a pre-allocated output tensor. Allows scaling of input and output tensors.

```julia
julia> # Example usage for einsum! would go here, but is not provided in the source.
```

--------------------------------

### Performance Comparison with DefaultBackend

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Benchmarks the performance of Einsum contractions using the DefaultBackend on CUDA arrays. This example highlights the overhead associated with the default backend for GPU operations.

```julia
using BenchmarkTools

A = CUDA.rand(Float32, 64, 64, 64)
B = CUDA.rand(Float32, 64, 64, 64)

# DefaultBackend: requires permute + reshape + GEMM + reshape
set_einsum_backend!(DefaultBackend())
@btime CUDA.@sync ein"ijk,jkl->il"($A, $B)
```

--------------------------------

### Check CUDA.jl Package Status

Source: https://under-peter.github.io/OMEinsum.jl/dev/cuda

Verifies the installed version of the CUDA.jl package, which is a prerequisite for using cuTENSOR.

```julia
using Pkg
Pkg.status("CUDA")
```

--------------------------------

### Check cuTENSOR Availability

Source: https://under-peter.github.io/OMEinsum.jl/dev/cuda

Verifies if the cuTENSOR library is installed and available for use with OMEinsum. This check is crucial before attempting to use the cuTENSOR backend.

```julia
using CUDA
using cuTENSOR  # Must be loaded to enable the cuTENSOR backend
using OMEinsum

# Check if cuTENSOR is available
if cuTENSOR.has_cutensor()
    println("cuTENSOR is available!")
else
    println("cuTENSOR is not available")
end

```

--------------------------------

### indices_and_locs Method Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Given input and output index labels for an einsum operation, this method returns distinct output labels, input labels not in the output, and their locations within the input and output structures.

```julia
julia> # Example usage for indices_and_locs would go here, but is not provided in the source.
```

--------------------------------

### filliys! Method Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Iterates through NestedEinsumConstructor objects to save the correct 'iy' (output indices) within them. This is an internal helper method.

```julia
julia> # Example usage for filliys! would go here, but is not provided in the source.
```

--------------------------------

### loop_einsum Method Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Performs a tensor contraction based on an EinCode and input tensors, using a provided size dictionary. This is a core function for evaluating einsum operations.

```julia
julia> # Example usage for loop_einsum would go here, but is not provided in the source.
```

--------------------------------

### einsum_grad Method Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Calculates the gradient of an einsum evaluation with respect to a specific input tensor. Requires the input tensors, output, size dictionary, and the index of the tensor for which the gradient is computed.

```julia
julia> using OMEinsum: einsum_grad, get_size_dict

julia> a, b = rand(2,2), rand(2,2);

julia> c = einsum(EinCode((('i','j'),('j','k')), ('i','k')), (a,b));

julia> sd = get_size_dict((('i','j'),('j','k')), (a,b));

julia> einsum_grad((('i','j'),('j','k')), (a,b), ('i','k'), sd, c, 1) ≈ c * transpose(b)
true
```

--------------------------------

### Broadcast Scalar to Diagonal Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/background

Demonstrates broadcasting a scalar to the diagonal part of a matrix using Einsum notation. The input is an empty string (scalar), and the output is ii.

```text
->ii
```

--------------------------------

### get_size_dict! Method Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Verifies consistency of input indices and tensors, then returns a dictionary for retrieving the size of index labels. Used internally for size management.

```julia
julia> # Example usage for get_size_dict! would go here, but is not provided in the source.
```

--------------------------------

### einsum Function Example

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Computes the tensor resulting from contracting input tensors according to a specified einsum code. Supports EinCode, NestedEinsum, and SlicedEinsum.

```julia
julia> a, b = rand(2,2), rand(2,2);

julia> einsum(EinCode((('i','j'),('j','k')),('i','k')), (a, b)) ≈ a * b
true
```

```julia
julia> einsum(EinCode((('i','j'),('j','k')),('k','i')), (a, b)) ≈ permutedims(a * b, (2,1))
true
```

--------------------------------

### Get Output Index of Einsum Notation

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Returns the output index for an einsum notation. This function is useful for understanding the structure of the einsum expression.

```julia
getiyv(code::AbstractEinsum) -> Vector{LT}
```

--------------------------------

### Get Output Tensor Labels

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Retrieves the labels of the output tensor for einsum objects. Returns a vector containing the output labels.

```julia
julia> getiyv(ein"(ij,jk),k->i")
1-element Vector{Char}:
 'i': ASCII/Unicode U+0069 (category Ll: Letter, lowercase)
```

--------------------------------

### Get Current Einsum Backend

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Retrieves the currently active global einsum backend. This is useful for checking if a specific backend like CuTensorBackend is in use.

```julia
backend = get_einsum_backend()
if backend isa CuTensorBackend
    println("Using cuTENSOR")
else
    println("Using default BLAS/CUBLAS")
end
```

--------------------------------

### Execute and get result for Peterson graph 3-coloring

Source: https://under-peter.github.io/OMEinsum.jl/dev/applications

Executes the defined tensor contraction 'code' for the Peterson graph, filling in the tensors with 's'. It returns 0, indicating no valid 3-colorings exist.

```julia
code(fill(s, 10)...)[]
```

--------------------------------

### Enable and Use cuTENSOR Backend

Source: https://under-peter.github.io/OMEinsum.jl/dev/cuda

Demonstrates how to globally set OMEinsum to use the cuTENSOR backend for GPU operations. It also shows how to reset to the default backend after use. Ensure cuTENSOR.jl is loaded first.

```julia
using CUDA
using cuTENSOR  # ← Required! This loads the CuTENSORExt extension
using OMEinsum

# Set the backend globally
set_einsum_backend!(CuTensorBackend())

# Now all GPU einsum operations will use cuTENSOR
A = CUDA.rand(Float32, 100, 200, 300)
B = CUDA.rand(Float32, 200, 300, 400)
C = ein"ijk,jkl->il"(A, B)  # Uses cuTENSOR

# Reset to default backend
set_einsum_backend!(DefaultBackend())

```

--------------------------------

### Get Lazy Einsum Entry

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Returns the lazily calculated entry of an EinArray at the specified indices.

```julia
getindex(A::EinArray, inds...)
```

--------------------------------

### Basic CUDA Usage and Benchmarking

Source: https://under-peter.github.io/OMEinsum.jl/dev/cuda

Demonstrates how to perform an optimized tensor contraction on the GPU using OMEinsum and CUDA.jl. It includes steps for defining the contraction, optimizing the code, and benchmarking performance on both CPU and GPU.

```julia
using CUDA, OMEinsum

code = ein"ij,jk,kl,li->"

A, B, C, D = rand(1000, 1000), rand(1000, 300), rand(300, 800), rand(800, 1000)

size_dict = OMEinsum.get_size_dict(getixsv(code), (A, B, C, D))

optcode = optimize_code(code, size_dict, TreeSA())

```

```julia
using BenchmarkTools

@btime optcode($A, $B, $C, $D)

```

```julia
cuA, cuB, cuC, cuD = CuArray(A), CuArray(B), CuArray(C), CuArray(D)

@btime CUDA.@sync optcode($cuA, $cuB, $cuC, $cuD)

```

--------------------------------

### OMEinsumContractionOrders.getiyv

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Returns the output index of the einsum notation.

```APIDOC
## OMEinsumContractionOrders.getiyv

### Description
Returns the output index of the einsum notation.

### Method
```julia
getiyv(code::AbstractEinsum) -> Vector{LT}
```
```

--------------------------------

### Performance Comparison: Default vs. cuTENSOR Backend

Source: https://under-peter.github.io/OMEinsum.jl/dev/cuda

Compares the performance of a non-GEMM tensor contraction using OMEinsum on the GPU with both the DefaultBackend (CUBLAS) and the CuTensorBackend (cuTENSOR). This highlights the benefits of cuTENSOR for complex patterns.

```julia
using CUDA
using cuTENSOR  # Required for cuTENSOR backend
using OMEinsum, BenchmarkTools

# Create test tensors (non-GEMM pattern)
A = CUDA.rand(Float32, 64, 64, 64)
B = CUDA.rand(Float32, 64, 64, 64)

# Benchmark with DefaultBackend (CUBLAS)
set_einsum_backend!(DefaultBackend())
@btime CUDA.@sync ein"ijk,jkl->il"($A, $B)
# Requires: permute → reshape → GEMM → reshape

# Benchmark with CuTensorBackend
set_einsum_backend!(CuTensorBackend())
@btime CUDA.@sync ein"ijk,jkl->il"($A, $B)

```

--------------------------------

### Direct Tensor Contraction with CuTensorBackend

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Demonstrates direct tensor contraction using the CuTensorBackend for GPU acceleration. Requires CUDA.jl and OMEinsum.

```julia
set_einsum_backend!(CuTensorBackend())
@btime CUDA.@sync ein"ijk,jkl->il"($A, $B)
```

--------------------------------

### Get Label Data Type

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Returns the data type used to represent labels within the einsum notation. This is a type-query function for einsum labels.

```julia
labeltype(code::AbstractEinsum) -> Type
```

--------------------------------

### Get Label Elimination Order

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Returns a vector of labels sorted by their elimination order in the contraction tree. The contraction tree is defined by the input `code`.

```julia
label_elimination_order(code) -> Vector
```

--------------------------------

### Treewidth Optimizer Initialization

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Initializes the Treewidth optimizer with a specified elimination algorithm. The default algorithm is SafeRules.

```julia
optimizer = Treewidth();
```

--------------------------------

### Get Input Indices of Einsum Notation

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Returns the input indices for an einsum notation. Each inner vector represents the labels associated with an input tensor.

```julia
getixsv(code::AbstractEinsum) -> Vector{Vector{LT}}
```

--------------------------------

### Check Current Einsum Backend

Source: https://under-peter.github.io/OMEinsum.jl/dev/basic

Retrieves and displays the currently active computation backend for OMEinsum.

```julia
get_einsum_backend()
```

--------------------------------

### Set Default Einsum Backend

Source: https://under-peter.github.io/OMEinsum.jl/dev/basic

Configures OMEinsum to use the default backend, typically involving BLAS/CUBLAS via reshape/permute.

```julia
set_einsum_backend!(DefaultBackend())
```

--------------------------------

### Nested Contractions with cuTENSOR Backend

Source: https://under-peter.github.io/OMEinsum.jl/dev/cuda

Shows how to set the cuTENSOR backend, optimize a contraction code, and execute it on GPU arrays for nested tensor network contractions.

```julia
using CUDA, cuTENSOR, OMEinsum

set_einsum_backend!(CuTensorBackend())

# Define a tensor network
code = ein"ij,jk,kl,lm->im"

# Optimize contraction order
size_dict = Dict('i'=>100, 'j'=>100, 'k'=>100, 'l'=>100, 'm'=>100)
optcode = optimize_code(code, size_dict, TreeSA())

# Execute with cuTENSOR (each pairwise contraction uses cuTENSOR)
A, B, C, D = [CUDA.rand(Float32, 100, 100) for _ in 1:4]
result = optcode(A, B, C, D)
```

--------------------------------

### Get Unique Labels from Einsum Code

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Returns a vector of unique labels (indices) present in an AbstractEinsum object. Useful for understanding the structure of the tensor network.

```python
OMEinsumContractionOrders.uniquelabels(code::AbstractEinsum) -> Vector{LT}
```

--------------------------------

### Visualize Einsum Code as Tensor Network Graph

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Visualizes an AbstractEinsum object as a tensor network graph using GraphViz. Can display the graph on screen or save it to a file. Supports custom layouts and display configurations.

```python
OMEinsumContractionOrders.viz_eins(code::AbstractEinsum; locs=StressLayout(), filename = nothing, kwargs...)
```

--------------------------------

### OMEinsum.get_einsum_backend

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Retrieves the currently active global einsum backend. This allows users to check which backend (e.g., CuTENSOR, default BLAS/CUBLAS) is being used for computations.

```APIDOC
## OMEinsum.get_einsum_backend

### Description
Get the current global einsum backend.

### Returns
The currently active `EinsumBackend` instance.

### Example
```julia
backend = get_einsum_backend()
if backend isa CuTensorBackend
    println("Using cuTENSOR")
else
    println("Using default BLAS/CUBLAS")
end
```

### See Also
`set_einsum_backend!`, `EinsumBackend`
```

--------------------------------

### Perform Matrix Multiplication using @ein_str

Source: https://under-peter.github.io/OMEinsum.jl/dev/basic

Demonstrates matrix multiplication using the `@ein_str` macro directly within a function call. It also shows how to retrieve the size dictionary for labels and use the lower-level `einsum` and `einsum!` functions.

```julia
A, B = randn(2, 3), randn(3, 4)
code1(A, B)
size_dict = OMEinsum.get_size_dict(getixsv(code1), (A, B))
einsum(code1, (A, B), size_dict)
einsum!(code1, (A, B), zeros(2, 4), true, false, size_dict)
```

--------------------------------

### Optimized String Macro for Einsum (@optein_str)

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

The `@optein_str` macro is similar to `@ein_str` but provides optimized contraction order, assuming uniform dimensions.

```julia
optein"ij,jk,kl -> ik"(A, B, C)
```

--------------------------------

### OMEinsum.filliys!

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Recursively traverses a tree of `NestedEinsumConstructor` objects and assigns the correct `iy` (output index labels) to each.

```APIDOC
## OMEinsum.filliys!

### Description
Goes through all `NestedEinsumConstructor` objects in the tree and saves the correct `iy` in them.

### Method Signature
```julia
filliys!(neinsum::NestedEinsumConstructor)
```
```

--------------------------------

### PathSA Optimizer Configuration

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Optimizes einsum contraction patterns using simulated annealing on a tensor expression tree with path decomposition. Parameters control the annealing schedule, number of trials, and iterations.

```julia
PathSA(; βs=0.01:0.05:15, ntrials=10, niters=50, score=ScoreFunction())
```

--------------------------------

### Get Input Tensor Labels

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Retrieves the labels of input tensors for various einsum objects like EinCode and NestedEinsum. Returns a vector of vectors, where each inner vector represents the labels for one input tensor.

```julia
julia> getixsv(ein"(ij,jk),k->i")
3-element Vector{Vector{Char}}:
 ['i', 'j']
 ['j', 'k']
 ['k']
```

--------------------------------

### viz_eins

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Visualizes an AbstractEinsum object by generating a GraphViz graph. It supports specifying node layout and output filename, or displaying the graph directly.

```APIDOC
## viz_eins

### Description
Visualizes an `AbstractEinsum` object by creating a tensor network graph and rendering it using GraphViz.

### Method
`viz_eins(code::AbstractEinsum; locs=StressLayout(), filename = nothing, kwargs...)

### Parameters
#### Arguments
* `code::AbstractEinsum`: The `AbstractEinsum` object to visualize.

#### Keyword Arguments
* `locs=StressLayout()`: The coordinates or layout algorithm to use for positioning the nodes.
* `filename = nothing`: The name of the file to save the visualization to. If `nothing`, the visualization will be displayed on the screen.
* `config = GraphDisplayConfig()`: The configuration for displaying the graph.
* `kwargs...`: Additional keyword arguments to be passed to the `GraphViz` constructor.
```

--------------------------------

### Setting DefaultBackend for Tensor Contractions

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Configures OMEinsum to use the DefaultBackend, which leverages BLAS/CUBLAS for tensor contractions by reducing them to matrix multiplications. This is suitable for matrix-like contractions.

```julia
set_einsum_backend!(DefaultBackend())
ein"ij,jk->ik"(A, B)  # Uses BLAS gemm
```

--------------------------------

### SABipartite Optimizer Configuration

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Optimizes einsum contraction order using simulated annealing with bipartite partitioning. It includes parameters for target space complexity, annealing schedule, number of trials, iterations, and group size.

```julia
SABipartite(; sc_target=25, ntrials=50, βs=0.1:0.2:15.0, niters=1000
    max_group_size=40, greedy_config=GreedyMethod(), initializer=:random)
```

--------------------------------

### Set Einsum Backend

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Globally sets the backend for einsum operations. This is useful for specifying hardware acceleration like CuTensor.

```julia
set_einsum_backend!(CuTensorBackend())
```

--------------------------------

### HyperND Optimizer Configuration

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Configures the Nested-dissection based optimizer. It recursively partitions a tensor network and applies greedy algorithms to the leaves. Parameters control recursion depth, width, scaling of index weights, and partitioning algorithms.

```julia
HyperND(;
    dis = KaHyParND(),
    algs = (MF(), AMF(), MMD()),
    level = 6,
    width = 120,
    scale = 100,
    imbalances = 130:130,
    score = ScoreFunction(),
)
```

--------------------------------

### viz_contraction

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Visualizes the tensor network contraction process, creating an animation. It allows customization of layout, framerate, output filename, and progress display.

```APIDOC
## viz_contraction

### Description
Visualize the contraction process of a tensor network.

### Method
`viz_contraction(code::Union{NestedEinsum, SlicedEinsum}; locs=StressLayout(), framerate=10, filename=tempname() * ".mp4", show_progress=true)`

### Parameters
#### Arguments
* `code`: The tensor network to visualize.

#### Keyword Arguments
* `locs`: The coordinates or layout algorithm to use for positioning the nodes (default: `StressLayout()`).
* `framerate`: The frame rate of the animation (default: 10).
* `filename`: The name of the output file (default: a temporary file with `.mp4` extension).
* `show_progress`: Whether to show progress information (default: `true`).

### Returns
* The path of the generated file.
```

--------------------------------

### Inplace Macro for Tensor Contraction (@ein!)

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

The `@ein!` macro provides an inplace interface for tensor contractions, similar to other packages. It supports assignment, addition, and subtraction.

```julia
@ein! A[i,k] := B[i,j] * C[j,k]     # A = B * C
@ein! A[i,k] += B[i,j] * C[j,k]     # A += B * C
@ein! A[i,k] -= B[i,j] * C[j,k]     # A -= B * C
```

--------------------------------

### Visualize Tensor Network Contraction Process

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Visualizes the contraction process of a tensor network. Generates an animation (MP4 or GIF) of the contraction. Allows customization of layout, frame rate, and output filename.

```python
OMEinsumContractionOrders.viz_contraction(code::Union{NestedEinsum, SlicedEinsum}; locs=StressLayout(), framerate=10, filename=tempname() * ".mp4", show_progress=true)
```

--------------------------------

### Keep Data on GPU for cuTENSOR Operations

Source: https://under-peter.github.io/OMEinsum.jl/dev/cuda

Demonstrates the recommended way to perform Einstein summations using cuTENSOR by keeping data on the GPU throughout the computation. Avoids repeated CPU-GPU transfers.

```julia
cuA, cuB, cuC = CuArray.((A, B, C))
result = ein"(ij,jk),kl->il"(cuA, cuB, cuC)
```

```julia
result = ein"ij,jk->ik"(CuArray(A), CuArray(B))  # Transfer every call
```

--------------------------------

### Constructing DynamicEinCode from a Graph

Source: https://under-peter.github.io/OMEinsum.jl/dev/contractionorder

Demonstrates creating a `DynamicEinCode` object from a random regular graph. This is useful when the `@ein_str` literal does not provide optimization for more than two input tensors. Requires importing OMEinsum, OMEinsumContractionOrders, and OMEinsumContractionOrders.Graphs.

```julia
using OMEinsum, OMEinsumContractionOrders, OMEinsumContractionOrders.Graphs
graph = random_regular_graph(20, 3; seed=42){20, 30} undirected simple Int64 graph
code = EinCode([[e.src, e.dst] for e in edges(graph)], Int[])1∘2, 1∘11, 1∘15, 2∘19, 2∘20, 3∘4, 3∘6, 3∘18, 4∘13, 4∘17, 5∘8, 5∘10, 5∘20, 6∘13, 6∘19, 7∘8, 7∘10, 7∘12, 8∘14, 9∘12, 9∘14, 9∘17, 10∘15, 11∘13, 11∘18, 12∘17, 14∘20, 15∘16, 16∘18, 16∘19 ->
```

--------------------------------

### Compute gradient with Zygote

Source: https://under-peter.github.io/OMEinsum.jl/dev/autodiff

Leverage Zygote, a source-to-source automatic differentiation tool, to compute gradients for einsum expressions. This approach is more general and integrates with Zygote's ecosystem.

```julia
using Zygote  # the 2nd way  
Zygote.gradient((A, B, C)->ein"(ij, jk), ki->"(A, B, C)[], A, B, C)([0.8733463495494487 0.40221136622364656 -0.5113134191531026; 1.5749987711017213 3.8132000947394307 4.304507420494414], [0.554319352730959 0.9925914157533164 -2.367352726665581 1.2554581855231646; 0.7933099930434828 0.03716467452843923 -1.405669839684711 0.847290537418059; 0.8348756962870559 0.6875626509113218 -2.408537436639154 1.3367344458859205], [-0.28228952260847023 1.7598534392711838; 0.3100748687994144 -2.49667108192942; -0.04518035773905347 -4.533545816926059; 0.25005753191116153 1.4091793687367735])
```

--------------------------------

### Optimize EinCode with Treewidth

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Optimizes an Einstein summation code using the Treewidth optimizer and a provided size dictionary. The output shows the optimized contraction order.

```julia
optcode = optimize_code(eincode, size_dict, optimizer)
ab, ba -> a
├─ ab
└─ bcf, acf -> ba
   ├─ bcef, e -> bcf
   │  ├─ bcef
   │  └─ e
   └─ acd, df -> acf
      ├─ acd
      └─ df
```

--------------------------------

### TreeSASlicer Configuration

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Configures the Tree Simulated Annealing (TreeSA) slicing algorithm to reach a target space complexity. It includes annealing parameters, fixed slices, an optimization ratio, and a score function.

```julia
TreeSASlicer{IT, LT} <: CodeSlicer
```

--------------------------------

### Generate Uniform Tensor Size Dictionary

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Returns a dictionary mapping labels to a specified uniform size. Useful for setting up tensor network size information.

```python
OMEinsumContractionOrders.uniformsize(code::AbstractEinsum, size::Int) -> Dict
```

--------------------------------

### Set the global einsum backend

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Sets the global backend for einsum operations. This function modifies global state, so caution is advised in concurrent environments. It accepts backends like `DefaultBackend()` for CPU or `CuTensorBackend()` for GPU.

```julia
using OMEinsum, CUDA

set_einsum_backend!(CuTensorBackend())

```

--------------------------------

### Simulated Annealing Optimization

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Optimizes the einsum contraction order using Simulated Annealing with a bipartition and Greedy approach. Requires the einsum code, size dictionary, and various parameters to control the optimization process.

```julia
optimize_sa(code, size_dict; sc_target, max_group_size=40, βs=0.1:0.2:15.0, niters=1000, ntrials=50,
       sub_optimizer = GreedyMethod(), initializer=:random)
```

--------------------------------

### OMEinsumContractionOrders.matrix_to_tree!

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Construct a tree decomposition of an edge-weighted hypergraph using the elimination algorithm `alg`. We ensure that the indices incident to the outer tensor are contained in the root bag of the tree decomposition.

```APIDOC
## OMEinsumContractionOrders.matrix_to_tree!

### Description
Construct a tree decomposition of an edge-weighted hypergraph using the elimination algorithm `alg`. We ensure that the indices incident to the outer tensor are contained in the root bag of the tree decomposition.

### Method
```julia
matrix_to_tree!(marker, weights, ev, ve, el, alg)
```
```

--------------------------------

### Macro for Tensor Contraction (@ein)

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

The `@ein` macro provides a convenient interface for tensor contractions, similar to other packages. It allows for implicit output array naming and the use of numbers for dummy indices.

```julia
@ein A[i,k] := B[i,j] * C[j,k]     # A = B * C
```

--------------------------------

### TreeSA Optimizer Configuration

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Configures the TreeSA optimizer for einsum contraction patterns using simulated annealing on a tensor expression tree. It allows customization of annealing parameters, initialization methods, scoring, and decomposition types.

```julia
TreeSA{IT, DT} <: CodeOptimizer
TreeSA(; βs=collect(0.01:0.05:15), ntrials=10, niters=50, initializer=:greedy, score=ScoreFunction(), decomposition_type=TreeDeomp())
```

--------------------------------

### KaHyParBipartite Optimizer Configuration

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Optimizes einsum contraction order using KaHyPar and Greedy methods. It recursively cuts tensors into groups using KaHyPar, then finds contraction orders within each group using greedy search. Key parameters include target space complexity and imbalance controls.

```julia
KaHyParBipartite(; sc_target, imbalances=collect(0.0:0.005:0.8),
    max_group_size=40, greedy_config=GreedyMethod())
```

--------------------------------

### Optimize tensor contraction order

Source: https://under-peter.github.io/OMEinsum.jl/dev/applications

Optimizes the contraction order for the Peterson graph 3-coloring problem using 'optimize_code' with the TreeSA algorithm. This significantly reduces the computational complexity.

```julia
optcode = optimize_code(code, uniformsize(code, 3), TreeSA())
```

--------------------------------

### Construct Incidence Matrix for Einsum

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Constructs the weighted incidence matrix for an Einstein summation expression. This method is used internally for graph-based optimization.

```julia
einexpr_to_matrix!(marker, ixs, iy, size_dict)
```

--------------------------------

### Execute optimized contraction for Peterson graph

Source: https://under-peter.github.io/OMEinsum.jl/dev/applications

Executes the optimized tensor contraction for the Peterson graph. The result is 0, confirming the absence of valid 3-colorings even after optimization.

```julia
optcode(fill(s, 10)...)[]
```

--------------------------------

### OMEinsumContractionOrders.optimize_tree

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Optimize the einsum contraction pattern specified by `code`, and edge sizes specified by `size_dict`. Check the docstring of `TreeSA` for detailed explanation of other input arguments.

```APIDOC
## OMEinsumContractionOrders.optimize_tree

### Description
Optimize the einsum contraction pattern specified by `code`, and edge sizes specified by `size_dict`. Check the docstring of `TreeSA` for detailed explanation of other input arguments.

### Method
```julia
optimize_tree(code, size_dict; βs, ntrials, niters, initializer, score)
```
```

--------------------------------

### Abstract Type for Einsum Notations

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Abstract type for einsum notations. Requires `getixsv`, `getiyv`, and `uniquelabels` interfaces.

```julia
AbstractEinsum
```

--------------------------------

### Compute cost and gradient with OMEinsum

Source: https://under-peter.github.io/OMEinsum.jl/dev/autodiff

Use the `cost_and_gradient` function from OMEinsum for efficient gradient computation of tensor contractions. This method is optimized for einsum operations.

```julia
using OMEinsum  # the 1st way  
A, B, C = randn(2, 3), randn(3, 4), randn(4, 2);

y, g = cost_and_gradient(ein"(ij, jk), ki->", (A, B, C))(fill(9.918772889041218), Any[[0.8733463495494487 0.40221136622364656 -0.5113134191531026; 1.5749987711017213 3.8132000947394307 4.304507420494414], [0.554319352730959 0.9925914157533164 -2.367352726665581 1.2554581855231646; 0.7933099930434828 0.03716467452843923 -1.405669839684711 0.847290537418059; 0.8348756962870559 0.6875626509113218 -2.408537436639154 1.3367344458859205], [-0.28228952260847023 1.7598534392711838; 0.3100748687994144 -2.49667108192942; -0.04518035773905347 -4.533545816926059; 0.25005753191116153 1.4091793687367735]])
```

--------------------------------

### OMEinsum.get_size_dict!

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Verifies the consistency of input indices and tensors, and returns a dictionary mapping index labels to their sizes. This is crucial for setting up einsum operations correctly.

```APIDOC
## OMEinsum.get_size_dict!

### Description
Returns a dictionary that is used to get the size of an index-label in the einsum-specification with input-indices `ixs` and tensors `xs` after consistency within `ixs` and between `ixs` and `xs` has been verified.

### Method Signature
```julia
get_size_dict!(ixs, xs, size_info)
```
```

--------------------------------

### einexpr_to_matrix!

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Constructs the weighted incidence matrix for an Einstein summation expression.

```APIDOC
## Method einexpr_to_matrix!

### Signature
```julia
einexpr_to_matrix!(marker, ixs, iy, size_dict)
```

### Description
Construct the weighted incidence matrix corresponding to an Einstein summation expression. This function enumerates index sets and constructs an edge-weighted hypergraph representation.
```

--------------------------------

### Compute Einsum with Caching

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Computes the einsum contraction and caches intermediate results. This is useful for optimizing repeated computations.

```julia
cached_einsum(code, xs, size_dict)
```

--------------------------------

### Treewidth Optimizer

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

The Treewidth optimizer uses algorithms from CliqueTrees.jl and TreeWidthSolver.jl to find an optimal contraction order based on tree width.

```APIDOC
## struct Treewidth

### Description
Tree width based solver for optimizing tensor contraction orders. It utilizes algorithms implemented in CliqueTrees.jl and TreeWidthSolver.jl.

### Fields
* `alg::EL` : The algorithm to use for the treewidth calculation. Available elimination algorithms include `AMF`, `MF`, and `MMD`.

### Example
```julia
optimizer = Treewidth()
optcode = optimize_code(eincode, size_dict, optimizer)
```
```

--------------------------------

### Size Dictionary Creation

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Creates a dictionary mapping character labels to their corresponding log2 dimensions. This is used to define the size of tensors.

```julia
size_dict = Dict([c=>(1<<i) for (i,c) in enumerate(['a', 'b', 'c', 'd', 'e', 'f'])]...)
```

--------------------------------

### Compute Cost and Gradient

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Calculates the cost and gradients with respect to input tensors `xs` for a given einsum contraction. The default message for back-propagation is 1.

```julia
cost_and_gradient(code, xs, ȳ)
```

--------------------------------

### OMEinsumContractionOrders.optimize_sa

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Optimize the einsum `code` contraction order using the Simulated Annealing bipartition + Greedy approach. `size_dict` is a dictionary that specifies leg dimensions. Check the docstring of `SABipartite` for detailed explanation of other input arguments.

```APIDOC
## OMEinsumContractionOrders.optimize_sa

### Description
Optimize the einsum `code` contraction order using the Simulated Annealing bipartition + Greedy approach. `size_dict` is a dictionary that specifies leg dimensions. Check the docstring of `SABipartite` for detailed explanation of other input arguments.

### Method
```julia
optimize_sa(code, size_dict; sc_target, max_group_size=40, βs=0.1:0.2:15.0, niters=1000, ntrials=50,
       sub_optimizer = GreedyMethod(), initializer=:random)
```

### References
  * Hyper-optimized tensor network contraction
```

--------------------------------

### uniformsize

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Returns a dictionary mapping each label in an AbstractEinsum object to a specified uniform size. Useful for setting consistent tensor dimensions.

```APIDOC
## uniformsize

### Description
Returns a dictionary that maps each label to the given size.

### Method
`uniformsize(code::AbstractEinsum, size::Int) -> Dict`

### Parameters
#### Arguments
* `code`: An `AbstractEinsum` object.
* `size`: The uniform size to assign to each label.
```

--------------------------------

### Optimizing Contraction Order with TreeSA

Source: https://under-peter.github.io/OMEinsum.jl/dev/contractionorder

Optimizes the contraction order of an `EinCode` object using the `TreeSA` algorithm. This results in a `SlicedEinsum` or `NestedEinsum` object, typically reducing time and read-write complexities.

```julia
optcode = optimize_code(code, size_dict, TreeSA(ntrials=1))
```

--------------------------------

### Optimize Einsum Contraction Code

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Optimizes einsum contraction code to reduce time and space complexity. Use this to find an efficient contraction path for tensor networks. Requires the einsum code, a dictionary of edge sizes, and an optimizer.

```julia
optimize_code(eincode, size_dict, optimizer = GreedyMethod(); slicer=nothing, simplifier=nothing, permute=true) -> optimized_eincode
```

```julia
using OMEinsum

code = ein"ij, jk, kl, il->"

optimize_code(code, uniformsize(code, 2), TreeSA());
```

--------------------------------

### Define Matrix Multiplication with @ein Macro

Source: https://under-peter.github.io/OMEinsum.jl/dev/basic

Combines the einsum notation definition and the matrix multiplication operation in a single line using the `@ein` macro. This is convenient for simple operations.

```julia
@ein C[i,k] := A[i,j] * B[j,k]
```

--------------------------------

### OMEinsum.getiyv

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Retrieves the labels of the output tensor for einsum code objects like EinCode and NestedEinsum. It returns a vector containing the index labels of the output tensor.

```APIDOC
## OMEinsum.getiyv

### Description
Get labels of the output tensor for `EinCode`, `NestedEinsum` and some other einsum like objects. Returns a vector.

### Method Signature
```julia
getiyv(code)
```

### Example
```julia
getiyv(ein"(ij,jk),k->i")
```

### Returns
A 1-element Vector of Char, e.g., `['i']`.
```

--------------------------------

### Create Diagonal Matrix from Vector

Source: https://under-peter.github.io/OMEinsum.jl/dev/basic

Constructs a diagonal matrix where the vector elements form the diagonal using Einsum notation.

```julia
ein"i->ii"(w)
```

--------------------------------

### Direct Optimized Contraction with @optein_str

Source: https://under-peter.github.io/OMEinsum.jl/dev/contractionorder

Constructs an optimized contraction directly using the `@optein_str` string literal. This method assumes each index has a size of 2, which may not yield the absolute optimal order for all tensor sizes.

```julia
optein"ij,jk,kl,li->"
```

--------------------------------

### OMEinsumContractionOrders.readjson

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Read the contraction order from a JSON file.

```APIDOC
## OMEinsumContractionOrders.readjson

### Description
Read the contraction order from a JSON file.

### Arguments
  * `filename` : the name of the file to read from.

### Method
```julia
readjson(filename::AbstractString)
```
```

--------------------------------

### Optimized Contraction Order with @optein_str

Source: https://under-peter.github.io/OMEinsum.jl/dev/basic

Performs an optimized contraction for multiple tensors using the `@optein_str` macro, which automatically determines the contraction order without prior knowledge of tensor sizes.

```julia
tensors = [randn(100, 100) for _ in 1:4]
optein"ij,jk,kl,lm->im"(tensors...)
```

--------------------------------

### Perform Contractions with cuTENSOR

Source: https://under-peter.github.io/OMEinsum.jl/dev/docstrings

Executes matrix contractions using the cuTENSOR backend on CUDA arrays. This demonstrates a typical use case for GPU acceleration.

```julia
A = CUDA.rand(Float32, 100, 200)
B = CUDA.rand(Float32, 200, 300)
C = ein"ij,jk->ik"(A, B)
```

--------------------------------

### Sum All Elements of a Matrix

Source: https://under-peter.github.io/OMEinsum.jl/dev/basic

Calculates the sum of all elements in a matrix using Einsum notation.

```julia
ein"ij->"(A)
```
Tokens:
Raw