ensembler.samplers package

Submodules

ensembler.samplers.newtonian module

Module: Sampler

The sampler module is provides methods exploring the potential functions.

Newtonian Integrators

class ensembler.samplers.newtonian.leapFrogIntegrator(dt=0.002)

Bases: ensembler.samplers.newtonian.newtonianSampler

The leapFrogIntegrator is similar to the velocity Verlet method. Leapfrog integration is equivalent to updating positions and velocities at interleaved time points, staggered in such a way that they “leapfrog” over each other.

current_forces: numbers.Number

current_position: numbers.Number

current_velocity: numbers.Number

dt: float

name: str = 'Leap Frog Integrator'

step(system: system) → numbers.Number

This function is performing an integration step in leapFrog fashion.

Parameters

system (systemType) – A system, that should be integrated.

Returns

This Tuple contains the new: (new Position, new Velocity, new Force)

Return type

Tuple[Number, Number, Number]

class ensembler.samplers.newtonian.newtonianSampler(dt=0.002)

Bases: ensembler.samplers._basicSamplers._samplerCls

This class is the parent class for all newtonian samplers. The pre-implemented newtonian type samplers currently comprise the Velocity Verlet, Position Verlet and Leapfrog integrator.

__init__(dt=0.002)

This is the Constructor of the newtonian samplers.

Parameters

dt (Number, optional) – time step of an integration, by default 0.002

current_forces: numbers.Number

current_position: numbers.Number

current_velocity: numbers.Number

dt: float

class ensembler.samplers.newtonian.positionVerletIntegrator(dt=0.002)

Bases: ensembler.samplers.newtonian.newtonianSampler

The position Verlet Integrator has similar properties as the verlocity Verlet Integrator.

Verlet, Loup (1967). “Computer “Experiments” on Classical Fluids. I. Thermodynamical Properties of Lennard−Jones Molecules”. Physical Review. 159 (1): 98–103.

current_forces: numbers.Number

current_position: numbers.Number

current_velocity: numbers.Number

dt: float

name: str = 'Position Verlet Integrator'

step(system: system) → numbers.Number

This function is performing an integration step in Position Verlet fashion.

Parameters

system (systemType) – A system, that should be integrated.

Returns

This Tuple contains the new: (new Position, new Velocity, new Force)

Return type

Tuple[Number, Number, Number]

class ensembler.samplers.newtonian.velocityVerletIntegrator(dt=0.002)

Bases: ensembler.samplers.newtonian.newtonianSampler

The velocity Verlet Integrator is one of the simplest integrators that provides good numerical stability as well as time-reversibility and symplectic properties. It’s local error in position is of order dt^4 and the local error in verlocity is of order dt^2.

Verlet, Loup (1967). “Computer “Experiments” on Classical Fluids. I. Thermodynamical Properties of Lennard−Jones Molecules”. Physical Review. 159 (1): 98–103.

current_forces: numbers.Number

current_position: numbers.Number

current_velocity: numbers.Number

dt: float

name: str = 'Verlocity Verlet Integrator'

step(system: system) → numbers.Number

This function is performing an integration step in Verlocity Verlet fashion.

Parameters

system (systemType) – A system, that should be integrated.

Returns

This Tuple contains the new: (new Position, new Velocity, new Force)

Return type

Tuple[Number, Number, Number]

ensembler.samplers.optimizers module

Module: Sampler

The sampler module is provides methods exploring the potential functions.

Optimization Methods

class ensembler.samplers.optimizers.cg(max_step_size: float = 1, epsilon: float = 1e-20)

Bases: ensembler.samplers.optimizers.conjugate_gradient

epsilon: float

class ensembler.samplers.optimizers.conjugate_gradient(max_step_size: float = 1, epsilon: float = 1e-20)

Bases: ensembler.samplers.optimizers.optimizer

Conjugate gradient is an algorithm for the numerical solution of linear equations and for energy minimization. Linear equations should have a symmetric matrix and be positive-definite.

__init__(max_step_size: float = 1, epsilon: float = 1e-20)

This is the Constructor of the conjugate gradient optimizer

Parameters

• max_step_size (float, optional) – maximal size of an optimization step in any direction, by default 1

• epsilon (float, optional) – Step size(s) to use when the gradient is approximated numerically. Defaults to sqrt(eps), with eps the floating point machine precision. Usually sqrt(eps) is about 1.5e-8., by default 10**-20

epsilon: float

optimize(potential, x0, maximal_iterations=100) → dict

Performs the optimization on the basis of the scipy.optimize.fmin_cg function. Raises custim errors if the optimization was not sucessfull.

Parameters

• potential (potentialType) – Energy potential of the system

• x0 (array) – A user-supplied initial estimate of xopt, the optimal value of x. Usually the starting position

• maximal_iterations (int, optional) – Maximum number of iterations to perform, by default 100

Returns

Dictionary that contains the optimized position (“optimal_position”) with its corresponding potential energy “minimal_potential_energy”, the number of iterations needed to converge “used_iterations” and a list of arrays, containing the results at each iteration “position_trajectory”

Return type

dict

Raises

ValueError – Value Error is raised if the optimization did not converged or if the optimization run into an internal error.

step(system: system) → Tuple[float, None, float]

This function is performing an integration step for optimizing a potential.

NOTE: This is not the optimal way to call scipy optimization, but it works with the interfaces and is useful for theoretical thinking about it. It is not optimal or even efficient here! -> it simulates the optimization process as a stepwise process

Parameters

system (systemType) – This is a system, that should be integrated.

Returns

• Tuple[float, None, float]

• This Tuple contains the new ((new Position, none, new Force))

class ensembler.samplers.optimizers.optimizer

Bases: ensembler.samplers._basicSamplers._samplerCls

This class is the parent class for all optimizers. The pre-implemented optimizers currently comprise the conjugate gradient.

maxStepSize: float

ensembler.samplers.stochastic module

Module: Sampler

The sampler module is provides methods exploring the potential functions.

Stochastic Integrators

class ensembler.samplers.stochastic.langevinIntegrator(dt: float = 0.005, gamma: float = 50, old_position: float = None)

Bases: ensembler.samplers.stochastic.stochasticSampler

This class implements the Position Langevin sampler. In Contrast to the Monte Carlo Methods, Langevin integrators provide information on the kinetics of the system. The Position Langevin Integrator does not calculate velocities. Therefore, the kinetic energy is undefined.

__init__(dt: float = 0.005, gamma: float = 50, old_position: float = None)

This is the Constructor of the Langevin samplers.

Parameters

• dt (Number, optional) – time step of an integration, by default 0.005

• gamma (Number, optional) – Friktion constant of the system, by default 50

• old_position (Iterable[Number, Number] of size nDim, optional) – determines the position at step -1, if not set the system will use the velocity to determine this position

fixedStepSize: numbers.Number

name: str = 'Langevin Integrator'

step(system)

This interface function needs to be implemented for a subclass.

The purpose of this function is to perform one integration step.

Parameters

system (systemType) – A system, that should be integrated.

Returns

This Tuple contains the new: (new Position, new velocity, position Shift/ force)

Return type

Tuple[float, float, float]

update_positon(system)

Integrate step according to Position Langevin BBK samplers Designed after: http://localscf.com/localscf.com/LangevinDynamics.aspx.html

update position

This interface function needs to be implemented for a subclass. The purpose of this function is to perform one integration step.

Parameters

system (systemType) – A system, that should be integrated.

Returns

This Tuple contains the new: (new Position, new velocity=None) for velocity return use langevinVelocityIntegrator

Return type

Tuple[float, None]

class ensembler.samplers.stochastic.langevinVelocityIntegrator(dt: float = 0.005, gamma: float = 50, old_position: float = None)

Bases: ensembler.samplers.stochastic.langevinIntegrator

This class implements the Velocity Langevin sampler. It can provide information on the kinetics of the system. In Contrast to the Position Langevin Integrator, the Velocity Langevin sampler does calculate velocities. Therefore, the kinetic energy is definded. It inherits the function step from the Position Langevin Integrator and overwrites update_position.

fixedStepSize: numbers.Number

name: str = 'Velocity Langevin Integrator'

update_positon(system)

Integrate step according to Velocity Langevin BKK samplers Designed after: http://localscf.com/localscf.com/LangevinDynamics.aspx.html

update position

This interface function needs to be implemented for a subclass. The purpose of this function is to perform one integration step.

Parameters

system (systemType) – A system, that should be integrated.

Returns

This Tuple contains the new: (new Position, new velocity)

returns both velocities and positions at full steps

Return type

Tuple[float, None]

class ensembler.samplers.stochastic.metropolisMonteCarloIntegrator(space_range: tuple = None, step_size_coefficient: numbers.Number = 5, minimal_step_size: float = None, fixed_step_size=None, randomness_increase_factor=1.25, max_iteration_tillAccept: int = 10000)

Bases: ensembler.samplers.stochastic.stochasticSampler

This class is implementing a metropolis monte carlo Integrator. In contrast to the Monte Carlo Integrator, that has completely random steps, this sampler has limitations to the randomness. This limitation is expressed in the Metropolis Criterion and ensures that the microcanonical ensemble is sampled.

There is a standard Metropolis Criterion implemented, but it can also be exchanged with a different one.

Default Metropolis Criterion:

$ decision = (E_{t} < E_{t-1}) || ( rand <= e^{(-1/(R/T*1000))*(E_t-E_{t-1})}$ with:

• $R$ as universal gas constant

The original Metropolis Criterion (Nicholas Metropolis et al.; J. Chem. Phys.; 1953 ;doi: https://doi.org/10.1063/1.1699114):

$ p_A(E_{t}, E_{t-1}, T) = min(1, e^{-1/(k_b*T) * (E_{t} - E_{t-1})}) $ decision: True if( 0.5 < p_A(E_{t}, E_{t-1}, T)) else False with:

• $k_b$ as Boltzmann Constant

__init__(space_range: tuple = None, step_size_coefficient: numbers.Number = 5, minimal_step_size: float = None, fixed_step_size=None, randomness_increase_factor=1.25, max_iteration_tillAccept: int = 10000)

This is the Constructor of the Metropolis-MonteCarlo samplers.

Parameters

• minimal_step_size (Number, optional) – minimal size of an integration step in any direction, by default None

• space_range (Tuple[Number, Number], optional) – maximal and minimal allowed position for after an integration step. If not fullfilled, step is rejected. By default None

• fixed_step_size (Number, optional) – this option restrains each integration step to a certain size in each dimension, by default None

• randomness_increase_factor (int, optional) – arbitrary factor, controlling the amount of randomness(the bigger the more random steps), by default 1

• max_iteration_tillAccept (int, optional) – number, after which a step is accepted, regardless its likelihood (turned off if np.inf). By default None

convergence_limit: int = inf

maxIterationTillAccept: float = inf

metropolis_criterion(ene_new, current_state)

metropolisCriterion

The metropolis criterion decides if a step is accepted.

Parameters

• ene_new (float) – new energy in case the step is accepted

• current_state (stateType) – state of the current step

• Returns boolean – defines if step is accepted or not

• ——-

name: str = 'Metropolis Monte Carlo Integrator'

step(system: system) → Tuple[float, None, float]

This function is performing an Metropolis Monte Carlo integration step.

Parameters

system (systemType) – A system, that should be integrated.

Returns

This Tuple contains the new: (new Position, None, position Shift/ force)

Return type

Tuple[float, None, float]

class ensembler.samplers.stochastic.monteCarloIntegrator(space_range: Tuple[numbers.Number, numbers.Number] = None, step_size_coefficient: numbers.Number = 5, minimal_step_size: numbers.Number = None, fixed_step_size: numbers.Number = None)

Bases: ensembler.samplers.stochastic.stochasticSampler

This class implements the classic Monte Carlo samplers. It chooses its moves purely randomly. Therefore, the distributions generated by this integrator do not resemble the (micro/grand) canonical ensemble. Additionally, no kinetic information can be obtained from Monte Carlo samplers.

__init__(space_range: Tuple[numbers.Number, numbers.Number] = None, step_size_coefficient: numbers.Number = 5, minimal_step_size: numbers.Number = None, fixed_step_size: numbers.Number = None)

This is the Constructor of the MonteCarlo samplers.

Parameters

• space_range (Tuple[Number, Number], optional) – maximal and minimal allowed position for after an integration step. If not fullfilled, step is rejected. By default None

• step_size_coefficient (Number, optional) – gives the range of the random numbers. Default is one and therefore values between 1 and -1 are chosen. (Default: 1)

• minimal_step_size (Number, optional) – minimal size of an integration step in any direction, by default None

• fixed_step_size (Number, optional) – this option restrains each integration step to a certain size in each dimension, by default None

fixedStepSize: numbers.Number

name: str = 'Monte Carlo Integrator'

step(system: system) → Tuple[float, None, float]

This function is performing an integration step in MonteCarlo fashion.

Parameters

system (systemType) – A system, that should be integrated.

Returns

This Tuple contains the new: (new Position, None, position Shift/ force)

Return type

Tuple[float, None, float]

class ensembler.samplers.stochastic.stochasticSampler

Bases: ensembler.samplers._basicSamplers._samplerCls

This class is the parent class for all stochastic samplers. The pre-implemented stochastic type samplers currently comprise various Monte-Carlo and Langevin Methods.

fixedStepSize: numbers.Number

minStepSize: numbers.Number = None

posShift: float = 0

random_shift(nDimensions: int) → Union[float, numpy.array]

randomShift

This function calculates the shift for the current position.

Parameters

nDimensions (int) – gives the dimensionality of the position, defining the ammount of shifts.

Returns

returns the Shifts

Return type

Union[float, List[float]]

resolution: float = 0.01

spaceRange: Tuple[numbers.Number, numbers.Number] = None

step_size_coefficient: numbers.Number = 1

Module contents

A variety of samplers that can be used to explore potential energy function. (e.g. Monte Carlo, Lagevin integrator …)