# Energy Parameters

For secondary structure free energy evaluation we usually utilize the set of thermodynamic Nearest Neighbor energy parameters also used in other software, such as UNAfold and RNAstructure.

Specialized Modules:

- Salt Corrections
- Loading / Saving Energy Parameter Sets
- Converting Energy Parameter Files

## Available Parameter Sets

While the RNAlib already contains a compiled-in set of the latest Turner 2004 Free Energy Parameters, we defined a file format that allows to change these parameters at runtime. The ViennaRNA Package already comes with a set of parameter files containing

- Turner 1999 RNA parameters

- Mathews 1999 DNA parameters

- Andronescu 2007 RNA parameters

- Mathews 2004 DNA parameters

## Energy Parameter API

  Defines

  VRNA_GQUAD_MAX_STACK_SIZE
    #include <ViennaRNA/params/basic.h>
  VRNA_GQUAD_MIN_STACK_SIZE
    #include <ViennaRNA/params/basic.h>
  VRNA_GQUAD_MAX_LINKER_LENGTH
    #include <ViennaRNA/params/basic.h>
  VRNA_GQUAD_MIN_LINKER_LENGTH
    #include <ViennaRNA/params/basic.h>
  VRNA_GQUAD_MIN_BOX_SIZE
    #include <ViennaRNA/params/basic.h>
  VRNA_GQUAD_MAX_BOX_SIZE
    #include <ViennaRNA/params/basic.h>

  Typedefs

  typedef struct vrna_param_s vrna_param_t
    #include <ViennaRNA/params/basic.h>

    Typename for the free energy parameter data structure vrna_params.

  typedef struct vrna_exp_param_s vrna_exp_param_t
    #include <ViennaRNA/params/basic.h>

    Typename for the Boltzmann factor data structure vrna_exp_params.

  typedef struct vrna_param_s paramT
    #include <ViennaRNA/params/basic.h>

    Old typename of vrna_param_s.

    Deprecated:

      Use vrna_param_t instead!

  typedef struct vrna_exp_param_s pf_paramT
    #include <ViennaRNA/params/basic.h>

    Old typename of vrna_exp_param_s.

    Deprecated:

      Use vrna_exp_param_t instead!

  Functions

  vrna_param_t *vrna_params(vrna_md_t *md)
    #include <ViennaRNA/params/basic.h>

    Get a data structure containing prescaled free energy parameters.

    If a NULL pointer is passed for the model details parameter, the default model parameters are stored within the requested vrna_param_t structure.

    See also

    vrna_md_t, vrna_md_set_default(), vrna_exp_params()

    Parameters:

      - md – A pointer to the model details to store inside the structure (Maybe NULL)

    Returns:

      A pointer to the memory location where the requested parameters are stored

  vrna_param_t *vrna_params_copy(vrna_param_t *par)
    #include <ViennaRNA/params/basic.h>

    Get a copy of the provided free energy parameters.

    If NULL is passed as parameter, a default set of energy parameters is created and returned.

    See also

    vrna_params(), vrna_param_t

    Parameters:

      - par – The free energy parameters that are to be copied (Maybe NULL)

    Returns:

      A copy or a default set of the (provided) parameters

  vrna_exp_param_t *vrna_exp_params(vrna_md_t *md)
    #include <ViennaRNA/params/basic.h>

    Get a data structure containing prescaled free energy parameters already transformed to Boltzmann factors.

    This function returns a data structure that contains all necessary precomputed energy contributions for each type of loop.

    In contrast to vrna_params(), the free energies within this data structure are stored as their Boltzmann factors, i.e.

    \( exp(-E / kT) \)

    where \( E \) is the free energy.

    If a NULL pointer is passed for the model details parameter, the default model parameters are stored within the requested vrna_exp_param_t structure.

    See also

    vrna_md_t, vrna_md_set_default(), vrna_params(), vrna_rescale_pf_params()

    Parameters:

      - md – A pointer to the model details to store inside the structure (Maybe NULL)

    Returns:

      A pointer to the memory location where the requested parameters are stored

  vrna_exp_param_t *vrna_exp_params_comparative(unsigned int n_seq, vrna_md_t *md)
    #include <ViennaRNA/params/basic.h>

    Get a data structure containing prescaled free energy parameters already transformed to Boltzmann factors (alifold version)

    If a NULL pointer is passed for the model details parameter, the default model parameters are stored within the requested vrna_exp_param_t structure.

    See also

    vrna_md_t, vrna_md_set_default(), vrna_exp_params(), vrna_params()

    Parameters:

      - n_seq – The number of sequences in the alignment

      - md – A pointer to the model details to store inside the structure (Maybe NULL)

    Returns:

      A pointer to the memory location where the requested parameters are stored

  vrna_exp_param_t *vrna_exp_params_copy(vrna_exp_param_t *par)
    #include <ViennaRNA/params/basic.h>

    Get a copy of the provided free energy parameters (provided as Boltzmann factors)

    If NULL is passed as parameter, a default set of energy parameters is created and returned.

    See also

    vrna_exp_params(), vrna_exp_param_t

    Parameters:

      - par – The free energy parameters that are to be copied (Maybe NULL)

    Returns:

      A copy or a default set of the (provided) parameters

  void vrna_params_subst(vrna_fold_compound_t *fc, vrna_param_t *par)
    #include <ViennaRNA/params/basic.h>

    Update/Reset energy parameters data structure within a vrna_fold_compound_t.

    Passing NULL as second argument leads to a reset of the energy parameters within fc to their default values. Otherwise, the energy parameters provided will be copied over into fc.

    SWIG Wrapper Notes:

      This function is attached to vrna_fc_s objects as overloaded `params_subst()` method.

      When no parameter is passed, the resulting action is the same as passing `NULL` as second parameter to vrna_params_subst(), i.e. resetting the parameters to the global defaults. See, e.g. `RNA.fold_compound.params_subst()` in the Python API.

    See also

    vrna_params_reset(), vrna_param_t, vrna_md_t, vrna_params()

    Parameters:

      - fc – The vrna_fold_compound_t that is about to receive updated energy parameters

      - par – The energy parameters used to substitute those within fc (Maybe NULL)

  void vrna_exp_params_subst(vrna_fold_compound_t *fc, vrna_exp_param_t *params)
    #include <ViennaRNA/params/basic.h>

    Update the energy parameters for subsequent partition function computations.

    This function can be used to properly assign new energy parameters for partition function computations to a vrna_fold_compound_t. For this purpose, the data of the provided pointer `params` will be copied into `fc` and a recomputation of the partition function scaling factor is issued, if the `pf_scale` attribute of `params` is less than `1.0`.

    Passing NULL as second argument leads to a reset of the energy parameters within fc to their default values

    SWIG Wrapper Notes:

      This function is attached to vrna_fc_s objects as overloaded `exp_params_subst()` method.

      When no parameter is passed, the resulting action is the same as passing `NULL` as second parameter to vrna_exp_params_subst(), i.e. resetting the parameters to the global defaults. See, e.g. `RNA.fold_compound.exp_params_subst()` in the Python API.

    See also

    vrna_exp_params_reset(), vrna_exp_params_rescale(), vrna_exp_param_t, vrna_md_t, vrna_exp_params()

    Parameters:

      - fc – The fold compound data structure

      - params – A pointer to the new energy parameters

  void vrna_exp_params_rescale(vrna_fold_compound_t *fc, double *mfe)
    #include <ViennaRNA/params/basic.h>

    Rescale Boltzmann factors for partition function computations.

    This function may be used to (automatically) rescale the Boltzmann factors used in partition function computations. Since partition functions over subsequences can easily become extremely large, the RNAlib internally rescales them to avoid numerical over- and/or underflow. Therefore, a proper scaling factor \(s\) needs to be chosen that in turn is then used to normalize the corresponding partition functions \(\hat{q}[i,j] = q[i,j] / s^{(j-i+1)}\).

    This function provides two ways to automatically adjust the scaling factor.

    1. Automatic guess

    2. Automatic adjustment according to MFE

    Passing `NULL` as second parameter activates the automatic guess mode. Here, the scaling factor is recomputed according to a mean free energy of `184.3*length`

    cal for random sequences.

    On the other hand, if the MFE for a sequence is known, it can be used to recompute a more robust scaling factor, since it represents the lowest free energy of the entire ensemble of structures, i.e. the highest Boltzmann factor. To activate this second mode of

    automatic adjustment according to MFE, a pointer to the MFE value needs to be passed as second argument. This value is then taken to compute the scaling factor as \( s = exp((sfact * MFE) / kT / length )\), where sfact is an additional scaling weight located in the vrna_md_t data structure of `exp_params` in `fc`.

    The computed scaling factor \(s\) will be stored as `pf_scale` attribute of the `exp_params` data structure in `fc`.

    SWIG Wrapper Notes:

      This function is attached to vrna_fc_s objects as overloaded `exp_params_rescale()` method.

      When no parameter is passed to this method, the resulting action is the same as passing `NULL` as second parameter to vrna_exp_params_rescale(), i.e. default scaling of the partition function. Passing an energy in kcal/mol, e.g. as retrieved by a previous call to the `mfe()` method, instructs all subsequent calls to scale the partition function accordingly. See, e.g. `RNA.fold_compound.exp_params_rescale()` in the Python API.

    See also

    vrna_exp_params_subst(), vrna_md_t, vrna_exp_param_t, vrna_fold_compound_t

    Note

    This recomputation only takes place if the `pf_scale` attribute of the `exp_params` data structure contained in `fc` has a value below `1.0`.

    Parameters:

      - fc – The fold compound data structure

      - mfe – A pointer to the MFE (in kcal/mol) or NULL

  void vrna_params_reset(vrna_fold_compound_t *fc, vrna_md_t *md)
    #include <ViennaRNA/params/basic.h>

    Reset free energy parameters within a vrna_fold_compound_t according to provided, or default model details.

    This function allows one to rescale free energy parameters for subsequent structure prediction or evaluation according to a set of model details, e.g. temperature values. To do so, the caller provides either a pointer to a set of model details to be used for rescaling, or NULL if global default setting should be used.

    SWIG Wrapper Notes:

      This function is attached to vrna_fc_s objects as overloaded `params_reset()` method.

      When no parameter is passed to this method, the resulting action is the same as passing `NULL` as second parameter to vrna_params_reset(), i.e. global default model settings are used. Passing an object of type vrna_md_s resets the fold compound according to the specifications stored within the vrna_md_s object. See, e.g. `RNA.fold_compound.params_reset()` in the Python API.

    See also

    vrna_exp_params_reset(), vrna_params_subs()

    Parameters:

      - fc – The fold compound data structure

      - md – A pointer to the new model details (or NULL for reset to defaults)

  void vrna_exp_params_reset(vrna_fold_compound_t *fc, vrna_md_t *md)
    #include <ViennaRNA/params/basic.h>

    Reset Boltzmann factors for partition function computations within a vrna_fold_compound_t according to provided, or default model details.

    This function allows one to rescale Boltzmann factors for subsequent partition function computations according to a set of model details, e.g. temperature values. To do so, the caller provides either a pointer to a set of model details to be used for rescaling, or NULL if global default setting should be used.

    SWIG Wrapper Notes:

      This function is attached to vrna_fc_s objects as overloaded `exp_params_reset()` method.

      When no parameter is passed to this method, the resulting action is the same as passing `NULL` as second parameter to vrna_exp_params_reset(), i.e. global default model settings are used. Passing an object of type vrna_md_s resets the fold compound according to the specifications stored within the vrna_md_s object. See, e.g. `RNA.fold_compound.exp_params_reset()` in the Python API.

    See also

    vrna_params_reset(), vrna_exp_params_subst(), vrna_exp_params_rescale()

    Parameters:

      - fc – The fold compound data structure

      - md – A pointer to the new model details (or NULL for reset to defaults)

  void vrna_params_prepare(vrna_fold_compound_t *fc, unsigned int options)
    #include <ViennaRNA/params/basic.h>
  vrna_param_t *get_parameter_copy(vrna_param_t *par)
    #include <ViennaRNA/params/basic.h>
  vrna_exp_param_t *get_scaled_pf_parameters(void)
    #include <ViennaRNA/params/basic.h>

    get a data structure of type vrna_exp_param_t which contains the Boltzmann weights of several energy parameters scaled according to the current temperature

    Deprecated:

      Use vrna_exp_params() instead!

    Returns:

      The data structure containing Boltzmann weights for use in partition function calculations

  vrna_exp_param_t *get_boltzmann_factors(double temperature, double betaScale, vrna_md_t md, double pf_scale)
    #include <ViennaRNA/params/basic.h>

    Get precomputed Boltzmann factors of the loop type dependent energy contributions with independent thermodynamic temperature.

    This function returns a data structure that contains all necessary precalculated Boltzmann factors for each loop type contribution.

    In contrast to

    get_scaled_pf_parameters(), this function enables setting of independent temperatures for both, the individual energy contributions as well as the thermodynamic temperature used in \( exp(-\Delta G / kT) \)

    Deprecated:

      Use vrna_exp_params() instead!

    See also

    get_scaled_pf_parameters(), get_boltzmann_factor_copy()

    Parameters:

      - temperature – The temperature in degrees Celcius used for (re-)scaling the energy contributions

      - betaScale – A scaling value that is used as a multiplication factor for the absolute temperature of the system

      - md – The model details to be used

      - pf_scale – The scaling factor for the Boltzmann factors

    Returns:

      A set of precomputed Boltzmann factors

  vrna_exp_param_t *get_boltzmann_factor_copy(vrna_exp_param_t *parameters)
    #include <ViennaRNA/params/basic.h>

    Get a copy of already precomputed Boltzmann factors.

    Deprecated:

      Use vrna_exp_params_copy() instead!

    See also

    get_boltzmann_factors(), get_scaled_pf_parameters()

    Parameters:

      - parameters – The input data structure that shall be copied

    Returns:

      A copy of the provided Boltzmann factor data set

  vrna_exp_param_t *get_scaled_alipf_parameters(unsigned int n_seq)
    #include <ViennaRNA/params/basic.h>

    Get precomputed Boltzmann factors of the loop type dependent energy contributions (alifold variant)

    Deprecated:

      Use vrna_exp_params_comparative() instead!

  vrna_exp_param_t *get_boltzmann_factors_ali(unsigned int n_seq, double temperature, double betaScale, vrna_md_t md, double pf_scale)
    #include <ViennaRNA/params/basic.h>

    Get precomputed Boltzmann factors of the loop type dependent energy contributions (alifold variant) with independent thermodynamic temperature.

    Deprecated:

      Use vrna_exp_params_comparative() instead!

  vrna_param_t *scale_parameters(void)
    #include <ViennaRNA/params/basic.h>

    Get precomputed energy contributions for all the known loop types.

    Deprecated:

      Use vrna_params() instead!

    Note

    OpenMP: This function relies on several global model settings variables and thus is not to be considered threadsafe. See get_scaled_parameters() for a completely threadsafe implementation.

    Returns:

      A set of precomputed energy contributions

  vrna_param_t *get_scaled_parameters(double temperature, vrna_md_t md)
    #include <ViennaRNA/params/basic.h>

    Get precomputed energy contributions for all the known loop types.

    Call this function to retrieve precomputed energy contributions, i.e. scaled according to the temperature passed. Furthermore, this function assumes a data structure that contains the model details as well, such that subsequent folding recursions are able to retrieve the correct model settings

    Deprecated:

      Use vrna_params() instead!

    See also

    vrna_md_t, set_model_details()

    Parameters:

      - temperature – The temperature in degrees Celcius

      - md – The model details

    Returns:

      precomputed energy contributions and model settings

  vrna_param_t *copy_parameters(void)
    #include <ViennaRNA/params/basic.h>
  vrna_param_t *set_parameters(vrna_param_t *dest)
    #include <ViennaRNA/params/basic.h>
  vrna_exp_param_t *scale_pf_parameters(void)
    #include <ViennaRNA/params/basic.h>
  vrna_exp_param_t *copy_pf_param(void)
    #include <ViennaRNA/params/basic.h>
  vrna_exp_param_t *set_pf_param(vrna_param_t *dest)
    #include <ViennaRNA/params/basic.h>
  struct vrna_param_s
    #include <ViennaRNA/params/basic.h>

    The datastructure that contains temperature scaled energy parameters.

    Public Members

    int id
    int stack[NBPAIRS + 1][NBPAIRS + 1]
    int hairpin[31]
    int bulge[MAXLOOP + 1]
    int internal_loop[MAXLOOP + 1]
    int mismatchExt[NBPAIRS + 1][5][5]
    int mismatchI[NBPAIRS + 1][5][5]
    int mismatch1nI[NBPAIRS + 1][5][5]
    int mismatch23I[NBPAIRS + 1][5][5]
    int mismatchH[NBPAIRS + 1][5][5]
    int mismatchM[NBPAIRS + 1][5][5]
    int dangle5[NBPAIRS + 1][5]
    int dangle3[NBPAIRS + 1][5]
    int int11[NBPAIRS + 1][NBPAIRS + 1][5][5]
    int int21[NBPAIRS + 1][NBPAIRS + 1][5][5][5]
    int int22[NBPAIRS + 1][NBPAIRS + 1][5][5][5][5]
    int ninio[5]
    double lxc
    int MLbase
    int MLintern[NBPAIRS + 1]
    int MLclosing
    int TerminalAU
    int DuplexInit
    int Tetraloop_E[200]
    char Tetraloops[1401]
    int Triloop_E[40]
    char Triloops[241]
    int Hexaloop_E[40]
    char Hexaloops[1801]
    int TripleC
    int MultipleCA
    int MultipleCB
    int gquad[VRNA_GQUAD_MAX_STACK_SIZE + 1][3 * VRNA_GQUAD_MAX_LINKER_LENGTH + 1]
    int gquadLayerMismatch
    int gquadLayerMismatchMax
    double temperature

      Temperature used for loop contribution scaling.

    vrna_md_t model_details

      Model details to be used in the recursions.

    char param_file[256]

      The filename the parameters were derived from, or empty string if they represent the default.

    int SaltStack
    int SaltLoop[MAXLOOP + 2]
    double SaltLoopDbl[MAXLOOP + 2]
    int SaltMLbase
    int SaltMLintern
    int SaltMLclosing
    int SaltDPXInit
  struct vrna_exp_param_s
    #include <ViennaRNA/params/basic.h>

    The data structure that contains temperature scaled Boltzmann weights of the energy parameters.

    Public Members

    int id

      An identifier for the data structure.

      Deprecated:

        This attribute will be removed in version 3

    double expstack[NBPAIRS + 1][NBPAIRS + 1]
    double exphairpin[31]
    double expbulge[MAXLOOP + 1]
    double expinternal[MAXLOOP + 1]
    double expmismatchExt[NBPAIRS + 1][5][5]
    double expmismatchI[NBPAIRS + 1][5][5]
    double expmismatch23I[NBPAIRS + 1][5][5]
    double expmismatch1nI[NBPAIRS + 1][5][5]
    double expmismatchH[NBPAIRS + 1][5][5]
    double expmismatchM[NBPAIRS + 1][5][5]
    double expdangle5[NBPAIRS + 1][5]
    double expdangle3[NBPAIRS + 1][5]
    double expint11[NBPAIRS + 1][NBPAIRS + 1][5][5]
    double expint21[NBPAIRS + 1][NBPAIRS + 1][5][5][5]
    double expint22[NBPAIRS + 1][NBPAIRS + 1][5][5][5][5]
    double expninio[5][MAXLOOP + 1]
    double lxc
    double expMLbase
    double expMLintern[NBPAIRS + 1]
    double expMLclosing
    double expTermAU
    double expDuplexInit
    double exptetra[40]
    double exptri[40]
    double exphex[40]
    char Tetraloops[1401]
    double expTriloop[40]
    char Triloops[241]
    char Hexaloops[1801]
    double expTripleC
    double expMultipleCA
    double expMultipleCB
    double expgquad[VRNA_GQUAD_MAX_STACK_SIZE + 1][3 * VRNA_GQUAD_MAX_LINKER_LENGTH + 1]
    double expgquadLayerMismatch
    int gquadLayerMismatchMax
    double kT
    double pf_scale

      Scaling factor to avoid over-/underflows.

    double temperature

      Temperature used for loop contribution scaling.

    double alpha

      Scaling factor for the thermodynamic temperature.

      This allows for temperature scaling in Boltzmann factors independently from the energy contributions. The resulting Boltzmann factors are then computed by \( e^{-E/(\alpha \cdot K \cdot T)} \)

    vrna_md_t model_details

      Model details to be used in the recursions.

    char param_file[256]

      The filename the parameters were derived from, or empty string if they represent the default.

    double expSaltStack
    double expSaltLoop[MAXLOOP + 2]
    double SaltLoopDbl[MAXLOOP + 2]
    int SaltMLbase
    int SaltMLintern
    int SaltMLclosing
    int SaltDPXInit