Allow overriding of n_equilibration_iterations and statistical_inefficiency args for computation of free energy

[zhang-ivy]

Description

The MultiStateSamplerAnalyzer automatically determines n_equilibration_iterations and statistical inefficiency (g_t) here.

I have discovered that for my barnase:barstar repex simulations, number_equilibrated (aka n_equilibration_iterations) is always 1, which is too small. I'd like to be able to manually feed in n_equilibration_iterations and/or statistical inefficiency before retrieving the free energy.

This PR allows overriding n_equilibration_iterations and statistical_inefficiency in the following way:

# Given a MultiStateReporter, create a MultiStateSamplerAnalyzer
analyzer = MultiStateSamplerAnalyzer(reporter, max_n_iterations=3000, n_equilibration_iterations=2001, statistical_inefficiency=10)

# Compute free energy
f_ij, df_ij = analyzer.get_free_energy()

Note that the changes in this PR only affect the determination of the decorrelated samples (which are inputed to MBAR to compute the free energy). It does not effect functions like read_energies() or generate_mixing_statistics()

Replaces #585

Todos

• Implement feature / fix bug
• Add tests
• Update documentation as needed
• Update changelogNotable points that this PR has either accomplished or will accomplish.

Status

• Ready to go

[ijpulidos]

Looks good, thanks! Just some comments that I believe should be addressed.

[zhang-ivy]

@ijpulidos : I've updated the docstring to clarify the paper / equations that the variable names come from. Should be ready for another review!

[ijpulidos]

Looks good, thanks!