some docs and cleanup

more docs and cleanup

cleanup

adcc/AdcMatrix.py

@@ -33,10 +33,6 @@
 
 
 class AdcExtraTerm:
-    # NOTE: currently requires the matrix
-    # to allow for block construction with the same
-    # interface as the usual adc_pp, i.e.,
-    # reference_state, ground_state, intermediates
     def __init__(self, matrix, blocks):
         """Initialise an AdcExtraTerm.
         This class can be used to add customs terms
@@ -109,7 +105,7 @@ def __init__(self, method, hf_or_mp, block_orders=None, intermediates=None,
                                  libadcc.HartreeFockSolution_i)):
             hf_or_mp = LazyMp(hf_or_mp)
         if not isinstance(hf_or_mp, LazyMp):
-            raise TypeError("mp_results is not a valid object. It needs to be "
+            raise TypeError("hf_or_mp is not a valid object. It needs to be "
                             "either a LazyMp, a ReferenceState or a "
                             "HartreeFockSolution_i.")
 

adcc/adc_pp/environment.py

@@ -27,9 +27,10 @@
 def block_ph_ph_0_pe(hf, mp, intermediates):
     """
     Constructs an :py:class:`AdcBlock` that describes the
-    coupling to the polarizable environment from PE via a CIS-like
-    coupling density as described in 10.1021/ct300763v, eq 63.
-    Since the contribution depends on the input amplitude itself,
+    linear response coupling to the polarizable environment
+    from PE via a CIS-like transition density as described
+    in 10.1021/ct300763v, eq 63. Since the contribution
+    depends on the input amplitude itself,
     a diagonal term cannot be formulated.
     """
     op = hf.operators

adcc/backends/pyscf.py

@@ -281,7 +281,7 @@ def run_hf(xyz, basis, charge=0, multiplicity=1, conv_tol=1e-11,
     )
     if pe_options:
         from pyscf.solvent import PE
-        mf = PE(scf.HF(mol), pe_options["potfile"])
+        mf = PE(scf.HF(mol), pe_options)
     else:
         mf = scf.HF(mol)
     mf.conv_tol = conv_tol

adcc/workflow.py

@@ -129,6 +129,10 @@ def run_adc(data_or_matrix, n_states=None, kind="any", conv_tol=None,
         virtuals for both the MP and ADC methods performed). For ways to define
         these see the description in :py:class:`adcc.ReferenceState`.
 
+    environment : bool or list or dict, optional
+        The keywords to specify how coupling to an environment model,
+        e.g. PE, is treated. For details see :ref:`environment`.
+
     Other parameters
     ----------------
     max_subspace : int, optional
@@ -513,26 +517,6 @@ def setup_environment(matrix, environment):
     Internal function called from run_adc.
     """
     valid_envs = ["ptss", "ptlr", "linear_response"]
-    # valid_solvent_schemes = {
-    #     "hf": """
-    #         only couple via the 'solvated' orbitals of the HF reference
-    #         state, no additional matrix terms or perturbative corrections
-    #         are used automatically
-    #     """,
-    #     "ptss": """
-    #         perturbative state-specific (ptSS) correction, computed based on
-    #         the difference density between the ground and excited state
-    #     """,
-    #     "ptlr": """
-    #         perturbative linear-response (ptLR) correction, computed based on
-    #         the transition density between the ground and excited state
-    #     """,
-    #     # NOTE: could also be called 'lr'...
-    #     "postscf": """
-    #         iterative coupling to the solvent via a CIS-like coupling
-    #         density matrix, the term is added to the ADC matrix
-    #     """,
-    # }
     hf = matrix.reference_state
     if hf.environment and environment is None:
         raise InputError(

docs/calculations.rst

@@ -27,6 +27,8 @@ to be applied. Arbitrary combinations of these variants,
 e.g. applying **both** CVS and FC approximations are supported as well.
 See :ref:`frozen-spaces` for details.
 
+Calculations with :ref:`environment` are also supported.
+
 General ADC(n) calculations
 ---------------------------
 General ADC(n) calculations,
@@ -685,6 +687,95 @@ In fact all three may be combined jointly with any available ADC method,
 if desired.
 
 
+.. _`environment`:
+
+Polarisable Embedding
+---------------------
+
+ADC calculations with the Polarisable Embedding (PE) model are supported
+for the PySCF and Psi4 backends via the `CPPE library <https://github.com/maxscheurer/cppe>`_ :cite:`Scheurer2019`.
+In the PE model, interactions with the environment are represented by a
+multi-center multipole expansion for electrostatics, and polarisation is modeled
+via dipole polarizabilities located at the expansion sites.
+For a general introduction of PE and a tutorial on how to set up calculations, please see the tutorial review :cite:`Steinmann2019`.
+The embedding potential needed for PE can be generated using `PyFraME <https://gitlab.com/FraME-projects/PyFraME>`_, which is installable
+via ``pip install pyframe``.
+
+There are different options to include environment effects in ADC excited state calculations, summarised in
+the following table:
+
++------------------------------------------------+-----------------------+--------------------------------------------------------------------------+-----------------------------------------------+
+| Name                                           | ``environment``       | Comment                                                                  | Reference                                     |
++================================================+=======================+==========================================================================+===============================================+
+| coupling through reference state only          | ``False``             | only couple via the 'solvated' orbitals of the SCF reference state,      | :cite:`Scheurer2018`                          |
+|                                                |                       | no additional matrix terms or corrections are used                       |                                               |
++------------------------------------------------+-----------------------+--------------------------------------------------------------------------+-----------------------------------------------+
+| perturbative state-specific correction (ptSS)  | ``"ptss"``            | computed from the difference density betweenthe ground and excited state | :cite:`Scheurer2018`                          |
++------------------------------------------------+-----------------------+--------------------------------------------------------------------------+-----------------------------------------------+
+| perturbative linear-response correction (ptLR) | ``"ptlr"``            | computed from the transition density between                             | :cite:`Scheurer2018`                          |
+|                                                |                       | the ground and excited state                                             |                                               |
++------------------------------------------------+-----------------------+--------------------------------------------------------------------------+-----------------------------------------------+
+| linear response iterative coupling             | ``"linear_response"`` | iterative coupling to the solvent via a CIS-like coupling density,       | :cite:`Lunkenheimer2013`, :cite:`Marefat2018` |
+|                                                |                       | the additional term is added to the ADC matrix                           |                                               |
++------------------------------------------------+-----------------------+--------------------------------------------------------------------------+-----------------------------------------------+
+
+The scheme can be selected with the ``environment`` parameter in :func:`adcc.run_adc` (and also in the short-hand method functions, e.g. :func:`adcc.adc2`).
+If a PE-SCF ground state is found but no ``environment`` parameter is specified, an error will be thrown.
+Specifying ``environment=True`` will enable both perturbative corrections, equivalent to ``environment=["ptss", "ptlr"]``.
+Combining ``"ptlr"`` with ``"linear_response"`` is not allowed since both describe the same physical effect in a different manner.
+
+The following example computes PE-ADC(2) excited states of para-nitroaniline in the presence of six water molecules
+a) with perturbative corrections and
+b) with the linear response scheme. The results of both schemes are then printed out for comparison.
+
+.. code-block:: python
+
+   import adcc
+   from pyscf import gto, scf
+   from pyscf.solvent import PE
+
+   mol = gto.M(
+      atom="""
+      C          8.64800        1.07500       -1.71100
+      C          9.48200        0.43000       -0.80800
+      C          9.39600        0.75000        0.53800
+      C          8.48200        1.71200        0.99500
+      C          7.65300        2.34500        0.05500
+      C          7.73200        2.03100       -1.29200
+      H         10.18300       -0.30900       -1.16400
+      H         10.04400        0.25200        1.24700
+      H          6.94200        3.08900        0.38900
+      H          7.09700        2.51500       -2.01800
+      N          8.40100        2.02500        2.32500
+      N          8.73400        0.74100       -3.12900
+      O          7.98000        1.33100       -3.90100
+      O          9.55600       -0.11000       -3.46600
+      H          7.74900        2.71100        2.65200
+      H          8.99100        1.57500        2.99500
+      """,
+      basis='sto-3g',
+   )
+
+   scfres = PE(scf.RHF(mol), {"potfile": "pna_6w.pot"})
+   scfres.conv_tol = 1e-8
+   scfres.conv_tol_grad = 1e-6
+   scfres.max_cycle = 250
+   scfres.kernel()
+
+   # model the solvent through perturbative corrections
+   state_pt = adcc.adc2(scfres, n_singlets=5, conv_tol=1e-5,
+                        environment=['ptss', 'ptlr'])
+
+   # now model the solvent through linear-response coupling
+   # in the ADC matrix, re-using the matrix from previous run.
+   # This will modify state_pt.matrix
+   state_lr = adcc.run_adc(state_pt.matrix, n_singlets=5, conv_tol=1e-5,
+                           environment='linear_response')
+
+   print(state_pt.describe())
+   print(state_lr.describe())
+
+
 Further examples and details
 ----------------------------
 Some further examples can be found in the ``examples`` folder

docs/ref.bib

@@ -297,3 +297,58 @@ @Article{Wormit2014
   pages   = {774-784},
   doi     = {10.1080/00268976.2013.859313},
 }
+
+@article{Scheurer2018,
+author = {Scheurer, Maximilian and Herbst, Michael F. and Reinholdt, Peter and Olsen, J{\'{o}}gvan Magnus Haugaard and Dreuw, Andreas and Kongsted, Jacob},
+doi = {10.1021/acs.jctc.8b00576},
+issn = {1549-9618},
+journal = {J. Chem. Theory Comput.},
+number = {9},
+pages = {4870−4883},
+pmid = {30086234},
+title = {{Polarizable Embedding Combined with the Algebraic Diagrammatic Construction: Tackling Excited States in Biomolecular Systems}},
+volume = {14},
+year = {2018}
+}
+
+@article{Lunkenheimer2013,
+author = {Lunkenheimer, Bernd and K{\"{o}}hn, Andreas},
+doi = {10.1021/ct300763v},
+issn = {15499626},
+journal = {J. Chem. Theory Comput.},
+title = {{Solvent effects on electronically excited states using the conductor-like screening model and the second-order correlated method ADC(2)}},
+year = {2013}
+}
+
+@article{Marefat2018,
+author = {{Marefat Khah}, Alireza and {Karbalaei Khani}, Sarah and H{\"{a}}ttig, Christof},
+doi = {10.1021/acs.jctc.8b00396},
+issn = {15499626},
+journal = {J. Chem. Theory Comput.},
+pmid = {30040882},
+title = {{Analytic Excited State Gradients for the QM/MM Polarizable Embedded Second-Order Algebraic Diagrammatic Construction for the Polarization Propagator PE-ADC(2)}},
+year = {2018}
+}
+
+@article{Scheurer2019,
+  title={CPPE: An open-source C++ and Python library for polarizable embedding},
+  author={Scheurer, Maximilian and Reinholdt, Peter and Kjellgren, Erik Rosendahl and Olsen, Jógvan Magnus Haugaard and Dreuw, Andreas and Kongsted, Jacob},
+  journal={J. Chem. Theory Comput.},
+  volume={15},
+  number={11},
+  pages={6154--6163},
+  year={2019},
+  doi={10.1021/acs.jctc.9b00758},
+}
+
+@ARTICLE{Steinmann2019,
+  title     = {Response properties of embedded molecules through the polarizable embedding model},
+  author    = {Steinmann, Casper and Reinholdt, Peter and N{\o}rby, Morten
+               Steen and Kongsted, Jacob and Olsen, J{\'o}gvan Magnus Haugaard},
+  journal   = {Int. J. Quantum Chem.},
+  volume    =  {119},
+  number    =  {1},
+  pages     = {e25717},
+  year      =  {2019},
+  doi       =  {10.1002/qua.25717},
+}