[hannahbaumann]

Description

LLM / AI generated code disclosure

LLMs or other AI-powered tools (beyond simple IDE use cases) were used in this contribution:

• No
• Yes: [If yes, please provide details here]

Checklist

• Read the AI Policy and filled in the AI-generated code disclosure.
• Adhered to the contribution guidelines
• All new code is appropriately documented (user-facing code must have complete docstrings).
• Ran pre-commit: you can run pre-commit locally or comment on this PR with pre-commit.ci autofix.
• Added a news entry, or the changes are not user-facing.

Manual Tests: these are slow so don't need to be run every commit, only before merging and when relevant changes are made (generally at reviewer-discretion).

• GPU integration tests
• example notebook testing
• packaging tests: run this for any large feature PRs or PRs that add test data.

Developers certificate of origin

• I certify that this contribution is covered by the MIT License here and the Developer Certificate of Origin at https://developercertificate.org/.

[atravitz]

this looks good, but as mentioned over in OpenFreeEnergy/ExampleNotebooks#359, I think it would make sense to move the protocol-specific explanations over to the user guide. Thoughts?

[hannahbaumann]

@atravitz I added some of the content from the notebook to the protocol user guides here and removed it in the notebooks!

[atravitz]

I think the content is good, but the single-paragraph format is confusing. I made a suggestion for making it more structured, but anything that makes it more readable is fine by me!

[atravitz]

Suggested change

	Each leg writes a multistate trajectory (``complex.nc`` and ``solvent.nc``) with its topology
	(``alchemical_system.pdb``). The trajectory stores the positions of every replica, together with the λ state each
	replica was in at each iteration. A trajectory can therefore be read in two ways: at a fixed λ **state**, combining
	frames from whichever replica occupied that state, or along a single **replica** as it moves between λ states.
	This applies to the default replica exchange sampler (``sampler_method = "repex"``).
	With ``"independent"`` sampling, replicas never change state, so both give the same trajectory;
	with ``"sams"``, a λ state is not necessarily occupied at every iteration, so reading by state may not be possible.
	Only the atoms selected by ``output_indices`` are saved, which by default excludes water.
	Both files can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states,
	Each leg writes:
	- a multistate trajectory (``complex.nc`` and ``solvent.nc``)
	- the trajectory's corresponding topology (``alchemical_system.pdb``)
	For the default replica exchange sampler (``sampler_method = "repex"``), the trajectory stores the positions of every replica, together with the λ state each replica was in at each iteration.
	A ``repex`` trajectory can therefore be read in two ways: at a fixed λ **state**, combining frames from whichever replica occupied that state, or along a single **replica** as it moves between λ states.
	With ``"independent"`` sampling, replicas never change state, so both give the same trajectory.
	With ``"sams"``, a λ state is not necessarily occupied at every iteration, so reading by state may not be possible.
	Only the atoms selected by ``output_indices`` are saved, which by default excludes water.
	Both files can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states,

I find the block of text difficult to parse as-is. Maybe breaking it up like this would help? It would also be good to link to/from the API sampler_method setting.