Struct net_ensembles::sampling::WangLandau1T

pub struct WangLandau1T<Hist, Rng, Ensemble, S, Res, Energy> { /* fields omitted */ }

The 1/t Wang Landau approach comes from this paper

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

• The original Wang Landau algorithim comes from this paper

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

impl<Hist, R, E, S, Res, Energy> WangLandau1T<Hist, R, E, S, Res, Energy> where
    Hist: Histogram + HistogramVal<Energy>, 

pub fn is_initialized(&self) -> bool

Check if self is initialized

• if this returns true, you can begin the WangLandau simulation
• otherwise call one of the self.init* methods

impl<Hist, R, E, S, Res, Energy> WangLandau1T<Hist, R, E, S, Res, Energy> where
    R: Rng,
    E: MarkovChain<S, Res>,
    Hist: Histogram + HistogramVal<Energy>,
    Energy: Clone, 

pub fn new(
    log_f_threshold: f64,
    ensemble: E,
    rng: R,
    step_size: usize,
    histogram: Hist,
    check_refine_every: usize
) -> Result<WangLandau1T<Hist, R, E, S, Res, Energy>, WangLandauErrors>

Create a new WangLandau simulation

IMPORTANT You have to call one of the init* functions, to create a valid state, before you can start the simulation

Parameter

• log_f_threshold: how small should the ln(f) (see paper) become until the simulation is finished?
• ensemble: The ensemble to explore. Current state of ensemble will be used as inital condition for the init* functions
• step_size: The markov steps will be performed with this step size, e.g., ensemble.m_steps(step_size)
• histogram: Provides the binning. You can either use one of the already implemented histograms, like HistU32Fast, HistU32, HistF64 etc. or implement your own by implementing the traits Histogram + HistogramVal<Energy> yourself
• check_refine_every: how often to check, if every bin in the histogram was hit. Needs to be at least 1. Good values depend on the problem at hand, but if you are unsure, you can start with a value like 1000

pub fn init_greedy_heuristic<F>(
    &mut self,
    energy_fn: F,
    step_limit: Option<u64>
) -> Result<(), WangLandauErrors> where
    F: Fn(&mut E) -> Option<Energy>, 

Find a valid starting Point

• if the ensemble is already at a valid starting point, the ensemble is left unchanged (as long as your energy calculation does not change the ensemble)
• Uses a greedy heuristik. Performs markov steps. If that brought us closer to the target interval, the step is accepted. Otherwise it is rejected

Parameter

• step_limit: Some(val) -> val is max number of steps tried, if no valid state is found, it will return an Error. None -> will loop until either a valid state is found or forever
• energy_fn function calculating Some(energy) of the system or rather the Parameter of which you wish to obtain the probability distribution. Has to be the same function as used for the wang landau simulation later. If there are any states, for which the calculation is invalid, None should be returned
• steps resulting in ensembles for which energy_fn(&mut ensemble) is None will always be rejected

pub fn init_interval_heuristik<F>(
    &mut self,
    overlap: NonZeroUsize,
    energy_fn: F,
    step_limit: Option<u64>
) -> Result<(), WangLandauErrors> where
    F: Fn(&mut E) -> Option<Energy>,
    Hist: HistogramIntervalDistance<Energy>, 

Find a valid starting Point

• if the ensemble is already at a valid starting point, the ensemble is left unchanged (as long as your energy calculation does not change the ensemble)
• 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

Parameter

• step_limit: Some(val) -> val is max number of steps tried, if no valid state is found, it will return an Error. None -> will loop until either a valid state is found or forever
• energy_fn function calculating Some(energy) of the system or rather the Parameter of which you wish to obtain the probability distribution. Has to be the same function as used for the wang landau simulation later. If there are any states, for which the calculation is invalid, None should be returned
• steps resulting in ensembles for which energy_fn(&mut ensemble) is None will always be rejected

pub fn init_mixed_heuristik<F, U>(
    &mut self,
    overlap: NonZeroUsize,
    mid: U,
    energy_fn: F,
    step_limit: Option<u64>
) -> Result<(), WangLandauErrors> where
    F: Fn(&mut E) -> Option<Energy>,
    U: One + Bounded + WrappingAdd + Eq + PartialOrd<U>,
    Hist: HistogramIntervalDistance<Energy>, 

Find a valid starting Point

• if the ensemble is already at a valid starting point, the ensemble is left unchanged (as long as your energy calculation does not change the ensemble)
• overlap - see HistogramIntervalDistance trait Should be greater than 0 and smaller than the number of bins in your histogram. E.g. overlap = 3 if you have 200 bins
• mid - should be something like 128u8, 0i8 or 0i16. It is very unlikely that using a type with more than 16 bit makes sense for mid
• step_limit: Some(val) -> val is max number of steps tried, if no valid state is found, it will return an Error. None -> will loop until either a valid state is found or forever
• alternates between greedy and interval heuristik everytime a wrapping counter passes mid or U::min_value()
• I recommend using this heuristik, if you do not know which one to use

Parameter

• energy_fn function calculating Some(energy) of the system or rather the Parameter of which you wish to obtain the probability distribution. Has to be the same function as used for the wang landau simulation later. If there are any states, for which the calculation is invalid, None should be returned
• steps resulting in ensembles for which energy_fn(&mut ensemble) is None will always be rejected

pub fn wang_landau_step<F>(&mut self, energy_fn: F) where
    F: Fn(&E) -> Option<Energy>, 

Wang Landau Step

• performs a single Wang Landau step

Parameter

• energy_fn function calculating Some(energy) of the system or rather the Parameter of which you wish to obtain the probability distribution. If there are any states, for which the calculation is invalid, None should be returned
• steps resulting in ensembles for which energy_fn(&mut ensemble) is None will always be rejected

Important

• You have to call one of the self.init* functions before calling this one - will panic otherwise

pub unsafe fn wang_landau_step_unsafe<F>(&mut self, energy_fn: F) where
    F: FnMut(&mut E) -> Option<Energy>, 

Wang Landau Step

• if possible, use self.wang_landau_step() instead - it is safer
• unsafe, because you have to make sure, that the energy_fn function does not change the state of the ensemble in such a way, that the result of energy_fn changes when called again. Maybe do cleanup at the beginning of the energy function?
• performs a single Wang Landau step

Parameter

• energy_fn function calculating Some(energy) of the system or rather the Parameter of which you wish to obtain the probability distribution. If there are any states, for which the calculation is invalid, None should be returned
• steps resulting in ensembles for which energy_fn(&mut ensemble) is None will always be rejected

Important

• You have to call one of the self.init* functions before calling this one - will panic otherwise

pub fn wang_landau_step_acc<F>(&mut self, energy_fn: F) where
    F: FnMut(&E, &S, &mut Energy), 

Wang Landau Step

• performs a single Wang Landau step

Parameter

• energy_fn function calculating the energy of the system on the fly
• steps resulting in invalid ensembles are not allowed!

Important

• You have to call one of the self.init* functions before calling this one - will panic otherwise

pub fn wang_landau_convergence<F>(&mut self, energy_fn: F) where
    F: Fn(&E) -> Option<Energy>, 

Wang Landau

• perform Wang Landau simulation
• calls self.wang_landau_step(energy_fn, valid_ensemble) until self.is_finished()

pub fn wang_landau_convergence_acc<F>(&mut self, energy_fn: F) where
    F: FnMut(&E, &S, &mut Energy), 

Wang Landau - efficient energy calculation

• perform Wang Landau simulation
• calls self.wang_landau_step_acc(energy_fn, valid_ensemble) until self.is_finished()

pub unsafe fn wang_landau_convergence_unsafe<F>(&mut self, energy_fn: F) where
    F: FnMut(&mut E) -> Option<Energy>, 

Wang Landau

• if possible, use self.wang_landau_convergence() instead - it is safer
• You have mutable access to your ensemble, which is why this function is unsafe. If you do anything, which changes the future outcome of the energy function, the results will be wrong!
• perform Wang Landau simulation
• calls self.wang_landau_step_unsafe(energy_fn, valid_ensemble) until self.is_finished()

pub fn wang_landau_while<F, W>(&mut self, energy_fn: F, condition: W) where
    F: Fn(&E) -> Option<Energy>,
    W: FnMut(&WangLandau1T<Hist, R, E, S, Res, Energy>) -> bool, 

Wang Landau

• perform Wang Landau simulation
• calls self.wang_landau_step(energy_fn) until self.is_finished() or condition(&self) is false

pub fn wang_landau_while_acc<F, W>(&mut self, energy_fn: F, condition: W) where
    F: FnMut(&E, &S, &mut Energy),
    W: FnMut(&WangLandau1T<Hist, R, E, S, Res, Energy>) -> bool, 

Wang Landau

• perform Wang Landau simulation
• calls self.wang_landau_step(energy_fn) until self.is_finished() or condition(&self) is false

pub unsafe fn wang_landau_while_unsafe<F, W>(
    &mut self,
    energy_fn: F,
    condition: W
) where
    F: FnMut(&mut E) -> Option<Energy>,
    W: FnMut(&WangLandau1T<Hist, R, E, S, Res, Energy>) -> bool, 

Wang Landau

• if possible, use self.wang_landau_while() instead - it is safer
• You have mutable access to your ensemble, which is why this function is unsafe. If you do anything, which changes the future outcome of the energy function, the results will be wrong!
• perform Wang Landau simulation
• calls self.wang_landau_step(energy_fn) until self.is_finished() or condition(&self) is false

Trait Implementations

impl<Hist, Rng, Ensemble, S, Res, Energy> Clone for WangLandau1T<Hist, Rng, Ensemble, S, Res, Energy> where
    Rng: Clone,
    S: Clone,
    Res: Clone,
    Hist: Clone,
    Energy: Clone,
    Ensemble: Clone, 

pub fn clone(&self) -> WangLandau1T<Hist, Rng, Ensemble, S, Res, Energy>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Hist, Rng, Ensemble, S, Res, Energy> Debug for WangLandau1T<Hist, Rng, Ensemble, S, Res, Energy> where
    Rng: Debug,
    S: Debug,
    Res: Debug,
    Hist: Debug,
    Energy: Debug,
    Ensemble: Debug, 

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

Formats the value using the given formatter.

impl<'de, Hist, Rng, Ensemble, S, Res, Energy> Deserialize<'de> for WangLandau1T<Hist, Rng, Ensemble, S, Res, Energy> where
    Rng: Deserialize<'de>,
    S: Deserialize<'de>,
    Hist: Deserialize<'de>,
    Energy: Deserialize<'de>,
    Ensemble: Deserialize<'de>, 

pub fn deserialize<__D>(
    __deserializer: __D
) -> Result<WangLandau1T<Hist, Rng, Ensemble, S, Res, Energy>, <__D as Deserializer<'de>>::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<Hist, Rng, Ensemble, S, Res, Energy> Serialize for WangLandau1T<Hist, Rng, Ensemble, S, Res, Energy> where
    Rng: Serialize,
    S: Serialize,
    Hist: Serialize,
    Energy: Serialize,
    Ensemble: Serialize, 

pub 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.

impl<Hist, R, E, S, Res, Energy> TryFrom<WangLandau1T<Hist, R, E, S, Res, Energy>> for EntropicSampling<Hist, R, E, S, Res, Energy> where
    R: Rng,
    Hist: Histogram, 

type Error = EntropicErrors

The type returned in the event of a conversion error.

pub fn try_from(
    wl: WangLandau1T<Hist, R, E, S, Res, Energy>
) -> Result<EntropicSampling<Hist, R, E, S, Res, Energy>, <EntropicSampling<Hist, R, E, S, Res, Energy> as TryFrom<WangLandau1T<Hist, R, E, S, Res, Energy>>>::Error>

Performs the conversion.

impl<Hist, R, E, S, Res, Energy> WangLandau for WangLandau1T<Hist, R, E, S, Res, Energy>

pub fn log_f(&self) -> f64

get current value of log_f

pub fn log_f_threshold(&self) -> f64

returns currently set threshold for log_f

pub fn set_log_f_threshold(
    &mut self,
    log_f_threshold: f64
) -> Result<f64, WangLandauErrors>

Try to set the threshold.

pub fn log_density(&self) -> &Vec<f64, Global>

Current (non normalized) estimate of ln(P(E))

pub fn write_log<W>(&self, writer: W) -> Result<(), Error> where
    W: Write, 

Writes Information about the simulation to a file. E.g. How many steps were performed.

pub fn mode(&self) -> WangLandauMode

Returns current wang landau mode

pub fn step_counter(&self) -> usize

Counter

pub fn total_steps_rejected(&self) -> usize

How many steps were rejected until now?

pub fn total_steps_accepted(&self) -> usize

How many steps were accepted until now?

fn is_finished(&self) -> bool

Checks wang landau threshold

fn log_density_base10(&self) -> Vec<f64, Global>

Current (non normalized) estimate of log10(P(E))

fn log_density_base(&self, base: f64) -> Vec<f64, Global>

Current (non normalized) estimate of log_base(P(E))

fn steps_total(&self) -> usize

Counter

fn fraction_accepted_total(&self) -> f64

Calculate, which fraction of steps were accepted

fn fraction_rejected_total(&self) -> f64

Calculate, which fraction of steps were rejected

impl<Hist, R, E, S, Res, Energy> WangLandauEnergy<Energy> for WangLandau1T<Hist, R, E, S, Res, Energy>

pub fn energy(&self) -> Option<&Energy>

returns the last accepted Energy calculated None if no energy was calculated yet

impl<Hist, R, E, S, Res, Energy> WangLandauEnsemble<E> for WangLandau1T<Hist, R, E, S, Res, Energy>

pub fn ensemble(&self) -> &E

return reference to current state of ensemble

pub unsafe fn ensemble_mut(&mut self) -> &mut E

mutable reference to current state

impl<Hist, R, E, S, Res, Energy> WangLandauHist<Hist> for WangLandau1T<Hist, R, E, S, Res, Energy>

pub fn hist(&self) -> &Hist

returns current histogram