API Reference

sig(path::AbstractMatrix, m::Int) -> Vector

Compute the truncated path signature up to level m.

The path signature is a graded feature vector that characterizes the path's geometry. It consists of iterated integrals computed recursively using Chen's identity.

Arguments

• path::AbstractMatrix{T}: N×d matrix where N ≥ 2 is the number of points and d ≥ 1 is the dimension. Each row represents a point in d-dimensional space.
• m::Int: Truncation level (m ≥ 1). The signature will include levels 1 through m.

Returns

• Vector{T}: Flattened coefficient vector of length d + d² + ... + dᵐ containing signature coefficients ordered by level (all level-1 terms, then level-2, etc.).

Computational Complexity

• Time: O(N · dᵐ⁺¹) where N is path length
• Space: O(dᵐ⁺¹) for signature storage

Examples

# 2D path with 100 points, signature up to level 3
path = randn(100, 2)
s = sig(path, 3)
length(s)  # 2 + 4 + 8 = 14

# 3D path, level 4
path = randn(50, 3)
s = sig(path, 4)
length(s)  # 3 + 9 + 27 + 81 = 120

Notes

• This function allocates scratch buffers internally. For repeated calls, consider using signature_path! with a preallocated SignatureWorkspace.
• For log-signature (more compact representation), see logsig.

References

K.T. Chen (1957). "Integration of paths, geometric invariants and a generalized Baker-Hausdorff formula."

See also: logsig, prepare, signature_path!

sig(paths::AbstractArray{T,3}, m::Int; threaded::Bool=true) -> Matrix{T}

Compute truncated path signatures for a batch of paths.

Arguments

• paths::AbstractArray{T,3}: N×D×B array where:
  • N ≥ 2: number of time points per path
  • D ≥ 1: spatial dimension
  • B ≥ 1: batch size (number of paths)
• m::Int: Truncation level (m ≥ 1)
• threaded::Bool=true: Use multi-threading when true

Returns

• Matrix{T}: S×B matrix where S = d + d² + ... + dᵐ (signature length) and each column result[:, i] contains the signature of paths[:, :, i]

Computational Complexity

• Time: O(B · N · dᵐ⁺¹) where B is batch size, N is path length
• Space: O(B · dᵐ⁺¹) for output storage
• Threading: Near-linear speedup with number of threads for large batches

Examples

# Batch of 100 paths, each with 50 time points in 3D space
paths = randn(50, 3, 100)
sigs = sig(paths, 4)  # Returns 120×100 matrix
size(sigs)  # (120, 100)

# Access signature of the 5th path
sig_5 = sigs[:, 5]

# Disable threading for small batches
sigs = sig(paths, 4; threaded=false)

Performance Notes

• Uses Threads.@threads when threaded=true (default)
• Threading overhead may not be worth it for very small batches (B < 10)
• For maximum performance with manual workspace management, see signature_path!

See also: sig, logsig, SignatureWorkspace

logsig(path::AbstractMatrix, basis::BasisCache) -> Vector

Compute the log-signature of a path projected onto the Lyndon basis.

The log-signature is the logarithm (in the tensor algebra) of the signature, and provides a more compact representation. When projected onto the Lyndon basis, it gives coefficients in the free Lie algebra, which is much smaller than the full tensor algebra.

Arguments

• path::AbstractMatrix{T}: N×d matrix where N ≥ 2 is the number of points. Dimension d must match the basis.
• basis::BasisCache: Precomputed basis from prepare(d, m)

Returns

• Vector{T}: Log-signature coefficients in Lyndon basis. Length equals number of Lyndon words up to length m.

Computational Complexity

• Time: O(N · dᵐ⁺¹ + L²) where L is number of Lyndon words
• Space: O(dᵐ⁺¹) for intermediate signature computation

Examples

# Setup
path = randn(100, 3)
basis = prepare(3, 4)

# Compute log-signature
ls = logsig(path, basis)

# Log-signature is much more compact than signature
println("Log-signature size: ", length(ls))        # Depends on Lyndon words
println("Full signature size: ", 3 + 9 + 27 + 81)  # 120

Notes

• Requires precomputed basis from prepare.
• More compact than sig but requires additional preprocessing.
• Best suited when you need many log-signatures with the same (d, m).

References

Lyons, Caruana, Lévy (2007). "Differential equations driven by rough paths." Lecture Notes in Mathematics.

See also: sig, prepare, BasisCache

logsig(paths::AbstractArray{T,3}, basis::BasisCache; threaded::Bool=true) -> Matrix{T}

Compute log-signatures for a batch of paths using a precomputed Lyndon basis.

Arguments

• paths::AbstractArray{T,3}: N×D×B array of paths where:
  • N ≥ 2: number of time points per path
  • D ≥ 1: spatial dimension (must match basis)
  • B ≥ 1: batch size (number of paths)
• basis::BasisCache: Precomputed basis from prepare(D, m)
• threaded::Bool=true: Use multi-threading when true

Returns

• Matrix{T}: L×B matrix where L is the number of Lyndon words and each column result[:, i] contains the log-signature of paths[:, :, i]

Computational Complexity

• Time: O(B · (N · dᵐ⁺¹ + L²)) where L is number of Lyndon words
• Space: O(B · L) for output storage
• Log-signature dimension L is much smaller than signature dimension

Examples

# Precompute basis once for 3D paths, level 4
basis = prepare(3, 4)

# Process batch of 100 paths
paths = randn(50, 3, 100)
logsigs = logsig(paths, basis)

# Log-signature is more compact than signature
println("Log-signature size: ", size(logsigs, 1))  # Much less than 120
println("Number of paths: ", size(logsigs, 2))     # 100

# Process another batch with same basis
more_paths = randn(50, 3, 50)
more_logsigs = logsig(more_paths, basis)

Performance Notes

• Precompute and reuse basis for all batches with the same (D, m)
• Threading provides significant speedup for large batches
• More memory-efficient than sig due to compact representation

See also: logsig, sig, prepare, BasisCache

prepare(d::Int, m::Int) -> BasisCache

Precompute Lyndon basis and projection matrix for log-signature computation.

This function builds the data structures needed for logsig. The Lyndon basis provides a Hall basis for the free Lie algebra, giving a minimal representation of the log-signature with dimension dim_Lie(d,m) ≪ d + d² + ... + dᵐ.

Arguments

• d::Int: Path dimension (d ≥ 1)
• m::Int: Truncation level (m ≥ 1)

Returns

• BasisCache: Opaque structure containing basis information. Pass to logsig.

Performance Notes

• This computation can be expensive for large d and m (involves symbolic shuffles).
• Cache the result and reuse for multiple paths with the same (d, m).
• Time complexity: O(L²) where L is the number of Lyndon words.

Examples

# Precompute basis for 3D paths, level 5
basis = prepare(3, 5)

# Reuse for multiple paths
for path in paths
    ls = logsig(path, basis)
    # process ls...
end

References

Reutenauer (1993). "Free Lie Algebras." Oxford University Press.

See also: logsig, BasisCache

Tensor{T,D,M} <: AbstractTensor{T}

Dense tensor algebra element up to level M in dimension D.

This is the core data structure for representing truncated tensor series in the path signature computation. It stores coefficients for all tensor levels from 0 to M in a single flat array with efficient memory layout.

Type Parameters

• T: Element type (e.g., Float64, Float32)
• D: Dimension (number of coordinate axes)
• M: Maximum truncation level

Fields

• coeffs::Vector{T}: Flattened coefficient array containing all levels 0 through M. Length is 1 + D + D² + ... + Dᴹ⁺¹ (includes padding for alignment).
• offsets::Vector{Int}: Starting indices for each level in coeffs. Length M+2.

Construction

# Create zero tensor
t = Tensor{Float64, 3, 4}()

# Create from coefficient vector
coeffs = randn(len)  # Must match expected length
t = Tensor{Float64, 3, 4}(coeffs)

Notes

• Most users should use sig instead of working with Tensor directly.
• For advanced applications requiring direct tensor manipulation, see signature_path!.
• The type parameters {T,D,M} are compile-time constants, enabling aggressive optimization.

See also: sig, signature_path, SignatureWorkspace

SignatureWorkspace{T,D,M}

Preallocated workspace for computing path signatures without allocations.

This workspace contains scratch buffers used internally by the Horner update scheme. Reusing a workspace across multiple signature computations eliminates memory allocations in the hot path, which is beneficial for batch processing or moving window applications.

Type Parameters

• T: Element type (e.g., Float64, Float32)
• D: Path dimension (number of coordinates per point)
• M: Truncation level (maximum signature level to compute)

Fields

• B1::Vector{T}: First scratch buffer of length D^(M-1)
• B2::Vector{T}: Second scratch buffer of length D^(M-1)

Example

# Create workspace for dimension 3, level 4
ws = SignatureWorkspace{Float64, 3, 4}()

# Reuse workspace for multiple paths
for path in paths
    out = Tensor{Float64, 3, 4}()
    signature_path!(out, path, ws)
    # process out...
end

See also: signature_path!

BasisCache{T}

Cached Lyndon basis data for efficient log-signature computation.

This structure stores precomputed data for projecting signatures onto the Lyndon basis, which provides a minimal free-Lie algebra representation of the log-signature.

Fields

• d::Int: Path dimension
• m::Int: Truncation level
• lynds::Vector{Word}: Lyndon words up to length m
• L::Matrix{T}: Lower-triangular projection matrix

Notes

Create instances using prepare, not directly.

See also: prepare, logsig

signature_path(::Type{Tensor{T}}, path, m::Int) -> Tensor{T,D,m}

Compute path signature and return as a Tensor (not flattened).

This is a lower-level function that returns the signature in tensor form rather than as a flattened vector. Most users should use sig instead.

Arguments

• ::Type{Tensor{T}}: Element type for the output tensor
• path: Path as AbstractMatrix{T} or AbstractVector{SVector{D,T}}
• m::Int: Truncation level

Returns

• Tensor{T,D,m}: Signature tensor with graded structure preserved

See also: sig, signature_path!