Base MCRunner

class mcpele.monte_carlo._BaseMCRunner

Bases: mcpele.monte_carlo._monte_carlo_cpp._Cdef_MC

Abstract base class for MC runners, all MC runners should derive from this base class.

Note

The design of this class relies on a number of implementation choices made for the pele::MC cpp class. This is not limiting by any means, developers can easily modify this class to write a base class that uses a different basic MC class. Using the pele::MC class is however recommended.

Warning

the cython wrapper to the pele::MC class demands that the first 4 parameters of all inheriting classes constructors be positional as in the parent class. Hence pay particular attention to the first 4 positional arguments when constructing a MCrunner class! A workaround could be a pure Python class that has a member of type _BaseMCrunner, then what you do with the constructor will not matter as long as the member is constructed correctly

Parameters:

potential : BasePotential

the potential (or cost function) return energy, gradient and hessian information given a set of coordinates

coords : numpy.array

these are the initial coordinates for the system

niter : int

total number of MC iterations to perform

Attributes

potential	(BasePotential) the potential (or cost function) return energy, gradient and hessian information given a set of coordinates
start_coords	(numpy.array) initial coordinates array
temperature	(double) temperature or equivalent control parameter
niter	(int) number of Monte Carlo iteration to perform
ndim	(int) number of degrees of freedom (which is len(coords))
res	(Result container) dictionary-like container for the results

abort()

abort run()

this is done by setting niter to infinity

add_accept_test()

add AcceptTest to MCrunner

order in which multiple accept tests are added matters

Parameters:

test : AcceptTest

class of type AcceptTest, constructed beforehand

add_action()

add Action to MCrunner

order in which multiple actions are added matters

Parameters:

action : Action

class of type Action, constructed beforehand

add_conf_test()

add ConfTest to MCrunner

to be executed before the energy evaluation (potential call). These should be configurational tests that are faster to evaluate than the potential call, so that fast rejections save computational time. The order in which multiple conf tests are added matters.

Parameters:

test : ConfTest

class of type ConfTest, constructed beforehand

add_late_conf_test()

add ConfTest to MCrunner

to be executed after the energy evaluation (potential call). These should be configurational tests that are slower to evaluate than the potential call, so that configurations that have been rejected by the AcceptTest don’t need to be tested in order to save computational time. The order in which multiple conf tests are added matters.

Parameters:

test : ConfTest

class of type ConfTest, constructed beforehand

get_E_rejection_fraction()

get the fraction of steps rejected by accept tests

Returns:

f : double

fraction of steps rejected by the accept tests

get_accepted_fraction()

get the accepted fraction of steps

Returns:

f : double

accepted fraction of steps

get_conf_rejection_fraction()

get the fraction of steps rejected by configuration tests

Returns:

f : double

fraction of steps rejected by the configuration tests

get_config()

Return the coordinates of the current configuration and its associated energy

get_coords()

get the coordinates

Returns:

x : numpy.array

array of coordinates

get_energy()

get the energy

Returns:

energy : double

energy for current coordinates

get_iterations_count()

get the total number of iterations

accumulates the number of iterations for many run() calls

Returns:

n : int

total number of iteration (accumulated over multiple run() calls)

get_neval()

get the total number of energy evaluation (per run)

Returns:

neval : int

total number of energy evaluation accumulated over a single run

get_norm_coords()

get the norm of the coordinates

Returns:

norm : double

norm of coordinates

\[\sqrt{x \cdot x}\]

get_results()

Must return a result object, generally must contain at least final configuration and energy

Returns:

res : Result container

dictionary-like container typically containing coords and energy accessible via:

• res.coords
• res.energy

get_status()

Returns typical information about the status of the Monte Carlo walker

status : Result container

dictionary-like container typically containing coords and energy accessible via:

• status.iteration
• status.acc_frac
• status.conf_reject_frac
• status.E_reject_frac
• status.energy
• status.neval

get_temperature()

get the temperature

Returns:

T : double

temperature or equivalent control parameter

one_iteration()

perform a single iteration of the MC loop

reset_energy()

recomputes and resets the energy of the system

run()

perform niter iterations of the MC loop

set_config()

sets current configuration and its energy

Parameters:

coords : numpy.array

these are the initial coordinates for the system

energy : double

energy of coords

set_control()

sets the temperature or whichever control parameter that takes the role of the temperature, such as the stifness of an harmonic sprint to which the system is coupled. This abstract method must be overwritten in any derived class.

set_coordinates()

set the coordinates

Parameters:

coords : numpy.array

coordinates of the system

energy: double

associated energy with coords

set_report_steps()

set number of steps for which the MC loop should report to :class`TakeStep`

Parameters:

steps : int

number of steps out of niter_count, which is the total count of the MCrunner which accumulates the number of iterations for many run() calls

set_takestep()

add TakeStep to MCrunner

Multiple takestep should be combined using the appropriate classes designed to combined them, such as TakeStepPattern and TakeStepProbabilities

Parameters:

test : TakeStep

class of type TakeStep, constructed beforehand

set_temperature()

set the temperature

Parameters:

T : double

temperature or equivalent control parameter