/usr/share/doc/psi4/html/plugins.html is in psi4-data 1:0.3-5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Plugins: Adding New Functionality to Psi4 — Psi4 [] Docs</title>
<link rel="stylesheet" href="_static/psi4.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="./" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/jquery.cookie.js"></script>
<script type="text/javascript" src="_static/toggle_sections.js"></script>
<script type="text/javascript" src="_static/toggle_sidebar.js"></script>
<script type="text/javascript" src="_static/toggle_codeprompt.js"></script>
<link rel="shortcut icon" href="_static/favicon-psi4.ico"/>
<link rel="top" title="Psi4 [] Docs" href="index.html" />
<link rel="up" title="Contributions: Intro to Programming in Psi4" href="contributing.html" />
<link rel="next" title="Best Practices for Python Functions" href="bestpractices_py.html" />
<link rel="prev" title="Contributions: Intro to Programming in Psi4" href="contributing.html" />
</head>
<body role="document">
<div class="relbar-top">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> </li>
<li class="right" >
<a href="contents.html" title="Table Of Contents"
accesskey="C">toc</a> </li>
<li class="right" >
<a href="bestpractices_py.html" title="Best Practices for Python Functions"
accesskey="N">next</a> </li>
<li class="right" >
<a href="contributing.html" title="Contributions: Intro to Programming in Psi4"
accesskey="P">previous</a> </li>
<li><a href="index.html">Psi4 []</a> » </li>
<li class="nav-item nav-item-1"><a href="contributing.html" accesskey="U">Contributions: Intro to Programming in <span class="sc">Psi4</span></a> »</li>
</ul>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<a class="reference internal image-reference" href="_images/psi4banner.png"><img alt="Psi4 Project Logo" src="_images/psi4banner.png" style="width: 100%;" /></a>
<div class="section" id="plugins-adding-new-functionality-to-psifour">
<span id="sec-plugins"></span><h1>Plugins: Adding New Functionality to <span class="sc">Psi4</span><a class="headerlink" href="#plugins-adding-new-functionality-to-psifour" title="Permalink to this headline">¶</a></h1>
<div class="section" id="modular-approach-to-development">
<h2>Modular Approach to Development<a class="headerlink" href="#modular-approach-to-development" title="Permalink to this headline">¶</a></h2>
<p>The redesign of <span class="sc">Psi4</span> into a single-executable changed the way that
code development is done. The standalone nature of modules in previous
versions of Psi made their development very easy, as new functionality
could be implemented almost as a standalone executable, which could easily
be ported into the Psi code when completed. The new design specifies that
these modules are now libraries, not separate executables, which are
linked into the main Psi executable. The single-executable design is
conducive to code reuse, as it allows common tasks to be implemented as a
class instead of a module; the functionality can then be easily obtained
throughout the code by creating objects as required. Examples of this are
the LibMints class, which provides similar functionality to the old cints
module, and LibTrans, which replaces the old transqt code. When codes are
wrapped in a library, they should be placed into <a class="reference external" href="https://github.com/psi4/psi4public/blob/master/src/lib">psi4/src/lib</a>, and
codes that resemble modules belong in <a class="reference external" href="https://github.com/psi4/psi4public/blob/master/src/bin">psi4/src/bin</a>.</p>
<p>The single-executable design leads to a somewhat cumbersome development
cycle, since every time a change is made, one must compile the code,
archive it into a library, and then re-link the code into the main
executable. It’s also daunting to new developers if they’re required to
learn the structure of the source tree, executable initialization code,
and makefile systems in the existing code in order to add new features,
which was never a problem with previous versions due to the independent
nature of the modules. To overcome these problems, <span class="sc">Psi4</span> now has a
useful plugin feature. This allows codes to be developed as standalone
entities, which are compiled independently of the Psi source, but can
still link against Psi’s vast library. The plugins can be loaded at
run-time from any location. To be able to use plugins, you should compile
your source code with the <code class="docutils literal"><span class="pre">--with-plugins</span></code> flag passed to configure;
this will enable loading of plugins at runtime.</p>
</div>
<div class="section" id="creating-a-new-plugin">
<h2>Creating a New Plugin<a class="headerlink" href="#creating-a-new-plugin" title="Permalink to this headline">¶</a></h2>
<p><span class="sc">Psi4</span> can create basic plugins for you and automatically tailor them
to your compilation environment. To create a basic plugin, run the
following while replacing <code class="docutils literal"><span class="pre">myplugin</span></code> with the name of your great code.
If the name you provide is not valid, <span class="sc">Psi4</span> will complain.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">psi4</span> <span class="o">--</span><span class="n">new</span><span class="o">-</span><span class="n">plugin</span> <span class="n">myplugin</span>
</pre></div>
</div>
<p><span class="sc">Psi4</span> will create a new directory with the name you specify for the
plugin. In this example, a directory named myplugin will be created.</p>
<p>All you need to do is cd into the directory and type make. Then execute
psi4 in the directory on the default input file.</p>
<p><span class="sc">Psi4</span> comes with a few templates that provide an excellent starting
point. These include code that demonstrates AO, MO, and SO integrals. Use
one of the following commands that meets your needs:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">psi4</span> <span class="o">--</span><span class="n">new</span><span class="o">-</span><span class="n">plugin</span> <span class="n">myplugin</span> <span class="o">+</span><span class="n">aointegrals</span>
<span class="gp">>>> </span><span class="n">psi4</span> <span class="o">--</span><span class="n">new</span><span class="o">-</span><span class="n">plugin</span> <span class="n">myplugin</span> <span class="o">+</span><span class="n">mointegrals</span>
<span class="gp">>>> </span><span class="n">psi4</span> <span class="o">--</span><span class="n">new</span><span class="o">-</span><span class="n">plugin</span> <span class="n">myplugin</span> <span class="o">+</span><span class="n">sointegrals</span>
<span class="gp">>>> </span><span class="n">psi4</span> <span class="o">--</span><span class="n">new</span><span class="o">-</span><span class="n">plugin</span> <span class="n">myplugin</span> <span class="o">+</span><span class="n">wavefunction</span>
<span class="gp">>>> </span><span class="n">psi4</span> <span class="o">--</span><span class="n">new</span><span class="o">-</span><span class="n">plugin</span> <span class="n">myplugin</span> <span class="o">+</span><span class="n">scf</span>
</pre></div>
</div>
<p>Several stable sample plugin directories are available to consult in the
<a class="reference external" href="https://github.com/psi4/psi4public/blob/master/plugins">psi4/plugins</a> directory. Other plugin directories can be used as models
but are in active development. For documentation on plugin modules, see
<span class="xref std std-ref">Available Plugins</span>.</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/psi4/psi4public/blob/master/plugins/aointegrals/aointegrals.cc">psi4/plugins/aointegrals/aointegrals.cc</a>
An example that uses the LibMints library to generate and print AO basis (no symmetry) integrals.</li>
<li><a class="reference external" href="https://github.com/psi4/psi4public/blob/master/plugins/backtrans/backtrans.cc">psi4/plugins/backtrans/backtrans.cc</a>
A test of the one- and two-particle density matrix backtransformation code.</li>
<li><a class="reference external" href="https://github.com/psi4/psi4public/blob/master/plugins/mointegrals/mointegrals.cc">psi4/plugins/mointegrals/mointegrals.cc</a>
An example that uses the LibTrans library to generate and print MO basis integrals.</li>
<li><a class="reference external" href="https://github.com/psi4/psi4public/blob/master/plugins/mollerplesset2/mp2.cc">psi4/plugins/mollerplesset2/mp2.cc</a>
A plugin that uses LibTrans to generate open- and closed-shell MP2 energies.</li>
<li><a class="reference external" href="https://github.com/psi4/psi4public/blob/master/plugins/sointegrals/sointegrals.cc">psi4/plugins/sointegrals/sointegrals.cc</a>
An example that uses the LibMints library to generate and print SO basis (with symmetry) integrals.</li>
</ul>
</div>
<div class="section" id="files-in-a-plugin-directory">
<h2>Files in a Plugin Directory<a class="headerlink" href="#files-in-a-plugin-directory" title="Permalink to this headline">¶</a></h2>
<p>In addition to the main <code class="docutils literal"><span class="pre">myplugin.cc</span></code> file, a fresh plugin directory contains the following files</p>
<ul>
<li><p class="first"><strong>Makefile</strong> — Makefile for the directory. As long as you are the
only user of the plugin, this should not need editing. After any change to
the plugin C++ code, <code class="docutils literal"><span class="pre">make</span></code> must be run in the plugin directory to
recompile the <code class="docutils literal"><span class="pre">myplugin.so</span></code> executable, but recompiling the main
<span class="sc">Psi4</span> code is not necessary. (<span class="sc">Psi4</span> must have originally been
compiled with configure directive <code class="docutils literal"><span class="pre">--with-plugins</span></code>.)</p>
</li>
<li><p class="first"><strong>input.dat</strong> — Sample input file for the plugin.
Since the <code class="docutils literal"><span class="pre">__init__.py</span></code> file makes the plugin directory look like a
Python module, the plugin can be treated as such in an input file. The
location of the plugin directory must be included in <span class="target" id="index-0"></span><a class="reference internal" href="external.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal"><span class="pre">PYTHONPATH</span></code></a>,
either externally in the calling shell or defined in the input file.
This is usually done by manipulating <span class="target" id="index-1"></span><a class="reference internal" href="external.html#envvar-PSIPATH"><code class="xref std std-envvar docutils literal"><span class="pre">PSIPATH</span></code></a>. Then,
the plugin can be loaded as <code class="docutils literal"><span class="pre">import</span> <span class="pre">myplugin</span></code> and executed as
<code class="docutils literal"><span class="pre">energy('myplugin')</span></code>. Any other Python functions are also available from
the input file, <em>e.g.</em> <code class="docutils literal"><span class="pre">myplugin.testfunction()</span></code>, note the namespace
protection.</p>
</li>
<li><p class="first"><strong>pymodule.py</strong> — Python component of the plugin. The procedure
for calling plugin code shown in <code class="docutils literal"><span class="pre">input.dat</span></code> sounds very simple, but it
can be made simpler still. By encoding the sequence of <span class="sc">Psi4</span> module
calls needed to run the plugin in the <code class="docutils literal"><span class="pre">run_myplugin()</span></code> function in this
file, the plugin is hooked into the main <span class="sc">Psi4</span> driver function
<a class="reference internal" href="energy.html#driver.energy" title="driver.energy"><code class="xref py py-func docutils literal"><span class="pre">energy()</span></code></a> and so can be accessed through
<code class="docutils literal"><span class="pre">energy('myplugin')</span></code> in an input file. Any other Python functions can
also be placed in this file.</p>
</li>
<li><p class="first"><strong>__init__.py</strong> — Init script for the plugin (in the sense that
the whole plugin directory is a Python module). This file generally won’t
need editing unless additional Python files are added to the plugin
directory (add additional lines to the <code class="docutils literal"><span class="pre">#</span> <span class="pre">Load</span> <span class="pre">Python</span> <span class="pre">modules</span></code> section)
or the plugin depends on .so codes in other plugin directories (add
additional plugin_load lines relative to the current plugin directory to
the <code class="docutils literal"><span class="pre">#</span> <span class="pre">Load</span> <span class="pre">C++</span> <span class="pre">plugin</span></code> section as modeled in
<a class="reference external" href="https://github.com/psi4/psi4public/blob/master/tests/plugin_libcim/__init__.py">psi4/tests/plugin_libcim/__init__.py</a>).</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c">#</span>
<span class="c">#@BEGIN LICENSE</span>
<span class="c">#</span>
<span class="c"># @plugin@ by Psi4 Developer, a plugin to:</span>
<span class="c">#</span>
<span class="c"># PSI4: an ab initio quantum chemistry software package</span>
<span class="c">#</span>
<span class="c"># This program is free software; you can redistribute it and/or modify</span>
<span class="c"># it under the terms of the GNU General Public License as published by</span>
<span class="c"># the Free Software Foundation; either version 2 of the License, or</span>
<span class="c"># (at your option) any later version.</span>
<span class="c">#</span>
<span class="c"># This program is distributed in the hope that it will be useful,</span>
<span class="c"># but WITHOUT ANY WARRANTY; without even the implied warranty of</span>
<span class="c"># MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the</span>
<span class="c"># GNU General Public License for more details.</span>
<span class="c">#</span>
<span class="c"># You should have received a copy of the GNU General Public License along</span>
<span class="c"># with this program; if not, write to the Free Software Foundation, Inc.,</span>
<span class="c"># 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.</span>
<span class="c">#</span>
<span class="c">#@END LICENSE</span>
<span class="c">#</span>
<span class="sd">"""Plugin docstring.</span>
<span class="sd">"""</span>
<span class="n">__version__</span> <span class="o">=</span> <span class="s">'0.1'</span>
<span class="n">__author__</span> <span class="o">=</span> <span class="s">'Psi4 Developer'</span>
<span class="c"># Load Python modules</span>
<span class="kn">from</span> <span class="nn">pymodule</span> <span class="kn">import</span> <span class="o">*</span>
<span class="c"># Load C++ plugin</span>
<span class="kn">import</span> <span class="nn">os</span>
<span class="kn">import</span> <span class="nn">psi4</span>
<span class="n">plugdir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="n">__file__</span><span class="p">))[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">sofile</span> <span class="o">=</span> <span class="n">plugdir</span> <span class="o">+</span> <span class="s">'/'</span> <span class="o">+</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">plugdir</span><span class="p">)[</span><span class="mi">1</span><span class="p">]</span> <span class="o">+</span> <span class="s">'.so'</span>
<span class="n">psi4</span><span class="o">.</span><span class="n">plugin_load</span><span class="p">(</span><span class="n">sofile</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li><p class="first"><strong>doc.rst</strong> — Documentation file. Place in this file any notes,
equations, warnings to users, todo lists, <em>etc.</em>. Plain text is fine,
though reStructuredText is the ultimate goal. Remove the <code class="docutils literal"><span class="pre">..</span> <span class="pre">comment</span></code>
text and build Sphinx documentation for samples of linking keywords,
sections, and math. This file is absorbed into the <span class="sc">Psi4</span>
documentation, along with any docstrings to Python functions, and the C++
keywords block in the <code class="docutils literal"><span class="pre">myplugin.cc</span></code> file. See <a class="reference internal" href="documentation.html#sec-documentation"><span>Documentation</span></a>
for building documentation and <span class="xref std std-ref">Available Plugins</span>
for this file’s final destination.</p>
</li>
</ul>
<p>To create a purely Python plugin, create a new plugin directory, then
remove the <code class="docutils literal"><span class="pre">Makefile</span></code> and <code class="docutils literal"><span class="pre">myplugin.cc</span></code> files and
erase the shared object loading portion of <code class="docutils literal"><span class="pre">__init__.py</span></code>. Create as many .py
files as necessary (registering each one in <code class="docutils literal"><span class="pre">__init__.py</span></code>), use
<code class="docutils literal"><span class="pre">input.dat</span></code> as a model for loading the plugin, no recompile ever
necessary.</p>
<style type="text/css"><!--
.green {color: red;}
.sc {font-variant: small-caps;}
--></style></div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Plugins: Adding New Functionality to <span class="sc">Psi4</span></a><ul>
<li><a class="reference internal" href="#modular-approach-to-development">Modular Approach to Development</a></li>
<li><a class="reference internal" href="#creating-a-new-plugin">Creating a New Plugin</a></li>
<li><a class="reference internal" href="#files-in-a-plugin-directory">Files in a Plugin Directory</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="contributing.html"
title="previous chapter">Contributions: Intro to Programming in <span class="sc">Psi4</span></a></p>
<h4>Next topic</h4>
<p class="topless"><a href="bestpractices_py.html"
title="next chapter">Best Practices for Python Functions</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/plugins.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="relbar-bottom">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> </li>
<li class="right" >
<a href="contents.html" title="Table Of Contents"
>toc</a> </li>
<li class="right" >
<a href="bestpractices_py.html" title="Best Practices for Python Functions"
>next</a> </li>
<li class="right" >
<a href="contributing.html" title="Contributions: Intro to Programming in Psi4"
>previous</a> </li>
<li><a href="index.html">Psi4 []</a> » </li>
<li class="nav-item nav-item-1"><a href="contributing.html" >Contributions: Intro to Programming in <span class="sc">Psi4</span></a> »</li>
</ul>
</div>
</div>
<div class="footer" role="contentinfo">
© Copyright 2015, The Psi4 Project.
Last updated on Tuesday, 12 January 2016 03:10PM.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.3.
</div>
<!-- cloud_sptheme 1.3 -->
</body>
</html>
|