
==================================================== SimRNA3 3.17 User Manual ===================================================================

1. Functionality

SimRNA is tool that predicts RNA 3D structure. Input for the program could be just sequence of RNA or starting structure written in PDB file.
Output is trajectory of simulation of RNA folding (file with extension .trafl). Program also creates file .bonds that should 
be used with .trafl to browse trajectory with pro_trafl browser.

2. Usage

----- You MUST have directory (or symbolic link to some other location) named 'data' inside your working directory.
----- 'data' directory (or link) contains energy function files and is necessary to run SimRNA,
----- data stored inside strongly affect results you obtain (don't make changes inside)
----- If you don't have this directory of program (for some reason) can't see it usually you see:
----- "Error in opening file ./data/arccos"

------------------------------------------------------------Options-----------------------------------------------------------------------------

  -s input_file_sequence

Or:

  -p input_file_PDB  <--- lowercase p
  
  -P input_file_PDB  <--- capital P
  
  In the second case occupancy and bfactor columns are using as atom position constraints:

	- if occupancy is equal 0.000 then current atom is fixed, its position is not changed during entire simulation
	- if occupancy is between 0.000 and 1.000 (but neither 0.000 nor 1.000) then bfactor value is treated as a radius
		of unrestricter movement
	- if occupancy is equal 1.000 atom is not restricted (while the other atoms can be restricted)

Optional:

  -o output_file_name (if not specified, program will create name by truncating input pdb or sequence file name)
  
  -S secondary_strc_restraints_file (allows specifying SS restraints in bracket format, it should be just single line, in case of pseudoknots second (and/or following lines) should be add accordingly

  -l program generates list of pdb files (each trajectory frame is written additionally to pdb)

  -n number_of_iterarions

  -r restraints_file

  -d dyes_file /* don't use it - doesn't work properly because of coding for a specific case */

  -t trafl_frame_file /used for trajectory (trafl) energy recalculation, while energy parametres are changed

  -c simulation_config_file
  
  -R int_number  (you can initiate random number generator from your value)
  
  -E int_number_of_Replicas (replica exchange monte carlo method, program initiates specified number of relica and perform REMC simulation)

  -m without parameter -> switch on global RNA moves /* not checked, don't use */


---------------------------------------------------------Options description-------------------------------------------------------------------------



 -s input_file_sequence -> argument is basic text file with sequence of RNA (both upper and lower cases are acceptable).

For example:  AGACUGCUGAGAGACC

To have more than one RNA chains as input You should just separate them with white spaces.
For example:

	aagcua aaagcugggcu
or

 AGACUGCUGAGAGACC
 UGCUGAGAGACC
 
if you want to provide secondary strucure restraints use -S with contents, i.e:

one line:

.((((......)))).

or several lines:

.((((......)))).
......(........)


-p input_file_PDB -> argument is PDB file with starting strucure

-n number_of_iterarions -> argument is number of iterations in one temperature cycle of simulated annealing

-r restraints_file -> argument is input file with restraints between atoms

--------------------------------------------------------------------------
There are two types of distance restraints: WELL and SLOPE (same as DISTANCE before, keyword DISTANCE still works for SLOPE)

For both types of restraints you need to specify: atoms to be constrained (names), min_dist, max_dist, and weight.

Restraints of type WELL are 0 except for range: min_dist <---> max_dist. For that range value is: -1*weight.
Restraints of type SLOPE are 0 within the range: min_dist <---> max_dist. Outside that range positive value of penatly is added. Value is: dist_violation*weight

Restraints for a given pairs of atoms can be combined (added). It requires two (or more) lines to specify subsequent contributions.

Restraints format:

WELL restraint (line in restraints file):
WELL        atom_1_id      atom_2_id    min_dist  max_dist  weight

SLOPE restraint (line in restraints file):
SLOPE        atom_1_id      atom_2_id    min_dist  max_dist  weight

or (alternative for SLOPE):
DISTANCE        atom_1_id      atom_2_id    min_dist  max_dist  weight

example line of restraints file:

SLOPE        A/23/C4'        C/45/P        6.5        7.5     1.0

where (nucleotide numbers are according to numbering in input PDB file !!! ):

A/23/C4' means atom C4' in nucleotide 23 in chain A
C/45/P means atom P in nucleotide 45 in chain C

6.5 minimal distance thrs
7.5 maximal distance thrs
1.0 weight of this restraint

atom name N means N in SimRNA representation, so N1 for pirymidines and N9 for purines !
it can also be used N9 for purines and N1 for pirymidines
in SimRNA3 you can also restrain C2 and also C6 atoms for purines and C4 atoms for pirymidines !

You can also apply restraints for a middle atom of the base (pseudo atom) which is named MB !!!
-----------------------------------------------------------------------------

-c simulation_config file -> argument is file with simulation configuration parameters

With this option You can configure simulation in more advanced way.
Configuration file is text file with one parameter set in one line. Options:

NUMBER_OF_ITERATIONS N

Number of unified iterations in simulated annealing simulation. This value (if set) will overwrite value given with -n option

TRA_WRITES_IN_EVERY_N_ITERATIONS N

Specifies after how many interations current conformation is appended to the trajectory file

INIT_TEMP Float

Starting temperature of simulation.

FINAL_STEP Float

Final temperature of simulation.

!!! Final temperature can be lower or higher that initial temperature. In the second case system is being gradually heated. !!!
!!! Final temperature can be also equal the initial temperature. In such case program maintains same temperature during entire simulation !!!

Order of parameters is not important.

config file example lines (upper case only):

NUMBER_OF_ITERATIONS	1000
TRA_WRITE_IN_EVERY_N_ITERATIONS 20
INIT_TEMP		1.35
FINAL_TEMP		0.90

additionally:

short range energy terms can be reweighted:

BONDS_WEIGHT 0.8
ANGLES_WEIGHT 0.8
TORS_ANGLES_WEIGHT 0.25

secondary structure specified with -S can be scaled by (default value is 1.0):

SECOND_STRC_RESTRAINTS_WEIGHT 1.0

frequencies of subsequent Monte Carlo moves can be adjusted:

FRACTION_OF_NITROGEN_ATOM_MOVES 0.01
FRACTION_OF_ONE_ATOM_MOVES      0.49
FRACTION_OF_TWO_ATOMS_MOVES     0.49
FRACTION_OF_FRAGMENT_MOVES      0.01

(values above are default)

For systems composed of several RNA chains additional constraint, namely limiting sphere, is activated. This sphere prevents escaping chains from each other.
It also reduces space (volume) of simulated system. When any atom exceeds limiting shpere additional positive value is added to the total energy. Value: dist_of_violation*weight

By default radius of that sphere is calculated as: 5.0*sqrt(numberOfNucleotides)
Weight is set to 1.0.

Those values can be specified by the user in config.dat file (i.e.):

LIMITING_SPHERE_RADIUS 41.5
LIMITING_SPHERE_WEIGHT 0.25

User should be notified about redifinition of those variables in SimRNA output.

===============================================================================================================================================
