Struct net_ensembles::sampling::ReplicaExchangeWangLandau
source · [−]pub struct ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res> { /* private fields */ }
Expand description
Efficient replica exchange Wang landau
- use this to quickly build your own parallel replica exchange wang landau simulation
Tipp
Use the short hand Rewl
Citations
- the following paper were used to progamm this - you should cite them, if you use this library for a publication!
Y. W. Li, T. Vogel, T. Wüst and D. P. Landau, “A new paradigm for petascale Monte Carlo simulation: Replica exchange Wang-Landau sampling,” J. Phys.: Conf. Ser. 510 012012 (2014), DOI 10.1088/1742-6596/510/1/012012
T. Vogel, Y. W. Li, T. Wüst and D. P. Landau, “Exploring new frontiers in statistical physics with a new, parallel Wang-Landau framework,” J. Phys.: Conf. Ser. 487 012001 (2014), DOI 10.1088/1742-6596/487/1/012001
T. Vogel, Y. W. Li, T. Wüst and D. P. Landau, “Scalable replica-exchange framework for Wang-Landau sampling,” Phys. Rev. E 90: 023302 (2014), DOI 10.1103/PhysRevE.90.023302
R. E. Belardinelli and V. D. Pereyra, “Fast algorithm to calculate density of states,” Phys. Rev. E 75: 046701 (2007), DOI 10.1103/PhysRevE.75.046701
F. Wang and D. P. Landau, “Efficient, multiple-range random walk algorithm to calculate the density of states,” Phys. Rev. Lett. 86, 2050–2053 (2001), DOI 10.1103/PhysRevLett.86.2050
Implementations
sourceimpl<Ensemble, R, Hist, Energy, S, Res> ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>
impl<Ensemble, R, Hist, Energy, S, Res> ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>
sourcepub fn walkers(&self) -> &Vec<RewlWalker<R, Hist, Energy, S, Res>, Global>
pub fn walkers(&self) -> &Vec<RewlWalker<R, Hist, Energy, S, Res>, Global>
Read access to internal rewl walkers
- each of these walkers independently samples an interval.
- see paper for more infos
sourcepub fn ensemble_iter(
&self
) -> impl Iterator<Item = RwLockReadGuard<'_, Ensemble>>
pub fn ensemble_iter(
&self
) -> impl Iterator<Item = RwLockReadGuard<'_, Ensemble>>
Iterator over ensembles
If you do not know what RwLockReadGuard<'a, Ensemble>
is - do not worry.
you can just pretend it is &Ensemble
and everything should work out fine,
since it implements Deref
.
Of cause, you can also take a look at RwLockReadGuard
sourcepub fn get_ensemble(&self, index: usize) -> Option<RwLockReadGuard<'_, Ensemble>>
pub fn get_ensemble(&self, index: usize) -> Option<RwLockReadGuard<'_, Ensemble>>
read access to your ensembles
None
ifindex
out of range- If you do not know what
RwLockReadGuard<Ensemble>
is - do not worry. you can just pretend it is&Ensemble
and everything will work out fine, since it implementsDeref
. Of cause, you can also take a look atRwLockReadGuard
sourcepub unsafe fn ensemble_iter_mut(
&mut self
) -> impl Iterator<Item = &mut Ensemble>
pub unsafe fn ensemble_iter_mut(
&mut self
) -> impl Iterator<Item = &mut Ensemble>
Mutable iterator over ensembles
- if possible, prefer
ensemble_iter
Safety
- it is assumed, that whatever you change has no effect on the Markov Chain, the result of the energy function etc.
- might panic if a thread is poisened
sourcepub unsafe fn get_ensemble_mut(&mut self, index: usize) -> Option<&mut Ensemble>
pub unsafe fn get_ensemble_mut(&mut self, index: usize) -> Option<&mut Ensemble>
mut access to your ensembles
- if possible, prefer
get_ensemble
- None if
index
out of range
Safety
- it is assumed, that whatever you change has no effect on the Markov Chain, the result of the energy function etc.
- might panic if a thread is poisened
sourcepub fn num_intervals(&self) -> NonZeroUsize
pub fn num_intervals(&self) -> NonZeroUsize
sourcepub fn walkers_per_interval(&self) -> NonZeroUsize
pub fn walkers_per_interval(&self) -> NonZeroUsize
Returns number of walkers per interval
sourcepub fn change_step_size_of_interval(
&mut self,
n: usize,
step_size: usize
) -> Result<(), ()>
pub fn change_step_size_of_interval(
&mut self,
n: usize,
step_size: usize
) -> Result<(), ()>
Change step size for markov chain of walkers
- changes the step size used in the sweep
- changes step size of all walkers in the nth interval
- returns Err if index out of bounds, i.e., the requested interval does not exist
- interval counting starts at 0, i.e., n=0 is the first interval
sourcepub fn get_step_size_of_interval(&self, n: usize) -> Option<usize>
pub fn get_step_size_of_interval(&self, n: usize) -> Option<usize>
Get step size for markov chain of walkers
- returns
None
if index out of bounds, i.e., the requested interval does not exist - interval counting starts at 0, i.e., n=0 is the first interval
sourcepub fn change_sweep_size_of_interval(
&mut self,
n: usize,
sweep_size: NonZeroUsize
) -> Result<(), ()>
pub fn change_sweep_size_of_interval(
&mut self,
n: usize,
sweep_size: NonZeroUsize
) -> Result<(), ()>
Change sweep size for markov chain of walkers
- changes the sweep size used in the sweep
- changes sweep size of all walkers in the nth interval
- returns Err if index out of bounds, i.e., the requested interval does not exist
- interval counting starts at 0, i.e., n=0 is the first interval
sourcepub fn get_sweep_size_of_interval(&self, n: usize) -> Option<NonZeroUsize>
pub fn get_sweep_size_of_interval(&self, n: usize) -> Option<NonZeroUsize>
Get sweep size for markov chain of walkers
- returns
None
if index out of bounds, i.e., the requested interval does not exist - interval counting starts at 0, i.e., n=0 is the first interval
sourcepub fn min_roundtrips(&self) -> usize
pub fn min_roundtrips(&self) -> usize
Minimum of roundtrips
Definition of roundtrip: If a walker is in the leftest interval, then in the rightest and then in the leftest again (or the other way around) then this is counted as one roundtrip.
This will return the minimum of roundtrips
sourcepub fn max_roundtrips(&self) -> usize
pub fn max_roundtrips(&self) -> usize
Maximum of roundtrips
Definition of roundtrip: If a walker is in the leftest interval, then in the rightest and then in the leftest again (or the other way around) then this is counted as one roundtrip.
This will return the maximum of roundtrips
sourcepub fn roundtrip_iter(&self) -> impl Iterator<Item = usize>
pub fn roundtrip_iter(&self) -> impl Iterator<Item = usize>
Roundtrips
Definition of roundtrip: If a walker is in the leftest interval, then in the rightest and then in the leftest again (or the other way around) then this is counted as one roundtrip.
This will return an iterator over the roundtrips
sourcepub fn largest_log_f(&self) -> f64
pub fn largest_log_f(&self) -> f64
returns largest value of factor log_f present in the walkers
sourcepub fn log_f_vec(&self) -> Vec<f64, Global>
pub fn log_f_vec(&self) -> Vec<f64, Global>
Log_f factors of the walkers
- the log_f’s will be reduced towards 0 during the simulation
sourcepub fn set_log_f_threshold(
&mut self,
new_threshold: f64
) -> Result<f64, ThresholdErrors>
pub fn set_log_f_threshold(
&mut self,
new_threshold: f64
) -> Result<f64, ThresholdErrors>
change the threshold of log_f
- it has to be a positive, normal number
sourcepub fn is_finished(&self) -> bool
pub fn is_finished(&self) -> bool
Is the simulation finished?
checks if all walkers have factors log_f
that are below the threshold you chose
sourcepub fn derivative_merged_log_prob_and_aligned(
&self
) -> Result<ReplicaGlued<Hist>, HistErrors>where
Hist: HistogramCombine + Histogram,
pub fn derivative_merged_log_prob_and_aligned(
&self
) -> Result<ReplicaGlued<Hist>, HistErrors>where
Hist: HistogramCombine + Histogram,
Results of the simulation
This is what we do the simulation for!
It uses derivative merging to give you a ReplicaGlued
which you can use to write
the data into a file.
The derivative merged is explained in derivative_merged_log_prob_and_aligned
Notes
Fails if the internal histograms (intervals) do not align. Might fail if there is no overlap between neighboring intervals
sourcepub fn average_merged_log_probability_and_align(
&self
) -> Result<ReplicaGlued<Hist>, HistErrors>where
Hist: HistogramCombine + Histogram,
pub fn average_merged_log_probability_and_align(
&self
) -> Result<ReplicaGlued<Hist>, HistErrors>where
Hist: HistogramCombine + Histogram,
Results of the simulation
This is what we do the simulation for!
It uses average merging to give you a ReplicaGlued
which you can use to write
the data into a file.
The average merged is explained in average_merged_and_aligned
Notes
Fails if the internal histograms (intervals) do not align. Might fail if there is no overlap between neighboring intervals
sourcepub fn get_id_vec(&self) -> Vec<usize, Global>
pub fn get_id_vec(&self) -> Vec<usize, Global>
Get Ids
This is an indicator that the replica exchange works. In the beginning, this will be a sorted vector, e.g. [0,1,2,3,4]. Then it will show, where the ensemble, which the corresponding walkers currently work with, originated from. E.g. If the vector is [3,1,0,2,4], Then walker 0 has a ensemble originating from walker 3, the walker 1 is back to its original ensemble, walker 2 has an ensemble originating form walker 0 and so on.
sourcepub fn get_hist(&self, index: usize) -> Option<&Hist>
pub fn get_hist(&self, index: usize) -> Option<&Hist>
read access to internal histogram
- None if index out of range
sourcepub fn into_rees(
self
) -> ReplicaExchangeEntropicSampling<(), Ensemble, R, Hist, Energy, S, Res>where
Hist: Histogram,
pub fn into_rees(
self
) -> ReplicaExchangeEntropicSampling<(), Ensemble, R, Hist, Energy, S, Res>where
Hist: Histogram,
Convert into Rees
This creates a Replica exchange entropic sampling simulation from this Replica exchange wang landau simulation
sourcepub fn into_rees_with_extra<Extra>(
self,
extra: Vec<Extra, Global>
) -> Result<ReplicaExchangeEntropicSampling<Extra, Ensemble, R, Hist, Energy, S, Res>, (ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>, Vec<Extra, Global>)>where
Hist: Histogram,
pub fn into_rees_with_extra<Extra>(
self,
extra: Vec<Extra, Global>
) -> Result<ReplicaExchangeEntropicSampling<Extra, Ensemble, R, Hist, Energy, S, Res>, (ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>, Vec<Extra, Global>)>where
Hist: Histogram,
Convert into Rees
- similar to into_rees, though now we can store extra information. The extra information can be anything, e.g., files in which each walker should later write information every nth step or something else entirely.
important
- The vector
extra
must be exactly as long as the walker slice and each walker is assigned the corresponding entry from the vectorextra
- You can look at the walker slice with the walkers method
sourceimpl<Ensemble, R, Hist, Energy, S, Res> ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>where
R: Send + Sync + Rng + SeedableRng,
Hist: Send + Sync + Histogram + HistogramVal<Energy>,
Energy: Send + Sync + Clone,
Ensemble: MarkovChain<S, Res>,
Res: Send + Sync,
S: Send + Sync,
impl<Ensemble, R, Hist, Energy, S, Res> ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>where
R: Send + Sync + Rng + SeedableRng,
Hist: Send + Sync + Histogram + HistogramVal<Energy>,
Energy: Send + Sync + Clone,
Ensemble: MarkovChain<S, Res>,
Res: Send + Sync,
S: Send + Sync,
sourcepub fn simulate_until_convergence<F>(&mut self, energy_fn: F)where
Ensemble: Send + Sync,
R: Send + Sync,
F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync,
pub fn simulate_until_convergence<F>(&mut self, energy_fn: F)where
Ensemble: Send + Sync,
R: Send + Sync,
F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync,
Perform the Replica exchange wang landau simulation
- will simulate until all walkers have factors
log_f
that are below the threshold you chose
sourcepub fn simulate_while<F, C>(&mut self, energy_fn: F, condition: C)where
Ensemble: Send + Sync,
R: Send + Sync,
F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync,
C: FnMut(&ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>) -> bool,
pub fn simulate_while<F, C>(&mut self, energy_fn: F, condition: C)where
Ensemble: Send + Sync,
R: Send + Sync,
F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync,
C: FnMut(&ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>) -> bool,
Perform the Replica exchange wang landau simulation
- will simulate until all walkers have factors
log_f
that are below the threshold you chose or - until condition returns false
sourcepub fn check_energy_fn<F>(&mut self, energy_fn: F) -> boolwhere
Energy: PartialEq<Energy>,
F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync,
Ensemble: Sync + Send,
pub fn check_energy_fn<F>(&mut self, energy_fn: F) -> boolwhere
Energy: PartialEq<Energy>,
F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync,
Ensemble: Sync + Send,
Sanity check
- checks if the stored (i.e., last) energy(s) of the system match with the result of energy_fn
sourcepub fn sweep<F>(&mut self, energy_fn: F)where
Ensemble: Send + Sync,
R: Send + Sync,
F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync,
pub fn sweep<F>(&mut self, energy_fn: F)where
Ensemble: Send + Sync,
R: Send + Sync,
F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync,
Sweep
- Performs one sweep of the Replica exchange wang landau simulation
- You can make a complete simulation, by repeatatly calling this method
until
self.is_finished()
returns true