Struct sampling::entropic_sampling::EntropicSamplingAdaptive

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

Entropic sampling made easy

J. Lee, “New Monte Carlo algorithm: Entropic sampling,” Phys. Rev. Lett. 71, 211–214 (1993), DOI: 10.1103/PhysRevLett.71.211

Implementations

impl<Hist, R, E, S, Res, T> EntropicSamplingAdaptive<Hist, R, E, S, Res, T>

pub fn ensemble(&self) -> &E

Current state of the Ensemble

pub fn energy(&self) -> &T

Energy of ensemble

• assuming energy_fn (see self.entropic_step etc.) is deterministic and will allways give the same result for the same ensemble, this returns the energy of the current ensemble

pub fn step_count(&self) -> usize

Number of entropic steps done until now

• will be reset by self.refine_estimate

pub fn step_goal(&self) -> usize

Number of entropic steps to be performed

• if self was created from WangLandauAdaptive, step_goal will be equal to the number of WangLandau steps, that were performed

pub fn set_step_goal(&mut self, step_goal: usize)

Number of entropic steps to be performed

• set the number of steps to be performed by entropic sampling

pub fn min_step_size(&self) -> usize

Smallest possible markov step (m_steps of MarkovChain trait) by entropic step

pub fn max_step_size(&self) -> usize

Largest possible markov step (m_steps of MarkovChain trait) by entropic step

pub fn best_of_steps(&self) -> &Vec<usize>

Currently used best of

• might have length 0, if statistics are still being gathered
• otherwise this contains the step sizes, from which the next stepsize is drawn uniformly

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)
• NaN if no steps were performed yet

pub fn total_entr_steps_accepted(&self) -> usize

total number of entropic steps, that were accepted

pub fn total_entr_steps_rejected(&self) -> usize

total number of entropic steps, that were rejected

pub fn fraction_accepted_total_entropic(&self) -> f64

Fraction of steps accepted since the creation of self

• NaN if no steps were performed yet

pub fn log_density_estimate(&self) -> &Vec<f64>

• returns the (non normalized) log_density estimate log(P(E)), with which the simulation was started
• if you created this from a WangLandau simulation, this is the result of the WangLandau Simulation

pub fn hist(&self) -> &Hist

Return current state of histogram

impl<Hist, R, E, S, Res, T> EntropicSamplingAdaptive<Hist, R, E, S, Res, T>where
    Hist: Histogram,
    R: Rng,

pub fn from_wl_adaptive(
    wl: WangLandauAdaptive<Hist, R, E, S, Res, T>
) -> Result<Self, EntropicErrors>

Creates EntropicSamplingAdaptive from a WangLandauAdaptive state

• WangLandauAdaptive state needs to be valid, i.e., you must have called one of the init* methods

• this ensures, that the members old_energy and old_bin are not None

pub fn log_density_refined(&self) -> Vec<f64>

calculates the (non normalized) log_density estimate log(P(E)) according to the paper

pub fn refine_estimate(&mut self) -> Vec<f64>

Calculates self.log_density_refined and uses that as estimate for a the entropic sampling simulation

• returns old estimate

prepares self for a new entropic simulation

• sets new estimate for log(P(E))
• resets statistic gathering
• resets step_count

pub fn set_adjust_bestof_every(&mut self, adjust_bestof_every: usize)

How often to adjust bestof_steps?

• if you try to set a value smaller 10, it will be set to 10
• will reevalute the statistics every adjust_bestof_every steps,

• this will not start new statistics gathering but just trigger a reevaluation of the gathered statistics (should be O(max_stepsize - min_stepsize))

pub fn is_rebuilding_statistics(&self) -> bool

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

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<Hist, R, E, S, Res, T> EntropicSamplingAdaptive<Hist, R, E, S, Res, T>where
    Hist: Histogram + HistogramVal<T>,
    R: Rng,
    E: MarkovChain<S, Res>,
    T: Clone,

pub unsafe fn entropic_sampling_while_unsafe<F, G, W>(
    &mut self,
    energy_fn: F,
    print_fn: G,
    condition: W
)where
    F: FnMut(&mut E) -> Option<T>,
    G: FnMut(&Self),
    W: FnMut(&Self) -> bool,

Entropic sampling

• performs self.entropic_step(energy_fn) until condition is false
• Note: you have access to the current step_count (self.step_count())

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 energy_fn: should be the same as used for Wang Landau, otherwise the results will be wrong!
• print_fn: see below

Correlations

• if you want to measure correlations between “energy” and other measurable quantities, use print_fn, which will be called after each step - use this function to write to a file or whatever you desire
• Note: You do not have to recalculate the energy, if you need it in print_fn: just call self.energy()
• you have access to your ensemble with self.ensemble()
• if you do not need it, you can use |_|{} as print_fn

Safety

• While you do have mutable access to the ensemble, the energy function should not change the ensemble in a way, which affects the next calculation of the energy
• This is intended for usecases, where the energy calculation is more efficient with mutable access, e.g., through using a buffer stored in the ensemble
• Note: I chose to make this function unsafe to force users to aknowledge the (purely logical) limitations regarding the usage of the mutable ensemble. From a programming point of view this will not lead to any undefined behavior or such regardless of if the user fullfills the requirements

pub fn entropic_sampling_while<F, G, W>(
    &mut self,
    energy_fn: F,
    print_fn: G,
    condition: W
)where
    F: FnMut(&E) -> Option<T>,
    G: FnMut(&Self),
    W: FnMut(&Self) -> bool,

Entropic sampling

• performs self.entropic_step(energy_fn) until condition is false
• Note: you have access to the current step_count (self.step_count())

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 energy_fn: should be the same as used for Wang Landau, otherwise the results will be wrong!
• print_fn: see below

Correlations

• if you want to measure correlations between “energy” and other measurable quantities, use print_fn, which will be called after each step - use this function to write to a file or whatever you desire
• Note: You do not have to recalculate the energy, if you need it in print_fn: just call self.energy()
• you have access to your ensemble with self.ensemble()
• if you do not need it, you can use |_|{} as print_fn

pub fn entropic_sampling_while_acc<F, G, W>(
    &mut self,
    energy_fn: F,
    print_fn: G,
    condition: W
)where
    F: FnMut(&E, &S, &mut T),
    G: FnMut(&Self),
    W: FnMut(&Self) -> bool,

Entropic sampling using an accumulating markov step

• performs self.entropic_step_acc(&mut energy_fn) until condition(self) == false

Parameter

• energy_fn function calculating the energy E of the system (or rather the Parameter of which you wish to obtain the probability distribution) during the markov steps, which can be more efficient.
• Important energy_fn: should be the same as used for Wang Landau, otherwise the results will be wrong!
• print_fn: see below

Correlations

• if you want to measure correlations between “energy” and other measurable quantities, use print_fn, which will be called after each step - use this function to write to a file or whatever you desire
• Note: You do not have to recalculate the energy, if you need it in print_fn: just call self.energy()
• you have access to your ensemble with self.ensemble()
• if you do not need it, you can use |_|{} as print_fn

pub unsafe fn entropic_sampling_unsafe<F, G>(&mut self, energy_fn: F, print_fn: G)where
    F: FnMut(&mut E) -> Option<T>,
    G: FnMut(&mut Self),

Entropic sampling

• if possible, use self.entropic_sampling() instead!
• More powerful version of self.entropic_sampling(), since you now have mutable access
• to access ensemble mutable, use self.ensemble_mut()
• Note: Whatever you do with the ensemble (or self), should not change the result of the energy function, if performed again. Otherwise the results will be false!
• performs self.entropic_step_unsafe(energy_fn) until self.step_count == self.step_goal

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 energy_fn: should be the same as used for Wang Landau, otherwise the results will be wrong!
• print_fn: see below

Correlations

• if you want to measure correlations between “energy” and other measurable quantities, use print_fn, which will be called after each step - use this function to write to a file or whatever you desire
• Note: You do not have to recalculate the energy, if you need it in print_fn: just call self.energy()
• you have access to your ensemble with self.ensemble()
• if you do not need it, you can use |_|{} as print_fn

Safety

• While you do have mutable access to the ensemble, the energy function should not change the ensemble in a way, which affects the next calculation of the energy
• This is intended for usecases, where the energy calculation is more efficient with mutable access, e.g., through using a buffer stored in the ensemble
• Note: I chose to make this function unsafe to force users to aknowledge the (purely logical) limitations regarding the usage of the mutable ensemble. From a programming point of view this will not lead to any undefined behavior or such regardless of if the user fullfills the requirements

pub fn entropic_sampling<F, G>(&mut self, energy_fn: F, print_fn: G)where
    F: FnMut(&E) -> Option<T>,
    G: FnMut(&Self),

Entropic sampling

• performs self.entropic_step(energy_fn) until self.step_count == self.step_goal

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 energy_fn: should be the same as used for Wang Landau, otherwise the results will be wrong!
• print_fn: see below

Correlations

• if you want to measure correlations between “energy” and other measurable quantities, use print_fn, which will be called after each step - use this function to write to a file or whatever you desire
• Note: You do not have to recalculate the energy, if you need it in print_fn: just call self.energy()
• you have access to your ensemble with self.ensemble()
• if you do not need it, you can use |_|{} as print_fn

pub fn entropic_sampling_acc<F, G>(&mut self, energy_fn: F, print_fn: G)where
    F: FnMut(&E, &S, &mut T),
    G: FnMut(&Self),

Entropic sampling using an accumulating markov step

• performs self.entropic_step_acc(&mut energy_fn) until self.step_count == self.step_goal

Parameter

• energy_fn function calculating the energy E of the system (or rather the Parameter of which you wish to obtain the probability distribution) during the markov steps, which can be more efficient.
• Important energy_fn: should be the same as used for Wang Landau, otherwise the results will be wrong!
• print_fn: see below

Correlations

• if you want to measure correlations between “energy” and other measurable quantities, use print_fn, which will be called after each step - use this function to write to a file or whatever you desire
• Note: You do not have to recalculate the energy, if you need it in print_fn: just call self.energy()
• you have access to your ensemble with self.ensemble()
• if you do not need it, you can use |_|{} as print_fn

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

Entropic step

• performs a single 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

• energy_fn: should be the same as used for Wang Landau, otherwise the results will be wrong!

Safety

• While you do have mutable access to the ensemble, the energy function should not change the ensemble in a way, which affects the next calculation of the energy
• This is intended for usecases, where the energy calculation is more efficient with mutable access, e.g., through using a buffer stored in the ensemble
• Note: I chose to make this function unsafe to force users to aknowledge the (purely logical) limitations regarding the usage of the mutable ensemble. From a programming point of view this will not lead to any undefined behavior or such regardless of if the user fullfills the requirements

pub fn entropic_step<F>(&mut self, energy_fn: F)where
    F: FnMut(&E) -> Option<T>,

Entropic step

• performs a single 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

• energy_fn: should be the same as used for Wang Landau, otherwise the results will be wrong!

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

Accumulating entropic step

• performs a single step

Parameter

• energy_fn function calculating the energy E of the system (or rather the Parameter of which you wish to obtain the probability distribution) during the markov steps, which can be more efficient.

Important

• energy_fn: should be the same as used for Wang Landau, otherwise the results will be wrong!

Trait Implementations

impl<Hist: Clone, R: Clone, E: Clone, S: Clone, Res: Clone, T: Clone> Clone for EntropicSamplingAdaptive<Hist, R, E, S, Res, T>

fn clone(&self) -> EntropicSamplingAdaptive<Hist, R, E, S, Res, T>

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, T: Debug> Debug for EntropicSamplingAdaptive<Hist, R, E, S, Res, T>

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

Formats the value using the given formatter.

impl<'de, Hist, R, E, S, Res, T> Deserialize<'de> for EntropicSamplingAdaptive<Hist, R, E, S, Res, T>where
    Hist: Deserialize<'de>,
    R: Deserialize<'de>,
    E: Deserialize<'de>,
    S: Deserialize<'de>,
    T: 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, T> Entropic for EntropicSamplingAdaptive<Hist, R, E, S, Res, T>where
    Hist: Histogram,
    R: Rng,

fn step_counter(&self) -> usize

Number of entropic steps done until now

• will be reset by self.refine_estimate

fn step_goal(&self) -> usize

Number of entropic steps to be performed

• if self was created from WangLandauAdaptive, step_goal will be equal to the number of WangLandau steps, that were performed

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_density(&self) -> Vec<f64>

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

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

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

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

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

impl<Hist, R, E, S, Res, Energy> EntropicEnergy<Energy> for EntropicSamplingAdaptive<Hist, R, E, S, Res, Energy>where
    Hist: Histogram,
    R: Rng,

fn energy(&self) -> &Energy

Energy of ensemble

• assuming energy_fn (see self.entropic_step etc.) is deterministic and will allways give the same result for the same ensemble, this returns the energy of the current ensemble

impl<Hist, R, E, S, Res, Energy> EntropicEnsemble<E> for EntropicSamplingAdaptive<Hist, R, E, S, Res, Energy>where
    Hist: Histogram,
    R: Rng,

fn ensemble(&self) -> &E

return reference to current state of ensemble

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

returns mutable reference to ensemble

impl<Hist, R, E, S, Res, Energy> EntropicHist<Hist> for EntropicSamplingAdaptive<Hist, R, E, S, Res, Energy>where
    Hist: Histogram,
    R: Rng,

fn hist(&self) -> &Hist

returns current histogram

impl<Hist, R, E, S, Res, Energy> HasRng<R> for EntropicSamplingAdaptive<Hist, R, E, S, Res, Energy>where
    R: Rng,

fn rng(&mut self) -> &mut R

Access RNG

fn swap_rng(&mut self, rng: &mut R)

If you need to exchange the internal rng

impl<Hist, R, E, S, Res, T> Serialize for EntropicSamplingAdaptive<Hist, R, E, S, Res, T>where
    Hist: Serialize,
    R: Serialize,
    E: Serialize,
    S: Serialize,
    T: 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 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.