{"id":17287619,"url":"https://github.com/dnlbauer/wham","last_synced_at":"2025-07-05T00:38:00.637Z","repository":{"id":50599306,"uuid":"151449425","full_name":"dnlbauer/WHAM","owner":"dnlbauer","description":"An efficient, multithreaded weighted histogram analysis (WHAM) implementation for the post-processing of umbrella MD simulations.","archived":false,"fork":false,"pushed_at":"2024-04-01T02:11:25.000Z","size":113601,"stargazers_count":27,"open_issues_count":4,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-10T11:54:45.030Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnlbauer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-10-03T17:05:01.000Z","updated_at":"2024-11-23T11:12:42.000Z","dependencies_parsed_at":"2023-12-13T19:23:33.220Z","dependency_job_id":null,"html_url":"https://github.com/dnlbauer/WHAM","commit_stats":{"total_commits":167,"total_committers":7,"mean_commits":"23.857142857142858","dds":"0.23353293413173648","last_synced_commit":"545c0ecbd339ef081c1b18feeaea10ea10a89219"},"previous_names":["danijoo/wham"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnlbauer%2FWHAM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnlbauer%2FWHAM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnlbauer%2FWHAM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnlbauer%2FWHAM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnlbauer","download_url":"https://codeload.github.com/dnlbauer/WHAM/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248870103,"owners_count":21174983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-15T10:03:50.733Z","updated_at":"2025-04-14T11:25:01.353Z","avatar_url":"https://github.com/dnlbauer.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.com/danijoo/WHAM.svg?branch=master)](https://travis-ci.com/danijoo/WHAM) [![crates.io](https://img.shields.io/badge/crates.io-orange.svg?longCache=true)](https://www.crates.io/crates/wham) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1488597.svg)](https://doi.org/10.5281/zenodo.1488597)\n\n\n\nWeighted Histogram Analysis Method (WHAM)\n===\nThis is an fast implementation of the weighted histogram analysis method\nwritten in Rust. It allows the calculation of multidimensional free energy profiles\nfrom umbrella sampling simulations. For more details on the method, I suggest *Roux, B.\n(1995). The calculation of the potential of mean force using computer simulations, CPC, 91(1), 275-282.*\n\nFeatures\n---\n- Fast, especially for small systems\n- Multithreaded (automatically runs on all available cores) \n- Multidimensional (any number of collective variables are possible)\n- Autocorrelation to remove correlated samples\n- Error analysis via bootstrapping\n- Unit tested\n\nInstallation\n---\nInstallation from source via cargo:\n```bash\n# cargo installation\ncurl -sSf https://static.rust-lang.org/rustup.sh | sh\n\ncargo install wham\n```\n\nUsage\n---\nwham has a convenient command line interface. You can see all options with\n```wham -h```:\n\n```\nwham 1.1.0\nD. Bauer \u003cbauer@cbs.tu-darmstadt.de\u003e\nwham is a fast implementation of the weighted histogram analysis method (WHAM) written in Rust. It currently supports\npotential of mean force (PMF) calculations in multiple dimensions at constant temperature.\n\nMetadata file format:\n    /path/to/timeseries_file1  x_1  x_2  x_N  fc_1  fc_2  fc_N\n    /path/to/timeseries_file2  x_1  x_2  x_N  fc_1  fc_2  fc_N\n    /path/to/timeseries_file3  x_1  x_2  x_N  fc_1  fc_2  fc_N\nThe first column is a path to a timeseries file _relative_ to the metadata file (see below). This is followed by the\nposition of the umbrella potential x in N dimensions and the force constant fc in each dimension. Lines starting with a\n# are treated as comments and will not be parsed.\n\nTimeseries file format:\n    time  x_1  x_2  x_N\n    time  x_1  x_2  x_N\n    time  x_1  x_2  x_N\nThe first column will be ignored and is followed by N reaction coordinates x.\n\nShipped under the GPLv3 license.\n\nUSAGE:\n    wham [FLAGS] [OPTIONS] --bins \u003cBINS\u003e --max \u003cHIST_MAX\u003e --file \u003cMETADATA\u003e --min \u003cHIST_MIN\u003e --temperature \u003ctemperature\u003e\n\nFLAGS:\n    -c, --cyclic     For periodic reaction coordinates. If this is set, the first and last coordinate bin in each\n                     dimension are treated as neighbors for the bias calculation.\n    -h, --help       Prints help information\n    -g, --uncorr     Estimates statistical inefficiency of each timeseries via autocorrelation and removes correlated\n                     samples (default is off).\n    -V, --version    Prints version information\n    -v, --verbose    Enables verbose output.\n\nOPTIONS:\n    -b, --bins \u003cBINS\u003e                  Number of histogram bins (comma separated).\n        --bt \u003cbootstrap\u003e               Number of bayesian bootstrapping runs for error analysis by assigning random\n                                       weights (defaults to 0).\n        --seed \u003cbootstrap_seed\u003e        Random seed for bootstrapping runs.\n        --convdt \u003cconvdt\u003e              Performs WHAM for slices with the given delta in time and returns an output file\n                                       for each slice. THis is useful to check the result for convergence. Example: with\n                                       --convdt 100 and a timeseries ranging from 0-300, free energy surfaces for slices\n                                       0-100, 0-200 and 0-300 will be given returned.\n        --end \u003cend\u003e                    Skip rows in timeseries with an index larger than this value (defaults to 1e+20)\n    -i, --iterations \u003cITERATIONS\u003e      Stop WHAM after this many iterations without convergence (defaults to 100,000).\n        --max \u003cHIST_MAX\u003e               Histogram maxima (comma separated). Also accepts \"pi\".\n    -f, --file \u003cMETADATA\u003e              Path to the metadata file.\n        --min \u003cHIST_MIN\u003e               Histogram minima (comma separated for multiple dimensions). Also accepts \"pi\".\n    -o, --output \u003coutput\u003e              Free energy output file (defaults to wham.out).\n        --start \u003cstart\u003e                Skip rows in timeseries with an index smaller than this value (defaults to 0)\n    -T, --temperature \u003ctemperature\u003e    WHAM temperature in Kelvin.\n    -t, --tolerance \u003cTOLERANCE\u003e        Abortion criteria for WHAM calculation. WHAM stops if abs(F_new - F_old) \u003c\n                                       tolerance (defaults to 0.000001).\n```\n\nExamples\n---\nThe example folder contains input and output files for two simple test systems:\n\n- 1d_cyclic: Phi torsion angle of dialanine in vaccum\n- 2d_cyclic: Phi and psi torsion angles of the same system\n\nThe command below will run the two dimensional example (simulation of dialanine phi and psi angle) and calculate the free energy based on the two collective variables\nin the range of -3.14 to 3.14, with 100 bins in each dimension and periodic collective variables:\n \n```bash\nwham --max 3.14,3.14 --min -3.14,-3.14 -T 300 --bins 100,100 --cyclic -f example/2d/metadata.dat       \n\u003e Supplied WHAM options: Metadata=example/2d/metadata.dat, hist_min=[-3.14, -3.14], hist_max=[3.14, 3.14], bins=[100, 100] verbose=false, tolerance=0.000001, iterations=100000, temperature=300, cyclic=true\n\u003e Reading input files.\n\u003e 625 windows, 624262 datapoints\n\u003e Iteration 10: dF=0.389367172324539\n\u003e Iteration 20: dF=0.21450559607810152\n(...)\n\u003e Iteration 620: dF=0.0000005800554892309461\n\u003e Iteration 630: dF=0.00000047424278621817084\n\u003e Finished. Dumping final PMF\n(... pmf dump ...)\n\n```\nAfter convergence, final bias offsets (F) and the free energy will be dumped to stdout and the output file is written.\n\nThe output file contains the free energy and probability for each bin. Probabilities are normalized to sum to P=1.0 and\nthe smallest free energy is set to 0 (with other free energies based on that).\n```\n#coord1    coord2    Free Energy    +/-    Probability    +/-\n-3.108600    \t-3.108600    10.331716    0.000000    0.000095    0.000000\n-3.045800    \t-3.108600    8.893231    0.000000    0.000170    0.000000\n-2.983000    \t-3.108600    7.372765    0.000000    0.000312    0.000000\n-2.920200    \t-3.108600    6.207354    0.000000    0.000498    0.000000\n-2.857400    \t-3.108600    4.915298    0.000000    0.000836    0.000000\n-2.794600    \t-3.108600    3.644738    0.000000    0.001392    0.000000\n-2.731800    \t-3.108600    3.021743    0.000000    0.001787    0.000000\n-2.669000    \t-3.108600    2.827463    0.000000    0.001932    0.000000\n-2.606200    \t-3.108600    2.647531    0.000000    0.002076    0.000000\n(...)\n```\n\nError analysis\n---\nWHAM can perform error analysis using the bayesian bootstrapping method. Every simulation window is assumed to be an\nindividual set of data points. By calculating probabilities N times with randomly assigned weights for each window,\none can estimate the error as standard deviation between the N bootstrapping runs. For more details see\n*Van der Spoel, D. et al. (2010). g_wham—A Free Weighted Histogram Analysis Implementation Including Robust Error and\nAutocorrelation Estimates, JCTC, 6(12), 3713-3720*.\n\nTo perform bayesian bootstrapping in WHAM, use the ```-bt \u003cRUNS\u003e``` flag to perform \u003cRUNS\u003e individual bootstrapping\nruns. The error estimates of bin probabilities and free energy will be given as standard error (SE) in a \nseparate column (+/-) in the output file. If no error analysis is performed, these columns are set to 0.0.\n\nAutocorrelation analysis\n---\nWith the ```--uncorr``` flag, WHAM calculates the autocorrelation time ```tau``` for all timeseries and all collective\nvariables. Timeseries are then filtered based on their highest autocorrelation time to remove correlated samples from\nthe dataset. This reduces the number of data points but can improve the accuracy of the result.\n\nFor filtering, the statistical inefficiency `g` is calculated: ```g = 1 + 2*tau```, and only every `g`th element of the\ntimeseries is used for unbiasing. A more detailed description of the method can be found in\n*Chodera, J.D. et al. (2007). Use of the weighted histogram analysis method for the analysis of simulated and parallel\ntempering simulations, JCTC 3(1):26-41*\n\nLicense \u0026 Citing\n---\nWHAM is licensed under the GPL-3.0 license. Please read the LICENSE file in this\nrepository for more information.\n\nThere's no publication for this WHAM implementation. However, there is a citeabe DOI. If you use this software for your work, please consider citing it: *Bauer, D., WHAM - An efficient weighted histogram analysis implementation written in Rust, Zenodo. https://doi.org/10.5281/zenodo.1488597*\n\nParts of this work, especially some perfomance optimizations and the I/O format, are inspired by the\nimplementation of A. Grossfield (*Grossfield, A, WHAM: the weighted histogram analysis method, http://membrane.urmc.rochester.edu/content/wham*).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnlbauer%2Fwham","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnlbauer%2Fwham","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnlbauer%2Fwham/lists"}