See cclib/cclib@a964332 from refs/heads/master

Author: cclib

_sources/data_notes.rst.txt

@@ -513,6 +513,18 @@ optdone
 
 A list that indexes which elements of `atomcoords`_ represent converged geometries.
 
+optstatus
+---------
+
+A list of integers representing the status of each step in an optimisation. The possible optimisation statuses are defined in bit value notation to allow for coding for multiple states and are given by:
+
+    * ``OPT_UNKNOWN = 0b000 = 0`` is the default and means optimisation is in progress.
+    * ``OPT_NEW = 0b001 = 1`` is set for every new optimisation (e.g. PES, IRCs, etc.)
+    * ``OPT_DONE = 0b010 = 2`` is set for the last step of an optimisation that converged.
+    * ``OPT_UNCONVERGED = 0b100 = 4`` is set for every unconverged step (e.g. should be mutually exclusive with ``OPT_DONE``)
+
+So, to robustly check if step ``i`` has converged, one should check ``data.optstatus[i] & OPT_DONE`` instead of ``data.optstatus[i] == OPT_DONE``.
+
 scancoords
 ----------
 

contents.html

@@ -150,6 +150,7 @@
 <li class="toctree-l2"><a class="reference internal" href="data_notes.html#nmo">nmo</a></li>
 <li class="toctree-l2"><a class="reference internal" href="data_notes.html#nmrtensors">nmrtensors</a></li>
 <li class="toctree-l2"><a class="reference internal" href="data_notes.html#optdone">optdone</a></li>
+<li class="toctree-l2"><a class="reference internal" href="data_notes.html#optstatus">optstatus</a></li>
 <li class="toctree-l2"><a class="reference internal" href="data_notes.html#scancoords">scancoords</a></li>
 <li class="toctree-l2"><a class="reference internal" href="data_notes.html#scanenergies">scanenergies</a></li>
 <li class="toctree-l2"><a class="reference internal" href="data_notes.html#scannames">scannames</a></li>

data_notes.html

@@ -91,6 +91,7 @@
 <li class="toctree-l2"><a class="reference internal" href="#nmo">nmo</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#nmrtensors">nmrtensors</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#optdone">optdone</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#optstatus">optstatus</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#scancoords">scancoords</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#scanenergies">scanenergies</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#scannames">scannames</a></li>
@@ -607,6 +608,19 @@ <h2>nmrtensors<a class="headerlink" href="#nmrtensors" title="Link to this headi
 <h2>optdone<a class="headerlink" href="#optdone" title="Link to this heading"></a></h2>
 <p>A list that indexes which elements of <a class="reference internal" href="#atomcoords">atomcoords</a> represent converged geometries.</p>
 </section>
+<section id="optstatus">
+<h2>optstatus<a class="headerlink" href="#optstatus" title="Link to this heading"></a></h2>
+<p>A list of integers representing the status of each step in an optimisation. The possible optimisation statuses are defined in bit value notation to allow for coding for multiple states and are given by:</p>
+<blockquote>
+<div><ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">OPT_UNKNOWN</span> <span class="pre">=</span> <span class="pre">0b000</span> <span class="pre">=</span> <span class="pre">0</span></code> is the default and means optimisation is in progress.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">OPT_NEW</span> <span class="pre">=</span> <span class="pre">0b001</span> <span class="pre">=</span> <span class="pre">1</span></code> is set for every new optimisation (e.g. PES, IRCs, etc.)</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">OPT_DONE</span> <span class="pre">=</span> <span class="pre">0b010</span> <span class="pre">=</span> <span class="pre">2</span></code> is set for the last step of an optimisation that converged.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">OPT_UNCONVERGED</span> <span class="pre">=</span> <span class="pre">0b100</span> <span class="pre">=</span> <span class="pre">4</span></code> is set for every unconverged step (e.g. should be mutually exclusive with <code class="docutils literal notranslate"><span class="pre">OPT_DONE</span></code>)</p></li>
+</ul>
+</div></blockquote>
+<p>So, to robustly check if step <code class="docutils literal notranslate"><span class="pre">i</span></code> has converged, one should check <code class="docutils literal notranslate"><span class="pre">data.optstatus[i]</span> <span class="pre">&amp;</span> <span class="pre">OPT_DONE</span></code> instead of <code class="docutils literal notranslate"><span class="pre">data.optstatus[i]</span> <span class="pre">==</span> <span class="pre">OPT_DONE</span></code>.</p>
+</section>
 <section id="scancoords">
 <h2>scancoords<a class="headerlink" href="#scancoords" title="Link to this heading"></a></h2>
 <p>An array containing the geometries for each step of shape <code class="docutils literal notranslate"><span class="pre">[number</span> <span class="pre">of</span> <span class="pre">scan</span> <span class="pre">steps,</span> <span class="pre">number</span> <span class="pre">of</span> <span class="pre">atoms,</span> <span class="pre">3]</span></code>. In the case of an unrelaxed scan this is equivalent to <a class="reference internal" href="#atomcoords">atomcoords</a>, however this is not the case for a relaxed scan as a geometry optimization is performed at each scan step.</p>