From 122e428efe7b212c7e886fa52ba11911c56ac89c Mon Sep 17 00:00:00 2001 From: Anton Reinhard Date: Sat, 26 Aug 2023 20:29:43 +0200 Subject: [PATCH] Continue documenting --- src/graph/mute.jl | 44 +++++++++++++++++++++++++++++++++++------ src/graph/print.jl | 12 ++++++++++- src/graph/properties.jl | 10 ++++++++++ src/graph/type.jl | 13 +++++++++++- src/graph/validate.jl | 11 ++++++++++- src/models/abc/parse.jl | 18 ++++++++++++++++- 6 files changed, 98 insertions(+), 10 deletions(-) diff --git a/src/graph/mute.jl b/src/graph/mute.jl index e572d6b..1f71f3a 100644 --- a/src/graph/mute.jl +++ b/src/graph/mute.jl @@ -179,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) @@ -197,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) @@ -208,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) @@ -219,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) @@ -233,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) diff --git a/src/graph/print.jl b/src/graph/print.jl index 7717724..729b14c 100644 --- a/src/graph/print.jl +++ b/src/graph/print.jl @@ -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: ") diff --git a/src/graph/properties.jl b/src/graph/properties.jl index da254d2..ed5e985 100644 --- a/src/graph/properties.jl +++ b/src/graph/properties.jl @@ -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)) diff --git a/src/graph/type.jl b/src/graph/type.jl index 11ad5dc..f65c228 100644 --- a/src/graph/type.jl +++ b/src/graph/type.jl @@ -15,9 +15,10 @@ end """ DAG -The DAG is the representation of the graph as a set of nodes. +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. @@ -42,6 +43,11 @@ mutable struct DAG diff::Diff end +""" + PossibleOperations() + +Construct and return an empty [`PossibleOperations`](@ref) object. +""" function PossibleOperations() return PossibleOperations( Set{NodeFusion}(), @@ -50,6 +56,11 @@ function PossibleOperations() ) end +""" + DAG() + +Construct and return an empty [`DAG`](@ref). +""" function DAG() return DAG( Set{Node}(), diff --git a/src/graph/validate.jl b/src/graph/validate.jl index d2c7dba..c033d2f 100644 --- a/src/graph/validate.jl +++ b/src/graph/validate.jl @@ -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) diff --git a/src/models/abc/parse.jl b/src/models/abc/parse.jl index e5ed4c5..1ea6fac 100644 --- a/src/models/abc/parse.jl +++ b/src/models/abc/parse.jl @@ -6,6 +6,11 @@ regex_c = r"^[A-C]\(([^']*),([^']*)\)$" # Regex for the combinations of 2 pa regex_m = r"^M\(([^']*),([^']*),([^']*)\)$" # Regex for the combinations of 3 particles regex_plus = r"^\+$" # Regex for the sum +""" + parse_nodes(input::AbstractString) + +Parse the given string into a vector of strings containing each node. +""" function parse_nodes(input::AbstractString) regex = r"'([^']*)'" matches = eachmatch(regex, input) @@ -13,6 +18,11 @@ function parse_nodes(input::AbstractString) return output end +""" + parse_edges(input::AbstractString) + +Parse the given string into a vector of strings containing each edge. Currently unused since the entire graph can be read from just the node names. +""" function parse_edges(input::AbstractString) regex = r"\('([^']*)', '([^']*)'\)" matches = eachmatch(regex, input) @@ -20,7 +30,13 @@ function parse_edges(input::AbstractString) return output end -# reads an abc-model process from the given file +""" + parse_abc(filename::String; verbose::Bool = false) + +Read an abc-model process from the given file. If `verbose` is set to true, print some progress information to stdout. + +Returns a valid [`DAG`](@ref). +""" function parse_abc(filename::String, verbose::Bool = false) file = open(filename, "r")