Aleaverfay/create atom index mapping b/w PoseStack and CanonicalForm

[aleaverfay]

Adding an extra argument to the pose_stack_from_canonical_form function, return_atom_mapping, that will cause the function to return a mapping between the atom indices in the input canonical form and the atom indices in the pose stack that was created. This mapping will ease the access into and out of PoseStack.

From the documentation:

return_atom_mapping: return the mapping for atoms in the canonical-form tensor
        to their PoseStack index; this could be used to update the coordinates
        in a PoseStack without rebuilding it (as long as the chemical identity
        is meant to be unchanged) or to perhaps remap derivatives to or from
        pose stack ordering. If requested, the atom mapping will be the last two
        arguments returned by this function, as two tensors:
            ps, t1, t2 = pose_stack_from_canonical_form(
                ...,
                return_atom_mapping=True
            )
            can_ord_coords[
                t1[:, 0], t1[:, 1], t1[:, 2]
            ] = ps.coords[
                t2[:, 0], t2[:, 1]
            ]
        where t1 is a tensor nats x 3 where
        - position [i, 0] is the pose index
        - position [i, 1] is the residue index, and
        - position [i, 2] is the canonical-ordering atom index
        and t2 is a tensor nats x 2 where
        - position [i, 0] is the pose index, and
        - position [i, 1] is the pose-ordered atom index

[codecov[bot]]

Codecov Report

Attention: 31 lines in your changes are missing coverage. Please review.

Comparison is base (b8940ef) 95.13% compared to head (b0fc2f2) 94.86%. Report is 5 commits behind head on master.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #279 +/- ## ========================================== - Coverage 95.13% 94.86% -0.27% ========================================== Files 340 365 +25 Lines 21546 23509 +1963 ========================================== + Hits 20497 22301 +1804 - Misses 1049 1208 +159 ``` | [Flag](https://app.codecov.io/gh/uw-ipd/tmol/pull/279/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd) | Coverage Δ | | |---|---|---| | [_shrug_Testing_CPU](https://app.codecov.io/gh/uw-ipd/tmol/pull/279/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd) | `89.88% <95.08%> (-0.11%)` | :arrow_down: | | [_shrug_Testing_CPU_w_o_jit](https://app.codecov.io/gh/uw-ipd/tmol/pull/279/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd) | `91.71% <96.90%> (-0.11%)` | :arrow_down: | | [_shrug_Testing_CUDA](https://app.codecov.io/gh/uw-ipd/tmol/pull/279/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd) | `92.26% <96.66%> (-0.21%)` | :arrow_down: | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#carryforward-flags-in-the-pull-request-comment) to find out more. | [Files](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd) | Coverage Δ | | |---|---|---| | [tmol/\_\_init\_\_.py](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#diff-dG1vbC9fX2luaXRfXy5weQ==) | `100.00% <100.00%> (ø)` | | | [tmol/chemical/restypes.py](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#diff-dG1vbC9jaGVtaWNhbC9yZXN0eXBlcy5weQ==) | `94.44% <100.00%> (+0.39%)` | :arrow_up: | | [tmol/io/details/canonical\_packed\_block\_types.py](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#diff-dG1vbC9pby9kZXRhaWxzL2Nhbm9uaWNhbF9wYWNrZWRfYmxvY2tfdHlwZXMucHk=) | `100.00% <100.00%> (ø)` | | | [tmol/io/details/compiled/compiled.py](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#diff-dG1vbC9pby9kZXRhaWxzL2NvbXBpbGVkL2NvbXBpbGVkLnB5) | `100.00% <100.00%> (ø)` | | | [tmol/io/details/his\_taut\_resolution.py](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#diff-dG1vbC9pby9kZXRhaWxzL2hpc190YXV0X3Jlc29sdXRpb24ucHk=) | `100.00% <100.00%> (ø)` | | | [tmol/io/details/left\_justify\_canonical\_form.py](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#diff-dG1vbC9pby9kZXRhaWxzL2xlZnRfanVzdGlmeV9jYW5vbmljYWxfZm9ybS5weQ==) | `100.00% <100.00%> (ø)` | | | [tmol/pack/rotamer/build\_rotamers.py](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#diff-dG1vbC9wYWNrL3JvdGFtZXIvYnVpbGRfcm90YW1lcnMucHk=) | `100.00% <ø> (ø)` | | | [tmol/pose/packed\_block\_types.py](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#diff-dG1vbC9wb3NlL3BhY2tlZF9ibG9ja190eXBlcy5weQ==) | `99.20% <100.00%> (+0.09%)` | :arrow_up: | | [tmol/pose/pose\_stack\_builder.py](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#diff-dG1vbC9wb3NlL3Bvc2Vfc3RhY2tfYnVpbGRlci5weQ==) | `97.61% <100.00%> (+0.69%)` | :arrow_up: | | [tmol/score/\_\_init\_\_.py](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd#diff-dG1vbC9zY29yZS9fX2luaXRfXy5weQ==) | `100.00% <100.00%> (ø)` | | | ... and [57 more](https://app.codecov.io/gh/uw-ipd/tmol/pull/279?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd) | | ... and [6 files with indirect coverage changes](https://app.codecov.io/gh/uw-ipd/tmol/pull/279/indirect-changes?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=uw-ipd)

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.