oxDNA README
------------

oxDNA is a simulation code that was initially conceived as an implementation of the coarse-grained DNA
model introduced by T. E. Ouldridge, J. P. K. Doye and A. A. Louis (http://dx.doi.org/10.1063/1.3552946).
It has been since reworked and it is now an extensible simulation+analysis framework.
It natively supports DNA, RNA, Lennard-Jones and patchy particle simulations on both CPU and NVIDIA
GPUs.

REQUIREMENTS
------------

Without CUDA support:
cmake >= 2.6
make
gcc >= 4.2 / icc >= 11.0

With CUDA support:
cmake >= 2.8
make
gcc >= 4.2 / icc >= 11.0
CUDA toolkit >= 4.0

Generating the documentation (with 'make docs', see below) requires doxygen. 

COMPILING oxDNA
---------------

Extract the oxDNA archive and then:

cd oxDNA 		# enter the oxDNA folder
mkdir build 	# create a new build folder. It is good practice to compile out-of-source
cd build
cmake ..		# here you can specify additional options, see next section
make -j4		# compile oxDNA. The -jX make option makes it compile the code in parallel by using X threads.

At the end of the compilation three executables (oxDNA, DNAnalysis and confGenerator) will be placed
in the build/bin folder.

CMAKE OPTIONS
-------------

-DCUDA=ON		Enables CUDA support
-DDebug=ON		Compiles with debug symbols and without optimisation flags
-DG=ON			Compiles with debug symbols + optimisation flags
-DINTEL=ON		Uses INTEL's compiler suite
-DMPI=ON		Compiles oxDNA with MPI support

MAKE TARGETS
-------------

make
	Compiles oxDNA
	
make docs
    Produces html doxygen documentation.
    oxDNA: DOCS/html_oxDNA/index.html
    UTILS: DOCS/html_UTILS/index.html

TESTING
-------

make test
	Runs quick tests to check whether oxDNA has been correctly compiled or not.
	This command runs a several short system test in the TEST/ directory
    Test results can be viewed in TEST/logs
	
make test_scientific
	Runs longer tests to check that oxDNA works (not fully implemented yet) 

USAGE
-----

oxDNA input_file

OUTPUT FILE
-----------

The energy.dat (default name, can be changed in the configuration file) has this layout for MD:
time potential_energy kinetic_energy total_energy

The energy.dat (default name, can be changed in the configuration file) has this layout for MC:
time potential_energy hydrogen_bonding_energy acc_trasl acc_rot [acc_volume]

Mind that potential, kinetic and total energies are divided by the number of particles.

Configurations are saved in the trajectory file (appended one after the other).

OBSERVABLES
-----------

The observable infrastructure was devised to help building
customized output from oxDNA (and DNAAnalysis) without having to
dive in the simulation code itself. 

The relevant keys in the input file are analysis_data_output_* and
data_output_* (see below). These take as an argument, between curly
brackets, a series of lines that is interpreted as an input file.
An example is:

data_output_1 = {
name = caca.dat
print_every = 100
col_1 = {
type = potential_energy
}
col_2 = {
type = step
units = MD
}
}

this will print in caca.dat two colums, the first with the
potential energy and the second with the steps in MD units (dt
aware). 

The lines in between curly brackets are interpreted as input files
by the single observables.

See also the doxygen documentation for Observables/ObservableOutput.h

oxDNA provides a plugin infrastructure to manage additional 
Observables. See the doxygen documentation for PluginManagement/PluginManager.h

INPUT FILE OPTIONS
------------------

As always in UNIX environments, everything is case sensitive.
The options are in the form key = value. Key-value pairs should be either on different
lines or separated by a semicolon. There can be arbitrary spaces before and after both key and value. 
Line with a leading # will be treated as comments. The expected type of the value is specified between < and >. 
A <bool> key can be specified with values 1|0, yes|no or true|false.  
The | symbol (pipe) is used to indicate the different values that can be used to specify a value for the key.
Keys between [ and ] are optional.

Core options:

    T = <float>
        temperature of the simulation. It can be expressed in simulation units
        or kelvin (append a k or K after the value) or celsius (append a c or
        C after the value).
    [fix_diffusion = <bool>]
        if true, particles that leave the simulation box are brought back in
        via periodic boundary conditions. Defaults to true.
    [seed = <int>]
        seed for the random number generator. On Unix systems, defaults to
        either a number from /dev/urandom or to time(NULL)
    [confs_to_skip = <int>]
        how many configurations should be skipped before using the next one as
        the initial configuration, defaults to 0
    restart_step_counter = <boolean>/<bool>
        false means that the step counter will start from the value read in
        the configuration file, true means that the step counter will start
        from 0/if True oxDNA will reset the step counter to 0, otherwise it
        will start from the step counter found in the initial configuration.
        Defaults to False.
    [external_forces = <bool>]
        specifies whether there are external forces acting on the nucleotides
        or not. If it is set to 1, then a file which specifies the external
        forces' configuration has to be provided (see external_forces_file)
    [external_forces_file = <path>]
        specifies the file containing all the external forces' configurations.
        Currently there are six supported force types: string, twist, trap,
        repulsion_plane, repulsion_plane_moving and mutual_trap (see
        EXAMPLES/TRAPS for some examples)
    [back_in_box = <bool>]
        whether particles should be brought back into the box when a
        configuration is printed or not, defaults to false
    [lastconf_file = <path>]
        path to the file where the last configuration will be dumped
    trajectory_file = <path>
        path to the file which will contain the output trajectory of the
        simulation
    [binary_initial_conf = <bool>]
        whether the initial configuration is a binary configuration or not,
        defaults to false
    [lastconf_file_bin = <path>]
        path to the file where the last configuration will be printed in
        binary format, if not specified no binary configurations will be
        printed
    [print_reduced_conf_every = <int>]
        every how many time steps configurations containing only the centres
        of mass of the strands should be printed. If 0, no reduced
        configurations will be printed
    [reduced_conf_output_dir = <path>]
        path to the folder where reduced configurations will be printed
    [no_stdout_energy = <bool>]
        if true oxDNA will not print the default simulation output, including
        the energy, to stdout. Defaults to false
    [print_timings = <bool>]
        whether oxDNA should print out to a file performance timings at the
        end of the simulation or not, defaults to false
    [timings_filename = <path>]
        path to the file where timings will be printed
    [output_prefix = <string>]
        the name of all output files will be preceded by this prefix, defaults
        to an empty string
    [print_input = <bool>]
        make oxDNA write the input key=value pairs used by the simulation in a
        file named input.pid, with pid being the oxDNA pid. Defaults to False.
    conf_file = <string>
        path to the starting configuration
    steps = <int>
        length of the simulation, in time steps
    [equilibration_steps = <int>]
        number of equilibration steps. During equilibration, oxDNA does not
        generate any output. Defaults to 0
    time_scale = linear/log_lin
        a linear time_scale will make oxDNA print linearly-spaced
        configurations. a log_lin will make it print linearly-spaced cycles of
        logarithmically-spaced configurations.
    print_conf_interval = <int>
        if the time scale is linear, this is the number of time steps between
        the outputing of configurations, otherwise this is just the first
        point of the logarithmic part of the log_lin time scale
    print_conf_ppc = <int>
        mandatory only if time_scale == log_line. This is the number of
        printed configurations in a single logarithmic cycle.
    [print_energy_every = <int>]
        number of time steps between the outputing of the energy (and of the
        other default observables such as acceptance ratios in Monte Carlo
        simulations). Defaults to 0.
    verlet_skin = <float>
        width of the skin that controls the maximum displacement after which
        Verlet lists need to be updated.
    [list_type = verlet|cells|no]
        Type of neighbouring list to be used in CPU simulations. 'no' implies
        a O(N^2) computational complexity. Defaults to verlet.
    particle = <int>
        particle to apply the force to. -1 applies it to all particles.
    F0 = <float>
        Initial force.
    wait_time = <float>
        time interval over which the force is constant. Units are (MD/MC)
        steps.
    increment = <float>
        amount by which to increment the force every wait_time steps.
    stiff = <float>
        stiffness of the spring
    r0 = <float>
        equilibrium elongation of the spring
    com_list = <string>
        comma-separated list containing the ids of all the particles whose
        centre of mass is subject to the force
    ref_list = <string>
        comma-separated list containing the ids of all the particles whose
        centre of mass is the reference point for the force acting on the
        other group of particles
    rate = <float>
        growth rate of the force. It is [oxDNA energy units / (oxDNA distance
        units * (MD/MC) steps].
    name = <string>
        name of the output stream. stdout or stderr are accepted values
    print_every = <integer>
        frequency of output, in number steps for oxDNA, in number of
        configurations for DNAnalysis
    [start_from = <integer>]
        start outputing from the given step, defaults to 0
    [stop_at = <integer>]
        stop outputing at this step, defaults to -1 (which means never)
    [only_last = <bool>]
        if true, the output will not be appended to the stream, but it will
        overwrite the previous output each time, defaults to false
    [binary = <bool>]
        if true, the output will be printed in binary, defaults to false
    [linear = <bool>]
        if true the OutputObservable will save in linear scale, otherwise will
        use the logline scale by FS. Defaults to true
    [update_name_with_time = <bool>]
        if true the output filename will be changed by using the 'name' key as
        a prefix and the current step as a suffix. Defaults to false
    col_<n> = {
    type = name of the first observable
    [other observable options as lines of 'key = value']
    }
        this syntax specifies the column of the output file. Note that <n> is
        the column index and should start from 1

-------------------------------------------------------------------------------

MD options:

    backend = CPU
        For CPU FFS
    backend_precision = <any>
        CPU FFS may use any precision allowed for a normal CPU MD simulation
    sim_type = FFS_MD
        This must be set for an FFS simulation
    [thermostat = no|refresh|brownian|langevin|srd]
        Select the simulation thermostat for MD simulations. 'no' means
        constant-energy simulations. 'refresh' is the Anderson thermostat.
        'brownian' is an Anderson-like thermostat that refreshes momenta of
        randomly chosen particles. 'langevin' implements a regular Langevin
        thermostat. 'srd' is an (experimental) implementation of a stochastic
        rotational dynamics algorithm. 'no' and 'brownian' are also available
        on CUDA. Defaults to 'no'.
    gamma_trans = <float>
        translational damping coefficient for the Langevin thermostat. Either
        this or diff_coeff should be specified in the input file.
    newtonian_steps = <int>
        number of integration timesteps after which momenta are refreshed
    pt = <float>
        probability of refreshing the momenta of each particle
    diff_coeff = <float>
        base diffusion coefficient. Either pt or diff_coeff should be
        specified in the input file

-------------------------------------------------------------------------------

MC options:

    ensemble = nvt|npt
        ensemble of the simulation
    [check_energy_every = <float>]
        oxDNA will compute the energy from scratch, compare it with the
        current energy and throw an error if the difference is larger then
        check_energy_threshold. Defaults to 10.
    [check_energy_threshold = <float>]
        threshold for the energy check. Defaults to 1e-2f for single precision
        and 1e-6 for double precision.
    delta_translation = <float>
        controls the trial translational displacement, which is a randomly
        chosen number between -0.5*delta and 0.5*delta for each direction.
    delta_rotation = <float>
        controls the angular rotational displacement, given by a randomly
        chosen angle between -0.5*delta and 0.5*delta radians.
    delta_volume = <float>
        controls the volume change in npt simulations.
    P = <float>
        the pressure of the simulation. Used only if ensemble == npt.
    [adjust_moves = <bool>]
        if true, oxDNA will run for equilibration_steps time steps while
        changing the delta of the moves in order to have an optimal acceptance
        ratio. It does not make sense if equilibration_steps is 0 or not
        given. Defaults to false
    [maxclust = <int>]
        Default: N; maximum number of particles to be moved together. Defaults
        to the whole system
    [small_system = <bool>]
        Default: false; whether to use an interaction computation suited for
        small systems.
    [preserve_topology = <bool>]
        Default: false; sets a maximum size for the move attempt to 0.5, which
        guarantees that the topology of the system is conserved. Also prevents
        very large moves and might speed up simulations of larger systems,
        while suppressing diffusion
    [umbrella_sampling = <bool>]
        Default: false; whether to use umbrella sampling
    [op_file = <string>]
        Mandatory if umbrella_sampling is set to true; path to file with the
        description of the order parameter
    [weights_file = <string>]
        Mandatory if umbrella_sampling is set to true; path to file with the
        weights to use in umbrella sampling
    [last_hist_file = <string>]
        Optional if umbrella_sampling is set to true, otherwise ignored;
        Default: last_hist.dat; path to file where the histograms associated
        with umbrella sampling will be stored. This is printed with the same
        frequency as the energy file. Should become an observable sooner or
        later
    [traj_hist_file = <string>]
        Optional if umbrella_sampling is set to true, otherwise ignored;
        Default: traj_hist.dat; path to file where the series histograms
        associated with umbrella sampling will be stored, allowing to monitor
        the time evolution of the histogram and possibly to remove parts of
        the simulation. This is printed with the same frequency as the energy
        file. Should become an observable sooner or later
    [init_hist_file = <string>]
        Optional if umbrella_sampling is set to true, otherwise ignored;
        Default: none; path to a file to load a previous histogram from,
        useful if one wants to continue a simulation to obtain more
        statistics.
    [extrapolate_hist = <float>,<float>,..., <float>]
        Optional if umbrella_sampling is set to true, otherwise ignored;
        Default: none; series of temperatures to which to extrapolate the
        histograms. They can be given as float in reduced units, or the units
        can be specified as in the T option
    [safe_weights = <bool>]
        Default: true; whether to check consistency in between order parameter
        file and weight file. Only used if umbrella_sampling = true
    [default_weight = <float>]
        Default: none; mandatory if safe_weights = true; default weight for
        states that have no specified weight assigned from the weights file
    [skip_hist_zeros = <bool>]
        Default: false; Wether to skip zero entries in the traj_hist file
    [equilibration_steps = <int>]
        Default: 0; number of steps to ignore to allow for equilibration

-------------------------------------------------------------------------------

Interactions/RNAInteraction_relax.h options:

    relax_type = <string>
        Possible values: constant_force, harmonic_force; Relaxation algorithm
        used
    relax_strength = <float>
        Force constant for the replacement of the FENE potential

Interactions/DNAInteraction_relax.h options:

    relax_type = <string>
        Possible values: constant_force, harmonic_force; Relaxation algorithm
        used
    relax_strength = <float>
        Force constant for the replacement of the FENE potential

Interactions/DirkInteraction2.h options:

    length = <float>
        lenght of the cylinders
    DHS_radius = <float>
        radius of the diploar hard sphere on top of each cylinder
    DHS_rcut = <float>
        distance cutoff for the reaction field treatment
    DHS_eps = <float>
        background dielectric constant for the reaction field treatment

Interactions/RNAInteraction2.h options:

    [use_average_seq = <boolean>]
        defaults to yes
    [seq_dep_file = <string>]
        sets the location of the files with sequence-dependent parameters
    [external_model = <string>]
        overrides default constants for the model, set in rna_model.h), by
        values specified by this option
    [salt = <float>]
        sets the salt concentration in M, defaults to 1
    [mismatch_repulsion = <boolean>]
        defaults to no

Interactions/DirkInteractionSin.h options:

    length = <float>
        lenght of the cylinders
    DHS_radius = <float>
        radius of the diploar hard sphere on top of each cylinder
    DHS_rcut = <float>
        distance cutoff for the reaction field treatment
    DHS_eps = <float>
        background dielectric constant for the reaction field treatment

Interactions/HardCylinderInteraction.h options:

    height = <float>
        cylinder length

Interactions/DNAInteraction.h options:

    [use_average_seq = <boolean>]
        defaults to yes
    [hb_multiplier = <float>]
        HB interaction multiplier applied to all the nucleotides having a
        custom numbered base whose magnitude is > 300, defaults to 1.0

Interactions/LJInteraction.h options:

    LJ_rcut = <float>
        interaction cutoff
    [LJ_kob_andersen = <bool>]
        Simulate a Kob-Andersen mixture. Defaults to false.
    [LJ_n = <int>]
        Generalised LJ exponent. Defaults to 6, which is the classic LJ value.

Interactions/TSPInteraction.h options:

    TSP_rfene = <float>
        FENE length constant for bonded interactions
    TSP_sigma[type] = <float>
        particle diameter associated to each interaction
    TSP_epsilon[type] = <float>
        energy scale associated to each interaction
    TSP_attractive[type] = <float>
        whether the interaction contains an attractive tail or not
    TSP_n[type] = <int>
        exponent for the generalised LJ potential for each interaction
    [TSP_attractive_anchor = <bool>]
        set to true if you want the anchor monomer to be of type B instead of
        type A. Defaults to false
    [TSP_only_chains = <bool>]
        if true the system will be composed of chains only. The topology will
        be interpreted accordingly by ignoring the first value of each line
        (which, in the case of TSPs, is the number of arms). Defaults to false
    [TSP_only_intra = <bool>]
        if true monomers belonging to different stars will not interact.
        Defaults to false

Interactions/TEPInteraction.h options:

    [use_average_seq = <boolean>]
        defaults to yes
    [hb_multiplier = <float>]
        HB interaction multiplier applied to all the nucleotides having a
        custom numbered base whose magnitude is > 300, defaults to 1.0

Interactions/DHSInteraction.h options:

    DHS_eps = <float>
        background dielectrci constant for reaction field treatment
    DHS_rcut = <float>
        cutoff for the reaction field treatment

Interactions/DirkInteractionBias.h options:

    length = <float>
        lenght of the cylinders
    DHS_radius = <float>
        radius of the diploar hard sphere on top of each cylinder
    DHS_rcut = <float>
        distance cutoff for the reaction field treatment
    DHS_eps = <float>
        background dielectric constant for the reaction field treatment

Interactions/RNAInteraction.h options:

    [use_average_seq = <boolean>]
        defaults to yes
    [seq_dep_file = <string>]
        sets the location of the files with sequence-dependent parameters
    [external_model = <string>]
        overrides default constants for the model, set in rna_model.h), by
        values specified by this option

Interactions/PatchyInteraction.h options:

    PATCHY_N = <int>
        number of patches
    [PATCHY_N_B = <int>]
        number of patches on species B
    [PATCHY_alpha = <float>]
        width of patches, defaults to 0.12

Interactions/DNA2Interaction.h options:

    salt_concentration = <float>
        sets the salt concentration in M
    [dh_lambda = <float>]
        the value that lambda, which is a function of temperature (T) and salt
        concentration (I), should take when T=300K and I=1M, defaults to the
        value from Debye-Huckel theory, 0.3616455
    [dh_strength = <float>]
        the value that scales the overall strength of the Debye-Huckel
        interaction, defaults to 0.0543
    [dh_half_charged_ends = <bool>]
        set to false for 2N charges for an N-base-pair duplex, defaults to 1

Interactions/InteractionFactory.h options:

    [interaction_type = DNA|RNA|HS|LJ|patchy|TSP|DNA_relax|DNA_nomesh|Box|HardCylinder|HardSpheroCylinder|DHS|Dirk]
        Particle-particle interaction of choice. Check the documentation
        relative to the specific interaction for more details. Defaults to
        dna.

Interactions/BoxInteraction.h options:

    box_sides = <float>, <float>, <float>
        sides of the box

Interactions/HardSpheroCylinderInteraction.h options:

    length = <float>
        length of the spherocylinder

Interactions/DirkInteraction.h options:

    length = <float>
        lenght of the cylinders
    DHS_radius = <float>
        radius of the diploar hard sphere on top of each cylinder
    DHS_rcut = <float>
        distance cutoff for the reaction field treatment
    DHS_eps = <float>
        background dielectric constant for the reaction field treatment

-------------------------------------------------------------------------------

CUDA options:

    backend = CUDA
        For CUDA FFS -- NB unlike the CPU implementation, the CUDA
        implementation does not print extra columns with the current order
        parameter values whenever the energy is printed
    backend_precision = mixed
        CUDA FFS is currently only implemented for mixed precision
    sim_type = FFS_MD
        This must be set for an FFS simulation
    order_parameters_file = <string>
        path to the order parameters file
    ffs_file = <string>
        path to the file with the simulation stopping conditions. Optionally,
        one may use 'master conditions' (CUDA FFS only), which allow one to
        more easily handle very high dimensional order parameters. See the
        EXAMPLES/CUDA_FFS/README file for more information
    [ffs_generate_flux = <bool>]
        CUDA FFS only. Default: False; if False, the simulation will run until
        a stopping condition is reached; if True, a flux generation simulation
        will be run, in which case reaching a condition will cause a
        configuration to be saved but will not terminate the simulation. In
        the stopping condition file, the conditions must be labelled forward1,
        forward2, ... (for the forward conditions); and backward1, backward2,
        ... (for the backward conditions), ... instead of condition1,
        condition2, ... . To get standard flux generation, set the forward and
        backward conditions to correspond to crossing the same interface (and
        use conditions corresponding to different interfaces for Tom's flux
        generation). As with the single shooting run mode, the name of the
        condition crossed will be printed to stderr each time.
    [gen_flux_save_every = <integer>]
        CUDA FFS only. Mandatory if ffs_generate_flux is True; save a
        configuration for 1 in every N forward crossings
    [gen_flux_total_crossings = <integer>]
        CUDA FFS only. Mandatory if ffs_generate_flux is True; stop the
        simulation after N crossings achieved
    [gen_flux_conf_prefix = <string>]
        CUDA FFS only. Mandatory if ffs_generate_flux is True; the prefix used
        for the file names of configurations corresponding to the saved
        forward crossings. Counting starts at zero so the 3rd crossing
        configuration will be saved as MY_PREFIX_N2.dat
    [gen_flux_debug = <bool>]
        CUDA FFS only. Default: False; In a flux generation simulation, set to
        true to save backward-crossing configurations for debugging
    [check_initial_state = <bool>]
        CUDA FFS only. Default: False; in a flux generation simulation, set to
        true to turn on initial state checking. In this mode an initial
        configuration that crosses the forward conditions after only 1 step
        will cause the code to complain and exit. Useful for checking that a
        flux generation simulation does not start out of the A-state
    [die_on_unexpected_master = <bool>]
        CUDA FFS only. Default: False; in a flux generation simulation that
        uses master conditions, set to true to cause the simulation to die if
        any master conditions except master_forward1 or master_backward1 are
        reached. Useful for checking that a flux generation simulation does
        not enter any unwanted free energy basins (i.e. other than the initial
        state and the desired final state)
    [unexpected_master_prefix = <string>]
        CUDA FFS only. Mandatory if die_on_unexpected_master is True; the
        prefix used for the file names of configurations corresponding to
        reaching any unexpected master conditions (see
        die_on_unexpected_master).
    [CUDA_device = <int>]
        CUDA-enabled device to run the simulation on. If it is not specified
        or it is given a negative number, a suitable device will be
        automatically chosen.
    [CUDA_sort_every = <int>]
        sort particles according to a 3D Hilbert curve every CUDA_sort_every
        time steps. This will greatly enhnance performances for some types of
        interaction. Defaults to 0, which disables sorting.
    [threads_per_block = <int>]
        Number of threads per block on the CUDA grid. defaults to 2 * the size
        of a warp.
    [CUDA_list = no|verlet]
        Neighbour lists for CUDA simulations. Defaults to 'no'.

-------------------------------------------------------------------------------

Analysis options:

    [analysis_confs_to_skip = <int>]
        number of configurations that should be excluded from the analysis.
    analysis_data_output_<n> = {
    ObservableOutput
    }
        specify an analysis output stream. <n> is an integer number and should
        start from 1. The setup and usage of output streams are documented in
        the ObservableOutput class.

-------------------------------------------------------------------------------

Observables/Step.h options:

    [units = steps|MD]
        units to print the time on. time in MD units = steps * dt, defaults to
        step

Observables/DensityProfile.h options:

    max_value = <float>
        anything with a relevant coordinate grater than this will be ignored.
        Mind that the observable is PBC-aware.
    bin_size = <float>
        the bin size for the profile
    axis = <char>
        Possible values: x, y, z the axis along which to compute the profile

Observables/Pitch.h options:

    bp1a_id = <int>
        base pair 1 particle a id
    bp1b_id = <int>
        base pair 1 particle b id
    bp2a_id = <int>
        base pair 2 particle a id
    bp2b_id = <int>
        base pair 2 particle b id

Observables/ParticlePosition.h options:

    particle_id = <int>
        particle id
    [orientation = <bool>]
        defaults to false. If 1, it also prints out the orientation
    [absolute = <bool>]
        defaults to false. If 1, does not use periodic boundaries and it
        prints out the absolute position of the center of mass

Observables/SaltExtrapolation.h options:

    salts = <float>, <float>, ...
        list of salt concentration to extrapolate to
    temps = <T>, <T>, ...
        list of temperatures to extrapolate to, separated with commas.
        Temperatures can be specified in reduced units, Kelvin, Celsius as
        0.10105, 30C, 30c, 30 c, 303.15 k, 303.15K, 303.15k
    [op_file = <string>]
        order parameter file. If not found, it will use the one from the input
        file
    [weights_file = <string>]
        weights file. If not found, the one from the input file will be used.

Observables/Pressure.h options:

    type = pressure
        an observable that computes the osmotic pressure of the system
    [stress_tensor = <bool>]
        if true, the output will contain 7 fields, with the first being the
        total pressure and the other 6 the six independent components of the
        stress tensor, xx, yy, zz, xy, xz, yz

Observables/HBEnergy.h options:

    [pairs_file = <string>]
        OrderParameter file containing the list of pairs whose HB energy is to
        be computed
    [base_file = <string>]
        file containing a list of nucleotides whose HB energy is to be
        computed, one nucleotide per line

Observables/Distance.h options:

    particle_1 = <int>
        index of the first particle
    particle_2 = <int>
        index of the second particle. The distance is returned as r(2) - r(1)
    [PBC = <bool>]
        Whether to honour PBC. Defaults to True
    [dir = <float>, <float>, <float>]
        vector to project the distance along. Beware that it gets normalized
        after reading. Defaults to (1, 1, 1) / sqrt(3)

Observables/ForceEnergy.h options:

    [print_group = <string>]
        limits the energy computation to the forces belonging to a specific
        group of forces. This can be set by adding a group_name option to each
        force's input. By default ForceEnergy computes the energy due to all
        the forces.

Observables/PotentialEnergy.h options:

    [split = <bool>]
        defaults to false, it tells the observable to print all the terms
        contributing to the potential energy

Observables/CoaxVariables.h options:

    particle1_id = <int>
        particle 1 id
    particle2_id = <int>
        particle 2 id

Observables/ObservableOutput.h options:

    name = <string>
        name of the output stream. stdout or stderr are accepted values
    print_every = <integer>
        frequency of output, in number steps for oxDNA, in number of
        configurations for DNAnalysis
    [start_from = <integer>]
        start outputing from the given step, defaults to 0
    [stop_at = <integer>]
        stop outputing at this step, defaults to -1 (which means never)
    [only_last = <bool>]
        if true, the output will not be appended to the stream, but it will
        overwrite the previous output each time, defaults to false
    [binary = <bool>]
        if true, the output will be printed in binary, defaults to false
    [linear = <bool>]
        if true the OutputObservable will save in linear scale, otherwise will
        use the logline scale by FS. Defaults to true
    [update_name_with_time = <bool>]
        if true the output filename will be changed by using the 'name' key as
        a prefix and the current step as a suffix. Defaults to false
    col_<n> = {
    type = name of the first observable
    [other observable options as lines of 'key = value']
    }
        this syntax specifies the column of the output file. Note that <n> is
        the column index and should start from 1

Observables/Rdf.h options:

    max_value = <float>
        maximum r to consider
    bin_size = <float>
        bin size for the g(r)
    [axes = <string>]
        Possible values: x, y, z, xy, yx, zy, yz, xz, zx. Those are the axes
        to consider in the computation. Mind that the normalization always
        assumes 3D sytems for the time being.

Observables/MeanVectorCosine.h options:

    chain_id = <int>
        chain id
    first_particle_position = <int>
        defaults to 0. position along the chain of  the first particle on
        which to compute the vector's cosine with the next particle
    last_particle_position = <int>
        defaults to N-2, where N is the number of elements of the chain.
        Position along the chain of the last particle over which to compute
        the vector's cosine with the next particle
    vector_to_average = <int>
        defaults to 1. Can be 1,2, or 3 depending on the vectors we wish to
        consider, or 0. In that case it measures the quantity (v2*v2')(v3*v3')
        - |v2 ^ v2||v3 ^ v3|

Observables/PairEnergy.h options:

    particle1_id = <int>
        particle 1 id
    particle2_id = <int>
        particle 2 id

Observables/Configurations/PdbOutput.h options:

    [back_in_box = <bool>]
        Default: true; if true the particle positions will be brought back in
        the box
    [show = <int>,<int>,...]
        Default: all particles; list of comma-separated indexes of the
        particles that will be shown. Other particles will not appear
    [hide = <int>,<int>,...]
        Default: no particles; list of comma-separated indexes of particles
        that will not be shown
    [ref_particle = <int>]
        Default: -1, no action; The nucleotide with the id specified (starting
        from 0) is set at the centre of the box. Overriden if ref_strands is
        specified. Ignored if negative or too large for the system.
    [ref_strand = <int>]
        Default: -1, no action; The strand with the id specified (starts from
        1) is set at the centre of the box. Ignored if negative or too large
        for the system.

Observables/Configurations/TclOutput.h options:

    [back_in_box = <bool>]
        Default: true; if true the particle positions will be brought back in
        the box
    [show = <int>,<int>,...]
        Default: all particles; list of comma-separated indexes of the
        particles that will be shown. Other particles will not appear
    [hide = <int>,<int>,...]
        Default: no particles; list of comma-separated indexes of particles
        that will not be shown
    [print_labels = <bool>]
        Default: false; if true labels with the strand id are printed next to
        one end of the strand.
    [resolution = <int>]
        Default: 20; resolution set in the tcl file.
    [ref_particle = <int>]
        Default: -1, no action; The nucleotide with the id specified (starting
        from 0) is set at the centre of the box. Overriden if ref_strands is
        specified. Ignored if negative or too large for the system.
    [ref_strand = <int>]
        Default: -1, no action; The strand with the id specified, starting
        from 1, is set at the centre of the box. Ignored if negative or too
        large for the system.

Observables/Configurations/Configuration.h options:

    [back_in_box = <bool>]
        if true the particle positions will be brought back in the box,
        defaults to false
    [show = <int>,<int>,...]
        list of comma-separated particle indexes whose positions will be put
        into the final configuration
    [hide = <int>,<int>,...]
        list of comma-separated particle indexes whose positions won't be put
        into the final configuration
    [reduced = <bool>]
        if true only the strand centres of mass will be printed, defaults to
        false

Observables/Configurations/ChimeraOutput.h options:

    [colour_by_sequece = <bool>]
        Default: false; whether to coulour the bases according to the base
        type (A, C, G, T

-------------------------------------------------------------------------------

Forward Flux Sampling (FFS) options:

    backend = CPU/CUDA
        For CPU FFS/For CUDA FFS -- NB unlike the CPU implementation, the CUDA
        implementation does not print extra columns with the current order
        parameter values whenever the energy is printed
    backend_precision = <any>/mixed
        CPU FFS may use any precision allowed for a normal CPU MD
        simulation/CUDA FFS is currently only implemented for mixed precision
    sim_type = FFS_MD
        This must be set for an FFS simulation
    order_parameters_file = <string>
        path to the order parameters file
    ffs_file = <string>
        path to the file with the simulation stopping conditions. Optionally,
        one may use 'master conditions' (CUDA FFS only), which allow one to
        more easily handle very high dimensional order parameters. See the
        EXAMPLES/CUDA_FFS/README file for more information
    [ffs_generate_flux = <bool>]
        CUDA FFS only. Default: False; if False, the simulation will run until
        a stopping condition is reached; if True, a flux generation simulation
        will be run, in which case reaching a condition will cause a
        configuration to be saved but will not terminate the simulation. In
        the stopping condition file, the conditions must be labelled forward1,
        forward2, ... (for the forward conditions); and backward1, backward2,
        ... (for the backward conditions), ... instead of condition1,
        condition2, ... . To get standard flux generation, set the forward and
        backward conditions to correspond to crossing the same interface (and
        use conditions corresponding to different interfaces for Tom's flux
        generation). As with the single shooting run mode, the name of the
        condition crossed will be printed to stderr each time.
    [gen_flux_save_every = <integer>]
        CUDA FFS only. Mandatory if ffs_generate_flux is True; save a
        configuration for 1 in every N forward crossings
    [gen_flux_total_crossings = <integer>]
        CUDA FFS only. Mandatory if ffs_generate_flux is True; stop the
        simulation after N crossings achieved
    [gen_flux_conf_prefix = <string>]
        CUDA FFS only. Mandatory if ffs_generate_flux is True; the prefix used
        for the file names of configurations corresponding to the saved
        forward crossings. Counting starts at zero so the 3rd crossing
        configuration will be saved as MY_PREFIX_N2.dat
    [gen_flux_debug = <bool>]
        CUDA FFS only. Default: False; In a flux generation simulation, set to
        true to save backward-crossing configurations for debugging
    [check_initial_state = <bool>]
        CUDA FFS only. Default: False; in a flux generation simulation, set to
        true to turn on initial state checking. In this mode an initial
        configuration that crosses the forward conditions after only 1 step
        will cause the code to complain and exit. Useful for checking that a
        flux generation simulation does not start out of the A-state
    [die_on_unexpected_master = <bool>]
        CUDA FFS only. Default: False; in a flux generation simulation that
        uses master conditions, set to true to cause the simulation to die if
        any master conditions except master_forward1 or master_backward1 are
        reached. Useful for checking that a flux generation simulation does
        not enter any unwanted free energy basins (i.e. other than the initial
        state and the desired final state)
    [unexpected_master_prefix = <string>]
        CUDA FFS only. Mandatory if die_on_unexpected_master is True; the
        prefix used for the file names of configurations corresponding to
        reaching any unexpected master conditions (see
        die_on_unexpected_master).

-------------------------------------------------------------------------------