Struct sampling::rewl::ReplicaExchangeWangLandauBuilder

pub struct ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res> { /* private fields */ }

Use this to create a replica exchange wang landau simulation

• Tipp: Use shorthand RewlBuilder

Notes

• Don’t be intimidated by the number of trait bounds an generic parameters. You should very rarely have to explicitly write the types, as Rust will infer them for you.

Implementations

impl<Ensemble, Hist, S, Res> ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>

where Hist: Histogram + Sized + Sync + Send + Clone, Ensemble: MarkovChain<S, Res> + Sized + Sync + Send + Clone, S: Send + Sync, Res: Sync + Send,

pub fn finished_fraction(&self) -> f64

Fraction of finished intervals

• which fraction of the intervals has found valid starting configurations?

Note

• even if every interval has a valid configuration directly after using one of the from_… methods, it fill show a fraction of 0.0 - the fraction will only be correct after calling one of the …build methods (on the Error of the result)

pub fn finished_slice(&self) -> &[bool]

Is the interval in a valid starting configuration?

Check which intervals have valid starting points

Note

• in the beginning the RewlBuilder has no way of knowing, if the intervals have valid starting configuration - as it does not know the energy function yet. Therefore this will only be correct after calling one of the …build methods (on the Error of the result)

pub fn hists(&self) -> &[Hist]

Read access to histograms

pub fn ensembles(&self) -> &[Ensemble]

Read access to the ensembles

pub fn step_sizes(&self) -> &[usize]

Access step sizes of individual intervals

pub fn step_sizes_mut(&mut self) -> &mut [usize]

Change step size of individual intervals

• change step size of intervals

pub fn sweep_sizes(&self) -> &[NonZeroUsize]

Accesss sweep size of individual intervals

pub fn sweep_sizes_mut(&mut self) -> &mut [NonZeroUsize]

Change sweep size of individual intervals

• change sweep size of intervals

pub fn from_ensemble_vec( ensembles: Vec<Ensemble>, hists: Vec<Hist>, step_size: usize, sweep_size: NonZeroUsize, walker_per_interval: NonZeroUsize, log_f_threshold: f64 ) -> Result<Self, RewlBuilderErr>

new rewl builder

• used to create a Replica exchange wang landau simulation.
• use this method, if you want to have fine control over each walker, i.e., if you can provide ensembles, who’s energy is already inside the corresponding intervals hists
• you might want to use from_ensemble or from_ensemble_tuple instead

Parameter	meaning
ensembles	a vector of ensembles, one for each interval. Corresponds to the hists entries.
hists	Overlapping intervals for the wang landau walkers. Should be sorted according to their respective left bins.
step_size	step_size for the markov steps, which will be performed
sweep_size	How many steps will be performed until the replica exchanges are proposed
walker_per_interval	How many walkers should be used for each interval (entry of hists)
log_f_threshold	Threshold for the logarithm of the factor f (see paper). Rewl Simulation is finished, when all(!) walkers have a factor log_f smaller than this threshold

Notes

• for proper statistics, you should seed the random number generators (used for the markov chain) of all ensembles differently!
• log_f_threshold has to be a normal and non negative number
• each entry of ensembles will be cloned walker_per_interval - 1 times and their respective rngs will be seeded via the HasRng trait

pub fn from_ensemble<R>( ensemble: Ensemble, hists: Vec<Hist>, step_size: usize, sweep_size: NonZeroUsize, walker_per_interval: NonZeroUsize, log_f_threshold: f64 ) -> Result<Self, RewlBuilderErr>

where Ensemble: HasRng<R> + Clone, R: Rng + SeedableRng,

Create a builder to create a replica exchange wang landau (Rewl) simulation

• creates vector of ensembles and (re)seeds their respective rngs (by using the HasRng trait)
• calls Self::from_ensemble_vec(…) afterwards, look there for more information about the parameter

pub fn from_ensemble_tuple<R>( ensemble_tuple: (Ensemble, Ensemble), hists: Vec<Hist>, step_size: usize, sweep_size: NonZeroUsize, walker_per_interval: NonZeroUsize, log_f_threshold: f64 ) -> Result<Self, RewlBuilderErr>

where Ensemble: HasRng<R> + Clone, R: Rng + SeedableRng,

Create a builder to create a replica exchange wang landau (Rewl) simulation

• creates vector of ensembles and (re)seeds their respective rngs (by using the HasRng trait). The vector is created by cloning ensemble_tuple.0 for everything up to the middle of the vector and ensemble_tuple.1 for the rest. The length of the vector will be the same as hists.len(). If It is an uneven number, the middle element will be a clone of ensemble_tuple.1
• calls Self::from_ensemble_vec(…) afterwards, look there for more information about the parameter
• use this, if you know configurations, that would be good starting points for finding configurations at either end of the intervals.

pub fn greedy_build<R, F, Energy>( self, energy_fn: F ) -> Rewl<Ensemble, R, Hist, Energy, S, Res>

where Hist: HistogramVal<Energy>, Ensemble: HasRng<R> + Sized, R: Rng + SeedableRng + Send + Sync, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• uses a greedy heuristic to find valid configurations, meaning configurations that are within the required intervals, i.e., histograms

Note

• Depending on how complex your energy landscape is, this can take a very long time, maybe not even terminating at all.
• You can use self.try_greedy_choose_rng_build to limit the time of the search

pub fn try_greedy_build<R, F, C, Energy>( self, energy_fn: F, condition: C ) -> Result<Rewl<Ensemble, R, Hist, Energy, S, Res>, Self>

where Hist: HistogramVal<Energy>, Ensemble: HasRng<R> + Sized, R: Rng + SeedableRng + Send + Sync, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, C: Fn() -> bool + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• similar to greedy_build
• condition can be used to limit the time of the search - it will end when condition returns false. ##Note
• condition will only be checked once every sweep, i.e., every sweep_size markov steps

pub fn greedy_choose_rng_build<R, R2, F, Energy>( self, energy_fn: F ) -> Rewl<Ensemble, R, Hist, Energy, S, Res>

where Hist: HistogramVal<Energy>, R: Rng + SeedableRng + Send + Sync, Ensemble: HasRng<R2> + Sized, R2: Rng + SeedableRng, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• similar to greedy_build
• Difference: You can choose a different Rng for the Wang Landau walkers (i.e., the acceptance of the replica exchange moves etc.)
• usage: self.greedy_choose_rng_build::<RNG,_,_,_>(energy_fn)

pub fn try_greedy_choose_rng_build<R, R2, F, C, Energy>( self, energy_fn: F, condition: C ) -> Result<Rewl<Ensemble, R, Hist, Energy, S, Res>, Self>

where Hist: HistogramVal<Energy>, R: Rng + SeedableRng + Send + Sync, Ensemble: HasRng<R2> + Sized, R2: Rng + SeedableRng, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, C: Fn() -> bool + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• similar to try_greedy_build
• Difference: You can choose a different Rng for the Wang Landau walkers (i.e., the acceptance of the replica exchange moves etc.)
• usage: self.try_greedy_choose_rng_build::<RNG,_,_,_,_>(energy_fn, condition)

pub fn interval_heuristik_build<R, R2, F, Energy>( self, energy_fn: F, overlap: NonZeroUsize ) -> Rewl<Ensemble, R, Hist, Energy, S, Res>

where Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>, R: Rng + SeedableRng + Send + Sync, Ensemble: HasRng<R> + Sized, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• uses an interval heuristic to find valid configurations, meaning configurations that are within the required intervals, i.e., histograms
• Uses overlapping intervals. Accepts a step, if the resulting ensemble is in the same interval as before, or it is in an interval closer to the target interval. Take a look at the HistogramIntervalDistance trait
• overlap should smaller than the number of bins in your histogram. E.g. overlap = 3 if you have 200 bins

Note

• Depending on how complex your energy landscape is, this can take a very long time, maybe not even terminating at all.
• You can use try_interval_heuristik_build to limit the time of the search

pub fn try_interval_heuristik_build<R, F, C, Energy>( self, energy_fn: F, condition: C, overlap: NonZeroUsize ) -> Result<Rewl<Ensemble, R, Hist, Energy, S, Res>, Self>

where Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>, R: Rng + SeedableRng + Send + Sync, Ensemble: HasRng<R> + Sized, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, C: Fn() -> bool + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• similar to interval_heuristik_build
• condition can be used to limit the time of the search - it will end when condition returns false. ##Note
• condition will only be checked once every sweep, i.e., every sweep_size markov steps

pub fn interval_heuristik_choose_rng_build<R, R2, F, Energy>( self, energy_fn: F, overlap: NonZeroUsize ) -> Rewl<Ensemble, R, Hist, Energy, S, Res>

where Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>, R: Rng + SeedableRng + Send + Sync, Ensemble: HasRng<R2> + Sized, R2: Rng + SeedableRng, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• similar to try_interval_heuristik_build
• Difference: You can choose a different Rng for the Wang Landau walkers (i.e., the acceptance of the replica exchange moves etc.)
• usage: self.try_interval_heuristik_build::<RNG,_,_,_,_>(energy_fn, overlap)

pub fn try_interval_heuristik_choose_rng_build<R, R2, F, C, Energy>( self, energy_fn: F, condition: C, overlap: NonZeroUsize ) -> Result<Rewl<Ensemble, R, Hist, Energy, S, Res>, Self>

where Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>, R: Rng + SeedableRng + Send + Sync, Ensemble: HasRng<R2> + Sized, R2: Rng + SeedableRng, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, C: Fn() -> bool + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• similar to interval_heuristik_choose_rng_build
• Difference: You can choose the Random number generator used for the Rewl Walkers, i.e., for accepting or rejecting the markov steps and replica exchanges.
• usage: `self.try_interval_heuristik_choose_rng_build<RNG, ,,,>(energy_fn, condition, overlap)]

pub fn mixed_heuristik_build<R, F, Energy>( self, energy_fn: F, overlap: NonZeroUsize, greedy_steps: NonZeroUsize, interval_steps: NonZeroUsize ) -> Rewl<Ensemble, R, Hist, Energy, S, Res>

where Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>, R: Rng + SeedableRng + Send + Sync, Ensemble: HasRng<R> + Sized, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• alternates between interval-heuristik and greedy-heuristik

• The interval heuristik uses overlapping intervals. Accepts a step, if the resulting ensemble is in the same interval as before, or it is in an interval closer to the target interval. Take a look at the HistogramIntervalDistance trait

• overlap should smaller than the number of bins in your histogram. E.g. overlap = 3 if you have 200 bins

• greedy_steps: How many steps to perform with greedy heuristik before switching to interval heuristik?

• interval_steps: How many steps to perform with interval heuristik before switching back to greedy heuristik?

Note

• Depending on how complex your energy landscape is, this can take a very long time, maybe not even terminating at all.
• You can use try_mixed_heuristik_build to limit the time of the search

pub fn try_mixed_heuristik_build<R, F, C, Energy>( self, energy_fn: F, condition: C, overlap: NonZeroUsize, greedy_steps: NonZeroUsize, interval_steps: NonZeroUsize ) -> Result<Rewl<Ensemble, R, Hist, Energy, S, Res>, Self>

where Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>, R: Rng + SeedableRng + Send + Sync, Ensemble: HasRng<R> + Sized, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, C: Fn() -> bool + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• alternates between interval-heuristik and greedy-heuristik

• The interval heuristik uses overlapping intervals. Accepts a step, if the resulting ensemble is in the same interval as before, or it is in an interval closer to the target interval. Take a look at the HistogramIntervalDistance trait

• overlap should smaller than the number of bins in your histogram. E.g. overlap = 3 if you have 200 bins

• greedy_steps: How many steps to perform with greedy heuristik before switching to interval heuristik?

• interval_steps: How many steps to perform with interval heuristik before switching back to greedy heuristik?

Note

• condition can be used to limit the time of the search - it will end when condition returns false (or a valid solution is found)
• condition will be checked each time the heuristik switches between greedy and interval heuristik

pub fn try_mixed_heuristik_choose_rng_build<R, R2, F, C, Energy>( self, energy_fn: F, condition: C, overlap: NonZeroUsize, greedy_steps: NonZeroUsize, interval_steps: NonZeroUsize ) -> Result<Rewl<Ensemble, R, Hist, Energy, S, Res>, Self>

where Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>, R: Rng + SeedableRng + Send + Sync, Ensemble: HasRng<R2> + Sized, R2: Rng + SeedableRng, F: Fn(&mut Ensemble) -> Option<Energy> + Copy + Send + Sync, C: Fn() -> bool + Copy + Send + Sync, Energy: Sync + Send + Clone, RewlWalker<R, Hist, Energy, S, Res>: Send,

Create Rewl, i.e., Replica exchange wang landau simulation

• similar to try_mixed_heuristik_build

• difference: Lets you choose the rng type for the Rewl simulation, i.e., the rng used for accepting or rejecting markov steps and replica exchange moves

• usage: self.try_mixed_heuristik_choose_rng_build<RNG_TYPE, _, _, _, _>(energy_fn, condition, overlap, greedy_steps, interval_steps)

• greedy_steps: How many steps to perform with greedy heuristik before switching to interval heuristik?

• interval_steps: How many steps to perform with interval heuristik before switching back to greedy heuristik?

Note

• condition will be checked each time the heuristik switches between greedy and interval heuristik

Trait Implementations

impl<Ensemble: Clone, Hist: Clone, S: Clone, Res: Clone> Clone for ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>

fn clone(&self) -> ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Ensemble: Debug, Hist: Debug, S: Debug, Res: Debug> Debug for ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, Ensemble, Hist, S, Res> Deserialize<'de> for ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>

where Ensemble: Deserialize<'de>, Hist: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<Ensemble, Hist, S, Res> Serialize for ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>

where Ensemble: Serialize, Hist: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.