Struct sampling::wang_landau::WangLandauAdaptive

pub struct WangLandauAdaptive<Hist, R, E, S, Res, Energy> { /* private fields */ }

Adaptive WangLandau 1/t

• please cite

Yannick Feld and Alexander K. Hartmann, “Large-deviations of the basin stability of power grids,” Chaos 29:113113 (2019), DOI 10.1063/1.5121415

as this adaptive approach was first used and described in this paper. Also cite the following

• 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 algorithm 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> WangLandauAdaptive<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<R, E, S, Res, Hist, Energy> WangLandauAdaptive<Hist, R, E, S, Res, Energy>

pub fn min_step_size(&self) -> usize

Smallest possible markov step (m_steps of MarkovChain trait) tried by wang landau step

pub fn max_step_size(&self) -> usize

Largest possible markov step (m_steps of MarkovChain trait) tried by wang landau step

pub fn is_rebuilding_statistics(&self) -> bool

Is the simulation in the process of rebuilding the statistics, i.e., is it currently trying many different step sizes?

pub fn finished_rebuilding_statistics(&self) -> bool

Is the simulation has finished the process of rebuilding the statistics, i.e., is it currently not trying many different step sizes

pub fn fraction_of_statistics_gathered(&self) -> f64

Tracks progress

• tracks progress until self.is_rebuilding_statistics becomes false
• returned value is always 0 <= val <= 1.0

pub fn fraction_accepted_current(&self) -> f64

Fraction of steps accepted since the statistics were reset the last time

• (steps accepted since last reset) / (steps since last reset)

pub fn estimate_statistics(&self) -> Result<Vec<f64>, WangLandauErrors>

Estimate accept/reject statistics

• contains list of estimated probabilities for accepting a step of corresponding step size
• list[i] corresponds to step size i + self.min_step
• O(trial_step_max - trial_step_min)

impl<R, E, S, Res, Hist, Energy> WangLandauAdaptive<Hist, R, E, S, Res, Energy>

pub fn samples_per_trial(&self) -> usize

• samples_per_trial - how often a specific step_size should be tried before estimating the fraction of accepted steps resulting from the stepsize
• This number was used to create a trial list of appropriate length

impl<R, E, S, Res, Hist, Energy> WangLandauAdaptive<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, samples_per_trial: usize, trial_step_min: usize, trial_step_max: usize, min_best_of_count: usize, best_of_threshold: f64, histogram: Hist, check_refine_every: usize ) -> Result<Self, WangLandauErrors>

New WangLandauAdaptive

• log_f_threshold - threshold for the simulation
• ensemble ensemble used for the simulation
• rng - random number generator used
• samples_per_trial - how often a specific step_size should be tried before estimating the fraction of accepted steps resulting from the stepsize
• trial_step_min and trial_step_max: The step sizes tried are: [trial_step_min, trial_step_min + 1, …, trial_step_max]
• min_best_of_count: After estimating, use at least the best min_best_of_count step sizes found
• best_of_threshold: After estimating, use all steps for which abs(acceptance_rate -0.5) <= best_of_threshold holds true
• histogram: How your energy will be binned etc
• check_refine_every: how often to check if log_f can be refined?

Important

• **You need to call on of the self.init* members before starting the Wang Landau simulation! - you can check with self.is_initialized()
• Err if trial_step_max < trial_step_min
• Err if log_f_threshold <= 0.0

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>, Hist: HistogramIntervalDistance<Energy>, U: One + Bounded + WrappingAdd + Eq + PartialOrd,

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 trait HistogramIntervalDistance. Should 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 heuristic every time a wrapping counter passes mid or U::min_value()

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

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_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 heuristic. 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 wang_landau_while<F, W>(&mut self, energy_fn: F, condition: W)

where F: Fn(&E) -> Option<Energy>, W: FnMut(&Self) -> bool,

Wang Landau

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

Important

• You have to call one of the self.init* functions before calling this one - you can check with self.is_initialized()
• will panic otherwise, at least in debug mode

pub fn wang_landau_while_acc<F, W>(&mut self, energy_fn: F, condition: W)

where F: FnMut(&E, &S, &mut Energy), W: FnMut(&Self) -> bool,

Wang Landau Simulation

• similar to wang_landau_while

Difference

uses accumulating markov steps, i.e., it updates the Energy during the markov steps. This can be more efficient. Therefore the energy_fn now gets the state of the ensemble after the markov step &E, the step that was performed &S as well as a mutable reference to the old Energy &mut Energy which is to change

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(&Self) -> bool,

Wang Landau

• if possible, use self.wang_landau_while() instead - it is safer
• You have mutable access to your ensemble 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

Safety

• You have to call one of the self.init* functions before calling this one - you can check with self.is_initialized()
• will panic otherwise, at least in debug mode
• Be careful of the mutable access of your energy, it has the potential to break logical things in the wang-landau etc. simulations

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()

Important

• You have to call one of the self.init* functions before calling this one - you can check with self.is_initialized()
• will panic otherwise, at least in debug mode

pub fn wang_landau_convergence_acc<F>(&mut self, energy_fn: F)

where F: FnMut(&E, &S, &mut Energy),

Wang Landau simulation

• similar to wang_landau_convergence

Difference

uses accumulating markov steps, i.e., it updates the Energy during the markov steps. This can be more efficient. Therefore the energy_fn now gets the state of the ensemble after the markov step &E, the step that was performed &S as well as a mutable reference to the old Energy &mut Energy which is to change

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 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()

Safety

• You have to call one of the self.init* functions before calling this one - you can check with self.is_initialized()
• will panic otherwise, at least in debug mode

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 - you can check with self.is_initialized()
• will panic otherwise, at least in debug mode

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
• 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

Safety

• You have to call one of the self.init* functions before calling this one - you can check with self.is_initialized()
• will panic otherwise, at least in debug mode
• 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?

pub fn wang_landau_step_acc<F>(&mut self, energy_fn: F)

where F: FnMut(&E, &S, &mut Energy),

Accumulating wang landau step

• similar to wang_landau_step

Difference

• this uses accumulating markov steps, i.e., it calculates the Energy during each markov step, which can be more efficient. This assumes, that cloning the Energy is cheap, which is true for primitive types like usize or f64
• parameter of energy_fn: &E Ensemble after the markov step &S was performed. &mut Energy is the old energy, which has to be changed to the new energy of the system

Trait Implementations

impl<Hist: Clone, R: Clone, E: Clone, S: Clone, Res: Clone, Energy: Clone> Clone for WangLandauAdaptive<Hist, R, E, S, Res, Energy>

fn clone(&self) -> WangLandauAdaptive<Hist, R, E, S, Res, Energy>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Hist: Debug, R: Debug, E: Debug, S: Debug, Res: Debug, Energy: Debug> Debug for WangLandauAdaptive<Hist, R, E, S, Res, Energy>

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

Formats the value using the given formatter.

impl<'de, Hist, R, E, S, Res, Energy> Deserialize<'de> for WangLandauAdaptive<Hist, R, E, S, Res, Energy>

where Hist: Deserialize<'de>, R: Deserialize<'de>, E: Deserialize<'de>, S: Deserialize<'de>, Energy: Deserialize<'de>,

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<Hist, R, E, S, Res, Energy> GlueAble<Hist> for WangLandauAdaptive<Hist, R, E, S, Res, Energy>

where Hist: Clone,

fn push_glue_entry_ignoring( &self, job: &mut GlueJob<Hist>, ignore_idx: &[usize] )

fn push_glue_entry(&self, job: &mut GlueJob<H>)

impl<Hist, R, E, S, Res, Energy> Serialize for WangLandauAdaptive<Hist, R, E, S, Res, Energy>

where Hist: Serialize, R: Serialize, E: Serialize, S: Serialize, Energy: Serialize,

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<Hist, R, E, S, Res, T> TryFrom<WangLandauAdaptive<Hist, R, E, S, Res, T>> for EntropicSampling<Hist, R, E, S, Res, T>

where Hist: Histogram, R: Rng,

fn try_from( wl: WangLandauAdaptive<Hist, R, E, S, Res, T> ) -> Result<Self, Self::Error>

Uses as stepsize: first entry of bestof. If bestof is empty, it uses wl.min_step_size() + (wl.max_step_size() - wl.max_step_size()) / 2

type Error = EntropicErrors

The type returned in the event of a conversion error.

impl<Hist, R, E, S, Res, T> TryFrom<WangLandauAdaptive<Hist, R, E, S, Res, T>> for EntropicSamplingAdaptive<Hist, R, E, S, Res, T>

where Hist: Histogram, R: Rng,

type Error = EntropicErrors

The type returned in the event of a conversion error.

fn try_from( wl: WangLandauAdaptive<Hist, R, E, S, Res, T> ) -> Result<Self, Self::Error>

Performs the conversion.

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

fn total_steps_accepted(&self) -> usize

How many steps were accepted until now?

fn total_steps_rejected(&self) -> usize

How many steps were rejected until now?

fn log_f(&self) -> f64

get current value of log_f

fn log_f_threshold(&self) -> f64

returns currently set threshold for log_f

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

Try to set the threshold.

fn log_density(&self) -> &Vec<f64>

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

fn mode(&self) -> WangLandauMode

Returns current wang landau mode

fn step_counter(&self) -> usize

Counter

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

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

fn is_finished(&self) -> bool

Checks wang landau threshold

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

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

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

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<R, E, S, Res, Hist, Energy> WangLandauEnergy<Energy> for WangLandauAdaptive<Hist, R, E, S, Res, Energy>

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

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

impl<R, E, S, Res, Hist, T> WangLandauEnsemble<E> for WangLandauAdaptive<Hist, R, E, S, Res, T>

fn ensemble(&self) -> &E

return reference to current state of ensemble

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

mutable reference to current state

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

fn hist(&self) -> &Hist

returns current histogram