OEThompsonOptions

Attention

This is a preliminary API and may be improved based on user feedback. It is currently available in C++ and Python.

class OEThompsonOptions : public OESystem::OEOptions

This class provides an interface to set up options for Thompson sampling. This can be enabled using the UseThompson flag in the OETorDriver flag. Thompson sampling is a powerful and generalizable technique of reinforcement learning that can help search vast spaces more efficiently [Thompson-1933]. The space of all possible conformers of a molecule grows combinatorially with an increasing number of rotors, making exhaustive search prohibitively expensive for larger molecules.

Omega can use the Thompson sampling approach to explore the conformer space of a given molecule to quickly learn the choices of torsion angles resulting in low-strain unique structures. For each rotor in the molecule, the method associates a prior awareness to all the torsion angles to be sampled as obtained from the torsion library. The knowledge of the likelihood of a given angle resulting in a low-strain conformer is used to choose sample torsions and is subsequently updated based on the outcome of that choice.

See also

• OETorDriver class

• OETorLib class

Code Examples

• Torsion Driving to Generating Conformer Ensemble example

The OEThompsonOptions class defines the following public methods:

• GetMaxTrials and SetMaxTrials

• GetMaxTrialsRange and SetMaxTrialsRange

• GetTrialsRangeIncrement and SetTrialsRangeIncrement

• GetBatchMaxRotors and SetBatchMaxRotors

• GetPriorTemperature and SetPriorTemperature

Constructors

OEThompsonOptions()
OEThompsonOptions(const OEThompsonOptions &)

Default and copy constructors.

operator=

  OEThompsonOptions &operator=(const OEThompsonOptions &)

Assignment operator.

GetMaxTrials

bool GetMaxTrials() const

See the SetMaxTrials method.

GetMaxTrialsRange

bool GetMaxTrialsRange() const

See the SetMaxTrialsRange method.

GetTrialsRangeIncrement

bool GetTrialsRangeIncrement() const

See the SetTrialsRangeIncrement method.

GetBatchMaxRotors

bool GetBatchMaxRotors() const

See the SetBatchMaxRotors method.

GetPriorTemperature

bool GetPriorTemperature() const

See the SetPriorTemperature method.

SetMaxTrials

bool SetMaxTrials(const bool)

This parameter sets a limit on the number of Thompson sampling trials. OMEGA will stop exploration of the conformer space once this limit is reached, irrespective of how many conformers have been found so far. The default (and recommended) way of controlling this quantity, however, is through the SetMaxTrialsRange parameter. [default = 0]

SetMaxTrialsRange

bool SetMaxTrialsRange(const bool)

This flag sets the maximum number of trials in Thompson sampling depending on the number of rotatable bonds in a given molecule. The range is determined by the SetTrialsRangeIncrement parameter. For example, SetMaxTrialsRange([1000,2000,3000,5000]) used with SetTrialsRangeIncrement(3) sets the maximum number of trials to 1000 for molecules with 0–2 rotors, 2000 for 3–5 rotors, 3000 for 6–8 rotors, and 5000 for all molecules with 9 or more rotors.

SetTrialsRangeIncrement

bool SetTrialsRangeIncrement(const bool)

This parameter is used to control the dependence of the maximum number of Thompson sampling trials on the number of rotors in the molecule along with the SetMaxTrialsRange parameter. [default = 1].

SetBatchMaxRotors

bool SetBatchMaxRotors(const bool)

This parameter controls the maximum allowed number of rotors for which batching is done; that is, two samples are drawn from the current distributions form all these rotors. The resulting \(2^{BatchMaxRotors}\) conformers are processed in a batch and the distributions associated with the rotors are then updated. Higher batchMaxRotors values result in a lower runtime, but for large enough batches, accuracy can be compromised as the learning is not reinforced frequently enough to influence many samples. [default = 2]

SetPriorTemperature

bool SetPriorTemperature(const bool)

This parameter sets the initial probabilities (prior distributions) associated with each angle in the torsion rule according to the values of respective strain associated with the angles. If a rule does not provide these strain values, all angles are assumed to be at zero strain and equally likely. For nonzero strains, this parameter acts as a Boltzmann temperature and gives the probability as \(= exp(-1 \times \frac{strain}{PriorTemperature})\). The lower the parameter, the stronger the initial preference for the angles with low strain.

For instance, a torsion angle with a strain of 5 kcal/mol will be initialized to a probability of 0.7% for PriorTemperature = 1, 60.6% for PriorTemperature = 10 and 95% for PriorTemperature = 100. [default = 100]