Hydrofabric network cycle detection

[hellkite500]

Cycles in the hydrofabric topology can cause a boost::not_a_dag exception to occur (when performing topological sort of the graph, for example.)

This exception, however, doesn't provide any useful context to determine what part of the hydrofabric creates/contributes to the cycle to be investigated.

This PR provides a custom cycle detection visitor which records the vertices of all back edges in the graph. This visitor is then used in the init_indicies function of all network creation to run an undirected depth first search and record the cycles. All cycles are identified and the vertices are mapped back to the hydrofabric ID and reported in a std::domain_error exception message that looks like

Cycle(s) detected in hydrofabric
The following features form a cycle:
        nex-1 --> cat-0

Additions

• detect_cycles visitor

Removals

• None

Changes

• std::domain_error thrown in network creation when cycles are detected

Testing

1. New test added which attempts to create a Network using a topology which has a cycle

Notes

Some additional code is left in the visitor implementation commented out. If additional information about hydrofabric features involved in the cycle are needed, it can be used to provide all vertices related to a reported cycle.

Checklist

• PR has an informative and human-readable title
• Changes are limited to a single goal (no scope creep)
• Code can be automatically merged (no conflicts)
• Code follows project standards (link if applicable)
• Passes all existing automated tests
• Any change in functionality is tested
• New functions are documented (with a description, list of inputs, and expected output)
• Placeholder code is flagged / future todos are captured in comments
• Project documentation has been updated (including the "Unreleased" section of the CHANGELOG)
• Reviewers requested with the Reviewers tool ➡️

Target Environment support

• Linux
• MacOS

[PhilMiller]

As phrased, this message might confusingly suggest that the identifying elements of distinct cycles are actually the set of elements in a single cycle

[hellkite500]

Would something like

Cycle(s) detected in hydrofabric
The following features form the connecting edge of a cycle:
        nex-1 --> cat-0

be more clear?

[PhilMiller]

I think that's an improvement. Maybe "The following features each form the connecting edge of a cycle" (added 'each')?

I realize we probably don't need to word-smith this much more, since anyone encountering this is pretty likely to make their way back to us to help with getting it resolved.

[hellkite500]

I like added "each" to be clear when multiple cycles are found. I'll touch it up and rebase.

[PhilMiller]

Suggested change

	detect_cycles vis(&cycles);
	//Run an undirected, depth first search applying the loop detector visitor
	//cycles added as vertex pairs for the closing edge of the cycle
	boost::undirected_dfs(this->graph, vis, make_assoc_property_map(vis.vertex_coloring), make_assoc_property_map(vis.edge_coloring));
	detect_cycles cycles_visitor(&cycles);
	//Run an undirected, depth first search applying the loop detector visitor
	//cycles added as vertex pairs for the closing edge of the cycle
	boost::undirected_dfs(this->graph, cycles_visitor, make_assoc_property_map(vis.vertex_coloring), make_assoc_property_map(vis.edge_coloring));

Just making the name a bit more verbose for clarity. Alternately,

Suggested change

	detect_cycles vis(&cycles);
	//Run an undirected, depth first search applying the loop detector visitor
	//cycles added as vertex pairs for the closing edge of the cycle
	boost::undirected_dfs(this->graph, vis, make_assoc_property_map(vis.vertex_coloring), make_assoc_property_map(vis.edge_coloring));
	//Run an undirected, depth first search applying the loop detector visitor
	//cycles added as vertex pairs for the closing edge of the cycle
	boost::undirected_dfs(this->graph, detect_cycles(&cycles), make_assoc_property_map(vis.vertex_coloring), make_assoc_property_map(vis.edge_coloring));

Just don't name the temporary visitor object at all

[PhilMiller]

I think I like the latter a bit better