Perform topological sort to order components

[cmacmackin]

Using the access control information introduced in #421, this PR makes it possible for Hermes-3 to work out the order of components at run-time. This will make things far simpler and more robust for users. It will also fail faster if there is an unsatisfiable or circular dependency.

Closes #384.

[cmacmackin]

This is nearly done. Remaining tasks:

• Merge Control access to state variables in transform method #421 and rebase.
• There is one integration test giving me strange h5py errors on my computer. It doesn't look to be related to any changes I've made. We'll see what happens in CI. I seem to recall we saw something similar elsewhere at one point.
• Update documentation.

[codecov]

Codecov Report

❌ Patch coverage is 50.97656% with 502 lines in your changes missing coverage. Please review.
✅ Project coverage is 53.56%. Comparing base (d66b56c) to head (5f3578c).

Files with missing lines	Patch %	Lines
include/fixed_fraction_radiation.hxx	0.00%	157 Missing ⚠️
src/sheath_boundary_simple.cxx	20.53%	89 Missing ⚠️
include/detachment_controller.hxx	73.52%	27 Missing ⚠️
src/binormal_stpm.cxx	33.33%	20 Missing ⚠️
include/temperature_feedback.hxx	63.46%	19 Missing ⚠️
src/electromagnetic.cxx	38.70%	19 Missing ⚠️
include/simple_pump.hxx	0.00%	18 Missing ⚠️
include/upstream_density_feedback.hxx	14.28%	18 Missing ⚠️
src/temperature_feedback.cxx	0.00%	17 Missing ⚠️
src/anomalous_diffusion.cxx	39.13%	14 Missing ⚠️
... and 31 more

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #428      +/-   ##
==========================================
+ Coverage   49.09%   53.56%   +4.46%     
==========================================
  Files          96       97       +1     
  Lines       10037    10217     +180     
  Branches     1452     1485      +33     
==========================================
+ Hits         4928     5473     +545     
+ Misses       4604     4220     -384     
- Partials      505      524      +19     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mikekryjak]

I missed this in #421, but I see that you added a long-needed feature - a better way to determine species type which is based on the charge:

hermes-3/src/component_scheduler.cxx

Lines 339 to 352 in 8fc17e0

	// FIXME: Would there be any spcies without AA? Is there any other
	// reliable way to identify what is a species?
	else if (component_options[name_trimmed].isSet("AA")) {
	if (component_options[name_trimmed].isSet("charge")) {
	const BoutReal charge = component_options[name_trimmed]["charge"];
	if (charge > 1e-5) {
	positive_ions.push_back(name_trimmed);
	} else if (charge < -1e-5) {
	negative_ions.push_back(name_trimmed);
	} else {
	neutrals.push_back(name_trimmed);
	}
	} else {
	neutrals.push_back(name_trimmed);

There is already a function that does the same in hermes_utils and is used in a few places in the code:

hermes-3/include/hermes_utils.hxx

Lines 61 to 70 in 053c9bb

	/// Identify species name string as electron, ion or neutral
	inline SpeciesType identifySpeciesType(const std::string& species) {
	if (species == "e") {
	return SpeciesType::electron;
	} else if ((species == "i") or
	species.find(std::string("+")) != std::string::npos) {
	return SpeciesType::ion;
	}
	// Not electron or ion -> neutral
	return SpeciesType::neutral;

Ideally there should be only one tool to do this, and your new one seems more robust. Is there any reason not to replace the one in hermes_utils with the new one?

[cmacmackin]

Ideally there should be only one tool to do this, and your new one seems more robust. Is there any reason not to replace the one in hermes_utils with the new one?

Probably not. I just wasn't sure if people would be happy about me changing that bit of code. Note that this will require changing the function signature of identifySpeciesType so that it takes the Options instead of just a string.

[mikekryjak]

I went through the sorting algorithm and I see that you have left a good amount of comments on the individual bits. However, I found it difficult to get my head around what's going on just because of the amount of steps involved. It would be very useful to have a paragraph describing how the algorithm works step-by-step, either in the docs or in the comments (or both)

[cmacmackin]

There are some places (e.g., when writing tests) where it was convenient to just be able to have a list of species names and use the old heuristics to categorise them. Probably not a good enough reason to keep that though.

[ZedThree]

LGTM, thanks @cmacmackin!

There's some trivial bits that I'm happy to fix myself

[cmacmackin]

I've merged in the changes from #596 as they are useful to writing error messages during the topological sort process.