Struct net_ensembles::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 + Sync + Send + Clone,
    Ensemble: MarkovChain<S, Res> + 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, Global>,
    hists: Vec<Hist, Global>,
    step_size: usize,
    sweep_size: NonZeroUsize,
    walker_per_interval: NonZeroUsize,
    log_f_threshold: f64
) -> Result<ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>, 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, Global>,
    step_size: usize,
    sweep_size: NonZeroUsize,
    walker_per_interval: NonZeroUsize,
    log_f_threshold: f64
) -> Result<ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>, 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, Global>,
    step_size: usize,
    sweep_size: NonZeroUsize,
    walker_per_interval: NonZeroUsize,
    log_f_threshold: f64
) -> Result<ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>, 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
) -> ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>where
    Hist: HistogramVal<Energy>,
    Ensemble: HasRng<R>,
    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<ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>, ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>>where
    Hist: HistogramVal<Energy>,
    Ensemble: HasRng<R>,
    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
) -> ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>where
    Hist: HistogramVal<Energy>,
    R: Rng + SeedableRng + Send + Sync,
    Ensemble: HasRng<R2>,
    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<ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>, ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>>where
    Hist: HistogramVal<Energy>,
    R: Rng + SeedableRng + Send + Sync,
    Ensemble: HasRng<R2>,
    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
) -> ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>where
    Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>,
    R: Rng + SeedableRng + Send + Sync,
    Ensemble: HasRng<R>,
    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<ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>, ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>>where
    Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>,
    R: Rng + SeedableRng + Send + Sync,
    Ensemble: HasRng<R>,
    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
) -> ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>where
    Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>,
    R: Rng + SeedableRng + Send + Sync,
    Ensemble: HasRng<R2>,
    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<ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>, ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>>where
    Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>,
    R: Rng + SeedableRng + Send + Sync,
    Ensemble: HasRng<R2>,
    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
) -> ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>where
    Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>,
    R: Rng + SeedableRng + Send + Sync,
    Ensemble: HasRng<R>,
    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<ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>, ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>>where
    Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>,
    R: Rng + SeedableRng + Send + Sync,
    Ensemble: HasRng<R>,
    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<ReplicaExchangeWangLandau<Ensemble, R, Hist, Energy, S, Res>, ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>>where
    Hist: HistogramVal<Energy> + HistogramIntervalDistance<Energy>,
    R: Rng + SeedableRng + Send + Sync,
    Ensemble: HasRng<R2>,
    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, Hist, S, Res> Clone for ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>where
    Ensemble: Clone,
    Hist: Clone,
    S: Clone,
    Res: Clone,

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, Hist, S, Res> Debug for ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>where
    Ensemble: Debug,
    Hist: Debug,
    S: Debug,
    Res: Debug,

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

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<ReplicaExchangeWangLandauBuilder<Ensemble, Hist, S, Res>, <__D as Deserializer<'de>>::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 as Serializer>::Ok, <__S as Serializer>::Error>where
    __S: Serializer,

Serialize this value into the given Serde serializer.