ufjc.monte_carlo

A module for the Metropolis-Hastings Markov chain Monte Carlo method.

This module consist of the class MHMCMC which contains attributes and methods that allow single-chain quantities to be computed using the Metropolis-Hastings Markov chain Monte Carlo method.

Example

Import and instantiate the class with a single-chain model:

>>> from ufjc import uFJC
>>> from ufjc.monte_carlo import MHMCMC
>>> class_instance = MHMCMC(uFJC())
class MHMCMC(single_chain_model)[source]

Bases: BasicUtility

The Metropolis-Hastings Markov chain Monte Carlo class.

This class contains attributes and methods used to compute statistical thermodynamic quantities using the Metropolis-Hastings Markov chain Monte Carlo method [1] for a given single-chain model.

N_b

The number of chain links. Inherited from single_chain_model.

beta_U_config

The configurational potential energy. Inherited from single_chain_model.

beta_Pi_config

The configurational total potential energy. Inherited from single_chain_model.

init_config

The default initial configuration. Inherited from single_chain_model.

burn_in(init_config, **kwargs)[source]

Burn-in (throw away samples) until in the effective sampling region.

This function runs a Monte Carlo calculation without utilizing samples, instead throwing them away until a desired number have been thrown away or a desired tolerance has been reached. This is typically done to obtain a burned-in configuration to use as the initial configuration for an actual Monte Carlo calculation.

Parameters:

  • init_config (numpy.ndarray) – The initial configuration.

  • **kwargs – Arbitrary keyword arguments. Passed to mh_next_config_append.

Returns:

The final, burned-in configuration.

Return type:

numpy.ndarray

gamma_isotensional_MHMCMC(eta, **kwargs)[source]

Parallel Monte Carlo calculation function for the isotensional \(\gamma(\eta)\).

Given a nondimensional force, this function computes the nondimensional end-to-end length using the average of several Monte Carlo calculations run in parallel. Given multiple nondimensional forces, this function does the above in serial for each nondimensional force.

Parameters:

  • eta (array_like) – The nondimensional force(s).

  • **kwargs – Arbitrary keyword arguments. Passed to parallel_calculation.

Returns:

The nondimensional end-to-end length(s).

Return type:

numpy.ndarray

Example

Calculate the nondimensional end-to-end length under a nondimensional force of 23 and ensure that it is within one percent of the exact result:

>>> from ufjc import uFJC
>>> from ufjc.monte_carlo import MHMCMC
>>> gamma_MHMCMC = MHMCMC(uFJC()).gamma_isotensional_MHMCMC(23)
>>> gamma_exact = uFJC().gamma(23, approach='exact')
>>> np.abs(gamma_exact - gamma_MHMCMC)/gamma_exact < 1e-2
array([ True])
gamma_isotensional_MHMCMC_serial(config, **kwargs)[source]

Serial Monte Carlo calculation function for the isotensional \(\gamma(\eta)\).

This function computes the nondimensional end-to-end length using a Monte Carlo calculation given an initial configuration.

Parameters:

  • config (numpy.ndarray) – The initial configuration, typically already burned-in.

  • **kwargs – Arbitrary keyword arguments. Passed to mh_next_config.

Returns:

The nondimensional end-to-end length.

Return type:

float

Example

Calculate the nondimensional end-to-end length under a nondimensional force of 23 and ensure that it is within one percent of the exact result:

>>> import numpy as np
>>> from ufjc import uFJC
>>> from ufjc.monte_carlo import MHMCMC
>>> gamma_MHMCMC = MHMCMC(uFJC()). \
...     gamma_isotensional_MHMCMC(23, num_processes=1)
>>> gamma_exact = uFJC().gamma(23, approach='exact')
>>> np.abs(gamma_exact - gamma_MHMCMC)/gamma_exact < 1e-2
array([ True])
mh_next_config(prev_config, **kwargs)[source]

Generates accepted configurations given a previous configuration.

This function returns an accepted configuration given a previous configuration. Trial configurations are generated and repeatedly rejected until accepted as the next configuration based on the Metropolis-Hastings algorithm.

Parameters:

  • prev_config (numpy.ndarray) – The previous configuration.

  • **kwargs – Arbitrary keyword arguments. Passed to trial_config.

Returns:

The accepted (next) configuration.

Return type:

numpy.ndarray

mh_next_config_append(prev_configs, **kwargs)[source]

Append next configuration onto a history of previous configurations.

This function calls mh_next_config and appends the resulting next configuration onto a given history of previous configurations.

Parameters:

  • prev_configs (numpy.ndarray) – The previous history of configurations.

  • **kwargs – Arbitrary keyword arguments. Passed to mh_next_config.

Returns:

The updated history of configurations.

Return type:

numpy.ndarray

parallel_calculation(serial_fun, **kwargs)[source]

Monte Carlo calculation averaged over several parallel processes.

This function performs several Monte Carlo calculations in parallel and returns the average result from all processes. Each Monte Carlo calculation is performed using serial_fun. The default is to utilize all available processors.

Parameters:

  • serial_fun (function) – The function for a single Monte Carlo calculation.

  • **kwargs – Arbitrary keyword arguments. Passed to serial_fun.

Returns:

The process-averaged result.

Return type:

float

Note

To avoid issues with multiprocessing and MacOS/Windows, num_processes is set to 1 for anything but Linux.

trial_config(prev_config, **kwargs)[source]

Generates trial configurations given a previous configuration.

This function returns a trial configuration given a previous starting configuration. The possibility of rigid-body translation is prevented by fixing the first coordinate at the origin. In the isometric ensemble, the last coordinate is left unchanged in order to keep the end-to-end vector fixed.

Parameters:

  • prev_config (numpy.ndarray) – The previous configuration.

  • **kwargs – Arbitrary keyword arguments.

Returns:

The generated trial configuration.

Return type:

numpy.ndarray

Example

Generate a trial configuration in the isometric ensemble and ensure that the end-to-end remains unchanged:

>>> from ufjc import uFJC
>>> from ufjc.monte_carlo import MHMCMC
>>> model = uFJC(N_b=8)
>>> prev_config = model.init_config
>>> trial_config = MHMCMC(model).trial_config(prev_config,
...     ensemble='isometric')
>>> (prev_config == trial_config)[(0,-1),:]
array([[ True,  True,  True],
       [ True,  True,  True]])

References

[1]

James M Haile. Molecular Dynamics Simulation: Elementary Methods. Wiley, 1992. URL: https://www.wiley.com/Molecular+Dynamics+Simulation:+Elementary+Methods-p-9780471184393.