Update documentation

_sources/forces.md.txt

@@ -205,11 +205,45 @@ The following snippet defines a plane that acts on the whole system and will not
 
 ````
 
+## Attraction plane
+
+This kind of external force implements an attraction plane that attracts particles towards the plane with a constant force component while constraining them to stay on one side using a repulsive force component (compare repulsion plane).
+The repulsion is implemented as a harmonic interaction, but the stiffness can be made arbitrarily high to mimic a hard repulsion.
+The attraction is implemented as a constant force defined as: stiffness * a, where a = 1 units of length.
+Both attractive and repulsive component use the same stiffness value.
+
+A force of this kind is specified with `type = attraction_plane`. The relevant keys are:
+
+* `particle = <int>`: comma-separated list of indices of particles to apply the force to. A value of `-1` or `all` applies it to all particles. Entries separated by a dash "-" get expanded in a list of all the particles on a same strand comprised between the two indices. For instance, `particle = 1,2,5-7` applies the force to 1,2,5,6,7 if 5 and 7 are on the same strand.
+* `stiff = <float>`: stiffness of the repulsion and strength of the attraction.
+* `dir = <float>,<float>,<float>`: the vector normal to the plane: it should point towards the half-plane where the attraction is not acting.
+* `position = <float>`: defines the position of the plane along the direction identified by the plane normal.
+
+If direction is `dir`{math}`=(u,v,w)`, then the plane contains all the points {math}`(x,y,z)` that satisfy the equation: {math}`u x + v y + w z + {\rm position} = 0`.
+Nucleotides with coordinates {math}`(x,y,z)` that satisfy {math}`u x + v y + w z + {\rm position} \ge 0` will feel a constant attraction force towards the plane equal to `stiff`.
+Nucleotides with coordinates {math}`(x,y,z)` that satisfy {math}`u x + v y + w z + {\rm position} \lt 0` will feel a repulsion force equal to `stiff` \* *D*, where {math}`D = | ux + vy + wz + \mbox{position}| / \sqrt{u^2 + v^2 + w^2 }` is the distance of the nucleotide from the plane.
+
+````{admonition} Example
+
+The following snippet defines an attraction plane that acts on on all nucleotides, pulling them towards the YZ plane (x-direction at origin).
+Particles with a positive x-coordinate are pulled towards the YZ plane by a constant force of 1 simulation unit \* x (48.6 pN \* x for DNA)
+A restoring force proportional to 1 simulation unit \* x (48.6 pN \* x for DNA) is exerted on all particles with a negative x-coordinate, constraining them at the plane.
+
+    {
+    type = attraction_plane
+    particle = -1
+    stiff = 1.00
+    dir = 1, 0, 0
+    position = 0
+    }
+
+````
+
 ## Repulsive sphere
 
 This force encloses particle(s) in a repulsive sphere. The repulsion force is harmonic.
 
-A force of this kind is specified with `type = sphere`. The relevant keys are: 
+A force of this kind is specified with `type = sphere`. The relevant keys are:
 
 * `particle = <int>`: comma-separated list of indices of particles to apply the force to. A value of `-1` or `all` applies it to all particles. Entries separated by a dash "-" get expanded in a list of all the particles on a same strand comprised between the two indices. For instance, `particle = 1,2,5-7` applies the force to 1,2,5,6,7 if 5 and 7 are on the same strand.
 * `stiff = <float>`: stiffness of the repulsion.

_sources/index.md.txt

@@ -1,15 +1,33 @@
 # oxDNA
 
-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. 
+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. The following nucleic-acid-related force fields are implemented:
 
-oxDNA can perform both molecular dynamics (MD) and Monte Carlo (MC) simulations of the oxDNA and oxRNA models. MD simulations can be run on single CPUs or single CUDA-enabled GPUs, while MC simulations, which can only be run serially, can exploit the Virtual Move Monte Carlo algorithm to greatly speed-up equilibration and sampling, and Umbrella Sampling biasing to efficiently obtain free-energy profiles. The package also features a Forward-Flux Sampling interface to study the kinetics of rare events, and makes it possible to alter the behaviour of the systems by adding *external forces* that can be used, for instance, to pull on or apply torques to strands or confine nucleotides within semi-planes or spheres.
+* [oxDNA1](https://pubs.aip.org/aip/jcp/article-abstract/137/13/135101/191221/Sequence-dependent-thermodynamics-of-a-coarse?redirectedFrom=fulltext)
+* [oxDNA2](https://pubs.aip.org/aip/jcp/article-abstract/142/23/234901/193554/Introducing-improved-structural-properties-and?redirectedFrom=fulltext)
+* [oxRNA](https://pubs.aip.org/aip/jcp/article-abstract/140/23/235102/73414/A-nucleotide-level-coarse-grained-model-of-RNA?redirectedFrom=fulltext)
+* [oxNA](https://pubs.aip.org/aip/jcp/article/160/11/115101/3275728)
 
-The package also includes `oxpy`, a Python library which makes it possible to control the behavior of the simulation using Python scripts. The repository contains examples that demonstrate how to leverage `oxpy` to write backends to run replica-exchange and well-tempered metadynamics simulations, which are popular techniques in modern molecular dynamics to improve sampling efficiency.
+oxDNA can perform both molecular dynamics (MD) and Monte Carlo (MC) simulations of the oxDNA and oxRNA models. MD simulations can be run on single CPUs or single CUDA-enabled GPUs, while MC simulations, which can only be run serially, can exploit the Virtual Move Monte Carlo algorithm to greatly speed-up equilibration and sampling, and [Umbrella Sampling biasing](umbrella_sampling.md) to efficiently obtain free-energy profiles. The package also features a [Forward-Flux Sampling interface](ffs.md) to study the kinetics of rare events, and makes it possible to alter the behaviour of the systems by adding [*external forces*](forces.md) that can be used, for instance, to pull on or apply torques to strands or confine nucleotides within semi-planes or spheres.
 
-The package can also be used to compute nucleic-acid-related quantities such as the energy due to hydrogen bonding or stacking, the distance between groups of nucleotides, the list of hydrogen-bonded nucleotides or of over-stretched bonds, and much more. The analysis can be performed while the simulation is running or on generated trajectory files.
+The package also includes [the `oxpy` Python module](oxpy/index.md), which makes it possible to control the behavior of the simulation using Python scripts. The repository contains examples that demonstrate how to leverage `oxpy` to write backends to run replica-exchange and well-tempered metadynamics simulations, which are popular techniques in modern molecular dynamics to improve sampling efficiency.
+
+The package can be used to compute [nucleic-acid-related quantities](observables.md) such as the energy due to hydrogen bonding or stacking, the distance between groups of nucleotides, the list of hydrogen-bonded nucleotides or of over-stretched bonds, and much more. The analysis can be performed while the simulation is running or on generated trajectory files.
 
 The simulation engine is complemented by an updated version of `oxDNA_analysis_tools` (`oat`), a Python library aimed at facilitating the analysis of oxDNA/oxRNA trajectories. `Oat` provides numerous common simulation trajectory analysis tools including alignment, mean structures, subsetting trajectories, distances between nucleotides, interduplex angles, and comparisons in hydrogen bonding patterns between the trajectory and an idealized structure.
 
+## Citing oxDNA
+
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.04693/status.svg)](https://doi.org/10.21105/joss.04693)
+
+Please cite these publications for any work that uses the oxDNA simulation package:
+
+- for the code:
+  * [E. Poppleton et al., J. Open Source Softw. 8, 4693 (2023)](https://doi.org/10.21105/joss.04693)
+- for the CUDA-powered code:
+  * [L. Rovigatti et al., J. Comput. Chem. 36, 1 (2015)](https://doi.org/10.1002/jcc.23763)
+- for oxDNA analysis tools:
+  * [E. Poppleton et al., Nucleic Acids Research e72 (2020)](https://doi.org/10.1093/nar/gkab324)
+
 ```{eval-rst}
 .. toctree::
    :caption: Table of Contents

_sources/install.md.txt

@@ -26,7 +26,7 @@ make -j4         # compile oxDNA. The -jX make option makes it compile the code
 
 At the end of the compilation three executables (*oxDNA*, *DNAnalysis* and *confGenerator*) will be placed in the `build/bin` directory. 
 
-Compiling with Python bindings will also generate an `oxpy` package in the `build/oxpy` directory that can be imported in Python. Running `make install` will attempt to copy the package (as well as `oxDNA_analysis_tools`) to the `pip`'s module directory. The specific location will depend on your system's settings. We advise you to use [virtual environments](https://docs.python.org/3/tutorial/venv.html) (see *e.g.* [pipenv](https://docs.pipenv.org/)) to avoid conflicts with other packages and/or dependency and permission issues.
+Compiling with Python bindings will also generate an `oxpy` package in the `build/oxpy` directory that can be imported in Python. Running `make install` will attempt to copy the package (as well as `oxDNA_analysis_tools`) to the `pip`'s module directory. The specific location will depend on your system's settings. We advise you to use [virtual environments](https://docs.python.org/3/tutorial/venv.html) (see *e.g.* [pipenv](https://docs.pipenv.org/) or [conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html)) to avoid conflicts with other packages and/or dependency and permission issues.
 
 ### Updating a local copy
 

_sources/oat/api.md.txt

@@ -266,6 +266,7 @@ decimate(align_output, decimate_output, ncpus=5, start=200, stride=10)
 ```
 
 ## File info
+
 ```{eval-rst}
 .. toctree::
    :maxdepth: 2
@@ -280,6 +281,22 @@ decimate(align_output, decimate_output, ncpus=5, start=200, stride=10)
 .. autofunction:: oxDNA_analysis_tools.file_info.file_info
 ```
 
+## Forces to dot-bracket
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 2
+
+.. currentmodule:: oxDNA_analysis_tools
+
+.. autosummary::
+    :nosignatures:
+
+    oxDNA_analysis_tools.forces2db.forces2db
+
+.. autofunction:: oxDNA_analysis_tools.forces2db.forces2db
+```
+
 ## Mean
 
 ```{eval-rst}
@@ -346,6 +363,38 @@ decimate(align_output, decimate_output, ncpus=5, start=200, stride=10)
 .. autofunction:: oxDNA_analysis_tools.output_bonds.output_bonds
 ```
 
+## OxDNA to PDB
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 2
+
+.. currentmodule:: oxDNA_analysis_tools
+
+.. autosummary::
+    :nosignatures:
+
+    oxDNA_analysis_tools.oxDNA_PDB.oxDNA_PDB
+
+.. autofunction:: oxDNA_analysis_tools.oxDNA_PDB.oxDNA_PDB
+```
+
+## Pairs to dot-bracket
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 2
+
+.. currentmodule:: oxDNA_analysis_tools
+
+.. autosummary::
+    :nosignatures:
+
+    oxDNA_analysis_tools.pairs2db.pairs2db
+
+.. autofunction:: oxDNA_analysis_tools.pairs2db.pairs2db
+```
+
 ## Principle component analysis
 
 ```{eval-rst}

_sources/oat/cli.md.txt

@@ -133,6 +133,14 @@
     :prog: oat file_info
 ```
 
+## Forces to dot-bracket
+```{eval-rst}
+.. argparse::
+    :filename: ../analysis/src/oxDNA_analysis_tools/forces2db.py
+    :func: cli_parser
+    :prog: oat forces2db
+```
+
 ## Forces to pairs
 
 ```{eval-rst}
@@ -196,6 +204,14 @@
     :prog: oat oxDNA_PDB
 ```
 
+## Pairs to dot-bracket
+```{eval-rst}
+.. argparse::
+    :filename: ../analysis/src/oxDNA_analysis_tools/pairs2db.py
+    :func: cli_parser
+    :prog: oat pairs2db
+```
+
 ## Principal component analysis
 
 ```{eval-rst}

_sources/oat/forces.md.txt

@@ -17,13 +17,15 @@ Python data structures for all forces defined by oxDNA
     oxDNA_analysis_tools.external_force_utils.forces.harmonic_trap
     oxDNA_analysis_tools.external_force_utils.forces.rotating_harmonic_trap
     oxDNA_analysis_tools.external_force_utils.forces.repulsion_plane
+    oxDNA_analysis_tools.external_force_utils.forces.attraction_plane
     oxDNA_analysis_tools.external_force_utils.forces.repulsion_sphere
 
 .. autofunction:: oxDNA_analysis_tools.external_force_utils.forces.mutual_trap
 .. autofunction:: oxDNA_analysis_tools.external_force_utils.forces.string
 .. autofunction:: oxDNA_analysis_tools.external_force_utils.forces.harmonic_trap
 .. autofunction:: oxDNA_analysis_tools.external_force_utils.forces.rotating_harmonic_trap
 .. autofunction:: oxDNA_analysis_tools.external_force_utils.forces.repulsion_plane
+.. autofunction:: oxDNA_analysis_tools.external_force_utils.forces.attraction_plane
 .. autofunction:: oxDNA_analysis_tools.external_force_utils.forces.repulsion_sphere
 ```
 

forces.html

@@ -62,6 +62,7 @@
 <li class="toctree-l2"><a class="reference internal" href="#harmonic-trap">Harmonic trap</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#rotating-harmonic-trap">Rotating harmonic trap</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#repulsion-plane">Repulsion plane</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#attraction-plane">Attraction plane</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#repulsive-sphere">Repulsive sphere</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#yukawa-sphere">Yukawa sphere</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#type-com"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">com</span></code></a></li>
@@ -303,6 +304,38 @@ <h2>Repulsion plane<a class="headerlink" href="#repulsion-plane" title="Permalin
 </div>
 </div>
 </section>
+<section id="attraction-plane">
+<h2>Attraction plane<a class="headerlink" href="#attraction-plane" title="Permalink to this heading"></a></h2>
+<p>This kind of external force implements an attraction plane that attracts particles towards the plane with a constant force component while constraining them to stay on one side using a repulsive force component (compare repulsion plane).
+The repulsion is implemented as a harmonic interaction, but the stiffness can be made arbitrarily high to mimic a hard repulsion.
+The attraction is implemented as a constant force defined as: stiffness * a, where a = 1 units of length.
+Both attractive and repulsive component use the same stiffness value.</p>
+<p>A force of this kind is specified with <code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">attraction_plane</span></code>. The relevant keys are:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">particle</span> <span class="pre">=</span> <span class="pre">&lt;int&gt;</span></code>: comma-separated list of indices of particles to apply the force to. A value of <code class="docutils literal notranslate"><span class="pre">-1</span></code> or <code class="docutils literal notranslate"><span class="pre">all</span></code> applies it to all particles. Entries separated by a dash “-” get expanded in a list of all the particles on a same strand comprised between the two indices. For instance, <code class="docutils literal notranslate"><span class="pre">particle</span> <span class="pre">=</span> <span class="pre">1,2,5-7</span></code> applies the force to 1,2,5,6,7 if 5 and 7 are on the same strand.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">stiff</span> <span class="pre">=</span> <span class="pre">&lt;float&gt;</span></code>: stiffness of the repulsion and strength of the attraction.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">dir</span> <span class="pre">=</span> <span class="pre">&lt;float&gt;,&lt;float&gt;,&lt;float&gt;</span></code>: the vector normal to the plane: it should point towards the half-plane where the attraction is not acting.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">position</span> <span class="pre">=</span> <span class="pre">&lt;float&gt;</span></code>: defines the position of the plane along the direction identified by the plane normal.</p></li>
+</ul>
+<p>If direction is <code class="docutils literal notranslate"><span class="pre">dir</span></code><span class="math notranslate nohighlight">\(=(u,v,w)\)</span>, then the plane contains all the points <span class="math notranslate nohighlight">\((x,y,z)\)</span> that satisfy the equation: <span class="math notranslate nohighlight">\(u x + v y + w z + {\rm position} = 0\)</span>.
+Nucleotides with coordinates <span class="math notranslate nohighlight">\((x,y,z)\)</span> that satisfy <span class="math notranslate nohighlight">\(u x + v y + w z + {\rm position} \ge 0\)</span> will feel a constant attraction force towards the plane equal to <code class="docutils literal notranslate"><span class="pre">stiff</span></code>.
+Nucleotides with coordinates <span class="math notranslate nohighlight">\((x,y,z)\)</span> that satisfy <span class="math notranslate nohighlight">\(u x + v y + w z + {\rm position} \lt 0\)</span> will feel a repulsion force equal to <code class="docutils literal notranslate"><span class="pre">stiff</span></code> * <em>D</em>, where <span class="math notranslate nohighlight">\(D = | ux + vy + wz + \mbox{position}| / \sqrt{u^2 + v^2 + w^2 }\)</span> is the distance of the nucleotide from the plane.</p>
+<div class="admonition-example admonition">
+<p class="admonition-title">Example</p>
+<p>The following snippet defines an attraction plane that acts on on all nucleotides, pulling them towards the YZ plane (x-direction at origin).
+Particles with a positive x-coordinate are pulled towards the YZ plane by a constant force of 1 simulation unit * x (48.6 pN * x for DNA)
+A restoring force proportional to 1 simulation unit * x (48.6 pN * x for DNA) is exerted on all particles with a negative x-coordinate, constraining them at the plane.</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>{
+type = attraction_plane
+particle = -1
+stiff = 1.00
+dir = 1, 0, 0
+position = 0
+}
+</pre></div>
+</div>
+</div>
+</section>
 <section id="repulsive-sphere">
 <h2>Repulsive sphere<a class="headerlink" href="#repulsive-sphere" title="Permalink to this heading"></a></h2>
 <p>This force encloses particle(s) in a repulsive sphere. The repulsion force is harmonic.</p>