{"id":1454,"date":"2025-05-23T06:22:03","date_gmt":"2025-05-23T06:22:03","guid":{"rendered":"https:\/\/sharc-md.org\/?page_id=1454"},"modified":"2025-05-23T11:30:54","modified_gmt":"2025-05-23T11:30:54","slug":"manual_4-0","status":"publish","type":"page","link":"https:\/\/sharc-md.org\/?page_id=1454","title":{"rendered":"Manual"},"content":{"rendered":"

Read the manual below or download the PDF<\/a>.
\nIf you are looking for the SHARC 3.0 manual, download the PDF<\/a> here instead.<\/p>\n

SHARC: Surface Hopping in the Adiabatic Representation Including Arbitrary Couplings—Manual<\/title><\/p>\n<h1 align=\"center\">SHARC: Surface Hopping in the Adiabatic Representation Including Arbitrary Couplings-Manual <\/h1>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<h1>Contents <\/h1>\n<p><a href=\"#tth_chAp1\">1  Introduction<\/a><br \/>    <a href=\"#tth_sEc1.1\">1.1  Capabilities<\/a><br \/>        <a href=\"#tth_sEc1.1.1\">1.1.1  New features in S<span style=\"font-size:x-small\">HARC<\/span> Version 4.0<\/a><br \/>    <a href=\"#tth_sEc1.2\">1.2  References<\/a><br \/>    <a href=\"#tth_sEc1.3\">1.3  Authors<\/a><br \/>        <a href=\"#tth_sEc1.3.1\">1.3.1  Eternal list of contributors<\/a><br \/>        <a href=\"#tth_sEc1.3.2\">1.3.2  List of contributors to S<span style=\"font-size:x-small\">HARC<\/span> 4<\/a><br \/>    <a href=\"#tth_sEc1.4\">1.4  Suggestions and Bug Reports<\/a><br \/>    <a href=\"#tth_sEc1.5\">1.5  Notation in this Manual<\/a><br \/>    <a href=\"#tth_sEc1.6\">1.6  Terms of Use<\/a><br \/><a href=\"#tth_chAp2\">2  Installation<\/a><br \/>    <a href=\"#tth_sEc2.1\">2.1  How To Obtain<\/a><br \/>    <a href=\"#tth_sEc2.2\">2.2  Installation<\/a><br \/>        <a href=\"#tth_sEc2.2.1\">2.2.1  Libraries<\/a><br \/>        <a href=\"#tth_sEc2.2.2\">2.2.2  WF<span style=\"font-size:x-small\">OVERLAP<\/span> Program<\/a><br \/>        <a href=\"#tth_sEc2.2.3\">2.2.3  Test Suite<\/a><br \/>        <a href=\"#tth_sEc2.2.4\">2.2.4  Additional Programs<\/a><br \/>        <a href=\"#tth_sEc2.2.5\">2.2.5  Quantum Chemistry Programs<\/a><br \/><a href=\"#tth_chAp3\">3  Execution<\/a><br \/>    <a href=\"#tth_sEc3.1\">3.1  Running a single trajectory<\/a><br \/>        <a href=\"#tth_sEc3.1.1\">3.1.1  Input files<\/a><br \/>        <a href=\"#tth_sEc3.1.2\">3.1.2  Running the dynamics code<\/a><br \/>        <a href=\"#tth_sEc3.1.3\">3.1.3  Output files<\/a><br \/>    <a href=\"#tth_sEc3.2\">3.2  Typical workflow for an ensemble of trajectories<\/a><br \/>        <a href=\"#tth_sEc3.2.1\">3.2.1  Initial condition generation<\/a><br \/>        <a href=\"#tth_sEc3.2.2\">3.2.2  Setting up the dynamics simulations<\/a><br \/>        <a href=\"#tth_sEc3.2.3\">3.2.3  Running the dynamics simulations<\/a><br \/>        <a href=\"#tth_sEc3.2.4\">3.2.4  Analysis of the dynamics results<\/a><br \/>    <a href=\"#tth_sEc3.3\">3.3  Programs and Scripts of the S<span style=\"font-size:x-small\">HARC<\/span> Suite<\/a><br \/>        <a href=\"#tth_sEc3.3.1\">3.3.1  Setup and Preparation<\/a><br \/>        <a href=\"#tth_sEc3.3.2\">3.3.2  Trajectory Running and Management<\/a><br \/>        <a href=\"#tth_sEc3.3.3\">3.3.3  Analysis<\/a><br \/>        <a href=\"#tth_sEc3.3.4\">3.3.4  Others<\/a><br \/>        <a href=\"#tth_sEc3.3.5\">3.3.5  Interfaces<\/a><br \/>    <a href=\"#tth_sEc3.4\">3.4  The S<span style=\"font-size:x-small\">HARC<\/span> dynamics drivers<\/a><br \/>        <a href=\"#tth_sEc3.4.1\">3.4.1  Original driver: <b><tt>sharc.x<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc3.4.2\">3.4.2  PySHARC driver: <b><tt>driver.py<\/tt><\/b><\/a><br \/><a href=\"#tth_chAp4\">4  Input files<\/a><br \/>    <a href=\"#tth_sEc4.1\">4.1  Main input file<\/a><br \/>        <a href=\"#tth_sEc4.1.1\">4.1.1  General remarks<\/a><br \/>        <a href=\"#tth_sEc4.1.2\">4.1.2  Input keywords<\/a><br \/>        <a href=\"#tth_sEc4.1.3\">4.1.3  Detailed Description of the Keywords<\/a><br \/>        <a href=\"#tth_sEc4.1.4\">4.1.4  Example<\/a><br \/>    <a href=\"#tth_sEc4.2\">4.2  Geometry file<\/a><br \/>    <a href=\"#tth_sEc4.3\">4.3  Velocity file<\/a><br \/>    <a href=\"#tth_sEc4.4\">4.4  Coefficient file<\/a><br \/>    <a href=\"#tth_sEc4.5\">4.5  Laser file<\/a><br \/>    <a href=\"#tth_sEc4.6\">4.6  Atom mask file<\/a><br \/>    <a href=\"#tth_sEc4.7\">4.7  RATTLE file<\/a><br \/>    <a href=\"#tth_sEc4.8\">4.8  Frozen atoms file<\/a><br \/>    <a href=\"#tth_sEc4.9\">4.9  Droplet atoms file<\/a><br \/>    <a href=\"#tth_sEc4.10\">4.10  Thermostat settings file<\/a><br \/><a href=\"#tth_chAp5\">5  Output files<\/a><br \/>    <a href=\"#tth_sEc5.1\">5.1  Log file: <b><tt>output.log<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc5.2\">5.2  Listing file: <b><tt>output.lis<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc5.3\">5.3  Data file: <b><tt>output.dat<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc5.3.1\">5.3.1  Specification of the data file<\/a><br \/>    <a href=\"#tth_sEc5.4\">5.4  Data file in NetCDF format: : <b><tt>output.dat.nc<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc5.5\">5.5  Separate nuclear data file in NetCDF format: <b><tt>output_NUC.dat.nc<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc5.6\">5.6  XYZ file: <b><tt>output.xyz<\/tt><\/b><\/a><br \/><a href=\"#tth_chAp6\">6  Interfaces<\/a><br \/>        <a href=\"#tth_sEc6.0.1\">6.0.1  Overview over Interfaces<\/a><br \/>        <a href=\"#tth_sEc6.0.2\">6.0.2  Assoiated File Names and Example Directory<\/a><br \/>        <a href=\"#tth_sEc6.0.3\">6.0.3  Generic keywords in resource files of many interfaces<\/a><br \/>    <a href=\"#tth_sEc6.1\">6.1  Do-Nothing Interface<\/a><br \/>    <a href=\"#tth_sEc6.2\">6.2  QMout Interface<\/a><br \/>    <a href=\"#tth_sEc6.3\">6.3  Analytical PESs Interface<\/a><br \/>        <a href=\"#tth_sEc6.3.1\">6.3.1  Parametrization<\/a><br \/>        <a href=\"#tth_sEc6.3.2\">6.3.2  Template file: <b><tt>ANALYTICAL.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.3.3\">6.3.3  Template file: <b><tt>ANALYTICAL.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.3.4\">6.3.4  During setup<\/a><br \/>    <a href=\"#tth_sEc6.4\">6.4  LVC Interface<\/a><br \/>        <a href=\"#tth_sEc6.4.1\">6.4.1  Input files<\/a><br \/>        <a href=\"#tth_sEc6.4.2\">6.4.2  Resource file<\/a><br \/>        <a href=\"#tth_sEc6.4.3\">6.4.3  During setup<\/a><br \/>        <a href=\"#tth_sEc6.4.4\">6.4.4  Template File Setup: <b><tt>setup_LVCparam.py<\/tt><\/b>, <b><tt>create_LVCparam.py<\/tt><\/b>, <b><tt>modify_LVC_template.py<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc6.5\">6.5  SPaiNN Interface<\/a><br \/>        <a href=\"#tth_sEc6.5.1\">6.5.1  Template file: <b><tt>SPAINN.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.5.2\">6.5.2  Resource file: <b><tt>SPAINN.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.5.3\">6.5.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.6\">6.6  SCHNARC Interface<\/a><br \/>        <a href=\"#tth_sEc6.6.1\">6.6.1  Template file: <b><tt>SCHNARC.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.6.2\">6.6.2  Template file: <b><tt>SCHNARC.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.6.3\">6.6.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.7\">6.7  OpenMM Interface<\/a><br \/>        <a href=\"#tth_sEc6.7.1\">6.7.1  Template file<\/a><br \/>        <a href=\"#tth_sEc6.7.2\">6.7.2  Resource file<\/a><br \/>        <a href=\"#tth_sEc6.7.3\">6.7.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.8\">6.8  G<span style=\"font-size:x-small\">AUSSIAN<\/span> Interface<\/a><br \/>        <a href=\"#tth_sEc6.8.1\">6.8.1  Template file: <b><tt>GAUSSIAN.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.8.2\">6.8.2  Resource file: <b><tt>GAUSSIAN.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.8.3\">6.8.3  During setup<\/a><br \/>        <a href=\"#tth_sEc6.8.4\">6.8.4  Extracting normal modes: <b><tt>GAUSSIAN_freq.py<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc6.9\">6.9  O<span style=\"font-size:x-small\">RCA<\/span> Interface<\/a><br \/>        <a href=\"#tth_sEc6.9.1\">6.9.1  Template file: <b><tt>ORCA.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.9.2\">6.9.2  Resource file: <b><tt>ORCA.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.9.3\">6.9.3  During setup<\/a><br \/>        <a href=\"#tth_sEc6.9.4\">6.9.4  Extracting normal modes: <b><tt>ORCA_hess_freq.py<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc6.10\">6.10  NWC<span style=\"font-size:x-small\">HEM<\/span> Interface<\/a><br \/>        <a href=\"#tth_sEc6.10.1\">6.10.1  Template file: <b><tt>NWCHEM.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.10.2\">6.10.2  Resource file: <b><tt>NWCHEM.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.10.3\">6.10.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.11\">6.11  Turbomole Interface<\/a><br \/>        <a href=\"#tth_sEc6.11.1\">6.11.1  Template file: <b><tt>TURBOMOLE.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.11.2\">6.11.2  Resource file: <b><tt>TURBOMOLE.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.11.3\">6.11.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.12\">6.12  O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> Interface<\/a><br \/>        <a href=\"#tth_sEc6.12.1\">6.12.1  Template file: <b><tt>MOLCAS.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.12.2\">6.12.2  Resource file: <b><tt>MOLCAS.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.12.3\">6.12.3  During setup<\/a><br \/>        <a href=\"#tth_sEc6.12.4\">6.12.4  Template file generator: <b><tt>molcas_input.py<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc6.13\">6.13  MNDO Interface<\/a><br \/>        <a href=\"#tth_sEc6.13.1\">6.13.1  Template file: <b><tt>MNDO.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.13.2\">6.13.2  Resource file: <b><tt>MNDO.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.13.3\">6.13.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.14\">6.14  MOPAC-PI Interface<\/a><br \/>        <a href=\"#tth_sEc6.14.1\">6.14.1  Template file: <b><tt>MOPACPI.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.14.2\">6.14.2  Resource file: <b><tt>MOPACPI.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.14.3\">6.14.3  Reparametrized Hamiltonians, definition of microstates and additional potentials: <b><tt>ext_param<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.14.4\">6.14.4  QM\/MM force field files<\/a><br \/>        <a href=\"#tth_sEc6.14.5\">6.14.5  QM\/MM connection table file: <b><tt>MOPACPI_tnk.xyz<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.14.6\">6.14.6  QM\/MM force field file: e.g. <b><tt>oplsaa.prm<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.14.7\">6.14.7  QM\/MM additional force field definition file: <b><tt>MOPACPI_tnk.key<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.14.8\">6.14.8  During setup<\/a><br \/>    <a href=\"#tth_sEc6.15\">6.15  LEGACY Interface<\/a><br \/>        <a href=\"#tth_sEc6.15.1\">6.15.1  Template file: <b><tt>LEGACY.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.15.2\">6.15.2  Resource file: <b><tt>LEGACY.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.15.3\">6.15.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.16\">6.16  AMS-ADF Interface<\/a><br \/>        <a href=\"#tth_sEc6.16.1\">6.16.1  Template file: <b><tt>AMS_ADF.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.16.2\">6.16.2  Resource file: <b><tt>AMS_ADF.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.16.3\">6.16.3  During setup<\/a><br \/>        <a href=\"#tth_sEc6.16.4\">6.16.4  Frequencies converter: <b><tt>AMS_ADF_freq.py<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc6.17\">6.17  COLUMBUS Interface<\/a><br \/>        <a href=\"#tth_sEc6.17.1\">6.17.1  Template input<\/a><br \/>        <a href=\"#tth_sEc6.17.2\">6.17.2  Resource file: <b><tt>COLUMBUS.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.17.3\">6.17.3  Template setup<\/a><br \/>        <a href=\"#tth_sEc6.17.4\">6.17.4  During setup<\/a><br \/>    <a href=\"#tth_sEc6.18\">6.18  B<span style=\"font-size:x-small\">AGEL<\/span> Interface<\/a><br \/>        <a href=\"#tth_sEc6.18.1\">6.18.1  Template file: <b><tt>BAGEL.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.18.2\">6.18.2  Resource file: <b><tt>BAGEL.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.18.3\">6.18.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.19\">6.19  MOLPRO Interface<\/a><br \/>        <a href=\"#tth_sEc6.19.1\">6.19.1  Template file: <b><tt>MOLPRO.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.19.2\">6.19.2  Resource file: <b><tt>MOLPRO.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.19.3\">6.19.3  Error checking<\/a><br \/>        <a href=\"#tth_sEc6.19.4\">6.19.4  Things to keep in mind<\/a><br \/>        <a href=\"#tth_sEc6.19.5\">6.19.5  During setup<\/a><br \/>        <a href=\"#tth_sEc6.19.6\">6.19.6  Molpro input generator: <b><tt>molpro_input.py<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc6.20\">6.20  PySCF Interface<\/a><br \/>        <a href=\"#tth_sEc6.20.1\">6.20.1  Template file: <b><tt>PYSCF.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.20.2\">6.20.2  Resource file: <b><tt>PYSCF.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.20.3\">6.20.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.21\">6.21  ASE Database Interface<\/a><br \/>        <a href=\"#tth_sEc6.21.1\">6.21.1  Template file: <b><tt>ASE_DB.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.21.2\">6.21.2  During setup<\/a><br \/>    <a href=\"#tth_sEc6.22\">6.22  Umbrella Sampling Interface<\/a><br \/>        <a href=\"#tth_sEc6.22.1\">6.22.1  Template file: <b><tt>UMBRELLA.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.22.2\">6.22.2  Restraints file<\/a><br \/>        <a href=\"#tth_sEc6.22.3\">6.22.3  Resource file: <b><tt>UMBRELLA.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.22.4\">6.22.4  During setup<\/a><br \/>    <a href=\"#tth_sEc6.23\">6.23  Numerical Differentiation Interface<\/a><br \/>        <a href=\"#tth_sEc6.23.1\">6.23.1  Template file: <b><tt>NUMDIFF.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.23.2\">6.23.2  Resource file: <b><tt>NUMDIFF.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.23.3\">6.23.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.24\">6.24  QM\/MM Interface<\/a><br \/>        <a href=\"#tth_sEc6.24.1\">6.24.1  Template file: <b><tt>QMMM.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.24.2\">6.24.2  Resource file: <b><tt>QMMM.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.24.3\">6.24.3  Connectivity and QM\/MM type file: <b><tt>QMMM.table<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.24.4\">6.24.4  During setup<\/a><br \/>    <a href=\"#tth_sEc6.25\">6.25  ECI Interface<\/a><br \/>        <a href=\"#tth_sEc6.25.1\">6.25.1  Theory and implementation<\/a><br \/>        <a href=\"#tth_sEc6.25.2\">6.25.2  QM directory of ECI interface<\/a><br \/>        <a href=\"#tth_sEc6.25.3\">6.25.3  Template file: <b><tt>ECI.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.25.4\">6.25.4  Resources file: <b><tt>ECI.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.25.5\">6.25.5  Standard output of SHARC_ECI.py<\/a><br \/>        <a href=\"#tth_sEc6.25.6\">6.25.6  During setup<\/a><br \/>    <a href=\"#tth_sEc6.26\">6.26  Adaptive Sampling Interface<\/a><br \/>        <a href=\"#tth_sEc6.26.1\">6.26.1  Template file: <b><tt>ADAPTIVE.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.26.2\">6.26.2  Resources file: <b><tt>ADAPTIVE.resources<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.26.3\">6.26.3  During setup<\/a><br \/>    <a href=\"#tth_sEc6.27\">6.27  Fallback Interface<\/a><br \/>        <a href=\"#tth_sEc6.27.1\">6.27.1  Template file: <b><tt>FALLBACK.template<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc6.27.2\">6.27.2  During setup<\/a><br \/>    <a href=\"#tth_sEc6.28\">6.28  File-based Interface Specifications<\/a><br \/>        <a href=\"#tth_sEc6.28.1\">6.28.1  <b><tt>QM.in<\/tt><\/b> Specification<\/a><br \/>        <a href=\"#tth_sEc6.28.2\">6.28.2  <b><tt>QM.out<\/tt><\/b> Specification<\/a><br \/>        <a href=\"#tth_sEc6.28.3\">6.28.3  Further Specifications<\/a><br \/>        <a href=\"#tth_sEc6.28.4\">6.28.4  Save Directory Specification<\/a><br \/>    <a href=\"#tth_sEc6.29\">6.29  The WF<span style=\"font-size:x-small\">OVERLAP<\/span> Program<\/a><br \/>        <a href=\"#tth_sEc6.29.1\">6.29.1  Installation<\/a><br \/>        <a href=\"#tth_sEc6.29.2\">6.29.2  Workflow<\/a><br \/>        <a href=\"#tth_sEc6.29.3\">6.29.3  Calling the program<\/a><br \/>        <a href=\"#tth_sEc6.29.4\">6.29.4  Input data<\/a><br \/>        <a href=\"#tth_sEc6.29.5\">6.29.5  Output<\/a><br \/><a href=\"#tth_chAp7\">7  Auxilliary Scripts<\/a><br \/>    <a href=\"#tth_sEc7.1\">7.1  Wigner Distribution Sampling: <b><tt>wigner.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.1.1\">7.1.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.1.2\">7.1.2  Normal mode types<\/a><br \/>        <a href=\"#tth_sEc7.1.3\">7.1.3  Non-default masses<\/a><br \/>        <a href=\"#tth_sEc7.1.4\">7.1.4  Sampling at finite temperatures<\/a><br \/>        <a href=\"#tth_sEc7.1.5\">7.1.5  Output<\/a><br \/>    <a href=\"#tth_sEc7.2\">7.2  Vibrational State Selected Sampling: <b><tt>wigner_state_selected.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.2.1\">7.2.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.2.2\">7.2.2  Major options<\/a><br \/>        <a href=\"#tth_sEc7.2.3\">7.2.3  Template<\/a><br \/>        <a href=\"#tth_sEc7.2.4\">7.2.4  Normal mode types<\/a><br \/>        <a href=\"#tth_sEc7.2.5\">7.2.5  Non-default masses<\/a><br \/>        <a href=\"#tth_sEc7.2.6\">7.2.6  Output<\/a><br \/>    <a href=\"#tth_sEc7.3\">7.3  Initial condition for collision dynamics: <b><tt>bimolecular_collision.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.3.1\">7.3.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.3.2\">7.3.2  Usage<\/a><br \/>    <a href=\"#tth_sEc7.4\">7.4  A<span style=\"font-size:x-small\">MBER<\/span> Trajectory Sampling: <b><tt>amber_to_initconds.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.4.1\">7.4.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.4.2\">7.4.2  Time Step<\/a><br \/>        <a href=\"#tth_sEc7.4.3\">7.4.3  Atom Types and Masses<\/a><br \/>        <a href=\"#tth_sEc7.4.4\">7.4.4  Output<\/a><br \/>    <a href=\"#tth_sEc7.5\">7.5  S<span style=\"font-size:x-small\">HARC<\/span> Trajectory Sampling: <b><tt>sharctraj_to_initconds.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.5.1\">7.5.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.5.2\">7.5.2  Random Picking of Time Step<\/a><br \/>        <a href=\"#tth_sEc7.5.3\">7.5.3  Output<\/a><br \/>    <a href=\"#tth_sEc7.6\">7.6  Creating an XYZ file from an Amber restart file: <b><tt>restartnc_to_xyz.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.6.1\">7.6.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.6.2\">7.6.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.6.3\">7.6.3  Output<\/a><br \/>    <a href=\"#tth_sEc7.7\">7.7  Creating an XYZ file from a S<span style=\"font-size:x-small\">HARC<\/span> trajectory: <b><tt>sharctraj_to_xyz.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.7.1\">7.7.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.7.2\">7.7.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.7.3\">7.7.3  Output<\/a><br \/>    <a href=\"#tth_sEc7.8\">7.8  Setup of Initial Calculations: <b><tt>setup_init.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.8.1\">7.8.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.8.2\">7.8.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.8.3\">7.8.3  Interface-specific input<\/a><br \/>        <a href=\"#tth_sEc7.8.4\">7.8.4  Input for Run Scripts<\/a><br \/>        <a href=\"#tth_sEc7.8.5\">7.8.5  Output<\/a><br \/>    <a href=\"#tth_sEc7.9\">7.9  Excitation Selection: <b><tt>excite.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.9.1\">7.9.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.9.2\">7.9.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.9.3\">7.9.3  Output<\/a><br \/>        <a href=\"#tth_sEc7.9.4\">7.9.4  Specification of the <b><tt>initconds.excited<\/tt><\/b> file format<\/a><br \/>    <a href=\"#tth_sEc7.10\">7.10  Calculation of Absorption Spectra: <b><tt>spectrum.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.10.1\">7.10.1  Input<\/a><br \/>        <a href=\"#tth_sEc7.10.2\">7.10.2  Output<\/a><br \/>        <a href=\"#tth_sEc7.10.3\">7.10.3  Error Analysis<\/a><br \/>    <a href=\"#tth_sEc7.11\">7.11  Laser field generation: <b><tt>laser.x<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.11.1\">7.11.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.11.2\">7.11.2  Input<\/a><br \/>    <a href=\"#tth_sEc7.12\">7.12  Preparing QM\/MM calculations: <b><tt>setup_from_prmtop.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.12.1\">7.12.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.12.2\">7.12.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.12.3\">7.12.3  Output<\/a><br \/>    <a href=\"#tth_sEc7.13\">7.13  Setup of Trajectories: <b><tt>setup_traj.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.13.1\">7.13.1  Input<\/a><br \/>        <a href=\"#tth_sEc7.13.2\">7.13.2  Interface-specific input<\/a><br \/>        <a href=\"#tth_sEc7.13.3\">7.13.3  Running and output control<\/a><br \/>        <a href=\"#tth_sEc7.13.4\">7.13.4  Run script setup<\/a><br \/>        <a href=\"#tth_sEc7.13.5\">7.13.5  Output<\/a><br \/>    <a href=\"#tth_sEc7.14\">7.14  File transfer: <b><tt>retrieve.sh<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc7.15\">7.15  Resetting trajectories: <b><tt>clean_traj.sh<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.15.1\">7.15.1  Usage<\/a><br \/>    <a href=\"#tth_sEc7.16\">7.16  Ensemble Diagnostics Tool: <b><tt>diagnostics.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.16.1\">7.16.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.16.2\">7.16.2  Input<\/a><br \/>    <a href=\"#tth_sEc7.17\">7.17  Data Extractor: <b><tt>data_extractor.x<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.17.1\">7.17.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.17.2\">7.17.2  Output<\/a><br \/>    <a href=\"#tth_sEc7.18\">7.18  Data Extractor for NetCDF: <b><tt>data_extractor_NetCDF.x<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.18.1\">7.18.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.18.2\">7.18.2  Output<\/a><br \/>    <a href=\"#tth_sEc7.19\">7.19  Data Converter for NetCDF: <b><tt>data_converter.x<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.19.1\">7.19.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.19.2\">7.19.2  Output<\/a><br \/>    <a href=\"#tth_sEc7.20\">7.20  Data Converter from NetCDF to ASCII: <b><tt>data_converter_to_ASCII.x<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.20.1\">7.20.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.20.2\">7.20.2  Output<\/a><br \/>    <a href=\"#tth_sEc7.21\">7.21  Data Converter from NetCDF nuclear files to XYZ: <b><tt>data_extractor_NUC_xyz.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.21.1\">7.21.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.21.2\">7.21.2  Output<\/a><br \/>    <a href=\"#tth_sEc7.22\">7.22  Plotting the Extracted Data: <b><tt>make_gnuscript.py<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc7.23\">7.23  Internal Coordinates Analysis: <b><tt>geo.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.23.1\">7.23.1  Input<\/a><br \/>        <a href=\"#tth_sEc7.23.2\">7.23.2  Options<\/a><br \/>    <a href=\"#tth_sEc7.24\">7.24  Normal Mode Analysis: <b><tt>geo_NM.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.24.1\">7.24.1  Input<\/a><br \/>        <a href=\"#tth_sEc7.24.2\">7.24.2  Output Format<\/a><br \/>    <a href=\"#tth_sEc7.25\">7.25  Calculation of Ensemble Populations: <b><tt>populations.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.25.1\">7.25.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.25.2\">7.25.2  Output<\/a><br \/>    <a href=\"#tth_sEc7.26\">7.26  Calculation of Numbers of Hops: <b><tt>transition.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.26.1\">7.26.1  Usage<\/a><br \/>    <a href=\"#tth_sEc7.27\">7.27  Fitting population data to kinetic models: <b><tt>make_fit.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.27.1\">7.27.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.27.2\">7.27.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.27.3\">7.27.3  Output<\/a><br \/>    <a href=\"#tth_sEc7.28\">7.28  Obtaining Special Geometries: <b><tt>crossing.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.28.1\">7.28.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.28.2\">7.28.2  Output<\/a><br \/>    <a href=\"#tth_sEc7.29\">7.29  Essential Dynamics Analysis: <b><tt>trajana_essdyn.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.29.1\">7.29.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.29.2\">7.29.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.29.3\">7.29.3  Output<\/a><br \/>    <a href=\"#tth_sEc7.30\">7.30  General Data Analysis: <b><tt>data_collector.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.30.1\">7.30.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.30.2\">7.30.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.30.3\">7.30.3  Output<\/a><br \/>    <a href=\"#tth_sEc7.31\">7.31  Handling large sets of coordinate data: <b><tt>align_and_reorder_traj.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.31.1\">7.31.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.31.2\">7.31.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.31.3\">7.31.3  Output<\/a><br \/>    <a href=\"#tth_sEc7.32\">7.32  Producing radial distribution functions: <b><tt>frames_to_RDF.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.32.1\">7.32.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.32.2\">7.32.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.32.3\">7.32.3  Options<\/a><br \/>        <a href=\"#tth_sEc7.32.4\">7.32.4  Output<\/a><br \/>        <a href=\"#tth_sEc7.32.5\">7.32.5  Obtaining mask files<\/a><br \/>    <a href=\"#tth_sEc7.33\">7.33  Producing 3D distributions: <b><tt>frames_to_dx.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.33.1\">7.33.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.33.2\">7.33.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.33.3\">7.33.3  Options<\/a><br \/>        <a href=\"#tth_sEc7.33.4\">7.33.4  Output<\/a><br \/>    <a href=\"#tth_sEc7.34\">7.34  Computing X-ray scattering: <b><tt>RDF_to_scattering.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.34.1\">7.34.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.34.2\">7.34.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.34.3\">7.34.3  Options<\/a><br \/>        <a href=\"#tth_sEc7.34.4\">7.34.4  Output<\/a><br \/>    <a href=\"#tth_sEc7.35\">7.35  Optimizations: <b><tt>otool_external<\/tt><\/b> and <b><tt>setup_orca_opt.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.35.1\">7.35.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.35.2\">7.35.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.35.3\">7.35.3  Output<\/a><br \/>        <a href=\"#tth_sEc7.35.4\">7.35.4  Description of <b><tt>orca_External<\/tt><\/b> and <b><tt>otool_external<\/tt><\/b><\/a><br \/>    <a href=\"#tth_sEc7.36\">7.36  Single Point Calculations: <b><tt>setup_single_point.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.36.1\">7.36.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.36.2\">7.36.2  Input<\/a><br \/>        <a href=\"#tth_sEc7.36.3\">7.36.3  Output<\/a><br \/>    <a href=\"#tth_sEc7.37\">7.37  Format Data from <b><tt>QM.out<\/tt><\/b> Files: <b><tt>QMout_print.py<\/tt><\/b><\/a><br \/>        <a href=\"#tth_sEc7.37.1\">7.37.1  Usage<\/a><br \/>        <a href=\"#tth_sEc7.37.2\">7.37.2  Output<\/a><br \/><a href=\"#tth_chAp8\">8  Methods and Algorithms<\/a><br \/>    <a href=\"#tth_sEc8.1\">8.1  Absorption Spectrum<\/a><br \/>    <a href=\"#tth_sEc8.2\">8.2  Active and inactive states<\/a><br \/>    <a href=\"#tth_sEc8.3\">8.3  Amdahl’s Law<\/a><br \/>    <a href=\"#tth_sEc8.4\">8.4  Bootstrapping for Population Fits<\/a><br \/>    <a href=\"#tth_sEc8.5\">8.5  Computing electronic populations<\/a><br \/>    <a href=\"#tth_sEc8.6\">8.6  Damping<\/a><br \/>    <a href=\"#tth_sEc8.7\">8.7  Decoherence<\/a><br \/>        <a href=\"#tth_sEc8.7.1\">8.7.1  Energy-based decoherence<\/a><br \/>        <a href=\"#tth_sEc8.7.2\">8.7.2  Augmented FSSH decoherence<\/a><br \/>    <a href=\"#tth_sEc8.8\">8.8  Essential Dynamics Analysis<\/a><br \/>    <a href=\"#tth_sEc8.9\">8.9  Excitation Selection<\/a><br \/>        <a href=\"#tth_sEc8.9.1\">8.9.1  Excitation Selection with Diabatization<\/a><br \/>    <a href=\"#tth_sEc8.10\">8.10  Global fits and kinetic models<\/a><br \/>        <a href=\"#tth_sEc8.10.1\">8.10.1  Reaction networks<\/a><br \/>        <a href=\"#tth_sEc8.10.2\">8.10.2  Kinetic models<\/a><br \/>        <a href=\"#tth_sEc8.10.3\">8.10.3  Global fit<\/a><br \/>    <a href=\"#tth_sEc8.11\">8.11  Gradient transformation<\/a><br \/>        <a href=\"#tth_sEc8.11.1\">8.11.1  Nuclear gradient tensor transformation scheme<\/a><br \/>        <a href=\"#tth_sEc8.11.2\">8.11.2  Time derivative matrix transformation scheme<\/a><br \/>        <a href=\"#tth_sEc8.11.3\">8.11.3  Dipole moment derivatives<\/a><br \/>    <a href=\"#tth_sEc8.12\">8.12  Internal coordinates definitions<\/a><br \/>    <a href=\"#tth_sEc8.13\">8.13  Kinetic energy adjustments<\/a><br \/>        <a href=\"#tth_sEc8.13.1\">8.13.1  Reflection for frustrated hops<\/a><br \/>        <a href=\"#tth_sEc8.13.2\">8.13.2  Choices of momentum adjustment direction<\/a><br \/>    <a href=\"#tth_sEc8.14\">8.14  Projection operator<\/a><br \/>    <a href=\"#tth_sEc8.15\">8.15  Fewest switches with time uncertainty<\/a><br \/>    <a href=\"#tth_sEc8.16\">8.16  Laser fields<\/a><br \/>        <a href=\"#tth_sEc8.16.1\">8.16.1  Form of the laser field<\/a><br \/>        <a href=\"#tth_sEc8.16.2\">8.16.2  Envelope functions<\/a><br \/>        <a href=\"#tth_sEc8.16.3\">8.16.3  Field functions<\/a><br \/>        <a href=\"#tth_sEc8.16.4\">8.16.4  Chirped pulses<\/a><br \/>        <a href=\"#tth_sEc8.16.5\">8.16.5  Quadratic chirp without Fourier transform<\/a><br \/>    <a href=\"#tth_sEc8.17\">8.17  Laser interactions<\/a><br \/>        <a href=\"#tth_sEc8.17.1\">8.17.1  Surface Hopping with laser fields<\/a><br \/>    <a href=\"#tth_sEc8.18\">8.18  Linear\/Quadratic Vibronic Coupling Models<\/a><br \/>        <a href=\"#tth_sEc8.18.1\">8.18.1  Obtaining LVC parameters from ab initio data<\/a><br \/>    <a href=\"#tth_sEc8.19\">8.19  Normal Mode Analysis<\/a><br \/>    <a href=\"#tth_sEc8.20\">8.20  Optimization of Crossing Points<\/a><br \/>    <a href=\"#tth_sEc8.21\">8.21  Phase tracking<\/a><br \/>        <a href=\"#tth_sEc8.21.1\">8.21.1  Phase tracking of the transformation matrix<\/a><br \/>        <a href=\"#tth_sEc8.21.2\">8.21.2  Tracking of the phase of the MCH wave functions<\/a><br \/>    <a href=\"#tth_sEc8.22\">8.22  Random initial velocities<\/a><br \/>    <a href=\"#tth_sEc8.23\">8.23  Representations<\/a><br \/>        <a href=\"#tth_sEc8.23.1\">8.23.1  Current state in MCH representation<\/a><br \/>    <a href=\"#tth_sEc8.24\">8.24  Sampling from Wigner Distribution<\/a><br \/>        <a href=\"#tth_sEc8.24.1\">8.24.1  Sampling at Non-zero Temperature<\/a><br \/>    <a href=\"#tth_sEc8.25\">8.25  Scaling<\/a><br \/>    <a href=\"#tth_sEc8.26\">8.26  Seeding of the RNG<\/a><br \/>    <a href=\"#tth_sEc8.27\">8.27  Selection of gradients and nonadiabatic couplings<\/a><br \/>    <a href=\"#tth_sEc8.28\">8.28  State ordering<\/a><br \/>    <a href=\"#tth_sEc8.29\">8.29  Surface Hopping<\/a><br \/>    <a href=\"#tth_sEc8.30\">8.30  Self-Consistent Potential Methods<\/a><br \/>        <a href=\"#tth_sEc8.30.1\">8.30.1  Decoherence in SCP methods<\/a><br \/>    <a href=\"#tth_sEc8.31\">8.31  Effective Nonadiabatic Coupling Vector<\/a><br \/>    <a href=\"#tth_sEc8.32\">8.32  Velocity Verlet<\/a><br \/>    <a href=\"#tth_sEc8.33\">8.33  Wavefunction propagation<\/a><br \/>        <a href=\"#tth_sEc8.33.1\">8.33.1  Propagation using nonadiabatic couplings<\/a><br \/>        <a href=\"#tth_sEc8.33.2\">8.33.2  Propagation using overlap matrices – Local diabatization<\/a><br \/>        <a href=\"#tth_sEc8.33.3\">8.33.3  Propagation using overlap matrices – Norm-preserving interpolation<\/a><br \/>    <a href=\"#tth_sEc8.34\">8.34  Time Derivative Couplings and Curvature Approximation<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_chAp1\"><\/a><\/p>\n<h1>\nChapter 1 <br \/>Introduction<\/h1>\n<div class=\"p\"><!----><\/div>\n<p>When a molecule is irradiated by light, a number of dynamical processes can take place, in which the molecule redistributes the energy among different electronic and vibrational degrees of freedom.<br \/>\nKasha’s rule <a href=\"#Kasha1950DFS\" id=\"CITEKasha1950DFS\" class=\"tth_citation\">[1<\/a>] states that radiationless transfer from higher excited singlet states to the lowest-lying excited singlet state (S<sub>1<\/sub>) is faster than fluorescence (F).<br \/>\nThis radiationless transfer is called internal conversion (IC) and involves a changes between electronic states of the same multiplicity.<br \/>\nIf a transition occurs between electronic states of different spin, the process is called intersystem crossing (ISC).<br \/>\nA typical ISC process is from a singlet to a triplet state, and once the lowest triplet is populated, phosphorescence (P) can take place.<br \/>\nIn Figure <a href=\"#fig:jablonski\">1.1<\/a>, radiative (F and P) and radiationless (IC and ISC) processes are summarized in a so-called Jablonski diagram.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg1.1\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/jablonski.png\"> <\/p>\n<div style=\"text-align:center\">Figure 1.1: Jablonski diagram showing the conceptual photophysical processes. Straight arrows show radiative processes: absorption (hν), fluorescence (F), and phosphorescence (P); wavy arrows show radiationless processes: internal conversion (IC) and intersystem crossing (ISC). <\/div>\n<p> <a id=\"fig:jablonski\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>The non-radiative IC and ISC processes are fundamental concepts which play a decisive role in photophysics, photochemistry, and photobiology.<br \/>\nIC processes are present in the excited-state dynamics of many organic and inorganic molecules, whose applications range from solar energy conversion to drug therapy.<br \/>\nEven many, very small molecules, for example O2 and O3, SO2, NO2 and other nitrous oxides, show efficient IC, which has important consequences in atmospheric chemistry and the study of the environment and pollution.<br \/>\nIC is also the first step of the biological process of visual perception, where the retinal moiety of rhodopsin absorbs a photon and non-radiatively performs a torsion around one of the double bonds, changing the conformation of the protein and inducing a neural signal.<br \/>\nSimilarly, protection of the human body from the influence of UV light is achieved through very efficient IC in DNA, proteins and melanins.<br \/>\nUltrafast IC to the electronic ground state allows quickly converting the excitation energy of the UV photons into nuclear kinetic energy, which is spread harmlessly as heat to the environment.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>ISC processes are completely forbidden in the frame of the non-relativistic Schrödinger equation, but they become allowed when including spin-orbit couplings, a relativistic effect <a href=\"#Marian2012WCMS\" id=\"CITEMarian2012WCMS\" class=\"tth_citation\">[2<\/a>].<br \/>\nSpin-orbit coupling depends on the nuclear charge and becomes stronger for heavy atoms, therefore it is typically known as a “heavy atom” effect.<br \/>\nHowever, it has been recently recognized that even for molecules with only first- and second-row atoms, ISC might be relevant and can be competitive in time scales with IC.<br \/>\nA small selection of the growing number of molecules where efficient ISC in a sub-ps time scale has been predicted are SO2 <a href=\"#Wilkinson2014JCP\" id=\"CITEWilkinson2014JCP\" class=\"tth_citation\">[3<\/a>,<a href=\"#Mai2014JCP_SO2\" id=\"CITEMai2014JCP_SO2\" class=\"tth_citation\">[4<\/a>,<a href=\"#Leveque2014JCP_ISC\" id=\"CITELeveque2014JCP_ISC\" class=\"tth_citation\">[5<\/a>], benzene <a href=\"#Penfold2012JCP\" id=\"CITEPenfold2012JCP\" class=\"tth_citation\">[6<\/a>], aromatic nitrocompounds <a href=\"#Vogt2013JPC\" id=\"CITEVogt2013JPC\" class=\"tth_citation\">[7<\/a>] or DNA nucleobases and derivatives <a href=\"#Crespo-Hernandez2004CR\" id=\"CITECrespo-Hernandez2004CR\" class=\"tth_citation\">[8<\/a>,<a href=\"#Richter2012JPCL\" id=\"CITERichter2012JPCL\" class=\"tth_citation\">[9<\/a>,<a href=\"#Martinez-Fernandez2012CC\" id=\"CITEMartinez-Fernandez2012CC\" class=\"tth_citation\">[10<\/a>,<a href=\"#Mai2013C\" id=\"CITEMai2013C\" class=\"tth_citation\">[11<\/a>,<a href=\"#Reichardt2010CC\" id=\"CITEReichardt2010CC\" class=\"tth_citation\">[12<\/a>].<br \/>\nHowever, IC and ISC are also of fundamental importance in transition metal complexes, which are often used as photosensitizers or photocatalysts in various technological applications.<br \/>\nOverall, it can be said that the possible applications of photoinduced ultrafast dynamics are legion, and its understanding is of critical importance for many scientific investigations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Theoretical simulations can greatly contribute to understand non-radiative processes by following the nuclear motion on the excited-state potential energy surfaces (PES) in real time.<br \/>\nThese simulations are called excited-state dynamics simulations.<br \/>\nSince the Born-Oppenheimer approximation is not applicable for this kind of dynamics, nonadiabatic effects need to be incorporated into the simulations.<br \/>\nThe principal methodology to tackle excited-state dynamics simulations is to numerically integrate the time-dependent Schrödinger equation, which is usually called full quantum dynamics simulations (QD).<br \/>\nGiven accurate PESs, QD is able to match experimental accuracy.<br \/>\nHowever, the need for the “a priori” knowledge of the full multi-dimensional PES renders this type of simulations quickly unfeasible for more than few degrees of freedom.<br \/>\nSeveral alternative methodologies are possible to alleviate this problem.<br \/>\nOne of the most popular ones is to use surface hopping nonadiabatic dynamics.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Surface hopping was originally devised by Tully <a href=\"#Tully1971JCP\" id=\"CITETully1971JCP\" class=\"tth_citation\">[13<\/a>] and greatly improved later by the “fewest-switches criterion”<a href=\"#Tully1990JCP\" id=\"CITETully1990JCP\" class=\"tth_citation\">[14<\/a>] and it has been reviewed extensively since then, see e.g. <a href=\"#Barbatti2011WCMS\" id=\"CITEBarbatti2011WCMS\" class=\"tth_citation\">[15<\/a>,<a href=\"#Subotnik2016ARPC\" id=\"CITESubotnik2016ARPC\" class=\"tth_citation\">[16<\/a>,<a href=\"#Wang2016JPCL\" id=\"CITEWang2016JPCL\" class=\"tth_citation\">[17<\/a>,<a href=\"#Doltsinis2006\" id=\"CITEDoltsinis2006\" class=\"tth_citation\">[18<\/a>,<a href=\"#Doltsinis2002JTCC\" id=\"CITEDoltsinis2002JTCC\" class=\"tth_citation\">[19<\/a>].<br \/>\nIn surface hopping, the motion of the excited-state wave packet is approximated by the motion of an ensemble of many independent, classical trajectories. Each trajectory is at every instant of time tied to one particular PES, and the nuclear motion is integrated using the gradient of this PES. However, nonadiabatic population transfer can lead to the switching of a trajectory from one PES to another PES. This switching (also called “hopping”, which is the origin of the name “surface hopping”) is based on a stochastic algorithm, taking into account the change of the electronic population from one time step to the next one.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The advantages of the surface hopping methodology and thus its popularity are well summarized in Ref. <a href=\"#Barbatti2011WCMS\" class=\"tth_citeref\">[15<\/a>]:<\/p>\n<ul>\n<li> The method is conceptually simple, since it is based on classical mechanics. The nuclear propagation is based on Newton’s equations and can be performed in Cartesian coordinates, avoiding any problems with curved coordinate systems as in QD.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> For the propagation of the trajectories only local information of the PESs is needed. This avoids the calculation of the full, multi-dimensional PES in advance, which is the main bottleneck of QD methods. In surface hopping dynamics, all degrees of freedom can be included in the simulation. Additionally, all necessary quantities can be calculated on-demand, usually called “on-the-fly” in this context.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> The independent trajectories can be trivially parallelized.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<p>The strongest of these points of course is the fact that all degrees of freedom can be included easily in the calculations, allowing to describe large systems.<br \/>\nOne should note, however, that surface hopping methods in the standard formulation <a href=\"#Tully1971JCP\" class=\"tth_citeref\">[13<\/a>,<a href=\"#Tully1990JCP\" class=\"tth_citeref\">[14<\/a>]-due to the classical nature of the trajectories-do not allow to treat some purely quantum-mechanical effects like tunneling, (tunneling for selected degrees of freedom is possible <a href=\"#Hammes-Schiffer1994JCP\" id=\"CITEHammes-Schiffer1994JCP\" class=\"tth_citation\">[20<\/a>]). Additionally, quantum coherence between the electronic states is usually described poorly, because of the independent-trajectory ansatz. This can be treated with some ad-hoc corrections, e.g., in <a href=\"#Granucci2007JCP\" id=\"CITEGranucci2007JCP\" class=\"tth_citation\">[21<\/a>].<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the original surface hopping method, only nonadiabatic couplings are considered, only allowing for population transfer between electronic states of the same multiplicity (IC).<br \/>\nThe S<span style=\"font-size:x-small\">HARC<\/span> methodology is a generalization of standard surface hopping since it allows to include any type of coupling. Beyond nonadiabatic couplings (for IC), spin-orbit couplings (for ISC) or interactions of dipole moments with electric fields (to explicitly describe laser-induced processes) can be included.<br \/>\nA number of methodologies for surface hopping including one or the other type of potential couplings have been proposed in references <a href=\"#Thachuk1996JCP\" id=\"CITEThachuk1996JCP\" class=\"tth_citation\">[22<\/a>,<a href=\"#Maiti2004JPCA\" id=\"CITEMaiti2004JPCA\" class=\"tth_citation\">[23<\/a>,<a href=\"#Jones2008JPCA\" id=\"CITEJones2008JPCA\" class=\"tth_citation\">[24<\/a>,<a href=\"#Mitric2009PRA\" id=\"CITEMitric2009PRA\" class=\"tth_citation\">[25<\/a>,<a href=\"#Granucci2012JCP\" id=\"CITEGranucci2012JCP\" class=\"tth_citation\">[26<\/a>,<a href=\"#Curchod2013C\" id=\"CITECurchod2013C\" class=\"tth_citation\">[27<\/a>,<a href=\"#Cui2014JCP\" id=\"CITECui2014JCP\" class=\"tth_citation\">[28<\/a>], but S<span style=\"font-size:x-small\">HARC<\/span> can include all types of potential couplings on the same footing. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span> methodology is an extension to standard surface hopping which allows to include these kinds of couplings. The central idea of S<span style=\"font-size:x-small\">HARC<\/span> is to obtain a fully diagonal Hamiltonian, which is adiabatic with respect to all couplings. The diagonal Hamiltonian is obtained by unitary transformation of the Hamiltonian including all couplings. Surface hopping is conducted on the transformed electronic states.<br \/>\nThis has a number of advantages over the standard surface hopping methodology, where no diagonalization is performed:<\/p>\n<ul>\n<li> Potential couplings (like spin-orbit couplings and laser-dipole couplings) are usually delocalized. Surface hopping, however, rests on the assumption that the couplings are localized and hence surface hops only occur in the small region where the couplings are large. Within S<span style=\"font-size:x-small\">HARC<\/span>, by transforming away the potential couplings, additional terms of nonadiabatic (kinetic) couplings arise, which are localized.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> The potential couplings have an influence on the gradients acting on the nuclei. To a good approximation, within S<span style=\"font-size:x-small\">HARC<\/span> it is possible to include this influence in the dynamics.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> When including spin-orbit couplings for states of higher multiplicity, diagonalization solves the problem of rotational invariance of the multiplet components (see <a href=\"#Granucci2012JCP\" class=\"tth_citeref\">[26<\/a>]).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span> suite of programs is an implementation of the S<span style=\"font-size:x-small\">HARC<\/span> method.<br \/>\nBesides the core dynamics code, it comes with a number of tools aiding in the setup, maintenance, and analysis of the trajectories.<br \/>\nIt also provides a large suite of interfaces to many different electronic structure methods and models for excited-state potential energy surfaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc1.1\"><\/a><\/p>\n<h2>\n1.1  Capabilities<\/h2>\n<div class=\"p\"><!----><\/div>\n<p>The main features of the S<span style=\"font-size:x-small\">HARC<\/span> suite in Version 4.0 are:<\/p>\n<ul>\n<li> Non-adiabatic dynamics based on the surface hopping (SH) <a href=\"#Mai2018\" id=\"CITEMai2018\" class=\"tth_citation\">[29<\/a>] and coherent switching with decay of mixing (CSDM) <a href=\"#Zhu2004JCP\" id=\"CITEZhu2004JCP\" class=\"tth_citation\">[30<\/a>,<a href=\"#ShuCSDM2020JCTC\" id=\"CITEShuCSDM2020JCTC\" class=\"tth_citation\">[31<\/a>] methodologies\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Ability to describe internal conversion and intersystem crossing with any number of states (singlets, doublets, triplets, or higher multiplicities).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Inclusion of interactions with laser fields in the dipole approximation.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Algorithms for stable wave function propagation in the presence of very small or very large couplings.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Propagation using either nonadiabatic couplings vectors 〈α|[(∂)\/(∂<b>R<\/b>)]|β〉, wave function overlaps 〈α(t<sub>0<\/sub>)|β(t)〉 (via the local diabatization procedure <a href=\"#Granucci2007JCP\" class=\"tth_citeref\">[21<\/a>]), or based on the curvature of the potential energy surfaces <a href=\"#Shu2022JCTC\" id=\"CITEShu2022JCTC\" class=\"tth_citation\">[32<\/a>,<a href=\"#Zhao2023JCTC2\" id=\"CITEZhao2023JCTC2\" class=\"tth_citation\">[33<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Gradients including the effects of spin-orbit couplings (with the approximation that the diabatic spin-orbit couplings are slowly varying).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> A flexible, modular, nestable suite of interfaces to potential energy surface models, electronic structure softwares, and multiscale models <a href=\"#Mausenberger2025Chemrxiv\" id=\"CITEMausenberger2025Chemrxiv\" class=\"tth_citation\">[34<\/a>].<br \/>\n The interface suite contains:<\/p>\n<ul>\n<li> Fast, I\/O-avoiding interfaces for analytical model potentials, linear\/quadratic vibronic coupling models (optionally with electrostatic embedding) <a href=\"#Plasser2018PCCP\" id=\"CITEPlasser2018PCCP\" class=\"tth_citation\">[35<\/a>,<a href=\"#Polonius2023JCTC\" id=\"CITEPolonius2023JCTC\" class=\"tth_citation\">[36<\/a>,<a href=\"#Polonius2024JCTC\" id=\"CITEPolonius2024JCTC\" class=\"tth_citation\">[37<\/a>], molecular mechanics force fields ( O<span style=\"font-size:x-small\">PEN<\/span>MM) and machine-learning potentials based on the F<span style=\"font-size:x-small\">IELD<\/span>S<span style=\"font-size:x-small\">CHNET<\/span> (with electrostatic embedding) or SP<span style=\"font-size:x-small\">AI<\/span>NN packages;\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interfaces for TD-DFT: G<span style=\"font-size:x-small\">AUSSIAN<\/span> 16, O<span style=\"font-size:x-small\">RCA<\/span> 5 and 6, NWChem 7.2, and AMS ADF;\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interfaces for ADC(2) and CC2: Turbomole 7.8;\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interfaces for SA-CASSCF and correlated multireference methods (various variants of CASPT2, MRCI, and PDFT): O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> 23 and 24, M<span style=\"font-size:x-small\">OLPRO<\/span> 2023, C<span style=\"font-size:x-small\">OLUMBUS<\/span>, B<span style=\"font-size:x-small\">AGEL<\/span>, and P<span style=\"font-size:x-small\">Y<\/span>SCF;\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interfaces for semi-empirical excited-state methods: MNDO and M<span style=\"font-size:x-small\">OPAC<\/span>-PI;\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Nestable “hybrid” interfaces for<br \/>\n quantum mechanics\/molecular mechanics (QM\/MM),<br \/>\n excitonic configuration interaction (ECI),<br \/>\n adaptive sampling,<br \/>\n numerical differentiation,<br \/>\n umbrella sampling,<br \/>\n and storing electronic structure data.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Energy-difference-based partial coupling approximation to speed up calculations <a href=\"#Pittner2009CP\" id=\"CITEPittner2009CP\" class=\"tth_citation\">[38<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Energy-based decoherence correction <a href=\"#Granucci2007JCP\" class=\"tth_citeref\">[21<\/a>], augmented-FSSH decoherence correction <a href=\"#Jain2016JCTC\" id=\"CITEJain2016JCTC\" class=\"tth_citation\">[39<\/a>] and decay-of-mixing decoherence for SCP methods to perform CSDM or SCDM <a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>,<a href=\"#ZhuSCDM2004JCP\" id=\"CITEZhuSCDM2004JCP\" class=\"tth_citation\">[40<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Calculation of Dyson norms for single-photon ionization spectra (for most interfaces) <a href=\"#Ruckenbauer2016SR\" id=\"CITERuckenbauer2016SR\" class=\"tth_citation\">[41<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> On-the-fly wave function analysis with TheoDORE <a href=\"#Plasser2014JCP1\" id=\"CITEPlasser2014JCP1\" class=\"tth_citation\">[42<\/a>,<a href=\"#Plasser2014JCP2\" id=\"CITEPlasser2014JCP2\" class=\"tth_citation\">[43<\/a>,<a href=\"#Plasser2017TheoDORE\" id=\"CITEPlasser2017TheoDORE\" class=\"tth_citation\">[44<\/a>] (for several interfaces).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Langevin thermostat and droplet restraining potentials.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Suite of auxiliary Python scripts for all steps of the setup procedure and for various analysis tasks: Electronic populations, nuclear motion, time-resolved spectra, solvent distributions, X-ray scattering, and several others.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Methods to parametrize vibronic coupling models (and support for active learning of machine-learning models).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Code to optimize minima and minimum-energy intersections (using the O<span style=\"font-size:x-small\">RCA<\/span> optimizer).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Comprehensive tutorial.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc1.1.1\"><\/a><\/p>\n<h3>\n1.1.1  New features in S<span style=\"font-size:x-small\">HARC<\/span> Version 4.0<\/h3>\n<div class=\"p\"><!----><\/div>\n<p> <b>The S<span style=\"font-size:x-small\">HARC<\/span> Version 4.0 constitutes a significant milestone in the development of the package.<\/b><br \/>\nThe main goal was to <b>redesign the complete framework of the communication<\/b> between the S<span style=\"font-size:x-small\">HARC<\/span> dynamics driver and the electronic structure data providers.<br \/>\nTo this end, a complete refactoring of the interfaces was carried out.<br \/>\nThe new interfaces are developed in an object-oriented way, using inheritance to simplify development.<br \/>\nThe communication protocol was generalized and made more rigorous.<br \/>\nFor the user, the main advantages are (i) better performance for fast dynamics using model potentials, (ii) more systematic setup routines, and (iii) the possibility to combine and nest interfaces to achieve a broad variety of workflows.<br \/>\nThese “<b>interfaces that can call other interfaces<\/b>” are called <i>hybrid interfaces<\/i> in S<span style=\"font-size:x-small\">HARC<\/span>.<br \/>\nThe modularity of these hybrid interfaces was the inspiration for the new S<span style=\"font-size:x-small\">HARC<\/span> logo.<br \/>\nThe hybrid interfaces enable methods like<br \/>\nquantum mechanics\/molecular mechanics (QM\/MM) to describe solvated molecules,<br \/>\nexcitonic configuration interaction (ECI) to describe multichromophoric systems,<br \/>\nadaptive sampling and automatic data storage to collect electronic structure data (for machine learning or other purposes),<br \/>\nautomatic numerical differentiation (to get gradients, nonadiabatic couplings, or other derivatives), or<br \/>\numbrella sampling for various sampling tasks.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The most important changes in S<span style=\"font-size:x-small\">HARC<\/span> 4.0 are:<\/p>\n<ul>\n<li> Dynamics program:\n<ul>\n<li> There are now two dynamics drivers, <b><tt>sharc.x<\/tt><\/b> and <b><tt>driver.py<\/tt><\/b>.<br \/>\n The former driver supports all previous and new features of S<span style=\"font-size:x-small\">HARC<\/span> and uses a file-I\/O-based communication with the interfaces.<br \/>\n The latter driver communicates with all interfaces directly in-memory, similar to the previous PySHARC modules.<br \/>\n Whenever we refer to PySHARC in this manual, we refer to working with <b><tt>driver.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Some features that in S<span style=\"font-size:x-small\">HARC<\/span> 3 were only available in <b><tt>sharc.x<\/tt><\/b> are now also available in <b><tt>driver.py<\/tt><\/b> (e.g., Army Ants, time uncertainty, SCP\/Ehrenfest, CSDM, curvature-driven dynamics).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Langevin thermostat and droplet restraining potential for long dynamics of liquid droplets.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interfaces:\n<ul>\n<li> Complete redesign, using new data classes and interface base classes, refactoring of most interfaces as given below\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> New electronic structure information:\n<ul>\n<li> Atom-centered multipole fit of electron densities up to quadrupole charges based on the RESP method,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interfaces can deliver basis set information and density matrices (handled with PySCF),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interfaces can receive a dedicated set of point charges to use in electrostatic embedding, and can deliver gradients and NACs on these point charges,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Stub interfaces:\n<ul>\n<li> <b><tt>SHARC_DO_NOTHING.py<\/tt><\/b>: for testing and developing\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_QMOUT.py<\/tt><\/b>: for frozen-nuclei trajectories\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Fast interfaces:\n<ul>\n<li> <b><tt>SHARC_ANALYTICAL.py<\/tt><\/b>: for analytical PESs, redesigned around <b><tt>sympy<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_LVC.py<\/tt><\/b>: for vibronic coupling models, redesigned and strongly improved, can do electrostatic embedding,<a href=\"#Polonius2023JCTC\" class=\"tth_citeref\">[36<\/a>,<a href=\"#Polonius2024JCTC\" class=\"tth_citeref\">[37<\/a>,<a href=\"#Farkhutdinova2025JPCA\" id=\"CITEFarkhutdinova2025JPCA\" class=\"tth_citation\">[45<\/a>] <b><tt>modify_LVC_template.py<\/tt><\/b> to edit LVC models,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_SPAINN.py<\/tt><\/b>: new interface for machine-learning potentials based on the PaiNN architecture,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_SCHNARC.py<\/tt><\/b>: new interface for machine-learning potentials based on the FieldSchnet architecture, which can do ML\/MM simulations,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_OPENMM.py<\/tt><\/b>: new interface for MM dynamics using A<span style=\"font-size:x-small\">MBER<\/span> <b><tt>prmtop<\/tt><\/b> files,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Ab initio interfaces with new, S<span style=\"font-size:x-small\">HARC<\/span>4-compatible implementations:\n<ul>\n<li> <b><tt>SHARC_GAUSSIAN.py<\/tt><\/b>: redesigned, can do electrostatic embedding, RESP fits, provides density matrices, <b><tt>GAUSSIAN_freq.py<\/tt><\/b> to extract frequency Molden files,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_ORCA.py<\/tt><\/b>: redesigned, <b><tt>ORCA_hess_freq.py<\/tt><\/b> to extract frequency Molden files,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_NWCHEM.py<\/tt><\/b>: new interface for TD-DFT in NWC<span style=\"font-size:x-small\">HEM<\/span>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_TURBOMOLE.py<\/tt><\/b>: redesigned (used to be called <b><tt>SHARC_RICC2.py<\/tt><\/b>), can do electrostatic embedding, removed dependency with O<span style=\"font-size:x-small\">RCA<\/span> for spin-orbit couplings,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_MOLCAS.py<\/tt><\/b>: redesigned, can do electrostatic embedding, RESP fits, provides density matrices,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_MNDO.py<\/tt><\/b>: new interface for semi-empirical MRCI based on OM2 using the MNDO code,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_MOPACPI.py<\/tt><\/b>: new interface for semi-empirical MRCI using the M<span style=\"font-size:x-small\">OPAC<\/span>-P<span style=\"font-size:x-small\">I<\/span> code, which can do QM\/MM with Tinker,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_LEGACY.py<\/tt><\/b>: new interface that serves as a SHARC4-compatible frontend to SHARC3-style legacy interfaces,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Legacy ab initio interfaces:\n<ul>\n<li> <b><tt>SHARC_COLUMBUS.py<\/tt><\/b>, <b><tt>SHARC_BAGEL.py<\/tt><\/b>, <b><tt>SHARC_AMS_ADF.py<\/tt><\/b>: minor changes to make them compatible to <b><tt>SHARC_LEGACY.py<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_MOLPRO.py<\/tt><\/b>: updated to work with MOLPRO 2023, minor changes to make it compatible to <b><tt>SHARC_LEGACY.py<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_PYSCF.py<\/tt><\/b>: new S<span style=\"font-size:x-small\">HARC<\/span>3-style legacy interface for PySCF (CASSCF, MC-PDFT),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Single-child hybrid interfaces:\n<ul>\n<li> <b><tt>SHARC_ASE_DB.py<\/tt><\/b>: new single-child hybrid interface to store geometries and electronic properties into a database,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_UMBRELLA.py<\/tt><\/b>: new single-child hybrid interface to add harmonic restrains to any other interface,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_NUMDIFF.py<\/tt><\/b>: new “multiple clones of a single-child” hybrid interface for numerical gradients, nonadiabatic couplings, spin-orbit\/dipole derivatives,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Multi-child hybrid interfaces:\n<ul>\n<li> <b><tt>SHARC_QMMM.py<\/tt><\/b>: new multi-child hybrid interface for electrostatic-embedding QM\/MM,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_ECI.py<\/tt><\/b>: new multi-child hybrid interface for divide-and-conquer-style excitonic configuration interaction calculations,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_ADAPTIVE.py<\/tt><\/b>: new multi-child hybrid interface for adaptive sampling (also called active learning or query by committee),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>SHARC_FALLBACK.py<\/tt><\/b>: new multi-child hybrid interface that calls a secondary backup interface if a primary trial interface fails,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> New save directory management concept that simplifies assignment of saved files to time steps, automatic garbage collection in save directory,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Charges per multiplicity are now defined by the driver\/parent interface, rather than in template files,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interfaces know their own set of features and have their own setup routines, thus work smoother with all setup tools, <b><tt>factory.py<\/tt><\/b> tool to find all available interfaces,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Better support for calculations with many atoms:\n<ul>\n<li> <b><tt>restartnc_to_xyz.py<\/tt><\/b>, <b><tt>setup_from_prmtop.py<\/tt><\/b>, <b><tt>sharctraj_to_xyz.py<\/tt><\/b>: new tools that help setting up and analyzing trajectories from A<span style=\"font-size:x-small\">MBER<\/span> restart and prmtop files as well as to recycle S<span style=\"font-size:x-small\">HARC<\/span> trajectories into new initial conditions\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>align_and_reorder.py<\/tt><\/b>, <b><tt>frame_to_RDF.py<\/tt><\/b>, <b><tt>frame_to_dx.py<\/tt><\/b>, <b><tt>RDF_to_scattering.py<\/tt><\/b>: new tools to analyze the time-dependent one- or three-dimensional distributions of solvent around a target molecule and related X-ray scattering.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> The drivers can save electronic and nuclear data in separate output files with separate strides.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Other changes:\n<ul>\n<li> <b><tt>geo_NM.py<\/tt><\/b>: To compute normal mode coordinates from xyz. Using a combination of <b><tt>geo_NM.py<\/tt><\/b> and <b><tt>data_collector.py<\/tt><\/b>, one can achieve all functionality of <b><tt>trajana_nma.py<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>data_converter_to_ASCII.x<\/tt><\/b> to convert output data files in NetCDF format to ASCII format.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>wigner_state_selected.py<\/tt><\/b> updated and <b><tt>bimolecular_collision.py<\/tt><\/b> added\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>spectrum.py<\/tt><\/b> can compute absolute absorption cross sections\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Removed and deprecated functionalities:\n<ul>\n<li> <b><tt>trajana_nma.py<\/tt><\/b> is superseded by a combination of <b><tt>geo_NM.py<\/tt><\/b> and <b><tt>data_collector.py<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>make_fitscript.py<\/tt><\/b> and <b><tt>bootstrap.py<\/tt><\/b> are superseded by <b><tt>make_fit.py<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>ORCA_freq.py<\/tt><\/b> is superseded by <b><tt>ORCA_hess_freq.py<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>pysharc_lvc.py<\/tt><\/b> and <b><tt>pysharc_qmout.py<\/tt><\/b> are superseded by <b><tt>driver.py<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> The link with the COBRAMM package is not present in S<span style=\"font-size:x-small\">HARC<\/span>4 currently. QM\/MM simulations can be setup and run using <b><tt>tleap<\/tt><\/b>, <b><tt>setup_from_prmtop.py<\/tt><\/b>, <b><tt>setpu_traj.py<\/tt><\/b>, <b><tt>SHARC_QMMM.py<\/tt><\/b>, <b><tt>SHARC_OPENMM.py<\/tt><\/b>, and new functions within <b><tt>sharc.x<\/tt><\/b>\/<b><tt>driver.py<\/tt><\/b>. Alternatively, you can still use S<span style=\"font-size:x-small\">HARC<\/span>3 with COBRAMM.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> All package parts now use fully consistently defined physical constants.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc1.2\"><\/a><\/p>\n<h2>\n1.2  References<\/h2>\n<div class=\"p\"><!----><\/div>\n<p>The following references should be cited when using the S<span style=\"font-size:x-small\">HARC<\/span> suite:<\/p>\n<ul>\n<li> <a href=\"#Mai2018WCMS\" id=\"CITEMai2018WCMS\" class=\"tth_citation\">[46<\/a>] Mai2018WCMS.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"#Mai2025SHARC\" id=\"CITEMai2025SHARC\" class=\"tth_citation\">[47<\/a>] Mai2025SHARC.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>Details can be found in the following references:<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The theoretical background of S<span style=\"font-size:x-small\">HARC<\/span> is described in Refs. <a href=\"#Richter2011JCTC\" id=\"CITERichter2011JCTC\" class=\"tth_citation\">[48<\/a>,<a href=\"#Richter2012JCTC_erratum\" id=\"CITERichter2012JCTC_erratum\" class=\"tth_citation\">[49<\/a>,<a href=\"#Mai2015IJQC\" id=\"CITEMai2015IJQC\" class=\"tth_citation\">[50<\/a>,<a href=\"#Mai2018WCMS\" class=\"tth_citeref\">[46<\/a>,<a href=\"#Mausenberger2025Chemrxiv\" class=\"tth_citeref\">[34<\/a>].<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p>Other features implemented in the S<span style=\"font-size:x-small\">HARC<\/span> suite are described in the following references:<\/p>\n<ul>\n<li> Energy-based decoherence correction: <a href=\"#Granucci2007JCP\" class=\"tth_citeref\">[21<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Augmented-FSSH decoherence correction: <a href=\"#Jain2016JCTC\" class=\"tth_citeref\">[39<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Global flux SH: <a href=\"#Wang2014JCTC\" id=\"CITEWang2014JCTC\" class=\"tth_citation\">[51<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Local diabatization and wave function overlap calculation: <a href=\"#Granucci2001JCP\" id=\"CITEGranucci2001JCP\" class=\"tth_citation\">[52<\/a>,<a href=\"#Plasser2012JCP\" id=\"CITEPlasser2012JCP\" class=\"tth_citation\">[53<\/a>,<a href=\"#Plasser2016JCTC\" id=\"CITEPlasser2016JCTC\" class=\"tth_citation\">[54<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Sampling of initial conditions from a quantum-mechanical harmonic Wigner distribution: <a href=\"#Dahl1988JCP\" id=\"CITEDahl1988JCP\" class=\"tth_citation\">[55<\/a>,<a href=\"#Schinke1995\" id=\"CITESchinke1995\" class=\"tth_citation\">[56<\/a>,<a href=\"#Barbatti2016IJQC\" id=\"CITEBarbatti2016IJQC\" class=\"tth_citation\">[57<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Excited state selection for initial condition generation: <a href=\"#Barbatti2007JPPA\" id=\"CITEBarbatti2007JPPA\" class=\"tth_citation\">[58<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Laser field interactions: <a href=\"#Bajo2012JPCA\" id=\"CITEBajo2012JPCA\" class=\"tth_citation\">[59<\/a>,<a href=\"#Marquetand2011FD\" id=\"CITEMarquetand2011FD\" class=\"tth_citation\">[60<\/a>,<a href=\"#Heindl2021JCP\" id=\"CITEHeindl2021JCP\" class=\"tth_citation\">[61<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Calculation of ring puckering parameters and their classification: <a href=\"#Cremer1975JACS\" id=\"CITECremer1975JACS\" class=\"tth_citation\">[62<\/a>,<a href=\"#Boeyens1976JCMS\" id=\"CITEBoeyens1976JCMS\" class=\"tth_citation\">[63<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Normal mode analysis <a href=\"#Kurtz2001JCP\" id=\"CITEKurtz2001JCP\" class=\"tth_citation\">[64<\/a>,<a href=\"#Plasser2009\" id=\"CITEPlasser2009\" class=\"tth_citation\">[65<\/a>] and essential dynamics analysis: <a href=\"#Amadei1993PSFB\" id=\"CITEAmadei1993PSFB\" class=\"tth_citation\">[66<\/a>,<a href=\"#Plasser2009\" class=\"tth_citeref\">[65<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Bootstrapping for error estimation: <a href=\"#Nangia2004JCP\" id=\"CITENangia2004JCP\" class=\"tth_citation\">[67<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Crossing point optimization: <a href=\"#Bearpark1994CPL\" id=\"CITEBearpark1994CPL\" class=\"tth_citation\">[68<\/a>,<a href=\"#Levine2008JPCB\" id=\"CITELevine2008JPCB\" class=\"tth_citation\">[69<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Computation of ionization spectra: <a href=\"#Ruckenbauer2016SR\" class=\"tth_citeref\">[41<\/a>,<a href=\"#Ruckenbauer2016JCP\" id=\"CITERuckenbauer2016JCP\" class=\"tth_citation\">[70<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Wave function comparison with overlaps: <a href=\"#Plasser2016JCP\" id=\"CITEPlasser2016JCP\" class=\"tth_citation\">[71<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Dynamics with linear vibronic coupling models: <a href=\"#Plasser2018PCCP\" class=\"tth_citeref\">[35<\/a>,<a href=\"#Gomez2019JPCA\" id=\"CITEGomez2019JPCA\" class=\"tth_citation\">[72<\/a>,<a href=\"#Polonius2023JCTC\" class=\"tth_citeref\">[36<\/a>,<a href=\"#Polonius2024JCTC\" class=\"tth_citeref\">[37<\/a>,<a href=\"#Farkhutdinova2025JPCA\" class=\"tth_citeref\">[45<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Computation of electronic populations: <a href=\"#Landry2013JCP\" id=\"CITELandry2013JCP\" class=\"tth_citation\">[73<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Dynamics with neural network potentials and other machine learning properties: <a href=\"#Westermayr2020JPCL\" id=\"CITEWestermayr2020JPCL\" class=\"tth_citation\">[74<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Coherent switching with decay of mixing: <a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>,<a href=\"#ShuCSDM2020JCTC\" class=\"tth_citeref\">[31<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Time derivative algorithms tSE and tCSDM: <a href=\"#ShutCSDM2020JCTC\" id=\"CITEShutCSDM2020JCTC\" class=\"tth_citation\">[75<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Curvature driven algorithms κSE, κTSH, and κCSDM: <a href=\"#Shu2022JCTC\" class=\"tth_citeref\">[32<\/a>,<a href=\"#Zhao2023JCTC2\" class=\"tth_citeref\">[33<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Projection operator conserves angular momentum and center of mass motion: <a href=\"#Shu2020JPCL\" id=\"CITEShu2020JPCL\" class=\"tth_citation\">[76<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Time-derivative-matrix gradient correction scheme: <a href=\"#ShuTDM2023JCTC\" id=\"CITEShuTDM2023JCTC\" class=\"tth_citation\">[77<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Trajectory surface hopping with time uncertainty: <a href=\"#Jasper2002JCP\" id=\"CITEJasper2002JCP\" class=\"tth_citation\">[78<\/a>,<a href=\"#Zhao2023JCTC\" id=\"CITEZhao2023JCTC\" class=\"tth_citation\">[79<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>The quantum chemistry programs to which interfaces with S<span style=\"font-size:x-small\">HARC<\/span> exist are described in the following sources:<\/p>\n<ul>\n<li> ADF: <a href=\"#Baerends2025JCP\" id=\"CITEBaerends2025JCP\" class=\"tth_citation\">[80<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> B<span style=\"font-size:x-small\">AGEL<\/span>: <a href=\"#Shiozaki2018WCMS\" id=\"CITEShiozaki2018WCMS\" class=\"tth_citation\">[81<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> C<span style=\"font-size:x-small\">OLUMBUS<\/span>: <a href=\"#Lischka2011WCMS\" id=\"CITELischka2011WCMS\" class=\"tth_citation\">[82<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> G<span style=\"font-size:x-small\">AUSSIAN<\/span>: <a href=\"#Gaussian16\" id=\"CITEGaussian16\" class=\"tth_citation\">[83<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> M<span style=\"font-size:x-small\">OLCAS<\/span>: <a href=\"#LiManni2023JCTC\" id=\"CITELiManni2023JCTC\" class=\"tth_citation\">[84<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> M<span style=\"font-size:x-small\">OLPRO<\/span>: <a href=\"#Werner2020JCP\" id=\"CITEWerner2020JCP\" class=\"tth_citation\">[85<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> MNDO: <a href=\"#Stewart1990MOPAC\" id=\"CITEStewart1990MOPAC\" class=\"tth_citation\">[86<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> M<span style=\"font-size:x-small\">OPAC<\/span>-PI: <a href=\"#Mopac-pi\" id=\"CITEMopac-pi\" class=\"tth_citation\">[87<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> NWC<span style=\"font-size:x-small\">HEM<\/span>: <a href=\"#Apra2020JCP\" id=\"CITEApra2020JCP\" class=\"tth_citation\">[88<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> P<span style=\"font-size:x-small\">Y<\/span>SCF: <a href=\"#Sun2020JCP\" id=\"CITESun2020JCP\" class=\"tth_citation\">[89<\/a>,<a href=\"#Hennefarth2024JCTC\" id=\"CITEHennefarth2024JCTC\" class=\"tth_citation\">[90<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> O<span style=\"font-size:x-small\">RCA<\/span>: <a href=\"#Neese2017WCMS\" id=\"CITENeese2017WCMS\" class=\"tth_citation\">[91<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> T<span style=\"font-size:x-small\">URBOMOLE<\/span>: <a href=\"#TURBOMOLE70\" id=\"CITETURBOMOLE70\" class=\"tth_citation\">[92<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>Others:<\/p>\n<ul>\n<li> T<span style=\"font-size:x-small\">HEO<\/span>DORE: <a href=\"#Plasser2014JCP1\" class=\"tth_citeref\">[42<\/a>,<a href=\"#Plasser2014JCP2\" class=\"tth_citeref\">[43<\/a>,<a href=\"#Plasser2017TheoDORE\" class=\"tth_citeref\">[44<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> WF<span style=\"font-size:x-small\">OVERLAP<\/span>: <a href=\"#Plasser2016JCTC\" class=\"tth_citeref\">[54<\/a>,<a href=\"#Plasser2016JCP\" class=\"tth_citeref\">[71<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> LVC\/MM: <a href=\"#Polonius2023JCTC\" class=\"tth_citeref\">[36<\/a>,<a href=\"#Polonius2024JCTC\" class=\"tth_citeref\">[37<\/a>]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc1.3\"><\/a><\/p>\n<h2>\n1.3  Authors<\/h2>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc1.3.1\"><\/a><\/p>\n<h3>\n1.3.1  Eternal list of contributors<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Since the initial release in 2014, the S<span style=\"font-size:x-small\">HARC<\/span> suite has received contributions from (listed alphabetically):<br \/>\nAndrew Atkins,<br \/>\nDavide Avagliano,<br \/>\nBrigitta Bachmair,<br \/>\nLaura Gagliardi,<br \/>\nHans Georg Gallmetzer,<br \/>\nSandra Gómez,<br \/>\nLeticia González,<br \/>\nJesus González-Vázquez,<br \/>\nLorenz Grünewald,<br \/>\nMoritz Heindl,<br \/>\nMatthew R. Hennefarth,<br \/>\nNicolai Machholdt Høyer,<br \/>\nLea M. Ibele,<br \/>\nFeven A. Korsaye,<br \/>\nSimon Kropf,<br \/>\nSebastian Mai,<br \/>\nPhilipp Marquetand,<br \/>\nSascha Mausenberger,<br \/>\nMaximilian F. S. J. Menger,<br \/>\nMarkus Oppel,<br \/>\nTomislav Pitesa,<br \/>\nFelix Plasser,<br \/>\nSeverin Polonius,<br \/>\nMartin Richter,<br \/>\nMatthias Ruckenbauer,<br \/>\nEduarda Sangiogo Gil,<br \/>\nYinan Shu,<br \/>\nNadja K. Singer,<br \/>\nIgnacio Sola,<br \/>\nMaximilian X. Tiefenbacher,<br \/>\nDonald G. Truhlar,<br \/>\nDóra Vörös,<br \/>\nLinyao Zhang,<br \/>\nPatrick Zobel.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc1.3.2\"><\/a><\/p>\n<h3>\n1.3.2  List of contributors to S<span style=\"font-size:x-small\">HARC<\/span> 4<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The list of contributors to the current release S<span style=\"font-size:x-small\">HARC<\/span> 4.0 (as used in the package citation) is:<br \/>\nSebastian Mai,<br \/>\nBrigitta Bachmair,<br \/>\nLaura Gagliardi,<br \/>\nHans Georg Gallmetzer,<br \/>\nLorenz Grünewald,<br \/>\nMatthew R. Hennefarth,<br \/>\nNicolai Machholdt Høyer,<br \/>\nFeven A. Korsaye,<br \/>\nSascha Mausenberger,<br \/>\nMarkus Oppel,<br \/>\nTomislav Pitesa,<br \/>\nSeverin Polonius,<br \/>\nEduarda Sangiogo Gil,<br \/>\nYinan Shu,<br \/>\nNadja K. Singer,<br \/>\nMaximilian X. Tiefenbacher,<br \/>\nDonald G. Truhlar,<br \/>\nDóra Vörös,<br \/>\nLinyao Zhang,<br \/>\nLeticia González.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc1.4\"><\/a><\/p>\n<h2>\n1.4  Suggestions and Bug Reports<\/h2>\n<div class=\"p\"><!----><\/div>\n<p>Bug reports and suggestions for possible features can be submitted <a href=\"https:\/\/github.com\/sharc-md\/sharc\/issues\">to the Issues page on Github<\/a> (for publicly accessible discussions) or to <a href=\"mailto:sharc@univie.ac.at\">sharc@univie.ac.at<\/a> (if non-public information are to be shared).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc1.5\"><\/a><\/p>\n<h2>\n1.5  Notation in this Manual<\/h2>\n<div class=\"p\"><!----><\/div>\n<p><b>Names of programs  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span> suite consists of Fortran90 programs as well as Python and Shell scripts. The executable Fortran90 programs are denoted by the extension <b><tt>.x<\/tt><\/b>, the Python scripts have the extension <b><tt>.py<\/tt><\/b> and the Shell scripts <b><tt>.sh<\/tt><\/b>. Within this manual, all program names are given in <b><tt>bold monospaced font<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc1.6\"><\/a><\/p>\n<h2>\n1.6  Terms of Use<\/h2>\n<p><a id=\"sec:license\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p> S<span style=\"font-size:x-small\">HARC<\/span> Program Suite<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Copyright 2025, University of Vienna<\/p>\n<div class=\"p\"><!----><\/div>\n<p> S<span style=\"font-size:x-small\">HARC<\/span> is free software: you can redistribute it and\/or modify<br \/>\nit under the terms of the GNU General Public License as published by<br \/>\nthe Free Software Foundation, either version 3 of the License, or<br \/>\n(at your option) any later version.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> S<span style=\"font-size:x-small\">HARC<\/span> is distributed in the hope that it will be useful,<br \/>\nbut WITHOUT ANY WARRANTY; without even the implied warranty of<br \/>\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br \/>\nGNU General Public License for more details.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A copy of the GNU General Public License is given below.<br \/>\nIt is also available at <a href=\"http:\/\/www.gnu.org\/licenses\/\">www.gnu.org\/licenses\/<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div style=\"text-align:center\"> <b><\/p>\n<div class=\"large\">GNU General Public License<\/div>\n<p><\/b>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <b>1.    Preamble<\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The GNU General Public License is a free, copyleft license for<br \/>\nsoftware and other kinds of works.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The licenses for most software and other practical works are designed<br \/>\nto take away your freedom to share and change the works. By contrast,<br \/>\nthe GNU General Public License is intended to guarantee your freedom to<br \/>\nshare and change all versions of a program-to make sure it remains free<br \/>\nsoftware for all its users. We, the Free Software Foundation, use the<br \/>\nGNU General Public License for most of our software; it applies also to<br \/>\nany other work released this way by its authors. You can apply it to<br \/>\nyour programs, too.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When we speak of free software, we are referring to freedom, not<br \/>\nprice. Our General Public Licenses are designed to make sure that you<br \/>\nhave the freedom to distribute copies of free software (and charge for<br \/>\nthem if you wish), that you receive source code or can get it if you<br \/>\nwant it, that you can change the software or use pieces of it in new<br \/>\nfree programs, and that you know you can do these things.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>To protect your rights, we need to prevent others from denying you<br \/>\nthese rights or asking you to surrender the rights. Therefore, you have<br \/>\ncertain responsibilities if you distribute copies of the software, or if<br \/>\nyou modify it: responsibilities to respect the freedom of others.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For example, if you distribute copies of such a program, whether<br \/>\ngratis or for a fee, you must pass on to the recipients the same<br \/>\nfreedoms that you received. You must make sure that they, too, receive<br \/>\nor can get the source code. And you must show them these terms so they<br \/>\nknow their rights.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Developers that use the GNU GPL protect your rights with two steps:<br \/>\n(1) assert copyright on the software, and (2) offer you this License<br \/>\ngiving you legal permission to copy, distribute and\/or modify it.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For the developers’ and authors’ protection, the GPL clearly explains<br \/>\nthat there is no warranty for this free software. For both users’ and<br \/>\nauthors’ sake, the GPL requires that modified versions be marked as<br \/>\nchanged, so that their problems will not be attributed erroneously to<br \/>\nauthors of previous versions.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Some devices are designed to deny users access to install or run<br \/>\nmodified versions of the software inside them, although the manufacturer<br \/>\ncan do so. This is fundamentally incompatible with the aim of<br \/>\nprotecting users’ freedom to change the software. The systematic<br \/>\npattern of such abuse occurs in the area of products for individuals to<br \/>\nuse, which is precisely where it is most unacceptable. Therefore, we<br \/>\nhave designed this version of the GPL to prohibit the practice for those<br \/>\nproducts. If such problems arise substantially in other domains, we<br \/>\nstand ready to extend this provision to those domains in future versions<br \/>\nof the GPL, as needed to protect the freedom of users.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, every program is threatened constantly by software patents.<br \/>\nStates should not allow patents to restrict development and use of<br \/>\nsoftware on general-purpose computers, but in those that do, we wish to<br \/>\navoid the special danger that patents applied to a free program could<br \/>\nmake it effectively proprietary. To prevent this, the GPL assures that<br \/>\npatents cannot be used to render the program non-free.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The precise terms and conditions for copying, distribution and<br \/>\nmodification follow.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <b>2.    Terms and Conditions<\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<ol type=\"1\">\n<li> Definitions.\n<div class=\"p\"><!----><\/div>\n<p>“This License” refers to version 3 of the GNU General Public License.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>“Copyright” also means copyright-like laws that apply to other kinds of<br \/>\nworks, such as semiconductor masks.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>“The Program” refers to any copyrightable work licensed under this<br \/>\nLicense. Each licensee is addressed as “you”. “Licensees” and<br \/>\n“recipients” may be individuals or organizations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>To “modify” a work means to copy from or adapt all or part of the work<br \/>\nin a fashion requiring copyright permission, other than the making of an<br \/>\nexact copy. The resulting work is called a “modified version” of the<br \/>\nearlier work or a work “based on” the earlier work.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A “covered work” means either the unmodified Program or a work based<br \/>\non the Program.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>To “propagate” a work means to do anything with it that, without<br \/>\npermission, would make you directly or secondarily liable for<br \/>\ninfringement under applicable copyright law, except executing it on a<br \/>\ncomputer or modifying a private copy. Propagation includes copying,<br \/>\ndistribution (with or without modification), making available to the<br \/>\npublic, and in some countries other activities as well.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>To “convey” a work means any kind of propagation that enables other<br \/>\nparties to make or receive copies. Mere interaction with a user through<br \/>\na computer network, with no transfer of a copy, is not conveying.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>An interactive user interface displays “Appropriate Legal Notices”<br \/>\nto the extent that it includes a convenient and prominently visible<br \/>\nfeature that (1) displays an appropriate copyright notice, and (2)<br \/>\ntells the user that there is no warranty for the work (except to the<br \/>\nextent that warranties are provided), that licensees may convey the<br \/>\nwork under this License, and how to view a copy of this License. If<br \/>\nthe interface presents a list of user commands or options, such as a<br \/>\nmenu, a prominent item in the list meets this criterion.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Source Code.\n<div class=\"p\"><!----><\/div>\n<p>The “source code” for a work means the preferred form of the work<br \/>\nfor making modifications to it. “Object code” means any non-source<br \/>\nform of a work.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A “Standard Interface” means an interface that either is an official<br \/>\nstandard defined by a recognized standards body, or, in the case of<br \/>\ninterfaces specified for a particular programming language, one that<br \/>\nis widely used among developers working in that language.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The “System Libraries” of an executable work include anything, other<br \/>\nthan the work as a whole, that (a) is included in the normal form of<br \/>\npackaging a Major Component, but which is not part of that Major<br \/>\nComponent, and (b) serves only to enable use of the work with that<br \/>\nMajor Component, or to implement a Standard Interface for which an<br \/>\nimplementation is available to the public in source code form. A<br \/>\n“Major Component”, in this context, means a major essential component<br \/>\n(kernel, window system, and so on) of the specific operating system<br \/>\n(if any) on which the executable work runs, or a compiler used to<br \/>\nproduce the work, or an object code interpreter used to run it.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The “Corresponding Source” for a work in object code form means all<br \/>\nthe source code needed to generate, install, and (for an executable<br \/>\nwork) run the object code and to modify the work, including scripts to<br \/>\ncontrol those activities. However, it does not include the work’s<br \/>\nSystem Libraries, or general-purpose tools or generally available free<br \/>\nprograms which are used unmodified in performing those activities but<br \/>\nwhich are not part of the work. For example, Corresponding Source<br \/>\nincludes interface definition files associated with source files for<br \/>\nthe work, and the source code for shared libraries and dynamically<br \/>\nlinked subprograms that the work is specifically designed to require,<br \/>\nsuch as by intimate data communication or control flow between those<br \/>\nsubprograms and other parts of the work.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The Corresponding Source need not include anything that users<br \/>\ncan regenerate automatically from other parts of the Corresponding<br \/>\nSource.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The Corresponding Source for a work in source code form is that<br \/>\nsame work.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Basic Permissions.\n<div class=\"p\"><!----><\/div>\n<p>All rights granted under this License are granted for the term of<br \/>\ncopyright on the Program, and are irrevocable provided the stated<br \/>\nconditions are met. This License explicitly affirms your unlimited<br \/>\npermission to run the unmodified Program. The output from running a<br \/>\ncovered work is covered by this License only if the output, given its<br \/>\ncontent, constitutes a covered work. This License acknowledges your<br \/>\nrights of fair use or other equivalent, as provided by copyright law.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>You may make, run and propagate covered works that you do not<br \/>\nconvey, without conditions so long as your license otherwise remains<br \/>\nin force. You may convey covered works to others for the sole purpose<br \/>\nof having them make modifications exclusively for you, or provide you<br \/>\nwith facilities for running those works, provided that you comply with<br \/>\nthe terms of this License in conveying all material for which you do<br \/>\nnot control copyright. Those thus making or running the covered works<br \/>\nfor you must do so exclusively on your behalf, under your direction<br \/>\nand control, on terms that prohibit them from making any copies of<br \/>\nyour copyrighted material outside their relationship with you.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Conveying under any other circumstances is permitted solely under<br \/>\nthe conditions stated below. Sublicensing is not allowed; section 10<br \/>\nmakes it unnecessary.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Protecting Users’ Legal Rights From Anti-Circumvention Law.\n<div class=\"p\"><!----><\/div>\n<p>No covered work shall be deemed part of an effective technological<br \/>\nmeasure under any applicable law fulfilling obligations under article<br \/>\n11 of the WIPO copyright treaty adopted on 20 December 1996, or<br \/>\nsimilar laws prohibiting or restricting circumvention of such<br \/>\nmeasures.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When you convey a covered work, you waive any legal power to forbid<br \/>\ncircumvention of technological measures to the extent such circumvention<br \/>\nis effected by exercising rights under this License with respect to<br \/>\nthe covered work, and you disclaim any intention to limit operation or<br \/>\nmodification of the work as a means of enforcing, against the work’s<br \/>\nusers, your or third parties’ legal rights to forbid circumvention of<br \/>\ntechnological measures.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Conveying Verbatim Copies.\n<div class=\"p\"><!----><\/div>\n<p>You may convey verbatim copies of the Program’s source code as you<br \/>\nreceive it, in any medium, provided that you conspicuously and<br \/>\nappropriately publish on each copy an appropriate copyright notice;<br \/>\nkeep intact all notices stating that this License and any<br \/>\nnon-permissive terms added in accord with section 7 apply to the code;<br \/>\nkeep intact all notices of the absence of any warranty; and give all<br \/>\nrecipients a copy of this License along with the Program.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>You may charge any price or no price for each copy that you convey,<br \/>\nand you may offer support or warranty protection for a fee.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Conveying Modified Source Versions.\n<div class=\"p\"><!----><\/div>\n<p>You may convey a work based on the Program, or the modifications to<br \/>\nproduce it from the Program, in the form of source code under the<br \/>\nterms of section 4, provided that you also meet all of these conditions:<\/p>\n<ol type=\"a\">\n<li> The work must carry prominent notices stating that you modified<br \/>\n it, and giving a relevant date.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> The work must carry prominent notices stating that it is<br \/>\n released under this License and any conditions added under section<br \/>\n 7. This requirement modifies the requirement in section 4 to<br \/>\n “keep intact all notices”.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> You must license the entire work, as a whole, under this<br \/>\n License to anyone who comes into possession of a copy. This<br \/>\n License will therefore apply, along with any applicable section 7<br \/>\n additional terms, to the whole of the work, and all its parts,<br \/>\n regardless of how they are packaged. This License gives no<br \/>\n permission to license the work in any other way, but it does not<br \/>\n invalidate such permission if you have separately received it.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> If the work has interactive user interfaces, each must display<br \/>\n Appropriate Legal Notices; however, if the Program has interactive<br \/>\n interfaces that do not display Appropriate Legal Notices, your<br \/>\n work need not make them do so.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<p>A compilation of a covered work with other separate and independent<br \/>\nworks, which are not by their nature extensions of the covered work,<br \/>\nand which are not combined with it such as to form a larger program,<br \/>\nin or on a volume of a storage or distribution medium, is called an<br \/>\n“aggregate” if the compilation and its resulting copyright are not<br \/>\nused to limit the access or legal rights of the compilation’s users<br \/>\nbeyond what the individual works permit. Inclusion of a covered work<br \/>\nin an aggregate does not cause this License to apply to the other<br \/>\nparts of the aggregate.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Conveying Non-Source Forms.\n<div class=\"p\"><!----><\/div>\n<p>You may convey a covered work in object code form under the terms<br \/>\nof sections 4 and 5, provided that you also convey the<br \/>\nmachine-readable Corresponding Source under the terms of this License,<br \/>\nin one of these ways:<\/p>\n<ol type=\"a\">\n<li> Convey the object code in, or embodied in, a physical product<br \/>\n (including a physical distribution medium), accompanied by the<br \/>\n Corresponding Source fixed on a durable physical medium<br \/>\n customarily used for software interchange.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Convey the object code in, or embodied in, a physical product<br \/>\n (including a physical distribution medium), accompanied by a<br \/>\n written offer, valid for at least three years and valid for as<br \/>\n long as you offer spare parts or customer support for that product<br \/>\n model, to give anyone who possesses the object code either (1) a<br \/>\n copy of the Corresponding Source for all the software in the<br \/>\n product that is covered by this License, on a durable physical<br \/>\n medium customarily used for software interchange, for a price no<br \/>\n more than your reasonable cost of physically performing this<br \/>\n conveying of source, or (2) access to copy the<br \/>\n Corresponding Source from a network server at no charge.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Convey individual copies of the object code with a copy of the<br \/>\n written offer to provide the Corresponding Source. This<br \/>\n alternative is allowed only occasionally and noncommercially, and<br \/>\n only if you received the object code with such an offer, in accord<br \/>\n with subsection 6b.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Convey the object code by offering access from a designated<br \/>\n place (gratis or for a charge), and offer equivalent access to the<br \/>\n Corresponding Source in the same way through the same place at no<br \/>\n further charge. You need not require recipients to copy the<br \/>\n Corresponding Source along with the object code. If the place to<br \/>\n copy the object code is a network server, the Corresponding Source<br \/>\n may be on a different server (operated by you or a third party)<br \/>\n that supports equivalent copying facilities, provided you maintain<br \/>\n clear directions next to the object code saying where to find the<br \/>\n Corresponding Source. Regardless of what server hosts the<br \/>\n Corresponding Source, you remain obligated to ensure that it is<br \/>\n available for as long as needed to satisfy these requirements.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Convey the object code using peer-to-peer transmission, provided<br \/>\n you inform other peers where the object code and Corresponding<br \/>\n Source of the work are being offered to the general public at no<br \/>\n charge under subsection 6d.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<div class=\"p\"><!----><\/div>\n<p>A separable portion of the object code, whose source code is excluded<br \/>\nfrom the Corresponding Source as a System Library, need not be<br \/>\nincluded in conveying the object code work.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A “User Product” is either (1) a “consumer product”, which means any<br \/>\ntangible personal property which is normally used for personal, family,<br \/>\nor household purposes, or (2) anything designed or sold for incorporation<br \/>\ninto a dwelling. In determining whether a product is a consumer product,<br \/>\ndoubtful cases shall be resolved in favor of coverage. For a particular<br \/>\nproduct received by a particular user, “normally used” refers to a<br \/>\ntypical or common use of that class of product, regardless of the status<br \/>\nof the particular user or of the way in which the particular user<br \/>\nactually uses, or expects or is expected to use, the product. A product<br \/>\nis a consumer product regardless of whether the product has substantial<br \/>\ncommercial, industrial or non-consumer uses, unless such uses represent<br \/>\nthe only significant mode of use of the product.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>“Installation Information” for a User Product means any methods,<br \/>\nprocedures, authorization keys, or other information required to install<br \/>\nand execute modified versions of a covered work in that User Product from<br \/>\na modified version of its Corresponding Source. The information must<br \/>\nsuffice to ensure that the continued functioning of the modified object<br \/>\ncode is in no case prevented or interfered with solely because<br \/>\nmodification has been made.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you convey an object code work under this section in, or with, or<br \/>\nspecifically for use in, a User Product, and the conveying occurs as<br \/>\npart of a transaction in which the right of possession and use of the<br \/>\nUser Product is transferred to the recipient in perpetuity or for a<br \/>\nfixed term (regardless of how the transaction is characterized), the<br \/>\nCorresponding Source conveyed under this section must be accompanied<br \/>\nby the Installation Information. But this requirement does not apply<br \/>\nif neither you nor any third party retains the ability to install<br \/>\nmodified object code on the User Product (for example, the work has<br \/>\nbeen installed in ROM).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The requirement to provide Installation Information does not include a<br \/>\nrequirement to continue to provide support service, warranty, or updates<br \/>\nfor a work that has been modified or installed by the recipient, or for<br \/>\nthe User Product in which it has been modified or installed. Access to a<br \/>\nnetwork may be denied when the modification itself materially and<br \/>\nadversely affects the operation of the network or violates the rules and<br \/>\nprotocols for communication across the network.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Corresponding Source conveyed, and Installation Information provided,<br \/>\nin accord with this section must be in a format that is publicly<br \/>\ndocumented (and with an implementation available to the public in<br \/>\nsource code form), and must require no special password or key for<br \/>\nunpacking, reading or copying.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Additional Terms.\n<div class=\"p\"><!----><\/div>\n<p>“Additional permissions” are terms that supplement the terms of this<br \/>\nLicense by making exceptions from one or more of its conditions.<br \/>\nAdditional permissions that are applicable to the entire Program shall<br \/>\nbe treated as though they were included in this License, to the extent<br \/>\nthat they are valid under applicable law. If additional permissions<br \/>\napply only to part of the Program, that part may be used separately<br \/>\nunder those permissions, but the entire Program remains governed by<br \/>\nthis License without regard to the additional permissions.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When you convey a copy of a covered work, you may at your option<br \/>\nremove any additional permissions from that copy, or from any part of<br \/>\nit. (Additional permissions may be written to require their own<br \/>\nremoval in certain cases when you modify the work.) You may place<br \/>\nadditional permissions on material, added by you to a covered work,<br \/>\nfor which you have or can give appropriate copyright permission.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Notwithstanding any other provision of this License, for material you<br \/>\nadd to a covered work, you may (if authorized by the copyright holders of<br \/>\nthat material) supplement the terms of this License with terms:<\/p>\n<ol type=\"a\">\n<li> Disclaiming warranty or limiting liability differently from the<br \/>\n terms of sections 15 and 16 of this License; or<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Requiring preservation of specified reasonable legal notices or<br \/>\n author attributions in that material or in the Appropriate Legal<br \/>\n Notices displayed by works containing it; or<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Prohibiting misrepresentation of the origin of that material, or<br \/>\n requiring that modified versions of such material be marked in<br \/>\n reasonable ways as different from the original version; or<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Limiting the use for publicity purposes of names of licensors or<br \/>\n authors of the material; or<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Declining to grant rights under trademark law for use of some<br \/>\n trade names, trademarks, or service marks; or<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Requiring indemnification of licensors and authors of that<br \/>\n material by anyone who conveys the material (or modified versions of<br \/>\n it) with contractual assumptions of liability to the recipient, for<br \/>\n any liability that these contractual assumptions directly impose on<br \/>\n those licensors and authors.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<div class=\"p\"><!----><\/div>\n<p>All other non-permissive additional terms are considered “further<br \/>\nrestrictions” within the meaning of section 10. If the Program as you<br \/>\nreceived it, or any part of it, contains a notice stating that it is<br \/>\ngoverned by this License along with a term that is a further<br \/>\nrestriction, you may remove that term. If a license document contains<br \/>\na further restriction but permits relicensing or conveying under this<br \/>\nLicense, you may add to a covered work material governed by the terms<br \/>\nof that license document, provided that the further restriction does<br \/>\nnot survive such relicensing or conveying.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you add terms to a covered work in accord with this section, you<br \/>\nmust place, in the relevant source files, a statement of the<br \/>\nadditional terms that apply to those files, or a notice indicating<br \/>\nwhere to find the applicable terms.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Additional terms, permissive or non-permissive, may be stated in the<br \/>\nform of a separately written license, or stated as exceptions;<br \/>\nthe above requirements apply either way.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Termination.\n<div class=\"p\"><!----><\/div>\n<p>You may not propagate or modify a covered work except as expressly<br \/>\nprovided under this License. Any attempt otherwise to propagate or<br \/>\nmodify it is void, and will automatically terminate your rights under<br \/>\nthis License (including any patent licenses granted under the third<br \/>\nparagraph of section 11).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>However, if you cease all violation of this License, then your<br \/>\nlicense from a particular copyright holder is reinstated (a)<br \/>\nprovisionally, unless and until the copyright holder explicitly and<br \/>\nfinally terminates your license, and (b) permanently, if the copyright<br \/>\nholder fails to notify you of the violation by some reasonable means<br \/>\nprior to 60 days after the cessation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Moreover, your license from a particular copyright holder is<br \/>\nreinstated permanently if the copyright holder notifies you of the<br \/>\nviolation by some reasonable means, this is the first time you have<br \/>\nreceived notice of violation of this License (for any work) from that<br \/>\ncopyright holder, and you cure the violation prior to 30 days after<br \/>\nyour receipt of the notice.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Termination of your rights under this section does not terminate the<br \/>\nlicenses of parties who have received copies or rights from you under<br \/>\nthis License. If your rights have been terminated and not permanently<br \/>\nreinstated, you do not qualify to receive new licenses for the same<br \/>\nmaterial under section 10.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Acceptance Not Required for Having Copies.\n<div class=\"p\"><!----><\/div>\n<p>You are not required to accept this License in order to receive or<br \/>\nrun a copy of the Program. Ancillary propagation of a covered work<br \/>\noccurring solely as a consequence of using peer-to-peer transmission<br \/>\nto receive a copy likewise does not require acceptance. However,<br \/>\nnothing other than this License grants you permission to propagate or<br \/>\nmodify any covered work. These actions infringe copyright if you do<br \/>\nnot accept this License. Therefore, by modifying or propagating a<br \/>\ncovered work, you indicate your acceptance of this License to do so.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Automatic Licensing of Downstream Recipients.\n<div class=\"p\"><!----><\/div>\n<p>Each time you convey a covered work, the recipient automatically<br \/>\nreceives a license from the original licensors, to run, modify and<br \/>\npropagate that work, subject to this License. You are not responsible<br \/>\nfor enforcing compliance by third parties with this License.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>An “entity transaction” is a transaction transferring control of an<br \/>\norganization, or substantially all assets of one, or subdividing an<br \/>\norganization, or merging organizations. If propagation of a covered<br \/>\nwork results from an entity transaction, each party to that<br \/>\ntransaction who receives a copy of the work also receives whatever<br \/>\nlicenses to the work the party’s predecessor in interest had or could<br \/>\ngive under the previous paragraph, plus a right to possession of the<br \/>\nCorresponding Source of the work from the predecessor in interest, if<br \/>\nthe predecessor has it or can get it with reasonable efforts.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>You may not impose any further restrictions on the exercise of the<br \/>\nrights granted or affirmed under this License. For example, you may<br \/>\nnot impose a license fee, royalty, or other charge for exercise of<br \/>\nrights granted under this License, and you may not initiate litigation<br \/>\n(including a cross-claim or counterclaim in a lawsuit) alleging that<br \/>\nany patent claim is infringed by making, using, selling, offering for<br \/>\nsale, or importing the Program or any portion of it.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Patents.\n<div class=\"p\"><!----><\/div>\n<p>A “contributor” is a copyright holder who authorizes use under this<br \/>\nLicense of the Program or a work on which the Program is based. The<br \/>\nwork thus licensed is called the contributor’s “contributor version”.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A contributor’s “essential patent claims” are all patent claims<br \/>\nowned or controlled by the contributor, whether already acquired or<br \/>\nhereafter acquired, that would be infringed by some manner, permitted<br \/>\nby this License, of making, using, or selling its contributor version,<br \/>\nbut do not include claims that would be infringed only as a<br \/>\nconsequence of further modification of the contributor version. For<br \/>\npurposes of this definition, “control” includes the right to grant<br \/>\npatent sublicenses in a manner consistent with the requirements of<br \/>\nthis License.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Each contributor grants you a non-exclusive, worldwide, royalty-free<br \/>\npatent license under the contributor’s essential patent claims, to<br \/>\nmake, use, sell, offer for sale, import and otherwise run, modify and<br \/>\npropagate the contents of its contributor version.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the following three paragraphs, a “patent license” is any express<br \/>\nagreement or commitment, however denominated, not to enforce a patent<br \/>\n(such as an express permission to practice a patent or covenant not to<br \/>\nsue for patent infringement). To “grant” such a patent license to a<br \/>\nparty means to make such an agreement or commitment not to enforce a<br \/>\npatent against the party.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you convey a covered work, knowingly relying on a patent license,<br \/>\nand the Corresponding Source of the work is not available for anyone<br \/>\nto copy, free of charge and under the terms of this License, through a<br \/>\npublicly available network server or other readily accessible means,<br \/>\nthen you must either (1) cause the Corresponding Source to be so<br \/>\navailable, or (2) arrange to deprive yourself of the benefit of the<br \/>\npatent license for this particular work, or (3) arrange, in a manner<br \/>\nconsistent with the requirements of this License, to extend the patent<br \/>\nlicense to downstream recipients. “Knowingly relying” means you have<br \/>\nactual knowledge that, but for the patent license, your conveying the<br \/>\ncovered work in a country, or your recipient’s use of the covered work<br \/>\nin a country, would infringe one or more identifiable patents in that<br \/>\ncountry that you have reason to believe are valid.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If, pursuant to or in connection with a single transaction or<br \/>\narrangement, you convey, or propagate by procuring conveyance of, a<br \/>\ncovered work, and grant a patent license to some of the parties<br \/>\nreceiving the covered work authorizing them to use, propagate, modify<br \/>\nor convey a specific copy of the covered work, then the patent license<br \/>\nyou grant is automatically extended to all recipients of the covered<br \/>\nwork and works based on it.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A patent license is “discriminatory” if it does not include within<br \/>\nthe scope of its coverage, prohibits the exercise of, or is<br \/>\nconditioned on the non-exercise of one or more of the rights that are<br \/>\nspecifically granted under this License. You may not convey a covered<br \/>\nwork if you are a party to an arrangement with a third party that is<br \/>\nin the business of distributing software, under which you make payment<br \/>\nto the third party based on the extent of your activity of conveying<br \/>\nthe work, and under which the third party grants, to any of the<br \/>\nparties who would receive the covered work from you, a discriminatory<br \/>\npatent license (a) in connection with copies of the covered work<br \/>\nconveyed by you (or copies made from those copies), or (b) primarily<br \/>\nfor and in connection with specific products or compilations that<br \/>\ncontain the covered work, unless you entered into that arrangement,<br \/>\nor that patent license was granted, prior to 28 March 2007.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Nothing in this License shall be construed as excluding or limiting<br \/>\nany implied license or other defenses to infringement that may<br \/>\notherwise be available to you under applicable patent law.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> No Surrender of Others’ Freedom.\n<div class=\"p\"><!----><\/div>\n<p>If conditions are imposed on you (whether by court order, agreement or<br \/>\notherwise) that contradict the conditions of this License, they do not<br \/>\nexcuse you from the conditions of this License. If you cannot convey a<br \/>\ncovered work so as to satisfy simultaneously your obligations under this<br \/>\nLicense and any other pertinent obligations, then as a consequence you may<br \/>\nnot convey it at all. For example, if you agree to terms that obligate you<br \/>\nto collect a royalty for further conveying from those to whom you convey<br \/>\nthe Program, the only way you could satisfy both those terms and this<br \/>\nLicense would be to refrain entirely from conveying the Program.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Use with the GNU Affero General Public License.\n<div class=\"p\"><!----><\/div>\n<p>Notwithstanding any other provision of this License, you have<br \/>\npermission to link or combine any covered work with a work licensed<br \/>\nunder version 3 of the GNU Affero General Public License into a single<br \/>\ncombined work, and to convey the resulting work. The terms of this<br \/>\nLicense will continue to apply to the part which is the covered work,<br \/>\nbut the special requirements of the GNU Affero General Public License,<br \/>\nsection 13, concerning interaction through a network will apply to the<br \/>\ncombination as such.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Revised Versions of this License.\n<div class=\"p\"><!----><\/div>\n<p>The Free Software Foundation may publish revised and\/or new versions of<br \/>\nthe GNU General Public License from time to time. Such new versions will<br \/>\nbe similar in spirit to the present version, but may differ in detail to<br \/>\naddress new problems or concerns.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Each version is given a distinguishing version number. If the<br \/>\nProgram specifies that a certain numbered version of the GNU General<br \/>\nPublic License “or any later version” applies to it, you have the<br \/>\noption of following the terms and conditions either of that numbered<br \/>\nversion or of any later version published by the Free Software<br \/>\nFoundation. If the Program does not specify a version number of the<br \/>\nGNU General Public License, you may choose any version ever published<br \/>\nby the Free Software Foundation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the Program specifies that a proxy can decide which future<br \/>\nversions of the GNU General Public License can be used, that proxy’s<br \/>\npublic statement of acceptance of a version permanently authorizes you<br \/>\nto choose that version for the Program.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Later license versions may give you additional or different<br \/>\npermissions. However, no additional obligations are imposed on any<br \/>\nauthor or copyright holder as a result of your choosing to follow a<br \/>\nlater version.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Disclaimer of Warranty.\n<div class=\"p\"><!----><\/div>\n<p> THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY<br \/>\n APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE<br \/>\n COPYRIGHT HOLDERS AND\/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS”<br \/>\n WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,<br \/>\n INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF<br \/>\n MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE<br \/>\n RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.<br \/>\n SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL<br \/>\n NECESSARY SERVICING, REPAIR OR CORRECTION.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Limitation of Liability.\n<div class=\"p\"><!----><\/div>\n<p> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN<br \/>\n WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES<br \/>\n AND\/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR<br \/>\n DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL<br \/>\n DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM<br \/>\n (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED<br \/>\n INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE<br \/>\n OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH<br \/>\n HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH<br \/>\n DAMAGES.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interpretation of Sections 15 and 16.\n<div class=\"p\"><!----><\/div>\n<p>If the disclaimer of warranty and limitation of liability provided<br \/>\nabove cannot be given local legal effect according to their terms,<br \/>\nreviewing courts shall apply local law that most closely approximates<br \/>\nan absolute waiver of all civil liability in connection with the<br \/>\nProgram, unless a warranty or assumption of liability accompanies a<br \/>\ncopy of the Program in return for a fee.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_chAp2\"><\/a><\/p>\n<h1>\nChapter 2 <br \/>Installation<\/h1>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc2.1\"><\/a><\/p>\n<h2>\n2.1  How To Obtain<\/h2>\n<div class=\"p\"><!----><\/div>\n<p> S<span style=\"font-size:x-small\">HARC<\/span> can be obtained from the S<span style=\"font-size:x-small\">HARC<\/span> homepage <a href=\"http:\/\/sharc-md.org\">www.sharc-md.org<\/a>.<br \/>\nIn the Download section, follow the link to G<span style=\"font-size:x-small\">ITHUB<\/span> to clone or download the latest S<span style=\"font-size:x-small\">HARC<\/span> release version.<br \/>\nNote that in some cases a more recent version can be downloaded from the <a href=\"https:\/\/github.com\/sharc-md\/sharc\/tree\/main\"><b><tt>main<\/tt><\/b> branch on Github<\/a>, which can contain bugfixes that are not yet included in a release version.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that you accept the Terms of Use given in Section <a href=\"#sec:license\">1.6<\/a> when you download S<span style=\"font-size:x-small\">HARC<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc2.2\"><\/a><\/p>\n<h2>\n2.2  Installation<\/h2>\n<p><a id=\"sec:install\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to install and run S<span style=\"font-size:x-small\">HARC<\/span> under Linux (Windows and OS X are currently not supported), the following are required or recommended:<\/p>\n<ul>\n<li> A Fortran90 compiler (this release is tested against <a href=\"https:\/\/gcc.gnu.org\/fortran\/\">GNU Fortran<\/a> 8.5.0 and <a href=\"https:\/\/software.intel.com\/en-us\/fortran-compilers\">Intel Fortran<\/a> ifort\/ifx 2024.1).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> A C compiler.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> The <a href=\"http:\/\/www.netlib.org\/blas\/\">BLAS<\/a>, <a href=\"http:\/\/www.netlib.org\/lapack\/\">LAPACK<\/a> and <a href=\"http:\/\/http:\/\/www.fftw.org\/\">FFTW3<\/a> libraries.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"https:\/\/www.python.org\/downloads\/release\/python-3109\/\">Python 3<\/a> (This release requires at least Python 3.11).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Conda\/miniconda with several libraries as indicated below (or another way of installing all required Python packages)\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>make<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>git<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p><b>Extracting  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The source code of the S<span style=\"font-size:x-small\">HARC<\/span> suite is distributed via <a href=\"https:\/\/github.com\/sharc-md\/sharc\">github<\/a>. In order to install it, first clone the repository in a suitable directory:<br \/>\n<tt>git clone https:\/\/github.com\/sharc-md\/sharc.git<\/tt><br \/>\nThe new directory called <b><tt>sharc\/<\/tt><\/b> which contains all the necessary subdirectories and files.<br \/>\nIn Figure <a href=\"#fig:installation\">2.1<\/a> the directory structure of the complete S<span style=\"font-size:x-small\">HARC<\/span> directory is shown.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg2.1\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/dirs_SHARC.png\"> <\/p>\n<div style=\"text-align:center\">Figure 2.1: Directory tree containing a complete S<span style=\"font-size:x-small\">HARC<\/span> installation.<\/div>\n<p> <a id=\"fig:installation\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc2.2.1\"><\/a><\/p>\n<h3>\n2.2.1  Libraries<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>Fortran installation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p> S<span style=\"font-size:x-small\">HARC<\/span> requires the BLAS, LAPACK and FFTW3 libraries. During the installation, it might be necessary to alter the <b><tt>LDFLAGS<\/tt><\/b> string in the <b><tt>Makefile<\/tt><\/b>, depending on where the relevant libraries are located on your system. In this way, it is for example possible to use vendor-provided libraries like the <a href=\"https:\/\/software.intel.com\/en-us\/intel-mkl\">Intel MKL<\/a>. For more details see the <b><tt>INSTALL<\/tt><\/b> file which is included in the S<span style=\"font-size:x-small\">HARC<\/span> distribution.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Python installation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to compile with <b><tt>pysharc<\/tt><\/b>, it is necessary to first create a suitable Python installation through the Anaconda distribution.<br \/>\nA working minimal environment can be created with (ignore the line break):<br \/>\n<tt>conda create -n sharc4.0 -c conda-forge python=3.12 numpy scipy h5py matplotlib<\/tt><br \/>\n<tt>pyparsing netcdf4 gfortran_linux-64 pyscf openmm numba sympy pyyaml pytorch pytest ase<\/tt><br \/>\n<tt>opt_einsum threadpoolctl<\/tt><br \/>\nSubsequently, the environment has to be activated with<br \/>\n<tt>conda activate sharc4.0<\/tt><br \/>\nbefore one can proceed with the installation of SHARC.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Instead of the command above, you should also be able to use<br \/>\n<tt>conda env create --file=$SHARC\/..\/conda_env_sharc4.0.yml<\/tt><br \/>\nNote that these two approaches might not produce 100% identical results.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Machine learning interfaces  <\/b><br \/>\nTo use the <b><tt>SPaiNN<\/tt><\/b> interface, clone the repository and install it:<br \/>\n<tt>git clone https:\/\/github.com\/CompPhotoChem\/SPaiNN.git<\/tt><br \/>\n<tt>cd SPaiNN && pip install .<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p>To use the <b><tt>SchNarc<\/tt><\/b> interface, install schnetpack 1, clone the repository, and install it:<br \/>\n<tt>pip install schnetpack==1.0.1<\/tt><br \/>\n<tt>git clone https:\/\/github.com\/schnarc\/SchNarc.git<\/tt><br \/>\n<tt>cd SchNarc && pip install .<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Note that the <b><tt>SPaiNN<\/tt><\/b> and <b><tt>SchNarc<\/tt><\/b> interfaces are mutually exclusive, since they require different versions of SchNetPack!<\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Compiling and installing (without <b><tt>pysharc<\/tt><\/b>)  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>To compile the Fortran90 programs of the S<span style=\"font-size:x-small\">HARC<\/span> suite, go to the <b><tt>source\/<\/tt><\/b> directory.<br \/>\n<tt>cd source\/<\/tt><br \/>\nand edit the <b><tt>Makefile<\/tt><\/b> by adjusting the variables in the top part.<br \/>\nIf you only want to install regular S<span style=\"font-size:x-small\">HARC<\/span> (no <b><tt>pysharc<\/tt><\/b> or NetCDF), set <b><tt>USE_PYSHARC<\/tt><\/b> to <b><tt>false<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Then, inside <b><tt>source\/<\/tt><\/b> issuing the command:<br \/>\n<tt>make install<\/tt><br \/>\nwill compile the source, create all the binaries, and copy the binary files into the <b><tt>sharc\/bin\/<\/tt><\/b> directory of the<br \/>\n S<span style=\"font-size:x-small\">HARC<\/span> distribution, which already contains all the python scripts which<br \/>\ncome with S<span style=\"font-size:x-small\">HARC<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Compiling and installing (with <b><tt>pysharc<\/tt><\/b>)  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you intend to perform computations with <b><tt>pysharc<\/tt><\/b> (using the efficient <b><tt>driver.py<\/tt><\/b>) or with NetCDF functionality, you need to set <b><tt>USE_PYSHARC<\/tt><\/b> to <b><tt>true<\/tt><\/b> in <b><tt>source\/Makefile<\/tt><\/b>.<br \/>\nNote that currently, some options (adaptive time steps) are not supported in this way.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Due to a number of dependencies, compiling with <b><tt>pysharc<\/tt><\/b> is slightly more complicated than without.<br \/>\nThe simplest way to compile both <b><tt>pysharc<\/tt><\/b> and the regular executables together is to<\/p>\n<ol type=\"1\">\n<li> run <b><tt>make install<\/tt><\/b> in <b><tt>pysharc\/<\/tt><\/b>, then\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> run <b><tt>make install<\/tt><\/b> in <b><tt>source\/<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, you might want to compile the regular executables without <b><tt>pysharc<\/tt><\/b> or NetCDF, and then compile <b><tt>pysharc<\/tt><\/b>.<br \/>\nTo do this:<\/p>\n<ol type=\"1\">\n<li> set <b><tt>USE_PYSHARC<\/tt><\/b> to <b><tt>false<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> run <b><tt>make install<\/tt><\/b> in <b><tt>source\/<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> run <b><tt>make clean<\/tt><\/b> in <b><tt>source\/<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> set <b><tt>USE_PYSHARC<\/tt><\/b> to <b><tt>true<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> run <b><tt>make install<\/tt><\/b> in <b><tt>pysharc\/<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<div class=\"p\"><!----><\/div>\n<p><b>Environment setup  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to use the S<span style=\"font-size:x-small\">HARC<\/span> suite, you have to set some environment variables. The recommended approach is to source either of the <b><tt>sharcvars<\/tt><\/b> files (generated by <b><tt>make<\/tt><\/b>) that are located in the <b><tt>bin\/<\/tt><\/b> directory. For example, if you have cloned S<span style=\"font-size:x-small\">HARC<\/span> into your home directory, just use:<br \/>\n<tt>source ~\/sharc\/bin\/sharcvars.sh<\/tt>    (for bourne shell users)<br \/>\nor<br \/>\n<tt>source ~\/sharc\/bin\/sharcvars.csh<\/tt>    (for c-shell type users)<br \/>\nNote that it may be convenient to put this line into your shell’s login<br \/>\nscripts.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc2.2.2\"><\/a><\/p>\n<h3>\n2.2.2   WF<span style=\"font-size:x-small\">OVERLAP<\/span> Program<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span> package contains as a submodule the program WF<span style=\"font-size:x-small\">OVERLAP<\/span>, which is necessary for many functionalities of S<span style=\"font-size:x-small\">HARC<\/span>.<br \/>\nIn order to install and test this program, see Section <a href=\"#sec:int:wfoverlap\">6.29<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc2.2.3\"><\/a><\/p>\n<h3>\n2.2.3  Test Suite<\/h3>\n<p><a id=\"sec:tests.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb2.1\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 2.1: Environment variables for S<span style=\"font-size:x-small\">HARC<\/span> test jobs. These variables need to be set before the test job execution.<\/div>\n<p> <a id=\"tab:test_vars\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$GAUSSIAN <\/td>\n<td align=\"left\">Points to the main directory of the G<span style=\"font-size:x-small\">AUSSIAN<\/span> installation, which contains the G<span style=\"font-size:x-small\">AUSSIAN<\/span> executables (e.g., <b><tt>g09<\/tt><\/b>\/<b><tt>g16<\/tt><\/b> or <b><tt>l9999.exe<\/tt><\/b>).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$MNDO <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$MOLCAS <\/td>\n<td align=\"left\">Points to the main directory of the O<span style=\"font-size:x-small\">PENMOLCAS<\/span> installation, containing <b><tt>molcas.rte<\/tt><\/b> and directories <b><tt>basis_library\/<\/tt><\/b> and <b><tt>bin\/<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$MOPACPI <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$TURBOMOLE <\/td>\n<td align=\"left\">Points to the main directory of the T<span style=\"font-size:x-small\">URBOMOLE<\/span> installation, which contains subdirectories like <b><tt>basen\/<\/tt><\/b>, <b><tt>bin\/<\/tt><\/b>, or <b><tt>scripts\/<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$ORCA <\/td>\n<td align=\"left\">Points to the directory containing the O<span style=\"font-size:x-small\">RCA<\/span> executables, e.g., <b><tt>orca<\/tt><\/b>, <b><tt>orca_gtoint<\/tt><\/b>, or <b><tt>orca_fragovl<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$NWCHEM <\/td>\n<td align=\"left\">Points to the main installation directory, which contains subdirectories <b><tt>bin<\/tt><\/b> and <b><tt>data<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$THEODORE <\/td>\n<td align=\"left\">Points to the main directory of the T<span style=\"font-size:x-small\">HEO<\/span>DORE installation. <b><tt>$THEODORE\/bin\/<\/tt><\/b> should contain <b><tt>analyze_tden.py<\/tt><\/b>. If you install and activate TheoDORE as usual, then <b><tt>$THEODIR<\/tt><\/b> is that folder.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$molcas <\/td>\n<td align=\"left\">Should point to the same location as <b><tt>$MOLCAS<\/tt><\/b>, or another M<span style=\"font-size:x-small\">OLCAS<\/span> installation. Note that <b><tt>$molcas<\/tt><\/b> is only used by some C<span style=\"font-size:x-small\">OLUMBUS<\/span> test jobs. Also note that <b><tt>$molcas<\/tt><\/b> does not need to point to the M<span style=\"font-size:x-small\">OLCAS<\/span> installation interfaced to C<span style=\"font-size:x-small\">OLUMBUS<\/span>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$orca <\/td>\n<td align=\"left\">Should point to the same location as <b><tt>$ORCA<\/tt><\/b>, or another O<span style=\"font-size:x-small\">RCA<\/span> installation. Note that <b><tt>$orca<\/tt><\/b> is only used by some tests where O<span style=\"font-size:x-small\">RCA<\/span> is used as helper program (e.g., for <b><tt>setup_orca_opt.py<\/tt><\/b> or spin-orbit calculations with <b><tt>SHARC_TURBOMOLE.py<\/tt><\/b>).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$AMS <\/td>\n<td align=\"left\">Points to the main directory of the ADF installation, which contains the file <b><tt>adfrc.sh<\/tt><\/b> and subdirectory <b><tt>bin\/<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$BAGEL <\/td>\n<td align=\"left\">Points to the main directory of the B<span style=\"font-size:x-small\">AGEL<\/span> installation, which contains subdirectories <b><tt>bin\/<\/tt><\/b> and <b><tt>lib\/<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$COLUMBUS <\/td>\n<td align=\"left\">Points to the directory containing the C<span style=\"font-size:x-small\">OLUMBUS<\/span> executables, e.g., <b><tt>runls<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">$MOLPRO <\/td>\n<td align=\"left\">Points to the <b><tt>bin\/<\/tt><\/b> directory of the M<span style=\"font-size:x-small\">OLPRO<\/span> installation, which contains the <b><tt>molpro.exe<\/tt><\/b> file.<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>After the installation, it is advisable to first execute the test suite of S<span style=\"font-size:x-small\">HARC<\/span>, which will test the fundamental functionality of SHARC to communicate with other programs.<br \/>\nChange to an empty directory and execute<br \/>\n<tt>$SHARC\/tests.py<\/tt><br \/>\nThe interactive script will first verify the Python installation (no message will appear if the Python installation is fine).<br \/>\nSubsequently, the script prompts the user to enter which tests should be executed.<br \/>\nThe script will also ask for a number of environment variables, which are listed in Table <a href=\"#tab:test_vars\">2.1<\/a> if needed.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, the tests have been updated.<br \/>\nThere is at least one test for each ab initio interface.<br \/>\nAdditional tests are present for interfaces that require <b><tt>wfoverlap.x<\/tt><\/b>, TheoDORE, or interact somehow with other (optional) software.<br \/>\nIn each case, the <b><tt>_curvature<\/tt><\/b> test (if present) tests the corresponding interface without any auxiliary programs.<br \/>\nAll tests starting with the name of an ab initio program run short trajectories testing whether the main dynamics code, the interfaces, the quantum chemistry programs, and auxiliary programs (e.g., T<span style=\"font-size:x-small\">HEO<\/span>DORE, <b><tt>wfoverlap.x<\/tt><\/b>, O<span style=\"font-size:x-small\">RCA<\/span>) work correctly together.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p>If the installation was successful and Python is installed correctly, <b><tt>Analytical_overlap<\/tt><\/b>, <b><tt>LVC_overlap<\/tt><\/b>, and most tests named <b><tt>scripts_<NAME><\/tt><\/b> should execute without error. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The test calculations involving the quantum chemistry programs can be used to check that S<span style=\"font-size:x-small\">HARC<\/span> can correctly call these programs and that they are installed correctly.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If any of the tests show differences between output and reference output, it is advisable to check the respective files (i.e., compare <b><tt>$SHARC\/..\/tests\/RESULTS\/<job>\/<\/tt><\/b> to <b><tt>.\/RUNNING_TESTS\/<job>\/<\/tt><\/b>).<br \/>\nNote that small differences (different sign of values or small numerical deviations) in the output can already occur when using a different version of the quantum chemistry programs, different compilers, different libraries, or different parallization schemes.<br \/>\nIt should be noted that along trajectories, these small changes can add up to notably influence the trajectories, but across the ensemble these small changes will likely cancel out.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc2.2.4\"><\/a><\/p>\n<h3>\n2.2.4  Additional Programs<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>For full functionality of the S<span style=\"font-size:x-small\">HARC<\/span> suite, several additional programs are recommended (all of these programs are currently freely available, except for some parts of A<span style=\"font-size:x-small\">MBER<\/span>):<\/p>\n<div class=\"p\"><!----><\/div>\n<ul>\n<li> The Python package <a href=\"https:\/\/matplotlib.org\/\"> M<span style=\"font-size:x-small\">ATPLOTLIB<\/span><\/a>.<br \/>\n <br \/>\n If the M<span style=\"font-size:x-small\">ATPLOTLIB<\/span> package, some auxiliary scripts (e.g., <b><tt>trajana_essdyn.py<\/tt><\/b>) can automatically generate certain plots.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> The <a href=\"http:\/\/www.gnuplot.info\/\"> G<span style=\"font-size:x-small\">NUPLOT<\/span><\/a> plotting software.<br \/>\n <br \/>\n G<span style=\"font-size:x-small\">NUPLOT<\/span> is not strictly necessary, since all output files could be plotted using other plotting programs. However, a number of scripts from the S<span style=\"font-size:x-small\">HARC<\/span> suite automatically generate G<span style=\"font-size:x-small\">NUPLOT<\/span> scripts after data processing, allowing to quickly plot the results.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> A molecular visualization software able to read xyz files (e.g. <a href=\"http:\/\/www.cmbi.ru.nl\/molden\/molden.html\"> M<span style=\"font-size:x-small\">OLDEN<\/span><\/a>, <a href=\"http:\/\/gabedit.sourceforge.net\/\"> G<span style=\"font-size:x-small\">ABEDIT<\/span><\/a>, <a href=\"http:\/\/molekel.cscs.ch\/wiki\/pmwiki.php\"> M<span style=\"font-size:x-small\">OLEKEL<\/span><\/a> or <a href=\"http:\/\/www.ks.uiuc.edu\/Research\/vmd\/\">VMD<\/a>).<br \/>\n <br \/>\n Molecular visualization software is needed in order to animate molecular motion in the dynamics.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> The <a href=\"http:\/\/theodore-qc.sourceforge.net\/\"> T<span style=\"font-size:x-small\">HEO<\/span>DORE<\/a> wave function analysis suite (version 3.0 or higher).<br \/>\n <br \/>\n The wave function analysis package T<span style=\"font-size:x-small\">HEO<\/span>DORE allows to compute various descriptors of electronic wave functions (supported by some interfaces), which is helpful to follow the state characters along trajectories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> The <a href=\"http:\/\/ambermd.org\/\"> A<span style=\"font-size:x-small\">MBER<\/span><\/a> molecular dynamics package.<br \/>\n <br \/>\n A<span style=\"font-size:x-small\">MBER<\/span> can be used to prepare topology files and initial conditions based on ground state molecular dynamics simulations (instead of using a Wigner distribution), which is especially useful for large systems.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> The <a href=\"https:\/\/orcaforum.kofo.mpg.de\"> O<span style=\"font-size:x-small\">RCA<\/span><\/a> ab initio package.<br \/>\n <br \/>\n O<span style=\"font-size:x-small\">RCA<\/span> can be employed as external optimizer. In combination with the S<span style=\"font-size:x-small\">HARC<\/span> interfaces, it is possible to perform optimizations of minima, conical intersections, and crossing points for any method interfaced to S<span style=\"font-size:x-small\">HARC<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc2.2.5\"><\/a><\/p>\n<h3>\n2.2.5  Quantum Chemistry Programs<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Even though S<span style=\"font-size:x-small\">HARC<\/span> comes with several interfaces for analytical potentials (and hence can be used without any quantum chemistry program), one of the main application of S<span style=\"font-size:x-small\">HARC<\/span> is certainly on-the-fly ab initio dynamics.<br \/>\nIn this case, one of the following interfaced quantum chemistry programs is necessary:<\/p>\n<ul>\n<li> <a href=\"https:\/\/openmm.org\/\">OpenMM<\/a>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"http:\/\/www.gaussian.com\"> G<span style=\"font-size:x-small\">AUSSIAN<\/span><\/a> (this release was checked against G<span style=\"font-size:x-small\">AUSSIAN<\/span> 16).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"https:\/\/orcaforum.kofo.mpg.de\"> O<span style=\"font-size:x-small\">RCA<\/span><\/a> (version 5.0 or 6.0).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"https:\/\/nwchemgit.github.io\/index.html\"> NWC<span style=\"font-size:x-small\">HEM<\/span><\/a> (version 7.2 or higher)\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"http:\/\/www.turbomole.com\"> T<span style=\"font-size:x-small\">URBOMOLE<\/span><\/a> (this release was checked against T<span style=\"font-size:x-small\">URBOMOLE<\/span> 7.8).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"https:\/\/gitlab.com\/Molcas\/OpenMolcas\/\"> O<span style=\"font-size:x-small\">PENMOLCAS<\/span><\/a> (this release was checked against O<span style=\"font-size:x-small\">PENMOLCAS<\/span> 24).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"https:\/\/mndo.kofo.mpg.de\/\"> MNDO<\/a> (version 8.0 of 15 August 2019).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"https:\/\/gitlab.com\/granucci\/mopacpi\"> MOPAC-PI<\/a> (commit c2124b7a from 6 November 2024), including its internal version of T<span style=\"font-size:x-small\">INKER<\/span>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"http:\/\/www.univie.ac.at\/columbus\/docs_COL70\/documentation_main.html\"> C<span style=\"font-size:x-small\">OLUMBUS<\/span> 7<\/a>\n<ul>\n<li> <a href=\"http:\/\/www.univie.ac.at\/columbus\/docs_COL70\/columbus_molcas_link.html\"> C<span style=\"font-size:x-small\">OLUMBUS<\/span>-M<span style=\"font-size:x-small\">OLCAS<\/span> interface<\/a> for spin-orbit couplings.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"https:\/\/nubakery.org\/index.html\"> B<span style=\"font-size:x-small\">AGEL<\/span><\/a> (commit 0ea6b59 from Mar 27, 2019 or newer).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"http:\/\/www.scm.com\/ADF\"> A<span style=\"font-size:x-small\">MSTERDAM<\/span> D<span style=\"font-size:x-small\">ENSITY<\/span> F<span style=\"font-size:x-small\">UNCTIONAL<\/span><\/a> (this release was tested against AMS 2024).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"http:\/\/www.molpro.net\/\"> M<span style=\"font-size:x-small\">OLPRO<\/span><\/a> (this release was checked against M<span style=\"font-size:x-small\">OLPRO<\/span> 2023).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <a href=\"https:\/\/pyscf.org\/\"> P<span style=\"font-size:x-small\">Y<\/span>SCF<\/a> with <a href=\"https:\/\/github.com\/matthew-hennefarth\/pyscf-forge\"><b><tt>PySCF Forge<\/tt><\/b><\/a>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>See the relevant sections in Chapter <a href=\"#chap:interfaces\">6<\/a> for a description of the quantum chemical methods available with each of these programs.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_chAp3\"><\/a><\/p>\n<h1>\nChapter 3 <br \/>Execution<\/h1>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span> suite consists of the two main dynamics codes <b><tt>sharc.x<\/tt><\/b> and <b><tt>driver.py<\/tt><\/b> and a large set of auxiliary programs, like setup scripts and analysis tools.<br \/>\nAdditionally, the suite comes with interfaces to several quantum chemistry software packages, as described elsewhere.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the following, first it is explained how to run a single trajectory by setting up all necessary input for the dynamics code <b><tt>sharc.x<\/tt><\/b> manually, as a minimum working example.<br \/>\nAfterwards, the usage of the auxiliary scripts and the standard workflow is explained.<br \/>\nDetailed information on the S<span style=\"font-size:x-small\">HARC<\/span> input files is given in chapter <a href=\"#chap:input\">4<\/a>.<br \/>\nChapter <a href=\"#chap:output\">5<\/a> documents the different output files S<span style=\"font-size:x-small\">HARC<\/span> produces.<br \/>\nThe interfaces are described in chapter <a href=\"#chap:interfaces\">6<\/a> and the auxiliary scripts in chapter <a href=\"#chap:aux\">7<\/a>.<br \/>\nAll relevant theoretical background is given in chapter <a href=\"#chap:met\">8<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>More hands-on examples can be found in the Tutorial.<br \/>\nAdditionally, we recommend several instructional videos recorded during the <a href=\"https:\/\/compchem-cybertraining.github.io\/Cyber_Training_Workshop_2022\/_episodes\/06-sharc\">Cyber Training Workshop 2022<\/a> by Alexey Akimov from the University af Buffalo, NY.<br \/>\nThese videos were recorded with S<span style=\"font-size:x-small\">HARC<\/span>3, but they still have instructional value for new users.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.1\"><\/a><\/p>\n<h2>\n3.1  Running a single trajectory<\/h2>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.1.1\"><\/a><\/p>\n<h3>\n3.1.1  Input files<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Both drivers (<b><tt>sharc.x<\/tt><\/b> and <b><tt>driver.py<\/tt><\/b>) requires the same input files.<br \/>\nThe most important file is called <b><tt>input<\/tt><\/b> and contains all settings for the dynamics.<br \/>\nThe initial geometry is read from the <b><tt>geom<\/tt><\/b> file.<br \/>\nThese two files are mandatory.<br \/>\nAdditional, optional files can be used to provide the initial velocities (<b><tt>veloc<\/tt><\/b>), the initial state coefficients (<b><tt>coeff<\/tt><\/b>), and\/or a laser field (<b><tt>laser<\/tt><\/b>).<br \/>\nMoreover, several files can be used to mask certain atoms from certain algorithms (<b><tt>atommask<\/tt><\/b>), to constrain certain bond lengths (<b><tt>rattle<\/tt><\/b>), to freeze the position of certain atoms (<b><tt>frozen<\/tt><\/b>), to apply a droplet restraining potential to certain atoms (<b><tt>droplet<\/tt><\/b>), and\/or to define settings of the thermostat (<b><tt>thermostat_setting<\/tt><\/b>).<br \/>\nFor all optional files. if not given, the missing information is automatically set according to some keywords in <b><tt>input<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The input files inside a trajectory folder are shown in Figure <a href=\"#fig:dir_traj\">3.1<\/a>.<br \/>\nThe content of the main input file is explained in detail in Section <a href=\"#sec:inputfile\">4.1<\/a>, the geometry file is specified in Section <a href=\"#sec:geomfile\">4.2<\/a>.<br \/>\nThe specifications of the velocity, coefficient, and laser files are given in Sections <a href=\"#sec:velocfile\">4.3<\/a>, <a href=\"#sec:coefffile\">4.4<\/a> and <a href=\"#sec:laserfile\">4.5<\/a>, respectively.<br \/>\nThe atom mask file is likewise documented in Section <a href=\"#sec:atommaskfile\">4.6<\/a>, the RATTLE file in Section <a href=\"#sec:rattlefile\">4.7<\/a>, the frozen atoms file in Section <a href=\"#sec:frozenfile\">4.8<\/a>, the droplet atoms file in Section <a href=\"#sec:dropletfile\">4.9<\/a>, and the thermostat file in Section <a href=\"#sec:thermostatfile\">4.10<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg3.1\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/dir_traj.png\"> <\/p>\n<div style=\"text-align:center\">Figure 3.1: Input files for a S<span style=\"font-size:x-small\">HARC<\/span> dynamics simulation. Directories are in blue, executable scripts in green, regular files in white and optional files in grey.<\/div>\n<p> <a id=\"fig:dir_traj\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Additionally, the directory <b><tt>QM\/<\/tt><\/b> is required, containing the interface-specific input files.<br \/>\nIf the trajectory is run with <b><tt>sharc.x<\/tt><\/b>, then the script <b><tt>QM\/runQM.sh<\/tt><\/b> needs to be present, since the communication of <b><tt>sharc.x<\/tt><\/b> and the interfaces is implemented through this script.<br \/>\nEvery time that <b><tt>sharc.x<\/tt><\/b> is making a quantum chemistry call, the current geometry and the requests are written to <b><tt>QM\/QM.in<\/tt><\/b>.<br \/>\nThen, <b><tt>sharc.x<\/tt><\/b> calls <b><tt>QM\/runQM.sh<\/tt><\/b>, waits for the script to finish and then reads the requested quantities from <b><tt>QM\/QM.out<\/tt><\/b>.<br \/>\nThe script <b><tt>QM\/runQM.sh<\/tt><\/b> is fully responsible to generate the requested results from the provided input.<br \/>\nIn virtually all cases, this task is handled by S<span style=\"font-size:x-small\">HARC<\/span>‘s interfaces (see Chapter <a href=\"#chap:interfaces\">6<\/a>), so that the script <b><tt>QM\/runQM.sh<\/tt><\/b> has a particularly simple form:<br \/>\n<tt>cd QM\/<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p><tt>$SHARC\/SHARC_<NAME>.py QM.in <\/tt><br \/>\nwith the corresponding interface name given.<br \/>\nWhen running with <b><tt>sharc.x<\/tt><\/b>, this script is the location where the chosen interface is defined.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the trajectory is instead run with <b><tt>driver.py<\/tt><\/b>, then the <b><tt>runQM.sh<\/tt><\/b> script does not need to be present.<br \/>\nThe chosen interface is instead given to <b><tt>driver.py<\/tt><\/b> as a command line option.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the interfaces in nearly all cases need additional input files, which must be present in <b><tt>QM\/<\/tt><\/b>, independent of whether <b><tt>sharc.x<\/tt><\/b> or <b><tt>driver.py<\/tt><\/b> is used.<br \/>\nMost interfaces require two files, a template file and a reource file.<br \/>\nThe contained information depends on the type of interface, but typically contains model information, quantum chemistry information, information about the child interfaces, and\/or information about computational resources.<br \/>\nSee Chapter <a href=\"#chap:interfaces\">6<\/a> for details.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.1.2\"><\/a><\/p>\n<h3>\n3.1.2  Running the dynamics code<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Given the necessary input files, S<span style=\"font-size:x-small\">HARC<\/span> can be started by executing<br \/>\n<tt>user@host> $SHARC\/sharc.x input<\/tt><br \/>\nNote that besides the input file, at least the geometry file needs to be present (see chapter <a href=\"#chap:input\">4<\/a> for details).<br \/>\nIf using the Python driver, the trajectory can be started by executing<br \/>\n<tt>user@host> $SHARC\/driver.py -i <NAME> input<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that for large systems (i.e., many electronic states and\/or many atoms), it might in some cases be required to increase the stack size before starting either of the two dynamics drivers.<br \/>\nThis can be achieved by<br \/>\n<tt>user@host> ulimit -s unlimited<\/tt><br \/>\nIf the system is too large and the stack size is not increased, typically SHARC will crash with a segmentation fault.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A running trajectory can be stopped gracefully after the current time step by creating an empty file <b><tt>STOP<\/tt><\/b>:<br \/>\n<tt>user@host> touch STOP<\/tt><br \/>\nThis is usually preferable to simply killing S<span style=\"font-size:x-small\">HARC<\/span>, because the current time step is properly finished and all files are correctly written for analysis and restart.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to restart a trajectory, add the <b><tt>restart<\/tt><\/b> keyword to the input file and call the driver again.<br \/>\nPlease refer to Section <a href=\"#sec:inputfile\">4.1<\/a> for further details.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to start a trajectory from time zero, no restart files from a previous run must be present, otherwise the dynamics drivers will raise an error.<br \/>\nA trajectory folder can conveniently be purged of most output files by using <b><tt>$SHARC\/clean_traj.sh<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.1.3\"><\/a><\/p>\n<h3>\n3.1.3  Output files<\/h3>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg3.2\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/dir_traj_after.png\"> <\/p>\n<div style=\"text-align:center\">Figure 3.2: Files of a S<span style=\"font-size:x-small\">HARC<\/span> dynamics simulation after running. Directories are in blue, executable scripts in green, regular files in white and optional files in grey. Output files are in yellow.<\/div>\n<p> <a id=\"fig:dir_traj_after\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Figure <a href=\"#fig:dir_traj_after\">3.2<\/a> shows the content of a trajectory directory after the execution of either of S<span style=\"font-size:x-small\">HARC<\/span>‘s drivers.<br \/>\nThere will be at least six new files.<br \/>\nThe files that always will be created are <b><tt>output.log<\/tt><\/b>, <b><tt>output.lis<\/tt><\/b>, <b><tt>output.dat<\/tt><\/b> and <b><tt>output.xyz<\/tt><\/b>, as well as <b><tt>restart.ctrl<\/tt><\/b> and <b><tt>restart.traj<\/tt><\/b>.<br \/>\nOptionally, two more output files are created, <b><tt>output.dat.nc<\/tt><\/b> and <b><tt>output_NUC.dat.nc<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>output.log<\/tt><\/b> contains mainly a listing of the chosen options and the resulting dynamics settings.<br \/>\nAt higher print levels, the log file contains also information per time step (useful for debugging).<br \/>\n<b><tt>output.lis<\/tt><\/b> contains a table with one line per time step, giving active states, energies and expectation values.<br \/>\n<b><tt>output.xyz<\/tt><\/b> contains the geometries of all time steps (the comments to each geometry give the active state and current time).<br \/>\n<b><tt>output.dat<\/tt><\/b> contains a list of all important matrices and vectors at each time step.<br \/>\nThis information can be extracted with <b><tt>data_extractor.x<\/tt><\/b> to yield plottable table files.<br \/>\nIf <b><tt>netcdf<\/tt><\/b> output has been selected via the options in the <b><tt>input<\/tt><\/b> file, then <b><tt>output.dat.nc<\/tt><\/b> will be present as well.<br \/>\nIf it is present, <b><tt>output.dat<\/tt><\/b> will only contain its header, but no information per time step.<br \/>\nThe information per time step is contained in <b><tt>output.dat.nc<\/tt><\/b>.<br \/>\nUse <b><tt>data_extractor_NetCDF.x<\/tt><\/b> in this case.<br \/>\nIf, the <b><tt>netcdf_separate_nuc<\/tt><\/b> option is chosen instead of regular <b><tt>netcdf<\/tt><\/b> output, then the <b><tt>output_NUC.dat.nc<\/tt><\/b> file is also present.<br \/>\nIn this case, electronic information is in <b><tt>output.dat.nc<\/tt><\/b> and nuclear information in <b><tt>output_NUC.dat.nc<\/tt><\/b>, which is useful because one can separately control how often these files are written.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For details about the content of the output files, see chapter <a href=\"#chap:output\">5<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The restart files contain the full state of a trajectory and its control variables from the last successful time step.<br \/>\nThese files are needed in order to restart a trajectory at this time step (either because the calculation failed, or in order to extend the simulation time beyond the original maximum simulation time).<br \/>\nThe <b><tt>restart\/<\/tt><\/b> directory contains all persistent files that are needed for the interfaces (for restarting, but also between all time steps).<br \/>\nUsually, users do not need to inspect the restart files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.2\"><\/a><\/p>\n<h2>\n3.2  Typical workflow for an ensemble of trajectories<\/h2>\n<p><a id=\"sec:typical_workflow\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Usually, one is not interested in running only a single trajectory, since a single trajectory cannot reproduce the branching of a wave packet into different reaction channels.<br \/>\nIn order to do so, within surface hopping an ensemble of independent trajectories is employed.<br \/>\nWhen dealing with a (possibly large) ensemble of trajectories, setup, management, and analysis need to be automatized.<br \/>\nHence, the S<span style=\"font-size:x-small\">HARC<\/span> suite contains a number of scripts fulfilling different tasks in the usual workflow of setting up ensembles of trajectories.<br \/>\nThe standard workflow is given schematically in Figure <a href=\"#fig:workflow\">3.3<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg3.3\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/prepare.png\"> <\/p>\n<div style=\"text-align:center\">Figure 3.3: Typical basic workflow for conducting excited-state dynamics simulations with S<span style=\"font-size:x-small\">HARC<\/span>.<\/div>\n<p> <a id=\"fig:workflow\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.2.1\"><\/a><\/p>\n<h3>\n3.2.1  Initial condition generation<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In the typical workflow, the user will first create a set of suitable initial conditions.<br \/>\nIn the context of the S<span style=\"font-size:x-small\">HARC<\/span> package, an initial condition is a set of an initial geometry, initial velocity, initial occupied state, and initial wave function coefficients.<br \/>\nMany such sets are needed in order to setup physically sound dynamics simulations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Generation of initial geometries and velocities  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within the S<span style=\"font-size:x-small\">HARC<\/span> suite, initial geometries and velocities can be generated based on a quantum harmonic oscillator Wigner distribution.<br \/>\nThe theoretical background is given in Section <a href=\"#met:wigner\">8.24<\/a>.<br \/>\nThe calculation is performed by <b><tt>wigner.py<\/tt><\/b>, which is explained in Section <a href=\"#sec:wigner.py\">7.1<\/a>.<br \/>\nFor special Wigner sampling tasks (e.g., only specific energies, modes), one can use <b><tt>wigner_state_selected.py<\/tt><\/b> (Section <a href=\"#sec:wigner_state_selected.py\">7.2<\/a>).<br \/>\nTo combine the initial conditions of two molecules for collision\/scattering simulations, one can use <b><tt>bimolecular_collision.py<\/tt><\/b> (Section <a href=\"#sec:bimolecular_collision.py\">7.3<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>As given in Figure <a href=\"#fig:workflow\">3.3<\/a>, <b><tt>wigner.py<\/tt><\/b> needs as input the result of a frequency calculation in M<span style=\"font-size:x-small\">OLDEN<\/span> format.<br \/>\nThe calculation can be performed by any quantum chemistry program and any method the user sees fit (there are some scripts which can aid in the frequency calculation, see Sections <a href=\"#sec:GAUSSIAN_freq.py\">6.8.4<\/a>, <a href=\"#sec:ORCA_hess_freq.py\">6.9.4<\/a>,<br \/>\n<a href=\"#sec:molcas_input.py\">6.12.4<\/a>, <a href=\"#sec:AMS_ADF_freq.py\">6.16.4<\/a>, <a href=\"#sec:molpro_input.py\">6.19.6<\/a>).<br \/>\n<b><tt>wigner.py<\/tt><\/b> produces the file <b><tt>initconds<\/tt><\/b>, which contains a list of initial conditions ready for further processing.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, initial geometries and velocities can be extracted from molecular dynamics simulations in the ground state.<br \/>\nCurrently, it is possible to either convert restart files from A<span style=\"font-size:x-small\">MBER<\/span> to an <b><tt>initconds<\/tt><\/b> file (using <b><tt>amber_to_initconds.py<\/tt><\/b>, see Section <a href=\"#sec:amber_to_initconds.py\">7.4<\/a>) or to randomly sample snapshots from previous S<span style=\"font-size:x-small\">HARC<\/span> trajectories (using <b><tt>sharctraj_to_initconds.py<\/tt><\/b>, see Section <a href=\"#sec:sharctraj_to_initconds.py\">7.5<\/a>).<br \/>\nIn some cases, these tasks can also be performed with <b><tt>restartnc_to_xyz.py<\/tt><\/b> (Section <a href=\"#sec:restartnc_to_xyz.py\">7.6<\/a>) and <b><tt>sharctraj_to_xyz.py<\/tt><\/b> (Section <a href=\"#sec:sharctraj_to_xyz.py\">7.7<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Generation of initial coefficients and states  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the second preparation step, for each of the sampled initial geometries it has to be decided which excited state should be the initial one.<br \/>\nIn simple cases, the user may manually choose the initial excited state using <b><tt>excite.py<\/tt><\/b> (optionally after diabatization; see <a href=\"#sec:excite.py\">7.9<\/a>).<br \/>\nAlternatively, the selection of initial states can be performed based on the excitation energies and oscillator strengths of the excited states at each initial geometry (this approximately simulates a delta-pulse excitation). <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The latter options (diabatization or energies\/oscillator strengths) make it necessary to carry out vertical excitation calculation before the selection of the initial states.<br \/>\nThe calculations can be set up with <b><tt>setup_init.py<\/tt><\/b> (see Section <a href=\"#sec:setup_init.py\">7.8<\/a>).<br \/>\nThis script prepares for each initial condition in the <b><tt>initconds<\/tt><\/b> file a directory with the necessary input to perform the calculation.<br \/>\nThe user should then execute the run script (<b><tt>run.sh<\/tt><\/b>) in each of the directories (either manually or through a batch queueing system).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After the vertical excitation calculations are completed, the vertical excitation energies and oscillator strengths of each calculation are collected by <b><tt>excite.py<\/tt><\/b> (see <a href=\"#sec:excite.py\">7.9<\/a>).<br \/>\nThe same script then performs the selection of the initial electronic state for each initial geometry.<br \/>\nThe results are written to a new file, <b><tt>initconds.excited<\/tt><\/b>.<br \/>\nThis file contains all information needed to setup the ensemble. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Additionally, <b><tt>spectrum.py<\/tt><\/b> (<a href=\"#sec:spectrum.py\">7.10<\/a>) can calculate absorption spectra based on the <b><tt>initconds.excited<\/tt><\/b> file.<br \/>\nThis may be useful to verify that the level of theory chosen is appropriate (e.g., by comparing to an experimental spectrum), or to choose a suitable excitation window for the determination of the initial state.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.2.2\"><\/a><\/p>\n<h3>\n3.2.2  Setting up the dynamics simulations<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>To prepare for the trajectory setup, in some cases specific input files need to be prepared.<br \/>\nThis includes <b><tt>laser<\/tt><\/b> files that can be produced with <b><tt>laser.x<\/tt><\/b> (Section <a href=\"#sec:laser.x\">7.11<\/a>) or QM\/MM-related files that can be created with <b><tt>setup_from_prmtop.py<\/tt><\/b> (Section <a href=\"#sec:setup_from_prmtop.py\">7.12<\/a>).<br \/>\nFurther interface-specific files can be produced with, e.g., <b><tt>molcas_input.py<\/tt><\/b> (Section <a href=\"#sec:molcas_input.py\">6.12.4<\/a>),<br \/>\n<b><tt>molpro_input.py<\/tt><\/b> (Section <a href=\"#sec:molpro_input.py\">6.19.6<\/a>),<br \/>\n<b><tt>setup_LVCparam.py<\/tt><\/b>,<br \/>\n<b><tt>create_LVCparam.py<\/tt><\/b>,<br \/>\nand <b><tt>modify_LVC_template.py<\/tt><\/b> (see all three in Section <a href=\"#sec:setup_LVCparam.py\">6.4.4<\/a>).<br \/>\nHowever, for many interface, one only needs to take an example template file from <b><tt>$SHARC\/..\/examples\/<\/tt><\/b> and adapt it to the specific needs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Based on the initial conditions given in <b><tt>initconds.excited<\/tt><\/b> and the prepared input\/template files, the input for all trajectories in the ensemble can be setup by <b><tt>setup_traj.py<\/tt><\/b> (see Section <a href=\"#sec:setup_traj.py\">7.13<\/a>).<br \/>\nThe script produces one directory for each trajectory, containing the input files for the dynamics drivers and the selected interface.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.2.3\"><\/a><\/p>\n<h3>\n3.2.3  Running the dynamics simulations<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In order to run a particular trajectory, the user should execute the run script (<b><tt>run.sh<\/tt><\/b>) in the directory of the trajectory.<br \/>\nSince those calculations can run between minutes and several weeks (depending on the level of theory used and the number of time steps), it is advisable to submit the run scripts to a batch queueing system. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The progress of the simulations can be monitored most conveniently in the <b><tt>output.lis<\/tt><\/b> files.<br \/>\nIf the calculations are running in some temporary directory, the output files can be copied to the local directory (where they were setup) with the <b><tt>scp<\/tt><\/b> wrapper <b><tt>retrieve.sh<\/tt><\/b> (see Section <a href=\"#sec:retrieve.sh\">7.14<\/a>).<br \/>\nThis allows to perform ensemble analysis while the trajectories are still running.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If a trajectory fails, the temporary directory where the calculation is running is not deleted.<br \/>\nThe file <b><tt>README<\/tt><\/b> will be created in the trajectory’s directory, giving the time of the failure and the location of the temporary data, so that the case can be investigated. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to signal S<span style=\"font-size:x-small\">HARC<\/span> to terminate a trajectory after the current time step is completed, the user can create a (possibly empty) file <b><tt>STOP<\/tt><\/b> in the working directory of the trajectory (the directory where <b><tt>sharc.x<\/tt><\/b> is running).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>To remove all output files of a trajectory and restore it to the status after setup, one can use <b><tt>clean_traj.sh<\/tt><\/b> (Section <a href=\"#sec:clean_traj.sh\">7.15<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The status of the ensemble of trajectories can be checked with <b><tt>diagnostics.py<\/tt><\/b> (Section <a href=\"#sec:diagnostics.py\">7.16<\/a>).<br \/>\nThis script checks the presence and integrity of all relevant files, the progress of all trajectories, and warns if trajectories behave unexpectedly (non-conversion of total energy, intruder states, etc).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.2.4\"><\/a><\/p>\n<h3>\n3.2.4  Analysis of the dynamics results<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Each trajectory can be analyzed independently by inspecting the output files (see chapter <a href=\"#chap:output\">5<\/a>).<br \/>\nMost importantly, calling <b><tt>data_extractor.x<\/tt><\/b> (<a href=\"#sec:data_extractor.x\">7.17<\/a>) or <b><tt>data_extractor_NetCDF.x<\/tt><\/b> (<a href=\"#sec:data_extractor_NetCDF.x\">7.18<\/a>) on the <b><tt>output.dat<\/tt><\/b> file of a trajectory creates a number of formatted files.<br \/>\nIf needed, the <b><tt>output.dat<\/tt><\/b> and <b><tt>output.dat.nc<\/tt><\/b> files can be interconverted with <b><tt>data_converter.x<\/tt><\/b> (<a href=\"#sec:data_converter.x\">7.19<\/a>) and <b><tt>data_converter_to_ASCII.x<\/tt><\/b> (<a href=\"#sec:data_converter_to_ASCII.x\">7.20<\/a>).<br \/>\nIn special cases, the file <b><tt>output_NUC.dat.nc<\/tt><\/b> is produced, which can be converted to <b><tt>output.xyz<\/tt><\/b> with <b><tt>data_extractor_NUC_xyz.py<\/tt><\/b> (Section <a href=\"#sec:data_extractor_NUC_xyz.py\">7.21<\/a>).<br \/>\nThe files produced by the extractor programs can be plotted with the help of <b><tt>make_gnuscript.py<\/tt><\/b> (Section <a href=\"#sec:make_gnuscript.py\">7.22<\/a>) and G<span style=\"font-size:x-small\">NUPLOT<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The nuclear geometries in <b><tt>output.xyz<\/tt><\/b> file can be analyzed in terms of internal coordinates (bond lengths, angles, ring conformations, etc.) using <b><tt>geo.py<\/tt><\/b> (Section <a href=\"#sec:geo.py\">7.23<\/a>) and in terms of normal mode coordinates using <b><tt>geo_NM.py<\/tt><\/b> (Section <a href=\"#sec:geo_NM.py\">7.24<\/a>).<br \/>\nThe manual analysis of all individual trajectories is usually a good idea to verify that the trajectories are correctly executing, and to find general reaction pathways.<br \/>\nThe manual analysis often permits to formulate some hypotheses, which can then be verified with the statistical analysis tools.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For the statistical analysis of the complete ensemble, the first step should usually be to run <b><tt>diagnostics.py<\/tt><\/b> (Section <a href=\"#sec:diagnostics.py\">7.16<\/a>).<br \/>\nThis script will determine how long the different trajectories are, and, more importantly, will check the trajectories for file integrity, conservation of total energy, and continuity of potential\/kinetic energy.<br \/>\nBased on a set of customizable criteria, the script determines for each trajectory a “maximum usable time”.<br \/>\nThe script then can mark all trajectories with maximum usable time below a given threshold to be excluded from analysis (by creating a file <b><tt>DONT_ANALYZE<\/tt><\/b> in the trajectory’s directory).<br \/>\nThe other analysis scripts will then ignore trajectories marked by <b><tt>diagnostics.py<\/tt><\/b>.<br \/>\nTrajectories can also be manually excluded from analysis, by creating a file called <b><tt>CRASHED<\/tt><\/b>, <b><tt>DEAD<\/tt><\/b>, or <b><tt>RUNNING<\/tt><\/b> in the respective directory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After the trajectories were checked and unsuitable ones excluded, the statistical analysis scripts can be used.<br \/>\nThe script <b><tt>populations.py<\/tt><\/b> (Section <a href=\"#sec:populations.py\">7.25<\/a>) can calculate average excited-state populations using different algorithms and prepares files needed to obtain time constants and their uncertainties.<br \/>\nThe script <b><tt>transition.py<\/tt><\/b> (Section <a href=\"#sec:transition.py\">7.26<\/a>) can analyze the total number of hops between all pairs of states in an ensemble, allowing to identify relevant relaxation routes in the dynamics.<br \/>\nUsing the script <b><tt>make_fit.py<\/tt><\/b> (Section <a href=\"#sec:make_fit.py\">7.27<\/a>), it is possible to make elaborate global fits of chemical kinetics models to the populations data, allowing to extract rate constants from the populations, and to compute errors for these rate constants.<br \/>\nThe script <b><tt>crossing.py<\/tt><\/b> (Section <a href=\"#sec:crossing.py\">7.28<\/a>) can find and extract notable geometries, e.g., those geometries where a surface hop between two particular states occurred.<br \/>\nUsing <b><tt>trajana_essdyn.py<\/tt><\/b> (Section <a href=\"#sec:trajana_essdyn.py\">7.29<\/a>) it is possible to perform essential dynamics analysis.<br \/>\nFinally, <b><tt>data_collector.py<\/tt><\/b> (Section <a href=\"#sec:data_collector.py\">7.30<\/a>) can merge arbitrary tabulated data from the trajectories and perform various analysis procedures (compute mean\/standard deviation, data convolution, summation, integration), which can be used to compute, e.g., time-dependent distribution functions or time-dependent spectra.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Three new analysis scripts in S<span style=\"font-size:x-small\">HARC<\/span>4 can be used to collect coordinate data for each time step, align them in specific ways, and compute one- and three-dimensional distribution functions.<br \/>\nThese scripts are <b><tt>align_and_reorder_traj.py<\/tt><\/b> (Section <a href=\"#sec:align_and_reorder_traj.py\">7.31<\/a>), <b><tt>frames_to_RDF.py<\/tt><\/b> (Section <a href=\"#sec:frames_to_RDF.py\">7.32<\/a>), and <b><tt>frames_to_dx.py<\/tt><\/b> (Section <a href=\"#sec:frames_to_dx.py\">7.33<\/a>).<br \/>\nAs they are intended for large-scale analysis of big systems, they are only compatible with NetCDF output.<br \/>\nThe output of <b><tt>frames_to_RDF.py<\/tt><\/b> can be used to compute X-ray scattering signals using <b><tt>RDF_to_scattering.py<\/tt><\/b> (Section <a href=\"#sec:RDF_to_scattering.py\">7.34<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.3\"><\/a><\/p>\n<h2>\n3.3  Programs and Scripts of the S<span style=\"font-size:x-small\">HARC<\/span> Suite<\/h2>\n<div class=\"p\"><!----><\/div>\n<p>The following tables list all the programs in the S<span style=\"font-size:x-small\">HARC<\/span> suite.<br \/>\nThe rightmost column gives the section where the program is documented.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.3.1\"><\/a><\/p>\n<h3>\n3.3.1  Setup and Preparation<\/h3>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">wigner.py <\/td>\n<td align=\"left\">Creates initial conditions from a Wigner distribution. <\/td>\n<td width=\"414\"><a href=\"#sec:wigner.py\">7.1<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">wigner_state_selected.py <\/td>\n<td align=\"left\">Creates initial conditions from selected vibrational states. <\/td>\n<td width=\"414\"><a href=\"#sec:wigner_state_selected.py\">7.2<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">bimolecular_collision.py <\/td>\n<td align=\"left\">Creates initial conditions from two <b><tt>initconds<\/tt><\/b> files. <\/td>\n<td width=\"414\"><a href=\"#sec:bimolecular_collision.py\">7.3<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">amber_to_initconds.py <\/td>\n<td align=\"left\">Creates initial conditions from Amber restart files. <\/td>\n<td width=\"414\"><a href=\"#sec:amber_to_initconds.py\">7.4<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">sharctraj_to_initconds.py <\/td>\n<td align=\"left\">Creates initial conditions from S<span style=\"font-size:x-small\">HARC<\/span> trajectories. <\/td>\n<td width=\"414\"><a href=\"#sec:sharctraj_to_initconds.py\">7.5<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">restartnc_to_xyz.py <\/td>\n<td align=\"left\">Directly creates <b><tt>QM.in<\/tt><\/b> or <b><tt>geom<\/tt><\/b>\/<b><tt>veloc<\/tt><\/b> files from Amber restart files. <\/td>\n<td width=\"414\"><a href=\"#sec:restartnc_to_xyz.py\">7.6<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">sharctraj_to_xyz.py <\/td>\n<td align=\"left\">Directly creates <b><tt>QM.in<\/tt><\/b> or <b><tt>geom<\/tt><\/b>\/<b><tt>veloc<\/tt><\/b> files from S<span style=\"font-size:x-small\">HARC<\/span> trajectories. <\/td>\n<td width=\"414\"><a href=\"#sec:sharctraj_to_xyz.py\">7.7<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">setup_init.py <\/td>\n<td align=\"left\">Sets up initial vertical excitation calculations. <\/td>\n<td width=\"414\"><a href=\"#sec:setup_init.py\">7.8<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">excite.py <\/td>\n<td align=\"left\">Generates excited state lists for initial conditions and selects initial states. <\/td>\n<td width=\"414\"><a href=\"#sec:excite.py\">7.9<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">spectrum.py <\/td>\n<td align=\"left\">Generates absorption spectra from initial conditions files. <\/td>\n<td width=\"414\"><a href=\"#sec:spectrum.py\">7.10<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">laser.x <\/td>\n<td align=\"left\">Prepares files containing laser fields. <\/td>\n<td width=\"414\"><a href=\"#sec:laser.x\">7.11<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">setup_from_prmtop.py <\/td>\n<td align=\"left\">Sets up files for QM\/MM simulations (topology\/force field files, RATTLE files, and QM\/MM table files) from Amber topology files. <\/td>\n<td width=\"414\"><a href=\"#sec:setup_from_prmtop.py\">7.12<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">setup_traj.py <\/td>\n<td align=\"left\">Sets up the dynamics simulations based on the initial conditions. <\/td>\n<td width=\"414\"><a href=\"#sec:setup_traj.py\">7.13<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">setup_LVCparam.py <\/td>\n<td align=\"left\">Sets up single point calculations for LVC parametrization. <\/td>\n<td width=\"414\"><a href=\"#sec:setup_LVCparam.py\">6.4.4<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">create_LVCparam.py <\/td>\n<td align=\"left\">Produces LVC model files from parametrization data. <\/td>\n<td width=\"414\"><a href=\"#sec:setup_LVCparam.py\">6.4.4<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">modify_LVC_template.py <\/td>\n<td align=\"left\">Removes states, modes, or dipole moments from LVC parameter files.<\/td>\n<td width=\"414\"><a href=\"#sec:setup_LVCparam.py\">6.4.4<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">GAUSSIAN_freq.py <\/td>\n<td align=\"left\">Converts G<span style=\"font-size:x-small\">AUSSIAN<\/span> output files of frequency calculations to Molden format. <\/td>\n<td width=\"414\"><a href=\"#sec:GAUSSIAN_freq.py\">6.8.4<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ORCA_hess_freq.py <\/td>\n<td align=\"left\">Converts O<span style=\"font-size:x-small\">RCA<\/span> Hessian files to Molden format. <\/td>\n<td width=\"414\"><a href=\"#sec:ORCA_hess_freq.py\">6.9.4<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">molcas_input.py <\/td>\n<td align=\"left\">Prepares M<span style=\"font-size:x-small\">OLCAS<\/span> input files and template files for the M<span style=\"font-size:x-small\">OLCAS<\/span> interface. <\/td>\n<td width=\"414\"><a href=\"#sec:molcas_input.py\">6.12.4<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">AMS_ADF_freq.py <\/td>\n<td align=\"left\">Converts ADF output files of frequency calculations to Molden format. <\/td>\n<td width=\"414\"><a href=\"#sec:AMS_ADF_freq.py\">6.16.4<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">molpro_input.py <\/td>\n<td align=\"left\">Prepares M<span style=\"font-size:x-small\">OLPRO<\/span> input files and template files for the M<span style=\"font-size:x-small\">OLPRO<\/span> interface. <\/td>\n<td width=\"414\"><a href=\"#sec:molpro_input.py\">6.19.6<\/a><\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.3.2\"><\/a><\/p>\n<h3>\n3.3.2  Trajectory Running and Management<\/h3>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">sharc.x <\/td>\n<td align=\"left\">Legacy dynamics driver with full feature support but slow I\/O-based interface communication. <\/td>\n<td width=\"414\"><a href=\"#sec:drivers:sharc.x\">3.4.1<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">driver.py <\/td>\n<td align=\"left\">New PySHARC dynamics driver with fast in-memory interface communication but with a few unsupported features. <\/td>\n<td width=\"414\"><a href=\"#sec:drivers:driver.py\">3.4.2<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">retrieve.sh <\/td>\n<td align=\"left\"><b><tt>scp<\/tt><\/b> wrapper to retrieve dynamics output during the simulation. <\/td>\n<td width=\"414\"><a href=\"#sec:retrieve.sh\">7.14<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">clean_traj.sh <\/td>\n<td align=\"left\">Removes all output and restart files from a trajectory. <\/td>\n<td width=\"414\"><a href=\"#sec:clean_traj.sh\">7.15<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">diagnostics.py <\/td>\n<td align=\"left\">Checks ensembles for integrity, progress, energy conservation. <\/td>\n<td width=\"414\"><a href=\"#sec:diagnostics.py\">7.16<\/a><\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.3.3\"><\/a><\/p>\n<h3>\n3.3.3  Analysis<\/h3>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">data_extractor.x <\/td>\n<td align=\"left\">Extracts plottable results from the S<span style=\"font-size:x-small\">HARC<\/span> output data file. <\/td>\n<td width=\"414\"><a href=\"#sec:data_extractor.x\">7.17<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">data_extractor_NetCDF.x <\/td>\n<td align=\"left\">Extracts plottable results from the S<span style=\"font-size:x-small\">HARC<\/span> output data file in NetCDF format. <\/td>\n<td width=\"414\"><a href=\"#sec:data_extractor_NetCDF.x\">7.18<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">data_converter.x <\/td>\n<td align=\"left\">Converts <b><tt>output.dat<\/tt><\/b> files to <b><tt>output.dat.nc<\/tt><\/b> files. <\/td>\n<td width=\"414\"><a href=\"#sec:data_converter.x\">7.19<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">data_converter_to_ASCII.x <\/td>\n<td align=\"left\">Converts <b><tt>output.dat.nc<\/tt><\/b> files to <b><tt>output.dat.cp<\/tt><\/b>. <\/td>\n<td width=\"414\"><a href=\"#sec:data_converter_to_ASCII.x\">7.20<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">data_extractor_NUC_xyz.py <\/td>\n<td align=\"left\">Converts <b><tt>output_NUC.dat.nc<\/tt><\/b> files to <b><tt>output.xyz<\/tt><\/b> <\/td>\n<td width=\"414\"><a href=\"#sec:data_extractor_NUC_xyz.py\">7.21<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">make_gnuscript.py <\/td>\n<td align=\"left\">Creates gnuplot scripts to plot trajectory data. <\/td>\n<td width=\"414\"><a href=\"#sec:make_gnuscript.py\">7.22<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">geo.py <\/td>\n<td align=\"left\">Calculates internal coordinates from xyz files. <\/td>\n<td width=\"414\"><a href=\"#sec:geo.py\">7.23<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">geo_NM.py <\/td>\n<td align=\"left\">Calculates normal model coordinates from xyz files. <\/td>\n<td width=\"414\"><a href=\"#sec:geo_NM.py\">7.24<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">populations.py <\/td>\n<td align=\"left\">Calculates ensemble populations. <\/td>\n<td width=\"414\"><a href=\"#sec:populations.py\">7.25<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">transition.py <\/td>\n<td align=\"left\">Calculates total number of hops within an ensemble. <\/td>\n<td width=\"414\"><a href=\"#sec:transition.py\">7.26<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">make_fit.py <\/td>\n<td align=\"left\">Performs kinetic model fits and bootstrapping. <\/td>\n<td width=\"414\"><a href=\"#sec:make_fit.py\">7.27<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">crossing.py <\/td>\n<td align=\"left\">Extracts specific geometries from ensembles. <\/td>\n<td width=\"414\"><a href=\"#sec:crossing.py\">7.28<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">trajana_essdyn.py <\/td>\n<td align=\"left\">Performs an essential dynamics analysis for an ensemble. <\/td>\n<td width=\"414\"><a href=\"#sec:trajana_essdyn.py\">7.29<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">data_collector.py <\/td>\n<td align=\"left\">Collects data from tabular files and performs various analyses <\/td>\n<td width=\"414\"><a href=\"#sec:data_collector.py\">7.30<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">align_and_reorder_traj.py <\/td>\n<td align=\"left\">Collects, aligns, and converts coordinates into NetCDF files per time step. <\/td>\n<td width=\"414\"><a href=\"#sec:align_and_reorder_traj.py\">7.31<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">frames_to_RDF.py <\/td>\n<td align=\"left\">Computes radial histograms\/distribution functions from NetCDF files. <\/td>\n<td width=\"414\"><a href=\"#sec:frames_to_RDF.py\">7.32<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">frames_to_dx.py <\/td>\n<td align=\"left\">Computes 3D distributions in dx format from NetCDF files. <\/td>\n<td width=\"414\"><a href=\"#sec:frames_to_dx.py\">7.33<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">RDF_to_scattering.py <\/td>\n<td align=\"left\">Computes X-ray scattering from histogram data. <\/td>\n<td width=\"414\"><a href=\"#sec:RDF_to_scattering.py\">7.34<\/a><\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.3.4\"><\/a><\/p>\n<h3>\n3.3.4  Others<\/h3>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">tests.py <\/td>\n<td align=\"left\">Script to automatically run the S<span style=\"font-size:x-small\">HARC<\/span> test suite. <\/td>\n<td width=\"414\"><a href=\"#sec:tests.py\">2.2.3<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">wfoverlap.x <\/td>\n<td align=\"left\">Program to compute wave function overlaps, used by most interfaces. <\/td>\n<td width=\"414\"><a href=\"#sec:int:wfoverlap\">6.29<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">Orca_External <\/td>\n<td align=\"left\">Script to carry out optimizations with O<span style=\"font-size:x-small\">RCA<\/span>4 as optimizer and S<span style=\"font-size:x-small\">HARC<\/span> as gradient provider. <\/td>\n<td width=\"414\"><a href=\"#sec:Orca_External\">7.35<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">otool_external <\/td>\n<td align=\"left\">Script to carry out optimizations with O<span style=\"font-size:x-small\">RCA<\/span>5\/6 as optimizer and S<span style=\"font-size:x-small\">HARC<\/span> as gradient provider. <\/td>\n<td width=\"414\"><a href=\"#sec:Orca_External\">7.35<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">setup_orca_opt.py <\/td>\n<td align=\"left\">Script to setup optimizations with O<span style=\"font-size:x-small\">RCA<\/span> as optimizer and S<span style=\"font-size:x-small\">HARC<\/span> as gradient provider. <\/td>\n<td width=\"414\"><a href=\"#sec:Orca_External\">7.35<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">setup_single_point.py <\/td>\n<td align=\"left\">Script to setup single point calculations with S<span style=\"font-size:x-small\">HARC<\/span> interfaces. <\/td>\n<td width=\"414\"><a href=\"#sec:setup_single_point.py\">7.36<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">QMout_print.py <\/td>\n<td align=\"left\">Script to convert a <b><tt>QM.out<\/tt><\/b> file to a table with energies and oscillator strengths. <\/td>\n<td width=\"414\"><a href=\"#sec:QMout_print.py\">7.37<\/a><\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.3.5\"><\/a><\/p>\n<h3>\n3.3.5  Interfaces<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>Stub interfaces  <\/b> <\/p>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">SHARC_DO_NOTHING.py <\/td>\n<td align=\"left\">Provides zeros for all requested quantities (overlap matrices are returned as unit matrices). Intended for testing purposes only. <\/td>\n<td width=\"414\"><a href=\"#sec:int:do_nothing\">6.1<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_QMOUT.py <\/td>\n<td align=\"left\">Provides the Hamiltonian (with SOCs) and dipole moments from a provided <b><tt>QM.out<\/tt><\/b> file and returns zeros otherwise (unit matrix overlaps). Intended for S<span style=\"font-size:x-small\">HARC<\/span> trajectories with frozen nuclei\/electron-only dynamics. <\/td>\n<td width=\"414\"><a href=\"#sec:int:qmout\">6.2<\/a><\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p><b>Fast interfaces  <\/b> <\/p>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">SHARC_ANALYTICAL.py <\/td>\n<td align=\"left\">Provides SOCs, gradients, overlaps, dipole moments, and dipole moment derivatives based on analytical expressions formulated in <b><tt>sympy<\/tt><\/b> of diabatic matrix elements defined in Cartesian coordinates. <\/td>\n<td width=\"414\"><a href=\"#sec:int:analytical\">6.3<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_LVC.py <\/td>\n<td align=\"left\">Provides SOCs, gradients, nonadiabatic couplings, overlaps, and dipole moments based on linear\/quadratic-vibronic coupling models defined in mass-weighted normal mode coordinates. <\/td>\n<td width=\"414\"><a href=\"#sec:int:lvc\">6.4<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_SPAINN.py <\/td>\n<td align=\"left\">Calculates gradients, dipole moments, and nonadiabatic coupling vectors using SPaiNN machine learning models. <\/td>\n<td width=\"414\"><a href=\"#sec:int:spainn\">6.5<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_SCHNARC.py <\/td>\n<td align=\"left\">Provides gradients, dipole moments, and nonadiabatic coupling vectors using (Field)Schnet machine learning models. Can do electrostatic embedding. <\/td>\n<td width=\"414\"><a href=\"#sec:int:schnarc\">6.6<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_OPENMM.py <\/td>\n<td align=\"left\">Provides gradients, dipole moments, and multipolar fits using OpenMM and Amber force fields. <\/td>\n<td width=\"414\"><a href=\"#sec:int:openmm\">6.7<\/a><\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p><b>Ab initio interfaces  <\/b> <\/p>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">SHARC_GAUSSIAN.py <\/td>\n<td align=\"left\">Provides dipole moments, gradients, overlaps, Dyson norms, TheoDORE wave function descriptors, multipolar fits, and density matrices at the TD-DFT level of theory using G<span style=\"font-size:x-small\">AUSSIAN<\/span>. Can do electrostatic embedding. <\/td>\n<td width=\"414\"><a href=\"#sec:int:gaussian\">6.8<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_ORCA.py <\/td>\n<td align=\"left\">Provides SOCs, dipole moments, gradients, overlaps, Dyson norms, and TheoDORE wave function descriptors at the TD-DFT level of theory using O<span style=\"font-size:x-small\">RCA<\/span>. Can do electrostatic embedding. <\/td>\n<td width=\"414\"><a href=\"#sec:int:orca\">6.9<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_NWCHEM.py <\/td>\n<td align=\"left\">Provides dipole moments, gradients, and overlaps at the TD-DFT level of theory using NWC<span style=\"font-size:x-small\">HEM<\/span>. <\/td>\n<td width=\"414\"><a href=\"#sec:int:nwchem\">6.10<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_TURBOMOLE.py <\/td>\n<td align=\"left\">Provides SOCs, dipole moments, gradients, overlaps, Dyson norms, and TheoDORE wave function descriptors at the ADC(2) and CC2 levels of theory using T<span style=\"font-size:x-small\">URBOMOLE<\/span>. Can do electrostatic embedding. Some restrictions apply to CC2. Needs O<span style=\"font-size:x-small\">RCA<\/span> for SOCs. <\/td>\n<td width=\"414\"><a href=\"#sec:int:turbomole\">6.11<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_MOLCAS.py <\/td>\n<td align=\"left\">Provides SOCs, dipole moments, gradients, nonadiabatic coupling vectors, overlaps, Dyson norms, TheoDORE wave function descriptors, multipolar fits, and density matrices for CASSCF\/RASSCF, several CASPT2 variants, and some PDFT variants (using O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span>). Can do electrostatic embedding. <\/td>\n<td width=\"414\"><a href=\"#sec:int:molcas\">6.12<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_MNDO.py <\/td>\n<td align=\"left\">Provides dipole moments, gradients, nonadiabatic coupling vectors, and overlaps at the semiempirical MRCI level of theory using the MNDO code. Restricted to singlet states. Can do electrostatic embedding. <\/td>\n<td width=\"414\"><a href=\"#sec:int:mndo\">6.13<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_MOPACPI.py <\/td>\n<td align=\"left\">Provides dipole moments, gradients, nonadiabatic coupling vectors, and overlaps at the semiempirical MRCI level of theory using the MOPAC-PI code. Restricted to singlet states. Has built-in QM\/MM capabilities. <\/td>\n<td width=\"414\"><a href=\"#sec:int:mopac-pi\">6.14<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_LEGACY.py <\/td>\n<td align=\"left\">Provides SOCs, dipole moments, gradients, nonadiabatic coupling vectors, overlaps, Dyson norms, and TheoDORE wave function descriptors by calling any of the legacy interfaces below. <\/td>\n<td width=\"414\"><a href=\"#sec:int:legacy\">6.15<\/a><\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p><b>Legacy ab initio interfaces  <\/b> <\/p>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">SHARC_AMS_ADF.py <\/td>\n<td align=\"left\">Provides SOCs, dipole moments, gradients, overlaps, Dyson norms, and TheoDORE wave function descriptors at the TD-DFT level of theory using ADF. <\/td>\n<td width=\"414\"><a href=\"#sec:int:adf\">6.16<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_COLUMBUS.py <\/td>\n<td align=\"left\">Provides SOCs, dipole moments, gradients, nonadiabatic couplings, overlaps, and Dyson norms at the CASSCF, RASSCF, and MRCISD levels of theory using C<span style=\"font-size:x-small\">OLUMBUS<\/span>.<br \/>\n Some restrictions apply depending on the chosen integral engine. <\/td>\n<td width=\"414\"><a href=\"#sec:int:columbus\">6.17<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_BAGEL.py <\/td>\n<td align=\"left\">Provides dipole moments, gradients, nonadiabatic couplings, and overlaps at the CASSCF, CASPT2, MS-CASPT2, and XMS-CASPT2 level of theory using B<span style=\"font-size:x-small\">AGEL<\/span>. Restricted to singlet states. <\/td>\n<td width=\"414\"><a href=\"#sec:int:bagel\">6.18<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_MOLPRO.py <\/td>\n<td align=\"left\">Provides SOCs, dipole moments, gradients, nonadiabatic couplings, overlaps, and Dyson norms at the CASSCF level of theory (using M<span style=\"font-size:x-small\">OLPRO<\/span>). <\/td>\n<td width=\"414\"><a href=\"#sec:int:molpro\">6.19<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_PYSCF.py <\/td>\n<td align=\"left\">Provides dipole moments, gradients, and nonadiabatic couplings at the CASSCF, MC-PDFT, CMS-PDFT, and L-PDFT levels of theory (using P<span style=\"font-size:x-small\">Y<\/span>SCF). Restricted to singlet states. <\/td>\n<td width=\"414\"><a href=\"#sec:int:pyscf\">6.20<\/a><\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p><b>Single-child hybrid interfaces  <\/b> <\/p>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">SHARC_ASE_DB.py <\/td>\n<td align=\"left\">Provides any requested data from a single child interface. Stores geometry, point charges, and all results in a database using the ASE package. <\/td>\n<td width=\"414\"><a href=\"#sec:int:ase_db\">6.21<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_UMBRELLA.py <\/td>\n<td align=\"left\">Provides any requested data from a single child interface. Adds harmonic restraints to energies and gradients, using various collective variables. <\/td>\n<td width=\"414\"><a href=\"#sec:int:umbrella\">6.22<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_NUMDIFF.py <\/td>\n<td align=\"left\">Provides requested data from a single child interface. Also provides gradients, nonadiabatic couplings, and dipole moment\/SOC derivatives from finite differences. <\/td>\n<td width=\"414\"><a href=\"#sec:int:numdiff\">6.23<\/a><\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p><b>Multi-child hybrid interfaces  <\/b> <\/p>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">SHARC_QMMM.py <\/td>\n<td align=\"left\">Provides requested data by performing an electrostatic embedding QM\/MM calculation with one QM and two MM children. <\/td>\n<td width=\"414\"><a href=\"#sec:int:qmmm\">6.24<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_ECI.py <\/td>\n<td align=\"left\">Provides energies and dipole moments by performing an excitonic configuration interaction calculation based on several fragments computed with child interfaces. Requires electronstatic embedding, multipolar fitting, and density matrices from all children. <\/td>\n<td width=\"414\"><a href=\"#sec:int:eci\">6.25<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_ADAPTIVE.py <\/td>\n<td align=\"left\">Provides requested data from several child interfaces with a quorum-based termination criterion. <\/td>\n<td width=\"414\"><a href=\"#sec:int:adaptive\">6.26<\/a><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SHARC_FALLBACK.py <\/td>\n<td align=\"left\">Provides requested data from a trial child. If the trial child fails, provides data from a backup child instead. <\/td>\n<td width=\"414\"><a href=\"#sec:int:fallback\">6.27<\/a><\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.4\"><\/a><\/p>\n<h2>\n3.4  The S<span style=\"font-size:x-small\">HARC<\/span> dynamics drivers<\/h2>\n<p><a id=\"sec:drivers\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The original dynamics driver of S<span style=\"font-size:x-small\">HARC<\/span>, present since version 1.0, is <b><tt>sharc.x<\/tt><\/b>.<br \/>\nThis is a monolithic Fortran program that performs all steps of the S<span style=\"font-size:x-small\">HARC<\/span> method, including input parsing, initialization, nuclear propagation, requesting electronic structure information from an interface, electronic propagation, computing hopping probabilities, making hopping decisions, and producing output.<br \/>\nThe communication with the electronic structure interfaces is based on writing and reading ASCII files, as described in Section <a href=\"#sec:int_spec\">6.28<\/a>.<br \/>\nBesides the reading and writing of several files (which takes time and limits precision), this form of communication also implies that the electronic structure interface is restarted\/reloaded into memory at every time step (or even several times per time step).<br \/>\nHence, this is a relatively slow form of communication, which typically adds a few tenths of a second up to a few seconds per time step.<br \/>\nFor expensive on-the-fly quantum chemistry interfaces, where each time step takes at least several minutes, this time overhead is negligible.<br \/>\nHowever, for very fast potential energy surface methods (like analytical models, vibronic coupling models, machine learning models, or force fields), the overhead might well take much longer than the actual computation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>To overcome the limitations of file I\/O and reloading interface code, with S<span style=\"font-size:x-small\">HARC<\/span>2.1 the PySHARC approach was introduced.<br \/>\nPYSHARC is an implementation of the S<span style=\"font-size:x-small\">HARC<\/span> dynamics driver in Python that directly calls the Fortran routines of <b><tt>sharc.x<\/tt><\/b> through the Python-C API via intermediate C routines.<br \/>\nIn this way, both the Fortran code and the interface code can be run within the same program, omitting file-based communication and reloading of interface code.<br \/>\nUsing PySHARC can reduce the cost per time step for the mentioned fast methods from few seconds to few milliseconds, providing a dramatic speedup of the S<span style=\"font-size:x-small\">HARC<\/span> simulations.<br \/>\nConsequently, the use of PySHARC is highly advisable for S<span style=\"font-size:x-small\">HARC<\/span> simulations with all fast interfaces.<br \/>\nWhereas in S<span style=\"font-size:x-small\">HARC<\/span>3, each interface required a separate PySHARC driver, in S<span style=\"font-size:x-small\">HARC<\/span>4, all interfaces use the common <b><tt>driver.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>PySHARC is intended to change the S<span style=\"font-size:x-small\">HARC<\/span> workflow as little as possible.<br \/>\nBasically all features of <b><tt>sharc.x<\/tt><\/b> are supported.<br \/>\nThe only change that needs to be applied is to call the <b><tt>pysharc<\/tt><\/b> driver instead of <b><tt>sharc.x<\/tt><\/b>.<br \/>\nThe general trajectory setup script <b><tt>setup_traj.py<\/tt><\/b> can create input files for either driver.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The high efficiency of PySHARC is optimally combined with an efficient way of producing output.<br \/>\nAs the historical output format of S<span style=\"font-size:x-small\">HARC<\/span> in terms of ASCII files is not optimized for performance, during the implementation of PySHARC also new output routines, using the NetCDF binary file format, were implemented.<br \/>\nIt is advisable that every time PySHARC is run, output is written in NetCDF format.<br \/>\nDetails of NetCDF output are documented in Section <a href=\"#sec:netcdf\">5.4<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>As described in Section <a href=\"#sec:install\">2.2<\/a>, the S<span style=\"font-size:x-small\">HARC<\/span> code can be compiled in two ways, without and with PySHARC support.<br \/>\nIf compiled without PySHARC support, then only <b><tt>sharc.x<\/tt><\/b> is available.<br \/>\nIf compiled with PySHARC support, then both drivers will be created.<br \/>\nIt is noteworthy that the <b><tt>sharc.x<\/tt><\/b> with PySHARC is compiled differently and supports some different options than if compiled without PySHARC support.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.4.1\"><\/a><\/p>\n<h3>\n3.4.1  Original driver: <b><tt>sharc.x<\/tt><\/b><\/h3>\n<p><a id=\"sec:drivers:sharc.x\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>sharc.x<\/tt><\/b> driver is executed with<br \/>\n<tt>user@host> $SHARC\/sharc.x <filename><\/tt><br \/>\nTypically, the input file name is <b><tt>input<\/tt><\/b>.<br \/>\nInstead of the file name, one can provide any one of the arguments <b><tt>-v<\/tt><\/b>, <b><tt>-version<\/tt><\/b>, or <b><tt>-info<\/tt><\/b>.<br \/>\nIn this way, <b><tt>sharc.x<\/tt><\/b> will print its version infos and then exits.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When using <b><tt>sharc.x<\/tt><\/b>, the verbosity of the driver code is controlled by the <b><tt>printlevel<\/tt><\/b> keyword in the <b><tt>input<\/tt><\/b> file.<br \/>\nThe verbosity of the employed interfaces can be controlled via the environment variables $SHARCLOG or $SHARC_LOG.<br \/>\nPossible settings are <b><tt>40<\/tt><\/b> for ßilent”, <b><tt>11<\/tt><\/b> for default verbosity, and <b><tt>10<\/tt><\/b> for “debug” print.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within <b><tt>sharc.x<\/tt><\/b>, if the package was compiled without PySHARC support, the no support for NetCDF output is provided.<br \/>\nThe only <b><tt>output_format<\/tt><\/b> is <b><tt>ascii<\/tt><\/b>.<br \/>\nHowever, if the package was compiled without PySHARC, then the Bulirsch-Stoer-Hack and adaptive velocity Verlet nuclear integrators are available.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc3.4.2\"><\/a><\/p>\n<h3>\n3.4.2  PySHARC driver: <b><tt>driver.py<\/tt><\/b><\/h3>\n<p><a id=\"sec:drivers:driver.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The PySHARC driver can be execited with<br \/>\n<tt>user@host> $SHARC\/driver.py -i <NAME> <filename><\/tt><br \/>\nHere, <b><tt><filename><\/tt><\/b> has the same meaning as for <b><tt>sharc.x<\/tt><\/b>.<br \/>\nThe <b><tt>-i<\/tt><\/b> option (alias <b><tt>-interface<\/tt><\/b>) is used to select the interface that is employed in the dynamics.<br \/>\nIf hybrid interfaces are used, the <b><tt>-<\/tt><\/b> option only specifies the top-level interface; its child interfaces are set in the input files for the top-level interface, and <b><tt>driver.py<\/tt><\/b> does not know about the child interfaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>By default, <b><tt>driver.py<\/tt><\/b> initializes its child interface in the so-called <i>persistent mode<\/i>.<br \/>\nThis mode only has an effect for fast interfaces (those derived from <b><tt>SHARC_FAST.py<\/tt><\/b>); most other interfaces simply ignore this mode.<br \/>\nIn persistent mode, fast interfaces will not write interface-specific restart files in each time step, but only in the very last time step.<br \/>\nThis improves performance with those interfaces, but leaves the output without restart files in the case of a crash\/external termination.<br \/>\nUsing <b><tt>-p<\/tt><\/b> or <b><tt>-nonpersistent<\/tt><\/b>, the driver can be ordered to initialize the interface in non-persistent mode, where restart files are written every time step.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>With <b><tt>driver.py<\/tt><\/b>, the verbosity of the used interface(s) can be directly controlled via command line options.<br \/>\nUsing <b><tt>-s<\/tt><\/b> or <b><tt>-silent<\/tt><\/b>, only minimal information is printed.<br \/>\nThe level <b><tt>-s<\/tt><\/b> or <b><tt>-verbose<\/tt><\/b> provides the standard amount of output.<br \/>\nUsing <b><tt>-d<\/tt><\/b> or <b><tt>-debug<\/tt><\/b>, additional information on the execution of the interfaces is provided.<br \/>\nInstead of using these flags, the environment variables $SHARCLOG or $SHARC_LOG can be used.<br \/>\nNote that the flags and environment variables have no effect on the verbosity of the dynamics code itself.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When the package is compiled with PySHARC support, then via <b><tt>driver.py<\/tt><\/b> (and also via <b><tt>sharc.x<\/tt><\/b>), NetCDF output might be available (needs to be separately activated during compilation).<br \/>\nIn turn, with PySHARC support, the Bulirsch-Stoer-Hack and adaptive velocity Verlet integrators are not available.<br \/>\nOther options that in S<span style=\"font-size:x-small\">HARC<\/span>3 were not supported by PySHARC are now available in S<span style=\"font-size:x-small\">HARC<\/span>4.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_chAp4\"><\/a><\/p>\n<h1>\nChapter 4 <br \/>Input files<\/h1>\n<p><a id=\"chap:input\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this chapter, the format of all S<span style=\"font-size:x-small\">HARC<\/span> input files are presented. Those are the main input file (here called <b><tt>input<\/tt><\/b>), the geometry file, the velocity file, the coefficients file, the laser file, and the atom mask file. Only the first two are mandatory, the others are optional input files. All input files are ASCII text files.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.1\"><\/a><\/p>\n<h2>\n4.1  Main input file<\/h2>\n<p><a id=\"sec:inputfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This section presents the format and all input keywords for the main S<span style=\"font-size:x-small\">HARC<\/span> input. Note that when using <b><tt>setup_traj.py<\/tt><\/b>, full knowledge of the S<span style=\"font-size:x-small\">HARC<\/span> input keywords is not required.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.1.1\"><\/a><\/p>\n<h3>\n4.1.1  General remarks<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The input file has a relatively flexible structure. With very few exceptions, each single line is independent. An input line starts with a keyword, followed optionally by a number of arguments to this keyword. Example:<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <tt>stepsize 0.5<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here, <b><tt>stepsize<\/tt><\/b> is the keyword, referring to the size of the time steps for the nuclear motion in the dynamics. <b><tt>0.5<\/tt><\/b> gives the size of this time step, in this example 0.5 fs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A number of keywords have no arguments and act as simple switches (e.g., <b><tt>restart<\/tt><\/b>, <b><tt>gradcorrect<\/tt><\/b>, <b><tt>grad_select<\/tt><\/b>, <b><tt>nac_select<\/tt><\/b>, <b><tt>ionization<\/tt><\/b>, <b><tt>track_phase<\/tt><\/b>, <b><tt>dipole_gradient<\/tt><\/b>). Those keywords can be prefixed with <b><tt>no<\/tt><\/b> to explicitly deactivate the option (e.g., <b><tt>norestart<\/tt><\/b> deactivates restarts).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In each line a trailing comment can be added in the input file, by using the special character <b><tt>#<\/tt><\/b>. Everything after <b><tt>#<\/tt><\/b> is ignored by the input parser of S<span style=\"font-size:x-small\">HARC<\/span>. The input file also can contain arbitrary blank lines and lines containing only comments. All input is case-insensitive.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The input file is read by S<span style=\"font-size:x-small\">HARC<\/span> by subsequently searching the file for all known keywords. Hence, unknown or misspelled keywords are ignored. Also, the order of the keywords is completely arbitray. Note however, that if a keyword is repeated in the input only the <i>first<\/i> instance is used by the program. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.1.2\"><\/a><\/p>\n<h3>\n4.1.2  Input keywords<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In Table <a href=\"#tab:input\">4.1<\/a>, all input keywords for the S<span style=\"font-size:x-small\">HARC<\/span> input file are listed.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb4.1\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<table border=\"1\">\n<tr>\n<td colspan=\"4\" align=\"left\">\n<div style=\"text-align:center\">Table 4.1: Input keywords for <b><tt>sharc.x<\/tt><\/b> and <b><tt>driver.py<\/tt><\/b>. The first column gives the name of the keyword, the second lists possible arguments and the third line provides an explanation. Defaults are marked like <b><span style=\"color:#00BF28\">this<\/span><\/b>. $n denotes the n-th argument to the keyword. <\/div>\n<\/td>\n<\/tr>\n<p><a id=\"tab:input\"><br \/>\n<\/a><\/p>\n<tr>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><span class=\"roman\"><b>Keyword<\/b> <\/td>\n<td align=\"left\"><b>Arguments<\/b> <\/td>\n<td align=\"left\"><b>Explanation<\/b><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">printlevel <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Controls the verbosity of the log file.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=0 <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Log file is empty<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=1 <\/td>\n<td align=\"left\"><span class=\"footnotesize\">+ List of internal steps<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=2<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">+ Input parsing information<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=3 <\/td>\n<td align=\"left\"><span class=\"footnotesize\">+ Some information per time step<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=4 <\/td>\n<td align=\"left\"><span class=\"footnotesize\">+ More information per time step<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=5 <\/td>\n<td align=\"left\"><span class=\"footnotesize\">+ Much more information per time step<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">restart <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Dynamics is resumed from restart files.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">norestart<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Dynamics is initialized from input files. This gives an error if restart files are present.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\"><b><tt>norestart<\/tt><\/b> takes precedence.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">write_restart_files<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Write restart files.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nowrite_restart_files <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Don’t write restart files. Restart will not be possible!<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\"><b><tt>write_restart_files<\/tt><\/b> takes precedence.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">retain_restart_files <\/td>\n<td align=\"left\"><b>integer<\/b><\/td>\n<td align=\"left\">Retain interface restart files for the last $1 steps.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$=<b><span style=\"color:#00BF28\">2<\/span><\/b> or <b><span style=\"color:#00BF28\">3<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">With overlaps, default is 3 and minimum value is 1.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">rngseed <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Seed for the random number generator.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">10997279<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Used for surface hopping and AFSSH decoherence.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">compatibility <\/td>\n<td align=\"left\">$1=<b><span style=\"color:#00BF28\">0<\/span><\/b> <\/td>\n<td align=\"left\">Compatibility mode disabled.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=1 <\/td>\n<td align=\"left\">Do not draw a second random number per step (for decoherence).<\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Input file keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">geomfile <\/td>\n<td align=\"left\"><b>quoted string<\/b> <\/td>\n<td align=\"left\">File name containing the initial geometry.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">“geom”<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">velocfile <\/td>\n<td align=\"left\"><b>quoted string<\/b> <\/td>\n<td align=\"left\">File containing the initial velocities.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">“veloc”<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only read if <b><tt>veloc external<\/tt><\/b>.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coefffile <\/td>\n<td align=\"left\"><b>quoted string<\/b> <\/td>\n<td align=\"left\">File containing the initial wave function coefficients.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">“coeff”<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only read if <b><tt>coeff external<\/tt><\/b>.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">laserfile <\/td>\n<td align=\"left\"><b>quoted string<\/b> <\/td>\n<td align=\"left\">File containing the laser field.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">“laser”<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only read if <b><tt>laser external<\/tt><\/b>.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">atommaskfile <\/td>\n<td align=\"left\"><b>quoted string<\/b> <\/td>\n<td align=\"left\">File containing the atom mask.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">ätommask”<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only read if <b><tt>atommask external<\/tt><\/b>.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">rattlefile <\/td>\n<td align=\"left\"><b>quoted string<\/b> <\/td>\n<td align=\"left\">File containing the list of bond length constraints.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">“rattle”<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only read if <b><tt>rattle<\/tt><\/b>.<\/span><\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Trajectory initialization keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">veloc <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Sets the initial velocities.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=zero<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Initial velocities are zero.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=random $2 <b>float<\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Random initial velocities with $2 eV kinetic energy per atom.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=external <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Initial velocities are read from file.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nstates <\/td>\n<td align=\"left\">list of <b>integer<\/b>s <\/td>\n<td align=\"left\">Number of states per multiplicity.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1 (<b><span style=\"color:#00BF28\">1<\/span><\/b>) <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Number of singlet states<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$2 (<b><span style=\"color:#00BF28\">0<\/span><\/b>) <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Number of doublet states<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$3 (<b><span style=\"color:#00BF28\">0<\/span><\/b>) <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Number of triplet states<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$… (<b><span style=\"color:#00BF28\">0<\/span><\/b>) <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Number of states of higher multiplicities<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">charge <\/td>\n<td align=\"left\">list of <b>integer<\/b>s <\/td>\n<td align=\"left\">Charge of states per multiplicity.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1 (<b><span style=\"color:#00BF28\">no default<\/span><\/b>) <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Charge of singlet states<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$2 <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Charge of doublet states<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$3 <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Charge of triplet states<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$… <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Charge of states of higher multiplicities<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">actstates <\/td>\n<td align=\"left\">list of <b>integer<\/b>s <\/td>\n<td align=\"left\">Number of active states per multiplicity.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">same as <b><tt>nstates<\/tt><\/b><\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">By default, all states are active.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">state <\/td>\n<td align=\"left\"><b>integer<\/b>, <b>string<\/b> <\/td>\n<td align=\"left\">Specifies the initial state.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">(no default; S<span style=\"font-size:x-small\">HARC<\/span> exits if <b><tt>state<\/tt><\/b> is missing).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1 <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Initial state.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$2=MCH <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Initial state and coefficients are given in MCH representation.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$2=diag <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Initial state and coefficients are given in diagonal representation.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coeff <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Sets the wave function coefficients.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=auto<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Initial coefficient are determined automatically from initial state.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=external <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Initial coefficients are read from file.<\/span><\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Laser field keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">laser <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Sets the laser field.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=none<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">No laser field is applied.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=internal <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Laser field is calculated at each time step from internal function.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=external <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Laser field for each time step is read during initialization.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">laserwidth <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Laser bandwidth used to detect induced hops.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">1.0 eV<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Time step keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">stepsize <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Length of the nuclear dynamics time steps in fs.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">0.5 fs<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nsubsteps <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Number of substeps for the integration of the electronic equation of motion.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">25<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nsteps <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Number of simulation steps.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">3<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">tmax <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Total length of the simulation in fs.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\">No effect if <b><tt>nsteps<\/tt><\/b> is present.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">killafter <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Terminates the trajectory after $1 fs in the lowest state. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">-1<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">If $1 < 0, trajectories are never killed.<\/span><\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Integrator keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">integrator <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Method to control the integrator.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=fvv<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Fixed time step velocity Verlet integrator.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=avv <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Adaptive time step velocity Verlet integrator (not in <b><tt>pysharc<\/tt><\/b>).<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">convthre <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Convergence threshold for adaptive integrators (in eV). <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=1e-04<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">stepsize_min <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Minimum step size allowed in adaptive velocity Verlet.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=stepsize\/16<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">stepsize_max <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Maximum step size allowed in adaptive velocity Verlet.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=stepsize*2<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">stepsize_min_exp <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Minimum power of 2 allowed in adjusting the time step in adaptive velocity Verlet. If used, this keyword will overwrite keyword stepsize_min.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=-4<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">stepsize_max_exp <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Maximum power of 2 allowed in adjusting the time step in adaptive velocity Verlet. If used, this keyword will overwrite keyword stepsize_max.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=2<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Dynamics setting keywords that applicable to both TSH and SCP methods –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">method <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Nonadiabatic dynamics method.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=tsh<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Uses trajectory surface hopping.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=scp, ehrenfest <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Uses self-consistent potential methods.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coupling <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Quantities describing the nonadiabatic couplings.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=ddr,nacdr <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Uses vectorial nonadiabatic couplings 〈ψ<sub>α<\/sub>|∂\/∂R|ψ<sub>β<\/sub>〉.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=ddt,nacdt <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Uses temporal nonadiabatic couplings 〈ψ<sub>α<\/sub>|∂\/∂t|ψ<sub>β<\/sub>〉.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=<b><span style=\"color:#00BF28\">overlap<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Uses the overlaps 〈ψ<sub>α<\/sub>(t<sub>0<\/sub>)|ψ<sub>β<\/sub>(t)〉 (local diabatization).<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=ktdc <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Uses curvature driven approximation for time derivative coupling.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ktdc_method <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Method to compute curvature driven approximated time derivative coupling.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=energy<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Second order finite difference of energy (default for TSH).<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=gradient<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">First order finite difference of dot product of gradients and velocity vector (default for SCP).<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">eeom <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Method to control the propagator of electronic equation of motion. We suggest the users use default options.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=ci <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Constant interpolation.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=li<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Linear interpolation. This is the default when set coupling=ddr or coupling=ktdc.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=ld<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Local diabatization. This is the default when set coupling=overlap and method=tsh.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=npi<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Norm preserving interpolation.<a href=\"#Meek2014JPCL\" id=\"CITEMeek2014JPCL\" class=\"tth_citation\">[93<\/a>] This is the default when set coupling=overlap and method=scp.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">gradcorrect <\/td>\n<td align=\"left\">empty or <b>string<\/b> <\/td>\n<td align=\"left\">Include NACs in gradient transformation.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=none, ngt, nac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Include (E<sub>α<\/sub>−E<sub>β<\/sub>)〈ψ<sub>α<\/sub>|∂\/∂R|ψ<sub>β<\/sub>〉 in gradient transformation.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=tdm, kmatrix <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Include (E<sub>α<\/sub>−E<sub>β<\/sub>)〈ψ<sub>α<\/sub>|∂\/∂t|ψ<sub>β<\/sub>〉 in gradient transformation.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">nogradcorrect<\/span><\/b><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Transform only the gradients.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">tdm_method <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Method to control the computations of time derivative of potential energies in diagonal basis in TDM gradient correction scheme.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=gradient<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Time derivative of potential energies in diagonal basis are computed from transformation of time derivative matrix in MCH basis. And the time derivative of potential energies in MCH basis are computed by a dot product between nuclear gradient vector and velocity vector. This is the default option for coupling=ddr or coupling=overlap.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=energy<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Time derivative of potential energies in diagonal basis are computed from finite difference. This is more accurate for curvature driven methods because in curvature-driven algorithms we approximate TDCs instead of computing TDCs accurately form electronic structure software. This is the default option for coupling=ktdc.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">decoherence_scheme <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Method for decoherence correction.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=none<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">No decoherence correction.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=edc <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Energy-difference based correction.<a href=\"#Granucci2010JCP\" id=\"CITEGranucci2010JCP\" class=\"tth_citation\">[94<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=afssh <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Augmented FSSH.<a href=\"#Jain2016JCTC\" class=\"tth_citeref\">[39<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=dom <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Add decay-of-mixing decoherence to SCP methods to perform CSDM or SCDM.<a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>,<a href=\"#ShuCSDM2020JCTC\" class=\"tth_citeref\">[31<\/a>] Not usable for TSH.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">decoherence <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Applies decoherence correction (defaults are EDC for TSH methods and Decay-of-Mixing for SCP methods).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">nodecoherence<\/span><\/b><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">No decoherence correction.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\"><b><tt>nodecoherence<\/tt><\/b> takes precedence.<\/span><\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Surface hopping setting keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">surf <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Potential energy surfaces used in TSH. No effect for SCP.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=diagonal,sharc<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Uses diagonal potentials.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=MCH <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Uses MCH potentials.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ekincorrect <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Adjustment of the kinetic energy after a surface hop.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=none <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Kinetic energy is not adjusted. Jumps are never frustrated.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=parallel_vel<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Velocity is rescaled to adjust kinetic energy.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_pvel <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of vibrational motion is rescaled.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_nac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of 〈ψ<sub>α<\/sub>|∂\/∂R|ψ<sub>β<\/sub>〉 is rescaled.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_diff <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of ∆∇E is rescaled.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_pnac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of projected 〈ψ<sub>α<\/sub>|∂\/∂R|ψ<sub>β<\/sub>〉 is rescaled. The projection ensures conservation of nuclear orbital angular momentum and center of mass motion<a href=\"#Shu2020JPCL\" class=\"tth_citeref\">[76<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_enac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of effective nonadiabatic coupling vector is rescaled.<a href=\"#ShutCSDM2020JCTC\" class=\"tth_citeref\">[75<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_penac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of projected effective nonadiabatic coupling vector is rescaled.<a href=\"#ShutCSDM2020JCTC\" class=\"tth_citeref\">[75<\/a>,<a href=\"#Shu2020JPCL\" class=\"tth_citeref\">[76<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">reflect_frustrated <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Reflection of trajectory after frustrated hop.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=none<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">No reflection.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_vel <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Full velocity vector is reflected.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_pvel <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of vibrational motion is reflected.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_nac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of 〈ψ<sub>α<\/sub>|∂\/∂R|ψ<sub>β<\/sub>〉 is reflected.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_diff <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of ∆∇E is reflected.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_pnac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of projected 〈ψ<sub>α<\/sub>|∂\/∂R|ψ<sub>β<\/sub>〉 is reflected. The projection ensures conservation of nuclear orbital angular momentum and center of mass motion<a href=\"#Shu2020JPCL\" class=\"tth_citeref\">[76<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_enac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of effective nonadiabatic coupling vector is reflected.<a href=\"#ShutCSDM2020JCTC\" class=\"tth_citeref\">[75<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=parallel_penac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of projected effective nonadiabatic coupling vector is reflected.<a href=\"#ShutCSDM2020JCTC\" class=\"tth_citeref\">[75<\/a>,<a href=\"#Shu2020JPCL\" class=\"tth_citeref\">[76<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=delV_vel <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Full velocity vector is reflected according to ∇V criteria.<a href=\"#Jasper2003CPL\" id=\"CITEJasper2003CPL\" class=\"tth_citation\">[95<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=delV_pvel <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of vibrational motion is reflected according to ∇V criteria.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=delV_nac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of 〈ψ<sub>α<\/sub>|∂\/∂R|ψ<sub>β<\/sub>〉 is reflected according to ∇V criteria.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=delV_diff <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of ∆∇E is reflected according to ∇V criteria.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=delV_pnac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of projected 〈ψ<sub>α<\/sub>|∂\/∂R|ψ<sub>β<\/sub>〉 is reflected according to ∇V criteria.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=delV_enac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of effective nonadiabatic coupling vector is reflected according to ∇V criteria.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=delV_penac <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Only the velocity component in the direction of projected effective nonadiabatic coupling vector is reflected according to ∇V criteria.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">hopping_procedure <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Method for hopping probabilities.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=off <\/td>\n<td align=\"left\"><span class=\"footnotesize\">No hops (same as <b><tt>no_hops<\/tt><\/b>).<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=sharc,standard<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Standard S<span style=\"font-size:x-small\">HARC<\/span> hopping probabilities.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=gfsh <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Global flux SH hopping probabilities.<a href=\"#Wang2014JCTC\" class=\"tth_citeref\">[51<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">no_hops <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Disables surface hopping.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\"><b><tt>no_hops<\/tt><\/b> takes precedence over <b><tt>hopping_procedure<\/tt><\/b>.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">force_hop_to_gs <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Activates forced hops to lowest state.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\">hop is forced if lowest-active energy difference < $1 (in eV)<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">time_uncertainty <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Employ fewest switches with time uncertainty algorithm in TSH to reduce the number of frustrated hops.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">notime_uncertainty<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\">No time uncertainty used.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">decoherence_param <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Value α in EDC (in Hartree).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">0.1<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">$1 > 0.0<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">atommask <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Activates masking of atoms (for EDC, <b><tt>parallel_vel<\/tt><\/b>).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=none<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">No atoms are masked.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=external <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Atom mask is read from external file.<\/span><\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Self-consistent potential methods setting keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">neom <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Methods to control the direction of the nonadiabatic force in nuclear equation of motion for SCP methods.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=ddr,nacdr<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Use full nonadiabatic coupling vector. This is the default when coupling=ddr.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=gdiff<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Use effective nonadiabatic coupling vector, which is a combination of difference gradient vector and velocity vector. This is the default when coupling=overlap or coupling=ktdc.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">neom_rep <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Representations used to propagate nuclear equation of motion for SCP methods.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=diag<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Use diagonal representation.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=MCH <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Uses MCH representation.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">pointer_basis <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Methods to control the pointer basis employed in decay-of-mixing algorithms. We suggest use the default option.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=diag<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Use the diagonal basis as the pointer basis.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=MCH <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Use the MCH basis as the pointer basis.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">switching_procedure <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Methods for scheme used to switch the pointer state in decay-of-mixing algorithms.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=csdm<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Using coherent switching with decay of mixing. <a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>,<a href=\"#ShuCSDM2020JCTC\" class=\"tth_citeref\">[31<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=scdm <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Using self-consistent decay of mixing. <a href=\"#ZhuSCDM2004JCP\" class=\"tth_citeref\">[40<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=ndm <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Using natural decay of mixing. <a href=\"#Hack2001JCP2\" id=\"CITEHack2001JCP2\" class=\"tth_citation\">[96<\/a>]<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=off <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Surface switching is off.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">nac_projection<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Applies projection on the direction of the nonadiabatic force in nuclear equation of motion for SCP methods. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\">This is the default option that ensures conservation of nuclear orbital angular momentum and center of mass motion.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nonac_projection <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Do not apply projection on the direction of nonadiabatic force in nuclear equation of motion for SCP methods.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">decotime_method <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Method to control computation of decoherence time.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1<b><span style=\"color:#00BF28\">=csdm<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">computed with CSDM method <a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>,<a href=\"#ShuCSDM2020JCTC\" class=\"tth_citeref\">[31<\/a>].<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=scdm <\/td>\n<td align=\"left\"><span class=\"footnotesize\">computed with SCDM method <a href=\"#ZhuSCDM2004JCP\" class=\"tth_citeref\">[40<\/a>].<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=edc <\/td>\n<td align=\"left\"><span class=\"footnotesize\">computed with EDC (energy based decoherence) method <a href=\"#Granucci2010JCP\" class=\"tth_citeref\">[94<\/a>].<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=sd <\/td>\n<td align=\"left\"><span class=\"footnotesize\">computed with SD (stochastic decoherence) method <a href=\"#Jasper2007JCP\" id=\"CITEJasper2007JCP\" class=\"tth_citation\">[97<\/a>].<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">decoherence_param_alpha <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Value α in decay of mixing decoherence time (in Hartreee).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">0.1<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">$1 > 0.0<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">decoherence_param_beta <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Value β in decay of mixing decoherence time (unitless).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">1.0<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">$1>0.0<\/span><\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Constraints –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">rattle <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Enables bond length constraints through RATTLE.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">norattle<\/span><\/b><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">No RATTLE.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\"><b><tt>norattle<\/tt><\/b> takes precedence.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">rattletolerance <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Convergence criterion for RATTLE.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">1e-7<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">$1 > 0.0<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">freeze <\/td>\n<td align=\"left\"><b>various<\/b> <\/td>\n<td align=\"left\">Specifies info for freezing atoms.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=<b><span style=\"color:#00BF28\">none<\/span><\/b> <\/td>\n<td align=\"left\">All atoms are propagated.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=last $2=n<\/td>\n<td align=\"left\">Last n atoms are not propagated.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=atoms $2=at<sub>1<\/sub> at<sub>2<\/sub> …<\/td>\n<td align=\"left\">Atoms with index at<sub>1<\/sub>, at<sub>2<\/sub>, … are not propagated.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=file $2=<b><span style=\"color:#00BF28\">“frozen”<\/span><\/b><\/td>\n<td align=\"left\">Read information from file (Section <a href=\"#sec:frozenfile\">4.8<\/a>).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">restrictive_potential <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Activate restrictive potentials. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=<b><span style=\"color:#00BF28\">none<\/span><\/b> <\/td>\n<td align=\"left\">No restrictive potential is used.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=droplet <\/td>\n<td align=\"left\">Restricted droplet potential is used.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=tether <\/td>\n<td align=\"left\">Tethering of atom(s) is employed. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=droplet_tether <\/td>\n<td align=\"left\">Both restrictive potential and tethering of atom(s).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">restricted_droplet_force <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Sets force for restricted droplet potential. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1 <\/td>\n<td align=\"left\">Force constant in [(E<sub>h<\/sub>)\/(a<sub>0<\/sub><sup>2<\/sup>)].<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">restricted_droplet_radius <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Sets radius of sphere for restricted droplet potential beyond this sphere. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">12<\/span><\/b> <\/td>\n<td align=\"left\">Radius in Å.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">restricted_droplet_atoms <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Specifies atoms to be affected by the restrictive potential. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=<b><span style=\"color:#00BF28\">all<\/span><\/b> <\/td>\n<td align=\"left\">All atoms are affected.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=noH <\/td>\n<td align=\"left\">H atoms are not affected.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=list <\/td>\n<td align=\"left\">Look up atoms from keyword <tt>restricted_droplet_atoms_list<\/tt>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=file $2=(<b><span style=\"color:#00BF28\">“droplet”<\/span><\/b>)<\/td>\n<td align=\"left\">Infos about which atoms are affected is set in specified file. This file is required to have n<sub><span class=\"roman\">atoms<\/span><\/sub> lines specifying for each atom whether to apply the potential: <tt>T<\/tt> (affected) or <tt>F<\/tt> (not affected).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">restricted_droplet_atoms_list <\/td>\n<td align=\"left\">list of <b>integer<\/b>s <\/td>\n<td align=\"left\">Lists atoms to be <b>not<\/b> affected by the potential. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=at<sub>1<\/sub> at<sub>2<\/sub> …<\/td>\n<td align=\"left\">Atoms with atom index at<sub>1<\/sub>, at<sub>2<\/sub>, … not affected.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">tethering_force <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Force constant for tethering of atom. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1 <\/td>\n<td align=\"left\">Force constant in [(E<sub>h<\/sub>)\/(a<sub>0<\/sub><sup>2<\/sup>)].<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">tethering_radius <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Sets radius inside which tethering potential is zero. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1 <\/td>\n<td align=\"left\">Radius in Å.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">tether_at <\/td>\n<td align=\"left\">(list of) <b>integer<\/b>s <\/td>\n<td align=\"left\">Selects indices for tethering. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=(at<sub>1<\/sub> at<sub>2<\/sub> …) <\/td>\n<td align=\"left\">Atoms with indices at<sub>1<\/sub>, at<sub>2<\/sub>, … are to be tethered.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">tethering_position <\/td>\n<td align=\"left\">list of <b>float<\/b>s <\/td>\n<td align=\"left\">Sets position to which selected atoms are tethered. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1 = x<sub><span class=\"roman\">tether<\/span><\/sub> <\/td>\n<td align=\"left\">x-coordinate of tethering center in Å.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$2 = y<sub><span class=\"roman\">tether<\/span><\/sub> <\/td>\n<td align=\"left\">y-coordinate of tethering center in Å.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$3 = z<sub><span class=\"roman\">tether<\/span><\/sub> <\/td>\n<td align=\"left\">z-coordinate of tethering center in Å.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">Center of mass of tethered atoms<\/span><\/b>.<\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Energy control keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ezero <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Energy shift for Hamiltonian diagonal elements (Hartree).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">0.0<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Is not determined automatically!<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scaling <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Scaling factor for Hamiltonian matrix and gradients.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">1.0<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">0. < $1<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">soc_scaling <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Scaling factor for spin-orbit coupling.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">1.0<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">0. < $1<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dampeddyn <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Scaling factor for kinetic energy at each time step.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">1.0<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">0. ≤ $1 ≤ 1.<\/span><\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Thermostat keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">thermostat <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Activates thermostat.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=<b><span style=\"color:#00BF28\">none<\/span><\/b> <\/td>\n<td align=\"left\">No thermostat is used.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=langevin <\/td>\n<td align=\"left\">Langevin thermostat is used.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">rngseed_thermostat <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Seed for the thermostat random number generator.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=<b><span style=\"color:#00BF28\"><tt>rngseed<\/tt><\/span><\/b> <\/td>\n<td align=\"left\">Same as used for surface hopping. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">norestart_thermostat_random <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Use only when want to restart with seed given in restart file without recovering end of last random number sequence. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">thermostatregions <\/td>\n<td align=\"left\"><b>various<\/b> <\/td>\n<td align=\"left\">Specifies info for thermostatting regions.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=<b><span style=\"color:#00BF28\">one<\/span><\/b> <\/td>\n<td align=\"left\">Same thermostat conditions for whole system (1 region only).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=first $2=n<\/td>\n<td align=\"left\">Thermostat with 2 regions where first n atoms belong to region 1. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=atomlist $2=r<sub>1<\/sub> r<sub>2<\/sub> … <\/td>\n<td align=\"left\">Thermostat where region number (integer starting from 1) is defined here for each atom. (Number of regions is taken as maximum.)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=file $2=”file” <\/td>\n<td align=\"left\">Thermostat settings are taken from the file (default <b><span style=\"color:#00BF28\">“thermostat_setting”<\/span><\/b>), see Section <a href=\"#sec:thermostatfile\">4.10<\/a>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">temperature <\/td>\n<td align=\"left\">list of <b>float<\/b>s <\/td>\n<td align=\"left\">Sets the temperatures in K for each region.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$n=<b><span style=\"color:#00BF28\">293.15<\/span><\/b> <\/td>\n<td align=\"left\">Temperature for region n (provide as many numbers as regions).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">thermostat_const <\/td>\n<td align=\"left\">list of <b>float<\/b>s <\/td>\n<td align=\"left\">Sets additional values required by the thermostat.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$n <\/td>\n<td align=\"left\">Depends on <tt>thermostat<\/tt>. For the Langevin thermostat, provide one friction coefficient in fs<sup>−1<\/sup> per region.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">remove_trans_rot <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Removes the translational and rotational components of the entire system in each time step. <\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Gradient and NAC selection keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">grad_select <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Only some gradients are calculated at every time step.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">grad_all<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">All gradients are calculated at every time step (Alias: <b><tt>nograd_select<\/tt><\/b>).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\"><b><tt>grad_all<\/tt><\/b> takes precedence.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nac_select <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Only some 〈ψ<sub>α<\/sub>|∂\/∂R|ψ<sub>β<\/sub>〉 are calculated at every time step.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">nac_all<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">All 〈ψ<sub>α<\/sub>|∂\/∂R|ψ<sub>β<\/sub>〉 are calculated at every time step (Alias: <b><tt>nonac_select<\/tt><\/b>).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\"><b><tt>nac_all<\/tt><\/b> takes precedence.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">eselect <\/td>\n<td align=\"left\"><b>float<\/b> <\/td>\n<td align=\"left\">Parameter for selection of gradients and NACs (in eV).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">0.5 eV<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">select_directly<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Do not do a second QM calculation for gradients and NACs.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">noselect_directly <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Do a second QM calculation for gradients and NACs.<\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Phase tracking keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">track_phase<\/span><\/b><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Track the phase of the transformation matrix <b>U<\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">notrack_phase <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">No phase tracking of <b>U<\/b> (can provide very large speedups in <b><tt>pysharc<\/tt><\/b>, but check whether results are affected).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">phases_from_interface<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Request phase information from interface.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nophases_from_interface <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Try to recover phase information from QM data.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">phases_at_zero <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Request phase from interface at t=0.<\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Property computation keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">spinorbit<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Include spin-orbit couplings into the Hamiltonian.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nospinorbit <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Neglect spin-orbit couplings.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dipole_gradient <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Include dipole moments derivatives in the gradients.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">nodipole_gradient<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Neglect dipole moments derivatives.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ionization <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Calculate ionization probabilities on-the-fly.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">noionization<\/span><\/b><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">No ionization probabilities.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ionization_step <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Calculate ionization probabilities every $1 time step.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">1<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">By default calculated every time step (if <b><tt>ionization<\/tt><\/b>).<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">theodore <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Calculate wavefunction descriptors on-the-fly.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">notheodore<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">No wavefunction descriptors.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">theodore_step <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Calculate wavefunction descriptors every $1 time step.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">1<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">By default calculated every time step (if <b><tt>theodore<\/tt><\/b>).<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">n_property1d <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Allocate for that many 1D properties.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">1<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\"><\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">n_property2d <\/td>\n<td align=\"left\"><b>integer<\/b> <\/td>\n<td align=\"left\">Allocate for that many 2D properties.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">1<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\"><\/span><\/td>\n<\/tr>\n<tr>\n<td colspan=\"3\" align=\"center\">– Output control keywords –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">write_grad <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Writes gradients to <b><tt>output.dat<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">nowrite_grad<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">write_nacdr <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Writes NACs to <b><tt>output.dat<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">nowrite_nacdr<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><span style=\"color:#00BF28\">write_overlap<\/span><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Writes overlaps to <b><tt>output.dat<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nowrite_overlap <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\">Not written if not requested.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">only_store_overlaps <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">Enables computation and storage of overlaps even when not required by the simulation (e.g., to diabatize populations).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">write_property1d <\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">on if <b><tt>theodore<\/tt><\/b><\/span><\/b> <\/td>\n<td align=\"left\">Writes 1D properties to <b><tt>output.dat<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nowrite_property1d <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">write_property2d <\/td>\n<td align=\"left\"><b><span style=\"color:#00BF28\">on if <b><tt>ionization<\/tt><\/b><\/span><\/b> <\/td>\n<td align=\"left\">Writes 2D properties to <b><tt>output.dat<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nowrite_property2d <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">output_dat_steps <\/td>\n<td align=\"left\"><b>integer<\/b> (1, 3, or 5 numbers) <\/td>\n<td align=\"left\">Determines at which steps <b><tt>sharc.x<\/tt><\/b> writes to <b><tt>output.dat<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1 (<b><span style=\"color:#00BF28\">1<\/span><\/b>) <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Stride for writing to <b><tt>output.dat<\/tt><\/b> (default every step).<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$2 (<b><span style=\"color:#00BF28\">not given<\/span><\/b>) <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Step at which stride is switched to $3.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$3 (<b><span style=\"color:#00BF28\">not given<\/span><\/b>) <\/td>\n<td align=\"left\"><span class=\"footnotesize\">New stride applied if step ≥ $2.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$4 (<b><span style=\"color:#00BF28\">not given<\/span><\/b>) <\/td>\n<td align=\"left\"><span class=\"footnotesize\">Step at which stride is switched to $5.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$5 (<b><span style=\"color:#00BF28\">not given<\/span><\/b>) <\/td>\n<td align=\"left\"><span class=\"footnotesize\">New stride applied if step ≥ $4.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\">Always give 1, 3, or 5 arguments.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">output_dat_steps_nuc <\/td>\n<td align=\"left\"><b>integer<\/b> (1, 3, or 5 numbers) <\/td>\n<td align=\"left\">If <b><tt>output_format netcdf_separate_nuclei<\/tt><\/b>, then this controls the steps at which nuclear data is written.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><span class=\"footnotesize\">Works the same as <b><tt>output_dat_steps<\/tt><\/b>.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">output_format <\/td>\n<td align=\"left\"><b>string<\/b> <\/td>\n<td align=\"left\">Format of <b><tt>output.dat<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=<b><span style=\"color:#00BF28\">ascii<\/span><\/b> <\/td>\n<td align=\"left\"><span class=\"footnotesize\">as documented in Section <a href=\"#sec:datfile\">5.3<\/a>.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=netcdf <\/td>\n<td align=\"left\"><span class=\"footnotesize\">as documented in Section <a href=\"#sec:netcdf\">5.4<\/a>. Also deactivates writing of restart files (except last step) and <b><tt>output.xyz<\/tt><\/b>.<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">$1=netcdf_separate_nuclei <\/td>\n<td align=\"left\"><span class=\"footnotesize\">as <b><tt>netcdf<\/tt><\/b> and as documented in Section <a href=\"#sec:netcdf_nuc\">5.5<\/a>. <\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<\/tr>\n<p><\/span><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.1.3\"><\/a><\/p>\n<h3>\n4.1.3  Detailed Description of the Keywords<\/h3>\n<p><a id=\"ssec:input:keywords\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Printlevel  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>printlevel<\/tt><\/b> keyword controls the verbosity of the log file. The data output file (<b><tt>output.dat<\/tt><\/b>) and the listing file (<b><tt>output.lis<\/tt><\/b>) are not affected by the print level. The print levels are described in section <a href=\"#sec:logfile\">5.1<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Restart  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are two keywords controlling trajectory restarting. The keyword <b><tt>restart<\/tt><\/b> enables restarting, while <b><tt>norestart<\/tt><\/b> disables restart. If both keywords are present, <b><tt>norestart<\/tt><\/b> takes precedence. The default (none of the keywords present) is no restart.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When restarting, all control variables are read from the restart file instead of the input file. The only exceptions are <b><tt>nsteps<\/tt><\/b> and <b><tt>tmax<\/tt><\/b>. In this way, a trajectory which ran for the full simulation time can easily be restarted to extend the simulation time.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that none of the auxiliary scripts adds the <b><tt>restart<\/tt><\/b> keyword to the input file. The user has to manually add the restart file to the input files of the relevant trajectories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, the interfaces employ a new way of tracking their interface-specific restart files.<br \/>\nTherefore, the S<span style=\"font-size:x-small\">HARC<\/span>3 keywords <b><tt>restart_rerun_last_qm_step<\/tt><\/b> and <b><tt>restart_goto_new_qm_step<\/tt><\/b> are not needed anymore and were removed.<br \/>\nThe interfaces can now automatically identify the last successful previous step and restart accordingly.<br \/>\nThus, users do not need to distinguish anymore whether they restart a trajectory after a non-graceful crash\/kill of the simulation (e.g., due to queueing system time limits) or a after the simulation was gracefully stopped (e.g., after reaching <b><tt>tmax<\/tt><\/b>\/<b><tt>nsteps<\/tt><\/b>, after using the <b><tt>STOP<\/tt><\/b> file, or after using the <b><tt>killafter<\/tt><\/b> mechanism).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, the keywords <b><tt>write_restart_files<\/tt><\/b> and <b><tt>nowrite_restart_files<\/tt><\/b> were added.<br \/>\nThe default is to write restart files, unless the NetCDF <b><tt>output_format<\/tt><\/b> is chosen.<br \/>\nWith NetCDF output, restart files are generally not written, except at the last time steps, where <b><tt>write_restart_files<\/tt><\/b> and <b><tt>nowrite_restart_files<\/tt><\/b> take control.<br \/>\nIf both keywords are present, <b><tt>write_restart_files<\/tt><\/b> takes precendence. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Another new keyword in S<span style=\"font-size:x-small\">HARC<\/span>4 is <b><tt>retain_restart_files<\/tt><\/b>.<br \/>\nThis keyword is passed from the driver to the interfaces and controls how many interface-specific restart files the interfaces will keep in storage.<br \/>\nA sensible behavior of ab initio interfaces would be to always retain the files from the previous time step, e.g., for orbital restart.<br \/>\nIf wave function overlaps are used, then the files from the previous time step <em>must<\/em> be retained.<br \/>\nThe <b><tt>retain_restart_files<\/tt><\/b> is mostly intended to store additional restart files, e.g., to archive orbital files for all time steps.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>RNG Seed  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The RNG seed is used to initialize the random number generator, which provides the random numbers for the surface hopping procedure (and the AFSSH decoherence scheme). For details how the seed is used internally, see section <a href=\"#met:seed\">8.26<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that in the case of a restart, the random number generator is seeded normally, and then the appropriate number of random numbers is drawn so that the random number sequence is consistent.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Compatibility Mode  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>With this keyword, one can activate a compatibility mode that allows reproducing results of older versions of S<span style=\"font-size:x-small\">HARC<\/span>.<br \/>\nA value of 0 disables compatibility mode.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Currently, the only other option is a value of 1.<br \/>\nIn this mode, <b><tt>sharc.x<\/tt><\/b> draws only one random number for each step, like it was the case in S<span style=\"font-size:x-small\">HARC<\/span> 1.0 (from S<span style=\"font-size:x-small\">HARC<\/span> 2.0, it draws two random numbers per step, one for hopping and one for decoherence schemes).<br \/>\nThis compatibility mode cannot be combined with the A-FSSH decoherence correction.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Geometry Input  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The initial geometry must be given in a second file in the <a href=\"http:\/\/www.univie.ac.at\/columbus\/docs_COL70\/documentation_main.html\">input format also used by C<span style=\"font-size:x-small\">OLUMBUS<\/span><\/a>. The default name for this file is <b><tt>geom<\/tt><\/b>. The geometry filename can be given in the input file with the <b><tt>geomfile<\/tt><\/b> keyword. Note that the filename has to be enclosed in single or double quotes. See section <a href=\"#sec:geomfile\">4.2<\/a> for more details.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Velocity Input  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using the <b><tt>veloc<\/tt><\/b> keyword, the initial velocities can be either set to zero, determined randomly or read from a file. Random determination of the velocities is such that each atom has the same kinetic energy, which must be specified after <b><tt>veloc random<\/tt><\/b> in units of eV. Determination of the random velocities is detailed in <a href=\"#met:veloc\">8.22<\/a>. Note that after the initial velocities are generated, the RNG is reseeded (i.e., the sequence of random numbers in the surface hopping procedure is independent of whether random initial velocities are used).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, the initial velocities can be read from a file.<br \/>\nThe default velocity filename is <b><tt>veloc<\/tt><\/b>, but the filename can be specified with the <b><tt>velocfile<\/tt><\/b> keyword. Note that the filename has to be enclosed in single or double quotes. The file must contain the Cartesian components of the velocity for each atom on a new line, in the same order as in the geomety file. The velocity is interpreted in terms of atomic units (bohr\/atu). See section <a href=\"#sec:velocfile\">4.3<\/a> for more details.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of States and Active States  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>nstates<\/tt><\/b> controls how many states are taken into account in the dynamics. The keyword arguments specify the number of singlet, doublet, triplet, etc. states. There is no hard-coded maximum multiplicity in the S<span style=\"font-size:x-small\">HARC<\/span> code, however, some interfaces may restrict the maximum multiplicity. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using the <b><tt>actstates<\/tt><\/b> keyword, the dynamics can be restricted to some lowest states in each multiplicity. For each multiplicity, the number of active states must not be larger than the number of states. All couplings between the active states and the frozen states are deleted. These couplings include off-diagonal elements in the H<sup>MCH<\/sup> matrix, in the overlap matrix, and in the matrix containing the nonadiabatic couplings. Freezing states can be useful if transient absorption spectra are to be calculated without increasing computational cost due to the large number of states.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the initial state must not be frozen.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Charges of States  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, the charge of the different electronic states has been promoted from an interface-private, optional parameter to a compulsory parameter that the driver is aware of.<br \/>\nThis is primarily to prepare for multi-fragment calculations including charge transfer.<br \/>\nThis change makes it necessary to specify the charge for each multiplicity in the S<span style=\"font-size:x-small\">HARC<\/span> input file.<br \/>\nNote that all states of a given multiplicity are required to have the same charge.<br \/>\nDifferent multiplicities can and will have different charges.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Initial State  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The initial state can be given either in MCH or diagonal representation. The keyword <b><tt>state<\/tt><\/b> is followed by an integer specifying the initial state and either the string <b><tt>mch<\/tt><\/b> or <b><tt>diag<\/tt><\/b>. For the MCH representations, states are enumerated according to the canonical state ordering, see <a href=\"#met:ordering\">8.28<\/a>. The diagonal states are ordered according to energy. Note that the initial state must be active. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the initial state is given in the MCH basis but the dynamics is carried out in the diagonal basis, determination of the initial diagonal state is carried out after the initial QM calculation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Initial Coefficients  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The initial coefficients can be determined automatically from the initial state, using <b><tt>coeff auto<\/tt><\/b> in the input file. If the initial state is given in the diagonal representation as i, the initial coefficients are c<sup>diag<\/sup><sub>j<\/sub>=δ<sub>ij<\/sub>. If the initial state is, however, given in the MCH representation, then c<sup>MCH<\/sup><sub>j<\/sub>=δ<sub>ij<\/sub> and the determination of <b>c<\/b><sup>diag<\/sup>=<b>U<\/b><sup>†<\/sup><b>c<\/b><sup>MCH<\/sup> is carried out after the initial QM calculation.<br \/>\nCurrently, <b><tt>coeff auto<\/tt><\/b> is always used by the automatic setup scripts.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Besides automatic determination, the initial coefficients can be read from a file. The default filename is <b><tt>coeff<\/tt><\/b>, but the filename can be given with the keyword <b><tt>coefffile<\/tt><\/b>. Note that the filename has to be enclosed in single or double quotes. The file must contain the real and imaginary part of the initial coefficients, one line per state with no blank lines inbetween. These coefficients are interpreted to be in the same representation as the initial state, i.e. the <b><tt>state<\/tt><\/b> keyword influences the initial coefficients. For details on the file format, see section <a href=\"#sec:coefffile\">4.4<\/a>.<br \/>\nNote that the setup scripts currently cannot setup trajectories with <b><tt>coeff external<\/tt><\/b>, so this can be considered an expert option.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Laser Input  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>laser<\/tt><\/b> controls whether a laser field is included in the dynamics (influencing the coefficient propagation and the energies\/gradients by means of the Stark effect). <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The input of an external laser field uses the file <b><tt>laser<\/tt><\/b>. This file is specified in <a href=\"#sec:laserfile\">4.5<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to detect laser-induced hops, S<span style=\"font-size:x-small\">HARC<\/span> compares the instantaneous central laser energy with the energy gap between the old and new states. If the difference between the laser energy and the energy gap is smaller than the laser bandwidth (given with the <b><tt>laserwidth<\/tt><\/b> keyword), the hop is classified as laser-induced. Those hops are never frustrated and the kinetic energy is not scaled to preserve total energy (instead, the kinetic energy is preserved).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Simulation Time step  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>stepsize<\/tt><\/b> controls the length of a time step (in fs) for the dynamics. The nuclear motion is integrated using the Velocity-Verlet algorithm with this time step. Surface hopping is performed once per time step and 1-3 quantum chemistry calculations are performed per time step (depending on the selection schedule). Each time step is divided in <b><tt>nsubsteps<\/tt><\/b> substeps for the integration of the electronic equation-of-motion. Since integration is performed in the MCH representation, the default of 25 substeps is usually sufficient, even if very small potential couplings are encountered. A larger number of substeps might be necessary if high-frequency laser fields are included or if the energy shift (<b><tt>ezero<\/tt><\/b>) is not well-chosen.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Simulation Time  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>nsteps<\/tt><\/b> controls the total length of the simulation. The total simulation time is <b><tt>nsteps<\/tt><\/b> times <b><tt>stepsize<\/tt><\/b>. <b><tt>nsteps<\/tt><\/b> does not include the initial quantum chemistry calculation. Instead of the number of steps, the total simulation time can be given directly (in fs) using the keyword <b><tt>tmax<\/tt><\/b>. In this case, <b><tt>nsteps<\/tt><\/b> is calculated as <b><tt>tmax<\/tt><\/b> divided by <b><tt>stepsize<\/tt><\/b>. If both keywords (<b><tt>nsteps<\/tt><\/b> and <b><tt>tmax<\/tt><\/b>) are present, <b><tt>nsteps<\/tt><\/b> is used. All setup scripts will generally use the <b><tt>tmax<\/tt><\/b> keyword.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using the keyword <b><tt>killafter<\/tt><\/b>, the dynamics can be terminated before the full simulation time. <b><tt>killafter<\/tt><\/b> specifies (in fs) the time the trajectory can move in the lowest-energy state before the simulation is terminated. By default, simulations always run to the full simulation time and are not terminated prematurely.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Integrator for Nuclear Equation of Motion  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>integrator<\/tt><\/b> controls the integrator for nuclear equation of motion used in S<span style=\"font-size:x-small\">HARC<\/span>. There are two options, <b><tt>integrator fvv<\/tt><\/b> uses the fixed time step velocity Verlet algorithm, which is the default. The time step in fixed time step velocity Verlet is set by keyword <b><tt>stepsize<\/tt><\/b>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, one can use <b><tt>integrator avv<\/tt><\/b>, which turns on the adaptive time step velocity Verlet algorithm. The initial time step in adaptive velocity Verlet algorithm is set by keyword <b><tt>stepsize<\/tt><\/b>. In adaptive velocity Verlet, the algorithm will check the total energy conservation of the trajectory at successive time steps. If the energy difference is above the threshold, the timestep will be reduced to half, and if the energy difference is less than one fifth of the threshold, the timestep will be doubled. The threshold can be set by keyword <b><tt>convthre<\/tt><\/b>, the default is 1e-04 eV. One can also set up the minimum and maximum allowed stepsize in adaptive velocity Verlet. This is achieved by keyword <b><tt>stepsize_min<\/tt><\/b> and <b><tt>stepsize_max<\/tt><\/b>. The default values for <b><tt>stepsize_min<\/tt><\/b> and <b><tt>stepsize_max<\/tt><\/b> are stepsize\/16 and stepsize*2 respectively. Alternatively, one can set up the minimum or maximum stepsize in an exponential form to base 2. This is done by calling keywords <b><tt>stepsize_min_exp<\/tt><\/b> and <b><tt>stepsize_max_exp<\/tt><\/b>. The default values for these two keywords are -4 and 1, respectively. For example, when setting <b><tt>stepszie_min_exp -4<\/tt><\/b>, the minimum stepsize is stepsize\/(2<sup>−4<\/sup>). Setting up keywords <b><tt>stepsize_min_exp<\/tt><\/b> and <b><tt>stepsize_max_exp<\/tt><\/b> will overwrite keywords <b><tt>stepsize_min<\/tt><\/b> and <b><tt>stepsize_max<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the adaptive time step is used, the output files will contain data at the computed times, which might not be a regular grid of time steps. This can lead to a swarm of trajectories that do not have data at the same time steps. To enable ensemble analysis, in this case <b><tt>data_extractor.x<\/tt><\/b> will automatically perform linear interpolation of the results. It will write all output files twice, once with the original time steps (file names contain <b><tt>original<\/tt><\/b>) and once interpolated to multiples of the original <b><tt>stepsize<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that for the S<span style=\"font-size:x-small\">HARC<\/span>4.0 release, adaptive time steps are not available when the compilation was done with <b><tt>pysharc<\/tt><\/b> support.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Dynamics Method  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Starting from S<span style=\"font-size:x-small\">HARC<\/span>3.0, one is able to perform two categories of nonadiabatic dynamics algorithms, namely trajectory surface hopping, and self-consistent potential methods. The dynamics employed can be set up by keyword <b><tt>method<\/tt><\/b>. Using keyword <b><tt>method tsh<\/tt><\/b> enables trajectory surface hopping, and <b><tt>method scp<\/tt><\/b> enables self-consistent potential methods.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that for the S<span style=\"font-size:x-small\">HARC<\/span>3.0 release, self-consistent potential methods are not available when the compilation was done with <b><tt>pysharc<\/tt><\/b> support.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Description of Non-adiabatic Coupling  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The code allows propagating the electronic wave function using four different quantities describing nonadiabatic effects, see <a href=\"#met:propagate\">8.33<\/a>. The keyword <b><tt>coupling<\/tt><\/b> controls which of these quantities is requested from the QM interfaces and used in the propagation. The first option is <b><tt>nacdr<\/tt><\/b>, which requires the nonadiabatic coupling vectors 〈ψ<sub>α<\/sub>|∂\/∂<b>R<\/b>|ψ<sub>β<\/sub>〉. For the wave function propagation, the scalar product of these vectors and the nuclear velocity is calculated to obtain the matrix 〈ψ<sub>α<\/sub>|∂\/∂t|ψ<sub>β<\/sub>〉. During the propagation, this matrix is interpolated linearly within each classical time step. Currently, only few S<span style=\"font-size:x-small\">HARC<\/span> interfaces can provide these couplings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, one can directly request the matrix elements 〈ψ<sub>α<\/sub>|∂\/∂t|ψ<sub>β<\/sub>〉, which can be used for the propagation. The corresponding argument to <b><tt>coupling<\/tt><\/b> is <b><tt>nacdt<\/tt><\/b>. In this case, the matrix is taken as constant throughout each classical time step. Currently, none of the interfaces in S<span style=\"font-size:x-small\">HARC<\/span> can deliver these couplings, because they are computed via overlaps, and if overlaps are known it is preferable to use local diabatization.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The third possibility is the use of the overlap matrix, requested with <b><tt>coupling overlaps<\/tt><\/b> (this is the default). The overlap matrix is used subsequently in the local diabatization algorithm for the wave function propagation. Currently, all S<span style=\"font-size:x-small\">HARC<\/span> interfaces can provide these couplings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The fourth possibility is to use the curvature driven method to approximate time derivative couplings (<b><tt>coupling ktdc<\/tt><\/b>). In curvature driven methods, the time derivative coupling is completely approximated by knowing the curvatures of the potential energy surfaces. And therefore, can be interfaced with electronic structure theories for which the nonadiabatic coupling vector is not available, or the wave function is not defined – and therefore one can not compute overlap integrals from electronic structure theory. Therefore, curvature driven methods can be interfaced with any electronic structure theory that provides energies and gradients. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Method to Compute Curvature Approximated Time Derivative Coupling  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If one uses <b><tt>coupling ktdc<\/tt><\/b>, there are two possible ways to compute time derivative coupling (TDC). One can compute the curvature of potential energy surface with respect to time from either the second order finite difference of energy along time by calling <b><tt>ktdc_method energy<\/tt><\/b>; or from the first order finite difference of the dot product of gradients and velocity vector <b><tt>ktdc_method gradient<\/tt><\/b>, see <a href=\"#met:curvature\">8.34<\/a>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Electronic Equation of Motion Propagator  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>One can control the electronic propagator by calling keyword <b><tt>eeom<\/tt><\/b>, see <a href=\"#met:propagate\">8.33<\/a>. There are four options, <b><tt>eeom ci<\/tt><\/b> does not interpolate the time derivative coupling during the substep propagation. <b><tt>eeom li<\/tt><\/b> linearly interpolates the time derivative coupling during the substep propagation. <b><tt>eeom ld<\/tt><\/b> uses the local diabatization. <b><tt>eeom npi<\/tt><\/b> uses a norm preserving interpolation propagator.<a href=\"#Meek2014JPCL\" class=\"tth_citeref\">[93<\/a>,<a href=\"#ShutCSDM2020JCTC\" class=\"tth_citeref\">[75<\/a>] We suggest the users use the default propagator, which depends on the used coupling quantity.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Correction to the Diagonal Gradients  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>As detailed in <a href=\"#met:gradtra\">8.11<\/a>, transformation of the diagonal representation requires contributions from the nonadiabatic coupling vectors or time derivative couplings. The two correction schemes are called nuclear-gradient-tensor scheme and time-derivative-matrix scheme. The nuclear-gradient-tensor scheme corrects the gradients with nonadiabatic coupling vectors. In this case S<span style=\"font-size:x-small\">HARC<\/span> will request the calculation of the nonadiabatic coupling vectors, even if they are not used in the wave function propagation. The time-derivative-matrix scheme corrects the gradients with the time derivative couplings. Using <b><tt>gradcorrect<\/tt><\/b>, <b><tt>gradcorrect ngt<\/tt><\/b>, or <b><tt>gradcorrect nac<\/tt><\/b> enables nuclear-gradient-tensor scheme; using <b><tt>gradcorrect tdm<\/tt><\/b> enables time-derivative-matrix scheme. In order to explicitly turn off this gradient correction, use the <b><tt>nogradcorrect<\/tt><\/b> keyword.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Method to Compute Time-Derivative-Matrix Scheme  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This approach only applies when one uses <b><tt>gradcorrect tdm<\/tt><\/b>. There are two ways to compute time derivatives of potential energies in the diagonal basis in the TDM scheme. One can compute the time derivative of potential energies in the diagonal basis from transformation of the time derivative matrix in the MCH basis. This computation is enabled by using <b><tt>tmd_method gradient<\/tt><\/b>. In this approach, the time derivative of potential energies in the MCH basis are computed from the dot product between the nuclear gradient vector and the velocity vector. This is the default option for <b><tt>coupling ddr<\/tt><\/b> or <b><tt>coupling overlap<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, one can compute the time derivative of potential energies in the diagonal basis from finite differences. This approach is more accurate for curvature driven methods because in curvature-driven algorithms we do not have ab initio time derivative couplings. This is the default option for <b><tt>coupling ktdc<\/tt><\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Decoherence Correction Scheme  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are four options for the decoherence correction (see <a href=\"#met:decoherence\">8.7<\/a>) in S<span style=\"font-size:x-small\">HARC<\/span>, which can be selected with the <b><tt>decoherence_scheme<\/tt><\/b> keyword. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>With the default <b><tt>decoherence_scheme none<\/tt><\/b>, no decoherence correction is applied.<br \/>\nThe energy-difference based decoherence (EDC) scheme of Granucci et al. <a href=\"#Granucci2010JCP\" class=\"tth_citeref\">[94<\/a>] can be activated with <b><tt>decoherence_scheme edc<\/tt><\/b>.<br \/>\nThe keyword <b><tt>decoherence_param<\/tt><\/b> can be used to change the relevant parameter α (see <a href=\"#met:decoherence\">8.7<\/a>). The default is 0.1 Hartree, which is the value recommended by Granucci et al. <a href=\"#Granucci2010JCP\" class=\"tth_citeref\">[94<\/a>]. Notice EDC scheme only applies to TSH methods.<br \/>\nAlternatively, the AFSSH (augmented fewest-switches surface hopping) scheme of Jain et al. <a href=\"#Jain2016JCTC\" class=\"tth_citeref\">[39<\/a>] can be employed, using <b><tt>decoherence_scheme afssh<\/tt><\/b>. This scheme does not use any parameters, so the keyword <b><tt>decoherence_param<\/tt><\/b> will have no effect.<br \/>\nNote that in any case, the decoherence correction is applied to the states in the representation chosen with the <b><tt>surf<\/tt><\/b> keyword.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For self-consistent potential methods, the decay of mixing decoherence scheme of Truhlar et al.<a href=\"#ZhuSCDM2004JCP\" class=\"tth_citeref\">[40<\/a>,<a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>,<a href=\"#ShuCSDM2020JCTC\" class=\"tth_citeref\">[31<\/a>] can be activated with <b><tt>decoherence_scheme dom<\/tt><\/b>. In combination with <b><tt>method scp<\/tt><\/b>, it enables either CSDM or SCDM methods. The decoherence time in CSDM or SCDM uses energy based decoherence time. The keywords <b><tt>decoherence_param_alpha<\/tt><\/b> and <b><tt>decoherence_param_beta<\/tt><\/b> can be used to change the relevant parameters α and β (see <a href=\"#met:decoherence\">8.7<\/a>). The default is 0.1 Hartree for α and 1 for β. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that for the S<span style=\"font-size:x-small\">HARC<\/span>3.0 release, self-consistent potential methods and decay of mixing decoherence are not available when the compilation was done with <b><tt>pysharc<\/tt><\/b> support.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keywords <b><tt>decoherence<\/tt><\/b> (activates EDC decoherence) and <b><tt>nodecoherence<\/tt><\/b> are present for backwards compatibility.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Surface Treatment  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>surf<\/tt><\/b> controls whether the dynamics runs on diagonal potential energy surfaces (which makes it a S<span style=\"font-size:x-small\">HARC<\/span> simulation) or on the MCH PESs (which corresponds to a spin-diabatic <a href=\"#Granucci2012JCP\" class=\"tth_citeref\">[26<\/a>] or FISH <a href=\"#Mitric2009PRA\" class=\"tth_citeref\">[25<\/a>] simulation, or a regular surface hopping simulation). Internally, dynamics on the MCH potentials is conducted by setting the U matrix equal to the unity matrix at each time step. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Adjustment of the Kinetic Energy  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>ekincorrect<\/tt><\/b> controls how the kinetic energy is adjusted after a surface hop to preserve total energy. <b><tt>ekincorrect none<\/tt><\/b> deactivates the adjustment, so that the total energy is not preserved after a hop. Using this option, jumps can never be frustrated and are always performed according to the hopping probabilities. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>ekincorrect parallel_vel<\/tt><\/b>, the kinetic energy is adjusted by simply rescaling the nuclear velocities so that the new kinetic energy is E<sub>tot<\/sub>−E<sub>pot<\/sub>. Jumps are frustrated if the new potential energy would exceed the total energy.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>ekincorrect parallel_nac<\/tt><\/b>, the kinetic energy is adjusted by rescaling the component of the nuclear velocities parallel to the nonadiabatic coupling vector between the old and new state. The hop is frustrated if there is not enough kinetic energy in this direction to conserve total energy. Note that <b><tt>ekincorrect parallel_nac<\/tt><\/b> implies the calculation of the nonadiabatic coupling vector, even if they are not used for the wave function propagation.<br \/>\nNote that using the nonadiabatic coupling vector causes non-conservation of nuclear orbital angular momentum, and center of mass motion. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>ekincorrect parallel_diff<\/tt><\/b>, the kinetic energy is adjusted by rescaling the component of the nuclear velocities parallel to the difference gradient vector between the old and new state. The hop is frustrated if there is not enough kinetic energy in this direction to conserve total energy. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>ekincorrect parallel_pnac<\/tt><\/b>, the kinetic energy is adjusted by rescaling the component of the nuclear velocities parallel to the projected nonadiabatic coupling vector between the old and new state. The hop is frustrated if there is not enough kinetic energy in this direction to conserve total energy. Projected nonadiabatic coupling vector ensures conservation of nuclear orbital angular momentum and center of mass motion. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>ekincorrect parallel_enac<\/tt><\/b>, the kinetic energy is adjusted by rescaling the component of the nuclear velocities parallel to the effective nonadiabatic coupling vector between the old and new state. The hop is frustrated if there is not enough kinetic energy in this direction to conserve total energy. Notice that effective nonadiabatic coupling vector also destroys the conservation of nuclear orbital angular momentum and center of mass motion. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>ekincorrect parallel_penac<\/tt><\/b>, the kinetic energy is adjusted by rescaling the component of the nuclear velocities parallel to the projected effective nonadiabatic coupling vector between the old and new state. The hop is frustrated if there is not enough kinetic energy in this direction to conserve total energy. Using the projection conserves angular momentum and center of mass motion.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Frustrated Hops  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>reflect_frustrated<\/tt><\/b> furthermore controls whether the velocities are inverted after a frustrated hop.<br \/>\nWith <b><tt>reflect_frustrated none<\/tt><\/b> (the default), after a frustrated hop, the velocity vector is not modified.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>reflect_frustrated parallel_vel<\/tt><\/b>, the full velocity vector is inverted when a frustrated hop is encountered.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>With the third option, <b><tt>reflect_frustrated parallel_nac<\/tt><\/b>, only the velocity component parallel to the nonadiabatic coupling vector between the active and frustrated states is inverted. This implies the calculation of the nonadiabatic coupling vector, even if they are not used for the wave function propagation. Note that reflect the velocity along the direction of nonadiabatic coupling vector will cause non-conservation of nuclear orbital angular momentum and center of mass motion.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>With <b><tt>reflect_frustrated parallel_diff<\/tt><\/b>, only the velocity component parallel to the gradient difference vector between the active and frustrated states is inverted. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>With <b><tt>reflect_frustrated parallel_pnac<\/tt><\/b>, only the velocity component parallel to the projected nonadiabatic coupling vector between the active and frustrated states is inverted. Using projection operator conserves nuclear orbital angular momentum and center of mass motion. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>With <b><tt>reflect_frustrated parallel_enac<\/tt><\/b>, only the velocity component parallel to the effective nonadiabatic coupling vector between the active and frustrated states is inverted.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>With <b><tt>reflect_frustrated parallel_penac<\/tt><\/b>, only the velocity component parallel to the projected effective nonadiabatic coupling vector between the active and frustrated states is inverted. Using projected effective nonadiabatic coupling vector ensures conservation of angular momentum. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, one can employ the ∇V criteria by Jasper and Truhlar.<a href=\"#Jasper2003CPL\" class=\"tth_citeref\">[95<\/a>] This is enabled by calling respectively <b><tt>reflect_frustrated delV_vel<\/tt><\/b>, <b><tt>reflect_frustrated delV_pvel<\/tt><\/b>, <b><tt>reflect_frusrated delV_nac<\/tt><\/b>, <b><tt>reflect_frustrated delV_diff<\/tt><\/b>, <b><tt>reflect_frustrated delV_pnac<\/tt><\/b>, <b><tt>reflect_frustrated delV_enac<\/tt><\/b>, and <b><tt>reflect_frustrated delV_penac<\/tt><\/b> for velocity component parallel to velocity vector, projected velocity vector, nonadiabatic coupling vector, gradient difference, projected nonadiabatic coupling vector, efffective nonadiabatic coupling vector, and projected effective nonadiabatic coupling vector.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Surface Hopping Scheme  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are three options for the computation of the hopping probabilities (see <a href=\"#met:hopping\">8.29<\/a>) in S<span style=\"font-size:x-small\">HARC<\/span>, which can be selected with the <b><tt>hopping_procedure<\/tt><\/b> keyword. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>hopping_procedure off<\/tt><\/b>, surface hopping will be disabled, such that the active state (in the representation chosen with the <b><tt>surf<\/tt><\/b> keyword) will never change.<br \/>\nWith the default, <b><tt>hopping_procedure sharc<\/tt><\/b>, the standard hopping probability equation from Ref. <a href=\"#Mai2015IJQC\" class=\"tth_citeref\">[50<\/a>] will be used.<br \/>\nAlternatively, one can use the global flux surface hopping scheme <a href=\"#Wang2014JCTC\" class=\"tth_citeref\">[51<\/a>], which might be advantageous in super-exchange situations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>One can also turn off surface hopping with the <b><tt>no_hops<\/tt><\/b> keyword.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Forced Hops to Ground State  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>With this option, one can force S<span style=\"font-size:x-small\">HARC<\/span> to hop from the active to the lowest state if the energy gap between these two states falls below a certain threshold.<br \/>\nThe threshold is given as argument to the <b><tt>force_hop_to_gs<\/tt><\/b> keyword (in eV).<br \/>\nThis option is useful for single-reference methods that fail to converge if the ground state-excited state energy gap becomes too small.<br \/>\nc<br \/>\nNote that this option forces hops from any higher-lying state to the lowest, independent whether there are other states between the active and the lowest state.<br \/>\nAlso note that once in the lowest state, hopping is completely forbidden if this option is active.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Surface hopping with time uncertainty  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The time uncertainty algorithm is the same as the Tully’s fewest switches algorithm except when a frustrated hop is encountered.<a href=\"#Zhao2023JCTC\" class=\"tth_citeref\">[79<\/a>,<a href=\"#Jasper2002JCP\" class=\"tth_citeref\">[78<\/a>] When a frustrated hop is encountered, the trajectory surface hopping with fewest switches and time uncertainty (TSH-FSTU) method effectively looks for nearby regions where a hop can be successful. Then, if a such a region is found, the TSH-FSTU method allows a nonlocal hop. One can interpret this as the FSTU algorithm borrowing some energy along the timeline of the trajectory according to time-energy uncertainty principle. The FSTU algorithm can greatly reduce the number of frustrated hops. The time uncertainty option can be turn on by using keyword <b><tt>time_uncertainty<\/tt><\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that for the S<span style=\"font-size:x-small\">HARC<\/span>3.0 release, surface hopping with time uncertainty is not available when the compilation was done with <b><tt>pysharc<\/tt><\/b> support.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Atom Masking  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Some of the above surface hopping settings might not be fully size consistent: (i) in <b><tt>ekincorrect parallel_vel<\/tt><\/b>, all atoms are uniformly accelerated\/slowed during velocity rescaling; (ii) in <b><tt>reflect_frustrated parallel_vel<\/tt><\/b>, the velocities of all atoms are inverted; (iii) with <b><tt>decoherence_scheme edc<\/tt><\/b>, the kinetic energy of all atoms determines the decoherence rate. In large systems (e.g., in solution), these effects might be unrealistic, because, e.g., a surface hop in the chromophore should not uniformly slow down all water molecules.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>atommask<\/tt><\/b> keyword can then be used to exclude certain atoms from the three mentioned procedures. With <b><tt>atommask external<\/tt><\/b>, the list of masked and active atoms is read from the file specified with the <b><tt>atommaskfile<\/tt><\/b> keyword (default <b><tt>ätommask\"<\/tt><\/b>). The format of this file is described in section <a href=\"#sec:atommaskfile\">4.6<\/a>. With the other possible option, <b><tt>atommask none<\/tt><\/b> (the default), all atoms are considered for these procedures.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the <b><tt>atommask<\/tt><\/b> keyword has no effect on <b><tt>ekincorrect parallel_nac<\/tt><\/b>, <b><tt>reflect_frustrated parallel_nac<\/tt><\/b>, and <b><tt>decoherence_scheme afssh<\/tt><\/b>, because these procedures are size consistent by themselves.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Nonadiabatic Force Direction in SCP Methods  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In generalized self-consistent potential method, the nuclear equation of motion involves two terms, the adiabatic force and nonadiabatic force, see <a href=\"#met:scpmethod\">8.30<\/a>. The keyword <b><tt>neom<\/tt><\/b> controls the direction of the nonadiabatic force. There are two options, <b><tt>neom ddr<\/tt><\/b> or <b><tt>neom nacdr<\/tt><\/b> uses the nonadiabatic coupling vector as the direction for nonadiabatic force. This reduces the generalized semiclassical Ehrenfest to original semiclassical Ehrenfest. Alternatively, one can use <b><tt>neom gdiff<\/tt><\/b> where the direction of nonadiabatic force is set to be effective nonadiabatic coupling vector, see <a href=\"#met:effectivenac\">8.31<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Representation for nuclear equation of motion in SCP methods  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>One can actually show that for SCP methods, nuclear equation of motion should be invariant with respect to the choice of representation. However, when decoherence is included, such invariance may not be rigorously true anymore. Therefore, one can use either diagonal or MCH representation to propagate nuclear equation of motion. This can be achieved by keyword <b><tt>neom_rep<\/tt><\/b>. Currently, we suggest users to use diagonal representation by using <b><tt>neom_rep diag<\/tt><\/b>, which is also the default. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Pointer Basis  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>pointer_basis<\/tt><\/b> controls the representation of the pointer state in the decay of mixing algorithm (self-consistent potential method),<a href=\"#Shu2023JCTC\" id=\"CITEShu2023JCTC\" class=\"tth_citation\">[98<\/a>] i.e., whether decoherence converges towards a state in the diagonal basis or MCH basis. It is recommended to use the diagonal representation by setting <b><tt>pointer_basis diag<\/tt><\/b>, and this is the default option. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Surface Switching Procedure  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Keyword <b><tt>switching_procedure<\/tt><\/b> only applies to self-consistent potential methods. This keyword controls how pointer state is switched in decay of mixing algorithms. <b><tt>switching_procedure csdm<\/tt><\/b> turns on coherent switching with decay of mixing (CSDM). In CSDM switching procedure, one propagates two populations, namely true electronic population which involves decay of mixing, and coherent electronic population which only propagates coherently. The coherent population will be synchronized to the true electronic population for every complete passage of a strong interaction region. This procedure has been shown to be the most accurate way to compute pointer state switching probability.<a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>,<a href=\"#Zhu2005JCTC\" id=\"CITEZhu2005JCTC\" class=\"tth_citation\">[99<\/a>]<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, one can use an older version of decay of mixing algorithm called self-consistent decay of mixing (SCDM), which can be enabled by using <b><tt>switching_procedure scdm<\/tt><\/b>. Similarly as in CSDM, one propagates both true electronic population and coherent electronic population. The difference between CSDM and SCDM is that in SCDM one does not synchronize the coherent electronic population to true population. This has been shown to be accurate in many cases but not as accurate as CSDM.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>NAC projection  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>When using NACs computed from electronic structure software in nuclear equation of motion of the SCP method, it does not preserve conservation of angular momentum and center of mass motion. The projection operator option (<b><tt>nac_projection<\/tt><\/b>) removes translational and rotational components in a vector. Therefore, it is suggested that one should always use projected NACs or projected effective NACs in nuclear EOM.<a href=\"#Shu2020JPCL\" class=\"tth_citeref\">[76<\/a>] <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keywords <b><tt>nac_projection<\/tt><\/b> and <b><tt>nonac_projection<\/tt><\/b> are used to control if the projection should be used for terms involve NACs in SCP methods. If <b><tt>nac_projection<\/tt><\/b> is used, then the nonadiabatic force direction in SCP methods set by keyword <b><tt>neom<\/tt><\/b> will be projected. Therefore, using <b><tt>nac_projection<\/tt><\/b> is always suggested and is set to default.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For trajectory surface hopping, the only place that may exist a term associated with NACs are in momendum adjustment after a hop or momentum reversal after a frustrated hop. Using projected velocity vector, projected NACs or projected effective NACs can be set up using the keywords <b><tt>ekincorrect<\/tt><\/b> and <b><tt>reflect_frustrated<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Decoherence time parameters for Decay of Mixing algorithms  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The decoherence time for decay of mixing algorithms can be selected with <b><tt>decotime_method<\/tt><\/b>. Similarly as in EDC, decay of mixing uses an energy-based decoherence time.<a href=\"#ZhuSCDM2004JCP\" class=\"tth_citeref\">[40<\/a>,<a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>] Selecting <b><tt>decotime_method edc<\/tt><\/b> two parameters in energy-based decoherence time can be changed, see <a href=\"#met:decoherence\">8.7<\/a>. The two parameters can be set by keywords <b><tt>decoherence_param_alpha<\/tt><\/b> and <b><tt>decoherence_param_beta<\/tt><\/b>. Default values for these two parameters are 0.1 Hartree and 1.0. These are also the suggested values in the original publicaton.<a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>] Alternatively one can use <b><tt>decotime_method scdm<\/tt><\/b> or <b><tt>decotime_method scdm<\/tt><\/b> to select decoherence time as defined in scdm and csdm methods (see <a href=\"#met:scpmethod\">8.30<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Bond length constraints with RATTLE  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>One can use the RATTLE algorithm to constrain the length of some bonds (or generally, interatomic distances) to some fixed value.<br \/>\nThe <b><tt>rattle<\/tt><\/b> keyword can be used to activate this option.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Activating <b><tt>rattle<\/tt><\/b> requires providing a file with the list of atom pairs whose distance should be fixed.<br \/>\nThe format for this file is described in section <a href=\"#sec:rattlefile\">4.7<\/a>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>One can also use the <b><tt>rattletolerance<\/tt><\/b> keyword to modify the convergence criterion of the RATTLE linear equation solver.<br \/>\nHowever, for most purposes, the default should be acceptable.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Freezing atoms  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using the <b><tt>freeze<\/tt><\/b> keyword, one can constrain a set of atoms to their initial Cartesian positions.<br \/>\nThis is implemented by skipping these atoms in the velocity Verlet and thermostat routines, however, from a physical standpoint this is equivalent to giving them infinite masses and zero initial velocities.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>freeze<\/tt><\/b> keyword can be used in different ways.<br \/>\nIf the first argument is <b><tt>none<\/tt><\/b>, no atoms are frozen and dynamics is occurring normally.<br \/>\nThis is the default.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the first argument is <b><tt>last<\/tt><\/b>, then S<span style=\"font-size:x-small\">HARC<\/span> expects a second argument, which is an integer specifying the number of atoms that should be frozen.<br \/>\nThus, <b><tt>freeze last 10<\/tt><\/b> will freeze the ten last atoms in the system.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the first argument is <b><tt>atoms<\/tt><\/b>, then S<span style=\"font-size:x-small\">HARC<\/span> will read a arbitrary number of atom indices (counting starts at 1) from the same line.<br \/>\nFor example, <b><tt>freeze atoms 1 4 7<\/tt><\/b> will freeze the atoms with indices 1, 4, and 7.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the first argument is <b><tt>file<\/tt><\/b>, then S<span style=\"font-size:x-small\">HARC<\/span> will read the frozen atoms from the file <b><tt>frozen<\/tt><\/b> (Section <a href=\"#sec:frozenfile\">4.8<\/a>).<br \/>\nOptionally, a second argument can be given to specify the file name (e.g., <b><tt>freeze file \"frozen_atoms\"<\/tt><\/b>).<br \/>\nNote that the filename must be given in quotes.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Droplet restraining potential and tethering potential  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The droplet potential and tethering potentials are intended for large QM\/MM simulations of a central solute molecule surrounded by a large sphere of solvent molecules (the droplet).<br \/>\nThe droplet potential’s task is to keep the droplet from evaporating, because in S<span style=\"font-size:x-small\">HARC<\/span> one currently cannot use periodic boundary conditions.<br \/>\nThe tethering potential’s task is then to ensure that the solute molecule remains close to the center of the droplet.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>To use either of the two potentials, the <b><tt>restrictive_potential<\/tt><\/b> keyword has to be used.<br \/>\nOne can either activate only the droplet (argument <b><tt>droplet<\/tt><\/b>), the tether (argument <b><tt>tether<\/tt><\/b>), or both (argument <b><tt>droplet_tether<\/tt><\/b>).<br \/>\nWith the default choice <b><tt>none<\/tt><\/b>, neither is active.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The droplet potential is defined as E<sub>drop<\/sub>(<span class=\"overacc2\">→<\/span>R) = ∑<sub>i<\/sub> [k\/2] (|<span class=\"overacc2\">→<\/span>R<sub>i<\/sub>| − R<sub>cut<\/sub>)<sup>2<\/sup>  Θ(|<span class=\"overacc2\">→<\/span>R<sub>i<\/sub>| − R<sub>cut<\/sub>), with all distances |<span class=\"overacc2\">→<\/span>R<sub>i<\/sub>| measured from the origin of the coordinate system.<br \/>\nThe droplet potential is a flat-bottom harmonic potential acting on each atom individually.<br \/>\nIt is defined by two parameters, k and R<sub>cut<\/sub>, which can be set by the keywords <b><tt>restrictive_droplet_force<\/tt><\/b> (in Hartree per Bohr<sup>2<\/sup>, no default) and <b><tt>restrictive_droplet_radius<\/tt><\/b> (in Å, default 12 Å).<br \/>\nUsing the <b><tt>restricted_droplet_atoms<\/tt><\/b> and <b><tt>restricted_droplet_atoms_list<\/tt><\/b> keywords, one can control which atoms should feel the droplet force, as indicated in Table <a href=\"#tab:input\">4.1<\/a>.<br \/>\nHowever, in most cases, all atoms should be included.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The tether potential actually has the same functional form as the droplet potential.<br \/>\nThe main difference is that the tether is typically only applied to a few atoms (e.g., the solute molecule or only some solute atoms) and that one can choose its origin.<br \/>\nThe tether potential is defined by two parameters, k and R<sub>cut<\/sub>, which can be set by the keywords <b><tt>tethering_force<\/tt><\/b> (in Hartree per Bohr<sup>2<\/sup>) and <b><tt>tethering_radius<\/tt><\/b> (in Å).<br \/>\nUsing the <b><tt>tether_at<\/tt><\/b> keyword, one can provide the atom indices.<br \/>\nUsing <b><tt>tethering_position<\/tt><\/b>, one can define the origin of the tethering force.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Reference Energy  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>ezero<\/tt><\/b> gives the energy shift for the diagonal elements of the Hamiltonian. The shift should be chosen so that the shifted diagonal elements are reasonably small (large diagonal elements in the Hamiltonian lead to rapidly changing coefficients, requiring extremely short subtime steps). <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the energy shift default is 0, i.e., S<span style=\"font-size:x-small\">HARC<\/span> does not choose an energy shift based on the energies at the first time step (this would lead to each trajectory having a different energy shift).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Scaling and Damping  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The scaling factor for the energies and gradients must be positive (not zero), see section <a href=\"#met:scaling\">8.25<\/a>.<br \/>\nOne can also scale only spin-orbit couplings by using <b><tt>soc_scaling<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The damping factor must be in the interval [0,1] (first, since the kinetic energy is always positive; second, because a damping factor larger than 1 would lead to exponentially growing kinetic energy). Also see section <a href=\"#met:damping\">8.6<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Thermostat settings  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, one thermostat is available, which is the Langevin thermostat.<br \/>\nIt can be activated with <b><tt>thermostat langevin<\/tt><\/b>.<br \/>\nThe default is <b><tt>thermostat none<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The Langevin thermostat is stochastic and therefore requires random numbers in every time step.<br \/>\nIn S<span style=\"font-size:x-small\">HARC<\/span>, the Langevin thermostat uses its own, separate random number generator, independent of the one that is used for determining surface hops.<br \/>\nThe <b><tt>rngseed_thermostat<\/tt><\/b> keyword can be used to set the seed for this second RNG.<br \/>\nThe default behaviour is to use the same seed as for the hopping RNG.<br \/>\nThis is safe, as the thermostat RNG uses a different implementation than the surface hop RNG, and therefore different, unrelated sequences will be obtained.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The behaviour of S<span style=\"font-size:x-small\">HARC<\/span>‘s thermostats when restarting a trajectory requires a short notice.<br \/>\nBy default, when restarting a trajectory, the thermostat RNG seed is read from <b><tt>restart.traj<\/tt><\/b> and the thermostat RNG is fast-forwarded to the same state it would have had without stopping and restarting the trajectory.<br \/>\nIn certain cases (e.g., forward flux sampling, where multiple trajectories with different thermostat seeds should be restarted from one restart file), this behaviour can be turned off with the <b><tt>norestart_thermostat_random<\/tt><\/b> keyword.<br \/>\nIf the keyword is used, the RNG seed is still read from <b><tt>restart.traj<\/tt><\/b>, but the RNG is not fast-forwarded.<br \/>\nThe trajectory can be restarted with a different thermostat RNG seed by manually modifying <b><tt>restart.traj<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The thermostat in S<span style=\"font-size:x-small\">HARC<\/span>4 can be used to heat different sets of atoms (“regions”) to different temperatures.<br \/>\nThe <b><tt>thermostatregions<\/tt><\/b> keyword can be used in several ways.<br \/>\nUsing <b><tt>thermostatregions one<\/tt><\/b> sets only one all-encompassing region.<br \/>\nUsing <b><tt>thermostatregions first 20<\/tt><\/b> instead sets up two regions, where the first 20 atoms are in region 1 and all remaining atoms in region 2.<br \/>\nGeneral regions can be defined via <b><tt>thermostatregions atomlist 1 1 1 2 2 2<\/tt><\/b>, where the user should provide the thermostat region index for each atom in the atom order (e.g., in the example, atoms 1-3 are in region 1 and atoms 4-6 in region 2).<br \/>\nAlternatively, <b><tt>thermostatregions file \"thermostat_settings\"<\/tt><\/b> would read the thermostat region indices for each atom from file <b><tt>thermostat_settings<\/tt><\/b>, together with the temperatures and thermostat constants.<br \/>\nThe file format is defined in Section <a href=\"#sec:thermostatfile\">4.10<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For each region, the temperature can be set separately.<br \/>\nYou have to provide as many temperatures as there are regions.<br \/>\nFor example, <b><tt>temperature 300. 600.<\/tt><\/b> sets the temperature to 300 K for region 1 and to 600 K for region 2.<br \/>\nNote that using multiple regions with very strongly differing temperatures can lead to non-equilibrium heat transport through the system, which can lead to various problems if not set up carefully.<br \/>\nThe <b><tt>temperature<\/tt><\/b> keyword is ignored if <b><tt>thermostatregions file<\/tt><\/b> is used.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>thermostat_const<\/tt><\/b> can be used to set further parameters for the thermostat in each region.<br \/>\nIn S<span style=\"font-size:x-small\">HARC<\/span>4, there is only the Langevin thermostat, which takes one parameter, the friction coefficient.<br \/>\nIf you have multiple regions, the friction coefficient has to be given for each region.<br \/>\nFor example, with two regions, you could use <b><tt>thermostat_const 0.001 0.02<\/tt><\/b> to have a weak thermostat in region 1 and a more aggressive thermostat in region 2.<br \/>\nNote that the friction constant from the input file is interpreted in fs<sup>−1<\/sup>, which is a very large unit.<br \/>\nTypical friction coefficients are around 0.001 fs<sup>−1<\/sup>, although larger values (e.g., the default of 0.020 fs<sup>−1<\/sup>) are probably needed to ensure fast thermalization in short trajectories.<br \/>\nThe <b><tt>thermostat_const<\/tt><\/b> keyword is ignored if <b><tt>thermostatregions file<\/tt><\/b> is used.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A related keyword is <b><tt>remove_trans_rot<\/tt><\/b>, which projects out translational and rotational components from the velocity vector.<br \/>\nThis keyword is only active if a thermostat is used.<br \/>\nIf you are interested in preserving the momentum and angular momentum in simulations without thermostat, see the options using projected NAC vectors with keywords <b><tt>ekincorrect<\/tt><\/b>, <b><tt>reflect_frustrated<\/tt><\/b>, and <b><tt>nac_projection<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Selection of Gradients and Non-Adiabatic Couplings  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p> S<span style=\"font-size:x-small\">HARC<\/span> allows to selectively calculate only certain gradients and nonadiabatic coupling vectors at each time step. Those gradients and nonadiabatic coupling vectors not selected are not requested from the interfaces, thus decreasing the computational cost. The selection procedure is detailed in <a href=\"#met:selection\">8.27<\/a>.<br \/>\nSelection of gradients is activated by <b><tt>grad_select<\/tt><\/b>, selection for nonadiabatic couplings by <b><tt>nac_select<\/tt><\/b>. Selection is turned off by default. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The selection procedure picks only states which are closer in energy to the classically occupied state than a given threshold. The threshold is 0.5 eV by default and can be adjusted using the <b><tt>eselect<\/tt><\/b> keyword.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Since S<span style=\"font-size:x-small\">HARC<\/span>2.1, by default the <b><tt>select_directly<\/tt><\/b> keyword is active, which tells S<span style=\"font-size:x-small\">HARC<\/span> to use the energies of the last time step for selecting, so that only one call per time step is necessary.<br \/>\nThe alternative (keyword <b><tt>noselect_directly<\/tt><\/b>) is to perform two quantum chemistry calls per time step. In the first call, all quantities are requested except for the ones to be selected. The energies are used to determine which gradients and NACs to calculate in a second quantum chemistry call.<br \/>\nThe option <b><tt>select_directly<\/tt><\/b> is strongly recommended in almost all instances, since for most quantum chemistry programs it is not possible to make sure that the wave function phases from both calls are consistent.<br \/>\nAdditionally, for all interfaces the calculation becomes more expensive with two calls per step.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that some interface may (for some electronic structure methods) compute the gradients numerically.<br \/>\nIn this case, the interface will automatically compute the gradients of all states together.<br \/>\nTherefore, <b><tt>grad_select<\/tt><\/b> offers no advantage for numerical gradient runs and it is strongly suggested to use the default option <b><tt>grad_all<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Phase Tracking  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Phase tracking is an important ingredient in S<span style=\"font-size:x-small\">HARC<\/span>. It is necessary for two reasons: (i) the columns of the transformation matrix <b>U<\/b> are determined only up to an arbitrary phase factor <span class=\"roman\">e<\/span><sup><span class=\"roman\">i<\/span>ϕ<\/sup> (and additional mixing angles in case of degeneracy), and (ii) the wave functions produced by any quantum chemistry code are determined only up to an arbitrary sign.<br \/>\nBoth kind of phases need to be tracked in S<span style=\"font-size:x-small\">HARC<\/span> in order to obtain smoothly varying matrix elements which can be properly integrated.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>By default, S<span style=\"font-size:x-small\">HARC<\/span> automatically tracks the phases in the <b>U<\/b> matrix (explicit keyword: <b><tt>track_phase<\/tt><\/b>), because all required information is always available. This phase tracking can be deactivated with the <b><tt>notrack_phase<\/tt><\/b> keyword, which can provide a significant speed advantage for <b><tt>pysharc<\/tt><\/b> calculations. However, you should check whether your results are affected by <b><tt>notrack_phase<\/tt><\/b>, and revert to <b><tt>track_phase<\/tt><\/b> if they do.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The tracking of the wave function signs depends on the interfaces, because only they have access to the explicit form of the wave functions. S<span style=\"font-size:x-small\">HARC<\/span> by default (explicit keyword: <b><tt>phases_from_interface<\/tt><\/b>) requests that the interface tracks the signs and reports any sign changes to S<span style=\"font-size:x-small\">HARC<\/span>. Currently, all interfaces can provide this phase information, but all of them need to perform overlap calculations to do so. The <b><tt>nophases_from_interface<\/tt><\/b> keyword can be used to deactivate these requests.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In some situations, it might be necessary to have consistent wave function signs between different trajectories. In this case, the <b><tt>phases_at_zero<\/tt><\/b> keyword can be used to compute sign information at t=0; this requires that the relevant wave function data of the reference is already located in the <b><tt>restart\/<\/tt><\/b> directory before the trajectory is started. Note that <b><tt>phases_at_zero<\/tt><\/b> is therefore an expert option.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Spin-Orbit Couplings  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using the keyword <b><tt>nospinorbit<\/tt><\/b> the calculation of spin-orbit couplings is disabled. S<span style=\"font-size:x-small\">HARC<\/span> will only request the diagonal elements of the Hamiltonian from the interfaces. If the interface returns a non-diagonal Hamiltonian anyways, the off-diagonal elements are deleted.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>spinorbit<\/tt><\/b> (which is the default) enables spin-orbit couplings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Dipole Moment Gradients  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The derivatives of the dipole moments can be included in the gradients. This can be activated with the keyword <b><tt>dipole_gradient<\/tt><\/b>. Currently, only the analytical and M<span style=\"font-size:x-small\">OLCAS<\/span> interfaces can deliver these quantities.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Ionization  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>ionization<\/tt><\/b> activates (<b><tt>noionization<\/tt><\/b> deactivates) the on-the-fly calculation of ionization transition properties. If the keyword is given, by default these properties are calculated every time step. The keyword <b><tt>ionization_step<\/tt><\/b> can be used to calculate these properties only every n-th time step.<br \/>\nIf the keyword is given, S<span style=\"font-size:x-small\">HARC<\/span> will request the calculation of the ionization properties from the interface, which needs to be able to calculate them.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The ionization probabilities are treated as one 2D property matrix, hence <b><tt>n_property2d<\/tt><\/b> should be at least 1.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b> T<span style=\"font-size:x-small\">HEO<\/span>DORE  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>theodore<\/tt><\/b> activates (<b><tt>notheodore<\/tt><\/b> deactivates) the on-the-fly calculation of wave function descriptors with the T<span style=\"font-size:x-small\">HEO<\/span>DORE program. This can be very useful to track the wave function character of the states on-the-fly.<br \/>\nThe interface must be able to execute and T<span style=\"font-size:x-small\">HEO<\/span>DORE and return its output to S<span style=\"font-size:x-small\">HARC<\/span> (currently, the ADF, G<span style=\"font-size:x-small\">AUSSIAN<\/span>, T<span style=\"font-size:x-small\">URBOMOLE<\/span>, and O<span style=\"font-size:x-small\">RCA<\/span> interfaces can do this). The keyword <b><tt>theodore_step<\/tt><\/b> can be used to calculate these descriptors only every n-th time step. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The T<span style=\"font-size:x-small\">HEO<\/span>DORE descriptors are treated as one 1D property vector for each descriptor, and <b><tt>n_property1d<\/tt><\/b> should be at least as large as the number of descriptors computed by the interface.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Output control  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are a number of keywords which control what information is written to the <b><tt>output.dat<\/tt><\/b> file.<br \/>\nThese keywords are <b><tt>write_grad<\/tt><\/b>, <b><tt>write_nacdr<\/tt><\/b>, <b><tt>write_overlap<\/tt><\/b>, <b><tt>write_property1d<\/tt><\/b>, and <b><tt>write_property2d<\/tt><\/b> (and the inverse of each one, e.g., <b><tt>nowrite_grad<\/tt><\/b>).<br \/>\nOnly <b><tt>write_overlap<\/tt><\/b> is activated by default, because it does not enlarge the data file by much, and contains important information which is read by <b><tt>data_extractor.x<\/tt><\/b>.<br \/>\n<b><tt>write_grad<\/tt><\/b> and <b><tt>write_nacdr<\/tt><\/b> are turned off by default; they are primarily intended for users who want to keep all quantum chemical data, e.g., for training in machine learning.<br \/>\nThe keywords <b><tt>write_property1d<\/tt><\/b> and <b><tt>write_property2d<\/tt><\/b> are automatically activated if <b><tt>theodore<\/tt><\/b> or <b><tt>ionization<\/tt><\/b> (respectively) are activated.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Output writing stride  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword <b><tt>output_dat_steps<\/tt><\/b> can be used to control how often data is written to <b><tt>output.dat<\/tt><\/b>.<br \/>\nThis is useful to reduce the amount of data generated by long trajectories (e.g., with the LVC or analytical interfaces).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the simplest version, using <b><tt>output_dat_steps N<\/tt><\/b> will set the output stride to <b><tt>N<\/tt><\/b>, so that <b><tt>output.dat<\/tt><\/b> is updated every <b><tt>N<\/tt><\/b>-th step (i.e., if step modulo <b><tt>N<\/tt><\/b> is equal to zero).<br \/>\nThe default is to write every step.<br \/>\nBecause in nonadiabatic dynamics, usually ballistic processes occur rapidly in the beginning and statistical processes occur slowly for longer times, this keyword allows printing more often in the beginning and less often for longer times.<br \/>\nTo use this feature, write <b><tt>output_dat_steps N1 M2 N2<\/tt><\/b>, which will use <b><tt>N1<\/tt><\/b> as the stride if step is larger or equal to zero, and <b><tt>N2<\/tt><\/b> as the stride if step is larger or equal to <b><tt>M2<\/tt><\/b>.<br \/>\nOne can also use three different strides via <b><tt>output_dat_steps N1 M2 N2 M3 N3<\/tt><\/b>, but not more than three.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that for these numbers <b><tt>sharc.x<\/tt><\/b> enforces <b><tt>N<\/tt><\/b> ≥ 1 and <b><tt>M<\/tt><\/b> ≥ 0, but no particular ordering.<br \/>\nHence, it is possible to use longer strides in the beginning and smaller strides later, although this is rarely useful.<br \/>\nIf step is larger\/equal to both <b><tt>M2<\/tt><\/b> and <b><tt>M3<\/tt><\/b>, then <b><tt>N3<\/tt><\/b> will be used.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Also note that the data written to <b><tt>output.dat<\/tt><\/b> is always simply the data for the respective time step, no average over the last <b><tt>N<\/tt><\/b> steps.<br \/>\nThis needs to be kept in mind when analyzing the trajectory plots.<br \/>\nIn particular, <b><tt>data_extractor.x<\/tt><\/b> computes diabatic coefficients from the product of all overlap matrices in <b><tt>output.dat<\/tt><\/b>.<br \/>\nHence, if not all time steps are written, the diabatized coefficients will be wrong.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Setting a variable output stride is currently not compatible with the adaptive time step integrator.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If <b><tt>output_format netcdf_separate_nuclei<\/tt><\/b> is active, then one can use <b><tt>output_dat_steps_nuc<\/tt><\/b> to separately control the stride for writing output into <b><tt>output_NUC.dat.nc<\/tt><\/b>.<br \/>\nIn this way, it is possible to write out electronic information (Hamiltonian, dipoles, overlaps, coefficients, etc.) every time step but write nuclear data only every <b><tt>N<\/tt><\/b> steps.<br \/>\nThis is useful if one has only few electronic states but a large number of atoms.<br \/>\nConversely, it is possible to write nuclear data every time step but electronic data only every <b><tt>N<\/tt><\/b> time steps.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Output format  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>See Sections <a href=\"#sec:datfile\">5.3<\/a>, <a href=\"#sec:netcdf\">5.4<\/a>, and <a href=\"#sec:netcdf_nuc\">5.5<\/a> for details.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.1.4\"><\/a><\/p>\n<h3>\n4.1.4  Example<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The following input samples provide typical inputs for excited-state dynamics: the first for trajectory surface hopping (TSH) and the second for CSDM. Both include internal conversion (IC) within a singlet manifold as well as intersystem crossing (ISC) to triplet states. A large number of excited singlet states are included to enable the calculation of transient absorption spectra but only the lowest three singlet states actually participate in the dynamics. <\/p>\n<div class=\"p\"><!----><\/div>\n<pre>\nnstates   8  0 3      # many singlet states for transient absorption\nactstates 3  0 3      # only few states to reduce gradient costs\ncharge    0 +1 0      # neutral singlets and triplets\n                      # doublet charge ignored (their number is zero)\nstepsize 0.5          # typical time step for a molecule containing H\ntmax 1000.0           # one picosecond\nsurf diagonal\nmethod tsh\nstate 3 mch                  # start on the S2 singlet state\ncoeff auto                   # coefficient of S2 will be set to one\ncoupling overlap             # \\\ndecoherence_scheme edc       # | typical settings\nekincorrect parallel_vel     # |\ngradcorrect                  # \/\ngrad_select           # \\\nnac_select            # | improve performance\neselect 0.3           # \/\nveloc external        # velocities come from file \"veloc\"\nvelocfile \"veloc\"     #\nRNGseed 65435\nezero -399.41494751   # ground state energy of molecule\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<pre>\nnstates   8  0 3      # many singlet states for transient absorption\nactstates 3  0 3      # only few states to reduce gradient costs\ncharge    0 +1 0      # neutral singlets and triplets\n                      # doublet charge ignored (their number is zero)\nstepsize 0.1          # typical time step for CSDM method\ntmax 1000.0           # one picosecond\nsurf diagonal\nmethod scp\nstate 3 mch                  # start on the S2 singlet state\ncoeff auto                   # coefficient of S2 will be set to one\ncoupling nacdr             # \\\nneom ddr                     # | \nswitching_procedure CSDM     # |\ndecoherence_scheme dom       # | \ndecotime_method csdm         # | typical settings\nekincorrect parallel_nac     # |\nnac_projection               # |\ngradcorrect                  # \/\ngrad_select           # \\\nnac_select            # | improve performance\neselect 0.3           # \/\nveloc external        # velocities come from file \"veloc\"\nvelocfile \"veloc\"     #\nRNGseed 65435\nezero -399.41494751   # ground state energy of molecule\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.2\"><\/a><\/p>\n<h2>\n4.2  Geometry file<\/h2>\n<p><a id=\"sec:geomfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The geometry file (default file name is <b><tt>geom<\/tt><\/b>) contains the initial coordinates of all atoms. This file must be present when starting a new trajectory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The format is based on the <a href=\"http:\/\/www.univie.ac.at\/columbus\/docs_COL70\/documentation_main.html\"> C<span style=\"font-size:x-small\">OLUMBUS<\/span> geometry file format<\/a> (however, S<span style=\"font-size:x-small\">HARC<\/span> is more flexible with the formatting of the numbers). For each atom, the file contains one line, giving the chemical symbol (a string), the atomic number (a real number), the x, y and z coordinates of the atom in Bohrs (three real numbers), and the relative atomic weight of the atom (a real number). The six items must be separated by spaces. The real numbers are read in using Fortran list-directed I\/O, and hence are free format (can have any numbers of decimals, exponential notation, etc.). Element symbols can have at most 2 characters.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The following is an example of a <b><tt>geom<\/tt><\/b> file for CH2:<\/p>\n<pre>\nC 6.0  0.0 0.0  0.0 12.000\nH 1.0  1.7 0.0 -1.2  1.008\nH 1.0  1.7 0.0  3.7  1.008\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.3\"><\/a><\/p>\n<h2>\n4.3  Velocity file<\/h2>\n<p><a id=\"sec:velocfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The velocity file (default <b><tt>veloc<\/tt><\/b>) contains the initial nuclear velocities (e.g., from a Wigner distribution sampling). This file is optional (the velocities can be initialized with the <b><tt>veloc<\/tt><\/b> input keyword). <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The file contains one line of input for each atom, where the order of atoms must be the same as in the <b><tt>geom<\/tt><\/b> file. Each line consists of three items, separated by spaces, where the first is the x component of the nuclear velocity, followed by the y and z components (three real numbers). The input is interpreted in atomic units (Bohr\/atu).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The following is an example of a <b><tt>veloc<\/tt><\/b> file:<\/p>\n<pre>\n 0.0001  0.0000  0.0002\n 0.0002  0.0000  0.0012\n 0.0003  0.0000 -0.0007\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.4\"><\/a><\/p>\n<h2>\n4.4  Coefficient file<\/h2>\n<p><a id=\"sec:coefffile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The coefficient file contains the initial wave function coefficients. The file contains one line per state (total number of states, i.e., multiplets count multiple times). Each line specifies the initial coefficient of one state. If the initial state is specified in the MCH representation (input keyword <b><tt>state<\/tt><\/b>), then the order of the initial coefficients must be as given by the canonical ordering (see section <a href=\"#met:ordering\">8.28<\/a>). If the initial state is given in diagonal representation, then the initial coefficients correspond to the states given in energetic ordering, starting with the lowest state.<br \/>\nEach line contains two real numbers, giving first the real and then the imaginary part of the initial coefficient of the respective state.<br \/>\nNote that after read-in, the coefficient vector is normalized to one.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Example:<\/p>\n<pre>\n0.0 0.0\n1.0 0.0\n0.0 0.0\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.5\"><\/a><\/p>\n<h2>\n4.5  Laser file<\/h2>\n<p><a id=\"sec:laserfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The laser file contains a table with the amplitude of the laser field ϵ(t) at each time step of the <i>electronic<\/i> propagation. Given a laser field of the general form:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-0.png\">\n<\/td>\n<td width=\"1%\">(4.1)<\/td>\n<\/tr>\n<\/table>\n<p>each line consists of 8 elements: t (in fs), ℜ(ϵ<sub>x<\/sub>(t)), ℑ(ϵ<sub>x<\/sub>(t)), ℜ(ϵ<sub>y<\/sub>(t)), ℑ(ϵ<sub>y<\/sub>(t)), ℜ(ϵ<sub>z<\/sub>(t)), ℑ(ϵ<sub>z<\/sub>(t)), (all in atomic units), and finally the instantaneous central frequency (also atomic units).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The time step in the laser file must exactly match the time step used for the electronic propagation, which is the time step used for the nuclear propagation (keyword <b><tt>stepsize<\/tt><\/b>) divided by the number of substeps (keyword <b><tt>nsubsteps<\/tt><\/b>). The first line of the laser file must correspond to t=0 fs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Example:<\/p>\n<pre>\n0.00E+00 -0.68E-03  0.00E+00  0.00E+00  0.00E+00  0.00E+00  0.00E+00  0.31E+00\n0.10E-02 -0.77E-02  0.00E+00  0.00E+00  0.00E+00  0.00E+00  0.00E+00  0.33E+00\n0.20E-02 -0.13E-01  0.00E+00  0.00E+00  0.00E+00  0.00E+00  0.00E+00  0.35E+00\n     ...       ...       ...       ...       ...       ...       ...       ...\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.6\"><\/a><\/p>\n<h2>\n4.6  Atom mask file<\/h2>\n<p><a id=\"sec:atommaskfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The atom mask file contains for each atom a line with a Boolean entry (“T” or “F”), which indicates whether the atom should be considered in the relevant procedures.<br \/>\nSpecifically, the atom masking settings affect the options <b><tt>ekincorrect parallel_vel<\/tt><\/b>, <b><tt>reflect_frustrated parallel_vel<\/tt><\/b>, and <b><tt>decoherence_scheme edc<\/tt><\/b>.<br \/>\nIn all cases, “T” indicates that the atom should be considered (as if <b><tt>atommask<\/tt><\/b> was not given), whereas “F” indicates that the atom should be ignored for these procedures.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Example:<\/p>\n<pre>\n T\n T\n F\n F\n...\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.7\"><\/a><\/p>\n<h2>\n4.7  RATTLE file<\/h2>\n<p><a id=\"sec:rattlefile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The RATTLE file contains a list of all the atom pairs whose interatomic distance should be fixed by the RATTLE algorithm.<br \/>\nIn the file, each line should contain two integer numbers that indicate the atom indices of one atom pair.<br \/>\nAtom indices start at 1.<br \/>\nOptionally, some lines can also have a third entry, which is a float with the desired interatomic distance in Bohr units.<br \/>\nIf the third entry is not give, then the distance is fixed to the value that is found in the initial geometry file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Example:<\/p>\n<pre>\n1 3\n2 4  2.05\n2 5\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.8\"><\/a><\/p>\n<h2>\n4.8  Frozen atoms file<\/h2>\n<p><a id=\"sec:frozenfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The frozen atoms file contains one line per atom, which should be either <b><tt>T<\/tt><\/b> (atom is propagated) or <b><tt>F<\/tt><\/b> (atom is frozen).<br \/>\nThis format is exactly the same as in the <b><tt>atommaskfile<\/tt><\/b> (Section <a href=\"#sec:atommaskfile\">4.6<\/a>).<br \/>\nThe default file name is <b><tt>frozen<\/tt><\/b>, which is used with <b><tt>freeze file<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.9\"><\/a><\/p>\n<h2>\n4.9  Droplet atoms file<\/h2>\n<p><a id=\"sec:dropletfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The droplet atoms file contains one line per atom, which should be either <b><tt>T<\/tt><\/b> (atom feels droplet potential) or <b><tt>F<\/tt><\/b> (droplet potential does not act on that atom).<br \/>\nThis format is exactly the same as in the <b><tt>atommaskfile<\/tt><\/b> (Section <a href=\"#sec:atommaskfile\">4.6<\/a>).<br \/>\nThe default file name is <b><tt>droplet<\/tt><\/b>, which is used with <b><tt>restricted_droplet_atoms file<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc4.10\"><\/a><\/p>\n<h2>\n4.10  Thermostat settings file<\/h2>\n<p><a id=\"sec:thermostatfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The thermostat settings file can be used to define the number of thermostat regions, their temperatures, their thermostat parameters, and the assignment of all atoms to the regions.<br \/>\nThe file format is<\/p>\n<pre>\n<n_regions>\n<n_regions lines with temperatures>\n<n_regions lines with all parameters for the thermostat>\n<n_atom lines with one region index>\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>For example, with two regions, the Langevin thermostat, and six atoms, the thermostat file could look like:<\/p>\n<pre>\n2   ! two regions\n300.0   ! temperature in K for region 1\n500.0   ! temperature in K for region 2\n0.01   ! friction coefficient in fs^-1 for region 1\n0.05   ! friction coefficient in fs^-1 for region 2\n1   ! atom 1 assigned to region 1\n1   ! atom 2 assigned to region 1\n1\n2   ! atom 4 assigned to region 2\n2\n2\n<\/pre>\n<p>Trailing comments beyond the expected amount of entries per line are ignored.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The default file name is <b><tt>thermostat_settings<\/tt><\/b>, which is used with <b><tt>thermostatregions file<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_chAp5\"><\/a><\/p>\n<h1>\nChapter 5 <br \/>Output files<\/h1>\n<p><a id=\"chap:output\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This chapter documents the content of the output files of S<span style=\"font-size:x-small\">HARC<\/span>.<br \/>\nThose output files are <b><tt>output.log<\/tt><\/b>, <b><tt>output.lis<\/tt><\/b>, <b><tt>output.dat<\/tt><\/b> and <b><tt>output.xyz<\/tt><\/b>.<br \/>\nFor users using NetCDF output via PySHARC, additional output files are <b><tt>output.dat.nc<\/tt><\/b> and <b><tt>output_NUC.dat.nc<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc5.1\"><\/a><\/p>\n<h2>\n5.1  Log file: <b><tt>output.log<\/tt><\/b><\/h2>\n<p><a id=\"sec:logfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The log file <b><tt>output.log<\/tt><\/b> contains general information about all steps of the S<span style=\"font-size:x-small\">HARC<\/span> simulation, e.g., about the parsing of the input files, results of quantum chemistry calls, internal matrices and vectors, etc. The content of the log file can be controlled with the keyword <b><tt>printlevel<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> main input file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the following, all printlevels are explained.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Printlevel 0  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>At printlevel 0, only the execution infos (date, host and working directory at execution start) and build infos (compiler, compile date, building host and working directory) are given.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Printlevel 1  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>At printlevel 1, also the content of the input file (cleaned of comments and blank lines) is echoed in the log file. Also, the start of each time step is given.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Printlevel 2  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>At printlevel 2, the log file also contains information about the parsing of the input files (echoing all enabled options, initial geometry, velocity and coefficients, etc.) and about the initialization of the coefficients after the first quantum chemistry calculation. This printlevel is recommended for production calculations, since it is the highest printlevel where no output per time step is written to the log file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Printlevel 3  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This and higher printlevels add output per time step to the log file. At printlevel 3, the log file contains at each time step the data from the velocity-Verlet algorithm (old and new acceleration, velocity and geometry), the old and new coefficients, the surface hopping probabilities and random number, the occupancies before and after decoherence correction as well as the kinetic, potential and total energies.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Printlevel 4  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>At printlevel 4, additionally the log file contains information on the quantum chemistry calls (file names, which quantities were read, gradient and nonadiabatic coupling vector selection) and the propagator matrix.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Printlevel 5  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>At printlevel 5, additionally the log file contains the results of each quantum chemistry calls (all matrices and vectors), all matrices involved in the propagation as well as the matrices involved in the gradient transformation. This is the highest printlevel currently implemented.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc5.2\"><\/a><\/p>\n<h2>\n5.2  Listing file: <b><tt>output.lis<\/tt><\/b><\/h2>\n<p><a id=\"sec:lisfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The listing file <b><tt>output.lis<\/tt><\/b> is a tabular summary of the progress of the dynamics simulation. At the end of each time step (including the initial time step), one line with 11 elements is printed. These are, from left to right:<\/p>\n<ol type=\"1\">\n<li> current step (counting starts at zero for the initial step),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> current simulation time (fs),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> current state in the diagonal representation,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> approximate corresponding MCH state (see subsection <a href=\"#ssec:state_transform\">8.23.1<\/a>),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> kinetic energy (eV),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> potential energy (eV),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> total energy (eV),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> total angular momentum [ħ],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> current gradient norm (in eV\/Å),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> total sum of populations (called Density in the file),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> current expectation values of the state dipole moment (Debye),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> current expectation values of total spin,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> wall clock time needed for the time step.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<p>The listing file also contains one extra line for each surface hopping or pointer state switching event. For accepted hops, the old and new states (in diagonal representation) and the random number are given. Frustrated hops and resonant hops are also mentioned. Note that the extra line for surface hopping occurs before the regular line for the time step. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The listing file can be plotted with standard tools like G<span style=\"font-size:x-small\">NUPLOT<\/span> and can be read with <b><tt>data_collector.py<\/tt><\/b>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Energies  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The kinetic energy is calculated at the end of each time step (i.e., after surface hopping events and the corresponding adjustments). The potential energy is the energy of the currently active diagonal state. The total energy is the sum of those two.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Expectation values  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The gradient norms given in the listing file is calculated as follows:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-1.png\">\n<\/td>\n<td width=\"1%\">(5.1)<\/td>\n<\/tr>\n<\/table>\n<p>which is then transformed to eV\/Å.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The expectation values of the dipole moment for the active state β is calculated from:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-2.png\">\n<\/td>\n<td width=\"1%\">(5.2)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>The expectation value of the total spin of the active state β is calculated as follows:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-3.png\">\n<\/td>\n<td width=\"1%\">(5.3)<\/td>\n<\/tr>\n<\/table>\n<p>where S<sub>α<\/sub> is the total spin of the MCH state with index α.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc5.3\"><\/a><\/p>\n<h2>\n5.3  Data file: <b><tt>output.dat<\/tt><\/b><\/h2>\n<p><a id=\"sec:datfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The data file <b><tt>output.dat<\/tt><\/b> contains all relevant data from the simulation for all time steps, in ASCII format. Accordingly, this file can become quite large for long trajectories, for many atoms, or if many states are included, but for most file systems it is easier to deal with a single large file than with many small files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Usually, after the simulation is finished the data file is processed by <b><tt>data_extractor.x<\/tt><\/b> to obtain a number of tabular files which can be plotted or post-processed (e.g., with <b><tt>data_collector.py<\/tt><\/b>).<br \/>\nFor this, see Sections <a href=\"#sec:data_extractor.x\">7.17<\/a> for the data extractor, <a href=\"#sec:make_gnuscript.py\">7.22<\/a> for plotting, and <a href=\"#sec:data_collector.py\">7.30<\/a> for post-processing.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that if you use NetCDF output, then <b><tt>output.dat<\/tt><\/b> will only contain the header information and header arrays.<br \/>\nSee Section <a href=\"#sec:netcdf\">5.4<\/a> for more details.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc5.3.1\"><\/a><\/p>\n<h3>\n5.3.1  Specification of the data file<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The data file format was changed between S<span style=\"font-size:x-small\">HARC<\/span>1 and S<span style=\"font-size:x-small\">HARC<\/span>2. The new format uses a different header, which is keyword-based (like the <b><tt>input<\/tt><\/b> file) and starts with <b><tt>SHARC_version X.Y<\/tt><\/b>. The general structure of the time step data is the same as in the first release version.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The data file contains a short header followed by the data per time step. All quantities are commented in the data file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The header is keyword-based and contains at least the following entries:<\/p>\n<ol type=\"1\">\n<li> method (surface hopping or CSDM),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> integrator,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> maximum multiplicity,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> number of states per multiplicity,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> number of atoms,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> time step,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> maximum number of time steps,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> number of substeps,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> reference energy,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>write_overlap<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>write_grad<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>write_nacdr<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>write_property1d<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>write_property2d<\/tt><\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> number of 1D properties,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> number of 2D properties,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> information whether a laser field is included.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<div class=\"p\"><!----><\/div>\n<p>At the end of the header, the data file contains a header array section. Currently, this includes:<\/p>\n<ol type=\"1\">\n<li> atomic numbers,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> elements,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> masses,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> full laser field for all substeps (only if flag is set).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<div class=\"p\"><!----><\/div>\n<p>The entry for each time step contains:<\/p>\n<ol type=\"1\">\n<li> step index and current time for adaptive integrators,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Hamiltonian in MCH representation,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> transformation matrix <b>U<\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> MCH dipole moment matrices (x, y, z),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> overlap matrix in MCH representation (only if flag is set),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> coefficients in the diagonal representation,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> hopping probablities in the diagonal representation\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> kinetic energy,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> currently active state in diagonal representation and approximate state in MCH representation,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> random number for surface hopping,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> wall clock time (in seconds)\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> geometry (Bohrs),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> velocities (atomic units),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> 2D property matrices (only if flag is set),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> 1D property vectors (only if flag is set),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> gradient vectors (only if flag is set),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> nonadiabatic coupling vectors (only if flag is set).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc5.4\"><\/a><\/p>\n<h2>\n5.4  Data file in NetCDF format: : <b><tt>output.dat.nc<\/tt><\/b><\/h2>\n<p><a id=\"sec:netcdf\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If <b><tt>output_format<\/tt><\/b> is set to <b><tt>netcdf<\/tt><\/b>, then only the header and header arrays will be written to the <b><tt>output.dat<\/tt><\/b> file, but no information per time step.<br \/>\nThe latter is instead written in (binary) NetCDF format to <b><tt>output.dat.nc<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>This option is intended to provide faster output for fast simulations with <b><tt>pysharc<\/tt><\/b>.<br \/>\nHowever, it is also an option that leads to less disk memory consumption, and can be used with <b><tt>sharc.x<\/tt><\/b>.<br \/>\nTo this end, <b><tt>output_format<\/tt><\/b>=<b><tt>netcdf<\/tt><\/b> also deactivates writing of the <b><tt>output.xyz<\/tt><\/b> file.<br \/>\nAlso, when NetCDF files are written, no restart files are produced, except on the last time step or in case of errors.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>NetCDF output files can be extracted with <b><tt>data_extractor_NetCDF.x<\/tt><\/b> (see Section <a href=\"#sec:data_extractor_NetCDF.x\">7.18<\/a>).<br \/>\nThis program can also regenerate the <b><tt>output.xyz<\/tt><\/b> for further analysis.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Currently, there are a few limitations in this approach.<br \/>\nMost importantly, the NetCDF files do not store the property vectors and property matrices that can be stored in the <b><tt>output.dat<\/tt><\/b> files.<br \/>\nHence, computations with the <b><tt>ionization<\/tt><\/b> or <b><tt>theodore<\/tt><\/b> keywords should not use the NetCDF format.<br \/>\nAdditionally, gradients and nonadiabatic coupling vectors are not written to NetCDF output files. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The program <b><tt>data_converter.x<\/tt><\/b> (see Section <a href=\"#sec:data_converter.x\">7.19<\/a>) can be used to convert an <b><tt>output.dat<\/tt><\/b> file into a NetCDF file.<br \/>\nThis can be useful when archiving an ensemble of trajectories, as the NetCDF files are much smaller than the ASCII files.<br \/>\nNote that after conversion, the <b><tt>output.xyz<\/tt><\/b> files can be deleted, as they can be regenerated from the NetCDF file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Conversely, sometimes it is useful to inspect the data manually, which is difficult in NetCDF format.<br \/>\nIn this case, one can use <b><tt>data_converter_to_ASCII.x<\/tt><\/b> (see Section <a href=\"#sec:data_converter_to_ASCII.x\">7.20<\/a>), which will produce a file called <b><tt>output.dat.cp<\/tt><\/b> (to not overwrite the original <b><tt>output.dat<\/tt><\/b> with the header).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc5.5\"><\/a><\/p>\n<h2>\n5.5  Separate nuclear data file in NetCDF format: <b><tt>output_NUC.dat.nc<\/tt><\/b><\/h2>\n<p><a id=\"sec:netcdf_nuc\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>With the option <b><tt>output_format netcdf_separate_nuclei<\/tt><\/b>, SHARC will split the output data into two NetCDF files.<br \/>\nThe files <b><tt>output.dat<\/tt><\/b> and <b><tt>output.dat.nc<\/tt><\/b> are written as if the system contains only one atom.<br \/>\nAdditionally, the file <b><tt>output_NUC.dat.nc<\/tt><\/b> is written with only the coordinates and velocities.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that <b><tt>output_NUC.dat.nc<\/tt><\/b> is not compatible with <b><tt>data_extractor_NetCDF.x<\/tt><\/b> or <b><tt>data_converter_to_ASCII.x<\/tt><\/b>.<br \/>\nHowever, it can be read by <b><tt>sharctraj_to_xyz.py<\/tt><\/b> (Section <a href=\"#sec:sharctraj_to_xyz.py\">7.7<\/a>), <b><tt>data_extractor_NUC_xyz.py<\/tt><\/b> (Section <a href=\"#sec:data_extractor_NUC_xyz.py\">7.21<\/a>), and <b><tt>align_and_reorder_trjaj.py<\/tt><\/b> (Section <a href=\"#sec:align_and_reorder_traj.py\">7.31<\/a>).<br \/>\nThe first of these scripts can be used to extract one time step from the file and write it in xyz, <b><tt>initconds<\/tt><\/b>, or <b><tt>geom<\/tt><\/b>\/<b><tt>veloc<\/tt><\/b> formats; this is useful to setup trajectories starting from time steps of a previous trajectory.<br \/>\nThe second script extracts the entire <b><tt>output_NUC.dat.nc<\/tt><\/b> into XYZ format for visualization and analysis purposes (e.g., with <b><tt>geo.py<\/tt><\/b> or <b><tt>geo_NM.py<\/tt><\/b>.<br \/>\nThe third script can align coordinates in <b><tt>output_NUC.dat.nc<\/tt><\/b> files, reorder a trajectory swarm to get NetCDF coordinate files for each time step, and convert the files to a NetCDF format that follows Amber conventions (thus, can be opened by, e.g., VMD or <b><tt>cpptraj<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc5.6\"><\/a><\/p>\n<h2>\n5.6  XYZ file: <b><tt>output.xyz<\/tt><\/b><\/h2>\n<p><a id=\"sec:xyzfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>output.xyz<\/tt><\/b> contains the geometries of all time steps in standard xyz file format. It can be used with visualization programs like M<span style=\"font-size:x-small\">OLDEN<\/span>, G<span style=\"font-size:x-small\">ABEDIT<\/span> or M<span style=\"font-size:x-small\">OLEKEL<\/span> to create movies of the molecular motion, or with <b><tt>geo.py<\/tt><\/b> (see <a href=\"#sec:geo.py\">7.23<\/a>) to calculate internal coordinates for each time step.<br \/>\nUsing <b><tt>geo_NM.py<\/tt><\/b> and a normal mode file (<b><tt>V0.txt<\/tt><\/b>, see Section <a href=\"#sec:setup_LVCparam.py\">6.4.4<\/a> for details), normal mode coordinates can be computed.<br \/>\nFurthermore, <b><tt>trajana_essdyn.py<\/tt><\/b> (see <a href=\"#sec:trajana_essdyn.py\">7.29<\/a>) reads this file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The comments of the geometries (given in the second line of each geometry block) contain information about the simulation time and the active state (first in diagonal basis, then in MCH basis).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If <b><tt>output_format<\/tt><\/b>=<b><tt>netcdf<\/tt><\/b>, the <b><tt>output.xyz<\/tt><\/b> file will be empty.<br \/>\nUse <b><tt>data_extractor_NetCDF.x<\/tt><\/b> (Section <a href=\"#sec:data_extractor_NetCDF.x\">7.18<\/a>) with the <b><tt>-xyz<\/tt><\/b> flag to obtain the <b><tt>output.xyz<\/tt><\/b> file.<br \/>\nConversely, if <b><tt>output_format<\/tt><\/b>=<b><tt>netcdf_separate_nuclei<\/tt><\/b> is used, the <b><tt>output.xyz<\/tt><\/b> file can be generated from <b><tt>output_NUC.dat.nc<\/tt><\/b> via the script <b><tt>data_extractor_NUC_xyz.py<\/tt><\/b> (Section <a href=\"#sec:data_extractor_NUC_xyz.py\">7.21<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_chAp6\"><\/a><\/p>\n<h1>\nChapter 6 <br \/>Interfaces<\/h1>\n<p><a id=\"chap:interfaces\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This chapter describes the interface between S<span style=\"font-size:x-small\">HARC<\/span> and any provider of electronic structure information, like potential energy surface models or quantum chemistry programs. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface infrastructure of S<span style=\"font-size:x-small\">HARC<\/span> was completely overhauled in S<span style=\"font-size:x-small\">HARC<\/span>4, compared to previous versions.<br \/>\nIn S<span style=\"font-size:x-small\">HARC<\/span>3 and previous versions, S<span style=\"font-size:x-small\">HARC<\/span> interfaces were in principle any script that reads a communication file (<b><tt>QM.in<\/tt><\/b>) coming from <b><tt>sharc.x<\/tt><\/b> and returning the requested information in a second communication file (<b><tt>QM.out<\/tt><\/b>).<br \/>\nOn the contrary, in S<span style=\"font-size:x-small\">HARC<\/span>4 each interface is a Python module implementing a class.<br \/>\nEach interface has a main function that implements the communication via <b><tt>QM.in<\/tt><\/b> and <b><tt>QM.out<\/tt><\/b>, but additionally each interface also has several methods to instantiate, initialize, execute, and setup a calculation from within Python.<br \/>\nIn this way, one can run PySHARC trajectories using <b><tt>driver.py<\/tt><\/b> that avoid file I\/O for much higher performance.<br \/>\nThis dual capability is shown in Figure <a href=\"#fig:interface_general\">6.1<\/a>.<br \/>\nAdditionally, S<span style=\"font-size:x-small\">HARC<\/span>4 interfaces can call other S<span style=\"font-size:x-small\">HARC<\/span>4 interfaces, which makes it possible to produce complex workflows in a flexible manner (e.g., QM\/MM, numerical gradients, etc).<br \/>\nNote that this interface nesting also applies to setting up of trajectories, where S<span style=\"font-size:x-small\">HARC<\/span>4 interfaces communicate with the setup scripts by providing the available features and routines to take care of all interface-specific files.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg6.1\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/general.png\"> <\/p>\n<div style=\"text-align:center\">Figure 6.1: Communication between <b><tt>sharc.x<\/tt><\/b>, <b><tt>driver.py<\/tt><\/b>, the interfaces, and the quantum chemistry codes.<\/div>\n<p> <a id=\"fig:interface_general\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Section <a href=\"#sec:int:overview\">6.0.1<\/a> gives a short overview of the existing interfaces.<br \/>\nThe subsequent sections document the capabilities of all interfaces.<br \/>\nIn Section <a href=\"#sec:int_spec\">6.28<\/a>, a short specification of the interface is given (for users who want to develop their own interface).<br \/>\nFinally, Section <a href=\"#sec:int:wfoverlap\">6.29<\/a> provides the documentation for the <b><tt>wfoverlap.x<\/tt><\/b> auxiliary program.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.0.1\"><\/a><\/p>\n<h3>\n6.0.1  Overview over Interfaces<\/h3>\n<p><a id=\"sec:int:overview\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>4 interfaces are derived from three different base classes: fast interfaces, ab initio interfaces, and hybrid interfaces.<br \/>\nHowever, this classification is more relevant for interface developers, whereas for users a slightly finer granularity is more useful.<br \/>\nIn this way, we can distinguish six different interface kinds of interfaces:<\/p>\n<ul>\n<li> <b>Stub interfaces<\/b> are very simply interfaces that do not do file I\/O or call an external program, but instead simply return trivial information, like zeros, unit matrices, or constant values. These are mostly intended for testing.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b>Fast interfaces<\/b> implement fast potential energy methods that are evaluated within Python, without file I\/O or expensive ab initio computations. Examples include analytical, machine-learning, or molecular mechanics models. These interfaces can run in the so-called <i>persisent<\/i> mode, where they do not even write files for restart (except on the last time step).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b>Ab initio interfaces<\/b> allow S<span style=\"font-size:x-small\">HARC<\/span> to communicate with external quantum chemistry programs. These interfaces perform file I\/O and use the save directory to store information between time steps (e.g., for orbital restart, wave function overlaps). These interfaces have been reimplemented to follow S<span style=\"font-size:x-small\">HARC<\/span>4 standards.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b>Legacy ab initio interfaces<\/b> are interfaces that have been directly taken from S<span style=\"font-size:x-small\">HARC<\/span>3 without extensive reimplementations for S<span style=\"font-size:x-small\">HARC<\/span>4. They have all capabilities they had in S<span style=\"font-size:x-small\">HARC<\/span>3. In order to use them in S<span style=\"font-size:x-small\">HARC<\/span>4, they can be called via <b><tt>SHARC_LEGACY.py<\/tt><\/b>, which is a S<span style=\"font-size:x-small\">HARC<\/span>4-compliant interface that acts as a front-end to the legacy interfaces.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b>Single-child hybrid interfaces<\/b> are interfaces that use a single child interface to do part or most of the work. These allows users to manipulate the electronic structure data on the way between the actual providing interface and the caller. Examples are storing electronic structure data in a data base, adding harmonic restrains, or performing numerical differentiation.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b>Multi-child hybrid interfaces<\/b> are interfaces that use a <i>kindergarden<\/i> of several child interfaces, e.g., to compute the electronic structure results for only a part of the system. They implement, e.g., QM\/MM, excitonic multi-fragment models, or adaptive sampling procedures.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>Table <a href=\"#tab:interfaces\">6.1<\/a> gives an overview over all interfaces available in S<span style=\"font-size:x-small\">HARC<\/span>4.<br \/>\nThe different features in the table are explained here:<\/p>\n<ul>\n<li> Energies (<b><tt>H<\/tt><\/b>): This is the most basic request and is available from every interface. It is omitted in Table <a href=\"#tab:interfaces\">6.1<\/a>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Spin-orbit couplings (<b><tt>SOC<\/tt><\/b>): Adds spin-orbit coupling matrix elements between all electronic states to the electronic Hamiltonian. The relevant spin functions are typically in the spherical representation (i.e., complex-valued and with well-defined M<sub>S<\/sub> values) but can also be in another basis (e.g., real-valued spin functions).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Dipole moments (<b><tt>DM<\/tt><\/b>): This requests the entire matrix of electric dipole moments and transition dipole moments between all electronic states. Typically, S<span style=\"font-size:x-small\">HARC<\/span>4 interfaces will return those in the length representation. For some interfaces, some dipole moments cannot be returned and will thus be zero (e.g., excited-to-excited transition dipole moments for TD-DFT).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Gradients (<b><tt>GRAD<\/tt><\/b>): This requests the entire list of gradients of all electronic states, although the request can also be posed to compute only a subset of all gradients.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Nonadiabatic coupling vectors (<b><tt>NACDR<\/tt><\/b>): This requests the entire matrix of nonadiabatic coupling vectors 〈Ψ<sub>α<\/sub>|∇<sub><span class=\"overacc2\">→<\/span>R<\/sub>|Ψ<sub>β<\/sub>〉 for all electronic states, although also a subset can be requested.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Wave function overlaps (<b><tt>OVERLAP<\/tt><\/b>): This requests the matrix containing 〈Ψ<sub>α<\/sub>(t)|Ψ<sub>β<\/sub>(t+∆t)〉, computed between the current step and the most recent previous one (using information in the save directory, unless the interface is persistent). Interfaces that can compute overlaps can also serve <b><tt>PHASES<\/tt><\/b> requests.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Dyson norms (<b><tt>ION<\/tt><\/b>): This requests the matrix containing the Dyson norms between all electronic states. This is handled by S<span style=\"font-size:x-small\">HARC<\/span> as a <i>property matrix<\/i>, which does not affect the dynamics.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Electronic wave function descriptors (<b><tt>TheoDORE<\/tt><\/b>): This requests various descriptors for electronic wave functions (charge transfer, multiconfigurational character, localization, etc), which are treated as sets of <i>property vectors<\/i> that do not affect the dynamics.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Electrostatic embedding via point charges (<b><tt>point charges<\/tt><\/b>): This is not request, but a feature that some S<span style=\"font-size:x-small\">HARC<\/span>4 interfaces have. They can receive a set of point charges and perform electrostatic embedding. If gradients or nonadiabatic coupling vectors are requested, also returns those on the point charges.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Atomic point-multipole representation of electronic densities (<b><tt>multipolar_fit<\/tt><\/b>): This requests for each electronic state and each pair of electronic states a set of monopoles+dipoles+quadrupoles per atom that represents the electrostatics of the corresponding state or transition density.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Molecular wave function information and density matrices (<b><tt>mol\/densities<\/tt><\/b>): This requests that the atomic orbital basis set and all possible electronic density matrices in the atomic orbital basis are returned.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.1\"><br \/>\n<\/a> <\/p>\n<div class=\"small\">\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.1: Overview over capabilities of S<span style=\"font-size:x-small\">HARC<\/span>4 interfaces. <\/div>\n<p> <a id=\"tab:interfaces\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Interface <\/td>\n<td align=\"left\">Method <\/td>\n<td align=\"left\">Mult\n <\/td>\n<td align=\"center\">\n <\/td>\n<td align=\"center\">\n <\/td>\n<td align=\"center\">\n <\/td>\n<td align=\"center\">\n <\/td>\n<td align=\"center\">\n <\/td>\n<td align=\"center\">\n <\/td>\n<td align=\"center\">\n <\/td>\n<td align=\"center\">\n <\/td>\n<td align=\"center\">\n <\/td>\n<td align=\"center\">\n <\/td>\n<td align=\"left\">\n <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Stub interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">DO_NOTHING <\/td>\n<td align=\"left\">zeros <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:do_nothing\">6.1<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:do_nothing\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">QMOUT <\/td>\n<td align=\"left\">constant <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:qmout\">6.2<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:qmout\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Fast interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ANALYTICAL <\/td>\n<td align=\"left\">sympy <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:analytical\">6.3<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:analytical\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">LVC <\/td>\n<td align=\"left\">LVC\/QVC models <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:lvc\">6.4<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:lvc\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SPAINN <\/td>\n<td align=\"left\">PaiNN models <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:spainn\">6.5<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:spainn\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SCHNARC <\/td>\n<td align=\"left\">SchnArc models <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:schnarc\">6.6<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:spainn\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">OPENMM <\/td>\n<td align=\"left\">MM force fields <\/td>\n<td align=\"left\">1 state <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">(√) <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:openmm\">6.7<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:openmm\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Ab initio interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">GAUSSIAN <\/td>\n<td align=\"left\">TD-DFT <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<sup>b<\/sup> <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"left\"><a href=\"#sec:int:gaussian\">6.8<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:gaussian\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ORCA <\/td>\n<td align=\"left\">TD-DFT <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<sup>c<\/sup> <\/td>\n<td align=\"center\">√<sup>b<\/sup> <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:orca\">6.9<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:orca\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">NWCHEM <\/td>\n<td align=\"left\">TD-DFT <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<sup>b<\/sup> <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:nwchem\">6.10<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:nwchem\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">TURBOMOLE <\/td>\n<td align=\"left\">ADC(2), CC2 <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<sup>c<\/sup> <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:turbomole\">6.11<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:turbomole\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MOLCAS <\/td>\n<td align=\"left\">RASSCF, (X)MS-CASPT2 <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"left\"><a href=\"#sec:int:molcas\">6.12<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:molcas\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MNDO <\/td>\n<td align=\"left\">OM2\/MRCI <\/td>\n<td align=\"left\">singlet <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:mndo\">6.13<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:mndo\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MOPACPI <\/td>\n<td align=\"left\">AM1\/FOMO-CI <\/td>\n<td align=\"left\">singlet <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">–<sup>d<\/sup> <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:mopac-pi\">6.14<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:mopac-pi\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">LEGACY <\/td>\n<td align=\"left\">SHARC legacy interface <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:legacy\">6.15<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:legacy\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Legacy ab initio interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">AMS_ADF <\/td>\n<td align=\"left\">TD-DFT <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<sup>b<\/sup> <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">–<\/td>\n<td align=\"center\">–<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:adf\">6.16<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:adf\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">COLUMBUS <\/td>\n<td align=\"left\">CASSCF, MRCISD <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<sup>e<\/sup> <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">–<\/td>\n<td align=\"center\">–<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:columbus\">6.17<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:columbus\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">BAGEL <\/td>\n<td align=\"left\">CASSCF, (X)MS-CASPT2 <\/td>\n<td align=\"left\">singlet <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">–<\/td>\n<td align=\"center\">–<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:bagel\">6.18<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:bagel\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MOLPRO <\/td>\n<td align=\"left\">CASSCF <\/td>\n<td align=\"left\">any <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">–<\/td>\n<td align=\"center\">–<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:molpro\">6.19<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:molpro\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">PYSCF <\/td>\n<td align=\"left\">CASSCF, CMS-PDFT <\/td>\n<td align=\"left\">singlet <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">√<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">– <\/td>\n<td align=\"center\">–<\/td>\n<td align=\"center\">–<\/td>\n<td align=\"center\">– <\/td>\n<td align=\"left\"><a href=\"#sec:int:pyscf\">6.20<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:pyscf\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Single-child hybrid interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ASE <\/td>\n<td align=\"left\">save data <\/td>\n<td colspan=\"11\" align=\"left\">Depends on child interface. <\/td>\n<td align=\"left\"><a href=\"#sec:int:ase_db\">6.21<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:ase_db\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">UMBRELLA <\/td>\n<td align=\"left\">add restraints <\/td>\n<td colspan=\"11\" align=\"left\">Depends on child interface. <\/td>\n<td align=\"left\"><a href=\"#sec:int:umbrella\">6.22<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:umbrella\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">NUMDIFF <\/td>\n<td align=\"left\">finite differences <\/td>\n<td colspan=\"11\" align=\"left\">Depends on child interface. <\/td>\n<td align=\"left\"><a href=\"#sec:int:numdiff\">6.23<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:numdiff\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Multi-child hybrid interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">QMMM <\/td>\n<td align=\"left\">el.-stat. embedding <\/td>\n<td colspan=\"11\" align=\"left\">Depends on child interfaces. <\/td>\n<td align=\"left\"><a href=\"#sec:int:qmmm\">6.24<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:qmmm\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ECI <\/td>\n<td align=\"left\">excitonic HF\/CI <\/td>\n<td colspan=\"11\" align=\"left\">Depends on child interfaces. <\/td>\n<td align=\"left\"><a href=\"#sec:int:eci\">6.25<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:eci\">pageref<\/a> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ADAPTIVE <\/td>\n<td align=\"left\">quorum-based <\/td>\n<td colspan=\"11\" align=\"left\">Depends on child interfaces. <\/td>\n<td align=\"left\"><a href=\"#sec:int:adaptive\">6.26<\/a> <\/td>\n<td align=\"left\"><a href=\"#sec:int:adaptive\">pageref<\/a> <\/td>\n<\/tr>\n<div class=\"p\"><!----><\/div>\n<p> √ available;<br \/>\n (√) only returns trivial results (zeros\/unit matrices);<br \/>\n <sup>a<\/sup> and wave function phases;<br \/>\n <sup>b<\/sup> TDMs only between S<sub>0<\/sub> and excited singlets;<br \/>\n <sup>c<\/sup> SOCs only between singlets and triplets;<br \/>\n <sup>d<\/sup> Has an internal QM\/MM implementation;<br \/>\n <sup>e<\/sup> either NAC or SOC, but not both at the same time;\n<\/div>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.0.2\"><\/a><\/p>\n<h3>\n6.0.2  Assoiated File Names and Example Directory<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Table <a href=\"#tab:interface_files\">6.2<\/a> shows the file names for interface-related input files of the different interfaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The directory <b><tt>$SHARC\/..\/examples\/<\/tt><\/b> contains comprehensively commented examples of these input files for all interfaces.<br \/>\nThese example files should be regarded as supplementary files to the documentation of the interfaces.<br \/>\nIn general, it is recommended that users copy the example template files and modify them to their needs, except for the few interfaces for which some automated template generation tool exists.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the subdirectories of <b><tt>$SHARC\/..\/examples\/<\/tt><\/b> are not intended for testing.<br \/>\nTo make functioning calculations out of the examples, some paths and variables in the resource files need to be adjusted.<br \/>\nIf you need automatically working test calculations for S<span style=\"font-size:x-small\">HARC<\/span>, consider using <b><tt>tests.py<\/tt><\/b> instead.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.2\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.2: Overview over files of S<span style=\"font-size:x-small\">HARC<\/span> interfaces.<\/div>\n<p> <a id=\"tab:interface_files\"><br \/>\n<\/a> <\/p>\n<table>\n<tr>\n<td align=\"left\">Interface <\/td>\n<td align=\"left\">Template file <\/td>\n<td align=\"left\">Resource file <\/td>\n<td align=\"left\">Initial MOs<\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Stub interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">DO_NOTHING <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">N\/A <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">QMOUT <\/td>\n<td align=\"left\"><b><tt>QMOUT.template<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">N\/A <\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Fast interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ANALYTICAL <\/td>\n<td align=\"left\"><b><tt>ANALYTICAL.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>ANALYTICAL.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">LVC <\/td>\n<td align=\"left\"><b><tt>LVC.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>LVC.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SPAINN <\/td>\n<td align=\"left\"><b><tt>SPAINN.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>SPAINN.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">OPENMM <\/td>\n<td align=\"left\"><b><tt>OPENMM.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>OPENMM.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Ab initio interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">GAUSSIAN <\/td>\n<td align=\"left\"><b><tt>GAUSSIAN.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>GAUSSIAN.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>GAUSSIAN.chk.<job>.init<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ORCA <\/td>\n<td align=\"left\"><b><tt>ORCA.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>ORCA.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>ORCA.gbw.<job>.init<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">NWCHEM <\/td>\n<td align=\"left\"><b><tt>NWCHEM.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>NWCHEM.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">TURBOMOLE <\/td>\n<td align=\"left\"><b><tt>TURBOMOLE.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>TURBOMOLE.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>mos.init<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MOLCAS <\/td>\n<td align=\"left\"><b><tt>MOLCAS.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>MOLCAS.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>MOLCAS.<mult>.RasOrb.init<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><tt>MOLCAS.<mult>.JobIph.init<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MNDO <\/td>\n<td align=\"left\"><b><tt>MNDO.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>MNDO.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MOPACPI <\/td>\n<td align=\"left\"><b><tt>MOPAC_PI.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>MOPAC_PI.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">LEGACY <\/td>\n<td align=\"left\"><b><tt>LEGACY.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>LEGACY.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Legacy ab initio interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">AMS_ADF <\/td>\n<td align=\"left\"><b><tt>AMS_ADF.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>AMS_ADF.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>AMS_ADF.t21.<job>.init<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">COLUMBUS <\/td>\n<td align=\"left\">a directory <\/td>\n<td align=\"left\"><b><tt>COLUMBUS.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>mocoef_mc.init.<job><\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">COLUMBUS <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\"><b><tt>molcas.RasOrb.init.<job><\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">BAGEL <\/td>\n<td align=\"left\"><b><tt>BAGEL.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>BAGEL.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>archive.<mult>.init<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MOLPRO <\/td>\n<td align=\"left\"><b><tt>MOLPRO.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>MOLPRO.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>wf.<job>.init<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">PYSCF <\/td>\n<td align=\"left\"><b><tt>PYSCF.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>PYSCF.resources<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>pyscf.init.chk<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Single-child hybrid interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">PIPE <\/td>\n<td align=\"left\"><b><tt>PIPE.template<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">N\/A <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ASE_DB <\/td>\n<td align=\"left\"><b><tt>ASE_DB.template<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">N\/A <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">UMBRELLA <\/td>\n<td align=\"left\"><b><tt>UMBRELLA.template<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<td align=\"left\">N\/A <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">NUMDIFF <\/td>\n<td align=\"left\"><b><tt>NUMDIFF.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>NUMDIFF.resources<\/tt><\/b> <\/td>\n<td align=\"left\">N\/A <\/td>\n<\/tr>\n<tr>\n<td colspan=\"2\" align=\"center\">– Multi-child hybrid interfaces –<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">QMMM <\/td>\n<td align=\"left\"><b><tt>QMMM.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>QMMM.resources<\/tt><\/b> <\/td>\n<td align=\"left\">N\/A <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ECI <\/td>\n<td align=\"left\"><b><tt>ECI.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>ECI.resources<\/tt><\/b> <\/td>\n<td align=\"left\">N\/A <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ADAPTIVE <\/td>\n<td align=\"left\"><b><tt>ADAPTIVE.template<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>ADAPTIVE.resources<\/tt><\/b> <\/td>\n<td align=\"left\">N\/A <\/td>\n<\/tr>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.0.3\"><\/a><\/p>\n<h3>\n6.0.3  Generic keywords in resource files of many interfaces<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Table <a href=\"#tab:resources\">6.3<\/a>, <a href=\"#tab:resources_aux\">6.4<\/a>, and <a href=\"#tab:resources_resp\">6.5<\/a> provides general information about keywords that are valid for the resource files of many interfaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.3\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.3: General keywords for the resource files. Which keywords are actually used depends on the interface.<\/div>\n<p> <a id=\"tab:resources\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scratchdir <\/td>\n<td align=\"left\">Is a path to the temporary directory. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. If it does not exist, the interface will create it. In any case, the interface will delete this directory after the calculation.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">savedir <\/td>\n<td align=\"left\">Is a path to another temporary directory. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. The interface will store files needed for restart there. <b>Is superseded by the savedir requested by the caller, so this keyword is usually optional in the resource file.<\/b>\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">retain <\/td>\n<td align=\"left\">Followed by an integer giving the number of old time steps to retain in the step file.<b> Is superseded by the retain setting from the caller, so this keyword is usually optional in the resource file.<\/b>\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">memory <\/td>\n<td align=\"left\">The memory usable by the interface. Behaviour is interface-specific.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ncpu <\/td>\n<td align=\"left\">The number of CPUs used by the interface. Is overridden by environment variables from queuing engines (e.g., <b><tt>$NSLOTS<\/tt><\/b> or <b><tt>$SLURM_NTASKS_PER_NODE<\/tt><\/b>). Parallel behaviour is interface-specific.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">min_cpu <\/td>\n<td align=\"left\">Minimum number of CPUs per job. Parallel behaviour is interface-specific.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ngpu <\/td>\n<td align=\"left\">The number of GPUs used by the interface. Parallel behaviour is interface-specific.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">schedule_scaling <\/td>\n<td align=\"left\">Gives the expected parallelizable fraction of the parallezable calculations (Amdahl’s law). With a value close to zero, the interface will try to run all jobs at the same time. With values close to one, jobs will be run sequentially with the maximum number of cores. Exact behaviour is interface-specific.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">delay <\/td>\n<td align=\"left\">Followed by a float giving the delay in seconds between starting parallel jobs to avoid excessive disk I\/O (usually not necessary).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">always_orb_init <\/td>\n<td align=\"left\">Do not use the orbital guesses from previous calculations\/time steps, but always use the provided initial orbitals.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">always_guess <\/td>\n<td align=\"left\">Always use the orbital guess from the quantum chemistry program.\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.4\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.4: Auxiliary-program-related keywords for the resource files. Which keywords are actually used depends on the interface.<\/div>\n<p> <a id=\"tab:resources_aux\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">wfoverlap <\/td>\n<td align=\"left\">Path to the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code. Needed for overlap and Dyson norm calculations in some interfaces.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">wfthres <\/td>\n<td align=\"left\">(float) Gives the amount of wave function norm which will be kept in the truncation of the determinant files. Default is interface-specific.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">numfrozcore <\/td>\n<td align=\"left\">Number of frozen core orbitals for overlap and Dyson norm calculations. A value of -1 enables automatic frozen core.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">wfnumocc <\/td>\n<td align=\"left\">Number of ignored occupied orbitals in Dyson calculations.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nooverlap <\/td>\n<td align=\"left\">Do not save determinant files for overlap computations.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">theodir <\/td>\n<td align=\"left\">Path to the T<span style=\"font-size:x-small\">HEO<\/span>DORE installation. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. The interface will set <b><tt>$PYTHONPATH<\/tt><\/b> automatically.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">theodore_prop <\/td>\n<td align=\"left\">Followed by a list with the descriptors which T<span style=\"font-size:x-small\">HEO<\/span>DORE should compute. Note that descriptors will only be computed for restricted singlets (and triplets). Instead of a simple list, a Python literal can also be used, as in the T<span style=\"font-size:x-small\">HEO<\/span>DORE input files.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">theodore_fragment <\/td>\n<td align=\"left\">Followed by a list of atom numbers which should constitute a fragment in T<span style=\"font-size:x-small\">HEO<\/span>DORE. For multiple fragments, the keyword can be used multiple times. Instead, the keyword can be followed by a Python literal, as in the T<span style=\"font-size:x-small\">HEO<\/span>DORE input files.\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.5\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.5: RESP-fitting-related keywords for the resource files. Which keywords are actually used depends on the interface.<\/div>\n<p> <a id=\"tab:resources_resp\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">resp_target <\/td>\n<td align=\"left\">Defines the target for the RESP restraint. Default is ‘zero’, but ‘mulliken’ and ‘lowdin’ can also be used.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">resp_layers <\/td>\n<td align=\"left\">Number of layers, default 4.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">resp_first_layer <\/td>\n<td align=\"left\">Factor for the radius of the innermost fitting layer. The other factors are computed as first + [0.4\/(√{n<sub>layers<\/sub>})]*i for i=0 to n<sub>layers<\/sub>−1. The actual radius of each fitting layer is the product of the factors times the VdW radius of the respective atom. Default is 1.4. Together with the default 4 layers, the layer factors are 1.4, 1.6, 1.8, 2.0 (as, e.g., in <span class=\"roman\">Gaussian<\/span>).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">resp_density <\/td>\n<td align=\"left\">Fitting point density in points per Å<sup>2<\/sup>. Default is 10.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">resp_fit_order <\/td>\n<td align=\"left\">Integer, 0, 1, or 2 for monopoles-only, monopoles+dipoles, or up to quadrupoles. Default 2.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">resp_grid <\/td>\n<td align=\"left\">String defining the spherical quadrature used. Possible are ‘lebedev’, ‘random’, ‘golden_spiral’, ‘gamess’, and ‘marcus_deserno’. Default is ‘lebedev’, which is the one with the highest inherent symmetry.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">resp_betas <\/td>\n<td align=\"left\">Parameters that define the strength of the restraint for the different fitting orders. Defaults are 0.0005, 0.0015, 0.003 for monopoles, dipoles, quadrupoles. See <a href=\"#Polonius2023JCTC\" class=\"tth_citeref\">[36<\/a>].\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">resp_mk_radii <\/td>\n<td align=\"left\">Use original Merz-Kollman radii for HCNOSP <a href=\"#Singh1984JCC\" id=\"CITESingh1984JCC\" class=\"tth_citation\">[100<\/a>]. Default is to use values from Ref. <a href=\"#Mantina2009JPCA\" id=\"CITEMantina2009JPCA\" class=\"tth_citation\">[101<\/a>] for all atoms.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">resp_vdw_radii <\/td>\n<td align=\"left\">Provide a list of VdW radii for all atoms, in Python syntax. Has precedence over <b><tt>resp_vdw_radii_symbol<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">resp_vdw_radii_symbol <\/td>\n<td align=\"left\">Provide a dictionary of VdW radii for all elements, in Python syntax.\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.1\"><\/a><\/p>\n<h2>\n6.1  Do-Nothing Interface<\/h2>\n<p><a id=\"sec:int:do_nothing\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Stub interface that returns all zeros.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>-Do-Nothing interface is a stub interface that returns zeros for all requested quantities (but unit overlaps and unity phases).<br \/>\nIn that sense, it supports every request, except for molecule\/density matrices.<br \/>\nIt is intended as a developers tool and cannot be used to carry out any actual investigations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface does not have any template or resource options and in fact does not even read either file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During setup, this interface asks a random question and writes the user’s reply to a file in the relevant directory.<br \/>\nThis file does not have any effect.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.2\"><\/a><\/p>\n<h2>\n6.2  QMout Interface<\/h2>\n<p><a id=\"sec:int:qmout\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Stub interface that returns constant energies and potential-like couplings, and zeros for other requests, for frozen-nuclei dynamics.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>-QMout interface is a stub interface intended for running dynamics with frozen nuclei, i.e., purely electronic dynamics.<br \/>\nAs such, it returns constant energies, spin-orbit couplings, dipole moments, and possibly multipolar density expansions, but otherwise returns zeros (but unit overlaps and unity phases).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Its name stems from the fact that it reads the constant energies, couplings, and other quantities from a <b><tt>QM.out<\/tt><\/b> file, as it is produced by all other interfaces.<br \/>\nNote that it ignores all content of this file except for energies, spin-orbit couplings, dipole moments, and multipolar density expansions.<br \/>\nWhen it is looking for the file, the assumed file name is <b><tt>QMout.template<\/tt><\/b>.<br \/>\nThe interface has no other options besides the contents of the <b><tt>QMout.template<\/tt><\/b> file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During setup, the interface asks first for the path to a template file.<br \/>\nIf this path leads to a <b><tt>QM.out<\/tt><\/b> file, it is used as is for all trajectories that are set up.<br \/>\nIf this path is a directory containing <b><tt>ICOND<\/tt><\/b> folders, then the <b><tt>QM.out<\/tt><\/b> file for <b><tt>TRAJ_XXXXX<\/tt><\/b> is automatically taken from <b><tt>ICOND_XXXXX<\/tt><\/b>.<br \/>\nThe interface then asks whether the <b><tt>QM.out<\/tt><\/b> files should be copied or linked.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.3\"><\/a><\/p>\n<h2>\n6.3  Analytical PESs Interface<\/h2>\n<p><a id=\"sec:int:analytical\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Fast interface for self-coded potential energy surfaces using SymPy.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This interface allows to run dynamics simulations on PESs expressed with analytical functions.<br \/>\nThe system Hamiltonian is defined in a diabatic representation, and the interface automatically diagonalizes this Hamiltonian to produce adiabatic states.<br \/>\nIf spin-orbit couplings are given, these are treated like in other interfaces (they are not diagonalized away), so that the interface returns data in the MCH representation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Since S<span style=\"font-size:x-small\">HARC<\/span>4, this interface requires the Python package <b><tt>sympy<\/tt><\/b>.<br \/>\nThis package is used to automatically find the derivatives of the Hamiltonian matrix elements, so that the derivatives do not have to be coded by hand, like in older S<span style=\"font-size:x-small\">HARC<\/span> versions.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs two additional input files, called <b><tt>ANALYTICAL.template<\/tt><\/b> and <b><tt>ANALYTICAL.resources<\/tt><\/b>.<br \/>\nThe former one contains the definitions of all analytical expressions, the second one contains two optional settings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, the interface can provide energies, SOCs, gradients, nonadiabatic couplings, overlaps and phases.<br \/>\nThe necessary data to compute overlaps with the previous time step are stored in main memory if the interface is in persistent mode, or in the save directory in non-persistent mode. Additionally, (transition)dipole moments can be defined.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.3.1\"><\/a><\/p>\n<h3>\n6.3.1  Parametrization<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interface has to be provided with analytical expressions for all matrix elements of the following matrices in the diabatic basis:<\/p>\n<ul>\n<li> Hamiltonian: <b>H<\/b>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> (Optionally) (Transition) dipole matrices for each polarization direction: <b>M<\/b><sub>i<\/sub>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> (Optionally) real and imaginary part of the SOC matrix: Σ\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>The diabatic Hamiltonian is diagonalized:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-4.png\">\n<\/td>\n<td width=\"1%\">(6.1)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>Then the following calculations lead to the MCH matrices which are passed to S<span style=\"font-size:x-small\">HARC<\/span>:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-5.png\">\n<\/td>\n<td width=\"1%\">(6.2)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-6.png\">\n<\/td>\n<td width=\"1%\">(6.3)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-7.png\">\n<\/td>\n<td width=\"1%\">(6.4)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-8.png\">\n<\/td>\n<td width=\"1%\">(6.5)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-9.png\">\n<\/td>\n<td width=\"1%\">(6.6)<\/td>\n<\/tr>\n<\/table>\n<p>The MCH Hamiltonian is the diagonalized diabatic Hamiltonian plus the SO matrix transformed into the MCH basis.<br \/>\nThe gradients in the MCH basis are obtained by transforming the derivative of the diabatic Hamiltonian (computed with <b><tt>sympy<\/tt><\/b>) into the MCH basis.<br \/>\nThe nonadiabatic coupling vectors are computed likewise.<br \/>\nThe dipole matrices are simply transformed into the MCH basis.<br \/>\nThe overlap matrix is the overlap of old and new transformation matrix.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.3.2\"><\/a><\/p>\n<h3>\n6.3.2  Template file: <b><tt>ANALYTICAL.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interface-specific input file is called <b><tt>ANALYTICAL.template<\/tt><\/b>. It contains the analytical expressions for all matrix elements mentioned above. All analytical expressions in this file are evaluated considering the atomic coordinates read from <b><tt>QM.in<\/tt><\/b> or passed by the caller.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The file consists of a file header and the file body.<br \/>\nThe file body consists of variable definition blocks and matrix blocks.<br \/>\nA commented template file is located in <b><tt>$SHARC\/..\/examples\/SHARC_ANALYTICAL\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Header  <\/b> <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The header looks similar to an xyz file:<\/p>\n<pre>\n2\n2\nI       xI       0       0\nBr      xBr      0       0\n<\/pre>\n<p>Here, the first line gives the number of atoms and the second line the number of states.<br \/>\nNote that this interface ignores whatever system charge is declared by the caller.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>On the remaining lines, each Cartesian component of the atomic coordinates is associated to a variable name, which can be used in the analytical expressions.<br \/>\nIf a zero (<b><tt>0<\/tt><\/b>) is given instead of a variable name, then the corresponding Cartesian coordinate is neglected.<br \/>\nIn the above example, the variable name <b><tt>xI<\/tt><\/b> is associated with the x coordinate of the first atom given in <b><tt>QM.in<\/tt><\/b>.<br \/>\nThe y and z coordinates of the first atom are neglected.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>All variable names must be <a href=\"https:\/\/docs.python.org\/2\/reference\/lexical_analysis.html#identifiers\">valid Python identifiers<\/a> and must not start with an underscore.<br \/>\nHence, all strings starting with a letter, followed by an arbitrary number of letters, digits and underscores, are valid.<br \/>\nIt is not allowed to use a variable name twice.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note, that the file header also contains the atom labels, which are just used for cross-checking against the atom labels in <b><tt>QM.in<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The file header must not contain comments, neither at the end of a line nor separate lines. Also, blank lines are not allowed in the header. After the last line of the header (where the variables for the n<sub>atom<\/sub>-th atom are defined), blank lines and comments can be used freely (except in matrix blocks).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Variable definition blocks  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Variable definition blocks can be used to store additional numerical values (beyond the atomic coordinates) in variables, which can then be used in the equations in the matrix blocks. The most obvious use for this is of course to define values which will appear several times in the equations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A variable definition block looks like:<\/p>\n<pre>\nVariables\nA1      0.067\ng1      0.996   # Trailing comment\n# Blank line with comment only\nR1      4.666\nEnd\n<\/pre>\n<p>Each block starts with the keyword “Variables” and is terminated with “End”. In-between, on each line a variable name and the corresponding numerical value (separated by blanks) can be given. Note that the naming conventions given above also apply to variables defined in these blocks. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>There can be any number of complete variable definitions blocks in the input file. All blocks are read first, before any matrix expressions are evaluated. Hence, the relative order of the variable blocks and the matrix blocks does not matter. Also, note that variable names must not appear twice, so variables cannot be redefined halfway through the file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Matrix blocks  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The most important information in the input file are of course contained in the expressions in the matrix blocks. In general, a matrix block has the following format:<\/p>\n<pre>\nMatrix_Identifier\nV11;\nV12;    V22;\nV13;    V23;    V33;\n...\n<\/pre>\n<p>The first line identifies the type of matrix. Those are valid identifiers:<\/p>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td width=\"197\"><b><tt>Hamiltonian<\/tt><\/b> <\/td>\n<td width=\"355\">Defines the Hamiltonian including the diabatic potential couplings.<\/td>\n<\/tr>\n<tr>\n<td width=\"197\"><b><tt>Dipole<\/tt><\/b> followed by 1, 2 or 3 <\/td>\n<td width=\"355\">(Transition) dipole moment matrix for Cartesian direction x, y or z, respectively.<\/td>\n<\/tr>\n<tr>\n<td width=\"197\"><b><tt>SOC<\/tt><\/b> followed by <b><tt>Re<\/tt><\/b> or <b><tt>Im<\/tt><\/b> <\/td>\n<td width=\"355\">Real or Imaginary (respectively) part of the spin-orbit coupling matrix Σ.<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>Since the interface searches the file for these identifiers starting from the top until it is found, for each matrix only the first block takes effect. Note, that the Hamiltonian must be present. If dipole matrix or SO matrix definitions are missing, they will be assumed zero.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the lines after the identifier, the expressions for each matrix element are given. Note the lower triangular format (all matrices are assumed symmetric, except the imaginary part of the SO matrix, which is assumed antisymmetric). Matrix elements must be separated by semicolons (so that whitespace can be used inside the expressions), including all end-of-lines (also the last line). There must be at least as many lines as the number of states (additional lines are neglected). If any line or matrix element is missing, the interface will abort.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>An exemplary block looks like:<\/p>\n<pre>\nHamiltonian\nA1*( (1.-exp(g1*(R1-xI+xBr)))**2-1.);\n0.0006;                                        3e-5*(xI-xBr)**2;\n<\/pre>\n<p>It is important to understand that the expressions are directly evaluated by <b><tt>sympy<\/tt><\/b>, hence all expressions must be valid Python\/<b><tt>sympy<\/tt><\/b> expressions which evaluate to numeric (integer or float) values. Only the variables defined above can be used.<br \/>\nNote that exponentiation in Python is <b><tt>**<\/tt><\/b>.<br \/>\nMathematical functions from <b><tt>sympy<\/tt><\/b>, e.g., <a href=\"https:\/\/docs.sympy.org\/latest\/modules\/functions\/elementary.html\">these elementary functions<\/a>, are available.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.3.3\"><\/a><\/p>\n<h3>\n6.3.3  Template file: <b><tt>ANALYTICAL.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The resource file of <b><tt>SHARC_ANALYTICAL.py<\/tt><\/b> knows only one keyword.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The keyword is <b><tt>diagonalize<\/tt><\/b>.<br \/>\nIt is true by default, but using <b><tt>diagonalize false<\/tt><\/b>, one can turn off diagonalization, so that one can run directly in the diabatic basis.<br \/>\nNote that this will give wrong results if the off-diagonal elements of the Hamiltonian are not constant.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.3.4\"><\/a><\/p>\n<h3>\n6.3.4  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_ANALYTICAL.py<\/tt><\/b> follows the standard initialization procedure during setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The first step is to locate the <b><tt>ANALYTICAL.template<\/tt><\/b> input file.<br \/>\nIf a file named <b><tt>ANALYTICAL.template<\/tt><\/b> exists in the current directory, it is suggested as a default.<br \/>\nOtherwise, the user is prompted to specify the correct path manually.<br \/>\nThis is repeated until a valid file is provided.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Once the template file is confirmed, it is automatically scanned for required keywords depending on the type of calculation requested.<br \/>\nIf <b><tt>SOC<\/tt><\/b> is among the requested properties (e.g., within <b><tt>setup_traj.py<\/tt><\/b>), the template file must contain a <b><tt>SOC<\/tt><\/b> section.<br \/>\nLikewise, for dipole-related requests (<b><tt>dm<\/tt><\/b> or <b><tt>dmdr<\/tt><\/b>), the <b><tt>Dipole<\/tt><\/b> section must be present.<br \/>\nOnce setup is finished, the provided template file is copied or symlinked into the working directory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the setup routine does not ask for a resource file.<br \/>\nIf you require one, you need to create and copy it manually.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.4\"><\/a><\/p>\n<h2>\n6.4  LVC Interface<\/h2>\n<p><a id=\"sec:int:lvc\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Fast interface for linear and quadratic vibronic coupling models, also with electrostatic embedding.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The purpose of the LVC interface is to allow performing computationally efficient dynamics using a linear vibronic coupling (LVC) or quadratic vibronic coupling (QVC) model <a href=\"#Koeppel84ACP\" id=\"CITEKoeppel84ACP\" class=\"tth_citation\">[102<\/a>].<br \/>\nThe relevant equations can be found in Section <a href=\"#met:lvc\">8.18<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, the interface can provide energies, SOCs, gradients, nonadiabatic couplings, overlaps, multipolar charges, and deal with point charges.<br \/>\nThe necessary data to compute overlaps with the previous time step are stored in main memory if the interface is in persistent mode, or in the save directory in non-persistent mode.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.4.1\"><\/a><\/p>\n<h3>\n6.4.1  Input files<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Two input files are needed:<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><b><tt>V0.txt<\/tt><\/b>  <\/b><br \/>\nContains all information to describe the reference harmonic oscillator V<sub>0<\/sub>: the equilibrium geometry, the frequencies ω<sub>i<\/sub>, and an orthogonal matrix containing the normal coordinates K<sub>αi<\/sub>.<\/p>\n<pre>\nGeometry\n S     16.    0.00000000    0.00000000   -0.00039079   31.97207180\n O      8.    0.00000000   -2.38362453    1.36159121   15.99491464\n O      8.    0.00000000    2.38362453    1.36159120   15.99491464\nFrequencies\n 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000  0.00234  0.0053  0.0064\nMass-weighted normal modes\n  0.0000  1.0000  0.0000  0.0000  0.0000  0.0000  0.0000  0.0000  0.0000\n  0.6564  0.0000  0.0000  0.3108  0.0494  0.2004  0.0000  0.0000 -0.6557\n...\n<\/pre>\n<p>Here, the reference geometry is given as element, nuclear charge, Cartesian coordinates (x\/y\/z, in Bohrs), and mass (in atomic mass units).<br \/>\nThe frequencies are given all on one line, in Hartree energy units.<br \/>\nThe normal mode transformation matrix is given with one column per normal mode (same order as the frequencies) and with three lines per atom (x\/y\/z, same order as in the reference geometry).<br \/>\n<b><tt>V0.txt<\/tt><\/b> can be created from a M<span style=\"font-size:x-small\">OLDEN<\/span> file using <b><tt>wigner.py -l<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><b><tt>LVC.template<\/tt><\/b>  <\/b><br \/>\nContains the state-specific information:<br \/>\nϵ<sub>i<\/sub>,<br \/>\nκ<sub>i<\/sub><sup>(n)<\/sup>,<br \/>\nλ<sub>j<\/sub><sup>(m,n)<\/sup>,<br \/>\nγ<sub>ij<\/sub><sup>(m,n)<\/sup>,<br \/>\nη<sub>mn<\/sub>,<br \/>\nΛ<sub>i<\/sub><sup>(m,n)<\/sup>,<br \/>\nP<sup>(m,n)<\/sup><sub>apb<\/sub>,<br \/>\nas well as (transition) dipole moments (see Section <a href=\"#met:lvc\">8.18<\/a>).<br \/>\nHere, for multiplets most parameters are are shared between the multiplet components, whereas in the SOC and dipole moment matrices the multiplet components are provided explicitly.<\/p>\n<pre>\nV0.txt\n4 0 3 \nepsilon\n7\n  1   1  0.0000000000\n  1   2  0.1640045037\n  1   3  0.1781507393\n  1   4  0.2500917150\n  3   1  0.1341247878\n  3   2  0.1645714941\n  3   3  0.1700512159\nkappa\n12\n  1   2     7  1.19647e-03\n  1   2     8  1.21848e-02\n...\nlambda\n3\n  1   1   4     9 -1.83185e-02\n  1   2   3     9  7.32022e-03\n  3   1   3     9  5.71746e-03\nlambda_soc\n0\ngamma\n0\nSOC R\n  0.000e+00  0.000e+00  0.000e+00  0.000e+00  0.000e+00  0.000e+00 ...\n  0.000e+00  0.000e+00  0.000e+00  0.000e+00  0.000e+00 -1.086e-04 ...\n...\nSOC I\n  0.000e+00  0.000e+00  0.000e+00  0.000e+00  0.000e+00  0.000e+00 ...\n  0.000e+00  0.000e+00  0.000e+00  1.000e+00  0.000e+00  1.000e-04 ...\n...\nDMX R\n -7.400e-07 -1.639e-01  0.000e+00  3.000e-06  0.000e+00  0.000e+00  ...\n -1.639e-01  3.930e-06  0.000e+00  2.400e-05  0.000e+00  0.000e+00  ...\n...\nDMX I\n...\nDMY R\n...\nDMY I\n...\nDMZ R\n...\nDMZ I\n...\nMultipolar Density Fit\n72\n1  1  1   0     -0.081  0.135  0.000 -0.000 -0.114  0.093  0.020 -0.000  0.000 -0.000\n1  1  1   1     -0.138 -0.123  0.000 -0.000  0.645 -2.028  1.382  0.000  0.000 -0.000\n1  1  1   2      0.109 -0.015 -0.030 -0.000 -0.137  0.161 -0.023  0.089  0.000  0.000\n1  1  1   3      0.109 -0.015  0.030  0.000 -0.137  0.161 -0.023 -0.089 -0.000  0.000\n1  1  2   0      0.000 -0.000  0.000  0.000  0.000 -0.000 -0.000  0.000 -0.000 -0.297\n1  1  2   1     -0.000  0.000 -0.000  0.000 -0.000 -0.000  0.000 -0.000  0.000  2.286\n1  1  2   2     -0.000  0.000  0.000  0.119 -0.000  0.000 -0.000 -0.000 -0.038 -0.217\n1  1  2   3      0.000  0.000  0.000 -0.119  0.000  0.000 -0.000  0.000  0.038 -0.217\n...\n<\/pre>\n<p>Only the three first lines are mandatory, but if no other parameters are given, all states will have the same potentials (the ground state potential).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.4.2\"><\/a><\/p>\n<h3>\n6.4.2  Resource file<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, the interface also got a <b><tt>LVC.resource<\/tt><\/b> file.<br \/>\nIt only knows two keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The first keyword is <b><tt>diagonalize<\/tt><\/b>.<br \/>\nIt is true by default, but using <b><tt>diagonalize false<\/tt><\/b>, one can turn off diagonalization, so that one can run directly in the diabatic basis.<br \/>\nNote that this will give wrong gradients\/NACs if any non-zero λ terms are present.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The second keyword is <b><tt>do_kabsch<\/tt><\/b>.<br \/>\nIf set to <b><tt>true<\/tt><\/b>, the Kabsch algorithm will be used to align the current geometry with the reference geometry.<br \/>\nBy default, it is true of point charges are present.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.4.3\"><\/a><\/p>\n<h3>\n6.4.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_LVC.py<\/tt><\/b> follows the standard initialization procedure during setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The first step is to locate the <b><tt>LVC.template<\/tt><\/b> input file.<br \/>\nIf a file named <b><tt>LVC.template<\/tt><\/b> exists in the current directory, it is suggested as a default.<br \/>\nOtherwise, the user is prompted to specify the correct path manually.<br \/>\nThis process is repeated until a valid file is provided.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Once the template file is confirmed, it is automatically scanned for required sections based on the requested properties.<br \/>\nFor spin-orbit coupling (<b><tt>soc<\/tt><\/b>), either <b><tt>SOC<\/tt><\/b> or <b><tt>lambda_soc<\/tt><\/b> must appear in the template.<br \/>\nIf dipole moments are requested (<b><tt>dm<\/tt><\/b>), the file must contain a <b><tt>DM<\/tt><\/b> section.<br \/>\nRequests involving <b><tt>point_charges<\/tt><\/b> or <b><tt>multipolar_fit<\/tt><\/b> require the presence of the <b><tt>Multipolar Density Fit<\/tt><\/b> section.<br \/>\nIf any required section is missing, the setup terminates with an error.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After the template check, the user is asked whether an <b><tt>LVC.resources<\/tt><\/b> file is available.<br \/>\nIf so, the file path must be specified.<br \/>\nIf not, the user is prompted whether to enable the Kabsch algorithm, which aligns molecular geometries.<br \/>\nIf selected, a simple resource file containing the line <b><tt>do_kabsch true<\/tt><\/b> is created automatically in the working directory during preparation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>As in the analytical interface, the setup routine copies or symlinks all required files into the working directory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.4.4\"><\/a><\/p>\n<h3>\n6.4.4  Template File Setup: <b><tt>wigner.py<\/tt><\/b>, <b><tt>setup_LVCparam.py<\/tt><\/b>, <b><tt>create_LVCparam.py<\/tt><\/b>, <b><tt>modify_LVC_template.py<\/tt><\/b><\/h3>\n<p><a id=\"sec:setup_LVCparam.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Reference potential  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>V0.txt<\/tt><\/b> is created using the <b><tt>wigner.py<\/tt><\/b> script, which is also used for initial condition generation. Simply call, e.g.<br \/>\n<b><tt>$SHARC\/wigner.py -l <filename.molden><\/tt><\/b><br \/>\nNote that this best works if all 3N normal modes are present in the file.<br \/>\nIf the translations and rotations are missing, the script will add the necessary number of zero-vector modes.<br \/>\nIf you experience a failure in <b><tt>wigner.py<\/tt><\/b>, please try first to provide a molden file with sufficient numerical precision.<br \/>\nIt is also advisable to properly symmetrize the relevant frequency calculation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Setup for single point calculations  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>To obtain the LVC parameters, two steps are necessary: (i) running quantum chemistry calculations, and (ii) converting the quantum chemistry output to the LVC parameters.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The first of these steps is carried out with <b><tt>setup_LVCparam.py<\/tt><\/b>.<br \/>\nIt is an interactive script that works very similarly to the other setup scripts (e.g., <b><tt>setup_init.py<\/tt><\/b>, <b><tt>setup_traj.py<\/tt><\/b>).<br \/>\nThe script will ask for the following:<\/p>\n<ul>\n<li> Path to the <b><tt>V0.txt<\/tt><\/b> file,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Number of states,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Charge per multiplicity,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Which interface to use (in principle, all S<span style=\"font-size:x-small\">HARC<\/span>-interfaces can be used, but only the ab initio interfaces are useful here),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Whether spin-orbit couplings should be calculated (only if applicable),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Whether linear SOC terms should be computed (only if applicable),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Whether κ parameters should be obtained from analytical gradients or numerical differentiation (depends on availability of analytical gradients),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Whether to compute intrastate quadratic terms γ<sub>ii<\/sub><sup>(αα)<\/sup> (other γ terms cannot be obtained automatically at this time) and how they are computed,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Whether to compute γ<sub>ii<\/sub><sup>(αα)<\/sup> only for selected states (only if applicable),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Whether λ parameters should be obtained from analytical nonadiabatic coupling vectors or numerical differentiation (depends on availability of analytical nonadiabatic coupling vectors),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Which normal modes to include,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Which normal modes to consider for quadratic terms γ<sub>ii<\/sub><sup>(αα)<\/sup> (only if applicable),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Which displacement value to use for numerical differentiation (default 0.05 dimensionless mass-frequency scaled units),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Whether intruder states should be ignored or not,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Whether one- or two-sided differentiation should be done,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Whether multipolar charges should be included for LVC\/MM,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interface-specific input for the chosen quantum chemistry interface (see in the individual interface’s sections in Chapter <a href=\"#chap:interfaces\">6<\/a>).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<p>The script will set up a directory (<b><tt>DSPL_RESULTS<\/tt><\/b>) with one subdirectory for each single point calculation.<br \/>\nIf all terms are computed analytically, then only the <b><tt>DSPL_000_eq<\/tt><\/b> subdirectory will be present.<br \/>\nOtherwise, for each chosen normal mode 1-2 subdirectories (for one-sided or two-sided differentiation) will be present (possibly more if γ terms are requested).<br \/>\nAdditionally, <b><tt>displacements.log<\/tt><\/b> presents the most important settings.<br \/>\nIn all cases, <b><tt>displacements.json<\/tt><\/b> is also present; this file is crucial to communicate all settings to the read-out script after the single point jobs are finished.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Creating LVC parameter files  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>After all jobs are successfully finished (<b><tt>QM.out<\/tt><\/b> file present in each directory), run <b><tt>create_LVCparam.py<\/tt><\/b> inside the <b><tt>DSPL_RESULTS<\/tt><\/b> directory.<br \/>\nThis is a fully automatic script that reads <b><tt>displacements.json<\/tt><\/b> and the <b><tt>QM.out<\/tt><\/b> files in the subdirectories.<br \/>\nAfter everything is successfully read, it creates the <b><tt>LVC.template<\/tt><\/b> file.<br \/>\nThis file can be used to run S<span style=\"font-size:x-small\">HARC<\/span>-LVC trajectories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Modifying LVC parameters  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Sometimes, one wants to remove certain normal modes or diabatic states from an LVC model, e.g., to investigate the influence of these modes\/states.<br \/>\nThis can be done with the command line tool <b><tt>modify_LVC_template.py<\/tt><\/b>.<br \/>\nA tooltip is available with the <b><tt>-h<\/tt><\/b> option.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Currently, it is only possible to remove the highest diabatic states in each multiplicity.<br \/>\nFor example, a template file with 4 singlets and 3 triplets can be reduced to the lowest 2 singlets and 2 triplets.<br \/>\nIn contrast, any modes can be removed by providing a selection string.<br \/>\nFor example, <b><tt>\"712,14,1589\"<\/tt><\/b> selects modes 7-12, 14, and 15-89, i.e., it removes modes modes 1-6, 13, and any modes after 89.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script also has the three options <b><tt>-no-transition-multipoles<\/tt><\/b>, <b><tt>-no-es2es-transition-multipoles<\/tt><\/b>, as well as <b><tt>-no-es2es-transition-multipoles-for-mult<\/tt><\/b> that can be used to remove multipolar charges that represent transition densities.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.5\"><\/a><\/p>\n<h2>\n6.5  SPaiNN Interface<\/h2>\n<p><a id=\"sec:int:spainn\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Fast interface to run machine learning potential energy surface models based on the PaiNN architecture.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– SPAINN interface allows to run S<span style=\"font-size:x-small\">HARC<\/span> simulations with machine learning potentials using SchNetPack 2.0.<br \/>\nNeither spin-orbit couplings or overlaps can be computed, but NACs are available.<br \/>\nThe interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>SPAINN.template<\/tt><\/b>) and a resource file (<b><tt>SPAINN.resources<\/tt><\/b>). For more information on how to use SPaiNN visit the <a href=\"https:\/\/spainn.readthedocs.io\/\">SPaiNN documentation<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.5.1\"><\/a><\/p>\n<h3>\n6.5.1  Template file: <b><tt>SPAINN.template<\/tt><\/b><\/h3>\n<p>This file contains the specifications for the machine learning potential prediction. The file only contains a number of keywords, given in table <a href=\"#tab:spainn_temp\">6.6<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A fully commented template file-with all possible options, a comprehensive descriptions, and some practical hints-is located in <b><tt>$SHARC\/..\/examples\/SHARC_SPAINN\/SPAINN.template<\/tt><\/b>.<br \/>\nWe recommend that users start from this template file and modify it appropriately for their calculations.<br \/>\nTo install SPaiNN clone the repository from GitHub and install with pip.<\/p>\n<pre>\n    git clone https:\/\/github.com\/CompPhotoChem\/SPaiNN.git\n    cd SPaiNN\n    pip install .\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.6\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.6: Keywords for the <b><tt>SPAINN.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:spainn_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">cutoff <\/td>\n<td align=\"left\">Cutoff radius for the cutoff function. Note: This should match with the cutoff radius used for training!\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nac_key <\/td>\n<td align=\"left\">“nacs” or ßmooth_nacs”.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">properties <\/td>\n<td align=\"left\">List of properties that will be predicted. E.g. [ënergy”, “forces”, “dipoles”, “nacs”]\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.5.2\"><\/a><\/p>\n<h3>\n6.5.2  Resource file: <b><tt>SPAINN.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>SPAINN.resources<\/tt><\/b> contains only the path to the SPaiNN model.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.7\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.7: Keywords for the <b><tt>SPAINN.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:spainn_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">modelpath <\/td>\n<td align=\"left\">Path to the trained SPaiNN model. Note that the model cannot be easily verified by the interface at the start. You will obtain an error if you request more states than are in the model or properties that the model cannot predict.\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.5.3\"><\/a><\/p>\n<h3>\n6.5.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_SPAINN.py<\/tt><\/b> follows the standard initialization procedure during setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The setup begins by locating the <b><tt>SPAINN.template<\/tt><\/b> input file.<br \/>\nIf a file with this name exists in the current directory, the user is asked whether it should be used.<br \/>\nIf no such file is present, or the user declines, a valid path must be specified manually.<br \/>\nThis process is repeated until a valid file is provided.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the machine learning model that is referenced in the template file will not be validated.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the user is asked whether a <b><tt>SPAINN.resources<\/tt><\/b> file is available.<br \/>\nIf so, the path to this file must be entered, and the file must exist.<br \/>\nIf no such file is available, the user is prompted for the location of a trained SPaiNN model via the <b><tt>modelpath<\/tt><\/b> field.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During preparation, the provided template is copied or symlinked into the working directory.<br \/>\nIf a resource file was provided during setup, it is also copied or linked.<br \/>\nOtherwise, a new <b><tt>SPAINN.resources<\/tt><\/b> file is created automatically containing the <b><tt>modelpath<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.6\"><\/a><\/p>\n<h2>\n6.6  SCHNARC Interface<\/h2>\n<p><a id=\"sec:int:schnarc\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Fast interface to run machine learning potential energy surface models based on the Schnet and FieldSchnet architectures.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– SCHNARC interface allows to run S<span style=\"font-size:x-small\">HARC<\/span>simulations with machine learning potentials using SchNetPack 1.0.<br \/>\nWhile the interface is principally able to deliver NACs and spin-orbit couplings (like previous versions), this functionality in the current version has not been tested.<br \/>\nWe therefore recommend to use the time derivative based couplings (<b><tt>coupling ktdc<\/tt><\/b>), also because couplings between different states are notoriously hard to train.<br \/>\nSince ML machine learned potentials do provide a wave function, overlaps cannot be computed.<br \/>\nThis interface can accept point charges and uses the FieldSchNet approach to perform a form of electrostatic embedding.<br \/>\nThe interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>SCHNARC.template<\/tt><\/b>) and a resource file (<b><tt>SCHNARC.resources<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>To install SchNarc you first should clone <a href=\"https:\/\/github.com\/atomistic-machine-learning\/schnetpack\/tree\/schnetpack1.0\">SchNetPack 1.0<\/a> from Github.<br \/>\nYou can then clone <a href=\"https:\/\/github.com\/schnarc\/SchNarc\">SchNarc<\/a> from Github.<br \/>\nThe installation guide provided on the website is for an older S<span style=\"font-size:x-small\">HARC<\/span> version, so we do not recommend following it.<br \/>\nInstead use <b><tt>pip<\/tt><\/b> to install the package.<br \/>\nIf you want to use electrostatic embedding in order to run QM\/MM simulations, you have to install <a href=\"https:\/\/github.com\/atomistic-machine-learning\/field_schnet\">FieldSchNet<\/a> and use the files from <a href=\"https:\/\/doi.org\/10.5281\/zenodo.14536036\">Zenodo<\/a> substituting the ones from SchNarc.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.6.1\"><\/a><\/p>\n<h3>\n6.6.1  Template file: <b><tt>SCHNARC.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the machine learning potential prediction.<br \/>\nA fully commented template file-with all possible options, a comprehensive descriptions, and some practical hints-is located in <b><tt>$SHARC\/..\/examples\/SHARC_SCHNARC\/SCHNARC.template<\/tt><\/b>.<br \/>\nWe recommend that users start from this template file and modify it appropriately for their calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.6.2\"><\/a><\/p>\n<h3>\n6.6.2  Template file: <b><tt>SCHNARC.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>SCHNARC.template<\/tt><\/b> contains only the keyword <b><tt>modelpath<\/tt><\/b>, which is the path to the SchNarc model.<br \/>\nThis should ideally be an absolute path.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.6.3\"><\/a><\/p>\n<h3>\n6.6.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_SCHNARC.py<\/tt><\/b> follows the standard initialization procedure during setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The setup process begins by identifying the <b><tt>SCHNARC.template<\/tt><\/b> file.<br \/>\nIf this file is found in the current directory, the user is asked whether it should be used.<br \/>\nIf not, or if declined, the user must manually provide a valid path to the template file.<br \/>\nThis continues until a valid file is confirmed.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The template file has only a single keyword, which is <b><tt>modelpath<\/tt><\/b>, which specifies the path to the a pytorch model using either the SCHNARC or FieldSchNet architecture. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>During preparation, the template file is either copied or symlinked into the working directory, depending on the configuration.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.7\"><\/a><\/p>\n<h2>\n6.7  OpenMM Interface<\/h2>\n<p><a id=\"sec:int:openmm\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Fast interface for molecular mechanics force fields via the OpenMM package, for one state.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This interface implements molecular mechanics force fields using <a href=\"https:\/\/openmm.org\/\">OpenMM<\/a>.<br \/>\nGiven the nature of force fields, this interface can only provide results for a single state which formally is assumed a singlet.<br \/>\nThe interface is written to work with A<span style=\"font-size:x-small\">MBER<\/span>-style <b><tt>prmtop<\/tt><\/b> files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, the interface can provide energies, dipole moments, gradients, and multipolar charges (although only monopole terms will be nonzero).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.7.1\"><\/a><\/p>\n<h3>\n6.7.1  Template file<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The template file <b><tt>OPENMM.template<\/tt><\/b> only knows one keyword, <b><tt>prmtop<\/tt><\/b>, which provides the path to the prmtop file that defines the system and force field.<br \/>\nIn principle, any prmtop file generated with <b><tt>tleap<\/tt><\/b> or other A<span style=\"font-size:x-small\">MBERTOOLS<\/span> should be compatible with the interface, given that the topology is correct.<br \/>\nPrmtop files for QM\/MM calculations can be created with <b><tt>setup_from_prmtop.py<\/tt><\/b>, see Section <a href=\"#sec:setup_from_prmtop.py\">7.12<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.7.2\"><\/a><\/p>\n<h3>\n6.7.2  Resource file<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The resource file<b><tt>OPENMM.resources<\/tt><\/b> knows two keywords.<br \/>\nThe first is <b><tt>ncpu<\/tt><\/b>, which defines the number of CPU cores to be used.<br \/>\nThe second is <b><tt>cuda_device<\/tt><\/b>, which accepts an integer that defines the CUDA device to be used.<br \/>\nIf this keyword is given, OpenMM is switched from the CPU platform to the CUDA platform.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.7.3\"><\/a><\/p>\n<h3>\n6.7.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_OPENMM.py<\/tt><\/b> follows the standard setup procedure used by other interfaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The user is prompted to specify the path to the <b><tt>OPENMM.template<\/tt><\/b> file.<br \/>\nThe system will attempt to read the specified file using its internal parser.<br \/>\nIf any issue arises (e.g., invalid formatting, missing files, etc.), the parser is reset and the user is asked again.<br \/>\nThis process repeats until a valid template is provided.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>From the parsed template, the necessary <b><tt>prmtop<\/tt><\/b> file is extracted and stored as an extra input file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, the user is asked whether they have an <b><tt>OPENMM.resources<\/tt><\/b> file.<br \/>\nIf confirmed, they must provide a valid path to it.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During the preparation phase, all required files (template, <b><tt>prmtop<\/tt><\/b>, and optional resources) are either copied or symlinked into the working directory depending on the configuration.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.8\"><\/a><\/p>\n<h2>\n6.8   G<span style=\"font-size:x-small\">AUSSIAN<\/span> Interface<\/h2>\n<p><a id=\"sec:int:gaussian\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Ab initio interface for TD-DFT in Gaussian 16.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– G<span style=\"font-size:x-small\">AUSSIAN<\/span> interface allows to run S<span style=\"font-size:x-small\">HARC<\/span> simulations with G<span style=\"font-size:x-small\">AUSSIAN<\/span>‘s TD-DFT functionality.<br \/>\nThe interface is compatible with restricted and unrestricted ground states (i.e., with all multiplicities), but not with symmetry.<br \/>\nSpin-orbit couplings cannot be computed, but wave function overlaps from the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code are available (no nonadiabatic couplings).<br \/>\nDyson norms can also be computed through the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code.<br \/>\n T<span style=\"font-size:x-small\">HEO<\/span>DORE (version 2.0 or higher) can be used to perform automatic wave function analysis.<br \/>\nFurthermore, in S<span style=\"font-size:x-small\">HARC<\/span>4 the interface can do electrostatic embedding with point charges (gradients on point charges available).<br \/>\nFinally, it can extract and return a P<span style=\"font-size:x-small\">Y<\/span>SCF <b><tt>mol<\/tt><\/b> object (containing the atomic orbital basis set) and corresponding one-particle (state\/transition) density matrices, as well as multipolar fits of these density matrices.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>GAUSSIAN.template<\/tt><\/b>) and a resource file (<b><tt>GAUSSIAN.resources<\/tt><\/b>).<br \/>\nIf files <b><tt>QM\/GAUSSIAN.chk.init<\/tt><\/b> or <b><tt>QM\/GAUSSIAN.chk.<job>.init<\/tt><\/b> are present, they are used to provide an initial orbital guess for the SCF calculation of the respective job.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.8.1\"><\/a><\/p>\n<h3>\n6.8.1  Template file: <b><tt>GAUSSIAN.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the quantum chemistry calculation. Note that this is not a valid G<span style=\"font-size:x-small\">AUSSIAN<\/span> input file. The file only contains a number of keywords, given in table <a href=\"#tab:gauss_temp\">6.8<\/a>. The actual input for G<span style=\"font-size:x-small\">AUSSIAN<\/span> will be generated automatically through the interface.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A fully commented template file-with all possible options, a comprehensive descriptions, and some practical hints-is located in <b><tt>$SHARC\/..\/examples\/SHARC_GAUSSIAN\/GAUSSIAN.template<\/tt><\/b>.<br \/>\nWe recommend that users start from this template file and modify it appropriately for their calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.8\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.8: Keywords for the <b><tt>GAUSSIAN.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:gauss_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis <\/td>\n<td align=\"left\">Gives the basis set for all atoms (default def2svp). <b>Note that wave function overlaps are likely wrong with Pople basis sets<\/b> and other basis sets with shared SP shells (e.g., STO-3G).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">functional <\/td>\n<td align=\"left\">followed by one string giving the exchange-correlation functional. Default is <b><tt>PBEPBE<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dispersion <\/td>\n<td align=\"left\">Activates dispersion correction. Arguments are written verbatim to G<span style=\"font-size:x-small\">AUSSIAN<\/span> input (in <b><tt>EmpiricalDispersion=()<\/tt><\/b>). Default is no dispersion. An example argument would be <b><tt>GD3<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scrf <\/td>\n<td align=\"left\">Activates solvation. All arguments (e.g., <b><tt>iefpcm solvent=water<\/tt><\/b>) are copied to G<span style=\"font-size:x-small\">AUSSIAN<\/span> input (in <b><tt>scrf=()<\/tt><\/b>).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">grid <\/td>\n<td align=\"left\">Followed by a string (e.g., <b><tt>grid finegrid<\/tt><\/b>) defining which integration grid and accuracy to use. For details, see the example template file.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">denfit <\/td>\n<td align=\"left\">Activates density fitting, which might speed up the computation.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scf <\/td>\n<td align=\"left\">Arguments are written verbatim to G<span style=\"font-size:x-small\">AUSSIAN<\/span> input (in <b><tt>scf=()<\/tt><\/b>).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">no_tda <\/td>\n<td align=\"left\">This keyword deactivates TDA, which the interface requests by default.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">td_conv <\/td>\n<td align=\"left\">This sets the TD-DFT convergence threshold to 10<sup>−X<\/sup>. Default is 6.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">unrestricted_triplets <\/td>\n<td align=\"left\">Requests that the triplets are calculated in a separate job from an unrestricted ground state. Default is to compute triplets as linear response of the restricted singlet ground state.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">noneqsolv <\/td>\n<td align=\"left\">Adds <b><tt>noneqsolv<\/tt><\/b> to the <b><tt>td=()<\/tt><\/b> block.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">neglected_gradient <\/td>\n<td align=\"left\">String that is ‘zero’, ‘gs’, or ‘closest’ (default ‘zero’) to control how non-requested gradients are set.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">state_densities <\/td>\n<td align=\"left\">Uses <b><tt>density=current<\/tt><\/b> for all dipole moments and state densities.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">iop <\/td>\n<td align=\"left\">Arguments are written verbatim to G<span style=\"font-size:x-small\">AUSSIAN<\/span> input (in <b><tt>iop=()<\/tt><\/b>). Expert option.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">keys <\/td>\n<td align=\"left\">Arguments are written verbatim to G<span style=\"font-size:x-small\">AUSSIAN<\/span> input as separate keywords. Expert option.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis_external <\/td>\n<td align=\"left\">Pastes the content of the given file after the geometry in the G<span style=\"font-size:x-small\">AUSSIAN<\/span> input file. Also sets the basis set to <b><tt>gen<\/tt><\/b>. Expert option.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">paste_input_file <\/td>\n<td align=\"left\">Pastes the content of the given file after the external basis block in the G<span style=\"font-size:x-small\">AUSSIAN<\/span> input file. Expert option.\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.8.2\"><\/a><\/p>\n<h3>\n6.8.2  Resource file: <b><tt>GAUSSIAN.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>GAUSSIAN.resources<\/tt><\/b> contains mainly paths (to the G<span style=\"font-size:x-small\">AUSSIAN<\/span> executables, to the scratch directory, etc.) and other resources, plus settings for <b><tt>wfoverlap.x<\/tt><\/b> and T<span style=\"font-size:x-small\">HEO<\/span>DORE. This file must reside in the same directory where the interface is started. It uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The G<span style=\"font-size:x-small\">AUSSIAN<\/span> interface employs essentially all keywords from Tables <a href=\"#tab:resources\">6.3<\/a>, <a href=\"#tab:resources_aux\">6.4<\/a>, and <a href=\"#tab:resources_resp\">6.5<\/a> (except: ngpu), as it uses W<span style=\"font-size:x-small\">FOVERLAP<\/span>, T<span style=\"font-size:x-small\">HEO<\/span>DORE, as well as the RESP module.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:gauss_sh2\">6.9<\/a>.<br \/>\nA fully commented resource file with possible options and descriptions is located in <b><tt>$SHARC\/..\/examples\/SHARC_GAUSSIAN\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.9\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.9: Keywords for the <b><tt>GAUSSIAN.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:gauss_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">groot <\/td>\n<td align=\"left\">Is the path to the G<span style=\"font-size:x-small\">AUSSIAN<\/span> installation directory. This directory should contain the G<span style=\"font-size:x-small\">AUSSIAN<\/span> executables, e.g., <b><tt>g09<\/tt><\/b>\/<b><tt>g16<\/tt><\/b>, <b><tt>l9999.exe<\/tt><\/b>, etc. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. The interface will set <b><tt>$GAUSS_EXEDIR<\/tt><\/b> to this path.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dry_run <\/td>\n<td align=\"left\">If set to true, will not clean the scratchdir, write input files, or run Gaussian calculations. It will perform overlap, TheoDORE, and RESP calculations, and parse output.\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p><b>Parallelization  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p> G<span style=\"font-size:x-small\">AUSSIAN<\/span> usually shows very good parallel scaling for most TD-DFT calculations.<br \/>\nHowever, it is more efficient to carry out multiple G<span style=\"font-size:x-small\">AUSSIAN<\/span> calculations (different multiplicities, multiple gradients) in parallel, each one using a smaller number of CPUs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the S<span style=\"font-size:x-small\">HARC<\/span>– G<span style=\"font-size:x-small\">AUSSIAN<\/span> interface, parallelization is controlled by the keywords <b><tt>ncpu<\/tt><\/b>, <b><tt>schedule_scaling<\/tt><\/b>, and <b><tt>min_cpu<\/tt><\/b>.<br \/>\nThe first keyword controls the maximum number of CPUs which the interface is allowed to use for all G<span style=\"font-size:x-small\">AUSSIAN<\/span> runs simultaneously.<br \/>\nThe second keyword is the parallel fraction from Amdahl’s Law, see Section <a href=\"#met:amdahl\">8.3<\/a>.<br \/>\nWith a value close to zero, the interface will try to run all jobs at the same time. With values close to one, jobs will be run sequentially with the maximum number of cores.<br \/>\nTypical values for <b><tt>schedule_scaling<\/tt><\/b> are around 0.90 for both GGA functionals and hybrid functionals, possibly less for very small computations.<br \/>\nThe third keyword defines how many cores to use at least for each calculation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.8.3\"><\/a><\/p>\n<h3>\n6.8.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The GAUSSIAN interface setup begins with the specification of the GAUSSIAN root directory.<br \/>\nThe script first attempts to retrieve the path from environment variables (<b><tt>$g16root<\/tt><\/b> or <b><tt>$g09root<\/tt><\/b>).<br \/>\nIf not found, it prompts the user to manually input the path, expanding the path if necessary.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the user is asked to specify a scratch directory for the GAUSSIAN calculations.<br \/>\nNote that the path is not validated by the script, as the calculations may be run on a different machine.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script will then check for the presence of a valid <b><tt>GAUSSIAN.template<\/tt><\/b> file.<br \/>\nIf a valid file is detected, the user is prompted to confirm if it should be used.<br \/>\nOtherwise, the user must specify the path to a valid template file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>While specifying the template file, the script also checks if additional files are referenced within the template, such as <b><tt>basis_external<\/tt><\/b> or <b><tt>paste_input_file<\/tt><\/b>, and adds them to the list of files for setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The user is then prompted to provide a restart file (GAUSSIAN <b><tt>chk<\/tt><\/b> file) for initial orbitals molecular orbitals.<br \/>\nThis is optional.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, the script checks if the user has a <b><tt>GAUSSIAN.resources<\/tt><\/b> file.<br \/>\nIf the user does not have one, the script will ask for information (number of CPUs, parallel scaling, and memory) in order to generate a new resources file.<br \/>\nThe interactive setup of the resource file also allows users to setup the required settings for wave function overlap calculations (path to <b><tt>wfoverlap.x<\/tt><\/b> and wave function truncation threshold) and for TheoDORE wave function analysis (path to TheoDORE, property list, and fragment list).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.8.4\"><\/a><\/p>\n<h3>\n6.8.4  Extracting normal modes: <b><tt>GAUSSIAN_freq.py<\/tt><\/b><\/h3>\n<p><a id=\"sec:GAUSSIAN_freq.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This script reads a Gaussian output file from a frequency calculation (requires <b><tt>freq=hpmodes<\/tt><\/b>) and generates a Molden file.<br \/>\nThese files can be visualized or fed into <b><tt>wigner.py<\/tt><\/b> and <b><tt>wigner_state_selected.py<\/tt><\/b>.<br \/>\nThe idea of this script is to provide a higher numerical precision of the normal mode vectors, compared to the alternative of opening a normal Gaussian output file in <b><tt>Molden<\/tt><\/b> and saving it in Molden format.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The usage is:<\/p>\n<pre>\n$SHARC\/GAUSSIAN_freq.py GAUSSIAN.log\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The script takes the output from the <b><tt>Standard orientation<\/tt><\/b> section.<br \/>\nIf you want to use the input orientation, use <b><tt>NoSymmetry<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.9\"><\/a><\/p>\n<h2>\n6.9   O<span style=\"font-size:x-small\">RCA<\/span> Interface<\/h2>\n<p><a id=\"sec:int:orca\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Ab initio interface for TD-DFT in ORCA 5 and 6.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– O<span style=\"font-size:x-small\">RCA<\/span> interface allows to run S<span style=\"font-size:x-small\">HARC<\/span> simulations with O<span style=\"font-size:x-small\">RCA<\/span>‘s TD-DFT functionality.<br \/>\nThe interface is compatible with restricted and unrestricted ground states (i.e., with all multiplicities), but not with symmetry.<br \/>\nSpin-orbit couplings can be computed and wave function overlaps from the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code are available (no nonadiabatic couplings).<br \/>\nDyson norms can also be computed through the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code.<br \/>\n T<span style=\"font-size:x-small\">HEO<\/span>DORE (version 2.0 or higher) can be used to perform automatic wave function analysis.<br \/>\nFurthermore, in S<span style=\"font-size:x-small\">HARC<\/span>4 the interface can do electrostatic embedding with point charges (gradients on point charges available).<br \/>\nThe interface works with O<span style=\"font-size:x-small\">RCA<\/span> 5 and 6.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>ORCA.template<\/tt><\/b>) and a resource file (<b><tt>ORCA.resources<\/tt><\/b>).<br \/>\nIf files <b><tt>QM\/ORCA.gbw.init<\/tt><\/b> or <b><tt>QM\/ORCA.gbw.<job>.init<\/tt><\/b> are present, they are used to provide an initial orbital guess for the SCF calculation of the respective job.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.9.1\"><\/a><\/p>\n<h3>\n6.9.1  Template file: <b><tt>ORCA.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the quantum chemistry calculation. Note that this is not a valid O<span style=\"font-size:x-small\">RCA<\/span> input file. The file only contains a number of keywords, given in table <a href=\"#tab:orca_temp\">6.10<\/a>. The actual input for O<span style=\"font-size:x-small\">RCA<\/span> will be generated automatically through the interface.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A fully commented template file-with all possible options, a comprehensive descriptions, and some practical hints-is located at <b><tt>$SHARC\/..\/examples\/SHARC_ORCA\/ORCA.template<\/tt><\/b>.<br \/>\nWe recommend that users start from this template file and modify it appropriately for their calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.10\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.10: Keywords for the <b><tt>ORCA.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:orca_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis <\/td>\n<td align=\"left\">Gives the basis set for all atoms (default 6-31G).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">auxbasis <\/td>\n<td align=\"left\">Gives the auxiliary basis set (default: Orca chooses).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis_per_element <\/td>\n<td align=\"left\">Overrides the basis set for the specified element (argument 1: element symbol, argument 2: basis set). Can be given multiple times.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis_per_atom <\/td>\n<td align=\"left\">Overrides the basis set for the specified atom (argument 1: atom number starting at 1, argument 2: basis set). Can be given multiple times.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ecp_per_element <\/td>\n<td align=\"left\">Overrides the ECP for the specified atom (ECP). Can be given multiple times.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">functional <\/td>\n<td align=\"left\">followed by one string giving the exchange-correlation functional. Default is <b><tt>PBE<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">hfexchange <\/td>\n<td align=\"left\">Modifies the amount of HF exchange in the functional (give in fraction of 1). Default is whatever the chosen functional uses.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dispersion <\/td>\n<td align=\"left\">Activates dispersion correction. Arguments are written verbatim to O<span style=\"font-size:x-small\">RCA<\/span> input. Default is no dispersion.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">no_tda <\/td>\n<td align=\"left\">This keyword deactivates TDA, which the interface requests by default.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">unrestricted_triplets <\/td>\n<td align=\"left\">Requests that the triplets are calculated in a separate job from an unrestricted ground state. Default is to compute triplets as linear response of the restricted singlet ground state.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">neglected_gradient <\/td>\n<td align=\"left\">String that is ‘zero’, ‘gs’, or ‘closest’ (default ‘zero’) to control how non-requested gradients are set.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ri <\/td>\n<td align=\"left\">Controls the density fitting scheme. Arguments can be, e.g., <b><tt>rijcosx<\/tt><\/b>. If not given, RI is decided by ORCA defaults.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">maxiter <\/td>\n<td align=\"left\">Maximum iterations in ORCA SCF. Default 700.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">keys <\/td>\n<td align=\"left\">Arguments are written verbatim to O<span style=\"font-size:x-small\">RCA<\/span> input as separate keywords. Use this to activate CPCM, ZORA, set grid sizes, etc. Expert option.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">paste_input_file <\/td>\n<td align=\"left\">Path to a file whose content is pasted verbatim into the ORCA input. Expert option. We recommend to use an absolute path here.\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.9.2\"><\/a><\/p>\n<h3>\n6.9.2  Resource file: <b><tt>ORCA.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>ORCA.resources<\/tt><\/b> contains mainly paths (to the O<span style=\"font-size:x-small\">RCA<\/span> executables, to the scratch directory, etc.) and other resources, plus settings for <b><tt>wfoverlap.x<\/tt><\/b> and T<span style=\"font-size:x-small\">HEO<\/span>DORE. This file must reside in the same directory where the interface is started. It uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The O<span style=\"font-size:x-small\">RCA<\/span> interface employs essentially all keywords from Tables <a href=\"#tab:resources\">6.3<\/a> (except: ngpu) and <a href=\"#tab:resources_aux\">6.4<\/a>, as it uses W<span style=\"font-size:x-small\">FOVERLAP<\/span>, T<span style=\"font-size:x-small\">HEO<\/span>DORE.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:orca_sh2\">6.11<\/a>.<br \/>\nA fully commented resource file with possible options and descriptions is located in <b><tt>$SHARC\/..\/examples\/SHARC_ORCA\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.11\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.11: Keywords for the <b><tt>ORCA.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:orca_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">orcadir <\/td>\n<td align=\"left\">Is the path to the O<span style=\"font-size:x-small\">RCA<\/span> installation directory. This directory should contain executables like <b><tt>orca<\/tt><\/b>, <b><tt>orca_int<\/tt><\/b>, or <b><tt>orca_fragovl<\/tt><\/b>. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. The interface will automatically update the <b><tt>$LD_LIBRARY_PATH<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dry_run <\/td>\n<td align=\"left\">If set to true, will not clean the scratchdir, write input files, or run ORCA calculations. It will perform overlap, TheoDORE, and RESP calculations, and parse output.\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p><b>Parallelization  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p> O<span style=\"font-size:x-small\">RCA<\/span> usually shows very good parallel scaling for most TD-DFT calculations.<br \/>\nIn the interface, only one O<span style=\"font-size:x-small\">RCA<\/span> input is written for each multiplicity, as all gradients can be computed in one job.<br \/>\nHence, <b><tt>schedule_scaling<\/tt><\/b> has rarely any effect.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.9.3\"><\/a><\/p>\n<h3>\n6.9.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The ORCA interface setup begins with the specification of the ORCA root directory.<br \/>\nThe script prompts the user to manually input the path, expanding the path if necessary.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the user is asked to specify a scratch directory for the ORCA calculations.<br \/>\nNote that the path is not validated by the script, as the calculations may be run on a different machine.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script will then check for the presence of a valid <b><tt>ORCA.template<\/tt><\/b> file.<br \/>\nIf a valid file is detected, the user is prompted to confirm if it should be used.<br \/>\nOtherwise, the user must specify the path to a valid template file.<br \/>\nNote that the ORCA interface’s setup routine will not copy extra input files (e.g., used with <b><tt>paste_input_file<\/tt><\/b>), so one should use an absolute path in the template file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The user is then prompted to provide a restart file (ORCA <b><tt>gbw<\/tt><\/b> file) for initial orbitals molecular orbitals.<br \/>\nThis is optional.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, the script checks if the user has a <b><tt>ORCA.resources<\/tt><\/b> file.<br \/>\nIf the user does not have one, the script will ask for information (number of CPUs, parallel scaling, and memory) in order to generate a new resources file.<br \/>\nThe interactive setup of the resource file also allows users to setup the required settings for wave function overlap calculations (path to <b><tt>wfoverlap.x<\/tt><\/b> and wave function truncation threshold) and for TheoDORE wave function analysis (path to TheoDORE, property list, and fragment list).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.9.4\"><\/a><\/p>\n<h3>\n6.9.4  Extracting normal modes: <b><tt>ORCA_hess_freq.py<\/tt><\/b><\/h3>\n<p><a id=\"sec:ORCA_hess_freq.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This script reads an ORCA Hessian file (e.g., <b><tt>orca.hess<\/tt><\/b>) from a frequency calculation and generates a Molden file.<br \/>\nThese files can be visualized or fed into <b><tt>wigner.py<\/tt><\/b> and <b><tt>wigner_state_selected.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The idea of this script is to provide a higher numerical precision of the normal mode vectors, compared to reading them from ORCA’s standard output.<br \/>\nAdditionally, <b><tt>.hess<\/tt><\/b> files from ORCA are in a consistent format independent of whether symmetry was used or not.<br \/>\nHence, with <b><tt>ORCA_hess_freq.py<\/tt><\/b>, normal modes from frequency calculations with explicit symmetry can be converted to Molden format and used in S<span style=\"font-size:x-small\">HARC<\/span>.<br \/>\nThis is especially beneficial for constructing LVC models (with <b><tt>setup_LVCparam.py<\/tt><\/b> and <b><tt>create_LVCparam.py<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The usage is:<\/p>\n<pre>\n$SHARC\/ORCA_hess_freq.py ORCA.hess\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.10\"><\/a><\/p>\n<h2>\n6.10   NWC<span style=\"font-size:x-small\">HEM<\/span> Interface<\/h2>\n<p><a id=\"sec:int:nwchem\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Ab initio interface for TD-DFT in NWC<span style=\"font-size:x-small\">HEM<\/span> 7.2.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– NWC<span style=\"font-size:x-small\">HEM<\/span> interface allows to run S<span style=\"font-size:x-small\">HARC<\/span> simulations with NW<span style=\"font-size:x-small\">CHEM<\/span>‘s TD-DFT functionality.<br \/>\nThe interface is compatible with restricted and unrestricted ground states (i.e., with all multiplicities), but not with symmetry.<br \/>\nTriplets have to be computed as response of a triplet ground state.<br \/>\nSpin-orbit couplings are not available, but wave function overlaps from the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code are available (no nonadiabatic couplings).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>NWCHEM.template<\/tt><\/b>) and a resource file (<b><tt>NWCHEM.resources<\/tt><\/b>).<br \/>\nCurrently, initial MOs cannot be provided.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.10.1\"><\/a><\/p>\n<h3>\n6.10.1  Template file: <b><tt>NWCHEM.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the quantum chemistry calculation. Note that this is not a valid NWC<span style=\"font-size:x-small\">HEM<\/span> input file. The file only contains a number of keywords, given in Table <a href=\"#tab:nwchem_temp\">6.12<\/a>. The actual input for NWC<span style=\"font-size:x-small\">HEM<\/span> will be generated automatically through the interface.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A fully commented template file-with all possible options, a comprehensive descriptions, and some practical hints-is located at <b><tt>$SHARC\/..\/examples\/SHARC_NWCHEM\/NWCHEM.template<\/tt><\/b>.<br \/>\nWe recommend that users start from this template file and modify it appropriately for their calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.12\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.12: Keywords for the <b><tt>NWCHEM.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:nwchem_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis <\/td>\n<td align=\"left\">Gives the basis set for all atoms (default def2-SVP).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">library_path <\/td>\n<td align=\"left\">Gives the path to the NWChem basis set library.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">functional <\/td>\n<td align=\"left\">followed by a string defining the exchange-correlation functional, as customary in NWChem. Default is <b><tt>B3LYP<\/tt><\/b>. For CAM-B3LYP is <b><tt>xc xcamb88 1.00 lyp 0.81 vwn_5 0.19 hfexch 1.00<\/tt><\/b>. See the <a href=\"https:\/\/nwchemgit.github.io\/Density-Functional-Theory-for-Molecules.html\">manual<\/a>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">cam <\/td>\n<td align=\"left\">Options for CAM functionals. For CAM-B3LYP is <b><tt>0.33 cam_alpha 0.19 cam_beta 0.46<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dispersion <\/td>\n<td align=\"left\">Activates dispersion correction. Arguments are written verbatim to NWC<span style=\"font-size:x-small\">HEM<\/span> input. Default is no dispersion. Use <b><tt>vdw 3<\/tt><\/b> for D3 and <b><tt>vdw 4<\/tt><\/b> for D3BJ.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">tda <\/td>\n<td align=\"left\">This keyword activates TDA (default is on). Use <b><tt>tda false<\/tt><\/b> to turn it off.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">cosmo <\/td>\n<td align=\"left\">Use to activate COSMO implicit solvation. Give a float with the dielectric constant as argument. Note that COSMO is not fully supported for TD-DFT (only for ground state).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">grid <\/td>\n<td align=\"left\">Options for integration grid. Default is as in NWChem\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">maxiter <\/td>\n<td align=\"left\">Maximum iterations in SCF. Default as in NWChem.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">spherical <\/td>\n<td align=\"left\">Force spherical basis sets (needed for wave function overlaps). No argument.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">forcecartesian <\/td>\n<td align=\"left\">Force Cartesian basis sets (overlaps do not work).\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.10.2\"><\/a><\/p>\n<h3>\n6.10.2  Resource file: <b><tt>NWCHEM.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>NWCHEM.resources<\/tt><\/b> contains mainly paths (to the NWC<span style=\"font-size:x-small\">HEM<\/span> executables, to the scratch directory, etc.) and other resources, plus settings for <b><tt>wfoverlap.x<\/tt><\/b>. This file must reside in the same directory where the interface is started. It uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The NWC<span style=\"font-size:x-small\">HEM<\/span> interface employs essentially all keywords from Tables <a href=\"#tab:resources\">6.3<\/a> (except: ngpu) and the W<span style=\"font-size:x-small\">FOVERLAP<\/span>-related keywords from <a href=\"#tab:resources_aux\">6.4<\/a>.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:nwchem_sh2\">6.13<\/a>.<br \/>\nA fully commented resource file with possible options and descriptions is located in <b><tt>$SHARC\/..\/examples\/SHARC_NWCHEM\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.13\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.13: Keywords for the <b><tt>NWCHEM.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:nwchem_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nwchem <\/td>\n<td align=\"left\">Is the path to the NWC<span style=\"font-size:x-small\">HEM<\/span> binary executable. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dry_run <\/td>\n<td align=\"left\">If set to true, will not clean the scratchdir, write input files, or run NWChem calculations. It will perform overlap calculations and parse output.\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.10.3\"><\/a><\/p>\n<h3>\n6.10.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The NWChem interface setup begins with the specification of the NWChem binary executable.<br \/>\nThe script prompts the user to manually input the path.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the user is asked to specify a scratch directory for the NWChem calculations.<br \/>\nNote that the path is not validated by the script, as the calculations may be run on a different machine.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script will then ask for an <b><tt>NWCHEM.template<\/tt><\/b> file.<br \/>\nNote that the setup routine does not perform any checking on this file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The setup routines do not allow copying initial orbital files for NWChem.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, the script checks if the user has a <b><tt>NWCHEM.resources<\/tt><\/b> file.<br \/>\nIf the user does not have one, the script will ask for information (number of CPUs and memory) in order to generate a new resources file.<br \/>\nThe interactive setup of the resource file also allows users to setup the required settings for wave function overlap calculations (path to <b><tt>wfoverlap.x<\/tt><\/b> and wave function truncation threshold).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.11\"><\/a><\/p>\n<h2>\n6.11  Turbomole Interface<\/h2>\n<p><a id=\"sec:int:turbomole\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Ab initio interface for Turbomole’s CC2 and ADC(2) methods.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note: This interface was called <b><tt>SHARC_RICC2.py<\/tt><\/b> in S<span style=\"font-size:x-small\">HARC<\/span>2 and S<span style=\"font-size:x-small\">HARC<\/span>3, but was renamed in S<span style=\"font-size:x-small\">HARC<\/span>4.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– T<span style=\"font-size:x-small\">URBOMOLE<\/span> interface can be used to conduct excited-state dynamics based on T<span style=\"font-size:x-small\">URBOMOLE<\/span>‘s CC2 and ADC(2) methods.<br \/>\nIt can do both restricted and unrestricted ground states, so all multiplicities are available.<br \/>\nThe interface uses the programs <b><tt>define<\/tt><\/b>, <b><tt>dscf<\/tt><\/b> and <b><tt>ricc2<\/tt><\/b>.<br \/>\nFor spin-orbit couplings, no O<span style=\"font-size:x-small\">RCA<\/span> installation is needed anymore, but a T<span style=\"font-size:x-small\">URBOMOLE<\/span> version is required that supports computation of the spin-orbit integrals.<br \/>\nOnly ADC(2) can be used to calculate spin-orbit couplings, but not CC2 (hence, it is not recommended to perform CC2 calculations with both singlet and triplet states).<br \/>\nEven with ADC(2), only singlet-triplet SOCs are obtained, but no triplet-triplet SOCs; S<sub>0<\/sub>-triplet SOCs are also missing currently.<br \/>\n T<span style=\"font-size:x-small\">HEO<\/span>DORE (version 2.0 and higher) can be used to perform automatic wave function analysis.<br \/>\nWavefunction overlaps and Dyson norms are calculated using the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>TURBOMOLE.template<\/tt><\/b>) and a general input file (<b><tt>TURBOMOLE.resources<\/tt><\/b>).<br \/>\nIf a file <b><tt>QM\/mos.init<\/tt><\/b> is are present, it is used to provide an initial orbital guess for the SCF calculation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.11.1\"><\/a><\/p>\n<h3>\n6.11.1  Template file: <b><tt>TURBOMOLE.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the quantum chemistry calculation. Note that this is not a valid T<span style=\"font-size:x-small\">URBOMOLE<\/span> input file. The file only contains a number of keywords, given in table <a href=\"#tab:turbomole_temp\">6.14<\/a>. The actual input for T<span style=\"font-size:x-small\">URBOMOLE<\/span> will be generated automatically through <b><tt>define<\/tt><\/b>.<br \/>\nA fully commented template file with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_TURBOMOLE\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.14\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.14: Keywords for the <b><tt>TURBOMOLE.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:turbomole_temp\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis <\/td>\n<td align=\"left\">The basis set used. The interface will convert this string to the correct case for T<span style=\"font-size:x-small\">URBOMOLE<\/span>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">auxbasis <\/td>\n<td align=\"left\">The auxiliary basis set used in. If no auxbasis is given, the interface will let <b><tt>define<\/tt><\/b> decide on a suitable auxbasis.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basislib <\/td>\n<td align=\"left\">Path to external basis set library. Can be used to employ custom basis sets.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">method <\/td>\n<td align=\"left\">Followed by a string, which is either “CC2” or “ADC(2)” (case insensitive), defining the level of theory. Default is “ADC(2)”.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">douglas-kroll <\/td>\n<td align=\"left\">Activates the use of the scalar-relativistic DK Hamiltonian of 2nd order. Default (if no keyword is given) is to use the non-relativistic Hamiltonian.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">spin-scaling <\/td>\n<td align=\"left\">Followed by a string, which is either “none”, “scs” or “sos”. Using these options, spin-component scaling can be activated. Under certain restrictions (no SOC, no transition dipole moments, no SMP), “lt-sos” can be used to perform cheaper “sos” calculations.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scf <\/td>\n<td align=\"left\">Followed by a string which is either “dscf” or “ridft”. Using this option, the SCF program can be chosen. Note that currently, there is no advantage of using “ridft”.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">frozen <\/td>\n<td align=\"left\">Followed by an integer giving the number of frozen core orbitals in the <b><tt>ricc2<\/tt><\/b> calculations. Default is to use frozen core orbitals and let <b><tt>define<\/tt><\/b> decide on the number. If frozen core is not wanted, use <b><tt>frozen 0<\/tt><\/b> in the template.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dipolelevel <\/td>\n<td align=\"left\">Followed by an integer which is either 0, 1, or 2. Controls which dipole moment calculations are skipped by the interface.<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<h4>External basis set libary<\/h4>\n<div class=\"p\"><!----><\/div>\n<p>If users want to employ their own basis sets, they can create a basis set library directory with the required files, and use the <b><tt>basislib<\/tt><\/b> keyword to tell the interface to use this directory.<br \/>\nThe <b><tt>basislib<\/tt><\/b> keyword cannot be used together with the <b><tt>auxbasis<\/tt><\/b> keyword.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The specified directory must contain <b><tt>basen\/<\/tt><\/b> and <b><tt>cbasen\/<\/tt><\/b> subdirectories. These must contain one file per element, containing the desired basis set parameters.<br \/>\nThe files in <b><tt>cbasen\/<\/tt><\/b> must auxiliary basis sets of the same name as the basis sets in <b><tt>basen\/<\/tt><\/b>.<br \/>\nSee the T<span style=\"font-size:x-small\">URBOMOLE<\/span> directory structure to see how the directories and files need to be prepared.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.11.2\"><\/a><\/p>\n<h3>\n6.11.2  Resource file: <b><tt>TURBOMOLE.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>TURBOMOLE.resources<\/tt><\/b> contains mainly paths (to the T<span style=\"font-size:x-small\">URBOMOLE<\/span> and O<span style=\"font-size:x-small\">RCA<\/span> executables, to the scratch directory, etc.). This file must reside in the same directory where the interface is started. It uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The T<span style=\"font-size:x-small\">URBOMOLE<\/span> interface employs essentially all keywords from Tables <a href=\"#tab:resources\">6.3<\/a> (except: ngpu) and <a href=\"#tab:resources_aux\">6.4<\/a>, as it uses W<span style=\"font-size:x-small\">FOVERLAP<\/span>, T<span style=\"font-size:x-small\">HEO<\/span>DORE.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:turbomole_sh2\">6.15<\/a>.<br \/>\nA fully commented resource file with possible options and descriptions is located in <b><tt>$SHARC\/..\/examples\/SHARC_TURBOMOLE\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.15\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.15: Keywords for the <b><tt>TURBOMOLE.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:turbomole_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">turbodir <\/td>\n<td align=\"left\">Is the path to the T<span style=\"font-size:x-small\">URBOMOLE<\/span> installation directory. This directory should contain subdirectories like <b><tt>bin\/<\/tt><\/b>, <b><tt>basen\/<\/tt><\/b>, <b><tt>cbasen\/<\/tt><\/b>, or <b><tt>scripts\/<\/tt><\/b>. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. The interface will set <b><tt>$TURBODIR<\/tt><\/b> to this path, and will set the <b><tt>$PATH<\/tt><\/b> correctly (using T<span style=\"font-size:x-small\">URBOMOLE<\/span>‘s <b><tt>sysname<\/tt><\/b> tool. If this keyword is not present in <b><tt>RICC2.resources<\/tt><\/b>, the interface will use the environment variable <b><tt>$TURBODIR<\/tt><\/b>, if it is set.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dry_run <\/td>\n<td align=\"left\">If set to true, will not clean the scratchdir, write input files, or run Turbomole calculations. It will perform overlap and TheoDORE calculations, and parse output.\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Note that the interface sets all environment variables necessary to run T<span style=\"font-size:x-small\">URBOMOLE<\/span> (e.g., <b><tt>$PATH<\/tt><\/b>) automatically, based on the input from <b><tt>TURBOMOLE.resources<\/tt><\/b> and <b><tt>QM.in<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For parallel calculations, the interface will call the SMP executables of T<span style=\"font-size:x-small\">URBOMOLE<\/span> and WF<span style=\"font-size:x-small\">OVERLAP<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the <b><tt>dipolelevel<\/tt><\/b> keyword can have significant impact on the calculation time.<br \/>\nGenerally, in response methods like CC2 and ADC(2), extra computational effort is required for the calculation of state and transition dipole moments .<br \/>\nHowever, dipole moments have only influence in the dynamics simulations if a laser field is present.<br \/>\nUsing the <b><tt>dipolelevel<\/tt><\/b> keyword, it is possible to deactivate dipole moment calculations if they are not required.<br \/>\nThere are three different settings for <b><tt>dipolelevel<\/tt><\/b>: <\/p>\n<ul>\n<li> <b><tt>dipolelevel<\/tt><\/b>=0: The interface will return only dipole moments which can be calculated at no cost (state dipole moments of states where a gradient is calculated; excited-excited transition dipole moments if SOCs are calculated)\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>dipolelevel<\/tt><\/b>=1: In addition, the interface will calculate transition dipole moments between S<sub>0<\/sub> and excited singlet states. Use at least this level for the initial condition setup (<b><tt>setup_init.py<\/tt><\/b> takes care of this).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>dipolelevel<\/tt><\/b>=2: The interface will calculate all state and transition dipole moments\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<p>If only energies and dipole moments are calculated, <b><tt>dipolelevel<\/tt><\/b>=1 is only slightly more expensive than <b><tt>dipolelevel<\/tt><\/b>=0, while <b><tt>dipolelevel<\/tt><\/b>=2 increases computation time more strongly.<br \/>\nHowever, the computation time also depends on whether or not spin-orbit couplings and gradients are calculated. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.11.3\"><\/a><\/p>\n<h3>\n6.11.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The TURBOMOLE interface setup begins with checking for the presence of a valid <b><tt>TURBOMOLE.template<\/tt><\/b> file.<br \/>\nIf a valid file is detected, the user is prompted to confirm if it should be used.<br \/>\nOtherwise, the user must specify the path to a valid template file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Then, the user is asked to provide a resource file.<br \/>\nIf the user does not have one, the script will ask for information (path to TURBOMOLE, scratch directory, number of CPUs, parallel scaling, and memory) in order to generate a new resources file.<br \/>\nThe interactive setup of the resource file also allows users to setup the required settings for wave function overlap calculations (path to <b><tt>wfoverlap.x<\/tt><\/b> and wave function truncation threshold) and for TheoDORE wave function analysis (path to TheoDORE, property list, and fragment list).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.12\"><\/a><\/p>\n<h2>\n6.12   O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> Interface<\/h2>\n<p><a id=\"sec:int:molcas\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Ab initio interface for O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span>‘ RASSCF, (X)MS-CASPT2, and PDFT methods.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> interface can be used to conduct excited-state dynamics based on O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span>‘ CASSCF, MS-CASPT2, XMS-CASPT2, MC-PDFT, XMS-PDFT, or CMS-PDFT methods.<br \/>\nFor all methods, RASSCF wave functions can also be used.<br \/>\nGradients are available for CASSCF, RASSCF, and (X)MS-CASPT2 (consider using <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> otherwise).<br \/>\nCurrently, S<span style=\"font-size:x-small\">HARC<\/span> is tested to work with O<span style=\"font-size:x-small\">PENMOLCAS<\/span> 24.<br \/>\nThe newest versions of M<span style=\"font-size:x-small\">OLCAS<\/span> might also work, but no guarantee is given.<br \/>\nNote that within this Manual, M<span style=\"font-size:x-small\">OLCAS<\/span> and O<span style=\"font-size:x-small\">PENMOLCAS<\/span> are used synonymously, because from S<span style=\"font-size:x-small\">HARC<\/span>‘s viewpoint, they only differ in the driver program (<b><tt>pymolcas<\/tt><\/b> or <b><tt>molcas.exe<\/tt><\/b>).<br \/>\nThe support for MC-PDFT, XMS-PDFT, or CMS-PDFT is currently to be regarded as experimental, with some features not available or not working properly.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface uses the modules GATEWAY, SEWARD (integrals), RASSCF (wave function, energies), RASSI (transition dipole moments, spin-orbit couplings, overlaps, Dyson norms), MCLR, ALASKA (gradients), and WFA (wave function analysis).<br \/>\nCholesky decomposition is always enforced by the interface and cannot be turned off.<br \/>\nThe CASPT2 and MCPDFT modules are used for their respective energy methods.<br \/>\nFor CASSCF, RASSCF, and (X)MS-CASPT2, analytical nonadiabatic coupling vectors are available.<br \/>\nWave function analysis can be performed through the WFA module, using the keywords for TheoDORE that are used in other interfaces.<br \/>\nThe interface allows to include point charges (gradients and nonadiabatic couplings on these point charges are available).<br \/>\nMultipolar density fits and delivery of molecule object\/density matrices is implemented.<br \/>\nNote that O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> cannot average over states of different multiplicities; hence, the multiplicities are always computed in separate jobs which all share the same CAS settings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>MOLCAS.template<\/tt><\/b>) and a resource file (<b><tt>MOLCAS.resources<\/tt><\/b>).<br \/>\nIf the interface finds files with the name <b><tt>QM\/MOLCAS.<i>.JobIph.init<\/tt><\/b> or <b><tt>QM\/MOLCAS.<i>.RasOrb.init<\/tt><\/b>, they are used as initial wave function files, where <b><tt><i><\/tt><\/b> is the multiplicity.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.12.1\"><\/a><\/p>\n<h3>\n6.12.1  Template file: <b><tt>MOLCAS.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the wave function. Note that this is not a valid O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> input file. No sections like <b><tt>$GATEWAY<\/tt><\/b>, etc., can be used. The file only contains a number of keywords, given in table <a href=\"#tab:molcas_temp\">6.16<\/a>.<br \/>\nThe actual input files are automatically generated.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A fully commented template file with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_MOLCAS\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.16\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.16: Keywords for the <b><tt>MOLCAS.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:molcas_temp\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis <\/td>\n<td align=\"left\">The basis set used. Note that some basis sets (e.g., Pople basis sets) do not work properly, since the spin-orbit integrals cannot be calculated. Note that textscMolcas will automatically employ Douglas-Kroll-Hess or other relativistic options appropriate for the chosen basis set.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">baslib <\/td>\n<td align=\"left\">Can be used to provide the path to a custom basis set library (analogous to the baslib keyword in O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span>).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nactel <\/td>\n<td align=\"left\">Number of active electrons for CASSCF, assuming a neutral molecule. The actual number of active electrons is computed based on the charge per multiplicity received from the caller or <b><tt>QM.in<\/tt><\/b> file.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ras2 <\/td>\n<td align=\"left\">Number of active orbitals for CASSCF.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ras1 <\/td>\n<td align=\"left\">Maximum number of holes in RAS1 in a RASSCF calculation (identical for all multiplicities).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ras3 <\/td>\n<td align=\"left\">Maximum number of electrons in RAS3 in a RASSCF calculation (identical for all multiplicities).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">inactive <\/td>\n<td align=\"left\">Number of inactive orbitals.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">roots <\/td>\n<td align=\"left\">Followed by a list of integers, giving the number of states per multiplicity in the state-averaging procedure.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">method <\/td>\n<td align=\"left\">Followed by a string, which is one of “CASSCF”, “CASPT2”, “MS-CASPT2”, “XMS-PDFT”, or “CMS-PDFT” (case insensitive), defining the level of theory. Default is “CASSCF”.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">functional <\/td>\n<td align=\"left\">Followed by a string, which is one of “t:PBE”, “ft:PBE”, “t:BLYP”, “ft:BLYP”, “t:revPBE”, “ft:revPBE”, “t:LSDA”, or “ft:LSDA” (case insensitive), defining the functionals used in PDFT. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ipea <\/td>\n<td align=\"left\">Followed by a float giving the IP-EA shift for CASPT2 (see O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> manual for more information). The default is 0.25, as in O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">imaginary <\/td>\n<td align=\"left\">Followed by a float giving the imaginary level shift for CASPT2 (see O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> manual for more information). The default is 0.0, as in O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">frozen <\/td>\n<td align=\"left\">Number of frozen orbitals for CASPT2. Default is -1, which lets O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> choose the number of frozen orbitals.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">cholesky_accu <\/td>\n<td align=\"left\">Sets the Cholesky threshold. Note that Cholesky decomposition is always requested by the interface and cannot be turned off.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">gradaccudefault <\/td>\n<td align=\"left\">(float) Default accuracy for CP-MCSCF.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">gradaccumax <\/td>\n<td align=\"left\">(float) Worst acceptable accuracy for CP-MCSCF. This is used if MCLR does not converge-the interface will try to rerun the calculation with a looser convergence criterion in MCLR, in order to avoid a crashed trajectory. Note that this might lead to violations of conservation of total energy, as gradients might be inaccurate with looser CP-MCSCF convergence.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">iterations <\/td>\n<td align=\"left\">(two floats) Maximum number of iterations in RASSCF and in orbital optimization.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">rasscf_thrs <\/td>\n<td align=\"left\">(three floats) Specify convergence thresholds for: energy, orbital rotation matrix, and energy gradient, as in the RASSCF input.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">pcmset <\/td>\n<td align=\"left\">Activates the PCM mode. Three arguments follow: the solvent (a string, default “water”), the AARE value (a float, default 0.4, optional), the RMIN value (a float, default 1.0, optional). Check O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> manual for details.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">pcmstate <\/td>\n<td align=\"left\">Defines the state for which the PCM charges will be optimized. Followed by two numbers: multiplicity (1=singlet, …) and state (1=lowest state of that multiplicity). Default is the first state according to the state request.<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Simple template files can be set up with the tool <b><tt>molcas_input.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.12.2\"><\/a><\/p>\n<h3>\n6.12.2  Resource file: <b><tt>MOLCAS.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>MOLCAS.resources<\/tt><\/b> contains mainly paths (to the O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> executables, to the scratch directory, etc.). This file must reside in the same directory where the interface is started. It uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> interface employs essentially all keywords from Tables <a href=\"#tab:resources\">6.3<\/a> (except: ngpu), <a href=\"#tab:resources_aux\">6.4<\/a> (only theodir, theodore_prop and theodore_fragment) for WFA, and <a href=\"#tab:resources_resp\">6.5<\/a> for RESP.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:molcas_sh2\">6.17<\/a>.<br \/>\nA fully commented resource file for this interface with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_MOLCAS\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.17\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.17: Keywords for the <b><tt>MOLCAS.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:molcas_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">molcas <\/td>\n<td align=\"left\">Is the path to the O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> installation. This directory should contain subdirectories like <b><tt>bin\/<\/tt><\/b>, <b><tt>basis_library\/<\/tt><\/b>, <b><tt>data\/<\/tt><\/b>, or <b><tt>lib\/<\/tt><\/b>. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. The interface will set <b><tt>$MOLCAS<\/tt><\/b> to this path. If this keyword is not present in <b><tt>MOLCAS.resources<\/tt><\/b>, the interface will use the environment variable <b><tt>$MOLCAS<\/tt><\/b>, if it is set.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">driver <\/td>\n<td align=\"left\">Path to the M<span style=\"font-size:x-small\">OLCAS<\/span>\/ O<span style=\"font-size:x-small\">PEN<\/span>MOLCAS driver (<b><tt>molcas.exe<\/tt><\/b> or <b><tt>pymolcas<\/tt><\/b>).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dry_run <\/td>\n<td align=\"left\">If set to true, will not clean the scratchdir, write input files, or run O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> calculations. It will perform overlap, TheoDORE, and RESP calculations, and parse output.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">mpi_parallel <\/td>\n<td align=\"left\">Uses MPI parallel O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> runs. The number of cores is dynamically chosen based on the available cores and the number of tasks (energies, gradients, displacements).<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Note that the interface sets all environment variables necessary to run O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> (e.g., <b><tt>$MOLCAS<\/tt><\/b>, <b><tt>$MOLCASMEM<\/tt><\/b>, <b><tt>$WorkDir<\/tt><\/b> ,<b><tt>$Project<\/tt><\/b>) automatically, based on the input from <b><tt>MOLCAS.resources<\/tt><\/b> and <b><tt>QM.in<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Some explanations on parallelization: In S<span style=\"font-size:x-small\">HARC<\/span>4, the interface has been completely redesigned.<br \/>\nThe interface cannot do numerical gradients anymore (use <b><tt>SHARC_NUMDIFF.py<\/tt><\/b>), and the parallelization schemes of the old interface are not available anymore.<br \/>\nInstead, there are two possible modes to run parallel calculations with the new S<span style=\"font-size:x-small\">HARC<\/span>– O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> interface.<br \/>\nIn the first (default) mode, every individual O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> job is run with 1 core, but if several multiplicities, or multiple gradients\/nonadiabatic coupling vectors are requested, then these will be run in parallel (first all energy calculations in parallel, then all vectors in parallel).<br \/>\nAt most <b><tt>ncpu<\/tt><\/b> jobs will be run in parallel, which might lead to idle CPUs, especially in the energy calculations.<br \/>\nIn the second parallelization mode (used through <b><tt>mpi_parallel<\/tt><\/b>), all O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> jobs are run with <b><tt>ncpu<\/tt><\/b> cores, one job after the other.<br \/>\nIt is not possible to mix these modes, as in other interfaces, because changing the number of CPU cores in O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> would require rerunning SEWARD (which distributes the integrals over <b><tt>ncpu<\/tt><\/b> files).<br \/>\nThe second parallelization mode avoids idle CPU cores, but parallel speed up\/efficiency should be evaluated before running large projects to avoid wasting CPU time.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.12.3\"><\/a><\/p>\n<h3>\n6.12.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The Molcas interface setup begins by prompting you to specify the path to the Molcas executable (via an environment variable or explicit path) and a scratch directory for temporary integral files.<br \/>\nThese locations will be used during the calculation and must be valid on the machine where you run SHARC.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the setup checks for a <b><tt>MOLCAS.template<\/tt><\/b> file in the current directory.<br \/>\nIf one is found, you will be asked whether to use it; otherwise you must supply the path to a valid <b><tt>MOLCAS.template<\/tt><\/b> file.<br \/>\nThis template should contain all required input directives needed for a CASSCF calculation, including basis sets, CASSCF parameters, and state\u2010averaging settings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>You are then asked to enter the number of CPUs to be used per trajectory and the total RAM (in MB) that Molcas may consume. These values will be written to <b><tt>MOLCAS.resources<\/tt><\/b> and govern the parallelization and memory allocation of your jobs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For initial wavefunction guesses, the interface allows to choose whether to supply JobIph or RasOrb files.<br \/>\nSubsequently, file paths for initial orbitals for each requested multiplicity need to be given.<br \/>\nIf you opt not to provide guess files, a warning reminds you that CASSCF convergence may be slow or unstable without proper starting MOs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, if a wave function analysis via <b><tt>libwfa<\/tt><\/b> was requested, the setup will display a list of valid wave function descriptors (e.g., Om, PR, POS, COH, MC, etc.; note that this list is somewhat shorter than for the TDDFT interfaces) and ask you to select which to compute.<br \/>\nYou will then define fragments by entering atom\u2010index lists (one fragment per line, ending with <b><tt>end<\/tt><\/b>). <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.12.4\"><\/a><\/p>\n<h3>\n6.12.4  Template file generator: <b><tt>molcas_input.py<\/tt><\/b><\/h3>\n<p><a id=\"sec:molcas_input.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This is a small interactive script to generate template files for the S<span style=\"font-size:x-small\">HARC<\/span>– O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> interface.<br \/>\nIt simply queries the user for some input parameters and then writes the file <b><tt>MOLCAS.template<\/tt><\/b>, which can be used to run S<span style=\"font-size:x-small\">HARC<\/span> simulations with the S<span style=\"font-size:x-small\">HARC<\/span>– O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> interface.<br \/>\nThe input generator can also be used to write proper O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> input files for single-point calculations and optimizations\/frequency calculations on CASSCF and (MS-)CASPT2 level of theory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Type of calculation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Choose to either perform a single-point calculation or a minimum optimization (including optionally frequency calculation), or to generate a template file. For the template generation, no geometry file is needed, but the script looks for a <b><tt>MOLCAS.input<\/tt><\/b> in the same directory and allows to copy the settings. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>For single-point calculations, optimizations and frequency calculations, files in M<span style=\"font-size:x-small\">OLDEN<\/span> format are created (containing the orbitals, optimization steps and normal modes, respectively). The file <b><tt>MOLCAS.freq.molden<\/tt><\/b> can be used to generate initial conditions with <b><tt>wigner.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Geometry file  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The geometry file is only used to calculate the nuclear charge.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Charge  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This is the overall charge of the molecule. This number is used with the nuclear charge to calculate the number of electrons and from there the number of inactive orbitals and active electrons.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Method  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Choose either CASSCF or CASPT2. Multi-state CASPT2 can be requested later.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Basis set  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This is simply a string, which is <i>not<\/i> checked by the script to be a valid basis set of the O<span style=\"font-size:x-small\">PEN<\/span>M<span style=\"font-size:x-small\">OLCAS<\/span> library.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of active electrons and orbitals  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>These settings are necessary for the definition of the CASSCF wave function. The number of inactive orbitals is automatically calculated from the total number of electrons and the number of active electrons.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>States for state-averaging  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For each multiplicity, the number of states for the state-averaging procedure must be equal or larger than the number of states used in the dynamics.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Further settings  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Depending on the run type and method, the script might ask further questions regarding the root to optimize, CASPT2 settings (whether to do multi-state CASPT2, IPEA shift, imaginary level shift), or whether a spin-orbit RASSI should be performed (for input file generation only).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.13\"><\/a><\/p>\n<h2>\n6.13   MNDO Interface<\/h2>\n<p><a id=\"sec:int:mndo\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Ab initio interface to run OM2\/MRCI calculations using the MNDO code.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– MNDO interface allows to run S<span style=\"font-size:x-small\">HARC<\/span> simulations with MNDO’s OM2 (and ODM2) Hamiltonian, using SCF or floating-occupation SCF orbitals and GUGA-based MRCISD.<br \/>\nThe interface is compatible with restricted and restricted open-shell ground states.<br \/>\nNonadiabatic couplings are available as well as wave function overlaps from the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code.<br \/>\nThe S<span style=\"font-size:x-small\">HARC<\/span>– MNDO interface furthermore allows to do electrostatic embedding, with gradients and nonadiabatic coupling vectors on the point charges being available.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>MNDO.template<\/tt><\/b>) and a resource file (<b><tt>MNDO.resources<\/tt><\/b>). <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.13.1\"><\/a><\/p>\n<h3>\n6.13.1  Template file: <b><tt>MNDO.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the quantum chemistry calculation. Note that this is not a valid MNDO input file. The file only contains a number of keywords, given in table <a href=\"#tab:mndo_temp\">6.18<\/a>. The actual input for MNDO will be generated automatically through the interface.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A fully commented template file-with all possible options, a comprehensive descriptions, and some practical hints-is located at <b><tt>$SHARC\/..\/examples\/SHARC_MNDO\/MNDO.template<\/tt><\/b>.<br \/>\nWe recommend that users start from this template file and modify it appropriately for their calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.18\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.18: Keywords for the <b><tt>MNDO.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:mndo_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">hamiltonian <\/td>\n<td align=\"left\">(string) This keyword changes the Hamiltonian between OM2 and ODM2. Options: OM2, ODM2. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">rohf <\/td>\n<td align=\"left\">(int) Controls the use of restricted open-shell Hartree-Fock procedure. 0 is restricted RHF, 1 is ROHF. Default value is 0.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">fomo <\/td>\n<td align=\"left\">(int) Switch for floating occupation molecular orbital procedure. 0 turns off, 1 turns on. Default value is 0.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">kitscf <\/td>\n<td align=\"left\">(int) Controls the maximum number of SCF iterations. Default value is 5000.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ici1 <\/td>\n<td align=\"left\">(int) Controls the number of occupied orbitals. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ici2 <\/td>\n<td align=\"left\">(int) Controls the number of unoccupied orbitals. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">act_orbs <\/td>\n<td align=\"left\">(list of int) List of the indices of the orbitals in the active space, starting from 1. Number of entries has to be <b><tt>ici1<\/tt><\/b> + <b><tt>ici2<\/tt><\/b>. Example: <b><tt>act_orbs 3 4 6<\/tt><\/b>. Default value is an empty list. <b>Hint<\/b>: This is only necessary if you want specific orbitals in your active space, similar to CASSCF calculations. In order to ensure that the orbitals stay the same over a simulation use orbital mapping (<b><tt>imomap<\/tt><\/b>). If you simply want to select the <b><tt>n<\/tt><\/b> highest occupied and <b><tt>m<\/tt><\/b> lowest unoccupied orbitals in your active space use <b><tt>ici1<\/tt><\/b> and <b><tt>ici2<\/tt><\/b> without <b><tt>act_orbs<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">imomap <\/td>\n<td align=\"left\">(int) To control orbital tracking during trajecories. 0 turns it off, 1 turns it on. <b>Hint<\/b>: should only be used for molecules that do not twist around a π-bond. <b>Attention<\/b>: Do not use orbital mapping together with overlap calculations, this causes severe problems in the dynamics! Default value is 0.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nciref <\/td>\n<td align=\"left\">(int) Controls the number of references configurations. Maximum allowed value 20. Default value is 1.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">mciref <\/td>\n<td align=\"left\">(int) Definition of the reference occupations. = 0 Stardard definition. = 1 Starting from the reference occupations corresponding to mciref=0, add further references so that their fraction in all CI roots is at least 85%, and repeat the CI calculation once. Default value is 0.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">levexc <\/td>\n<td align=\"left\">(int) Maximum excitation level relative to any of the reference configurations. From 1 (singlet) to 6 (sextet). Default value is 2 (doublet).\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.13.2\"><\/a><\/p>\n<h3>\n6.13.2  Resource file: <b><tt>MNDO.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>MNDO.resources<\/tt><\/b> contains mainly paths (to the MNDO executables, to the scratch directory, etc.) and other resources, plus settings for <b><tt>wfoverlap.x<\/tt><\/b>. This file must reside in the same directory where the interface is started. It uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The MNDO interface employs the keywords scratchdir, savedir, retain and delay from Tables <a href=\"#tab:resources\">6.3<\/a> and all keywords from <a href=\"#tab:resources_aux\">6.4<\/a> for WF<span style=\"font-size:x-small\">OVERLAPS<\/span>.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:mndo_sh2\">6.19<\/a>.<br \/>\nA fully commented resource file for this interface with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_MNDO\/MNDO.resources<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.19\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.19: Keywords for the <b><tt>MNDO.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:mndo_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">mndodir <\/td>\n<td align=\"left\">Is the path to the MNDO installation directory. This directory should contain the executable <b><tt>mndo2020<\/tt><\/b>. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. The interface will automatically update the <b><tt>$LD_LIBRARY_PATH<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">neglected_gradient <\/td>\n<td align=\"left\">Decides how not-requested gradients are reported back (Options: <b><tt>zero<\/tt><\/b>: default, not-requested gradients are zero; <b><tt>gs<\/tt><\/b>: not-requested gradients are equal to ground state gradient; <b><tt>closest<\/tt><\/b>: not-requested gradients are equal to closest-energy requested gradient).\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.13.3\"><\/a><\/p>\n<h3>\n6.13.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_MNDO.py<\/tt><\/b> follows the standard initialization procedure during setup.<br \/>\nThe user is asked for two files.<br \/>\nFirst, the <b><tt>MNDO.template<\/tt><\/b> needs to be provided.<br \/>\nIn the second question, the user is asked for a <b><tt>MNDO.resources<\/tt><\/b> file. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>If no resources file was prepared before, the setup routine will help in the construction of this file.<br \/>\nIn order, the user will get asked for the path to the MNDO directory (<b><tt>mndodir<\/tt><\/b>), then for the <b><tt>scratchdir<\/tt><\/b>, and then for the available memory (<b><tt>memory<\/tt><\/b>).<br \/>\nIf overlaps were selected during setup, also the path to the wave function overlap code is asked for.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.14\"><\/a><\/p>\n<h2>\n6.14   MOPAC-PI Interface<\/h2>\n<p><a id=\"sec:int:mopac-pi\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Ab initio interface for semi-empirical FOMO-CI simulations using MOPAC-PI, optionally with QM\/MM using T<span style=\"font-size:x-small\">INKER<\/span>.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– MOPAC-PI interface allows to run S<span style=\"font-size:x-small\">HARC<\/span> simulations with MOPAC-PI’s semiempirical Hamiltonians (e.g. AM1, PM3, PM6).<br \/>\nThe interface is compatible with the floating occupation molecular orbital-configuration interaction (FOMO-CI) method.<br \/>\nGradients and nonadiabatic couplings are available, as well as wave function overlaps calculated by MOPAC-PI itself (rather than by WF<span style=\"font-size:x-small\">OVERLAP<\/span>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– MOPAC-PI interface furthermore allows to perform QM\/MM dynamics, using T<span style=\"font-size:x-small\">INKER<\/span> for the MM part.<br \/>\nNote that this QM\/MM does not work via the hybrid <b><tt>SHARC_QMMM.py<\/tt><\/b> interface, but via a QM\/MM implementation directly integrated into MOPAC-PI.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>MOPACPI.template<\/tt><\/b>) and a resource file (<b><tt>MOPACPI.resources<\/tt><\/b>).<br \/>\nThere is also an option to use different parameters for the semiempirical hamiltonians (reparametrization) and to use additional potentials on certain bonds or dihedrals.<br \/>\nThese additional parameters are handled by the <b><tt>ext_param<\/tt><\/b> file.<br \/>\nIn the case of QM\/MM calculations, three more input files are needed: a T<span style=\"font-size:x-small\">INKER<\/span> force field file (e.g., <b><tt>oplsaa.prm<\/tt><\/b>), <b><tt>MOPACPI_tnk.key<\/tt><\/b> where additional atomtypes can be defined, and <b><tt>MOPACPI_tnk.xyz<\/tt><\/b> which contains the connectivity and force field IDs per atom.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.14.1\"><\/a><\/p>\n<h3>\n6.14.1  Template file: <b><tt>MOPACPI.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the quantum chemistry calculation. Note that this is not a valid MOPAC-PI input file. The file only contains a number of keywords, given in table <a href=\"#tab:mopacpi_temp\">6.20<\/a>. The actual input for MOPAC-PI will be generated automatically through the interface.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A fully commented template file-with all possible options, a comprehensive descriptions, and some practical hints-is located at <b><tt>$SHARC\/..\/examples\/SHARC_MOPACPI\/MOPACPI.template<\/tt><\/b>.<br \/>\nFor QM\/MM calculations, a second example template (along with the QM\/MM-specific files) is located at <b><tt>$SHARC\/..\/examples\/SHARC_MOPACPI_Tinker\/MOPACPI.template<\/tt><\/b>.<br \/>\nWe recommend that users start from this template file and modify it appropriately for their calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.20\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.20: Keywords for the <b><tt>MOPACPI.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:mopacpi_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ham <\/td>\n<td align=\"left\">(string) Controls the Hamiltonian used. Options: MNDO, AM1, PM3, RM1, PM6, and PM7. The default keyword is AM1.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">numb_elec <\/td>\n<td align=\"left\">(int) Controls the number of electrons in the active space. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">numb_orb <\/td>\n<td align=\"left\">(int) Controls the number of orbitals in the active space. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">flocc <\/td>\n<td align=\"left\">(float) Floating occupation parameter. Default value is 0.1.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">meci <\/td>\n<td align=\"left\">(int) Number of CI vectors to be printed. Default value is 20.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">mxroot <\/td>\n<td align=\"left\">(int) maximum number of CI vectors calculated by MECI. The default value is 20.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">add_pot <\/td>\n<td align=\"left\">(bool) Controls the additional external potential that can be added in the <tt>ext_param<\/tt> file and described in below. Options: True, False. Default value is False.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">external_par <\/td>\n<td align=\"left\">(int) controls the number of external parameters for the semiempirical Hamiltonian. Theses parameters can be added in the <tt>ext_param<\/tt> file as shown below. The <b><tt>ext_param<\/tt><\/b> file has to be added if <b><tt>external_par<\/tt><\/b> is provided and the value bigger than 0.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">micros <\/td>\n<td align=\"left\">(int) Number entries (microstates) to define the active space of configuration interaction calculations. Definition of the microstates can be included in the ext_param file as a lists of 0 and 1.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">qmmm <\/td>\n<td align=\"left\">Controls the number of external point charges for QM\/MM calculations.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">link_atom_pos <\/td>\n<td align=\"left\">(list of int) List of the index (starting from 1) of the of the atoms involved in the linkbonds. Example: <b><tt>link_atom_pos 1 22<\/tt><\/b>\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">link_atoms <\/td>\n<td align=\"left\">(list of string) Controls the kind of linkbonds used for QM\/MM calculations. Example: <b><tt>link_atoms Hx12.0 Hx12.0<\/tt><\/b>. For the QM calculations atoms with index 1 and 22 (as defined in link_atom_pos are replaced by hydrogens of mass 12.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">force_field <\/td>\n<td align=\"left\">(string) Name of the <tt>Tinker<\/tt> force-field file. The file has to be in the same folder as the <b><tt>MOPACPI.rescources<\/tt><\/b> and <b><tt>MOPACPI.template<\/tt><\/b> files.\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.14.2\"><\/a><\/p>\n<h3>\n6.14.2  Resource file: <b><tt>MOPACPI.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>MOPACPI.resources<\/tt><\/b> contains mainly paths (to the MOPAC-PI executables, to the scratch directory, etc.). This file must reside in the same directory where the interface is started. It uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The MOPAC-PI interface employs the keywords scratchdir, savedir, retain and delay from Table <a href=\"#tab:resources\">6.3<\/a>.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:mopacpi_sh2\">6.21<\/a>.<br \/>\nA fully commented resource file for this interface with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_MOPACPI\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.21\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.21: Keywords for the <b><tt>MOPACPI.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:mopacpi_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">mopacpidir <\/td>\n<td align=\"left\">Is the path to the MOPACPI installation directory. This directory should contain the executable <b><tt>mopacpi<\/tt><\/b>. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. The interface will automatically update the <b><tt>$LD_LIBRARY_PATH<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">qmmm_table <\/td>\n<td align=\"left\">Followed by the path to the connection table file, in S<span style=\"font-size:x-small\">HARC<\/span>-QM\/MM format.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">qmmm_ff_file <\/td>\n<td align=\"left\">Followed by the path to the force field file, in A<span style=\"font-size:x-small\">MBER<\/span>95 format for T<span style=\"font-size:x-small\">INKER<\/span>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">neglected_gradient <\/td>\n<td align=\"left\">Decides how not-requested gradients are reported back (Options: <b><tt>zero<\/tt><\/b>: default, not-requested gradients are zero; <b><tt>gs<\/tt><\/b>: not-requested gradients are equal to ground state gradient; <b><tt>closest<\/tt><\/b>: not-requested gradients are equal to closest-energy requested gradient).\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.14.3\"><\/a><\/p>\n<h3>\n6.14.3  Reparametrized Hamiltonians, definition of microstates and additional potentials: <b><tt>ext_param<\/tt><\/b><\/h3>\n<p>The file <b><tt>ext_param<\/tt><\/b> contains additional parameters for <b><tt>MOPAC-PI<\/tt><\/b>. This file must reside in the same directory where the interface is started.<br \/>\nWhen using the three possible sets of parameters, the exact syntax shown below needs to be followed.<br \/>\nParameters for the reparametrized Hamiltonians need to be preceeded by <b><tt>EXTERNAL PARAMETERS<\/tt><\/b>.<br \/>\nThe definition of the microstates needs to be preceeded by <b><tt>MICROS<\/tt><\/b>.<br \/>\nAnd if a additional potential is used the definition of the needs to start with <b><tt>ADDED POTENTIAL<\/tt><\/b>, followed by a comment line, and needs to end with <b><tt>END ADDED POTENTIAL<\/tt><\/b>.<\/p>\n<pre>\nEXTERNAL PARAMETERS \nUSS     C          -49.5362424932\nUPP     C          -33.7229206876\nBETST   C          -13.7975775576\n...\nFN34    Hx           2.92552463\nPQNS    Hx           2.0\nMICROS\n11111110000001111111000000\n11111101000001111110100000\n...\n11111110000000111111000001\nADDED POTENTIAL\nAZOPOT FENIL\n45 56 44 20 -0.3828085961 82.1722609695 13.4165638641\n46 47 18 4 0.09497 -0.66\nEND ADDED POTENTIAL\n    \n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The full example is given in <b><tt>$SHARC\/..\/examples\/SHARC_MOPACPI_Tinker\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.14.4\"><\/a><\/p>\n<h3>\n6.14.4  QM\/MM force field files<\/h3>\n<p><a id=\"subchap:qmmmm_mopacpi\"><br \/>\n<\/a><br \/>\nIn total threee files need to be provided to run QM\/MM calculations. <\/p>\n<ul>\n<li> <b><tt>oplsaaa.prm<\/tt><\/b>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>MOPACPI_tnk.xyz<\/tt><\/b>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>MOPACPI_tnk.key<\/tt><\/b>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<p>These force field files should be found in the QM directory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.14.5\"><\/a><\/p>\n<h3>\n6.14.5  QM\/MM connection table file: <b><tt>MOPACPI_tnk.xyz<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file defines which atoms are in the QM or MM region, the atom types (for T<span style=\"font-size:x-small\">INKER<\/span>), and the connectivity.<br \/>\nNote that the S<span style=\"font-size:x-small\">HARC<\/span>– MOPAC-PI interface uses newly developed routines to setup QM\/MM calculations and communicate with T<span style=\"font-size:x-small\">INKER<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A sample looks like:<\/p>\n<div class=\"p\"><!----><\/div>\n<pre>\n6056\n1 C      27.179361     30.197594     28.975494     981        3        11        19         0\n2 C      27.955915     27.560778     30.953823     981        4        13        23         0\n3 C      27.179033     31.217045     28.059326     981        1        21        24         0\n4 C      27.971155     26.196959     30.972338     981        2        20        25         0\n5 C      24.798410     30.211231     28.888300     981        6        19        26         0\n6 C      24.813580     31.242962     27.972143     981        5         8        21         0\n7 C      31.083271     33.473904     29.885555     981       10        27        28        29\n8 F      23.663391     31.744644     27.488258     984        6         0         0         0\n9 O      29.496525     29.714893     28.482552     983       11        16         0         0\n...\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The full example is given in <b><tt>$SHARC\/..\/examples\/SHARC_MOPACPI_Tinker\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.14.6\"><\/a><\/p>\n<h3>\n6.14.6  QM\/MM force field file: e.g. <b><tt>oplsaa.prm<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file defines the force field used for the MM part of the calculation.<br \/>\nNote that the path to this file needs to be set in the MOPACPI.template file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>An example is given in <b><tt>$SHARC\/..\/examples\/SHARC_MOPACPI_Tinker\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.14.7\"><\/a><\/p>\n<h3>\n6.14.7  QM\/MM additional force field definition file: <b><tt>MOPACPI_tnk.key<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file defines additional atom types and Coulomb, as well as Lennard-Jones terms. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>An example is given in <b><tt>$SHARC\/..\/examples\/SHARC_MOPACPI_Tinker\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.14.8\"><\/a><\/p>\n<h3>\n6.14.8  During setup<\/h3>\n<p>During setup, <b><tt>SHARC_MOPACPI.py<\/tt><\/b> will ask for a template file (<b><tt>MOPACPI.template<\/tt><\/b>) and in the following question, if external parameters for a reparameterization of the Hamiltonian or additional potentials are needed, the path to <b><tt>ext_params<\/tt><\/b> needs to be give as well.<br \/>\nAfterwards the user is asked for a <b><tt>MOPACPI.resources<\/tt><\/b> file. If no resources file can be provided SHARC will help in the construction of this file.<br \/>\nFor QM\/MM calculations the three files described in <a href=\"#subchap:qmmmm_mopacpi\">6.14.4<\/a> need to be provided too.<br \/>\nFor the construction of these three files we currently have no pipeline, it is completely up to the user to make these files. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.15\"><\/a><\/p>\n<h2>\n6.15  LEGACY Interface<\/h2>\n<p><a id=\"sec:int:legacy\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>An interface that provides backwards compatibility of S<span style=\"font-size:x-small\">HARC<\/span>4 with S<span style=\"font-size:x-small\">HARC<\/span>3-style interfaces.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p> S<span style=\"font-size:x-small\">HARC<\/span>4 contains very extensive changes to the previously existing interface infrastructure, due to the switch to object-oriented, inherited interface classes and the addition of nestable hybrid interfaces.<br \/>\nThese changes made it necessary to rewrite or extensively modify the existing interfaces.<br \/>\nCurrently, not all previous interfaces were converted to the new interface infrastructure.<br \/>\nIn order to use those S<span style=\"font-size:x-small\">HARC<\/span>3-style interfaces within S<span style=\"font-size:x-small\">HARC<\/span>4, we provide <b><tt>SHARC_LEGACY.py<\/tt><\/b>.<br \/>\n<b><tt>SHARC_LEGACY.py<\/tt><\/b> is a somewhat untypical mixture of an ab initio interface (it calls external software via a shell call) and a hybrid interface (it calls another interface).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Energies, spin-orbit couplings, dipole moments, gradients, nonadiabatic couplings, overlaps, Dyson norms, and TheoDORE descriptors are available.<br \/>\nElectrostatic embedding (i.e., QM\/MM), multipolar density representations, and density matrices are not available.<br \/>\nWith <b><tt>SHARC_LEGACY.py<\/tt><\/b>, the following five interfaces can be used:<br \/>\n<b><tt>SHARC_AMS_ADF.py<\/tt><\/b>, <b><tt>SHARC_COLUMBUS.py<\/tt><\/b>, <b><tt>SHARC_BAGEL.py<\/tt><\/b>, <b><tt>SHARC_MOLPRO.py<\/tt><\/b>, and <b><tt>SHARC_PYSCF.py<\/tt><\/b>.<br \/>\n<b><tt>SHARC_LEGACY.py<\/tt><\/b> here takes care of (i) providing the setup routines for these interfaces, so that they can be used with the updated <b><tt>setup_*.py<\/tt><\/b> scripts, (ii) the updated time step logic of S<span style=\"font-size:x-small\">HARC<\/span>4, and (iii) providing a legal importable and callable interface that can be used as child interface for hybrids like <b><tt>SHARC_NUMDIFF.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_LEGACY.py<\/tt><\/b> needs two input files, called <b><tt>LEGACY.template<\/tt><\/b> and <b><tt>LEGACY.resources<\/tt><\/b>.<br \/>\nNote that the interface cannot access or affect the settings of the chosen child interface.<br \/>\nFor the documentation of their input, see the respective sections.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.15.1\"><\/a><\/p>\n<h3>\n6.15.1  Template file: <b><tt>LEGACY.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specification of the chosen legacy child interface and the path to the directory containing the input files for the legacy child.<br \/>\nThe possible keywords are given in Table <a href=\"#tab:legacy_temp\">6.22<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.22\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.22: Keywords for the <b><tt>LEGACY.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:legacy_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">child_program <\/td>\n<td align=\"left\">Selects the legacy child. Can be one of <b><tt>ams_adf<\/tt><\/b>, <b><tt>columbus<\/tt><\/b>, <b><tt>bagel<\/tt><\/b>, <b><tt>molpro<\/tt><\/b>, <b><tt>pyscf<\/tt><\/b> (not case sensitive). No default.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">child_dir <\/td>\n<td align=\"left\">Defines the path to the directory containing the child’s interface-specific files.\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p>The folders <b><tt>$SHARC\/..\/examples\/SHARC_LEGACY_*<\/tt><\/b> provide example inputs for each of the five legacy interfaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.15.2\"><\/a><\/p>\n<h3>\n6.15.2  Resource file: <b><tt>LEGACY.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file currently has only one keyword, as documented in Table <a href=\"#tab:legacy_res\">6.23<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.23\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.23: Keywords for the <b><tt>LEGACY.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:legacy_res\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scratchdir <\/td>\n<td align=\"left\">The directory to run the child inside. Do not use the same as the scratchdir for the child. Default is to run it in <b><tt>$(pwd)\/SCRATCH<\/tt><\/b>.\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.15.3\"><\/a><\/p>\n<h3>\n6.15.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>During setup, <b><tt>SHARC_LEGACY.py<\/tt><\/b> uses specific routines for each of the legacy interfaces, see below.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.16\"><\/a><\/p>\n<h2>\n6.16  AMS-ADF Interface<\/h2>\n<p><a id=\"sec:int:adf\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Legacy ab initio interface for TD-DFT with the ADF engine of the Amsterdam Modeling Suite (AMS).<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>-AMS-ADF interface <b><tt>SHARC_AMS_ADF.py<\/tt><\/b> allows to run S<span style=\"font-size:x-small\">HARC<\/span> simulations with ADF’s TD-DFT functionality.<br \/>\nThe interface is compatible with restricted and unrestricted ground states, but not with symmetry.<br \/>\nSpin-orbit couplings are obtained with the perturbative ZORA formalism, and wave function overlaps from the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code are available (but no nonadiabatic couplings).<br \/>\nDyson norms can also be computed through the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code.<br \/>\n T<span style=\"font-size:x-small\">HEO<\/span>DORE (version 2.0 and higher) can be used to perform automatic wave function analysis.<br \/>\nThe previous QM\/MM capabilities of the S<span style=\"font-size:x-small\">HARC<\/span>-AMS-ADF interface are not available anymore, due to significant restructuring of QM\/MM within AMS.<br \/>\nQM\/MM is also not possible via S<span style=\"font-size:x-small\">HARC<\/span>4’s capabilities, because legacy interfaces cannot handle point charges.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>AMS_ADF.template<\/tt><\/b>) and a resource file (<b><tt>AMS_ADF.resources<\/tt><\/b>).<br \/>\nIf files <b><tt>QM\/AMS_ADF.t21.<job>.init<\/tt><\/b> are present, they are used to provide an initial orbital guess for the SCF calculation of the respective job.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface automatically uses Python code provided with AMS to allow reading of ADF’s binary output files.<br \/>\nOnly AMS2020 or newer is supported, as in older versions ADF was not available through the AMS driver.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>-AMS-ADF interface is a legacy interface, usable in S<span style=\"font-size:x-small\">HARC<\/span>4 through <b><tt>SHARC_LEGACY.py<\/tt><\/b>, in particular considering the setup routines.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.16.1\"><\/a><\/p>\n<h3>\n6.16.1  Template file: <b><tt>AMS_ADF.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the quantum chemistry calculation.<br \/>\nNote that this is not a valid AMS input file.<br \/>\nThe file only contains a number of keywords, given in table <a href=\"#tab:adf_temp\">6.24<\/a>.<br \/>\nThe actual input for AMS will be generated automatically through the interface.<br \/>\nIn order to enable many functionalities of AMS\/ADF and to allow fine-tuning of the performance for large calculations, the template has a relatively large number of keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A fully commented template file-with all possible options, a comprehensive descriptions, and some practical hints-is located in <b><tt>$SHARC\/..\/examples\/SHARC_AMS_ADF\/AMS_ADF.template<\/tt><\/b>.<br \/>\nWe recommend that users start from this template file and modify it appropriately for their calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.24\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.24: Keywords for the <b><tt>AMS_ADF.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:adf_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis <\/td>\n<td align=\"left\">Gives the basis set for all atoms (default SZ).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis_path <\/td>\n<td align=\"left\">gives the path to the basis library of ADF ( and $ can be used).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis_per_element <\/td>\n<td align=\"left\">Followed by an elemental symbol (e.g., “Fe”, “H.1”) and then by a path to the desired ADF basis set file. Files with frozen core should not be used.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">define_fragment <\/td>\n<td align=\"left\">Followed by an elemental symbol (e.g., “Fe”, “H.1”) and then by a list of atom numbers which should belong to this atom type.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">functional <\/td>\n<td align=\"left\">Followed by two strings. First argument gives the type of functional (LDA, GGA, hybrid), second argument gives the functional (VWN, BP86, B3LYP, …).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">functional_xcfun <\/td>\n<td align=\"left\">Enables functional evaluation with the XCFun library within ADF.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dispersion <\/td>\n<td align=\"left\">If present, is written verbatim to ADF input with all arguments.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">relativistic <\/td>\n<td align=\"left\">If not given, perform a nonrelativistic calculation. Otherwise, copy the line verbatim to the ADF input.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">charge <\/td>\n<td align=\"left\">Sets the total charge of the system. Can be either followed by a single integer (then the interface will automatically assign the charges to the multiplicities) or by one charge per multiplicity. <b>Note that as a legacy interface, SHARC or parent interfaces cannot control the charges directly, so they have to be defined in the template file<\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">totalenergy <\/td>\n<td align=\"left\">Activates the computation of total energies (by default, ADF computes binding energies). Does not work for relativistic calculations.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">cosmo <\/td>\n<td align=\"left\">Followed by a string giving a solvent. Activates COSMO (no gradients possible).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">cosmo_neql <\/td>\n<td align=\"left\">Activates non-equilibrium solvation, which is needed for vertical excitation calculations. Is followed by a float giving the square of the refractive index of the solvent.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">grid <\/td>\n<td align=\"left\">Followed by two strings (e.g., <b><tt>beckegrid normal<\/tt><\/b> or <b><tt>integration 4.0<\/tt><\/b>) defining which integration grid and accuracy to use. For details, see the example template file.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">grid_per_atom <\/td>\n<td align=\"left\">Followed by a string (e.g., <b><tt>basic<\/tt><\/b>, <b><tt>normal<\/tt><\/b>, <b><tt>good<\/tt><\/b>) and a list of the atoms which should have the given integration accuracy. Can be used multiple times with different qualities.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">fit <\/td>\n<td align=\"left\">Followed by two strings (e.g., <b><tt>zlmfit normal<\/tt><\/b> or <b><tt>stofit<\/tt><\/b>) defining which Coulomb integration method and accuracy to use. For details, see the example template file.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">fit_per_atom <\/td>\n<td align=\"left\">Works like <b><tt>grid_per_atom<\/tt><\/b>, but for the Coulomb method accuracy.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">exactdensity <\/td>\n<td align=\"left\">Enables the <b><tt>exactdensity<\/tt><\/b> keyword in the ADF input.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">rihartreefock <\/td>\n<td align=\"left\">Followed by a quality keyword (e.g., <b><tt>basic<\/tt><\/b>, <b><tt>normal<\/tt><\/b>, <b><tt>good<\/tt><\/b>). If not present, the old HF exchange routines in ADF are used.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">rihf_per_atom <\/td>\n<td align=\"left\">Works like <b><tt>grid_per_atom<\/tt><\/b>, but for the RI Hartree Fock method.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">linearscaling <\/td>\n<td align=\"left\">Followed by an integer (between 0 and 99), which controls whether certain terms are neglected in ADF.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">cpks_eps <\/td>\n<td align=\"left\">Followed by a float (default 0.0001) giving the convergence threshold in the CPKS equations for excited-state gradients.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">occupations <\/td>\n<td align=\"left\">If present, the foll line is copied verbatim to the ADF input.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scf_iterations <\/td>\n<td align=\"left\">Followed by the maximum number of SCF iterations (default: 100)\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">no_tda <\/td>\n<td align=\"left\">This keyword deactivates TDA, which the interface requests by default.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">fullkernel <\/td>\n<td align=\"left\">Uses the full (non-ALDA) kernel in TD-DFT. Not compatible with gradients, and automatically activates <b><tt>functional_xcfun<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">paddingstates <\/td>\n<td align=\"left\">Followed by a list of integers, which give the number of extra states to compute by ADF, but which are neglected in the output. Should not be changed between time steps, as this will break ADF’s restart routines.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dvd_vectors <\/td>\n<td align=\"left\">Number of Davidson vectors. Default: min(40,nstates+40).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dvd_tolerance <\/td>\n<td align=\"left\">Energy convergence criterion for the excited states (in Hartree).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">unrestricted_triplets <\/td>\n<td align=\"left\">Requests that the triplets are calculated in a separate job from an unrestricted ground state (no spin-orbit couplings available). Default is to compute triplets as linear response of the restricted singlet ground state.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">modifyexcitations <\/td>\n<td align=\"left\">Followed by an integer, indicating that excitation should only be possible from the first n MOs. Can be used to compute core-excitation states (for X-Ray spectra).\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.16.2\"><\/a><\/p>\n<h3>\n6.16.2  Resource file: <b><tt>AMS_ADF.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>AMS_ADF.resources<\/tt><\/b> contains mainly paths (to the AMS executables, to the scratch directory, etc.) and other resources, plus settings for <b><tt>wfoverlap.x<\/tt><\/b> and T<span style=\"font-size:x-small\">HEO<\/span>DORE. This file must reside in the same directory where the interface is started. It uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The AMS-ADF interface employs essentially all keywords from Tables <a href=\"#tab:resources\">6.3<\/a> (except: ngpu), as well as WF<span style=\"font-size:x-small\">OVERLAP<\/span> and T<span style=\"font-size:x-small\">HEO<\/span>DORE keywords from Table <a href=\"#tab:resources_aux\">6.4<\/a>.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:adf_sh2\">6.25<\/a>.<br \/>\nA fully commented resource file with all possible options and comprehensive descriptions is located in <b><tt>$SHARC\/..\/examples\/SHARC_AMS_ADF\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.25\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.25: Keywords for the <b><tt>AMS_ADF.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:adf_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">adfhome <\/td>\n<td align=\"left\">Is the path to the ADF installation. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. The interface will set <b><tt>$ADFHOME<\/tt><\/b> to this path, and will also set <b><tt>$ADFBIN<\/tt><\/b> to <b><tt>$ADFHOME\/bin\/<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scmlicense <\/td>\n<td align=\"left\">Is the path to the ADF license file. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scm_tmpdir <\/td>\n<td align=\"left\">Path to the ADF-internal scratch directory. Usually, this is set at installation, but can be overridden here. Should not exist and must not be identical to scratchdir.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">neglected_gradient <\/td>\n<td align=\"left\">Decides how not-requested gradients are reported back (Options: <b><tt>zero<\/tt><\/b>: default, not-requested gradients are zero; <b><tt>gs<\/tt><\/b>: not-requested gradients are equal to ground state gradient; <b><tt>closest<\/tt><\/b>: not-requested gradients are equal to closest-energy requested gradient).\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p><b>Parallelization  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>ADF usually shows very good parallel scaling for most calculations.<br \/>\nHowever, it is more efficient to carry out multiple ADF calculations (different multiplicities, multiple gradients) in parallel, each one using a smaller number of CPUs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the S<span style=\"font-size:x-small\">HARC<\/span>-AMS-ADF interface, parallelization is controlled by the keywords <b><tt>ncpu<\/tt><\/b> and <b><tt>schedule_scaling<\/tt><\/b>.<br \/>\nThe first keyword controls the maximum number of CPUs which the interface is allowed to use for all ADF runs simultaneously.<br \/>\nThe second keyword is the parallel fraction from Amdahl’s Law, see Section <a href=\"#met:amdahl\">8.3<\/a>.<br \/>\nWith a value close to zero, the interface will try to run all jobs at the same time. With values close to one, jobs will be run sequentially with the maximum number of cores.<br \/>\nTypical values for <b><tt>schedule_scaling<\/tt><\/b> are 0.95 for GGA functionals, 0.75 for hybrid functionals, and 0.90 for hybrid functions in combination with the <b><tt>rihartreefock<\/tt><\/b> option.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that multiple gradients can be computed in a single ADF run, so that there will be multiple jobs to schedule only if including several multiplicities (beyond singlet plus triplet).<br \/>\nIf only a single multiplicity is computed (or singlets plus triplets), then the <b><tt>schedule_scaling<\/tt><\/b> keyword does not have any effect.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.16.3\"><\/a><\/p>\n<h3>\n6.16.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>If you want to setup trajectories for <b><tt>SHARC_AMS_ADF.py<\/tt><\/b>, you have to select in the respective setup script the <b><tt>SHARC_LEGACY.py<\/tt><\/b> legacy frontend interface.<br \/>\nThis is because <b><tt>SHARC_AMS_ADF.py<\/tt><\/b> is not yet converted to S<span style=\"font-size:x-small\">HARC<\/span>4 format and thus does not have its own setup routines.<br \/>\nThe setup routines are instead in <b><tt>SHARC_LEGACY.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After selecting <b><tt>SHARC_LEGACY.py<\/tt><\/b>, you will directly get prompted for which of the five legacy interfaces you want to use.<br \/>\nSelect <b><tt>SHARC_AMS_ADF.py<\/tt><\/b>.<br \/>\nLater during setup, the setup dialogue for <b><tt>SHARC_AMS_ADF.py<\/tt><\/b> will be carried out.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During the setup dialogue, you are first queried whether you want to setup <b><tt>$AMSHOME<\/tt><\/b> and <b><tt>$SCMLICENSE<\/tt><\/b> from the <b><tt>amsrc.sh<\/tt><\/b> file or give the paths manually.<br \/>\nThen you are asked for the path to the template file.<br \/>\nThe template file needs to contain at least the basis set, functional, and charge.<br \/>\nNote that, as a non- S<span style=\"font-size:x-small\">HARC<\/span>4 interface, <b><tt>SHARC_AMS_ADF.py<\/tt><\/b> does not receive the desired charge from the S<span style=\"font-size:x-small\">HARC<\/span> driver, but reads it from the template file.<br \/>\nMake sure that the charge in the template file and in the dynamics input is consistent.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Subsequently, the setup queries for the initial MO files (<b><tt>.t21<\/tt><\/b> or <b><tt>.rkf<\/tt><\/b> files).<br \/>\nFor DFT-based trajectories, initial MO files are not strictly necessary, but might speed up the first time step.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, the setup dialogue asks for the information for the resource file.<br \/>\nIt queries for the number of CPU cores and the parallel scaling.<br \/>\nMemory usage cannot be controlled by <b><tt>SHARC_AMS_ADF.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If wave function overlaps are needed, the code queries for the path to the overlap executable, the wave function truncation threshold, and the memory limit.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If TheoDORE wave function analysis was selected, it also asks for the path to TheoDORE, the descriptors, and the fragmentation scheme.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.16.4\"><\/a><\/p>\n<h3>\n6.16.4  Frequencies converter: <b><tt>AMS_ADF_freq.py<\/tt><\/b><\/h3>\n<p><a id=\"sec:AMS_ADF_freq.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The small script <b><tt>AMS_ADF_freq.py<\/tt><\/b> can be used to convert the standard output or the <b><tt>adf.rkf<\/tt><\/b> file created by an ADF frequency calculation.<br \/>\nThe usage is very simple:<\/p>\n<pre>\n$SHARC\/AMS_ADF_freq.py ADF.out\n<\/pre>\n<p>or:<\/p>\n<pre>\n$SHARC\/AMS_ADF_freq.py adf.rkf\n<\/pre>\n<p>The script detects automatically the file format.<br \/>\nNote that in ADF, the infrared intensities are only accessible from the standard output, so use this for IR spectrum generation.<br \/>\nHowever, the data in <b><tt>adf.rkf<\/tt><\/b> has a higher numeric precision, so it is recommended to convert the <b><tt>adf.rkf<\/tt><\/b> file if no intensities are needed.<br \/>\nIn any case, a file called <b><tt><filename>.molden<\/tt><\/b> is written, containing the frequencies and normal modes.<br \/>\nThis file can then be used with <b><tt>wigner.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.17\"><\/a><\/p>\n<h2>\n6.17  COLUMBUS Interface<\/h2>\n<p><a id=\"sec:int:columbus\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Legacy ab initio interface for RASSCF and MRCISD calculations in the C<span style=\"font-size:x-small\">OLUMBUS<\/span> package.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– C<span style=\"font-size:x-small\">OLUMBUS<\/span> interface allows to run S<span style=\"font-size:x-small\">HARC<\/span> dynamics based on C<span style=\"font-size:x-small\">OLUMBUS<\/span>‘ CASSCF, RASSCF and MRCI wave functions.<br \/>\nThe interface is compatible to C<span style=\"font-size:x-small\">OLUMBUS<\/span> calculations utilizing the C<span style=\"font-size:x-small\">OLUMBUS<\/span>– M<span style=\"font-size:x-small\">OLCAS<\/span> interface ( S<span style=\"font-size:x-small\">EWARD<\/span> integrals and A<span style=\"font-size:x-small\">LASKA<\/span> gradients), or using the D<span style=\"font-size:x-small\">ALTON<\/span> integral code distributed with C<span style=\"font-size:x-small\">OLUMBUS<\/span>.<br \/>\nUsing S<span style=\"font-size:x-small\">EWARD<\/span> integrals, spin-orbit couplings can be calculated, but no nonadiabatic couplings (only overlaps can thus be used).<br \/>\nUsing D<span style=\"font-size:x-small\">ALTON<\/span> integrals, spin-orbit couplings are not possible, but nonadiabatic couplings can be calculated.<br \/>\nThe CASSCF step can be done with either C<span style=\"font-size:x-small\">OLUMBUS<\/span>‘ <b><tt>mcscf<\/tt><\/b> code (all features available) or with M<span style=\"font-size:x-small\">OLCAS<\/span>‘ <b><tt>rasscf<\/tt><\/b> code (faster, but no gradients possible).<br \/>\nThe interface utilizes the WF<span style=\"font-size:x-small\">OVERLAP<\/span> program to calculate the overlap matrices.<br \/>\nThe interface can also calculate Dyson norms between neutral and ionic wave functions using the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code.<br \/>\nQM\/MM is not possible via S<span style=\"font-size:x-small\">HARC<\/span>4’s capabilities, because legacy interfaces cannot handle point charges.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs as additional input the file <b><tt>QM\/COLUMBUS.resources<\/tt><\/b> and a template directory containing all input files needed for the C<span style=\"font-size:x-small\">OLUMBUS<\/span> calculations. Initial MOs can be given in the file <b><tt>QM\/mocoef_mc.init<\/tt><\/b>.<br \/>\nFor multiple jobs, initial MOs can be given as <b><tt>QM\/mocoef_mc.init.<job><\/tt><\/b>.<br \/>\nFor runs with <b><tt>rasscf<\/tt><\/b>, initial MOs have to be given as <b><tt>molcas.RasOrb.init<\/tt><\/b> or <b><tt>molcas.RasOrb.init.<job><\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– C<span style=\"font-size:x-small\">OLUMBUS<\/span> interface is a legacy interface, usable in S<span style=\"font-size:x-small\">HARC<\/span>4 through <b><tt>SHARC_LEGACY.py<\/tt><\/b>, in particular considering the setup routines.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.17.1\"><\/a><\/p>\n<h3>\n6.17.1  Template input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interface does not generate the full C<span style=\"font-size:x-small\">OLUMBUS<\/span> input on-the-fly.<br \/>\nInstead, the interface uses an existing set of input files and performs only necessary modifications (e.g., the number of states).<br \/>\nThe set of input files must be provided by the user.<br \/>\nPlease see the <a href=\"https:\/\/columbus-program-system.gitlab.io\/columbus\/doc.html\"> C<span style=\"font-size:x-small\">OLUMBUS<\/span> online documentation<\/a> and, most importantly, the<br \/>\n<a href=\"https:\/\/columbus-program-system.gitlab.io\/columbus\/tutorial-SO.pdf\"> C<span style=\"font-size:x-small\">OLUMBUS<\/span> SOCI tutorial<\/a> for a documentation of the necessary input.<br \/>\nThe S<span style=\"font-size:x-small\">HARC<\/span> tutorial also has a section about generating the required C<span style=\"font-size:x-small\">OLUMBUS<\/span> input file collection.<br \/>\nAn example template directory is located in <b><tt>$SHARC\/..\/examples\/SHARC_COLUMBUS\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Generally, the input consists of a directory with one subdirectory with input for each multiplicity (singlets, doublets, triplets, …).<br \/>\nHowever, even-electron wave functions of different multiplicities can be computed together in the same job if spin-orbit couplings are desired.<br \/>\nIndependent multiple-DRT inputs (ISC keyword) are also acceptable.<br \/>\nNote that symmetry is not allowed when using the interface.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Note that as a legacy interface, SHARC or parent interfaces cannot control the molecular charge per multiplicity directly, so you need to prepare all C<span style=\"font-size:x-small\">OLUMBUS<\/span> input with the correct charges in mind.<\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The path to the template directory must be given in <b><tt>COLUMBUS.resources<\/tt><\/b>, along with the other resources settings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Integral input  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface is able to use input for calculations using S<span style=\"font-size:x-small\">EWARD<\/span> or D<span style=\"font-size:x-small\">ALTON<\/span> integrals.<br \/>\nIf you want to calculate SOCs, you have to use S<span style=\"font-size:x-small\">EWARD<\/span> and have to include the AMFI keyword in the integral input.<br \/>\nIf you use D<span style=\"font-size:x-small\">ALTON<\/span>, SOCs are not available, but it is possible to compute nonadiabatic couplings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>It is important to make sure that <b>the order of atoms<\/b> in the template input files and in the S<span style=\"font-size:x-small\">HARC<\/span> input <b>is consistent<\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>It is necessary to prepare all template subdirectories with the same integral code and the same AO basis set. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>MCSCF input  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The MCSCF section can use any desired state-averaging scheme, since the number of states in MCSCF is independent of the number of states in the MRCI module. However, frozen core orbitals in the MCSCF step are not possible (since otherwise gradients cannot be computed). Prepare the MCSCF input for CI gradients. It is advisable to use very tight MCSCF convergence criteria.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If gradients are not needed, you can also manually prepare a M<span style=\"font-size:x-small\">OLCAS<\/span> RASSCF input in <b><tt>molcas.input<\/tt><\/b>, in order to use M<span style=\"font-size:x-small\">OLCAS<\/span> RASSCF instead of C<span style=\"font-size:x-small\">OLUMBUS<\/span> MCSCF (see <b><tt>molcas_rasscf<\/tt><\/b> keyword).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>MRCI input  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Either prepare a single-DRT input without SOCI (to cover a single multiplicity), a single-DRT input with SOCI and a sufficient maximum multiplicity for spin-orbit couplings or an independent multiple-DRT input (as, e.g., for ISC optimizations). Make sure that all multiplicities are covered with all input directories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the MRCI input, make sure to use sequential <b><tt>ciudg<\/tt><\/b>. Also take care to setup gradient input on MRCI level.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Job control  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Setup a single-point calculation with the following steps:<\/p>\n<ul>\n<li> SCF\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> MCSCF\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> MR-CISD (serial operation) <b>or<\/b> SO-CI coupled to non-rel CI (for SOCI DRT inputs)\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> one-electron properties for all methods\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> transition moments for MR-CISD\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> nonadiabatic couplings (and\/or gradients)\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>Request first transition moments and interstate couplings (or alternatively full nonadiabatic couplings if Dalton integrals are used) in the following dialogues. Analysis in internal coordinates and intersection slope analysis are not required.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.17.2\"><\/a><\/p>\n<h3>\n6.17.2  Resource file: <b><tt>COLUMBUS.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The C<span style=\"font-size:x-small\">OLUMBUS<\/span> interface employs essentially all keywords from Tables <a href=\"#tab:resources\">6.3<\/a> (except: ngpu), as well as WF<span style=\"font-size:x-small\">OVERLAP<\/span> keywords from Table <a href=\"#tab:resources_aux\">6.4<\/a>.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:columbus_sh2\">6.26<\/a>.<br \/>\nA fully commented resource file with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_COLUMBUS\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.26\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<table>\n<tr>\n<td colspan=\"3\" align=\"left\">\n<div style=\"text-align:center\">Table 6.26: Keywords for the <b><tt>COLUMBUS.resources<\/tt><\/b> file.<\/div>\n<\/td>\n<\/tr>\n<p><a id=\"tab:columbus_sh2\"><br \/>\n<\/a><\/p>\n<tr>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><span class=\"roman\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p>columbus <\/td>\n<td align=\"left\">Path to the C<span style=\"font-size:x-small\">OLUMBUS<\/span> main directory. This directory should contain executables like <b><tt>runc<\/tt><\/b>, <b><tt>mcscf.x<\/tt><\/b>, <b><tt>cidrt.x<\/tt><\/b>, or <b><tt>ciudg.x<\/tt><\/b>. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">molcas <\/td>\n<td align=\"left\">Path to the M<span style=\"font-size:x-small\">OLCAS<\/span> main directory. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. This path is only used to get the AO overlaps for overlap\/Dyson calculations (since in this case the interface calls M<span style=\"font-size:x-small\">OLCAS<\/span> explicitly). Otherwise C<span style=\"font-size:x-small\">OLUMBUS<\/span> will use the path to M<span style=\"font-size:x-small\">OLCAS<\/span> specified during the installation of C<span style=\"font-size:x-small\">OLUMBUS<\/span>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">runc <\/td>\n<td align=\"left\">Path to the <b><tt>runc<\/tt><\/b> script for C<span style=\"font-size:x-small\">OLUMBUS<\/span> execution. Default is <b><tt>$COLUMBUS\/runc<\/tt><\/b>. This keyword is intended for users who like to modify <b><tt>runc<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">wfoverlap <\/td>\n<td align=\"left\">Path to WF<span style=\"font-size:x-small\">OVERLAP<\/span>. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. Only necessary if overlaps or Dyson norms are calculated.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">integrals <\/td>\n<td align=\"left\">Followed by a string which is either <b><tt>seward<\/tt><\/b> or <b><tt>dalton<\/tt><\/b>. Chooses the integral program for C<span style=\"font-size:x-small\">OLUMBUS<\/span>. Note that with D<span style=\"font-size:x-small\">ALTON<\/span> integrals SOC is not available. Default is <b><tt>seward<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">molcas_rasscf <\/td>\n<td align=\"left\">Use M<span style=\"font-size:x-small\">OLCAS<\/span>‘ RASSCF program instead of C<span style=\"font-size:x-small\">OLUMBUS<\/span>‘ MCSCF program. Needs a properly prepared C<span style=\"font-size:x-small\">OLUMBUS<\/span> input (<b><tt>&RASSCF<\/tt><\/b> section in <b><tt>molcas.input<\/tt><\/b>). Note that gradients are not available in this mode.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">template <\/td>\n<td align=\"left\">Is followed by the path to the directory containing the template subdirectories. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. See also <a href=\"#int:col:template\">6.17.3<\/a>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">DIR <\/td>\n<td align=\"left\">See <a href=\"#int:col:template\">6.17.3<\/a>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MOCOEF <\/td>\n<td align=\"left\">See <a href=\"#int:col:template\">6.17.3<\/a>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.17.3\"><\/a><\/p>\n<h3>\n6.17.3  Template setup<\/h3>\n<p><a id=\"int:col:template\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The template directory contains several subdirectories with input for different multiplicities. An example is given in figure <a href=\"#fig:dirs_COLtemp\">6.2<\/a>. In <b><tt>COLUMBUS.resources<\/tt><\/b>, the user has to associate each multiplicity to a subdirectory. The line “<b><tt>DIR 1 Sing_Trip<\/tt><\/b>” would make the interface use the input files from the subdirectory <b><tt>Sing_Trip<\/tt><\/b> when calculating singlet states (the <b><tt>1<\/tt><\/b> refers to singlet calculations). All calculations using a particular input subdirectory are called a job.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Additionally, the user must specify which job(s) provide the MO coefficients (e.g., the calculation for doublet states could be based on the same MOs as the singlet and triplet calculation). The line “<b><tt>MOCOEF Doub_Quar Sing_Trip<\/tt><\/b>” would tell the interface to do a MCSCF calculation in the <b><tt>Sing_Trip<\/tt><\/b> job, and reuse the MOs when doing the <b><tt>Doub_Quar<\/tt><\/b> job without reoptimizing the MOs.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg6.2\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/dirs_COLtemp.png\"> <\/p>\n<div style=\"text-align:center\">Figure 6.2: Example directory structure of the C<span style=\"font-size:x-small\">OLUMBUS<\/span> template directory<\/div>\n<p> <a id=\"fig:dirs_COLtemp\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.17.4\"><\/a><\/p>\n<h3>\n6.17.4  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>If you want to set up trajectories for <b><tt>SHARC_COLUMBUS.py<\/tt><\/b>, you have to select in the respective setup script the <b><tt>SHARC_LEGACY.py<\/tt><\/b> legacy frontend interface.<br \/>\nThis is because <b><tt>SHARC_COLUMBUS.py<\/tt><\/b> is not yet converted to the S<span style=\"font-size:x-small\">HARC<\/span>4 format and does not have its own setup routines.<br \/>\nThe setup routines are instead in <b><tt>SHARC_LEGACY.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After selecting <b><tt>SHARC_LEGACY.py<\/tt><\/b>, you will directly be prompted for which of the five legacy interfaces you want to use.<br \/>\nSelect <b><tt>SHARC_COLUMBUS.py<\/tt><\/b>.<br \/>\nLater during setup, the setup dialogue for <b><tt>SHARC_COLUMBUS.py<\/tt><\/b> will be carried out.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During the setup dialogue, you are first queried for the path to the COLUMBUS installation.<br \/>\nYou can accept the path from the <b><tt>$COLUMBUS<\/tt><\/b> environment variable or enter one manually.<br \/>\nThen you are asked for the scratch directory, where COLUMBUS will store temporary files.<br \/>\nThis directory will be deleted after the calculation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the setup prompts for the path to the COLUMBUS template directory.<br \/>\nThe template directory must contain at least one subdirectory for each multiplicity that will be simulated.<br \/>\nEach subdirectory must contain all required input files (<b><tt>control.run<\/tt><\/b>, <b><tt>mcscfin<\/tt><\/b>, <b><tt>tranin<\/tt><\/b>, <b><tt>propin<\/tt><\/b>, <b><tt>cidrtin<\/tt><\/b>, <b><tt>ciudgin<\/tt><\/b>, and optionally <b><tt>cidrtin.*<\/tt><\/b> for multiple DRTs).<br \/>\nThe script will attempt to match each multiplicity to one of the provided subdirectories automatically.<br \/>\nIf necessary, you can manually assign which subdirectory to use for which multiplicity.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Afterward, the script asks for the mapping of <b><tt>mocoef<\/tt><\/b> (MO coefficient) files across multiplicities.<br \/>\nEach job (multiplicity-specific subdirectory) can reuse the <b><tt>mocoef<\/tt><\/b> file from another job.<br \/>\nIn this way, you can, e.g., base all multiplicities’ MRCI computations on the singlet MOs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If desired, you can choose to copy the entire template directory into each trajectory folder.<br \/>\nBy default, it is only linked.<br \/>\nNote that copying will produce a large number of files and directories, especially with many trajectories.<br \/>\nNote that, as a non- S<span style=\"font-size:x-small\">HARC<\/span>4 interface, the charge given in the template file is not checked against the charges in the dynamics input.<br \/>\nUsers must make sure that these are consistent.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>You are then asked whether you have an initial MO guess file (e.g., <b><tt>mocoef_mc.init<\/tt><\/b>).<br \/>\nWhile optional, it is strongly recommended to provide one, as CASSCF calculations can otherwise become unstable or very slow.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, you are prompted to enter the amount of memory (in MB) to be made available to COLUMBUS.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If wave function overlaps are needed, the script asks for the path to the overlap executable, the determinant screening threshold, and the number of frozen core orbitals.<br \/>\nIf Dyson orbital analysis is also selected, the number of doubly occupied orbitals must be provided.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.18\"><\/a><\/p>\n<h2>\n6.18   B<span style=\"font-size:x-small\">AGEL<\/span> Interface<\/h2>\n<p><a id=\"sec:int:bagel\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Legacy ab initio interface for multi-reference methods in the B<span style=\"font-size:x-small\">AGEL<\/span> package.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– B<span style=\"font-size:x-small\">AGEL<\/span> interface allows to run S<span style=\"font-size:x-small\">HARC<\/span> simulations with B<span style=\"font-size:x-small\">AGEL<\/span>‘s CASSCF, SS-CASPT2, MS-CASPT2, and XMS-CASPT2 functionalities.<br \/>\nThe interface is compatible with all multiplicities, but not with symmetry.<br \/>\nNote that separate active spaces are used for each multiplicity.<br \/>\n B<span style=\"font-size:x-small\">AGEL<\/span> features analytical gradients and nonadiabatic couplings for all of these methods, but no spin-orbit coupings.<br \/>\nWave function overlaps and Dyson norms can be obtained from the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code.<br \/>\nQM\/MM is not possible, as legacy interfaces cannot handle point charges.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that B<span style=\"font-size:x-small\">AGEL<\/span> does not allow extracting the AO overlap matrix that is required for overlap and Dyson norm calculations; hence, the S<span style=\"font-size:x-small\">HARC<\/span>– B<span style=\"font-size:x-small\">AGEL<\/span> interface computes the AO overlaps through P<span style=\"font-size:x-small\">Y<\/span>SCF.<br \/>\nAlso note that, currently, it is not recommended to work with MS-CASPT2 gradients and XMS-CASPT2 should always be preferred.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface needs two additional input files, a template file for the quantum chemistry (file name is <b><tt>BAGEL.template<\/tt><\/b>) and a resource file (<b><tt>BAGEL.resources<\/tt><\/b>).<br \/>\nIf files <b><tt>QM\/archive.<mult>.init<\/tt><\/b> are present, they are used to provide an initial orbital guess for the CASSCF calculation of the respective multiplicity.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Note that as a legacy interface, SHARC or parent interfaces cannot control the molecular charge per multiplicity directly, so you need to prepare all B<span style=\"font-size:x-small\">AGEL<\/span> input with the correct charges in mind.<\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that when running B<span style=\"font-size:x-small\">AGEL<\/span>, it might be necessary for the user to set <b><tt>$LD_LIBRARY_PATH<\/tt><\/b> appropriately, so that all relevant libraries (<b><tt>boost<\/tt><\/b>, <b><tt>fabric<\/tt><\/b>, …) can be found.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.18.1\"><\/a><\/p>\n<h3>\n6.18.1  Template file: <b><tt>BAGEL.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the quantum chemistry calculation. Note that this is not a valid B<span style=\"font-size:x-small\">AGEL<\/span> input file. The file only contains a number of keywords, given in table <a href=\"#tab:bagel_temp\">6.27<\/a>. The actual input for B<span style=\"font-size:x-small\">AGEL<\/span> will be generated automatically through the interface.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A fully commented template file-with all possible options, a comprehensive descriptions, and some practical hints-is located at <b><tt>$SHARC\/..\/examples\/SHARC_BAGEL\/BAGEL.template<\/tt><\/b>.<br \/>\nWe recommend that users start from this template file and modify it appropriately for their calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.27\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.27: Keywords for the <b><tt>BAGEL.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:bagel_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis <\/td>\n<td align=\"left\">Gives the basis set for all atoms (default svp). It is advisable to always specify a basis set file with absolute path.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">df_basis <\/td>\n<td align=\"left\">Gives the auxiliary basis set (default: svp-jkfit). It is advisable to always specify a DF basis set file with absolute path.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dkh <\/td>\n<td align=\"left\">Activates the (scalar-relativistic) Douglas-Kroll-Hess Hamiltonian.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nact <\/td>\n<td align=\"left\">Number of active orbitals.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nclosed <\/td>\n<td align=\"left\">Number of closed-shell orbitals.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nstate <\/td>\n<td align=\"left\">Number of state-averaging states per multiplicity.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">method <\/td>\n<td align=\"left\">Can be <b><tt>casscf<\/tt><\/b>, <b><tt>caspt2<\/tt><\/b>, <b><tt>ms-caspt2<\/tt><\/b>, or <b><tt>xms-caspt2<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">shift <\/td>\n<td align=\"left\">Level shift for CASPT2 (default: 0.0, give float in Hartree).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">shift_imag <\/td>\n<td align=\"left\">Switches from real to imaginary level shift (use <b><tt>shift<\/tt><\/b> to specify the magnitude).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">orthogonal_basis <\/td>\n<td align=\"left\">Switches on the <b><tt>orthogonal_basis<\/tt><\/b> option of B<span style=\"font-size:x-small\">AGEL<\/span>. Is activated automatically for imaginary level shifts.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">msmr <\/td>\n<td align=\"left\">Switches on multi-state-multi-reference treatment in CASPT2. Default is single-state-single-reference (SS-SR).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">maxiter <\/td>\n<td align=\"left\">Iteration limit for energy calculations (SCF, PT2). Default 500. A too high value can slow down the calculation unnecessarily.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">maxziter <\/td>\n<td align=\"left\">Iteration limit for Z-vector calculations (gradients, NACME). Default 100. A too high value can slow down the calculation unnecessarily.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">charge <\/td>\n<td align=\"left\">Sets the total charge of the system. Can be either followed by a single integer (then the interface will automatically assign the charges to the multiplicities) or by one charge per multiplicity.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">frozen <\/td>\n<td align=\"left\">Number of frozen core orbitals for CASPT2 steps. Default is -1, which lets B<span style=\"font-size:x-small\">AGEL<\/span> automatically decide.\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.18.2\"><\/a><\/p>\n<h3>\n6.18.2  Resource file: <b><tt>BAGEL.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>BAGEL.resources<\/tt><\/b> contains mainly paths (to the B<span style=\"font-size:x-small\">AGEL<\/span> executables, to the scratch directory, etc.) and other resources, plus settings relevant for <b><tt>wfoverlap.x<\/tt><\/b>. This file must reside in the same directory where the interface is started. It uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The B<span style=\"font-size:x-small\">AGEL<\/span> interface employs essentially all keywords from Tables <a href=\"#tab:resources\">6.3<\/a> (except: ngpu), as well as WF<span style=\"font-size:x-small\">OVERLAP<\/span> keywords from Table <a href=\"#tab:resources_aux\">6.4<\/a>.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:bagel_sh2\">6.28<\/a>.<br \/>\nA fully commented resource file with all possible options and comprehensive descriptions is located in <b><tt>$SHARC\/..\/examples\/SHARC_BAGEL\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.28\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.28: Keywords for the <b><tt>BAGEL.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:bagel_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">bagel <\/td>\n<td align=\"left\">Is the path to the B<span style=\"font-size:x-small\">AGEL<\/span> installation directory. This directory should contain subdirectories <b><tt>bin\/<\/tt><\/b> and <b><tt>lib\/<\/tt><\/b>. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. The interface will automatically update the <b><tt>$LD_LIBRARY_PATH<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">mpi_parallel <\/td>\n<td align=\"left\">If given, the interface will call B<span style=\"font-size:x-small\">AGEL<\/span> with <b><tt>mpirun -n NCPU<\/tt><\/b>, otherwise it will use OpenMP.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dipolelevel <\/td>\n<td align=\"left\">Followed by an integer which is either 0, 1, or 2. Controls which dipole moment calculations are skipped by the interface.\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Note that the <b><tt>dipolelevel<\/tt><\/b> keyword can have significant impact on the calculation time.<br \/>\nGenerally, in CASPT2 calculations, extra computational effort is required for the calculation of state and transition dipole moments.<br \/>\nHowever, dipole moments have only influence in the dynamics simulations if a laser field is present.<br \/>\nUsing the <b><tt>dipolelevel<\/tt><\/b> keyword, it is possible to deactivate dipole moment calculations if they are not required.<br \/>\nThere are three different settings for <b><tt>dipolelevel<\/tt><\/b>: <\/p>\n<ul>\n<li> <b><tt>dipolelevel<\/tt><\/b>=0: The interface will return only dipole moments which can be calculated at no cost (state dipole moments of states where a gradient is calculated; transition dipole moments if nonadiabatic couplings are calculated)\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>dipolelevel<\/tt><\/b>=1: In addition, the interface will calculate transition dipole moments between S<sub>0<\/sub> and excited singlet states. Use at least this level for the initial condition setup (<b><tt>setup_init.py<\/tt><\/b> takes care of this).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>dipolelevel<\/tt><\/b>=2: The interface will calculate all state and transition dipole moments\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<p>If only energies and dipole moments are calculated, <b><tt>dipolelevel<\/tt><\/b>=1 is only slightly more expensive than <b><tt>dipolelevel<\/tt><\/b>=0, while <b><tt>dipolelevel<\/tt><\/b>=2 increases computation time more strongly.<br \/>\nHowever, the computation time also depends on whether or not nonadiabatic couplings and gradients are calculated. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Parallelization  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The parallel scaling behavior of B<span style=\"font-size:x-small\">AGEL<\/span> heavily depends on the system (number of atoms, active space, frozen core, …) and on the parallelization mode (MPI or OpenMP).<br \/>\nHence, it is advisable that the optimal settings (number of cores, parallelization mode) are tested before starting dynamics projects.<br \/>\nNote that the interface can only trivially parallelize B<span style=\"font-size:x-small\">AGEL<\/span> calculations across several independent multiplicities, but not across multiple gradient or nonadiabatic coupling calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.18.3\"><\/a><\/p>\n<h3>\n6.18.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>If you want to set up trajectories for <b><tt>SHARC_BAGEL.py<\/tt><\/b>, you have to select in the respective setup script the <b><tt>SHARC_LEGACY.py<\/tt><\/b> legacy frontend interface.<br \/>\nThis is because <b><tt>SHARC_BAGEL.py<\/tt><\/b> is not yet converted to the S<span style=\"font-size:x-small\">HARC<\/span>4 format and does not have its own setup routines.<br \/>\nThe setup routines are instead in <b><tt>SHARC_LEGACY.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After selecting <b><tt>SHARC_LEGACY.py<\/tt><\/b>, you will directly be prompted for which of the five legacy interfaces you want to use.<br \/>\nSelect <b><tt>SHARC_BAGEL.py<\/tt><\/b>.<br \/>\nLater during setup, the setup dialogue for <b><tt>SHARC_BAGEL.py<\/tt><\/b> will be carried out.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During the setup dialogue, you are first queried for the path to the BAGEL installation.<br \/>\nThen you are asked for the scratch directory, where BAGEL will store temporary files.<br \/>\nThis directory will be deleted after the calculation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the setup prompts for the path to the BAGEL template.<br \/>\nThe file is checked for completeness.<br \/>\nIt must contain at least the basis set, the density fitting basis, and the number of active and inactive orbitals.<br \/>\nThe file also has to contain information about the number of states for state-averaging.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the setup dialogue asks for the dipole level (see above).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Then, the user is asked to set up the initial orbitals.<br \/>\nWhile optional, it is strongly recommended to provide one, as CASSCF calculations can otherwise become unstable or very slow.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>You are then asked for the number of CPU cores and whether to use MPI parallelization.<br \/>\nIt is not possible to control the memory used by BAGEL.<br \/>\nIn BAGEL, MPI parallelization is more efficient than OpenMP.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If wave function overlaps are needed, the script asks for the path to the overlap executable and the memory for the overlap code.<br \/>\nThere is no wave function truncation threshold, because CASSCF wave functions are very efficiently computed with <b><tt>wfoverlap.x<\/tt><\/b>.<br \/>\nIf Dyson orbital analysis is also selected, the number of doubly occupied orbitals must be provided.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.19\"><\/a><\/p>\n<h2>\n6.19  MOLPRO Interface<\/h2>\n<p><a id=\"sec:int:molpro\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Legacy ab initio interface for CASSCF in the M<span style=\"font-size:x-small\">OLPRO<\/span> package.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– M<span style=\"font-size:x-small\">OLPRO<\/span> interface allows to run S<span style=\"font-size:x-small\">HARC<\/span> dynamics with M<span style=\"font-size:x-small\">OLPRO<\/span>‘s CASSCF wave functions.<br \/>\nRASSCF is not supported, since on RASSCF level state-averaging over different multiplicities is not possible.<br \/>\nThe interface uses M<span style=\"font-size:x-small\">OLPRO<\/span>‘s CI program in order to calculate transition dipole moments and spin-orbit couplings.<br \/>\nGradients and nonadiabatic coupling vectors are calculated using M<span style=\"font-size:x-small\">OLPRO<\/span>‘s ALASKA code.<br \/>\nIn the new version of the interface, overlaps are calculated using the WF<span style=\"font-size:x-small\">OVERLAP<\/span> code.<br \/>\nWavefunction phases between the CASSCF and MRCI wave functions are automatically adjusted.<br \/>\nThe interface can trivially parallelize the computation of gradients and coupling vectors over several processors.<br \/>\nExecution of parallel M<span style=\"font-size:x-small\">OLPRO<\/span> binaries is currently not supported.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Important note:<\/b> It appears that in some cases the sign of the nonadiabatic coupling vectors randomly changes along a trajectory ran with M<span style=\"font-size:x-small\">OLPRO<\/span>, and that it is not possible to identify this sign change from the MO and CI coefficients.<br \/>\nHence, propagation with <b><tt>coupling nacdr<\/tt><\/b> is currently discouraged for the S<span style=\"font-size:x-small\">HARC<\/span>– M<span style=\"font-size:x-small\">OLPRO<\/span> interface.<br \/>\nAlternative possibilities to run S<span style=\"font-size:x-small\">HARC<\/span>-CASSCF dynamics with nonadiabatic coupling vectors are given by the M<span style=\"font-size:x-small\">OLCAS<\/span> (section <a href=\"#sec:int:molcas\">6.12<\/a>) and B<span style=\"font-size:x-small\">AGEL<\/span> (section <a href=\"#sec:int:bagel\">6.18<\/a>) interfaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– M<span style=\"font-size:x-small\">OLPRO<\/span> interface needs two additional input files, which should be present in <b><tt>QM\/<\/tt><\/b>. Those input files are <b><tt>MOLPRO.resources<\/tt><\/b>, which contains, e.g., the paths to M<span style=\"font-size:x-small\">OLPRO<\/span> and the scratch directory, and <b><tt>MOLPRO.template<\/tt><\/b>, which is a keyword-argument input file specifying the CASSCF level of theory.<br \/>\nIf <b><tt>QM\/wf.init<\/tt><\/b> is present, it will be used as a M<span style=\"font-size:x-small\">OLPRO<\/span> wave function file containing the initial MOs.<br \/>\nFor calculations with several “jobs” (see below), initial orbitals can also given as <b><tt>QM\/wf.<job>.init<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Note that as a legacy interface, SHARC or parent interfaces cannot control the molecular charge per multiplicity directly, so you need to prepare all M<span style=\"font-size:x-small\">OLPRO<\/span> input with the correct charges in mind.<\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.19.1\"><\/a><\/p>\n<h3>\n6.19.1  Template file: <b><tt>MOLPRO.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The template file is a keyword-argument list file, similar to the template files of most other interfaces.<br \/>\nA fully commented template file with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_MOLPRO\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For simple cases, an example for the template file looks like this:<\/p>\n<pre>\nbasis def2-svp\ndkho 2                  # Douglas-Kroll second order\nocc 14\nclosed 10\nnelec           24\nroots           4 0 3\nrootpad         1 0 1\n<\/pre>\n<p>This specifies a SA(4S+3T)-CASSCF(4,4)\/def2-SVP calculation for 24 electrons.<br \/>\nNote the <b><tt>rootpad<\/tt><\/b> keyword, which adds one singlet and one triplet with zero weight to the state-averaging (so technically this is a SA(5S+4T) calculation, but the results are the same as SA(4S+3T)).<br \/>\nThese zero-weight states are sometimes useful to improve convergence of CASSCF.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface can also be used to perform several independent CASSCF calculations for different multiplicities (e.g., one CASSCF for the neutral states and another one for the ionic states).<br \/>\nIn this case, each independent CASSCF calculation is called a “job”.<br \/>\nIn the template, most settings can be modified independently for each job.<br \/>\nAn example is given here:<\/p>\n<pre>\n# In this way, users can employ custom basis sets\nbasis_external \/path\/to\/basisset        # no spaces in path allowed\ndkho 2\n# job 1 for singlet+triplet; job 2 for doublets\njobs 1 2 1\nocc 14 13       # for job 1 and 2\nclosed 11 10    # for job 1 and 2\nnelec           24 23 24   # for job 1\nnelec           24 23 24   # for job 2\nroots           4 0 3   # for job 1\nroots           0 2 0   # for job 2\nrootpad         1 0 1   # for job 1\nrootpad         0 2 0   # for job 2\n<\/pre>\n<p>This template specifies two jobs, where job 1 should be used to compute singlet and triplet states, and job 2 used for doublet states.<br \/>\nJob 1 is a SA(4S+3T)-CASSCF(2,3) computation, with singlets and triplets each having 24 electrons.<br \/>\nJob 2 is a SA(2D)-CASSCF(3,3) computation, with 23 electrons.<br \/>\nNote how for different jobs it is possible to have different active spaces and state-averaging schemes.<br \/>\nHowever, keep in mind that all states of a given multiplicity are always calculated in the same job (e.g., it is not possible to have one job for S<sub>0<\/sub> and another job for S<sub>1<\/sub> and S<sub>2<\/sub>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>It is also possible to do a mixed input, for example having two jobs, but only giving one number after <b><tt>occ<\/tt><\/b> or <b><tt>closed<\/tt><\/b>.<br \/>\nThe interface provides comprehensive error messages during the template check.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Also note the <b><tt>basis_external<\/tt><\/b> keyword. It provides a file, whose content is used in the basis set definition (it is inserted verbatim into <b><tt>basis={...}<\/tt><\/b> in the M<span style=\"font-size:x-small\">OLPRO<\/span> input).<br \/>\nIt is possible to use the generated input from the <a href=\"https:\/\/bse.pnl.gov\/bse\/portal\">Basis Set Exchange Library<\/a>, but the <b><tt>basis={<\/tt><\/b> and <b><tt>}<\/tt><\/b> need to be deleted from the file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Remember that <b><tt>molpro_input.py<\/tt><\/b> cannot create multi-job templates or templates with the <b><tt>basis_external<\/tt><\/b> keyword.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.19.2\"><\/a><\/p>\n<h3>\n6.19.2  Resource file: <b><tt>MOLPRO.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interface requires some additional information beyond the content of <b><tt>QM.in<\/tt><\/b>. This information is given in the file <b><tt>MOLPRO.resources<\/tt><\/b>, which must reside in the directory where the interface is started. This file uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The M<span style=\"font-size:x-small\">OLPRO<\/span> interface employs essentially all keywords from Tables <a href=\"#tab:resources\">6.3<\/a> (except: ngpu), as well as WF<span style=\"font-size:x-small\">OVERLAP<\/span> keywords from Table <a href=\"#tab:resources_aux\">6.4<\/a>.<br \/>\nInterface-specific keywords are given in Table <a href=\"#tab:molpro_sh2\">6.29<\/a>.<br \/>\nA fully commented resource file for this interface with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_MOLPRO<\/tt><\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Mandatory keywords are the paths to M<span style=\"font-size:x-small\">OLPRO<\/span>, the scratch directory, and to the WF<span style=\"font-size:x-small\">OVERLAP<\/span> executable (the latter for overlap, Dyson, or NACDR calculations).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.29\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.29: Keywords for the <b><tt>MOLPRO.resources<\/tt><\/b> input file.<\/div>\n<p> <a id=\"tab:molpro_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">molpro <\/td>\n<td align=\"left\">Is followed by a string giving the path to the M<span style=\"font-size:x-small\">OLPRO<\/span> directory. This directory should contain the executable <b><tt>molpro.exe<\/tt><\/b>. Relative and absolute paths, environment variables and <b><tt> <\/tt><\/b> can be used. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">molpro_arguments <\/td>\n<td align=\"left\">Put all command line options for M<span style=\"font-size:x-small\">OLPRO<\/span> that you want to use, except <b><tt>-W -I -d<\/tt><\/b>, because those are set by the interface. In this way, you can run M<span style=\"font-size:x-small\">OLPRO<\/span> in parallel (on top of running independent jobs in parallel), but note that the <b><tt>ncpu<\/tt><\/b> keyword does not take this into account.\n<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p><b>Parallel execution of MOLPRO  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the new version of the S<span style=\"font-size:x-small\">HARC<\/span>– M<span style=\"font-size:x-small\">OLPRO<\/span> interface, calculations of multiple independent active spaces (“jobs”), of several gradients, and of several nonadiabatic coupling vectors are automatically parallelized over the given number of CPU cores.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that M<span style=\"font-size:x-small\">OLPRO<\/span> calls can also be parallelized via the <b><tt>molpro_arguments<\/tt><\/b> key in the resource file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.19.3\"><\/a><\/p>\n<h3>\n6.19.3  Error checking<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interface is written such that the output of M<span style=\"font-size:x-small\">OLPRO<\/span> is checked for commonly occuring errors, mostly bad convergence in the MCSCF or CP-MCSCF parts. In these cases, the input is adjusted and M<span style=\"font-size:x-small\">OLPRO<\/span> restarted. This will be done until all calculations are finished or an unrecoverable error is detected.<br \/>\nThe interface will try to solve the following error messages:<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>EXCESSIVE GRADIENT IN CI  <\/b> This error message can occur in the MCSCF part. The calculation is restarted with a P-space threshold (see M<span style=\"font-size:x-small\">OLPRO<\/span> manual) of 1. If the error remains, the threshold is quadrupled until the calculation converges or the threshold is above 100.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>NO CONVERGENCE IN REFERENCE CI  <\/b> The error occurs in the CI part. The calculation is restarted with a P-space threshold (see M<span style=\"font-size:x-small\">OLPRO<\/span> manual) of 1. If the error remains, the threshold is quadrupled until the calculation converges or the threshold is above 100.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>NO CONVERGENCE OF CP-MCSCF  <\/b> This error occurs when solving the linear equations needed for the calculation of MCSCF gradients or nonadiabatic coupling vectors. In this case, the interface finds in the output the value of closest convergence and restarts the calculation with the value found as the new convergence criterion. This ensures that the CP-MCSCF calculation converges, albeit with lower accuracy for this gradient for this time step.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>This error check is controlled by two keywords in the <b><tt>MOLPRO.resources<\/tt><\/b> file. The interface first tries to converge the CP-MCSCF calculation to <b><tt>gradaccudefault<\/tt><\/b>. If this fails, it tries to converge to the best value possible within 900 iterations. <b><tt>gradaccumax<\/tt><\/b> defines the worst accuracy accepted by the interface. If a CP-MCSCF calculation cannot be converged below <b><tt>gradaccumax<\/tt><\/b> then the interface exits with an error, leading to the abortion of the trajectory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.19.4\"><\/a><\/p>\n<h3>\n6.19.4  Things to keep in mind<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>Initial orbital guess  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For CASSCF calculations it is always a good idea to start from converged MOs from a nearby geometry. For the first time step, if a file <b><tt>QM\/wf.init<\/tt><\/b> is present, the S<span style=\"font-size:x-small\">HARC<\/span>– M<span style=\"font-size:x-small\">OLPRO<\/span> interface will take this file for the starting orbitals. In case of multi-job calculations, separate initial orbitals can be provided with files called <b><tt>QM\/wf.<job>.init<\/tt><\/b>, where <b><tt><job><\/tt><\/b> is an integer.<br \/>\nIn subsequent calculations, the MOs from the previous step will be used (unless the <b><tt>always_orb_init<\/tt><\/b> keyword is used).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Basis sets  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to employ user-defined basis sets, in the template the keyword <b><tt>basis_external<\/tt><\/b>, followed by a filename, can be used.<br \/>\nThe interface will then take the content of this file and insert it as basis set definition in the M<span style=\"font-size:x-small\">OLPRO<\/span> input files (i.e., it will add in the input <b><tt>basis={ <content of the file> }<\/tt><\/b>.<br \/>\nNote that the filename must not contain spaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.19.5\"><\/a><\/p>\n<h3>\n6.19.5  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>If you want to set up trajectories for <b><tt>SHARC_MOLPRO.py<\/tt><\/b>, you have to select in the respective setup script the <b><tt>SHARC_LEGACY.py<\/tt><\/b> legacy frontend interface.<br \/>\nAfter selecting <b><tt>SHARC_LEGACY.py<\/tt><\/b>, choose <b><tt>SHARC_MOLPRO.py<\/tt><\/b>.<br \/>\nLater during setup, the setup dialogue for <b><tt>SHARC_MOLPRO.py<\/tt><\/b> will be carried out.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During the setup dialogue, you are first queried for the path to the MOLPRO executable.<br \/>\nShell variables and <b><tt> <\/tt><\/b> can be used and will be expanded when the interface is started.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, you are asked for the scratch directory, where MOLPRO will store temporary files.<br \/>\nThis directory will be deleted after the calculation, and its validity cannot be checked by the script since you may run the calculations on a different machine.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Then the setup prompts for the path to the <b><tt>MOLPRO.template<\/tt><\/b> file.<br \/>\nThis file is checked for the following keywords: <b><tt>basis<\/tt><\/b>, <b><tt>closed<\/tt><\/b>, <b><tt>occ<\/tt><\/b>, <b><tt>nelec<\/tt><\/b>, and <b><tt>roots<\/tt><\/b>.<br \/>\nIf a file named <b><tt>MOLPRO.template<\/tt><\/b> exists in the working directory and passes this check, you may choose to use it; otherwise, you will be prompted to provide a valid template filename.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the setup dialogue asks for an initial wavefunction guess.<br \/>\nYou will be asked whether you have a MOLPRO wavefunction file (e.g. <b><tt>wf.init<\/tt><\/b>); if so, you must supply its path.<br \/>\nIf not, a warning is issued reminding you that CASSCF calculations may run very long or yield incorrect results without proper starting MOs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>You are then asked to specify the amount of memory available to MOLPRO (in MB) and the number of CPUs to be used by each trajectory.<br \/>\nIf wave function overlaps are needed, you will also be prompted for the path to the <b><tt>wfoverlap.x<\/tt><\/b> executable.<br \/>\nNote that the MOLPRO interface computes wave function overlaps not only when they are explicitly requested, but also when nonadiabatic coupling vectors are requested, in order to match the wave function phases of the CASSCF wave function (from which the nonadiabatic couplings are computed) and the wave function in the MRCI module (which computes spin-orbit couplings and dipole moments).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, default values for gradient accuracy thresholds (<b><tt>molpro.gradaccudefault<\/tt><\/b>, <b><tt>molpro.gradaccumax<\/tt><\/b>), number of core orbitals (<b><tt>molpro.ncore<\/tt><\/b>), and number of doubly occupied orbitals (<b><tt>molpro.ndocc<\/tt><\/b>) are set automatically.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During job preparation, the setup routines write a <b><tt>MOLPRO.resources<\/tt><\/b> file into the job directory, containing: the <b><tt>molpro<\/tt><\/b> executable path, the <b><tt>scratchdir<\/tt><\/b> and <b><tt>savedir<\/tt><\/b> locations, gradient accuracy defaults (<b><tt>gradaccudefault<\/tt><\/b>, <b><tt>gradaccumax<\/tt><\/b>), <b><tt>memory<\/tt><\/b> and <b><tt>ncpu<\/tt><\/b> settings, and optionally the <b><tt>wfoverlap<\/tt><\/b> executable path.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.19.6\"><\/a><\/p>\n<h3>\n6.19.6  Molpro input generator: <b><tt>molpro_input.py<\/tt><\/b><\/h3>\n<p><a id=\"sec:molpro_input.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to quickly setup simple inputs for M<span style=\"font-size:x-small\">OLPRO<\/span>, the S<span style=\"font-size:x-small\">HARC<\/span> suite contains a small script called <b><tt>molpro_input.py<\/tt><\/b>. It can be used to setup single point calculations, optimizations and frequency calculations on the HF, DFT, MP2 and CASSCF level of theory. Of course, M<span style=\"font-size:x-small\">OLPRO<\/span> has far more capabilities, but these are not covered by <b><tt>molpro_input.py<\/tt><\/b>. However, <b><tt>molpro_input.py<\/tt><\/b> can also prepare template files which are compatible with the S<span style=\"font-size:x-small\">HARC<\/span>– M<span style=\"font-size:x-small\">OLPRO<\/span> interface (<b><tt>MOLPRO.template<\/tt><\/b> file).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script interactively asks the user to specify the calculation and afterwards writes an input file and optionally a run script.<\/p>\n<div class=\"p\"><!----><\/div>\n<h4>Input<\/h4>\n<div class=\"p\"><!----><\/div>\n<p><b>Type of calculation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Choose to either perform a single-point calculation or a minimum optimization (including optionally frequency calculation), to generate a template file, or an optimization of a state crossing. For the template generation, no geometry file is needed, but the script looks for a <b><tt>MOLPRO.input<\/tt><\/b> in the same directory and allows to copy the settings. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>For single-point calculations, optimizations and frequency calculations, files in M<span style=\"font-size:x-small\">OLDEN<\/span> format called <b><tt>geom.molden<\/tt><\/b>, <b><tt>opt.molden<\/tt><\/b> or <b><tt>freq.molden<\/tt><\/b>, respectively, are created (containing the orbitals, optimization steps and normal modes, respectively). The file <b><tt>freq.molden<\/tt><\/b> can be used to generate initial conditions with <b><tt>wigner.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Geometry  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Specify the geometry file in xyz format. Number of atoms and total nuclear charge is detected automatically. After the user inputs the total charge, the number of electrons is calculated automatically.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the case of the generation of a template file, instead only the number of electrons is required.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Non-default atomic masses  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If a frequency calculation is requested, the user may modify the mass of specific atoms (e.g. to investigate isotopic effects). In the following menu, the user can add or remove atoms with their mass to a list containing all atoms with non-default masses. Each atom is referred to by its number as in the geometry file. Using the command <b><tt>show<\/tt><\/b> the user can display the list of atoms with non-default masses. Typing <b><tt>end<\/tt><\/b> confirms the list.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that when using the produced M<span style=\"font-size:x-small\">OLDEN<\/span> file later with <b><tt>wigner.py<\/tt><\/b>, the user has to enter the same non-default masses again, since the M<span style=\"font-size:x-small\">OLDEN<\/span> file does not contain the masses and <b><tt>wigner.py<\/tt><\/b> has no way to retrieve these numbers.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Level of theory  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Supported are Hartree-Fock (HF), density functional theory (DFT), Møller-Plesset perturbation theory (MP2), equation-of-motion coupled-cluster with singles and doubles (EOM-CCSD) and CASSCF (either single-state or state-averaged). All methods (except EOM-CCSD) are compatible with odd-electron wave functions (<b><tt>molpro_input.py<\/tt><\/b> will use the corresponding UHF, UMP2 and UKS keywords in the input file, if necessary).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For template generation, state-average CASSCF is automatically chosen. All methods (except EOM-CCSD) can be combined with optimizations and frequency calculations, however, the frequency calculation is much more efficient with HF or SS-CASSCF. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>DFT functional  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For DFT calculations, enter a functional and choose whether dispersion correction should be applied. Note that the functional is just a string which is not checked by <b><tt>molpro_input.py<\/tt><\/b>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Basis set  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The basis set is just a string which is not checked by <b><tt>molpro_input.py<\/tt><\/b>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>CASSCF settings  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For CASSCF calculations, enter the number of active electrons and orbitals. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>For SS-CASSCF, only the multiplicity needs to be specified. For SA-CASSCF, specify the number of states per multiplicity to be included. Note that M<span style=\"font-size:x-small\">OLPRO<\/span> allows to average over states with different numbers of electrons. This feature is not supported in <b><tt>molpro_input.py<\/tt><\/b>. However, the user can generate a closely-matching input and simply add the missing states to the CASSCF block manually. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>For optimizations at SA-CASSCF level, the state to be optimized has to be given. For crossing point optimizations, two states need to be entered. The script automatically detects whether a conical intersection or a crossing between states of different multiplicity is requested and sets up the input accordingly.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>EOM-CCSD settings  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>EOM-CCSD calculations allow to calculate relatively accurate excited-state energies and oscillator strengths from a Hartree-Fock reference, but only for singlet excited states.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The user has to specify the number of states to be calculated. If only one state is requested, the script will setup a regular ground state CCSD calculation, while for more than one states, an EOM-CCSD calculation is setup.<br \/>\nNote that the calculation of transition properties takes twice as long as the energy calculation itself.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Memory  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Enter the amount of memory for M<span style=\"font-size:x-small\">OLPRO<\/span>. Note that values smaller than 50 MB are ignored, and 50 MB are used in this case.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Run script  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If requested, the script also generates a simple Bash script (<b><tt>run_molpro.sh<\/tt><\/b>) to directly execute M<span style=\"font-size:x-small\">OLPRO<\/span>. The user has to enter the path to M<span style=\"font-size:x-small\">OLPRO<\/span> and the path to a suitable (fast) scratch directory. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the scratch directory will be deleted after the calculation, only the wave function file <b><tt>wf<\/tt><\/b> will be copied back to the main directory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.20\"><\/a><\/p>\n<h2>\n6.20  PySCF Interface<\/h2>\n<p><a id=\"sec:int:pyscf\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Legacy ab initio interface for running CASSCF and PFDT calculations with P<span style=\"font-size:x-small\">Y<\/span>SCF.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– P<span style=\"font-size:x-small\">Y<\/span>SCF interface allows to run S<span style=\"font-size:x-small\">HARC<\/span> dynamics with an implementation of state-averaged CASSCF and PDFT in P<span style=\"font-size:x-small\">Y<\/span>SCF.<br \/>\nThe interface can compute energies, dipole moment matrices, gradients, and nonadiabatic coupling vectors.<br \/>\nSpin-orbit couplings, wave function overlaps, or other advanced features are not available.<br \/>\nThe interface can only compute singlet states currently.<br \/>\nThe interface supports some parallelism, as provided by P<span style=\"font-size:x-small\">Y<\/span>SCF’s OpenMP capabilities, but note that the number of used cores cannot be strictly controlled (some parts of the calculation will use all available cores).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The PDFT implementation requires the installation of <a href=\"https:\/\/github.com\/pyscf\/pyscf-forge\">PySCF Forge<\/a>.<br \/>\nWith this implementation, the variants MC-PDFT (multi-configurational pair DFT), CMS-PDFT (compressed state multistate PDFT), and L-PDFT (linearized PDFT) are available.<br \/>\nSee the <a href=\"https:\/\/github.com\/pyscf\/pyscf-forge\/tree\/master\/doc\/mcpdft\">Documentation<\/a> for details and references.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– P<span style=\"font-size:x-small\">Y<\/span>SCF interface needs two additional input files, which should be present in <b><tt>QM\/<\/tt><\/b>. Those input files are <b><tt>PYSCF.resources<\/tt><\/b>, which contains, e.g., the paths to P<span style=\"font-size:x-small\">Y<\/span>SCF and the scratch directory, and <b><tt>PYSCF.template<\/tt><\/b>, which is a keyword-argument input file specifying the level of theory.<br \/>\nIf <b><tt>QM\/pyscf.init.chk<\/tt><\/b> is present, it will be used for the initial MOs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Note that as a legacy interface, SHARC or parent interfaces cannot control the molecular charge per multiplicity directly, so you need to prepare all P<span style=\"font-size:x-small\">Y<\/span>SCF input with the correct charges in mind.<\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.20.1\"><\/a><\/p>\n<h3>\n6.20.1  Template file: <b><tt>PYSCF.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file contains the specifications for the quantum chemistry calculation. Note that this is not a valid B<span style=\"font-size:x-small\">AGEL<\/span> input file. The file only contains a number of keywords, given in table <a href=\"#tab:pyscf_temp\">6.30<\/a>. The actual input for B<span style=\"font-size:x-small\">AGEL<\/span> will be generated automatically through the interface.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A fully commented template file-with all possible options, a comprehensive descriptions, and some practical hints-is located at <b><tt>$SHARC\/..\/examples\/SHARC_PYSCF\/PYSCF.template<\/tt><\/b>.<br \/>\nWe recommend that users start from this template file and modify it appropriately for their calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.30\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.30: Keywords for the <b><tt>PYSCF.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:pyscf_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">basis <\/td>\n<td align=\"left\">(string) Any string that P<span style=\"font-size:x-small\">Y<\/span>SCF recognizes as a basis set. This keyword is mandatory, not giving it results in an error.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">method <\/td>\n<td align=\"left\">(string) Any one of “casscf”, “l-pdft”, “mc-pdft”, or “cms-pdft”. Default is CASSCF.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">pdft-functional <\/td>\n<td align=\"left\">(string) Any one of “tpbe” or “ftpbe”. Default is T-PBE.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ncas <\/td>\n<td align=\"left\">(int) Number of active orbitals. This keyword is mandatory, not giving it results in an error.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">nelecas <\/td>\n<td align=\"left\">(int) Numer of active electrons. This keyword is mandatory, not giving it results in an error.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">roots <\/td>\n<td align=\"left\">(int) Number of states for state-averaging. This keyword is mandatory, not giving it results in an error.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">charge <\/td>\n<td align=\"left\">(int) Total molecular charge. Default is zero. From the charge and <b><tt>nelecas<\/tt><\/b>, the number of inactive electrons is determined (this must be even). <b>Note that for a legacy interface, SHARC or parent interfaces cannot control the molecular charge per multiplicity directly, so the charge must be given in the template.<\/b>\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">grids-level <\/td>\n<td align=\"left\">(int) A number specifying the DFT quadrature, between 2 and 6. Default is 4.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">conv-tol <\/td>\n<td align=\"left\">(float) Convergence criterion for CASSCF solver. Default 1e-7.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">conv-tol-grad <\/td>\n<td align=\"left\">(float) Convergence criterion for CASSCF solver. Default 1e-4.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">max-stepsize <\/td>\n<td align=\"left\">(float) Step size for CASSCF solver. Default 0.02.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">max-cycle-macro <\/td>\n<td align=\"left\">(int) Maximum number of macro cycles. Default 50.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">max-cycle-micro <\/td>\n<td align=\"left\">(int) Maximum number of micro cycles. Default 4.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ah-level-shift <\/td>\n<td align=\"left\">(float) Setting for the AH solver of P<span style=\"font-size:x-small\">Y<\/span>SCF. Default 1e-8.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ah-conv-tol <\/td>\n<td align=\"left\">(float) Setting for the AH solver of P<span style=\"font-size:x-small\">Y<\/span>SCF. Default 1e-12.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ah-max-cycle <\/td>\n<td align=\"left\">(int) Setting for the AH solver of P<span style=\"font-size:x-small\">Y<\/span>SCF. Default 30.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ah-lindep <\/td>\n<td align=\"left\">(float) Setting for the AH solver of P<span style=\"font-size:x-small\">Y<\/span>SCF. Default 1e-14.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ah-start-tol <\/td>\n<td align=\"left\">(float) Setting for the AH solver of P<span style=\"font-size:x-small\">Y<\/span>SCF. Default 2.5.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ah-start-cycle <\/td>\n<td align=\"left\">(int) Setting for the AH solver of P<span style=\"font-size:x-small\">Y<\/span>SCF. Default 3.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">fix-spin-shift <\/td>\n<td align=\"left\">(float) Necessary shift when using the P<span style=\"font-size:x-small\">Y<\/span>SCF-internal CASSCF solver. Default 0.2. Not used if <b><tt>pyscf-forge<\/tt><\/b> is installed.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">grad-max-cycle <\/td>\n<td align=\"left\">(int) Maximum number of cycles in the coupled-perturbed equations needed for gradients. Default 50.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">verbose <\/td>\n<td align=\"left\">(int) Print level of the P<span style=\"font-size:x-small\">Y<\/span>SCF output. Default is 3, which gives only sparse output of results. Use 4-6 to obtain more output. The output file <b><tt>PySCF_<job>.log<\/tt><\/b> will be located in the directory where the interface runs (this might be located in the scratch directory assigned to <b><tt>SHARC_LEGACY.py<\/tt><\/b>).\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.20.2\"><\/a><\/p>\n<h3>\n6.20.2  Resource file: <b><tt>PYSCF.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>PYSCF.resources<\/tt><\/b> contains mainly paths (to the P<span style=\"font-size:x-small\">Y<\/span>SCF executables, to the scratch directory, etc.) and other resources, plus settings relevant for <b><tt>wfoverlap.x<\/tt><\/b>. This file must reside in the same directory where the interface is started. It uses a simple “<b><tt>keyword argument<\/tt><\/b>” syntax. Comments using # and blank lines are possible, the order of keywords is arbitrary. Lines with unknown keywords are ignored, since the interface just searches the file for certain keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The P<span style=\"font-size:x-small\">Y<\/span>SCF interface employs keywords from Tables <a href=\"#tab:resources\">6.3<\/a> (<b><tt>scratchdir<\/tt><\/b>, <b><tt>savedir<\/tt><\/b>, <b><tt>memory<\/tt><\/b>, <b><tt>ncpu<\/tt><\/b>, <b><tt>always_guess<\/tt><\/b>, <b><tt>always_orb_init<\/tt><\/b>).<br \/>\nThere are no other interface-specific keywords.<br \/>\nA fully commented resource file with all possible options and comprehensive descriptions is located in <b><tt>$SHARC\/..\/examples\/SHARC_PYSCF\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.20.3\"><\/a><\/p>\n<h3>\n6.20.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>If you want to set up trajectories for <b><tt>SHARC_PYSCF.py<\/tt><\/b>, you have to select in the respective setup script the <b><tt>SHARC_LEGACY.py<\/tt><\/b> legacy frontend interface.<br \/>\nAfter selecting <b><tt>SHARC_LEGACY.py<\/tt><\/b>, immediately choose <b><tt>SHARC_PYSCF.py<\/tt><\/b>.<br \/>\nThe setup dialogue for <b><tt>SHARC_PYSCF.py<\/tt><\/b> will then be carried out later during the setup script.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During the setup dialogue, you are first prompted for the scratch directory.<br \/>\nThis directory will be used to store the PySCF temporary files and will be deleted after the calculation.<br \/>\nSince you may run the calculation on a different machine, the script cannot verify whether the path is valid, nor will it expand shell variables or <b><tt> <\/tt><\/b> during setup (these will be expanded during interface run time).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, you are asked for the path to the <b><tt>PYSCF.template<\/tt><\/b> file.<br \/>\nIf a file named <b><tt>PYSCF.template<\/tt><\/b> exists in your working directory, you will be offered to use it; otherwise, you must specify a valid template filename.<br \/>\nThis file should contain whatever input directives you require for your PySCF calculation, as the interface will generate the remainder of the input automatically.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>You will then be queried about an initial wavefunction guess.<br \/>\nIf you have a previous checkpoint file with MOs, you can supply its path; the file will be copied as <b><tt>pyscf.init.chk<\/tt><\/b> into the job directory.<br \/>\nIf you choose not to provide a guess, a warning reminds you that CASSCF calculations may run very slowly or yield incorrect results without a proper starting wavefunction.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, you must specify the amount of memory (in MB) that PySCF may use.<br \/>\nCurrently, the number of CPU cores cannot be set during setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When the job is prepared, a file named <b><tt>PYSCF.resources<\/tt><\/b> is written into the job directory containing the scratch directory and memory settings.<br \/>\nThe specified <b><tt>PYSCF.template<\/tt><\/b> is copied into the directory, and-if provided-the initial wavefunction file is also placed there.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.21\"><\/a><\/p>\n<h2>\n6.21  ASE Database Interface<\/h2>\n<p><a id=\"sec:int:ase_db\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Single child hybrid interface that stores data into an ASE database.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– ASE_DB (<a href=\"https:\/\/wiki.fysik.dtu.dk\/ase\/index.html\">Atomic Simulation Environment<\/a>) interface is a single-child hybrid interface that intercepts data from its child interface and stores it into an ASE database.<br \/>\nDuring interception the data will not be changed and is then directly passed to a parent interface or the S<span style=\"font-size:x-small\">HARC<\/span> driver.<br \/>\nThis interface is particularly useful to generate datasets for training machine learning models.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Available features  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>– ASE_DB interface provides exactly the same set of features as the chosen child interface, without any restrictions.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.21.1\"><\/a><\/p>\n<h3>\n6.21.1  Template file: <b><tt>ASE_DB.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The ASE_DB.template file is written in yaml format. Table <a href=\"#tab:ase_sh2\">6.31<\/a> lists the existing keywords.<br \/>\nA fully commented template file for this interface with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_ASE_DB\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.31\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.31: Keywords for the <b><tt>ASE_DB.template<\/tt><\/b> input file.<\/div>\n<p> <a id=\"tab:ase_sh2\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">reference <\/td>\n<td align=\"left\">Specifies the reference SHARC interface that is used to generate the data. Is a dictionary that contains three keys, ïnterface” contains the name of the child interface being used, followed by a list ärgs” that contains arguments which are used to instantiate the child interface, and “kwargs” that contains a dictionary of keyword arguments which are used to instantiate the child interface. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">props_to_save <\/td>\n<td align=\"left\">Is a list with the names of the properties to be stored in the ASE database.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ase_file <\/td>\n<td align=\"left\">Name or path of the ASE database file, if the file already exists the data will be appended.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">format <\/td>\n<td align=\"left\">Specifies the format of the stored data. There are two options, ßharc” which leaves the data as is, and ßpainn” which converts the data into a format SPaiNN uses.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">output_steps <\/td>\n<td align=\"left\">Save every nth step to the database.<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.21.2\"><\/a><\/p>\n<h3>\n6.21.2  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>As a hybrid interface, there are some peculiarities when doing a setup with <b><tt>SHARC_ASE_DB.py<\/tt><\/b>.<br \/>\nTo use <b><tt>SHARC_ASE_DB.py<\/tt><\/b> with any child interface, during setup select <b><tt>SHARC_ASE_DB.py<\/tt><\/b>.<br \/>\nImmediately after, you will get prompted to provide the <b><tt>ASE_DB.template<\/tt><\/b> file, which contain the information of which child interface is desired.<br \/>\nThe ASE_DB interface will then instantiate its child, in order to access the child’s feature set and itself returning its feature set to the setup script.<br \/>\nNote that if the child interface is another hybrid interface, then you will get asked for that interface’s template file as well, until all interfaces of the call tree are specified.<br \/>\nThe details depend slightly on which hybrid interface you use.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The situation is different if <b><tt>SHARC_ASE_DB.py<\/tt><\/b> is not the topmost interface in the call tree.<br \/>\nIn that case, the template file of the calling hybrid interface has to specify the ASE_DB interface as a child.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After selecting the interface and its child(ren), at a later point the setup script will start the interface-specific setup dialogue.<br \/>\nHowever, <b><tt>SHARC_ASE_DB.py<\/tt><\/b> itself does not require any settings itself and directly delegates to the child’s interface-specific setup dialogue.<br \/>\nPay attention to the <b><tt>Setting up child interface<\/tt><\/b> notice.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.22\"><\/a><\/p>\n<h2>\n6.22  Umbrella Sampling Interface<\/h2>\n<p><a id=\"sec:int:umbrella\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Single-child hybrid interface to add various harmonic restraints to a molecule.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>-umbrella sampling interface allows adding harmonic restraints to any other calculation.<br \/>\nRestraints are possible for distances, angles, dihedrals, and energy gaps.<br \/>\nMultiple restraints are possible.<br \/>\nThe sum of all restrain energies is added uniformly to all state energies, and their gradients are added uniformly to all state gradients, for those gradients that were requested by the caller.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If <b><tt>pytorch<\/tt><\/b> is installed, it will be used to compute the energies and gradients of all geometrical restraints (distances, angles, dihedrals), but not for energy gaps.<br \/>\nIf <b><tt>pytorch<\/tt><\/b> is not installed, all restraints are nonetheless available through a custom implementation of energies and forces.<br \/>\nFor energy gap restraints, the gradient of both involved states will be added to the set of requested states received from the caller (or of all involved states if more than one energy gap restraint is used).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Available features  <\/b><br \/>\nThe S<span style=\"font-size:x-small\">HARC<\/span>-umbrella sampling interface provides exactly the same set of features as the chosen child interface, without any restrictions.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.22.1\"><\/a><\/p>\n<h3>\n6.22.1  Template file: <b><tt>UMBRELLA.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interface requires three files in total: a template file in standard S<span style=\"font-size:x-small\">HARC<\/span> syntax, the restraint file, and the resources file.<br \/>\nTable <a href=\"#tab:umbrella_temp\">6.32<\/a> provides the keys for the template file.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.32\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.32: Keywords for the <b><tt>UMBRELLA.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:umbrella_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">restraint_file <\/td>\n<td align=\"left\">(string) Path to the file containing the restraint specifications. See below for the format of this file.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">child-program <\/td>\n<td align=\"left\">(string) Name of the child interface. For interface <b><tt>SHARC_<name>.py<\/tt><\/b>, provide the <b><tt><name><\/tt><\/b> part here. It will be automatically made uppercase. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">child-dir <\/td>\n<td align=\"left\">(string) Relative path to the folder containing the input files for the child interface. Default is <b><tt><NAME>\/<\/tt><\/b>.\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.22.2\"><\/a><\/p>\n<h3>\n6.22.2  Restraints file<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The restraints file specifies the restraints to add to the potential energy of all states.<br \/>\nThe file contains one line per restraint, in the following way:<\/p>\n<pre>\nr   300. kcal\/mol angstrom   1.4 angstrom  1 2\na   800. cm-1     degree    90.0 degree    1 2 3\nd    75. kj\/mol   radian     0.0 radian    1 2 3 4\nde   4.6 per      eV         0.3 eV        1 2\n<\/pre>\n<p>Here, column 1 specifies the type of restraint.<br \/>\nThe keywords are case-insensitive.<br \/>\nThere can be as many lines\/restraints as desired, of any type of restraint.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Column 2 specifies the numerical value of the force constant k used in the harmonic restraint.<br \/>\nIn principle, this force constant is internally used in terms of units of Hartree energy, Bohr radius, and radians.<br \/>\nTo simplify their input, columns 3 and 4 can be used to provide units.<br \/>\nIn the example, the force constants are 300 kcal\/mol\/Å, 800 cm<sup>−1<\/sup>\/degree, 75 kJ\/mol\/radian, and 4.6 eV<sup>−1<\/sup>.<br \/>\nHere, each unit keyword defines a factor, and the numerical value in column 2 is multiplied by the factor from column 3 and divided by the factor from column 4.<br \/>\nThe keywords <b><tt>eh<\/tt><\/b>, <b><tt>bohr<\/tt><\/b>, <b><tt>radian<\/tt><\/b>, <b><tt>one<\/tt><\/b>, and <b><tt>per<\/tt><\/b> are aliases for a factor of 1.<br \/>\nOther possible keywords are <b><tt>kcal\/mol<\/tt><\/b>, <b><tt>kj\/mol<\/tt><\/b>, <b><tt>eV<\/tt><\/b>, <b><tt>angstrom<\/tt><\/b>, and <b><tt>degree<\/tt><\/b>, with the respective conversion factors.<br \/>\nAll keywords are case-insensitive.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Columns 5 and 6 specify the position of the minimum of the harmonic restraint, called the reference value below in the equations.<br \/>\nThe keywords in column 6 act as multiplicative factors to the numerical value, and all the same keywords can be used.<br \/>\nThe keywords in column 6 do not need to be the same as in column 4.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Columns 7 and further ones specify the indices of the atoms or states that are involved in the restraints.<br \/>\nIndices for atoms and for states both start at 1.<br \/>\nFor bonds, two indices must be given, and the restraint is invariant under switching of the two indices.<br \/>\nFor angles, three indices must be given, where the second index defines the apex atom.<br \/>\nFor dihedrals, four indices must be given, in the order in which they are connected.<br \/>\nFor energy gaps, two indices must be given, where the second index will be used as the upper state (see equation below, a positive reference energy gap will force the second state to be above the first state).<br \/>\nThis choice is made so that “negative” gaps can be sampled, e.g., if one of the states is a singlet and one is a triplet.<br \/>\nNote that the state indices follow standard S<span style=\"font-size:x-small\">HARC<\/span> state indexing (in the MCH representation, which is the representation that the interfaces work in).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The following energy expressions are used:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-10.png\">\n<\/td>\n<td width=\"1%\">(6.7)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-11.png\">\n<\/td>\n<td width=\"1%\">(6.8)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-12.png\">\n<\/td>\n<td width=\"1%\">(6.9)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-13.png\">\n<\/td>\n<td width=\"1%\">(6.10)<\/td>\n<\/tr>\n<\/table>\n<p>Here, i, j, k, and l are atom indices, α and β are state indices (β is assumed to be the upper state), k is a force constant, and “ref” indicates the chosen center of the bias potential.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.22.3\"><\/a><\/p>\n<h3>\n6.22.3  Resource file: <b><tt>UMBRELLA.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The resource file has only one keyword, as given in Table <a href=\"#tab:umbrella_sh2\">6.33<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.33\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.33: Keywords for the <b><tt>UMBRELLA.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:umbrella_sh2\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scratchdir <\/td>\n<td align=\"left\">(string) Path to the scratch directory. This will be used to override the scratch directory of the child, as is customary for hybrid interfaces (likewise, if <b><tt>SHARC_UMBRELLA.py<\/tt><\/b> is called from a hybrid parent interface, then the <b><tt>scratchdir<\/tt><\/b> from <b><tt>UMBRELLA.resources<\/tt><\/b> will be ignored).\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.22.4\"><\/a><\/p>\n<h3>\n6.22.4  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>As a hybrid interface, there are some peculiarities when doing a setup with <b><tt>SHARC_UMBRELLA.py<\/tt><\/b>.<br \/>\nTo use <b><tt>SHARC_UMBRELLA.py<\/tt><\/b>, select it directly in your setup script.<br \/>\nImmediately, you will be prompted for the path to your <b><tt>UMBRELLA.template<\/tt><\/b> file, which tells the interface which child QMin program to invoke (plus other details).<br \/>\nIf your child is itself a hybrid interface, you will then be asked for that interface’s own template file, and so on down the call tree.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After reading the template, you will be asked if you already have an <b><tt>UMBRELLA.resources<\/tt><\/b> file.<br \/>\nIf so, supply its path here; otherwise it will remain absent (but <b><tt>SHARC_UMBRELLA.py<\/tt><\/b> does not have many resource options).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next you will see a <b><tt>Setting up child interface<\/tt><\/b> notice.<br \/>\nAt this point, <b><tt>SHARC_UMBRELLA.py<\/tt><\/b> hands off to the child interface’s own setup dialogue.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.23\"><\/a><\/p>\n<h2>\n6.23  Numerical Differentiation Interface<\/h2>\n<p><a id=\"sec:int:numdiff\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Single-child hybrid interface (with clones of the same child) for finite differences numerical gradients and nonadiabatic coupling vectors.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>-numerical differentiation interface can compute gradients, nonadiabatic coupling vectors, dipole moment derivatives, and spin-orbit coupling derivatives for any other interface that can provide energies, wave function overlaps, dipole moments, and spin-orbit couplings, respectively.<br \/>\nCurrently, the interface is based on central differences evaluated in Cartesian coordinates, using uniform displacements for all atoms and directions.<br \/>\nThe interface can do the derivatives in two different ways (<b><tt>numdiff_representation<\/tt><\/b>), either using the adiabatic quantities directly, or using wave function overlaps to diabatize the quantities and computing their derivatives.<br \/>\nThe latter option is slightly more expensive but more numerically stable if electronic state crossings occur close to the reference geometry.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For ease of reference, we provide the essential equations here.<br \/>\nAdiabatic central differences are evaluated as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-14.png\"><a id=\"eq:int:numdiff:central\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(6.11)<\/td>\n<\/tr>\n<\/table>\n<p>where F is a matrix element of the Hamiltonian, overlap, or dipole matrices.<br \/>\nFor the quad-step central differences, the equation is instead:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-15.png\"><a id=\"eq:int:numdiff:quad\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(6.12)<\/td>\n<\/tr>\n<\/table>\n<p>For diabatic central differences, the equation is:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-16.png\"><a id=\"eq:int:numdiff:diabatic\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(6.13)<\/td>\n<\/tr>\n<\/table>\n<p>where the entire Hamiltonian or dipole matrices <b>F<\/b> are transformed before computing the derivative.<br \/>\nIn the diabatic mode, the nonadiabatic couplings are computed as the energy-gap-scaled off-diagonal elements of the derivatives of the diabatic Hamiltonian (i.e., [1\/(∆E)][(∂H)\/(∂R)]):<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-17.png\"><a id=\"eq:int:numdiff:diabatic_nac\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(6.14)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>As an important note, currently, <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> will not accept any hybrid interface as its child (i.e., those derived from the <b><tt>SHARC_HYBRID.py<\/tt><\/b> base class.<br \/>\nThis restriction might change in future versions.<br \/>\nAlso note that fast child interfaces will generally be run in non-persistent mode (i.e., with file I\/O).<br \/>\nHence, numerical differences of fast interfaces will be slower than expected.<br \/>\nThese restrictions arise because <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> manipulates the save directory of its child, but hybrid children would have an unpredictable save directory structure and fast interfaces in persistent mode do not write save directories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Available features  <\/b><br \/>\nThe S<span style=\"font-size:x-small\">HARC<\/span>-numerical differentiation interface provides features that depend on the features of the child as well as on the <b><tt>numdiff_representation<\/tt><\/b> and <b><tt>whitelist<\/tt><\/b> options (more details below).<br \/>\nBriefly, if the child can provide energies, then <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> can provide gradients.<br \/>\nIf the child provides energies and overlaps, <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> can provide nonadiabatic coupling vectors.<br \/>\nIf the child provides dipole moments or spin-orbit couplings, their respective derivatives are available from <b><tt>SHARC_NUMDIFF.py<\/tt><\/b>.<br \/>\nIf <b><tt>numdiff_representation<\/tt><\/b> is set to diabatic, then all four types of derivatives all require overlaps from the child.<br \/>\nIf any of the four quantities would also be available from the child directly, then <b><tt>whitelist<\/tt><\/b> can be used to use the quantities from the child rather than from numerical differentiation.<br \/>\nAny request besides gradients, nonadiabatic coupling vectors, dipole moment derivatives, and spin-orbit coupling derivatives is completely delegated to the child interface (for the reference geometry).<br \/>\nHence, the feature set of <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> is the feature set of the child, plus those derivatives that can be computed.<br \/>\nNote that <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> does not accept point charges, so it cannot serve as QM interface in QM\/MM calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.23.1\"><\/a><\/p>\n<h3>\n6.23.1  Template file: <b><tt>NUMDIFF.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interface requires two input files.<br \/>\nThe possible options for the template file are given in Table <a href=\"#tab:numdiff_temp\">6.34<\/a>.<br \/>\nThe file follows standard keyword argument syntax, as in other interfaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.34\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.34: Keywords for the <b><tt>NUMDIFF.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:numdiff_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">qm-program <\/td>\n<td align=\"left\">(string) Name of the child interface. For interface <b><tt>SHARC_<name>.py<\/tt><\/b>, provide the <b><tt><name><\/tt><\/b> part here. It will be automatically made uppercase. Note that <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> formally uses multiple children, but they are clones (all share the same settings), so only one child needs to be specified. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">qm-dir <\/td>\n<td align=\"left\">(string) Relative path to the folder containing the input files for the child interface. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">numdiff_method <\/td>\n<td align=\"left\">(string) Specifies the numerical differentiation scheme. Currently, options are <b><tt>central-diff<\/tt><\/b> (the default) and <b><tt>central-quad<\/tt><\/b>. The default uses two displacements per degree of freedom, the second option uses twice as much. See Equations (<a href=\"#eq:int:numdiff:central\">6.11<\/a>) and (<a href=\"#eq:int:numdiff:quad\">6.12<\/a>).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">numdiff_representation <\/td>\n<td align=\"left\">(string) Specifies the electronic representation for differentiating. Currently, options are <b><tt>adiabatic<\/tt><\/b> (the default) and <b><tt>diabatic<\/tt><\/b>. The first option uses the adiabatic quantities of the displaced geometries directly, whereas the second option diabatizes them using the overlaps between reference geometry and displaced geometry. This adds the cost of overlap calculations at all displacements, but leads to more accurate derivatives. See Equation (<a href=\"#eq:int:numdiff:diabatic\">6.13<\/a>).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">numdiff_stepsize <\/td>\n<td align=\"left\">(float) The numerical Cartesian displacement in Bohrs. Default is 0.01. For <b><tt>central-quad<\/tt><\/b>, additional displacements of twice that value are done.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">whitelist <\/td>\n<td align=\"left\">(one or more strings) The requests specified here are delegated to the reference child, if it can provide them. Possible options are <b><tt>grad<\/tt><\/b>, <b><tt>nacdr<\/tt><\/b>, <b><tt>dmdr<\/tt><\/b>, and <b><tt>socdr<\/tt><\/b>. Note that an empty list is not possible, if you do not want any white-listed requests, remove the <b><tt>whitelist<\/tt><\/b> command.\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.23.2\"><\/a><\/p>\n<h3>\n6.23.2  Resource file: <b><tt>NUMDIFF.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The resource file has only few keywords, as given in Table <a href=\"#tab:numdiff_sh2\">6.35<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A few remarks on how the children are run.<br \/>\nIn all cases, the reference child is run first.<br \/>\nBy default, it uses whatever number of CPU cores is specified in its resource file.<br \/>\nIf <b><tt>use_all_cores_for_ref<\/tt><\/b> is true, the reference child will use all CPU cores available to <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> instead.<br \/>\nAfter the reference child is finished, <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> evaluates whether displacement calculations have to be carried out, depending on (i) the current requests, (ii) the <b><tt>whitelist<\/tt><\/b>, and (iii) the available features of the child.<br \/>\nIf <b><tt>grad<\/tt><\/b>, <b><tt>nacdr<\/tt><\/b>, <b><tt>dmdr<\/tt><\/b>, or <b><tt>socdr<\/tt><\/b> are requested and not white-listed and available from the child, they will be computed numerically.<br \/>\nOnly then the displaced children will be set up and run, distributed over the number of CPU cores available to <b><tt>SHARC_NUMDIFF.py<\/tt><\/b>.<br \/>\nEach displaced child will use as many CPU cores as specified in the child’s resource file.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.35\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.35: Keywords for the <b><tt>NUMDIFF.resources<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:numdiff_sh2\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">scratchdir <\/td>\n<td align=\"left\">(string) Path to the scratch directory. This will be used to host the scratch directories of all children (reference and displacements), i.e., <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> will overwrite the scratch directories of all children (likewise, if <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> is called from a hybrid parent interface, then the <b><tt>scratchdir<\/tt><\/b> from <b><tt>NUMDIFF.resources<\/tt><\/b> will be ignored).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ncpu <\/td>\n<td align=\"left\">(int) The number of CPU cores used to run the calculation of the reference and displaced children. Note that the reference child is always run first. Only the displacement children are run in parallel.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">use_all_cores_for_ref <\/td>\n<td align=\"left\">(bool) Use all CPU cores as available to <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> for the reference child.\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.23.3\"><\/a><\/p>\n<h3>\n6.23.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>As a hybrid interface, there are some peculiarities when doing a setup with <b><tt>SHARC_NUMDIFF.py<\/tt><\/b>.<br \/>\nTo use it, select <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> directly in your setup script.<br \/>\nYou will then immediately be prompted for the path to your <b><tt>NUMDIFF.template<\/tt><\/b> file, which tells the interface which underlying QM program to invoke and how to perform the numerical differentiation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_NUMDIFF.py<\/tt><\/b> will then instantiate its child and query it for its feature set.<br \/>\nBased on that feature set and the settings in the template file, the <b><tt>SHARC_NUMDIFF.py<\/tt><\/b> interface automatically composes its own feature set, which is returned to the setup script.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>At a later point during setup, the interface-specific setup dialogue is started.<br \/>\n<b><tt>SHARC_NUMDIFF.py<\/tt><\/b> will ask for the number of CPU cores and the scratch directory to be used.<br \/>\nSubsequently, the interface-specific setup dialogue of the child is launched (indicated by <b><tt>Setting up QM\u2011interface<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.24\"><\/a><\/p>\n<h2>\n6.24  QM\/MM Interface<\/h2>\n<p><a id=\"sec:int:qmmm\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Multi-child hybrid interface for QM\/MM calculations using electrostatic embedding and link atoms.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>-QM\/MM interface implements <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-18.png\"><a id=\"eq:QMMM\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(6.15)<\/td>\n<\/tr>\n<\/table>\n<p>Here, E<sub>QM<\/sub>(QM; MMpc) is the QM energy of the QM region, including its interaction with the MM point charges.<br \/>\nE<sub>MM<\/sub>(QM’+MM) is the MM energy of the full system, with QM region point charges set to zero.<br \/>\nE<sub>MM<\/sub>(QM’) is the MM energy of the QM region alone, also with QM region point charges set to zero.<br \/>\nSetting the QM region point charges to zero at the MM level prevents double-counting Coulomb interactions, which are already accounted for in the QM calculation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within the interface, the three energy contributions from Equation (<a href=\"#eq:QMMM\">6.15<\/a>) are computed in three independent calls to three child interfaces.<br \/>\nThese are called the <b><tt>QM<\/tt><\/b>, <b><tt>MMS<\/tt><\/b>, and <b><tt>MML<\/tt><\/b> children, in the order given in the equation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interface also supports link atoms, i.e., bonds between a QM and an MM atom.<br \/>\nTo make this work, the connectivity table has to be included in the <b><tt>QMMM.table<\/tt><\/b> input file (see below).<br \/>\nThe link atom scheme<a href=\"#Senn2009ACIE\" id=\"CITESenn2009ACIE\" class=\"tth_citation\">[103<\/a>] is treated as follows in the <b><tt>QM<\/tt><\/b> calculation.<br \/>\nAll QM atoms are kept, all MM atoms bonded to QM atoms are replaced by hydrogen.<br \/>\nThe position of the hydrogen (cap) atoms is defined by the positions of the QM and bonded MM atoms, so the cap atoms do not provide independent degrees of freedom.<br \/>\nThe point charge of the bonded MM atom is set to zero, its charge is distributed evenly over all its bonding partners that are MM atoms.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Available features  <\/b><br \/>\nThe S<span style=\"font-size:x-small\">HARC<\/span>-QM\/MM interface provides features that depend on the features of the QM and MM child interfaces.<br \/>\nFor electrostatic embedding (which is currently the only option), the QM interface must have the <b><tt>point_charges<\/tt><\/b> feature, i.e., it needs to be able to receive point charges and include them in the QM calculation.<br \/>\nLikewise, the MM interface needs to have the <b><tt>multipolar_fit<\/tt><\/b> feature, i.e., it needs to be able to provide partial charges\/multipoles for the MM state.<br \/>\nIf these features are available, then the QM\/MM interface will provide energies and\/or gradients if they are available from both the QM and MM interfaces.<br \/>\nAll other features are inherited from the QM interface.<br \/>\nThe QM\/MM interface does not provide the <b><tt>point_charges<\/tt><\/b> feature, so it is currently not possible to do nested QM\/QM\/MM or QM\/MM\/MM calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.24.1\"><\/a><\/p>\n<h3>\n6.24.1  Template file: <b><tt>QMMM.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interface requires two input files.<br \/>\nThe possible options for the template file are given in Table <a href=\"#tab:qmmm_temp\">6.36<\/a>.<br \/>\nThe file follows standard keyword argument syntax, as in other interfaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.36\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.36: Keywords for the <b><tt>QMMM.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:qmmm_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">qmmm_table <\/td>\n<td align=\"left\">(string) Path to the <b><tt>QMMM.table<\/tt><\/b> file containing the connectivity and QM\/MM type information. See Section <a href=\"#sec:int:qmmm:table\">6.24.3<\/a>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">qm-program <\/td>\n<td align=\"left\">(string) Name of the QM child interface. For interface <b><tt>SHARC_<name>.py<\/tt><\/b>, provide the <b><tt><name><\/tt><\/b> part here. It will be automatically made uppercase. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">mm-program <\/td>\n<td align=\"left\">(string) Name of the MM child interface. Note that the MML and MMS children use the same interface class. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">embedding <\/td>\n<td align=\"left\">(string) Selects the type of embedding. Currently, only <b><tt>subtractive<\/tt><\/b> is allowed (the default).\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">qm-dir <\/td>\n<td align=\"left\">(string) Relative path to the folder containing the input files for the QM child interface. This keyword is required.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">mml-dir <\/td>\n<td align=\"left\">(string) Relative path to the folder containing the input files for the MML child interface. Default is <b><tt>MML<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">mms-dir <\/td>\n<td align=\"left\">(string) Relative path to the folder containing the input files for the MMS child interface. Default is <b><tt>MMS<\/tt><\/b>.\n<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">mm_dipole <\/td>\n<td align=\"left\">(bool) If false (the default), then the dipole moments returned by the QM\/MM interface are those of the QM interface. If true, then the dipole moment induced by the distribution of MM charges is added to the diagonal of the dipole matrix.\n<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.24.2\"><\/a><\/p>\n<h3>\n6.24.2  Resource file: <b><tt>QMMM.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This file is currently not used.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.24.3\"><\/a><\/p>\n<h3>\n6.24.3  Connectivity and QM\/MM type file: <b><tt>QMMM.table<\/tt><\/b><\/h3>\n<p><a id=\"sec:int:qmmm:table\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This file specifies the connectivity\/topology of the system and assigns each atom to either the QM or MM region.<br \/>\nAn example file is shown here.<\/p>\n<pre>\nqm  O    2\nqm  C    3 4            1\nqm  H                   2\nqm  C    5 6 7          2\nqm  H                   4\nqm  H                   4\nmm  C    8 9 10         4\nmm  H                   7\nmm  H                   7\nmm  C    11 12 13       7\nmm  H                   10\nmm  H                   10\nmm  H                   10\nmm  O    15 16\nmm  H                   14\nmm  H                   14\n<\/pre>\n<p>The file specifies a OHC-CH2-CH2-CH3 + H2O system (butanal plus one water), where the OHC-CH2 group is in the QM region.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.24.4\"><\/a><\/p>\n<h3>\n6.24.4  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>As a hybrid interface, there are some peculiarities when doing a setup with <b><tt>SHARC_QMMM.py<\/tt><\/b>.<br \/>\nTo use it, select <b><tt>SHARC_QMMM.py<\/tt><\/b> directly in your setup script.<br \/>\nYou will then immediately be prompted for the path to your <b><tt>QMMM.template<\/tt><\/b> file, which tells the interface which underlying QM and MM interfaces to invoke.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_QMMM.py<\/tt><\/b> will then instantiate its children and query them for their feature set.<br \/>\nBased on these feature sets, the <b><tt>SHARC_QMMM.py<\/tt><\/b> interface automatically composes its own feature set, which is returned to the setup script.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>At a later point during setup, the interface-specific setup dialogue is started.<br \/>\n<b><tt>SHARC_QMMM.py<\/tt><\/b> will ask for a resource file, which will be copied if given.<br \/>\nSubsequently, the interface-specific setup dialogues of the children are launched sequentially (indicated by <b><tt>Setting up QM-interface<\/tt><\/b>, <b><tt>Setting up MML-interface (whole system)<\/tt><\/b>, and for subtractive QM\/MM schemes also <b><tt>Setting up MMS-interface (qm system)<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.25\"><\/a><\/p>\n<h2>\n6.25  ECI Interface<\/h2>\n<p><a id=\"sec:int:eci\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Multi-child hybrid interface for excitonic Hartree-Fock and excitonic configuration interaction (EHF\/ECI) calculations.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>-ECI interface (<b><tt>SHARC_ECI.py<\/tt><\/b>) implements the ab-initio exciton-like theory for the efficient calculation of ground and excited electronic states of multichromophoric systems, described in the references <a href=\"#Pitesa2024\" id=\"CITEPitesa2024\" class=\"tth_citation\">[104<\/a>] and <a href=\"#Pitesa2025\" id=\"CITEPitesa2025\" class=\"tth_citation\">[105<\/a>]. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.25.1\"><\/a><\/p>\n<h3>\n6.25.1  Theory and implementation<\/h3>\n<p><a id=\"sec:int:eci:theory\"><br \/>\n<\/a><br \/>\nThe ECI method works as follows, in roughly three steps.<br \/>\nThese steps assume that the multichromophoric system is divided into fragments (also called chromophores or sites) that share no atoms (i.e., disjoint fragments).<\/p>\n<div class=\"p\"><!----><\/div>\n<h4>Site-state calculations<\/h4>\n<p>In the first step, <b><tt>SHARC_ECI.py<\/tt><\/b> conducts a single-point calculation (so-called site state calculations, SSCs) of the desired number of states (of various multiplicities and charges) for each individual site, with embedding point charges placed on the positions of the nuclei of all other sites.<br \/>\nThis gives the set of so-called site states.<br \/>\nOne feature of the ECI method is that it is agnostic of the precise electronic-structure ansatz used in the SSC, i.e., the site states can be calculated with any level of theory.<br \/>\nHence, <b><tt>SHARC_ECI.py<\/tt><\/b> performs the SSCs via its SSC children-(some of) the ab-initio interfaces of S<span style=\"font-size:x-small\">HARC<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<h4>Building the ECI basis<\/h4>\n<p>In the second step, <b><tt>SHARC_ECI.py<\/tt><\/b> constructs the so-called excitonic basis-a basis of antisymmetrized products of the site states.<br \/>\nHerein, unlike in conventional exciton models, one can have antisymmetrized products of different kinds-the product of all site ground states (GS product), the products where a single site is in an excited state and all others in the ground state (local excitations, LEs), and the products with an arbitrary number of excited site states (multilocal excitations, MLEs: double-local excitations, DLEs; triple-local excitations, TLEs; …).<br \/>\nWhich type of the products will be included in the basis is controlled by specifying the ECI expansion (EHF, ECIS, ECISD,…), where the GS product plays role of excitonic “HF configuration”, LEs play role of excitonic ßingles”, DLEs of excitonic “doubles”, etc.<br \/>\nNote that this does not mean that, e.g., all LEs are electronically singly-excited configurations.<br \/>\nIf the excited site state present in an LE is a doubly-excited state itself, the LE will be a doubly-excited configuration (but still an excitonic ßingle”).<br \/>\nAlso, this does not mean that the products are individual Slater determinants, but rather correlated configurations, if the site states themselves are.<br \/>\nIn this sense, the excitonic basis in ECI is nominally build in the analogous way the CI basis is build: the ground site states are multiplied to give the GS product, and then all desired (M)LEs are generated by exchanging a certain number (one for LEs, two for DLEs) of ground site states in the GS product with excited site states provided for particular fragments in the SSC.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>    However, the ECI interface is not restricted only to the GS product as the äufbau” one (i.e., the one on which ground-to-excited site state replacements will be done to create LEs and MLEs), but it allows the definition of multiple <i>aufbau site states<\/i> per fragment, which then give rise to multiple <i>aufbau products<\/i>, in an each-by-each-multiplication fashion.<br \/>\nMoreover, different aufbau site states of a single fragment can even have different charges (e.g. S<sub>0<\/sub> of neutral fragment, and D<sub>0<\/sub> of fragment’s cation).<br \/>\nEven excited site states can be defined as aufbau site states.<br \/>\nThe (M)LEs are then created by replacing a certain number of aufbau site states from each aufbau product with non-aufbau site states <i>of the same charge but not necessarily of the same multiplicity<\/i>.<br \/>\nFor example, in a two-chromophoric system, if only the S<sub>0<\/sub> site states of both fragments are defined as the aufbau site states, only the \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub> product will be the aufbau product (in this case matching with the GS product).<br \/>\nThen, if each chromophore has S<sub>1<\/sub>, T<sub>1<\/sub>, D<sub>0<\/sub><sup>+<\/sup>, D<sub>0<\/sub><sup>−<\/sup>, D<sub>1<\/sub><sup>+<\/sup> and D<sub>1<\/sub><sup>−<\/sup> non-aufbau site states provided in the SSCs, and the ECIS expansion is requested, the constructed non-aufbau products will be: \\ket<span class=\"roman\">S<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub>, \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>1<\/sub>, \\ket<span class=\"roman\">T<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub> and \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">T<\/span><sub>1<\/sub>.<br \/>\nThe charge-transfer (CT) products \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup> and \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup> will not be constructed, as this would require changing the fragments’ charges.<br \/>\nThese products can be constructed by setting all S<sub>0<\/sub>, D<sub>0<\/sub><sup>+<\/sup> and D<sub>0<\/sub><sup>−<\/sup> site states as the aufbau ones for both fragments.<br \/>\nIn this case, the aufbau products will be \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub>, \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup>, \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup>, \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">S<\/span><sub>0<\/sub>, \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup><span class=\"roman\">S<\/span><sub>0<\/sub>, \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup> and \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup>.<br \/>\nDepending on the specified full-system charge, the interface will take either only \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub>, \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup> and \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup> for charge 0, or \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup> and \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">S<\/span><sub>0<\/sub> for charge 1, or \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup> and \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup><span class=\"roman\">S<\/span><sub>0<\/sub> for charge −1.<br \/>\nThen, for charge 0 and an ECIS expansion, the \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub> aufbau product will give \\ket<span class=\"roman\">S<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub>, \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>1<\/sub>, \\ket<span class=\"roman\">T<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub> and \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">T<\/span><sub>1<\/sub> LEs, the \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup> will give \\ket<span class=\"roman\">D<\/span><sub>1<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup> and \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>1<\/sub><sup>−<\/sup> LEs, while \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup> will give \\ket<span class=\"roman\">D<\/span><sub>1<\/sub><sup>−<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup> and \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup><span class=\"roman\">D<\/span><sub>1<\/sub><sup>+<\/sup> LEs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>    Note that the products (both aufbau or non-aufbau) actually contain the site states with well-defined site-specific S and M<sub>S<\/sub> value. In this sense, \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup> above is not a single product but rather a symbolic representation of a set of four products, having four combinations of M<sub>S<\/sub> values of the two doublet site states: (+\\sfrac12,+\\sfrac12), (+\\sfrac12,−\\sfrac12), (−\\sfrac12,+\\sfrac12) and (−\\sfrac12,−\\sfrac12).<br \/>\nAfter all products are generated, the interface will take only those having the total M<sub>S<\/sub> value equal to the S value of the specified full-system multiplicity (0 for singlets, \\sfrac12 for doublets, 1 for triplets, etc.).<br \/>\nFor example, for full-system singlet spin, the interface will take \\ket<span class=\"roman\">D<\/span><sub>x<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>y<\/sub><sup>−<\/sup> products only with (+\\sfrac12,−\\sfrac12) and (−\\sfrac12,+\\sfrac12) combinations of M<sub>S<\/sub> values, while for triplets it will take only (+\\sfrac12,+\\sfrac12).<br \/>\nSimilarly, for full-system triplet spin, only \\ket<span class=\"roman\">T<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub> with T<sub>1<\/sub> site state having M<sub>S<\/sub>=1 will be taken, etc.<br \/>\nHowever, such products are not necessarily eigenfunctions of the full-system spin.<br \/>\nFor example, for singlet spin, \\ket<span class=\"roman\">S<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub> LE is a singlet configuration, but \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup> with either (+\\sfrac12,−\\sfrac12) or (−\\sfrac12,+\\sfrac12) is not.<br \/>\nIn this case, the singlet function is a linear combination [1\/(√2)][(+\\sfrac12,−\\sfrac12)−(−\\sfrac12,+\\sfrac12)].<br \/>\nThe less obvious example would be \\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">T<\/span><sub>1<\/sub>, which for the full-system doublet spin is a linear combination [1\/3][√6(−\\sfrac12,+1)−√3(\\sfrac12,0)].<br \/>\nThese spin-adapted products are called excitonic configuration state functions (ECSFs) and the interface will generate them automatically by diagonalization of the full-system spin operator.<br \/>\nThe raw antisymmetrized products are then referred to as excitonic Slater determinants (ESDs), in analogy with the CI method and Slater determinants.<\/p>\n<div class=\"p\"><!----><\/div>\n<h4>Construction of the ECI Hamiltonian<\/h4>\n<p>In the third step, the ECI Hamiltonian matrix of the full system is evaluated for each multiplicity (and M<sub>S<\/sub>=S) in the excitonic basis of ESDs.<br \/>\nThis is done within the strong orthogonality assumption (SOA).<br \/>\nTo construct the ECI Hamiltonian, one needs only two ïngredients” from the each site: the site energies and the site density matrices, which are obtained from the SSC children.<br \/>\nIt is important to note that the couplings between the ESDs where the two site states of a fragment differ in the charge are currently neglected, as the underlying theory is under development.<br \/>\nAn example for this would be the couplings between an LE and a CT product, e.g., \\mel<span class=\"roman\">S<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"overacc1\">∧<\/span>H<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup>.<br \/>\nThe Hamiltonian is then rotated to the basis of ECSFs, and the full-system states are obtained by diagonalization of the ECI Hamiltonian for each full-system multiplicity. <\/p>\n<div class=\"p\"><!----><\/div>\n<h4>EHF embedding<\/h4>\n<p>Importantly, before the SSCs, <b><tt>SHARC_ECI.py<\/tt><\/b> can determine the optimal embedding point charges of all atoms of all fragments via the excitonic Hartree-Fock (EHF) method <a href=\"#Pitesa2024\" class=\"tth_citeref\">[104<\/a>].<br \/>\nThe EHF algorithm involves iterative ground-state calculations on each fragment with the ground-state RESP point charges of other all fragments placed in the surroundings, followed by the RESP fit of the obtained ground-state densities, until all RESP charges stop changing.<br \/>\nThe ground-state calculations and the RESP fits are done via the EHF children of <b><tt>SHARC_ECI.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>    Such obtained charges should minimize the energy of the GS product, just like the optimal orbitals in HF minimize the energy of a Slater determinant.<br \/>\nHowever, <b><tt>SHARC_ECI.py<\/tt><\/b> also has some other options to utilize non-optimal embedding charges in various ways, in order to reduce computational cost (see below in Section <a href=\"#sec:int:eci:template\">6.25.3<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>    Note that the EHF part of the <b><tt>SHARC_ECI.py<\/tt><\/b> run will not calculate the EHF energy of the system, but will only find the optimal embedding charges (i.e., despite its name, it is an excitonic analogue of SCF rather than HF).<br \/>\nThe EHF energy will be calculated later when building the ECI Hamiltonian.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Available features  <\/b><br \/>\nThe <b><tt>SHARC_ECI.py<\/tt><\/b> currently provides only the <b><tt>h<\/tt><\/b>, <b><tt>dm<\/tt><\/b>, <b><tt>mol<\/tt><\/b> and <b><tt>point_charges<\/tt><\/b> features.<br \/>\nIt requires from its EHF children only the <b><tt>multipolar_fit<\/tt><\/b> and <b><tt>point_charges<\/tt><\/b>.<br \/>\nFrom the SSC children, it always requires the <b><tt>h<\/tt><\/b>, <b><tt>mol<\/tt><\/b>, <b><tt>density_matrices<\/tt><\/b> and <b><tt>point_charges<\/tt><\/b> features, regardless of the requests given to it.<\/p>\n<div class=\"p\"><!----><\/div>\n<h4>Limitations<\/h4>\n<p>The current theoretical framework and implementation entail a few consequences: <\/p>\n<ul>\n<li> Despite the ECI method being agnostic to the SSC ansatz, the site states can currently only be calculated on CIS\/TD-DFT level with Gaussian or on CASSCF level with OpenMolcas, since only <b><tt>SHARC_GAUSSIAN.py<\/tt><\/b> and <b><tt>SHARC_MOLCAS.py<\/tt><\/b> have the <b><tt>density_matrices<\/tt><\/b> feature.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> In order for the method to work accurately, sites can interact strongly but should not be too close in space (e.g., covalently bonded), as this will break the SOA.<br \/>\n The method is supposed to work well for supramolecular aggregates, metal complexes with no low-lying metal-centered excitations, and other similar systems.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Regardless of the system, the method will not diverge in the region of overlapping sites, due to the SOA.<br \/>\n Thus, the method should not currently be used to perform scans (that include close-site region), optimizations, or molecular dynamics.<br \/>\n It is currently primarily intended for the spectroscopic calculations on the systems described in the previous bullet.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Even if the sites might be sufficiently far apart, some of the calculated site states might penetrate the regions of other sites (e.g., Rydberg states) and thus break SOA.<br \/>\n Hence, <b><tt>SHARC_ECI.py<\/tt><\/b> will expel those site states prior to the construction of the ECI basis <a href=\"#Pitesa2024\" class=\"tth_citeref\">[104<\/a>].<\/p>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<p>We intent to overcome these limitations in future releases of S<span style=\"font-size:x-small\">HARC<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.25.2\"><\/a><\/p>\n<h3>\n6.25.2  QM directory of ECI interface<\/h3>\n<p>The <b><tt>QM<\/tt><\/b> directory of <b><tt>SHARC_ECI.py<\/tt><\/b> has to contain a template file (Section <a href=\"#sec:int:eci:template\">6.25.3<\/a>), a resources file (Section <a href=\"#sec:int:eci:resource\">6.25.4<\/a>), and a directory per child containing its input files.<br \/>\nAs mentioned above, <b><tt>SHARC_ECI.py<\/tt><\/b> has two types of children-EHF and SSC children.<br \/>\nAn EHF child is an interface used to calculate the ground state of a single fragment for a single full-system charge during the EHF procedure.<br \/>\nAn SSC child is an interface used to calculate all the (ground and excited) site states for a single fragment and a single charge for a single full-system charge.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>    All fragments are given a <b><tt>label<\/tt><\/b> in <b><tt>ECI.template<\/tt><\/b> (see Section <a href=\"#sec:int:eci:template\">6.25.3<\/a>).<br \/>\nThe names of the <b><tt>QM<\/tt><\/b> directories of the EHF children have to be <b><tt><label>_embedding_Z<Z><\/tt><\/b>, where <b><tt><Z><\/tt><\/b> is the full-system charge.<br \/>\nThe names of the <b><tt>QM<\/tt><\/b> directories of the SSC children have to be <b><tt><label>_z<z>_Z<Z><\/tt><\/b>, where <b><tt><z><\/tt><\/b> is the fragment charge and <b><tt><Z><\/tt><\/b> is again the full-system charge.<br \/>\nThe template file, the resources file and the structure of the standard output of <b><tt>SHARC_ECI.py<\/tt><\/b> will be illustrated in following subsections on an example of an ECI calculation of 6 neutral singlet and 6 neutral triplet states of a system containing two BODIPY chromophores connected via C-H… F hydrogen bond.<br \/>\nDonor is labeled <b><tt>BD<\/tt><\/b> and the acceptor <b><tt>BA<\/tt><\/b>, while the site states are calculated on TD-ωB97xD\/def2svp level with <b><tt>SHARC_GAUSSIAN.py<\/tt><\/b>.<br \/>\nThe example can be found in <b><tt>$SHARC\/..\/examples\/SHARC_ECI<\/tt><\/b>.<br \/>\nSince in this case we calculate only full-system neutral states while having site states of <b><tt>BD<\/tt><\/b> with charges 0 and 1 and site states of <b><tt>BA<\/tt><\/b> with charges 0 and −1 (see below in Section <a href=\"#sec:int:eci:template\">6.25.3<\/a>), the <b><tt>QM<\/tt><\/b> directory of <b><tt>SHARC_ECI.py<\/tt><\/b> in this case contains <b><tt>BD_embedding_Z0<\/tt><\/b>, <b><tt>BA_embedding_Z0<\/tt><\/b>, <b><tt>BD_z0_Z0<\/tt><\/b>, <b><tt>BD_z1_Z0<\/tt><\/b>, <b><tt>BA_z0_Z0<\/tt><\/b> and <b><tt>BA_z-1_Z0<\/tt><\/b> children <b><tt>QM<\/tt><\/b> subdirectories.<br \/>\nAlso, since each child is a S<span style=\"font-size:x-small\">HARC<\/span>-GAUSSIAN interface (also see in Section <a href=\"#sec:int:eci:template\">6.25.3<\/a>), each of these subdirectories contains the only two input files of <b><tt>SHARC_GAUSSIAN.py<\/tt><\/b>: <b><tt>GAUSSIAN.template<\/tt><\/b> and <b><tt>GAUSSIAN.resources<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.25.3\"><\/a><\/p>\n<h3>\n6.25.3  Template file: <b><tt>ECI.template<\/tt><\/b><\/h3>\n<p><a id=\"sec:int:eci:template\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The example below shows a template file of <b><tt>SHARC_ECI.py<\/tt><\/b> in <b><tt>yaml<\/tt><\/b> format for the aforementioned <b><tt>BD<\/tt><\/b>–<b><tt>BA<\/tt><\/b> system.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"small\">\n<pre>\n---\nfragments: \n    BD: \n        atoms: 0-20\n        aufbau_site_states: [{Z: 0, M: 1, N: 1},{Z: 1, M: 2, N: 1}]\n        EHF:\n            interface : GAUSSIAN\n            embedding_site_state:\n                0: {Z: 0, M: 1, N: 1}\n            guess: true\n            write: true\n            max_cycles: 10\n            forced: false\n            tQ: 0.01\n        SSC:\n            interface: GAUSSIAN\n            data: w\n            states:\n                0: [2, 0, 1]\n                1: [0, 1, 0]\n    BA: \n        atoms: 21-41\n        aufbau_site_states: [{Z: 0, M: 1, N: 1}, {Z: -1, M: 2, N: 1}]\n        EHF:\n            interface : GAUSSIAN\n            embedding_site_state:\n                0: {Z: 0, M: 1, N: 1}\n            guess: true\n            write: true\n            max_cycles: 10\n            forced: false\n            tQ: 0.01\n        SSC:\n            interface: GAUSSIAN\n            data: w\n            states:\n                0: [2, 0, 1]\n                -1: [0, 1, 0]\ncalculation:\n    tO: 0.90\n    RI: \n        active: true\n        Jauxbasis: def2svpjkfit\n        Kauxbasis: def2svpjkfit\n        tS: 1.e-4\n        tC: 1.e-3\n        chunksize: -1\n    excitonic_basis:\n        ECI: \n            0: true\n            1: all\n            2: all\n    active_integrals:\n        J: \n            '(0,0)': [ [BD, BA] ]\n            '(0,1)': [ [BD, BA] ]\n            '(0,2)': [ [BD, BA] ]\n        K: \n            '(0,0)': [ [BD, BA] ]\n            '(0,1)': [ [BD, BA] ]\n            '(0,2)': [ [BD, BA] ]  \n<\/pre>\n<\/p><\/div>\n<div class=\"p\"><!----><\/div>\n<p>The top-level dictionary allows only two keys, <b><tt>fragments<\/tt><\/b> and <b><tt>calculation<\/tt><\/b>.<br \/>\nThe <b><tt>fragments<\/tt><\/b> is mandatory (no default value), while <b><tt>calculation<\/tt><\/b> is not mandatory (see below for the defaults).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>yaml<\/tt><\/b> file is generally organized as a hierarchical dictionary.<br \/>\nThe following paragraphs specify the syntax and functionality of all the relevant keys.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>fragments  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>fragments<\/tt><\/b> dictionary has to have as many items as there are fragments in the system (in this example case, two).<br \/>\nThe minimal number of fragments is one.<br \/>\nThe key for each fragment is an arbitrary label of the fragment (in this case, <b><tt>BD<\/tt><\/b> and <b><tt>BA<\/tt><\/b>).<br \/>\nNote that every fragment must have a unique label.<br \/>\nThe dictionary given for each fragment specifies everything related to this fragment in the context of the entire ECI calculation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>fragments: <label>  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For each fragment, the following entries must be present: <b><tt>atoms<\/tt><\/b>, <b><tt>aufbau_site_states<\/tt><\/b>, <b><tt>EHF<\/tt><\/b>, and <b><tt>SSC<\/tt><\/b>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>fragments: <label>: atoms  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>atoms<\/tt><\/b> entry specifies the atoms of the full system that belong to this fragment, and is mandatory.<br \/>\nIt can be given as a range (e.g., <b><tt>0-20<\/tt><\/b>), or a comma-delimited sequence (e.g., <b><tt>0,2,5,13<\/tt><\/b>), or a combination of the two (e.g., <b><tt>0-10,15,17,20-22<\/tt><\/b>).<br \/>\nThe indexation is with respect to the atom ordering given in the <b><tt>QM.in<\/tt><\/b> object of the S<span style=\"font-size:x-small\">HARC<\/span>-ECI interface, and starts with zero.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>fragments: <label>: aufbau_site_states  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>aufbau_site_states<\/tt><\/b> is an arbitrarily long list of aufbau site states of a fragment, and is mandatory.<br \/>\nEach aufbau site state in the list is given as a dictionary with keys: <b><tt>Z<\/tt><\/b> – the charge of the state, <b><tt>M<\/tt><\/b> – the multiplicity of the state, and <b><tt>N<\/tt><\/b> – the ordinal number of the state within a given charge-multiplicity manifold, starting from 1.<br \/>\nIn the example, <b><tt>BD<\/tt><\/b> has the first neutral singlet, <b><tt>{Z:0, M:1, N:1}<\/tt><\/b>, and the first cationic doublet, <b><tt>{Z:1, M:2, N:1}<\/tt><\/b>, site states as the aufbau ones, i.e., S<sub>0<\/sub> and D<sub>0<\/sub><sup>+<\/sup>.<br \/>\nOn the other hand, <b><tt>BA<\/tt><\/b> has S<sub>0<\/sub> and D<sub>0<\/sub><sup>−<\/sup>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>fragments: <label>: EHF  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>EHF<\/tt><\/b> dictionary defines the entire treatment of the fragment in the EHF procedure: <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>interface<\/tt><\/b> entry (in the example, both fragments use <b><tt>GAUSSIAN<\/tt><\/b>) specifies the S<span style=\"font-size:x-small\">HARC<\/span> interface to be used as an EHF child for this fragment, i.e., to perform the single-point calculation of the fragment and the RESP fit in each EHF cycle.<br \/>\nWe remind that an EHF child can be any interface that supports <b><tt>multipolar_fit<\/tt><\/b> and <b><tt>point_charges<\/tt><\/b> features.<br \/>\nSpecifying the interface is mandatory (no default).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>embedding_site_state<\/tt><\/b> specifies the state of the fragment that needs to be calculated in each EHF cycle and whose state density is to be used in the RESP fit.<br \/>\nUsers have to specify one embedding site state for each full-system charge.<br \/>\nIn the example, both <b><tt>BD<\/tt><\/b> and <b><tt>BA<\/tt><\/b> use the S<sub>0<\/sub> as the embedding site state for full-system charge <b><tt>0<\/tt><\/b>.<br \/>\nSince 0 is the only full-system charge specified, only the full-system states of this charge can be calculated with this template file.<br \/>\nIf one wants to obtain the EHF charges that will minimize the energy of the GS product(s), the embedding site states should be set to the sites’ ground states.<br \/>\nIf, however, one sets S<sub>0<\/sub> state of one fragment and S<sub>1<\/sub> state of the other fragment as the embedding site states, obtained charges will minimize the energy of the \\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>1<\/sub> LE product.<br \/>\nSuch a choice would effectively perform a “excitonic ∆SCF” instead of an EHF calculation, and the current implementation allows this.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>guess<\/tt><\/b> is boolean specifying whether the interface should try to read the RESP charges from a file with the path <b><tt><label>_embedding_Z<Z>\/QM.out<\/tt><\/b> and use them as the guess charges in EHF for the fragment.<br \/>\nIf set to <b><tt>true<\/tt><\/b>, but the reading of the file fails or if the file does not contain the RESP charges of the <b><tt>embedding_site_state<\/tt><\/b>, the interface will assign the guess embedding charge for each atom of the fragment to zero and will only raise warning.<br \/>\nIf it is set to <b><tt>false<\/tt><\/b>, the interface will not attempt to read any guess charges but will set them to zeros.<br \/>\nThe default value is <b><tt>true<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>write<\/tt><\/b> is boolean specifying whether the interface should write the final EHF charges of a fragment to a file with the path <b><tt><label>_embedding_Z<Z>\/QM.out<\/tt><\/b>.<br \/>\nThe default is <b><tt>true<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>tQ<\/tt><\/b> keyword sets the threshold for the convergence of the change of the atomic RESP charges of the fragment.<br \/>\nA fragment is considered converged in EHF if the RESP charges of all of its atoms are changing below <b><tt>tQ<\/tt><\/b>.<br \/>\nDefault is <b><tt>0.001<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>forced<\/tt><\/b> specifies whether the fragment is forced to converge.<br \/>\nNote that ECI can accommodate <i>arbitrary<\/i> point charges as embedding charges, so RESP charges of not every fragment have to be fully converged in order for the ECI calculation to give good results.<br \/>\nThe default is <b><tt>true<\/tt><\/b>.<br \/>\nUsing <b><tt>false<\/tt><\/b> can be used, e.g., to work with fixed embedding charges.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>max_cycles<\/tt><\/b> is the maximum number of EHF cycles in which the RESP charges will be updated for this fragment.<br \/>\nAfter this number of EHF cycles is exceeded, if <b><tt>forced<\/tt><\/b> is <b><tt>false<\/tt><\/b>, the interface will stop performing single-point calculations and RESP fits of this fragment in all following EHF cycles, and will simply keep its RESP charges to the last ones.<br \/>\nIf for any fragment <b><tt>forced<\/tt><\/b> is <b><tt>true<\/tt><\/b> and the <b><tt>max_cycles<\/tt><\/b> is exceeded before its convergence, the ECI interface will raise error.<br \/>\nThe default is <b><tt>20<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>fragments: <label>: SSC  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>SSC<\/tt><\/b> dictionary specifies the treatment of the fragment in the context of the site-state calculations:<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>interface<\/tt><\/b>, just like in <b><tt>EHF<\/tt><\/b>, specifies the S<span style=\"font-size:x-small\">HARC<\/span> interface that is used to calculate the site states of the fragment.<br \/>\nThese interface calls currently will have only <b><tt>h<\/tt><\/b>, <b><tt>density_matrices<\/tt><\/b> and <b><tt>mole<\/tt><\/b> requests, so eligible interfaces here are any that accommodate those and <b><tt>point_charges<\/tt><\/b> as features.<br \/>\nIt is mandatory (no default).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>data<\/tt><\/b> is a string specifying whether the interface should write the site-state data to or\/and read the site-state data from <b><tt><label>_z<z>_Z<Z>\/QM.out<\/tt><\/b> file.<br \/>\nIf the value contains <b><tt>r<\/tt><\/b>, the interface will attempt to read the site-state data from the file, and if this fails, unlike in the EHF’s <b><tt>guess<\/tt><\/b>, the interface will raise an error.<br \/>\nIf it succeeds, the interface will not calculate the site states for the fragment but will use the read data.<br \/>\nIf the value does not contain <b><tt>r<\/tt><\/b>, <b><tt>SHARC_ECI.py<\/tt><\/b> will call the <b><tt>interface<\/tt><\/b> to perform the SSC for the fragment.<br \/>\nIndependently, if the value contains <b><tt>w<\/tt><\/b>, interface will write (either read or calculated) data to <b><tt><label>_z<z>_Z<Z>\/QM.out<\/tt><\/b> file.<br \/>\nThis key can be useful to calculate the site states in the first call of the interface and dump the data to QM.out files (with <b><tt>w<\/tt><\/b> given to each fragment), and then only read them in any future call of <b><tt>SHARC_ECI.py<\/tt><\/b> (with <b><tt>r<\/tt><\/b> given to each fragment) while, e.g., benchmarking anything specified in <b><tt>calculation<\/tt><\/b> dictionary (see below, e.g., ECI expansion, different thresholds, auxiliary basis set for RI, etc.).<br \/>\nAlso, it can be useful if one wants to add a few more site states to a single fragment (so one must repeat the SSC for that fragment) but use already calculated site state set of other fragments.<br \/>\nThe default is <b><tt>w<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>states<\/tt><\/b> specifies which site states for the fragment need to be calculated.<br \/>\nIts keys are the charges of the fragment, while the values are the lists of the number of the site states per multiplicity, just like the <b><tt>states<\/tt><\/b> entry in a <b><tt>QM.in<\/tt><\/b> file or in the <b><tt>input<\/tt><\/b> file of the SHARC drivers.<br \/>\nIn the example above, <b><tt>BD<\/tt><\/b> will have only the first two singlet (S<sub>0<\/sub> and S<sub>1<\/sub>) and the first triplet (T<sub>1<\/sub>) site states of the charge <b><tt>0<\/tt><\/b>, and D<sub>0<\/sub> site state of the charge <b><tt>1<\/tt><\/b>.<br \/>\nOn the other hand, <b><tt>BA<\/tt><\/b> will have S<sub>0<\/sub>, S<sub>1<\/sub> and T<sub>1<\/sub> site states of the charge <b><tt>0<\/tt><\/b> and D<sub>0<\/sub> site state of the charge <b><tt>-1<\/tt><\/b>.<br \/>\nNote that all <b><tt>aufbau_site_states<\/tt><\/b> of a fragment have to be included in the <b><tt>states<\/tt><\/b>, or an error will be raised.<br \/>\nThis, however, does not hold for the <b><tt>embedding_site_states<\/tt><\/b> of the fragment, although in practice will probably be the case.<br \/>\nCurrently it is not possible to skip some states within a charge-multiplicy manifold, e.g., one cannot have neutral S<sub>0<\/sub>, S<sub>1<\/sub> and S<sub>3<\/sub> site states on a fragment (skipping S<sub>2<\/sub>).<br \/>\nAlso, note that the given numbers of site states per charge-multiplicity manifold of a fragment are used identically for all full-system charges.<br \/>\nHypothetically, one could use a completely different set of site states for each different full-system charge, but then these ECI calculations would not be done on an equal footing.<br \/>\n(Using different site states for different full-system charges would be similar to using different basis sets for a neutral molecule and its cation; here one sees the analogy between site states in ECI and orbitals in CI).<br \/>\nHowever, also note that, just like neutral and cationic molecular orbitals will be different functions after respective HF calculations, the site states of a fragment also might be physically different states for different full-system charges, due to the different <b><tt>embedding_site_states<\/tt><\/b> of other fragments for different full-system charges in the respective EHF calculations.<br \/>\nIt is mandatory (no default).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>calculation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>calculation<\/tt><\/b> dictionary specifies all options that are not specific to related to specific fragments in the ECI calculation.<br \/>\nIt has keys <b><tt>tO<\/tt><\/b>, <b><tt>RI<\/tt><\/b>, <b><tt>excitonic_basis<\/tt><\/b> and <b><tt>active_integrals<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>calculation: tO  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>tO<\/tt><\/b> is the threshold for the inter-site overlap integrals, designed to automatically track the site states that lead to the breakdown of SOA.<br \/>\nFor the details see Chapter 3.2.2 in Ref. .<br \/>\nDefault is <b><tt>0.95<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>calculation: RI  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>RI<\/tt><\/b> entry specifies the setup of using the RI approximation in the calculation of the ECI Hamiltonian matrix:<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>active<\/tt><\/b> entry is a boolean specifying whether the RI is used or not.<br \/>\nThe theory of RI-ECI is presented in Ref. .<br \/>\nDefault is <b><tt>true<\/tt><\/b>, and we strongly encourage using the RI, since the algorithm without it is implemented only as a proof of concept and is very memory demanding already for medium-size fragments. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>Jauxbasis<\/tt><\/b> and <b><tt>Kauxbasis<\/tt><\/b> entries specify the auxiliary basis sets used in the RI-ECI calculation of the J and K terms.<br \/>\nThe basis set has to be available in <b><tt>PySCF<\/tt><\/b> package (in particular, in the module <a href=\"https:\/\/pyscf.org\/\\_modules\/pyscf\/gto\/basis.html\"><tt>https:\/\/pyscf.org\/\\_modules\/pyscf\/gto\/basis.html<\/tt><\/a>).<br \/>\nDefault for both is <b><tt>augccpvdzri<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>tS<\/tt><\/b> and <b><tt>tC<\/tt><\/b> entries are the thresholds for the prescreening of the inter-site three-centric two-electron exchange integrals.<br \/>\nCheck Ref.  for details.<br \/>\nDefault for <b><tt>tS<\/tt><\/b> is <b><tt>0.0001<\/tt><\/b> and for <b><tt>tC<\/tt><\/b> is <b><tt>0.001<\/tt><\/b>.<br \/>\nIn our experience, the default values are sufficient to obtain accurate state energies.<br \/>\nIn systems with weak interactions, and especially if the system is symmetric and the full-system states should reflect this symmetry, we recommend to significantly tighten both thresholds.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>chunksize<\/tt><\/b> is an integer specifying the number of partial densities of the first fragment in a pair that will be contracted with the Cholesky factors simultaneously.<br \/>\nThis usually defines the peak in the memory usage in the building of the ECI Hamiltonian.<br \/>\nIn particular, it controls the size of the biggest intermediate, that is of the size N<sup>F<\/sup><sub><span class=\"roman\">part<\/span><\/sub>N<sup>F<\/sup><sub><span class=\"roman\">AO<\/span><\/sub>N<sup>G<\/sup><sub><span class=\"roman\">AO<\/span><\/sub>N<sup>FG<\/sup><sub><span class=\"roman\">aux<\/span><\/sub> (see discussion after Equation (8) in Ref. ) by splitting the first dimension of the tensor in chunks of the <b><tt>chunksize<\/tt><\/b> size.<br \/>\nFor example, if one has two identical fragments, each having N<sup>F<\/sup><sub><span class=\"roman\">AO<\/span><\/sub> = N<sup>G<\/sup><sub><span class=\"roman\">AO<\/span><\/sub>=300 while the auxiliary basis set of the dimer has N<sup>FG<\/sup><sub><span class=\"roman\">aux<\/span><\/sub>=3000, the tensor takes up 2.16 GB per partial density.<br \/>\nIf one has around 20 GB at disposal, but has 30 different partial densities on the fragment F, not the entire tensor can be stored at once, as it would weight 64.8 GB.<br \/>\nIn this case, one can set <b><tt>chunksize=8<\/tt><\/b> and 8 densities will be contracted at time, taking 17.28 GB.<br \/>\nThe entire contraction is then done in 4 chunks, with the first three chunks having 8 densities and the last one having 6 remaining densities (8×3 + 6 = 30).<br \/>\nSetting <b><tt>chunksize=-1<\/tt><\/b> corresponds to performing the contraction in one chunk (in this example being equivalent to <b><tt>chunksize=30<\/tt><\/b>) and is the default.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>calculation: excitonic_basis  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>excitonic_basis<\/tt><\/b> dictionary specifies what excitonic basis is going to be build from the calculated site states.<br \/>\nCurrently, it only has a single key, <b><tt>ECI<\/tt><\/b>.<br \/>\nThe entire <b><tt>excitonic_basis<\/tt><\/b> dictionary can be omitted, in which case it defaults to the default of its key <b><tt>ECI<\/tt><\/b> (see below).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>calculation: excitonic_basis: ECI  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>ECI<\/tt><\/b> is a dictionary that specifies the ECI basis that is going to be build.<br \/>\nIts keys are integers starting from <b><tt>0<\/tt><\/b> to the number of fragments.<br \/>\nThese keys represent the antisymmetrized products in the sense of their excitation rank (<b><tt>0<\/tt><\/b> – the aufbau product(s), <b><tt>1<\/tt><\/b> – LEs, <b><tt>2<\/tt><\/b> – DLEs, etc.).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>0<\/tt><\/b> entry can have only values <b><tt>true<\/tt><\/b> and <b><tt>false<\/tt><\/b>, specifying whether the aufbau product(s) will be present in the final ECI basis.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Each other key <b><tt>F<\/tt><\/b> > <b><tt>0<\/tt><\/b> can have values <b><tt>all<\/tt><\/b>, <b><tt>false<\/tt><\/b>, or a list of <b><tt>F<\/tt><\/b>-membered subsets of fragment labels.<br \/>\nIf <b><tt>all<\/tt><\/b>, then all products of the rank <b><tt>F<\/tt><\/b> will be generated.<br \/>\nIf <b><tt>false<\/tt><\/b>, no product of the rank <b><tt>F<\/tt><\/b> will be generated.<br \/>\nIf a list of fragment subsets is given, only <b><tt>F<\/tt><\/b>-ranked products where the excitations are found on the fragments from any of the subsets will be generated.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For example, if <b><tt>1: [[BD]]<\/tt><\/b> is given in this example, only LEs with the excitation on <b><tt>BD<\/tt><\/b> will be generated (no LEs with the excitation on <b><tt>BA<\/tt><\/b>).<br \/>\nFor this system, <b><tt>1: [[BD], [BA]<\/tt><\/b> is equivalent to <b><tt>1: all<\/tt><\/b>.<br \/>\nThe highest excitation rank for this system is <b><tt>2<\/tt><\/b>, since there are two fragments.<br \/>\nOnly possible values here are <b><tt>2: all<\/tt><\/b>, <b><tt>2: [[BD, BA]]<\/tt><\/b>, and <b><tt>2: false<\/tt><\/b>, where the first two are equivalent.<br \/>\nNote that the ordering of the fragments within a subset is irrelevant (e.g., <b><tt>[BD, BA]<\/tt><\/b> and <b><tt>[BA,BD]<\/tt><\/b> are the same).<br \/>\nIf any excitation rank is not specified within the <b><tt>ECI<\/tt><\/b> dictionary, the defaults are <b><tt>0: true<\/tt><\/b>, <b><tt>1: all<\/tt><\/b>, and <b><tt>F: false<\/tt><\/b> for <b><tt>F<\/tt><\/b> > <b><tt>1<\/tt><\/b>, which defines the ECIS expansion.<br \/>\nIf the entire <b><tt>ECI<\/tt><\/b> is not specified, it defaults to a dictionary with default values for each key (i.e., again to the ECIS).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>calculation: active_integrals  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>active_integrals<\/tt><\/b> dictionary specifies the type of the two-site integrals that will be computed when building the ECI Hamiltonian.<br \/>\nThere are two classes of integrals: Coulomb and exchange two-site integrals, marked with the entries <b><tt>J<\/tt><\/b> and <b><tt>K<\/tt><\/b>.<br \/>\nBoth of them are given as a dictionary with tuples <b><tt>'(0,0)'<\/tt><\/b>, <b><tt>'(0,1)'<\/tt><\/b> and <b><tt>'(0,2)'<\/tt><\/b> as keys.<br \/>\nAs can be seen, the first entry in each tuple is exclusively <b><tt>0<\/tt><\/b>, and is a placeholder for future development (considering charge transfer couplings).<br \/>\nThe second entry can be <b><tt>0<\/tt><\/b>, <b><tt>1<\/tt><\/b> or <b><tt>2<\/tt><\/b>.<br \/>\nThe tuple <b><tt>'(0,0)'<\/tt><\/b> symbolizes the two-site integrals contributing to the matrix elements with zero differences in the site states (fragment-wise), i.e., the diagonal matrix elements.<br \/>\nThese integrals are always (Coulomb or exchange) integrals between two state densities.<br \/>\nThe tuple <b><tt>'(0,1)'<\/tt><\/b> symbolizes the two-site integrals contributing to the matrix elements with one site-state difference, such as GS-LE couplings, same-site LE-LE couplings, a subset of LE-DLE couplings, a subset of DLE-DLE couplings, etc.<br \/>\nThese integrals are always evaluated between one state density and one transition density.<br \/>\nSimilarly, the tuple <b><tt>'(0,2)'<\/tt><\/b> symbolizes the two-site integrals contributing to the matrix elements with two site-state differences, such as GS-DLE couplings, different-site LE-LE couplings, a subset of LE-DLE couplings, a subset of DLE-DLE couplings, etc.<br \/>\nThese integrals are always computed between two transition densities.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For each type of the integrals, one can give values <b><tt>all<\/tt><\/b>, <b><tt>false<\/tt><\/b> or a list of fragment pairs, where <b><tt>all<\/tt><\/b>\/<b><tt>false<\/tt><\/b> specifies that all\/no integrals of the kind will be calculated.<br \/>\nIf the list of the fragment pairs is given (like in the example, e.g., <b><tt>'(0,1)': [ [BD,BA] ]<\/tt><\/b>), only the integrals between the fragments in the pairs will be calculated.<br \/>\nThis is useful if the user knows that a certain pairs of fragments are too far away so that the interfragment exchange can be neglected.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The default for each type of the integrals is <b><tt>all<\/tt><\/b>.<br \/>\nOne can also specify <b><tt>J: all<\/tt><\/b> immediately, which is equivalent to <b><tt>J: '(0,0)': all, '(0,1)': all, '(0,2)': all<\/tt><\/b>.<br \/>\nThe analogous stands for <b><tt>J: false<\/tt><\/b>, and also applies to <b><tt>K<\/tt><\/b> equally.<br \/>\nIf omitted, <b><tt>J: all<\/tt><\/b> and <b><tt>K: all<\/tt><\/b> are defaults.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Also, <b><tt>all<\/tt><\/b> or <b><tt>false<\/tt><\/b> can be immediately given to <b><tt>active_integrals<\/tt><\/b> entry.<br \/>\nThe first is equivalent to <b><tt>J: all, K: all<\/tt><\/b> and specifies that all two-site integrals (of any type and kind) required by ECI theory should be computed.<br \/>\nThe later is equivalent to <b><tt>J: false, K: false<\/tt><\/b> and specifies that no two-site integral will be calculated.<br \/>\nThis gives the non-interacting picture, i.e., the full-system energies will be only the sums of the site energies.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>As a special example, the Frenkel exciton model that does not include two-site exchange, the interaction energy on the diagonal matrix elements, as well as the same-site LE-LE couplings, is specified by<br \/>\n<span class=\"small\"><\/p>\n<pre>\n    active_integrals: \n        J: \n            '(0,0)': false\n            '(0,1)': false\n            '(0,2)': all\n        K: false\n<\/pre>\n<p> <\/span><\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.25.4\"><\/a><\/p>\n<h3>\n6.25.4  Resources file: <b><tt>ECI.resources<\/tt><\/b><\/h3>\n<p><a id=\"sec:int:eci:resource\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Resources file of ECI interface is a <b><tt>yaml<\/tt><\/b> file having keys: <b><tt>scratchdir<\/tt><\/b>, <b><tt>ncpu<\/tt><\/b> and <b><tt>sitejobs<\/tt><\/b>.<br \/>\n<span class=\"small\"><\/p>\n<pre>\n---\nncpu: 40\nscratchdir: SCRATCH\nsitejobs: [ [BA,0], [BA,-1], [BD,0], [BD,1] ]\n<\/pre>\n<p> <\/span><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Inside specified <b><tt>scratchdir<\/tt><\/b>, the interface will create the <b><tt>scratchdir<\/tt><\/b>s of all its EHF and SSC children, with the hardcoded names <b><tt><scratchdir>\/<label>_embedding_Z<Z><\/tt><\/b> and <b><tt><scratchdir>\/<label>_z<z>_Z<Z><\/tt><\/b>, i.e. the <b><tt>scratchdir<\/tt><\/b>s given in children’s resources files will be ignored.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>On the other hand, the ECI interface does not interfere with the <b><tt>ncpu<\/tt><\/b> value of its children, i.e., the user has to specify these for both ECI and each child’s interface in a consistent and efficient way.<br \/>\nIn the <b><tt>BD-BA<\/tt><\/b> example, 40 cores are given to <b><tt>SHARC_ECI.py<\/tt><\/b> and, since we have two equally-sized fragments <b><tt>BD<\/tt><\/b> and <b><tt>BA<\/tt><\/b> treated with the same level of theory, we set <b><tt>ncpu: 20<\/tt><\/b> in both <b><tt>B*_embedding_Z0\/GAUSSIAN.resources<\/tt><\/b>, so that the two EHF children are launched in parallel.<br \/>\nRegarding the SSC children in the example, <b><tt>BD<\/tt><\/b> and <b><tt>BA<\/tt><\/b> both have S<sub>0<\/sub>, S<sub>1<\/sub>, T<sub>1<\/sub> neutral site states, and D<sub>0<\/sub><sup>+<\/sup> and D<sub>0<\/sub><sup>−<\/sup> site states respectively.<br \/>\nAssuming that the neutral calculation on a fragment is roughly four times more expensive than the calculation of D<sub>0<\/sub><sup>+<\/sup>, i.e., D<sub>0<\/sub><sup>−<\/sup>, we give 16 cores to each <b><tt>BD_z0_Z0<\/tt><\/b> and <b><tt>BA_z0_Z0<\/tt><\/b>, while <b><tt>BD_z1_Z0<\/tt><\/b> and <b><tt>BA_z-1_Z0<\/tt><\/b> are given 4 cores each.<br \/>\nIn this way, all four SSC children will be launched in parallel and will finish approximately in the same time.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>sitejobs<\/tt><\/b> is a list of SSC children defining the order they will be launched during SSC.<br \/>\nUsing this keyword and <b><tt>ncpu<\/tt><\/b> of individual children, users can make their own scheduling of the SSC.<br \/>\nIn the upper example, any order of SSC children given in <b><tt>sitejobs<\/tt><\/b> would result in launching all four children simultaneously because four <b><tt>ncpu<\/tt><\/b> given in respective <b><tt>GAUSSIAN.resources<\/tt><\/b> sum up exactly to 40.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Let us emphasize that the ECI interface itself does not have any keyword defining the limit of its overall memory usage.<br \/>\nIn other words, it will try to allocate as much memory as it needs.<br \/>\nNevertheless, as discussed in Section <a href=\"#sec:int:eci:template\">6.25.3<\/a>, user can control the probable memory peak of the ECI calculation with <b><tt>calculation: RI: chunksize<\/tt><\/b> keyword.<br \/>\nAlso, note that the RESP fit in ab-initio interfaces (like <b><tt>SHARC_GAUSSIAN.py<\/tt><\/b>) in EHF can be very memory demanding, so for a larger number of fragments (or fragments with many basis functions) one will have to launch not all EHF children at the same time, but rather in chunks, giving more CPUs to each child.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.25.5\"><\/a><\/p>\n<h3>\n6.25.5  Standard output of SHARC_ECI.py<\/h3>\n<p><a id=\"sec:int:eci:stdout\"><br \/>\n<\/a><br \/>\nApart from the standard output printed by corresponding base classes (<b><tt>SHARC_INTERFACE.py<\/tt><\/b> and <b><tt>SHARC_HYBRID.py<\/tt><\/b>), <b><tt>SHARC_ECI.py<\/tt><\/b> prints its own formatted output as it goes through its run function, to enable user to follow the progress.<br \/>\nWhile the output printed during EHF and SSC is pretty simple and understandable by itself (see <b><tt>$SHARC\/..\/examples\/SHARC_ECI\/QM.log<\/tt><\/b>), the loggings produced during the excitonic part of an ECI calculation are commented and explained here.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>This part of loggings starts with a simple title and the basic self-explanatory infos of the ECI calculation:<br \/>\n<span class=\"small\"><\/p>\n<pre>\n ================== Excitonic part of the ECI calculation ==================\n    BASIC INFOS OF THE CALCULATION:\n       The number of CPUs for NumPY and PySCF set up to 40\n       Multiplicities to be calculated: [1, 3]\n       ECI level:\n          GS: True\n          LE: [[BD], [BA]]\n         DLE: [[BD, BA]]\n<\/pre>\n<p> <\/span><br \/>\nThis is followed by a simple info about the sites and the site states:<br \/>\n<span class=\"scriptsize\"><\/p>\n<pre>\n    BASIC INFOS OF THE SITES:\n       Site: BD\n                  Atoms:       N         N         C         C         C         C         C         C         C         C         C     ...\n           RESP charges:   -0.05455  -0.04286  -0.02586  -0.24813  -0.16312   0.05665  -0.11178   0.03569  -0.16726  -0.23580  -0.02365  \n            Site states:       S0_(0)^(0)      S1_(0)^(0)     T1_(-1)^(0)      T1_(0)^(0)     T1_(+1)^(0)  D0_(-1\/2)^(1+)  D0_(+1\/2)^(1+)\n          Site energies:    -680.54580417   -680.41734691   -680.48556468   -680.48556468   -680.48556468   -680.26156327   -680.26156327\n            Num. of el.:      98.00000001     98.00000001     97.99999998     97.99999998     97.99999998     97.00000000     97.00000000\n                  Alpha:      49.00000001     49.00000001     47.99999998     48.99999999     50.00000043     49.00000000     49.00000000\n                   Beta:      49.00000001     49.00000001     50.00000000     48.99999999     48.00000041     48.00000000     48.00000000\n       Site: BA\n                  Atoms:       N         N         C         C         C         C         C         C         C         C         C      ...\n           RESP charges:    0.02019  -0.01494  -0.05860  -0.22107  -0.17489   0.00786  -0.08828   0.02863  -0.16114  -0.23276  -0.01928 \n            Site states:       S0_(0)^(0)      S1_(0)^(0)     T1_(-1)^(0)      T1_(0)^(0)     T1_(+1)^(0)  D0_(-1\/2)^(1-)  D0_(+1\/2)^(1-)\n          Site energies:    -680.54624350   -680.41830441   -680.48648910   -680.48648910   -680.48648910   -680.61761335   -680.61761335\n            Num. of el.:      97.99999999     97.99999999     97.99999999     97.99999999     97.99999999     98.99999999     98.99999999\n                  Alpha:      48.99999999     49.00000000     47.99999998     48.99999999     50.00000068     49.99999999     49.99999999\n                   Beta:      48.99999999     49.00000000     50.00000001     48.99999999     48.00000066     48.99999999     48.99999999\n<\/pre>\n<p> <\/span><br \/>\nHere, for each site, the first table represents the atomic symbols and the corresponding embedding charges that were obtained from the EHF.<br \/>\nThe second table shows the site states, their energies (as obtained from the SSC children) and the number of electrons (total, alpha and beta), calculated from the state densities obtained from the children.<br \/>\nThis is convenient to check, to see whether the generation of the density matrices and the rotation of the basis set to the <b><tt>PySCF<\/tt><\/b> convention went well.<br \/>\nNote that, when using <b><tt>SHARC_GAUSSIAN.py<\/tt><\/b> as an SSC child, to obtain correct number of alpha and beta electrons for the triplet site states one has to specify <b><tt>wfthres<\/tt><\/b> greater than 1 in the <b><tt>GAUSSIAN.resources<\/tt><\/b> of the child.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The symbols of the site states contain letter(s) for multiplicity (S, D, T, Q, and then corresponding Roman numbers V, VI, VII,…), followed by an ordinal number of the state (<b><tt>N-1<\/tt><\/b> for the ground-state multiplicity and <b><tt>N<\/tt><\/b> for other multiplicities), followed by the M<sub>S<\/sub> value in the subscript and the site charge in the superscript.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Then follows the section dedicated to the generation of the excitonic basis:<br \/>\n<span class=\"footnotesize\"><\/p>\n<pre>\n    CONSTRUCTION OF THE ECI BASIS:\n       Aufbau ESDs ( # = 5 ):\n          [ BD^(0) : S0_(0) | BA^(0) : S0_(0) ]\n          [ BD^(1+) : D0_(-1\/2) | BA^(1-) : D0_(-1\/2) ]\n          [ BD^(1+) : D0_(-1\/2) | BA^(1-) : D0_(+1\/2) ]\n          [ BD^(1+) : D0_(+1\/2) | BA^(1-) : D0_(-1\/2) ]\n          [ BD^(1+) : D0_(+1\/2) | BA^(1-) : D0_(+1\/2) ]\n       Number of aufbau and excited ESDs before overlap criterion: 29\n       Overlap criterion:\n          (Fragment,charge) pair: (BD,0), (BA,0):\n             The best complement overlap: 1 - < T1_(+1) | S0_(0) > = 0.9946171197256403\n             No site-state pair need to be expelled!\n          (Fragment,charge) pair: (BD,0), (BA,-1):\n             The best complement overlap: 1 - < S0_(0) | D0_(-1\/2) > = 0.9942053512401284\n             No site-state pair need to be expelled!\n          (Fragment,charge) pair: (BD,1), (BA,0):\n             The best complement overlap: 1 - < D0_(-1\/2) | S0_(0) > = 0.9955291827037946\n             No site-state pair need to be expelled!\n          (Fragment,charge) pair: (BD,1), (BA,-1):\n             The best complement overlap: 1 - < D0_(-1\/2) | D0_(-1\/2) > = 0.9951728369089206\n             No site-state pair need to be expelled!\n       Number of aufbau and excited ESDs after overlap criterion: 29\n<\/pre>\n<p> <\/span><br \/>\nFirst, the interface prints the list of all aufbau ESDs having correct full-system charge.<br \/>\nEach ESD is represented as an N<sub><span class=\"roman\">frag<\/span><\/sub>-long list of the site states, separated by vertical bars (<b><tt> - <\/tt><\/b>).<br \/>\nEach site state is represented by fragment label and its charge in the superscript (e.g., <b><tt>BA^(1-)<\/tt><\/b>), separated by <b><tt>:<\/tt><\/b> from the state symbol without the charge (e.g., <b><tt>D0_(+1\/2)<\/tt><\/b>).<br \/>\nThen, the interface construct all excited ESDs (LEs, DLEs,…) and reports the total number of ESDs.<br \/>\nThen it applies the overlap criterion for each site pair and eventually expels some ESDs from the ECI basis.<br \/>\nFor each (fragment, charge) pair, the max. complement overlap of the site states is printed, as well as the site-state pairs for which relative complement overlap is lower than <b><tt>tO*maxO<\/tt><\/b> (in the example, there were no site-state pairs violating the SOA).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> Further, the results of the spin adaptation are printed:<br \/>\n<span class=\"footnotesize\"><\/p>\n<pre>\n       Spin adaptation for multiplicity 1:\n          Found 13 ESDs with MS = 0.0\n          Constructed 6 ECSFs spanned by 9 ESDs:\n             ( 0 ) =\n               1.000000[ BD^(0) : S0_(0) | BA^(0) : S0_(0) ]\n             ( BD^(1+) : D0 | BA^(1-) : D0 ) =\n              -0.707107[ BD^(1+) : D0_(-1\/2) | BA^(1-) : D0_(+1\/2) ]\n               0.707107[ BD^(1+) : D0_(+1\/2) | BA^(1-) : D0_(-1\/2) ]\n             ( BD^(0) : S1 ) =\n               1.000000[ BD^(0) : S1_(0) | BA^(0) : S0_(0) ]\n             ( BA^(0) : S1 ) =\n               1.000000[ BD^(0) : S0_(0) | BA^(0) : S1_(0) ]\n             ( BD^(0) : S1 | BA^(0) : S1 ) =\n               1.000000[ BD^(0) : S1_(0) | BA^(0) : S1_(0) ]\n             ( BD^(0) : T1 | BA^(0) : T1 ) =\n               0.577350[ BD^(0) : T1_(-1) | BA^(0) : T1_(+1) ]\n              -0.577350[ BD^(0) : T1_(0) | BA^(0) : T1_(0) ]\n               0.577350[ BD^(0) : T1_(+1) | BA^(0) : T1_(-1) ]\n       Spin adaptation for multiplicity 3:\n          Found 7 ESDs with MS = 1.0\n          Constructed 6 ECSFs spanned by 7 ESDs:\n             ( BD^(1+) : D0 | BA^(1-) : D0 ) =\n               1.000000[ BD^(1+) : D0_(+1\/2) | BA^(1-) : D0_(+1\/2) ]\n             ( BD^(0) : T1 ) =\n               1.000000[ BD^(0) : T1_(+1) | BA^(0) : S0_(0) ]\n             ( BA^(0) : T1 ) =\n               1.000000[ BD^(0) : S0_(0) | BA^(0) : T1_(+1) ]\n             ( BD^(0) : S1 | BA^(0) : T1 ) =\n               1.000000[ BD^(0) : S1_(0) | BA^(0) : T1_(+1) ]\n             ( BD^(0) : T1 | BA^(0) : T1 ) =\n              -0.707107[ BD^(0) : T1_(0) | BA^(0) : T1_(+1) ]\n               0.707107[ BD^(0) : T1_(+1) | BA^(0) : T1_(0) ]\n             ( BD^(0) : T1 | BA^(0) : S1 ) =\n               1.000000[ BD^(0) : T1_(+1) | BA^(0) : S1_(0) ]\n       Time spent in constructing the ECI basis (sec) = 0.261\n<\/pre>\n<p> <\/span><br \/>\nFor each multiplicity, the number of ECSFs constructed by a number of ESDs is reported.<br \/>\nThen each ECSF is printed in the basis of ESDs.<br \/>\nThe symbol of an ECSF is a tuple of the site states separated by <b><tt> - <\/tt><\/b>. Each site state has the framgnet label and its charge, separated by <b><tt>:<\/tt><\/b> from the label of the state without M<sub>S<\/sub>, symbolizing the the ECSFs are not necessarily the eigenstates of the site-specific <span class=\"overacc1\">∧<\/span>S<sub>z<\/sub> operator (but are the eigenstates of the full-system <span class=\"overacc1\">∧<\/span>S<sub>z<\/sub> and <span class=\"overacc1\">∧<\/span>S<sup>2<\/sup>).<br \/>\nAs can be seen, the symbols of ECSFs do not contain labels all site states, but only of those that differ from the first state given in the <b><tt>aufbau_site_state<\/tt><\/b> list of each fragment.<br \/>\nIn <b><tt>BD-BA<\/tt><\/b> example, both fragments have S<sub>0<\/sub> site state as the first aufbau one (second aufbau site states are D<sub>0<\/sub><sup>+<\/sup> and D<sub>0<\/sub><sup>−<\/sup> respectively), hence the symbol of the ECSF corresponding to <sup>1<\/sup>\\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub> should not have any site state printed.<br \/>\nFor this reason, this ECSF is labeled as <b><tt>(0)<\/tt><\/b>.<br \/>\nThe ECSFs corresponding to LEs will then have a single site state printed, DLEs, two site states, etc.<br \/>\nThe CT products (with respect to the site charges of the first aufbau site states) then have both donor and acceptor site state emphasized in the symbol of ECSF (e.g., <b><tt>( BD^(1+) : D0 - BA^(1-) : D0 )<\/tt><\/b> in the example).<br \/>\nIn this example, the printed ECSFs are GS product <sup>1<\/sup>\\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub>, <sup>1<\/sup>\\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup> CT product, <sup>1<\/sup>\\ket<span class=\"roman\">S<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub> LE on <b><tt>BD<\/tt><\/b>, <sup>1<\/sup>\\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>1<\/sub> LE on <b><tt>BA<\/tt><\/b>, and <sup>1<\/sup>\\ket<span class=\"roman\">S<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>1<\/sub> and <sup>1<\/sup>\\ket<span class=\"roman\">T<\/span><sub>1<\/sub><span class=\"roman\">T<\/span><sub>1<\/sub> DLEs, all spin-adapted for the singlet full-system spin.<br \/>\nTriplet ECSFs are <sup>3<\/sup>\\ket<span class=\"roman\">D<\/span><sub>0<\/sub><sup>+<\/sup><span class=\"roman\">D<\/span><sub>0<\/sub><sup>−<\/sup>, <sup>3<\/sup>\\ket<span class=\"roman\">T<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub>, <sup>3<\/sup>\\ket<span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">T<\/span><sub>1<\/sub>, <sup>3<\/sup>\\ket<span class=\"roman\">T<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>1<\/sub>, <sup>3<\/sup>\\ket<span class=\"roman\">S<\/span><sub>1<\/sub><span class=\"roman\">T<\/span><sub>1<\/sub> and <sup>3<\/sup>\\ket<span class=\"roman\">T<\/span><sub>1<\/sub><span class=\"roman\">T<\/span><sub>1<\/sub>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> Further, interface calculates the ECI Hamiltonian in the constructed excitonic basis, for each multiplicity simultaneously, by looping over the fragments\/fragment pairs.<br \/>\n<span class=\"scriptsize\"><\/p>\n<pre>\n    CONSTRUCTION OF THE ECI HAMILTONIAN:\n       Generating the dictionary of ECI integrals took 0.002 sec.\n       Calculating ECI V-integrals...\n           Site: BD, Nuclei: BA\n              Took 0.02 sec.\n           Site: BA, Nuclei: BD\n              Took 0.033 sec.\n        Calculating ECI J-integrals...\n          Site 1: BD, Site 2: BA\n             Calculation of P-matrix of dim. (2368, 2368) took 0.411 sec.\n             Calculation of L-tensors of dims. (231, 231, 2368) and (231, 231, 2368) took 0.288 sec.\n             First contraction took 0.739 sec.\n             Second contraction took 0.001 sec.\n             Distribution took 0.0 sec.\n       Calculating ECI K-integrals...\n          Site 1: BD, Site 2: BA\n             Number of atoms per fragment: 18\/21 and 14\/21\n             Number of shells per fragment: 59\/105 and 56\/105\n             Number of AOs per fragment: 127\/231 and 128\/231\n             Calculation of P-matrix of dim. (2368, 2368) and its Cholesky decomposition took 0.07 sec.\n             Calculation of L-tensor of dim. (2368, 127, 128) took 0.045 sec.\n             Calculation of Cholesky factors took 0.224 sec.\n             Prescreening took 0.213 sec.\n             Chunk 1 ( contracting 34 densities of the first fragment )...\n             Done in 0.515 sec.\n       Summing up J- and K-matrices, adding site energies and VNN to the diagonal, and rotating J-, K-, and H-matrices to the basis of ECSFs...\n       Total inter-fragment nuclear-nuclear repulsion (au) = 708.5748067802617\n       H-, J-, K-matrices for multiplicity 1 in the basis of ECSFs:\n          H-matrix:\n             -1361.0908146054         0.0000000000         0.0002633611        -0.0000163705        -0.0021649706         0.0000000055\n                 0.0000000000     -1360.9466671910         0.0000000000         0.0000000000         0.0000000000         0.0000000000\n                 0.0002633611         0.0000000000     -1360.9624319791        -0.0021647097        -0.0004058577        -0.0000000000\n                -0.0000163705         0.0000000000        -0.0021647097     -1360.9628867326         0.0002815142        -0.0000000000\n                -0.0021649706         0.0000000000        -0.0004058577         0.0002815142     -1360.8344815781         0.0000000038\n                 0.0000000055         0.0000000000        -0.0000000000        -0.0000000000         0.0000000038     -1360.9708608588\n          J-matrix:\n                 0.0038436955         0.0000000000         0.0000963597        -0.0000245797        -0.0021640119         0.0000000000\n                 0.0000000000        -0.0652297716         0.0000000000         0.0000000000         0.0000000000         0.0000000000\n                 0.0000963597         0.0000000000         0.0038124367        -0.0021640119        -0.0004141173         0.0000000000\n                -0.0000245797         0.0000000000        -0.0021640119         0.0038415313         0.0001141418         0.0000000000\n                -0.0021640119         0.0000000000        -0.0004141173         0.0001141418         0.0038328724         0.0000000000\n                 0.0000000000         0.0000000000         0.0000000000         0.0000000000         0.0000000000         0.0038149941\n          K-matrix:\n                 0.0026106372         0.0000000000        -0.0001670014        -0.0000082092         0.0000009587        -0.0000000055\n                 0.0000000000         0.0022608037         0.0000000000         0.0000000000         0.0000000000         0.0000000000\n                -0.0001670014         0.0000000000         0.0026540078         0.0000006978        -0.0000082596         0.0000000000\n                -0.0000082092         0.0000000000         0.0000006978         0.0026196904        -0.0001673724         0.0000000000\n                 0.0000009587         0.0000000000        -0.0000082596        -0.0001673724         0.0026631326        -0.0000000038\n                -0.0000000055         0.0000000000         0.0000000000         0.0000000000        -0.0000000038         0.0026220760\n       H-, J-, K-matrices for multiplicity 3 in the basis of ECSFs:\n          H-matrix:\n             -1360.9466672398         0.0000000000         0.0000000000         0.0000000000         0.0000000000         0.0000000000\n                 0.0000000000     -1361.0305986559        -0.0000000037         0.0000000000         0.0000000041        -0.0006912039\n                 0.0000000000        -0.0000000037     -1361.0310619982         0.0002927294        -0.0000000247         0.0000000000\n                 0.0000000000         0.0000000000         0.0002927294     -1360.9026763539         0.0000044933         0.0000000000\n                 0.0000000000         0.0000000041        -0.0000000247         0.0000044933     -1360.9708582316        -0.0000006056\n                 0.0000000000        -0.0006912039         0.0000000000         0.0000000000        -0.0000006056     -1360.9026304185\n          J-matrix:\n                -0.0652297716         0.0000000000         0.0000000000         0.0000000000         0.0000000000         0.0000000000\n                 0.0000000000         0.0038202531         0.0000000000         0.0000000000         0.0000000000        -0.0006994784\n                 0.0000000000         0.0000000000         0.0038427062         0.0001256414         0.0000000000         0.0000000000\n                 0.0000000000         0.0000000000         0.0001256414         0.0038144602         0.0000000000         0.0000000000\n                 0.0000000000         0.0000000000         0.0000000000         0.0000000000         0.0038149941         0.0000000000\n                 0.0000000000        -0.0006994784         0.0000000000         0.0000000000         0.0000000000         0.0038584511\n          K-matrix:\n                 0.0022608525         0.0000000000         0.0000000000         0.0000000000         0.0000000000         0.0000000000\n                 0.0000000000         0.0026107342         0.0000000037         0.0000000000        -0.0000000041        -0.0000082744\n                 0.0000000000         0.0000000037         0.0026114386        -0.0001670880         0.0000000247         0.0000000000\n                 0.0000000000         0.0000000000        -0.0001670880         0.0026548039        -0.0000044933         0.0000000000\n                 0.0000000000        -0.0000000041         0.0000000247        -0.0000044933         0.0026194488         0.0000006056\n                 0.0000000000        -0.0000082744         0.0000000000         0.0000000000         0.0000006056         0.0026197850\n       Time spent in calculating ECI Hamiltonian (sec) = 2.938\n<\/pre>\n<p> <\/span><br \/>\nFor this, it needs to calculate all inter-site Coulomb nuclear-electron (marked by <b><tt>V<\/tt><\/b>) and electron-electron (marked by <b><tt>J<\/tt><\/b>) interaction integrals, as well as the inter-site exchange integrals (marked by <b><tt>K<\/tt><\/b>).<br \/>\nFor more expensive <b><tt>J<\/tt><\/b> and <b><tt>K<\/tt><\/b> integrals, the shapes of some intermediate tensors, as well as the timings of some substeps, are printed.<br \/>\nEventually, the ECI Hamiltonian, as well as its Coulomb and exchange contributions, is printed for each full-system multiplicity in the basis of respective ECSFs, sorted as printed at the end of the section <b><tt>CONSTRUCTION OF THE ECI BASIS<\/tt><\/b>.<br \/>\nFor example, one can easily see strong exciton coupling \\mel<sup>1<\/sup><span class=\"roman\">S<\/span><sub>1<\/sub><span class=\"roman\">S<\/span><sub>0<\/sub>|<span class=\"overacc1\">∧<\/span>H<sup>1<\/sup><span class=\"roman\">S<\/span><sub>0<\/sub><span class=\"roman\">S<\/span><sub>1<\/sub> = −0.0021647097 <span class=\"roman\">Hartree<\/span> ≈ −59 <span class=\"roman\">meV<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> Finally, after diagonalization of the full-system Hamiltonian for each multiplicity, the interface prints the info of the full-system eigenstates:<br \/>\n<span class=\"scriptsize\"><\/p>\n<pre>\n    FULL-SYSTEM STATES:\n       Ground state is of multiplicity 1\n       Ground-state energy = -1361.0908334161868\n       Full-systems states for multiplicity 1 in the basis of ECSFs:\n          -----------------------------------\n          State     Eex\/eV      fosc     Psi\n          -----------------------------------\n              0      0.000     0.0000    1.000( 0 )  0.008( BD^(0) : S1 | BA^(0) : S1 ) -0.002( BD^(0) : S1 )\n              1      3.265     0.0000    1.000( BD^(0) : T1 | BA^(0) : T1 )\n              2      3.429     0.0037    0.743( BA^(0) : S1 )  0.669( BD^(0) : S1 )  0.001( 0 )\n              3      3.547     1.3839    0.743( BD^(0) : S1 ) -0.669( BA^(0) : S1 )  0.004( BD^(0) : S1 | BA^(0) : S1 )  0.002( 0 )\n              4      3.923     0.0000    1.000( BD^(1+) : D0 | BA^(1-) : D0 )\n              5      6.976     0.0000    1.000( BD^(0) : S1 | BA^(0) : S1 ) -0.008( 0 ) -0.003( BD^(0) : S1 )  0.002( BA^(0) : S1 )\n          -----------------------------------\n       Full-systems states for multiplicity 3 in the basis of ECSFs:\n          -----------------------------------\n          State     Eex\/eV               Psi\n          -----------------------------------\n              1      1.626               1.000( BA^(0) : T1 ) -0.002( BD^(0) : S1 | BA^(0) : T1 )\n              2      1.639               1.000( BD^(0) : T1 )  0.005( BD^(0) : T1 | BA^(0) : S1 )\n              3      3.265               1.000( BD^(0) : T1 | BA^(0) : T1 )\n              4      3.923               1.000( BD^(1+) : D0 | BA^(1-) : D0 )\n              5      5.120               1.000( BD^(0) : S1 | BA^(0) : T1 )  0.002( BA^(0) : T1 )\n              6      5.121               1.000( BD^(0) : T1 | BA^(0) : S1 ) -0.005( BD^(0) : T1 )\n          -----------------------------------\n    Time elapsed in the excitonic part = 3.926 sec.\n ============== End of excitonic part of the ECI calculation ===============\n<\/pre>\n<p> <\/span><br \/>\nFor each multiplicity, the interface prints the excitation energy and the ECI wavefunction in the basis of ECSFs (only those with ECI coefficient ≥ 0.001) of each full-system state.<br \/>\nFor the states sharing the multiplicity with the full-system ground state, the oscillator strengths are printed as well.<br \/>\nIn this example, one can see that all full-system states nearly correspond to a single ECSF (all leading ECI coefficienst are ≈ 1), except the <span class=\"roman\">S<\/span><sub>2<\/sub> and <span class=\"roman\">S<\/span><sub>3<\/sub> states, that are the superpositions of two <span class=\"roman\">S<\/span><sub>1<\/sub> LEs, with exciton splitting of ≈ 118 <span class=\"roman\">meV<\/span>.<br \/>\nThis is a consequence of fairly converged EHF procedure, i.e., if we have not converged the embedding charges properly (or even used no embedding), there would be a higher excitonic “correlation” in each state.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.25.6\"><\/a><\/p>\n<h3>\n6.25.6  During setup<\/h3>\n<p><a id=\"sec:int:eci:setup\"><br \/>\n<\/a><br \/>\nBefore calling a setup script, user has to have <b><tt>ECI.template<\/tt><\/b> and <b><tt>ECI.resources<\/tt><\/b> ready.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> After learning the path to <b><tt>ECI.template<\/tt><\/b> from the user, the interface will conclude what are all the EHF and SSC interfaces that need to be instantiated, by making all combinations of full-system charges (found as keys of <b><tt><label>: EHF: embedding_site_states<\/tt><\/b> dictionary) and the fragment’s charges (found as keys of <b><tt><label>: SSC: states<\/tt><\/b> dictionary).<br \/>\nIn the <b><tt>BD-BA<\/tt><\/b> example with the template file above, this will include: <b><tt>BD_embedding_Z0<\/tt><\/b>, <b><tt>BA_embedding_Z0<\/tt><\/b>, <b><tt>BD_z0_Z0<\/tt><\/b>, <b><tt>BD_z1_Z0<\/tt><\/b>, <b><tt>BA_z0_Z0<\/tt><\/b> and <b><tt>BA_z-1_Z0<\/tt><\/b>.<br \/>\nNote that the interface will not check whether all fragments have equal sets of full-system charges, or whether it is possible to “reach” each full-system charge given the charges of the fragments.<br \/>\nIf there is a contradiction here, the error will be raised only during the calculation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>However, after generating all full-system\/fragment charge combination for each fragment, the setup function will allow user to remove some of them.<br \/>\nThis could be useful when user wants to calculate more than one full-system charge, but not all the combinations are necessary for some of them.<br \/>\nIn the <b><tt>BD-BA<\/tt><\/b> example, if we would add a certain <b><tt>embedding_site_state<\/tt><\/b> for the full-system charge <b><tt>1<\/tt><\/b> to each fragment, the template file would immediately become usable for the calculation of <b><tt>[BD-BA]<sup>+<\/sup><\/tt><\/b>.<br \/>\nIn this case, the setup function would initially “plan” to instantiate SSC children <b><tt>BD_z0_Z0<\/tt><\/b>, <b><tt>BD_z1_Z0<\/tt><\/b>, <b><tt>BA_z0_Z0<\/tt><\/b>, <b><tt>BA_z-1_Z0<\/tt><\/b> for the full-system charge <b><tt>0<\/tt><\/b>, and <b><tt>BD_z0_Z1<\/tt><\/b>, <b><tt>BD_z1_Z1<\/tt><\/b>, <b><tt>BA_z0_Z1<\/tt><\/b>, <b><tt>BA_z-1_Z1<\/tt><\/b> for the full-system charge <b><tt>1<\/tt><\/b>.<br \/>\nHowever, it is obvious that <b><tt>BA_z-1_Z1<\/tt><\/b> and <b><tt>BD_z0_Z1<\/tt><\/b> are not needed, so user can delete those in this point during the setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, the setup functions of <b><tt>SHARC_ECI.py<\/tt><\/b> will call the corresponding setup functions of each child.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.26\"><\/a><\/p>\n<h2>\n6.26  Adaptive Sampling Interface<\/h2>\n<p><a id=\"sec:int:adaptive\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Multi-child hybrid interface for quorum-based dynamics, intended primarily for active learning.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>-ADAPTIVE interface uses at least two child interfaces, one lead and at least one advisor. During each step, all the child interfaces are executed. Afterwards the deviations between all pairs of lead and advisors and all pairs of advisors with advisors with a specified error function for specified properties is calculated. If one of the deviations exceeds a given threshold the interface can proceed with the results of the lead, or raise an exception, as well as saving the current geometry to a file.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg6.3\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/adaptive-workflow-scaled.png\"> <\/p>\n<div style=\"text-align:center\">Figure 6.3: Flow chart for the S<span style=\"font-size:x-small\">HARC<\/span>-ADAPTIVE interface after executing all children and calculating deviations for given properties.<\/div>\n<p> <a id=\"fig:adaptive-workflow\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>In any case, if there is no exception the results from the leader (first specified child) will be passed to the caller. Although this interface is intended to be used for active learning, it is not restricted to it.<br \/>\nAlternative use cases could be to compare, e.g., different DFT functionals or collect training data for several different electronic structure methods at the same time.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Available features  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The feature set available from the S<span style=\"font-size:x-small\">HARC<\/span>-ADAPTIVE interface is the intersection of the feature sets of all children (i.e., all features that are provided by all children).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.26.1\"><\/a><\/p>\n<h3>\n6.26.1  Template file: <b><tt>ADAPTIVE.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The ADAPTIVE.template file is written in yaml format. Table <a href=\"#tab:adaptive_temp\">6.37<\/a> lists the existing keywords.<br \/>\nA fully commented template file for this interface with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_ADAPTIVE\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.37\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.37: Keywords for the <b><tt>ADAPTIVE.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:adaptive_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">thresholds <\/td>\n<td align=\"left\">Dictionary with property as key (string) and threshold as value (float).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">error_function <\/td>\n<td align=\"left\">Name of the error function, default is “mae”, other predefined functions are “mae_max”, “mse”, “mse_max” and “rmse”.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">exit_on_fail <\/td>\n<td align=\"left\">Boolean, raise an exception if a threshold is exceeded, default true.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">write_geoms <\/td>\n<td align=\"left\">Boolean, write current geometry to a file in xyz format if a threshold is exceeded, default true<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">geom_file <\/td>\n<td align=\"left\">Name of the file where geometries will be saved. Note that if this file already exists data will be appended.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">interfaces <\/td>\n<td align=\"left\">List of child interfaces, first one is always the lead. Each entry is a dictionary with the keys “label” (can be chosen arbitrarily, has to be unique, must exist as a directory with the child interface resource and template files), ïnterface” (name of a valid S<span style=\"font-size:x-small\">HARC<\/span> interface), ärgs” (list of initialization parameters), and “kwargs” (dictionary of keyword arguments).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">custom_error <\/td>\n<td align=\"left\">Dictionary to specify a custom error function. Keys: “name” (define a name for the error function, will be used for ërror_function”), “file” (name of the Python file, must be in PYTHONPATH), and “function” (name of the function in the file).<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.26.2\"><\/a><\/p>\n<h3>\n6.26.2  Resources file: <b><tt>ADAPTIVE.resources<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The only valid keyword for this interface is <b><tt>ncpu<\/tt><\/b>, everything else, including scratch directories, is handled by the children themselves.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.26.3\"><\/a><\/p>\n<h3>\n6.26.3  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>As a hybrid interface, there are some peculiarities when doing a setup with <b><tt>SHARC_ADAPTIVE.py<\/tt><\/b>.<br \/>\nTo use it, select <b><tt>SHARC_ADAPTIVE.py<\/tt><\/b> directly in your setup script.<br \/>\nYou will then immediately be prompted for the path to your <b><tt>ADAPTIVE.template<\/tt><\/b> file, which tells the interface which child interfaces to invoke.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_ADAPTIVE.py<\/tt><\/b> will then instantiate its children and query them for their feature set.<br \/>\nBased on these feature sets, the <b><tt>SHARC_ADAPTIVE.py<\/tt><\/b> interface automatically composes its own feature set (the intersection of the children’s features), which is returned to the setup script.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>At a later point during setup, the interface-specific setup dialogue is started.<br \/>\n<b><tt>SHARC_ADAPTIVE.py<\/tt><\/b> will ask for a resource file, which will be copied if given.<br \/>\nSubsequently, the interface-specific setup dialogues of the children are launched sequentially (indicated by <b><tt>Setting up interface <name><\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.27\"><\/a><\/p>\n<h2>\n6.27  Fallback Interface<\/h2>\n<p><a id=\"sec:int:fallback\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><i>Two-child hybrid interface that calls a backup if the trial interface fails.<\/i><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The S<span style=\"font-size:x-small\">HARC<\/span>-FALLBACK interface uses exactly two child interfaces, one trial and one backup interface.<br \/>\nEach time the run function of the fallback interface is called, first the trial child will be executed.<br \/>\nIf this is successful, the results from the trial child will be passed to the caller.<br \/>\nIf the trial child fails (i.e., raises an exception), the backup child will be executed, using the same coordinates and requests, and its results will be passed to the caller.<br \/>\nIf the backup child also fails, the fallback interface will itself fail.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg6.4\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/fallback-workflow-scaled.png\"> <\/p>\n<div style=\"text-align:center\">Figure 6.4: Flow chart for the S<span style=\"font-size:x-small\">HARC<\/span> FALLBACK interface.<\/div>\n<p> <a id=\"fig:fallback-workflow\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p><b>Available features  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The feature set available from the S<span style=\"font-size:x-small\">HARC<\/span>-FALLBACK interface is the intersection of the feature sets of all children (i.e., all features that are provided by all children).<br \/>\nThe fallback interface never provides the <b><tt>overlaps<\/tt><\/b> or <b><tt>phases<\/tt><\/b> features (as this would involve computing overlaps between time steps from the trial interface and time steps from the backup interface, which is not possible).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.27.1\"><\/a><\/p>\n<h3>\n6.27.1  Template file: <b><tt>FALLBACK.template<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The FALLBACK.template file is written in yaml format.<br \/>\nTable <a href=\"#tab:fallback_temp\">6.38<\/a> lists the existing keywords.<br \/>\nA fully commented template file for this interface with all possible options is located in <b><tt>$SHARC\/..\/examples\/SHARC_FALLBACK\/<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.38\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.38: Keywords for the <b><tt>FALLBACK.template<\/tt><\/b> file.<\/div>\n<p> <a id=\"tab:fallback_temp\"><br \/>\n<\/a><br \/>\n <span class=\"small\"><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">trial_interface <\/td>\n<td align=\"left\">Is a dictionary with the keys ïnterface” (name of a valid S<span style=\"font-size:x-small\">HARC<\/span> interface), ärgs” (list of initialization parameters), and “kwargs” (dictionary of keyword arguments)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">fallback_interface <\/td>\n<td align=\"left\">Is a dictionary with the keys ïnterface” (name of a valid S<span style=\"font-size:x-small\">HARC<\/span> interface), ärgs” (list of initialization parameters), and “kwargs” (dictionary of keyword arguments)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">stop_at_nfails <\/td>\n<td align=\"left\">Raise an exception if the trial interface has failed <b><tt>n<\/tt><\/b> times. Default 2. <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">reset_fail_counter <\/td>\n<td align=\"left\">Reset fail counter after <b><tt>n<\/tt><\/b> successful trial steps. Default 1.<\/td>\n<\/tr>\n<\/table>\n<p><\/span><\/div>\n<div class=\"p\"><!----><\/div>\n<p>The options in the template file give some flexibility to control when the fallback interface stops trying to run the backup interface.<br \/>\nWith the default <b><tt>stop_at_nfails<\/tt><\/b>=2 and <b><tt>reset_fail_counter<\/tt><\/b>=1, the fallback interface will stop if the trial child fails in two <i>consecutive<\/i> time steps.<br \/>\nHowever, if the trial child is successful at least once between fails, the fallback interface will not stop.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.27.2\"><\/a><\/p>\n<h3>\n6.27.2  During setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>As a hybrid interface, there are some peculiarities when doing a setup with <b><tt>SHARC_FALLBACK.py<\/tt><\/b>.<br \/>\nTo use it, select <b><tt>SHARC_FALLBACK.py<\/tt><\/b> directly in your setup script.<br \/>\nYou will then immediately be prompted for the path to your <b><tt>FALLBACK.template<\/tt><\/b> file, which tells the interface which child interfaces to invoke.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>SHARC_FALLBACK.py<\/tt><\/b> will then instantiate its children and query them for their feature set.<br \/>\nBased on these feature sets, the <b><tt>SHARC_FALLBACK.py<\/tt><\/b> interface automatically composes its own feature set, which is returned to the setup script.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>At a later point during setup, the interface-specific setup dialogue is started.<br \/>\n<b><tt>SHARC_FALLBACK.py<\/tt><\/b> will ask for a resource file, which will be copied if given.<br \/>\nSubsequently, the interface-specific setup dialogues of the children are launched sequentially (indicated by <b><tt>Setting up Trial interface<\/tt><\/b> and <b><tt>Setting up Fallback interface<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.28\"><\/a><\/p>\n<h2>\n6.28  File-based Interface Specifications<\/h2>\n<p><a id=\"sec:int_spec\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>From the S<span style=\"font-size:x-small\">HARC<\/span> point of view, quantum chemical calculation proceeds as follows in the <b><tt>QM<\/tt><\/b> directory:<\/p>\n<ol type=\"1\">\n<li> write a file called <b><tt>QM\/QM.in<\/tt><\/b>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> call a script called <b><tt>QM\/runQM.sh<\/tt><\/b>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> read the output from a file called <b><tt>QM\/QM.out<\/tt><\/b>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<p>For specifications of the formats of these two files (<b><tt>QM.in<\/tt><\/b> and <b><tt>QM.out<\/tt><\/b>) see below. The executable script <b><tt>QM\/runQM.sh<\/tt><\/b> must accomplish that all necessary quantum chemical output is available in <b><tt>QM\/QM.out<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that this section does not document the S<span style=\"font-size:x-small\">HARC<\/span>4-style object-oriented Python interfaces.<br \/>\nThese interfaces are derived from the <b><tt>SHARC_FAST<\/tt><\/b>, <b><tt>SHARC_ABINITIO<\/tt><\/b>, or <b><tt>SHARC_HYBRID<\/tt><\/b> abstract base classes and have a large number of extra requirements.<br \/>\nIn particular, they require implementation of a set of three setup routines (<b><tt>get_features<\/tt><\/b>, <b><tt>get_infos<\/tt><\/b>, and <b><tt>prepare<\/tt><\/b>) that are needed for all of the setup scripts (e.g., <b><tt>setup_traj.py<\/tt><\/b>).<br \/>\nSuch S<span style=\"font-size:x-small\">HARC<\/span>4 interfaces also require following certain naming conventions and behaviour for files placed into the save directory.<br \/>\nIf you are interested in developing a S<span style=\"font-size:x-small\">HARC<\/span>4 interface, we recommend to contact the developers. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.28.1\"><\/a><\/p>\n<h3>\n6.28.1  <b><tt>QM.in<\/tt><\/b> Specification<\/h3>\n<p><a id=\"intf:qmin\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>QM.in<\/tt><\/b> file is written by S<span style=\"font-size:x-small\">HARC<\/span> every time a quantum chemistry calculation is necessary. It contains all information available to S<span style=\"font-size:x-small\">HARC<\/span>. This information includes the current geometry (and velocity), the time step, the number of states, the charges and the unit used to specify the atomic coordinates. The file also contains <i>control<\/i> keywords and <i>request<\/i> keywords. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The file format is consistent with a standard xyz file. The first line contains the number of atoms, the second line is a comment. S<span style=\"font-size:x-small\">HARC<\/span> writes the trajectory ID (a hash of all S<span style=\"font-size:x-small\">HARC<\/span> input files) to this line. The following lines specify the atom positions. As a fourth, fifth and sixth column, these lines may contain the atomic velocities.<br \/>\nAll following lines contain keywords, one per line and possibly with arguments. Comments can be inserted with ‘#’, and empty lines are permitted. Comments and empty lines are only permitted below the xyz file part.<br \/>\nAn examplary <b><tt>QM.in<\/tt><\/b> file is given in the following:<\/p>\n<pre>\n3\nJobname\nS     0.0     0.0     0.0    0.000  -0.020   0.002\nH     0.0     0.9     1.2    0.000  -0.030   0.000\nH     0.0    -0.9     1.2    0.000   0.010  -0.000\n# This is a comment\nStates 3 0 2\ncharge 0 1 0\nUnit Angstrom\nSOC\nDM\nGRAD 1 2\nOVERLAP\nNACDR select\n  1 2\n  end\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>There exist two types of keywords, <i>control<\/i> keywords and <i>request<\/i> keywords. Control keywords pass some information to the interface. Request keywords tell the interface to provide a quantity in the <b><tt>QM.out<\/tt><\/b> file. Table <a href=\"#tab:int_ctrl\">6.39<\/a> contains all control keywords while table <a href=\"#tab:int_req\">6.40<\/a> lists all request keywords.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.39\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.39: Control keywords for S<span style=\"font-size:x-small\">HARC<\/span> interfaces. These keywords pass information from S<span style=\"font-size:x-small\">HARC<\/span> to the interface.<\/div>\n<p> <a id=\"tab:int_ctrl\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">unit <\/td>\n<td align=\"left\">Specifies in which unit the atomic coordinates are to be interpreted. Possible arguments are “angstrom” and “bohr”.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">states <\/td>\n<td align=\"left\">Gives the number of excited states per multiplicity (singlets, doublet, triplets, …).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">savedir <\/td>\n<td align=\"left\">Gives a path to the directory where the interface should save files needed for restart and between time steps. If the interface-specific input files also have this keyword, S<span style=\"font-size:x-small\">HARC<\/span> assumes that the path in <b><tt>QM.in<\/tt><\/b> takes precedence.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">charge <\/td>\n<td align=\"left\">Gives the charge per multiplicity (singlets, doublet, triplets, …).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">point_charges <\/td>\n<td align=\"left\">Path to a point charge file.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">retain <\/td>\n<td align=\"left\">Integer which specifies for how many steps intermediate files are kept.<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.40\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 6.40: Request keywords for S<span style=\"font-size:x-small\">HARC<\/span> interfaces. See Table <a href=\"#tab:interfaces\">6.1<\/a> for which interfaces can fulfill these requests.<\/div>\n<p> <a id=\"tab:int_req\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Description<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">H <\/td>\n<td align=\"left\">Calculate the molecular Hamiltonian (diagonal matrix with the energies of the states of the model space). This request is always available.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SOC <\/td>\n<td align=\"left\">Calculate the molecular Hamiltonian including the SOCs (not diagonal anymore within the model space).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">DM <\/td>\n<td align=\"left\">Calculate the state dipole moments and transition dipole moments between all states.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">GRAD <\/td>\n<td align=\"left\">Calculate gradients for all states. If followed by a list of states, calculate only gradients for the specified states.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">NACDR <\/td>\n<td align=\"left\">Calculate nonadiabatic coupling vectors 〈Ψ<sub>1<\/sub>|∂\/∂<b>R<\/b>|Ψ<sub>2<\/sub>〉 between all pairs of states. If followed by “select”, read the list of pairs on the following lines until “end” and calculate nonadiabatic coupling vectors between the specified pairs of states.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">OVERLAP <\/td>\n<td align=\"left\">Calculate overlaps 〈Ψ<sub>1<\/sub>(t<sub>0<\/sub>)|Ψ<sub>2<\/sub>(t)〉 between all pairs of states (between the last and current time step). If followed by “select”, read the list of pairs on the following lines until “end” and calculate overlaps between the specified pairs of states.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">PHASES <\/td>\n<td align=\"left\">Calculate phases between the last and current step.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ION <\/td>\n<td align=\"left\">Calculate transition properties between neutral and ionic wave functions.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">THEODORE <\/td>\n<td align=\"left\">Run T<span style=\"font-size:x-small\">HEO<\/span>DORE to compute electronic descriptors for all states.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MULTIPOLAR_FIT <\/td>\n<td align=\"left\">Calculate a distributed multipole expansion representing the state electronic densities\/transition densities, via a RESP fit of these densities.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">SOCDR <\/td>\n<td align=\"left\">Calculate the Cartesian gradients of the full spin-orbit Hamiltonian (currently not used).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">DMDR <\/td>\n<td align=\"left\">Calculate the Cartesian gradients of the dipole moments and transition dipole moments of all states (currently not used).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">MOLDEN <\/td>\n<td align=\"left\">Generate M<span style=\"font-size:x-small\">OLDEN<\/span> files of the relevant orbitals and copy them to the savedir (this is a “pseudo-request” that does not produce output in <b><tt>QM.out<\/tt><\/b>).<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.28.2\"><\/a><\/p>\n<h3>\n6.28.2  <b><tt>QM.out<\/tt><\/b> Specification<\/h3>\n<p><a id=\"intf:qmout\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>QM.out<\/tt><\/b> file communicates back the results of the quantum chemistry calculation to the dynamics code. After S<span style=\"font-size:x-small\">HARC<\/span> called <b><tt>QM\/runQM.sh<\/tt><\/b>, it expects that the file <b><tt>QM\/QM.out<\/tt><\/b> exists and contains the relevant data. This file will not be created and is not needed if PySHARC is used.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The following quantities are expected in the file (depending whether the corresponding keyword is in the <b><tt>QM.in<\/tt><\/b> file): Hamiltonian matrix, dipole matrices, gradients, nonadiabatic couplings (either NACDR or NACDT), overlaps, wave function phases, property matrices. The format of <b><tt>QM.out<\/tt><\/b> is described in the following. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Each quantity is given as a data block, which has a fixed format. The order of the blocks is arbitrary, and between blocks arbitrary lines can be written. However, within a block no extraneous lines are allowed. Each data block starts with a exclamation mark <b><tt>!<\/tt><\/b>, followed by whitespace and an integer flag which specifies the type of data:<\/p>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"left\">0 <\/td>\n<td align=\"left\">Basic information<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">1 <\/td>\n<td align=\"left\">Hamiltonian matrix<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">2 <\/td>\n<td align=\"left\">Dipole matrices<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">3 <\/td>\n<td align=\"left\">Gradients<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">5 <\/td>\n<td align=\"left\">Non-adiabatic couplings (NACDR)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">6 <\/td>\n<td align=\"left\">Overlap matrix<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">7 <\/td>\n<td align=\"left\">Wavefunction phases<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">8 <\/td>\n<td align=\"left\">wall clock time for QM calculation<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">12 <\/td>\n<td align=\"left\">Dipole moment gradients<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">13 <\/td>\n<td align=\"left\">Spin-orbit matrix gradients<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">20 <\/td>\n<td align=\"left\">Two dimensional properties (matrices)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">21 <\/td>\n<td align=\"left\">One dimensional properties (vectors)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">22 <\/td>\n<td align=\"left\">Multipolar_fit<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">23 <\/td>\n<td align=\"left\">Scalar properties<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">30 <\/td>\n<td align=\"left\">Point charge gradients<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">31 <\/td>\n<td align=\"left\">Point charge non-adiabatic couplings<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">32 <\/td>\n<td align=\"left\">Point charge dipole moment gradients<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">33 <\/td>\n<td align=\"left\">Point charge spin-orbit matrix gradients<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">999 <\/td>\n<td align=\"left\">Notes<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>On the next line, two integers are expected giving the dimensions of the following matrix. Note, that all these matrices must be square matrices. On the following lines, the matrix or vector follows. Matrices are in general complex, and real and imaginary part of each element is given as a pair of floating point numbers.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The following shows an example of a 4×4 Hamiltonian matrix. Note that the imaginary parts directly follow the real parts (in this example, the Hamiltonian is real).<\/p>\n<pre>\n  ! 1 Hamiltonian Matrix (4x4, complex)\n  4 4\n -548.6488 0.0000    0.0000 0.0000    0.0003 0.0000    0.0003 0.0000\n    0.0000 0.0000 -548.6170 0.0000    0.0003 0.0000    0.0003 0.0000\n    0.0003 0.0000    0.0003 0.0000 -548.5986 0.0000    0.0000 0.0000\n    0.0003 0.0000    0.0003 0.0000    0.0000 0.0000 -548.5912 0.0000\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The three dipole moment matrices (x, y and z polarization) must follow directly after each other, where the dimension specifier must be present for each matrix. The dipole matrices are also expected to be complex-valued.<\/p>\n<pre>\n  ! 2 Dipole Moment Matrices (3x2x2, complex)\n  2 2\n  0.1320 0.0000 -0.0020 0.0000\n -0.0020 0.0000 -1.1412 0.0000\n  2 2\n  0.0000 0.0000  0.0000 0.0000\n  0.0000 0.0000  0.0000 0.0000\n  2 2\n  2.1828 0.0000  0.0000 0.0000\n  0.0000 0.0000  0.6422 0.0000\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>Gradient and nonadiabatic couplings vectors are written as 3×n<sub>atom<\/sub> matrices, with the x, y and z components of one atom per line. These vectors are expected to be real valued. Each vector is preceded by its dimensions.<\/p>\n<pre>\n! 3 Gradient Vectors (1x6x3, real)\n6 3 ! m1 1 s1 1 ms1 0\n 0.0000 -6.5429 -8.1187\n 0.0000  5.8586  8.0160\n 0.0000  6.8428  1.0265\n 0.0000  6.5429  8.1187\n 0.0000 -5.8586 -8.0160\n 0.0000 -6.8428 -1.0265\n<\/pre>\n<p>If gradients are requested, S<span style=\"font-size:x-small\">HARC<\/span> expects every gradient to be present, even if only some gradients are requested. The gradients are expected in the canonical ordering (see section <a href=\"#met:ordering\">8.28<\/a>), which implies that for higher multiplets the same gradient has to be present several times. For example, with 3 singlets and 3 triplets, S<span style=\"font-size:x-small\">HARC<\/span> expects 12 gradients in the <b><tt>QM.out<\/tt><\/b> file (each triplet has three components with M<sub>s<\/sub>= -1, 0 or 1).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Similarly, for nonadiabatic coupling vectors, S<span style=\"font-size:x-small\">HARC<\/span> expects all pairs, even between states of different multiplicity. The vectors are also in canonical ordering, where the inner loop goes over the ket states. For example, with 3 singlets and 3 triplets (12 states), S<span style=\"font-size:x-small\">HARC<\/span> expects 144 (12<sup>2<\/sup>) nonadiabatic coupling vectors in the <b><tt>QM.out<\/tt><\/b> file.<\/p>\n<pre>\n! 5 Non-adiabatic couplings (ddr) (2x2x1x3, real)\n1 3 ! m1 1 s1 1 ms1 0   m2 1 s2 1 ms2 0\n 0.0e+0  0.0e+0  0.0e+0 \n1 3 ! m1 1 s1 1 ms1 0   m2 1 s2 2 ms2 0\n+2.0e+0  0.0e+0  0.0e+0 \n1 3 ! m1 1 s1 2 ms1 0   m2 1 s2 1 ms2 0\n-2.0e+0  0.0e+0  0.0e+0 \n1 3 ! m1 1 s1 2 ms1 0   m2 1 s2 2 ms2 0\n 0.0e+0  0.0e+0  0.0e+0 \n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The nonadiabatic coupling matrix (NACDT keyword), the overlap matrix and the property matrix are single n×n matrices (n is the total number of states), respectively, like the Hamiltonian. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The wave function phases are a vector of complex numbers.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The wall clock time is a single real number. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The dipole moment gradients are a list of 3×n<sub>atom<\/sub> vectors, each specifying the gradient of one polarization of one dipole moment matrix element. In the outmost loop, the bra index is counted, then the ket index, then the polarization. Hence, the respective entry in <b><tt>QM.out<\/tt><\/b> would look like (for 2 states and 1 atom):<\/p>\n<pre>\n! 12 Dipole moment derivatives (2x2x3x1x3, real)\n1 3 ! m1 1 s1 1 ms1 0   m2 1 s2 1 ms2 0   pol 0\n 0.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 1 ms10   m2 1 s2 1 ms2 0  pol 1\n 0.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 1 ms10   m2 1 s2 1 ms2 0  pol 2\n 0.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 1 ms10   m2 1 s2 2 ms2 0  pol 0\n 1.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 1 ms10   m2 1 s2 2 ms2 0  pol 1\n 0.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 1 ms10   m2 1 s2 2 ms2 0  pol 2\n 0.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 2 ms10   m2 1 s2 1 ms2 0  pol 0\n 1.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 2 ms10   m2 1 s2 1 ms2 0  pol 1\n 0.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 2 ms10   m2 1 s2 1 ms2 0  pol 2\n 0.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 2 ms10   m2 1 s2 2 ms2 0  pol 0\n 0.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 2 ms10   m2 1 s2 2 ms2 0  pol 1\n 0.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n1 3 ! m1 1 s1 2 ms10   m2 1 s2 2 ms2 0  pol 2\n 0.000000000000E+00  0.000000000000E+00  0.000000000000E+00 \n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The section containing the 2D property matrices consists of three subsequent parts: (i) the number of property matrices contained, (ii) a label for each property matrix (as the property matrices might contain arbitrary data, depending on the interface and the requests), and (iii) the matrices (full, complex-valued matrices like above):<\/p>\n<pre>\n! 20 Property Matrices\n2    ! number of property matrices\n! Property Matrix Labels (1 strings)\nDyson norms\nExample matrix\n! Property Matrices (1x4x4, complex)\n4 4   ! Dyson norms\n 0.000E+00  0.000E+00  0.000E+00  0.000E+00  9.663E-01  0.000E+00  9.663E-01  0.000E+00 \n 0.000E+00  0.000E+00  0.000E+00  0.000E+00  4.822E-01  0.000E+00  4.822E-01  0.000E+00 \n 9.663E-01  0.000E+00  4.822E-01  0.000E+00  0.000E+00  0.000E+00  0.000E+00  0.000E+00 \n 9.663E-01  0.000E+00  4.822E-01  0.000E+00  0.000E+00  0.000E+00  0.000E+00  0.000E+00 \n4 4   ! Example matrix\n 1.000E+00  1.000E+00  0.000E+00  0.000E+00  0.000E+00  0.000E+00  0.000E+00  0.000E+00 \n 0.000E+00  0.000E+00  2.000E+00  2.000E+00  0.000E+00  0.000E+00  0.000E+00  0.000E+00 \n 0.000E+00  0.000E+00  0.000E+00  0.000E+00  3.000E+00  3.000E+00  0.000E+00  0.000E+00 \n 0.000E+00  0.000E+00  0.000E+00  0.000E+00  0.000E+00  0.000E+00  4.000E+00  4.000E+00 \n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The section containing the 1D property vectors also consists of three subsequent parts: (i) the number of property vectors contained, (ii) a label for each property vector (as the property vectors might contain arbitrary data, depending on the interface and the requests), and (iii) the vectors (real-valued):<\/p>\n<pre>\n! 21 Property Vectors\n2    ! number of property vectors\n! Property Vector Labels (2 strings)\nOm\nPRNTO\n! Property Vectors (2x4, real)\n4 ! TheoDORE descriptor 1 (Om)\n 0.000000000000E+000\n 4.318700000000E-001\n 2.688600000000E-001\n 2.590000000000E-002\n4 ! TheoDORE descriptor 2 (PRNTO)\n 0.000000000000E+000\n 2.318700000000E-001\n 1.688600000000E-001\n 1.590000000000E-002\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.28.3\"><\/a><\/p>\n<h3>\n6.28.3  Further Specifications<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interfaces may require additional input files beyond <b><tt>QM.in<\/tt><\/b>, which contain static information. This may include paths to the quantum chemistry executable, paths to scratch directories, or input templates for the quantum chemistry calculation (e.g. active space specifications, basis sets, etc.).<br \/>\nThe dynamics code does not depend on these additional files, but they should all be stored in the <b><tt>QM\/<\/tt><\/b> subdirectory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The current conventions in the S<span style=\"font-size:x-small\">HARC<\/span> suite are that the quantum chemistry interfaces use two additional input files, one specifying the level of theory (template file, e.g., <b><tt>MOLCAS.template<\/tt><\/b>, <b><tt>MOLPRO.template<\/tt><\/b>, …) and one specifying the computational resources like paths, memory, number of CPU cores, initial orbital source (resource file, e.g., <b><tt>MOLCAS.resources<\/tt><\/b>, <b><tt>MOLPRO.resources<\/tt><\/b>, …).<br \/>\nFurthermore, the current interfaces allow to read in initial orbitals (e.g., <b><tt>MOLCAS.*.RasOrb.init<\/tt><\/b>, <b><tt>mocoef.init<\/tt><\/b>, …).<br \/>\nFor interfaces with QM\/MM capabilities, additional files could be used to specify connection table, parameters, etc.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.28.4\"><\/a><\/p>\n<h3>\n6.28.4  Save Directory Specification<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interfaces must be able to save all information necessary for restart to a given directory. The absolute path is written to <b><tt>QM.in<\/tt><\/b> by S<span style=\"font-size:x-small\">HARC<\/span>. Hence, for the trajectories the path to the save directory is always a subdirectory of the working directory of S<span style=\"font-size:x-small\">HARC<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.29\"><\/a><\/p>\n<h2>\n6.29  The WF<span style=\"font-size:x-small\">OVERLAP<\/span> Program<\/h2>\n<p><a id=\"sec:int:wfoverlap\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This section does not describe an interface to S<span style=\"font-size:x-small\">HARC<\/span>, but rather the WF<span style=\"font-size:x-small\">OVERLAP<\/span> program.<br \/>\nThis program is part of the S<span style=\"font-size:x-small\">HARC<\/span> distribution, but can also be obtained as a <a href=\"https:\/\/sharc-md.org\/?page_id=309\">stand-alone package<\/a> (including a more detailed manual and a set of auxiliary scripts).<br \/>\nIt computes overlaps between many-electron wave functions expressed in terms of linear combinations of Slater determinant, which are based on molecular orbitals (from an LCAO ansatz).<br \/>\nIt can also compute Dyson orbitals and Dyson norms between wave functions differing by one α or one β electron.<br \/>\nThe program is based on the efficient and general algorithm published in Ref. <a href=\"#Plasser2016JCTC\" class=\"tth_citeref\">[54<\/a>].<br \/>\nIt is possible to vary the geometry, the basis set, the molecular orbitals, and the wavefunction expansion between the calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The resulting wave function overlaps or Dyson norms can be used for example for:<\/p>\n<ul>\n<li> Propagation in local diabatization, the main application inside S<span style=\"font-size:x-small\">HARC<\/span>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Computation of photoionization spectra <a href=\"#Ruckenbauer2016SR\" class=\"tth_citeref\">[41<\/a>,<a href=\"#Ruckenbauer2016JCP\" class=\"tth_citeref\">[70<\/a>],\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Comparison of wave functions at different levels of theory <a href=\"#Plasser2016JCP\" class=\"tth_citeref\">[71<\/a>].\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<p>If you employ the <b><tt>wfoverlap.x<\/tt><\/b> code inside the S<span style=\"font-size:x-small\">HARC<\/span> suite for these purposes, please cite these references!<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The documentation here only gives a brief overview over the input options of <span style=\"font-size:x-small\">WFOVERLAP<\/span>.<span style=\"font-size:x-small\">X<\/span>, because within the S<span style=\"font-size:x-small\">HARC<\/span> suite the <b><tt>wfoverlap.x<\/tt><\/b> program is always called automatically by the interfaces. For the full manual (and for access to the auxiliary scripts of <span style=\"font-size:x-small\">WFOVERLAP<\/span>.<span style=\"font-size:x-small\">X<\/span>), please download the separate <a href=\"https:\/\/sharc-md.org\/?page_id=309\"> WF<span style=\"font-size:x-small\">OVERLAP<\/span> package<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.29.1\"><\/a><\/p>\n<h3>\n6.29.1  Installation<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>Using precompiled binaries  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>After unpacking, the directory <b><tt>$SHARC<\/tt><\/b> should contain a binary <b><tt>wfoverlap_ascii.x<\/tt><\/b> and a link called <b><tt>wfoverlap.x<\/tt><\/b> pointing to the binary.<br \/>\nWith this setup, most interfaces should work without problems.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Manual installation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The only exceptions are the following: C<span style=\"font-size:x-small\">OLUMBUS<\/span> (overlaps and Dyson norms) and M<span style=\"font-size:x-small\">OLCAS<\/span> (only Dyson norms).<br \/>\nThese features are only available if <b><tt>wfoverlap.x<\/tt><\/b> is recompiled with proper support for these programs.<br \/>\nAlternatively, you may want to link <b><tt>wfoverlap.x<\/tt><\/b> against your favorite libraries.<br \/>\nIn these cases, a manual installation is necessary.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For the manual installation you need a working Fortran90 compatible compiler (Intel’s ifort is recommended),<br \/>\nsome reasonably fast BLAS\/LAPACK libraries (Intel’s MKL is recommended, although atlas is also fine).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Optionally, with a working C<span style=\"font-size:x-small\">OLUMBUS<\/span> Installation you can install the C<span style=\"font-size:x-small\">OLUMBUS<\/span> bindings, which will<br \/>\nallow direct reading of SIFS integral files generated by D<span style=\"font-size:x-small\">ALTON<\/span>. To use this option, it is<br \/>\nnecessary to use the <tt>read_dalton.o<\/tt> object file.<br \/>\n M<span style=\"font-size:x-small\">OLCAS<\/span>\/S<span style=\"font-size:x-small\">EWARD<\/span> integral files can be read by linking with the C<span style=\"font-size:x-small\">OLUMBUS<\/span>\/M<span style=\"font-size:x-small\">OLCAS<\/span> interface. Link against<br \/>\n<tt>read_molcas.o<\/tt> for this purpose.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>To compile the source code, switch to the <tt>source<\/tt> directory and edit the Makefile to adjust it to your Fortran compiler and BLAS\/LAPACK installation. The location of your C<span style=\"font-size:x-small\">OLUMBUS<\/span> installation has to be set via the enviroment variable<br \/>\n<tt>$COLUMBUS<\/tt>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Issuing the command:<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <tt>cd $SHARC\/..\/wfoverlap\/source\/<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p><tt>make<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p>will compile the source and create the binaries.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you are unable to link against C<span style=\"font-size:x-small\">OLUMBUS<\/span> and\/or M<span style=\"font-size:x-small\">OLCAS<\/span>, simply call<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <tt>make  wfoverlap_ascii.x<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p>to compile a minimal version of the CI Overlap program that only reads ASCII files.<br \/>\nIn this case, overlap and Dyson calculations with <b><tt>SHARC_COLUMBUS.py<\/tt><\/b> and Dyson calculations with <b><tt>SHARC_MOLCAS.py<\/tt><\/b> will not be possible.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Testing  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The command <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <tt>make test<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p>will run a couple of tests to check if the program is working correctly (alternatively you can call <tt>ovl_test.bash $OVDIR<\/tt>, but <b><tt>$OVDIR<\/tt><\/b> needs to be set before).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.29.2\"><\/a><\/p>\n<h3>\n6.29.2  Workflow<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The workflow of the overlap program is shown in Figure <a href=\"#fig:work\">6.5<\/a>.<br \/>\nFour pieces of input, as shown on top, have to be given:<\/p>\n<ul>\n<li> Overlaps between the two sets of AOs used to construct the bra and ket wavefunctions,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> MO coefficients of the bra and ket wavefunctions,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> information about the Slater determinants,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> the corresponding CI coefficients.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>Two main intermediates are computed, the MO overlaps and the unique factors <i>S<\/i><sub>kl<\/sub>, <span class=\"overacc2\">―<\/span><i>S<\/i><sub>kl<\/sub> where the latter may require significant amounts of memory to be stored.<br \/>\nThe reuse of these intermediates is one of the main reasons for the decent performance of the <b><tt>wfoverlap.<\/tt><\/b> program.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg6.5\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/wfoverlap.png\"> <\/p>\n<div style=\"text-align:center\">Figure 6.5: Workflow of the wavefunction overlap program.<\/div>\n<p> <a id=\"fig:work\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.29.3\"><\/a><\/p>\n<h3>\n6.29.3  Calling the program<\/h3>\n<p>The main program is called in the following form<br \/>\n<b><tt>wfoverlap.x [-m <mem=1000>] [-f <input_file=cioverlap.input>]<\/tt><\/b><br \/>\nwith the command line options<\/p>\n<ul>\n<li> <b><tt>-m<\/tt><\/b> : amount of memory in MB\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>-f<\/tt><\/b> : input file\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>Example:<br \/>\n<b><tt>wfoverlap.x -m 2000 -f wfov.in<\/tt><\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Mode  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The program automatically detects whether overlaps or Dyson orbitals should be calculated.<br \/>\nIf the number of electrons in the bra and ket wavefunctions is the same, wavefunction overlaps are computed.<br \/>\nIf the number of α electrons or the number of β electrons differ by exactly 1, Dyson orbitals are computed.<br \/>\nIf the wave functions differ by more than one electron, the program will stop with an error message.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Memory  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The amount of <b>memory<\/b> given is a decisive factor for the performance of the code.<br \/>\nDepending on the amount of memory, one of three different modes is chosen:<\/p>\n<div class=\"p\"><!----><\/div>\n<p>(i) All <i>S<\/i><sub>kl<\/sub> and <span class=\"overacc2\">―<\/span><i>S<\/i><sub>kl<\/sub> terms are kept in core (using arrays called <b><tt>P_ovl<\/tt><\/b>and <b><tt>Q_ovl<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>(ii) Only the <i>S<\/i><sub>kl<\/sub> factors (<b><tt>P_ovl<\/tt><\/b>) are kept in core. This is indicated by<br \/>\n<b><tt>Allocation of Q block overlap matrix failed.<br \/>\n - Using on-the-fly algorithm for Q determinants.<\/tt><\/b><br \/>\nThis mode is generally as efficient as 1. but shows somewhat worse parallel scaling.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>(iii) Not even all <i>S<\/i><sub>kl<\/sub> factors can be stored<br \/>\n<b><tt>Only 437 out of 886 columns of the P_ovl matrix are stored in memory (3 MB)!<br \/>\n Increase the amount of memory to improve the efficiency.<\/tt><\/b><br \/>\nThis mode is significantly slower than (i) and (ii) and should be avoided by increasing the amount of memory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Input file  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb6.41\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">Table 6.41: List of keywords given in the input file. The <b><tt>a_mo, b_mo, a_det, b_det<\/tt><\/b> keywords are mandatory, all others are optional.<\/div>\n<p> <a id=\"tab:key_wfo\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Keyword <\/td>\n<td align=\"left\">Default <\/td>\n<td width=\"355\">Description <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>a_mo<\/tt><\/b> <\/td>\n<td align=\"left\">– <\/td>\n<td width=\"355\">MO coefficient file (bra)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>b_mo<\/tt><\/b> <\/td>\n<td align=\"left\">– <\/td>\n<td width=\"355\">MO coefficient file (ket)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>a_mo_read<\/tt><\/b> <\/td>\n<td align=\"left\">0 <\/td>\n<td width=\"355\">Format for the MO coefficients (bra):<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td width=\"355\">0: C<span style=\"font-size:x-small\">OLUMBUS<\/span>, 1: M<span style=\"font-size:x-small\">OLCAS<\/span>, 2: T<span style=\"font-size:x-small\">URBOMOLE<\/span><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>b_mo_read<\/tt><\/b> <\/td>\n<td align=\"left\">0 <\/td>\n<td width=\"355\">Format for the MO coefficients (ket)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>a_det<\/tt><\/b> <\/td>\n<td align=\"left\">– <\/td>\n<td width=\"355\">Determinant file (bra)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>b_det<\/tt><\/b> <\/td>\n<td align=\"left\">– <\/td>\n<td width=\"355\">Determinant file (ket)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>ncore<\/tt><\/b> <\/td>\n<td align=\"left\">0 <\/td>\n<td width=\"355\">Number of discarded core orbitals<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>ndocc<\/tt><\/b> <\/td>\n<td align=\"left\">0 <\/td>\n<td width=\"355\">Number of doubly occupied orbitals that are not used for<br \/>\n annihilation in Dyson orbital calculations (only has effect if larger than <b><tt>ncore<\/tt><\/b>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>ao_read<\/tt><\/b> <\/td>\n<td align=\"left\">0 <\/td>\n<td width=\"355\">Format for overlap integrals:<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td width=\"355\">0: ASCII, 1: M<span style=\"font-size:x-small\">OLCAS<\/span>, 2: C<span style=\"font-size:x-small\">OLUMBUS<\/span>\/SIFS,<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td width=\"355\">-1: Compute by inversion of MO coefficient matrx<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>mix_aoovl<\/tt><\/b> <\/td>\n<td align=\"left\"><b><tt>S_mix\/ONEINT\/aoints<\/tt><\/b> <\/td>\n<td width=\"355\">AO overlap file<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">for <b><tt>ao_read=0\/1\/2<\/tt><\/b> <\/td>\n<td width=\"355\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>same_aos<\/tt><\/b> <\/td>\n<td align=\"left\">.false. <\/td>\n<td width=\"355\">If both calculations were performed with the same set of AOs (specify only for <b><tt>ao_read=1\/2<\/tt><\/b>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>nao_a<\/tt><\/b> <\/td>\n<td align=\"left\"><i>automatic<\/i> <\/td>\n<td width=\"355\">Number of bra AOs for <b><tt>ao_read=1\/2<\/tt><\/b> (specify only if different from ket AOs) <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>nao_b<\/tt><\/b> <\/td>\n<td align=\"left\"><i>automatic<\/i> <\/td>\n<td width=\"355\">Number of ket AOs (see above) <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>moprint<\/tt><\/b> <\/td>\n<td align=\"left\">0 <\/td>\n<td width=\"355\">Print Dyson orbitals: 1: coefficients to std. out,<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\">2: as Jmol script<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>force_direct_dets<\/tt><\/b> <\/td>\n<td align=\"left\">.false. <\/td>\n<td width=\"355\">Compute <i>S<\/i><sub>kl<\/sub> terms directly (turn off ßuperblocks”).<br \/>\n Recommended if the number of CPU-cores is large (on the same order as the number of ßuperblocks”).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>force_noprecalc<\/tt><\/b> <\/td>\n<td align=\"left\">.false. <\/td>\n<td width=\"355\">Do not precalculate the <span class=\"overacc2\">―<\/span><i>S<\/i><sub>kl<\/sub> factors.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><b><tt>mixing_angles<\/tt><\/b> <\/td>\n<td align=\"left\">.false. <\/td>\n<td width=\"355\">Compute mixing angles as a matrix logarithm.<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>An example input file is shown below:<\/p>\n<pre>\na_mo=mocoef_a\nb_mo=mocoef_b\na_det=dets_a\nb_det=dets_b\nao_read=2\nsame_aos\n<\/pre>\n<p>The full list of keywords is given in Table <a href=\"#tab:key_wfo\">6.41<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.29.4\"><\/a><\/p>\n<h3>\n6.29.4  Input data<\/h3>\n<p>Typically, three types of input need to be provided: AO overlaps, MO coefficients, and a combined file with determinant information and CI coefficients (cf. Figure <a href=\"#fig:work\">6.5<\/a>).<br \/>\nThe file formats are explained here.<br \/>\nWithin S<span style=\"font-size:x-small\">HARC<\/span>, these files are automatically extracted or converted by the interfaces, so the user does not need to create them.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>AO overlaps  <\/b><br \/>\nThe mixed AO overlaps < χ<sub>μ<\/sub>|χ<sub>ν<\/sub>′ > between the AOs used to expand the bra and ket wavefunctions are required.<br \/>\nThey are in general created by a “double molecule” calculation, i.e. an AO integral calculation where every atom is found twice in the input file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The native format (<b><tt>ao_read=0<\/tt><\/b>) is a simple ASCII file containing the relevant off-diagonal block of the mixed AO overlap matrix, e.g.<\/p>\n<div class=\"p\"><!----><\/div>\n<pre>\n   7 7\n     9.97108464676133E-001    2.36720699813181E-001   ...\n     2.36720699813181E-001    9.99919192433940E-001   ...\n     1.00147985713321E-002    6.52340422397770E-003   ...\n         ...\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>In addition, M<span style=\"font-size:x-small\">OLCAS<\/span> (<b><tt>ao_read=1<\/tt><\/b>) and C<span style=\"font-size:x-small\">OLUMBUS<\/span>\/SIFS (<b><tt>ao_read=2<\/tt><\/b>) files can be read in binary form.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the same AOs are used for the bra and ket wavefunctions and the MO coefficient matrix is square, it is possible to reconstruct the overlaps by inversion of the MO coefficient matrix (<b><tt>ao_read=-1<\/tt><\/b>).<br \/>\nIn this case it is not necessary to supply a <b><tt>mix_aoovl<\/tt><\/b> file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>MO coefficients  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>MO coefficients of the bra and ket wavefunctions can usually be read in directly in the form written by the quantum chemistry program.<br \/>\nThe supported options for <b><tt>a_mo_read<\/tt><\/b> and <b><tt>b_mo_read<\/tt><\/b> are <b><tt>0<\/tt><\/b> for C<span style=\"font-size:x-small\">OLUMBUS<\/span> format, <b><tt>1<\/tt><\/b> for M<span style=\"font-size:x-small\">OLCAS<\/span> lumorb format, and <b><tt>2<\/tt><\/b> for T<span style=\"font-size:x-small\">URBOMOLE<\/span> format.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Because the number of electrons strongly affects the run time of <b><tt>wfoverlap.x<\/tt><\/b>, it is generally beneficial to apply a frozen core approximation, even if the actual wave function calculation did not do so.<br \/>\nMost interfaces which use <b><tt>wfoverlap.x<\/tt><\/b> have a keyword <b><tt>numfrozcore<\/tt><\/b> in the resource file, which only affects the number of frozen core orbitals for the overlap calculation (If the interface support frozen core for the quantum chemistry itself, there will be a keyword in the template file).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Slater determinants and CI coefficients  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Slater determinants and CI coefficients are currently supplied by an ASCII file of the form<\/p>\n<pre>\n3 7 168\ndddddee   0.979083342437    0.979083342437   -0.122637656388\nddddabe  -0.094807515471   -0.094807515471   -0.663224542162\nddddbae   0.094807515471    0.094807515471    0.663224542162\n...\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The first line specifies<\/p>\n<ul>\n<li> the number of states (columns in the file),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> the number of MOs (length of the determinant strings), and\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> the number of determinants in the file (length of the file).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>Every subsequent line gives the determinant string and the corresponding CI coefficients for the different states.<br \/>\nThe following symbols are used in the determinant string:<\/p>\n<div class=\"p\"><!----><\/div>\n<ul>\n<br \/>d – doubly occupied<br \/>\n<br \/>a – singly occupied (α)<br \/>\n<br \/>b – singly occupied (β)<br \/>\n<br \/>e – empty<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>Most relevant for S<span style=\"font-size:x-small\">HARC<\/span> users, the <b><tt>wfoverlap.x<\/tt><\/b> program <em>fully considers all determinants inside these files<\/em>, without applying any form of truncation. Hence, truncation of long wave functions is done during the creation of the determinant files.<br \/>\nMost interfaces which write these files have a keyword <b><tt>wfthres<\/tt><\/b> in their resource file. This threshold is a number between 0.0 and 1.0, and is the minimum wave function norm to which the wave functions should be truncated. During truncation, the interfaces generally retain the largest-amplitude CI coefficients, and remove determinants with small coefficients, i.e., they find the truncated expansion with the fewest determinants which has a norm above the <b><tt>wfthres<\/tt><\/b>.<br \/>\nChoosing this threshold properly can very strongly affect the computational time spent in the overlap calculation. Generally, for CASSCF wave functions the threshold can be set to 1 (<b><tt>SHARC_MOLPRO.py<\/tt><\/b>, <b><tt>SHARC_MOLCAS.py<\/tt><\/b>, and <b><tt>SHARC_BAGEL.py<\/tt><\/b> always use all determinants and do not have the <b><tt>wfthres<\/tt><\/b> option), for TDA-DFT\/ADC(2) it should usually be well above 0.99, for and for MRCI wave functions it might be necessary to go as low as 0.95, depending on the accuracy and performance needed.<br \/>\nFor TD-DFT calculations without the Tamm-Damcoff approximation, the response vectors are usually normalized to |<b>X<\/b>|<sup>2<\/sup>−|<b>Y<\/b>|=1, but only <b>X<\/b> is used in the overlap calculation; since the norm of <b>X<\/b> can thus exceed 1, the <b><tt>wfthres<\/tt><\/b> should be increased above 1, too.<br \/>\nAs a rule of thumb, the threshold should always be chosen such that each state is represented by at least a few 100 determinants in the file, in order to obtain smoothly varying overlaps.<br \/>\nIf unsure, the user should perform a test calculation, varying the <b><tt>wfthres<\/tt><\/b> until a suitable one is found (i.e., with as many determinants as possible such that the cost of the overlap calculation is bearable).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc6.29.5\"><\/a><\/p>\n<h3>\n6.29.5  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Usually, the output of <b><tt>wfoverlap.x<\/tt><\/b> is automatically extracted by the interfaces, and reported in <b><tt>QM.out<\/tt><\/b> in the overlap or 2D-property sections.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Wavefunction overlaps  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The output first lists some information about the wavefunction structure and about the computational time taken for the individual steps (cf. Figure <a href=\"#fig:work\">6.5<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A typical result of a wavefunction overlap computation is shown here:<\/p>\n<pre>\n Overlap matrix <PsiA_i|PsiB_j>\n                |PsiB  1>     |PsiB  2>\n<PsiA  1|    0.5162656622 -0.2040109070\n<PsiA  2|   -0.2167057391 -0.5266552021\n Renormalized overlap matrix <PsiA_i|PsiB_j>\n                |PsiB  1>     |PsiB  2>\n<PsiA  1|    0.5162656622 -0.2040109070\n<PsiA  2|   -0.2167057391 -0.5266552021\n Performing Lowdin orthonormalization by SVD...\n Orthonormalized overlap matrix <PsiA_i|PsiB_j>\n                |PsiB  1>     |PsiB  2>\n<PsiA  1|    0.9273847015 -0.3741090956\n<PsiA  2|   -0.3741090956 -0.9273847015\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>Overlap matrix<\/tt><\/b> gives the raw overlap values<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-19.png\">\n<\/td>\n<td width=\"1%\">(6.16)<\/td>\n<\/tr>\n<\/table>\n<p>of the wavefunctions supplied.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>Renormalized overlap matrix<\/tt><\/b> gives the renormalized overlap values<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-20.png\">\n<\/td>\n<td width=\"1%\">(6.17)<\/td>\n<\/tr>\n<\/table>\n<p>relevant in the case of wavefunction truncation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>Orthonormalized overlap matrix<\/tt><\/b> is constructed according to a procedure described in more detail in Ref. <a href=\"#Plasser2016JCTC\" class=\"tth_citeref\">[54<\/a>].<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Dyson orbitals  <\/b><br \/>\nThe matrix of Dyson norms is printed at the end of the file<\/p>\n<div class=\"p\"><!----><\/div>\n<pre>\n ALPHA ionization\n Dyson norm matrix |<PsiA_i|PsiB_j>|^2                                          \n                |PsiB  1>     |PsiB  2>     |PsiB  3>                           \n<PsiA  1|    0.8817323437  0.4716319904  0.0680618001                           \n<PsiA  2|    0.0615587916  0.4657174978  0.8772909828                           \n<PsiA  3|    0.0000000000  0.0363130811  0.0000000000                           \n<PsiA  4|    0.9634885049  0.0000000000  0.0017379586                           \n<PsiA  5|    0.0000000000  0.9261839484  0.0000000000 \n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>In the case of <b><tt>moprint=1<\/tt><\/b> the orbitals are printed, as well.<br \/>\nThe expansion is given with respect to the MOs of the neutral system.<\/p>\n<pre>\n  Dyson orbitals in reference |ket> MO basis:                                   \n<PsiA  1|                                                                       \n         |PsiB   1>      |PsiB   2>      |PsiB   3>                             \nMO     1 -1.24032037E-03  0.00000000E+00  9.98160731E-04                        \nMO     2 -5.90277699E-02  0.00000000E+00  6.14517859E-02                        \nMO     3 -1.23295110E-09  0.00000000E+00  3.08416849E-10                        \nMO     4  0.00000000E+00 -6.86713110E-01  0.00000000E+00                        \nMO     5  9.31351013E-01  0.00000000E+00 -2.49427166E-01                        \nMO     6 -3.50106110E-02  0.00000000E+00  4.19935829E-02\nMO     7 -1.83303166E-10  0.00000000E+00 -3.67409953E-12                        \nMO     8 -1.91183349E-10  0.00000000E+00  9.40768334E-11 \n...\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_chAp7\"><\/a><\/p>\n<h1>\nChapter 7 <br \/>Auxilliary Scripts<\/h1>\n<p><a id=\"chap:aux\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this chapter, all auxiliary scripts and programs are documented. Input generators (like <b><tt>molpro_input.py<\/tt><\/b> and <b><tt>molcas_input.py<\/tt><\/b>) are documented in the relevant interface sections.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>All auxiliary scripts are either interactive-prompting user input from stdin in order to setup a certain task-or non-interactive, meaning they are controlled by command-line arguments and options, in the same way as many standard command-line tools work.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>All interactive scripts sequentially ask a number of questions to the user. In many cases, a default value is presented, which is either preset or detected by the scripts based on the availability of certain files. Furthermore, the scripts feature auto-completion of paths and filenames (use TAB), which is active only in questions where auto-completion is relevant. For certain questions where lists of integers needs to be entered, ranges can be indicated with the tilde symbol (), e.g., <b><tt>-8-2<\/tt><\/b> (note that no spaces are allowed between the tilde and the two numbers) to indicate the list <b><tt>-8 -7 -6 -5 -4 -3 -2<\/tt><\/b>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>All interactive scripts write a file called <b><tt>KEYSTROKES.<script_name><\/tt><\/b> which contains the user input from the last completed session. These files can be piped to the interactive scripts to perform the same task again, for example:<\/p>\n<pre>\nuser@host> cat KEYSTROKES.excite - | $SHARC\/excite.py\n<\/pre>\n<p>Note the <b><tt>-<\/tt><\/b>, which tells <b><tt>cat<\/tt><\/b> to switch to stdin after the file ends, so that the user can proceed if the script asks for more input than contained in the <b><tt>KEYSTROKES<\/tt><\/b> file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>All non-interactive scripts can be called with the <b><tt>-h<\/tt><\/b> option to obtain a short description, usage information and a list of the command line options.<br \/>\nNon-interactive scripts also write a <b><tt>KEYSTROKES.<script_name><\/tt><\/b> file, which will contain the last command entered to execute the script (including all options and arguments).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>All scripts can be safely killed during a run by using <b><tt>Ctrl-C<\/tt><\/b>. In the case of interactive scripts, a <b><tt>KEYSTROKES.tmp<\/tt><\/b> file remains, containing the user input made so far. Note that the <b><tt>KEYSTROKES.tmp<\/tt><\/b> file cannot be directly piped to the scripts, because <b><tt>KEYSTROKES.tmp<\/tt><\/b> will be overwritten when the script starts.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.1\"><\/a><\/p>\n<h2>\n7.1  Wigner Distribution Sampling: <b><tt>wigner.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:wigner.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The first step in preparing the dynamics calculation is to obtain a set of physically reasonable initial conditions. Each initial condition is a set of initial atomic coordinates, initial atomic velocities and initial electronic state. The initial geometry and velocities can be obtained in different ways. With S<span style=\"font-size:x-small\">HARC<\/span>, often sampling of a quantum-harmonic Wigner distribution is performed. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The sampling is carried out with the non-interactive Python script <b><tt>wigner.py<\/tt><\/b>. The theoretical background is summarized in Section <a href=\"#met:wigner\">8.24<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.1.1\"><\/a><\/p>\n<h3>\n7.1.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The general usage is <\/p>\n<pre>\nuser@host> $SHARC\/wigner.py [options] filename.molden\n<\/pre>\n<p><b><tt>wigner.py<\/tt><\/b> takes exactly one command-line argument (the input file with the frequencies and normal modes), plus some options. Usually, the <b><tt>-n<\/tt><\/b> option is necessary, since the default is to only create 3 initial conditions.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The argument is the filename of the file containing the information about the vibrational frequencies and normal modes. The file is by default assumed to be in the <a href=\"http:\/\/www.theochem.ru.nl\/molden\/molden_format.html\"> M<span style=\"font-size:x-small\">OLDEN<\/span> format<\/a>. For usage with <b><tt>wigner.py<\/tt><\/b>, only the following blocks have to be present:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\">\n<tr>\n<td><\/td>\n<td>\n<table border=\"0\">\n<tr>\n<td>\n<ul>\n<li> [FREQ]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> [FR-COORD]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> [FR-NORM-COORD]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<\/table>\n<p><!--vbox-->\n<\/td>\n<td><\/td>\n<\/tr>\n<\/table>\n<p><!--hboxt-->The script accepts a number of command-line options, specified in table <a href=\"#tab:wigner_opts\">7.1<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.1\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.1: Command-line options for script <b><tt>wigner.py<\/tt><\/b>.<\/div>\n<p> <a id=\"tab:wigner_opts\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td width=\"355\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit <\/td>\n<td width=\"355\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-n INTEGER <\/td>\n<td align=\"left\">Number of initial conditions to generate <\/td>\n<td width=\"355\">3 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-m <\/td>\n<td align=\"left\">Modify atom masses (starts interactive dialog) <\/td>\n<td width=\"355\">Most common isotopes <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-s FLOAT <\/td>\n<td align=\"left\">Scaling factor for the frequencies <\/td>\n<td width=\"355\">1.0 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-t FLOAT <\/td>\n<td align=\"left\">Use Boltzmann-weighted distribution at the given temperature <\/td>\n<td width=\"355\">0.0 K<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-T <\/td>\n<td align=\"left\">Discard very high vibrational states at high temperatures <\/td>\n<td width=\"355\">Don’t discard, but warn<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-L FLOAT <\/td>\n<td align=\"left\">Discard frequencies below the given one (in cm<sup>−1<\/sup>) <\/td>\n<td width=\"355\">10.0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-o FILENAME <\/td>\n<td align=\"left\">Output filename <\/td>\n<td width=\"355\"><b><tt>initconds<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-x <\/td>\n<td align=\"left\">Creates an xyz file with the sampled geometries <\/td>\n<td width=\"355\"><b><tt>initconds.xyz<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-l <\/td>\n<td align=\"left\">Instead of generating <b><tt>initconds<\/tt><\/b>, create input for <b><tt>SHARC_LVC.py<\/tt><\/b> <\/td>\n<td width=\"355\">Create <b><tt>initconds<\/tt><\/b><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-r INTEGER <\/td>\n<td align=\"left\">Seed for random number generator <\/td>\n<td width=\"355\">16661 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-f F <\/td>\n<td align=\"left\">Type of normal modes read (0=detect automatically, 1-4=see below) <\/td>\n<td width=\"355\">0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-keep_trans_rot <\/td>\n<td align=\"left\">Do not remove translations and rotations from velocity vector <\/td>\n<td width=\"355\">Remove them<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-use_eq_geom <\/td>\n<td align=\"left\">Sample only velocities, but keep equilibrium geometry <\/td>\n<td width=\"355\">Sample normally<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-use_zero_veloc <\/td>\n<td align=\"left\">Sample only geometries, but set velocities to zero <\/td>\n<td width=\"355\">Sample normally<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-dummy_molecule <\/td>\n<td align=\"left\">Produce a file with n initial conditions for a single hydrogen atom at the origin and zero velocities<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-single_atom EL <\/td>\n<td align=\"left\">Produce a file with n initial conditions for a single atom of element <b><tt>EL<\/tt><\/b> at the origin and zero velocities<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.1.2\"><\/a><\/p>\n<h3>\n7.1.2  Normal mode types<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The normal mode vectors contained in a M<span style=\"font-size:x-small\">OLDEN<\/span> file can follow different conventions, e.g., unscaled Cartesian displacements or different kinds of mass-weighted displacements.<br \/>\nBy default, <b><tt>wigner.py<\/tt><\/b> attempts to identify which convention is followed by the file (by performing different renormalizations and checking if the so-obtained matrix is orthogonal).<br \/>\nIn order to use this automatic detection, use <b><tt>-f 0<\/tt><\/b>, which is the default.<br \/>\nOtherwise, there are four possible options: <b><tt>-f 1<\/tt><\/b> to assume normal modes in the G<span style=\"font-size:x-small\">AUSSIAN<\/span> convention (used by G<span style=\"font-size:x-small\">AUSSIAN<\/span>, T<span style=\"font-size:x-small\">URBOMOLE<\/span>, Q-C<span style=\"font-size:x-small\">HEM<\/span>, ADF, and O<span style=\"font-size:x-small\">RCA<\/span>); <b><tt>-f 2<\/tt><\/b> to assume Cartesian normal modes (used by M<span style=\"font-size:x-small\">OLCAS<\/span> and M<span style=\"font-size:x-small\">OLPRO<\/span>); <b><tt>-f 3<\/tt><\/b> to assume the C<span style=\"font-size:x-small\">OLUMBUS<\/span> convention; or <b><tt>-f 4<\/tt><\/b> for mass-weighted, orthogonal normal modes.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.1.3\"><\/a><\/p>\n<h3>\n7.1.3  Non-default masses<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>When the <b><tt>-m<\/tt><\/b> option is used, the script will ask the user to interactively modify the atom masses. For each atom (referred to by the atom index as in the M<span style=\"font-size:x-small\">OLDEN<\/span> file), a mass can be given (relative atomic weights). Note that the frequency calculation which produces the M<span style=\"font-size:x-small\">OLDEN<\/span> should be done with the same atomic masses.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.1.4\"><\/a><\/p>\n<h3>\n7.1.4  Sampling at finite temperatures<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>When the <b><tt>-t<\/tt><\/b> option is used, the script assumes a finite, non-zero temperature.<br \/>\nThe sampling will then consist of two steps, where first randomly a vibrational state is picked from the Boltzmann distribution, and then the Wigner distribution of that state is employed.<br \/>\nFor more details, see Section <a href=\"#met:wigner\">8.24<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>At high temperatures and for low-frequency modes it is possible that very large vibrational quantum numbers will be selected.<br \/>\nBecause of the occurrence of factorials in the Laguerre polynomials in the excited Wigner distributions, this leads to variable overflow for ν<sub>vib<\/sub> > 150. Hence, the highest vibrational quantum number considered is 150, and higher ones are set to 150.<br \/>\nSince this can lead to an overrepresentation of ν<sub>vib<\/sub>=150, with the <b><tt>-T<\/tt><\/b> option one can instead discard all samplings where ν<sub>vib<\/sub> > 150.<br \/>\nNo matter whether <b><tt>-T<\/tt><\/b> is used or not, keep in mind that usually such high vibrational states might invalidate the assumption of an harmonic oscillator, and other sampling methods (e.g., molecular dynamics) should be considered.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.1.5\"><\/a><\/p>\n<h3>\n7.1.5  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script <b><tt>wigner.py<\/tt><\/b> generates a single output file, by default called <b><tt>initconds<\/tt><\/b>. All information about the initial conditions is stored in this file. Later steps in the preparation of the initial conditions add information about the excited states to this file. The file is formatted in a human-readable form.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>initconds<\/tt><\/b> file format is specified in section <a href=\"#sec:initcondsfile\">7.9.4<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When the <b><tt>-x<\/tt><\/b> option is given, additionally the script produces a file called <b><tt>initconds.xyz<\/tt><\/b>, which contains the sampled geometries in standard xyz format. This can be useful to inspect the distribution of geometry parameters (e.g., bond lengths) or to perform single point calculations at the sampled geometries.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When the <b><tt>-l<\/tt><\/b> option is given, the script only produces a file called <b><tt>V0.txt<\/tt><\/b>, which is a necessary input file for the LVC interface (see section <a href=\"#sec:int:lvc\">6.4<\/a>). If this option is activated, no <b><tt>initconds<\/tt><\/b> or <b><tt>initconds.xyz<\/tt><\/b> files are produced.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.2\"><\/a><\/p>\n<h2>\n7.2  Vibrational State Selected Sampling: <b><tt>wigner_state_selected.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:wigner_state_selected.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In addition to <b><tt>wigner.py<\/tt><\/b> one can use <b><tt>wigner_state_selected.py<\/tt><\/b> to perform vibrational-state-selected initial conditions.<br \/>\nIn that situation, one can specify the vibrational level for each normal mode. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.2.1\"><\/a><\/p>\n<h3>\n7.2.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The general usage is <\/p>\n<pre>\nuser@host> $SHARC\/wigner_state_selected.py [options] filename.molden\n<\/pre>\n<p><b><tt>wigner_state_selected.py<\/tt><\/b> takes exactly one command-line argument (the input file with the frequencies and normal modes), plus some options. Usually, the <b><tt>-vibselec<\/tt><\/b>, <b><tt>-vibdist<\/tt><\/b>, <b><tt>-vibstate<\/tt><\/b> or <b><tt>-vibene<\/tt><\/b>, and <b><tt>-n<\/tt><\/b> options are necessary, the default is to only create 3 initial conditions.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Like <b><tt>wigner.py<\/tt><\/b>, the argument is the filename of the file containing the information about the vibrational frequencies and normal modes. The file is by default assumed to be in the <a href=\"http:\/\/www.theochem.ru.nl\/molden\/molden_format.html\"> M<span style=\"font-size:x-small\">OLDEN<\/span> format<\/a>.<br \/>\nOnly the following blocks have to be present:<\/p>\n<ul>\n<li> [FREQ]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> [FR-COORD]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> [FR-NORM-COORD]\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>The script accepts a number of command-line options, specified in Table <a href=\"#tab:state_selected_opts\">7.2<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The descriptions of the main options <b><tt>-vibselect<\/tt><\/b>, <b><tt>-vibdist<\/tt><\/b>, <b><tt>-vibstate<\/tt><\/b>, <b><tt>-vibene<\/tt><\/b>, <b><tt>-method<\/tt><\/b>, and <b><tt>-template<\/tt><\/b> will be described in next section. <\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.2\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.2: Command-line options for script <b><tt>wigner_state_selected.py<\/tt><\/b>.<\/div>\n<p> <a id=\"tab:state_selected_opts\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td width=\"355\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-vibselect <\/td>\n<td align=\"left\">Method for the vibrational energy (possible: 1, 2, 4-7). <\/td>\n<td width=\"355\">6 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-vibdist <\/td>\n<td align=\"left\">Method for the phase space distribution (possible: 0, 1, 2). <\/td>\n<td width=\"355\">0 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-vibstate <\/td>\n<td align=\"left\">List of vibrational state for each mode. <\/td>\n<td width=\"355\">0 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-viblist <\/td>\n<td align=\"left\">Method to assign mode with the non-zero vibrational level. <\/td>\n<td width=\"355\">0 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-vibene <\/td>\n<td align=\"left\">List of vibrational energy for each model <\/td>\n<td width=\"355\">0.0 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-method <\/td>\n<td align=\"left\">Method for the computation of the energy (possible: 0, 1) <\/td>\n<td width=\"355\">0 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-template <\/td>\n<td align=\"left\">name of the template file to interface with electronic structure (see below). This is only needed when using <b><tt>-method 1<\/tt><\/b>. <\/td>\n<td width=\"355\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit <\/td>\n<td width=\"355\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-n INTEGER <\/td>\n<td align=\"left\">Number of initial conditions to generate <\/td>\n<td width=\"355\">3 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-m <\/td>\n<td align=\"left\">Modify atom masses (starts interactive dialog) <\/td>\n<td width=\"355\">Most common isotopes <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-s FLOAT <\/td>\n<td align=\"left\">Scaling factor for the frequencies <\/td>\n<td width=\"355\">1.0 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-t FLOAT <\/td>\n<td align=\"left\">Use Boltzmann-weighted distribution at the given temperature <\/td>\n<td width=\"355\">0.0 K<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-T <\/td>\n<td align=\"left\">Discard very high vibrational states at high temperatures <\/td>\n<td width=\"355\">Don’t discard, but warn<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-L FLOAT <\/td>\n<td align=\"left\">Discard frequencies below the given one (in cm<sup>−1<\/sup>) <\/td>\n<td width=\"355\">10.0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-o FILENAME <\/td>\n<td align=\"left\">Output filename <\/td>\n<td width=\"355\"><b><tt>initconds<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-x <\/td>\n<td align=\"left\">Creates an xyz file with the sampled geometries <\/td>\n<td width=\"355\"><b><tt>initconds.xyz<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-r INTEGER <\/td>\n<td align=\"left\">Seed for random number generator <\/td>\n<td width=\"355\">16661 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-f F <\/td>\n<td align=\"left\">Type of normal modes read (0=detect automatically, 1-4=see below) <\/td>\n<td width=\"355\">0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-keep_trans_rot <\/td>\n<td align=\"left\">Do not remove translations and rotations from velocity vector <\/td>\n<td width=\"355\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-use_eq_geom <\/td>\n<td align=\"left\">Sample only velocities, but keep equilibrium geometry <\/td>\n<td width=\"355\">Sample normally<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-use_zero_veloc <\/td>\n<td align=\"left\">Sample only geometries, but set velocities to zero <\/td>\n<td width=\"355\">Sample normally<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.2.2\"><\/a><\/p>\n<h3>\n7.2.2  Major options<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>wigner_state_selected.py<\/tt><\/b> script involves five major options to perform vibrational state selection.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-vibselect<\/tt><\/b> determines the method to select the vibrational mode energy:<\/p>\n<ul>\n<br \/> <b><tt>-vibselect 1<\/tt><\/b>: the user will provide a list of vibrational quantum numbers; this will require the keyword <b><tt>-vibstate<\/tt><\/b>.<br \/>\n<br \/> <b><tt>-vibselect 2<\/tt><\/b>: the program will assign vibrational quantum numbers for each mode. This assignment is random, and selected out of a Boltzmann distribution at a user-specified temperature from option <b><tt>-t<\/tt><\/b>.<br \/>\n<br \/> <b><tt>-vibselect 3<\/tt><\/b>: the program generates an initial velocity from a Maxwell thermal distribution at a given temperature from option <b><tt>-t<\/tt><\/b>. This is an option for canonical ensembles, not an option for state-selected ensembles. <b>This option is not available at the moment<\/b>.<br \/>\n<br \/> <b><tt>-vibselect 4<\/tt><\/b>: the amount of energy in each mode is the same, and is set by option <b><tt>-vibene E<\/tt><\/b>, where <b><tt>E<\/tt><\/b> is the energy of each mode in eV.<br \/>\n<br \/> <b><tt>-vibselect 5<\/tt><\/b>: the amount of energy in each mode is different, and is set option by <b><tt>-vibene E1,E2,E3,...<\/tt><\/b>, where <b><tt>E1,E2,E3,...<\/tt><\/b> is a list of energies in eV for each mode.<br \/>\n<br \/> <b><tt>-vibselect 6<\/tt><\/b>: default, similar as <b><tt>-vibselect 4<\/tt><\/b>, but the energy of each mode is computed as minimum of zero point energy and E.<br \/>\n<br \/> <b><tt>-vibselect 7<\/tt><\/b>: similar as <b><tt>-vibselect 5<\/tt><\/b>, but the energy of each mode is computed as minimum of zero point energy and E<sub>I<\/sub>, where I is the index of the mode.<\/ul>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-vibdist<\/tt><\/b> determines the type of phase space distribution:<\/p>\n<ul>\n<br \/> <b><tt>-vibdist 0<\/tt><\/b>: default, uses quasiclassical or classical distribution. It is a uniform distribution. It is quasiclassical if vibselect=1 or 2 and classical if vibselect ≥ 4.<br \/>\n<br \/> <b><tt>-vibdist 1<\/tt><\/b>: ground state harmonic oscillator distribution.<br \/>\n<br \/> <b><tt>-vibdist 2<\/tt><\/b>: Wigner distribution.<\/ul>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-vibstate<\/tt><\/b> is a quantum number for all modes or list of vibrational quantum numbers for each mode.<br \/>\nFor example, <b><tt>-vibstate 0<\/tt><\/b> specifies all vibrational mode with quantum number 0, i.e. all mode have only zero point energy.<br \/>\n<b><tt>-vibstate 0,1,2,...<\/tt><\/b> specifies the quantum number for each mode, in this example, the first three modes have vibrational quantum numbers 0, 1, and 2, respectively.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-viblist<\/tt><\/b> is a list of vibrational quantum numbers for all modes whose vibrational quantum number are non-zero, and the rest modes are all set to zero.<br \/>\nThis is convenient if one is setting up an initial condition for which most modes’ vibrational quantum number are zero, and only several modes’ quantum number are non-zero. For example, <b><tt>-viblist 1,1?5,3<\/tt><\/b> specifies all vibrational mode with 0 quantum number, except mode 1 and mode 5; mode 1 has vibrational quantum number 1, and mode 5 has vibrational quantum number 3.<br \/>\nPairs of numbers, i.e., mode and corresponding vibrational quantum number are separated by “?”. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-vibene<\/tt><\/b> is a vibrational energy for all modes or a list of vibrational energies for each mode.<br \/>\nFor example, <b><tt>-vibene 0.2<\/tt><\/b> specifies all vibrational mode with 0.2 eV of vibrational energy.<br \/>\n<b><tt>-vibene 0.1,0.2,0.1,...<\/tt><\/b> specifies the vibrational energy for each mode, in this example, the first three modes have vibrational energies of 0.1 eV, 0.2 eV, and 0.1 eV, respectively. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-method<\/tt><\/b> determines how energies are computed for geometries away from the equilibrium structure.<br \/>\nWith the default <b><tt>-method 0<\/tt><\/b>, the harmonic oscillator approximation, using the provided normal modes, is used.<br \/>\nWith <b><tt>-method 1<\/tt><\/b>, at each geometry an electronic structure calculation is performed, using the additional option <b><tt>-template<\/tt><\/b>, which specifies a script that interfacing with electronic structure calculations.<br \/>\n<b>Note that <b><tt>-method 1<\/tt><\/b> is not recommended, because one can also perform electronic structure calculations at all displaced geometries later, using <b><tt>setup_init.py<\/tt><\/b> and the S<span style=\"font-size:x-small\">HARC<\/span> interfaces.<br \/>\nThis allows to use all interfaced methods out-of-the-box without needing to write a template script, and is better supported in the rest of the S<span style=\"font-size:x-small\">HARC<\/span> workflow.<\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-template<\/tt><\/b> keyword follows by a file name that is a script serves as interface between the <b><tt>wigner_state_selected.py<\/tt><\/b> and electronic structure software.<br \/>\nWhen using ab initio potential, i.e., when set <b><tt>-method 1<\/tt><\/b>, the <b><tt>wigner_state_selected.py<\/tt><\/b> will write a file called <b><tt>tmp_state_selected.xyz<\/tt><\/b> everytime it samples a new geometry, and execute the script, then read the energy from an output file called <b><tt>energy_state_selected<\/tt><\/b>.<br \/>\nTherefore, the function of this user-defined script is to read <b><tt>tmp_state_selected.xyz<\/tt><\/b>, and write energy into file <b><tt>energy_state_selected<\/tt><\/b>.<br \/>\nSee the next subsection for an example.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.2.3\"><\/a><\/p>\n<h3>\n7.2.3  Template<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The following bash script shows an example of a template.<br \/>\nThe script reads the <b><tt>tmp_state_selected.xyz<\/tt><\/b>, write a Gaussian density functional calculation with MN15 functional and def2-TZVP basis set, and stores the density functional energy into file <b><tt>energy_state_selected<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<pre>\n#!\/bin\/bash\n#write a Gaussian input\necho \"%Chk=e.chk\" > e1.tmp\necho \"%Mem=11800mb\" >> e1.tmp\necho \"#P def2TZVP SCF=(Tight,novracc,maxcycle=500) Integral(Grid=UltraFine) MN15\" >> e1.tmp\necho \"  \" >> e1.tmp\necho \"my molecule\" >> e1.tmp\necho \"0  1\" >> t1.tmp\necho \"  \" > e2.tmp\necho \"  \" >> e2.tmp\ncat e1.tmp tmp_state_selected.xyz e2.tmp > e.com \n#run a Gaussian calculation\n\/software\/g09\/g09 < e.com > e.out\n#save the energy into energy_state_selected\ngrep 'SCF Done' e.out|awk '{print $5}' > energy_state_selected\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.2.4\"><\/a><\/p>\n<h3>\n7.2.4  Normal mode types<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The normal mode vectors contained in a M<span style=\"font-size:x-small\">OLDEN<\/span> file can follow different conventions, e.g., unscaled Cartesian displacements or different kinds of mass-weighted displacements.<br \/>\nBy default, <b><tt>wigner_state_selected.py<\/tt><\/b> attempts to identify which convention is followed by the file (by performing different renormalizations and checking if the so-obtained matrix is orthogonal).<br \/>\nIn order to use this automatic detection, use <b><tt>-f 0<\/tt><\/b>, which is the default.<br \/>\nOtherwise, there are four possible options: <b><tt>-f 1<\/tt><\/b> to assume normal modes in the G<span style=\"font-size:x-small\">AUSSIAN<\/span> convention (used by G<span style=\"font-size:x-small\">AUSSIAN<\/span>, T<span style=\"font-size:x-small\">URBOMOLE<\/span>, Q-C<span style=\"font-size:x-small\">HEM<\/span>, ADF, and O<span style=\"font-size:x-small\">RCA<\/span>); <b><tt>-f 2<\/tt><\/b> to assume Cartesian normal modes (used by M<span style=\"font-size:x-small\">OLCAS<\/span> and M<span style=\"font-size:x-small\">OLPRO<\/span>); <b><tt>-f 3<\/tt><\/b> to assume the C<span style=\"font-size:x-small\">OLUMBUS<\/span> convention; or <b><tt>-f 4<\/tt><\/b> for mass-weighted, orthogonal normal modes.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.2.5\"><\/a><\/p>\n<h3>\n7.2.5  Non-default masses<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>When the <b><tt>-m<\/tt><\/b> option is used, the script will ask the user to interactively modify the atom masses. For each atom (referred to by the atom index as in the M<span style=\"font-size:x-small\">OLDEN<\/span> file), a mass can be given (relative atomic weights). Note that the frequency calculation which produces the M<span style=\"font-size:x-small\">OLDEN<\/span> should be done with the same atomic masses.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.2.6\"><\/a><\/p>\n<h3>\n7.2.6  Output<\/h3>\n<p>The script <b><tt>wigner_state_selected.py<\/tt><\/b> generates a single output file, by default called <b><tt>initconds<\/tt><\/b>. All information about the initial conditions is stored in this file. Later steps in the preparation of the initial conditions add information about the excited states to this file. The file is formatted in a human-readable form.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>initconds<\/tt><\/b> file format is specified in section <a href=\"#sec:initcondsfile\">7.9.4<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When the <b><tt>-x<\/tt><\/b> option is given, additionally the script produces a file called <b><tt>initconds.xyz<\/tt><\/b>, which contains the sampled geometries in standard xyz format. This can be useful to inspect the distribution of geometry parameters (e.g., bond lengths) or to perform single point calculations at the sampled geometries.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.3\"><\/a><\/p>\n<h2>\n7.3  Initial condition for collision dynamics: <b><tt>bimolecular_collision.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:bimolecular_collision.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script <b><tt>bimolecular_collision.py<\/tt><\/b> is used in the preparation and sampling of initial conditions for bimolecular collision processes.<br \/>\nThis is achieved by merging <b><tt>initconds<\/tt><\/b> files from other sources (e.g., <b><tt>wigner.py<\/tt><\/b> or <b><tt>wigner_state_selected.py<\/tt><\/b>).<br \/>\nThere are two operation modes.<br \/>\nIf one is performing a molecule + molecule collision dynamics, one needs to provide two <b><tt>initconds<\/tt><\/b> files.<br \/>\nFor a molecule + atom collision dynamics, one needs to provide only one<b><tt>initconds<\/tt><\/b> file and additionally the element of the colliding atom. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.3.1\"><\/a><\/p>\n<h3>\n7.3.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>To set up an initial condition for colliding two molecules (here we simply call an atom a special case of molecule to simplify the discussion), the following collision parameters are required: initial separation of the two molecules, impact parameter, and collision energy.<br \/>\nNotice that, currently, setting up relative angular momenta between the two molecules is not supported. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The general usage for a molecule + molecule collision process is:<\/p>\n<pre>\nuser@host> $SHARC\/bimolecular_collision.py [options] initconds1 initconds2\n<\/pre>\n<p>and for a molecule + atom process it is:<\/p>\n<pre>\nuser@host> $SHARC\/bimolecular_collision.py [options] initconds1\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>bimolecular_collision.py<\/tt><\/b> takes one or two command-line arguments (the <b><tt>initconds<\/tt><\/b> files), plus some options.<br \/>\nUsually, the <b><tt>-bmin<\/tt><\/b>, <b><tt>-bmax<\/tt><\/b>, <b><tt>-separation<\/tt><\/b>, <b><tt>-relative_trans<\/tt><\/b>, and <b><tt>-n<\/tt><\/b> options are necessary.<br \/>\nThe default is to only create 1 initial conditions.<br \/>\nThe list of all available options are shown in Table <a href=\"#tab:bimolecular_collision_opts\">7.3<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.3\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.3: Command-line options for script <b><tt>bimolecular_collision.py<\/tt><\/b>.<\/div>\n<p> <a id=\"tab:bimolecular_collision_opts\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td width=\"355\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-atom <\/td>\n<td align=\"left\">The element used in molecular + atom collision dynamics (string). <\/td>\n<td width=\"355\">“H” <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-bmin <\/td>\n<td align=\"left\">minimum of impact parameter. <\/td>\n<td width=\"355\">0.0 (Å) <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-bmax <\/td>\n<td align=\"left\">maximum of impact parameter. <\/td>\n<td width=\"355\">5.0 (Å) <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-strata <\/td>\n<td align=\"left\">number of strata used in sampling impact parameter. <\/td>\n<td width=\"355\">1 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-separation <\/td>\n<td align=\"left\">initial separation between the two molecules <\/td>\n<td width=\"355\">10.0 (Å) <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-relative_trans <\/td>\n<td align=\"left\">relative translational energy between the two molecules. <\/td>\n<td width=\"355\">1.0 (eV) <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-no_random_orient <\/td>\n<td align=\"left\">not randomly re-orient each molecules. <\/td>\n<td width=\"355\">False <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-n INTEGER <\/td>\n<td align=\"left\">Number of initial conditions to generate <\/td>\n<td width=\"355\">3 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-o FILENAME <\/td>\n<td align=\"left\">Output filename <\/td>\n<td width=\"355\"><b><tt>initconds<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-x <\/td>\n<td align=\"left\">Creates an xyz file with the sampled geometries <\/td>\n<td width=\"355\"><b><tt>initconds.xyz<\/tt><\/b> <\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.3.2\"><\/a><\/p>\n<h3>\n7.3.2  Usage<\/h3>\n<p>The <b><tt>bimolecular_collision.py<\/tt><\/b> has seven major options. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-atom<\/tt><\/b> to specify the element used in molecule + atom collision dynamics. For example, <b><tt>-atom \"H\"<\/tt><\/b>, to specify a hydrogen atom.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Three options are used to randomly sample the impact parameter, where <b><tt>-bmin<\/tt><\/b> specifies the minimum impact parameter, <b><tt>-bmax<\/tt><\/b> specifies the maximum impact parameter, and <b><tt>-strata<\/tt><\/b> specifies how many strata are used in the stratified sampling of impact parameter.<br \/>\nFor example, <b><tt>-bmin 0.0 -bmax 5.0 -strata 1<\/tt><\/b> means the sampled impact parameter is in range 0.0 to 5.0 Å.<br \/>\nInstead, <b><tt>-bmin 0.0 -bmax 5.0 -strata 2<\/tt><\/b> means the first half of the initial conditions have impact parameter in range 0.0 to 2.5 Å, and the second half of the initial conditions have impact parameter in range of 2.5 to 5.0 Å.<br \/>\nThe stratified sampling is especially useful when trying to analyze the opacity function at the end of the trajectory simulation, i.e., one can observe how cross section changes as a function of impact parameter, and if the simulation is converged with respect to the impact parameter. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-separation<\/tt><\/b> sets the initial separation of the center of mass of the two molecules. The default value is 10 Å.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-relative_trans<\/tt><\/b> sets the initial relative translational energy between the two molecules in units of eV. The default is 1.0 eV.<br \/>\nNote that we are always letting molecule 2 collide towards molecule 1, so molecule 2 will receive the translational energy. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>-no_random_orient<\/tt><\/b> prevents the initial random re-orientation of the molecules.<br \/>\nNote that when we put two molecules together, one can re-orient each of the two molecules, and this is done by default.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.4\"><\/a><\/p>\n<h2>\n7.4   A<span style=\"font-size:x-small\">MBER<\/span> Trajectory Sampling: <b><tt>amber_to_initconds.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:amber_to_initconds.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The first step in preparing the dynamics calculation is to obtain a set of physically reasonable initial conditions. Each initial condition is a set of initial atomic coordinates, initial atomic velocities and initial electronic state. The initial geometry and velocities can be obtained in different ways.<br \/>\nBesides sampling from a quantum mechanical Wigner distribution (with <b><tt>wigner.py<\/tt><\/b>), it is a widespread approach to sample geometries and velocities from a ground state molecular dynamics simulation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>amber_to_initconds.py<\/tt><\/b>, one can convert the results of an A<span style=\"font-size:x-small\">MBER<\/span> simulation to a S<span style=\"font-size:x-small\">HARC<\/span> <b><tt>initconds<\/tt><\/b> file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that one can instead work with <b><tt>restartnc_to_xyz.py<\/tt><\/b> (see Section <a href=\"#sec:restartnc_to_xyz.py\">7.6<\/a>), which is more complicated to use but avoids huge <b><tt>initconds<\/tt><\/b> files in very large projects.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.4.1\"><\/a><\/p>\n<h3>\n7.4.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In order to use <b><tt>amber_to_initconds.py<\/tt><\/b>, it is necessary to first carry out an A<span style=\"font-size:x-small\">MBER<\/span> simulation.<br \/>\nYou need to add the following options to the A<span style=\"font-size:x-small\">MBER<\/span> MD input file: (i) <b><tt>ntxo=1<\/tt><\/b> to tell A<span style=\"font-size:x-small\">MBER<\/span> to write ASCII restart files, (ii) <b><tt>ntwr=-5000<\/tt><\/b> to create a restart file every 5000 steps (other values are possible, but use the minus to not overwrite the restart files).<br \/>\nThis will create a set of A<span style=\"font-size:x-small\">MBER<\/span> restart files called, e.g., <b><tt>md.rst_5000<\/tt><\/b>, <b><tt>md.rst_10000<\/tt><\/b>, …<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that it is also necessary to reimage the A<span style=\"font-size:x-small\">MBER<\/span> restart files, because S<span style=\"font-size:x-small\">HARC<\/span> does not work with periodic boundary conditions, but the A<span style=\"font-size:x-small\">MBER<\/span> trajectories might use them.<br \/>\nThe reimaging can be performed with A<span style=\"font-size:x-small\">MBER<\/span>‘s tool <b><tt>cpptraj<\/tt><\/b>, using the following input:<\/p>\n<pre>\nparm <filename>.prmtop\ntrajin <filename>.rst7\nautoimage\ntrajout <filename2>.rst7\nrun\n<\/pre>\n<p>This command has to be repeated for each restart file which needs to be reimaged.<br \/>\nNote that <b><tt>amber_to_initconds.py<\/tt><\/b> only works with the <b><tt>rst7<\/tt><\/b> ASCII file format, not with the <b><tt>rst<\/tt><\/b> format (even if it is ASCII-formatted).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you saved the restart files in A<span style=\"font-size:x-small\">MBER<\/span>‘s newer NetCDF format, <b><tt>cpptraj<\/tt><\/b> can also be used to convert them to ASCII <b><tt>rst7<\/tt><\/b> restart files.<br \/>\nIf you did not save restart files, <b><tt>cpptraj<\/tt><\/b> can even be used to generate restart files from the trajectory file (<b><tt>.mdcrd<\/tt><\/b> and <b><tt>.mdvel<\/tt><\/b>), but for this way it is necessary to save the velocities (<b><tt>.mdvel<\/tt><\/b> file).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>With the restart files prepared, call <b><tt>amber_to_initconds.py<\/tt><\/b> like this:<\/p>\n<pre>\nuser@host> $SHARC\/amber_to_initconds.py [options] md.prmtop md.rst_0 md.rst_5000 md.rst_10000 ...\n<\/pre>\n<p>The possible options are shown in Table <a href=\"#tab:amber_opts\">7.4<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.4\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.4: Command-line options for script <b><tt>amber_to_initconds.py<\/tt><\/b>.<\/div>\n<p> <a id=\"tab:amber_opts\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td width=\"355\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit <\/td>\n<td width=\"355\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-t FLOAT <\/td>\n<td align=\"left\">Time step (in femtoseconds) used in the A<span style=\"font-size:x-small\">MBER<\/span> simulation <\/td>\n<td width=\"355\">–<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-o FILENAME <\/td>\n<td align=\"left\">Output filename <\/td>\n<td width=\"355\"><b><tt>initconds<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-x <\/td>\n<td align=\"left\">Creates an xyz file with the sampled geometries <\/td>\n<td width=\"355\"><b><tt>initconds.xyz<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-m <\/td>\n<td align=\"left\">Modify atom masses (starts interactive dialog) <\/td>\n<td width=\"355\">As in <b><tt>prmtop<\/tt><\/b> file <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-keep_trans_rot <\/td>\n<td align=\"left\">Do not remove translations and rotations from velocity vector <\/td>\n<td width=\"355\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-use_zero_veloc <\/td>\n<td align=\"left\">Sample only geometries, but set velocities to zero <\/td>\n<td width=\"355\">Sample normally<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.4.2\"><\/a><\/p>\n<h3>\n7.4.2  Time Step<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Note that the option <b><tt>-t<\/tt><\/b> (giving the time step used in A<span style=\"font-size:x-small\">MBER<\/span> in femtoseconds) is mandatory; if not given, an error message is produced.<br \/>\nThis is because A<span style=\"font-size:x-small\">MBER<\/span> uses a Leapfrog algorithm and thus stores in the restart file R(t) and v(t−∆t\/2), whereas S<span style=\"font-size:x-small\">HARC<\/span> uses the velocity-Verlet algorithm and requires geometry and velocity at the same time, e.g., R(t−∆t\/2) and v(t−∆t\/2).<br \/>\nTo compensate this, <b><tt>amber_to_initconds.py<\/tt><\/b> computes R(t−∆t\/2) from R(t)−v(t−∆t\/2)∆t\/2.<br \/>\nHence, ∆t of the A<span style=\"font-size:x-small\">MBER<\/span> trajectory needs to be known.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.4.3\"><\/a><\/p>\n<h3>\n7.4.3  Atom Types and Masses<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>By default, atom types and masses are read from the <b><tt>prmtop<\/tt><\/b> file (from flags <b><tt>ATOMIC_NUMBER<\/tt><\/b> and <b><tt>MASS<\/tt><\/b>).<br \/>\nIf the atomic number is not sensible (e.g., -1 for a transition metal) then <b><tt>amber_to_initconds.py<\/tt><\/b> prompts the user to define the element.<br \/>\nThe masses in the <b><tt>prmtop<\/tt><\/b> file can be overridden if the <b><tt>-m<\/tt><\/b> option is given; then the user can adjust the mass of each atom individually.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.4.4\"><\/a><\/p>\n<h3>\n7.4.4  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>amber_to_initconds.py<\/tt><\/b> produces the same output as <b><tt>wigner.py<\/tt><\/b> (section  <a href=\"#sec:wigner.py\">7.1<\/a>).<br \/>\nBy default, a file called <b><tt>initconds<\/tt><\/b> is generated for the converted initial conditions.<br \/>\nIt is important to note that the first restart file given (the second command line argument) is treated as the “equilibrium” geometry for the purpose of generating the <b><tt>initconds<\/tt><\/b> file.<br \/>\nThe second given restart file is then converted to the initial condition with index 1, and so on.<br \/>\nNote that it is possible to give the same restart file multiple times as an argument (so that the same geometry can be used as “equilibrium” geometry and as proper initial condition.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.5\"><\/a><\/p>\n<h2>\n7.5   S<span style=\"font-size:x-small\">HARC<\/span> Trajectory Sampling: <b><tt>sharctraj_to_initconds.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:sharctraj_to_initconds.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The first step in preparing the dynamics calculation is to obtain a set of physically reasonable initial conditions. Each initial condition is a set of initial atomic coordinates, initial atomic velocities and initial electronic state. The initial geometry and velocities can be obtained in different ways.<br \/>\nBesides sampling from a quantum mechanical Wigner distribution, it is often appropriate to sample geometries and velocities from a ground state molecular dynamics simulation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>sharctraj_to_initconds.py<\/tt><\/b>, one can convert the results of a S<span style=\"font-size:x-small\">HARC<\/span> simulation to a new S<span style=\"font-size:x-small\">HARC<\/span> <b><tt>initconds<\/tt><\/b> file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.5.1\"><\/a><\/p>\n<h3>\n7.5.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In order to use <b><tt>sharctraj_to_initconds.py<\/tt><\/b>, it is necessary to first run a number of S<span style=\"font-size:x-small\">HARC<\/span> trajectories (the initial conditions for those need to be obtained with <b><tt>wigner.py<\/tt><\/b> or <b><tt>amber_to_initconds.py<\/tt><\/b>).<br \/>\nThe trajectories can be run with any number of states and in any state, and with any desirable options; only geometries and velocities are converted to the new <b><tt>initconds<\/tt><\/b> file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>With the trajectories prepared, call <b><tt>sharctraj_to_initconds.py<\/tt><\/b> like this:<\/p>\n<pre>\nuser@host> $SHARC\/sharctraj_to_initconds.py [options] Singlet_0 ...\n<\/pre>\n<p>Alternatively, with the <b><tt>-give_TRAJ_paths<\/tt><\/b> option, one can also do:<\/p>\n<pre>\nuser@host> $SHARC\/sharctraj_to_initconds.py --give_TRAJ_paths [options] TRAJ_00001 TRAJ_00002 ...\n<\/pre>\n<p>The possible options are shown in Table <a href=\"#tab:sharctraj_opts\">7.5<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.5\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.5: Command-line options for script <b><tt>sharctraj_to_initconds.py<\/tt><\/b>.<\/div>\n<p> <a id=\"tab:sharctraj_opts\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td width=\"335\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit <\/td>\n<td width=\"335\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-r INTEGER <\/td>\n<td align=\"left\">Seed for the random number generator <\/td>\n<td width=\"335\">16661 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-S INTEGER INTEGER <\/td>\n<td align=\"left\">Range of time steps from which a step is randomly chosen <\/td>\n<td width=\"335\">last step <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-o FILENAME <\/td>\n<td align=\"left\">Output filename <\/td>\n<td width=\"335\"><b><tt>initconds<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-x <\/td>\n<td align=\"left\">Creates an xyz file with the sampled geometries <\/td>\n<td width=\"335\"><b><tt>initconds.xyz<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-keep_trans_rot <\/td>\n<td align=\"left\">Do not remove translations and rotations from velocity <\/td>\n<td width=\"335\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-use_zero_veloc <\/td>\n<td align=\"left\">Sample only geometries, but set velocities to zero <\/td>\n<td width=\"335\">Sample normally<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-debug <\/td>\n<td align=\"left\">Show timings <\/td>\n<td width=\"335\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-give_TRAJ_paths <\/td>\n<td align=\"left\">Allows specifying individual trajectories <\/td>\n<td width=\"335\">Specify parent directories<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.5.2\"><\/a><\/p>\n<h3>\n7.5.2  Random Picking of Time Step<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>For each directory specified as command line argument, <b><tt>sharctraj_to_initconds.py<\/tt><\/b> picks exactly one time step and extracts geometries and velocities of that time step.<br \/>\nNote that a directory can be given several times as argument, so that multiple time steps can be selected.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The time steps are generally picked randomly (uniform probabilities) from an interval specified with the <b><tt>-S<\/tt><\/b> option.<br \/>\nThis option takes two integers, e.g., <b><tt>-S 50 -50<\/tt><\/b>, which can be positive or negative.<br \/>\nThe meaning of positive\/negative\/zero is the same as in P<span style=\"font-size:x-small\">YTHON<\/span>: positive numbers simply denote a time step (start counting with zero for the step zero of the trajectory); for negative numbers, start counting at the end, i.e., -1 is the last time step of the trajectory.<br \/>\nIn this way, it is possible to select the snapshot from the last n steps of all trajectories, even if they have different length.<br \/>\nThe example above, <b><tt>-S 50 -50<\/tt><\/b>, means picking a time step between the 50th and the 50th-last step. Note that if a trajectory is shorter than 100 steps, in this example it is skipped because there are no steps between the 50th and the 50th-last step.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.5.3\"><\/a><\/p>\n<h3>\n7.5.3  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>sharctraj_to_initconds.py<\/tt><\/b> produces the same output as <b><tt>wigner.py<\/tt><\/b> (section  <a href=\"#sec:wigner.py\">7.1<\/a>).<br \/>\nBy default, a file called <b><tt>initconds<\/tt><\/b> is generated for the converted initial conditions.<br \/>\nIt is important to note that the first directory given (the first command line argument) is treated as the “equilibrium” geometry for the purpose of generating the <b><tt>initconds<\/tt><\/b> file.<br \/>\nThe second given directory is then converted to the initial condition with index 1, and so on.<br \/>\nNote that it is possible to give the same directory multiple times as an argument (so that the same geometry can be used as “equilibrium” geometry and as proper initial condition.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.6\"><\/a><\/p>\n<h2>\n7.6  Creating an XYZ file from an Amber restart file: <b><tt>restartnc_to_xyz.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:restartnc_to_xyz.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>With the script <b><tt>restartnc_to_xyz.py<\/tt><\/b> one can extract information from an Amber restart file and write the Cartesian coordinates to different files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are three different modes in which the script can operate.<br \/>\nIn the default mode, the script is producing output in xyz format.<br \/>\nThe velocities from the restart file are discarded.<br \/>\nOptionally, the script can pick up lines from a <b><tt>QM.in<\/tt><\/b> file and append to the xyz output.<br \/>\nIn the second mode, the script produces output in initconds file format.<br \/>\nIn the third mode, the script produces a <b><tt>geom<\/tt><\/b> and a <b><tt>veloc<\/tt><\/b> file (overwriting previous files in the present folder).<br \/>\nIn both cases, the velocities from the restart file are considered.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that this script, like <b><tt>amber_to_initconds.py<\/tt><\/b> (Section <a href=\"#sec:amber_to_initconds.py\">7.4<\/a>) modifies the geometries read from the restart file by rewinding half a time step.<br \/>\nThis is because Amber uses a Leapfrog algorithm, but S<span style=\"font-size:x-small\">HARC<\/span> uses the velocity Verlet algorithm.<br \/>\nThis is the reason why the time step is a required argument for <b><tt>restartnc_to_xyz.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.6.1\"><\/a><\/p>\n<h3>\n7.6.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>restartnc_to_xyz.py<\/tt><\/b> is a command line tool, and is executed like this:<\/p>\n<pre>\nuser@host> $SHARC\/restartnc_to_xyz.py -t <time step>  <prmtop file>  <restartnc file> > <output file>\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The options are summarized in Table <a href=\"#tab:restartnc_options\">7.6<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.6\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.6: Command-line options for <b><tt>restartnc_to_xyz.py<\/tt><\/b>. <\/div>\n<p> <a id=\"tab:restartnc_options\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit. <\/td>\n<td align=\"left\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-t <\/td>\n<td align=\"left\">Specify the timestep in fs that Amber used <\/td>\n<td align=\"left\">required.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-a <\/td>\n<td align=\"left\">Output in Angstrom <\/td>\n<td align=\"left\">in Bohr <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-q <\/td>\n<td align=\"left\">Append request lines from file ‘QMin’ <\/td>\n<td align=\"left\">do not append anything <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-i <\/td>\n<td align=\"left\">Produce output to append to initconds <\/td>\n<td align=\"left\">produce output in xyz format <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-g <\/td>\n<td align=\"left\">Produce geom and veloc files <\/td>\n<td align=\"left\">produce output in xyz format<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.6.2\"><\/a><\/p>\n<h3>\n7.6.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>Time step  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here, the user needs to specify the timestep that was used for the Amber dynamics (e.g., 2 fs).<br \/>\nThe output coordinates will be <span class=\"overacc2\">→<\/span>R<sub>output<\/sub>=<span class=\"overacc2\">→<\/span>R<sub>from rst<\/sub> − [1\/2]∆t <span class=\"overacc2\">→<\/span>v<sub>from rst<\/sub>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Prmtop file  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Specify the prmtop file of the system that was propagated in Amber so that the information on atom types etc. can be extracted.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Restartnc file  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Specify the Amber restart file (NetCDF format) containing the molecular dynamics data that should be extracted.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.6.3\"><\/a><\/p>\n<h3>\n7.6.3  Output<\/h3>\n<p>The extracted Cartesian coordinates and\/or velocities of each time step are put to the terminal in the specified format (XYZ or initconds).<br \/>\nIn case of the <b><tt>-g<\/tt><\/b> option, the <b><tt>geom<\/tt><\/b> and <b><tt>veloc<\/tt><\/b> files are written to the current directory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.7\"><\/a><\/p>\n<h2>\n7.7  Creating an XYZ file from a S<span style=\"font-size:x-small\">HARC<\/span> trajectory: <b><tt>sharctraj_to_xyz.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:sharctraj_to_xyz.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script <b><tt>sharctraj_to_xyz.py<\/tt><\/b> allows extraction of the geometries and velocities of a single time step from a SHARC NetCDF trajectory file and prints or writes them in the same three formats as <b><tt>restartnc_to_xyz.py<\/tt><\/b> (XYZ files, <b><tt>QM.in<\/tt><\/b> files, and <b><tt>geom<\/tt><\/b>\/<b><tt>veloc<\/tt><\/b> file pairs).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The main application for this script is in reusing geometries and velocities from a finished S<span style=\"font-size:x-small\">HARC<\/span> trajectory to create new initial conditions.<br \/>\nIt shares this task with <b><tt>sharctraj_to_initconds.py<\/tt><\/b>, which is intended for smaller projects and ASCII <b><tt>output.dat<\/tt><\/b> files and operates on an entire swarm of trajectories to produce a new <b><tt>initconds<\/tt><\/b> file.<br \/>\nIn contrast, <b><tt>sharctraj_to_xyz.py<\/tt><\/b> operates on a single NetCDF <b><tt>output.dat.nc<\/tt><\/b>\/<b><tt>output_NUC.dat.nc<\/tt><\/b> file and is intended for projects where dummy <b><tt>initconds<\/tt><\/b> files are used.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.7.1\"><\/a><\/p>\n<h3>\n7.7.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>sharctraj_to_xyz.py<\/tt><\/b> is a command-line tool and is executed as follows: <\/p>\n<pre> \nuser@host> $SHARC\/sharctraj_to_xyz.py [options] <geom> <output.dat.nc>\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The available command-line options are summarized in Table <a href=\"#tab:sharctraj_options\">7.7<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.7\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.7: Command-line options for <b><tt>sharctraj_to_xyz.py<\/tt><\/b>.<\/div>\n<p><a id=\"tab:sharctraj_options\"><br \/>\n<\/a> <\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit. <\/td>\n<td align=\"left\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-s <\/td>\n<td align=\"left\">Select time step (negative numbers count from the end) <\/td>\n<td align=\"left\">last frame <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-a <\/td>\n<td align=\"left\">Output in Angstrom <\/td>\n<td align=\"left\">in Bohr <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-q <\/td>\n<td align=\"left\">Append request lines from file <b><tt>QM.in<\/tt><\/b> in same directory <\/td>\n<td align=\"left\">do not append anything <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-i <\/td>\n<td align=\"left\">Produce output to append to initconds format <\/td>\n<td align=\"left\">print XYZ format <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-g <\/td>\n<td align=\"left\">Write <b><tt>geom<\/tt><\/b> and <b><tt>veloc<\/tt><\/b> files <\/td>\n<td align=\"left\">print XYZ format <\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Note that in <b><tt>-i<\/tt><\/b> and <b><tt>-g<\/tt><\/b> modes, the flags <b><tt>-a<\/tt><\/b> and <b><tt>-q<\/tt><\/b> are ignored. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.7.2\"><\/a><\/p>\n<h3>\n7.7.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>Geometry file  <\/b><br \/>\nThe geometry file must be in SHARC format, containing atomic symbols, numbers, and masses. It is used to map the structure from the NetCDF file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>NetCDF trajectory file  <\/b><br \/>\nThe trajectory file must be in SHARC NetCDF format and must contain geometry and velocity information. This file is accessed at the selected time step to retrieve the data.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Time step  <\/b><br \/>\nThe desired time step to extract can be specified via the <b><tt>-s<\/tt><\/b> flag. Negative numbers count from the last frame backward (e.g., <b><tt>-1<\/tt><\/b> extracts the final step).<br \/>\nUnlike <b><tt>sharctraj_to_initconds.py<\/tt><\/b>, <b><tt>sharctraj_to_xyz.py<\/tt><\/b> does not have any options to pick a random time step, but because <b><tt>sharctraj_to_xyz.py<\/tt><\/b> operates only on a single file, randomization logic can be implemented in a Bash wrapper script.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.7.3\"><\/a><\/p>\n<h3>\n7.7.3  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Three different output modes are available:<\/p>\n<ul>\n<li> By default, the script prints atomic positions in XYZ format to standard output. Using the <b><tt>-q<\/tt><\/b> option, requests from a <b><tt>QM.in<\/tt><\/b> file in the same directory can be appended.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Using the <b><tt>-i<\/tt><\/b> option, the output is printed in <b><tt>initconds<\/tt><\/b> file format.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Using the <b><tt>-g<\/tt><\/b> option, two files <b><tt>geom<\/tt><\/b> and <b><tt>veloc<\/tt><\/b> are written to the current directory (overwriting any existing files).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.8\"><\/a><\/p>\n<h2>\n7.8  Setup of Initial Calculations: <b><tt>setup_init.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:setup_init.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interactive script <b><tt>setup_init.py<\/tt><\/b> creates input for single point calculations at the initial geometries given in an <b><tt>initconds<\/tt><\/b> file. These calculations might be necessary for some schemes to select the initial electronic state of the trajectory, e.g., based on the excitation energies and oscillator strength of the transitions from ground state to the excited state, or based on overlaps with a reference wave function. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are other choices of the initial state possible, which do not require single point calculations at all initial geometries. See the description of <b><tt>excite.py<\/tt><\/b> (section <a href=\"#sec:excite.py\">7.9<\/a>). In this case, <b><tt>setup_init.py<\/tt><\/b> can be used to set up only the calculation at the equilibrium geometry (see below at “Range of Initial Conditions”).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.8.1\"><\/a><\/p>\n<h3>\n7.8.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script is interactive, and can be started by simply typing <\/p>\n<pre>\nuser@host> $SHARC\/setup_init.py\n<\/pre>\n<p>Please be aware that the script will setup the calculations in the directory where it was started, so the user should <b><tt>cd<\/tt><\/b> to the desired directory before executing the script.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Please note that the script does not expand <b><tt> <\/tt><\/b> or shell variables, except where noted otherwise.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.8.2\"><\/a><\/p>\n<h3>\n7.8.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script will prompt the user for the input. In the following, all input parameters are documented:<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Initial Conditions File  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Enter the filename of the initial conditions file, which was generated beforehand with <b><tt>wigner.py<\/tt><\/b>. If the script finds a file called <b><tt>initconds<\/tt><\/b>, the user is asked whether to use this file, otherwise the user has to enter an appropriate filename. The script detects the number of initial conditions and number of atoms automatically from the initial conditions file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Range of Initial Conditions  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The initial conditions in <b><tt>initconds<\/tt><\/b> are indexed, starting with the index 1. In order to prepare ab initio calculations for a subset of all initial conditions, enter a range of indices, e.g. a and b. This will prepare all initial conditions with indices in the interval [a,b]. In any case, the script will additionally prepare a calculation for the equilibrium geometry (except if a finished calculation for the equilibrium geometry was found).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the interval [0,0] is given, the script will only setup the calculation at the equilibrium geometry.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of states  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user can specify the number of excited states to be calculated. Note that the ground state has to be counted as well, e.g., if 4 singlet states are specified, the calculation will involve the S<sub>0<\/sub>, S<sub>1<\/sub>, S<sub>2<\/sub> and S<sub>3<\/sub>. Also states of higher multiplicity can be given, e.g. triplet or quintet states.<br \/>\nFor even-electron molecules, including odd-electron states (e.g. doublets) is only useful if transition properties for ionization can be computed (e.g. Dyson norms with some of the interfaces). These transition properties can be used to calculate ionization spectra or to obtain initial conditions for dynamics after ionization.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Charge per multiplicity  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, the molecular charge is not set in the interface template files, but directly by the setup scripts\/ S<span style=\"font-size:x-small\">HARC<\/span> driver\/parent interface.<br \/>\nHence, enter the molecular charge per multiplicity here.<br \/>\nThis array needs to have the same length as the number of states array.<br \/>\nIf the number of states for some multiplicities is zero, the entered number will be ignored.<br \/>\nFor example, if you provided <b><tt>states 3 2 1<\/tt><\/b> and <b><tt>charges 0 +1 0<\/tt><\/b>, then the 3 singlets and 1 triplet states will be computed as neutral species, and the 2 doublet states as cations with charge +1.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Interface  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this point, choose any of the displayed interfaces to carry out the ab initio calculations.<br \/>\nEnter the corresponding number. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you selected <b><tt>SHARC_LEGACY.py<\/tt><\/b>, then you have to subsequently select the legacy interface that you intend to use.<br \/>\nIf you selected a hybrid interface, then you will subsequently be queried with the path to the corresponding template file, so that the hybrid interface can figure out the child interface it should use.<br \/>\nThis might continue recursively until all interfaces in the interface call tree are known.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Spin-orbit calculation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Usually, it is sufficient to calculate the spin-free excitation energies and oscillator strengths in order to decide for the initial state.<br \/>\nHowever, using this option, the effects of spin-orbit coupling on the excitation energies and oscillator strengths can be included.<br \/>\nNote that the script will not ask for spin-orbit couplings if only singlet states are included in the calculation, or if the chosen interface does not support calculation of spin-orbit couplings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Dyson norm calculation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In some cases, initial conditions should be set up to simulate dynamics after ionization.<br \/>\nNote that the script will only ask for this property if the chosen interface supports Dyson norms.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Reference overlaps  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The calculations can be setup in such a way that the wave function overlaps between states at the equilibrium geometry and the displaced geometries is computed.<br \/>\nThis allows correlating the states at the displaced geometries with the reference states, such that one can know the state characters of all states without inspection.<br \/>\nThis is useful for a crude “diabatization” of the states, e.g., if one wants to start all trajectories in the nπ<sup>*<\/sup> state of the molecule although this state can be S<sub>1<\/sub>, S<sub>2<\/sub>, or S<sub>3<\/sub> (use <b><tt>excite.py<\/tt><\/b> to setup initial conditions in such a way, see section <a href=\"#sec:excite.py\">7.9<\/a>).<br \/>\nNote that the script will only ask for this option if the chosen interface supports wave function overlaps.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When activating this option, keep in mind that the calculation in <b><tt>ICOND_00000<\/tt><\/b> must be successfully finished before any of the other <b><tt>ICOND_XXXXX<\/tt><\/b> calculations can be started.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>TheoDORE analysis  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the chosen interface supports wave function analysis with TheoDORE, then this option can be activated here.<br \/>\n<b><tt>setup_init.py<\/tt><\/b> will then include the relevant keywords in the computations, and the results of the TheoDORE analysis will be written to the <b><tt>QM.out<\/tt><\/b> files.<br \/>\nNote that the script will only ask for this option if the chosen interface supports wave function descriptors from TheoDORE.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The remaining settings for TheoDORE (fragment and descriptor input) will be asked later in <b><tt>setup_init.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.8.3\"><\/a><\/p>\n<h3>\n7.8.3  Interface-specific input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>After identifying all electronic structure information that needs to be computed, the setup script will call the chosen interface’s own setup routines.<br \/>\nThe interface will ask the user for all necessary information, depending on the requested quantities.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For hybrid interfaces, the children’s setup routines will also be called at some point, possibly in a recursive fashion, until all interfaces in the call tree are setup.<br \/>\nSee Chapter <a href=\"#chap:interfaces\">6<\/a> for the questions that the interfaces ask.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.8.4\"><\/a><\/p>\n<h3>\n7.8.4  Input for Run Scripts<\/h3>\n<p><a id=\"sec:setup_init.py:run\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Run script mode  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script <b><tt>setup_init.py<\/tt><\/b> generates a run script (Bash) for each initial condition calculation. Due to the large variety of cluster architectures, these run scripts might not work in every case. It is the user’s responsibility to adapt the generated run scripts to his needs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>setup_init.py<\/tt><\/b> can generate run scripts for two different schemes how to execute the calculations. With the first scheme, the ab initio calculations are performed in the directory where they were setup (subdirectories of the directory where <b><tt>setup_init.py<\/tt><\/b> was started). Note that the interfaces will still use their scratch directories to perform the actual quantum chemistry calculations. Currently, this is the default and simplest option.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>With the second option, the run scripts will transfer the input files for each ab initio calculation to a temporary directory, where the interface is started. After the interface finishes all calculations, the results files are transferred back to the primary directory and the temporary directory is deleted. Note that <b><tt>setup_init.py<\/tt><\/b> in any case creates the directory structure in the directory where it was started. The name of the temporary directory can contain shell variables, which will be expanded when the script is running (on the compute host).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Submission script  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The setup script can also create a Bash script for the submission of all ab initio calculations to a queueing system. The user has to provide a submission command for that, including any options which might be necessary. This submission script might not work with all queueing systems.<br \/>\nThe user should also enter a project name that is used to add a name option to the submission script.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.8.5\"><\/a><\/p>\n<h3>\n7.8.5  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>setup_init.py<\/tt><\/b> will create for each initial condition in the given range a directory whose names follow the format <b><tt>ICOND_%05i\/<\/tt><\/b>, where <b><tt>%05i<\/tt><\/b> is the index of the initial condition padded with zeroes to 5 digits. Additionally, the directory <b><tt>ICOND_00000\/<\/tt><\/b> is created for the calculation of the excitation energies at the equilibrium geometry.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>To each directory, the following files will be added:<\/p>\n<ul>\n<li> <b><tt>QM.in<\/tt><\/b>: Main input file for the interface, contains the geometry and the control keywords (to specify which quantities need to be calculated).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>run.sh<\/tt><\/b>: Run script, which can be started interactively in order to perform the ab initio calculation in this directory. Can also be adapted to a batch script for submission to a queue\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Interface-specific files: Usually a template file, a resource file, and an initial wave function.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>The calculations in each directory can be simply executed by starting <b><tt>run.sh<\/tt><\/b> in each directory. In order to perform this task consecutively on a single machine, the script <b><tt>all_run.sh<\/tt><\/b> can be executed. The file <b><tt>DONE<\/tt><\/b> contains the progress of this calculation.<br \/>\nAlternatively, each run script can be sent to a queueing system (you might need to adapt this script to you cluster system).<br \/>\nNote that if reference overlaps were requested, the calculation in <b><tt>ICOND_00000\/<\/tt><\/b> must be finished before starting any of the other calculations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In figure <a href=\"#fig:dirs_init\">7.1<\/a>, the directory tree structure setup by <b><tt>setup_init.py<\/tt><\/b> is given.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg7.1\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/dirs_init.png\"> <\/p>\n<div style=\"text-align:center\">Figure 7.1: Directory structure created by <b><tt>setup_init.py<\/tt><\/b>. Directories are in blue, executable scripts in green and regular files in black and white. Interface files usually include initial MO coefficients, template files and interface input files.<\/div>\n<p> <a id=\"fig:dirs_init\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>After all calculations are finished, <b><tt>excite.py<\/tt><\/b> can be used to collect the results.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.9\"><\/a><\/p>\n<h2>\n7.9  Excitation Selection: <b><tt>excite.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:excite.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>excite.py<\/tt><\/b> has two tasks: adding excited-state information to the <b><tt>initconds<\/tt><\/b> file, and deciding which excited state for which initial condition is a valid initial state for the dynamics.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.9.1\"><\/a><\/p>\n<h3>\n7.9.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script is interactive, and can be started by simply typing <\/p>\n<pre>\nuser@host> $SHARC\/excite.py\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.9.2\"><\/a><\/p>\n<h3>\n7.9.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>Initial condition file  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Enter the path to the initial conditions file, to which <b><tt>excite.py<\/tt><\/b> will add excited-state information. This file can already contain excited-state information (in this case this information can be reused).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Generate excited state list  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are three possibilities to add excited-state information to the <b><tt>initconds<\/tt><\/b> file:<\/p>\n<ol type=\"1\">\n<li> generate a list of dummy excited states,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> read excited-state information from the output of the initial ab initio calculations (prepare the calculations with <b><tt>setup_init.py<\/tt><\/b>),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> keep the existing excited-state information in the <b><tt>initconds<\/tt><\/b> file.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<p>The first option is mainly used if no initial ab initio calculations need to be performed (e.g., the initial state is known). <\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to use the second option, one should first setup initial excited-state calculations using <b><tt>setup_init.py<\/tt><\/b> (see <a href=\"#sec:setup_init.py\">7.8<\/a>) and run the calculations. <b><tt>excite.py<\/tt><\/b> can then read the output of the initial calculations and calculate excitation energies and oscillator strengths.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The third option can be used to reuse the information in the <b><tt>initconds<\/tt><\/b> file, e.g., to apply a different selection scheme to the states or to just read the number of states.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Path to ab initio results  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If <b><tt>excite.py<\/tt><\/b> will read the excited-state information from the ab initio calculation results, here the user has to provide the path to the directory containing the <b><tt>ICOND_%05i<\/tt><\/b> subdirectories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of states  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If a dummy list of states will be generated, the user has to provide the number of states per multiplicity. Note that a singlet ground state has to be counted as well, e.g. if 4 singlet states are specified, the calculation will involve the S<sub>0<\/sub>, S<sub>1<\/sub>, S<sub>2<\/sub> and S<sub>3<\/sub>. Also states of higher multiplicity can be given, e.g. doublet or triplet states (e.g., <b><tt>2 2 1<\/tt><\/b> for two singlets, two doublets and one triplet).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the ab initio results are read the number of states will be automatically determined from the results.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Excited-state representation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>When generating new lists of excited states (either dummy states or from ab initio results), the user has to specify the representation of the excited states (either MCH or diagonal representation). The MCH representation is spin-free, meaning that transition dipole moments are only allowed between states of the same multiplicity. For molecules without heavy atoms, this option is sufficient. For heavier atoms, the diagonal representation can be used, which includes the effects of spin-orbit coupling on the excitation energies and oscillator strengths.<br \/>\nNote, however, that excited-state selection with delta pulse excitation (option 3 under “Initial state selection”) should be carried out in the MCH representation if the ground state is not significantly spin-orbit-mixed.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When reading ab initio results, <b><tt>excite.py<\/tt><\/b> will diagonalize the Hamiltonian and transform the transition dipole matrices for each initial condition to obtain the diagonal representation. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>When a dummy state list is generated, the representation will only be written to <b><tt>initconds.excited<\/tt><\/b> (but has no actual numeric effect for <b><tt>excite.py<\/tt><\/b>). Note that the representation which is declared in the <b><tt>initconds.excited<\/tt><\/b> file influences how S<span style=\"font-size:x-small\">HARC<\/span> determines the initial coefficients (see the paragraph on initial coefficients in  <a href=\"#ssec:input:keywords\">4.1.3<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the representation cannot be changed if existing excited-state information is kept. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Hint: If the <b><tt>ICOND_%05i<\/tt><\/b> directories need to be deleted (e.g., due to disk space restrictions), making one read-out with <b><tt>excite.py<\/tt><\/b> for each representation and saving the results to two different files will preserve most necessary information.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Ionization probabilities  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If <b><tt>excite.py<\/tt><\/b> detects that the ab initio results contain ionization probabilities, then those can be used instead of the transition dipole moments. Note that in this case the transition dipole moments are not written to the <b><tt>initconds.excited<\/tt><\/b> file. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Reference energy  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>excite.py<\/tt><\/b> can read the reference energy (ground state equilibrium energy) directly from the ab initio results. If the ab initio data is read anyways, <b><tt>excite.py<\/tt><\/b> already knows the relevant path. If a dummy list of states is generated, the user can provide just the path to the <b><tt>QM.out<\/tt><\/b> file of the ab initio calculation for the equilibrium geometry. Otherwise, <b><tt>excite.py<\/tt><\/b> will prompt the user to enter a reference energy manually (in hartree).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Initial state selection  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Every excited state of each initial condition has a flag specifying it either as a valid initial state or not. <b><tt>excite.py<\/tt><\/b> has four modes how to flag the excited states:<\/p>\n<ol type=\"1\">\n<li> Unselect all excited states,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> User provides a list of initial states,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> States are selected stochastically based on excitation energies and oscillator strengths,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Keep all existing flags.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<p>The first option can be used if <b><tt>excite.py<\/tt><\/b> is only used to read the ab initio results for the generation of an absorption spectrum (using <b><tt>spectrum.py<\/tt><\/b>). <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The second option can be used to directly specify a list of initial states, if the initial state is known (e.g., starting in the ground state and exciting with an explicit laser field). In this case, the given states of <i>all<\/i> initial conditions are flagged as initial states. This option is also useful if reference overlaps were computed (see <a href=\"#sec:setup_init.py\">7.8<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The third option is only available if excited-state information exists (i.e., if no dummy list is generated). For details on the stochastic selection procedure, see section <a href=\"#met:exc_selection\">8.9<\/a>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The fourth option can only be used if the existing state information is kept. In this case <b><tt>excite.py<\/tt><\/b> does nothing except counting the number of flagged initial states.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Excitation window  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This option allows to exclude excited states from the selection procedure if they are outside a given energy window. This option is only available if excited state information exists, but not if a dummy list of states is generated (because the dummy states have no defined excitation energy).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For the stochastic selection procedure, states outside the excitation window do not count for the determination of p<sub>max<\/sub> (see equation (<a href=\"#eq:exc_prob\">8.45<\/a>)). This allows to excite, e.g., to a dark nπ<sup>*<\/sup> state despite the presence of a much brighter ππ<sup>*<\/sup> state.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For the keep-flags option, this option can be used to count the number of excited states in the energy window.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Considered states  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user can specify the list of desired initial states.<br \/>\nIf reference overlaps are present in the excitation calculations, then the user can choose to specify the initial state in terms of diabatized states (as defined by the overlap with the reference, where the diabatized states are identical to the computed states).<br \/>\nSee section <a href=\"#met:exc_diabatic\">8.9.1<\/a> for how the diabatization is carried out.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For the stochastic selection procedure, the user can instead exclude certain states from the procedure. Excluded states do not count for the determination of p<sub>max<\/sub> (see equation (<a href=\"#eq:exc_prob\">8.45<\/a>)).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the number of states per multiplicity is known, <b><tt>excite.py<\/tt><\/b> will print a table giving for each state index the multiplicity, quantum number and M<sub>s<\/sub> value.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Random number generator seed  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The random number generator in <b><tt>excite.py<\/tt><\/b> is used in the stochastic selection procedure. Instead of typing an integer, typing “<b><tt>!<\/tt><\/b>” will initialize the RNG from the system time. Note that this will not be reproducible, i.e. repeating the <b><tt>excite.py<\/tt><\/b> run with “<b><tt>!<\/tt><\/b>” as random seed will give a different selection in each run.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.9.3\"><\/a><\/p>\n<h3>\n7.9.3  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>excite.py<\/tt><\/b> writes all output to a file <b><tt><BASE>.excited<\/tt><\/b>, where <b><tt><BASE><\/tt><\/b> is the name of the initial conditions file used as input. The output file is also an initial conditions file, but contains additional information regarding the excited states, the reference energy and the representation of the excited states. An initial conditions file with excited-state information is needed for the final preparatory step: setting up the dynamics with <b><tt>setup_traj.py<\/tt><\/b>.<br \/>\nAdditionally, <b><tt>spectrum.py<\/tt><\/b> can calculate absorption spectra from excited-state initial condition files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.9.4\"><\/a><\/p>\n<h3>\n7.9.4  Specification of the <b><tt>initconds.excited<\/tt><\/b> file format<\/h3>\n<p><a id=\"sec:initcondsfile\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The initial conditions files <b><tt>initconds<\/tt><\/b> and <b><tt>initconds.excited<\/tt><\/b> contain lists of initial conditions, which are needed for the setup of trajectories. An initial condition is a set of initial coordinates of all atoms and corresponding initial velocities of each atom, and optionally a list of excited state informations. In the following, the format of this file is specified.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The file contains of a header, followed by the body of the file containing a list of the initial conditions. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>File header  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>An examplary header looks like:<br \/>\n<span class=\"footnotesize\"><\/p>\n<pre>\nSHARC Initial conditions file, version 0.2   <Excited>\nNinit     100\nNatom     2\nRepr      MCH\nEref         -0.50\nEharm           0.04\nStates    2 0 1 \nEquilibrium\n H   1.0  0.0  0.0  0.0   1.00782503   0.0  0.0  0.0\n H   1.0  1.5  0.0  0.0   1.00782503   0.0  0.0  0.0\n<\/pre>\n<p> <\/span><br \/>\nThe first line must read <b><tt>SHARC Initial conditions file, version <VERSION><\/tt><\/b>, with the correct version string followed. The string <b><tt>Excited<\/tt><\/b> is optional, and marks an initial conditions file as being an output file of <b><tt>excite.py<\/tt><\/b> (<b><tt>setup_traj.py<\/tt><\/b> will only accept files marked like this). The following lines contain:<\/p>\n<ol type=\"1\">\n<li> the number of initial conditions,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> the number of atoms,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> the electronic state representation (a string which is <b><tt>None<\/tt><\/b>, <b><tt>MCH<\/tt><\/b> or <b><tt>diag<\/tt><\/b>),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> the reference energy (hartree),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> the harmonic energy (zero point energy in the harmonic approximation, hartree),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> optionally the number of states per multiplicity.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<div class=\"p\"><!----><\/div>\n<p>After the header, first the equilibrium geometry is expected. It is demarked with the keyword <b><tt>Equilibrium<\/tt><\/b>, followed by n<sub>atom<\/sub> lines, each specifying one atom. Unlike the actual initial conditions, the equilibrium geometry does not have a list of excited states or defined energies.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>File body  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The file body contains a list of initial conditions. Each initial condition is specified by a block starting with a line containing the string <b><tt>Index<\/tt><\/b> and the number of the initial condition. In the file, the initial conditions are expected to appear in order.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A block specifying an initial condition looks like:<br \/>\n<span class=\"footnotesize\"><\/p>\n<pre>\nIndex     1\nAtoms\n H   1.0  -0.02  0.0  0.0   1.00782503  -0.001  0.0  0.0\n H   1.0   1.52  0.0  0.0   1.00782503   0.001  0.0  0.0\nStates\n001    -0.49    -0.49  -0.16   0.0  -0.03   0.0   0.05   0.0   0.0   0.00 False\n002    -0.25    -0.49   0.02   0.0   0.43   0.0  -1.77   0.0   6.5   0.53 True\n003    -0.40    -0.49   0.00   0.0   0.00   0.0   0.00   0.0   2.5   0.00 False\n004    -0.40    -0.49   0.00   0.0   0.00   0.0   0.00   0.0   2.5   0.00 False\n005    -0.40    -0.49   0.00   0.0   0.00   0.0   0.00   0.0   2.5   0.00 False\nEkin        0.004 a.u.\nEpot_harm   0.026 a.u.\nEpot        0.013 a.u.\nEtot_harm   0.030 a.u.\nEtot        0.018 a.u.\n<\/pre>\n<p> <\/span><br \/>\nThe formal structure of such a block is as follows. After the line containing the keyword <b><tt>Index<\/tt><\/b> and the index number, the keyword <b><tt>Atoms<\/tt><\/b> indicates the start of the list of atoms. Each atom is specified on one line:<\/p>\n<ol type=\"1\">\n<li> symbol,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> nuclear charge,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> x, y, z coordinate in Bohrs,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> atomic mass,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> x, y and z component of nuclear velocity in atomic units.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<div class=\"p\"><!----><\/div>\n<p>After the atom list, the keyword <b><tt>States<\/tt><\/b> indicates the list of electronic states. This list consists of one line per electronic state, but can be empty, if no information of the electronic states is available. Each line consists of: <\/p>\n<ol type=\"1\">\n<li> state number (starting with 1),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> state energy in Hartree,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> reference energy in Hartree (usually the energy of the lowest state),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> six numbers defining the transition dipole moment to the reference state (usually the lowest state),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> the excitation energy in eV,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> the oscillator strength,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> a string which is either <b><tt>True<\/tt><\/b> or <b><tt>False<\/tt><\/b>, specifying whether the electronic state was selected by <b><tt>excite.py<\/tt><\/b> as initial electronic state.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<p>The transition dipole moments are specified by six floating point numbers, which are real part of the x component, imaginary part of the x component, then the real and imaginary parts for the y and finally the z component (the transition dipole moments can be complex in the diagonal representation). <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The electronic state list is terminated with the keyword <b><tt>Ekin<\/tt><\/b>, which at the same time gives the kinetic energy of all atoms. The remaining entries give the potential energy in the harmonic approximation and the actual potential energy, as well as the total energy.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.10\"><\/a><\/p>\n<h2>\n7.10  Calculation of Absorption Spectra: <b><tt>spectrum.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:spectrum.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Aside from setting up trajectories, the <b><tt>initconds.excited<\/tt><\/b> files can also be used to generate absorption spectra based on the excitation energies and oscillator strengths in the file. The script <b><tt>spectrum.py<\/tt><\/b> calculates Gaussian, Lorentzian, or Log-normal convolutions of these data in order to obtain spectra. See Section <a href=\"#met:spectrum\">8.1<\/a> for further details.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>spectrum.py<\/tt><\/b> evaluates the absorption spectrum on a grid for all states it finds in an initial conditions file. Using command-line options, some initial conditions can be omitted in the convolution, see Table <a href=\"#tab:spectrum_opts\">7.8<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.10.1\"><\/a><\/p>\n<h3>\n7.10.1  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script is executed with the initial conditions file as argument:<\/p>\n<pre>\nuser@host> $SHARC\/spectrum.py [OPTIONS] initconds.excited\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The script accepts a number of command-line options, which are given in table <a href=\"#tab:spectrum_opts\">7.8<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.8\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.8: Command-line options for script <b><tt>spectrum.py<\/tt><\/b>.<\/div>\n<p> <a id=\"tab:spectrum_opts\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit. <\/td>\n<td align=\"left\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-o FILENAME <\/td>\n<td align=\"left\">Output filename for the spectrum <\/td>\n<td align=\"left\"><b><tt>spectrum.out<\/tt><\/b><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-n INTEGER <\/td>\n<td align=\"left\">Number of grid points <\/td>\n<td align=\"left\">500 <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-e FLOAT FLOAT <\/td>\n<td align=\"left\">Energy range (eV) for the spectrum <\/td>\n<td align=\"left\">1 to 10 eV<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-i INTEGER INTEGER <\/td>\n<td align=\"left\">Index range for the initial conditions <\/td>\n<td align=\"left\">1 to 1000<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-f FLOAT <\/td>\n<td align=\"left\">FWHM (eV) for the spectrum <\/td>\n<td align=\"left\">0.1 eV<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-G <\/td>\n<td align=\"left\">Gaussian convolution <\/td>\n<td align=\"left\">Gaussian<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-L <\/td>\n<td align=\"left\">Lorentzian convolution <\/td>\n<td align=\"left\">Gaussian<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-N <\/td>\n<td align=\"left\">Log-normal convolution <\/td>\n<td align=\"left\">Gaussian<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-s <\/td>\n<td align=\"left\">Use only selected initial conditions <\/td>\n<td align=\"left\">Use all<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-l <\/td>\n<td align=\"left\">Make a line spectrum <\/td>\n<td align=\"left\">Convolution<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-D <\/td>\n<td align=\"left\">Compute density of states (ignore f<sub>osc<\/sub>) <\/td>\n<td align=\"left\">Compute absorption<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-gnuplot FILENAME <\/td>\n<td align=\"left\">Write a G<span style=\"font-size:x-small\">NUPLOT<\/span> script <\/td>\n<td align=\"left\">No G<span style=\"font-size:x-small\">NUPLOT<\/span> script<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-B INTEGER <\/td>\n<td align=\"left\">Perform <b><tt>B<\/tt><\/b> bootstrapping cycles (error estimation) <\/td>\n<td align=\"left\">0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-b FILENAME <\/td>\n<td align=\"left\">Output filename for bootstrapping <\/td>\n<td align=\"left\"><b><tt>spectrum_bootstrap.out<\/tt><\/b><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-r INTEGER <\/td>\n<td align=\"left\">Seed for random number generator (for bootstrap) <\/td>\n<td align=\"left\">16661<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-p INTEGER <\/td>\n<td align=\"left\">Number of standard deviations (for bootstrap) <\/td>\n<td align=\"left\">3<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-c <\/td>\n<td align=\"left\">Calculate absorption cross section (Å<sup>2<\/sup>\/molecule) <\/td>\n<td align=\"left\">Off<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-m <\/td>\n<td align=\"left\">Convert absorption cross section to molar absorption coefficient (M<sup>−1<\/sup>cm<sup>−1<\/sup>)<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.10.2\"><\/a><\/p>\n<h3>\n7.10.2  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script writes the absorption spectrum to a file (by default <b><tt>spectrum.out<\/tt><\/b>). Using the <b><tt>-o<\/tt><\/b> option, the user can redirect the output to a suitable file. The output is a table containing n+2 columns, where n is the number of states found in the initial conditions file. The first column gives the energy in eV, within the given energy interval. In columns 2 to n+1 the state-wise absorption spectra are given. The last column contains the total absorption spectrum, i.e., the sum over all states. The table has n<sub>grid<\/sub>+1 rows. For line spectra the output format is exactly the same, however, the file will contain one row for each excited state of each initial condition in the initial conditions file. If density of states is computed, the script replaces the oscillator strength by a factor of 1 for all states.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Additionally, the script writes some information about the calculation to standard output, among these the maximum of the spectrum, which can be used in order to normalize the spectrum. The reported maximum is simply the largest value in the last column of the spectrum. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>If requested, the script generates a G<span style=\"font-size:x-small\">NUPLOT<\/span> script, which can be used to directly plot the spectrum. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the <b><tt>-c<\/tt><\/b> switch is used, the spectrum is computed in terms of absolute absorption cross section (in units of Å<sup>2<\/sup>).<br \/>\nThis option is not compatible with density-of-state spectra or line spectra.<br \/>\nIf the <b><tt>-m<\/tt><\/b> option is used additionally to <b><tt>-c<\/tt><\/b>, then the spectrum is computed in terms of the molar absorption coefficient (in units of M<sup>−1<\/sup>cm<sup>−1<\/sup>).<br \/>\nThe <b><tt>-m<\/tt><\/b> option cannot be used without <b><tt>-c<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.10.3\"><\/a><\/p>\n<h3>\n7.10.3  Error Analysis<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The shape of the spectrum is strongly influenced by the number of initial conditions included and by the width of the broadening function (FWHM).<br \/>\nIn principle, the FWHM of the broadening function should be as small as possible and the number of initial conditions extremely large, in order to obtain a correctly sampled spectrum.<br \/>\nIn reality, if only few initial conditions were considered, the FWHM should be chosen large enough to smooth out any artifical structure of the spectrum arising solely from the small sample size.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to estimate whether the number of initial conditions and the FWHM are well-chosen, <b><tt>spectrum.py<\/tt><\/b> can compute error estimates for the total absorption spectrum.<br \/>\nThis estimate is computed by a bootstrapping procedure (similar to the one used in <b><tt>bootstrap.py<\/tt><\/b>).<br \/>\nIn order to use it, use the <b><tt>-B<\/tt><\/b> option with a positive integer argument (the default is zero, and hence no bootstrapping is performed).<br \/>\nThe procedure will generate a second output file, called <b><tt>spectrum_bootstrap.out<\/tt><\/b> by default.<br \/>\nIt contains in the first column the energy in eV, in the second the geometric average spectrum from all bootstrap cycles, in column 3 and 4 the positive and negative errors of the spectrum, and in all further columns the individual spectra obtained in the bootstrap cycles.<br \/>\nIn <b><tt>gnuplot<\/tt><\/b>, in order to plot the average spectrum and the upper and lower error bounds, plot <b><tt>u 1:2<\/tt><\/b>, <b><tt>u 1:($2+$3)<\/tt><\/b>, and <b><tt>u 1:($2+$4)<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A suitable procedure is to start with a rather small FWHM, compute the spectrum with errors, and if the errors are unsatisfactorily large, increase stepwise the FWHM.<br \/>\nNote that the bootstrapping estimate will give very small errors if the FWHM is very large-even though the actual spectrum can look very different in this case.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.11\"><\/a><\/p>\n<h2>\n7.11  Laser field generation: <b><tt>laser.x<\/tt><\/b><\/h2>\n<p><a id=\"sec:laser.x\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The Fortran code <b><tt>laser.x<\/tt><\/b> can generate files containing laser fields which can be used with S<span style=\"font-size:x-small\">HARC<\/span>. It is possible to superimpose several lasers, use different polarizations and apply a number of chirp parameters.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.11.1\"><\/a><\/p>\n<h3>\n7.11.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The program is simply called by <\/p>\n<pre>\nuser@host> $SHARC\/laser.x\n<\/pre>\n<p>It will interactively ask for the laser parameters. After input is complete, it writes the laser field to the file <b><tt>laser<\/tt><\/b> in the format which S<span style=\"font-size:x-small\">HARC<\/span> expects (see <a href=\"#sec:laserfile\">4.5<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Similar to the interactive Python scripts, <b><tt>laser.x<\/tt><\/b> will also write the user input to <b><tt>KEYSTROKES.laser<\/tt><\/b>. After modifying this file, it can be used to directly execute <b><tt>laser.x<\/tt><\/b> without doing the interactive input again:<\/p>\n<pre>\nuser@host> $SHARC\/laser.x < KEYSTROKES.laser\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.11.2\"><\/a><\/p>\n<h3>\n7.11.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The first four options are global and need to be entered only once, all remaining input options need to be given for every laser pulse. For the definition of laser fields see section <a href=\"#met:laser_field\">8.16<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of lasers  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Any number of lasers can be used. The output file will contain the sum of all laser pulses defined.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Real-valued field  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If this is true, the output file will only contain the real parts of the laser field, while the columns defining the imaginary part of the field will be zero. Note, however, that S<span style=\"font-size:x-small\">HARC<\/span> will anyways only use the real part of the field in the simulations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Time interval and steps  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The definitions of the starting time, end time and time step of the laser field must exactly match the simulation time and time substeps of the S<span style=\"font-size:x-small\">HARC<\/span> simulation. Note, that the laser field must always start at t=0 fs to be used with S<span style=\"font-size:x-small\">HARC<\/span>. The end time for the laser field must therefore coincide with the total simulation time given in the S<span style=\"font-size:x-small\">HARC<\/span> input. The number of time steps for the laser field is t<sub>total<\/sub>\/∆t<sub>sub<\/sub> +1.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Files for debugging  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This option is normally not needed, and can be set to False. If set to True, the chirped and unchirped laser fields in both time and frequency domain will be written to files called <b><tt>DEBUG_... <\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Polarization vector  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The polarization vector <b>p<\/b> (will be normalized).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Type of envelope  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are two options possible for the envelope function <i>E<\/i>(t), either a Gaussian envelope or a sinusoidal one (see <a href=\"#met:laser_field\">8.16<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Field strength  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are two input lines for the field strength <i>E<\/i><sub>0<\/sub>, the first defining the unit in which the field strength is defined, the second gives the corresponding number. Field strength can be read in in GV\/m, TW\/cm<sup>−2<\/sup> or atomic units.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>FWHM and time intervals  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This option depends on the type of envelope chosen. While in both cases all 5 numbers need to be entered, for a Gaussian pulse only the first and third number have an effect. For a sinusoidal pulse all but the first number has an effect.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For a Gaussian pulse, the first argument corresponds to FWHM in equation (<a href=\"#eq:laser_gauss_2\">8.94<\/a>) and the third argument to t<sub>c<\/sub> in  (<a href=\"#eq:laser_gauss_1\">8.93<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For a sinusoidal pulse, the second, third, fourth and fifth argument correspond to t<sub>0<\/sub>, t<sub>c<\/sub>, t<sub>c2<\/sub> and t<sub>e<\/sub>, respectively, in equation (<a href=\"#eq:laser_sinus\">8.95<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Central frequency  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are two input lines for the central frequency ω<sub>0<\/sub>. The first defines the unit (wavelength in nm, energy in eV, or atomic units). The second line gives the value.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Phase  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The total phase ϕ is given in multiples of π. For example, the input “<b><tt>1.5<\/tt><\/b>” gives a phase of [(3π)\/2].<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Chirp parameters  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are four lines giving the chirp parameters b<sub>1<\/sub>, b<sub>2<\/sub>, b<sub>3<\/sub> and b<sub>4<\/sub>. See equation (<a href=\"#eq:laser_chirp\">8.97<\/a>) for the meaning of these parameters.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.12\"><\/a><\/p>\n<h2>\n7.12  Preparing QM\/MM calculations: <b><tt>setup_from_prmtop.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:setup_from_prmtop.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This script processes an A<span style=\"font-size:x-small\">MBER<\/span> <b><tt>prmtop<\/tt><\/b> topology file to generate input files for S<span style=\"font-size:x-small\">HARC<\/span> QM\/MM simulations.<br \/>\nIt allows the user to specify a list of QM atoms and prepares several auxiliary files such as <b><tt>QMMM.table<\/tt><\/b>, <b><tt>atommask<\/tt><\/b>, and <b><tt>rattle<\/tt><\/b>, as well as topology files for the two MM calculations involved in a subtractive electrostatic embedding QM\/MM simulation.<br \/>\nUse this script to prepare QM\/MM calculations with <b><tt>SHARC_QMMM.py<\/tt><\/b> and <b><tt>SHARC_OPENMM.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>See Sections <a href=\"#sec:int:qmmm\">6.24<\/a> and <a href=\"#sec:int:openmm\">6.7<\/a> for further details.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.12.1\"><\/a><\/p>\n<h3>\n7.12.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>setup_from_prmtop.py<\/tt><\/b> is a command-line script, invoked as: <\/p>\n<pre> \nuser@host> $SHARC\/setup_from_prmtop.py -f <prmtop> -q <qm_list> [options] \n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.12.2\"><\/a><\/p>\n<h3>\n7.12.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script requires the following arguments:<\/p>\n<ul>\n<li> <b><tt>-f <prmtop><\/tt><\/b>: Path to the A<span style=\"font-size:x-small\">MBER<\/span> <b><tt>.prmtop<\/tt><\/b> topology file.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>-q <qm_list><\/tt><\/b>: A space-separated or range-based list of QM atom indices (counting starts from 1) in quotes. Example: <b><tt>\"1 2 3 8 1012\"<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p>Optional flags: <\/p>\n<ul>\n<li> <b><tt>-rattle-hx<\/tt><\/b>: Generate a <b><tt>rattle<\/tt><\/b> file containing all H-X bonds (where X is any atom) and their equilibrium distances from the <b><tt>prmtop<\/tt><\/b> file.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>-atommask<\/tt><\/b>: Generate an <b><tt>atommask<\/tt><\/b> file marking QM atoms with <b><tt>T<\/tt><\/b> (True) and MM atoms with <b><tt>F<\/tt><\/b> (False), for use in decoherence and rescaling exclusion.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.12.3\"><\/a><\/p>\n<h3>\n7.12.3  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script generates several files in the current directory:<\/p>\n<div class=\"p\"><!----><\/div>\n<ul>\n<li> <b><tt>QMMM.table<\/tt><\/b>: Lists each atom’s QM\/MM type, atomic symbol, and bonded atoms. Required for <b><tt>SHARC_QMMM.py<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>NAME_chrg_0.prmtop<\/tt><\/b>: A copy of the original topology file, with QM atom charges set to zero. Use this for the <b><tt>MML<\/tt><\/b> child of <b><tt>SHARC_QMMM.py<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>NAME_qm_and_links_chrg0.prmtop<\/tt><\/b>: A truncated topology file containing only the QM and link atoms, with their charges set to zero. Use this for the <b><tt>MMS<\/tt><\/b> child of <b><tt>SHARC_QMMM.py<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>atommask<\/tt><\/b> (optional): Text file with one line per atom, either <b><tt>T<\/tt><\/b> or <b><tt>F<\/tt><\/b>, based on the QM atom list.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> <b><tt>rattle<\/tt><\/b> (optional): Contains all H-X bonds with equilibrium distances, used for constrained dynamics.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.13\"><\/a><\/p>\n<h2>\n7.13  Setup of Trajectories: <b><tt>setup_traj.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:setup_traj.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This interactive script prepares the input for the excited-state dynamics simulations with S<span style=\"font-size:x-small\">HARC<\/span>. It works similarly to <b><tt>setup_init.py<\/tt><\/b>, reading an initial conditions file, prompting the user for a number of input parameters, and finally prepares one directory per trajectory. However, the <b><tt>setup_traj.py<\/tt><\/b> input section is noticeably longer, because most options for the S<span style=\"font-size:x-small\">HARC<\/span> dynamics are covered.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.13.1\"><\/a><\/p>\n<h3>\n7.13.1  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>Initial conditions file  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Please be aware that <b><tt>setup_traj.py<\/tt><\/b> needs an initial conditions file generated by <b><tt>excite.py<\/tt><\/b> (files generated by <b><tt>wigner.py<\/tt><\/b>, <b><tt>amber_to_initconds.py<\/tt><\/b>, <b><tt>sharctraj_to_initconds.py<\/tt><\/b>, … are not allowed).<br \/>\nThe main distinction is that <b><tt>excite.py<\/tt><\/b> flags some excited states as selected for setup, and <b><tt>setup_traj.py<\/tt><\/b> requires this information.<br \/>\nThe script reads the number of initial states, the representation, and the reference energy automatically from the file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of states  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This is the total number of states per multiplicity included in the dynamics calculation. Affects the keyword <b><tt>nstates<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Only advanced users should use here a different number of states than given to <b><tt>setup_init.py<\/tt><\/b>. In this case, the excited-state information in the initial conditions file might be inconsistent. For example, if 10 singlets and 10 triplets were included in the initial calculations, but only 5 singlets and 5 triplets in the dynamics, then the sixth entry in the initial conditions file corresponds to S<sub>5<\/sub>, while <b><tt>setup_traj.py<\/tt><\/b> assumes the sixth entry to correspond to T<sub>1<\/sub>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Charge per multiplicity  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>4, the molecular charge is not set in the interface template files, but directly by the setup scripts\/ S<span style=\"font-size:x-small\">HARC<\/span> driver\/parent interface.<br \/>\nHence, enter the molecular charge per multiplicity here, which will be copied into the <b><tt>input<\/tt><\/b> file.<br \/>\nThis array needs to have the same length as the number of states array.<br \/>\nIf the number of states for some multiplicities is zero, the entered number will be ignored.<br \/>\nFor example, if you provided <b><tt>states 3 2 1<\/tt><\/b> and <b><tt>charges 0 +1 0<\/tt><\/b>, then the 3 singlets and 1 triplet states will be computed as neutral species, and the 2 doublet states as cations with charge +1.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Active states  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>States can be frozen for the dynamics calculation here. See section <a href=\"#met:activestates\">8.2<\/a> for a general description of state freezing in S<span style=\"font-size:x-small\">HARC<\/span>. Only the highest states in each multiplicity can be frozen, it is not possible to, e.g., freeze the ground state in simulations where ground state relaxation is negligible. Affects the keyword <b><tt>actstates<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Contents of the initial conditions file  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Optionally, a map of the contents of the initial conditions file can be displayed during the execution of <b><tt>setup_traj.py<\/tt><\/b>, showing for each state which initial conditions were selected (and which initial conditions do not have the necessary excited-state information). For each state, a table is given, where each symbol represents one initial condition. A dot “<b><tt>.<\/tt><\/b>” represents an initial condition where information about the current excited state is available, but which is not selected for dynamics. A hash mark “<b><tt>#<\/tt><\/b>” represents an initial condition which is selected for dynamics. A question mark “<b><tt>?<\/tt><\/b>” represents initial conditions for which no information about the excited state is available (e.g. if the initial excited-state calculation failed). The tutorial shows an example of this output.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The content of the initial conditions file is also summarized in a table giving the number of initial conditions selected per state. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Initial states for dynamics setup  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The user has to input all states from which trajectories should be launched. The numbers must be entered according to the above table giving the number of selected initial conditions per state. It is not allowed to specify inactive states as initial states. The script will give the number of trajectories which can be setup with the specified set of states. If no trajectories can be setup, the user has to specify another set of initial states. The initial state will be written to the S<span style=\"font-size:x-small\">HARC<\/span> input, specified in the same representation as given in the initial conditions file. The initial coefficients will be determined automatically by S<span style=\"font-size:x-small\">HARC<\/span>, according to the description in section <a href=\"#ssec:input:keywords\">4.1.3<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Starting index for dynamics setup and number of trajectories  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Specifies the first initial condition within the initial condition file to be included in the setup. This is useful, for example, if the user might setup 50 trajectories starting with index 1. <b><tt>setup_traj.py<\/tt><\/b> reports afterwards the last initial condition to be used for setup, e.g. index 90. Later, the user can setup additional trajectories, starting with index 91.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Random number generator seed  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The random number generator in <b><tt>setup_traj.py<\/tt><\/b> is used to randomly generate RNG seeds for the S<span style=\"font-size:x-small\">HARC<\/span> input. Instead of typing an integer, typing “<b><tt>!<\/tt><\/b>” will initialize the RNG from the system time. Note that this will not be reproducible, i.e. repeating the <b><tt>setup_traj.py<\/tt><\/b> run (with the same input) with “<b><tt>!<\/tt><\/b>” as random seed will give for the same trajectories different RNG seeds. Affects the keyword <b><tt>RNGseed<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Interface  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this point, choose any of the displayed interfaces to carry out the ab initio calculations.<br \/>\nEnter the corresponding number.<br \/>\nThe choice of the interface influences some dynamics options which can be set in the next section of the <b><tt>setup_traj.py<\/tt><\/b> input.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you selected <b><tt>SHARC_LEGACY.py<\/tt><\/b>, then you have to subsequently select the legacy interface that you intend to use.<br \/>\nIf you selected a hybrid interface, then you will subsequently be queried with the path to the corresponding template file, so that the hybrid interface can figure out the child interface it should use.<br \/>\nThis might continue recursively until all interfaces in the interface call tree are known.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Method  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here, the user can either choose TSH (surface hopping using the SHARC method) or SCP (self-consistent potential, i.e., Ehrenfest dynamics).<br \/>\nThis choice affects a large number of subsequent questions.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Simulation Time  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This is the maximum time that S<span style=\"font-size:x-small\">HARC<\/span> will run the dynamics simulation. If trajectories need to be run for longer time, it is recommended to first let the simulation finish. Afterwards, increase the simulation time in the corresponding S<span style=\"font-size:x-small\">HARC<\/span> input file (keyword <b><tt>tmax<\/tt><\/b>) and add the restart keyword (also make sure that the <b><tt>norestart<\/tt><\/b> keyword is not present). Then the simulation can be restarted by running again the <b><tt>run.sh<\/tt><\/b> script. Sets the keyword <b><tt>tmax<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Simulation Time Step  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This gives the time step for the dynamics. The on-the-fly ab initio calculations are performed with this time step, as is the propagation of the nuclear coordinates. A shorter time step gives more accurate results, especially if light atoms (hydrogen) are subjected to high kinetic energies or steep gradients. Of course a shorter time step is computationally more expensive. A good compromise in many situations is 0.5 fs. Sets the keyword <b><tt>stepsize<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Integrator  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here, the user can select between the fixed velocity-Verlet (<b><tt>fvv<\/tt><\/b>) and the adaptive velocity-Verlet (<b><tt>avv<\/tt><\/b>) algorithm.<br \/>\nNote that the adaptive algorithm is incompatible with several other functionality of S<span style=\"font-size:x-small\">HARC<\/span> (e.g., wave function overlaps, output stride control, thermostats).<br \/>\nIf the adaptive algorithm is chosen, <b><tt>setup_traj.py<\/tt><\/b> automatically removes wave function overlaps from the feature set, so that local diabatization will not be available when the propagation method is queried later.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the adaptive algorithm is chosen, <b><tt>setup_traj.py<\/tt><\/b> asks for the convergence threshold of the total energy (in eV).<br \/>\nThe adaptive algorithm will reduce the time step if this threshold is exceeded by the change in total energy between two time steps.<br \/>\nNote that <b><tt>setup_traj.py<\/tt><\/b> does not allow to set the other keywords that control the adaptive integrator (<b><tt>stepsize_min<\/tt><\/b>, <b><tt>stepsize_max<\/tt><\/b>, <b><tt>stepsize_min_exp<\/tt><\/b>, <b><tt>stepsize_max_exp<\/tt><\/b>).<br \/>\nHere, the defaults are to reduce the time step by half when total energy conservation is violated, possibly multiple times until the time step is one sixteenth of the original one.<br \/>\nThe time step is increased by a factor of 2 when the total energy conservation is overachieved (smaller than a fifth of the threshold).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of substeps  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This gives the number of substeps for the interpolation of the Hamiltonian for the propagation of the electronic wave function. Usually, 25 substeps are sufficient. In cases where the diagonal elements of the Hamiltonian are very large (very large excitation energies or a badly chosen reference energy) more substeps might be necessary. Sets the keyword <b><tt>nsubsteps<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Prematurely terminate trajectories  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Usually, trajectories which relaxed to the ground state do not recross to an excited state, but vibrate indefinitely in the ground state. If the user is not interested in these vibrations, such trajectories can be terminated prematurely in order to save computational resources. A threshold of 10-20 fs is usually a good choice to safely detect ground state relaxation. Sets the keyword <b><tt>killafter<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Representation for the dynamics  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Either the diagonal representation can be chosen (by typing “<b><tt>yes<\/tt><\/b>“) to perform dynamics with the S<span style=\"font-size:x-small\">HARC<\/span> methodology, or the dynamics can be performed on the MCH states (spin-diabatic dynamics <a href=\"#Granucci2012JCP\" class=\"tth_citeref\">[26<\/a>], FISH <a href=\"#Mitric2009PRA\" class=\"tth_citeref\">[25<\/a>]). Sets the keyword <b><tt>surf<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Spin-orbit couplings  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If more than just singlet states are requested, the script asks whether spin-orbit couplings should be computed. If the chosen interface cannot provide spin-orbit couplings, this question is not posed and automatically answered.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Quantities describing the non-adiabatic couplings  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Electronic propagation can be performed with temporal derivatives, nonadiabatic coupling vectors or overlap matrices (Local diabatization). Enter the corresponding number. Note that depending on the chosen interface, some options might not be available, as displayed by <b><tt>setup_traj.py<\/tt><\/b>. Also note that currently, no interface can provide temporal derivatives (because their computation involves calculating the overlap matrix and then local diabatization can be done instead). Sets the keyword <b><tt>coupling<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If nonadiabatic coupling vectors are chosen, the user is asked whether overlap matrices should be computed anyways to provide wave function phase tracking information. As the overlap calculations are usually fast compared to other steps, this is recommended.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Gradient transformation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The nonadiabatic coupling vectors can be used to correctly transform the gradients to the diagonal representation. If nonadiabatic coupling vectors are used anyways, this option is strongly recommended, since it gives more accurate gradients for no additional cost. Sets the keyword <b><tt>gradcorrect<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files. If the dynamics uses the MCH representation, this question is not asked. <\/p>\n<div class=\"p\"><!----><\/div>\n<h4>Questions for surface hopping<\/h4>\n<p> The following keywords are only posed if the selected method is surface hopping.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Surface hop treatment  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This option determines how the total energy is conserved after a surface hop and whether frustrated hops lead to reflection. Sets the keywords <b><tt>ekincorrect<\/tt><\/b> and <b><tt>reflect_frustrated<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Decoherence correction  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For most applications, a decoherence correction should be enabled. This controls the <b><tt>decoherence_scheme<\/tt><\/b> (and <b><tt>decoherence_param<\/tt><\/b> keywords in the S<span style=\"font-size:x-small\">HARC<\/span> input files. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that <b><tt>setup_traj.py<\/tt><\/b> does not allow to modify the α parameter for the energy-based decoherence (keyword <b><tt>decoherence_param<\/tt><\/b>). In order to change <b><tt>decoherence_param<\/tt><\/b>, the user has to manually edit the S<span style=\"font-size:x-small\">HARC<\/span> input files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Surface hopping scheme  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Choose one of the available schemes to compute the hopping probabilities or turn off hopping.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>You can also activate forced hops to the ground state, which is sometimes useful for single-reference methods that do not describe the ground state-excited state crossing topology correctly.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Scaling and Damping  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>These two prompts set the keywords <b><tt>scaling<\/tt><\/b> and <b><tt>damping<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files. The scaling parameter has to be positive, and the damping parameter has to be in the interval [0,1].<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Atom masking  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In some cases, the script will ask to specify the atoms to which decoherence\/rescaling\/reflection should be applied.<br \/>\nSee section <a href=\"#chap:input\">4<\/a> for explanations (keyword <b><tt>atommask<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Gradient and nonadiabatic coupling selection  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For dynamics in the MCH representation, selection of gradients is used by default, and only one gradient (of the current state) is calculated. Selection of nonadiabatic couplings is only relevant if they are used (for propagation, gradient correction or rescaling of the velocities after a surface hop). For the selection threshold, usually 0.5 eV is sufficient, except if spin-orbit coupling is very strong and hence the gradients mix strongly.<br \/>\nSets the keywords <b><tt>grad_select<\/tt><\/b> and <b><tt>nac_select<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files.<\/p>\n<div class=\"p\"><!----><\/div>\n<h4>Questions for self-consistent potential methods<\/h4>\n<p> The following keywords are only posed if the selected method is self-consistent potential (SCP), i.e., coherent switching with decay of mixing (CSDM).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Nuclear EOM  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the coherent nuclear propagation for the SCP method, the nuclear equation of motion can be controlled using the <b><tt>neom<\/tt><\/b> keyword. Note that this choice is independent of the form of coupling used in the electronic equation of motion.<br \/>\nChoices are <b><tt>ddr<\/tt><\/b> or <b><tt>gdiff<\/tt><\/b>, to either include the full NAC vectors into the gradient of the effective potential, or to construct effective NAC vectors from the gradient difference vector.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Switching scheme  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In decay-of-mixing algorithms, it is necessary to select an option for computing the probabilities of switching pointer states. This can be specified using the <b><tt>switching_procedure<\/tt><\/b> keyword.<br \/>\nCurrently, one can choose <b><tt>off<\/tt><\/b> or <b><tt>csdm<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Decoherence scheme and Decoherence time method  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For methods based on self-consistent potentials, decoherence is introduced through the decay-of-mixing algorithm. The use of the decay-of-mixing decoherence scheme is enabled by setting <b><tt>decoherence_scheme dom<\/tt><\/b>, while the method for computing the decoherence time can be specified using the <b><tt>decotime_method<\/tt><\/b> keyword.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Damping  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This prompt sets the keyword <b><tt>damping<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input files. The damping parameter has to be in the interval [0,1].<\/p>\n<div class=\"p\"><!----><\/div>\n<h4>Remaining general questions<\/h4>\n<div class=\"p\"><!----><\/div>\n<p><b>RATTLE  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script will ask whether RATTLE should be used.<br \/>\nIf this is the case, the user has to provide a <b><tt>rattle<\/tt><\/b> file.<br \/>\nThese can be prepared manually or with <b><tt>setup_from_prmtop.py<\/tt><\/b> (Section <a href=\"#sec:setup_from_prmtop.py\">7.12<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Thermostat  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the adaptive velocity-Verlet algorithm is not used, the user gets prompted whether a thermostat should be used.<br \/>\nCurrently, only the Langevin thermostat is available.<br \/>\nThe user has to provide the desired temperature (in K), RNG seed, and the friction coefficient (in fs<sup>−1<\/sup>).<br \/>\n<b><tt>setup_traj.py<\/tt><\/b> does not support setting up multiple thermostat regions, such options should be added manually after setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Droplet and tether potentials  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user gets asked whether to use a droplet and\/or tethering potential.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>First, the droplet potential is set up.<br \/>\nThe user can either manually enter the force constant and offset radius, or let these parameters be determined from the system size.<br \/>\nTo do so, the user has to enter five parameters.<br \/>\nFirst, the density, molar mass, and number of molecules define the radius of the solvent sphere.<br \/>\nWe recommend to use the density from the MD output, the molar mass of the solvent, and the number of solvent molecules (ignoring the solute).<br \/>\nSecond, the user sets the “wokness”, a parameter between 0 and 1 that defines how extensive the flat-bottom part of the droplet potential is.<br \/>\nGiving a value of 1 produces a harmonic oscillator with no flat-bottom part, and a value of 0 produces a particle-in-a-box-like flat potential with infinite walls.<br \/>\nWe recommend values of around 0.2-0.5; values close to 1 will lead to the droplet potential affecting the inner droplet region and values close to 0 will produce unphysical and instable behaviour close to the wall.<br \/>\nThe droplet offset radius is computed from the sphere radius and the wokness parameter.<br \/>\nThe fifth parameter is the pressure at the surface of the sphere.<br \/>\nThe force constant is then determined from the sphere and offset radius, such that the pressure is zero at the offset radius and equal to the entered pressure at the sphere radius.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In either case, after the definition of the droplet potential, the user can define the atoms that feel the droplet potential.<br \/>\nTypically, <b><tt>all<\/tt><\/b> should be chosen.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Second, the tether is set up.<br \/>\nHere, the user has to manually enter the tether force constant, tether position, and tether offset radius.<br \/>\nSubsequently, the atoms affected by the tether should be specified.<br \/>\nHere, typically only some or all of the solute molecule’s atoms are chosen.<br \/>\nWe recommend to set the offset radius of the tether to be larger than the solute molecule, so that the tether does not produce any force unless the molecule tries to diffuse towards the surface of the droplet.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Laser file  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The user can specify to use an external laser field during the dynamics, and has to provide the path to the laser file (see section <a href=\"#sec:laser.x\">7.11<\/a> and <a href=\"#sec:laserfile\">4.5<\/a>). <b><tt>setup_traj.py<\/tt><\/b> will check whether the number of steps and the time steps are compatible to the dynamics. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the interface can provide dipole moment gradients, <b><tt>setup_traj.py<\/tt><\/b> will also ask whether dipole moment gradients should be included in the simulations. Currently, these are not fully supported yet.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Dyson norm calculation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the interface is compatible, the user can request that Dyson norms are calculated on-the-fly. This option is only asked if Dyson norms can be computed (i.e., if states are present which differ by one electron, e.g., singlets and doublets).<br \/>\nNote that Dyson norms are not saved in NetCDF file format (question below).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b> T<span style=\"font-size:x-small\">HEO<\/span>DORE calculations  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the interface is compatible, the user can request that T<span style=\"font-size:x-small\">HEO<\/span>DORE is run on-the-fly.<br \/>\nNote that TheoDORE descriptors are not saved in NetCDF file format (question below).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.13.2\"><\/a><\/p>\n<h3>\n7.13.2  Interface-specific input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>After the dynamics and properties settings, the setup script will call the chosen interface’s own setup routines.<br \/>\nThe interface will ask the user for all necessary information, depending on the requested quantities.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For hybrid interfaces, the children’s setup routines will also be called at some point, possibly in a recursive fashion, until all interfaces in the call tree are setup.<br \/>\nSee Chapter <a href=\"#chap:interfaces\">6<\/a> for the questions that the interfaces ask.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.13.3\"><\/a><\/p>\n<h3>\n7.13.3  Running and output control<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>PySHARC setup  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>setup_traj.py<\/tt><\/b> will ask whether the user wants to run the trajectories using PySHARC, i.e., use <b><tt>driver.py<\/tt><\/b> instead of <b><tt>sharc.x<\/tt><\/b>.<br \/>\nNote that this is not possible if the adaptive time step integrator was chosen or if the S<span style=\"font-size:x-small\">HARC<\/span> package was not compiled with PySHARC support.<br \/>\nFor details, see Section <a href=\"#sec:drivers\">3.4<\/a> and Section <a href=\"#sec:install\">2.2<\/a>.<br \/>\nBriefly, PySHARC is intended for running fast potential energy methods, like analytical, vibronic coupling, machine learning, or force field models.<br \/>\nFor these models, PySHARC removes many overheads and allows orders of magnitude faster execution than <b><tt>sharc.x<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>NetCDF output format  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the script will ask whether output should be written in NetCDF format and whether nuclear and electronic information should be written to separate files.<br \/>\nSee Sections <a href=\"#sec:netcdf\">5.4<\/a> and <a href=\"#sec:netcdf_nuc\">5.5<\/a> for details.<br \/>\nThese options are only available if PySHARC support is installed.<br \/>\nThey lower I\/O demand and disk space and increase execution time, especially for fast methods.<br \/>\n<b>Note that with this format, Dyson norms, TheoDORE descriptors (and other properties), gradients, and nonadiabatic coupling vectors are not saved.<br \/>\nAdditionally, trajectory restart is not possible with NetCDF output format.<\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Separate output files should be used if the system has a huge number of states or atoms, and the user wants to separately set the output stride (below) for nuclei and electrons.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Output quantities  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The user can finally define which quantities are saved in the data file.<br \/>\nThe script will only ask for quantities that are computed and that can be saved.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Output stride  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user can adjust the data is written to <b><tt>output.dat<\/tt><\/b>, <b><tt>output.dat.nc<\/tt><\/b>, and <b><tt>output_NUC.dat.nc<\/tt><\/b>.<br \/>\nThe files <b><tt>output.log<\/tt><\/b>, <b><tt>output.lis<\/tt><\/b>, and <b><tt>output.xyz<\/tt><\/b> are not affected.<br \/>\nSee details in Section <a href=\"#sec:inputfile\">4.1<\/a> for details about the strides.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.13.4\"><\/a><\/p>\n<h3>\n7.13.4  Run script setup<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>This input section is very similar to the one in <b><tt>setup_init.py<\/tt><\/b> (see section <a href=\"#sec:setup_init.py\">7.8<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.13.5\"><\/a><\/p>\n<h3>\n7.13.5  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg7.2\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/dirs_traj.png\"> <\/p>\n<div style=\"text-align:center\">Figure 7.2: Directory structure created by <b><tt>setup_traj.py<\/tt><\/b>. Directories are in blue, executable scripts in green and regular files in black and white. Interface files usually include initial MO coefficients, template files and interface input files.<\/div>\n<p> <a id=\"fig:dirs_traj\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>setup_traj.py<\/tt><\/b> will create for each initial state a directory where all trajectories starting in this state will be put. If the initial conditions file specified that the initial conditions are in the MCH representation, then the initial states will be assumed to be in the MCH representation as well. In this case, the directories will be named <b><tt>Singlet_0<\/tt><\/b>, <b><tt>Singlet_1<\/tt><\/b>, …, <b><tt>Doublet_0<\/tt><\/b>, <b><tt>Triplet_1<\/tt><\/b>, … If the initial states are in the diagonal representation, then the directories are simply called <b><tt>X_1<\/tt><\/b>, … since they do not have a definite spin.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In each directory, subdirectories called <b><tt>TRAJ_%05i<\/tt><\/b> are created, where <b><tt>%05i<\/tt><\/b> is the initial condition index, padded to 5 digits with zeroes. In each trajectory’s directory, an S<span style=\"font-size:x-small\">HARC<\/span> input file called <b><tt>input<\/tt><\/b> will be created, which contains all the dynamics options chosen during the <b><tt>setup_traj.py<\/tt><\/b> run. Also, files <b><tt>geom<\/tt><\/b> and <b><tt>veloc<\/tt><\/b> will be created. For trajectories setup with <b><tt>setup_traj.py<\/tt><\/b>, the determination of the initial wave function coefficients is done by S<span style=\"font-size:x-small\">HARC<\/span>.<br \/>\nFurthermore, in each trajectory directory a subdirectory <b><tt>QM<\/tt><\/b> is created, where the <b><tt>runQM.sh<\/tt><\/b> script containing the call to the interface is put (if using <b><tt>sharc.x<\/tt><\/b>. In the directory <b><tt>QM<\/tt><\/b> also all interface-specific input files will be copied.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For each trajectory, a <b><tt>run.sh<\/tt><\/b> script will be created, which can be executed to run the dynamics simulation. You might need to adapt the run script to your cluster setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>setup_traj.py<\/tt><\/b> also creates a script <b><tt>all_run_traj.sh<\/tt><\/b>, which can be used to execute all trajectories sequentially.<br \/>\nNote that this is intended for small test trajectories, and should not be used for expensive production trajectories.<br \/>\nFor the latter, <b><tt>setup_traj.py<\/tt><\/b> can optionally create a script <b><tt>all_qsub_traj.sh<\/tt><\/b>, which can be executed to submit all trajectories to a queueing system. You might need to adapt also this script to your cluster setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The full directory structure created by <b><tt>setup_traj.py<\/tt><\/b> is given in figure <a href=\"#fig:dirs_traj\">7.2<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.14\"><\/a><\/p>\n<h2>\n7.14  File transfer: <b><tt>retrieve.sh<\/tt><\/b><\/h2>\n<p><a id=\"sec:retrieve.sh\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In some cases, S<span style=\"font-size:x-small\">HARC<\/span> will run on some temporary directory, and not in the directory where the trajectories have been submitted from. The shell script <b><tt>retrieve.sh<\/tt><\/b> is a simple <b><tt>scp<\/tt><\/b> wrapper, which can be executed (in a directory where a trajectory has been sent from) in order to retrieve the output files of this trajectory. This might not work for every cluster setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>It relies on the presence of the file <b><tt>host_infos<\/tt><\/b>. All trajectories set up with <b><tt>setup_traj.py<\/tt><\/b> create this file after the trajectory has been started with <b><tt>run.sh<\/tt><\/b>. <b><tt>retrieve.sh<\/tt><\/b> reads <b><tt>host_infos<\/tt><\/b> to determine the hostname and working directory of the trajectory and then uses <b><tt>scp<\/tt><\/b> to retrieve the output and restart files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script can be called with the option “<b><tt>-lis<\/tt><\/b>” in order to only retrieve the <b><tt>output.lis<\/tt><\/b> file, but not the other output files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the script is called with the option “<b><tt>-res<\/tt><\/b>” then also the restart files and the content of the <b><tt>restart\/<\/tt><\/b> directory are copied.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>It is advisable to configure public-key authentification for the hosts running the trajectories, so that not for every execution of <b><tt>retrieve.sh<\/tt><\/b> a password has to be entered.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.15\"><\/a><\/p>\n<h2>\n7.15  Resetting trajectories: <b><tt>clean_traj.sh<\/tt><\/b><\/h2>\n<p><a id=\"sec:clean_traj.sh\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Especially when developing and when performing preliminary test trajectories, it is useful to quickly reset a trajectory, in order to run it again.<br \/>\nThis is especially important because the S<span style=\"font-size:x-small\">HARC<\/span> drivers will refuse to run a trajectory from time zero if restart files are present.<br \/>\nSimilarly, most interfaces will raise an error if interface-specific restart files are present that do not match the requested time step.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The tool <b><tt>clean_traj.sh<\/tt><\/b> removes all <b><tt>output<\/tt><\/b> and <b><tt>restart<\/tt><\/b> files, the <b><tt>output_data\/<\/tt><\/b> folder, and empty marker files (<b><tt>STOP<\/tt><\/b>, <b><tt>CRASHED<\/tt><\/b>, <b><tt>DONT_ANALYZE<\/tt><\/b>, <b><tt>RUNNING<\/tt><\/b>, <b><tt>DEAD<\/tt><\/b>).<br \/>\nAdditionally, it recursively removes files from the <b><tt>QM\/<\/tt><\/b> and <b><tt>restart\/<\/tt><\/b> directories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.15.1\"><\/a><\/p>\n<h3>\n7.15.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Within a <b><tt>TRAJ_%05i\/<\/tt><\/b> folder, simply call the script.<br \/>\nIf the script is executed in a directory that does not match this naming convention, it will exit without deleting.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.16\"><\/a><\/p>\n<h2>\n7.16  Ensemble Diagnostics Tool: <b><tt>diagnostics.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:diagnostics.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The purpose of this script is to automatize the critical step of checking the trajectories in an ensemble for sanity before beginning the ensemble analysis.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The tool can check several different aspects of the trajectories.<br \/>\nFirst, it checks whether all relevant output files of the trajectories are present, and if they are complete and consistent (e.g., no missing lines due to network\/file system problems).<br \/>\nSecond, it checks simulation progress and status (e.g., whether the trajectory is running, crashed, finished, or stopped).<br \/>\nThird, it can check several energy-related requirements: total energy conservation, smoothness of kinetic and potential energy, and hopping energy differences.<br \/>\nIt also checks for conservation of total population, and for trajectories using local diabatization also intruder states are checked.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the diagnostics script can also be used to automatically run the <b><tt>data_extractor.x<\/tt><\/b> for all trajectories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Also note that <b><tt>diagnostics.py<\/tt><\/b> will not work if the <b><tt>printlevel<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> trajectories was lower than 2.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.16.1\"><\/a><\/p>\n<h3>\n7.16.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script is interactive, simply start it with no command-line arguments or options:<\/p>\n<pre>\nuser@host> $SHARC\/diagnostics.py\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.16.2\"><\/a><\/p>\n<h3>\n7.16.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>Paths to trajectories  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>First the script asks the user to specify all directories for whose content the analysis should be performed. Enter one directory path at a time, and finish the directory input section by typing “<b><tt>end<\/tt><\/b>“. Please do not specify each trajectory directory separately, but specify their parent directories, e.g. the directories <b><tt>Singlet_1<\/tt><\/b> and <b><tt>Singlet_2<\/tt><\/b>. <b><tt>diagnostics.py<\/tt><\/b> will automatically include all trajectories contained in these directories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Unlike the ensemble analysis scripts (these are <b><tt>populations.py<\/tt><\/b>, <b><tt>transition.py<\/tt><\/b>, <b><tt>crossing.py<\/tt><\/b>, <b><tt>trajana_essdyn.py<\/tt><\/b>, <b><tt>trajana_nma.py<\/tt><\/b>, and <b><tt>data_collector.py<\/tt><\/b>, see below), <b><tt>diagnostics.py<\/tt><\/b> ignores files which indicate the status of a trajectory (<b><tt>CRASHED<\/tt><\/b>, <b><tt>RUNNING<\/tt><\/b>, <b><tt>DONT_ANALYZE<\/tt><\/b>) and carries out the diagnostics routines as long as it identifies a directory as a S<span style=\"font-size:x-small\">HARC<\/span> trajectory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Settings  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The settings for the diagnostics run can be modified with a simple menu, which can be navigated with the commands <b><tt>show<\/tt><\/b>, <b><tt>help<\/tt><\/b>, <b><tt>end<\/tt><\/b>, and where the settings can be modified with <b><tt><key> <value><\/tt><\/b> (e.g., <b><tt>hop_energy 0.2<\/tt><\/b> sets the corresponding option to 0.2 eV).<br \/>\nA list of the settings is given in Table <a href=\"#tab:diagnostics\">7.9<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Generally, the keywords <b><tt>missing_output<\/tt><\/b>, <b><tt>missing_restart<\/tt><\/b>, and <b><tt>normal_termination<\/tt><\/b> should always be left at <b><tt>True<\/tt><\/b>, since checking them is cheap and the obtained information is important.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that <b><tt>data_extractor.x<\/tt><\/b> or <b><tt>data_extractor_NetCDF.x<\/tt><\/b> is always run for all trajectories, except if <b><tt>output.dat<\/tt><\/b> is older than the files in <b><tt>output_data\/<\/tt><\/b>.<br \/>\nDuring the check of each trajectory, <b><tt>output.lis<\/tt><\/b>, <b><tt>output_data\/energies.out<\/tt><\/b>, and <b><tt>output_data\/coeff_diag.out<\/tt><\/b> are furthermore checked for missing time steps.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.9\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.9: List of the settings for <b><tt>diagnostics.py<\/tt><\/b>.<\/div>\n<p> <a id=\"tab:diagnostics\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Key <\/td>\n<td align=\"left\">Value <\/td>\n<td align=\"center\">Explanation<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">missing_output <\/td>\n<td align=\"left\">Boolean <\/td>\n<td align=\"center\">Checks if öutput.lis”, öutput.log”, öutput.xyz”, öutput.dat” are existing. Setting to <b><tt>False<\/tt><\/b> only suppresses output, but files are always checked.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">missing_restart <\/td>\n<td align=\"left\">Boolean <\/td>\n<td align=\"center\">Checks if “restart.ctrl”, “restart.traj”, “restart\/” are existing. Files are not checked if set to <b><tt>False<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">normal_termination <\/td>\n<td align=\"left\">Boolean <\/td>\n<td align=\"center\">Checks for status of trajectory:<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><b><tt>RUNNING<\/tt><\/b>: no finish message in <b><tt>output.log<\/tt><\/b>, last step started recently.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><b><tt>STUCK<\/tt><\/b>: no finish message in <b><tt>output.log<\/tt><\/b>, last step started long ago.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><b><tt>CRASHED<\/tt><\/b>: error message in <b><tt>output.log<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><b><tt>FINISHED<\/tt><\/b>: finish message in <b><tt>output.log<\/tt><\/b>.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><b><tt>FINISHED (stopped by user)<\/tt><\/b>: finished due to <b><tt>STOP<\/tt><\/b> file.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">etot_window <\/td>\n<td align=\"left\">Float <\/td>\n<td align=\"center\">Maximum permissible drift (along full trajectory) in the total energy (in eV).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">etot_step <\/td>\n<td align=\"left\">Float <\/td>\n<td align=\"center\">Maximum permissible total energy difference between two successive time steps (in eV).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">epot_step <\/td>\n<td align=\"left\">Float <\/td>\n<td align=\"center\">Maximum permissible active state potential energy difference between two successive time steps (in eV). Not checked for time steps where a hop occurred.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ekin_step <\/td>\n<td align=\"left\">Float <\/td>\n<td align=\"center\">Maximum permissible kinetic energy difference between two successive time steps (in eV).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">pop_window <\/td>\n<td align=\"left\">Float <\/td>\n<td align=\"center\">Maximum permissible drift in total population.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">hop_energy <\/td>\n<td align=\"left\">Float <\/td>\n<td align=\"center\">Maximum permissible change in active state energy during a surface hop (in eV).<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">intruders <\/td>\n<td align=\"left\">Boolean <\/td>\n<td align=\"center\">Checks if intruder state messages in öutput.log” refer to active state.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">always_update <\/td>\n<td align=\"left\">Boolean <\/td>\n<td align=\"center\">Run the <b><tt>data_extractor.x<\/tt><\/b> always, even if <b><tt>output.dat<\/tt><\/b> is older than the produced files.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">extractor_mode <\/td>\n<td align=\"left\">String <\/td>\n<td align=\"center\">Controls command line flags for the <b><tt>data_extractor.x<\/tt><\/b>:<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><b><tt>xs<\/tt><\/b>: Uses the <b><tt>-xs<\/tt><\/b> flag.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><b><tt>s<\/tt><\/b>: Uses the <b><tt>-s<\/tt><\/b> flag.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><b><tt>l<\/tt><\/b>: Uses the <b><tt>-l<\/tt><\/b> flag.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><b><tt>xl<\/tt><\/b>: Uses the <b><tt>-xl<\/tt><\/b> flag.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><b><tt>dont<\/tt><\/b>: <b><tt>data_extractor.x<\/tt><\/b> is never run (this leads to incomplete diagnostics, but is very fast).<\/td>\n<\/tr>\n<\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p><b>Trajectory Flagging  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>diagnostics.py<\/tt><\/b> determines for each trajectory a “maximum usable time” value (T<sub>mu<\/sub>).<br \/>\nThis value is either the total simulation time or the time when the first violation (problems with time step consistency, total energy conservation, potential\/kinetic energy smoothness, hopping energy restriction, or intruder states) in the trajectory appeared.<br \/>\nThe script prints the T<sub>mu<\/sub> values for all trajectories at the end.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The user can then give a threshold for T<sub>mu<\/sub>, so that <b><tt>diagnostics.py<\/tt><\/b> excludes all trajectories with values smaller than the threshold from analysis (the script will create a file <b><tt>DONT_ANALYZE<\/tt><\/b> in the directory of each affected trajectory).<br \/>\nIn this way it is possible to perform ensemble analysis for a given simulation length while ignoring problematic trajectories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When choosing the threshold for T<sub>mu<\/sub>, keep in mind that a compromise usually has to be made.<br \/>\nA small value of the threshold will mean that many trajectories are admitted for analysis (because problems occurring late do not matter), giving good statistics, but that the analysis can only be carried out for the first part of the simulation time.<br \/>\nOn the other hand, choosing a large threshold allows analysis of a satisfactory simulation time, but only few trajectories will be included in the analysis (only the ones where no problems occurred for many time steps).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>It is advisable that the chosen threshold value is used as input for the ensemble analysis scripts which ask for a maximum analysis time (<b><tt>populations.py<\/tt><\/b>, <b><tt>transition.py<\/tt><\/b>, <b><tt>crossing.py<\/tt><\/b>, <b><tt>trajana_essdyn.py<\/tt><\/b>, <b><tt>trajana_nma.py<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.17\"><\/a><\/p>\n<h2>\n7.17  Data Extractor: <b><tt>data_extractor.x<\/tt><\/b><\/h2>\n<p><a id=\"sec:data_extractor.x\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>data_extractor.x<\/tt><\/b> is the primary tool to extract useful, tabular data from the <b><tt>output.dat<\/tt><\/b> file that is produced by <b><tt>sharc.x<\/tt><\/b>.<br \/>\nThe produced files can then be further processed, e.g., by plotting them or by computing ensemble statistics with <b><tt>data_collector.py<\/tt><\/b> (section <a href=\"#sec:data_collector.py\">7.30<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.17.1\"><\/a><\/p>\n<h3>\n7.17.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>data_extractor.x<\/tt><\/b> is a command line tool, and is called with the <b><tt>output.dat<\/tt><\/b> file as an argument, and possibly with some options.<\/p>\n<pre>\nuser@host> $SHARC\/data_extractor.x [options] output.dat\n<\/pre>\n<p>The program will create a directory <b><tt>output_data\/<\/tt><\/b> in the current working directory (not necessarily in the directory where <b><tt>output.dat<\/tt><\/b> resides). In this directory, several files are written, containing, e.g., the potential energies depending on time, populations depending on time, etc.<br \/>\nWhich files are created can be controlled with the command line options, which are summarized in Table <a href=\"#tab:dataextractor_options\">7.10<\/a>. For most applications, using the <b><tt>-xs<\/tt><\/b> or <b><tt>-s<\/tt><\/b> flags should be sufficient.<br \/>\nThe default is equivalent to <b><tt>-s<\/tt><\/b>.<br \/>\nNote that some options might not be available if the necessary data is not written to <b><tt>output.dat<\/tt><\/b> (see write options in Table <a href=\"#tab:input\">4.1<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The program will extract the complete <b><tt>output.dat<\/tt><\/b> file until it reaches the EOF. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>data_extractor.x<\/tt><\/b> program will automatically detect the format of the <b><tt>output.dat<\/tt><\/b> file (the S<span style=\"font-size:x-small\">HARC<\/span>1 release had a different file format than the more recent S<span style=\"font-size:x-small\">HARC<\/span>2, S<span style=\"font-size:x-small\">HARC<\/span>3, and S<span style=\"font-size:x-small\">HARC<\/span>4 releases).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that diabatic coefficients can only be obtained if wave function overlaps are present in <b><tt>output.dat<\/tt><\/b>.<br \/>\nFurthermore, the data file must contain all time steps, so diabatic coefficients will be wrong if the <b><tt>output_data_steps<\/tt><\/b> keyword is used to suppress writing of some time steps.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you are interested in diabatic populations averaged over an ensemble, some special steps need to be taken.<br \/>\nThe reason is that, by default, <b><tt>data_extractor.x<\/tt><\/b> equates the diabatic basis with the electronic states as provided in the first time step of the trajectory.<br \/>\nHence, different trajectories have different diabatic bases and averages across several trajectories are meaningless.<br \/>\nIn order to provide a common basis, run the initial condition calculations (using <b><tt>setup_init.py<\/tt><\/b>) with <em>reference overlaps<\/em>.<br \/>\nThe resulting <b><tt>QM.out<\/tt><\/b> file will then contain the overlaps between the states at the equilibrium geometry and the initial geometry.<br \/>\nThe <b><tt>QM.out<\/tt><\/b> file can then be provided to <b><tt>data_extractor.x<\/tt><\/b>:<\/p>\n<pre>\nuser@host:traj\/Singlet_2\/TRAJ_00123> ln -s init\/ICOND_00123\/ Reference\nuser@host:traj\/Singlet_2\/TRAJ_00123> $SHARC\/data_extractor.x output.dat\n<\/pre>\n<p><b><tt>data_extractor.x<\/tt><\/b> will attempt to find and open a file called <b><tt>Reference\/QM.out<\/tt><\/b> and extract the wave function overlaps from there.<br \/>\nThese are then used to define the diabatic basis.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.17.2\"><\/a><\/p>\n<h3>\n7.17.2  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>After the program finishes, the directory <b><tt>output_data\/<\/tt><\/b> contains a number of files. In each file, the number of columns is dependent in the total number n of states i ∈ {1…n}. The content of the files is listed in Table <a href=\"#tab:outputdata\">7.11<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The file <b><tt>expec.out<\/tt><\/b> contains the information of <b><tt>energy.out<\/tt><\/b>, <b><tt>spin.out<\/tt><\/b> and <b><tt>fosc.out<\/tt><\/b> in one file. The content of <b><tt>expec.out<\/tt><\/b> can be conveniently plotted by using <b><tt>make_gnuscript.py<\/tt><\/b> (section <a href=\"#sec:make_gnuscript.py\">7.22<\/a>) to generate a G<span style=\"font-size:x-small\">NUPLOT<\/span> script.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.10\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.10: Command-line options for <b><tt>data_extractor.x<\/tt><\/b>.<\/div>\n<p> <a id=\"tab:dataextractor_options\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit. <\/td>\n<td align=\"left\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-f <\/td>\n<td align=\"left\">File name (can also be given without file name) <\/td>\n<td align=\"left\">File name must be given <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-sk <\/td>\n<td align=\"left\">skip parsing of geom., vel., grad., NAC. <\/td>\n<td align=\"left\">False <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-e <\/td>\n<td align=\"left\">Write <b><tt>energy.out<\/tt><\/b> <\/td>\n<td align=\"left\">True <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-d <\/td>\n<td align=\"left\">Write <b><tt>fosc.out<\/tt><\/b> <\/td>\n<td align=\"left\">True <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-da <\/td>\n<td align=\"left\">Write <b><tt>fosc_act.out<\/tt><\/b> <\/td>\n<td align=\"left\">True <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-sp <\/td>\n<td align=\"left\">Write <b><tt>spin.out<\/tt><\/b> <\/td>\n<td align=\"left\">True <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-cd <\/td>\n<td align=\"left\">Write <b><tt>coeff_diag.out<\/tt><\/b>,<br \/>\n <b><tt>coeff_class_diag.out<\/tt><\/b>,<br \/>\n <b><tt>coeff_mixed_diag.out<\/tt><\/b> <\/td>\n<td align=\"left\">True <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-cm <\/td>\n<td align=\"left\">Write <b><tt>coeff_MCH.out<\/tt><\/b>,<br \/>\n <b><tt>coeff_class_MCH.out<\/tt><\/b>,<br \/>\n <b><tt>coeff_mixed_MCH.out<\/tt><\/b> <\/td>\n<td align=\"left\">True <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-cb <\/td>\n<td align=\"left\">Write <b><tt>coeff_diab.out<\/tt><\/b>,<br \/>\n <b><tt>coeff_class_diab.out<\/tt><\/b>,<br \/>\n <b><tt>coeff_mixed_diab.out<\/tt><\/b> <\/td>\n<td align=\"left\">True (if overlaps present) <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-p <\/td>\n<td align=\"left\">Write <b><tt>prob.out<\/tt><\/b> <\/td>\n<td align=\"left\">True <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-x <\/td>\n<td align=\"left\">Write <b><tt>expec.out<\/tt><\/b> <\/td>\n<td align=\"left\">True <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-xm <\/td>\n<td align=\"left\">Write <b><tt>expec_MCH.out<\/tt><\/b> <\/td>\n<td align=\"left\">True <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-id <\/td>\n<td align=\"left\">Write <b><tt>ion_diag.out<\/tt><\/b> <\/td>\n<td align=\"left\">False <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-im <\/td>\n<td align=\"left\">Write <b><tt>ion_MCH.out<\/tt><\/b> <\/td>\n<td align=\"left\">False <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-dd <\/td>\n<td align=\"left\">Write <b><tt>dip_mom_diag.out<\/tt><\/b> <\/td>\n<td align=\"left\">False <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-xs <\/td>\n<td align=\"left\"><b><tt>-e<\/tt><\/b>, <b><tt>, -d<\/tt><\/b>, <b><tt>, -cd<\/tt><\/b>, <b><tt>, -cm<\/tt><\/b>, <b><tt>, -p<\/tt><\/b>, <b><tt>, -x<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-s <\/td>\n<td align=\"left\"><b><tt>-sp<\/tt><\/b>, <b><tt>, -xm<\/tt><\/b>, <b><tt>, -cb<\/tt><\/b>, <b><tt>, -da<\/tt><\/b> plus <b><tt>-xs<\/tt><\/b> <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-l <\/td>\n<td align=\"left\"><b><tt>-id<\/tt><\/b>, <b><tt>, -im<\/tt><\/b> plus <b><tt>-s<\/tt><\/b> <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-xl <\/td>\n<td align=\"left\"><b><tt>-dd<\/tt><\/b> plus <b><tt>-l<\/tt><\/b> (i.e., all) <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.11\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<table>\n<tr>\n<td colspan=\"5\" align=\"left\">\n<div style=\"text-align:center\">Table 7.11: Content of the files written by <b><tt>data_extractor.x<\/tt><\/b>. n is the total number of states, j is a state index (j ∈ {1..n}), and α is the active state.<\/div>\n<\/td>\n<\/tr>\n<p><a id=\"tab:outputdata\"><br \/>\n<\/a><\/p>\n<tr>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><span class=\"roman\">File <\/td>\n<td align=\"left\"># Columns <\/td>\n<td colspan=\"2\" align=\"left\">Columns<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> energy.out <\/td>\n<td align=\"left\">4+n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">Kinetic energy (eV)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">3 <\/td>\n<td align=\"left\">Potential energy (eV) of active state (diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">4 <\/td>\n<td align=\"left\">Total energy (eV)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">4+j <\/td>\n<td align=\"left\">Potential energy (eV) of state j (diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">fosc.out <\/td>\n<td align=\"left\">2+n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">Oscillator strength from lowest to active state (diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+j <\/td>\n<td align=\"left\">Oscillator strength from lowest state to state j (diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">fosc_act.out <\/td>\n<td align=\"left\">1+2n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">1+j <\/td>\n<td align=\"left\">E<sub>j<\/sub>−E<sub>active<\/sub> (in eV, diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">1+n+j <\/td>\n<td align=\"left\">Oscillator strength from active state to state j (diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">spin.out <\/td>\n<td align=\"left\">2+n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">Total spin expectation value of active state<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+j <\/td>\n<td align=\"left\">Total spin expectation value of state j<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coeff_diag.out <\/td>\n<td align=\"left\">2+2n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">Norm of wave function ∑<sub>j<\/sub> |c<sub>j<\/sub><sup>diag<\/sup>|<sup>2<\/sup><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">1+2j <\/td>\n<td align=\"left\">ℜ(c<sub>j<\/sub><sup>diag<\/sup>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+2j <\/td>\n<td align=\"left\">ℑ(c<sub>j<\/sub><sup>diag<\/sup>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coeff_class_diag.out <\/td>\n<td align=\"left\">2+n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+j <\/td>\n<td align=\"left\">δ<sub>jα<\/sub><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coeff_mixed_diag.out <\/td>\n<td align=\"left\">2+n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+j <\/td>\n<td align=\"left\">δ<sub>jα<\/sub><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coeff_MCH.out <\/td>\n<td align=\"left\">2+2n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">Norm of wave function ∑<sub>j<\/sub> |c<sub>j<\/sub><sup>MCH<\/sup>|<sup>2<\/sup><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">1+2j <\/td>\n<td align=\"left\">ℜ(c<sub>j<\/sub><sup>MCH<\/sup>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+2j <\/td>\n<td align=\"left\">ℑ(c<sub>j<\/sub><sup>MCH<\/sup>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coeff_class_MCH.out <\/td>\n<td align=\"left\">2+n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+j <\/td>\n<td align=\"left\">|U<sub>jα<\/sub>|<sup>2<\/sup><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coeff_mixed_MCH.out <\/td>\n<td align=\"left\">2+n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+j <\/td>\n<td align=\"left\">|U<sub>jα<\/sub>|<sup>2<\/sup>+∑<sub>k,l<\/sub>2ℜ(U<sub>jk<\/sub>U<sup>*<\/sup><sub>jl<\/sub>c<sup>diag<\/sup><sub>k<\/sub>c<sup>diag*<\/sup><sub>l<\/sub>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coeff_diab.out <\/td>\n<td align=\"left\">2+2n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">Norm of wave function ∑<sub>j<\/sub> |c<sub>j<\/sub><sup>diab<\/sup>|<sup>2<\/sup><\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">1+2j <\/td>\n<td align=\"left\">ℜ(c<sub>j<\/sub><sup>diab<\/sup>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+2j <\/td>\n<td align=\"left\">ℑ(c<sub>j<\/sub><sup>diab<\/sup>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coeff_class_diab.out <\/td>\n<td align=\"left\">2+2n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+j <\/td>\n<td align=\"left\">|T<sub>jα<\/sub>|<sup>2<\/sup><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">coeff_mixed_diab.out <\/td>\n<td align=\"left\">2+2n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+j <\/td>\n<td align=\"left\">|T<sub>jα<\/sub>|<sup>2<\/sup>+∑<sub>k,l<\/sub>2ℜ(T<sub>jk<\/sub>T<sup>*<\/sup><sub>jl<\/sub>c<sup>diag<\/sup><sub>k<\/sub>c<sup>diag*<\/sup><sub>l<\/sub>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">prob.out <\/td>\n<td align=\"left\">2+n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">Random number from surface hopping<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2+j <\/td>\n<td align=\"left\">Cumulated hopping probability ∑<sub>k=1<\/sub><sup>j<\/sup> P<sub>k<\/sub><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">expec.out <\/td>\n<td align=\"left\">4+3n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">Kinetic energy (eV)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">3 <\/td>\n<td align=\"left\">Potential energy (eV) of active state (diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">4 <\/td>\n<td align=\"left\">Total energy (eV)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">4+j <\/td>\n<td align=\"left\">Potential energy (eV) of state j (diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">4+n+j <\/td>\n<td align=\"left\">Total spin expectation value of state j (diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">4+2n+j <\/td>\n<td align=\"left\">Oscillator strength of state j (diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">expec_MCH.out <\/td>\n<td align=\"left\">4+3n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">2 <\/td>\n<td align=\"left\">Kinetic energy (eV)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">3 <\/td>\n<td align=\"left\">Potential energy (eV) of approximate active state (MCH)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">4 <\/td>\n<td align=\"left\">Total energy (eV)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">4+j <\/td>\n<td align=\"left\">Potential energy (eV) of state j (MCH)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">4+n+j <\/td>\n<td align=\"left\">Total spin expectation value of state j (MCH)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">4+2n+j <\/td>\n<td align=\"left\">Oscillator strength of state j (MCH)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ion_diag.out <\/td>\n<td align=\"left\">4+3n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">1+j <\/td>\n<td align=\"left\">E<sub>j<\/sub>−E<sub>active<\/sub> (in eV, diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">1+n+j <\/td>\n<td align=\"left\">Dyson norm from active state to state j (diagonal)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">ion_MCH.out <\/td>\n<td align=\"left\">4+3n\n <\/td>\n<td align=\"center\">1 <\/td>\n<td align=\"left\">Time t (fs)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">1+j <\/td>\n<td align=\"left\">E<sub>j<\/sub>−E<sub>approximate active<\/sub> (in eV, mCH)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\">1+n+j <\/td>\n<td align=\"left\">Dyson norm from approximate active state to state j (MCH)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">dip_mom_diag.out\n <\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><\/td>\n<td align=\"left\">Formatted like a minimal <b><tt>output.dat<\/tt><\/b> <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><\/td>\n<td align=\"left\">file containing the dipole moment matrices <\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"left\"><\/td>\n<td align=\"center\"><\/td>\n<td align=\"left\">in diagonal representation.<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.18\"><\/a><\/p>\n<h2>\n7.18  Data Extractor for NetCDF: <b><tt>data_extractor_NetCDF.x<\/tt><\/b><\/h2>\n<p><a id=\"sec:data_extractor_NetCDF.x\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This program has the same function as the <b><tt>data_extractor.x<\/tt><\/b>.<br \/>\nWhile the latter acts on ASCII-formatted <b><tt>output.dat<\/tt><\/b> files, the <b><tt>data_extractor_NetCDF.x<\/tt><\/b> reads only the header from <b><tt>output.dat<\/tt><\/b>, but the time step data from <b><tt>output.dat.nc<\/tt><\/b>.<br \/>\nThis file is obtained by setting <b><tt>output_format<\/tt><\/b> to <b><tt>ascii<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input file.<br \/>\nFor more details, see Section <a href=\"#sec:netcdf\">5.4<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that this program currently does not support a few options of the <b><tt>data_extractor.x<\/tt><\/b>.<br \/>\nIn particular, the options <b><tt>-sk<\/tt><\/b>, <b><tt>-dd<\/tt><\/b>, <b><tt>-id<\/tt><\/b>, and <b><tt>-im<\/tt><\/b> are ignored and no corresponding output is produced.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using the <b><tt>-xyz<\/tt><\/b> flag, the <b><tt>data_extractor_NetCDF.x<\/tt><\/b> can be used to write an <b><tt>output.xyz<\/tt><\/b> file from the NetCDF data file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.18.1\"><\/a><\/p>\n<h3>\n7.18.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>data_extractor_NetCDF.x<\/tt><\/b> is used in the same way as <b><tt>data_extractor.x<\/tt><\/b>:<\/p>\n<pre>\nuser@host> $SHARC\/data_extractor_NetCDF.x [options] output.dat\n<\/pre>\n<p>Note that both <b><tt>output.dat<\/tt><\/b> and <b><tt>output.dat.nc<\/tt><\/b> need to be present.<br \/>\nThe file name of <b><tt>output.dat.nc<\/tt><\/b> is hardcoded, if your file is called differently, you should set a symbolic link.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.18.2\"><\/a><\/p>\n<h3>\n7.18.2  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Same as <b><tt>data_extractor.x<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.19\"><\/a><\/p>\n<h2>\n7.19  Data Converter for NetCDF: <b><tt>data_converter.x<\/tt><\/b><\/h2>\n<p><a id=\"sec:data_converter.x\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This program can be used to convert an <b><tt>output.dat<\/tt><\/b> file into a NetCDF file (<b><tt>output.dat.nc<\/tt><\/b>).<br \/>\nThis significantly reduces the size of the file, and allows deleting the <b><tt>output.xyz<\/tt><\/b> file (its content will be in the NetCDF file).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.19.1\"><\/a><\/p>\n<h3>\n7.19.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>data_converter.x<\/tt><\/b> usage is very simple:<\/p>\n<pre>\nuser@host> $SHARC\/data_converter.x output.dat\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>Note that the <b><tt>data_converter.x<\/tt><\/b> does not modify the <b><tt>output.dat<\/tt><\/b> file.<br \/>\nHence, in order to save disk space, remove the data (below the header) afterwards:<\/p>\n<pre>\nuser@host> sed -i '1,\/End of header array data\/!d' output.dat\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.19.2\"><\/a><\/p>\n<h3>\n7.19.2  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The program writes a file called <b><tt>output.dat.nc<\/tt><\/b>.<br \/>\nThis file can be extracted as usual with <b><tt>data_extractor_NetCDF.x<\/tt><\/b> (see Section <a href=\"#sec:data_extractor_NetCDF.x\">7.18<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.20\"><\/a><\/p>\n<h2>\n7.20  Data Converter from NetCDF to ASCII: <b><tt>data_converter_to_ASCII.x<\/tt><\/b><\/h2>\n<p><a id=\"sec:data_converter_to_ASCII.x\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This program converts a <b><tt>output.dat.nc<\/tt><\/b> to <b><tt>output.dat.cp<\/tt><\/b>, which will be in ASCII format.<br \/>\nThis will blow up the file size, but is sometimes necessary or convenient for the inspection of the file content or to apply certain scripts.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.20.1\"><\/a><\/p>\n<h3>\n7.20.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>data_converter_to_ASCII.x<\/tt><\/b> usage is very simple, and fully analogous to <b><tt>data_extractor_NetCDF.x<\/tt><\/b>:<\/p>\n<pre>\nuser@host> $SHARC\/data_converter_to_ASCII.x output.dat\n<\/pre>\n<p>Note that both <b><tt>output.dat<\/tt><\/b> and <b><tt>output.dat.nc<\/tt><\/b> need to be present.<br \/>\nThe file name of <b><tt>output.dat.nc<\/tt><\/b> is hardcoded, if your file is called differently, you should set a symbolic link.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.20.2\"><\/a><\/p>\n<h3>\n7.20.2  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The program writes a file called <b><tt>output.dat.cp<\/tt><\/b>.<br \/>\nThis file can be extracted as usual with <b><tt>data_extractor.x<\/tt><\/b> (see Section <a href=\"#sec:data_extractor.x\">7.17<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.21\"><\/a><\/p>\n<h2>\n7.21  Data Converter from NetCDF nuclear files to XYZ: <b><tt>data_extractor_NUC_xyz.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:data_extractor_NUC_xyz.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If the option <b><tt>output_format ascii_separate_nuclei<\/tt><\/b> is used, then the nuclear coordinates end up in the file <b><tt>output_NUC.dat.nc<\/tt><\/b>.<br \/>\nThis file cannot be extracted by <b><tt>data_extractor_NetCDF.x -xyz<\/tt><\/b> to produce an xyz file for analysis.<br \/>\nHowever, using <b><tt>data_extractor_NUC_xyz.py<\/tt><\/b>, the xyz file can be generated.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.21.1\"><\/a><\/p>\n<h3>\n7.21.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Usage is very simple:<\/p>\n<pre>\nuser@host> python $SHARC\/data_extractor_NUC_xyz.py geom output_NUC.dat.nc > output_NM.xyz\n<\/pre>\n<p>Note that the script reads the element symbols from the <b><tt>geom<\/tt><\/b> file.<br \/>\nThe script can read either <b><tt>output_NUC.dat.nc<\/tt><\/b> or <b><tt>output.dat.nc<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.21.2\"><\/a><\/p>\n<h3>\n7.21.2  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The program writes the xyz coordinates to standard output.<br \/>\nRedirect the output to store it in a file.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.22\"><\/a><\/p>\n<h2>\n7.22  Plotting the Extracted Data: <b><tt>make_gnuscript.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:make_gnuscript.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The contents of the output files of <b><tt>data_extractor.x<\/tt><\/b> can be plotted with G<span style=\"font-size:x-small\">NUPLOT<\/span>. In order to quickly generate an appropriate G<span style=\"font-size:x-small\">NUPLOT<\/span> script, <b><tt>make_gnuscript.py<\/tt><\/b> can be used. The usage is:<\/p>\n<pre>\nuser@host> $SHARC\/make_gnuscript.py <S> [<D> [<T> [<Q> ... ] ] ]\n<\/pre>\n<p><b><tt>make_gnuscript.py<\/tt><\/b> takes between 1 and 8 integers as command-line arguments, specifying the number of singlet, doublet, triplet, etc. states. It writes an appropriate G<span style=\"font-size:x-small\">NUPLOT<\/span> script to standard out, hence redirect the output to a file, e.g.:<\/p>\n<pre>\nuser@host> $SHARC\/make_gnuscript.py 3 0 2 > gnuscript.gp\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>Then, G<span style=\"font-size:x-small\">NUPLOT<\/span> can be run in the <b><tt>output_data<\/tt><\/b> directory of a trajectory:<\/p>\n<pre>\nuser@host> gnuplot gnuscript.gp\n<\/pre>\n<p>This can also be accomplished in one step using a pipe, e.g.:<\/p>\n<pre>\nuser@host> $SHARC\/make_gnuscript.py 3 0 2 | gnuplot\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The created plot script generates four different plots (press ENTER in the command-line where you started G<span style=\"font-size:x-small\">NUPLOT<\/span> to go to the next plot). The first plot shows the potential energy of all states in the dynamics over time in the diagonal representation. The currently occupied state is marked with black circles. A thin black line gives the total energy (sum of the kinetic energy and the potential energy of the currently occupied state). Each state is colored, with one color as contour and one color at the core of the line. The contour color represents the total spin expectation value of the state. The core color represents the oscillator strength of the state with the lowest state. See figure <a href=\"#fig:colors\">7.3<\/a> for the relevant color code.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg7.3\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/colors.png\"> <\/p>\n<div style=\"text-align:center\">Figure 7.3: Color code for plots generated with the use of <b><tt>make_gnuscript.py<\/tt><\/b>.<\/div>\n<p> <a id=\"fig:colors\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Note that by definition the “oscillator strength” of the lowest state with itself is exactly zero, hence the lowest state is also light grey. This dual coloring allows for a quick recognition of different types of states in the dynamics, e.g. singlets vs. triplets or nπ<sup>*<\/sup> vs. ππ<sup>*<\/sup> states.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The second plot shows the same data again, but using relative energies such that the energy of the lowest state is zero.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The third plot shows the population |c<sub>i<\/sub><sup>MCH<\/sup>|<sup>2<\/sup> of the MCH electronic states over time. The line colors are auto-generated in order to give a large spread of all colors over the excited states, but the colors might be sub-optimal, e.g. for printing. In this cases, the user should manually adjust the colors in the generated script.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The fourth plot shows the population |c<sub>i<\/sub><sup>diag<\/sup>|<sup>2<\/sup> of the diagonal electronic states over time. These are the populations which are actually used for surface hopping. However, since these states are spin-mixed, it is usually difficult to interpret these populations.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The fifth plot shows the surface hopping probabilities over time. The plot is setup in such a way that the visible area corresponding to a certain state is proportional to the probability to hop into the state. Hence, if for a given time step the random number (black circles) lies within a colored area, a surface hop to the corresponding state is performed.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.23\"><\/a><\/p>\n<h2>\n7.23  Internal Coordinates Analysis: <b><tt>geo.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:geo.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p> S<span style=\"font-size:x-small\">HARC<\/span> writes at every time step the molecular geometry to the file <b><tt>output.xyz<\/tt><\/b>. The non-interactive script <b><tt>geo.py<\/tt><\/b> can be used in order to extract internal coordinates from xyz files. The usage is:<\/p>\n<pre>\nuser@host> $SHARC\/geo.py [options] < Geo.inp > Geo.out\n<\/pre>\n<p>By default, the coordinates are read from <b><tt>output.xyz<\/tt><\/b>, but this can be changed with the <b><tt>-g<\/tt><\/b> option (see table <a href=\"#tab:Geo_options\">7.13<\/a>). Note that the internal coordinate specifications are read from standard input and the result table is written to standard out. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.23.1\"><\/a><\/p>\n<h3>\n7.23.1  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The specifications for the desired internal coordinates are read from standard input. It follows a simple syntax, where each internal coordinate is specified by a single line of input. Each line starts with a one-letter key which specifies the type of internal coordinate (e.g. bond length, angle, dihedral, …). The key is followed by a list of integers, specifying which atoms should be measured. As a simple example, <b><tt>r 1 2<\/tt><\/b> specifies the bond length (<b><tt>r<\/tt><\/b> is the key for bond lengths) between atoms 1 and 2. Note that the numbering of the atoms starts with 1. Each line of input is checked for consistency (whether any atom index is larger than the number of atoms, repeated atom indices, misspelled keys, wrong number of atom indices, …), and erroneous lines are ignored (this is indicate by an error message).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Table <a href=\"#tab:Geo_input\">7.12<\/a> lists the available types of internal coordinates. The output is a table, where the first column is the time (Actually, the geometries are just enumerated starting with zero, and the number multiplied by the time step from the <b><tt>-t<\/tt><\/b> option). The successive columns in the output table list the results of the internal coordinates calculations. Each request generates at least one column, see table <a href=\"#tab:Geo_input\">7.12<\/a>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that for most internal coordinates, the order of the atoms is crucial, since e.g. a<sub>123<\/sub> ≠ a<sub>213<\/sub>. This also holds for the Cremer-Pople parameter requests. For these input lines, the atoms should be listed in the order they appear in the ring (clockwise or counter-clockwise).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.12\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.12: Possible types of internal coordinates in <b><tt>geo.py<\/tt><\/b>. <\/div>\n<p> <a id=\"tab:Geo_input\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Key <\/td>\n<td align=\"center\"><span class=\"roman\"><span class=\"roman\">Atom <\/td>\n<td align=\"right\">Description <\/td>\n<td align=\"left\">Output columns<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"center\"><span class=\"roman\"><span class=\"roman\">Indices <\/td>\n<td align=\"right\"><\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">x <\/td>\n<td align=\"center\">a <\/td>\n<td align=\"right\">x coordinate of atom <b><tt>a<\/tt><\/b> <\/td>\n<td align=\"left\">x<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">y <\/td>\n<td align=\"center\">a <\/td>\n<td align=\"right\">y coordinate of atom <b><tt>a<\/tt><\/b> <\/td>\n<td align=\"left\">y<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">z <\/td>\n<td align=\"center\">a <\/td>\n<td align=\"right\">z coordinate of atom <b><tt>a<\/tt><\/b> <\/td>\n<td align=\"left\">z<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">r <\/td>\n<td align=\"center\">a b <\/td>\n<td align=\"right\">Bond length between <b><tt>a<\/tt><\/b> and <b><tt>b<\/tt><\/b> <\/td>\n<td align=\"left\">r<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">a <\/td>\n<td align=\"center\">a b c <\/td>\n<td align=\"right\">Angle between <b><tt>a<\/tt><\/b>–<b><tt>b<\/tt><\/b> and <b><tt>b<\/tt><\/b>–<b><tt>c<\/tt><\/b> <\/td>\n<td align=\"left\">a<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">d <\/td>\n<td align=\"center\">a b c d <\/td>\n<td align=\"right\">Dihedral, i.e., angle between normal vectors of (<b><tt>a,b,c<\/tt><\/b>) and (<b><tt>b,c,d<\/tt><\/b>) <\/td>\n<td align=\"left\">d<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"center\"><\/td>\n<td align=\"right\">(between -180<sup>°<\/sup> and 180<sup>°<\/sup>, same sign conventions as M<span style=\"font-size:x-small\">OLDEN<\/span>)<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">p <\/td>\n<td align=\"center\">a b c d <\/td>\n<td align=\"right\">Pyramidalization angle: 90<sup>°<\/sup> minus angle between bond <b><tt>a<\/tt><\/b>–<b><tt>b<\/tt><\/b> <\/td>\n<td align=\"left\">p<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"center\"><\/td>\n<td align=\"right\">and normal vector of (<b><tt>b,c,d<\/tt><\/b>)<\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">q <\/td>\n<td align=\"center\">a b c d <\/td>\n<td align=\"right\">Pyramidalization angle (alternative definition; angle between <\/td>\n<td align=\"left\">q<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"center\"><\/td>\n<td align=\"right\">bond <b><tt>a<\/tt><\/b>–<b><tt>b<\/tt><\/b> and average of bonds <b><tt>b<\/tt><\/b>–<b><tt>c<\/tt><\/b> and <b><tt>b<\/tt><\/b>–<b><tt>d<\/tt><\/b><\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">5 <\/td>\n<td align=\"center\">a b c d e <\/td>\n<td align=\"right\">Cremer-Pople parameters for 5-membered rings <a href=\"#Cremer1975JACS\" class=\"tth_citeref\">[62<\/a>] and<\/td>\n<td align=\"left\">q<sub>2<\/sub>, ϕ<sub>2<\/sub>, Boeyens<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"center\"><\/td>\n<td align=\"right\">comformation classification.<\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">6 <\/td>\n<td align=\"center\">a b c d e f <\/td>\n<td align=\"right\">Cremer-Pople parameters for 6-membered rings <a href=\"#Cremer1975JACS\" class=\"tth_citeref\">[62<\/a>] and<\/td>\n<td align=\"left\">Q, ϕ, θ, Boeyens<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"center\"><\/td>\n<td align=\"right\">Boeyens classification <a href=\"#Boeyens1976JCMS\" class=\"tth_citeref\">[63<\/a>].<\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">i <\/td>\n<td align=\"center\">a – f <\/td>\n<td align=\"right\">Angle between average plane through 3-rings (<b><tt>a - c<\/tt><\/b>) and (<b><tt>d - f<\/tt><\/b>) <\/td>\n<td align=\"left\">i<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">j <\/td>\n<td align=\"center\">a – h <\/td>\n<td align=\"right\">Angle between average plane through 4-rings (<b><tt>a - d<\/tt><\/b>) and (<b><tt>e - f<\/tt><\/b>) <\/td>\n<td align=\"left\">j<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">k <\/td>\n<td align=\"center\">a – j <\/td>\n<td align=\"right\">Angle between average plane through 5-rings (<b><tt>a - e<\/tt><\/b>) and (<b><tt>f - j<\/tt><\/b>) <\/td>\n<td align=\"left\">k<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">l <\/td>\n<td align=\"center\">a – l <\/td>\n<td align=\"right\">Angle between average plane through 6-rings (<b><tt>a - f<\/tt><\/b>) and (<b><tt>g - l<\/tt><\/b>) <\/td>\n<td align=\"left\">l<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">c <\/td>\n<td align=\"center\"><\/td>\n<td align=\"right\">Writes the comment (second line of the <\/td>\n<td align=\"left\">Comment<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td align=\"center\"><\/td>\n<td align=\"right\">xyz format) to the table.<\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<p><\/span><\/span><\/span><\/span><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>As an advice, it is always a good idea to put the comment as the <i>last<\/i> request, if needed. Since the comment may contain blanks, having the comment not as the very last column might make it impossible to plot the resulting table.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The Boeyens classification symbols which are output for 6-membered rings are reported in <span class=\"roman\">L<\/span><sup><span class=\"roman\">A<\/span><\/sup><span class=\"roman\">T<\/span><sub><span class=\"roman\">E<\/span><\/sub><span class=\"roman\">X<\/span> math code. Note that in the Boeyens classification scheme by definition a number of symbols are equivalent, and only one symbol is reported.<br \/>\nThese are the equivalent symbols: <sup>1<\/sup>C<sub>4<\/sub>=<sup>3<\/sup>C<sub>6<\/sub>=<sup>5<\/sup>C<sub>2<\/sub>, <sup>4<\/sup>C<sub>1<\/sub>=<sup>6<\/sup>C<sub>3<\/sub>=<sup>2<\/sup>C<sub>5<\/sub>, <sup>1<\/sup>T<sub>3<\/sub>=<sup>4<\/sup>T<sub>6<\/sub>, <sup>2<\/sup>T<sub>6<\/sub>=<sup>5<\/sup>T<sub>3<\/sub>, <sup>2<\/sup>T<sub>4<\/sub>=<sup>5<\/sup>T<sub>1<\/sub>, <sup>3<\/sup>T<sub>1<\/sub>=<sup>6<\/sup>T<sub>4<\/sub>, <sup>6<\/sup>T<sub>2<\/sub>=<sup>3<\/sup>T<sub>5<\/sub> and <sup>4<\/sup>T<sub>2<\/sub>=<sup>1<\/sup>T<sub>5<\/sub>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For 5-membered rings, the classification symbols are chosen similar to the Boeyens symbols. For the <sup>a<\/sup>E and E<sub>a<\/sub> symbols, atom a is puckered out of the plane and the four other atoms are coplanar, while for the <sup>a<\/sup>H<sub>b<\/sub> symbols the neighboring atoms a and b are puckered out of the plane in opposite directions and only the three remaining atoms are coplanar.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>It is also possible to measure angles between the average planes through two n-membered rings.<br \/>\nCurrently, this is only possible if both rings have the same number of atoms (3, 4, 5, or 6).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.23.2\"><\/a><\/p>\n<h3>\n7.23.2  Options<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>geo.py<\/tt><\/b> accepts a number of command-line options, see table <a href=\"#tab:Geo_options\">7.13<\/a>. All options have sensible defaults. However, especially if long comments should be written to the output file, it might be necessary to increase the field width. Note that the minimum column width is 20 so that the table header can be printed correctly.<br \/>\nAlso note that the column for the comment is enlarged by 50 characters.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.13\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.13: Command-line options for <b><tt>geo.py<\/tt><\/b>. <\/div>\n<p> <a id=\"tab:Geo_options\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit. <\/td>\n<td align=\"left\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-b <\/td>\n<td align=\"left\">Report x, y, z, r, q<sub>2<\/sub> and Q in Bohrs <\/td>\n<td align=\"left\">Angstrom<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-r <\/td>\n<td align=\"left\">Report a, d, p, q, ϕ<sub>2<\/sub>, ϕ, θ, i, j, k, and l in Radians <\/td>\n<td align=\"left\">Degrees<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-g FILENAME <\/td>\n<td align=\"left\">Read coordinates from the specified file <\/td>\n<td align=\"left\"><b><tt>output.xyz<\/tt><\/b><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-t FLOAT <\/td>\n<td align=\"left\">Assumed time step between successive geometries (fs) <\/td>\n<td align=\"left\">1.0 fs<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-w INTEGER <\/td>\n<td align=\"left\">Width of each column (min=20) <\/td>\n<td align=\"left\">20<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-p INTEGER <\/td>\n<td align=\"left\">Precision (Number of decimals, min=width-3) <\/td>\n<td align=\"left\">4<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.24\"><\/a><\/p>\n<h2>\n7.24  Normal Mode Analysis: <b><tt>geo_NM.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:geo_NM.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The non-interactive script <b><tt>geo_NM.py<\/tt><\/b> computes normal mode coordinates for a given molecular trajectory.<br \/>\nThe usage is: <\/p>\n<pre> \nuser@host> $SHARC\/geo_NM.py [options] > Geo_NM.out \n<\/pre>\n<p>By default, the coordinates are read from <b><tt>output.xyz<\/tt><\/b>, but this can be changed with the <b><tt>-g<\/tt><\/b> option (see Table <a href=\"#tab:Geo_NM_options\">7.14<\/a>).<br \/>\nAdditionally, the normal mode definitions are read from the <b><tt>V0.txt<\/tt><\/b> file, which contains the parameters defining the normal mode coordinates.<br \/>\nThe result table is written to standard output.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The computation uses the same formulae as for <b><tt>SHARC_LVC.py<\/tt><\/b> when computing the normal mode coordinates (Equation (<a href=\"#eq:Qi\">8.108<\/a>)).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.24.1\"><\/a><\/p>\n<h3>\n7.24.1  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Table <a href=\"#tab:Geo_NM_options\">7.14<\/a> lists the available options for the script.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.14\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.14: Command-line options for <b><tt>geo_NM.py<\/tt><\/b>.<\/div>\n<p><a id=\"tab:Geo_NM_options\"><br \/>\n<\/a> <\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit. <\/td>\n<td align=\"left\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-p <\/td>\n<td align=\"left\">Number of decimals for normal mode coordinates <\/td>\n<td align=\"left\">4<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-w <\/td>\n<td align=\"left\">Field width for the output table <\/td>\n<td align=\"left\">20<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-g FILENAME <\/td>\n<td align=\"left\">Read coordinates from the specified geometry file <\/td>\n<td align=\"left\"><b><tt>output.xyz<\/tt><\/b><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-v FILENAME <\/td>\n<td align=\"left\">Use the specified file with normal mode definitions <\/td>\n<td align=\"left\"><b><tt>V0.txt<\/tt><\/b><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-t FLOAT <\/td>\n<td align=\"left\">Timestep between successive geometries in fs <\/td>\n<td align=\"left\">1.0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-T INTEGER <\/td>\n<td align=\"left\">Start counting the timesteps from a specified value <\/td>\n<td align=\"left\">0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-k <\/td>\n<td align=\"left\">Switch on aligning the structures using the Kabsch algorithm <\/td>\n<td align=\"left\">off<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-q STRING <\/td>\n<td align=\"left\">Specify list of considered atoms for normal mode calculation (e.g., “18 12 20”) <\/td>\n<td align=\"left\">all atoms<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-b <\/td>\n<td align=\"left\">Enable buffered reading of the geometry file (useful for large files) <\/td>\n<td align=\"left\">off<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Using the options <b><tt>-k<\/tt><\/b> and <b><tt>-q<\/tt><\/b>, one can analyze the normal mode coordinates of a subsystem of a large calculation, e.g., a QM\/MM calculation.<br \/>\nUse the <b><tt>-q<\/tt><\/b> option to select which atoms are considered for the normal mode computation.<br \/>\nThe number of selected atoms must match the atom number in the <b><tt>V0.txt<\/tt><\/b> file.<br \/>\nTurn on the <b><tt>-k<\/tt><\/b> option in case the molecule\/selected atoms have not the same orientation as the reference geometry (which is generally the case in QM\/MM calculations), so that the geometry is aligned prior to computing the normal mode coordinates.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.24.2\"><\/a><\/p>\n<h3>\n7.24.2  Output Format<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The output is a table where each row corresponds to a geometry snapshot in the trajectory. The first column contains the time in femtoseconds, and the following columns contain the normal mode coordinates for each mode. The last column contains the comment from the geometry file.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.15\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.15: Output format of <b><tt>geo_NM.py<\/tt><\/b>.<\/div>\n<p><a id=\"tab:Geo_NM_output\"><br \/>\n<\/a> <\/p>\n<table>\n<tr>\n<td align=\"left\">Time (fs) <\/td>\n<td align=\"right\">Mode 1 <\/td>\n<td align=\"right\">Mode 2 <\/td>\n<td align=\"right\">… <\/td>\n<td align=\"left\">Comment <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">0.00 <\/td>\n<td align=\"right\">0.123456 <\/td>\n<td align=\"right\">0.234567 <\/td>\n<td align=\"right\">… <\/td>\n<td align=\"left\">First snapshot <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">1.00 <\/td>\n<td align=\"right\">0.234567 <\/td>\n<td align=\"right\">0.345678 <\/td>\n<td align=\"right\">… <\/td>\n<td align=\"left\">Second snapshot <\/td>\n<\/tr>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>Note that in most cases, <b><tt>V0.txt<\/tt><\/b> will contain zero vectors for the first six normal modes, so columns 2 to 7 will contain only zeros in the output of <b><tt>geo_NM.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.25\"><\/a><\/p>\n<h2>\n7.25  Calculation of Ensemble Populations: <b><tt>populations.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:populations.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For an ensemble of trajectories, usually one of the most relevant results are ensemble-averaged populations. The interactive script <b><tt>populations.py<\/tt><\/b> collects these populations from a set of trajectories. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Different methods to obtain populations or quantities approximating populations can be collected, as described below.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.25.1\"><\/a><\/p>\n<h3>\n7.25.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script is interactive, simply start it with no command-line arguments or options:<\/p>\n<pre>\nuser@host> $SHARC\/populations.py\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>Depending on the analysis mode (see below) it might be necessary to run <b><tt>data_extractor.x<\/tt><\/b> for each trajectory prior to running <b><tt>populations.py<\/tt><\/b> (but <b><tt>populations.py<\/tt><\/b> can also call <b><tt>data_extractor.x<\/tt><\/b> for each subdirectory, if desired). <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Paths to trajectories  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>First, the script asks the user to specify all directories for whose content the analysis should be performed. Enter one directory path at a time, and finish the directory input section by typing “<b><tt>end<\/tt><\/b>“. Please do not specify each trajectory directory separately, but specify their parent directories, e.g. the directories <b><tt>Singlet_1<\/tt><\/b> and <b><tt>Singlet_2<\/tt><\/b>. <b><tt>populations.py<\/tt><\/b> will automatically include all trajectories contained in these directories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you want to exclude certain trajectories from the analysis, it is sufficient to create an empty file called <b><tt>CRASHED<\/tt><\/b> or <b><tt>RUNNING<\/tt><\/b> in the corresponding trajectory directory. <b><tt>populations.py<\/tt><\/b> will ignore all directories containing one of these files. The file name is case insensitive, i.e., also files like <b><tt>crashed<\/tt><\/b> or even <b><tt>cRasHED<\/tt><\/b> will lead to the trajectory being ignored.<br \/>\nAdditionally, <b><tt>populations.py<\/tt><\/b> will ignore trajectories with a <b><tt>DONT_ANALYZE<\/tt><\/b> file from <b><tt>diagnostics.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Analysis mode  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>populations.py<\/tt><\/b>, there are two basic ways in obtaining the excited-state populations. The first way is to count the number of trajectories for which a certain condition holds. For example, the number of trajectories in each classical state can be obtained in this way. However, it is also possible to count the number of trajectories for which the total spin expectation value is within a certain interval.<br \/>\nThe second way to obtain populations is to obtain the sum of the absolute squares of the quantum amplitudes over all trajectories. Table <a href=\"#tab:Populations_modes\">7.16<\/a> contains a list of all possible analysis modes.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.16\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.16: Analysis modes for <b><tt>populations.py<\/tt><\/b>. The last column indicates whether <b><tt>data_extractor.x<\/tt><\/b> has to be run prior to the ensemble analysis.<\/div>\n<p> <a id=\"tab:Populations_modes\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Mode <\/td>\n<td width=\"296\">Description <\/td>\n<td align=\"left\"><span class=\"roman\">From which file? <\/td>\n<td align=\"left\">Extract?<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">1 <\/td>\n<td width=\"296\">For each diagonal state count how many trajectories have this state as active state. <\/td>\n<td align=\"left\">output.lis <\/td>\n<td align=\"left\">No<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">2 <\/td>\n<td width=\"296\">For each MCH state count how many trajectories have this state as approximate active state (see section <a href=\"#ssec:state_transform\">8.23.1<\/a>). <\/td>\n<td align=\"left\">output.lis <\/td>\n<td align=\"left\">No<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">3 <\/td>\n<td width=\"296\">For each MCH state count how many trajectories have this state as approximate active state (see section <a href=\"#ssec:state_transform\">8.23.1<\/a>). Multiplet components are summed up. <\/td>\n<td align=\"left\">output.lis <\/td>\n<td align=\"left\">No<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">4 <\/td>\n<td width=\"296\">Generate a histogram with definable bins (variable width). Bin the trajectories according to their total spin expectation value (of the currently active diagonal state). <\/td>\n<td align=\"left\">output.lis <\/td>\n<td align=\"left\">No<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">5 <\/td>\n<td width=\"296\">Generate a histogram with definable bins (variable width). Bin the trajectories according to their state dipole moment expectation value (of the currently active diagonal state). <\/td>\n<td align=\"left\">output.lis <\/td>\n<td align=\"left\">No<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">6 <\/td>\n<td width=\"296\">Generate a histogram with definable bins (variable width). Bin the trajectories according to the oscillator strength between lowest and currently active diagonal states. <\/td>\n<td align=\"left\">output_data\/fosc.out <\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">7 <\/td>\n<td width=\"296\">Calculate the sum of the absolute squares of the diagonal coefficients for each state. <\/td>\n<td align=\"left\">output_data\/coeff_diag.out<\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">8 <\/td>\n<td width=\"296\">Calculate the sum of the absolute squares of the MCH coefficients for each state. <\/td>\n<td align=\"left\">output_data\/coeff_MCH.out<\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">9 <\/td>\n<td width=\"296\">Calculate the sum of the absolute squares of the MCH coefficients for each state. Multiplet components are summed up. <\/td>\n<td align=\"left\">output_data\/coeff_MCH.out<\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">12 <\/td>\n<td width=\"296\">Transform option 1 to MCH basis (section <a href=\"#met:pop\">8.5<\/a>). <\/td>\n<td align=\"left\">output_data\/coeff_class_MCH.out<\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">13 <\/td>\n<td width=\"296\">Transform option 1 to MCH basis (section <a href=\"#met:pop\">8.5<\/a>). Multiplet components are summed up. <\/td>\n<td align=\"left\">output_data\/coeff_class_MCH.out<\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">14 <\/td>\n<td width=\"296\">Wigner-transform option 1 to MCH basis (section <a href=\"#met:pop\">8.5<\/a>). <\/td>\n<td align=\"left\">output_data\/coeff_mixed_MCH.out<\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">15 <\/td>\n<td width=\"296\">Wigner-transform option 1 to MCH basis (section <a href=\"#met:pop\">8.5<\/a>). Multiplet components are summed up. <\/td>\n<td align=\"left\">output_data\/coeff_mixed_MCH.out<\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">20 <\/td>\n<td width=\"296\">Calculate the sum of the absolute squares of the diabatic coefficients for each state (Only for trajectories with local diabatization). <\/td>\n<td align=\"left\">output_data\/coeff_diab.out<\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">21 <\/td>\n<td width=\"296\">Transform option 1 to diabatic basis (section <a href=\"#met:pop\">8.5<\/a>). <\/td>\n<td align=\"left\">output_data\/coeff_class_diab.out<\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">22 <\/td>\n<td width=\"296\">Wigner-transform option 1 to diabatic basis (section <a href=\"#met:pop\">8.5<\/a>). Multiplet components are summed up. <\/td>\n<td align=\"left\">output_data\/coeff_mixed_diab.out<\/td>\n<td align=\"left\">Yes<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p><b>Run data extractor  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For analysis modes 6, 7, 8, 9 and 20 it is necessary to first run the data extractor (see Section <a href=\"#sec:data_extractor.x\">7.17<\/a> or Section <a href=\"#sec:data_extractor_NetCDF.x\">7.18<\/a>).<br \/>\nThe script automatically detects whether the regular or NetCDF extractor should be called.<br \/>\nThis task can be accomplished by <b><tt>populations.py<\/tt><\/b>. However, for a large ensemble or for long trajectories this may take some time. Hence, it is not necessary to perform this step each time <b><tt>populations.py<\/tt><\/b> is run. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>populations.py<\/tt><\/b> will detect whether the file <b><tt>output.dat<\/tt><\/b> or the content of <b><tt>output_data\/<\/tt><\/b> is more recent. Only if <b><tt>output.dat<\/tt><\/b> is newer the <b><tt>data_extractor.x<\/tt><\/b> will be run for this trajectory.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that mode 20 can only be used for trajectories using local diabatization propagation (keyword <b><tt>coupling overlap<\/tt><\/b> in S<span style=\"font-size:x-small\">HARC<\/span> input file) or .<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of states  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For analysis modes 1, 2, 3, 7, 8 and 9 it is necessary to specify the number of states in each multiplicity. The number is auto-detected from the input file of one of the trajectories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Intervals  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For analysis modes 4, 5 and 6 the user must specify the intervals (i.e., the histogram bins) for the classification of the trajectories. The user has to input a list of interval borders, e.g.:<\/p>\n<pre>\nPlease enter the interval limits, all on one line.\nInterval limits: 1e-3 0.01 0.1 1\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>Note that scientific notation can be used. Based on this input, for each time step a histogram is created with the number of trajectories in each interval. The histogram bins are:<\/p>\n<ol type=\"1\">\n<li> x ≤ 10<sup>−3<\/sup>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> 10<sup>−3<\/sup> < x ≤ 0.01\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> 0.01 < x ≤ 0.1\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> 0.1 < x ≤ 1\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> 1 < x\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ol>\n<p>Note that there is always one more bin that interval borders entered.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Normalization  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If desired, <b><tt>populations.py<\/tt><\/b> can normalize the populations by dividing the populations by the number of trajectories. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Maximum simulation time  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This gives the maximum simulation time until which the populations are analyzed. For trajectories which are shorter than this value, the last population information is used to make the trajectory long enough. Trajectories which are longer are not analyzed to the end. <b><tt>populations.py<\/tt><\/b> prints the length of the shortest and longest trajectories after the analysis.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If <b><tt>diagnostics.py<\/tt><\/b> was executed previously, the user can enter here the threshold for the maximum usable time (see section <a href=\"#sec:diagnostics.py\">7.16<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Setup for bootstrapping  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The output file of <b><tt>populations.py<\/tt><\/b> is sufficient to perform kinetic model fits with the script <b><tt>make_fitscript.py<\/tt><\/b>.<br \/>\nHowever, if error estimates for the kinetic model are desired (using <b><tt>bootstrap.py<\/tt><\/b>), the output file of <b><tt>populations.py<\/tt><\/b> is not enough.<br \/>\nThe user can tell <b><tt>populations.py<\/tt><\/b> to save additional data which is required by <b><tt>bootstrap.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Gnuplot script  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>populations.py<\/tt><\/b> can generate an appropriate G<span style=\"font-size:x-small\">NUPLOT<\/span> script for the performed population analysis. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.25.2\"><\/a><\/p>\n<h3>\n7.25.2  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>By default, <b><tt>populations.py<\/tt><\/b> writes the resulting populations to <b><tt>pop.out<\/tt><\/b>. If the file already exists, the user is ask whether it shall be overwritten, or to provide an alternative filename. Note that the output file is checked only after the analysis is completed, so the program might run for a considerable amount of time before asking for the output file.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.26\"><\/a><\/p>\n<h2>\n7.26  Calculation of Numbers of Hops: <b><tt>transition.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:transition.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Another important information from the trajectory ensemble is the number of hopping events and the involved states, for example to judge the relative importance of competing reaction pathways.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interactive script <b><tt>transition.py<\/tt><\/b> calculates from an ensemble the number of hops between each pair of states and presents the results as “transition matrices”.<br \/>\nCurrently, the script employs the MCH active state information from <b><tt>output.lis<\/tt><\/b> for this computations.<br \/>\nNote that since the MCH active state is only an approximate quantity (since hops are actually performed in the diagonal basis in S<span style=\"font-size:x-small\">HARC<\/span>), the results should be checked carefully.<br \/>\nThe script <b><tt>transition.py<\/tt><\/b> is still partly work-in-progress.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.26.1\"><\/a><\/p>\n<h3>\n7.26.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script is interactive, simply start it with no command-line arguments or options:<\/p>\n<pre>\nuser@host> $SHARC\/transition.py\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p><b>Paths to trajectories  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>First the script asks the user to specify all directories for whose content the analysis should be performed. Enter one directory path at a time, and finish the directory input section by typing “<b><tt>end<\/tt><\/b>“. Please do not specify each trajectory directory separately, but specify their parent directories, e.g. the directories <b><tt>Singlet_1<\/tt><\/b> and <b><tt>Singlet_2<\/tt><\/b>. <b><tt>populations.py<\/tt><\/b> will automatically include all trajectories contained in these directories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you want to exclude certain trajectories from the analysis, it is sufficient to create an empty file called <b><tt>CRASHED<\/tt><\/b> or <b><tt>RUNNING<\/tt><\/b> in the corresponding trajectory directory. <b><tt>populations.py<\/tt><\/b> will ignore all directories containing one of these files. The file name is case insensitive, i.e., also files like <b><tt>crashed<\/tt><\/b> or even <b><tt>cRasHED<\/tt><\/b> will lead to the trajectory being ignored.<br \/>\nAdditionally, <b><tt>transition.py<\/tt><\/b> will ignore trajectories with a <b><tt>DONT_ANALYZE<\/tt><\/b> file from <b><tt>diagnostics.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Analysis mode  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The different analysis modes for <b><tt>transition.py<\/tt><\/b> are given in Table <a href=\"#tab:Transition_modes\">7.17<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.17\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.17: Analysis modes for <b><tt>transition.py<\/tt><\/b>. The last column indicates whether <b><tt>data_extractor.x<\/tt><\/b> has to be run prior to the ensemble analysis.<\/div>\n<p> <a id=\"tab:Transition_modes\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\">Mode <\/td>\n<td width=\"316\">Description <\/td>\n<td align=\"left\"><span class=\"roman\">From which <\/td>\n<td align=\"left\">Extract?<\/td>\n<\/tr>\n<tr>\n<td align=\"left\"><\/td>\n<td width=\"316\"><\/td>\n<td align=\"left\"><span class=\"roman\">file? <\/td>\n<td align=\"left\"><\/td>\n<\/tr>\n<tr>\n<td align=\"left\">1 <\/td>\n<td width=\"316\">Get transition matrix in MCH basis. <\/td>\n<td align=\"left\">output.lis <\/td>\n<td align=\"left\">No<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">2 <\/td>\n<td width=\"316\">Get transition matrix in MCH basis, ignoring hops within multiplets. <\/td>\n<td align=\"left\">output.lis <\/td>\n<td align=\"left\">No<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">3 <\/td>\n<td width=\"316\">Write a tabular file with the transition matrix in the MCH basis for each time step. <\/td>\n<td align=\"left\">output.lis <\/td>\n<td align=\"left\">No<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">4 <\/td>\n<td width=\"316\">Write a tabular file with the transition matrix in the MCH basis for each time step, ignoring hops within multiplets. <\/td>\n<td align=\"left\">output.lis <\/td>\n<td align=\"left\">No<\/td>\n<\/tr>\n<p><\/span><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.27\"><\/a><\/p>\n<h2>\n7.27  Fitting population data to kinetic models: <b><tt>make_fit.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:make_fit.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Often it is interesting to fit some functions to the population data from a trajectory ensemble, in order to provide a way to abstract the data and to obtain some kind of rate constants for population transfer, which allows to compare to experimental works.<br \/>\nIn simple cases, it might be sufficient to fit basic mono- and biexponential functions to the data, which provides the sought-after time constants.<br \/>\nHowever, often a more meaningful approach is based on a chemical kinetics model.<br \/>\nSuch a model is specified by a set of chemical species (e.g., electronic states, reactants, products, etc) connected by elementary reactions with associated rate constants, which together form a reaction network graph.<br \/>\nFor an explanation of those graphs, see section <a href=\"#met:globalfit\">8.10<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script <b><tt>make_fit.py<\/tt><\/b> helps the user in implementing and fitting such global fits to a kinetics model.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script works in a stand-alone fashion, unlike its predecessors (<b><tt>make_fitscript.py<\/tt><\/b> and <b><tt>bootstrap.py<\/tt><\/b>).<br \/>\nIt solves the differential equations numerically using a Runge-Kutta 5th order algorithm and fits the kinetic parameters using a number of different optimization algorithms.<br \/>\nThe script requires Python2 with N<span style=\"font-size:x-small\">UM<\/span>P<span style=\"font-size:x-small\">Y<\/span> and S<span style=\"font-size:x-small\">CI<\/span>P<span style=\"font-size:x-small\">Y<\/span>.<br \/>\nIf these are not available, use <b><tt>make_fitscript.py<\/tt><\/b> and <b><tt>bootstrap.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Often, one is also interested in obtaining an estimate of the error associated to these rate constants, e.g., in order to decide whether enough trajectories were computed.<br \/>\nA possible way to obtain such error estimates is the statistical bootstrapping procedure.<br \/>\nThe idea of bootstrapping is to generate <em>resamples<\/em> of the original ensemble; for an ensemble of n trajectories, one draws n random trajectories with replacement to obtain one resample.<br \/>\nThe resample can then be fitted like the original ensemble to obtain a second estimate of the rate constants.<br \/>\nBy generating many resamples, one can thus obtain a “probability” distribution of the rate constants, from which a statistical error measure can be calculated.<br \/>\nFor details on these statistical measures, see section <a href=\"#met:bootstrapping\">8.4<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script <b><tt>make_fit.py<\/tt><\/b> implements this resampling-fitting-statistics procedure.<br \/>\nIt is dependent on the output of <b><tt>populations.py<\/tt><\/b>, but otherwise works in a stand-alone fashion.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.27.1\"><\/a><\/p>\n<h3>\n7.27.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script is interactive, simply start it with no command-line arguments or options:<\/p>\n<pre>\nuser@host> $SHARC\/make_fit.py\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>Before you start the script, you need to prepare a file with the relevant populations data (usually, the output file of <b><tt>populations.py<\/tt><\/b> will suffice).<br \/>\nYou also might want to run <b><tt>transition.py<\/tt><\/b> first, which can help in developing a suitable kinetic model.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.27.2\"><\/a><\/p>\n<h3>\n7.27.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The interactive input for this script consists of specifying the reaction network graph, the initial conditions and the data file.<br \/>\nAdditionally, the user has to specify which species should be fitted to which data columns in the file.<br \/>\nOptionally, the user can specify the bootstrap settings for estimating errors.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Kinetic model species  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>As a first step, the user has to specify the set of species in the model.<br \/>\nEach species is fully described by its label.<br \/>\nA label must start with a letter and can be followed by letters, numbers and underscores (although an underscore must not be directly followed by another underscore).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During input, the user can add one or several labels to the set of species, remove labels and display the current set of defined labels.<br \/>\nIt is not possible to add a label twice.<br \/>\nOnce all labels are defined, the keyword <b><tt>end<\/tt><\/b> brings the user to the next input section (hence, <b><tt>end<\/tt><\/b> is not a valid label).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Kinetic model elementary reactions  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next, the reactions have to be defined.<br \/>\nA reaction is specified by its initial species, final species, and reaction rate label.<br \/>\nReaction rate labels are under the same restrictions as species labels and must not be already used as a species label.<br \/>\nFurthermore, initial and final species must be both defined previously and they must be different.<br \/>\nThere can only be one reaction from any species to another species (If a second reaction is defined, the first reaction label is simply overwritten).<br \/>\nNote that reaction rate labels can be used in several reactions (in this way, different rates can be restricted to be the same).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During input, the user can add and remove reactions and display the currently defined reactions (displayed as a matrix).<br \/>\nUnlike species labels, only one reaction can be added per line.<br \/>\nOnce all reactions are defined, the keyword <b><tt>end<\/tt><\/b> brings the user to the next input section.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Kinetic model initial values  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to specify the initial values for each species, the user simply has to define which species have non-zero initial population.<br \/>\nThese species will then be assigned an initial population constant, which can be fitted along with the reaction rates.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During input, the user can add and remove species from the set of species with non-zero initial population.<br \/>\nOnce all reactions are defined, the keyword <b><tt>end<\/tt><\/b> brings the user to the next input section.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Operation mode  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script can either read a <b><tt>pop.out<\/tt><\/b> file for a simple global fit, or a <b><tt>bootstrap_data\/<\/tt><\/b> directory for a global fit with error estimate.<br \/>\nIf the latter is chosen, the user needs to enter the number of bootstrap cycles.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Populations data file  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The user has to specify a path (autocomplete is enabled) to the file containing the population data to which the model functions should be fitted.<br \/>\nIn bootstrap mode, instead the path to the <b><tt>bootstrap_data\/<\/tt><\/b> directory (can be prepared with <b><tt>populations.py<\/tt><\/b>) needs to be given.<br \/>\nThe script reads the file\/files and automatically detects the maximum time and the number of data columns.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The file\/files should be formatted as a table, with one time step per line (e.g., an output file of <b><tt>populations.py<\/tt><\/b>).<br \/>\nOn each line, the first number is interpreted as the time in femtoseconds and all consecutive numbers (separated by spaces) as the populations at this time.<br \/>\nNote that the first entry must be at t=0 and all subsequent lines must be in strictly increasing order.<br \/>\nTime steps can be unevenly spaced if necessary.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Species-Data mapping  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the next setup section, the user has to specify which functions should be fitted to which data column from the data file.<br \/>\nIn the simplest case, one species is fitted to a single data column (e.g., the species <b><tt>S0<\/tt><\/b> is fitted to data column 2).<br \/>\nHowever, it is also possible to fit the sum of two species to a column (this can be useful, e.g., to describe biexponential processes) and to fit a species to the sum of several columns (e.g., one can fit to the total triplet population to obtain a total ISC rate constant).<br \/>\nIn general, it is also possible to fit sums of species to sums of columns.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>It is not allowed to use one species or one column in more than one mapping.<br \/>\nHowever, it is possible to leave species or data columns unused in the global fit.<br \/>\nWhile unused species still affect the outcome (through the reaction network definitions), unused data columns are simply ignored in the fit.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>During input, the user can add one mapping per line as well as display the current mappings.<br \/>\nFor the column definitions, ranges can be given with the tilde symbol, e.g., <b><tt>5 9<\/tt><\/b> is interpreted as <b><tt>5 6 7 8 9<\/tt><\/b>.<br \/>\nIf a typo is made, the user can reset the mappings and repeat only the mapping input without the need to repeat the previous sections.<br \/>\nOnce all mappings are defined, the keyword <b><tt>end<\/tt><\/b> finishes the input section.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Fitting procedure  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the last section, the user can edit the initial guesses for the rate constants and initial populations.<br \/>\nTo change a value, enter <b><tt>label = value<\/tt><\/b>.<br \/>\nUse <b><tt>show<\/tt><\/b> to print the current values for all constants.<br \/>\n<b><tt>end<\/tt><\/b> finishes the guess edit step.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Afterwards, the script asks whether the initial populations should be optimized or not.<br \/>\nThis is usually only useful if several species have non-zero initial populations.<br \/>\nIf you optimize initial populations, note that their sum might differ from 1 after optimization.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script also asks whether the rate constants should be constrained to positive values.<br \/>\nIf answered with <b><tt>yes<\/tt><\/b>, then the optimized rate constants are restricted to the range 0.000 001 to infinity (i.e., the time constants are constrained between 1 000 000 fs and 0 fs).<br \/>\nNote that with constraints S<span style=\"font-size:x-small\">CI<\/span>P<span style=\"font-size:x-small\">Y<\/span> uses the Trust Region Reflective algorithm, and the Levenberg-Marquardt algorithm for unconstrained cases.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.27.3\"><\/a><\/p>\n<h3>\n7.27.3  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script will write the output to standard out.<br \/>\nIt will first print the iterations of the fit, and the obtained results afterwards (all fitted parameters with errors).<br \/>\nThe script will also write two files, <b><tt>fit_results.txt<\/tt><\/b> and <b><tt>fit_results.gp<\/tt><\/b>.<br \/>\nThe latter is a G<span style=\"font-size:x-small\">NUPLOT<\/span> script that can be used to plot the global fit, which is useful for visual inspection.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the errors printed for normal runs are just the intrinsic fitting errors, which assume that the population data is error-free.<br \/>\nTo obtain realistic fitting errors that take into account the uncertainty due to the finite trajectory ensemble, use the bootstrap mode.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In bootstrap mode, the script initially will perform the same steps as in normal mode, using the average population from the bootstrap directory.<br \/>\nAfter writing the fit results and the two files, the script will start performing the bootstrap iterations, writing the fitted parameters in each iteration.<br \/>\nIn this way, the user can monitor the convergence of these values, to decide whether more iterations are required.<br \/>\nTypically, the values and errors will vary strongly during the first iterations and stabilize later.<br \/>\nThe convergence rate is strongly dependent on the fitting model and the data.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After all iterations are done (or the script is interrupted with <b><tt>Ctrl-C<\/tt><\/b>), the script will print a summary of the statistical analysis.<br \/>\nFor each fitting parameter (all time constants and all initial populations), the script will list the arithmetic mean and standard deviation (absolute and relative), the geometric mean and standard deviation (separately for + and −, absolute and relative), and the minimum and maximum values.<br \/>\nThe script will also print a histogram with the obtained distribution for each parameter.<br \/>\nFor details on these statistical measures, see section <a href=\"#met:bootstrapping\">8.4<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>bootstrap.py<\/tt><\/b> also creates an output file once it is finished.<br \/>\nThe file, <b><tt>fit_bootstrap.txt<\/tt><\/b>, contains the summary of the statistical analysis with the computed statistical measures and the histograms.<br \/>\nAdditionally, at the end this file contains a table with all obtained fitting parameters for resamples (e.g., for further statistical or correlation analysis).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.28\"><\/a><\/p>\n<h2>\n7.28  Obtaining Special Geometries: <b><tt>crossing.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:crossing.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In many cases, it is also important to obtain certain special geometries from the trajectories. The script <b><tt>crossing.py<\/tt><\/b> extracts geometries fulfilling special conditions from an ensemble of trajectories. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Currently, <b><tt>crossing.py<\/tt><\/b> finds geometries where the approximate MCH state (see section <a href=\"#ssec:state_transform\">8.23.1<\/a>) of the last time step is different from the MCH state of the current time step (i.e. <b><tt>crossing.py<\/tt><\/b> finds geometries where surface hops occured). <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.28.1\"><\/a><\/p>\n<h3>\n7.28.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script is interactive, simply start it with no command-line arguments or options:<\/p>\n<pre>\nuser@host> $SHARC\/crossing.py\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p>The input to the script is very similar to the one of <b><tt>populations.py<\/tt><\/b>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Paths to trajectories  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>First the script asks the user to specify all directories for whose content the analysis should be performed. Enter one directory path at a time, and finish the directory input section by typing “<b><tt>end<\/tt><\/b>“. Please do not specify each trajectory directory separately, but specify their parent directories, e.g. the directories <b><tt>Singlet_1<\/tt><\/b> and <b><tt>Singlet_2<\/tt><\/b>. <b><tt>crossing.py<\/tt><\/b> will automatically include all trajectories contained in these directories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you want to exclude certain trajectories from the analysis, it is sufficient to create an empty file called <b><tt>CRASHED<\/tt><\/b> or <b><tt>RUNNING<\/tt><\/b> in the corresponding trajectory directory. <b><tt>crossing.py<\/tt><\/b> will ignore all directories containing one of these files.<br \/>\nAdditionally, <b><tt>crossing.py<\/tt><\/b> will ignore trajectories with a <b><tt>DONT_ANALYZE<\/tt><\/b> file from <b><tt>diagnostics.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Analysis mode  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Currently, <b><tt>crossing.py<\/tt><\/b> only supports one analysis mode, where <b><tt>crossing.py<\/tt><\/b> is scanning for each trajectory the file <b><tt>output.lis<\/tt><\/b>. If the occupied MCH state (column 4 in output file <b><tt>output.lis<\/tt><\/b>) changes from one time step to the next, it is checked whether the old and new MCH states are the ones specified by the user. If this is the case, the geometry corresponding to the new time step (t) is retrieved from <b><tt>output.xyz<\/tt><\/b> (lines t(n<sub>atom<\/sub>+2)+1 to t(n<sub>atom<\/sub>+2)+n<sub>atom<\/sub>). <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>States involved in surface hop  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>First, the user has to specify the permissible old MCH state. The state has to be specified with two integers, the first giving the multiplicity (<b><tt>1<\/tt><\/b>=singlet, …), the second the state within the multiplicity (<b><tt>1 1<\/tt><\/b>=S<sub>0<\/sub>, <b><tt>1 2<\/tt><\/b>=S<sub>1<\/sub>, etc.). If a state of higher multiplicity is given, <b><tt>crossing.py<\/tt><\/b> will report all geometries where the old MCH state is any of the multiplet components. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>For the new MCH state, the same is valid.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Third, the direction of the surface hop has to be specified. Choosing “Backwards” has the same effect as exchanging the old and new MCH states. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.28.2\"><\/a><\/p>\n<h3>\n7.28.2  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>All geometries are in the end written to an output file, by default <b><tt>crossing.xyz<\/tt><\/b>. The file is in standard xyz format. The comment of each geometry gives the path to the trajectory where this geometry was extracted, the simulation time and the diagonal and MCH states at this simulation time. <\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.29\"><\/a><\/p>\n<h2>\n7.29  Essential Dynamics Analysis: <b><tt>trajana_essdyn.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:trajana_essdyn.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>An essential dynamics analysis <a href=\"#Amadei1993PSFB\" class=\"tth_citeref\">[66<\/a>] is a procedure to find the most active vibrational modes in an ensemble of trajectories.<br \/>\nIt is based on the computation of the covariance matrix between all Cartesian (or mass-weighted Cartesian) coordinates of all steps of all trajectories and a singular value decomposition of this covariance matrix.<br \/>\nFor details on the computation, see section <a href=\"#met:essdyn\">8.8<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The interactive script <b><tt>trajana_essdyn.py<\/tt><\/b> can be used to perform such an analysis.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.29.1\"><\/a><\/p>\n<h3>\n7.29.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>trajana_essdyn.py<\/tt><\/b> is an interactive script, which is started with:<\/p>\n<pre>\nuser@host> $SHARC\/trajana_essdyn.py\n<\/pre>\n<p>Note that before executing the script you should prepare an XYZ geometry file with the reference geometry (e.g., the ground state minimum or the average geometry from the trajectories).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.29.2\"><\/a><\/p>\n<h3>\n7.29.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>During interactive input, the script queries for the paths to the trajectories, the path to the reference structure, and a few other settings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Path to the trajectories  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>First the script asks the user to specify all directories for whose content the analysis should be performed. Enter one directory path at a time, and finish the directory input section by typing “<b><tt>end<\/tt><\/b>“. Please do not specify each trajectory directory separately, but specify their parent directories, e.g. the directories <b><tt>Singlet_1<\/tt><\/b> and <b><tt>Singlet_2<\/tt><\/b>. <b><tt>trajana_essdyn.py<\/tt><\/b> will automatically include all trajectories contained in these directories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you want to exclude certain trajectories from the analysis, it is sufficient to create an empty file called <b><tt>CRASHED<\/tt><\/b> or <b><tt>RUNNING<\/tt><\/b> in the corresponding trajectory directory. <b><tt>trajana_essdyn.py<\/tt><\/b> will ignore all directories containing one of these files.<br \/>\nAdditionally, <b><tt>trajana_essdyn.py<\/tt><\/b> will ignore trajectories with a <b><tt>DONT_ANALYZE<\/tt><\/b> file from <b><tt>diagnostics.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Path to reference structure  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For the essential dynamics analysis, a reference structure is required. This structure is substracted from all geometries for the correlation analysis.<br \/>\nThe structure can be in any format understandable by O<span style=\"font-size:x-small\">PEN<\/span>B<span style=\"font-size:x-small\">ABEL<\/span>, but the type of format needs to be specified.<br \/>\nIn most cases, the reference structure will be either in XYZ or M<span style=\"font-size:x-small\">OLDEN<\/span> format.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Mass-weighted coordinates  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If enabled, the correlation analysis will be carried out in mass-weighted Cartesian coordinates.<br \/>\nIn the output file, the mass-weighting will be removed properly.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of steps and time step  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>These parameters are automatically detected and suggested as defaults.<br \/>\nIt is not necessary to change them.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Time step intervals  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>By default, <b><tt>trajana_essdyn.py<\/tt><\/b> will analyze the full length of the simulations together.<br \/>\nHowever, it is also possible to compute the essential dynamics for different time intervals (e.g., if the molecular motion is different in the beginning of the dynamics).<br \/>\nMultiple, possibly overlapping, intervals can be entered; for each of the intervals, one set of output files is produced.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Results directory  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The path to the directory where the output files are stored.<br \/>\nThe path has to be entered as a relative or absolute path.<br \/>\nIf it does not exist, <b><tt>trajana_essdyn.py<\/tt><\/b> will create it.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.29.3\"><\/a><\/p>\n<h3>\n7.29.3  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Inside the results directory, <b><tt>trajana_essdyn.py<\/tt><\/b> will create two subdirectories, <b><tt>total_cov\/<\/tt><\/b> and <b><tt>cross_av\/<\/tt><\/b>.<br \/>\nIn the directory <b><tt>total_cov\/<\/tt><\/b> the results of the full covariance analysis are stored (i.e., essential modes found here have large total activity, but the trajectories could behave very differently).<br \/>\nOn the contrary, <b><tt>cross_av\/<\/tt><\/b> will contain the results of the analysis of the average trajectory (i.e., essential modes found here have strongly coherent activity, where all trajectories behave similarly).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For each time step interval entered, one output file (e.g., <b><tt>0-1000.molden<\/tt><\/b>) is created in each of the two subdirectories.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.30\"><\/a><\/p>\n<h2>\n7.30  General Data Analysis: <b><tt>data_collector.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:data_collector.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Whereas most of the other analysis scripts in the S<span style=\"font-size:x-small\">HARC<\/span> suite are intended for rather specific tasks, <b><tt>data_collector.py<\/tt><\/b> is aimed at providing a general analysis tool to carry out a large variety of tasks.<br \/>\nThe primary task of <b><tt>data_collector.py<\/tt><\/b> is to collect tabular data from files which are present in all trajectories, possibly perform some analysis procedures (smoothing, averaging, convoluting, integrating, summing), and output the combined data as a single file.<br \/>\nPossible applications of this functionality are statistical analysis of internal coordinates (e.g., mean and variation in a bond length), the creation of hair figures (e.g., a specific bond length plotted for all trajectories), data convolutions (e.g., distribution of bond length over time, simulation of time- and energy-resolved spectra), or data integration (e.g., computation of time-resolved intensities).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.30.1\"><\/a><\/p>\n<h3>\n7.30.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>data_collector.py<\/tt><\/b> is an interactive script, which is started with:<\/p>\n<pre>\nuser@host> $SHARC\/data_collector.py\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.30.2\"><\/a><\/p>\n<h3>\n7.30.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In general, the first step in <b><tt>data_collector.py<\/tt><\/b> is to collect tabular data files which exist in the directories of multiple trajectories.<br \/>\nFor each trajectory, this file needs to have the same file name and the same tabular format; for example, one could read for all trajectories the <b><tt>output.lis<\/tt><\/b> files.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Collecting  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Hence, in the first input section, the script asks the user to specify all directories for whose content the analysis should be performed. Enter one directory path at a time, and finish the directory input section by typing “<b><tt>end<\/tt><\/b>“. Please do not specify each trajectory directory separately, but specify their parent directories, e.g. the directories <b><tt>Singlet_1<\/tt><\/b> and <b><tt>Singlet_2<\/tt><\/b>. <b><tt>data_collector.py<\/tt><\/b> will automatically include all trajectories contained in these directories.<br \/>\nIf you want to exclude certain trajectories from the analysis, it is sufficient to create an empty file called <b><tt>CRASHED<\/tt><\/b> or <b><tt>RUNNING<\/tt><\/b> in the corresponding trajectory directory. <b><tt>data_collector.py<\/tt><\/b> will ignore all directories containing one of these files.<br \/>\nAdditionally, <b><tt>data_collector.py<\/tt><\/b> will ignore trajectories with a <b><tt>DONT_ANALYZE<\/tt><\/b> file from <b><tt>diagnostics.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the second step, <b><tt>data_collector.py<\/tt><\/b> displays all files which appear in multiple trajectories and which might be suitable for analysis (the script ignores files which it knows to be not suitable, e.g., <b><tt>output.dat<\/tt><\/b>, <b><tt>output.xyz<\/tt><\/b>, most files in the <b><tt>QM\/<\/tt><\/b> or <b><tt>restart\/<\/tt><\/b> subdirectories, …).<br \/>\nAll other files (e.g., <b><tt>output.lis<\/tt><\/b>, files in <b><tt>output_data\/<\/tt><\/b>, …) will be displayed, together with the number of appearances.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Once one of the files has been selected, one needs to assign the different data columns.<br \/>\n(i) One column is designated the time column T, which defines the sequentiality of the data:<br \/>\n(ii) Multiple columns can then be designated as data columns, called X columns in the following.<br \/>\n(iii) The same number of columns is designated as weight columns, called Y columns here (weights can be set equal to 1 by selecting column “0” in the relevant menu).<br \/>\nFor example, for a time-resolved spectrum, the transition energies would be the X data, whereas the oscillator strengths would be the Y data (weights).<br \/>\nWith these assignments, the full data set is defined:<\/p>\n<ul>\n<li> For each trajectory a\n<ul>\n<li> For each time step t\n<ul>\n<li> For each X column i there will be a value pair (x<sup>a<\/sup><sub>i<\/sub>(t),y<sup>a<\/sup><sub>i<\/sub>(t)) or (x<sup>a<\/sup><sub>i<\/sub>(t),1).\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<p>In the simplest case, there will be exactly one (x<sup>a<\/sup>(t),1) pair for each trajectory and time, which is a two-dimensional data set.<br \/>\nKeep in mind that in general, each trajectory could have different time steps at this point.<br \/>\nWe refer to this kind of data set (independent trajectories with possibly different time axes) as <b><tt>Type1<\/tt><\/b> data set.<br \/>\nAs will be described below, in <b><tt>data_collector.py<\/tt><\/b>, during certain processing steps the format of the data set is changed, which will create <b><tt>Type2<\/tt><\/b> or <b><tt>Type3<\/tt><\/b> data sets.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Once this data set is collected from the files (where too short or commented lines are ignored), <b><tt>data_collector.py<\/tt><\/b> allows for a number of subsequent processing steps, which are summarized in Figure <a href=\"#fig:data_collector\">7.4<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg7.4\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/data_collector.png\"> <\/p>\n<div style=\"text-align:center\">Figure 7.4:<br \/>\n Possible workflows in <b><tt>data_collector.py<\/tt><\/b>.<br \/>\n Grey boxes denote the different computational actions, yellow diamonds denote the different decisions which are queried in the input dialog, and the boxes at the denote the three different data set types (dark blue=<b><tt>Type1<\/tt><\/b>, light blue=<b><tt>Type2<\/tt><\/b>, green=<b><tt>Type3<\/tt><\/b>).<br \/>\n The different actions and data set types are explained in the text.\n <\/div>\n<p> <a id=\"fig:data_collector\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p><b>Smoothing  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this step, each trajectory is individually smoothed, using one of several smoothing kernels (Gaussian, Lorentzian, Log-normal, rectangular).<br \/>\nSmoothing does not change the size or format of the data set, each value is simply replaced by the corresponding smoothed value; hence, a new <b><tt>Type1<\/tt><\/b> data set is obtained.<br \/>\nSmoothing is applied to each X and each Y column independently, but always with the same kernel.<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-21.png\">\n<\/td>\n<td width=\"1%\">(7.1)<\/td>\n<\/tr>\n<\/table>\n<p>Here, f(t,t′) is the smoothing kernel.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Synchronizing  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this step, the <b><tt>Type1<\/tt><\/b> data set is reformatted, by merging all trajectories together.<br \/>\nThis step creates a <b><tt>Type2<\/tt><\/b> data set, which has a common T axis for all trajectories (simply the union of the T columns from all trajectories).<br \/>\nFor each time step, all X and Y values of all trajectories are collected.<br \/>\nIf a trajectories does not have data at a particular time step, NaNs will be inserted.<br \/>\nIn this way, a rectangular, two-dimensional data set is obtained, with as many rows as time steps, and 2n<sub>traj<\/sub>n<sub>X<\/sub> data columns.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A simple application of Collecting+Synchronizing could be to generate a table with the bond length for all time steps for all trajectories, in order to generate a “hair figure”.<br \/>\nThis task could in principle also be accomplished with Bash tools like <b><tt>awk<\/tt><\/b> and <b><tt>paste<\/tt><\/b>, but this is troublesome if the trajectories are of different length, with different time steps, or if the table files contain comments.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Averaging  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>Type2<\/tt><\/b> data set from the Synchronizing step can contain a large number of data columns (2n<sub>traj<\/sub>n<sub>X<\/sub>).<br \/>\nIn order to reduce this amount of information, the Averaging step can be used to compute the mean and standard deviation across all trajectories, separately for each time step.<br \/>\nThis will create a new <b><tt>Type2<\/tt><\/b> data set, which still has a common time axis, but will only contain 4n<sub>X<\/sub>+1 data columns; these are the mean and standard deviation of all X and Y columns, plus one column giving the number of trajectories for each time step.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Currently, this step can be performed with either arithmetic mean\/standard deviation or geometric mean\/standard deviation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Statistics  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Similar to the Averaging step, the Statistics step computes mean and standard deviations from a <b><tt>Type2<\/tt><\/b> data set.<br \/>\nThe difference is that during Statistics, these values are computed for all values from the first to the current time step.<br \/>\nThe data in the last time step thus gives the total statistics over all time steps and trajectories.<br \/>\nThe <b><tt>Type2<\/tt><\/b> data set from the Statistics step contains the same number of data columns as the one from the Averaging step.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Currently, this step can be performed with either arithmetic mean\/standard deviation or geometric mean\/standard deviation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>With the Averaging and Statistics steps, it is possible to compute the same data as with <b><tt>trajana_nma.py<\/tt><\/b> (if the appropriate files are read), namely the total (Statistics) and coherent (Averaging+Statistics) activity of the normal modes.<br \/>\nUsing <b><tt>data_collector.py<\/tt><\/b>, the same analysis can also be applied to internal coordinates computed with <b><tt>geo.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Convoluting(X)  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to create a data set which has common T <em>and<\/em> X axes (a <b><tt>Type3<\/tt><\/b> data set), it is in general necessary to perform some kind of data convolution involving the X column data.<br \/>\nIn order to do this, <b><tt>data_collector.py<\/tt><\/b> creates a grid along the X axis (n<sub>grid<\/sub> points from the minimum value to the maximum value of all X data in the data set, plus some padding).<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-22.png\">\n<\/td>\n<td width=\"1%\">(7.2)<\/td>\n<\/tr>\n<\/table>\n<p>The created <b><tt>Type3<\/tt><\/b> data set has n<sub>X<\/sub> data points for each time step and each X grid point.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using energies as X columns and oscillator strengths\/intensities as Y columns, in this way it is possible to compute time-dependent spectra.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Summing(Y)  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>When n<sub>X<\/sub> is larger than one, the Summing step can be used to compute the sum over all data points for each time step and each X grid point.<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-23.png\">\n<\/td>\n<td width=\"1%\">(7.3)<\/td>\n<\/tr>\n<\/table>\n<p>This creates a new <b><tt>Type3<\/tt><\/b> data set, which will only contain one data point for each time step and each X grid point.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For example, for a transient spectrum involving multiple final states (n<sub>X<\/sub> > 1), after the Convoluting(X) step one obtains one transient spectrum for each final state. With the Summing(Y) step, one can then compute the total transient absorption spectrum.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Integrating(X)  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>When computing transient spectra, one is often interested in integrating the spectrum within a certain energy window.<br \/>\nThis can be done with the Integrating(X) step.<br \/>\nAfter entering a lower and upper X limit, a new <b><tt>Type3<\/tt><\/b> data set is created, with only three data points per time step.<br \/>\nThe first data point contains the integral from minus infinity to the lower limit, the second data point the integral between lower and upper limit, and the third data point the integral from the upper limit to infinity.<br \/>\nIf Summing(Y) was not carried out, this integration is carried out independently for each of the n<sub>X<\/sub> data columns.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Convoluting(T)  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>Type3<\/tt><\/b> data set can also be convoluted along the time axis (e.g., in order to apply an instrument response function to a time-resolved spectrum).<br \/>\nIn order to do this, a uniform grid along the T axis is generated (with n<sub>Tgrid<\/sub> points from the minimum value to the maximum value of the previous T axis, plus some padding).<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-24.png\">\n<\/td>\n<td width=\"1%\">(7.4)<\/td>\n<\/tr>\n<\/table>\n<p>The created <b><tt>Type3<\/tt><\/b> data set has as many data points for each X grid point as before, but the number of time steps is now n<sub>Tgrid<\/sub>.<br \/>\nConvoluting(T) can be applied also if Summing(Y) and\/or Integrating(X) were used (in this case, the kernel is applied to the summed up or integrated data).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Integrating(T)  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This step carries out a cumulative summation along the T axis.<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-25.png\">\n<\/td>\n<td width=\"1%\">(7.5)<\/td>\n<\/tr>\n<\/table>\n<p>In this way, the data in the last time step constitute the integral over all time steps.<br \/>\nSince all the partial cumulative sums are also computed, integrals within some bounds can simply be computed as differences between partial cumulative sums.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Converting  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>At the end of the workflow, a <b><tt>Type3<\/tt><\/b> data set can be converted back into a <b><tt>Type2<\/tt><\/b> data set, which affects how the output file is formatted.<br \/>\nThis is usually a good idea if the Integrating(X) step was performed, but might not be a good idea otherwise.<br \/>\nSee below for how the different data set types are formatted on output.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.30.3\"><\/a><\/p>\n<h3>\n7.30.3  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>After the input dialog is finished, <b><tt>data_collector.py<\/tt><\/b> will start carrying out the requested analyses.<br \/>\nFor each of the workflow steps, one output file is written, so that all intermediate results can be used as well.<br \/>\nOutput files have automatically generated filenames, which describe how the data was obtained.<br \/>\nFilenames are always in the form <b><tt>collected_data_<T>_<X>_<Y>_<steps>.<type>.txt<\/tt><\/b>, where <b><tt><T><\/tt><\/b> is an integer giving the T column index, <b><tt><X><\/tt><\/b> and <b><tt><y><\/tt><\/b> are lists of integers of the X and Y column indices, <b><tt><steps><\/tt><\/b> is a string denoting which workflow steps were carried out, and <b><tt><type><\/tt><\/b> denotes the data set type.<br \/>\nFor example, an output file could be named <b><tt>collected_data_1_2_0_sy_cX.type3.txt<\/tt><\/b>, where column 1 was the T column, column 2 the X column, no Y column was used, Synchronizing and Convoluting(X) were performed, resulting in a <b><tt>Type3<\/tt><\/b> data set.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Format of <b><tt>Type1<\/tt><\/b> data set output  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>Type1<\/tt><\/b> data sets are formatted such that each trajectory is given as a continuous block, separated by an empty line.<br \/>\nWithin each block, each line contains the data of one time step, order increasingly.<br \/>\nEach line contains a trajectory index, the relative file path, the time, all X column data, and then all Y column data.<br \/>\n<span class=\"footnotesize\"><\/p>\n<pre>\n#    1                               2               3               4               5               6               7\n#Index                        Filename            Time    X Column   5    X Column   6    Y Column   0    Y Column   0\n     0 Singlet_1\/\/TRAJ_00001\/.\/Geo.out  0.00000000E+00  1.13340000E-01  7.99096900E+00  1.00000000E+00  1.00000000E+00\n     0 Singlet_1\/\/TRAJ_00001\/.\/Geo.out  5.00000000E-01  1.59173000E-01  7.94395200E+00  1.00000000E+00  1.00000000E+00\n     0 Singlet_1\/\/TRAJ_00001\/.\/Geo.out  1.00000000E+00  2.10868000E-01  7.89084000E+00  1.00000000E+00  1.00000000E+00\n     ...\n     1 Singlet_1\/\/TRAJ_00002\/.\/Geo.out  0.00000000E+00  5.03990000E-02  7.99078100E+00  1.00000000E+00  1.00000000E+00\n     1 Singlet_1\/\/TRAJ_00002\/.\/Geo.out  1.00000000E+00  3.80370000E-02  8.00349700E+00  1.00000000E+00  1.00000000E+00  \n     1 Singlet_1\/\/TRAJ_00002\/.\/Geo.out  2.00000000E+00  1.09515000E-01  7.93073500E+00  1.00000000E+00  1.00000000E+00 \n     ...\n     2 Singlet_1\/\/TRAJ_00004\/.\/Geo.out  0.00000000E+00  2.10908000E-01  8.29417600E+00  1.00000000E+00  1.00000000E+00\n     2 Singlet_1\/\/TRAJ_00004\/.\/Geo.out  5.00000000E-01  1.49506000E-01  8.35651800E+00  1.00000000E+00  1.00000000E+00\n     2 Singlet_1\/\/TRAJ_00004\/.\/Geo.out  1.00000000E+00  1.05887000E-01  8.40056700E+00  1.00000000E+00  1.00000000E+00\n     ...\n<\/pre>\n<p> <\/span><br \/>\nNote here in the example that the second trajectory has a time step of 1.0 fs and thus no data at 0.5 fs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Format of <b><tt>Type2<\/tt><\/b> data set output  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>Type2<\/tt><\/b> data sets are formatted such that all trajectories share a common time axis, hence for each time step there will be one line of data.<br \/>\nEach line starts with the time, followed columns with the data for the first trajectory, followed by the data for the second trajectory, etc.<br \/>\nWithin each trajectory, first all X columns, then all Y columns are given. If a Y column contains only unit weights (using special file column “0”), then this Y column is omitted from the <b><tt>Type2<\/tt><\/b> formatted output.<br \/>\n<span class=\"footnotesize\"><\/p>\n<pre>\n#             1               2               3               4               5               6               7  ...\n#          Time    X Column   5    X Column   6    X Column   5    X Column   6    X Column   5    X Column   6  ...\n 0.00000000E+00  1.13340000E-01  7.99096900E+00  5.03990000E-02  7.99078100E+00  2.10908000E-01  8.29417600E+00  ...\n 5.00000000E-01  1.59173000E-01  7.94395200E+00             NaN             NaN  1.49506000E-01  8.35651800E+00  ...\n 1.00000000E+00  2.10868000E-01  7.89084000E+00  3.80370000E-02  8.00349700E+00  1.05887000E-01  8.40056700E+00  ...\n ...\n<\/pre>\n<p> <\/span><br \/>\nNote here in the example that the second trajectory does not have data at 0.5 fs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Format of <b><tt>Typ3<\/tt><\/b> data set output  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>Type3<\/tt><\/b> data sets are formatted such that all trajectories share common time and X axes.<br \/>\nThe data is formatted block-wise, with the first block corresponding to the first time step and containing all points on the X grid, followed by an empty line, followed by the second block, etc.<br \/>\nEach block consists of n<sub>grid<\/sub> lines, each starting with the time and X value in the first two columns and followed by n<sub>X<\/sub> columns with the convoluted data.<br \/>\n<span class=\"footnotesize\"><\/p>\n<pre>\n#             1               2               3               4 \n#          Time          X_axis       Conv(5,0)       Conv(6,0) \n 0.00000000E+00 -1.45534000E-01  2.38544715E-05  0.00000000E+00 \n 0.00000000E+00  2.30671958E-01  1.51462322E+00  0.00000000E+00 \n 0.00000000E+00  6.06877917E-01  1.07930050E-01  0.00000000E+00 \n ...\n 5.00000000E-01 -1.45534000E-01  1.31312692E-04  0.00000000E+00 \n 5.00000000E-01  2.30671958E-01  1.28614756E+00  0.00000000E+00 \n 5.00000000E-01  6.06877917E-01  4.46251462E-10  0.00000000E+00 \n ...\n 1.00000000E+00 -1.45534000E-01  8.75871124E-05  0.00000000E+00 \n 1.00000000E+00  2.30671958E-01  2.42291042E+00  0.00000000E+00 \n 1.00000000E+00  6.06877917E-01  1.60277894E-16  0.00000000E+00 \n ...\n<\/pre>\n<p> <\/span><\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.31\"><\/a><\/p>\n<h2>\n7.31  Handling large sets of coordinate data: <b><tt>align_and_reorder_traj.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:align_and_reorder_traj.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script <b><tt>align_and_reorder_traj.py<\/tt><\/b> can be used to do two tasks simultaneously-(i) aligning the coordinate (and velocities) of trajectories and (ii) storing the coordinates resorted, with one file per time step instead of one file per trajectory.<br \/>\nThis script reads one NetCDF file with coordinates (and velocities) from each trajectory; it either reads <b><tt>output.dat.nc<\/tt><\/b> or <b><tt>output_NUC.dat.nc<\/tt><\/b>.<br \/>\nUsing the Kabsch algorithm, it translates and rotates a selected part of the system onto a reference geometry.<br \/>\nIt then stores one file per time step, containing the coordinates from all trajectories for that time step.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The output is also using NetCDF files, but these NetCDF files are compliant with the format used by A<span style=\"font-size:x-small\">MBER<\/span>.<br \/>\nHence, the resulting files can be read by VMD and <b><tt>cpptraj<\/tt><\/b> for further analysis.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.31.1\"><\/a><\/p>\n<h3>\n7.31.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>align_and_reorder_traj.py<\/tt><\/b> is an interactive script, which is started with:<\/p>\n<pre>\nuser@host> $SHARC\/align_and_reorder_traj.py\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.31.2\"><\/a><\/p>\n<h3>\n7.31.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b>Paths to trajectories  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This part works just as in other interactive scripts.<br \/>\nThe script asks the user to specify all directories for whose content the analysis should be performed. Enter one directory path at a time, and finish the directory input section by typing “<b><tt>end<\/tt><\/b>“. Please do not specify each trajectory directory separately, but specify their parent directories, e.g. the directories <b><tt>Singlet_1<\/tt><\/b> and <b><tt>Singlet_2<\/tt><\/b>. <b><tt>crossing.py<\/tt><\/b> will automatically include all trajectories contained in these directories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you want to exclude certain trajectories from the analysis, it is sufficient to create an empty file called <b><tt>CRASHED<\/tt><\/b> or <b><tt>RUNNING<\/tt><\/b> in the corresponding trajectory directory. <b><tt>crossing.py<\/tt><\/b> will ignore all directories containing one of these files.<br \/>\nAdditionally, <b><tt>align_and_reorder_traj.py<\/tt><\/b> will ignore trajectories with a <b><tt>DONT_ANALYZE<\/tt><\/b> file from <b><tt>diagnostics.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Coordinate file  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here, the user get prompted to select either <b><tt>output.dat.nc<\/tt><\/b> or <b><tt>output_NUC.dat.nc<\/tt><\/b>.<br \/>\nThe former is the default, the latter is only offered if such files are present.<br \/>\nWhich file to use depends on whether you have used <b><tt>output_format netcdf<\/tt><\/b> or <b><tt>output_format netcdf_separate_nuclei<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Reference geometry  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here you provide a file in xyz format with the reference geometry to which you want to align (part of) your system.<br \/>\nThe atoms in the reference file should have the same ordering as in the S<span style=\"font-size:x-small\">HARC<\/span> trajectories.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Reference atom map  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you only want to align part of the system (e.g., the QM region of a QM\/MM calculation), here you specify the atom numbers of the atoms that should be aligned.<br \/>\nThis list must have the same length as the reference geometry has atoms.<br \/>\nIf the reference geometry has a different atom ordering as the atoms in the S<span style=\"font-size:x-small\">HARC<\/span> trajectory, one can provide the indices in the correct way here; but this is error-prone and not recommended.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Perspective  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here one can choose between two options.<br \/>\nWhen using the “molecular perspective”, the molecule (i.e., the atoms in the reference atom map) is aligned optimally to the reference geometry at each individual time step.<br \/>\nThis minimizes motion of the molecule, so that one can observe the distribution of solvent around the molecule.<br \/>\nThis option removes self-rotation of the molecule, but because the frame of reference is different in each time step, this perspective is not an inertial frame.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, one can use the “solvent perspective”.<br \/>\nHere, the translation and rotation operation is determined for each trajectory only from the first time step, and the same operations are then applied to later time steps.<br \/>\nThis leads to a proper inertial frame of reference.<br \/>\nHere, one can observe that the molecule can rotate away from the reference orientation for later time steps, just as in reality.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Output files  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here one can choose to write or not write the coordinates and\/or the velocities.<br \/>\nThe default, and probably most used, option is to write only coordinates.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.31.3\"><\/a><\/p>\n<h3>\n7.31.3  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script creates, in the present directory, one NetCDF file per time step covered by the selected trajectories.<br \/>\nThe files are called <b><tt>frame_coord_mol_pers_XXXXX.nc<\/tt><\/b> or <b><tt>frame_coord_sol_pers_XXXXX.nc<\/tt><\/b>, depending on the chosen perspective.<br \/>\nThese files use all the settings needed to open them in VMD or <b><tt>cpptraj<\/tt><\/b>; note that you need a corresponding <b><tt>prmtop<\/tt><\/b> file in either case.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.32\"><\/a><\/p>\n<h2>\n7.32  Producing radial distribution functions: <b><tt>frames_to_RDF.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:frames_to_RDF.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This script is used together with the output NetCDF files from <b><tt>align_and_reorder_traj.py<\/tt><\/b> (Section <a href=\"#sec:align_and_reorder_traj.py\">7.31<\/a>).<br \/>\nIt calculates the radial distribution function (RDF) or radial histogram between two sets of atoms A and B over all snapshots t in the NetCDF file.<br \/>\nThe histogram is defined as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-26.png\">\n<\/td>\n<td width=\"1%\">(7.6)<\/td>\n<\/tr>\n<\/table>\n<p>The RDF is related to the histogram by<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-27.png\">\n<\/td>\n<td width=\"1%\">(7.7)<\/td>\n<\/tr>\n<\/table>\n<p>where δ<sub>AB<\/sub>=1 if the sets A and B are identical.<br \/>\nHence, the RDF is a normalized version of the histogram, although the normalization of the RDF is missing the volume of the system and hence the RDF will not approach 1 at long distances, as it should.<br \/>\nWe recommend to renormalize manually.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script also computes the Cartesian-weighted histogram, which for the x component is<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-28.png\">\n<\/td>\n<td width=\"1%\">(7.8)<\/td>\n<\/tr>\n<\/table>\n<p>and analogously for y and z.<br \/>\nNote that h<sub>AB<\/sub>(R)=h<sub>AB<\/sub><sup>x<\/sup>(R)+h<sub>AB<\/sub><sup>y<\/sup>(R)+h<sub>AB<\/sub><sup>z<\/sup>(R).<br \/>\nThe same applies to the RDFs.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that this script tries to use <b><tt>numba<\/tt><\/b> for just-in-time compilation, if <b><tt>numba<\/tt><\/b> is installed.<br \/>\nThis dramatically improves performance.<br \/>\nNote that the script caches the compiled code so that it can be reused when the script is called again.<br \/>\nHowever, this only works if all numerical parameters (especially the masks) are identical between the calls.<br \/>\nHence, if operating on a large number of files, try to arrange your computations such that you loop over the NetCDF files in the innermost loop.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.32.1\"><\/a><\/p>\n<h3>\n7.32.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>frames_to_RDF.py<\/tt><\/b> is a command-line, non-interactive script, which is started with:<\/p>\n<pre>\nuser@host> $SHARC\/frame_to_RDF.py <NetCDF> <mask1> <mask2> <outfile> [options]\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.32.2\"><\/a><\/p>\n<h3>\n7.32.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script has four required input arguments.<br \/>\nThe first argument is the path to the NetCDF file.<br \/>\nNote that NetCDF files that are produced by <b><tt>sharc.x<\/tt><\/b> or <b><tt>driver.py<\/tt><\/b> do not work, but files from <b><tt>align_and_reorder_traj.py<\/tt><\/b> (Section <a href=\"#sec:align_and_reorder_traj.py\">7.31<\/a>) do.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The second and third arguments are files specifying which atoms are in the sets A and B.<br \/>\nThese files can be in either of two file formats: raw ASCII (one integer per line) or output files of <b><tt>cpptraj<\/tt><\/b>‘s <b><tt>mask<\/tt><\/b> command.<br \/>\nNote that these two files can be identical, but if they are not, they must not have shared indices (this limitation might get removed in the future).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The fourth argument is the desired output file name.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.32.3\"><\/a><\/p>\n<h3>\n7.32.3  Options<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The optional arguments are summarized in Table <a href=\"#tab:RDF_options\">7.18<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.18\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.18: Command-line options for <b><tt>frames_to_RDF.py<\/tt><\/b>. <\/div>\n<p> <a id=\"tab:RDF_options\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit. <\/td>\n<td align=\"left\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-w FLOAT <\/td>\n<td align=\"left\">Bin width in Å <\/td>\n<td align=\"left\">0.1<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-n INT <\/td>\n<td align=\"left\">Number of bins <\/td>\n<td align=\"left\">100<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-r <\/td>\n<td align=\"left\">Write raw histograms <\/td>\n<td align=\"left\">write RDFs<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.32.4\"><\/a><\/p>\n<h3>\n7.32.4  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The output is an ASCII file with five columns.<br \/>\nThe first column is the distance in Å, the second one is the histogram or RDF, and the three remaining columns are the x, y, and z component of the histogram or RDF.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.32.5\"><\/a><\/p>\n<h3>\n7.32.5  Obtaining mask files<\/h3>\n<p><a id=\"sec:amber_mask_files\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Mask files can be written manually.<br \/>\nThey are simply an ASCII file with one integer per line, listing all the atoms that this mask encompasses.<br \/>\nCounting starts at 1.<br \/>\nNote that indices must not be repeated.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, mask files can be written with <b><tt>cpptraj<\/tt><\/b>.<br \/>\nThis requires a <b><tt>prmtop<\/tt><\/b> file and the NetCDF file that should be analyzed.<br \/>\nOne starts <b><tt>cpptraj<\/tt><\/b>, loads the <b><tt>prmtop<\/tt><\/b> file, then the first frame of the NetCDF file, then uses the <b><tt>mask<\/tt><\/b> command to select some atoms (using <a href=\"https:\/\/amberhub.chpc.utah.edu\/atom-mask-selection-syntax\/\"> A<span style=\"font-size:x-small\">MBER<\/span>‘s atom selection syntax<\/a>), then runs the program:<br \/>\n[commandchars=<br \/>{}]<br \/>\nparm system.prmtop<br \/>\ntrajin frame_coord_mol_pers_00000.nc 1 1<br \/>\nmask @mask @mask @mask @mask @run<br \/>\nquit<br \/>\nThis produces a file that starts with <b><tt>Frame AtomNum Atom ResNum Res MolNum<\/tt><\/b>.<br \/>\nIf this line is present, <b><tt>frames_to_RDF.py<\/tt><\/b> recognizes the format and reads the atom indices from the second column.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.33\"><\/a><\/p>\n<h2>\n7.33  Producing 3D distributions: <b><tt>frames_to_dx.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:frames_to_dx.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This script is used together with the output NetCDF files from <b><tt>align_and_reorder_traj.py<\/tt><\/b> (Section <a href=\"#sec:align_and_reorder_traj.py\">7.31<\/a>).<br \/>\nIt calculates the three-dimensional distribution of atoms from a set A on a grid, using kernel density estimation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that this script tries to use <b><tt>numba<\/tt><\/b> for just-in-time compilation, if <b><tt>numba<\/tt><\/b> is installed.<br \/>\nThis dramatically improves performance.<br \/>\nThe compiled code is not cached, unlike for <b><tt>frames_to_RDF.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.33.1\"><\/a><\/p>\n<h3>\n7.33.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>frames_to_dx.py<\/tt><\/b> is a command-line, non-interactive script, which is started with:<\/p>\n<pre>\nuser@host> $SHARC\/frame_to_dx.py <NetCDF> <mask> <outfile> [options]\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.33.2\"><\/a><\/p>\n<h3>\n7.33.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script has three required input arguments.<br \/>\nThe first argument is the path to the NetCDF file.<br \/>\nNote that NetCDF files that are produced by <b><tt>sharc.x<\/tt><\/b> or <b><tt>driver.py<\/tt><\/b> do not work, but files from <b><tt>align_and_reorder_traj.py<\/tt><\/b> (Section <a href=\"#sec:align_and_reorder_traj.py\">7.31<\/a>) do.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The second argument is a file specifying which atoms are in the set A.<br \/>\nThis file can be in either of two file formats: raw ASCII (one integer per line) or output files of <b><tt>cpptraj<\/tt><\/b>‘s <b><tt>mask<\/tt><\/b> command.<br \/>\nThe mask files can be created as defined in Section <a href=\"#sec:amber_mask_files\">7.32.5<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The third argument is the desired output file name.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.33.3\"><\/a><\/p>\n<h3>\n7.33.3  Options<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The optional arguments are summarized in Table <a href=\"#tab:dx_options\">7.19<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.19\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.19: Command-line options for <b><tt>frames_to_dx.py<\/tt><\/b>. <\/div>\n<p> <a id=\"tab:dx_options\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit. <\/td>\n<td align=\"left\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-w FLOAT <\/td>\n<td align=\"left\">Cell width in Å <\/td>\n<td align=\"left\">0.5<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-n INT <\/td>\n<td align=\"left\">Number of cells per direction <\/td>\n<td align=\"left\">40<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-f FLOAT <\/td>\n<td align=\"left\">FWHM of the convolution Gaussian in Å <\/td>\n<td align=\"left\">0.5<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-c X,Y,Z <\/td>\n<td align=\"left\">Center of the grid <\/td>\n<td align=\"left\">origin<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.33.4\"><\/a><\/p>\n<h3>\n7.33.4  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The output is an ASCII file containing grid data in OpenDX format.<br \/>\nThe file specifies the position of the grid and the values of each grid cell.<br \/>\nThese files can be visualized with VMD using the Isosurface representation.<br \/>\nSee Ref. <a href=\"#Polonius2024JCTC\" class=\"tth_citeref\">[37<\/a>] for a discussion how to choose the isovalues needed for the Isosurface plots.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.34\"><\/a><\/p>\n<h2>\n7.34  Computing X-ray scattering: <b><tt>RDF_to_scattering.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:RDF_to_scattering.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This script takes the output of <b><tt>frames_to_RDF.py<\/tt><\/b> with the <b><tt>-r<\/tt><\/b> option and computes X-ray scattering using the independent atom model.<br \/>\nNote that the script is rather preliminary and has only limited options.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The data to compute the atomic form factors are taken from <a href=\"https:\/\/lampz.tugraz.at\/~hadley\/ss1\/crystaldiffraction\/atomicformfactors\/formfactors.php\"><tt>https:\/\/lampz.tugraz.at\/~hadley\/ss1\/crystaldiffraction\/atomicformfactors\/formfactors.php<\/tt><\/a>, which employs linear combinations of Gaussian functions to model f<sub>i<\/sub>(Q).<br \/>\nThe full function is:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-29.png\">\n<\/td>\n<td width=\"1%\">(7.9)<\/td>\n<\/tr>\n<\/table>\n<p>These atomic form factors can be used up until Q=25Å<sup>−1<\/sup>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The scattering signal is computed as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-30.png\">\n<\/td>\n<td width=\"1%\">(7.10)<\/td>\n<\/tr>\n<\/table>\n<p>Note that the script does not currently perform any smoothing or normalization.<br \/>\nTherefore, only difference scattering signals should be computed and no absolute intensities are obtained.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.34.1\"><\/a><\/p>\n<h3>\n7.34.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>RDF_to_scattering.py<\/tt><\/b> is a command-line, non-interactive script, which is started like this (do not type the line break):<\/p>\n<pre>\nuser@host> $SHARC\/RDF_to_scattering.py --alpha <element1> --beta <element2> \n           --hist <histogram> --hist-ref <reference> [options]\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.34.2\"><\/a><\/p>\n<h3>\n7.34.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script requires several input arguments.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>-alpha<\/tt><\/b> and <b><tt>-beta<\/tt><\/b> flags specify the two elements for which the structure factor S(Q) is calculated.<br \/>\nThese must match keys in the atomic form factor data file (e.g. <b><tt>h<\/tt><\/b>, <b><tt>o<\/tt><\/b>, <b><tt>li1+<\/tt><\/b>).<br \/>\nThe keys are case-insensitive.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The <b><tt>-hist<\/tt><\/b> and <b><tt>-hist-ref<\/tt><\/b> flags give the paths to the files containing the pair distribution functions H<sub>αβ<\/sub>(r) and H<sub>αβ<\/sub><sup>ref<\/sup>(r), respectively.<br \/>\nThese files must contain at least two columns: the distance in Å in the first column and the histogram values in the user-selected column.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The form factor data file is specified with <b><tt>-data<\/tt><\/b>.<br \/>\nIf SHARC is properly installed and the environment variable <b><tt>$SHARC<\/tt><\/b> is set, the default form factor file is taken from <b><tt>$SHARC\/..\/lib\/formfactor_gaussian.txt<\/tt><\/b>.<br \/>\nIf this file exists, <b><tt>-data<\/tt><\/b> is optional, else it is required.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.34.3\"><\/a><\/p>\n<h3>\n7.34.3  Options<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The optional arguments are summarized in Table <a href=\"#tab:sq_options\">7.20<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.20\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.20: Command-line options for <b><tt>RDF_to_scattering.py<\/tt><\/b>. <\/div>\n<p> <a id=\"tab:sq_options\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-data FILE <\/td>\n<td align=\"left\">Form factor data file <\/td>\n<td align=\"left\">$SHARC\/..\/lib\/formfactor_gaussian.txt<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-alpha STR <\/td>\n<td align=\"left\">Element α key <\/td>\n<td align=\"left\">required<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-beta STR <\/td>\n<td align=\"left\">Element β key <\/td>\n<td align=\"left\">required<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-hist FILE <\/td>\n<td align=\"left\">Histogram H<sub>αβ<\/sub>(r) file <\/td>\n<td align=\"left\">required<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-hist-ref FILE <\/td>\n<td align=\"left\">Reference histogram H<sub>αβ<\/sub><sup>ref<\/sup>(r) file <\/td>\n<td align=\"left\">required<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-column INT <\/td>\n<td align=\"left\">Histogram column index (1-based) <\/td>\n<td align=\"left\">2<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-rcut FLOAT <\/td>\n<td align=\"left\">Cutoff for maximum r (Å) <\/td>\n<td align=\"left\">10.0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-qmax FLOAT <\/td>\n<td align=\"left\">Maximum Q value (Å<sup>−1<\/sup>) <\/td>\n<td align=\"left\">15.0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-qpoints INT <\/td>\n<td align=\"left\">Number of Q points to compute <\/td>\n<td align=\"left\">200<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit <\/td>\n<td align=\"left\">–<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.34.4\"><\/a><\/p>\n<h3>\n7.34.4  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The output is written to standard output and consists of two columns: the Q value and the corresponding structure factor S(Q).<br \/>\nEach line corresponds to a different Q value, spaced linearly between 0.01 and <b><tt>qmax<\/tt><\/b> with a total of <b><tt>qpoints<\/tt><\/b> values.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>These results can be redirected into a file for plotting or further analysis:<\/p>\n<pre>\nuser@host> .\/RDF_to_scattering.py ... > sq.dat\n<\/pre>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.35\"><\/a><\/p>\n<h2>\n7.35  Optimizations: <b><tt>otool_external<\/tt><\/b> and <b><tt>setup_orca_opt.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:Orca_External\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>All S<span style=\"font-size:x-small\">HARC<\/span> interfaces can deliver gradients for (multiple) ground and excited states in a uniform manner.<br \/>\nThis allows in principle to perform optimizations of excited-state minima, conical intersections, or crossing points.<br \/>\nIn order to employ a high-quality geometry optimizer for this task, the S<span style=\"font-size:x-small\">HARC<\/span> suite is interfaced to the external optimizer feature of O<span style=\"font-size:x-small\">RCA<\/span>.<br \/>\nThis is accomplished by providing the scripts <b><tt>orca_External<\/tt><\/b> (for O<span style=\"font-size:x-small\">RCA<\/span>4) and <b><tt>otool_external<\/tt><\/b> (for O<span style=\"font-size:x-small\">RCA<\/span>5\/6), which is called by O<span style=\"font-size:x-small\">RCA<\/span>, runs any of the S<span style=\"font-size:x-small\">HARC<\/span> interfaces, constructs the appropriate gradient, and returns that to <span class=\"roman\">Orca<\/span>.<br \/>\nFor the methodology used to construct the gradients, see section <a href=\"#met:orcaopt\">8.20<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to easily prepare the input files for such an optimization, the script <b><tt>setup_orca_opt.py<\/tt><\/b> can be used.<br \/>\nIt takes a geometry file, interface input files, and the path to O<span style=\"font-size:x-small\">RCA<\/span>, and creates a directory containing all relevant input files.<br \/>\nIn the following, <b><tt>setup_orca_opt.py<\/tt><\/b> is described first, because it is the script which the user directly employs.<br \/>\nAfterwards, <b><tt>orca_External<\/tt><\/b> and <b><tt>otool_external<\/tt><\/b> are specified.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.35.1\"><\/a><\/p>\n<h3>\n7.35.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>setup_orca_opt.py<\/tt><\/b> is an interactive script, which is started with:<\/p>\n<pre>\nuser@host> $SHARC\/setup_orca_opt.py\n<\/pre>\n<p>Note that before executing the script you should prepare a template for the interface you want to use (as, e.g., in <b><tt>setup_init.py<\/tt><\/b> or <b><tt>setup_traj.py<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.35.2\"><\/a><\/p>\n<h3>\n7.35.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In the input section, the script asks for: (i) the path to O<span style=\"font-size:x-small\">RCA<\/span>, (ii) the input geometries, (iii) the optimization settings, (iv) the interface settings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Path to O<span style=\"font-size:x-small\">RCA<\/span>  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user is prompted to provide the path to the O<span style=\"font-size:x-small\">RCA<\/span> directory. Note that the script will not expand the user (<b><tt> <\/tt><\/b>) and shell variables (since possibly the calculations are running on a different machine than the one used for setup). <b><tt> <\/tt><\/b> and shell variables will only be expanded during the actual calculation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The script works with O<span style=\"font-size:x-small\">RCA<\/span> 4, 5, and 6.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Interface  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this point, choose any of the displayed interfaces to carry out the ab initio calculations.<br \/>\nEnter the corresponding number. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you selected <b><tt>SHARC_LEGACY.py<\/tt><\/b>, then you have to subsequently select the legacy interface that you intend to use.<br \/>\nIf you selected a hybrid interface, then you will subsequently be queried with the path to the corresponding template file, so that the hybrid interface can figure out the child interface it should use.<br \/>\nThis might continue recursively until all interfaces in the interface call tree are known.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Input geometry  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user is prompted for a geometry file in XYZ format, containing one or more geometries (with consistent number of atoms).<br \/>\nFor each geometry in this file, a directory with all input files is created, in order to carry out multiple optimizations (e.g., with output from <b><tt>crossing.py<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of states  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user can specify the number of excited states to be calculated. Note that the ground state has to be counted as well, e.g., if 4 singlet states are specified, the calculation will involve the S<sub>0<\/sub>, S<sub>1<\/sub>, S<sub>2<\/sub> and S<sub>3<\/sub>. Also states of higher multiplicity can be given, e.g. triplet or quintet states. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Charge  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>As in other setup scripts, you need to provide the charge for each involved multiplicity.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>States to optimize  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Two different optimization tasks can be carried out: optimization of a minimum (ground or excited state) or optimization of a crossing point (either a conical intersection between states of the same multiplicity or a minimum-energy crossing points between states of different multiplicities; this is detected automatically).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For minima, the state to optimize needs to be specified.<br \/>\nFor crossing points, the two involved states need to be specified.<br \/>\nIn all cases, the specified states need to be included in the number of states given before.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>CI optimization parameters  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you are optimizing a conical intersection (states of same multiplicity) with an interface which cannot provide nonadiabatic coupling vectors (e.g., <b><tt>SHARC_TURBOMOLE.py<\/tt><\/b>, <b><tt>SHARC_ADF.py<\/tt><\/b>, or <b><tt>SHARC_GAUSSIAN.py<\/tt><\/b>), then the optimization will employ the the penalty function method of Levine, Coe, and Martínez <a href=\"#Levine2008JPCB\" class=\"tth_citeref\">[69<\/a>].<br \/>\nIn this method, a penalty function is optimized, which depends on the energies of the two states and on two parameters, σ and α (see section <a href=\"#met:orcaopt\">8.20<\/a> for their mathematical meaning).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Practically, the parameters affect how close the minimum of the penalty function is to the true minimum on the crossing seam and how hard the optimization will be to converge.<br \/>\nGenerally, a large σ will allow going closer to the true conical intersection, but will make the penalty function more stiff (steeper harmonic) and thus harder to optimize.<br \/>\nA small α will also allow going closer to the true conical intersection, but will make the penalty function less harmonic; at α = 0, the penalty function will have a cusp at the minimum, making it unoptimizable because the gradient never becomes zero.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The default values, 3.5 and 0.02, are the ones suggested in <a href=\"#Levine2008JPCB\" class=\"tth_citeref\">[69<\/a>].<br \/>\nThey can be regarded as relatively soft, i.e., they enable a very smooth convergence but might lead to unacceptably large energy gaps at convergence (i.e., the minimum of the penalty function is too far from the true minimum of the crossing seam).<br \/>\nIn this case, it is advisable to restart the optimization from the last point with increased σ (e.g., by a factor of 4), and simultaneously reducing the maximum step (see next point).<br \/>\nThe α is best left at the suggested value of 0.02 to avoid the cusp problem.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Maximum allowed displacement  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within O<span style=\"font-size:x-small\">RCA<\/span>, it is possible to restrict the maximum step (the trust radius) of the optimizer.<br \/>\nA larger maximum step might decrease the number of iterations necessary, but might also lead to instabilities in the optimization (if the potential energy surface is very steep or anharmonic).<br \/>\nHence, it can be advisable to reduce the maximum allowed step (from the default of 0.3 a.u.), especially if the starting geometry is already very good (e.g., after restart with increase of σ) or if the potential is known to be stiff (strong bond, large σ, small α, …).<br \/>\nNote that the maximum step can be restricted even the penalty function method is not used and σ and α are not relevant.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Interface-specific input  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This input section is basically the same as for other setup scripts.<br \/>\nNote that for hybrid interfaces, all child interfaces will also ask for relevant input.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Run script setup  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user needs to provide the path to the directory where the optimizations should be setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.35.3\"><\/a><\/p>\n<h3>\n7.35.3  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Inside the specified directory, <b><tt>setup_orca_opt.py<\/tt><\/b> creates one subdirectory for each geometry in the input geometry file.<br \/>\nEach subdirectory is prepared with the corresponding initial geometry file (<b><tt>geom.xyz<\/tt><\/b>), the O<span style=\"font-size:x-small\">RCA<\/span> input file (<b><tt>orca.inp<\/tt><\/b>), the appropriate interface-specific files, and a shell script for execution (<b><tt>run_EXTORCA.sh<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to run one of the optimizations, execute the shell script or send it to a batch queuing system.<br \/>\nNote that $SHARC needs to be added to the $PATH so that O<span style=\"font-size:x-small\">RCA<\/span> can find <b><tt>orca_External<\/tt><\/b>.<br \/>\nFor O<span style=\"font-size:x-small\">RCA<\/span>6, the <b><tt>$EXTOPTEXE<\/tt><\/b> variable must be set.<br \/>\n(Both of these steps are automatically done inside <b><tt>run_EXTORCA.sh<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When the shell script is started, O<span style=\"font-size:x-small\">RCA<\/span> will write a couple of output files, where the two most relevant are <b><tt>orca.trj<\/tt><\/b> and <b><tt>orca.log<\/tt><\/b>.<br \/>\nThe former is an XYZ file with all geometries from the optimization steps.<br \/>\nThe latter (the O<span style=\"font-size:x-small\">RCA<\/span> standard output) contains all details of the optimization (convergence, step size, etc) as well as a summary of what <b><tt>orca_External<\/tt><\/b> did (after the line <b><tt>EXTERNAL SHARC JOB<\/tt><\/b>).<br \/>\nThis summary contains all relevant energies and shows how the gradient is constructed.<br \/>\nNote that in each iteration, a line starting with <b><tt> <\/tt><\/b> is written, which contains the energies of the optimized state(s). This line can easily be extracted with <b><tt>grep<\/tt><\/b> to follow the optimization of a crossing point.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.35.4\"><\/a><\/p>\n<h3>\n7.35.4  Description of <b><tt>orca_External<\/tt><\/b> and <b><tt>otool_external<\/tt><\/b><\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>orca_External<\/tt><\/b> and <b><tt>otool_external<\/tt><\/b> provide a connection between the external optimizer of O<span style=\"font-size:x-small\">RCA<\/span> and any of the S<span style=\"font-size:x-small\">HARC<\/span> interfaces.<br \/>\nIn figure <a href=\"#fig:interface_orcaExt\">7.5<\/a>, the file communication between O<span style=\"font-size:x-small\">RCA<\/span>, <b><tt>orca_External<\/tt><\/b>, and the interfaces is presented.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg7.5\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/general_orcaExternal.png\"> <\/p>\n<div style=\"text-align:center\">Figure 7.5: Communication between O<span style=\"font-size:x-small\">RCA<\/span>, <b><tt>orca_External<\/tt><\/b>, the interfaces, and the quantum chemistry codes. The scheme works nearly identically for <b><tt>otool_external<\/tt><\/b>.<\/div>\n<p> <a id=\"fig:interface_orcaExt\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>As can be seen, <b><tt>orca_External<\/tt><\/b> writes <b><tt>QM.in<\/tt><\/b> and <b><tt>QM.out<\/tt><\/b> files, in the same way that <b><tt>sharc.x<\/tt><\/b> is doing.<br \/>\nAll information to write the <b><tt>QM.in<\/tt><\/b> file comes from the O<span style=\"font-size:x-small\">RCA<\/span> communication file <b><tt>orca.extcomp.inp<\/tt><\/b> (geometry) and the O<span style=\"font-size:x-small\">RCA<\/span> input file (number of states, interface, states to optimize).<br \/>\nTo provide the latter information, <b><tt>orca_External<\/tt><\/b> reads specially marked comments from the O<span style=\"font-size:x-small\">RCA<\/span> input file which are ignored by O<span style=\"font-size:x-small\">RCA<\/span>.<br \/>\nThese comments start with <b><tt>#SHARC:<\/tt><\/b>, followed by a keyword (<b><tt>states<\/tt><\/b>, <b><tt>interface<\/tt><\/b>, <b><tt>opt<\/tt><\/b>, or <b><tt>param<\/tt><\/b>) and the keyword arguments.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When using <b><tt>otool_external<\/tt><\/b>, the settings are not read from <b><tt>orca.inp<\/tt><\/b>, because <b><tt>otool_external<\/tt><\/b> cannot work out the path to <b><tt>orca.inp<\/tt><\/b> in a robust way.<br \/>\nInstead, the settings are read from a separate file <b><tt>otool_external.inp<\/tt><\/b> that is created by <b><tt>setup_orca_opt.py<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.36\"><\/a><\/p>\n<h2>\n7.36  Single Point Calculations: <b><tt>setup_single_point.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:setup_single_point.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>It is possible to run single point calculations through the S<span style=\"font-size:x-small\">HARC<\/span> interfaces.<br \/>\nThis is useful, e.g., to do a computation in exactly the same way as during the dynamics simulations.<br \/>\nSingle point calculations using the interfaces can also be easily automatized.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.36.1\"><\/a><\/p>\n<h3>\n7.36.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>setup_single_point.py<\/tt><\/b> is an interactive script, which is started with:<\/p>\n<pre>\nuser@host> $SHARC\/setup_single_point.py\n<\/pre>\n<p>Note that before executing the script you should prepare a template for the interface you want to use (as, e.g., in <b><tt>setup_init.py<\/tt><\/b> or <b><tt>setup_traj.py<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.36.2\"><\/a><\/p>\n<h3>\n7.36.2  Input<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In the input section, the script asks for: (i) the input geometries, (ii) the number of states, and (iii) the interface settings.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Interface  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this point, choose any of the displayed interfaces to carry out the ab initio calculations.<br \/>\nEnter the corresponding number. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>If you selected <b><tt>SHARC_LEGACY.py<\/tt><\/b>, then you have to subsequently select the legacy interface that you intend to use.<br \/>\nIf you selected a hybrid interface, then you will subsequently be queried with the path to the corresponding template file, so that the hybrid interface can figure out the child interface it should use.<br \/>\nThis might continue recursively until all interfaces in the interface call tree are known.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Input geometry  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user is prompted for a geometry file in XYZ format, containing one or more geometries (with consistent number of atoms).<br \/>\nFor each geometry in this file, a directory with all input files is created, in order to carry out multiple optimizations (e.g., with output from <b><tt>crossing.py<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Number of states  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user can specify the number of excited states to be calculated. Note that the ground state has to be counted as well, e.g., if 4 singlet states are specified, the calculation will involve the S<sub>0<\/sub>, S<sub>1<\/sub>, S<sub>2<\/sub> and S<sub>3<\/sub>. Also states of higher multiplicity can be given, e.g. triplet or quintet states. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Charge  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>As in other setup scripts, you need to provide the charge for each involved multiplicity.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Interface-specific input  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>This input section is basically the same as for other setup scripts.<br \/>\nNote that for hybrid interfaces, all child interfaces will also ask for relevant input.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Run script setup  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Here the user needs to provide the path to the directory where the optimizations should be setup.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.36.3\"><\/a><\/p>\n<h3>\n7.36.3  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Inside the specified directory, <b><tt>setup_single_point.py<\/tt><\/b> creates one subdirectory for each geometry in the input geometry file.<br \/>\nEach subdirectory is prepared with the corresponding geometry file (<b><tt>QM.in<\/tt><\/b>), the appropriate interface-specific files (template, resources, QM\/MM), and a shell script for execution (<b><tt>run.sh<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to run one of the optimizations, execute the shell script or send it to a batch queuing system.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>When the shell script is started, the chosen S<span style=\"font-size:x-small\">HARC<\/span> interface is executed.<br \/>\nThe interface writes a file called <b><tt>QM.log<\/tt><\/b> which contains details of the computation and progress status.<br \/>\nThe final results of the computation are written to <b><tt>QM.out<\/tt><\/b>, which can be inspected manually.<br \/>\nAlternatively, some basic data (excitation energies, oscillator strengths) can be computed with <b><tt>QMout_print.py<\/tt><\/b> (section <a href=\"#sec:QMout_print.py\">7.37<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.37\"><\/a><\/p>\n<h2>\n7.37  Format Data from <b><tt>QM.out<\/tt><\/b> Files: <b><tt>QMout_print.py<\/tt><\/b><\/h2>\n<p><a id=\"sec:QMout_print.py\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>With the script <b><tt>QMout_print.py<\/tt><\/b> one can print a table with energies and oscillator strengths from a <b><tt>QM.out<\/tt><\/b> file, as it is produced by the interfaces.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.37.1\"><\/a><\/p>\n<h3>\n7.37.1  Usage<\/h3>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>QMout_print.py<\/tt><\/b> is a command line tool, and is executed like this:<\/p>\n<pre>\nuser@host> $SHARC\/QMout_print.py [options] QM.out\n<\/pre>\n<p>The options are summarized in Table <a href=\"#tab:QMoutprint_options\">7.21<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_tAb7.21\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\">\n<div style=\"text-align:center\">Table 7.21: Command-line options for <b><tt>QMout_print.py<\/tt><\/b>. <\/div>\n<p> <a id=\"tab:QMoutprint_options\"><br \/>\n<\/a><\/p>\n<table>\n<tr>\n<td align=\"left\"><span class=\"roman\">Option <\/td>\n<td align=\"left\">Description <\/td>\n<td align=\"left\">Default<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-h <\/td>\n<td align=\"left\">Display help message and quit. <\/td>\n<td align=\"left\">– <\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-i FILENAME <\/td>\n<td align=\"left\">Path to <b><tt>QM.in<\/tt><\/b> file (to read number of states) <\/td>\n<td align=\"left\">–<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-s INTEGERS <\/td>\n<td align=\"left\">List of numbers of states per multiplicity <\/td>\n<td align=\"left\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-n NATOM <\/td>\n<td align=\"left\">Number of atoms (usually no need to specify) <\/td>\n<td align=\"left\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-e FLOAT <\/td>\n<td align=\"left\">Absolute energy shift in Hartree <\/td>\n<td align=\"left\">0.0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-E <\/td>\n<td align=\"left\">Compute absolute energies (equivalent to <b><tt>-e 0.0<\/tt><\/b>) <\/td>\n<td align=\"left\">false<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-D <\/td>\n<td align=\"left\">Output diagonal states <\/td>\n<td align=\"left\">MCH states<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-S STATE <\/td>\n<td align=\"left\">Initial state index <\/td>\n<td align=\"left\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-t N <\/td>\n<td align=\"left\">Mode (0: energies and dipoles, 1: only energies) <\/td>\n<td align=\"left\">0<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-L <\/td>\n<td align=\"left\">Format output in a single line (useful for scans) <\/td>\n<td align=\"left\">false<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">-I <\/td>\n<td align=\"left\">Use Dyson norms instead of oscillator strengths <\/td>\n<td align=\"left\">false<\/td>\n<\/tr>\n<p><\/span><\/table>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc7.37.2\"><\/a><\/p>\n<h3>\n7.37.2  Output<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The script prints a table with state index, state label, energy, relative energy, oscillator strength, and spin expectation value to standard output.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_chAp8\"><\/a><\/p>\n<h1>\nChapter 8 <br \/>Methods and Algorithms<\/h1>\n<p><a id=\"chap:met\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this chapter different aspects of S<span style=\"font-size:x-small\">HARC<\/span> simulations are discussed in detail. The topics are ordered alphabetically.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.1\"><\/a><\/p>\n<h2>\n8.1  Absorption Spectrum<\/h2>\n<p><a id=\"met:spectrum\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using <b><tt>spectrum.py<\/tt><\/b>, an absorption spectrum can be calculated as the sum over the absorption spectra of each individual initial condition:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-31.png\">\n<\/td>\n<td width=\"1%\">(8.1)<\/td>\n<\/tr>\n<\/table>\n<p>where i runs over the initial conditions.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The spectrum of a single initial condition is the convolution of its line spectrum, defined through a set of tuples (E<sup>α<\/sup>,f<sub>osc<\/sub><sup>α<\/sup>) for each electronic state α, where E<sup>α<\/sup> is the excitation energy and f<sub>osc<\/sub><sup>α<\/sup>) is the oscillator strength.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The convolution of the line spectrum can be performed with <b><tt>spectrum.py<\/tt><\/b> using either Gaussian or Lorentzian functions. The contribution of a state α to the absorption spectrum σ<sup>α<\/sup>(E) is given by:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-32.png\">\n<\/td>\n<td width=\"1%\">(8.2)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-33.png\">\n<\/td>\n<td width=\"1%\">(8.3)<\/td>\n<\/tr>\n<\/table>\n<p>or<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-34.png\">\n<\/td>\n<td width=\"1%\">(8.4)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-35.png\">\n<\/td>\n<td width=\"1%\">(8.5)<\/td>\n<\/tr>\n<\/table>\n<p>or<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-36.png\">\n<\/td>\n<td width=\"1%\">(8.6)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-37.png\">\n<\/td>\n<td width=\"1%\">(8.7)<\/td>\n<\/tr>\n<\/table>\n<p>where FWHM is the full width at half maximum.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.2\"><\/a><\/p>\n<h2>\n8.2  Active and inactive states<\/h2>\n<p><a id=\"met:activestates\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p> S<span style=\"font-size:x-small\">HARC<\/span> allows to “freeze” certain states, which then do not participate in the dynamics. Only energies and dipole moments are calculated, but all couplings are disabled. In this way, these states are never visited (hence also no gradients and nonadiabatic couplings are calculated, making the inclusion of these states cheap). Example:<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <tt>nstates 2 0 2<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p> <tt>actstates 2 0 1<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the example given, state T<sub>2<\/sub> is frozen. The corresponding Hamiltonian looks like:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-38.png\">\n<\/td>\n<td width=\"1%\">(8.8)<\/td>\n<\/tr>\n<\/table>\n<p>where all matrix elements marked <\/p>\n<table>\n<tr>\n<td align=\"center\">red<\/td>\n<\/tr>\n<\/table>\n<p> are deleted, since T<sub>2<\/sub> is frozen. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The corresponding matrix elements are also deleted from the nonadiabatic coupling and overlap matrices. For propagation including laser fields, also the corresponding transition dipole moments are neglected, while the transition dipole moments still show up in the output (in order to characterize the frozen states).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Active and frozen states are defined with the <b><tt>states<\/tt><\/b> and <b><tt>actstates<\/tt><\/b> keywords in the input file. Note that only the highest states in each multiplicity can be frozen, i.e., it is not possible to freeze the T<sub>1<\/sub> while having T<sub>2<\/sub> active. However, it is possible to freeze all states of a certain multiplicity.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.3\"><\/a><\/p>\n<h2>\n8.3  Amdahl’s Law<\/h2>\n<p><a id=\"met:amdahl\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Some of the interfaces (<b><tt>SHARC_MOLCAS.py<\/tt><\/b>, <b><tt>SHARC_ADF.py<\/tt><\/b> <b><tt>SHARC_GAUSSIAN.py<\/tt><\/b>, <b><tt>SHARC_ORCA.py<\/tt><\/b>) use Amdahl’s law to predict the most efficient way to run multiple calculations in parallel, where each calculation itself is parallelized.<br \/>\nFor example, in <b><tt>SHARC_GAUSSIAN.py<\/tt><\/b> it might be necessary to compute the gradients of five states, using four CPU cores.<br \/>\nThe most efficient way to run these five jobs depends on how well the G<span style=\"font-size:x-small\">AUSSIAN<\/span> computation scales with the number of cores-for bad scaling, running four jobs on one core each followed by the fifth job might be best, whereas for good scaling, running each job on four cores subsequently is better because no core is idle at any time.<br \/>\nIn order to automatically distribute the jobs efficiently, the interfaces use Amdahl’s law, which can be stated as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-39.png\">\n<\/td>\n<td width=\"1%\">(8.9)<\/td>\n<\/tr>\n<\/table>\n<p>Here, T(1) is the run time of the job with one CPU core, and r is the fraction of T(1) which benefits from parallelization.<br \/>\nThe parameter r can be given to the interfaces; it is between 0 and 1, where 0 means that the calculation does not get faster at all with multiple cores, whereas 1 means that the run time scales linearly with the number of cores.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.4\"><\/a><\/p>\n<h2>\n8.4  Bootstrapping for Population Fits<\/h2>\n<p><a id=\"met:bootstrapping\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Bootstrapping, in the context of population fitting, is a statistical method to obtain the statistical distribution of the fitted parameters, which can be used to infer the error associated with the fitted parameter.<br \/>\nThe general idea of bootstrapping is to take the original sample (the set of trajectories in the ensemble), and generate new samples (resamples) by randomly drawing trajectories “with replacement” from the original ensemble.<br \/>\nThese resamples will differ form the original ensemble by containing some trajectories multiple times while other trajectories might be missing.<br \/>\nFor each of the resamples, the fitting parameter are obtained normally and saved for later analysis.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After many resamples, we obtain a list of many “alternative” parameters, which can be plotted in a histogram to see the statistical distribution of the fitting parameter.<br \/>\nThe number of resamples should generally be large (several hundred or thousand resamples), although with <b><tt>bootstrap.py<\/tt><\/b>, one can inspect the convergence of the fitting parameters\/errors to decide how many resamples are sufficient.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>From the computed list of parameters, error measures can be computed.<br \/>\nAssume that {x<sub>i<\/sub>} is the set of fitting parameters obtained.<br \/>\n<b><tt>bootstrap.py<\/tt><\/b> and <b><tt>make_fit.py<\/tt><\/b> compute the arithmetic mean and standard deviation like this:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-40.png\">\n<\/td>\n<td width=\"1%\">(8.10)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-41.png\">\n<\/td>\n<td width=\"1%\">(8.11)<\/td>\n<\/tr>\n<\/table>\n<p>Because the distribution of {x<sub>i<\/sub>} might be skewed (e.g., contains some very large values but few very small ones), the script also computes the geometric mean and standard deviation like this:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-42.png\">\n<\/td>\n<td width=\"1%\">(8.12)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-43.png\">\n<\/td>\n<td width=\"1%\">(8.13)<\/td>\n<\/tr>\n<\/table>\n<p>Note that the geometric standard deviation is a dimensionless factor (unlike the arithmetic standard deviation, which has the same dimension as the mean).<br \/>\nTherefore, within <b><tt>bootstrap.py<\/tt><\/b> and <b><tt>make_fit.py<\/tt><\/b> the geometric errors are always displayed with separate upper and lower bounds as <span class=\"overacc2\">―<\/span>x\\substack+<span class=\"overacc2\">―<\/span>x(σ(x)−1) −<span class=\"overacc2\">―<\/span>x(1\/σ(x)−1).<br \/>\nNote that <b><tt>bootstrap.py<\/tt><\/b> and <b><tt>make_fit.py<\/tt><\/b> will always report one times the standard deviation in the output.<br \/>\nIf larger confidence intervals are desired, simply multiply the arithmetic error as usual.<br \/>\nFor the geometric error, use for example <span class=\"overacc2\">―<\/span>x\\substack+<span class=\"overacc2\">―<\/span>x(σ(x)<sup>2<\/sup>−1) −<span class=\"overacc2\">―<\/span>x(1\/σ(x)<sup>2<\/sup>−1).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.5\"><\/a><\/p>\n<h2>\n8.5  Computing electronic populations<\/h2>\n<p><a id=\"met:pop\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The electronic populations from S<span style=\"font-size:x-small\">HARC<\/span> trajectories can be obtained in different ways.<br \/>\nThis is primarily due to the fact that in surface hopping one could either consider the active state or the electronic wave function coefficients.<br \/>\nThis issue is discussed in detail in <a href=\"#Landry2013JCP\" class=\"tth_citeref\">[73<\/a>], where it is shown that the optimal way to obtain the electronic populations is actually a combination of both kinds of information in a Wigner-like transformation.<br \/>\nHence, there are three options in S<span style=\"font-size:x-small\">HARC<\/span>: (i) based on classical active state, (ii) based on electronic wave function coefficients, and (iii) based on Wigner-transform.<br \/>\nAdditionally, the populations can be analyzed in different representations (diagonal, MCH, diabatic).<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Diagonal representation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The diagonal representation, there is no basis transformation involved, and hence the equations are very simple.<br \/>\nFor a single trajectory, the three possible populations can be obtained by:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-44.png\">\n<\/td>\n<td width=\"1%\">(8.14)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-45.png\">\n<\/td>\n<td width=\"1%\">(8.15)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-46.png\">\n<\/td>\n<td width=\"1%\">(8.16)<\/td>\n<\/tr>\n<\/table>\n<p>where α is the active diagonal state.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>MCH representation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>To obtain the MCH representation, one needs to transform the populations with the matrix <b>U<\/b>.<br \/>\nHence, one obtains:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-47.png\">\n<\/td>\n<td width=\"1%\">(8.17)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-48.png\">\n<\/td>\n<td width=\"1%\">(8.18)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-49.png\">\n<\/td>\n<td width=\"1%\">(8.19)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p><b>Diabatic representation  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>To obtain the diabatic representation, one needs to transform the populations with the appropriate transformation matrix <b>T<\/b>, which in S<span style=\"font-size:x-small\">HARC<\/span> is obtained as the matrix product of reference overlap matrix, time-ordered overlap matrices, and <b>U<\/b> for the current time step.<br \/>\nHence, one obtains:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-50.png\">\n<\/td>\n<td width=\"1%\">(8.20)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-51.png\">\n<\/td>\n<td width=\"1%\">(8.21)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-52.png\">\n<\/td>\n<td width=\"1%\">(8.22)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.6\"><\/a><\/p>\n<h2>\n8.6  Damping<\/h2>\n<p><a id=\"met:damping\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>If damping is activated in S<span style=\"font-size:x-small\">HARC<\/span> (keyword <b><tt>dampeddyn<\/tt><\/b>), in each time step the following modification to the velocity vector is made<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-53.png\">\n<\/td>\n<td width=\"1%\">(8.23)<\/td>\n<\/tr>\n<\/table>\n<p>where C is the damping factor given in the input. Hence, in each time step the kinetic energy is modified by<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-54.png\">\n<\/td>\n<td width=\"1%\">(8.24)<\/td>\n<\/tr>\n<\/table>\n<p>The damping factor C must be between 0 and 1.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.7\"><\/a><\/p>\n<h2>\n8.7  Decoherence<\/h2>\n<p><a id=\"met:decoherence\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In surface hopping, without any corrections the coherence between the states is usually too large <a href=\"#Granucci2007JCP\" class=\"tth_citeref\">[21<\/a>]. A trajectory in state β, but where state α has a large coefficient, will still travel according to the gradient of state β. However, the gradients of state α are almost certainly different to the ones of state β. As a consequence, too much population of state α is following the gradient of state β. Decoherence corrections damp in different ways the population of all states α ≠ β, so that only population of β follows the gradient of state β.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Currently, in S<span style=\"font-size:x-small\">HARC<\/span> there are two decoherence corrections implemented, “energy-based decoherence”, or EDC, as given in <a href=\"#Granucci2010JCP\" class=\"tth_citeref\">[94<\/a>] and “augmented fewest-switches surface hopping”, or AFSSH, as described in <a href=\"#Jain2016JCTC\" class=\"tth_citeref\">[39<\/a>].<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.7.1\"><\/a><\/p>\n<h3>\n8.7.1  Energy-based decoherence<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In this scheme, after the surface hopping procedure, when the system is in state β, the coefficients are updated by the following relation<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-55.png\">\n<\/td>\n<td width=\"1%\">(8.25)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-56.png\">\n<\/td>\n<td width=\"1%\">(8.26)<\/td>\n<\/tr>\n<\/table>\n<p>where C is the decoherence parameter. The decoherence correction can be activated with the keyword <b><tt>decoherence<\/tt><\/b> in the input file. The decoherence parameter C can be set with the keyword <b><tt>decoherence_param<\/tt><\/b> (the default is 0.1 hartree, as suggested in <a href=\"#Granucci2010JCP\" class=\"tth_citeref\">[94<\/a>]).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.7.2\"><\/a><\/p>\n<h3>\n8.7.2  Augmented FSSH decoherence<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Augmented FSSH by Subotnik and coworkers is described in <a href=\"#Jain2016JCTC\" class=\"tth_citeref\">[39<\/a>].<br \/>\nFor S<span style=\"font-size:x-small\">HARC<\/span>, the augmented FSSH algorithm was adjusted to the case of the diagonal representation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The basic idea is that besides the actual trajectory, the program maintains an auxiliary trajectory for each state.<br \/>\nThe auxiliary trajectories are propagated using the gradients of the associated (not active) state, and because the gradients are different, the auxiliary trajectories eventually diverge from each other and from the main trajectory.<br \/>\nFrom this diverging, one can compute decoherence rates which can be used to stochastically set the electronic coefficients of the diverging state to zero.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>First, we compute two matrices:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-57.png\">\n<\/td>\n<td width=\"1%\">(8.27)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-58.png\">\n<\/td>\n<td width=\"1%\">(8.28)<\/td>\n<\/tr>\n<\/table>\n<p>where <b>S<\/b> is the overlap matrix, as used in <a href=\"#met:propagate\">8.33<\/a>.<br \/>\nHence, <b>S<\/b><sup>diag<\/sup>(t,t+∆t) is the overlap matrix in the diagonal basis and <b>H<\/b><sup>olddiag<\/sup>(t+∆t) is the Hamiltonian at time t+∆t expressed in the diagonal basis of time step t.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>We then propagate the auxiliary trajectories for each state j, considering that the active state is α.<br \/>\nFor this, we need the gradient matrix <b>G<\/b><sup>diag<\/sup> from section <a href=\"#met:gradtra\">8.11<\/a>.<br \/>\nWe define:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-59.png\">\n<\/td>\n<td width=\"1%\">(8.29)<\/td>\n<\/tr>\n<\/table>\n<p>We do the X step of the velocity-Verlet algorithm:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-60.png\">\n<\/td>\n<td width=\"1%\">(8.30)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-61.png\">\n<\/td>\n<td width=\"1%\">(8.31)<\/td>\n<\/tr>\n<\/table>\n<p>where A goes over the atoms.<br \/>\nThen, we compute the new gradient:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-62.png\">\n<\/td>\n<td width=\"1%\">(8.32)<\/td>\n<\/tr>\n<\/table>\n<p>We then carry out the v step:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-63.png\">\n<\/td>\n<td width=\"1%\">(8.33)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-64.png\">\n<\/td>\n<td width=\"1%\">(8.34)<\/td>\n<\/tr>\n<\/table>\n<p>We then perform a diabatization of the auxiliary trajectories (e.g., for a trivially avoided crossing, the moments between the crossing states are interchanged):<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-65.png\">\n<\/td>\n<td width=\"1%\">(8.35)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-66.png\">\n<\/td>\n<td width=\"1%\">(8.36)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-67.png\">\n<\/td>\n<td width=\"1%\">(8.37)<\/td>\n<\/tr>\n<\/table>\n<p>to transform the data back into the adiabatic basis at time t+∆t.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Finally, we carry out the decoherence correction procedure for each auxiliary trajectory.<br \/>\nWe compute the displacement from the auxiliary trajectory of the active state:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-68.png\">\n<\/td>\n<td width=\"1%\">(8.38)<\/td>\n<\/tr>\n<\/table>\n<p>We compute two rate constants:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-69.png\">\n<\/td>\n<td width=\"1%\">(8.39)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-70.png\">\n<\/td>\n<td width=\"1%\">(8.40)<\/td>\n<\/tr>\n<\/table>\n<p>or if no nonadiabatic coupling vectors are available:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-71.png\">\n<\/td>\n<td width=\"1%\">(8.41)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>We draw a random number (identical for all states) r between 0 and 1.<br \/>\nIf r < ∆t(r<sup>j<\/sup><sub>1<\/sub>−r<sup>j<\/sup><sub>2<\/sub>), then we collapse state j, by setting its coefficient to zero and enlarging the coefficient of the active state such that the total norm is conserved; we also set the moments <b>R<\/b><sup>j<\/sup> and <b>v<\/b><sup>j<\/sup> to zero.<br \/>\nIf no collapse occurred, if r < −∆t r<sup>j<\/sup><sub>1<\/sub>, we set the moments <b>R<\/b><sup>j<\/sup> and <b>v<\/b><sup>j<\/sup> to zero.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>After a surface hop occurred, we reset all auxiliary trajectories.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.8\"><\/a><\/p>\n<h2>\n8.8  Essential Dynamics Analysis<\/h2>\n<p><a id=\"met:essdyn\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>As an alternative to normal mode analysis (see section <a href=\"#met:nma\">8.19<\/a>), essential dynamics analysis can be used to identify important modes in the dynamics.<br \/>\nThis procedure is a principal component analysis of the geometric displacements.<a href=\"#Amadei1993PSFB\" class=\"tth_citeref\">[66<\/a>,<a href=\"#Plasser2009\" class=\"tth_citeref\">[65<\/a>]<br \/>\nUnlike normal mode analysis, it does not depend on the availability of the normal mode vectors.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The covariance matrix is computed from the following equation (μ and ν are indices over the 3N<sub>atom<\/sub> degrees of freedom):<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-72.png\">\n<\/td>\n<td width=\"1%\">(8.42)<\/td>\n<\/tr>\n<\/table>\n<p>and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-73.png\">\n<\/td>\n<td width=\"1%\">(8.43)<\/td>\n<\/tr>\n<\/table>\n<p>as a matrix <b>C<\/b> with elements:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-74.png\">\n<\/td>\n<td width=\"1%\">(8.44)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>Diagonalization of the symmetric matrix <b>C<\/b> gives a set of eigenvalues and eigenvectors.<br \/>\nThe eigenvectors represent the essential dynamics modes, and the corresponding eigenvalues are the variances of the modes.<br \/>\nModes with large variances show strong motion in the dynamics, whereas small variances are found for modes which show weak motion.<br \/>\nBecause the modes are uncorrelated, the few modes with the largest variance describe most of the molecular motion, which shows that essential dynamics analysis can be used to for data reduction.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.9\"><\/a><\/p>\n<h2>\n8.9  Excitation Selection<\/h2>\n<p><a id=\"met:exc_selection\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p><b><tt>excite.py<\/tt><\/b> can select initial active states for the dynamics based on the excitation energies E<sub>k,α<\/sub> and the oscillator strengths f<sup>osc<\/sup><sub>k,α<\/sub> for each initial condition k and excited state α. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>First, for all excited states of all initial conditions, the maximum value p<sub>max<\/sub> of <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-75.png\"><a id=\"eq:exc_prob\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.45)<\/td>\n<\/tr>\n<\/table>\n<p>is found. Then for each excited state, a random number r<sub>k,α<\/sub> is picked from [0,1]. If<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-76.png\">\n<\/td>\n<td width=\"1%\">(8.46)<\/td>\n<\/tr>\n<\/table>\n<p>then the excited state is selected as a valid initial condition. This excited-state selection scheme is taken from <a href=\"#Barbatti2011\" id=\"CITEBarbatti2011\" class=\"tth_citation\">[106<\/a>].<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within <b><tt>excite.py<\/tt><\/b> it is possible to restrict the selection to a subset of all excited states (only certain adiabatic states\/within a given energy range). In this case, also p<sub>max<\/sub> is only determined based on this subset of excited states.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.9.1\"><\/a><\/p>\n<h3>\n8.9.1  Excitation Selection with Diabatization<\/h3>\n<p><a id=\"met:exc_diabatic\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The active states can be selected based on a diabatization.<br \/>\nThis necessitates the wave function overlaps between a reference geometry (<b><tt>ICOND_00000\/<\/tt><\/b>) and the current initial condition k.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The overlap matrix with elements<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-77.png\">\n<\/td>\n<td width=\"1%\">(8.47)<\/td>\n<\/tr>\n<\/table>\n<p>can be computed with <b><tt>wfoverlap.x<\/tt><\/b> (calculations can be setup with <b><tt>setup_init.py<\/tt><\/b>).<br \/>\nThis overlap matrix is rescaled during the excitation selection procedure such S<sup>0k<\/sup><sub>11<\/sub> is equal to one (by dividing all elements by |S<sup>0k<\/sup><sub>11<\/sub>|<sup>2<\/sup>).<br \/>\nThen, assume we want to start all trajectories in the state which corresponds to state x at the reference geometry.<br \/>\nThe excitation selection will select a state y as initial state if S<sup>0k<\/sup><sub>xy<\/sub> > 0.5.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.10\"><\/a><\/p>\n<h2>\n8.10  Global fits and kinetic models<\/h2>\n<p><a id=\"met:globalfit\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this section, we specify the basic assumptions of the chemical kinetic models used with the scripts <b><tt>make_fitscript.py<\/tt><\/b> and <b><tt>make_fit.py<\/tt><\/b> and the globals fits of these models to data.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.10.1\"><\/a><\/p>\n<h3>\n8.10.1  Reaction networks<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The kinetic models used by <b><tt>make_fitscript.py<\/tt><\/b> and <b><tt>make_fit.py<\/tt><\/b> are based on a chemical reaction network, where chemical <i>species<\/i> react via unimolecular <i>reactions<\/i>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The reaction networks allowed in the script are a simple directed graphs, where the species are the vertices and the reactions are the directed edges.<br \/>\nEach reaction is characterized by an associated rate constant and connects exactly one reactant species to exactly one product species.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to obtain rate laws which can be integrated easily, there are a number of restrictions imposed on the network graphs.<br \/>\nSome restrictions and possible features of the graphs are depicted exemplarily in Figure <a href=\"#fig:graph_restrictions\">8.1<\/a>.<br \/>\nFirst, each species and each reaction rate needs to have a unique label.<br \/>\nThere cannot be two species with the same label, but there can be two reactions with the same reaction rate constant.<br \/>\nSecond, the graph must be a simple directed graph, hence there cannot be any (self-) loops or more than one reaction with the same initial and the same final species.<br \/>\nAll restrictions marked as “Not allowed” in the Figure are enforced in the input dialogue of <b><tt>make_fitscript.py<\/tt><\/b><br \/>\nHowever, back reactions are allowed (as a back reaction has a different initial and a different final species as the corresponding reaction).<br \/>\nExcept from these restrictions, the graph may contain combinations of sequential and parallel reactions.<br \/>\nThe graph may also be disjoint, i.e., it can be the union of several independent sub-networks.<br \/>\nDisjoint graphs with repeated reaction labels can be useful to fit population data from ensembles with identical settings but different initial conditions (in this case, merge the population files with <b><tt>paste<\/tt><\/b> before starting the fit.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are two kinds of cycles possible, called here <i>parallel pathways<\/i> and <i>closed walks<\/i>.<br \/>\nParallel pathways are independent sequences of reactions with the same initial and final species (e.g., A→ C and A→ B→ C).<br \/>\nA closed walk is a sequence of reactions where the initial species is equal to the final species.<br \/>\nThese cycles can sometimes lead to problems.<br \/>\nIf you use <b><tt>make_fitscript.py<\/tt><\/b>, then it is necessary that the system of differential equations of the rate laws can be integrated in closed form by M<span style=\"font-size:x-small\">AXIMA<\/span>.<br \/>\nSince <b><tt>make_fit.py<\/tt><\/b> solves the differential equation system numerically, it is not necessary that the solution can be given in closed form.<br \/>\nHowever, cycles can also lead to problems in the fitting procedure (rate constants in parallel pathways can be strongly correlated and cause large errors and bad convergence in fitting).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg8.1\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/allowed_notallowed.png\"> <\/p>\n<div style=\"text-align:center\">Figure 8.1: Forbidden and allowed features of the reaction network graphs.<\/div>\n<p> <a id=\"fig:graph_restrictions\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p>An example reaction network graph is shown in Figure <a href=\"#fig:example_graph\">8.2<\/a>.<br \/>\nIn this graph, there are 5 species (S<sub>2<\/sub>, S<sub>1<\/sub>, S<sub>0<\/sub>, T<sub>2<\/sub>, and T<sub>1<\/sub>) and 6 reactions, each with a rate constant (k<sub>S<\/sub>, k<sub>Rlx<\/sub>, k<sub>22<\/sub>, k<sub>11<\/sub>, k<sub>21<\/sub>, k<sub>12<\/sub>).<br \/>\nThis graph shows some features which are allowed in the reaction networks for <b><tt>make_fitscript.py<\/tt><\/b>: sequential reactions, parallel reactions, back reactions, and converging reaction pathways.<br \/>\nNote that this reaction network is likely to cause problems in the fitting step (large errors).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg8.2\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/example_graph.png\"> <\/p>\n<div style=\"text-align:center\">Figure 8.2: Example reaction network graph. For explanation see text.<\/div>\n<p> <a id=\"fig:example_graph\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.10.2\"><\/a><\/p>\n<h3>\n8.10.2  Kinetic models<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Based on the reaction network graph, a system of differential equations describing the rate laws of all species can be setup.<br \/>\nThe system of equations (equivalently, the matrix differential equation) can be written as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-78.png\"><a id=\"eq:rate_law\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.48)<\/td>\n<\/tr>\n<\/table>\n<p>where <b>s<\/b> is the vector of the time-dependent populations of each species and <b>A<\/b> is the matrix containing the rate constants.<br \/>\nIn order to construct <b>A<\/b>, start with <b>A<\/b>=0 and, for each reaction from species i to species j with rate k, substract k from A<sub>ii<\/sub> and add k to A<sub>ji<\/sub>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to integrate this system of equations, in practice one also needs to define initial conditions.<br \/>\nIn the present context, the initial conditions are fully specified by <b>s<\/b>(t=0)=<b>s<\/b><sub>0<\/sub>, where <b>s<\/b><sub>0<\/sub> are constant expressions defined by the user.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Solving (<a href=\"#eq:rate_law\">8.48<\/a>) yields (in not too complicated cases) the closed-form expressions for the functions <b>s<\/b>(t), which contain as parameters all rate constants k and all initial values <b>s<\/b><sub>0<\/sub>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.10.3\"><\/a><\/p>\n<h3>\n8.10.3  Global fit<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Suppose there is a data set <b>p<\/b>(t)=(p<sub>1<\/sub>(t),p<sub>2<\/sub>(t),…) of time-dependent populations of several states k=1,2,… and which is given at several points of time {t<sub>i<\/sub>: 0 < t<sub>i<\/sub> < t<sub><span class=\"roman\">max<\/span><\/sub>}.<br \/>\nWe can <i>fit<\/i> to one data set p<sub>k<\/sub>(t) a function s<sub>l<\/sub>(t) from <b>s<\/b>(t) by optimizing the parameters (mainly the rate constants) such that ∑<sub>i<\/sub> |p<sub>k<\/sub>(t<sub>i<\/sub>)−s<sub>l<\/sub>(t<sub>i<\/sub>)|<sup>2<\/sup> becomes minimal.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to perform global fit including several species l and several states k, we construct piecewise global functions from <b>p<\/b>(t) and <b>s<\/b>(t) and then optimize the parameters accordingly.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.11\"><\/a><\/p>\n<h2>\n8.11  Gradient transformation<\/h2>\n<p><a id=\"met:gradtra\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.11.1\"><\/a><\/p>\n<h3>\n8.11.1  Nuclear gradient tensor transformation scheme<\/h3>\n<p>Since the actual dynamics is performed on the PESs of the diagonal states, also the gradients have to be transformed to the diagonal representation. To this end, first a generalized gradient matrix <b>G<\/b><sup>MCH<\/sup> is constructed from the gradients <b>g<\/b><sup>MCH<\/sup><sub>α<\/sub>=−∇<sub>R<\/sub>H<sub>αα<\/sub><sup>MCH<\/sup><br \/>\nand the nonadiabatic coupling vectors<br \/>\n<b>K<\/b><sub>βα<\/sub><sup>MCH<\/sup>:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-79.png\">\n<\/td>\n<td width=\"1%\">(8.49)<\/td>\n<\/tr>\n<\/table>\n<p>Note that all quantities in the matrix are in the MCH representation, the superscripts were omitted for brevity.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The matrix <b>G<\/b><sup>MCH<\/sup> is subsequently transformed into the diagonal representation, using the transformation matrix <b>U<\/b>:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-80.png\">\n<\/td>\n<td width=\"1%\">(8.50)<\/td>\n<\/tr>\n<\/table>\n<p>The diagonal elements of <b>G<\/b><sup>diag<\/sup> now contain the gradients of the diagonal states, while the off-diagonal elements contain the scaled nonadiabatic couplings −(H<sup>diag<\/sup><sub>ββ<\/sub>−H<sup>diag<\/sup><sub>αα<\/sub>)<b>K<\/b><sub>βα<\/sub><sup>diag<\/sup>. The gradients are needed in the Velocity Verlet algorithm in order to propagate the nuclear coordinates. The nonadiabatic couplings are necessary if the velocity vector is to be rescaled along the nonadiabatic coupling vector.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Since the matrix <b>G<\/b><sup>MCH<\/sup> contains elements which are itself vectors with 3N components, the transformation is done component-wise (e.g. first a matrix G<sub>x,atom 1<\/sub> is constructed from the x components of all gradients (and nonadiabatic couplings) for atom 1, this matrix is transformed and written to the x, atom 1 component of <b>G<\/b><sup>diag<\/sup>, then this is repeated for all components).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Since the calculation of the nonadiabatic couplings <b>K<\/b><sup>MCH<\/sup><sub>βα<\/sub> might add considerable computational cost, there is the input keyword <b><tt>nogradcorrect<\/tt><\/b> which tells S<span style=\"font-size:x-small\">HARC<\/span> to neglect the <b>K<\/b><sup>MCH<\/sup><sub>βα<\/sub> in the gradient transformation. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>From S<span style=\"font-size:x-small\">HARC<\/span>3.0 onwards, this scheme is called nuclear gradient tensor scheme, or NGT scheme. The NGT scheme can be turned on by using keyword <b><tt>gradcorrect<\/tt><\/b> alone, or followed by options, i.e. <b><tt>gradcorrect ngt<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.11.2\"><\/a><\/p>\n<h3>\n8.11.2  Time derivative matrix transformation scheme<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, one can obtain the energy conserving force in diagonal representation by using the time derivative matrix scheme, or TDM scheme. In TDM scheme, no computation of nonadiabatic coupling vectors are required, and therefore it is more efficient. And TDM is especially recommended for overlap-based algorithms and curvature-driven algorithms because one of the advantages of these algorithms is that they do not require computating of nonadiabatic coupling vectors. See section <a href=\"#met:curvature\">8.34<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>One can turn on TDM scheme by using keyword <b><tt>gradcorrect tdm<\/tt><\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p> The TDM scheme utilizes the time derivative matrix <i>K<\/i><sup><span class=\"roman\">GB<\/span><\/sup>, with matrix elements given by<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-81.png\">\n<\/td>\n<td width=\"1%\">(8.51)<\/td>\n<\/tr>\n<\/table>\n<p>where GB denotes that this is a general basis which can be either diagonal or MCH representation, superscript SOC denotes the spin-orbit coupling terms, and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-82.png\">\n<\/td>\n<td width=\"1%\">(8.52)<\/td>\n<\/tr>\n<\/table>\n<p>where superscript SF denotes spin-free.<br \/>\nOne can show that, <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-83.png\">\n<\/td>\n<td width=\"1%\">(8.53)<\/td>\n<\/tr>\n<\/table>\n<p>and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-84.png\">\n<\/td>\n<td width=\"1%\">(8.54)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>Similar as in the NGT scheme, we now neglect [d\/dt]H<sup><span class=\"roman\">SOC<\/span><\/sup>. This gives the TDM scheme<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-85.png\"><a id=\"eq:tdm\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.55)<\/td>\n<\/tr>\n<\/table>\n<p>Therefore, <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-86.png\">\n<\/td>\n<td width=\"1%\">(8.56)<\/td>\n<\/tr>\n<\/table>\n<p>and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-87.png\">\n<\/td>\n<td width=\"1%\">(8.57)<\/td>\n<\/tr>\n<\/table>\n<p>This is very useful, because it allows us to compute [(dH<sup><span class=\"roman\">elec<\/span><span class=\"roman\">[<\/span><span class=\"roman\">diag<\/span><span class=\"roman\">]<\/span><\/sup><sub>αα<\/sub>)\/dt] without computing nonadiabatic coupling vectors. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> One can show that the only requirement a diagonal gradient needs to be fulfilled to conserve energy is, <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-88.png\">\n<\/td>\n<td width=\"1%\">(8.58)<\/td>\n<\/tr>\n<\/table>\n<p>where <span class=\"overacc1\">· <\/span><span class=\"roman\">P<\/span><sup><span class=\"roman\">diag<\/span><\/sup><sub><span class=\"roman\">TSH<\/span><\/sub> is the diagonal force. Therefore, by knowing [(dH<sup><span class=\"roman\">elec<\/span><span class=\"roman\">[<\/span><span class=\"roman\">diag<\/span><span class=\"roman\">]<\/span><\/sup><sub>αα<\/sub>)\/dt] one can obtain an alternative energy conserving force as<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-89.png\">\n<\/td>\n<td width=\"1%\">(8.59)<\/td>\n<\/tr>\n<\/table>\n<p>The above diagonal force conserves energy for any real and nonzero vector <span class=\"roman\">F<\/span><sub>αα<\/sub> that is not normal to <span class=\"overacc1\">· <\/span><span class=\"roman\">R<\/span>. In S<span style=\"font-size:x-small\">HARC<\/span>3.0, we use the following physically motivated choice of <span class=\"roman\">F<\/span><sub>αα<\/sub><\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-90.png\">\n<\/td>\n<td width=\"1%\">(8.60)<\/td>\n<\/tr>\n<\/table>\n<p>where state <i>γ<\/i> is a state in the MCH basis that corresponds to state <i>α<\/i> in the diagonal basis.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>3.0, the default is to use different approaches to compute [(dH<sup><span class=\"roman\">elec<\/span><span class=\"roman\">[<\/span><span class=\"roman\">diag<\/span><span class=\"roman\">]<\/span><\/sup><sub>αα<\/sub>)\/dt] for different algorithms. For overlap-based algorithms,<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-91.png\">\n<\/td>\n<td width=\"1%\">(8.61)<\/td>\n<\/tr>\n<\/table>\n<p>This defines <span class=\"roman\">k<\/span><sup><span class=\"roman\">MCH<\/span><\/sup> for overlap-based algorithm, and one transform <span class=\"roman\">k<\/span><sup><span class=\"roman\">MCH<\/span><\/sup> to <i>K<\/i><sup><span class=\"roman\">diag<\/span><\/sup> with equation  (<a href=\"#eq:tdm\">8.55<\/a>). This is called gradient approach, and can be turned on by using keyword <b><tt>tdm_method gradient<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The default for curvature-driven algorithms is that we employ finite differences to compute both [(dH<sup><span class=\"roman\">SF<\/span><span class=\"roman\">[<\/span><span class=\"roman\">MCH<\/span><span class=\"roman\">]<\/span><\/sup><sub>αα<\/sub>)\/dt] and [(dH<sup><span class=\"roman\">elec<\/span><span class=\"roman\">[<\/span><span class=\"roman\">diag<\/span><span class=\"roman\">]<\/span><\/sup><sub>αα<\/sub>)\/dt]. For the first and second time steps, we use first-order backward finite differences<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-92.png\">\n<\/td>\n<td width=\"1%\">(8.62)<\/td>\n<\/tr>\n<\/table>\n<p>where superscript A can be SOC, SF, or elec (full Hamiltonian, includong both SF and SOC).<br \/>\nAnd for later steps, we use second-order backward finite differences<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-93.png\">\n<\/td>\n<td width=\"1%\">(8.63)<\/td>\n<\/tr>\n<\/table>\n<p>This is called the energy approach, and can be turned on by using keyword <b><tt>tdm_method energy<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.11.3\"><\/a><\/p>\n<h3>\n8.11.3  Dipole moment derivatives<\/h3>\n<p><a id=\"met:dipolegrad\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For strong laser fields, the derivative of the dipole moments might be a non-negligible contribution to the gradients. In this case, they should be included in the gradient transformation step:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-94.png\">\n<\/td>\n<td width=\"1%\">(8.64)<\/td>\n<\/tr>\n<\/table>\n<p>This can be activated with the keyword <b><tt>dipole_grad<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input file.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.12\"><\/a><\/p>\n<h2>\n8.12  Internal coordinates definitions<\/h2>\n<p><a id=\"met:geo\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this section, the internal coordinates available in <b><tt>geo.py<\/tt><\/b> are defined.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Bond length  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The bond length between two atoms a and b is:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-95.png\">\n<\/td>\n<td width=\"1%\">(8.65)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p><b>Bond angle  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The bond angle for atoms a, b and c is defined as the angle<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-96.png\"><a id=\"eq:angle\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.66)<\/td>\n<\/tr>\n<\/table>\n<p>where <b>v<\/b><sub>ba<\/sub> is the vector from atom b to atom a.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Dihedral  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The dihedral angle is defined via the vectors <b>w<\/b><sub>1<\/sub> and <b>w<\/b><sub>2<\/sub>:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-97.png\">\n<\/td>\n<td width=\"1%\">(8.67)<\/td>\n<\/tr>\n<\/table>\n<p>The dihedral is given as the angle between <b>w<\/b><sub>1<\/sub> and <b>w<\/b><sub>2<\/sub> according to equation (<a href=\"#eq:angle\">8.66<\/a>).<br \/>\nIn order to distinguish left- and right-handed rotation, also the vector <b>Q<\/b>=<b>w<\/b><sub>1<\/sub>×<b>w<\/b><sub>2<\/sub> is computed, and if the angle between <b>Q<\/b> and <b>v<\/b><sub>bc<\/sub> is larger than 90<sup>°<\/sup> then the value of the dihedral is multiplied by -1.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Pyramidalization angle  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The pyramidalization angle is defined via the vectors <b>v<\/b><sub>ba<\/sub> and <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-98.png\">\n<\/td>\n<td width=\"1%\">(8.68)<\/td>\n<\/tr>\n<\/table>\n<p>The pyramidalization angle is then given as 90<sup>°<\/sup> − θ(<b>v<\/b><sub>ba<\/sub>,<b>w<\/b><sub>1<\/sub>).<br \/>\nThis definition of the pyramidalization angle works best for nearly planar arrangements, like in amino groups.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>An alternative definition of the pyramidalization angle works better for strongly pyramidalized situations (e.g., <em>fac<\/em>-arranged atoms in a octahedral metal complex).<br \/>\nThis pyramidalization angle is defined as 180<sup>°<\/sup> minus the angle between <b>v<\/b><sub>ab<\/sub> and the average of <b>v<\/b><sub>bc<\/sub> and <b>v<\/b><sub>bd<\/sub>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Cremer-Pople parameters  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The definitions of the Cremer-Pople parameters for 5- and 6-membered rings is described in <a href=\"#Cremer1975JACS\" class=\"tth_citeref\">[62<\/a>].<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Boeyens classification  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>For 6-membered rings, the Boeyens classification scheme is described in <a href=\"#Boeyens1976JCMS\" class=\"tth_citeref\">[63<\/a>].<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Angle between two rings  <\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to compute angles between the mean planes of two rings, we compute the normal vector of the two rings as in <a href=\"#Cremer1975JACS\" class=\"tth_citeref\">[62<\/a>].<br \/>\nWe then compute the angle between the two normal vectors.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.13\"><\/a><\/p>\n<h2>\n8.13  Kinetic energy adjustments<\/h2>\n<p><a id=\"met:ekinadj\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>There are several options how to adjust the kinetic energy after a surface hop occurred. The simplest option is to not adjust the kinetic energy at all (input: <b><tt>ekincorrect none<\/tt><\/b>), but this obviously leads to violation of the conservation of total energy.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, the velocities of all atoms can be rescaled so that the new kinetic energy and the potential energy of the new state β again sum up to the total energy.<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-99.png\">\n<\/td>\n<td width=\"1%\">(8.69)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-100.png\">\n<\/td>\n<td width=\"1%\">(8.70)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-101.png\">\n<\/td>\n<td width=\"1%\">(8.71)<\/td>\n<\/tr>\n<\/table>\n<p>Within this methodology, when the energy of the old state α was lower than the energy of the new state β the kinetic energy is lowered. Since the kinetic energy must be positive, this implies that there might be states which cannot be reached (their potential energy is above the total energy). A hop to such a state is called “frustrated hop” and will be rejected by S<span style=\"font-size:x-small\">HARC<\/span>. Rescaling parallel to the nuclear velocity vector is requested with <b><tt>ekincorrect parallel_vel<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, according to Tully’s original formulation of the surface hopping method <a href=\"#Tully1990JCP\" class=\"tth_citeref\">[14<\/a>], after a hop from α to β only the component of the velocity along the direction of the nonadiabatic coupling vector <b>K<\/b><sub>βα<\/sub> should be rescaled. With<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-102.png\">\n<\/td>\n<td width=\"1%\">(8.72)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-103.png\">\n<\/td>\n<td width=\"1%\">(8.73)<\/td>\n<\/tr>\n<\/table>\n<p>the available energy can be calculated:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-104.png\">\n<\/td>\n<td width=\"1%\">(8.74)<\/td>\n<\/tr>\n<\/table>\n<p>If ∆ < 0, the hop is frustrated and will be rejected. Otherwise, the scaled velocities <b>v<\/b>′ can be calculated as<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-105.png\">\n<\/td>\n<td width=\"1%\">(8.75)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-106.png\">\n<\/td>\n<td width=\"1%\">(8.76)<\/td>\n<\/tr>\n<\/table>\n<p>This procedure can be requested with <b><tt>ekincorrect parallel_nac<\/tt><\/b>. Note that in this case S<span style=\"font-size:x-small\">HARC<\/span> will request the nonadiabatic coupling vectors, even if they are not used for the wave function propagation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.13.1\"><\/a><\/p>\n<h3>\n8.13.1  Reflection for frustrated hops<\/h3>\n<p><a id=\"met:refl_frust\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>As suggested by Tully <a href=\"#Tully1990JCP\" class=\"tth_citeref\">[14<\/a>], during a frustrated hop one might want to reflect the trajectory (i.e., invert some component of the velocity vector).<br \/>\nIn S<span style=\"font-size:x-small\">HARC<\/span>, there are three possible options to this, the first being no reflection (<b><tt>reflect_frustrated none<\/tt><\/b>).<br \/>\nAlternatively, one can invert the total velocity vector <b>v<\/b>:=−<b>v<\/b> (<b><tt>reflect_frustrated parallel_vel<\/tt><\/b>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>As this leads to a nearly complete time reversal and might be inappropriate, as a third option one can choose to only reflect the velocity component parallel to the nonadiabatic coupling vector between the active state and the state to which the frustrated hop was attempted.<br \/>\nThe condition for reflection in this case is based on three scalar products:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-107.png\">\n<\/td>\n<td width=\"1%\">(8.77)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-108.png\">\n<\/td>\n<td width=\"1%\">(8.78)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-109.png\">\n<\/td>\n<td width=\"1%\">(8.79)<\/td>\n<\/tr>\n<\/table>\n<p>Reflection is only carried out if k<sub>1<\/sub>k<sub>2<\/sub> < 0 and k<sub>2<\/sub>k<sub>3<\/sub> < 0.<br \/>\nIn order to reflect, we compute:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-110.png\">\n<\/td>\n<td width=\"1%\">(8.80)<\/td>\n<\/tr>\n<\/table>\n<p>where <b>t<\/b><sub>A<\/sub> is the component of <b>t<\/b><sub>αf<\/sub> corresponding to atom A.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.13.2\"><\/a><\/p>\n<h3>\n8.13.2  Choices of momentum adjustment direction<\/h3>\n<p><a id=\"met:choice_vector\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In addition to previously mentioned choices of vectors to adjustment momentum, namely, velocity vector, and nonadiabatic coupling vector, in S<span style=\"font-size:x-small\">HARC<\/span>3.0 we have several new choices of momentum adjustment vectors. A complete list includes: velocity vector,<br \/>\nprojected velocity vector (vibrational velocity vector),<br \/>\nnonadiabatic coupling vector,<br \/>\nprojected nonadiabatic coupling vector,<br \/>\ndifference gradient vector,<br \/>\neffective nonadiabatic coupling vector,<br \/>\nand projected effective nonadiabatic coupling vector. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that using the projected vectors is recommended choice because these vectors can conserve angular momentum and center of mass motion. Section <a href=\"#met:effectivenac\">8.31<\/a> introduces the effective nonadiabatic coupling vector, and Section <a href=\"#met:projector\">8.14<\/a> introduces the projection operator. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Section <a href=\"#met:curvature\">8.34<\/a> distinguishes different types of nonadiabatic dynamics algorithms based on the coupling types to be computed. Although using nonadiabatic coupling vector as momentum adjustment direction is most accurate, one of the advantages of not using nonadiabatic coupling vector as momentum adjustment direction is that one can utilize the advantages of overlap-based algorithms and curvature-driven algorithms that nonadiabatic coupling vector is not needed in propagating electronic and nuclear equations of motion.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.14\"><\/a><\/p>\n<h2>\n8.14  Projection operator<\/h2>\n<p><a id=\"met:projector\"><br \/>\n<\/a><br \/>\n The projection operator<sup> <\/sup>projects out the translational and rotational components of a vector, i.e., nonadiabatic coupling vector (NAC vector). The projected NAC, is expressed as <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-111.png\">\n<\/td>\n<td width=\"1%\">(8.81)<\/td>\n<\/tr>\n<\/table>\n<p>where <b>1<\/b> and <b>Q<\/b> are the identity operator and projection operator, respectively, and A and B are indices of electronic states. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The projection operator is a 3<i>N<\/i>×3<i>N<\/i> matrix with elements<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-112.png\">\n<\/td>\n<td width=\"1%\">(8.82)<\/td>\n<\/tr>\n<\/table>\n<p>where indices <i>i<\/i> and <i>i’<\/i> label the nuclei and vary from 1 to <i>N<\/i>, <i>α<\/i>, <i>β<\/i>, <i>γ<\/i>, <i>α<\/i>‘, <i>β<\/i>‘, and <i>γ<\/i>‘ take on the values <i>x, y<\/i>, and <i>z<\/i>.<br \/>\n<span class=\"overacc1\">~<\/span><span class=\"roman\">I<\/span><sup> −<b>1<\/b><\/sup> is the inverse of matrix <span class=\"overacc1\">~<\/span><span class=\"roman\">I<\/span>.<br \/>\nMatrix <span class=\"overacc1\">~<\/span><span class=\"roman\">I<\/span> is same as moment of inertia matrix with all masses set to 1, and \\varepsilonup is the completely antisymmetric third-order unit pseudotensor, whose elements are the Levi-Civita symbols.<br \/>\nThe first term of the projection operator projects onto the three directions corresponding to overall translation, and the second term projects onto the three directions corresponding to overall rotation. <\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.15\"><\/a><\/p>\n<h2>\n8.15  Fewest switches with time uncertainty<\/h2>\n<p><a id=\"met:fstu\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p> The fewest switches with time uncertainty (FSTU) propagation is identical to the FS algorithm except when there is a frustrated hop. The FSTU looks for nonlocal hops to reduce the number of frustrated hops. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> At time <i>t<\/i>, the FSTU algorithm computes the potential energy differences between the active state <i>K<\/i> and the rest of the states,<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-113.png\">\n<\/td>\n<td width=\"1%\">(8.83)<\/td>\n<\/tr>\n<\/table>\n<p>where V<sub>α<\/sub>(t) is the adiabatic potential energy of state α at time <i>t<\/i>. In S<span style=\"font-size:x-small\">HARC<\/span>3.0, the velocity is rescaled after a K→ α hop according to<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-114.png\">\n<\/td>\n<td width=\"1%\">(8.84)<\/td>\n<\/tr>\n<\/table>\n<p>where <span class=\"roman\">v<\/span><sub><span class=\"roman\">A<\/span><\/sub>, <span class=\"roman\">h<\/span><sub>Kα<span class=\"roman\">,<\/span><span class=\"roman\">A<\/span><\/sub>, and M<sub><span class=\"roman\">A<\/span><\/sub> are respectively the velocity vector, momentum adjustment vector, and the atomic mass of atom A, and <i>f<\/i> is a unitless factor to be computed.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The factor <i>f<\/i> is computed by requiring energy conservation after a hop<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-115.png\">\n<\/td>\n<td width=\"1%\">(8.85)<\/td>\n<\/tr>\n<\/table>\n<p>Therefore,<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-116.png\">\n<\/td>\n<td width=\"1%\">(8.86)<\/td>\n<\/tr>\n<\/table>\n<p>where<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-117.png\">\n<\/td>\n<td width=\"1%\">(8.87)<\/td>\n<\/tr>\n<\/table>\n<p>and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-118.png\">\n<\/td>\n<td width=\"1%\">(8.88)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>To have a real solution of <i>f<\/i>, the following condition must be fulfilled:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-119.png\">\n<\/td>\n<td width=\"1%\">(8.89)<\/td>\n<\/tr>\n<\/table>\n<p>At time t<sub>0<\/sub>, when one encounters a K→ β hop that is frustrated by the FS algorithm, one computes the FSTU uncertainty time for this unconfirmed hop as<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-120.png\">\n<\/td>\n<td width=\"1%\">(8.90)<\/td>\n<\/tr>\n<\/table>\n<p>where the absolute value is needed because ∆E<sup>Kβ<\/sup>(t<sub>0<\/sub>) is negative. Then FSTU algorithm looks for energy accessible K→ β hop within this time uncertainty region.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.16\"><\/a><\/p>\n<h2>\n8.16  Laser fields<\/h2>\n<p><a id=\"met:laser_field\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The program <b><tt>laser.x<\/tt><\/b> can calculate laser fields as superpositions of several analytical, possibly chirped, laser pulses. In the following, the laser parametrization is given (see <a href=\"#Marquetand2007\" id=\"CITEMarquetand2007\" class=\"tth_citation\">[107<\/a>] for further details).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.16.1\"><\/a><\/p>\n<h3>\n8.16.1  Form of the laser field<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In general, the laser field ϵ(t) is a linear superposition of a number of laser pulses l<sub>i<\/sub>(t):<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-121.png\">\n<\/td>\n<td width=\"1%\">(8.91)<\/td>\n<\/tr>\n<\/table>\n<p>where <b>p<\/b><sub>i<\/sub> is the normalized polarization vector of pulse i.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A pulse l(t) is formed as the product of an envelope function and a field function. <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-122.png\">\n<\/td>\n<td width=\"1%\">(8.92)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.16.2\"><\/a><\/p>\n<h3>\n8.16.2  Envelope functions<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>There are two types of envelope function defined in <b><tt>laser.x<\/tt><\/b>, which are Gaussian and sinusoidal.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The Gaussian envelope is defined as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-123.png\"><a id=\"eq:laser_gauss_1\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.93)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-124.png\"><a id=\"eq:laser_gauss_2\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.94)<\/td>\n<\/tr>\n<\/table>\n<p>where <i>E<\/i><sub>0<\/sub> is the peak field strength, FWHM is the full width at half maximum and t<sub>c<\/sub> is the temporal center of the pulse.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The sinusoidal envelope is defined as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-125.png\"><a id=\"eq:laser_sinus\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.95)<\/td>\n<\/tr>\n<\/table>\n<p>where again <i>E<\/i><sub>0<\/sub> is the peak field strength, t<sub>0<\/sub> and t<sub>c<\/sub> define the interval where the field strength increases, and t<sub>c2<\/sub> and t<sub>e<\/sub> define the interval where the field strength decreases. Figure <a href=\"#fig:laser_envelope\">8.3<\/a> shows the general form of the envelope functions and the meaning of the temporal parameters t<sub>0<\/sub>, t<sub>c<\/sub>, t<sub>2c<\/sub> and t<sub>e<\/sub>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p><a id=\"tth_fIg8.3\"><br \/>\n<\/a> <\/p>\n<div style=\"text-align:center\"> <img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/laser_envelope.png\"> <\/p>\n<div style=\"text-align:center\">Figure 8.3: Types of laser envelopes implemented in <b><tt>laser.x<\/tt><\/b>.<\/div>\n<p> <a id=\"fig:laser_envelope\"><br \/>\n<\/a>\n<\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.16.3\"><\/a><\/p>\n<h3>\n8.16.3  Field functions<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>The field function f(t) is defined as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-126.png\">\n<\/td>\n<td width=\"1%\">(8.96)<\/td>\n<\/tr>\n<\/table>\n<p>where ω<sub>0<\/sub> is the central frequency and ϕ is the phase of the pulse. Even though the laser field is complex in this expression, in the propagation of the electronic wave function in S<span style=\"font-size:x-small\">HARC<\/span> only the real part is used.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.16.4\"><\/a><\/p>\n<h3>\n8.16.4  Chirped pulses<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In order to apply a chirp to the laser pulse l(t), it is first Fourier transformed to the frequency domain, giving the function <span class=\"overacc1\">~<\/span>l(ω). The chirp is applied by calculating:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-127.png\"><a id=\"eq:laser_chirp\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.97)<\/td>\n<\/tr>\n<\/table>\n<p>The chirped laser in the time domain l′(t) is then obtained by Fourier transform of the chirped pulse <span class=\"overacc1\">~<\/span>l′(ω).<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.16.5\"><\/a><\/p>\n<h3>\n8.16.5  Quadratic chirp without Fourier transform<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>If <b><tt>laser.x<\/tt><\/b> was compiled without the FFTW package, the only accessible chirps are quadratic chirps for Gaussian pulses:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-128.png\">\n<\/td>\n<td width=\"1%\">(8.98)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-129.png\">\n<\/td>\n<td width=\"1%\">(8.99)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-130.png\">\n<\/td>\n<td width=\"1%\">(8.100)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-131.png\">\n<\/td>\n<td width=\"1%\">(8.101)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-132.png\">\n<\/td>\n<td width=\"1%\">(8.102)<\/td>\n<\/tr>\n<\/table>\n<p>Other chirps are only possible with the Fourier transformation.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.17\"><\/a><\/p>\n<h2>\n8.17  Laser interactions<\/h2>\n<p><a id=\"met:laser\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The laser field ϵ is included in the propagation of the electronic wave function. In each substep of the propagation, the interaction of the laser field with the dipole moments is included in the Hamiltonian. The contribution <b>V<\/b><sub>i<\/sub> is in each time step added to the Hamiltonian in equations (<a href=\"#eq:ham_propn\">8.193<\/a>) or (<a href=\"#eq:ham_propl\">8.198<\/a>), respectively:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-133.png\">\n<\/td>\n<td width=\"1%\">(8.103)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-134.png\">\n<\/td>\n<td width=\"1%\">(8.104)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-135.png\">\n<\/td>\n<td width=\"1%\">(8.105)<\/td>\n<\/tr>\n<\/table>\n<p>where i, n t and ∆t are defined as in section <a href=\"#met:propagate\">8.33<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.17.1\"><\/a><\/p>\n<h3>\n8.17.1  Surface Hopping with laser fields<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>If laser fields are present, there can be two fundamentally different types of hops: laser-induced hops and nonadiabatic hops. The latter ones are the same hops as in the laser-free simulations, and demand that the total energy is conserved. The laser-induced hops on the other hand demand that the momentum (kinetic energy) is conserved. Hence, S<span style=\"font-size:x-small\">HARC<\/span> needs to decide for every hop whether it is laser-induced or not. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Consider a previous state α and a new state β. Currently, the hop is classified based on the energy gap ∆E=|E<sub>β<\/sub><sup>diag<\/sup>−E<sub>α<\/sub><sup>diag<\/sup>| and the instantaneous central energy of the laser pulse ω.<br \/>\nThe hop is assumed to be laser-induced if<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-136.png\">\n<\/td>\n<td width=\"1%\">(8.106)<\/td>\n<\/tr>\n<\/table>\n<p>where W is a fixed parameter. W can be set using the input keyword <b><tt>laserwidth<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If a hop has been classified as laser-free, the momentum is adjusted according to the equations given in section <a href=\"#met:ekinadj\">8.13<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.18\"><\/a><\/p>\n<h2>\n8.18  Linear\/Quadratic Vibronic Coupling Models<\/h2>\n<p><a id=\"met:lvc\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In the vibronic coupling model <a href=\"#Koeppel84ACP\" class=\"tth_citeref\">[102<\/a>] the diabatic energy and coupling matrix <b>V<\/b> is constructed as<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-137.png\"><a id=\"eq:V\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.107)<\/td>\n<\/tr>\n<\/table>\n<p>where V<sub>0<\/sub>(<span class=\"overacc2\">→<\/span>Q) is the reference potential and <b>W<\/b>(<span class=\"overacc2\">→<\/span>Q) includes the state-specific vibronic terms.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within S<span style=\"font-size:x-small\">HARC<\/span>, the reference potential is chosen to be a harmonic oscillator.<br \/>\nThe reference potential is expressed in dimensionless mass-frequency-scaled normal coordinates, which can be computed from the Cartesian coordinates r<sub>A<\/sub> as<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-138.png\"><a id=\"eq:Qi\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.108)<\/td>\n<\/tr>\n<\/table>\n<p>where ω<sub>i<\/sub> is the frequency of normal mode i, M<sub>A<\/sub> is an atomic mass, and K<sub>A i<\/sub> denotes the conversion matrix between mass-weighted Cartesian and normal coordinates.<br \/>\nUsing these coordinates, the harmonic reference potential is given as<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-139.png\"><a id=\"eq:V0Qi\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.109)<\/td>\n<\/tr>\n<\/table>\n<p>In the case of the quadratic vibronic coupling model, one additionally considers the following state-specific terms that constitute the <b>W<\/b> matrix.<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-140.png\"><a id=\"eq:Wnn\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.110)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-141.png\"><a id=\"eq:Wmn\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.111)<\/td>\n<\/tr>\n<\/table>\n<p>Here the ϵ<sub>α<\/sub> are the vertical excitation energies, the η<sub>αβ<\/sub> are the SOC constants, and the κ<sub>i<\/sub><sup>(α)<\/sup> and λ<sub>i<\/sub><sup>(αβ)<\/sup> are termed intrastate and interstate linear vibronic coupling constant <a href=\"#Koeppel84ACP\" class=\"tth_citeref\">[102<\/a>].<br \/>\nThe γ<sub>ij<\/sub><sup>(αβ)<\/sup> terms are quadratic vibronic coupling constants, where there are different types (inter\/intra-state as well as quadratic\/bilinear).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within S<span style=\"font-size:x-small\">HARC<\/span>4, the SOCs can also have a linear dependence:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-142.png\">\n<\/td>\n<td width=\"1%\">(8.112)<\/td>\n<\/tr>\n<\/table>\n<p>These are called <b><tt>lambda_soc<\/tt><\/b> in the <b><tt>LVC.template<\/tt><\/b> file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Also within S<span style=\"font-size:x-small\">HARC<\/span>4, one can use LVC in the presence of solvent point charges, in an electrostatic embedding fashion <a href=\"#Polonius2023JCTC\" class=\"tth_citeref\">[36<\/a>].<br \/>\nHere, a solvent-charge-dependent term is added to <b>W<\/b> (including the diagonal αα):<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-143.png\">\n<\/td>\n<td width=\"1%\">(8.113)<\/td>\n<\/tr>\n<\/table>\n<p>where <span class=\"overacc2\">→<\/span>r is the vector of the point charge coordinates, <span class=\"overacc2\">→<\/span>q collects the point charge values, and the sum is evaluated in real space, not in normal mode coordinates (therefore the equation shows <span class=\"overacc2\">→<\/span>R rather than <span class=\"overacc2\">→<\/span>Q).<br \/>\nHere, <b>T<\/b> is the geometric tensor <a href=\"#Polonius2023JCTC\" class=\"tth_citeref\">[36<\/a>] that is computed from the positions of all involved atoms, and <b>P<\/b><sup>αβ<\/sup> is the tensor of the multipole charges for the state density (αα) or transition density (αβ).<br \/>\nFor each αβ, there are 10n<sub>atom<\/sub> multipole charges.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the solvent-dependent term is computed considering the relative orientation of the current and reference geometry, by means of the Kabsch algorithm.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.18.1\"><\/a><\/p>\n<h3>\n8.18.1  Obtaining LVC parameters from ab initio data<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>All LVC parameters are either constant or linear, implying that they can be obtained from either a single ab initio computation or from some first derivative.<br \/>\nThe following equations show how the parameters ϵ<sub>α<\/sub>, η<sub>αβ<\/sub>, κ<sub>i<\/sub><sup>(α)<\/sup>, and λ<sub>i<\/sub><sup>(αβ)<\/sup> are obtained.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The parameters ϵ<sub>α<\/sub> are simply the vertical excitation energies at the reference geometry:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-144.png\">\n<\/td>\n<td width=\"1%\">(8.114)<\/td>\n<\/tr>\n<\/table>\n<p>where E<sup>ref<\/sup> is some reference energy.<br \/>\nLikewise, the SOC parameters η<sub>αβ<\/sub> are simply the SOC matrix elements at the reference geometry:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-145.png\">\n<\/td>\n<td width=\"1%\">(8.115)<\/td>\n<\/tr>\n<\/table>\n<p>These two equations hold because in the LVC model we assume that at the reference geometry diabatic basis and MCH basis coincide.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The intrastate linear vibronic coupling term κ<sub>i<\/sub><sup>(α)<\/sup> is the gradient of the diabatic energy of state n.<br \/>\nSince at the reference geometry, diabatic and MCH basis coincide, this is equivalent to the gradient of the corresponding MCH state.<br \/>\nThis gradient needs only be transformed from Cartesian coordinates into normal mode coordinates:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-146.png\">\n<\/td>\n<td width=\"1%\">(8.116)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>The interstate linear vibronic coupling term λ<sub>i<\/sub><sup>(αβ)<\/sup> is the gradient of the diabatic coupling between states n and m.<br \/>\nIf analytical nonadiabatic coupling vectors are available, these parameters can be obtained-similarly as the κ<sub>i<\/sub><sup>(α)<\/sup> parameters-by coordinate transformation of the energy-difference-scaled nonadiabatic coupling vector:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-147.png\">\n<\/td>\n<td width=\"1%\">(8.117)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>If gradients or nonadiabatic coupling vectors are not available, then the κ<sub>i<\/sub><sup>(α)<\/sup> and λ<sub>i<\/sub><sup>(αβ)<\/sup> parameters can be obtained numerically.<br \/>\nTo this end, one performs ab initio calculations at displaced geometries ±δQ<sub>i<\/sub>, where<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-148.png\">\n<\/td>\n<td width=\"1%\">(8.118)<\/td>\n<\/tr>\n<\/table>\n<p>The ab initio calculations at these geometries provide the energies H<sup>MCH<\/sup><sub>αα<\/sub>(r<sub>A<\/sub><sup>±i<\/sup>) and the wave function overlaps S<sup>±i<\/sup><sub>αβ<\/sub>=〈ψ<sup>MCH<\/sup><sub>α<\/sub>(<span class=\"overacc2\">→<\/span>r<sup>ref<\/sup>)|ψ<sup>MCH<\/sup><sub>β<\/sub>(<span class=\"overacc2\">→<\/span>r<sup>±i<\/sup>)〉.<br \/>\nFrom these data, the κ<sub>i<\/sub><sup>(α)<\/sup> values can be computed as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-149.png\">\n<\/td>\n<td width=\"1%\">(8.119)<\/td>\n<\/tr>\n<\/table>\n<p>and the λ<sub>i<\/sub><sup>(αβ)<\/sup> as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-150.png\">\n<\/td>\n<td width=\"1%\">(8.120)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>The Λ<sup>(αβ)<\/sup><sub>i<\/sub> terms are evaluated similarly from the diabatized SOCs.<br \/>\nThe multipolar charges are evaluated by means of a RESP fit; the diabatic multipolar charges in the LVC template file are assumed identical to the charges at the reference geometry.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.19\"><\/a><\/p>\n<h2>\n8.19  Normal Mode Analysis<\/h2>\n<p><a id=\"met:nma\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The normal mode analysis can be used to find important vibrational modes in the excited-state dynamics.<a href=\"#Kurtz2001JCP\" class=\"tth_citeref\">[64<\/a>,<a href=\"#Plasser2009\" class=\"tth_citeref\">[65<\/a>]<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Given a matrix <b>Q<\/b> containing the normal mode vectors and a reference geometry <b>R<\/b><sup>ref<\/sup>, calculate for each trajectory<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-151.png\">\n<\/td>\n<td width=\"1%\">(8.121)<\/td>\n<\/tr>\n<\/table>\n<p>to obtain the displacements in normal mode coordinates.<br \/>\nAveraging over the displacements gives the average trajectory:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-152.png\">\n<\/td>\n<td width=\"1%\">(8.122)<\/td>\n<\/tr>\n<\/table>\n<p>which should contain only coherent motion, since random motion cancels out in an ensemble.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A measure for the coherent activity in a mode is the standard deviation (over time) of the average trajectory:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-153.png\">\n<\/td>\n<td width=\"1%\">(8.123)<\/td>\n<\/tr>\n<\/table>\n<p>where k<sub>start<\/sub> and k<sub>end<\/sub> are the start and end time steps for the analysis.<br \/>\nR<sub>coh<\/sub> a vector with one number per normal mode, where larger number mean that there is more coherent activity in this mode.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>A measure for the total motion in a mode is the total standard deviation:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-154.png\">\n<\/td>\n<td width=\"1%\">(8.124)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.20\"><\/a><\/p>\n<h2>\n8.20  Optimization of Crossing Points<\/h2>\n<p><a id=\"met:orcaopt\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>With <b><tt>orca_External<\/tt><\/b> it is possible to optimize different kinds of crossing points.<br \/>\nIn all cases, these optimizations involve the energies of the lower state E<sub>l<\/sub> and upper state E<sub>u<\/sub>, the energy difference ∆E=E<sub>u<\/sub>−E<sub>l<\/sub>, the gradients of the lower state <b>g<\/b><sub>l<\/sub> and upper state <b>g<\/b><sub>u<\/sub>, the gradient difference vector <b>d<\/b>, and\/or the nonadiabatic coupling vector <b>t<\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The simplest case is the optimization of minimum-energy crossing points between states of different multiplicity, because in this case the nonadiabatic coupling vector is zero and the branching space is one-dimensional.<br \/>\nIn this case <a href=\"#Bearpark1994CPL\" class=\"tth_citeref\">[68<\/a>], the energy to optimize is E<sub>u<\/sub> inside the intersection space, and ∆E inside the branching space.<br \/>\nThe corresponding gradient to follow <b>F<\/b> can be written as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-155.png\">\n<\/td>\n<td width=\"1%\">(8.125)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>More complicated is the optimization of a conical intersection, between states of the same multiplicity, because the branching space is two-dimensional.<br \/>\nThe corresponding gradient to follow <b>F<\/b> is:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-156.png\">\n<\/td>\n<td width=\"1%\">(8.126)<\/td>\n<\/tr>\n<\/table>\n<p>where <b>d<\/b> and <b>t<\/b> need to be orthogonalized.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>If no nonadiabatic coupling vector is available because the interface cannot deliver them, conical intersections are optimized with the penalty function method of Levine et al. <a href=\"#Levine2008JPCB\" class=\"tth_citeref\">[69<\/a>].<br \/>\nThe effective energy to optimize is defined as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-157.png\">\n<\/td>\n<td width=\"1%\">(8.127)<\/td>\n<\/tr>\n<\/table>\n<p>This equation is a combination of the two main targets of the optimization, the average energy and the energy gap.<br \/>\nThe parameter σ allows prioritizing either of the two, with a larger σ leading to smaller energy gaps.<br \/>\nThe parameter α is there to avoid the discontinuity at E<sub>u<\/sub>=E<sub>l<\/sub>.<br \/>\nThe corresponding gradient to follow <b>F<\/b> is:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-158.png\">\n<\/td>\n<td width=\"1%\">(8.128)<\/td>\n<\/tr>\n<\/table>\n<p>Note that σ and α might strongly influence the quality (i.e., with the penalty function method the optimization will not converge to the true minimum energy conical intersection point) of the result and the convergence behavior.<br \/>\nA large σ and a small α will improve the quality of the result, but make the optimization harder to converge.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.21\"><\/a><\/p>\n<h2>\n8.21  Phase tracking<\/h2>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.21.1\"><\/a><\/p>\n<h3>\n8.21.1  Phase tracking of the transformation matrix<\/h3>\n<p><a id=\"met:phase_track\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>A Hermitian matrix <b>H<\/b><sup>MCH<\/sup> can always be diagonalized. Its eigenvectors form the rows of a unitary matrix <b>U<\/b>, which can be used to transform between the original basis and the basis of the eigenfunctions of <b>H<\/b>. <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-159.png\">\n<\/td>\n<td width=\"1%\">(8.129)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>However, the condition that <b>U<\/b> diagonalizes <b>H<\/b><sup>MCH<\/sup> is not sufficient to define <b>U<\/b> uniquely. Each normalized eigenvector <b>u<\/b> can be multiplied by a complex number on the unit circle and still remains a normalized eigenvector.<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-160.png\">\n<\/td>\n<td width=\"1%\">(8.130)<\/td>\n<\/tr>\n<\/table>\n<p>leads to<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-161.png\">\n<\/td>\n<td width=\"1%\">(8.131)<\/td>\n<\/tr>\n<\/table>\n<p>and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-162.png\">\n<\/td>\n<td width=\"1%\">(8.132)<\/td>\n<\/tr>\n<\/table>\n<p>Thus, for all diagonal matrices Φ with elements<br \/>\n δ<sub>βα<\/sub>exp(<span class=\"roman\">i<\/span>ϕ<sub>β<\/sub>),<br \/>\nalso the matrix <b>U<\/b>′=<b>U<\/b>Φ diagonalizes <b>H<\/b><sup>MCH<\/sup> (if <b>U<\/b> diagonalizes it).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The propagation of the coefficients in the diagonal basis is written as (see section <a href=\"#met:propagate\">8.33<\/a>):<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-163.png\">\n<\/td>\n<td width=\"1%\">(8.133)<\/td>\n<\/tr>\n<\/table>\n<p>where <b>U<\/b>(t) and <b>U<\/b>(t+∆t) are determined independently from diagonalizing the matrices <b>H<\/b><sup>MCH<\/sup>(t) and <b>H<\/b><sup>MCH<\/sup>(t+∆t), respectively. However, depending on the implementation of the diagonalization, <b>U<\/b>(t) and <b>U<\/b>(t+∆t) may carry unrelated, random phases. Even if <b>H<\/b><sup>MCH<\/sup>(t) and <b>H<\/b><sup>MCH<\/sup>(t+∆t) were identical, <b>U<\/b>(t) and <b>U<\/b>(t+∆t) might still differ, e.g.:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-164.png\">\n<\/td>\n<td width=\"1%\">(8.134)<\/td>\n<\/tr>\n<\/table>\n<p>The result is that the coefficients <b>c<\/b> pick up random phases during the propagation, leading to random changes in the direction of population transfer, invalidating the whole propagation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to make the phases of <b>U<\/b>(t) and <b>U<\/b>(t+∆t) as similar as possible, S<span style=\"font-size:x-small\">HARC<\/span> employs a projection technique. First, we define the overlap matrix <b>V<\/b> between <b>U<\/b>(t) and <b>U<\/b>(t+∆t):<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-165.png\">\n<\/td>\n<td width=\"1%\">(8.135)<\/td>\n<\/tr>\n<\/table>\n<p>For ∆t=0, clearly<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-166.png\">\n<\/td>\n<td width=\"1%\">(8.136)<\/td>\n<\/tr>\n<\/table>\n<p>and <b>V<\/b> can be identified with the phase matrix Φ.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>For ∆t ≠ 0, we must now find a matrix <b>P<\/b> so that<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-167.png\">\n<\/td>\n<td width=\"1%\">(8.137)<\/td>\n<\/tr>\n<\/table>\n<p>still diagonalizes <b>H<\/b><sup>MCH<\/sup>(t+∆t), but which minimizes the phase change with regard to <b>U<\/b>(t).<br \/>\nThe matrix <b>P<\/b> has elements<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-168.png\">\n<\/td>\n<td width=\"1%\">(8.138)<\/td>\n<\/tr>\n<\/table>\n<p>where E<sub>β<\/sub> is the β-th eigenvalue of <b>H<\/b><sup>MCH<\/sup>(t+∆t).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within the S<span style=\"font-size:x-small\">HARC<\/span> algorithm, the phase of <b>U<\/b>(t+∆t) is adjusted to be most similar to <b>U<\/b>(t) by calculating first <b>V<\/b>, generating <b>P<\/b> from <b>V<\/b> and the eigenvalues of <b>H<\/b><sup>MCH<\/sup>(t+∆t) and calculating the phase-corrected matrix <b>U<\/b>′(t+∆t) as <b>U<\/b>(t+∆t)<b>P<\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.21.2\"><\/a><\/p>\n<h3>\n8.21.2  Tracking of the phase of the MCH wave functions<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Additionally, within the quantum chemistry programs, the phases of the electronic wave functions may change from one time step to the next one. This will result in changes of the phase of all off-diagonal matrix elements (spin-orbit couplings, transition dipole moments, nonadiabatic couplings). S<span style=\"font-size:x-small\">HARC<\/span> has several possibilities to correct for that:<\/p>\n<ul>\n<li> The interface can provide wave function phases through <b><tt>QM.out<\/tt><\/b>.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> If the overlap matrix is available, its diagonal contains the necessary phase information.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Otherwise the scalar products of old and new nonadiabatic couplings and the relative phase of SOC matrix elements can be used to construct phase information.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.22\"><\/a><\/p>\n<h2>\n8.22  Random initial velocities<\/h2>\n<p><a id=\"met:veloc\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Random initial velocities are calculated with a given amount of kinetic energy E per atom a. For each atom, the velocity is calculated as follows, with two uniform random numbers θ and ϕ, from the interval [0,1[:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-169.png\">\n<\/td>\n<td width=\"1%\">(8.139)<\/td>\n<\/tr>\n<\/table>\n<p>This procedure gives a uniform probability distribution on a sphere with radius √{2E\/m<sub>a<\/sub>}.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the translational and rotational components of random initial velocities are not projected out in the current implementation.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Random initial velocities can be requested in the input with <b><tt>veloc random E<\/tt><\/b>, where E is a float defining the kinetic energy per atom (in eV).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.23\"><\/a><\/p>\n<h2>\n8.23  Representations<\/h2>\n<p><a id=\"sec:repr\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within S<span style=\"font-size:x-small\">HARC<\/span>, two different representations for the electronic states are used. The first is the so-called MCH basis, which is the basis of the eigenfunctions of the molecular Coulomb Hamiltonian. The molecular Coulomb Hamiltonian is the standard electronic Hamiltonian employed by the majority of quantum chemistry programs. It contains only the kinetic energy of the electrons and the potential energy arising from the Coulomb interaction between the electrons and nuclei.<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-170.png\">\n<\/td>\n<td width=\"1%\">(8.140)<\/td>\n<\/tr>\n<\/table>\n<p>With this hamiltonian, states of the same multiplicity couple via the nonadiabatic couplings, while states of different multiplicity do not interact at all. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>The second representation used in S<span style=\"font-size:x-small\">HARC<\/span> is the so-called diagonal representation. It is the basis of the eigenfunctions of the total Hamiltonian.<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-171.png\">\n<\/td>\n<td width=\"1%\">(8.141)<\/td>\n<\/tr>\n<\/table>\n<p>The term <span class=\"overacc1\">∧<\/span>H<sub>el<\/sub><sup>coup<\/sup> contains additional couplings not contained in the molecular Coulomb Hamiltonian. The most common couplings are spin-orbit couplings and interactions with an external electric field.<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-172.png\">\n<\/td>\n<td width=\"1%\">(8.142)<\/td>\n<\/tr>\n<\/table>\n<p>Both of these couplings introduce off-diagonal elements in the total Hamiltonian. Thus, the eigenfunctions of the molecular Coulomb Hamiltonian are not the eigenfunctions of the total Hamiltonian. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within S<span style=\"font-size:x-small\">HARC<\/span>, usually quantum chemistry information is read in the MCH representation, while the surface hopping is performed in the diagonal one.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.23.1\"><\/a><\/p>\n<h3>\n8.23.1  Current state in MCH representation<\/h3>\n<p><a id=\"ssec:state_transform\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Oftentimes, it is very useful to know to which MCH state the currently active diagonal state corresponds. If <span class=\"overacc1\">∧<\/span>H<sub>el<\/sub><sup>coup<\/sup> is small or the state separation is large, then each diagonal state approximately corresponds to one MCH state. Only in the case of large couplings and\/or near-degenerate states are the MCH states strongly mixed in the diagonal states.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to obtain for a given time step from the currently active diagonal state β the corresponding MCH state α, a vector <b>c<\/b><sup>diag<\/sup> with c<sub>i<\/sub><sup>diag<\/sup>=δ<sub>iβ<\/sub> is generated. The vector is transformed into the MCH representation<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-173.png\">\n<\/td>\n<td width=\"1%\">(8.143)<\/td>\n<\/tr>\n<\/table>\n<p>The corresponding MCH state α is the index of the (absolute) largest element of vector <b>c<\/b><sup>MCH<\/sup>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.24\"><\/a><\/p>\n<h2>\n8.24  Sampling from Wigner Distribution<\/h2>\n<p><a id=\"met:wigner\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The sampling is based on references <a href=\"#Dahl1988JCP\" class=\"tth_citeref\">[55<\/a>,<a href=\"#Schinke1995\" class=\"tth_citeref\">[56<\/a>].<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Besides the equilibrium geometry <b>R<\/b><sub>eq<\/sub>, the optimization plus frequency calculation provides a set of vibrational frequencies {ν<sub>i<\/sub>} and the corresponding normal mode vectors {<b>n<\/b><sub>i<\/sub>}, where i runs from 1 to N=3n<sub>atom<\/sub>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The normal mode vectors need to be provided in terms of mass-weighted Cartesian normal modes, in atomics units (Bohrs times square root of electron mass, i.e., a<sub>0<\/sub>·√{m<sub>e<\/sub>}).<br \/>\nMost quantum chemistry programs follow different conventions when writing M<span style=\"font-size:x-small\">OLDEN<\/span> files. M<span style=\"font-size:x-small\">OLPRO<\/span> and M<span style=\"font-size:x-small\">OLCAS<\/span> write these files with unweighted Cartesian normal modes, with units of a<sub>0<\/sub> (Bohrs). G<span style=\"font-size:x-small\">AUSSIAN<\/span>, T<span style=\"font-size:x-small\">URBOMOLE<\/span>, Q-C<span style=\"font-size:x-small\">HEM<\/span>, ADF, and O<span style=\"font-size:x-small\">RCA<\/span> employ what could be called the ” G<span style=\"font-size:x-small\">AUSSIAN<\/span> convention”, which are normalized Cartesian normal modes. C<span style=\"font-size:x-small\">OLUMBUS<\/span> uses yet another convention in the output of their <b><tt>suscal.x<\/tt><\/b> module.<br \/>\nThe script <b><tt>wigner.py<\/tt><\/b> automatically transforms these different conventions; it does so by applying all possible transformations to the input data until it finds one transformation which produces an orthonormal normal mode matrix.<br \/>\nThe latter one is then used for the Wigner sampling.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to create an initial condition (<b>R<\/b>,<b>v<\/b>), the following procedure is applied. Initially, <b>R<\/b><sub>0<\/sub>=<b>R<\/b><sub>eq<\/sub> and <b>v<\/b><sub>0<\/sub>=0. Then, for each normal mode i, two random numbers P<sub>i<\/sub> and Q<sub>i<\/sub> are chosen uniformly from the interval [−5,5]. The value of a ground state quantum Wigner distribution for these values is calculated:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-174.png\">\n<\/td>\n<td width=\"1%\">(8.144)<\/td>\n<\/tr>\n<\/table>\n<p>W<sub>i<\/sub> is compared to a uniform random r<sub>i<\/sub> number from [0,1]. If W<sub>i<\/sub> > r<sub>i<\/sub>, then P<sub>i<\/sub> and Q<sub>i<\/sub> are accepted.<br \/>\nSubsequently, the coordinates:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-175.png\"><a id=\"eq:wigner1\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.145)<\/td>\n<\/tr>\n<\/table>\n<p>and velocities<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-176.png\"><a id=\"eq:wigner2\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.146)<\/td>\n<\/tr>\n<\/table>\n<p>are updated.<br \/>\nThe random number procedure and updates are repeated for all normal modes, until (<b>R<\/b><sub>N<\/sub>,<b>v<\/b>)<sub>N<\/sub> is obtained, which constitutes one initial condition. Finally, the center of mass is restored and translational and rotational components are projected out of <b>v<\/b>. The harmonic potential energy is given by:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-177.png\">\n<\/td>\n<td width=\"1%\">(8.147)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.24.1\"><\/a><\/p>\n<h3>\n8.24.1  Sampling at Non-zero Temperature<\/h3>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p>In the case of a non-zero temperature, the molecule might not be in the vibrational ground state of the harmonic oscillator, but rather in an excited vibrational state.<br \/>\nFor a given mode i, the probability to be in any given vibrational state j (j=0 is the ground state) is:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-178.png\">\n<\/td>\n<td width=\"1%\">(8.148)<\/td>\n<\/tr>\n<\/table>\n<p>where y is ν<sub>i<\/sub> divided by k<sub>B<\/sub>T.<br \/>\nIn order to find the vibrational state for mode i, a random number is drawn (from [0,1]) and used as in equation (<a href=\"#eq:cumuprob\">8.154<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The displacements and velocity contributions for mode i in state j are then obtained as in equations (<a href=\"#eq:wigner1\">8.145<\/a>) and (<a href=\"#eq:wigner2\">8.146<\/a>), except that the Wigner distribution for state j is calculated as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-179.png\">\n<\/td>\n<td width=\"1%\">(8.149)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.25\"><\/a><\/p>\n<h2>\n8.25  Scaling<\/h2>\n<p><a id=\"met:scaling\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The scaling factor (keyword <b><tt>scaling<\/tt><\/b>) applies to all energies and derivatives of energies. Hence, the full Hamiltonian is scaled, and the gradients are scaled. Nothing else is scaled (no dipole moments, nonadiabatic couplings, overlaps, etc).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.26\"><\/a><\/p>\n<h2>\n8.26  Seeding of the RNG<\/h2>\n<p><a id=\"met:seed\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The standard Fortran 90 random number generator (used for <b><tt>sharc.x<\/tt><\/b>, but not for the auxiliary scripts) is seeded by a sequence of integers of length n, where n depends on the computer architecture. The input of S<span style=\"font-size:x-small\">HARC<\/span>, however, takes only a single RNG seed, which must reproducibly produce the same sequence of random numbers for the same input.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to generate the seed sequence from the single input x, the following procedure is applied:<\/p>\n<ul>\n<li> Query for the number n,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Generate a first seed sequence <b>s<\/b> with s<sub>i<\/sub>=x+37i+17i<sup>2<\/sup>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Seed with the sequence <b>s<\/b>,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Obtain a sequence <b>r<\/b> of n random numbers on the interval [0,1[,\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Generate a second seed sequence <b>s<\/b>′ with s<sub>i<\/sub>′=int(65536(r<sub>i<\/sub>−[1\/2])),\n<div class=\"p\"><!----><\/div>\n<\/li>\n<li> Reseed with the sequence <b>s<\/b>′.\n<div class=\"p\"><!----><\/div>\n<\/li>\n<\/ul>\n<p>The fifth step will generate a sequence of nearly uncorrelated numbers, distributed uniformly over the full range of possible integer values. <\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.27\"><\/a><\/p>\n<h2>\n8.27  Selection of gradients and nonadiabatic couplings<\/h2>\n<p><a id=\"met:selection\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In order to increase performance, it is possible to omit the calculation of certain gradients and nonadiabatic couplings. An energy-gap-based algorithm selects at each time step a subset of all possible gradients and nonadiabatic couplings to be calculated. Given the diagonal energy E<sup>diag<\/sup><sub>ξ<\/sub> of the current active state ξ, the gradient <b>g<\/b><sup>MCH<\/sup><sub>α<\/sub> of MCH state α is calculated if:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-180.png\">\n<\/td>\n<td width=\"1%\">(8.150)<\/td>\n<\/tr>\n<\/table>\n<p>where ε<sub>grad<\/sub> is the selection threshold.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Similarly, a nonadiabatic coupling vector <b>K<\/b><sup>MCH<\/sup><sub>βα<\/sub> is calculated if:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-181.png\">\n<\/td>\n<td width=\"1%\">(8.151)<\/td>\n<\/tr>\n<\/table>\n<p>with selection threshold ε<sub>nac<\/sub>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Neither <b>g<\/b><sup>MCH<\/sup><sub>α<\/sub> nor <b>K<\/b><sup>MCH<\/sup><sub>βα<\/sub> are ever calculated if α or β are frozen states.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>There is only one keyword (<b><tt>eselect<\/tt><\/b>) to set the selection threshold, so ε<sub>grad<\/sub> and ε<sub>nac<\/sub> are the same in most cases. <\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.28\"><\/a><\/p>\n<h2>\n8.28  State ordering<\/h2>\n<p><a id=\"met:ordering\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The canonical ordering of MCH states of different S and M<sub>S<\/sub> in S<span style=\"font-size:x-small\">HARC<\/span> is as follows. In the innermost loop, the quantum number is increased; then M<sub>S<\/sub> and finally S. Example:<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <tt>nstates 3 0 3<\/tt><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In this example, the order of states is given as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table>\n<tr>\n<td align=\"right\">Number <\/td>\n<td align=\"left\">Label <\/td>\n<td align=\"center\">S <\/td>\n<td align=\"center\">M<sub>S<\/sub> <\/td>\n<td align=\"center\">n<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">1<\/td>\n<td align=\"left\">S<sub>0<\/sub> <\/td>\n<td align=\"center\">0<\/td>\n<td align=\"center\">0<\/td>\n<td align=\"center\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">2<\/td>\n<td align=\"left\">S<sub>1<\/sub> <\/td>\n<td align=\"center\">0<\/td>\n<td align=\"center\">0<\/td>\n<td align=\"center\">2<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">3<\/td>\n<td align=\"left\">S<sub>2<\/sub> <\/td>\n<td align=\"center\">0<\/td>\n<td align=\"center\">0<\/td>\n<td align=\"center\">3<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">4<\/td>\n<td align=\"left\">T<sub>1<\/sub><sup>−<\/sup> <\/td>\n<td align=\"center\">2<\/td>\n<td align=\"center\">-1<\/td>\n<td align=\"center\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">5<\/td>\n<td align=\"left\">T<sub>2<\/sub><sup>−<\/sup> <\/td>\n<td align=\"center\">2<\/td>\n<td align=\"center\">-1<\/td>\n<td align=\"center\">2<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">6<\/td>\n<td align=\"left\">T<sub>3<\/sub><sup>−<\/sup> <\/td>\n<td align=\"center\">2<\/td>\n<td align=\"center\">-1<\/td>\n<td align=\"center\">3<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">7<\/td>\n<td align=\"left\">T<sub>1<\/sub><sup>0<\/sup> <\/td>\n<td align=\"center\">2<\/td>\n<td align=\"center\">0<\/td>\n<td align=\"center\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">8<\/td>\n<td align=\"left\">T<sub>2<\/sub><sup>0<\/sup> <\/td>\n<td align=\"center\">2<\/td>\n<td align=\"center\">0<\/td>\n<td align=\"center\">2<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">9<\/td>\n<td align=\"left\">T<sub>3<\/sub><sup>0<\/sup> <\/td>\n<td align=\"center\">2<\/td>\n<td align=\"center\">0<\/td>\n<td align=\"center\">3<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">10<\/td>\n<td align=\"left\">T<sub>1<\/sub><sup>+<\/sup> <\/td>\n<td align=\"center\">2<\/td>\n<td align=\"center\">+1<\/td>\n<td align=\"center\">1<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">11<\/td>\n<td align=\"left\">T<sub>2<\/sub><sup>+<\/sup> <\/td>\n<td align=\"center\">2<\/td>\n<td align=\"center\">+1<\/td>\n<td align=\"center\">2<\/td>\n<\/tr>\n<tr>\n<td align=\"right\">12<\/td>\n<td align=\"left\">T<sub>3<\/sub><sup>+<\/sup> <\/td>\n<td align=\"center\">2<\/td>\n<td align=\"center\">+1<\/td>\n<td align=\"center\">3<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>The canonical ordering of states is for example important in order to specify the initial state in the MCH basis (using the <b><tt>state<\/tt><\/b> keyword in the input file).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Note that the diagonal states do not follow the same prescription. Since the diagonal states are in general not eigenfunctions of the total spin operator, they do not have a well-defined multiplicity.<br \/>\nHence, the diagonal states are simply ordered by increasing energy.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.29\"><\/a><\/p>\n<h2>\n8.29  Surface Hopping<\/h2>\n<p><a id=\"met:hopping\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>Given two coefficient vectors <b>c<\/b><sup>diag<\/sup>(t) and <b>c<\/b><sup>diag<\/sup>(t+∆t) and the corresponding propagator matrix <b>R<\/b><sup>diag<\/sup>(t+∆t,t), the surface hopping probabilities are given by<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-182.png\">\n<\/td>\n<td width=\"1%\">(8.152)<\/td>\n<\/tr>\n<\/table>\n<p>where, however, P<sub>β→β<\/sub>=0 and all negative P<sub>β→α<\/sub> are set to zero.<br \/>\nThis equation is the default in S<span style=\"font-size:x-small\">HARC<\/span>, and can be used with <b><tt>hopping_procedure sharc<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, the hopping probabilities can be obtained with the “global flux surface hopping” method by Prezhdo and coworkers <a href=\"#Wang2014JCTC\" class=\"tth_citeref\">[51<\/a>].<br \/>\nThe equation is:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-183.png\">\n<\/td>\n<td width=\"1%\">(8.153)<\/td>\n<\/tr>\n<\/table>\n<p>As above, P<sub>β→β<\/sub>=0 and all negative P<sub>β→α<\/sub> are set to zero.<br \/>\nThis equation and can be used with <b><tt>hopping_procedure gfsh<\/tt><\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In any case, the hopping procedure itself obtains a uniform random number r from the interval [0,1]. A hop to state α is performed, if<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-184.png\"><a id=\"eq:cumuprob\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.154)<\/td>\n<\/tr>\n<\/table>\n<p>See section <a href=\"#met:refl_frust\">8.13.1<\/a> for further details on how frustrated hops (hops according to the hopping probabilities, but where not enough energy is available to execute the hop) are handled.<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.30\"><\/a><\/p>\n<h2>\n8.30  Self-Consistent Potential Methods<\/h2>\n<p><a id=\"met:scpmethod\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>In trajectory surface hopping (TSH) methods, the trajectory is propagating on a single potential energy surface at each segment of time. Contrary, in the self-consistent potential (SCP) methods, trajectories are propagating on a SCP which is an äveraged” potential. The SCP methods are also self-consistent in terms of electronic and nuclear equations of motion (EOMs), and therefore, does not suffer from the notorious frustrated hops problem of TSH. The starting point of advanced SCP methods like CSDM is semiclassical Ehrenfest (SE), which is derivable from the time-dependent Schrödinger equation (TDSE). <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Consider a wave function that is a product of electronic and nuclear wave functions<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-185.png\">\n<\/td>\n<td width=\"1%\">(8.155)<\/td>\n<\/tr>\n<\/table>\n<p>Inserting the above molecular wave function into the TDSE, employing the independent trajectory approximation, and treating electrons as quantum particles by expanding the electronic wave function in a general basis (GB),<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-186.png\">\n<\/td>\n<td width=\"1%\">(8.156)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>With some mathematical manipulation, one obtains the equation of motion of generalized semiclassical Ehrenfest (GSE) dynamics. The electronic equation of motion of GSE is identical to that of surface hopping, <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-187.png\">\n<\/td>\n<td width=\"1%\">(8.157)<\/td>\n<\/tr>\n<\/table>\n<p>Nuclear equation of motion involves two terms, namely, the adiabatic force and nonadiabatic force. <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-188.png\">\n<\/td>\n<td width=\"1%\">(8.158)<\/td>\n<\/tr>\n<\/table>\n<p>where adiabatic force and nonadiabatic force are, respectively, <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-189.png\">\n<\/td>\n<td width=\"1%\">(8.159)<\/td>\n<\/tr>\n<\/table>\n<p>and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-190.png\">\n<\/td>\n<td width=\"1%\">(8.160)<\/td>\n<\/tr>\n<\/table>\n<p>where <b>K<\/b><sub>αβ<\/sub><sup>diag<\/sup> is the nonadiabatic coupling vector (NAC). Alternatively, one can use an effective nonadiabatic coupling vector (effective NAC), <b>G<\/b><sub>αβ<\/sub>, which is defined as a combination of the difference gradient vector and the velocity vector:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-191.png\">\n<\/td>\n<td width=\"1%\">(8.161)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.30.1\"><\/a><\/p>\n<h3>\n8.30.1  Decoherence in SCP methods<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Whereas TSH dynamics involve the coherent propagation of a trajectory on a single potential energy surface, which is stochastically switched, SCP methods include decoherence by considering a combination of coherent and decoherent propagation of a trajectory on the self-consistent potential. This approach leads to the so-called <em>decay of mixing<\/em> methods.<br \/>\nIn this framework, the electronic equation of motion is:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-192.png\">\n<\/td>\n<td width=\"1%\">(8.162)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>where the coherent term is the same as in the GSE electronic equation of motion (as well as in the TSH equation). The decoherent contribution is introduced to drive the density matrix elements of the state β, which survives to decoherence (called the <em>pointer state<\/em>), to unity, while all other density matrix elements decay to zero within a relaxation time known as the decoherence time:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-193.png\"><a id=\"eeom_dm\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.163)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>This decoherent term also determines a force in the equation of motion of the nuclei and drives the trajectory to a pure electronic state (i.e., the pointer state):<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-194.png\">\n<\/td>\n<td width=\"1%\">(8.164)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>where [ <b>F<\/b> ]<sub>co<\/sub> is identical to the GSE nuclear equation of motion, and the decoherent force contribution is:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-195.png\">\n<\/td>\n<td width=\"1%\">(8.165)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>where <b>s<\/b> is the decoherence vector.<a href=\"#Hack2001JCP2\" class=\"tth_citeref\">[96<\/a>,<a href=\"#ZhuSCDM2004JCP\" class=\"tth_citeref\">[40<\/a>]<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Switchung Procedure  <\/b><br \/>\nThe pointer state is switched during the dynamics with a switching probability that can be computed in three different ways. In the natural decay of mixing (ndm) method <a href=\"#Hack2001JCP2\" class=\"tth_citeref\">[96<\/a>], the decay of mixing electronic density is used to calculate the switching probability according to the fewest-switches criterion:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-196.png\">\n<\/td>\n<td width=\"1%\">(8.166)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>The self-consistent decay of mixing (scdm)<a href=\"#ZhuSCDM2004JCP\" class=\"tth_citeref\">[40<\/a>] method, instead, locally eliminates the decoherent contribution in the electronic density within the switching algorithm:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-197.png\">\n<\/td>\n<td width=\"1%\">(8.167)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>In contrast to scdm, in the coherent switching with decay of mixing (csdm)<a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>] method, the decoherent contribution to the electronic density matrix used in the switching probability is switched off over an entire region of strong coupling:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-198.png\">\n<\/td>\n<td width=\"1%\">(8.168)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>where <span class=\"overacc1\">~<\/span>ρ<sub>βα<\/sub> are the density matrix elements associated to the coherent amplitudes and they are initialized to the decay of mixing quantities (ρ<sub>βα<\/sub><sup>co<\/sup> + ρ<sub>βα<\/sub><sup>de<\/sup>) at each local minimum of the coupling strenght defined by:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-199.png\">\n<\/td>\n<td width=\"1%\">(8.169)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p><b>Decoherence Time  <\/b><br \/>\nThe decoherence time in equation (<a href=\"#eeom_dm\">8.163<\/a>) can be computed using three different approaches. The energy-based decoherence (EDC) correction computes τ<sub>αβ<\/sub> as:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-200.png\">\n<\/td>\n<td width=\"1%\">(8.170)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>“where T is the total kinetic energy, and C is a parameter usually set to 0.1 Hartree <a href=\"#Granucci2010JCP\" class=\"tth_citeref\">[94<\/a>]. Alternatively, τ<sub>αβ<\/sub> can be evaluated in the SCDM framework using the internal vibrational kinetic energy (T<sub>vib<\/sub>) instead of the total kinetic energy:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-201.png\">\n<\/td>\n<td width=\"1%\">(8.171)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>where C is a user-defined parameter, usually set in the range of 6\u20139 <a href=\"#ZhuSCDM2004JCP\" class=\"tth_citeref\">[40<\/a>].<br \/>\nThe csdm method, instead, accounts for momentum constraints in the decoherence process:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-202.png\">\n<\/td>\n<td width=\"1%\">(8.172)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>where E<sub>0<\/sub> is 1 Hartree and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-203.png\">\n<\/td>\n<td width=\"1%\">(8.173)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>with P<sub>η<\/sub>, <span class=\"overacc1\">∧<\/span>s<sub>αβ,η<\/sub>, and M<sub>η<\/sub> representing the ηth component of the nuclear momentum, the ηth component of the decoherence direction, and the atomic mass corresponding to the ηth component of the nuclear degree of freedom, respectively.<a href=\"#Zhu2004JCP\" class=\"tth_citeref\">[30<\/a>]<\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.31\"><\/a><\/p>\n<h2>\n8.31  Effective Nonadiabatic Coupling Vector<\/h2>\n<p><a id=\"met:effectivenac\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The effective nonadiabatic coupling vector <b>G<\/b><sub>αβ<\/sub> is a mixture of difference gradient vector and velocity vector. <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-204.png\">\n<\/td>\n<td width=\"1%\">(8.174)<\/td>\n<\/tr>\n<\/table>\n<p>where<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-205.png\">\n<\/td>\n<td width=\"1%\">(8.175)<\/td>\n<\/tr>\n<\/table>\n<p>and c is a coefficient. The coefficient c is determined by requiring that the dot product between effective nonadiabatic coupling vector and velocity vector equals time derivative coupling:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-206.png\">\n<\/td>\n<td width=\"1%\">(8.176)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.32\"><\/a><\/p>\n<h2>\n8.32  Velocity Verlet<\/h2>\n<div class=\"p\"><!----><\/div>\n<p>The nuclear coordinates of atom A are updated according to the Velocity Verlet algorithm <a href=\"#Verlet1967PR\" id=\"CITEVerlet1967PR\" class=\"tth_citation\">[108<\/a>], based on the gradient of state β at <b>R<\/b>(t) and <b>R<\/b>(t+∆t):<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-207.png\">\n<\/td>\n<td width=\"1%\">(8.177)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-208.png\">\n<\/td>\n<td width=\"1%\">(8.178)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-209.png\">\n<\/td>\n<td width=\"1%\">(8.179)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-210.png\">\n<\/td>\n<td width=\"1%\">(8.180)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>Currently, there are no other integrators for the nuclear motion implemented in S<span style=\"font-size:x-small\">HARC<\/span>.<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.33\"><\/a><\/p>\n<h2>\n8.33  Wavefunction propagation<\/h2>\n<p><a id=\"met:propagate\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>The electronic wave function is needed in order to carry out surface hopping. The electronic wave function is expanded in the basis of the so-called model space <i>S<\/i>, which includes the few lowest states |ψ<sup>MCH<\/sup><sub>α<\/sub>〉 of the multiplicities under consideration (e.g. the 3 lowest singlet and 2 lowest triplet states). <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-211.png\">\n<\/td>\n<td width=\"1%\">(8.181)<\/td>\n<\/tr>\n<\/table>\n<p>All multiplet components are included explicitly, i.e., the inclusion of an MCH triplet state adds three explicit states to the model space (the three components of the triplet).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within S<span style=\"font-size:x-small\">HARC<\/span>, the wave function is represented just by the vector <b>c<\/b><sup>MCH<\/sup>. The Hamiltonian <b>H<\/b><sup>MCH<\/sup> is represented in matrix form with elements:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-212.png\">\n<\/td>\n<td width=\"1%\">(8.182)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>From the MCH representation, the diagonal representation can be obtained by unitary transformation within the model space <i>S<\/i> (<b>U<\/b><sup>†<\/sup><b>H<\/b><sup>MCH<\/sup><b>U<\/b>=<b>H<\/b><sup>diag<\/sup> and <b>U<\/b><sup>†<\/sup><b>c<\/b><sup>MCH<\/sup>=<b>c<\/b><sup>diag<\/sup>):<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-213.png\">\n<\/td>\n<td width=\"1%\">(8.183)<\/td>\n<\/tr>\n<\/table>\n<p>and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-214.png\">\n<\/td>\n<td width=\"1%\">(8.184)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>The propagation of the electronic wave function from time t to t+∆t can then be written as the product of a propagation matrix with the coefficients at time t:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-215.png\">\n<\/td>\n<td width=\"1%\">(8.185)<\/td>\n<\/tr>\n<\/table>\n<p>or<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-216.png\">\n<\/td>\n<td width=\"1%\">(8.186)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>In order to calculate <b>R<\/b><sup>MCH<\/sup>(t+∆t,t), S<span style=\"font-size:x-small\">HARC<\/span> uses (unitary) operator exponentials. <\/p>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.33.1\"><\/a><\/p>\n<h3>\n8.33.1  Propagation using nonadiabatic couplings<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Here we assume that in the dynamics the interaction between the electronic states is described by a matrix of time-derivative couplings <b>T<\/b><sup>MCH<\/sup>(t), such that<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-217.png\"><a id=\"eq:ddt\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.187)<\/td>\n<\/tr>\n<\/table>\n<p>or<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-218.png\"><a id=\"eq:ddr\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.188)<\/td>\n<\/tr>\n<\/table>\n<p>In equation (<a href=\"#eq:ddt\">8.187<\/a>), the time-derivative couplings are directly calculated by the quantum chemistry program (use <b><tt>coupling ddt<\/tt><\/b> in the S<span style=\"font-size:x-small\">HARC<\/span> input), while in (<a href=\"#eq:ddr\">8.188<\/a>) the matrix <b>T<\/b><sup>MCH<\/sup>(t) is obtained from the scalar product of the nuclear velocity and the nonadiabatic coupling vectors (use <b><tt>coupling ddr<\/tt><\/b> in the input).<\/p>\n<div class=\"p\"><!----><\/div>\n<p>The propagation matrix can then be written as <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-219.png\">\n<\/td>\n<td width=\"1%\">(8.189)<\/td>\n<\/tr>\n<\/table>\n<p>with the time-ordering operator <span class=\"overacc1\">∧<\/span><i>T<\/i>. For small time steps ∆t, <b>H<\/b><sup>MCH<\/sup>(τ) and <b>K<\/b><sup>MCH<\/sup>(τ) can be interpolated linearly<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-220.png\">\n<\/td>\n<td width=\"1%\">(8.190)<\/td>\n<\/tr>\n<\/table>\n<p>And in order to have a sufficiently small time step for this to work, the interval (t,t+∆t) is further split into subtime steps ∆τ = [(∆t)\/n]. <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-221.png\">\n<\/td>\n<td width=\"1%\">(8.191)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-222.png\">\n<\/td>\n<td width=\"1%\">(8.192)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-223.png\"><a id=\"eq:ham_propn\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.193)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-224.png\">\n<\/td>\n<td width=\"1%\">(8.194)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.33.2\"><\/a><\/p>\n<h3>\n8.33.2  Propagation using overlap matrices – Local diabatization<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>In many situations, the nonadiabatic couplings in <b>K<\/b><sup>MCH<\/sup> are very localized on the potential hypersurfaces. If this is the case, in the dynamics very short time steps are necessary to properly sample the nonadiabatic couplings. If too large time steps are used, part of the coupling may be missed, leading to wrong population transfer. The local diabatization algorithm gives more numerical stability in these situations. It can be requested with the line <b><tt>coupling overlap<\/tt><\/b> in the input file.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Within this algorithm, the change of the electronic states between time steps is described by the overlap matrix <b>S<\/b><sup>MCH<\/sup>(t,t+∆t)<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-225.png\"><a id=\"eq:overlap_definition\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.195)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>With this, the propagator matrix can be written as<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-226.png\">\n<\/td>\n<td width=\"1%\">(8.196)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-227.png\">\n<\/td>\n<td width=\"1%\">(8.197)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-228.png\"><a id=\"eq:ham_propl\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.198)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-229.png\">\n<\/td>\n<td width=\"1%\">(8.199)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.33.3\"><\/a><\/p>\n<h3>\n8.33.3  Propagation using overlap matrices – Norm-preserving interpolation<\/h3>\n<div class=\"p\"><!----><\/div>\n<p>Alternatively, one can use accurate interpolation of time derivative coupling from overlap matrices. Propagating the coefficients can be written as, <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-230.png\">\n<\/td>\n<td width=\"1%\">(8.200)<\/td>\n<\/tr>\n<\/table>\n<p>where n is the number of substeps (which can be set up by keyword <b>nsubsteps<\/b>), and l is the index of substep, with substep propagator <i>P<\/i><sup><span class=\"roman\">MCH<\/span><\/sup><sub><span class=\"roman\">C<\/span><span class=\"roman\">,<\/span>l<\/sub> defined as, <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-231.png\">\n<\/td>\n<td width=\"1%\">(8.201)<\/td>\n<\/tr>\n<\/table>\n<p>where, <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-232.png\">\n<\/td>\n<td width=\"1%\">(8.202)<\/td>\n<\/tr>\n<\/table>\n<p>i.e., one linearly interpolates the MCH Hamiltonian <span class=\"roman\">H<\/span><sup><span class=\"roman\">elec<\/span><span class=\"roman\">[<\/span><span class=\"roman\">MCH<\/span><span class=\"roman\">]<\/span><\/sup> between time t and t+∆t.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>In S<span style=\"font-size:x-small\">HARC<\/span>3.0, the <span class=\"roman\">T<\/span><sub>l<\/sub> has variants definitions, and these variants define most of the options available in S<span style=\"font-size:x-small\">HARC<\/span>3.0 keyword <b>eeom<\/b>. One can have the following possible definitions:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-233.png\">\n<\/td>\n<td width=\"1%\">(8.203)<\/td>\n<\/tr>\n<\/table>\n<p>where <span class=\"roman\">T<\/span><sup><span class=\"roman\">MCH<\/span><\/sup>(t+[(l∆t)\/n]) is the TDC at time t+[(l∆t)\/n] which is not computed from electronic structure software, but instead it is from a norm preserving interpolation <a href=\"#Meek2014JPCL\" class=\"tth_citeref\">[93<\/a>]. During time t and t+∆t, TDC at time <i>T<\/i> writes<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-234.png\">\n<\/td>\n<td width=\"1%\">(8.204)<\/td>\n<\/tr>\n<\/table>\n<p>where Θ(<i>T<\/i>) is a time-dependent transformation matrix that interpolates the MCH (adiabatic) electronic wave functions between time t and t+∆t:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-235.png\"><a id=\"eq:npi_tdc\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.205)<\/td>\n<\/tr>\n<\/table>\n<p>with<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-236.png\">\n<\/td>\n<td width=\"1%\">(8.206)<\/td>\n<\/tr>\n<\/table>\n<p>and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-237.png\">\n<\/td>\n<td width=\"1%\">(8.207)<\/td>\n<\/tr>\n<\/table>\n<p>where S<sup><span class=\"roman\">MCH<\/span><\/sup><sub>αβ<\/sub> is the overlap integral defined in equation equation (<a href=\"#eq:overlap_definition\">8.195<\/a>).<\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_sEc8.34\"><\/a><\/p>\n<h2>\n8.34  Time Derivative Couplings and Curvature Approximation<\/h2>\n<p><a id=\"met:curvature\"><br \/>\n<\/a><\/p>\n<div class=\"p\"><!----><\/div>\n<p>One of the key ingredients in propagating electronic and nuclear EOMs for GSE and electronic EOM for TSH is time derivative coupling (TDC) in MCH representation. And TDC serves the role as the electronic interstate coupling in the nonadiabatic dynamics. Because TDC cannot be computed directly from electronic structure software, TDC is evaluated by postprocessing quantum chemistry data. There are three ways to compute TDC: NAC-based, overlap-based, and curvature-driven. These three ways of computing TDC corresponds to the three types of algorithms respectively. And controlling the method of TDC evaluation in S<span style=\"font-size:x-small\">HARC<\/span>3.0 is done by using keyword <b>coupling<\/b>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>NAC-based TDC  <\/b><br \/>\nThe NAC-based TDC is computed according to equation  (<a href=\"#eq:ddr\">8.188<\/a>), which means a requirement of computing NACs <span class=\"roman\">K<\/span><sup><span class=\"roman\">MCH<\/span><\/sup> in MCH representation from quantum chemistry software. Notice that <span class=\"roman\">K<\/span><sup><span class=\"roman\">MCH<\/span><\/sup> computational cost scales quadratically as the number of electronic states involved. Therefore it is expensive. In addition, it limits the choices of electronic structure theory, because there is only very limited number of electronic structure theories for which the analytical implementation of NAC is available. Using NAC-based algorithm is enabled by using keyword <b>coupling nacdr<\/b> or <b>coupling ddr<\/b>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Overlap-based TDC  <\/b><br \/>\nThere are three ways to compute overlap-based TDC, all based on overlap integrals defined in equation (<a href=\"#eq:overlap_definition\">8.195<\/a>).<br \/>\nTherefore, to compute overlap-based TDC, one needs to compute electronic wave functions but not NACs from quantum chemistry software. Tully and Hammes-Schiffer first recognized that TDC can be evaluated based on overlaps. And this is called the Hammes-Schiffer-Tully (HST) scheme of evaluation of TDC from overlaps: <\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-238.png\">\n<\/td>\n<td width=\"1%\">(8.208)<\/td>\n<\/tr>\n<\/table>\n<p>where t is time, and ∆t is the time step. The HST scheme is improved by considering high-order finite difference:<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-239.png\">\n<\/td>\n<td width=\"1%\">(8.209)<\/td>\n<\/tr>\n<\/table>\n<p>And TDC is most accurately evaluated by a norm-preserving interpolation (NPI) scheme<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-240.png\">\n<\/td>\n<td width=\"1%\">(8.210)<\/td>\n<\/tr>\n<\/table>\n<p>where T<sup><span class=\"roman\">MCH<\/span><\/sup><sub>αβ<\/sub>(<i>T<\/i>) is defined in equation  (<a href=\"#eq:npi_tdc\">8.205<\/a>).<br \/>\nThe current implementation of S<span style=\"font-size:x-small\">HARC<\/span>3.0 employs the NPI scheme to compute overlap-based TDC. However, how TDC is actually used in propagation of electronic EOM is controlled by the keyword <b>eeom<\/b> and is discussed in section <a href=\"#met:propagate\">8.33<\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>One of the advantages of using NPI scheme over HST or high-order finite difference scheme is that it is more accurate for a situation where the nonadiabatic coupling vector is narrowly peaked (note that NAC is related to TDC), which is often called trivial crossings. It is also more accurate in propagating electronic EOM compared to NAC-based algorithms. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Also notice that the subtle difference between an NPI scheme to evaluate TDCs and the NPI algorithm to propagate electronic EOM. These two are closely related but different. <\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using an overlap-based algorithm is enabled by using keyword <b>coupling overlap<\/b>. <\/p>\n<div class=\"p\"><!----><\/div>\n<p><b>Curvature-driven TDC  <\/b><br \/>\nThe curvature-driven TDC is an approximated TDC that is evaluated from the curvature of potential energy surfaces. Therefore, to compute curvature-driven TDC, one only needs to compute potential energies, neither electronic wave functions nor NACs\/overlaps are need from quantum chemistry software. As pointed out by Baeck and An, NAC in a one-dimensional system can be approximated by<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-241.png\">\n<\/td>\n<td width=\"1%\">(8.211)<\/td>\n<\/tr>\n<\/table>\n<p>For simplicity we have defined<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-242.png\">\n<\/td>\n<td width=\"1%\">(8.212)<\/td>\n<\/tr>\n<\/table>\n<p>where q is a one-dimensional nuclear coordinate, and we have also adapted the original Baeck and An NAC to the current notation, i.e., the original Baeck and An NAC was considering only for internal conversion processes.<br \/>\nWe recognized that a trajectory is in fact propagating on a one-dimensional coordinate which is time. Combining this observation with Baeck and An one-dimensional approximation of NAC gives the definition of curvature-driven TDC (\\kappaupTDC)<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-243.png\"><a id=\"eq:ktdc\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.213)<\/td>\n<\/tr>\n<\/table>\n<p>with<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-244.png\">\n<\/td>\n<td width=\"1%\">(8.214)<\/td>\n<\/tr>\n<\/table>\n<p>Evaluation of the curvature of potential energy with respective to time can be done in two ways, namely by computing first-order differentiation of the time derivative of potential energies from backward finite difference (which is called gradient method), or second-order time derivative of potential energies from backward finite difference (which is called energy method). <\/p>\n<div class=\"p\"><!----><\/div>\n<p>We first discuss the gradient method. The gradient method is controlled by using keyword <b>ktdc_method gradient<\/b>. In thte gradient method, we employ the chain rule<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-245.png\">\n<\/td>\n<td width=\"1%\">(8.215)<\/td>\n<\/tr>\n<\/table>\n<p>Therefore,  (<a href=\"#eq:ktdc\">8.213<\/a>) can be written as<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-246.png\"><a id=\"eq:ktdc_2\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.216)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>If we define<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-247.png\">\n<\/td>\n<td width=\"1%\">(8.217)<\/td>\n<\/tr>\n<\/table>\n<p>and<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-248.png\"><a id=\"eq:ktdc_3\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.218)<\/td>\n<\/tr>\n<\/table>\n<p>then Equation (<a href=\"#eq:ktdc_2\">8.216<\/a>) is approximated by backward finite difference as<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-249.png\"><a id=\"eq:ktdc_4\"><br \/>\n<\/a>\n<\/td>\n<td width=\"1%\">(8.219)<\/td>\n<\/tr>\n<\/table>\n<p>Equations (<a href=\"#eq:ktdc_3\">8.218<\/a>) and (<a href=\"#eq:ktdc_4\">8.219<\/a>) define the gradient method. We can see that gradient method requires computation of gradients of all electronic states.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Next we discuss the energy method. The energy method is controlled by using keyword <b>ktdc_method energy<\/b>. In the energy method, we compute the curvature of potential energy with respective to time directly by backward finite difference as<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-250.png\">\n<\/td>\n<td width=\"1%\">(8.220)<\/td>\n<\/tr>\n<\/table>\n<p>Starting from the fourth step, we can use<\/p>\n<div class=\"p\"><!----><\/div>\n<table border=\"0\" width=\"100%\">\n<tr>\n<td><img decoding=\"async\" src=\"http:\/\/sharc-md.org\/wp-content\/uploads\/2025\/05\/\/equation-251.png\">\n<\/td>\n<td width=\"1%\">(8.221)<\/td>\n<\/tr>\n<\/table>\n<div class=\"p\"><!----><\/div>\n<p>Which method is more practical depends on the details of the simulation.<br \/>\nFor TSH without SOCs, only one gradient is needed per time step.<br \/>\nHence, the gradient method-which requires all gradients-adds significant extra cost and thus for TSH without SOCs it is more convenient to use the energy method.<br \/>\nFor TSH with SOCs (and without gradient selection) or for SCP, all gradients are computed anyways, so using the gradient method does not add extra cost.<br \/>\nThus, the more accurate gradient method is recommended in these cases.<\/p>\n<div class=\"p\"><!----><\/div>\n<p>Using the curvature-driven algorithm is enabled by using keyword <b>coupling ktdc<\/b>. And one can optionally use keyword <b>ktdc_method<\/b> to select either gradient or energy method to compute \\kappaupTDC. Otherwise, the default options for TSH is <b>ktdc_method energy<\/b>, and for SCP is <b>ktdc_method gradient.<\/b><\/p>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n<p> <a id=\"tth_chAp9\"><\/a><\/p>\n<h1>\nChapter 9 <br \/>Bibliography<\/h1>\n<div class=\"p\"><!----><\/div>\n<h2>Bibliography<\/h2>\n<dl>\n<dt><a href=\"#CITEKasha1950DFS\" id=\"Kasha1950DFS\">[1]<\/a><\/dt>\n<dd>\nM. Kasha:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1039\/df9500900014\">“Characterization of<br \/>\n electronic transitions in complex molecules”<\/a>. <em>Discuss. Faraday Soc.<\/em>,<br \/>\n <b>9<\/b>, 14 (1950).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMarian2012WCMS\" id=\"Marian2012WCMS\">[2]<\/a><\/dt>\n<dd>\nC. M. Marian: <a href=\"http:\/\/dx.doi.org\/10.1002\/wcms.83\">“Spin-orbit<br \/>\n coupling and intersystem crossing in molecules”<\/a>. <em>WIREs Comput. Mol.<br \/>\n Sci.<\/em>, <b>2<\/b>, 187-203 (2012).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEWilkinson2014JCP\" id=\"Wilkinson2014JCP\">[3]<\/a><\/dt>\n<dd>\nI. Wilkinson, A. E. Boguslavskiy, J. Mikosch, D. M. Villeneuve, H.-J. Wörner,<br \/>\n M. Spanner, S. Patchkovskii, A. Stolow:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4875035\">“Non-adiabatic and<br \/>\n intersystem crossing dynamics in SO<sub>2<\/sub> I: Bound State Relaxation Studied<br \/>\n By Time-Resolved Photoelectron Photoion Coincidence Spectroscopy”<\/a>. <em>J.<br \/>\n Chem. Phys.<\/em>, <b>140<\/b>, 204 301 (2014).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMai2014JCP_SO2\" id=\"Mai2014JCP_SO2\">[4]<\/a><\/dt>\n<dd>\nS. Mai, P. Marquetand, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4875036\">“Non-Adiabatic Dynamics in<br \/>\n SO<sub>2<\/sub>: II. The Role of Triplet States Studied by Surface-Hopping<br \/>\n Simulations”<\/a>. <em>J. Chem. Phys.<\/em>, <b>140<\/b>, 204 302 (2014).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITELeveque2014JCP_ISC\" id=\"Leveque2014JCP_ISC\">[5]<\/a><\/dt>\n<dd>\nC. Lévêque, R. Taïeb, H. Köppel:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4867252\">“Communication:<br \/>\n Theoretical prediction of the importance of the <sup>3<\/sup>B<sub>2<\/sub> state in the<br \/>\n dynamics of sulfur dioxide”<\/a>. <em>J. Chem. Phys.<\/em>, <b>140<\/b>, 091101<br \/>\n (2014).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPenfold2012JCP\" id=\"Penfold2012JCP\">[6]<\/a><\/dt>\n<dd>\nT. J. Penfold, R. Spesyvtsev, O. M. Kirkby, R. S. Minns, D. S. N. Parker, H. H.<br \/>\n Fielding, G. A. Worth:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4767054\">“Quantum dynamics study of<br \/>\n the competing ultrafast intersystem crossing and internal conversion in the<br \/>\n “channel 3″ region of benzene”<\/a>. <em>J. Chem. Phys.<\/em>, <b>137<\/b>,<br \/>\n 204310 (2012).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEVogt2013JPC\" id=\"Vogt2013JPC\">[7]<\/a><\/dt>\n<dd>\nR. A. Vogt, C. Reichardt, C. E. Crespo-Hernández:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/jp405656n\">“Excited-State Dynamics in<br \/>\n Nitro-Naphthalene Derivatives: Intersystem Crossing to the Triplet Manifold<br \/>\n in Hundreds of Femtoseconds”<\/a>. <em>J. Phys. Chem.<\/em>, <b>117<\/b>,<br \/>\n 6580-6588 (2013).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITECrespo-Hernandez2004CR\" id=\"Crespo-Hernandez2004CR\">[8]<\/a><\/dt>\n<dd>\nC. E. Crespo-Hernández, B. Cohen, P. M. Hare, B. Kohler:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/cr0206770\">“Ultrafast Excited-State<br \/>\n Dynamics in Nucleic Acids”<\/a>. <em>Chem. Rev.<\/em>, <b>104<\/b>, 1977-2020<br \/>\n (2004).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITERichter2012JPCL\" id=\"Richter2012JPCL\">[9]<\/a><\/dt>\n<dd>\nM. Richter, P. Marquetand, J. González-Vázquez, I. Sola, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/jz301312h\">“Femtosecond Intersystem<br \/>\n Crossing in the DNA Nucleobase Cytosine”<\/a>. <em>J. Phys. Chem. Lett.<\/em>,<br \/>\n <b>3<\/b>, 3090-3095 (2012).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMartinez-Fernandez2012CC\" id=\"Martinez-Fernandez2012CC\">[10]<\/a><\/dt>\n<dd>\nL. Martínez-Fernández, L. González, I. Corral:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1039\/C2CC15775F\">“An Ab Initio Mechanism<br \/>\n for Efficient Population of Triplet States in Cytotoxic Sulfur Substituted<br \/>\n DNA Bases: The Case of 6-Thioguanine”<\/a>. <em>Chem. Commun.<\/em>, <b>48<\/b>,<br \/>\n 2134-2136 (2012).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMai2013C\" id=\"Mai2013C\">[11]<\/a><\/dt>\n<dd>\nS. Mai, P. Marquetand, M. Richter, J. González-Vázquez, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1002\/cphc.201300370\">“Singlet and Triplet<br \/>\n Excited-State Dynamics Study of the Keto and Enol Tautomers of Cytosine”<\/a>.<br \/>\n <em>ChemPhysChem<\/em>, <b>14<\/b>, 2920-2931 (2013).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEReichardt2010CC\" id=\"Reichardt2010CC\">[12]<\/a><\/dt>\n<dd>\nC. Reichardt, C. E. Crespo-Hernández:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1039\/C0CC01181A\">“Ultrafast Spin Crossover<br \/>\n in 4-Thiothymidine in an Ionic Liquid”<\/a>. <em>Chem. Commun.<\/em>, <b>46<\/b>,<br \/>\n 5963-5965 (2010).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITETully1971JCP\" id=\"Tully1971JCP\">[13]<\/a><\/dt>\n<dd>\nJ. C. Tully, R. K. Preston:<br \/>\n <a href=\"http:\/\/dx.doi.org\/doi:10.1063\/1.1675788\">“Trajectory Surface<br \/>\n Hopping Approach to Nonadiabatic Molecular Collisions: The Reaction of<br \/>\n H<sup>+<\/sup> with D<sub>2<\/sub>“<\/a>. <em>J. Chem. Phys.<\/em>, <b>55<\/b>, 562-572 (1971).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITETully1990JCP\" id=\"Tully1990JCP\">[14]<\/a><\/dt>\n<dd>\nJ. C. Tully: <a href=\"http:\/\/dx.doi.org\/10.1063\/1.459170\">“Molecular<br \/>\n dynamics with electronic transitions”<\/a>. <em>J. Chem. Phys.<\/em>, <b>93<\/b>,<br \/>\n 1061-1071 (1990).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEBarbatti2011WCMS\" id=\"Barbatti2011WCMS\">[15]<\/a><\/dt>\n<dd>\nM. Barbatti: <a href=\"http:\/\/dx.doi.org\/10.1002\/wcms.64\">“Nonadiabatic<br \/>\n dynamics with trajectory surface hopping method”<\/a>. <em>WIREs Comput. Mol.<br \/>\n Sci.<\/em>, <b>1<\/b>, 620-633 (2011).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITESubotnik2016ARPC\" id=\"Subotnik2016ARPC\">[16]<\/a><\/dt>\n<dd>\nJ. E. Subotnik, A. Jain, B. Landry, A. Petit, W. Ouyang, N. Bellonzi:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1146\/annurev-physchem-040215-112245\">“Understanding<br \/>\n the Surface Hopping View of Electronic Transitions and Decoherence”<\/a>.<br \/>\n <em>Annu. Rev. Phys. Chem.<\/em>, <b>67<\/b>, 387-417 (2016).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEWang2016JPCL\" id=\"Wang2016JPCL\">[17]<\/a><\/dt>\n<dd>\nL. Wang, A. Akimov, O. V. Prezhdo:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jpclett.6b00710\">“Recent Progress<br \/>\n in Surface Hopping: 2011\u20132015”<\/a>. <em>J. Phys. Chem. Lett.<\/em>, <b>7<\/b>,<br \/>\n 2100-2112 (2016).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEDoltsinis2006\" id=\"Doltsinis2006\">[18]<\/a><\/dt>\n<dd>\nN. L. Doltsinis: “Molecular Dynamics Beyond the Born-Oppenheimer<br \/>\n Approximation: Mixed Quantum-Classical Approaches”. In J. Grotendorst,<br \/>\n S. Blügel, D. Marx (editors), <em>Computational Nanoscience: Do It<br \/>\n Yourself!<\/em>, volume 31 of <em>NIC Series<\/em>, 389-409, John von Neuman<br \/>\n Institut for Computing, Jülich (2006).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEDoltsinis2002JTCC\" id=\"Doltsinis2002JTCC\">[19]<\/a><\/dt>\n<dd>\nN. L. Doltsinis, D. Marx:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1142\/S0219633602000257\">“First Principles<br \/>\n Molecular Dynamics Involving Excited States And Nonadiabatic Transitions”<\/a>.<br \/>\n <em>J. Theor. Comput. Chem.<\/em>, <b>1<\/b>, 319-349 (2002).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEHammes-Schiffer1994JCP\" id=\"Hammes-Schiffer1994JCP\">[20]<\/a><\/dt>\n<dd>\nS. Hammes-Schiffer, J. C. Tully:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.467455\">“Proton transfer in<br \/>\n solution: Molecular dynamics with quantum transitions”<\/a>. <em>J. Chem.<br \/>\n Phys.<\/em>, <b>101<\/b>, 4657-4667 (1994).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEGranucci2007JCP\" id=\"Granucci2007JCP\">[21]<\/a><\/dt>\n<dd>\nG. Granucci, M. Persico:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.2715585\">“Critical appraisal of the<br \/>\n fewest switches algorithm for surface hopping”<\/a>. <em>J. Chem. Phys.<\/em>,<br \/>\n <b>126<\/b>, 134 114 (2007).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEThachuk1996JCP\" id=\"Thachuk1996JCP\">[22]<\/a><\/dt>\n<dd>\nM. Thachuk, M. Y. Ivanov, D. M. Wardlaw:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.472281\">“A semiclassical approach<br \/>\n to intense-field above-threshold dissociation in the long wavelength limit”<\/a>.<br \/>\n <em>J. Chem. Phys.<\/em>, <b>105<\/b>, 4094-4104 (1996).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMaiti2004JPCA\" id=\"Maiti2004JPCA\">[23]<\/a><\/dt>\n<dd>\nB. Maiti, G. C. Schatz, G. Lendvay:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/jp049143o\">“Importance of Intersystem<br \/>\n Crossing in the S(3P, 1D) + H2 → SH + H Reaction”<\/a>. <em>J.<br \/>\n Phys. Chem. A<\/em>, <b>108<\/b>, 8772-8781 (2004).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEJones2008JPCA\" id=\"Jones2008JPCA\">[24]<\/a><\/dt>\n<dd>\nG. A. Jones, A. Acocella, F. Zerbetto:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/jp805360v\">“On-the-Fly,<br \/>\n Electric-Field-Driven, Coupled Electron-Nuclear Dynamics”<\/a>. <em>J. Phys.<br \/>\n Chem. A<\/em>, <b>112<\/b>, 9650-9656 (2008).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMitric2009PRA\" id=\"Mitric2009PRA\">[25]<\/a><\/dt>\n<dd>\nR. Mitri\\’c, J. Petersen, V. Bonac\\’c-Koutecký:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1103\/PhysRevA.79.053416\">“Laser-field-induced<br \/>\n surface-hopping method for the simulation and control of ultrafast<br \/>\n photodynamics”<\/a>. <em>Phys. Rev. A<\/em>, <b>79<\/b>, 053 416 (2009).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEGranucci2012JCP\" id=\"Granucci2012JCP\">[26]<\/a><\/dt>\n<dd>\nG. Granucci, M. Persico, G. Spighi:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4707737\">“Surface hopping<br \/>\n trajectory simulations with spin-orbit and dynamical couplings”<\/a>. <em>J.<br \/>\n Chem. Phys.<\/em>, <b>137<\/b>, 22A501 (2012).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITECurchod2013C\" id=\"Curchod2013C\">[27]<\/a><\/dt>\n<dd>\nB. F. E. Curchod, T. J. Penfold, U. Rothlisberger, I. Tavernelli:<br \/>\n <a href=\"http:\/\/dx.doi.org\/doi:10.2533\/chimia.2013.218\">“Local Control<br \/>\n Theory using Trajectory Surface Hopping and Linear-Response Time-Dependent<br \/>\n Density Functional Theory”<\/a>. <em>Chimia<\/em>, <b>67<\/b>, 218-221 (2013).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITECui2014JCP\" id=\"Cui2014JCP\">[28]<\/a><\/dt>\n<dd>\nG. Cui, W. Thiel:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4894849\">“Generalized trajectory<br \/>\n surface-hopping method for internal conversion and intersystem crossing”<\/a>.<br \/>\n <em>J. Chem. Phys.<\/em>, <b>141<\/b>, 124 101 (2014).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMai2018\" id=\"Mai2018\">[29]<\/a><\/dt>\n<dd>\nS. Mai, F. Plasser, P. Marquetand, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1039\/9781788012669-00348\">“General<br \/>\n trajectory surface hopping method for ultrafast nonadiabatic dynamics”<\/a>. In<br \/>\n M. Vrakking, F. Lepine (editors), <em>Attosecond Molecular Dynamics<\/em>,<br \/>\n chapter 10, 348-385, The Royal Society of Chemistry (2018).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEZhu2004JCP\" id=\"Zhu2004JCP\">[30]<\/a><\/dt>\n<dd>\nC. Zhu, S. Nangia, A. W. Jasper, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.1793991\">“Coherent switching with<br \/>\n decay of mixing: An improved treatment of electronic coherence for<br \/>\n non-Born-Oppenheimer trajectories”<\/a>. <em>J. Chem. Phys.<\/em>, <b>121<\/b>,<br \/>\n 7658-7670 (2004).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEShuCSDM2020JCTC\" id=\"ShuCSDM2020JCTC\">[31]<\/a><\/dt>\n<dd>\nY. Shu, L. Zhang, S. Mai, S. Sun, L. González, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.0c00112\">“Implementation of<br \/>\n Coherent Switching with Decay of Mixing into the SHARC Program”<\/a>. <em>J.<br \/>\n Chem. Theory Comput.<\/em>, <b>16<\/b>, 3464-3475 (2020).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEShu2022JCTC\" id=\"Shu2022JCTC\">[32]<\/a><\/dt>\n<dd>\nY. Shu, L. Zhang, X. Chen, S. Sun, Y. Huang, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.1c01080\">“Nonadiabatic<br \/>\n Dynamics Algorithms with Only Potential Energies and Gradients:<br \/>\n Curvature-Driven Coherent Switching with Decay of Mixing and Curvature-Driven<br \/>\n Trajectory Surface Hopping”<\/a>. <em>J. Chem. Theory Comput.<\/em>, <b>18<\/b>,<br \/>\n 1320-1328 (2022).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEZhao2023JCTC2\" id=\"Zhao2023JCTC2\">[33]<\/a><\/dt>\n<dd>\nX. Zhao, I. C. D. Merritt, R. Lei, Y. Shu, D. Jacquemin, L. Zhang, X. Xu,<br \/>\n M. Vacher, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.3c00813\">“Nonadiabatic<br \/>\n Coupling in Trajectory Surface Hopping: Accurate Time<br \/>\n Derivative Couplings by the Curvature-Driven Approximation”<\/a>.<br \/>\n <em>J. Chem. Theory Comput.<\/em>, <b>19<\/b>, 6577-6588 (2023).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMausenberger2025Chemrxiv\" id=\"Mausenberger2025Chemrxiv\">[34]<\/a><\/dt>\n<dd>\nS. Mausenberger, S. Polonius, S. Mai, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.xxxx\/xxxxxx\">“Efficient, Hierarchical, and<br \/>\n Object-Oriented Electronic Structure Interfaces for Direct Nonadiabatic<br \/>\n Dynamics Simulations”<\/a>. <em>Chemarxiv<\/em> (2025).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPlasser2018PCCP\" id=\"Plasser2018PCCP\">[35]<\/a><\/dt>\n<dd>\nF. Plasser, S. Goméz, S. Mai, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1039\/C8CP05662E\">“Highly efficient surface<br \/>\n hopping dynamics using a linear vibronic coupling model”<\/a>. <em>Phys. Chem.<br \/>\n Chem. Phys.<\/em>, Advance Article, DOI:10.1039\/C8CP05 662E (2018).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPolonius2023JCTC\" id=\"Polonius2023JCTC\">[36]<\/a><\/dt>\n<dd>\nS. Polonius, O. Zhuravel, B. Bachmair, S. Mai:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.3c00805\">“LVC\/MM: A Hybrid<br \/>\n Linear Vibronic Coupling\/Molecular Mechanics Model with Distributed<br \/>\n Multipole-Based Electrostatic Embedding for Highly Efficient Surface Hopping<br \/>\n Dynamics in Solution”<\/a>. <em>J. Chem. Theory Comput.<\/em>, <b>19<\/b>,<br \/>\n 7171\u20137186 (2023).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPolonius2024JCTC\" id=\"Polonius2024JCTC\">[37]<\/a><\/dt>\n<dd>\nS. Polonius, D. Lehrner, L. Gonz\u00e1lez, S. Mai:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.4c00169\">“Resolving<br \/>\n Photoinduced Femtosecond Three-Dimensional Solute\u2013Solvent Dynamics through<br \/>\n Surface Hopping Simulations”<\/a>. <em>J. Chem. Theory Comput.<\/em>, <b>20<\/b>,<br \/>\n 4738\u20134750 (2024).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPittner2009CP\" id=\"Pittner2009CP\">[38]<\/a><\/dt>\n<dd>\nJ. Pittner, H. Lischka, M. Barbatti:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1016\/j.chemphys.2008.10.013\">“Optimization<br \/>\n of mixed quantum-classical dynamics: Time-derivative coupling terms and<br \/>\n selected couplings”<\/a>. <em>Chem. Phys.<\/em>, <b>356<\/b>, 147 – 152 (2009).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEJain2016JCTC\" id=\"Jain2016JCTC\">[39]<\/a><\/dt>\n<dd>\nA. Jain, E. Alguire, J. E. Subotnik:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.6b00673\">“An Efficient,<br \/>\n Augmented Surface Hopping Algorithm That Includes Decoherence for Use in<br \/>\n Large-Scale Simulations”<\/a>. <em>J. Chem. Theory Comput.<\/em>, <b>12<\/b>,<br \/>\n 5256-5268 (2016).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEZhuSCDM2004JCP\" id=\"ZhuSCDM2004JCP\">[40]<\/a><\/dt>\n<dd>\nC. Zhu, A. W. Jasper, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.1648306\">“Non-Born-Oppenheimer<br \/>\n Trajectories with Self-Consistent Decay of Mixing”<\/a>. <em>J. Chem. Phys.<\/em>,<br \/>\n <b>120<\/b> (2004).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITERuckenbauer2016SR\" id=\"Ruckenbauer2016SR\">[41]<\/a><\/dt>\n<dd>\nM. Ruckenbauer, S. Mai, P. Marquetand, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1038\/srep35522\">“Revealing Deactivation<br \/>\n Pathways Hidden in Time-Resolved Photoelectron Spectra”<\/a>. <em>Sci. Rep.<\/em>,<br \/>\n <b>6<\/b>, 35 522 (2016).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPlasser2014JCP1\" id=\"Plasser2014JCP1\">[42]<\/a><\/dt>\n<dd>\nF. Plasser, M. Wormit, A. Dreuw:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4885819\">“New tools for the<br \/>\n systematic analysis and visualization of electronic excitations. I.<br \/>\n Formalism”<\/a>. <em>J. Chem. Phys.<\/em>, <b>141<\/b>, 024 106 (2014).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPlasser2014JCP2\" id=\"Plasser2014JCP2\">[43]<\/a><\/dt>\n<dd>\nF. Plasser, S. A. Bäppler, M. Wormit, A. Dreuw:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4885820\">“New tools for the<br \/>\n systematic analysis and visualization of electronic excitations. II.<br \/>\n Applications”<\/a>. <em>J. Chem. Phys.<\/em>, <b>141<\/b>, 024 107 (2014).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPlasser2017TheoDORE\" id=\"Plasser2017TheoDORE\">[44]<\/a><\/dt>\n<dd>\nF. Plasser: “TheoDORE: A package for theoretical density, orbital<br \/>\n relaxation, and exciton analysis”. http:\/\/theodore-qc.sourceforge.net (2017).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEFarkhutdinova2025JPCA\" id=\"Farkhutdinova2025JPCA\">[45]<\/a><\/dt>\n<dd>\nD. Farkhutdinova, S. Polonius, P. Karrer, S. Mai, L. Gonz\u00e1lez:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jpca.4c07472\">“Parametrization of<br \/>\n Linear Vibronic Coupling Models for Degenerate Electronic States”<\/a>. <em>J.<br \/>\n Phys. Chem. A<\/em>, <b>129<\/b>, 2655\u20132666 (2025).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMai2018WCMS\" id=\"Mai2018WCMS\">[46]<\/a><\/dt>\n<dd>\nS. Mai, P. Marquetand, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1002\/wcms.1370\">“Nonadiabatic dynamics:<br \/>\n The SHARC approach”<\/a>. <em>WIREs Comput. Mol. Sci.<\/em>, <b>8<\/b>, e1370<br \/>\n (2018).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMai2025SHARC\" id=\"Mai2025SHARC\">[47]<\/a><\/dt>\n<dd>\nS. Mai, B. Bachmair, L. Gagliardi, H.-G. Gallmetzer, L. Grünewald, M. R.<br \/>\n Hennefarth, N. M. Høyer, F. A. Korsaye, S. Mausenberger, M. Oppel,<br \/>\n T. Pitesa, S. Polonius, E. S. Gil, Y. Shu, N. K. Singer, M. X.<br \/>\n Tiefenbacher, D. G. Truhlar, D. Vörös, L. Zhang, L. González:<br \/>\n “SHARC4.0: Surface Hopping Including Arbitrary Couplings – Program<br \/>\n Package for Non-Adiabatic Dynamics”. https:\/\/sharc-md.org\/ (2025).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITERichter2011JCTC\" id=\"Richter2011JCTC\">[48]<\/a><\/dt>\n<dd>\nM. Richter, P. Marquetand, J. González-Vázquez, I. Sola, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/ct1007394\">“SHARC: Ab Initio<br \/>\n Molecular Dynamics with Surface Hopping in the Adiabatic Representation<br \/>\n Including Arbitrary Couplings”<\/a>. <em>J. Chem. Theory Comput.<\/em>, <b>7<\/b>,<br \/>\n 1253-1258 (2011).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITERichter2012JCTC_erratum\" id=\"Richter2012JCTC_erratum\">[49]<\/a><\/dt>\n<dd>\nM. Richter, P. Marquetand, J. González-Vázquez, I. Sola, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/ct2005819\">“Correction to SHARC: Ab<br \/>\n Initio Molecular Dynamics with Surface Hopping in the Adiabatic<br \/>\n Representation Including Arbitrary Couplings”<\/a>. <em>J. Chem. Theory<br \/>\n Comput.<\/em>, <b>8<\/b>, 374-374 (2012).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMai2015IJQC\" id=\"Mai2015IJQC\">[50]<\/a><\/dt>\n<dd>\nS. Mai, P. Marquetand, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1002\/qua.24891\">“A General Method to<br \/>\n Describe Intersystem Crossing Dynamics in Trajectory Surface Hopping”<\/a>.<br \/>\n <em>Int. J. Quantum Chem.<\/em>, <b>115<\/b>, 1215-1231 (2015).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEWang2014JCTC\" id=\"Wang2014JCTC\">[51]<\/a><\/dt>\n<dd>\nL. Wang, D. Trivedi, O. V. Prezhdo:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/ct5003835\">“Global Flux Surface<br \/>\n Hopping Approach for Mixed Quantum-Classical Dynamics”<\/a>. <em>J. Chem.<br \/>\n Theory Comput.<\/em>, <b>10<\/b>, 3598-3605 (2014).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEGranucci2001JCP\" id=\"Granucci2001JCP\">[52]<\/a><\/dt>\n<dd>\nG. Granucci, M. Persico, A. Toniolo:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.1376633\">“Direct Semiclassical<br \/>\n Simulation of Photochemical Processes with Semiempirical Wave Functions”<\/a>.<br \/>\n <em>J. Chem. Phys.<\/em>, <b>114<\/b>, 10 608-10 615 (2001).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPlasser2012JCP\" id=\"Plasser2012JCP\">[53]<\/a><\/dt>\n<dd>\nF. Plasser, G. Granucci, J. Pittner, M. Barbatti, M. Persico, H. Lischka:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4738960\">“Surface Hopping Dynamics<br \/>\n using a Locally Diabatic Formalism: Charge Transfer in The Ethylene Dimer<br \/>\n Cation and Excited State Dynamics in the 2-Pyridone Dimer”<\/a>. <em>J. Chem.<br \/>\n Phys.<\/em>, <b>137<\/b>, 22A514 (2012).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPlasser2016JCTC\" id=\"Plasser2016JCTC\">[54]<\/a><\/dt>\n<dd>\nF. Plasser, M. Ruckenbauer, S. Mai, M. Oppel, P. Marquetand, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.5b01148\">“Efficient and<br \/>\n Flexible Computation of Many-Electron Wave Function Overlaps”<\/a>. <em>J.<br \/>\n Chem. Theory Comput.<\/em>, <b>12<\/b>, 1207 (2016).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEDahl1988JCP\" id=\"Dahl1988JCP\">[55]<\/a><\/dt>\n<dd>\nJ. P. Dahl, M. Springborg:<br \/>\n <a href=\"http:\/\/dx.doi.org\/doi:10.1063\/1.453761\">“The Morse oscillator<br \/>\n in position space, momentum space, and phase space”<\/a>. <em>J. Chem. Phys.<\/em>,<br \/>\n <b>88<\/b>, 4535-4547 (1988).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITESchinke1995\" id=\"Schinke1995\">[56]<\/a><\/dt>\n<dd>\nR. Schinke: <em>Photodissociation Dynamics: Spectroscopy and Fragmentation of<br \/>\n Small Polyatomic Molecules<\/em>. Cambridge University Press (1995).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEBarbatti2016IJQC\" id=\"Barbatti2016IJQC\">[57]<\/a><\/dt>\n<dd>\nM. Barbatti, K. Sen:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1002\/qua.25049\">“Effects of different<br \/>\n initial condition samplings on photodynamics and spectrum of pyrrole”<\/a>.<br \/>\n <em>Int. J. Quantum Chem.<\/em>, <b>116<\/b>, 762-771 (2016).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEBarbatti2007JPPA\" id=\"Barbatti2007JPPA\">[58]<\/a><\/dt>\n<dd>\nM. Barbatti, G. Granucci, M. Persico, M. Ruckenbauer, M. Vazdar,<br \/>\n M. Eckert-Maksi\\’c, H. Lischka:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1016\/j.jphotochem.2006.12.008\">“The<br \/>\n on-the-fly surface-hopping program system Newton-X: Application to ab<br \/>\n initio simulation of the nonadiabatic photodynamics of benchmark systems”<\/a>.<br \/>\n <em>J. Photochem. Photobiol. A<\/em>, <b>190<\/b>, 228-240 (2007).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEBajo2012JPCA\" id=\"Bajo2012JPCA\">[59]<\/a><\/dt>\n<dd>\nJ. J. Bajo, J. González-Vázquez, I. Sola, J. Santamaria, M. Richter,<br \/>\n P. Marquetand, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/jp208997r\">“Mixed Quantum-Classical<br \/>\n Dynamics in the Adiabatic Representation to Simulate Molecules Driven by<br \/>\n Strong Laser Pulses”<\/a>. <em>J. Phys. Chem. A<\/em>, <b>116<\/b>, 2800-2807<br \/>\n (2012).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMarquetand2011FD\" id=\"Marquetand2011FD\">[60]<\/a><\/dt>\n<dd>\nP. Marquetand, M. Richter, J. González-Vázquez, I. Sola, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1039\/c1fd00055a\">“Nonadiabatic ab initio<br \/>\n molecular dynamics including spin-orbit coupling and laser fields”<\/a>.<br \/>\n <em>Faraday Discuss.<\/em>, <b>153<\/b>, 261-273 (2011).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEHeindl2021JCP\" id=\"Heindl2021JCP\">[61]<\/a><\/dt>\n<dd>\nM. Heindl, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/5.0044807\">“Validating<br \/>\n fewest-switches surface hopping in the presence of laser fields”<\/a>. <em>J.<br \/>\n Chem. Phys.<\/em>, <b>154<\/b> (2021).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITECremer1975JACS\" id=\"Cremer1975JACS\">[62]<\/a><\/dt>\n<dd>\nD. Cremer, J. A. Pople:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/ja00839a011\">“General definition of<br \/>\n ring puckering coordinates”<\/a>. <em>J. Am. Chem. Soc.<\/em>, <b>97<\/b>,<br \/>\n 1354-1358 (1975).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEBoeyens1976JCMS\" id=\"Boeyens1976JCMS\">[63]<\/a><\/dt>\n<dd>\nJ. C. A. Boeyens: <a href=\"http:\/\/dx.doi.org\/10.1007\/BF01200485\">“The<br \/>\n conformation of six-membered rings”<\/a>. <em>J. Cryst. Mol. Struct.<\/em>,<br \/>\n <b>8<\/b>, 317 (1978).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEKurtz2001JCP\" id=\"Kurtz2001JCP\">[64]<\/a><\/dt>\n<dd>\nL. Kurtz, A. Hofmann, R. de Vivie-Riedle:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.1355658\">“Ground state normal mode<br \/>\n analysis: Linking excited state dynamics and experimental observables”<\/a>.<br \/>\n <em>J. Chem. Phys.<\/em>, <b>114<\/b>, 6151-6159 (2001).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPlasser2009\" id=\"Plasser2009\">[65]<\/a><\/dt>\n<dd>\nF. Plasser: <em>Dynamics Simulation of Excited State Intramolecular Proton<br \/>\n Transfer<\/em>. Master’s thesis, University of Vienna (2009).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEAmadei1993PSFB\" id=\"Amadei1993PSFB\">[66]<\/a><\/dt>\n<dd>\nA. Amadei, A. B. M. Linssen, H. J. C. Berendsen:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1002\/prot.340170408\">“Essential dynamics<br \/>\n of proteins”<\/a>. <em>Proteins: Struct., Funct., Bioinf.<\/em>, <b>17<\/b>,<br \/>\n 412-425 (1993).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITENangia2004JCP\" id=\"Nangia2004JCP\">[67]<\/a><\/dt>\n<dd>\nS. Nangia, A. W. Jasper, T. F. Miller, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.1641019\">“Army Ants Algorithm for<br \/>\n Rare Event Sampling of Delocalized Nonadiabatic Transitions by Trajectory<br \/>\n Surface Hopping and the Estimation of Sampling Errors by the Bootstrap<br \/>\n Method”<\/a>. <em>J. Chem. Phys.<\/em>, <b>120<\/b>, 3586-3597 (2004).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEBearpark1994CPL\" id=\"Bearpark1994CPL\">[68]<\/a><\/dt>\n<dd>\nM. J. Bearpark, M. A. Robb, H. B. Schlegel:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1016\/0009-2614(94)00433-1\">“A direct<br \/>\n method for the location of the lowest energy point on a potential surface<br \/>\n crossing”<\/a>. <em>Chem. Phys. Lett.<\/em>, <b>223<\/b>, 269 (1994).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITELevine2008JPCB\" id=\"Levine2008JPCB\">[69]<\/a><\/dt>\n<dd>\nB. G. Levine, J. D. Coe, T. J. Martínez:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/jp0761618\">“Optimizing Conical<br \/>\n Intersections without Derivative Coupling Vectors: Application to Multistate<br \/>\n Multireference Second-Order Perturbation Theory (MS-CASPT2)”<\/a>. <em>J.<br \/>\n Phys. Chem. B<\/em>, <b>112<\/b>, 405-413 (2008).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITERuckenbauer2016JCP\" id=\"Ruckenbauer2016JCP\">[70]<\/a><\/dt>\n<dd>\nM. Ruckenbauer, S. Mai, P. Marquetand, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4941948\">“Photoelectron spectra of<br \/>\n 2-thiouracil, 4-thiouracil, and 2,4-dithiouracil”<\/a>. <em>J. Chem. Phys.<\/em>,<br \/>\n <b>144<\/b>, 074 303 (2016).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPlasser2016JCP\" id=\"Plasser2016JCP\">[71]<\/a><\/dt>\n<dd>\nF. Plasser, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4958462\">“Communication:<br \/>\n Unambiguous comparison of many-electron wavefunctions through their<br \/>\n overlaps”<\/a>. <em>J. Chem. Phys.<\/em>, <b>145<\/b>, 021 103 (2016).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEGomez2019JPCA\" id=\"Gomez2019JPCA\">[72]<\/a><\/dt>\n<dd>\nS. Gómez, M. Heindl, A. Szabadi, L. González:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jpca.9b06103\">“From Surface<br \/>\n Hopping to Quantum Dynamics and Back. Finding Essential Electronic and<br \/>\n Nuclear Degrees of Freedom and Optimal Surface Hopping Parameters”<\/a>. <em>J.<br \/>\n Phys. Chem. A<\/em>, <b>123<\/b>, 8321\u20138332 (2019).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITELandry2013JCP\" id=\"Landry2013JCP\">[73]<\/a><\/dt>\n<dd>\nB. R. Landry, M. J. Falk, J. E. Subotnik:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.4837795\">“Communication: The<br \/>\n correct interpretation of surface hopping trajectories: How to calculate<br \/>\n electronic properties”<\/a>. <em>J. Chem. Phys.<\/em>, <b>139<\/b>, 211 101<br \/>\n (2013).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEWestermayr2020JPCL\" id=\"Westermayr2020JPCL\">[74]<\/a><\/dt>\n<dd>\nJ. Westermayr, M. Gastegger, P. Marquetand:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jpclett.0c00527\">“Combining<br \/>\n SchNet and SHARC: The SchNarc Machine Learning Approach for Excited-State<br \/>\n Dynamics”<\/a>. <em>J. Phys. Chem. Lett.<\/em>, <b>11<\/b>, 3828-3834 (2020).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEShutCSDM2020JCTC\" id=\"ShutCSDM2020JCTC\">[75]<\/a><\/dt>\n<dd>\nY. Shu, L. Zhang, S. Sun, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.0c00409\">“Time-Derivative<br \/>\n Couplings for Self-Consistent Electronically Nonadiabatic Dynamics”<\/a>.<br \/>\n <em>J. Chem. Theory Comput.<\/em>, <b>16<\/b>, 4098-4106 (2020).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEShu2020JPCL\" id=\"Shu2020JPCL\">[76]<\/a><\/dt>\n<dd>\nY. Shu, L. Zhang, Z. Varga, K. A. Parker, S. Kanchanakungwankul, S. Sun, D. G.<br \/>\n Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jpclett.9b03749\">“Conservation of<br \/>\n Angular Momentum in Direct Nonadiabatic Dynamics”<\/a>. <em>J. Phys. Chem.<br \/>\n Lett.<\/em>, <b>11<\/b>, 1135-1140 (2020).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEShuTDM2023JCTC\" id=\"ShuTDM2023JCTC\">[77]<\/a><\/dt>\n<dd>\nY. Shu, L. Zhang, D. Wu, X. Chen, S. Sun, D. G. Truhlar: “New Gradient<br \/>\n Correction Scheme for Electronically Nonadiabatic Dynamics Involving Multiple<br \/>\n Spin States”. <em>J. Chem. Theory Comput.<\/em> (2023).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEJasper2002JCP\" id=\"Jasper2002JCP\">[78]<\/a><\/dt>\n<dd>\nA. W. Jasper, S. N. Stechmann, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.1453404\">“Fewest-switches with time<br \/>\n uncertainty: A modified trajectory surface-hopping algorithm with better<br \/>\n accuracy for classically forbidden electronic transitions”<\/a>. <em>J. Chem.<br \/>\n Phys.<\/em>, <b>116<\/b>, 5424-5431 (2002).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEZhao2023JCTC\" id=\"Zhao2023JCTC\">[79]<\/a><\/dt>\n<dd>\nX. Zhao, Y. Shu, L. Zhang, X. Xu, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.2c01260\">“Direct<br \/>\n Nonadiabatic Dynamics of Ammonia with Curvature-Driven Coherent Switching<br \/>\n with Decay of Mixing and with Fewest Switches with Time Uncertainty: An<br \/>\n Illustration of Population Leaking in Trajectory Surface Hopping Due to<br \/>\n Frustrated Hops”<\/a>. <em>J. Chem. Theory Comput.<\/em>, <b>19<\/b>, 1672-1685<br \/>\n (2023).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEBaerends2025JCP\" id=\"Baerends2025JCP\">[80]<\/a><\/dt>\n<dd>\nE. J. Baerends, N. F. Aguirre, N. D. Austin, J. Autschbach, F. M. Bickelhaupt,<br \/>\n R. Bulo, C. Cappelli, A. C. T. van Duin, F. Egidi, C. Fonseca Guerra,<br \/>\n A. Förster, M. Franchini, T. P. M. Goumans, T. Heine, M. Hellström,<br \/>\n C. R. Jacob, L. Jensen, M. Krykunov, E. van Lenthe, A. Michalak, M. M.<br \/>\n Mitoraj, J. Neugebauer, V. P. Nicu, P. Philipsen, H. Ramanantoanina,<br \/>\n R. Rüger, G. Schreckenbach, M. Stener, M. Swart, J. M. Thijssen,<br \/>\n T. Trnka, L. Visscher, A. Yakovlev, S. van Gisbergen:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/5.0258496\">“The Amsterdam Modeling<br \/>\n Suite”<\/a>. <em>J. Chem. Phys.<\/em>, <b>162<\/b> (2025).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEShiozaki2018WCMS\" id=\"Shiozaki2018WCMS\">[81]<\/a><\/dt>\n<dd>\nT. Shiozaki: <a href=\"http:\/\/dx.doi.org\/10.1002\/wcms.1331\">“BAGEL:<br \/>\n Brilliantly Advanced General Electronic-structure Library”<\/a>. <em>WIREs<br \/>\n Comput. Mol. Sci.<\/em>, <b>8<\/b>, e1331 (2018).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITELischka2011WCMS\" id=\"Lischka2011WCMS\">[82]<\/a><\/dt>\n<dd>\nH. Lischka, T. Müller, P. G. Szalay, I. Shavitt, R. M. Pitzer, R. Shepard:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1002\/wcms.25\">“Columbus – a program<br \/>\n system for advanced multireference theory calculations.”<\/a> <em>WIREs Comput.<br \/>\n Mol. Sci.<\/em>, <b>1<\/b>, 191-199 (2011).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEGaussian16\" id=\"Gaussian16\">[83]<\/a><\/dt>\n<dd>\nM. J. Frisch, G. W. Trucks, H. B. Schlegel, G. E. Scuseria, M. A. Robb, J. R.<br \/>\n Cheeseman, G. Scalmani, V. Barone, G. A. Petersson, H. Nakatsuji, X. Li,<br \/>\n M. Caricato, A. V. Marenich, J. Bloino, B. G. Janesko, R. Gomperts,<br \/>\n B. Mennucci, H. P. Hratchian, J. V. Ortiz, A. F. Izmaylov, J. L. Sonnenberg,<br \/>\n D. Williams-Young, F. Ding, F. Lipparini, F. Egidi, J. Goings, B. Peng,<br \/>\n A. Petrone, T. Henderson, D. Ranasinghe, V. G. Zakrzewski, J. Gao, N. Rega,<br \/>\n G. Zheng, W. Liang, M. Hada, M. Ehara, K. Toyota, R. Fukuda, J. Hasegawa,<br \/>\n M. Ishida, T. Nakajima, Y. Honda, O. Kitao, H. Nakai, T. Vreven,<br \/>\n K. Throssell, J. A. Montgomery, Jr., J. E. Peralta, F. Ogliaro, M. J.<br \/>\n Bearpark, J. J. Heyd, E. N. Brothers, K. N. Kudin, V. N. Staroverov, T. A.<br \/>\n Keith, R. Kobayashi, J. Normand, K. Raghavachari, A. P. Rendell, J. C.<br \/>\n Burant, S. S. Iyengar, J. Tomasi, M. Cossi, J. M. Millam, M. Klene, C. Adamo,<br \/>\n R. Cammi, J. W. Ochterski, R. L. Martin, K. Morokuma, O. Farkas, J. B.<br \/>\n Foresman, D. J. Fox: “Gaussian16 Revision A.03” (2016), gaussian<br \/>\n Inc. Wallingford CT.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITELiManni2023JCTC\" id=\"LiManni2023JCTC\">[84]<\/a><\/dt>\n<dd>\nG. Li Manni, I. Fdez. Galván, A. Alavi, F. Aleotti, F. Aquilante,<br \/>\n J. Autschbach, D. Avagliano, A. Baiardi, J. J. Bao, S. Battaglia,<br \/>\n L. Birnoschi, A. Blanco-González, S. I. Bokarev, R. Broer, R. Cacciari,<br \/>\n P. B. Calio, R. K. Carlson, R. Carvalho Couto, L. Cerdán, L. F.<br \/>\n Chibotaru, N. F. Chilton, J. R. Church, I. Conti, S. Coriani,<br \/>\n J. Cuéllar-Zuquin, R. E. Daoud, N. Dattani, P. Decleva, C. de Graaf,<br \/>\n M. G. Delcey, L. De Vico, W. Dobrautz, S. S. Dong, R. Feng, N. Ferré,<br \/>\n M. Filatov(Gulak), L. Gagliardi, M. Garavelli, L. González, Y. Guan,<br \/>\n M. Guo, M. R. Hennefarth, M. R. Hermes, C. E. Hoyer, M. Huix-Rotllant, V. K.<br \/>\n Jaiswal, A. Kaiser, D. S. Kaliakin, M. Khamesian, D. S. King, V. Kochetov,<br \/>\n M. Kro\\’snicki, A. A. Kumaar, E. D. Larsson, S. Lehtola, M.-B. Lepetit,<br \/>\n H. Lischka, P. López Ríos, M. Lundberg, D. Ma, S. Mai,<br \/>\n P. Marquetand, I. C. D. Merritt, F. Montorsi, M. Mörchen, A. Nenov,<br \/>\n V. H. A. Nguyen, Y. Nishimoto, M. S. Oakley, M. Olivucci, M. Oppel,<br \/>\n D. Padula, R. Pandharkar, Q. M. Phung, F. Plasser, G. Raggi, E. Rebolini,<br \/>\n M. Reiher, I. Rivalta, D. Roca-Sanjuán, T. Romig, A. A. Safari,<br \/>\n A. Sánchez-Mansilla, A. M. Sand, I. Schapiro, T. R. Scott,<br \/>\n J. Segarra-Martí, F. Segatta, D.-C. Sergentu, P. Sharma, R. Shepard,<br \/>\n Y. Shu, J. K. Staab, T. P. Straatsma, L. K. Sørensen, B. N. C. Tenorio,<br \/>\n D. G. Truhlar, L. Ungur, M. Vacher, V. Veryazov, T. A. Voß, O. Weser,<br \/>\n D. Wu, X. Yang, D. Yarkony, C. Zhou, J. P. Zobel, R. Lindh:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.3c00182\">“The OpenMolcas<br \/>\n Web: A Community-Driven Approach to Advancing Computational Chemistry”<\/a>.<br \/>\n <em>J. Chem. Theory Comput.<\/em>, <b>19<\/b>, 6933\u20136991 (2023).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEWerner2020JCP\" id=\"Werner2020JCP\">[85]<\/a><\/dt>\n<dd>\nH.-J. Werner, P. J. Knowles, F. R. Manby, J. A. Black, K. Doll, A. He\u00dfelmann,<br \/>\n D. Kats, A. Köhn, T. Korona, D. A. Kreplin, Q. Ma, T. F. Miller,<br \/>\n A. Mitrushchenkov, K. A. Peterson, I. Polyak, G. Rauhut, M. Sibaev:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/5.0005081\">“The Molpro quantum<br \/>\n chemistry package”<\/a>. <em>J. Chem. Phys.<\/em>, <b>152<\/b> (2020).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEStewart1990MOPAC\" id=\"Stewart1990MOPAC\">[86]<\/a><\/dt>\n<dd>\nJ. J. P. Stewart: <a href=\"http:\/\/dx.doi.org\/10.1007\/bf00128336\">“MOPAC: A<br \/>\n semiempirical molecular orbital program”<\/a>. <em>Journal of Computer-Aided<br \/>\n Molecular Design<\/em>, <b>4<\/b>, 1\u2013103 (1990).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMopac-pi\" id=\"Mopac-pi\">[87]<\/a><\/dt>\n<dd>\nG. Granucci, M. Persico, D. Accomasso, E. Sangiogo Gil, S. Corni, J. Fregoni,<br \/>\n T. Laino, M. Tesi, A. Toniolo: “MOPAC-PI: a program for excited<br \/>\n state dynamics simulations based on nonadiabatic trajectories and<br \/>\n semiempirical electronic structure calculations” (2024).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEApra2020JCP\" id=\"Apra2020JCP\">[88]<\/a><\/dt>\n<dd>\nE. Aprà, E. J. Bylaska, W. A. de Jong, N. Govind, K. Kowalski, T. P.<br \/>\n Straatsma, M. Valiev, H. J. J. van Dam, Y. Alexeev, J. Anchell, V. Anisimov,<br \/>\n F. W. Aquino, R. Atta-Fynn, J. Autschbach, N. P. Bauman, J. C. Becca, D. E.<br \/>\n Bernholdt, K. Bhaskaran-Nair, S. Bogatko, P. Borowski, J. Boschen, J. Brabec,<br \/>\n A. Bruner, E. Cauët, Y. Chen, G. N. Chuev, C. J. Cramer, J. Daily,<br \/>\n M. J. O. Deegan, T. H. Dunning, M. Dupuis, K. G. Dyall, G. I. Fann, S. A.<br \/>\n Fischer, A. Fonari, H. Früchtl, L. Gagliardi, J. Garza, N. Gawande,<br \/>\n S. Ghosh, K. Glaesemann, A. W. Götz, J. Hammond, V. Helms, E. D. Hermes,<br \/>\n K. Hirao, S. Hirata, M. Jacquelin, L. Jensen, B. G. Johnson, H. Jónsson,<br \/>\n R. A. Kendall, M. Klemm, R. Kobayashi, V. Konkov, S. Krishnamoorthy,<br \/>\n M. Krishnan, Z. Lin, R. D. Lins, R. J. Littlefield, A. J. Logsdail,<br \/>\n K. Lopata, W. Ma, A. V. Marenich, J. Martin del Campo, D. Mejia-Rodriguez,<br \/>\n J. E. Moore, J. M. Mullin, T. Nakajima, D. R. Nascimento, J. A. Nichols,<br \/>\n P. J. Nichols, J. Nieplocha, A. Otero-de-la Roza, B. Palmer, A. Panyala,<br \/>\n T. Pirojsirikul, B. Peng, R. Peverati, J. Pittner, L. Pollack, R. M. Richard,<br \/>\n P. Sadayappan, G. C. Schatz, W. A. Shelton, D. W. Silverstein, D. M. A.<br \/>\n Smith, T. A. Soares, D. Song, M. Swart, H. L. Taylor, G. S. Thomas,<br \/>\n V. Tipparaju, D. G. Truhlar, K. Tsemekhman, T. Van Voorhis,<br \/>\n Á. Vázquez-Mayagoitia, P. Verma, O. Villa, A. Vishnu, K. D.<br \/>\n Vogiatzis, D. Wang, J. H. Weare, M. J. Williamson, T. L. Windus,<br \/>\n K. Woli\\’nski, A. T. Wong, Q. Wu, C. Yang, Q. Yu, M. Zacharias, Z. Zhang,<br \/>\n Y. Zhao, R. J. Harrison:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/5.0004997\">“NWChem: Past, present,<br \/>\n and future”<\/a>. <em>J. Phys. Chem.<\/em>, <b>152<\/b> (2020).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITESun2020JCP\" id=\"Sun2020JCP\">[89]<\/a><\/dt>\n<dd>\nQ. Sun, X. Zhang, S. Banerjee, P. Bao, M. Barbry, N. S. Blunt, N. A. Bogdanov,<br \/>\n G. H. Booth, J. Chen, Z.-H. Cui, J. J. Eriksen, Y. Gao, S. Guo, J. Hermann,<br \/>\n M. R. Hermes, K. Koh, P. Koval, S. Lehtola, Z. Li, J. Liu, N. Mardirossian,<br \/>\n J. D. McClain, M. Motta, B. Mussard, H. Q. Pham, A. Pulkin, W. Purwanto,<br \/>\n P. J. Robinson, E. Ronca, E. R. Sayfutyarova, M. Scheurer, H. F. Schurkus,<br \/>\n J. E. T. Smith, C. Sun, S.-N. Sun, S. Upadhyay, L. K. Wagner, X. Wang,<br \/>\n A. White, J. D. Whitfield, M. J. Williamson, S. Wouters, J. Yang, J. M. Yu,<br \/>\n T. Zhu, T. C. Berkelbach, S. Sharma, A. Y. Sokolov, G. K.-L. Chan:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/5.0006074\">“Recent developments in<br \/>\n the PySCF program package”<\/a>. <em>J. Phys. Chem.<\/em>, <b>153<\/b> (2020).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEHennefarth2024JCTC\" id=\"Hennefarth2024JCTC\">[90]<\/a><\/dt>\n<dd>\nM. R. Hennefarth, D. G. Truhlar, L. Gagliardi:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.4c01061\">“Semiclassical<br \/>\n Nonadiabatic Molecular Dynamics Using Linearized Pair-Density Functional<br \/>\n Theory”<\/a>. <em>J. Chem. Theory Comput.<\/em>, <b>20<\/b>, 8741\u20138748 (2024).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITENeese2017WCMS\" id=\"Neese2017WCMS\">[91]<\/a><\/dt>\n<dd>\nF. Neese: <a href=\"http:\/\/dx.doi.org\/10.1002\/wcms.81\">“Software update:<br \/>\n the ORCA program system, version 4.0”<\/a>. <em>WIREs Comput. Mol. Sci.<\/em>,<br \/>\n <b>8<\/b>, e1327 (2017).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITETURBOMOLE70\" id=\"TURBOMOLE70\">[92]<\/a><\/dt>\n<dd>\n“TURBOMOLE V7.0, A development of University of Karlsruhe and<br \/>\n Forschungszentrum Karlsruhe GmbH” (2015).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMeek2014JPCL\" id=\"Meek2014JPCL\">[93]<\/a><\/dt>\n<dd>\nG. A. Meek, B. G. Levine:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/jz5009449\">“Evaluation of the<br \/>\n Time-Derivative Coupling for Accurate Electronic State Transition<br \/>\n Probabilities from Numerical Simulations”<\/a>. <em>J. Phys. Chem. Lett.<\/em>,<br \/>\n <b>5<\/b>, 2351-2356 (2014).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEGranucci2010JCP\" id=\"Granucci2010JCP\">[94]<\/a><\/dt>\n<dd>\nG. Granucci, M. Persico, A. Zoccante:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.3489004\">“Including quantum<br \/>\n decoherence in surface hopping”<\/a>. <em>J. Chem. Phys.<\/em>, <b>133<\/b>,<br \/>\n 134 111 (2010).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEJasper2003CPL\" id=\"Jasper2003CPL\">[95]<\/a><\/dt>\n<dd>\nA. W. Jasper, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1016\/S0009-2614(02)01990-5\">“Improved<br \/>\n treatment of momentum at classically forbidden electronic transitions in<br \/>\n trajectory surface hopping calculations”<\/a>. <em>Chem. Phys. Lett.<\/em>,<br \/>\n <b>369<\/b>, 60 – 67 (2003).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEHack2001JCP2\" id=\"Hack2001JCP2\">[96]<\/a><\/dt>\n<dd>\nM. D. Hack, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.1368388\">“A natural decay of mixing<br \/>\n algorithm for non-Born\u2013Oppenheimer trajectories”<\/a>. <em>The Journal of<br \/>\n Chemical Physics<\/em>, <b>114<\/b>, 9305-9314 (2001).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEJasper2007JCP\" id=\"Jasper2007JCP\">[97]<\/a><\/dt>\n<dd>\nA. W. Jasper, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1063\/1.2798763\">“Non-Born-Oppenheimer<br \/>\n molecular dynamics of Na…FH photodissociation”<\/a>. <em>J. Chem.<br \/>\n Phys.<\/em>, <b>127<\/b>, 194 306 (2007).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEShu2023JCTC\" id=\"Shu2023JCTC\">[98]<\/a><\/dt>\n<dd>\nY. Shu, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.2c00988\">“Decoherence and<br \/>\n Its Role in Electronically Nonadiabatic Dynamics”<\/a>. <em>J. Chem. Theory<br \/>\n Comput.<\/em> (2023).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEZhu2005JCTC\" id=\"Zhu2005JCTC\">[99]<\/a><\/dt>\n<dd>\nC. Zhu, A. W. Jasper, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/ct050021p\">“Non-Born-Oppenheimer<br \/>\n Liouville-von Neumann Dynamics. Evolution of a Subsystem Controlled by Linear<br \/>\n and Population-Driven Decay of Mixing with Decoherent and Coherent<br \/>\n Switching”<\/a>. <em>J. Chem. Theory Comput.<\/em>, <b>1<\/b>, 527-540 (2005).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITESingh1984JCC\" id=\"Singh1984JCC\">[100]<\/a><\/dt>\n<dd>\nU. C. Singh, P. A. Kollman:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1002\/jcc.540050204\">“An approach to<br \/>\n computing electrostatic charges for molecules”<\/a>. <em>J. Comp. Chem.<\/em>,<br \/>\n <b>5<\/b>, 129\u2013145 (1984).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMantina2009JPCA\" id=\"Mantina2009JPCA\">[101]<\/a><\/dt>\n<dd>\nM. Mantina, A. C. Chamberlin, R. Valero, C. J. Cramer, D. G. Truhlar:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/jp8111556\">“Consistent van der Waals<br \/>\n Radii for the Whole Main Group”<\/a>. <em>J. Phys. Chem. A<\/em>, <b>113<\/b>,<br \/>\n 5806\u20135812 (2009).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEKoeppel84ACP\" id=\"Koeppel84ACP\">[102]<\/a><\/dt>\n<dd>\nH. Köppel, W. Domcke, L. S. Cederbaum: “Multimode molecular<br \/>\n dynamics beyond the Born-Oppenheimer approximation”. <em>Adv. Chem. Phys.<\/em>,<br \/>\n <b>57<\/b>, 59-246 (1984).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITESenn2009ACIE\" id=\"Senn2009ACIE\">[103]<\/a><\/dt>\n<dd>\nH. M. Senn, W. Thiel:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1002\/anie.200802019\">“QM\/MM Methods for<br \/>\n Biomolecular Systems”<\/a>. <em>Angew. Chem. Int. Ed.<\/em>, <b>48<\/b>, 1198-1229<br \/>\n (2009).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPitesa2024\" id=\"Pitesa2024\">[104]<\/a><\/dt>\n<dd>\nT. Pite\u0161a, S. Polonius, L. Gonz\u00e1lez, S. Mai:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jctc.4c00157\">“Excitonic<br \/>\n Configuration Interaction: Going Beyond the Frenkel Exciton Model”<\/a>. <em>J.<br \/>\n Chem. Theory Comput.<\/em>, <b>20<\/b>, 5609-5634 (2024).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEPitesa2025\" id=\"Pitesa2025\">[105]<\/a><\/dt>\n<dd>\nT. Pite\u0161a, S. Mai, L. Gonz\u00e1lez:<br \/>\n <a href=\"http:\/\/dx.doi.org\/10.1021\/acs.jpclett.5c00065\">“Efficient<br \/>\n Excitonic Configuration Interaction for Large-Scale Multichromophoric Systems<br \/>\n Using the Resolution-of-Identity Approximation”<\/a>. <em>J. Phys. Chem.<br \/>\n Lett.<\/em>, <b>16<\/b>, 2800-2807 (2025).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEBarbatti2011\" id=\"Barbatti2011\">[106]<\/a><\/dt>\n<dd>\nM. Barbatti, G. Granucci, M. Ruckenbauer, F. Plasser, J. Pittner, M. Persico,<br \/>\n H. Lischka: “NEWTON-X: a package for Newtonian dynamics close to<br \/>\n the crossing seam, version 1.2”. www.newtonx.org (2011).<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEMarquetand2007\" id=\"Marquetand2007\">[107]<\/a><\/dt>\n<dd>\nP. Marquetand: <em>Vectorial properties and laser control of molecular<br \/>\n dynamics<\/em>. Ph.D. thesis, University of Würzburg (2007),<br \/>\n <a href=\"http:\/\/opus.bibliothek.uni-wuerzburg.de\/volltexte\/2007\/2469\/\"><tt>http:\/\/opus.bibliothek.uni-wuerzburg.de\/volltexte\/2007\/2469\/<\/tt><\/a>.<\/p>\n<div class=\"p\"><!----><\/div>\n<\/dd>\n<dt><a href=\"#CITEVerlet1967PR\" id=\"Verlet1967PR\">[108]<\/a><\/dt>\n<dd>\nL. Verlet: <a href=\"http:\/\/dx.doi.org\/10.1103\/PhysRev.159.98\">“Computer<br \/>\n Ëxperiments” on Classical Fluids. I. Thermodynamical Properties of<br \/>\n Lennard-Jones Molecules”<\/a>. <em>Phys. Rev.<\/em>, <b>159<\/b>, 98-103 (1967).<\/dd>\n<\/dl>\n<div class=\"p\"><!----><\/div>\n<div class=\"p\"><!----><\/div>\n","protected":false},"excerpt":{"rendered":"<p>Read the manual below or download the PDF. If you are looking for the SHARC 3.0 manual, download the PDF here instead. SHARC: Surface Hopping in the Adiabatic Representation Including Arbitrary Couplings—Manual SHARC: Surface Hopping in the Adiabatic Representation Including Arbitrary Couplings-Manual Contents 1  Introduction    1.1  Capabilities        1.1.1  New features in SHARC Version 4.0    1.2  References    1.3  Authors        1.3.1  Eternal list […]<\/p>\n","protected":false},"author":2,"featured_media":0,"parent":15,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-1454","page","type-page","status-publish","hentry","wpautop"],"_links":{"self":[{"href":"https:\/\/sharc-md.org\/index.php?rest_route=\/wp\/v2\/pages\/1454","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/sharc-md.org\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/sharc-md.org\/index.php?rest_route=\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/sharc-md.org\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/sharc-md.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=1454"}],"version-history":[{"count":12,"href":"https:\/\/sharc-md.org\/index.php?rest_route=\/wp\/v2\/pages\/1454\/revisions"}],"predecessor-version":[{"id":1495,"href":"https:\/\/sharc-md.org\/index.php?rest_route=\/wp\/v2\/pages\/1454\/revisions\/1495"}],"up":[{"embeddable":true,"href":"https:\/\/sharc-md.org\/index.php?rest_route=\/wp\/v2\/pages\/15"}],"wp:attachment":[{"href":"https:\/\/sharc-md.org\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=1454"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}