added more documentation

examples/Getting Started.jl

@@ -96,10 +96,10 @@ md"""
 """
 
 # ╔═╡ 28ae4fcf-3c4f-4f4f-aec2-01455568fb96
-draw(project(A; dims = 2), latin)
+draw(fsmproject(A; dims = 2), latin)
 
 # ╔═╡ d5572c90-b5b7-49e4-8c24-5193b8f03196
-draw(project(A; dims = 1), latin)
+draw(fsmproject(A; dims = 1), latin)
 
 # ╔═╡ 8fc36715-a764-4f86-a848-c28a05179bd2
 md"""
@@ -107,7 +107,7 @@ md"""
 """
 
 # ╔═╡ d3a71d55-ce4a-42ea-aab0-80e76ad6802d
-draw(permutelabels(A, (2, 1)), latin)
+draw(fsmpermute(A, (2, 1)), latin)
 
 # ╔═╡ 06a69aa8-493b-4fda-974b-4685105be711
 md"""
@@ -115,7 +115,7 @@ md"""
 """
 
 # ╔═╡ 1943822d-3512-4778-9042-680208b149ee
-draw(reverse(A), latin)
+draw(fsmreverse(A), latin)
 
 # ╔═╡ e2c851dc-ab98-49fa-853d-f9c3a2b1b8f2
 notes = Dict(

src/TensorFSTs.jl

@@ -26,13 +26,12 @@ export SparseTensorFSM
 include("sparsetensorfsm.jl")
 
 
-export closure,
-       closure_plus,
-       compose,
-       project,
-       permutelabels,
-       fsmcat,
+export fsmcat,
        fsmclosure,
+       fsmcompose,
+       fsmpermute,
+       fsmproject,
+       fsmreverse,
        fsmunion
 
 include("ops.jl")

src/ops.jl

@@ -84,7 +84,7 @@ Base.:*(A::AbstractFSM, B::AbstractFSM) = fsmcat(A, B)
     A^+ # equivalent to fsmclosure(A; closure_plus = true)
 
 Compute the Kleene closure (also denoted *star*) of a weighted automaton `A`
-or the Kleene plus operation if `closure_plus = true`.
+or the Kleene plus operation if `closure_plus` is `true`.
 
 The Kleene closure of a ``N``-order weighted automaton ``A`` over the
 semiring ``(S, \\oplus, \\otimes, \\bar{0}, \\bar{1})``, denoted ``A^*``, is defined
@@ -134,39 +134,84 @@ Base.:^(A::AbstractFSM, ::typeof(*)) = fsmclosure(A; closure_plus = false)
 
 
 """
-    project(fsm; dims)
+    fsmpermute(A::AbstractFSM, p)
 
-Project machine onto a subset of labels by summing over all the label dimension
-`dims`.
-"""
-project
+Permute the label dimensions of the automaton `A` according to the permutation
+`p`.
 
-_project(fsm::AbstractFSM{T,N}, dims::Dims{M}) where {T,N,M} =
-    SparseTensorFSM{T,N-M}(dropdims(sum(fsm.M; dims); dims), fsm.α, fsm.ω)
+The permutation of the arcs' label of a ``N``-order weighted automaton ``A``
+over the semiring ``(S, \\oplus, \\otimes, \\bar{0}, \\bar{1})`` given a
+permutation ``p = (p_1, \\dots, p_N)`` is defined such that for all
+``x \\in (\\Sigma^*_1 \\times \\dots \\times \\Sigma^*_N)``:
+```math
+    \\text{permute}_p(A)(x) = A(x')
+```
+where ``x' = (x_{p_1}, \\dots, x_{p_N})`` is the permutation of ``x`` given ``p``.
 
-_project(fsm::AbstractFSM, dims::Integer) = _project(fsm, tuple(dims))
+## Complexity
+* Time: ``O(E)``
+* Depth: ``O(1)``
+where ``E`` is the number of arcs of the automaton ``A``.
 
-project(fsm; dims) = _project(fsm, dims)
+See also [`fsmproject`](@ref) and [`fsmreverse`](@ref).
+"""
+fsmpermute(A::AbstractFSM, p) = typeof(A)(permutedims(A.M, p), A.α, A.ω)
 
 
 """
-    permutelabels(fsm, p)
+    fsmproject(A::AbstractFSM; dims)
+
+Project the label dimensions `dims` of the automaton `A` onto the other label
+dimensions.
+
+The projection of a ``N``-order weighted automaton ``A`` over the
+semiring ``(S, \\oplus, \\otimes, \\bar{0}, \\bar{1})`` of the label dimensions
+``I \\subset \\{1, \\dots, N\\}`` onto ``I^{\\complement}``  is defined such that for all
+``x \\in (\\Sigma^*_1 \\times \\dots \\times \\Sigma^*_N)``:
+```math
+    \\text{project}_I(A)(x_{\\setminus I}) = \\bigoplus_{\\{ z \\: : \\: z_{\\setminus I} = x_{\\setminus I} \\}} A(z)
+```
+where ``x_{\\setminus I} = (x_i \\: : \\: i \\notin I)`` is the tuple of
+elements in ``x`` with index not in ``I``.
+
+## Complexity
+* Time: ``O(E)``
+* Depth: ``O(1)``
+where ``E`` is the number of arcs of the automaton ``A``.
 
-Permute the labels dimension according to the permutation `p`.
+See also [`fsmpermute`](@ref) and [`fsmreverse`](@ref).
 """
-permutelabels
+fsmproject
+
+_project(fsm::AbstractFSM{T,N}, dims::Dims{M}) where {T,N,M} =
+    SparseTensorFSM{T,N-M}(dropdims(sum(fsm.M; dims); dims), fsm.α, fsm.ω)
+
+_project(fsm::AbstractFSM, dims::Integer) = _project(fsm, tuple(dims))
 
-permutelabels(fsm::AbstractFSM{T,N}, p) where {T,N} =
-    SparseTensorFSM{T,N}(permutedims(fsm.M, p), fsm.α, fsm.ω)
+fsmproject(fsm; dims) = _project(fsm, dims)
 
 
 """
-    Base.reverse(fsm)
+    fsmreverse(A::AbstractFSM)
 
-Reverse the direction of the transitions in `fsm`
+Reverse the direction of the arcs in the automaton `A`.
+
+The reversal of a ``N``-order weighted automaton ``A`` over the semiring
+``(S, \\oplus, \\otimes, \\bar{0}, \\bar{1})``, denoted ``A^R``, is defined
+such that for all ``x \\in (\\Sigma^*_1 \\times \\dots \\times \\Sigma^*_N)``:
+```math
+    A^R(x) = A(x^R)
+```
+where ``x' = (x_1^R, \\dots, x_{N}^R)`` is the tuple of reversed sequences
+``x_i^R``.
+
+## Complexity
+* Time: ``O(E)``
+* Depth: ``O(1)``
+where ``E`` is the number of arcs of the automaton ``A``.
+See also [`fsmpermute`](@ref) and [`fsmproject`](@ref).
 """
-Base.reverse(fsm::AbstractFSM{T,N}) where {T,N} =
-    SparseTensorFSM{T,N}(transpose.(fsm.M), fsm.ω, fsm.α)
+fsmreverse(A::AbstractFSM) = typeof(A)(transpose.(A.M), A.ω, A.α)
 
 
 #@enum FSTPush toinitial tofinal
@@ -239,14 +284,23 @@ Base.reverse(fsm::AbstractFSM{T,N}) where {T,N} =
 
 
 """
-    compose(A, B)
+    fsmcompose(A::AbstractFSM{T}, B::AbstractFSM{T}) where T
+    A ∘ B
+
+Compute the composition of the automata ``A`` and ``B``.
 
-Compute the composition ``A \\circ B`` defined as
+The composition of a ``M``-order weighted automaton ``A`` and a ``N``-order
+weighted automaton ``B`` over the semiring ``(S, \\oplus, \\otimes, \\bar{0}, \\bar{1})``,
+denoted ``A \\circ B``, is defined such that for all
+``x \\in (\\Sigma^*_1 \\times \\dots \\times \\Sigma^*_{N-1})`` and
+``y \\in (\\Omega^*_2, \\dots, \\Omega^*_N)``:
 ```math
-\\forall (x, y) \\in \\Sigma^* \\times \\Omega^*, \\; (A \\circ B)(x, y) = \\bigoplus_{z \\in \\Delta^*} A(x,z) \\otimes B(z,y)
+    (A \\circ B)(x, y) = \\bigoplus_{\\delta \\in \\Delta^*} A(x, \\delta) \\otimes B(\\delta, y)
 ```
+where ``\\Delta`` is the set of symbols for the last label dimension of ``A``
+and the first label dimension of ``B``.
 """
-compose
+fsmcompose
 
 function _compose_M_leftϵ_first(
 		x::AbstractSparseArray{MatrixSemiring{P,Tm},Nx},
@@ -260,6 +314,7 @@ function _compose_M_leftϵ_first(
 	coordinates = Dims{N}[]
 	values = MatrixSemiring{P*Q,Tm}[]
 
+    # sum(X[:,ϵ])
 	yϵ = zero(eltype(y))
 	for ynzi in y.ptr[1]:y.ptr[2]-1
 		yval = y.values[ynzi]
@@ -297,7 +352,7 @@ function _compose_M_leftϵ_first(
 	sparse(coordinates, values, size(x)[1:end-1]..., size(y)[2:end]...)
 end
 
-function compose(A::AbstractFSM{T,Na}, B::AbstractFSM{T,Nb}) where {T,Na,Nb}
+function fsmcompose(A::AbstractFSM{T,Na}, B::AbstractFSM{T,Nb}) where {T,Na,Nb}
     M = _compose_M_leftϵ_first(A.M, B.M)
 	SparseTensorFSM{T,Na+Nb - 2}(M, kron(A.α, B.α), kron(A.ω, B.ω))
 end