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.

Constructors¶

OEThompsonOptions()
OEThompsonOptions(const OEThompsonOptions &)

Default and copy constructors.

operator=¶

OEThompsonOptions &operator=(const OEThompsonOptions &)

Assignment operator.

GetMaxTrials¶

unsigned int GetMaxTrials() const

See the SetMaxTrials method.

GetMaxTrialsRange¶

std::vector<unsigned int> GetMaxTrialsRange() const

See the SetMaxTrialsRange method.

GetTrialsRangeIncrement¶

unsigned int GetTrialsRangeIncrement() const

See the SetTrialsRangeIncrement method.

GetBatchMaxRotors¶

unsigned int GetBatchMaxRotors() const

See the SetBatchMaxRotors method.

GetPriorTemperature¶

double GetPriorTemperature() const

See the SetPriorTemperature method.

SetMaxTrials¶

bool SetMaxTrials(const unsigned int)

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 std::vector<unsigned>&)

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 unsigned int)

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 unsigned int)

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 double)

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]