Add Topology.add_molecules

[mattwthompson]

Resolves #1916; modifying the reproduction to leverage this change (topology.add_molecule(n_solvent * [water])) indicates timing differences are within noise

(Timings are at 2ed0083, see edit history for others)

#n,add_molecules,from_molecules
100,0.004326343536376953,0.004456996917724609
200,0.008298158645629883,0.008605003356933594
300,0.01304483413696289,0.012480974197387695
400,0.016698837280273438,0.039669036865234375
500,0.02105402946472168,0.020509958267211914
600,0.023821115493774414,0.02369093894958496
700,0.054055213928222656,0.028130054473876953
800,0.03286099433898926,0.05617833137512207
900,0.03642416000366211,0.036705732345581055
1000,0.06891608238220215,0.04215121269226074
1100,0.07125687599182129,0.04464316368103027
1200,0.04902386665344238,0.07808613777160645
1300,0.052931785583496094,0.08499383926391602
1400,0.08034300804138184,0.05517315864562988
1500,0.08928894996643066,0.059242963790893555
1600,0.0911250114440918,0.09041094779968262
1700,0.06853795051574707,0.09943413734436035
1800,0.0976266860961914,0.07319378852844238
1900,0.11597585678100586,0.10258984565734863
2000,0.10834097862243652,0.0783381462097168
2100,0.11317706108093262,0.10875320434570312
2200,0.11331892013549805,0.11619782447814941
2300,0.1267378330230713,0.12550926208496094
2400,0.15245485305786133,0.12961506843566895
2500,0.1312239170074463,0.12987184524536133
2600,0.13352394104003906,0.1362438201904297
2700,0.13997626304626465,0.1558849811553955
2800,0.1441199779510498,0.14195513725280762
2900,0.14261388778686523,0.1425330638885498
3000,0.1729898452758789,0.1553659439086914
3100,0.16576695442199707,0.15640711784362793
3200,0.17840981483459473,0.16184210777282715
3300,0.18575620651245117,0.16659212112426758
3400,0.1914048194885254,0.16928482055664062
3500,0.1950390338897705,0.17164182662963867
3600,0.17933392524719238,0.2037489414215088
3700,0.1815779209136963,0.20410919189453125
3800,0.19510793685913086,0.21448493003845215
3900,0.20508909225463867,0.2175590991973877
4000,0.20284199714660645,0.30047607421875
4100,0.24508309364318848,0.21770095825195312
4200,0.22712087631225586,0.23752117156982422
4300,0.27291321754455566,0.23709893226623535
4400,0.24172306060791016,0.24338698387145996
4500,0.22370076179504395,0.3592557907104492
4600,0.25223612785339355,0.29245591163635254
4700,0.3019530773162842,0.2697610855102539
4800,0.30089807510375977,0.2619192600250244
4900,0.28049492835998535,0.2615830898284912
5000,0.2817862033843994,0.3020761013031006

• Tag issue being addressed
• Add tests
• Update docstrings/documentation, if applicable
• Lint codebase
• Update changelog

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.76%. Comparing base (c036e7b) to head (22165d2).
Report is 1 commits behind head on main.

Additional details and impacted files

[j-wags]

Apologies, now that I see it implemented (and reinforced by the need for @overload decorators), I think that making a new add_molecules API point is the way to go.

[mattwthompson]

I think this should be

Suggested change

	assert indices == [*range(1, 10_001)]
	assert indices == [*range(10_000)]

but the behavior (of both functions) is to return a 1-indexed index whereas I expected 0-indexed: #1922

[j-wags]

(not blocking) Agree, please feel free to change this behavior for add_molecule and add_molecules in this PR (though you've already gone through one major change so we can also handle this in a future PR if you prefer).

[j-wags]

Excellent - This is good to merge as-is, or feel free to also fix #1922 and include it in the releasenotes. Thanks @mattwthompson!

[j-wags]

(not blocking) Agree, please feel free to change this behavior for add_molecule and add_molecules in this PR (though you've already gone through one major change so we can also handle this in a future PR if you prefer).

[mattwthompson]

Thanks - my preference is to (and I will) do them in separate PRs - but it'd be nice for them to be a part of the same release. If nothing surprising pops up I'll have the next one up shortly