Add a LinkNavigator utility

[tmadlener]

BEGINRELEASENOTES

• Add a LinkNavigator utility class that facilitates the lookup of linked objects

ENDRELEASENOTES

The main working principle is:

// From MC to reco particles
auto& mc2recoLinks = event.get<RecoMCParticleLinkCollection>("MCRecoTruthLink");
auto mc2reco = LinkNavigator{mc2recoLinks};

auto& mcps = event.get<MCParticle>("MCParticles");
for (const auto p : mcps) {
  const auto recos = mc2reco.getLinked(p);
}

recos in this case is a std::vector<WeightedObject<ReconstructedParticle>>, which effectively just couples an object and a relation weight together. The foreseen usage is something like this:

for (const auto p : mcps) {
  for (const auto& [reco, weight] : mc2reco.getLinked(p)) {
    // do something with reco and the weight
  }
}

• Needs (includes) Allow for relations between two arbitrary types #255
• Documentation
• Handling of std::is_same_v<FromT, ToT>

[tmadlener]

This is now also ready for review and I would like to merge it before the next tag.

[andresailer]

I am confused about what the getLinkedFrom returns. It returns the "To" entries of the links, right?
But names like getToLinkedFromFrom and getFromLinkedFromTo also sound a bit ridiculous?

[tmadlener]

Yes, exactly. I started the naming for these from the arguments. Maybe we can drop that detail from the documentation as well, as for the majority of links, I assume the templated version will do correct thing in any case.

Alternatively, we could also introduce a two argument version that takes the direction as some enum?

[andresailer]

I think a two argument version of getLinked with an enum sounds less confusing and more explicit than getLinkedFrom.

[tmadlener]

I have introduced a version with an overload set that takes a second argument to decide on the direction. Is Lookup{From,To} clear enough?

[andresailer]

I proposed some word changes to avoid re-using to and from in the documentation strings.

I think instead of Lookup Return might be more explicit.

getLinked(recoParticle, ReturnFrom);

makes it more obvious that we return from objects?

[tmadlener]

Suggested change

	/// Get all the objects and weights that are linked to the passed object
	/// Get all the objects and weights that are linked from the passed object

(?)

[andresailer]

No?
Rather

Suggested change

	/// Get all the objects and weights that are linked to the passed object
	/// Get all the *To* objects and weights that have links with the passed object

[andresailer]

Suggested change

	/// Get all the objects and weights that are linked to the passed object
	/// Get all the *From* objects and weights that have links with the passed object

[andresailer]

Suggested change

	/// Tag variable to select the lookup of *From* objects that are linked from a
	/// *To* object in podio::LinkNavigator::getLinked
	/// Tag variable to select the lookup of *From* objects that have links with the given
	/// *To* object in podio::LinkNavigator::getLinked

[andresailer]

Suggested change

	/// Tag variable to select the lookup of *To* objects that are linked from a
	/// *From* object in podio::LinkNavigator::getLinked
	/// Tag variable to select the lookup of *To* objects that have links with the given
	/// *From* object in podio::LinkNavigator::getLinked

[tmadlener]

Thanks for the wording suggestions. Unless I missed some instances (which is not unlikely), I think it should now all be more or less self-consistent.

[tmadlener]

Suggested change

	The return type of all methods is a `std::vector<WeightedObject>`, where the
	The return type of all methods is a `std::vector<podio::detail::links::WeightedObject>`, where the

With the implicit question whether we should lift this object out of the (implicitly private) detail namespace, since it is in principle user facing.