Refactor weight combination schemes

[wehs7661]

Checklist

This PR aims to not only address issue #29 but also include some additional tasks. Here is the checklist:

• Removing the functionality relevant to rmse_cutoff
• Removing the option final from the YAML parameter w_combine
  • Turning the YAML parameter w_combine into a boolean
  • Removing the function prepare_weights
• Deprecating the schemes of multiple swaps.
• Provide a YAML parameter w_mean_type to specify using simple means or weighted means in weight combination
• Compartmentalize the histogram correction method
• Update the documentation
• Update the unit tests

Some justifications

Generally, the idea is to simplify the options available in REXEE simulations, especially for those related to weight combinations. Since the weight combination does not seem to bring advantages, we plan to keep the most basic functionalities for demonstration purposes in the paper.

1. Removing the functionality relevant to rmse_cutoff

Preliminary data have shown that weight combination does not accelerate weight convergence in weight-updating simulations in most cases. Using rmse_cutoff was shown to alleviate the issue, but that is merely reflecting the fact that the combination is performed less frequently. Therefore, we decided to remove the YAML parameter rmse_cutoff and the relevant functionalities.

2. Removing the option final from the YAML parameter w_combine

The final weights are known to be noisy compared to the time-averaged weights and should never be used for weight combinations. Therefore, we decide to remove the option final from the choices of the YAML parameter w_combine. This would lead to only two options for w_combine, including None and avg. Therefore, we turned the parameter w_combine into a boolean - whenever weight combination is activated, we always use time-averaged weights. Additionally, we will need to remove the function prepare_weights.

3. Deprecating multiple exchange proposal scheme

As discussed in the paper, the multiple exchange proposal scheme does not have symmetric proposal probabilities, while the derivation of the acceptance ratio assumes symmetric proposal probabilities, which are much more common in replica exchange methods. That is, using the multiple exchange proposal scheme with the acceptance ratio derived in the paper would lead to a violation of the detailed balance. As such, we decided to deprecate the codes implementing the multiple exchange proposal scheme by commenting out the code. Note that we do not remove the codes completely as the detailed balance might still be obeyed if the acceptance ratio is carefully designed to accommodate the asymmetry of the proposal probabilities of the multiple exchange proposal scheme. Still, this is outside the scope of our paper, so the option will be made unavailable in the package. To do this, the following is required:

• Deprecate the YAML parameter n_ex.
• Deprecate the option multiple from the YAML parameter proposal.

4. Provide a YAML parameter to specify using simple means or weighted means in weight combination.

Currently, the implementation only uses inverse-variance weight means in weight combinations, but both options should be available as the inverse-variance weighted means do not always perform better than simple means.

5. Compartmentalize the histogram correction method

Currently, the histogram correction method is implemented in combine_weights and is always applied after weight combination. We decided to compartmentalize the histogram correction method and let users decide whether to perform histogram correction by specifying the new YAML parameter that we are also adding here, hist_corr.

[codecov]

Codecov Report

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

Comparison is base (19e0085) 54.40% compared to head (21ff0fd) 55.02%.

❗ Current head 21ff0fd differs from pull request most recent head 824d71b. Consider uploading reports for the commit 824d71b to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #31      +/-   ##
==========================================
+ Coverage   54.40%   55.02%   +0.61%     
==========================================
  Files           7        7              
  Lines        1542     1523      -19     
==========================================
- Hits          839      838       -1     
+ Misses        703      685      -18     

Files	Coverage Δ
ensemble_md/replica_exchange_EE.py	74.84% <94.28%> (+2.03%)	⬆️

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.