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.

class mlcg.nn.prior.Harmonic(statistics, name)

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)

Wrapper class for quickly computing bond priors (order 2 Harmonic priors)

class mlcg.nn.prior.HarmonicAngles(statistics)

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.

class mlcg.nn.prior.Dihedral(statistics, n_degs=6)

Prior that constrains dihedral planar angles using the following energy ansatz:

\[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 4 atoms.

class mlcg.nn.prior.Repulsion(statistics)

1-D power law repulsion prior for feature \(x\) of the form:

\[U_{ \textnormal{Repulsion}}(x) = (\sigma/x)^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.