rubydragon/metagraphoptimization.jl
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

Add documentation to every function and automatic doc html building (#6)

Browse Source 
Reviewed-on: Rubydragon/MetagraphOptimization.jl#6
Co-authored-by: Anton Reinhard <anton.reinhard@proton.me>
Co-committed-by: Anton Reinhard <anton.reinhard@proton.me>
This commit is contained in:
Anton Reinhard
2023-08-29 12:57:46 +02:00
committed by Anton Reinhard
parent 8014bbffcd
commit 065236be22
53 changed files with 1628 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
src/graph/compare.jl
View File

@@ -1,7 +1,30 @@
"""
in(node::Node, graph::DAG)
Check whether the node is part of the graph.
"""
in(node::Node, graph::DAG) = node in graph.nodes
in(edge::Edge, graph::DAG) = edge in graph.edges
"""
in(edge::Edge, graph::DAG)
Check whether the edge is part of the graph.
"""
function in(edge::Edge, graph::DAG)
n1 = edge.edge[1]
n2 = edge.edge[2]
if !(n1 in graph) || !(n2 in graph)
return false
end
return n1 in n2.children
end
"""
==(n1::Node, n2::Node, g::DAG)
Check equality of two nodes in a graph.
"""
function ==(n1::Node, n2::Node, g::DAG)
if typeof(n1) != typeof(n2)
return false

27
src/graph/interface.jl
View File

@@ -1,6 +1,10 @@
# user interface on the DAG
"""
push_operation!(graph::DAG, operation::Operation)
# applies a new operation to the end of the graph
Apply a new operation to the graph.
See also: [`DAG`](@ref), [`pop_operation!`](@ref)
"""
function push_operation!(graph::DAG, operation::Operation)
# 1.: Add the operation to the DAG
push!(graph.operationsToApply, operation)
@@ -8,7 +12,13 @@ function push_operation!(graph::DAG, operation::Operation)
return nothing
end
# reverts the latest applied operation, essentially like a ctrl+z for
"""
pop_operation!(graph::DAG)
Revert the latest applied operation on the graph.
See also: [`DAG`](@ref), [`push_operation!`](@ref)
"""
function pop_operation!(graph::DAG)
# 1.: Remove the operation from the appliedChain of the DAG
if !isempty(graph.operationsToApply)
@@ -23,10 +33,19 @@ function pop_operation!(graph::DAG)
return nothing
end
"""
can_pop(graph::DAG)
Return `true` if [`pop_operation!`](@ref) is possible, `false` otherwise.
"""
can_pop(graph::DAG) =
!isempty(graph.operationsToApply) || !isempty(graph.appliedOperations)
# reset the graph to its initial state with no operations applied
"""
reset_graph!(graph::DAG)
Reset the graph to its initial state with no operations applied.
"""
function reset_graph!(graph::DAG)
while (can_pop(graph))
pop_operation!(graph)

92
src/graph/mute.jl
View File

@@ -3,6 +3,18 @@
# 2: keep track of what was changed for the diff (if track == true)
# 3: invalidate operation caches
"""
insert_node!(graph::DAG, node::Node; track = true, invalidate_cache = true)
Insert the node into the graph.
## Keyword Arguments
`track::Bool`: Whether to add the changes to the [`DAG`](@ref)'s [`Diff`](@ref). Should be set `false` in parsing or graph creation functions for performance.
`invalidate_cache::Bool`: Whether to invalidate caches associated with the changes. Should also be turned off for graph creation or parsing.
See also: [`remove_node!`](@ref), [`insert_edge!`](@ref), [`remove_edge!`](@ref)
"""
function insert_node!(
graph::DAG,
node::Node,
@@ -26,6 +38,18 @@ function insert_node!(
return node
end
"""
insert_edge!(graph::DAG, node1::Node, node2::Node; track = true, invalidate_cache = true)
Insert the edge between node1 (child) and node2 (parent) into the graph.
## Keyword Arguments
`track::Bool`: Whether to add the changes to the [`DAG`](@ref)'s [`Diff`](@ref). Should be set `false` in parsing or graph creation functions for performance.
`invalidate_cache::Bool`: Whether to invalidate caches associated with the changes. Should also be turned off for graph creation or parsing.
See also: [`insert_node!`](@ref), [`remove_node!`](@ref), [`remove_edge!`](@ref)
"""
function insert_edge!(
graph::DAG,
node1::Node,
@@ -59,6 +83,18 @@ function insert_edge!(
return nothing
end
"""
remove_node!(graph::DAG, node::Node; track = true, invalidate_cache = true)
Remove the node from the graph.
## Keyword Arguments
`track::Bool`: Whether to add the changes to the [`DAG`](@ref)'s [`Diff`](@ref). Should be set `false` in parsing or graph creation functions for performance.
`invalidate_cache::Bool`: Whether to invalidate caches associated with the changes. Should also be turned off for graph creation or parsing.
See also: [`insert_node!`](@ref), [`insert_edge!`](@ref), [`remove_edge!`](@ref)
"""
function remove_node!(
graph::DAG,
node::Node,
@@ -86,6 +122,18 @@ function remove_node!(
return nothing
end
"""
remove_edge!(graph::DAG, node1::Node, node2::Node; track = true, invalidate_cache = true)
Remove the edge between node1 (child) and node2 (parent) into the graph.
## Keyword Arguments
`track::Bool`: Whether to add the changes to the [`DAG`](@ref)'s [`Diff`](@ref). Should be set `false` in parsing or graph creation functions for performance.
`invalidate_cache::Bool`: Whether to invalidate caches associated with the changes. Should also be turned off for graph creation or parsing.
See also: [`insert_node!`](@ref), [`remove_node!`](@ref), [`insert_edge!`](@ref)
"""
function remove_edge!(
graph::DAG,
node1::Node,
@@ -131,12 +179,24 @@ function remove_edge!(
return nothing
end
# return the graph "difference" since last time this function was called
"""
get_snapshot_diff(graph::DAG)
Return the graph's [`Diff`](@ref) since last time this function was called.
See also: [`revert_diff!`](@ref), [`AppliedOperation`](@ref) and [`revert_operation!`](@ref)
"""
function get_snapshot_diff(graph::DAG)
return swapfield!(graph, :diff, Diff())
end
# function to invalidate the operation caches for a given NodeFusion
"""
invalidate_caches!(graph::DAG, operation::NodeFusion)
Invalidate the operation caches for a given [`NodeFusion`](@ref).
This deletes the operation from the graph's possible operations and from the involved nodes' own operation caches.
"""
function invalidate_caches!(graph::DAG, operation::NodeFusion)
delete!(graph.possibleOperations, operation)
@@ -149,7 +209,13 @@ function invalidate_caches!(graph::DAG, operation::NodeFusion)
return nothing
end
# function to invalidate the operation caches for a given NodeReduction
"""
invalidate_caches!(graph::DAG, operation::NodeReduction)
Invalidate the operation caches for a given [`NodeReduction`](@ref).
This deletes the operation from the graph's possible operations and from the involved nodes' own operation caches.
"""
function invalidate_caches!(graph::DAG, operation::NodeReduction)
delete!(graph.possibleOperations, operation)
@@ -160,7 +226,13 @@ function invalidate_caches!(graph::DAG, operation::NodeReduction)
return nothing
end
# function to invalidate the operation caches for a given NodeSplit
"""
invalidate_caches!(graph::DAG, operation::NodeSplit)
Invalidate the operation caches for a given [`NodeSplit`](@ref).
This deletes the operation from the graph's possible operations and from the involved nodes' own operation caches.
"""
function invalidate_caches!(graph::DAG, operation::NodeSplit)
delete!(graph.possibleOperations, operation)
@@ -171,7 +243,11 @@ function invalidate_caches!(graph::DAG, operation::NodeSplit)
return nothing
end
# function to invalidate the operation caches of a ComputeTaskNode
"""
invalidate_operation_caches!(graph::DAG, node::ComputeTaskNode)
Invalidate the operation caches of the given node through calls to the respective [`invalidate_caches!`](@ref) functions.
"""
function invalidate_operation_caches!(graph::DAG, node::ComputeTaskNode)
if !ismissing(node.nodeReduction)
invalidate_caches!(graph, node.nodeReduction)
@@ -185,7 +261,11 @@ function invalidate_operation_caches!(graph::DAG, node::ComputeTaskNode)
return nothing
end
# function to invalidate the operation caches of a DataTaskNode
"""
invalidate_operation_caches!(graph::DAG, node::DataTaskNode)
Invalidate the operation caches of the given node through calls to the respective [`invalidate_caches!`](@ref) functions.
"""
function invalidate_operation_caches!(graph::DAG, node::DataTaskNode)
if !ismissing(node.nodeReduction)
invalidate_caches!(graph, node.nodeReduction)

12
src/graph/print.jl
View File

@@ -1,4 +1,9 @@
function show_nodes(io, graph::DAG)
"""
show_nodes(io::IO, graph::DAG)
Print a graph's nodes. Should only be used for small graphs as it prints every node in a list.
"""
function show_nodes(io::IO, graph::DAG)
print(io, "[")
first = true
for n in graph.nodes
@@ -12,6 +17,11 @@ function show_nodes(io, graph::DAG)
return print(io, "]")
end
"""
show(io::IO, graph::DAG)
Print the given graph to io. If there are too many nodes it will print only a summary of them.
"""
function show(io::IO, graph::DAG)
println(io, "Graph:")
print(io, " Nodes: ")

10
src/graph/properties.jl
View File

@@ -1,3 +1,8 @@
"""
graph_properties(graph::DAG)
Return the graph's properties, a named tuple with fields `.data`, `.compute_effort`, `.compute_intensity`, `.nodes` (number of nodes) and `.edges` (number of edges).
"""
function graph_properties(graph::DAG)
# make sure the graph is fully generated
apply_all!(graph)
@@ -23,6 +28,11 @@ function graph_properties(graph::DAG)
return result
end
"""
get_exit_node(graph::DAG)
Return the graph's exit node. This assumes the graph only has a single exit node. If the graph has multiple exit nodes, the one encountered first will be returned.
"""
function get_exit_node(graph::DAG)
for node in graph.nodes
if (is_exit_node(node))

43
src/graph/type.jl
View File

@@ -1,21 +1,28 @@
using DataStructures
"""
PossibleOperations
A struct storing all possible operations on a [`DAG`](@ref).
To get the [`PossibleOperations`](@ref) on a [`DAG`](@ref), use [`get_operations`](@ref).
"""
mutable struct PossibleOperations
nodeFusions::Set{NodeFusion}
nodeReductions::Set{NodeReduction}
nodeSplits::Set{NodeSplit}
end
function PossibleOperations()
return PossibleOperations(
Set{NodeFusion}(),
Set{NodeReduction}(),
Set{NodeSplit}(),
)
end
"""
DAG
# The actual state of the DAG is the initial state given by the set of nodes
# but with all the operations in appliedChain applied in order
The representation of the graph as a set of [`Node`](@ref)s.
A DAG can be loaded using the appropriate parse function, e.g. [`parse_abc`](@ref).
[`Operation`](@ref)s can be applied on it using [`push_operation!`](@ref) and reverted using [`pop_operation!`](@ref) like a stack.
To get the set of possible operations, use [`get_operations`](@ref).
The members of the object should not be manually accessed, instead always use the provided interface functions.
"""
mutable struct DAG
nodes::Set{Node}
@@ -36,6 +43,24 @@ mutable struct DAG
diff::Diff
end
"""
PossibleOperations()
Construct and return an empty [`PossibleOperations`](@ref) object.
"""
function PossibleOperations()
return PossibleOperations(
Set{NodeFusion}(),
Set{NodeReduction}(),
Set{NodeSplit}(),
)
end
"""
DAG()
Construct and return an empty [`DAG`](@ref).
"""
function DAG()
return DAG(
Set{Node}(),

11
src/graph/validate.jl
View File

@@ -1,4 +1,8 @@
# check whether the given graph is connected
"""
is_connected(graph::DAG)
Return whether the given graph is connected.
"""
function is_connected(graph::DAG)
nodeQueue = Deque{Node}()
push!(nodeQueue, get_exit_node(graph))
@@ -16,6 +20,11 @@ function is_connected(graph::DAG)
return length(seenNodes) == length(graph.nodes)
end
"""
is_valid(graph::DAG)
Validate the entire graph using asserts. Intended for testing with `@assert is_valid(graph)`.
"""
function is_valid(graph::DAG)
for node in graph.nodes
@assert is_valid(graph, node)