diff --git a/docs/Project.toml b/docs/Project.toml index 99f7845..f018ae3 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,6 +1,7 @@ [deps] BasicMD = "f448d96e-cc9b-4179-976a-6795f3ef2db6" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244" ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210" HypothesisTests = "09f84164-cd44-5f33-b23f-e6b0d136a0d5" Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" diff --git a/docs/make.jl b/docs/make.jl index ed623cc..cf81e84 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -9,9 +9,18 @@ if abspath(PROGRAM_FILE) == @__FILE__ end using WeightedEnsemble using Documenter +using DocumenterCitations + +bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"); style=:numeric) + makedocs(checkdocs=:none, sitename = "WeightedEnsemble.jl", modules = [WeightedEnsemble], + format=Documenter.HTML( + # ... + assets=String["assets/citations.css"], + ), + plugins=[bib], pages=[ "Home" => "index.md", "Structures" => "struct1.md", @@ -21,7 +30,9 @@ makedocs(checkdocs=:none, "Coarse Modeling" => "coarse1.md", "Utility Functions" => "util1.md", "Weighted Ensemble Methods" => "we1.md", - "Examples"=>["examples/equil1.md"] + "Examples"=>["examples/equil1.md"], + "References"=>"refs1.md", + "API"=>"api.md" ]) deploydocs(; repo="github.com/gideonsimpson/WeightedEnsemble.jl", diff --git a/docs/src/api.md b/docs/src/api.md new file mode 100644 index 0000000..aa651b9 --- /dev/null +++ b/docs/src/api.md @@ -0,0 +1,4 @@ +# Index + +```@index +``` diff --git a/docs/src/assets/citations.css b/docs/src/assets/citations.css new file mode 100644 index 0000000..2d2be76 --- /dev/null +++ b/docs/src/assets/citations.css @@ -0,0 +1,28 @@ +.citation dl { + display: grid; + grid-template-columns: max-content auto; +} + +.citation dt { + grid-column-start: 1; +} + +.citation dd { + grid-column-start: 2; + margin-bottom: 0.75em; +} + +.citation ul { + padding: 0 0 2.25em 0; + margin: 0; + list-style: none !important; +} + +.citation ul li { + text-indent: -2.25em; + margin: 0.33em 0.5em 0.5em 2.25em; +} + +.citation ol li { + padding-left: 0.75em; +} \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md index d6aedec..5089197 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -36,6 +36,9 @@ stored in an [`Ensemble`](@ref) data structure. The ensemble is evolved, successively, in two steps, _selection_ and _mutation_. As the partilces and weights evolve in time, we add a ``t`` subscript to indicate that these quantities change, ``\{(\omega_t^{i},\xi_t^{i}\}``. +This implementation has been used in [aristoff_weighted_2023, webber_splitting_2020](@cite). It is heavily influenced by the algoirthmic +description found in [aristoff_optimizing_2020](@cite). + ### Selection During the selection step, particles are resampled from the empirical distribution in such a way so as to maintain unbiasedness _and_ reduce variance @@ -149,16 +152,3 @@ parallelize the selection step. ## Acknowledgements This work was supported in part by the US National Science Foundation Grants DMS-1818716 and DMS-2111278. -## References - 1. Aristoff, D., Copperman, J., Simpson, G., Webber, R. J. & Zuckerman, D. M. Weighted ensemble: Recent mathematical developments. J. Chem. Phys. 158, 014108 (2023). - 2. Russo, J. D. et al. WESTPA 2.0: High-Performance Upgrades for Weighted Ensemble Simulations and Analysis of Longer-Timescale Applications. J. Chem. Theory Comput. 18, 638–649 (2022). - 3. Aristoff, D. An ergodic theorem for the weighted ensemble method. arXiv:1906.00856 (2021). - 4. Webber, R. J., Aristoff, D., & Simpson, G. A splitting method to reduce MCMC variance. arXiv:2011.13899 (2020) - 5. Aristoff, D. & Zuckerman, D. M. Optimizing Weighted Ensemble Sampling of Steady States. Multiscale Model. Simul. 18, 646–673 (2020). - 6. Huber, G. A. & Kim, S. Weighted-ensemble Brownian dynamics simulations for protein association reactions. Biophysical Journal 70, 97–110 (1996). - 7. Douc, R. & Cappe, O. Comparison of resampling schemes for particle filtering. in ISPA 2005. Proceedings of the 4th International Symposium on Image and Signal Processing and Analysis, 2005. 64–69 (IEEE, Zagreb, Croatia, 2005). doi:10.1109/ISPA.2005.195385. - -## Index -```@index -``` - diff --git a/docs/src/refs.bib b/docs/src/refs.bib new file mode 100644 index 0000000..35e4d35 --- /dev/null +++ b/docs/src/refs.bib @@ -0,0 +1,185 @@ + +@article{russo_westpa_2022, + title = {{WESTPA} 2.0: {High}-{Performance} {Upgrades} for {Weighted} {Ensemble} {Simulations} and {Analysis} of {Longer}-{Timescale} {Applications}}, + volume = {18}, + issn = {1549-9618}, + shorttitle = {{WESTPA} 2.0}, + url = {https://doi.org/10.1021/acs.jctc.1c01154}, + doi = {10.1021/acs.jctc.1c01154}, + abstract = {The weighted ensemble (WE) family of methods is one of several statistical mechanics-based path sampling strategies that can provide estimates of key observables (rate constants and pathways) using a fraction of the time required by direct simulation methods such as molecular dynamics or discrete-state stochastic algorithms. WE methods oversee numerous parallel trajectories using intermittent overhead operations at fixed time intervals, enabling facile interoperability with any dynamics engine. Here, we report on the major upgrades to the WESTPA software package, an open-source, high-performance framework that implements both basic and recently developed WE methods. These upgrades offer substantial improvements over traditional WE methods. The key features of the new WESTPA 2.0 software enhance the efficiency and ease of use: an adaptive binning scheme for more efficient surmounting of large free energy barriers, streamlined handling of large simulation data sets, exponentially improved analysis of kinetics, and developer-friendly tools for creating new WE methods, including a Python API and resampler module for implementing both binned and “binless” WE strategies.}, + number = {2}, + urldate = {2022-04-11}, + journal = {Journal of Chemical Theory and Computation}, + author = {Russo, John D. and Zhang, She and Leung, Jeremy M. G. and Bogetti, Anthony T. and Thompson, Jeff P. and DeGrave, Alex J. and Torrillo, Paul A. and Pratt, A. J. and Wong, Kim F. and Xia, Junchao and Copperman, Jeremy and Adelman, Joshua L. and Zwier, Matthew C. and LeBard, David N. and Zuckerman, Daniel M. and Chong, Lillian T.}, + month = feb, + year = {2022}, + note = {Publisher: American Chemical Society}, + pages = {638--649}, + file = {ACS Full Text Snapshot:/Users/grs53/Zotero/storage/9Z6QAG44/acs.jctc.html:text/html;Russo et al. - 2022 - WESTPA 2.0 High-Performance Upgrades for Weighted.pdf:/Users/grs53/Zotero/storage/E8LJLWT9/Russo et al. - 2022 - WESTPA 2.0 High-Performance Upgrades for Weighted.pdf:application/pdf}, +} + +@article{aristoff_optimizing_2020, + title = {Optimizing {Weighted} {Ensemble} {Sampling} of {Steady} {States}}, + volume = {18}, + issn = {1540-3459, 1540-3467}, + url = {https://epubs.siam.org/doi/10.1137/18M1212100}, + doi = {10.1137/18M1212100}, + abstract = {We propose parameter optimization techniques for weighted ensemble sampling of Markov chains in the steady-state regime. Weighted ensemble consists of replicas of a Markov chain, each carrying a weight, that are periodically resampled according to their weights inside of each of a number of bins that partition state space. We derive, from first principles, strategies for optimizing the choices of weighted ensemble parameters, in particular the choice of bins and the number of replicas to maintain in each bin. In a simple numerical example, we compare our new strategies with more traditional ones and with direct Monte Carlo.}, + language = {en}, + number = {2}, + urldate = {2022-04-13}, + journal = {Multiscale Modeling \& Simulation}, + author = {Aristoff, David and Zuckerman, Daniel M.}, + month = jan, + year = {2020}, + pages = {646--673}, + file = {Aristoff and Zuckerman - 2020 - Optimizing Weighted Ensemble Sampling of Steady St.pdf:/Users/grs53/Zotero/storage/YL7K7BMJ/Aristoff and Zuckerman - 2020 - Optimizing Weighted Ensemble Sampling of Steady St.pdf:application/pdf}, +} + +@article{aristoff_weighted_2023, + title = {Weighted ensemble: {Recent} mathematical developments}, + volume = {158}, + issn = {0021-9606, 1089-7690}, + shorttitle = {Weighted ensemble}, + url = {https://aip.scitation.org/doi/10.1063/5.0110873}, + doi = {10.1063/5.0110873}, + abstract = {Weighted ensemble (WE) is an enhanced sampling method based on periodically replicating and pruning trajectories generated in parallel. WE has grown increasingly popular for computational biochemistry problems due, in part, to improved hardware and accessible software implementations. Algorithmic and analytical improvements have played an important role, and progress has accelerated in recent years. Here, we discuss and elaborate on the WE method from a mathematical perspective, highlighting recent results that enhance the computational efficiency. The mathematical theory reveals a new strategy for optimizing trajectory management that approaches the best possible variance while generalizing to systems of arbitrary dimension.}, + language = {en}, + number = {1}, + urldate = {2023-03-08}, + journal = {The Journal of Chemical Physics}, + author = {Aristoff, D. and Copperman, J. and Simpson, G. and Webber, R. J. and Zuckerman, D. M.}, + month = jan, + year = {2023}, + pages = {014108}, + file = {Aristoff et al. - 2023 - Weighted ensemble Recent mathematical development.pdf:/Users/grs53/Zotero/storage/2TNPINDX/Aristoff et al. - 2023 - Weighted ensemble Recent mathematical development.pdf:application/pdf}, +} + +@article{aristoff_ergodic_2022, + title = {An ergodic theorem for the weighted ensemble method}, + volume = {59}, + issn = {0021-9002, 1475-6072}, + url = {https://www.cambridge.org/core/product/identifier/S0021900221000383/type/journal_article}, + doi = {10.1017/jpr.2021.38}, + abstract = {We study weighted ensemble, an interacting particle method for sampling distributions of Markov chains that has been used in computational chemistry since the 1990s. Many important applications of weighted ensemble require the computation of long time averages. We establish the consistency of weighted ensemble in this setting by proving an ergodic theorem for time averages. As part of the proof, we derive explicit variance formulas that could be useful for optimizing the method.}, + language = {en}, + number = {1}, + urldate = {2024-03-15}, + journal = {Journal of Applied Probability}, + author = {Aristoff, David}, + month = mar, + year = {2022}, + pages = {152--166}, + file = {Aristoff - 2022 - An ergodic theorem for the weighted ensemble metho.pdf:/Users/grs53/Zotero/storage/N3IGJGRK/Aristoff - 2022 - An ergodic theorem for the weighted ensemble metho.pdf:application/pdf}, +} + + +@article{russo_westpa_2022, + title = {{WESTPA} 2.0: {High}-{Performance} {Upgrades} for {Weighted} {Ensemble} {Simulations} and {Analysis} of {Longer}-{Timescale} {Applications}}, + volume = {18}, + issn = {1549-9618}, + shorttitle = {{WESTPA} 2.0}, + url = {https://doi.org/10.1021/acs.jctc.1c01154}, + doi = {10.1021/acs.jctc.1c01154}, + abstract = {The weighted ensemble (WE) family of methods is one of several statistical mechanics-based path sampling strategies that can provide estimates of key observables (rate constants and pathways) using a fraction of the time required by direct simulation methods such as molecular dynamics or discrete-state stochastic algorithms. WE methods oversee numerous parallel trajectories using intermittent overhead operations at fixed time intervals, enabling facile interoperability with any dynamics engine. Here, we report on the major upgrades to the WESTPA software package, an open-source, high-performance framework that implements both basic and recently developed WE methods. These upgrades offer substantial improvements over traditional WE methods. The key features of the new WESTPA 2.0 software enhance the efficiency and ease of use: an adaptive binning scheme for more efficient surmounting of large free energy barriers, streamlined handling of large simulation data sets, exponentially improved analysis of kinetics, and developer-friendly tools for creating new WE methods, including a Python API and resampler module for implementing both binned and “binless” WE strategies.}, + number = {2}, + urldate = {2022-04-11}, + journal = {Journal of Chemical Theory and Computation}, + author = {Russo, John D. and Zhang, She and Leung, Jeremy M. G. and Bogetti, Anthony T. and Thompson, Jeff P. and DeGrave, Alex J. and Torrillo, Paul A. and Pratt, A. J. and Wong, Kim F. and Xia, Junchao and Copperman, Jeremy and Adelman, Joshua L. and Zwier, Matthew C. and LeBard, David N. and Zuckerman, Daniel M. and Chong, Lillian T.}, + month = feb, + year = {2022}, + note = {Publisher: American Chemical Society}, + pages = {638--649}, + file = {ACS Full Text Snapshot:/Users/grs53/Zotero/storage/9Z6QAG44/acs.jctc.html:text/html;Russo et al. - 2022 - WESTPA 2.0 High-Performance Upgrades for Weighted.pdf:/Users/grs53/Zotero/storage/E8LJLWT9/Russo et al. - 2022 - WESTPA 2.0 High-Performance Upgrades for Weighted.pdf:application/pdf} +} + +@article{aristoff_weighted_2023, + title = {Weighted ensemble: {Recent} mathematical developments}, + volume = {158}, + issn = {0021-9606, 1089-7690}, + shorttitle = {Weighted ensemble}, + url = {https://aip.scitation.org/doi/10.1063/5.0110873}, + doi = {10.1063/5.0110873}, + abstract = {Weighted ensemble (WE) is an enhanced sampling method based on periodically replicating and pruning trajectories generated in parallel. WE has grown increasingly popular for computational biochemistry problems due, in part, to improved hardware and accessible software implementations. Algorithmic and analytical improvements have played an important role, and progress has accelerated in recent years. Here, we discuss and elaborate on the WE method from a mathematical perspective, highlighting recent results that enhance the computational efficiency. The mathematical theory reveals a new strategy for optimizing trajectory management that approaches the best possible variance while generalizing to systems of arbitrary dimension.}, + language = {en}, + number = {1}, + urldate = {2023-03-08}, + journal = {The Journal of Chemical Physics}, + author = {Aristoff, D. and Copperman, J. and Simpson, G. and Webber, R. J. and Zuckerman, D. M.}, + month = jan, + year = {2023}, + pages = {014108}, + file = {Aristoff et al. - 2023 - Weighted ensemble Recent mathematical development.pdf:/Users/grs53/Zotero/storage/2TNPINDX/Aristoff et al. - 2023 - Weighted ensemble Recent mathematical development.pdf:application/pdf} +} + +@article{aristoff_ergodic_2022, + title = {An ergodic theorem for the weighted ensemble method}, + volume = {59}, + issn = {0021-9002, 1475-6072}, + url = {https://www.cambridge.org/core/product/identifier/S0021900221000383/type/journal_article}, + doi = {10.1017/jpr.2021.38}, + abstract = {We study weighted ensemble, an interacting particle method for sampling distributions of Markov chains that has been used in computational chemistry since the 1990s. Many important applications of weighted ensemble require the computation of long time averages. We establish the consistency of weighted ensemble in this setting by proving an ergodic theorem for time averages. As part of the proof, we derive explicit variance formulas that could be useful for optimizing the method.}, + language = {en}, + number = {1}, + urldate = {2024-03-15}, + journal = {Journal of Applied Probability}, + author = {Aristoff, David}, + month = mar, + year = {2022}, + pages = {152--166}, + file = {Aristoff - 2022 - An ergodic theorem for the weighted ensemble metho.pdf:/Users/grs53/Zotero/storage/N3IGJGRK/Aristoff - 2022 - An ergodic theorem for the weighted ensemble metho.pdf:application/pdf} +} + +@article{huber_weighted-ensemble_1996, + title = {Weighted-ensemble {Brownian} dynamics simulations for protein association reactions}, + volume = {70}, + issn = {00063495}, + url = {https://linkinghub.elsevier.com/retrieve/pii/S0006349596795528}, + doi = {10.1016/S0006-3495(96)79552-8}, + abstract = {A new method, weighted-ensemble Brownian dynamics, is proposed for the simulation of protein-association reactions and other events whose frequencies of outcomes are constricted by free energy barriers. The method features a weighted ensemble of trajectories in configuration space with energy levels dictating the proper correspondence between "particles" and probability. Instead of waiting a very long time for an unlikely event to occur, the probability packets are split, and small packets of probability are allowed to diffuse almost immediately into regions of configuration space that are less likely to be sampled. The method has been applied to the Northrup and Erickson (1992) model of docking-type diffusionlimited reactions and yields reaction rate constants in agreement with those obtained by direct Brownian simulation, but at a fraction of the CPU time (10-4 to 10-3, depending on the model). Because the method is essentially a variant of standard Brownian dynamics algorithms, it is anticipated that weighted-ensemble Brownian dynamics, in conjunction with biophysical force models, can be applied to a large class of association reactions of interest to the biophysics community.}, + language = {en}, + number = {1}, + urldate = {2022-05-09}, + journal = {Biophysical Journal}, + author = {Huber, G.A. and Kim, S.}, + month = jan, + year = {1996}, + pages = {97--110}, + file = {Huber and Kim - 1996 - Weighted-ensemble Brownian dynamics simulations fo.pdf:/Users/grs53/Zotero/storage/Y5N2TNVG/Huber and Kim - 1996 - Weighted-ensemble Brownian dynamics simulations fo.pdf:application/pdf} +} + + +@misc{webber_splitting_2020, + title = {A splitting method to reduce {MCMC} variance}, + url = {http://arxiv.org/abs/2011.13899}, + doi = {10.48550/arXiv.2011.13899}, + abstract = {We explore whether splitting and killing methods can improve the accuracy of Markov chain Monte Carlo (MCMC) estimates of rare event probabilities, and we make three contributions. First, we prove that "weighted ensemble" is the only splitting and killing method that provides asymptotically consistent estimates when combined with MCMC. Second, we prove a lower bound on the asymptotic variance of weighted ensemble's estimates. Third, we give a constructive proof and numerical examples to show that weighted ensemble can approach this optimal variance bound, in many cases reducing the variance of MCMC estimates by multiple orders of magnitude.}, + urldate = {2022-10-14}, + publisher = {arXiv}, + author = {Webber, Robert J. and Aristoff, David and Simpson, Gideon}, + month = dec, + year = {2020}, + note = {arXiv:2011.13899 [cs, math]}, + keywords = {Mathematics - Numerical Analysis, 65C05, 65C40, 82C80}, + annote = {Comment: 30 pages, 9 figures}, + file = {arXiv Fulltext PDF:/Users/grs53/Zotero/storage/2NESNYHJ/Webber et al. - 2020 - A splitting method to reduce MCMC variance.pdf:application/pdf;arXiv.org Snapshot:/Users/grs53/Zotero/storage/V3H5RH4S/2011.html:text/html} +} + + +@inproceedings{douc_comparison_2005, + address = {Zagreb, Croatia}, + title = {Comparison of resampling schemes for particle filtering}, + isbn = {978-953-184-089-7}, + url = {http://ieeexplore.ieee.org/document/1521264/}, + doi = {10.1109/ISPA.2005.195385}, + abstract = {This contribution is devoted to the comparison of various resampling approaches that have been proposed in the literature on particle filtering. It is first shown using simple arguments that the so-called residual and stratified methods do yield an improvement over the basic multinomial resampling approach. A simple counter-example showing that this property does not hold true for systematic resampling is given. Finally, some results on the large-sample behavior of the simple bootstrap filter algorithm are given. In particular, a central limit theorem is established for the case where resampling is performed using the residual approach.}, + language = {en}, + urldate = {2024-03-10}, + booktitle = {{ISPA} 2005. {Proceedings} of the 4th {International} {Symposium} on {Image} and {Signal} {Processing} and {Analysis}, 2005.}, + publisher = {IEEE}, + author = {Douc, R. and Cappe, O. and Moulines, E.}, + year = {2005}, + note = {ISSN: 1845-5921}, + pages = {64--69}, + file = {Douc and Cappe - 2005 - Comparison of resampling schemes for particle filt.pdf:/Users/grs53/Zotero/storage/B99QI239/Douc and Cappe - 2005 - Comparison of resampling schemes for particle filt.pdf:application/pdf} +} diff --git a/docs/src/refs1.md b/docs/src/refs1.md new file mode 100644 index 0000000..a1bad1b --- /dev/null +++ b/docs/src/refs1.md @@ -0,0 +1,4 @@ +# References +```@bibliography +* +``` \ No newline at end of file diff --git a/docs/src/selection/resampling1.md b/docs/src/selection/resampling1.md index 1dd5600..92da65b 100644 --- a/docs/src/selection/resampling1.md +++ b/docs/src/selection/resampling1.md @@ -3,7 +3,7 @@ As it is neccessary to perform resampling, both for determining how many offspring each bin should have, and, having determined that, resampling the particles within each bin, we have provided several choices here. These -methods, and their properties, can be found in Douc et al. (2005). The provided +methods, and their properties, can be found in [douc_comparison_2005](@cite). The provided `selection!` functions default to using [`WeightedEnsemble.systematic`](@ref) across bins and [`WeightedEnsemble.multinomial`](@ref) within bins.