Fully-featured Primitive resolution shift operations

[timbernat]

Description

The core toolkit functionality added in #4 only supplies hierarchy expansion operations (in less general terms, CG -> AA backmap), but no contraction operations (i.e. bespoke coarse-graining from finer reolustion systems). Further, the implementation of expansion provided there is poorly-scalable, taking significant time even for systems on the order of 10k atoms, due to reliance on atomic operations on individual primitives, rather than caching information and making use of larger organizational units within the representaion (i.e. avoiding the "deregister -> reregister/relabel -> reconnect to neighbors" path taken now). This was a deliberate choice to facilitate reasoning about the correctness of the program and simplify implementation, but would benefit from more targeted optimization now that it has been tested in example workflows.

Todos

Notable points that this PR has either accomplished or will accomplish.

• Implement Primitive.contract(), allowing an intermediate level to be injected into a hierarchy between a parent Primitive and its children based on a partition of those children
  • Impose check on partitions which enforces that no more than one connection (pair of Connectors/edge) spans between any two parts
  • Write out-of-place version of contract (e.g. Primitive.contracted())
• Implement Primitive.cauterize(), which cut off all structure below a certain subprimitive in the hierarchy to mark it as a target for export
• Accelerate the implementation of Primitive.expand()
  • Implement native API for reassigning (still unique!) handles to children without de- and then re-registering them
  • Replace individual graph node/edge additions with graph unions of grandchild topology (requires aforementioned uniquification to be well-defined)
  • Implement total hierarchy-wide label uniquification in tree rendering (not directly relevant, but would be enabled by the same kind of tree-wde handle uniquification required for the above)

Questions

• Are there real, "interesting" systems which the no-multiedge restriction on contraction precludes from being represented? Certain classes of polyimides come to mind (multiple bonds between repeat units), but it may be possible to treat these systems with a different partition into repeat units. Feedback is needed from simulation folks

Status

• Opened non-draft PR
• Passed tests
• Passed co-dev review
  • Passed Copilot review to catch dumb spelling errors etc.
• Ready to go