Document common residue-related system preparation operations

[mattwthompson]

Is your feature request related to a problem? Please describe.

I'd like to be able to pass a residue name onto a molecule, or multiple residues scattered about within a molecule, and later trust iterators like

residue_names = [
    residue.residue_name for residue in topology.hierarchy_iterator("residues")
]

I have no idea how to do this and couldn't find documentation on it.

Describe the solution you'd like

ParmEd offers a convenient way to set the residue of a molecule. It would be nice to be able to this as simply with the toolkit, or document how to do it as simply as possible:

>>> import parmed
Warning: importing 'simtk.openmm' is deprecated.  Import 'openmm' instead.
>>> structure = parmed.load_file("out.pdb")
>>> structure.residues[0].name = 'YUP'
>>> structure.residues
ResidueList([
	<Residue YUP[1]; chain=A>
])

I'd also be nice to add some safeguards while working with default hierarchy schemes - i.e. residues with names and numbers, chains, and possibly insertion codes - to avoid weird states such as duplicate schemes, empty schemes, atoms and elements out of sync, etc.

Describe alternatives you've considered

I tried a handful of things - adding a bunch of HierarchySchemes and HierarchyElements, using Molecule.add_default_hierarchy_schemes, directly modifying each Atoms's .metadata dictionary, but everything I did was wrong. I got mismatches between what's stored in different schemes and atoms, some duplicate schemes, some empty schemes, a whole mess of a mess.

Additional context

I found some information searching the docs, but nothing that describes how to do this at a high level or the internal machinery of how this works.

This is a common user operation so we should consider appending to the Molecule cookbook or creating a new section altogether.

I consider tidying chemical topologies the domain of the toolkit, although Interchange will be where users complain about metadata being scrambled.

[j-wags]

Agreed - This could be a good one for a cookbook entry or example notebook. It could do something like showing a workflow that loads two proteins that are both "chain A" and a ligand with no chain info, and needs to get them into a format where the output molecules must all have distinct chain ids.