API Reference

Tensor4all

Tensor4all.jl is in an API-skeleton review phase.

The previous implementation has been intentionally removed so the package can be rebuilt against the design documents in docs/design/ without stale public surface area leaking into the rework. Importing the package is expected to work, but the real backend-facing types and operations are deferred to a later phase.

SkeletonPhaseError(message)

Raised when code expects functionality that is intentionally deferred during the review-first skeleton phase.

Examples

julia> using Tensor4all

julia> err = SkeletonPhaseError("not ready yet");

julia> sprint(showerror, err)
"not ready yet"

SkeletonNotImplemented(api, layer)

Raised by reviewable public APIs that are intentionally present before their backend behavior is implemented.

Examples

julia> using Tensor4all

julia> err = SkeletonNotImplemented(:contract, :core);

julia> sprint(showerror, err)
"Tensor4all skeleton phase: `contract` is planned in the `core` layer but not implemented yet."

BackendUnavailableError(message)

Raised when a backend-backed operation is requested but the tensor4all-rs shared library is not available.

Examples

julia> using Tensor4all

julia> err = BackendUnavailableError("backend missing");

julia> sprint(showerror, err)
"backend missing"

backend_library_path()

Return the expected path to the tensor4all-rs C API shared library.

This helper is backend-free and can be used during the skeleton phase to inspect where the package would look for the compiled library.

Examples

julia> using Tensor4all

julia> backend_library_path() isa String
true

require_backend()

Load and return the tensor4all-rs shared library handle.

This function is part of the skeleton API surface, but it only succeeds when a compiled backend is available.

Examples

julia> require_backend()
ERROR: BackendUnavailableError(...)

Index(dim; tags=String[], plev=0, id=next_index_id(), backend_handle=nothing)

Create a Julia-side review skeleton for an indexed tensor leg.

The metadata behavior is implemented during the skeleton phase, while the optional backend handle keeps the public shape aligned with the eventual backend-facing design.

Examples

julia> using Tensor4all

julia> i = Index(4; tags=["x"], plev=1);

julia> (dim(i), tags(i), plev(i))
(4, ["x"], 1)

dim(i)

Return the dimension of i.

id(i)

Return the stable identifier of i.

tags(i)

Return a copy of the string tags attached to i.

plev(i)

Return the prime level of i.

hastag(i, tag)

Return true when tag is attached to i.

sim(i)

Return a similar index with matching metadata and a fresh identifier.

prime(i, n=1)

Return i with its prime level increased by n.

prime(t, n=1)

Return t with all attached indices primed by n.

noprime(i)

Return i with prime level reset to zero.

setprime(i, n)

Return i with prime level set to n.

replaceind(xs, old, new)

Replace old by new in the index collection xs.

replaceinds(xs, replacements...)

Apply multiple index replacements in sequence to xs.

commoninds(xs, ys)

Return the indices in xs that also occur in ys, preserving the order from xs.

uniqueinds(xs, ys)

Return the indices in xs that do not occur in ys, preserving the order from xs.

Tensor(data, inds; backend_handle=nothing)

Create a tensor skeleton from Julia-owned dense array data and index metadata.

This constructor validates metadata and shape consistency during the skeleton phase. Backend-backed contraction and factorization behavior remains deferred.

Examples

julia> using Tensor4all

julia> i = Index(2; tags=["i"]);

julia> j = Index(3; tags=["j"]);

julia> t = Tensor(reshape(collect(1.0:6.0), 2, 3), [i, j]);

julia> (rank(t), dims(t))
(2, (2, 3))

inds(t)

Return a copy of the index metadata attached to t.

rank(t)

Return the tensor rank of t.

dims(t)

Return the dense array dimensions of t.

swapinds(t, a, b)

Swap index metadata a and b on t.

contract(a, b)

Placeholder for tensor contraction.

Examples

julia> contract(a, b)
ERROR: SkeletonNotImplemented(...)

contract(a, b)

Placeholder for backend-backed TreeTN contraction.

TreeTensorNetwork(tensors; adjacency, siteinds, linkinds, backend_handle=nothing)

Create a TreeTN-general review skeleton from local tensor metadata and explicit topology maps.

The topology helpers are implemented during the skeleton phase, while numerical operations remain stub-only until backend integration.

Examples

julia> ttn = TreeTensorNetwork(...; adjacency=..., siteinds=..., linkinds=...)

TensorTrain

Alias for TreeTensorNetwork{Int}, the primary chain-shaped network type in the Julia API.

MPS

Alias for TensorTrain. MPS-ness is a runtime structural property rather than a separate type.

MPO

Alias for TensorTrain. MPO-ness is a runtime structural property rather than a separate type.

vertices(ttn)

Return the sorted vertex labels of ttn.

neighbors(ttn, v)

Return the neighboring vertices of v.

siteinds(ttn, v)

Return the site indices attached to vertex v.

linkind(ttn, a, b)

Return the link index connecting vertices a and b.

is_chain(ttn)

Return true when ttn has integer vertices 1:n and chain connectivity.

is_mps_like(ttn)

Return true when each vertex carries exactly one site index.

is_mpo_like(ttn)

Return true when each vertex carries exactly two site indices.

orthogonalize!(ttn, args...)

Placeholder for backend-backed orthogonalization.

truncate!(ttn, args...)

Placeholder for backend-backed truncation.

inner(a, b)

Placeholder for backend-backed TreeTN inner products.

norm(ttn)

Placeholder for backend-backed TreeTN norms.

to_dense(ttn)

Placeholder for dense materialization of a TreeTN.

evaluate(ttn, args...)

Placeholder for backend-backed TreeTN evaluation.

QuanticsTransform(kind, parameters)

Metadata-only descriptor for a planned quantics transform.

The descriptor is reviewable during the skeleton phase, while transform materialization remains backend-backed and therefore stub-only.

affine_transform(; matrix, shift)

Create an affine transform descriptor.

shift_transform(; offsets)

Create a shift transform descriptor.

flip_transform(; variables)

Create a flip transform descriptor.

phase_rotation_transform(; phase)

Create a phase-rotation transform descriptor.

cumsum_transform(; variable)

Create a cumulative-sum transform descriptor.

fourier_transform(; variables)

Create a Fourier transform descriptor.

binaryop_transform(; op, variables)

Create a binary-operation transform descriptor.

materialize_transform(transform)

Placeholder for backend-backed transform materialization.

QTCIOptions(; tolerance=1.0e-8, max_rank=64, max_sweeps=10)

Metadata-only placeholder for future QTCI configuration.

QTCIDiagnostics(; converged=false, sweeps=0, final_error=Inf)

Metadata-only placeholder for future QTCI diagnostics.

QTCIResultPlaceholder(options, diagnostics)

Placeholder container for future QTCI results.