# Hard Constraints

This module covers all functionality for hard constraints in secondary structure prediction.

## Introduction

Hard constraints as implemented in our library can be specified for individual loop types, i.e. the atomic derivations of the RNA folding grammar rules. Hence, the pairing behavior of both, single nucleotides and pairs of bases, can be constrained in every loop context separately. Additionally, an abstract implementation using a callback mechanism allows for full control of more complex hard constraints.

## Hard Constraints API

  Defines

  VRNA_CONSTRAINT_DB
    #include <ViennaRNA/constraints/hard.h>

    Flag for vrna_constraints_add() to indicate that constraint is passed in pseudo dot-bracket notation.

    See also

    vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

  VRNA_CONSTRAINT_DB_ENFORCE_BP
    #include <ViennaRNA/constraints/hard.h>

    Switch for dot-bracket structure constraint to enforce base pairs.

    This flag should be used to really enforce base pairs given in dot-bracket constraint rather than just weakly-enforcing them.

    See also

    vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

  VRNA_CONSTRAINT_DB_PIPE
    #include <ViennaRNA/constraints/hard.h>

    Flag that is used to indicate the pipe ‘|’ sign in pseudo dot-bracket notation of hard constraints.

    Use this definition to indicate the pipe sign ‘|’ (paired with another base)

    See also

    vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

  VRNA_CONSTRAINT_DB_DOT
    #include <ViennaRNA/constraints/hard.h>

    dot ‘.’ switch for structure constraints (no constraint at all)

    See also

    vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

  VRNA_CONSTRAINT_DB_X
    #include <ViennaRNA/constraints/hard.h>

    ‘x’ switch for structure constraint (base must not pair)

    See also

    vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

  VRNA_CONSTRAINT_DB_RND_BRACK
    #include <ViennaRNA/constraints/hard.h>

    round brackets ‘(‘,’)’ switch for structure constraint (base i pairs base j)

    See also

    vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

  VRNA_CONSTRAINT_DB_INTRAMOL
    #include <ViennaRNA/constraints/hard.h>

    Flag that is used to indicate the character ‘l’ in pseudo dot-bracket notation of hard constraints.

    Use this definition to indicate the usage of ‘l’ character (intramolecular pairs only)

    See also

    vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

  VRNA_CONSTRAINT_DB_INTERMOL
    #include <ViennaRNA/constraints/hard.h>

    Flag that is used to indicate the character ‘e’ in pseudo dot-bracket notation of hard constraints.

    Use this definition to indicate the usage of ‘e’ character (intermolecular pairs only)

    See also

    vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

  VRNA_CONSTRAINT_DB_GQUAD
    #include <ViennaRNA/constraints/hard.h>

    ‘+’ switch for structure constraint (base is involved in a gquad)

    See also

    vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

    Warning

    This flag is for future purposes only! No implementation recognizes it yet.

  VRNA_CONSTRAINT_DB_WUSS
    #include <ViennaRNA/constraints/hard.h>

    Flag to indicate Washington University Secondary Structure (WUSS) notation of the hard constraint string.

    This secondary structure notation for RNAs is usually used as consensus secondary structure (SS_cons) entry in Stockholm formatted files

  VRNA_CONSTRAINT_DB_DEFAULT
    #include <ViennaRNA/constraints/hard.h>

    Switch for dot-bracket structure constraint with default symbols.

    This flag conveniently combines all possible symbols in dot-bracket notation for hard constraints and VRNA_CONSTRAINT_DB

    See also

    vrna_hc_add_from_db(), vrna_constraints_add(), vrna_message_constraint_options(), vrna_message_constraint_options_all()

  VRNA_CONSTRAINT_CONTEXT_EXT_LOOP
    #include <ViennaRNA/constraints/hard.h>

    Hard constraints flag, base pair in the exterior loop.

  VRNA_CONSTRAINT_CONTEXT_HP_LOOP
    #include <ViennaRNA/constraints/hard.h>

    Hard constraints flag, base pair encloses hairpin loop.

  VRNA_CONSTRAINT_CONTEXT_INT_LOOP
    #include <ViennaRNA/constraints/hard.h>

    Hard constraints flag, base pair encloses an internal loop.

  VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC
    #include <ViennaRNA/constraints/hard.h>

    Hard constraints flag, base pair encloses a multi branch loop.

  VRNA_CONSTRAINT_CONTEXT_MB_LOOP
    #include <ViennaRNA/constraints/hard.h>

    Hard constraints flag, base pair is enclosed in an internal loop.

  VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC
    #include <ViennaRNA/constraints/hard.h>

    Hard constraints flag, base pair is enclosed in a multi branch loop.

  VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS
    #include <ViennaRNA/constraints/hard.h>

    Constraint context flag indicating any loop context.

  Typedefs

  typedef struct vrna_hc_s vrna_hc_t
    #include <ViennaRNA/constraints/hard.h>

    Typename for the hard constraints data structure vrna_hc_s.

  typedef struct vrna_hc_up_s vrna_hc_up_t
    #include <ViennaRNA/constraints/hard.h>

    Typename for the single nucleotide hard constraint data structure vrna_hc_up_s.

  typedef unsigned char (*vrna_hc_eval_f)(int i, int j, int k, int l, unsigned char d, void *data)
    #include <ViennaRNA/constraints/hard.h>

    Callback to evaluate whether or not a particular decomposition step is contributing to the solution space.

    This is the prototype for callback functions used by the folding recursions to evaluate generic hard constraints. The first four parameters passed indicate the delimiting nucleotide positions of the decomposition, and the parameter `denotes` the decomposition step. The last parameter `data` is the auxiliary data structure associated to the hard constraints via vrna_hc_add_data(), or NULL if no auxiliary data was added.

    Notes on Callback Functions:

      This callback enables one to over-rule default hard constraints in secondary structure decompositions.

    See also

    VRNA_DECOMP_PAIR_HP, VRNA_DECOMP_PAIR_IL, VRNA_DECOMP_PAIR_ML, VRNA_DECOMP_ML_ML_ML, VRNA_DECOMP_ML_STEM, VRNA_DECOMP_ML_ML, VRNA_DECOMP_ML_UP, VRNA_DECOMP_ML_ML_STEM, VRNA_DECOMP_ML_COAXIAL, VRNA_DECOMP_EXT_EXT, VRNA_DECOMP_EXT_UP, VRNA_DECOMP_EXT_STEM, VRNA_DECOMP_EXT_EXT_EXT, VRNA_DECOMP_EXT_STEM_EXT, VRNA_DECOMP_EXT_EXT_STEM, VRNA_DECOMP_EXT_EXT_STEM1, vrna_hc_add_f(), vrna_hc_add_data()

    Param i:

      Left (5’) delimiter position of substructure

    Param j:

      Right (3’) delimiter position of substructure

    Param k:

      Left delimiter of decomposition

    Param l:

      Right delimiter of decomposition

    Param d:

      Decomposition step indicator

    Param data:

      Auxiliary data

    Return:

      A non-zero value if the decomposition is valid, 0 otherwise

  Functions

  void vrna_constraints_add(vrna_fold_compound_t *fc, const char *constraint, unsigned int options)
    #include <ViennaRNA/constraints/basic.h>

    Add constraints to a vrna_fold_compound_t data structure.

    Use this function to add/update the hard/soft constraints The function allows for passing a string ‘constraint’ that can either be a filename that points to a constraints definition file or it may be a pseudo dot-bracket notation indicating hard constraints. For the latter, the user has to pass the VRNA_CONSTRAINT_DB option. Also, the user has to specify, which characters are allowed to be interpreted as constraints by passing the corresponding options via the third parameter.

    The following is an example for adding hard constraints given in pseudo dot-bracket notation. Here, `fc` is the vrna_fold_compound_t object, `structure` is a char array with the hard constraint in dot-bracket notation, and `enforceConstraints` is a flag indicating whether or not constraints for base pairs should be enforced instead of just doing a removal of base pair that conflict with the constraint.

              unsigned int constraint_options = VRNA_CONSTRAINT_DB_DEFAULT;

              if (enforceConstraints)
                constraint_options |= VRNA_CONSTRAINT_DB_ENFORCE_BP;

              if (canonicalBPonly)
                constraint_options |= VRNA_CONSTRAINT_DB_CANONICAL_BP;

              vrna_constraints_add(fc, (const char *)cstruc, constraint_options);

    In constrat to the above, constraints may also be read from file:

            vrna_constraints_add(fc, constraints_file, VRNA_OPTION_DEFAULT);

    See also

    vrna_hc_add_from_db(), vrna_hc_add_up(), vrna_hc_add_up_batch() vrna_hc_add_bp_unspecific(), vrna_hc_add_bp(), vrna_hc_init(), vrna_sc_set_up(), vrna_sc_set_bp(), vrna_sc_add_SHAPE_deigan(), vrna_sc_add_SHAPE_zarringhalam(), vrna_hc_free(), vrna_sc_free(), VRNA_CONSTRAINT_DB, VRNA_CONSTRAINT_DB_DEFAULT, VRNA_CONSTRAINT_DB_PIPE, VRNA_CONSTRAINT_DB_DOT, VRNA_CONSTRAINT_DB_X, VRNA_CONSTRAINT_DB_ANG_BRACK, VRNA_CONSTRAINT_DB_RND_BRACK, VRNA_CONSTRAINT_DB_INTRAMOL, VRNA_CONSTRAINT_DB_INTERMOL, VRNA_CONSTRAINT_DB_GQUAD

    Parameters:

      - fc – The fold compound

      - constraint – A string with either the filename of the constraint definitions or a pseudo dot-bracket notation of the hard constraint. May be NULL.

      - options – The option flags

  void vrna_hc_init(vrna_fold_compound_t *fc)
    #include <ViennaRNA/constraints/hard.h>

    Initialize/Reset hard constraints to default values.

    This function resets the hard constraints to their default values, i.e. all positions may be unpaired in all contexts, and base pairs are allowed in all contexts, if they resemble canonical pairs. Previously set hard constraints will be removed before initialization.

    SWIG Wrapper Notes:

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

    See also

    vrna_hc_add_bp(), vrna_hc_add_bp_nonspecific(), vrna_hc_add_up()

    Parameters:

      - fc – The fold compound

  void vrna_hc_add_up(vrna_fold_compound_t *fc, unsigned int i, unsigned char option)
    #include <ViennaRNA/constraints/hard.h>

    Make a certain nucleotide unpaired.

    See also

    vrna_hc_add_bp(), vrna_hc_add_bp_nonspecific(), vrna_hc_init(), VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, VRNA_CONSTRAINT_CONTEXT_HP_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP, VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS

    Parameters:

      - fc – The vrna_fold_compound_t the hard constraints are associated with

      - i – The position that needs to stay unpaired (1-based)

      - option – The options flag indicating how/where to store the hard constraints

  int vrna_hc_add_up_strand(vrna_fold_compound_t *fc, unsigned int i, int strand, unsigned char option)
    #include <ViennaRNA/constraints/hard.h>

    Make a certain nucleotide unpaired.

    This function puts a constraint onto a single nucleotide to limit or enforce its structural context. The position `i` should be given in local coordinates relative to the strand `strand` it corresponds to.

    See also

    vrna_hc_add_bp(), vrna_hc_add_bp_nonspecific(), vrna_hc_init(), VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, VRNA_CONSTRAINT_CONTEXT_HP_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP, VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS

    Note

    A negative value for the strand number `strand` indicates autodetection of the strand number assuming that coordinate i is given as global coordinates for the (current) concatenation of all strands. In this case, the function behaves exactly as vrna_hc_add_up().

    Parameters:

      - fc – The vrna_fold_compound_t the hard constraints are associated with

      - i – The position that needs to stay unpaired (1-based)

      - strand – The strand number of nucleotide `i` (0-based, negative value for autodetect)

      - option – The options flag indicating how/where to store the hard constraints

  int vrna_hc_add_up_batch(vrna_fold_compound_t *fc, vrna_hc_up_t *constraints)
    #include <ViennaRNA/constraints/hard.h>

    Apply a list of hard constraints for single nucleotides.

    Parameters:

      - fc – The vrna_fold_compound_t the hard constraints are associated with

      - constraints – The list off constraints to apply, last entry must have position attribute set to 0

  int vrna_hc_add_bp(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, unsigned char option)
    #include <ViennaRNA/constraints/hard.h>

    Favorize/Enforce a certain base pair (i,j)

    See also

    vrna_hc_add_bp_nonspecific(), vrna_hc_add_up(), vrna_hc_init(), VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, VRNA_CONSTRAINT_CONTEXT_HP_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC, VRNA_CONSTRAINT_CONTEXT_MB_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC, VRNA_CONSTRAINT_CONTEXT_ENFORCE, VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS

    Parameters:

      - fc – The vrna_fold_compound_t the hard constraints are associated with

      - i – The 5’ located nucleotide position of the base pair (1-based)

      - j – The 3’ located nucleotide position of the base pair (1-based)

      - option – The options flag indicating how/where to store the hard constraints

  int vrna_hc_add_bp_strand(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, int strand_i, int strand_j, unsigned char option)
    #include <ViennaRNA/constraints/hard.h>

    Favorize/Enforce a certain base pair (i,j) where i and j may point to different strands.

    This function adds a base pair constraint for pair (i,j), where the positions i and j are relative to the RNA strands i and j correspond to. For each strand `strand_i` and @strand_j positions are 1-based. For instance, if position 5 of strand 0 must pair with position 10 of strand 1, the function call would be

        vrna_hc_add_bp(fc, 5, 10, 0, 1, VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS | VRNA_CONSTRAINT_CONTEXT_ENFORCE);

    Negative values for the strand numbers `strand_i` and `strand_j` indicate autodetection of the strand number assuming that coordinates i and/or j are given as global coordinates for the (current) concatenation of all strands

    See also

    vrna_hc_add_bp_nonspecific(), vrna_hc_add_up(), vrna_hc_add_bp(), vrna_hc_init(), VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, VRNA_CONSTRAINT_CONTEXT_HP_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC, VRNA_CONSTRAINT_CONTEXT_MB_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC, VRNA_CONSTRAINT_CONTEXT_ENFORCE, VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS

    Parameters:

      - fc – The vrna_fold_compound_t the hard constraints are associated with

      - i – The 5’ located nucleotide position of the base pair (1-based, relative to `strand_i`)

      - j – The 3’ located nucleotide position of the base pair (1-based, relative to `strand_j`)

      - strand_i – The strand number of pairing partner `i` (0-based, negative value for autodetect)

      - strand_i – The strand number of pairing partner `j` (0-based, negative value for autodetect)

      - option – The option flag(s) indicating loop types and enforcement of the constraint

  void vrna_hc_add_bp_nonspecific(vrna_fold_compound_t *fc, unsigned int i, int d, unsigned char option)
    #include <ViennaRNA/constraints/hard.h>

    Enforce a nucleotide to be paired (upstream/downstream)

    See also

    vrna_hc_add_bp(), vrna_hc_add_up(), vrna_hc_init(), VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, VRNA_CONSTRAINT_CONTEXT_HP_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC, VRNA_CONSTRAINT_CONTEXT_MB_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC, VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS

    Parameters:

      - fc – The vrna_fold_compound_t the hard constraints are associated with

      - i – The position that needs to stay unpaired (1-based)

      - d – The direction of base pairing ( \( d < 0 \): pairs upstream, \( d > 0 \): pairs downstream, \( d == 0 \): no direction)

      - option – The options flag indicating in which loop type context the pairs may appear

  void vrna_hc_free(vrna_hc_t *hc)
    #include <ViennaRNA/constraints/hard.h>

    Free the memory allocated by a vrna_hc_t data structure.

    Use this function to free all memory that was allocated for a data structure of type vrna_hc_t .

    See also

    get_hard_constraints(), vrna_hc_t

  int vrna_hc_add_from_db(vrna_fold_compound_t *fc, const char *constraint, unsigned int options)
    #include <ViennaRNA/constraints/hard.h>

    Add hard constraints from pseudo dot-bracket notation.

    This function allows one to apply hard constraints from a pseudo dot-bracket notation. The `options` parameter controls, which characters are recognized by the parser. Use the VRNA_CONSTRAINT_DB_DEFAULT convenience macro, if you want to allow all known characters

    SWIG Wrapper Notes:

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

    See also

    VRNA_CONSTRAINT_DB_PIPE, VRNA_CONSTRAINT_DB_DOT, VRNA_CONSTRAINT_DB_X, VRNA_CONSTRAINT_DB_ANG_BRACK, VRNA_CONSTRAINT_DB_RND_BRACK, VRNA_CONSTRAINT_DB_INTRAMOL, VRNA_CONSTRAINT_DB_INTERMOL, VRNA_CONSTRAINT_DB_GQUAD

    Parameters:

      - fc – The fold compound

      - constraint – A pseudo dot-bracket notation of the hard constraint.

      - options – The option flags

  struct vrna_hc_s
    #include <ViennaRNA/constraints/hard.h>

    The hard constraints data structure.

    The content of this data structure determines the decomposition pattern used in the folding recursions. Attribute ‘matrix’ is used as source for the branching pattern of the decompositions during all folding recursions. Any entry in matrix[i,j] consists of the 6 LSB that allows one to distinguish the following types of base pairs:

    - in the exterior loop (VRNA_CONSTRAINT_CONTEXT_EXT_LOOP)

    - enclosing a hairpin (VRNA_CONSTRAINT_CONTEXT_HP_LOOP)

    - enclosing an internal loop (VRNA_CONSTRAINT_CONTEXT_INT_LOOP)

    - enclosed by an exterior loop (VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC)

    - enclosing a multi branch loop (VRNA_CONSTRAINT_CONTEXT_MB_LOOP)

    - enclosed by a multi branch loop (VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC)

    The four linear arrays ‘up_xxx’ provide the number of available unpaired nucleotides (including position i) 3’ of each position in the sequence.

    See also

    vrna_hc_init(), vrna_hc_free(), VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, VRNA_CONSTRAINT_CONTEXT_HP_LOOP, VRNA_CONSTRAINT_CONTEXT_INT_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP, VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC

    Public Members

    vrna_hc_type_e type
    unsigned int n
    unsigned char state
    unsigned char *mx
    unsigned char **matrix_local
    unsigned int *up_ext

      A linear array that holds the number of allowed unpaired nucleotides in an exterior loop.

    unsigned int *up_hp

      A linear array that holds the number of allowed unpaired nucleotides in a hairpin loop.

    unsigned int *up_int

      A linear array that holds the number of allowed unpaired nucleotides in an internal loop.

    unsigned int *up_ml

      A linear array that holds the number of allowed unpaired nucleotides in a multi branched loop.

    vrna_hc_eval_f f

      A function pointer that returns whether or not a certain decomposition may be evaluated.

    void *data

      A pointer to some structure where the user may store necessary data to evaluate its generic hard constraint function.

    vrna_auxdata_free_f free_data

      A pointer to a function to free memory occupied by auxiliary data.

      The function this pointer is pointing to will be called upon destruction of the vrna_hc_s, and provided with the vrna_hc_s.data pointer that may hold auxiliary data. Hence, to avoid leaking memory, the user may use this pointer to free memory occupied by auxiliary data.

    vrna_hc_depot_t *depot
  struct vrna_hc_up_s
    #include <ViennaRNA/constraints/hard.h>

    A single hard constraint for a single nucleotide.

    Public Members

    int position

      The sequence position (1-based)

    int strand
    unsigned char options

      The hard constraint option