# Energy Evaluation for Individual Loops

To assess the free energy contribution of a particular loop \(L\) within a secondary structure, two variants are provided

- The bare free energy \(E_L\) (usually in units of deka-calories, i.e. multiples of \(10 \text{cal} \cdot \text{mol}^{-1}\), and

- The Boltzmann weight \(q = exp(-\beta E_L)\) of the free energy \(E_L\) (with \(\beta = \frac{1}{RT}\), gas constant \(R\) and temperature \(T\))

The latter is usually required for partition function computations.

## General

  Functions to evaluate the free energy of particular types of loops.

  Functions

  int vrna_eval_loop_pt(vrna_fold_compound_t *fc, int i, const short *pt)
    #include <ViennaRNA/eval.h>

    Calculate energy of a loop.

    SWIG Wrapper Notes:

      This function is attached as method `eval_loop_pt()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.eval_loop_pt()` in the Python API .

    Parameters:

      - fc – A vrna_fold_compound_t containing the energy parameters and model details

      - i – position of covering base pair

      - pt – the pair table of the secondary structure

    Returns:

      free energy of the loop in 10cal/mol

  int vrna_eval_loop_pt_v(vrna_fold_compound_t *fc, int i, const short *pt, int verbosity_level)
    #include <ViennaRNA/eval.h>

    Calculate energy of a loop.

    Parameters:

      - fc – A vrna_fold_compound_t containing the energy parameters and model details

      - i – position of covering base pair

      - pt – the pair table of the secondary structure

      - verbosity_level – The level of verbosity of this function

    Returns:

      free energy of the loop in 10cal/mol

## Exterior Loops

Functions to evaluate the free energy contributions for exterior (external) loops.

  Boltzmann weight (partition function) interface

  typedef struct vrna_mx_pf_aux_el_s *vrna_mx_pf_aux_el_t
    #include <ViennaRNA/loops/external.h>

    Auxiliary helper arrays for fast exterior loop computations.

    See also

    vrna_exp_E_ext_fast_init(), vrna_exp_E_ext_fast_rotate(), vrna_exp_E_ext_fast_free(), vrna_exp_E_ext_fast()

  FLT_OR_DBL vrna_exp_E_ext_stem(unsigned int type, int n5d, int n3d, vrna_exp_param_t *p)
    #include <ViennaRNA/loops/external.h>

    Evaluate a stem branching off the exterior loop (Boltzmann factor version)

    Given a base pair \((i,j)\) encoded by type, compute the energy contribution including dangling-end/terminal-mismatch contributions. Instead of returning the energy contribution per-se, this function returns the corresponding Boltzmann factor. If either of the adjacent nucleotides \((i - 1)\) and \((j+1)\) must not contribute stacking energy, the corresponding encoding must be \(-1\).

    See also

    vrna_E_ext_stem()

    Parameters:

      - type – The base pair encoding

      - n5d – The encoded nucleotide directly adjacent at the 5’ side of the base pair (may be -1)

      - n3d – The encoded nucleotide directly adjacent at the 3’ side of the base pair (may be -1)

      - p – The pre-computed energy parameters (Boltzmann factor version)

    Returns:

      The Boltzmann weighted energy contribution of the introduced exterior-loop stem

  vrna_mx_pf_aux_el_t vrna_exp_E_ext_fast_init(vrna_fold_compound_t *fc)
    #include <ViennaRNA/loops/external.h>
  void vrna_exp_E_ext_fast_rotate(vrna_mx_pf_aux_el_t aux_mx)
    #include <ViennaRNA/loops/external.h>
  void vrna_exp_E_ext_fast_free(vrna_mx_pf_aux_el_t aux_mx)
    #include <ViennaRNA/loops/external.h>
  FLT_OR_DBL vrna_exp_E_ext_fast(vrna_fold_compound_t *fc, int i, int j, vrna_mx_pf_aux_el_t aux_mx)
    #include <ViennaRNA/loops/external.h>
  void vrna_exp_E_ext_fast_update(vrna_fold_compound_t *fc, int j, vrna_mx_pf_aux_el_t aux_mx)
    #include <ViennaRNA/loops/external.h>

  Basic free energy interface

  int vrna_E_ext_stem(unsigned int type, int n5d, int n3d, vrna_param_t *p)
    #include <ViennaRNA/loops/external.h>

    Evaluate a stem branching off the exterior loop.

    Given a base pair \((i,j)\) encoded by type, compute the energy contribution including dangling-end/terminal-mismatch contributions. Instead of returning the energy contribution per-se, this function returns the corresponding Boltzmann factor. If either of the adjacent nucleotides \((i - 1)\) and \((j+1)\) must not contribute stacking energy, the corresponding encoding must be \(-1\).

    See also

    vrna_E_exp_stem()

    Parameters:

      - type – The base pair encoding

      - n5d – The encoded nucleotide directly adjacent at the 5’ side of the base pair (may be -1)

      - n3d – The encoded nucleotide directly adjacent at the 3’ side of the base pair (may be -1)

      - p – The pre-computed energy parameters

    Returns:

      The energy contribution of the introduced exterior-loop stem

  int vrna_eval_ext_stem(vrna_fold_compound_t *fc, int i, int j)
    #include <ViennaRNA/loops/external.h>

    Evaluate the free energy of a base pair in the exterior loop.

    Evalue the free energy of a base pair connecting two nucleotides in the exterior loop and take hard constraints into account.

    Typically, this is simply dangling end contributions of the adjacent nucleotides, potentially a terminal A-U mismatch penalty, and maybe some generic soft constraint contribution for that decomposition.

    Note

    For dangles == 1 || 3 this function also evaluates the three additional pairs (i + 1, j), (i, j - 1), and (i + 1, j - 1) and returns the minimum for all four possibilities in total.

    Parameters:

      - fc – Fold compound to work on (defines the model and parameters)

      - i – 5’ position of the base pair

      - j – 3’ position of the base pair

    Returns:

      Free energy contribution that arises when this pair is formed in the exterior loop

  int vrna_E_ext_loop_5(vrna_fold_compound_t *fc)
    #include <ViennaRNA/loops/external.h>
  int vrna_E_ext_loop_3(vrna_fold_compound_t *fc, int i)
    #include <ViennaRNA/loops/external.h>

## Hairpin Loops

Functions to evaluate the free energy contributions for hairpin loops.

  Basic free energy interface

  int vrna_E_hp_loop(vrna_fold_compound_t *fc, int i, int j)
    #include <ViennaRNA/loops/hairpin.h>

    Evaluate the free energy of a hairpin loop and consider hard constraints if they apply.

    This function evaluates the free energy of a hairpin loop

    In case the base pair is not allowed due to a constraint conflict, this function returns INF.

    Note

    This function is polymorphic! The provided vrna_fold_compound_t may be of type VRNA_FC_TYPE_SINGLE or VRNA_FC_TYPE_COMPARATIVE

    Parameters:

      - fc – The vrna_fold_compound_t that stores all relevant model settings

      - i – The 5’ nucleotide of the base pair (3’ to evaluate the pair as exterior hairpin loop)

      - j – The 3’ nucleotide of the base pair (5’ to evaluate the pair as exterior hairpin loop)

    Returns:

      The free energy of the hairpin loop in 10cal/mol

  int vrna_E_ext_hp_loop(vrna_fold_compound_t *fc, int i, int j)
    #include <ViennaRNA/loops/hairpin.h>

    Evaluate the free energy of an exterior hairpin loop and consider possible hard constraints.

    Note

    This function is polymorphic! The provided vrna_fold_compound_t may be of type VRNA_FC_TYPE_SINGLE or VRNA_FC_TYPE_COMPARATIVE

  int vrna_eval_ext_hp_loop(vrna_fold_compound_t *fc, int i, int j)
    #include <ViennaRNA/loops/hairpin.h>

    Evaluate free energy of an exterior hairpin loop.

  int vrna_eval_hp_loop(vrna_fold_compound_t *fc, int i, int j)
    #include <ViennaRNA/loops/hairpin.h>

    Evaluate free energy of a hairpin loop.

    SWIG Wrapper Notes:

      This function is attached as method `eval_hp_loop()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.eval_hp_loop()` in the Python API .

    Note

    This function is polymorphic! The provided vrna_fold_compound_t may be of type VRNA_FC_TYPE_SINGLE or VRNA_FC_TYPE_COMPARATIVE

    Parameters:

      - fc – The vrna_fold_compound_t for the particular energy evaluation

      - i – 5’-position of the base pair

      - j – 3’-position of the base pair

    Returns:

      Free energy of the hairpin loop closed by \( (i,j) \) in deka-kal/mol

  static int E_Hairpin(int size, int type, int si1, int sj1, const char *string, vrna_param_t *P)
    #include <ViennaRNA/loops/hairpin.h>

    Compute the Energy of a hairpin-loop.

    To evaluate the free energy of a hairpin-loop, several parameters have to be known. A general hairpin-loop has this structure: where X-Y marks the closing pair [e.g. a (G,C) pair]. The length of this loop is 6 as there are six unpaired nucleotides (a1-a6) enclosed by (X,Y). The 5’ mismatching nucleotide is a1 while the 3’ mismatch is a6. The nucleotide sequence of this loop is “a1.a2.a3.a4.a5.a6”

    See also

    scale_parameters(), vrna_param_t

    Note

    The parameter sequence should contain the sequence of the loop in capital letters of the nucleic acid alphabet if the loop size is below 7. This is useful for unusually stable tri-, tetra- and hexa-loops which are treated differently (based on experimental data) if they are tabulated.

    Warning

    Not (really) thread safe! A threadsafe implementation will replace this function in a future release!

    Energy evaluation may change due to updates in global variable “tetra_loop”

    Parameters:

      - size – The size of the loop (number of unpaired nucleotides)

      - type – The pair type of the base pair closing the hairpin

      - si1 – The 5’-mismatching nucleotide

      - sj1 – The 3’-mismatching nucleotide

      - string – The sequence of the loop (May be `NULL`, otherwise mst be at least \(size + 2\) long)

      - P – The datastructure containing scaled energy parameters

    Returns:

      The Free energy of the Hairpin-loop in dcal/mol

  Boltzmann weight (partition function) interface

  static FLT_OR_DBL exp_E_Hairpin(int u, int type, short si1, short sj1, const char *string, vrna_exp_param_t *P)
    #include <ViennaRNA/loops/hairpin.h>

    Compute Boltzmann weight \(e^{-\Delta G/kT} \) of a hairpin loop.

    See also

    get_scaled_pf_parameters(), vrna_exp_param_t, E_Hairpin()

    Note

    multiply by scale[u+2]

    Warning

    Not (really) thread safe! A threadsafe implementation will replace this function in a future release!

    Energy evaluation may change due to updates in global variable “tetra_loop”

    Parameters:

      - u – The size of the loop (number of unpaired nucleotides)

      - type – The pair type of the base pair closing the hairpin

      - si1 – The 5’-mismatching nucleotide

      - sj1 – The 3’-mismatching nucleotide

      - string – The sequence of the loop (May be `NULL`, otherwise mst be at least \(size + 2\) long)

      - P – The datastructure containing scaled Boltzmann weights of the energy parameters

    Returns:

      The Boltzmann weight of the Hairpin-loop

  FLT_OR_DBL vrna_exp_E_hp_loop(vrna_fold_compound_t *fc, int i, int j)
    #include <ViennaRNA/loops/hairpin.h>

    High-Level function for hairpin loop energy evaluation (partition function variant)

    See also

    vrna_E_hp_loop() for it’s free energy counterpart

    Note

    This function is polymorphic! The provided vrna_fold_compound_t may be of type VRNA_FC_TYPE_SINGLE or VRNA_FC_TYPE_COMPARATIVE

## Internal Loops

Functions to evaluate the free energy contributions for internal (interior) loops.

  Basic free energy interface

  int vrna_E_int_loop(vrna_fold_compound_t *fc, int i, int j)
    #include <ViennaRNA/loops/internal.h>
  int vrna_eval_int_loop(vrna_fold_compound_t *fc, int i, int j, int k, int l)
    #include <ViennaRNA/loops/internal.h>

    Evaluate the free energy contribution of an interior loop with delimiting base pairs \((i,j)\) and \((k,l)\).

    SWIG Wrapper Notes:

      This function is attached as method `eval_int_loop()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.eval_int_loop()` in the Python API .

    Note

    This function is polymorphic, i.e. it accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE as well as VRNA_FC_TYPE_COMPARATIVE

  int vrna_E_ext_int_loop(vrna_fold_compound_t *fc, int i, int j, int *ip, int *iq)
    #include <ViennaRNA/loops/internal.h>
  int vrna_E_stack(vrna_fold_compound_t *fc, int i, int j)
    #include <ViennaRNA/loops/internal.h>

  Boltzmann weight (partition function) interface

  FLT_OR_DBL vrna_exp_E_int_loop(vrna_fold_compound_t *fc, int i, int j)
    #include <ViennaRNA/loops/internal.h>
  FLT_OR_DBL vrna_exp_E_interior_loop(vrna_fold_compound_t *fc, int i, int j, int k, int l)
    #include <ViennaRNA/loops/internal.h>

## Multibranch Loops

Functions to evaluate the free energy contributions for mutlibranch loops.

  Boltzmann weight (partition function) interface

  typedef struct vrna_mx_pf_aux_ml_s *vrna_mx_pf_aux_ml_t
    #include <ViennaRNA/loops/multibranch.h>

    Auxiliary helper arrays for fast exterior loop computations.

    See also

    vrna_exp_E_ml_fast_init(), vrna_exp_E_ml_fast_rotate(), vrna_exp_E_ml_fast_free(), vrna_exp_E_ml_fast()

  FLT_OR_DBL vrna_exp_E_mb_loop_fast(vrna_fold_compound_t *fc, int i, int j, vrna_mx_pf_aux_ml_t aux_mx)
    #include <ViennaRNA/loops/multibranch.h>
  vrna_mx_pf_aux_ml_t vrna_exp_E_ml_fast_init(vrna_fold_compound_t *fc)
    #include <ViennaRNA/loops/multibranch.h>
  void vrna_exp_E_ml_fast_rotate(vrna_mx_pf_aux_ml_t aux_mx)
    #include <ViennaRNA/loops/multibranch.h>
  void vrna_exp_E_ml_fast_free(vrna_mx_pf_aux_ml_t aux_mx)
    #include <ViennaRNA/loops/multibranch.h>
  const FLT_OR_DBL *vrna_exp_E_ml_fast_qqm(vrna_mx_pf_aux_ml_t aux_mx)
    #include <ViennaRNA/loops/multibranch.h>
  const FLT_OR_DBL *vrna_exp_E_ml_fast_qqm1(vrna_mx_pf_aux_ml_t aux_mx)
    #include <ViennaRNA/loops/multibranch.h>
  FLT_OR_DBL vrna_exp_E_ml_fast(vrna_fold_compound_t *fc, int i, int j, vrna_mx_pf_aux_ml_t aux_mx)
    #include <ViennaRNA/loops/multibranch.h>

  Basic free energy interface

  int vrna_E_mb_loop_stack(vrna_fold_compound_t *fc, int i, int j)
    #include <ViennaRNA/loops/multibranch.h>

    Evaluate energy of a multi branch helices stacking onto closing pair (i,j)

    Computes total free energy for coaxial stacking of (i.j) with (i+1.k) or (k+1.j-1)

  int vrna_E_mb_loop_fast(vrna_fold_compound_t *fc, int i, int j, int *dmli1, int *dmli2)
    #include <ViennaRNA/loops/multibranch.h>
  int E_ml_rightmost_stem(int i, int j, vrna_fold_compound_t *fc)
    #include <ViennaRNA/loops/multibranch.h>
  int vrna_E_ml_stems_fast(vrna_fold_compound_t *fc, int i, int j, int *fmi, int *dmli)
    #include <ViennaRNA/loops/multibranch.h>