gv2adj/cmd/internal/markov/absorbing.go

/*
Copyright © 2025 filifa

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
package markov

import (
	"math"

	"gonum.org/v1/gonum/graph"
	"gonum.org/v1/gonum/graph/multi"
	"gonum.org/v1/gonum/graph/simple"
	"gonum.org/v1/gonum/graph/topo"
	"gonum.org/v1/gonum/mat"
)

// AbsorbingMarkovChain is a graph representing an absorbing Markov chain.
type AbsorbingMarkovChain struct {
	*multi.WeightedDirectedGraph
}

// NewAbsorbingMarkovChain returns an absorbing Markov chain with no nodes or
// edges.
func NewAbsorbingMarkovChain() *AbsorbingMarkovChain {
	return &AbsorbingMarkovChain{WeightedDirectedGraph: multi.NewWeightedDirectedGraph()}
}

// IsValid returns true if the graph is a valid Markov chain.
func (g *AbsorbingMarkovChain) IsValid() bool {
	for nodes := g.Nodes(); nodes.Next(); {
		u := nodes.Node()
		if g.outWeightSum(u) != 1 {
			return false
		}
	}

	return true
}

func (g *AbsorbingMarkovChain) outWeightSum(u graph.Node) float64 {
	sum := 0.0
	for nodes := g.From(u.ID()); nodes.Next(); {
		v := nodes.Node()
		e := g.WeightedEdge(u.ID(), v.ID())
		if e != nil {
			sum += e.Weight()
		}
	}

	return sum
}

// AbsorbingNodes returns all the nodes in the Markov chain identified as
// absorbing nodes.
func (g *AbsorbingMarkovChain) AbsorbingNodes() []graph.Node {
	absorbingNodes := make([]graph.Node, 0)
	for nodes := g.Nodes(); nodes.Next(); {
		u := nodes.Node()
		successors := g.From(u.ID())
		if successors.Len() != 1 {
			continue
		}

		successors.Next()
		v := successors.Node()
		if u == v {
			absorbingNodes = append(absorbingNodes, u)
		}
	}

	return absorbingNodes
}

// IsAbsorbing returns true if the Markov chain is an absorbing chain. This
// means at least one node is an absorbing node and that every node can reach
// an absorbing node.
func (g *AbsorbingMarkovChain) IsAbsorbing() bool {
	absorbingNodes := g.AbsorbingNodes()
	if len(absorbingNodes) == 0 {
		return false
	}

	for nodes := g.Nodes(); nodes.Next(); {
		u := nodes.Node()
		if !g.canBeAbsorbed(u, absorbingNodes) {
			return false
		}
	}

	return true
}

func (g *AbsorbingMarkovChain) canBeAbsorbed(u graph.Node, absorbingNodes []graph.Node) bool {
	for _, v := range absorbingNodes {
		if topo.PathExistsIn(g, u, v) {
			return true
		}
	}

	return false
}

// AdjacencyMatrix returns the graph's adjacency matrix.
func (g *AbsorbingMarkovChain) AdjacencyMatrix() *mat.Dense {
	adj := simple.NewDirectedMatrix(g.Nodes().Len(), 0, 0, 0)
	for edges := g.WeightedEdges(); edges.Next(); {
		e := edges.WeightedEdge()
		if e.From() == e.To() {
			continue
		}

		adj.SetWeightedEdge(e)
	}

	a := mat.DenseCopyOf(adj.Matrix())

	nodes := adj.Nodes()
	for i := 0; nodes.Next(); i++ {
		id := nodes.Node().ID()
		u := g.Node(id)

		e := g.WeightedEdge(u.ID(), u.ID())
		if e != nil {
			a.Set(i, i, e.Weight())
		}
	}

	return a
}

// NewEdge returns a weightedEdge that can be added to the Markov chain.
func (g *AbsorbingMarkovChain) NewEdge(from, to graph.Node) graph.Edge {
	e := g.WeightedDirectedGraph.NewWeightedLine(from, to, math.NaN()).(multi.WeightedLine)
	return &weightedEdge{WeightedLine: e}
}

// NewNode returns a Node that can be added to the Markov chain.
func (g *AbsorbingMarkovChain) NewNode() graph.Node {
	return &Node{Node: g.WeightedDirectedGraph.NewNode()}
}

// SetEdge adds a weighted edge to the Markov chain.
func (g *AbsorbingMarkovChain) SetEdge(e graph.Edge) {
	g.WeightedDirectedGraph.SetWeightedLine(e.(*weightedEdge))
}