Update documentation

_sources/forces.md.txt

@@ -232,6 +232,35 @@ The following snippet defines a repulsive sphere that acts on the first 50 nucle
 
 ````
 
+## Yukawa sphere
+
+This force encloses particle(s) in a sphere that interacts through a purely repulsive [WCA](http://www.sklogwiki.org/SklogWiki/index.php/Weeks-Chandler-Andersen_reference_system_model) potential complemented by a Yukawa potential of the form {math}`A \exp(-r / \lambda)`, where {math}`A` is the interaction strength (which can be either positive or negative), {math}`r` is the distance between a particle and the sphere surface, {math}`\lambda` is the Debye length. 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.
+* `radius = <float>`: radius of the sphere.
+* `debye_A = <float>`: Strength the Yukawa interaction.
+* `debye_length = <float>`: Debye length of the Yukawa interaction.
+* `WCA_epsilon = <float>`: strength of the WCA repulsion, defaults to `1`.
+* `WCA_sigma = <float>`: diameter of the WCA repulsion, defaults to `1`.
+* `WCA_n = <int>`: exponent of the WCA repulsion, defaults to `6`.
+* `[cutoff = <float>]`: cutoff of the interaction, defaults to four times the Debye length.
+* `[center = <float>,<float>,<float>]`: centre of the sphere, defaults to `0,0,0`.
+
+````{admonition} Example
+
+The following snippet defines a Yukawa sphere that acts on all nucleotides, confining them within a sphere of radius 5 centred in {math}`(0, 0, 10)`. The WCA parameters are set to their defaults, while the Debye length and strength are `5` and `-10`, respectively.
+
+	{
+	type = yukawa_sphere
+	radius = 5
+    center = 0,0,10
+	debye_length = 5
+	debye_A = -10
+	particle = all
+	}
+
+````
+
 ## `type = com`
 
     stiff = <float>

_sources/observables.md.txt

@@ -86,6 +86,11 @@ The following options are supported by all observabes:
 * `[id = <string>]`: a unique identifier that can be used to refer to this specific observable (see *e.g.* {meth}`~oxpy.core.ConfigInfo.get_observable_by_id`).
 * `[update_every = <int>]`: the number of time steps every which the observable is updated (but no output is printed). Note that this is supported only by some observables.
 
+The following options are supported by some observables, but we plan to extend their usage:
+
+* `[general_format = <bool>]`: print output numbers with the `printf`'s `%g` type field (see *e.g.* [here](https://stackoverflow.com/a/54162153/5140209) for details). Defaults to `false`.
+* `[precision = <int>]`: number of significant digits after decimal with which numbers should be printed. Defaults to 6.
+
 ## Simulation time
 
 Print the current simulation time as the number of steps or as molecular-dynamics time.

forces.html

@@ -63,6 +63,7 @@
 <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="#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>
 <li class="toctree-l2"><a class="reference internal" href="#type-lj-wall"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">LJ_wall</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="#type-sawtooth"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">sawtooth</span></code></a></li>
@@ -328,6 +329,35 @@ <h2>Repulsive sphere<a class="headerlink" href="#repulsive-sphere" title="Permal
 </div>
 </div>
 </section>
+<section id="yukawa-sphere">
+<h2>Yukawa sphere<a class="headerlink" href="#yukawa-sphere" title="Permalink to this heading"></a></h2>
+<p>This force encloses particle(s) in a sphere that interacts through a purely repulsive <a class="reference external" href="http://www.sklogwiki.org/SklogWiki/index.php/Weeks-Chandler-Andersen_reference_system_model">WCA</a> potential complemented by a Yukawa potential of the form <span class="math notranslate nohighlight">\(A \exp(-r / \lambda)\)</span>, where <span class="math notranslate nohighlight">\(A\)</span> is the interaction strength (which can be either positive or negative), <span class="math notranslate nohighlight">\(r\)</span> is the distance between a particle and the sphere surface, <span class="math notranslate nohighlight">\(\lambda\)</span> is the Debye length. 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">radius</span> <span class="pre">=</span> <span class="pre">&lt;float&gt;</span></code>: radius of the sphere.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">debye_A</span> <span class="pre">=</span> <span class="pre">&lt;float&gt;</span></code>: Strength the Yukawa interaction.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">debye_length</span> <span class="pre">=</span> <span class="pre">&lt;float&gt;</span></code>: Debye length of the Yukawa interaction.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">WCA_epsilon</span> <span class="pre">=</span> <span class="pre">&lt;float&gt;</span></code>: strength of the WCA repulsion, defaults to <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">WCA_sigma</span> <span class="pre">=</span> <span class="pre">&lt;float&gt;</span></code>: diameter of the WCA repulsion, defaults to <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">WCA_n</span> <span class="pre">=</span> <span class="pre">&lt;int&gt;</span></code>: exponent of the WCA repulsion, defaults to <code class="docutils literal notranslate"><span class="pre">6</span></code>.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">[cutoff</span> <span class="pre">=</span> <span class="pre">&lt;float&gt;]</span></code>: cutoff of the interaction, defaults to four times the Debye length.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">[center</span> <span class="pre">=</span> <span class="pre">&lt;float&gt;,&lt;float&gt;,&lt;float&gt;]</span></code>: centre of the sphere, defaults to <code class="docutils literal notranslate"><span class="pre">0,0,0</span></code>.</p></li>
+</ul>
+<div class="admonition-example admonition">
+<p class="admonition-title">Example</p>
+<p>The following snippet defines a Yukawa sphere that acts on all nucleotides, confining them within a sphere of radius 5 centred in <span class="math notranslate nohighlight">\((0, 0, 10)\)</span>. The WCA parameters are set to their defaults, while the Debye length and strength are <code class="docutils literal notranslate"><span class="pre">5</span></code> and <code class="docutils literal notranslate"><span class="pre">-10</span></code>, respectively.</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>{
+type = yukawa_sphere
+radius = 5
+center = 0,0,10
+debye_length = 5
+debye_A = -10
+particle = all
+}
+</pre></div>
+</div>
+</div>
+</section>
 <section id="type-com">
 <h2><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">com</span></code><a class="headerlink" href="#type-com" title="Permalink to this heading"></a></h2>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>stiff = &lt;float&gt;

index.html

@@ -164,6 +164,7 @@ <h1>oxDNA<a class="headerlink" href="#oxdna" title="Permalink to this heading">
 <li class="toctree-l2"><a class="reference internal" href="forces.html#rotating-harmonic-trap">Rotating harmonic trap</a></li>
 <li class="toctree-l2"><a class="reference internal" href="forces.html#repulsion-plane">Repulsion plane</a></li>
 <li class="toctree-l2"><a class="reference internal" href="forces.html#repulsive-sphere">Repulsive sphere</a></li>
+<li class="toctree-l2"><a class="reference internal" href="forces.html#yukawa-sphere">Yukawa sphere</a></li>
 <li class="toctree-l2"><a class="reference internal" href="forces.html#type-com"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">com</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="forces.html#type-lj-wall"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">LJ_wall</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="forces.html#type-sawtooth"><code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">sawtooth</span></code></a></li>

oat/api.html

@@ -222,7 +222,7 @@ <h2>Backbone flexibility<a class="headerlink" href="#backbone-flexibility" title
 </table>
 <dl class="py function">
 <dt class="sig sig-object py" id="oxDNA_analysis_tools.backbone_flexibility.backbone_flexibility">
-<span class="sig-prename descclassname"><span class="pre">oxDNA_analysis_tools.backbone_flexibility.</span></span><span class="sig-name descname"><span class="pre">backbone_flexibility</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">traj_info</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="utils.html#oxDNA_analysis_tools.UTILS.data_structures.TrajInfo" title="oxDNA_analysis_tools.UTILS.data_structures.TrajInfo"><span class="pre">TrajInfo</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">top_info</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="utils.html#oxDNA_analysis_tools.UTILS.data_structures.TopInfo" title="oxDNA_analysis_tools.UTILS.data_structures.TopInfo"><span class="pre">TopInfo</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">system</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="utils.html#oxDNA_analysis_tools.UTILS.data_structures.System" title="oxDNA_analysis_tools.UTILS.data_structures.System"><span class="pre">System</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">ncpus</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Tuple" title="(in Python v3.12)"><span class="pre">Tuple</span></a><span class="p"><span class="pre">[</span></span><span class="pre">array</span><span class="p"><span class="pre">]</span></span></span></span><a class="headerlink" href="#oxDNA_analysis_tools.backbone_flexibility.backbone_flexibility" title="Permalink to this definition"></a></dt>
+<span class="sig-prename descclassname"><span class="pre">oxDNA_analysis_tools.backbone_flexibility.</span></span><span class="sig-name descname"><span class="pre">backbone_flexibility</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">traj_info</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="utils.html#oxDNA_analysis_tools.UTILS.data_structures.TrajInfo" title="oxDNA_analysis_tools.UTILS.data_structures.TrajInfo"><span class="pre">TrajInfo</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">top_info</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="utils.html#oxDNA_analysis_tools.UTILS.data_structures.TopInfo" title="oxDNA_analysis_tools.UTILS.data_structures.TopInfo"><span class="pre">TopInfo</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">system</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="utils.html#oxDNA_analysis_tools.UTILS.data_structures.System" title="oxDNA_analysis_tools.UTILS.data_structures.System"><span class="pre">System</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">ncpus</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Tuple" title="(in Python v3.12)"><span class="pre">Tuple</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v1.26)"><span class="pre">ndarray</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v1.26)"><span class="pre">ndarray</span></a><span class="p"><span class="pre">]</span></span></span></span><a class="headerlink" href="#oxDNA_analysis_tools.backbone_flexibility.backbone_flexibility" title="Permalink to this definition"></a></dt>
 <dd><p>Calculate backbone flexibility of a trajectory.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>

oat/cli.html

@@ -897,8 +897,8 @@ <h3>Named Arguments<a class="headerlink" href="#Named Arguments" title="Permalin
 <h2>oxDNA -&gt; PDB<a class="headerlink" href="#oxdna-pdb" title="Permalink to this heading"></a></h2>
 <p><p>Convert oxDNA files to PDB.  This converter can handle oxDNANM protein simulation files.</p>
 </p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">usage</span><span class="p">:</span> <span class="n">oat</span> <span class="n">oxDNA_PDB</span> <span class="p">[</span><span class="o">-</span><span class="n">h</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">o</span> <span class="n">OUTPUT</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">d</span> <span class="n">OUTPUT_DIRECTION</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">H</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">u</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
-                     <span class="p">[</span><span class="o">-</span><span class="n">r</span> <span class="n">RMSF_BFACTOR</span><span class="p">]</span>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">usage</span><span class="p">:</span> <span class="n">oat</span> <span class="n">oxDNA_PDB</span> <span class="p">[</span><span class="o">-</span><span class="n">h</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">o</span> <span class="n">OUTPUT</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">d</span> <span class="n">OUTPUT_DIRECTION</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">q</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">H</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">u</span><span class="p">]</span>
+                     <span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">r</span> <span class="n">RMSF_BFACTOR</span><span class="p">]</span>
                      <span class="n">topology</span> <span class="n">configuration</span> <span class="n">direction</span> <span class="p">[</span><span class="n">pdbfiles</span> <span class="o">...</span><span class="p">]</span>
 </pre></div>
 </div>
@@ -928,6 +928,10 @@ <h3>Named Arguments<a class="headerlink" href="#Named Arguments" title="Permalin
 <dt><kbd>-d, --output_direction</kbd></dt>
 <dd><p>Direction to save nucleic acid strands in.  Should be “53” or “35”.  Defaults to same as input direction.</p>
 </dd>
+<dt><kbd>-q</kbd></dt>
+<dd><p>Don’t print ‘INFO’ messages to stderr</p>
+<p>Default: False</p>
+</dd>
 <dt><kbd>-H, --hydrogen</kbd></dt>
 <dd><p>if you want to include hydrogen atoms in the output PDB file</p>
 <p>Default: True</p>