Struct net_ensembles::sampling::Metropolis

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

Create a metropolis simulation

Citation see, e.g,

M. E. J. Newman and G. T. Barkema, “Monte Carlo Methods in Statistical Physics” Clarendon Press, 1999, ISBN: 978-0-19-8517979

Explanation

• used for large-deviation simulations
• Performes markov chain using the markov chain trait

All self.metropolis* functions do the following

• Let the current state of the system (i.e., the ensemble) be S(i) with corresponding energy E(i) = energy_fn(S(i)).
• Now perform a markov step, such that the new system is S_new with energy E_new.
• The new state will be accepted (meaning S(i+1) = S_new) with probability: min[1.0, exp{m_beta * (E_new - E(i))}]
• otherwise the new state will be rejected, meaning S(i + 1) = S(i).
• the measure function is called: measure(S(i + 1))

Implementations

impl<R, E, S, Res, T> Metropolis<E, R, S, Res, T>where
    T: Copy + AsPrimitive<f64>,

pub fn m_beta(&self) -> f64

returns stored m_beta value (-β for metropolis)

pub fn set_m_beta(&mut self, m_beta: f64)

sets m_beta (minus beta). Is related to the temperature: m_beta = -1 / temperature

pub fn set_temperature(&mut self, temperature: f64)

sets m_beta according to m_beta = -1 / temperature

pub fn energy(&self) -> T

returns stored value for current_energy

pub unsafe fn set_energy(&mut self, energy: T) -> Result<(), ()>

set stored value for current_energy

• Will return Err() if you try to set the energy to nan
• otherwise it will set the stored energy and return Ok(())

Important

• It is very unlikely that you need this function - Only use it, if you know what you are doing

Safety

This is not unsafe in the programming sense, but I chose to make it unsafe anyway to make the user aknowledge that this will result in a logical error for the algorithms if set to the incorrect energy

pub fn ensemble(&self) -> &E

returns reference to ensemble

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

returns mutable reference to ensemble

• use with care!

Safety

• if you change your ensemble, this might invalidate the simulation!
• The metropolis functions do not calculate the energy of the current state
• Unsafe purely for logical reasons, in the programming sense this function didn’t need to be unsafe

pub fn counter(&self) -> usize

returns stored value for the counter, i.e., where to resume iteration

• note: counter is a wrapping counter
• counter is increase each time, a markov step is performed, i.e, each time ensemble.m_steps(step_size) is called, the counter will increase by 1 (not by step_size)

pub fn reset_counter(&mut self)

resets the counter to 0

• note: counter is a wrapping counter

pub fn step_size(&self) -> usize

return current stepsize

pub fn set_step_size(&mut self, step_size: usize) -> Result<(), ()>

• change the stepsize
• returns err if you try to set stepsize to 0, because that would be invalid

impl<E, R, S, Res, T> Metropolis<E, R, S, Res, T>where
    R: Rng,
    E: MarkovChain<S, Res>,
    T: Copy + AsPrimitive<f64>,

pub fn new_from_m_beta(
    rng: R,
    ensemble: E,
    energy: T,
    m_beta: f64,
    step_size: usize
) -> Result<Metropolis<E, R, S, Res, T>, MetropolisError>

Create a new Metropolis struct - used for Metropolis simulations

	meaning
rng	the Rng used to decide, if a state should be accepted or rejected
ensemble	the ensemble that is explored with the markov chain
energy	current energy of the ensemble - cannot be NAN, should match energy_fn(ensemble) (see metropolis* functions)
m_beta	minus beta, has to be finite - used for acceptance, i.e., probability to accept a markov step from Energy E to Energy E_new is min[1.0, exp{m_beta * (E_new - E)}]
step_size	is used for each markov step, i.e., ensemble.m_steps(stepsize) is called

• will return Err if energy is nan or m_beta is not finite

pub fn new_from_temperature(
    rng: R,
    ensemble: E,
    energy: T,
    temperature: f64,
    step_size: usize
) -> Result<Metropolis<E, R, S, Res, T>, MetropolisError>

Create a new Metropolis struct - used for Metropolis simulations

	meaning
rng	the Rng used to decide, if a state should be accepted or rejected
ensemble	the ensemble that is explored with the markov chain
energy	current energy of the ensemble - cannot be NAN, should match energy_fn(ensemble) (see metropolis* functions)
temperature	m_beta = -1.0/temperature. Used for acceptance, i.e., probability to accept a markov step from Energy E to Energy E_new is min[1.0, exp{m_beta * (E_new - E)}]
step_size	is used for each markov step, i.e., ensemble.m_steps(stepsize) is called

• will return Err if energy is nan or m_beta is not finite

pub fn change_markov_chain<S2, Res2>(self) -> Metropolis<E, R, S2, Res2, T>where
    E: MarkovChain<S2, Res2>,

Change, which markov chain is used for the metropolis simulations

• Use this if there are different ways to perform a markov chain for your problem and you want to switch between them

pub fn metropolis<Energy, Mes>(
    &mut self,
    step_target: usize,
    energy_fn: Energy,
    measure: Mes
)where
    Energy: FnMut(&E) -> Option<T>,
    Mes: FnMut(&Metropolis<E, R, S, Res, T>),

Metropolis Simulation

• see
• performs self.counter..=step_target markov steps
• energy_fn(self.ensemble) is assumed to equal self.energy at the beginning!
• if energy_fn returns None, the step will always be rejected
• after each acceptance/rejection, measure is called

Note

• I assume, that the energy_fn never returns nan (when cast as f64) If nan is possible, please check for that beforhand and return None in that case
• Maybe do the same for infinity, it is unlikely, that infinit energys make sense

pub unsafe fn metropolis_unsafe<Energy, Mes>(
    &mut self,
    step_target: usize,
    energy_fn: Energy,
    measure: Mes
)where
    Energy: FnMut(&mut E) -> Option<T>,
    Mes: FnMut(&mut Metropolis<E, R, S, Res, T>),

Metropolis Simulation

• see
• performs self.counter..=step_target markov steps
• energy_fn(self.ensemble) is assumed to equal self.energy at the beginning!
• if energy_fn returns None, the step will always be rejected
• after each acceptance/rejection, measure is called

Important

• if possible, prefere self.metropolis as it is safer
• use this, if your energy function needs mutable access, or measureneeds mutable access. Be careful though, this can invalidate the results of your simulation

Safety

• I assume, that the energy_fn never returns nan (when cast as f64) If nan is possible, please check for that beforhand and return None in that case
• Maybe do the same for infinity, it is unlikely, that infinit energys make sense
• 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 metropolis_efficient<Energy, Mes>(
    &mut self,
    step_target: usize,
    energy_fn: Energy,
    measure: Mes
)where
    Energy: FnMut(&E, T, &[S]) -> Option<T>,
    Mes: FnMut(&Metropolis<E, R, S, Res, T>),

Metropolis Simulation

• see
• performs self.counter..=step_target markov steps
• energy_fn(self.ensemble) is assumed to equal self.energy at the beginning!
• if energy_fn returns None, the step will always be rejected
• after each acceptance/rejection, measure is called

Difference to self.metropolis

• Function parameter of energy_fn: &ensemble, old_energy, &[steps] - that means, you should prefere this, if you can calculate the new energy more efficient by accessing the old energy and the information about what the markov step changed

Note

• I assume, that the energy_fn never returns nan (when cast as f64) If nan is possible, please check for that beforhand and return None in that case
• Maybe do the same for infinity, it is unlikely, that infinit energys make sense

pub unsafe fn metropolis_efficient_unsafe<Energy, Mes>(
    &mut self,
    step_target: usize,
    energy_fn: Energy,
    measure: Mes
)where
    Energy: Fn(&mut E, T, &[S]) -> Option<T>,
    Mes: FnMut(&mut Metropolis<E, R, S, Res, T>),

Metropolis Simulation

• see
• performs self.counter..=step_target markov steps
• energy_fn(self.ensemble) is assumed to equal self.energy at the beginning!
• if energy_fn returns None, the step will always be rejected
• after each acceptance/rejection, measure is called

Difference to self.metropolis

• Function parameter of energy_fn: &ensemble, old_energy, &[steps] - that means, you should prefere this, if you can calculate the new energy more efficient by accessing the old energy and the information about what the markov step changed

Safety

• I assume, that the energy_fn never returns nan (when cast as f64) If nan is possible, please check for that beforhand and return None in that case
• Maybe do the same for infinity, it is unlikely, that infinite energys make sense

pub fn metropolis_while<Energy, Mes, Cond>(
    &mut self,
    energy_fn: Energy,
    measure: Mes,
    condition: Cond
)where
    Energy: FnMut(&E) -> Option<T>,
    Mes: FnMut(&Metropolis<E, R, S, Res, T>),
    Cond: FnMut(&Metropolis<E, R, S, Res, T>) -> bool,

Metropolis Simulation

• see
• checks condition(self) after each metropolis_step(&mut energy_fn) and returns when false is returned by the condition
• energy_fn(self.ensemble) is assumed to equal self.energy at the beginning!
• if energy_fn returns None, the step will always be rejected
• after each acceptance/rejection, measure is called

Note

• I assume, that the energy_fn never returns nan (when cast as f64) If nan is possible, please check for that beforhand and return None in that case
• Maybe do the same for infinity, it is unlikely, that infinit energys make sense

pub unsafe fn metropolis_while_unsafe<Energy, Mes, Cond>(
    &mut self,
    energy_fn: Energy,
    measure: Mes,
    condition: Cond
)where
    Energy: FnMut(&mut E) -> Option<T>,
    Mes: FnMut(&mut Metropolis<E, R, S, Res, T>),
    Cond: FnMut(&mut Metropolis<E, R, S, Res, T>) -> bool,

Metropolis simulation

• almost the same as metropolis_while

Difference

• energy_fn now works with a mutable reference of E (the ensemble).

Note

• prefere metropolis_while as it is safer.
• the changeing of the Ensemble must not affect subsequent Energy calculations - otherwise the logic of the algorithm breaks down

Safety

• 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 metropolis_efficient_while<Energy, Mes, Cond>(
    &mut self,
    energy_fn: Energy,
    measure: Mes,
    condition: Cond
)where
    Energy: FnMut(&E, T, &[S]) -> Option<T>,
    Mes: FnMut(&Metropolis<E, R, S, Res, T>),
    Cond: FnMut(&Metropolis<E, R, S, Res, T>) -> bool,

Metropolis simulation

• similar to metropolis_while

Difference

• energy fn can use the old energy and the performed markov steps to more efficiently calculate the current Energy

pub unsafe fn metropolis_efficient_while_unsafe<Energy, Mes, Cond>(
    &mut self,
    energy_fn: Energy,
    measure: Mes,
    condition: Cond
)where
    Energy: FnMut(&mut E, T, &[S]) -> Option<T>,
    Mes: FnMut(&mut Metropolis<E, R, S, Res, T>),
    Cond: FnMut(&mut Metropolis<E, R, S, Res, T>) -> bool,

Metropolis simulation

• similar to metropolis_efficient_while

Difference

• now energy_fn works with a mutable reference of the ensemble instead
• This is intended for usages in which the energy can be calculated much more efficiently using a mutable reference than an immutable one

Safety

• Only use this, if it is absolutly nessessary. The ensemble must not be changed in a way, which affects successive energy calculations (or the markov steps)

Trait Implementations

impl<E, R, S, Res, T> Clone for Metropolis<E, R, S, Res, T>where
    E: Clone,
    R: Clone,
    S: Clone,
    Res: Clone,
    T: Clone,

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'de, E, R, S, Res, T> Deserialize<'de> for Metropolis<E, R, S, Res, T>where
    E: Deserialize<'de>,
    R: Deserialize<'de>,
    S: Deserialize<'de>,
    T: Deserialize<'de>,

fn deserialize<__D>(
    __deserializer: __D
) -> Result<Metropolis<E, R, S, Res, T>, <__D as Deserializer<'de>>::Error>where
    __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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