Priors¶

mlcg.nn implements prior models that are important physical baselines imposing geometrical constraints on coarse-grained systems. These prior models can be supplied with a user-defined set of interaction parameters, or they can alternatively be parametrized directly from data for multiple interacting atom types.

These classes define several common molecular interactions. Because each prior subclasses torch.nn.Module, they can be treated as normal property predictors.

Harmonic¶

class mlcg.nn.prior.Harmonic(statistics, name, order)[source]¶

1-D Harmonic prior interaction for feature $x$ of the form:

\[U_{\text{Harmonic}}(x) = k\left( x - x_0 \right)^2\]

where $k$ is a harmonic/spring constant describing the interaction strength and $x_0$ is the equilibrium value of the feature $x$. A an optimizable constant energy offset is added during the prior parameter fitting.

Parameters:

statistics (Dict) –

Dictionary of interaction parameters for each type of atom pair/triple, where the keys are tuples of interacting bead types and the corresponding values define the interaction parameters. These Can be hand-designed or taken from the output of mlcg.geometry.statistics.compute_statistics, but must minimally contain the following information for each key:

tuple(*specific_types) : {
    "k" : #torch.Tensor scalar that describes the strength of the
        #harmonic interaction.
    "x_0" : #torch.Tensor scalar that describes the mean feature
        #value.
    ...

    }

The keys can be tuples of 2 or 3 atom type integers.

class mlcg.nn.prior.HarmonicBonds(statistics)[source]¶: Wrapper class for quickly computing bond priors (order 2 Harmonic priors)

class mlcg.nn.prior.HarmonicAngles(statistics)[source]¶

Wrapper class for quickly computing angle priors (order 3 Harmonic priors)

To avoid numerical instabilities, we use a functional form of the following way:

\[U_{\text{HarmonicAngles}}(\theta) = k\left( \cos{(\theta)} - \cos{(\theta_0)} \right)^2\]

where $\theta_0$ is the value of the angle at equilibrium.

Polynomial¶

class mlcg.nn.prior.Polynomial(statistics, name, order=None, n_degs=4)[source]¶

Prior representing a polynomial with the following energy ansatz:

\[V(x) = V_0 + \sum_{n=1}^{n_{deg}} k_n x^n\]

Parameters:

statistics (dict) –

Dictionary of interaction parameters for each type of atom combination, where the keys are tuples of interacting bead types and the corresponding values define the interaction parameters. These Can be hand-designed or taken from the output of mlcg.geometry.statistics.compute_statistics, but must minimally contain the following information for each key:

tuple(*specific_types) : {
    "ks" : ,#torch.Tensor that contains all k_1,..,k_{n_degs} coefficients
    "v_0" : ,#torch.Tensor that contains the constant offset
    ...
    }

The keys must be tuples of 2,3,4 atoms.

Fourier Series¶

class mlcg.nn.prior.FourierSeries(statistics, name='', n_degs=6, order=4)[source]¶

Prior class representing a fourier series of a periodic variable $theta$. The energy computed is given by the follwoing function

\[V(\theta) = v_0 + \sum_{n=1}^{n_{deg}} k1_n \sin{(n\theta)} + k2_n\cos{(n\theta)}\]

where $n_{deg}$ is the maximum number of terms to take in the sinusoidal series, $v_0$ is a constant offset, and $k1_n$ and $k2_n$ are coefficients for each term number $n$.

Parameters:

statistics (Dict) –

Dictionary of interaction parameters for each type of atom quadruple, where the keys are tuples of interacting bead types and the corresponding values define the interaction parameters. These Can be hand-designed or taken from the output of mlcg.geometry.statistics.compute_statistics, but must minimally contain the following information for each key:

tuple(*specific_types) : {
    "k1s" : #torch.Tensor that contains all k1 coefficients
    "k2s" : #torch.Tensor that contains all k2 coefficients
    "v_0" : #torch.Tensor that contains the constant offset
    ...
    }

The keys must be tuples of order atoms.

class mlcg.nn.prior.Dihedral(statistics, n_degs=3, name='dihedrals')[source]¶: Class to represent a Dihedral potential using a fourier series

Excluded volume¶

class mlcg.nn.prior.Repulsion(statistics)[source]¶

1-D power law repulsion prior for feature $x$ of the form:

\[U_{ \textnormal{Repulsion}}(x) = \left(\frac{\sigma}{x}\right)^6\]

where $\sigma$ is the excluded volume.

Parameters:

statistics (Dict) –

Dictionary of interaction parameters for each type of atom pair, where the keys are tuples of interacting bead types and the corresponding values define the interaction parameters. These Can be hand-designed or taken from the output of mlcg.geometry.statistics.compute_statistics, but must minimally contain the following information for each key:

tuple(*specific_types) : {
    "sigma" : #torch.Tensor scalar that describes the excluded
        #volume of the two interacting atoms.
    ...

    }

The keys can be tuples of 2 integer atom types.