Qbics Manual =============== - In the left panel, you can find a **quick overview** of the main sections of the manual - Below, you can find a **detailed** table of contents. .. toctree:: :maxdepth: 2 :caption: Program begin/compilation begin/installation begin/commandline .. toctree:: :maxdepth: 2 :caption: Input begin/inpstructure begin/inputlibrary .. toctree:: :maxdepth: 2 :caption: Tutorials: Basics tutorials/dft tutorials/semi tutorials/charmm tutorials/opt tutorials/ai .. toctree:: :maxdepth: 2 :caption: Tutorials: Mechanism tutorials/ts tutorials/eda .. toctree:: :maxdepth: 2 :caption: Tutorials: MD tutorials/md tutorials/enhanced_md .. toctree:: :maxdepth: 2 :caption: Tutorials: TSO-DFT, NOSI and MSDFT tutorials/tso1 tutorials/tso2 tutorials/msdft1 tutorials/msdft2 tutorials/msdft3 tutorials/msdft4 .. tutorials/qmmm .. toctree:: :maxdepth: 2 :caption: Keywords keywords/basis keywords/basinfo keywords/charmm keywords/eda keywords/grimmedisp keywords/md keywords/mecp keywords/mol keywords/msdft keywords/nddo keywords/nosi keywords/opt keywords/output keywords/pcm keywords/pifep keywords/pseudopotential keywords/qmmm keywords/scf keywords/scfguess keywords/tddft keywords/thermo keywords/wfn keywords/xtb .. keywords/sponge,pifep .. toctree:: :maxdepth: 2 :caption: Development develop/tools develop/styles develop/logic develop/git .. toctree:: :maxdepth: 1 :caption: Quick Links quicklink Compiling Qbics ==================== .. contents:: :local: To compile Qbics, please follow the instructions step-by-step. Download Source Code ---------------------------- Just visit ``_, you can find 2 source code files: - **Qbics Source Code** The is the **lean** source code of Qbics. To compile it, you may have to compile some libraries and set optimization, link options by yourself. The bonus is that you can optimize Qbics at a better level on your machine. - **Qbics Source Code with environment** This is the Qbics source code with compilation environment. In principle, on most Linux and macOS systems, you can compile it with just one command. This is recommended if you want to compile it rapidly. Preparations ----------------- The minimal requirement for compiling Qbics is: - ``gcc``, version >= 8.0; - ``g++``, version >= 8.0; - ``gfortran``, version >= 8.0; - ``make``, version >= 3.8; - ``cmake``, version >= 3.16; Below are some others: - ``Intel MKL``, version >= 2021.4.0, if MKL is to be used; - ``OpenMPI``, version >= 3.0, if MPI version of Qbics is required; - ``nvcc``, version >= 10.0, if GPU version of Qbics is required. One-Key Build: Quick Way -------------------------- If you do not want to build third-party libraries by yourself, you can download Qbics source code with compilation environment from ``_, which is named as ``qbics-source-env.tar.gz``. In most cases, you can compile it with just a few commands: .. code-block:: bash $ tar -xvzf qbics-source-env.tar.gz $ cd qbics-source-env $ ./build-qbics.sh On most Linux machines, this can be done smoothly and excutables will be available in ``qbics-Release/bin``. If you want to rebuild Qbics, then: .. code-block:: bash $ ./build-qbics.sh clean Type [yes] to make sure to delete *all* cache files: yes $ ./build-qbics.sh One-Key Build: More Options ----------------------------- Parallel Compilation ++++++++++++++++++++++++++++ If you want to use more CPU cores to compile Qbics, open ``build-qbics.sh`` and find .. code-block:: bash :linenos: :caption: build-qbics.sh ######################################################################## numCores=64 # Number of cores to compile. export CC=gcc FC=gfortran # Compilers. Just change ``numCores`` to the number you like. Use Intel MKL ++++++++++++++++++++++++++++ Intel MKL can significantly improve the performance of Qbics. The default option of building Qbics is NOT using MKL since not all machine has MKL installed. However, if you have MKL on your machine, you can simple activae MKL by: .. code-block:: bash $ tar -xvzf qbics-source-env.tar.gz $ cd qbics-source-env $ ./build-qbics.sh mkl Note that, these commands assume that Intel MKL is installed on ``/opt/intel``. Open ``build-qbics.sh`` and you can see: .. code-block:: bash :linenos: :caption: build-qbics.sh if test $1 = "mkl"; then source /opt/intel/oneapi/setvars.sh useMKL=1 fi Open ``qbics-source/Makefile`` and you can also see: .. code-block:: Makefile :linenos: :caption: qbics-source/Makefile # Third-party library. # ... omitted ... ifdef eigen_mkl LIBBLAS = -L/opt/intel/oneapi/mkl/2021.4.0/lib/intel64 -Wl,--no-as-needed -lmkl_intel_lp64 -lmkl_gnu_thread -lmkl_core -lgomp -lpthread -lm else LIBBLAS = ../third-party/OpenBLAS-0.3.28/lib/libopenblas.a endif # Third-party include. # ... omitted ... ifdef eigen_mkl INCBLAS = -I/opt/intel/oneapi/mkl/2021.4.0/include else INCBLAS = endif So, if you install MKL to another path, like ``/usr/intel``, you have to change all ``/opt/intel`` shown above to ``/usr/intel`` to enable compilers to find MKL. You can see that all linear algebras are done down with OpenBLAS if Intel MKL is not used. .. attention:: Here, we compile Qbics with **GNU compiler** and **link** with Intel MKL library. We do **NOT** use Intel compiler here. Aggressive Optimizations ++++++++++++++++++++++++++++ If you are pursuing extreme performance, you can also try: 1. Link to Intel MKL, like mentioned above. This is the most effective way. 2. In ``qbics-source/Makefile``, you can find the following lines: .. code-block:: Makefile :linenos: :caption: qbics-source/Makefile CXX = g++ CXXFLAG = -O2 --std=c++17 -fopenmp -ffast-math -fno-finite-math-only -fexpensive-optimizations -Wall -mavx2 -mfma CC = gcc CCFLAG = -O2 -fopenmp -Wall FC = gfortran FCFLAG = -O2 -fopenmp -Wall In ``CXXFLAG``, we have given optimal options. However, you can replace ``-O2`` to ``-O3``, and add options like ``-march=native -mtune=native``. This may or may **NOT** improve performance, and sometimes it may decrease performance. Please do benchmark to confirm your options. 3. According to our benchmark, using clang or intel compiler do **NOT** improve the performance as compared with GNU compiler, but you can try if they do on **your** machine. 4. For third-party libraries, you can also try to modify their compilation options. Please refer to their documentations. Build from Lean Source Code ---------------------------------- Modify Makefile ++++++++++++++++++ If you have your own third-party libraries and want to build only Qbics source code, just visit ``_ and download ``qbics-source.tar.gz``. After decompressing the package, find ``Makefile``: .. code-block:: Makefile :linenos: :caption: Makefile # Code information. SHELL=/bin/bash CODEINFO = -DCodeCommit="\"`git rev-parse HEAD`\"" \ -DCodeFlag="\"beta testing\"" \ -DCodeMajorVer=0 \ -DCodeMinorVer=4 \ -DCodeUser="\"`whoami | sed 's/\\\\/\\\\\\\\/g'`\"" \ -DCodeMachine="\"`hostname`\"" CODENAME = qbics # ...omitted... # Third-party library. LIBGNU = -lgfortran -lquadmath LIBXC = ../third-party/libxc-6.2.2/lib/libxc.a LIBDFTD = ../third-party/dftd3-0.9/libdftd3.a ifeq ($(MAKECMDGOALS),mac-cpu) LIBPLUMED = ../third-party/plumed-2.9.2/lib/libplumed.dylib LIBXTB = ../third-party/xtb-6.5.0/lib/libxtb.a else LIBPLUMED = ../third-party/plumed-2.9.2/lib/libplumed.a -lz LIBXTB = ../third-party/xtb-6.5.0/lib/libxtb.a ../third-party/xtb-6.5.0/lib/libmctc-lib.a #../third-party/xtb-6.5.0/lib/results_patch.o endif LIBFFTW3 = ../third-party/fftw-3.3.10/lib/libfftw3.a ../third-party/fftw-3.3.10/lib/libfftw3_omp.a LIBDLFIND = ../third-party/dl-find/libdlf.a ifdef eigen_mkl LIBBLAS = -L/opt/intel/oneapi/mkl/2021.4.0/lib/intel64 -Wl,--no-as-needed -lmkl_intel_lp64 -lmkl_gnu_thread -lmkl_core -lgomp -lpthread -lm else LIBBLAS = ../third-party/OpenBLAS-0.3.28/lib/libopenblas.a endif LIBCUDA = /usr/local/cuda-11.4/targets/x86_64-linux/lib/libcudart_static.a -lrt LIBSPONGE = # Third-party include. INCBOOST = -I../third-party/boost_1_78_0 INCEIGEN = -I../third-party/eigen-3.4.0 INCLIBXC = -I../third-party/libxc-6.2.2/include INCDFTD = -I../third-party/dftd3-0.9 INCPLUMED = -I../third-party/plumed-2.9.2/include INCFFTW3 = -I../third-party/fftw-3.3.10/include INCXTB = -I../third-party/xtb-6.5.0/include INCDLFIND = -I../third-party/dl-find ifdef eigen_mkl INCBLAS = -I/opt/intel/oneapi/mkl/2021.4.0/include else INCBLAS = endif INCCUDA = -I/usr/local/cuda-11.4/targets/x86_64-linux/include/ You need to change these lines: - Line 4: ``-DCodeFlag`` can be your unique flag, like ``Specific for XX Lab``; - Line 12-30: The paths to third-party libraries. For example, ``LIBXC`` is the path to libxc library ``libxc.a``; - Line 33-46: The paths to header files. For example, ``INCLIBXC`` is the path to libxc header flies like ``xc.h``. In addition, for dftd3-lib and DL-Find library, ``INCDFTD`` and ``INCDLFIND`` should be the paths to their module files like ``dftd3_api.mod`` and ``dlf_allocate.mod``, respectively. - Please pay attention that the options for some libraries depends on operating system or if Intel MKL is used, like ``LIBBLAS`` or ``INCBLAS``. Of course, you can also change C++, C, and Fortran compilers with ``CXX``, ``CC``, and ``FC``, respectively. Now, you can compile Qbics. Below are some examples: .. code-block:: bash $ make linux-cpu -j 32 # On Linux, wihtout Intel MKL, with 32 CPU cores $ make linux-cpu -j 32 eigen_mkl=1 # On Linux, wiht Intel MKL, with 32 CPU cores $ make mac-cpu -j 32 # On macOS, wihtout Intel MKL, with 32 CPU cores If the compilation succeeds, the executable ``bin/qbics-linux-cpu`` or ``bin/qbics-mac-cpu`` can be found. .. attention:: This ``Makefile`` can also be used to compile Qbics on Windows: .. code-block:: bash $ make win-cpu -j 8 # On Windows, wihtout Intel MKL, with 8 CPU cores However, you will have to install MSYS2 and MinGW64 on Windows, which may be quite complicated. I recommend you just download Windows executable from ``_. Third-Party Libraries ++++++++++++++++++++++++ Here, third-party libraries mean libraries that are not present on a native Linux or macOS machine. All third-party libraries needed by Qbics are: - Boost: ``_ A de facto standard library for extending C++ functionalities. - Eigen: ``_ A C++ linear algebra library. - libxc: ``_ A library for density functionals. - dftd3-lib: ``_ A library for Grimme dispersion correction. - plumed: ``_ A library for enhanced sampling. - libfftw3: ``_ A library for fast Frourier transformation. - xTB: ``_ A powerful semi-empirical quantum chemical method library. - DL-Find: ``_ An open-source geometry optimisation library. - OpenBLAS: ``_ The high performance linear algebra library backend for Eigen. It can be replaced by Intel MKL. - HDF5: ``_ The implementation of the HDF5 data model. - (Optional) Intel MKL: ``_ High performance math kernel library. - (Optional) OpenMPI: ``_ An implementation for MPI protocal to do parallelzation. - (Optional) CUDA: ``_ A development environment for creating high-performance, GPU-accelerated applications. Build GPU Version of Qbics ---------------------------- To build GPU version of Qbics, the first thing is to make sure that CPU version can be smoothly built. If you use **Qbics Source Code with environment**, you should have run ``./build-qbics.sh`` to successfully build a CPU version of Qbics. After this, open ``Makefile`` to find these lines: .. code-block:: Makefile :linenos: :caption: Makefile # ...omitted... LIBCUDA = /usr/local/cuda-11.4/targets/x86_64-linux/lib/libcudart_static.a -lrt LIBSPONGE = # Third-party include. # ...omitted... INCCUDA = -I/usr/local/cuda-11.4/targets/x86_64-linux/include/ You should modify ``LIBCUDA`` and ``INCCUDA`` to enable compiler to find CUDA library ``libcudart_static.a`` and CUDA head files, then you can compile GPU version of Qbics: .. code-block:: bash $ make linux-gpu -j 32 # On Linux, GPU version, with 32 CPU cores If the compilation succeeds, the executable ``bin/qbics-linux-gpu`` an be found. Currently, GPU version of Qbics is only available on Linux. Build MPI Version of Qbics ---------------------------- To build GPU version of Qbics, the first thing is to make sure that CPU version can be smoothly built. If you use **Qbics Source Code with environment**, you should have run ``./build-qbics.sh`` to successfully build a CPU version of Qbics. After this, make sure that your system has an MPI implementation, like OpenMPI or MPICH. We recommend `OpenMPI `_. To compile MPI version of Qbics: .. code-block:: bash $ make linux-cpu-mpi -j 32 # On Linux, MPI version, with 32 CPU cores If the compilation succeeds, the executable ``bin/qbics-linux-cpu-mpi`` an be found. Currently, MPI version of Qbics is only available on Linux. Additional Modules of Plumed ---------------------------- As shown above, Qbics can be compiled with plumed library. However, some additional modules of plumed are not included in the default plumed library (before 2025). For example, OPES algorithm or libtorch support are not compiled by default. If you want to use these features, you have to compile plumed with additional option like ``--enable-modules=+module1+module2+...`` when you compile plumed. For all modules, pleasse refer to ``_. For example, if you want to use the OPES algorithm and the PIV collective variable, you can compile plumed with: .. code-block:: bash $ ./configure --enable-modules=+opes+piv This can be added to ``build-qbics.sh``. If you do not want to recompile Qbics, you can use this to recompile plumed only and link it to Qbics. Possible Issues ---------------------------- In compiling Qbics, you may encounter some issues. Here are some common issues and solutions: 1. ``C++: fatal error: Killed signal terminated program cc1plus`` **Reason:** This is because the compilation of Qbics and related third-party libraries may take a long time and a large amount of memory. If you are working on a login node in some clusters, the system may kill your job due to the exceed of user quotas. **Solution:** In ``build-qbics.sh``, set ``numnCores=1`` to compile Qbics with only one CPU core. If this still does not work, you can try to **submit a job** to compile Qbics on computing nodes. 2. ``undefined reference to 'gsl_vector_get'`` **Reason:** In the compilation of Plumed, the GSL library is used in some old versions of Linux. In the newer versions of Linux, the GSL library is not needed anymore. **Solution:** Open ``Makefile`` and find the following line: .. code-block:: Makefile :linenos: :caption: Makefile ifeq ($(MAKECMDGOALS),mac-cpu) LIBPLUMED = ../third-party/plumed-2.9.2/lib/libplumed.dylib LIBXTB = ../third-party/xtb-6.5.0/lib/libxtb.a else LIBPLUMED = ../third-party/plumed-2.9.2/lib/libplumed.a -lz LIBXTB = ../third-party/xtb-6.5.0/lib/libxtb.a ../third-party/xtb-6.5.0/lib/libmctc-lib.a #../third-party/xtb-6.5.0/lib/results_patch.o endif In ``LIBPLUMED``, add ``-lgsl``, like this: .. code-block:: Makefile :linenos: :caption: Makefile :emphasize-lines: 5 ifeq ($(MAKECMDGOALS),mac-cpu) LIBPLUMED = ../third-party/plumed-2.9.2/lib/libplumed.dylib LIBXTB = ../third-party/xtb-6.5.0/lib/libxtb.a else LIBPLUMED = ../third-party/plumed-2.9.2/lib/libplumed.a -lz -lgsl LIBXTB = ../third-party/xtb-6.5.0/lib/libxtb.a ../third-party/xtb-6.5.0/lib/libmctc-lib.a #../third-party/xtb-6.5.0/lib/results_patch.o endif 3. ``Error: Rank mismatch in argument 'coords' at (1) (rank-l and scalar)`` **Reason:** This is because the coordinates of the system are not in the correct format. **Solution:** Check the coordinates of the system and make sure that they are in the correct format. 4. ``Error: Rank mismatch in argument 'coords' at (1)(rank-local and scalar)`` **Reason:** This is due to the different treatment of DL-Find code by different versions of Fortran compiler. **Solution:** Open ``third-party/dl-find-src/Makefile.qbics`` and find the following line: .. code-block:: Makefile :linenos: :caption: third-party/dl-find-src/Makefile.qbics ifeq ($(arch),gfortran) F90 = gfortran F90FLAGS = -C -M $(OBJDIR) F90FLAGS = -fimplicit-none -fbounds-check -std=gnu -Wconversion \ -Wsurprising #-fallow-argument-mismatch Delete ``#`` to make ``-fallow-argument-mismatch`` to be used: .. code-block:: Makefile :linenos: :caption: third-party/dl-find-src/Makefile.qbics :emphasize-lines: 5 ifeq ($(arch),gfortran) F90 = gfortran F90FLAGS = -C -M $(OBJDIR) F90FLAGS = -fimplicit-none -fbounds-check -std=gnu -Wconversion \ -Wsurprising -fallow-argument-mismatch Running Qbics ====================== .. contents:: :local: Qbics should be run from Windows command prompt or Linux/macOS terminal. To run Qbics, you just need to give an input file name. We prepare an input file called ``water.inp``: .. code-block:: bash :caption: water.inp :linenos: # A B3LYP/cc-pvdz calculation for water. basis cc-pvdz end scf charge 0 # Total charge. spin2p1 1 end mol O 0.00000000000000 0.05011194954430 0.05011194954224 H 0.00000000000000 -0.06080277603381 1.01069082652926 H 0.00000000000000 1.01069082648951 -0.06080277607149 end task energy b3lyp end Command Line Arguments ------------------------------------------- The usage of Qbics is: .. code-block:: bash qbics-linux-cpu [-n ] [-s ] [-m ] [-d ] [--gpu ] You can use this command to run Qbics: .. code-block:: bash $ qbics-linux-cpu water.inp > water.out The optional arguments are explained below: .. option:: -n .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Define the number of OpenMP threads for each MPI process. * - Default - ``1`` The value should be **less than the number of physical CPU cores** of the node it is run on. .. option:: -s .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Define the scratch path where omputational temporary files are saved. * - Default - ``./`` Qbics will use this path to write some computational temporary files. It should be on a **local, fast, and large** disk, and **not** remote ones, like NFS shared paths. For Windows users, the scratch path should be given in **Linux format**. For example, if the scratch path is ``D:\Jobs\Scratch`` (Windows format), then for Qbics you should give ``-d D:/Jobs/Scratch``. .. option:: -m .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Define the maximum memory size in GB that a MPI process can use * - Default - Unlimited For example, ``-m 5.5`` means that each MPI process will use up to 5.5 GB of memory, no matter how many OpenMP threads there are. Of course, it should not exceed the total memory size of the node. .. option:: -d .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Define the maximum disk size in GB that a MPI process can use in the scratch path. * - Default - Unlimited For example, ``-d 900`` means that each MPI process will use up to 900 GB of disk, no matter how many OpenMP threads there are. Of course, it should not exceed the total disk size in the scratch path. .. option:: --gpu .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Define GPU device IDs to be used. * - Default - ``0`` For example, ``--gpu 0,2,3`` means that Qbics will use GPU device of ID ``0``, ``2``, ``3`` to do calculations. Here is an example of running Qbics: .. code-block:: bash $ qbics-linux-cpu water.inp -n 8 -m 30 -d 500 -s /scratch/zhang > water.out This command will run Qbics with an input file ``water.inp``. The number of OpenMP threads is 8, maximum memory and disk size is 30 GB and 500 GB, respectively, and the scratch path is ``/scratch/zhang``. Run Qbics on a Single Node with GPU -------------------------------------------- If GPU devices are available, you can just run GPU version of Qbics like before, and Qbics will automatically use GPU if possible: .. code-block:: bash $ qbics-linux-gpu water.inp -n 8 > water.out In ``water.out``, Qbics will output the GPU found, and only use ``0``: .. code-block:: bash :caption: water.out :linenos: MPI is disabled in this version. # Nodes: 1 ID Hostname Memory (GB) #Cores #OpenMP 0 ubuntu-server 251 96 1 CUDA Device to be used: 0 CUDA Device: On node 0, ubuntu-server: 4 CUDA device is available: 0: NVIDIA GeForce RTX 4080 Computational ability: 8.9 Global memory: 16079 MB Block-shared memory: 48 KB = 6144 double Constant memory: 64 KB = 8192 double Maximum threads per block: 1024 Maximum thread dimension: 1024, 1024, 64 Maximum grid dimension: 2147483647, 65535, 65535 1: NVIDIA GeForce RTX 4080 Computational ability: 8.9 Global memory: 16077 MB Block-shared memory: 48 KB = 6144 double Constant memory: 64 KB = 8192 double Maximum threads per block: 1024 Maximum thread dimension: 1024, 1024, 64 Maximum grid dimension: 2147483647, 65535, 65535 In Line 8, Qbics has found 4 CUDA device. In Line 5, Qbics reports that ``0`` will be used, i.e., the device reported in Line 9. If you want to use all 4 GPUs, just run with ``--gpu`` arguments: .. code-block:: bash $ qbics-linux-gpu water.inp -n 8 --gpu 0,1,2,3 > water.out Read ``water.out`` to confirm that all 4 GPUs are used (Line 5): .. code-block:: bash :caption: water.out :linenos: MPI is disabled in this version. # Nodes: 1 ID Hostname Memory (GB) #Cores #OpenMP 0 ubuntu-server 251 96 1 CUDA Device to be used: 0 1 2 3 CUDA Device: On node 0, ubuntu-server: 4 CUDA device is available: 0: NVIDIA GeForce RTX 4080 Computational ability: 8.9 Global memory: 16079 MB Block-shared memory: 48 KB = 6144 double Constant memory: 64 KB = 8192 double Maximum threads per block: 1024 Maximum thread dimension: 1024, 1024, 64 Maximum grid dimension: 2147483647, 65535, 65535 Run Qbics on Multiple Nodes -------------------------------------------- To run MPI version of Qbics, make sure that the MPI implementation must be **the same version** as the one used to compile Qbics. To check this, first run MPI version in serial mode: .. code-block:: bash $ qbics-linux-cpu-mpi water.inp -n 8 > water.out In ``water.out``, you can find this: .. code-block:: bash :caption: water.out :linenos: C++ compiler: g++ (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0 C++ options: -O2 --std=c++17 -fopenmp -ffast-math -fno-finite-math-only -fexpensive-optimizations -Wall -mavx2 -mfma MPI compiler: mpirun (Open MPI) 4.1.2 Line 3 says that the MPI compiler is ``mpirun (Open MPI) 4.1.2``. Then, in shell, .. code-block:: bash $ mpirun -V mpirun (Open MPI) 4.1.2 Report bugs to http://www.open-mpi.org/community/help/ Thus, this ``mpirun`` is exactly the same version as Qbics needs. Run MPI Version of Qbics from Shell +++++++++++++++++++++++++++++++++++++++++ The following command: .. code-block:: bash $ mpirun -np 4 --bind-to none qbics-linux-cpu-mpi water.inp -n 8 > water.out Here, ``-np`` is the number of MPI processes. Note that you can also use ``-n`` to set up OpenMP parallelization. In this case, we have 4 MPI processes, each having 8 OpenMP threads. Here, ``--bind-to none`` is the CPU binding mode. If you do not give ``--bind-to none``, the number of OpenMP threads may be incorrect. Run MPI Version of Qbics from Slurm +++++++++++++++++++++++++++++++++++++++++ In most cases, you will run Qbics through a queueing system. In Qbics distribution, we give an example of a Slurm script ``tools/run_qbics.slurm`` to run Qbics: .. code-block:: bash :caption: tools/run_qbics.slurm :linenos: #!/bin/bash #SBATCH --job-name=water #SBATCH --nodes=4 # Total number of physical nodes. #SBATCH --ntasks=8 # Total number of MPI processes. #SBATCH --cpus-per-task=8 # Number of OpenMP thereads for each MPI process. #SBATCH --partition=your_partition # Load the appropriate modules if needed. # module load openmpi/4.1.1 inp=water.inp out=water.out mpirun qbics-linux-cpu-mpi $inp -n $SLURM_CPUS_PER_TASK > $out In this script, we request 4 physical nodes (``--nodes``) and totally 8 MPI processes (``--ntasks``), and each MPI process has 8 OpenMP threads (``--cpus-per-task``). Thus, we guess that each node will have 2 MPI processes. You can change these parameters according to your needs. ``--partition`` is the queue you want to use, which should be arranged by your cluster administrator. In Slurm script, ``mpirun`` does not need ``-np`` option, since Slurm will automatically set the number of MPI processes according to ``--ntasks``. Submit this task: .. code-block:: bash $ sbatch run_qbics.slurm After running, you can find these lines in ``water.out`` (on my cluster): .. code-block:: bash :caption: water.out :linenos: User: junz # Physical nodes: 4 Physical node names: cu295 cu296 cu297 cu298 MPI version: 3.1 # MPI processes: 8 Rank Hostname Memory (GB) #Cores #OpenMP 0 cu295 187 32 8 1 cu295 187 32 8 2 cu296 187 32 8 3 cu296 187 32 8 4 cu297 187 32 8 5 cu297 187 32 8 6 cu298 187 32 8 7 cu298 187 32 8 CUDA is disabled in this version. Indeed, we have 4 physical nodes, each having 2 MPI processes, and each MPI process has 8 OpenMP threads. We also know that each node has 32 cores and a memory of 187 GB. .. attention:: On different clusters, the slurm script may need some modifications. Please consult the administrator of your cluster. Input File Format ============================ .. contents:: :local: In Qbics, most computational settings are given in a single input file. The following one is a basic Qbics input file: .. code-block:: bash :caption: water.inp :linenos: # A B3LYP/cc-pvdz calculation for water. basis cc-pvdz end scf charge 0 # Total charge. spin2p1 1 end mol O 0.00000000000000 0.05011194954430 0.05011194954224 H 0.00000000000000 -0.06080277603381 1.01069082652926 H 0.00000000000000 1.01069082648951 -0.06080277607149 end task energy b3lyp opt b3lyp end - You can insert comments at any place using ``#``. - Statements like ``mol ... end`` are called a keyword block. In this example, we have ``basis``, ``scf`` and ``mol`` blocks. They give details about how calculations should be done by Qbics. - A special block is ``task``. It tells Qbics what tasks to do. In this example, there are two calculations: ``energy b3lyp`` and ``opt b3lyp``. They will be done one-by-one. Input Library ============================ .. contents:: :local: Here, we collect a lot of input files for Qbics. They are used in tutorials and keyword examples. You can use them **as templates for your own calculations.** Tutorials -------------- .. list-table:: :stub-columns: 1 * - Tutorial - Download * - :doc:`../tutorials/dft` - :download:`Files ` * - :doc:`../tutorials/semi` - :download:`Files ` * - :doc:`../tutorials/charmm` - :download:`Files ` * - :doc:`../tutorials/opt` - :download:`Files ` * - :doc:`../tutorials/md` - :download:`Files ` * - :doc:`../tutorials/ts` - :download:`Files ` * - :doc:`../tutorials/eda` - :download:`Files ` * - :doc:`../tutorials/tso1` - :download:`Files ` * - :doc:`../tutorials/tso2` - :download:`Files ` * - :doc:`../tutorials/msdft1` - :download:`Files ` * - :doc:`../tutorials/msdft2` - :download:`Files ` * - :doc:`../tutorials/msdft3` - :download:`Files ` * - :doc:`../tutorials/msdft4` - :download:`Files ` * - :doc:`../tutorials/enhanced_md` - :download:`Files ` Keywords ------------- .. list-table:: :stub-columns: 1 * - Keyword - Download * - :doc:`../keywords/basinfo` - :download:`Files ` * - :doc:`../keywords/basis` - :download:`Files ` * - :doc:`../keywords/charmm` - :download:`Files ` * - :doc:`../keywords/eda` - :download:`Files ` * - :doc:`../keywords/grimmedisp` - :download:`Files ` * - :doc:`../keywords/md` - :download:`Files ` * - :doc:`../keywords/mecp` - :download:`Files ` * - :doc:`../keywords/mol` - :download:`Files ` * - :doc:`../keywords/msdft` - :download:`Files ` * - :doc:`../keywords/nddo` - :download:`Files ` * - :doc:`../keywords/nosi` - :download:`Files ` * - :doc:`../keywords/opt` - :download:`Files ` * - :doc:`../keywords/output` - N/A * - :doc:`../keywords/pcm` - :download:`Files ` * - :doc:`../keywords/pifep` - :download:`Files ` * - :doc:`../keywords/pseudopotential` - :download:`Files ` * - :doc:`../keywords/qmmm` - :download:`Files ` * - :doc:`../keywords/scf` - :download:`Files ` * - :doc:`../keywords/scfguess` - :download:`Files ` * - :doc:`../keywords/tddft` - :download:`Files ` * - :doc:`../keywords/thermo` - :download:`Files ` * - :doc:`../keywords/wfn` - :download:`Files ` * - :doc:`../keywords/xtb` - :download:`Files ` Installing Qbics =================== .. contents:: :local: General Considerations ---------------------------- After compiling or downloading Qbics, you can find the following files: .. code-block:: bash qbics |------ basis |------ pseudopotential |------ xtbparams |------ tools |------ plumed |------ qbics-linux-cpu These files are: - ``basis`` Basis set files. Qbics will automatically use basis sets in this directory. - ``pseudopotential`` Pseudopotential files. Qbics will automatically use pseudopentials in this directory. - ``xtbparams`` xTB parameter files. Usually they are not used directly, since parameters are stored inside Qbics executable. - ``tools`` Some tools for computations. - ``plumed`` Executable of Plumed. - ``qbics-linux-cpu`` The Qbics executable. On other operating systems, it may be called ``qbics-mac-cpu`` or ``qbics-win-cpu``, etc. All available versions of Qbics are: .. list-table:: :widths: 2 10 :header-rows: 1 * - Name - Version * - ``qbics-linux-cpu`` - CPU version on Linux (OpenMP parallelized) * - ``qbics-linux-gpu`` - GPU version on Linux (OpenMP parallelized) * - ``qbics-linux-cpu-mpi`` - MPI parallelized CPU version on Linux (OpenMP parallelized) * - ``qbics-mac-cpu`` - CPU version on macOS (OpenMP parallelized) * - ``qbics-win-cpu`` - CPU version on Windows (OpenMP parallelized) You can run Qbics by using absolute path. On Windows, assume you put ``qbics`` in ``D:\software``, then: .. code-block:: bash $ D:\software\qbics\qbics-win-cpu water.inp > water.out On Linux or macOS, assume you put ``qbics`` in ``/home/zhang``, then: .. code-block:: bash $ /home/zhang/qbics/qbics-linux-cpu water.inp > water.out Of course, you can also put ``D:\software\qbics`` or ``/opt/qbics`` to ``PATH`` variable so you need not to type absolute path, but this is not mandated. You do **NOT** need to set other environment variables, since Qbics can automatically detect it absolute path and use this to locate paths like ``basis`` or ``pseudopotential``. GPU Version ---------------------------- The GPU version of Qbics is designed to run on NVIDIA GPUs with CUDA support. To use the GPU version, ensure that you have the appropriate NVIDIA drivers and CUDA toolkit for your hardware installed on your system for your. MPI Version ---------------------------- The MPI version of Qbics is designed to run on multi-node clusters. Ensure that you have an MPI implementation (like OpenMPI or MPICH) installed on your system. Such MPI implementation must be **the same version** as the one used to compile Qbics. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these pages: - :doc:`../keywords/basis` - :doc:`../keywords/pseudopotential` - :doc:`../keywords/scf` - :doc:`../keywords/scfguess` - :doc:`../keywords/grimmedisp` - :doc:`../keywords/mol` Density Functional Theory Calculations ========================================= .. contents:: :local: This tutorial will lead you step by step to do density functional theory (DFT) calculations using Qbics. Here we only do energy calculations. For geometry optimization and molecular dynamics, please refer to :doc:`opt` and :doc:`md`. Example: Single Point Energy of Water ----------------------------------------- We will now do the first calculation using Qbics. The following input file will calculate B3LYP-D3BJ/def2-tzvp energy for a water molecule: .. code-block:: :caption: water-1.inp :linenos: # This first calculation. basis def2-tzvp end scf charge 0 spin2p1 1 type R # You do not have to write it. The program will determine it by itself. end grimmedisp type bj end mol O 0. 0.00000000 -0.11081188 H 0. -0.78397589 0.44324751 H 0. 0.78397589 0.44324751 end task energy b3lyp end Then run it: .. code-block:: bash $ qbics water-1.inp -n 4 > water-1.out Here, ``-n 4`` means Qbics will use 4 CPU cores for parallization. This calculation is very fast. After calculation, you will find 2 new files: .. code-block:: water-1.out water-1.mwfn ``water-1.out`` is the output file for this calculation. You can find energies, molecular orbital (MO) information, spin, population, electric multipole moments in it: .. code-block:: :caption: water-1.out :linenos: SCF Energies ============ Kinetic energy: 76.16685643 Hartree Electron-nuclear attraction energy: -199.22128800 Hartree Pseudopotential energy: 0.00000000 Hartree Exchange-correlation energy: -7.55662337 Hartree Electron Coulomb energy: 46.77766964 Hartree Electron exchange energy: -1.78638759 Hartree Nuclear repulsion energy: 9.15711600 Hartree Grimme dispersion energy: -0.00057358 Hartree ---------------------------------------------------------------- SCF energy (E): -76.46323045 Hartree Virial quotien (V/T): -2.00389112 Molecular Orbitals ================== k = Gamma HOMO-LUMO (5-6) gap: 8.990 eV # Occupancies Energies/Hartree 1 2.000 -19.12516259 2 2.000 -1.01223986 3 2.000 -0.54372159 4 2.000 -0.38293836 ... Spin ==== Expected : 0.00000; S = 0.00000 Calculated : 0.00000; S = 0.00000 Mulliken Populations ==================== # Symbol Charge Spin ---------------------------------------------- 1 O -0.64331377 0.00000000 2 H 0.32165689 0.00000000 3 H 0.32165689 0.00000000 ---------------------------------------------- Sum -0.00000000 0.00000000 ---------------------------------------------- Electric Multipole Moments ========================== # Total Electronic Nuclear Unit ------------------------------------------------------------------------------------ Charge: 0 -0.0000 -10.0000 10.0000 |e| Dipole moment: X -0.0000 -0.0000 0.0000 Debye Y 0.0000 0.0000 0.0000 Debye Z 1.9936 1.9936 -0.0000 Debye Totla 1.9936 Debye Quadrupole moment: XX -7.5861 -7.5861 0.0000 Debye*Angstrom XY -0.0000 -0.0000 0.0000 Debye*Angstrom XZ -0.0000 -0.0000 0.0000 Debye*Angstrom YY -4.1639 -10.0682 5.9043 Debye*Angstrom YZ 0.0000 0.0000 -0.0000 Debye*Angstrom ZZ -6.4570 -8.8162 2.3592 Debye*Angstrom ------------------------------------------------------------------------------------ ``water-1.mwfn`` is the wave function file in `Multiwfn `_ format. You can do all wave function visualization and analysis with Multiwfn. A faster way is to use `Qbics-MolStar `_, an online app, you can also download it on your own Windows machine. Just drag ``water-1.mwfn`` into explorer, and it will be automatically loaded. Right-click :guilabel:`water-1.mwfn` and select :guilabel:`View Molecular Orbitals`: .. figure:: /_images/a1.png Now, select :guilabel:`5: -0.313564 (occ=2, RHF)`, which is the HOMO of water, then MO will be rendered: .. figure:: /_images/a2.png You can also view other MOs or properties. Now we will explain the input ``water-1.inp`` of the last example. - Anything after ``#`` is treated as comments. You can write anything anywhere in the input file. - ``basis ... end`` This block defines the basis set used the calculation. You can find all available basis sets in ``qbics/basis``. Just input the file name. You can also define your own basis set, or set basis set for different elements. See below. - ``scf ... end`` This block controls how the self-consistent field (SCF) calculations are done. By its name, you may understand that: - ``charge`` The charge of the molecule, like ``0``, ``+3``, ``-1``, etc. - ``spin2p1`` The spin multiplicity. For a molecule with :math:`n` unpaired electrons, this total spin is :math:`S=\frac{n}{2}`, so spin multiplicity is :math:`2S+1 = n+1`. For example, for a triplet state of water, you will use ``spin2p1 3``, then 2 unpaired electrons will occupy 2 alpha orbitals. - ``type`` The value is ``R`` if a restricted Hartree--Fock (HF) or Kohn--Sham (KS) is needed, or ``U`` is an unrestricted one is needed. If you do not write this, the program will determine it automatically according to spin multiplicity: ``R`` for singlet and ``U`` for other cases - ``grimmedisp ... end`` This block controls how Grimme dispersion correction is applied. Here we use ``bj`` to indicate Becke--Johnson dampling D3 correction. - ``mol ... end`` This block gives the molecule coordinates in XYZ format. You can also simply give a coordinate file name in XYZ or PDB format, say ``water.xyz`` or ``water.pdb``. - ``task ... end`` This tells Qbics what it should do. ``energy b3lyp`` means it will use B3LYP to calculate energy. You can put several tasks in this block. Based on the explanations above, you can now try to calculate the triplet state of water: .. code-block:: :caption: water-2.inp :linenos: # Triplet state of water. basis def2-tzvp end scf charge 0 spin2p1 3 type U # If you do not write it. The program will determine it by itself. end grimmedisp type bj end mol O 0. 0.00000000 -0.11081188 H 0. -0.78397589 0.44324751 H 0. 0.78397589 0.44324751 end task energy b3lyp end You can find MO occupations and spin here: .. code-block:: :caption: water-2.out :linenos: Molecular Orbitals ================== k = Gamma Alpha HOMO-LUMO (6-7) gap: 3.247 eV Beta HOMO-LUMO (4-5) gap: 5.963 eV Alpha Alpha Beta Beta # Occupancies Energies/Hartree Occupancies Energies/Hartree 1 1.000 -19.35044069 1.000 -19.31689276 2 1.000 -1.21472533 1.000 -1.12845421 3 1.000 -0.69876887 1.000 -0.66807740 4 1.000 -0.57036857 1.000 -0.52597568 5 1.000 -0.56380445 0.000 -0.30683178 6 1.000 -0.10311895 0.000 -0.01035402 ... Spin ==== Expected : 2.00000; S = 1.00000 Calculated : 2.00188; S = 1.00063 The spin of this calculation is ``1.00063``, which is very close to the theoretical value 1, indicating a very small spin contamination. More Basis Set Configurations ----------------------------------- Qbics hase provided flexible basis set configuration. This section will show it. Define Your Own Basis Set ++++++++++++++++++++++++++++++ Assume you want to use a basis set called pc-2 for water. However, this is not available in ``qbics/basis``, you can then define it by your self. - Go to basis set exchange website: https://www.basissetexchange.org/, choose ``pc-2`` for H and O, and download it using **GAUSSIAN** format. .. image:: /_images/a3.png .. attention:: Replace all ``D`` to ``E`` in the basis set definitions! Now we have two ways: - The first way: Simply copy it to ``basis ... end`` block: .. code-block:: :caption: water-3.inp :linenos: # This first calculation. basis # From: https://www.basissetexchange.org/basis/pc-2/format/gaussian94/?version=0& elements=1,8 H 0 S 4 1.00 0.754230E+02 0.240650E-02 0.113500E+02 0.184870E-01 0.259930E+01 0.897420E-01 0.735130E+00 0.281110E+00 S 1 1.00 0.231670E+00 0.100000E+01 S 1 1.00 0.741470E-01 0.100000E+01 P 1 1.00 0.160000E+01 0.100000E+01 P 1 1.00 0.450000E+00 0.100000E+01 D 1 1.00 0.125000E+01 0.100000E+01 **** O 0 S 7 1.00 0.147820E+05 0.535190E-03 0.221730E+04 0.413750E-02 0.504740E+03 0.212450E-01 0.142870E+03 0.824530E-01 0.463000E+02 0.236710E+00 0.163370E+02 0.440390E+00 0.598280E+01 0.364650E+00 S 7 1.00 0.221730E+04 -0.192750E-05 0.504740E+03 -0.579640E-04 0.142870E+03 -0.794940E-03 0.463000E+02 -0.731250E-02 0.163370E+02 -0.405740E-01 0.598280E+01 -0.915940E-01 0.167180E+01 0.209400E+00 S 1 1.00 0.646620E+00 0.100000E+01 S 1 1.00 0.216690E+00 0.100000E+01 P 4 1.00 0.604240E+02 0.689490E-02 0.139350E+02 0.490050E-01 0.415310E+01 0.182550E+00 0.141580E+01 0.376330E+00 P 1 1.00 0.475490E+00 0.100000E+01 P 1 1.00 0.145290E+00 0.100000E+01 D 1 1.00 0.220000E+01 0.100000E+01 D 1 1.00 0.650000E+00 0.100000E+01 F 1 1.00 0.110000E+01 0.100000E+01 **** end scf charge 0 spin2p1 1 type R # You need not to write it. The program will determine it by itself. end grimmedisp type bj end mol O 0. 0.00000000 -0.11081188 H 0. -0.78397589 0.44324751 H 0. 0.78397589 0.44324751 end task energy b3lyp end Then do the calculation as usual. - The second way: Save the basis set in a file called, say, ``pc-2-OH.txt``. Assume you put it in ``/home/you/calc/pc-2-OH.txt``, then write this file name in ``basis ... end`` block: .. code-block:: :caption: water-4.inp :linenos: # This first calculation. basis /home/you/calc/pc-2-OH.txt end scf charge 0 spin2p1 1 type R # You need not to write it. The program will determine it by itself. end grimmedisp type bj end mol O 0. 0.00000000 -0.11081188 H 0. -0.78397589 0.44324751 H 0. 0.78397589 0.44324751 end task energy b3lyp end Both ways will give the same result. Different Basis Sets for Different Elements +++++++++++++++++++++++++++++++++++++++++++++++ Assume you want to use pc-2 (defined above) for oxygen but cc-pvdz for hydrogen, you can use the following ``basis ... end``: .. code-block:: :caption: water-5.inp :linenos: basis element # This indicates that Qbics will assign basis set element by element. O /home/you/calc/pc-2-OH.txt H cc-pvdz end The word ``element`` in the first line of ``basis ... end`` block means that Qbics will assign basis set element by element. Then simply write the basis set for every element. Example: Heavy Elements with Pseudopotential ------------------------------------------------ General Rules +++++++++++++++ For heavy elements, one should use pseudopotential for reasonable calculations. .. attention:: You must write **BOTH** valence basis set and pseudopotential in the input file. If pseudopotential is not written explicitly in the input file, Qbics will **NOT** use it. This is because for some elements, there exist **both all-electron basis set and valence-only basis set with pseudopotential** at the same time, so you should make it clear in the input file. The valence basis sets and core pseudopotentials are stored in ``qbics/basis`` and ``qbics/pseudopotential``, respectively. For an element, you must use them consistently: .. list-table:: :widths: 8 8 :header-rows: 1 * - Valence Basis Set - Pseudopotential * - def2-X - def2-ecp * - (aug-)cc-X-pp - cc-ecp * - lanlX - lanl-ecp For example, you can use def2-TZVPP and def-ecp for any element, but **NEVER** use def2-TZVPP and lanl-ecp together! Assume you want to calculate B3LYP-D3BJ energy for AuCl\ :sub:`3`, you can use def2- series: .. code-block:: :caption: aucl3-1.inp :linenos: basis def2-tzvp end pseudopotential def2-ecp end scf charge 0 spin2p1 1 end grimmedisp type bj end mol Au 0.00000000 0.00000000 0. Cl 0.00000000 -2.33000000 0. Cl 2.01783919 1.16500000 0. Cl -2.01783919 1.16500000 0. end task energy b3lyp end Or, you may want to use cc-pvdz for chlorine and cc-pvdz-pp for gold, then the input is: .. code-block:: :caption: aucl3-2.inp :linenos: basis element Cl cc-pvdz Au cc-pvdz-pp end pseudopotential cc-ecp end This means that for the valence and core part of gold, cc-pvdz basis set and pseudopotential is used, respectively. Define Your Own Pseudopotential ++++++++++++++++++++++++++++++++++ You can also define your own pseudopotential like we have done for basis set. Again for AuCl\ :sub:`3`, we want to use SBKJC valence basis set and pseudopotentials, then - Go to basis set exchange website: https://www.basissetexchange.org/, choose ``SBKJC-VDZ`` for Au and Cl, and download it using **GAUSSIAN** format. .. image:: /_images/a4.png - Paste basis set and pseudotential definitions in ``basis ... end`` and ``pseudopotential ... end`` block, respectively: .. code-block:: :caption: aucl3-3.inp :linenos: basis # From: https://www.basissetexchange.org/basis/sbkjc-vdz/format/gaussian94/?version=0&elements=17,79 Cl 0 SP 3 1.00 2.225000 -.330980 -.126040 1.173000 0.115280 0.299520 0.385100 0.847170 0.583570 SP 1 1.00 0.130100 0.265340 0.340970 **** Au 0 SP 1 1.00 1.502000 1.000000 1.000000 SP 4 1.00 7.419000 0.222546 0.019924 4.023000 -1.086045 -.299997 1.698000 1.156039 0.748919 0.627100 0.518061 0.504023 SP 1 1.00 0.151500 1.000000 1.000000 SP 1 1.00 0.049250 1.000000 1.000000 D 3 1.00 3.630000 -.087402 1.912000 0.468634 0.842300 0.654805 D 1 1.00 0.375600 1.000000 D 1 1.00 0.154400 1.000000 **** end pseudopotential # From: https://www.basissetexchange.org/basis/sbkjc-vdz/format/gaussian94/?version=0&elements=17,79 CL 0 CL-ECP 2 10 d potential 1 1 4.8748300 -3.4073800 s-d potential 2 0 17.0036700 6.5096600 2 4.1038000 42.2778500 p-d potential 2 0 8.9002900 3.4286000 2 3.5264800 22.1525600 **** AU 0 AU-ECP 4 60 g potential 1 1 4.3876300 -10.7235800 s-g potential 3 0 1.5563600 6.3561200 2 3.7159300 -364.4403900 2 4.0679200 428.1975300 p-g potential 3 0 1.1879800 4.4151800 2 3.0155100 -136.5755000 2 3.5958800 194.2053500 d-g potential 2 0 35.2500000 8.8819800 2 5.0230700 86.7661200 f-g potential 1 0 1.6888100 6.2160300 **** end scf charge 0 spin2p1 1 end grimmedisp type bj end mol Au 0.00000000 0.00000000 0. Cl 0.00000000 -2.33000000 0. Cl 2.01783919 1.16500000 0. Cl -2.01783919 1.16500000 0. end task energy b3lyp end Note, you **MUST** add ``****`` between pseudopential definitions for each element. - Or, you can save both definitions in ``/home/you/calc/SBJKC.txt`` and ``/home/you/calc/SBJKC-ECP.txt``, respectively, and write these file names in the input file: .. code-block:: :caption: aucl3-4.inp :linenos: basis /home/you/calc/SBJKC.txt end pseudopotential /home/you/calc/SBJKC-ECP.txt end Example: Set Special SCF Initial Guess ----------------------------------------------- Qbics supports several ways to set SCF initial guess. The default one is the "superposition of atomic densities", which works quiet well in most cases. Sometimes, one may or must use other ways. Guess From Another Calculations +++++++++++++++++++++++++++++++++ Consider CH\ :sub:`3`\ NH\ :sub:`3`\ :sup:`+`\ OH\ :sup:`-`, we do a B3LYP-D3BJ/6-31g(d) calculation: .. code-block:: :caption: ch3nh3oh-1.inp :linenos: basis 6-31g(d) end scf charge 0 spin2p1 1 end grimmedisp type bj end mol C -0.02909313 -0.38166253 -1.63963825 H 0.82173570 -1.03039025 -1.62769450 H -0.03691367 0.17958863 -2.55059158 H -0.92347728 -0.96516294 -1.57252437 N 0.04484969 0.58404262 -0.44233044 H 0.93923384 1.16754303 -0.50944432 H -0.80597913 1.23277035 -0.45427419 H 0.05267023 0.02279146 0.46862289 O 0.06914388 -0.26694332 2.08310089 H -0.31212699 -0.12725829 2.95299779 end task energy b3lyp end After calculation, we will obtain a file ``ch3nh3oh-1.mwfn``. We can use this as an initial guess for a more expensive calculation, like B3LYP-D3BJ/6-311g(2df,2pd) calculation: .. code-block:: :caption: ch3nh3oh-2.inp :linenos: basis 6-311g(2df,2pd) end scf charge 0 spin2p1 1 end scfguess type mwfn file ch3nh3oh-1.mwfn end grimmedisp type bj end mol C -0.02909313 -0.38166253 -1.63963825 H 0.82173570 -1.03039025 -1.62769450 H -0.03691367 0.17958863 -2.55059158 H -0.92347728 -0.96516294 -1.57252437 N 0.04484969 0.58404262 -0.44233044 H 0.93923384 1.16754303 -0.50944432 H -0.80597913 1.23277035 -0.45427419 H 0.05267023 0.02279146 0.46862289 O 0.06914388 -0.26694332 2.08310089 H -0.31212699 -0.12725829 2.95299779 end task energy b3lyp end Here, ``scfguess ... end`` block controls the initial guess with ``type``, which can be: .. list-table:: :widths: 2 10 :header-rows: 1 * - Option - Meaning * - ``HCore`` - Diagonalization of core Hamiltonian. **NOT** recommended. * - ``AtmDen`` - Superposition of atomic densities. **Default.** * - ``MWFN`` - Read a wave function from a mwfn file given by ``file`` as initial guess. * - ``FragDen`` - Superposition of molecular fragment densities. See below. .. attention:: For an input file ``x.inp``, the program will rewrite ``x.mwfn`` during the calculation, so if you want to keep the ``x.mwfn``, you can copy it to something like ``x-1.mwfn``, and write .. code-block:: bash scfguess type mwfn file x-1.mwfn end Then the program will read ``x-1.mwfn`` for initial guess but not overwrite ``x.mwfn``. Guess From Fragment Superposition ++++++++++++++++++++++++++++++++++++ Consider CH\ :sub:`3`\ NH\ :sub:`3`\ :sup:`+`\ OH\ :sup:`-`, it seems to be logical that one can use the superposition of CH\ :sub:`3`\ NH\ :sub:`3`\ :sup:`+` and OH\ :sup:`-` as initial guess. This is very easy: .. code-block:: :caption: ch3nh3oh-3.inp :linenos: basis 6-311g(2df,2pd) end scf charge 0 spin2p1 1 end scfguess type fragden frag +1 1 1-8 frag -1 1 9 10 end grimmedisp type bj end mol C -0.02909313 -0.38166253 -1.63963825 H 0.82173570 -1.03039025 -1.62769450 H -0.03691367 0.17958863 -2.55059158 H -0.92347728 -0.96516294 -1.57252437 N 0.04484969 0.58404262 -0.44233044 H 0.93923384 1.16754303 -0.50944432 H -0.80597913 1.23277035 -0.45427419 H 0.05267023 0.02279146 0.46862289 O 0.06914388 -0.26694332 2.08310089 H -0.31212699 -0.12725829 2.95299779 end task energy b3lyp end Here, ``type fragden`` means we will use superposition of fragments as initial guess. The fragments can be defined with ``frag``: ``frag +1 1 1-8`` The first and second number is the charge and spin multiplicity of the fragment. Then is the atom indices for this fargment. It can be discontinuous like: ``frag +1 1 1 2 5 8-12 15`` In this case, the atom ``1 2 5 8 9 10 11 12 15`` will be a fragment. You can define any numbers of fragments. To determine the atomic indices, it is very convienent to use `Qbics-MolStar `_. Just drag ``ch3nh3oh-3.inp`` into explore, right-click :guilabel:`All`, then click :guilabel:`Add Component`, then click :guilabel:`Label` in :guilabel:`Representation`, then click :guilabel:`+ Create Component`, you can see clearly the atomic indices: .. image:: /_images/a5.png SCF Convergence Condition ---------------------------- There are 3 options in ``scf ... end`` block to control the convergence condition: .. code-block:: scf energy_cov 1.E-6 density_cov 1.E-6 max_it 100 end Here, ``energy_cov`` and ``density_cov`` means that the SCF is thought to converge when the energy and density change is smaller than ``1.E-6`` and ``1.E-6``, respectively. ``max_it`` means the maximum number of SCF iterations. You can change these when you need. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these pages: - :doc:`../keywords/xtb` - :doc:`../keywords/nddo` - :doc:`../keywords/mol` Semi-empirical Quantum Chemistry Methods ========================================= .. contents:: :local: This tutorial will lead you step by step to do semi-empirical quantum chemistry calculations using Qbics. There are two semi-empirical methods implemented in Qbics: xTB and NDDO (neglect of diatomic differential overlap). While xTB is a modern one with better accuracy and speed, NDDO is a traditional semi-empirical method, which is still widely used in many fields. Note that NDDO is a series of methods, including AM1, PM3, PM6, etc, which are all available in Qbics. xTB can be applied for elements from H to Rn (Z=86), while NDDO is only for elements from H to Cl (Z=17). xTB is more accurate than NDDO in general, but NDDO has some special parameterizations for specific systems, such as biomolecules. You can choose either one according to your needs. Example: xTB for Ligand-protecing Gold Clusters ------------------------------------------------- We will use xTB to calculate the binding energy of a ligand-protecting gold cluster, Au\ :sub:`18`\ (C\ :sub:`6`\ H\ :sub:`11`\ S)\ :sub:`14`, which is a model for gold nanoparticles: .. image:: /_images/a14.jpg The input file is: .. code-block:: :caption: aulig.inp :linenos: mol Au 6.95958 2.87913 2.94614 S 9.08599 3.67339 2.88510 S 4.89113 1.81941 3.01855 Au 5.82923 4.53162 5.05796 Au 4.13669 3.38239 1.49897 Au 5.79250 5.99300 2.82997 Au 8.65595 5.47861 4.26420 S 3.33616 4.66634 -0.18204 Au 3.45811 5.08053 3.76279 S 8.56081 7.20090 5.75077 Au 6.24304 7.42405 5.38760 S 7.04744 3.53845 6.81588 Au 3.89147 6.19365 6.32206 Au 6.56834 5.22532 8.23897 S 6.65568 7.45648 1.19187 Au 3.92517 7.94284 4.15361 Au 3.18725 6.66426 1.06638 Au 6.51959 9.17260 2.68377 S 1.11550 4.78967 4.09094 Au 0.97656 6.80219 5.13736 S 3.01320 8.66765 2.07979 S 6.26671 7.02193 9.67527 Au 5.18561 8.18601 7.95848 Au 5.18171 9.94301 5.85487 S 3.00776 5.17778 8.25337 Au 2.88045 8.79374 6.73399 S 0.61480 8.81770 6.18653 S 6.59196 10.92950 4.17781 Au 3.60146 10.47321 8.93384 Au 2.73505 7.19691 9.38807 S 3.42541 8.93876 10.69319 S 4.56391 11.83306 7.37982 C 4.95046 0.19661 2.19906 C 4.13304 0.27617 0.92539 C 6.43827 -0.19882 1.91962 H 4.54937 -0.47352 2.79236 C 4.32830 -1.08837 0.26931 H 4.45695 0.98625 0.34829 H 3.19681 0.43452 1.12181 C 5.75611 -1.40758 -0.15592 H 4.03232 -1.77426 0.88894 H 3.75560 -1.14070 -0.51433 C 6.56085 -1.57337 1.12181 H 5.78086 -2.22375 -0.68037 H 6.11951 -0.68416 -0.69252 H 7.48911 -1.76356 0.91526 H 6.20590 -2.30489 1.65233 H 6.91097 -0.27514 2.76401 H 6.86172 0.50545 1.40529 C 9.82213 2.61150 4.17741 C 11.27211 3.02202 4.31713 C 9.74817 1.08389 3.77445 H 9.35450 2.75237 5.02585 C 10.56493 0.41654 4.92663 H 8.83144 0.76495 3.75825 H 10.15792 0.92343 2.90981 C 12.02599 0.81419 4.94688 H 10.16185 0.65719 5.77507 H 10.50409 -0.54817 4.83551 C 12.15597 2.23072 5.30934 H 12.50229 0.26663 5.59080 H 12.41786 0.66328 4.07414 H 13.08043 2.51488 5.23847 H 11.85571 2.37597 6.22055 H 11.29164 3.95583 4.58037 H 11.68263 2.96345 3.44034 C 4.66625 4.65474 -1.39922 C 4.08243 5.21781 -2.70732 C 5.34316 3.30509 -1.70701 H 5.36069 5.27536 -1.09143 C 5.11020 5.41339 -3.85747 H 3.66929 6.07468 -2.51697 H 3.38482 4.61959 -3.01510 C 5.75779 4.03509 -4.14096 H 4.66354 5.74193 -4.65326 H 5.78875 6.05533 -3.59626 C 6.40351 3.59895 -2.71947 H 6.44382 4.10772 -4.82336 H 5.09199 3.38992 -4.43052 H 6.95572 2.81229 -2.84501 H 6.97114 4.31314 -2.39345 H 5.73476 2.93101 -0.90109 H 4.69806 2.67321 -2.06137 C 8.43376 7.22633 1.27772 C 8.75735 8.28980 0.28956 C 8.35307 5.81798 0.56900 H 8.85999 7.27198 2.15856 C 9.69198 5.73389 -0.12554 H 8.24574 5.10410 1.21495 H 7.62278 5.78581 -0.06682 C 9.96941 6.72193 -1.21293 H 10.38502 5.82694 0.54673 H 9.77560 4.84353 -0.50420 C 10.00162 8.16508 -0.53458 H 9.27489 6.68456 -1.88925 H 10.82171 6.53031 -1.63411 H 10.78731 8.25471 0.02835 H 10.02631 8.85607 -1.21293 H 8.80872 9.13067 0.77149 H 8.00761 8.35930 -0.32196 C 6.50278 1.84108 7.01432 C 7.28044 0.78458 6.26712 C 5.01755 1.78217 6.64983 H 6.57149 1.62563 7.96806 C 4.62585 0.27870 6.86447 H 4.87778 2.04901 5.72850 H 4.49708 2.36180 7.22896 C 5.32148 -0.69994 6.03831 H 4.78156 0.05322 7.79391 H 3.67418 0.18804 6.70046 C 6.86575 -0.64443 6.40482 H 5.19434 -0.49612 5.09875 H 4.97170 -1.58883 6.20840 H 7.00953 -0.95193 7.31401 H 7.37939 -1.20492 5.80342 H 7.24906 1.00744 5.32351 H 8.20707 0.84878 6.54251 C 0.20628 5.07898 2.57975 C -1.17788 5.60632 2.82071 C 0.12299 3.68230 1.96215 H 0.70535 5.68323 1.99050 C -2.09672 5.44393 1.59766 H -1.12354 6.54642 3.05358 H -1.56781 5.13549 3.57398 C -2.13396 4.00151 1.13800 H -2.99320 5.73375 1.82850 H -1.77409 6.00689 0.87679 C -0.77977 3.40755 0.79984 H -2.70051 3.94240 0.35234 H -2.54195 3.46517 1.83458 H -0.85827 2.45198 0.65607 H -0.42430 3.81421 -0.00607 H 1.02042 3.43820 1.69081 H -0.13232 3.07325 2.67289 C 1.22368 8.95953 2.26183 C 1.12729 10.21342 3.03333 C 0.58490 8.92423 0.89906 H 0.84462 8.23475 2.80046 C -0.33067 10.76335 3.01510 H 1.72744 10.87617 2.65264 H 1.40251 10.05251 3.94859 C -0.94306 10.81773 1.64018 H -0.88199 10.20064 3.58208 H -0.33207 11.65642 3.39579 C -0.86444 9.45049 0.98209 H -0.46965 11.47057 1.09953 H -1.87007 11.09632 1.70701 H -1.23397 9.50606 0.08707 H -1.40292 8.82297 1.48832 H 0.58426 8.01529 0.56293 H 1.09749 9.47365 0.28551 C 9.36023 8.74574 5.21214 C 10.86188 8.70547 5.36199 C 8.95878 10.12481 5.70825 H 9.21073 8.77731 4.24423 C 11.60848 10.07555 4.97725 H 11.21015 7.99337 4.80108 H 11.07472 8.48276 6.28130 C 11.02957 11.31196 5.49158 H 12.52433 10.01664 5.29314 H 11.64061 10.13767 4.00934 C 9.64347 11.22271 4.97928 H 11.48770 12.09264 5.14127 H 11.04890 11.33807 6.46152 H 9.64988 11.03765 4.02756 H 9.17822 12.06083 5.12507 H 8.00026 10.23061 5.60903 H 9.16848 10.19519 6.65186 C 1.34521 4.56248 7.90731 C 1.40899 3.18816 7.18441 C 0.54823 4.35183 9.30855 H 0.86252 5.20662 7.34641 C -0.07413 2.78935 7.12974 H 1.78534 3.27425 6.29547 H 1.92910 2.54705 7.69267 C -0.80128 2.46805 8.41759 H -0.55555 3.50944 6.69438 H -0.14563 2.01082 6.55264 C -0.86288 3.76310 9.11619 H -1.69120 2.12632 8.23940 H -0.31186 1.81328 8.94002 H -1.28564 3.64254 9.98083 H -1.40450 4.38118 8.59983 H 1.06264 3.75719 9.87755 H 0.47489 5.20576 9.76213 C -0.54610 8.85187 7.55700 C -1.42383 7.61911 7.56712 C 0.13609 9.11399 8.90357 H -1.14205 9.61310 7.39500 C -0.81332 9.13457 10.11650 H 0.59493 9.96753 8.85497 H 0.80788 8.42822 9.04734 C -1.61822 7.79848 10.15294 H -1.42237 9.88711 10.04562 H -0.30118 9.23490 10.93456 C -2.33420 7.77525 8.81447 H -1.02569 7.03632 10.24407 H -2.25370 7.79342 10.88596 H -2.83653 8.60120 8.72538 H -2.97165 7.04481 8.82257 H -0.88524 6.81500 7.63597 H -1.95664 7.57099 6.75918 C 5.66496 11.91514 3.03738 C 4.48325 12.57713 3.69345 C 6.75652 13.09456 3.09408 H 5.50202 11.51720 2.15654 C 4.01247 13.67426 2.75186 H 4.74047 12.95485 4.54999 H 3.77295 11.93342 3.84127 C 4.95307 14.81578 2.67492 H 3.89878 13.30013 1.86293 H 3.14769 13.99831 3.04953 C 6.28899 14.17196 2.16059 H 5.07738 15.22261 3.54563 H 4.63300 15.48946 2.05529 H 6.14907 13.79575 1.27772 H 6.97282 14.85592 2.09174 H 6.83302 13.43874 3.99719 H 7.62357 12.76089 2.81666 C 7.95025 7.70554 9.46245 C 9.08324 7.19276 10.30481 C 7.56261 9.04330 10.05575 H 8.19986 7.78177 8.51883 C 8.71371 9.99070 9.74796 H 7.43198 8.96562 11.01353 H 6.73901 9.36744 9.65481 C 10.01359 9.54163 10.38176 H 8.83261 10.04465 8.78612 H 8.49169 10.87665 10.06992 C 10.17136 8.09472 9.87755 H 9.95824 9.57114 11.34967 H 10.75522 10.09727 10.09017 H 10.20460 8.10323 8.90762 H 11.01530 7.73984 10.19749 H 8.89533 7.28281 11.25247 H 9.28629 6.26536 10.10435 C 3.58120 8.97738 12.45325 C 3.87228 7.63942 12.91696 C 4.76190 9.97412 12.52412 H 2.77621 9.34003 12.88051 C 5.22516 10.02524 13.96587 H 5.48641 9.67955 11.95107 H 4.47681 10.85355 12.23254 C 4.31547 9.13888 14.84873 H 5.19805 10.94040 14.28378 H 6.14155 9.71264 14.02459 C 4.30411 7.70335 14.37287 H 4.62974 9.17209 15.76602 H 3.41121 9.49129 14.83051 H 3.69312 7.18421 14.91758 H 5.19018 7.32063 14.46602 H 4.58019 7.25029 12.37833 H 3.08262 7.08128 12.82989 C 6.12615 12.74745 7.11152 C 5.69265 14.15817 6.96775 C 6.88685 12.44111 8.39531 H 6.60533 12.43112 6.31775 C 8.18621 13.33378 8.61401 H 7.14883 11.50780 8.38721 H 6.29036 12.57167 9.15061 C 7.69055 14.76319 8.40949 H 8.54378 13.21441 9.50699 H 8.87278 13.10822 7.96603 C 7.19952 14.81323 6.96572 H 8.41121 15.39975 8.54921 H 6.97027 14.96791 9.02506 H 7.78915 14.30147 6.38862 H 7.16999 15.72812 6.64578 H 5.15832 14.46117 7.72102 H 5.21541 14.31654 6.13753 end xtb chrg 0 uhf 0 gfn 1 end task energy xtb end Then run it: .. code-block:: bash $ qbics aulig.inp -n 4 > aulig.out Here, ``-n 4`` means Qbics will use 4 CPU cores for parallization. xTB is controlled by the ``xtb`` block: - ``chrg`` and ``uhf`` keywords define the charge and number of unpaired electrons of the system, respectively. - ``gfn`` keyword defines which version of xTB will be used. Currently, Qbics supports GFN1-xTB (``gfn 1``) and GFN2-xTB (``gfn 2``). You can choose one of them according to your needs. In this example, we use GFN1-xTB (``gfn 1``). According to our experience, for systems **NOT containing too many metallic atoms**, GFN1-xTB is is much better. For other systems, GFN2-xTB is better. You can also use implicit solvent model in xTB calculations with ``gbsa``: .. code-block:: :linenos: xtb chrg 0 uhf 0 gfn 1 gbsa h2o end So the solvent ``h2o`` will be used in the xTB calculation. The list of all supported solvents can be found in :doc:`../keywords/xtb`. Without giving ``gbsa``, the xTB calculation will be done in gas phase. In ``aulig.out``, you will find the energy: .. code-block:: :caption: aulig.out :linenos: xTB Iteration ... done (3.087 seconds) Total xTB energy: -382.97973634 Hartree Final total energy: -382.97973634 Hartree In ``aulig.inp``, you can change ``energy`` to ``opt`` to do geometry optimization, or ``md`` to do molecular dynamics simulation. For more information, please refer to :doc:`opt` and :doc:`md`, respectively. .. hint:: Qbics only supports a part of the xTB functions. Some functions like GFN0-xTB are not supported. If you want to use these functions, please use the original xTB program: ``_. Example: AM1 and PM3 for An Organic Anion ------------------------------------------------- We will use NDDO to calculate the energy of an organi anion, C\ :sub:`11`\ H\ :sub:`17`\ SO\ :sub:`3`\ :sup:`-`: .. image:: /_images/a15.jpg We will first use AM1. The input file is: .. code-block:: :caption: c11h17so3-1.inp :linenos: mol C -0.05133195 0.13820273 -0.07408260 H 1.06386427 0.23393150 -0.04053791 H -0.48221807 1.16269423 -0.21129857 C -0.55764462 -0.46814486 1.23108862 H -0.25721997 0.18955243 2.08945318 C -0.45901605 -0.75614552 -1.24106425 H -0.08318986 -0.31245213 -2.20112418 C 0.13909675 -2.14772780 -1.05064293 H 1.25634763 -2.07769530 -1.02321562 H -0.14484400 -2.80323400 -1.91285383 C 0.04667328 -1.85701716 1.40913664 H -0.28851614 -2.29736205 2.38206320 H 1.16439595 -1.78130414 1.43736333 C -0.37460514 -2.75694197 0.25288279 H 0.05838753 -3.78596700 0.40210267 C -1.90186350 -2.87990458 0.16288292 H -2.14499703 -3.44910342 -0.78452731 C -2.50285637 -3.65508897 1.30500807 C -2.07739083 -0.58718463 1.18573116 H -2.53453817 0.42961535 1.07690940 H -2.44934230 -1.03769263 2.14165477 C -1.98072027 -0.85710196 -1.28599969 H -2.42386255 0.16167103 -1.42776124 H -2.29241214 -1.49373089 -2.15289033 C -2.49210287 -1.47123081 0.01543189 H -3.61168946 -1.54021627 -0.01947598 S -2.36143038 -5.42667342 1.13627320 O -2.91083500 -5.72787974 -0.13380691 O -3.12407542 -5.92344897 2.22190957 O -0.97593034 -5.70753864 1.23827617 H -3.59090253 -3.41118657 1.38165847 H -2.04104042 -3.35568384 2.27489529 end nddo charge -1 spin2p1 1 end task energy am1 end The usage of NDDO is similar to DFT. The ``mol`` section defines the molecule, and the ``nddo`` section defines the charge (``charge``) and spin multiplicity (``spin2p1``) of the system. To use PM3, you can change the method to PM3 by replacing ``am1`` with ``pm3`` in the ``task`` section: .. code-block:: :caption: c11h17so3-2.inp :linenos: task energy pm3 end Of course, you can change ``energy`` to ``opt`` to do geometry optimization, or ``md`` to do molecular dynamics simulation. For more information, please refer to :doc:`opt` and :doc:`md`, respectively. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these pages: - :doc:`../keywords/charmm` - :doc:`../keywords/mol` For generating topology of organic molecules and biomolecules, please refer to **pdbtop** (``_). Molecular Mechanics Calculations ========================================= This tutorial will lead you step by step to do molecular mechanics (MM) calculations using Qbics. In Qbics, MM means CHARMM potential. For geometry optimization and molecular dynamics, please refer to :doc:`opt` and :doc:`md`. Topology and Parameters ---------------------------------- An MM calculation needs more steps since you must set up **topology** and **parameters** for the molecule. - **Topology** defines the bonds, angles, dihedrals, impropers and atomic charges. Qbics uses **PSF** file to record topology. - **Parameters** are those for bonding and nonbonding energy terms. Qbics uses **CHARMM** format parameter files. .. tip:: For CHARMM files, ``par*`` usually contains only parameters, ``top*`` usually contains only topologies, but ``toppar*`` contains both parameters and topologies. Qbics often fails to parse ``toppar*``, so you have to delete topology information in ``toppar*`` and keep only parameter information. Building topology and parameters of a system for MM calculations is probably the most difficult and error-prone step. There are many different ways to build topology for the same system: - Manually; - (**Strongly recommended**) Using **pdbtop** (``_); - Using **ABCluster** (``_); - Using **VMD** (``_); - Using **CHARMM-GUI** (``_). We strongly recommend to use `pdbtop `_ since it is highly compatible with Qbics. pdbtop cna be used to add hydrogens, add counterions, solvate in box or droplet, and treat covalently bonded ligands. To use pdbtop, please refer: - Download pdbtop: ``_ - pdbtop manual: ``_ In the following, we will give 2 examples. Both will be used in the QM/MM tutorial :doc:`qmmm`. Solvated Protein 5VBM ---------------------------------- Here, we want to do a calculation with a protein, whose PDB ID is 5VBM. To convert a protein from PDB bank to a format that Qbics can read, please follow the procedure given here: ``_. Finally, we get a protein solvated in water, whose coordinates and topology are stored in ``5vbm-sol.pdb`` and ``5vbm-sol.psf``, respectively. You can use `Qbics-MolStar `_ to visualize it, note that load topology ``5vbm-sol.psf`` in :guilabel:`Model` and coordinates ``5vbm-sol.pdb`` in :guilabel:`Coordinates`: .. figure:: /_images/a6.png Now, we need force field parameters. You can go to CHARMM website ``_ to download force field parameters, just select ``toppar_c36_jul24.tgz``, download and decompress it. Put ``par_all36m_prot.prm`` (parameters for protein) and ``toppar_water_ions.str`` (parameters for water and ions) to your current path. Now prepare the input file: .. code-block:: :caption: 5vbm-sol.inp :linenos: charmm # Here: # toppar_water_ions.str: the parameter file for water and ions. # par_all36m_prot.prm: the parameter file for proteins. # Both are obtained from website: https://mackerell.umaryland.edu/charmm_ff.shtml. parameters toppar_water_ions.str par_all36m_prot.prm topology 5vbm-sol.psf scaling14 1.0 rcutoff 12.0 rswitch 10.0 use_PBC # Add this line to turn on PBC. Lbox 70 70 70 # Define the box size. electrostatic pme # Use PME for electrostatics. PMEk 72 72 72 end mol 5vbm-sol.pdb end task energy charmm end Now run the calculation: .. code-block:: bash $ qbics 5vbm-sol.inp -n 4 > 5vbm-sol.out Here, ``-n 4`` means Qbics will use 4 CPU cores for parallization. This calculation is very fast. After calculation, check ``5vbm-sol.out``: .. code-block:: :caption: 5vbm-sol.out :linenos: CHARMM energies =============== Bond energy: 7661.69410280 kcal/mol Angle energy: 5772.78601511 kcal/mol Dihedral energy: 1557.76413669 kcal/mol Improper energy: 30.51152972 kcal/mol Coulombic energy: -2120.48409716 kcal/mol Lennard-Jones energy: 11507712434764.78906250 kcal/mol --------------------------------------------------- CHARMM energy: 11507712447667.06054688 kcal/mol This energy is very large, since the water box are generated randomly. You must optimize structure for any useful calculations. This will be introduced in :doc:`opt`. Now we will explain the input ``5vbm-sol.inp`` of the last example. - Anything after ``#`` is treated as comments. You can write anything anywhere in the input file. - ``charmm ... end`` This block defines the CHARMM force field. * ``parameters`` The CHARMM parameter files. You can provide many ones. * ``topology`` The topology of the system in PSF format. * ``scaling14`` The scaling factor for 1-4 interactions. For CHARMM calculations, ``1.0`` is preferred. * ``rcutoff`` and ``rswitch`` The cutoff and switch distance (in Angstrom) for nonbonded interactions. * For van der Waals interactions, they are the switch and cutoff distances for the switching function. * For electrostatic interaction energies: when ``electrostatic`` is ``cutoff``, they are the switch and cuttoff distances for its switching function; when ``electrostatic`` is ``pme``, ``rcutoff`` is the cutoff distance for short-range part, and ``rswitch`` is not used. * ``use_pbc`` The periodic boundary condition (PBC) is used. If it is not present, a gas phase calculation is applied. * ``Lbox`` The 3 lengths (in Angstrom) of the simulation box. Only valid when ``use_pbc`` is applied. * ``electrostatic`` The calculation method of electrostatic energy, which can be cut off at a certain distance, or particle mesh Ewald (PME) algorithm. For gas phase calculations, only ``cutoff`` is allowed; when PBC is turned on, one can use either ``pme`` (you should almost **ALWAY** use this for pure MM calculations) or ``cutoff`` (only used in QM/MM calculations). * ``PMEk`` The number of K points on 3 lengths of the box for PME calculations. It is recommended to be an integer that is **close** to the box length and is factorized to **only 2, 3, and 5.** - ``mol ... end`` This block gives the molecule coordinates. Unlike in :doc:`dft`, we just give the file name。 - ``task ... end`` This tells Qbics what it should do. ``energy charmm`` means it will use CHARMM force field to calculate energy. You can put several tasks in this block. Oragnic Molecule 92V ------------------------------- In many applications, you need to do MM calculations for small molecule in gas phase. This involves how to generate the topology and parameters for an arbitrary molecule. This can be easily done with `pdbtop `_. Here, we consider a ligand called 92V. To obtain the topology and paramters of this molecule, please follow the proceduer given here: ``_. What we need are: topology ``92v-2.psf``, parameters ``92v-1-naive.prm``, and structure ``92v.pdb``. Qbics can automatically parse PDB format. You can also use XYZ format if you prefer. To calculate its CHARMM energy in gas phase, use the following input: .. code-block:: :caption: 92v.inp :linenos: charmm parameters 92v-1-naive.prm topology 92v-2.psf scaling14 1.0 rcutoff 12.0 rswitch 100.0 # rswitch>rcutoff means no cutoff is used. end mol 92v.pdb end task energy charmm end Here we want to point out: - There is no ``use_pbc`` in ``charmm...end``, suggesting that this is a gas phase calculation. - Here, ``rswitch`` is greater than ``rcutoff``, this means **NO** cutoff is applied: all interactions are calculated! After calculation, we can find energies: .. code-block:: :caption: 92v.out :linenos: CHARMM energies =============== Bond energy: 79.40377426 kcal/mol Angle energy: 12.30743545 kcal/mol Dihedral energy: 93.12335114 kcal/mol Improper energy: 0.00000000 kcal/mol Coulombic energy: -116.19015178 kcal/mol Lennard-Jones energy: 31.73702659 kcal/mol --------------------------------------------------- CHARMM energy: 100.38143566 kcal/mol Final total energy: 100.38143566 kcal/mol .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these pages: - :doc:`../keywords/opt` - :doc:`../keywords/xtb` Geometry Optimization ========================================= .. contents:: :local: This tutorial will lead you step by step to do geometry optimization calculations using Qbics. Assume you have read :doc:`dft` or :doc:`charmm`. For optimization of transition states, please refer to :doc:`ts`. Geometry optimization is to find the minimum energy structure of a molecule. It is a common task in computational chemistry and materials. As long as you can do energy calculation, simply chaning ``energy`` to ``opt`` in the input file, you can do geometry optimization. Example: DFT for CH\ :sub:`3`\ CH\ :sub:`2`\ SO\ :sub:`3`\ H ----------------------------------------------------------------------- For DFT, we can do geometry optimization at B3LYP-D3BJ/def2-svp level of theory for the molecule CH\ :sub:`3`\ CH\ :sub:`2`\ SO\ :sub:`3`\ H. The input file is as follows: .. code-block:: :caption: ch3ch2so3h.inp :linenos: basis def2-svp end scf charge 0 spin2p1 1 end grimmedisp type bj end mol S 0.00000 0.00000 0.00000 O 1.37599 0.00000 0.00000 O -0.71199 1.18363 0.00000 O -0.45996 -0.69162 -1.43483 H -0.82001 -0.11945 -2.10909 C -0.62121 -1.12008 1.07039 H 0.14029 -1.49066 1.80382 H -1.47518 -0.71991 1.67461 C -1.14768 -2.34547 0.38391 H -0.34399 -2.85090 -0.10958 H -1.58848 -2.99835 1.10803 H -1.88611 -2.06128 -0.33641 end task opt b3lyp end During optimization, Qbics will write the latest optimized structure to ``ch3ch2so3h-opt.xyz``, and the optimization process will be written to ``ch3ch2so3h-opt-traj.xyz``. You can visualize the optimization process using `Qbics-MolStar `_. After optimization, we can see the energies by this command: .. code-block:: bash $ grep "E = " ch3ch2so3h-opt-traj.xyz | cat -n 1 E = -703.24635624 Hartree; coordinates in Angstrom. 2 E = -703.25408101 Hartree; coordinates in Angstrom. 3 E = -703.27695102 Hartree; coordinates in Angstrom. 4 E = -703.28018008 Hartree; coordinates in Angstrom. 5 E = -703.28163730 Hartree; coordinates in Angstrom. 6 E = -703.28278993 Hartree; coordinates in Angstrom. 7 E = -703.28366187 Hartree; coordinates in Angstrom. 8 E = -703.28479281 Hartree; coordinates in Angstrom. 9 E = -703.28607847 Hartree; coordinates in Angstrom. 10 E = -703.28606122 Hartree; coordinates in Angstrom. 11 E = -703.28666766 Hartree; coordinates in Angstrom. 12 E = -703.28677457 Hartree; coordinates in Angstrom. 13 E = -703.28709275 Hartree; coordinates in Angstrom. 14 E = -703.28735283 Hartree; coordinates in Angstrom. 15 E = -703.28758537 Hartree; coordinates in Angstrom. 16 E = -703.28770103 Hartree; coordinates in Angstrom. 17 E = -703.28775039 Hartree; coordinates in Angstrom. 18 E = -703.28777717 Hartree; coordinates in Angstrom. 19 E = -703.28779907 Hartree; coordinates in Angstrom. 20 E = -703.28782446 Hartree; coordinates in Angstrom. 21 E = -703.28783816 Hartree; coordinates in Angstrom. 22 E = -703.28786067 Hartree; coordinates in Angstrom. 23 E = -703.28786999 Hartree; coordinates in Angstrom. 24 E = -703.28787815 Hartree; coordinates in Angstrom. 25 E = -703.28788727 Hartree; coordinates in Angstrom. 26 E = -703.28789946 Hartree; coordinates in Angstrom. 27 E = -703.28792996 Hartree; coordinates in Angstrom. 28 E = -703.28798086 Hartree; coordinates in Angstrom. 29 E = -703.28805214 Hartree; coordinates in Angstrom. 30 E = -703.28821936 Hartree; coordinates in Angstrom. 31 E = -703.28858252 Hartree; coordinates in Angstrom. 32 E = -703.28826689 Hartree; coordinates in Angstrom. 33 E = -703.28902797 Hartree; coordinates in Angstrom. 34 E = -703.28916009 Hartree; coordinates in Angstrom. 35 E = -703.28936878 Hartree; coordinates in Angstrom. 36 E = -703.28949234 Hartree; coordinates in Angstrom. 37 E = -703.28966812 Hartree; coordinates in Angstrom. 38 E = -703.28983363 Hartree; coordinates in Angstrom. 39 E = -703.28987269 Hartree; coordinates in Angstrom. 40 E = -703.29037808 Hartree; coordinates in Angstrom. 41 E = -703.29064316 Hartree; coordinates in Angstrom. 42 E = -703.29099480 Hartree; coordinates in Angstrom. 43 E = -703.29143705 Hartree; coordinates in Angstrom. 44 E = -703.29170664 Hartree; coordinates in Angstrom. 45 E = -703.29220829 Hartree; coordinates in Angstrom. 46 E = -703.29260499 Hartree; coordinates in Angstrom. 47 E = -703.29312866 Hartree; coordinates in Angstrom. 48 E = -703.29323150 Hartree; coordinates in Angstrom. 49 E = -703.29367916 Hartree; coordinates in Angstrom. 50 E = -703.29379655 Hartree; coordinates in Angstrom. 51 E = -703.29399614 Hartree; coordinates in Angstrom. 52 E = -703.29413105 Hartree; coordinates in Angstrom. 53 E = -703.29421491 Hartree; coordinates in Angstrom. 54 E = -703.29430457 Hartree; coordinates in Angstrom. 55 E = -703.29434373 Hartree; coordinates in Angstrom. 56 E = -703.29437098 Hartree; coordinates in Angstrom. 57 E = -703.29437738 Hartree; coordinates in Angstrom. 58 E = -703.29437298 Hartree; coordinates in Angstrom. 59 E = -703.29436155 Hartree; coordinates in Angstrom. 60 E = -703.29435907 Hartree; coordinates in Angstrom. 61 E = -703.29435586 Hartree; coordinates in Angstrom. 62 E = -703.29435027 Hartree; coordinates in Angstrom. 63 E = -703.29435261 Hartree; coordinates in Angstrom. The energy has converged to ``-703.29435261 Hartree``, which is the final energy of the optimized structure. It has taken 63 steps to converge. Example: xTB Pre-optimization befor DFT Geomtry Optimization -------------------------------------------------------------- In the above example, the starting geometry is very bad, so it took 63 steps. Therefore, we can use :doc:`../keywords/xtb` to do a pre-optimization before DFT optimization, which is very fast: .. code-block:: :caption: ch3ch2so3h-xtb.inp :linenos: basis def2-svp end scf charge 0 spin2p1 1 end grimmedisp type bj end mol S 0.00000 0.00000 0.00000 O 1.37599 0.00000 0.00000 O -0.71199 1.18363 0.00000 O -0.45996 -0.69162 -1.43483 H -0.82001 -0.11945 -2.10909 C -0.62121 -1.12008 1.07039 H 0.14029 -1.49066 1.80382 H -1.47518 -0.71991 1.67461 C -1.14768 -2.34547 0.38391 H -0.34399 -2.85090 -0.10958 H -1.58848 -2.99835 1.10803 H -1.88611 -2.06128 -0.33641 end task opt xtb end This optimization only take several seconds. The final optimized structure is written to ``ch3ch2so3h-xtb-opt.xyz``. We can use it as the starting geometry for DFT optimization: .. code-block:: :caption: ch3ch2so3h-dft.inp :linenos: basis def2-svp end scf charge 0 spin2p1 1 end grimmedisp type bj end mol ch3ch2so3h-xtb-opt.xyz end task opt xtb end This task takes only 17 steps to converge to ``-703.29434128 Hartree``, which is very close to the one from direct DFT optmization, but is much faster! Example: DFT Geomtry Optimization with Constraints -------------------------------------------------------------- We can apply some constraints for geometry optimization. First, let us visualize this molecule with `Qbics-MolStar `_. Just drag ``ch3ch2so3h.inp`` into `Qbics-MolStar `_, then right-click :guilabel:`All`, then click :guilabel:`Add Component`, then click :guilabel:`Label` in :guilabel:`Representation`, then click :guilabel:`+ Create Component`, you can see clearly the atomic indices: .. figure:: /_images/a7.png Now, we want to fix the bond 4-5 and torsion 9-6-1-4, we can use the following input: .. code-block:: :caption: ch3ch2so3h-cons.inp :linenos: basis def2-svp end scf charge 0 spin2p1 1 end grimmedisp type bj end opt fix_bond 4 5 fix_torsion 9 6 1 4 end mol S 0.00000 0.00000 0.00000 O 1.37599 0.00000 0.00000 O -0.71199 1.18363 0.00000 O -0.45996 -0.69162 -1.43483 H -0.82001 -0.11945 -2.10909 C -0.62121 -1.12008 1.07039 H 0.14029 -1.49066 1.80382 H -1.47518 -0.71991 1.67461 C -1.14768 -2.34547 0.38391 H -0.34399 -2.85090 -0.10958 H -1.58848 -2.99835 1.10803 H -1.88611 -2.06128 -0.33641 end task opt b3lyp end This is very easy: just add constraints to ``opt...end``. Some exmaples of constraints are: - ``fix_atoms 1-4 8 10-11``: Fix atoms: ``1 2 3 4 8 10 11``; - ``fix_bond 4 5``: Fix the bond 4-5; - ``fix_angle 5 7 9``: Fix the angle 5-7-9; - ``fix_torsion 1 3 4 5``: Fix the torsion 1-3-4-5. There can be an arbitrary number of constraints. After calculation, it converge to ``-703.28739992 Hartree``, with fixed bond length and torsion. This can also be seen with `Qbics-MolStar `_. Drag ``ch3ch2so3h-cons-opt-traj.xyz`` into `Qbics-MolStar `_. Then, click atom 4 and 5, and then right-click one atom, click :guilabel:`Measure Distance` to shown the bond length; for the torsion, do the similar. Then, click the icon at the left-up corner, and click :guilabel:`Start` to play the trajectory. You can see that the bond length and torsion are successfully constrained. For comparison, we also shoa a bond length that is not constrained. .. figure:: /_images/a8.gif Example: MM for Solvated Protein 5VBM ----------------------------------------- For a MM system, a geometry optimization is also necessary. For the solvated protein 5VBM system given in :doc:`charmm`, we can optimize the geometry by simply changing ``energy`` to ``opt``: .. code-block:: :caption: 5vbm-sol.inp :linenos: charmm # Here: # toppar_water_ions.str: the parameter file for water and ions. # par_all36m_prot.prm: the parameter file for proteins. # Both are obtained from website: https://mackerell.umaryland.edu/charmm_ff.shtml. parameters toppar_water_ions.str par_all36m_prot.prm topology 5vbm-sol.psf scaling14 1.0 rcutoff 12.0 rswitch 10.0 use_PBC # Add this line to turn on PBC. Lbox 70 70 70 # Define the box size. electrostatic pme # Use PME for electrostatics. PMEk 72 72 72 end opt max_step 1000 end mol 5vbm-sol.pdb end task opt charmm end However, since this system contains 40353 atoms, it will take very long to reach the strict stationary point, which is often unnecessary if it is used as an initial structure for molecular dynamic simulations. Thus, we use ``max_step 1000`` in ``opt...end`` to limit the maximum step of optimization to 1000. In its output ``5vbm-sol.out``, we can see that just in 100 steps, the enregy is optimized from the ridiculous value ``11507712447667.06 kcal/mol`` to ``-146029.06 kcal/mol``, which is much more reasonable. Finally, the optimized energy is ``-170315.90 kcal/mol``. Using AI to Generate Qbics Input Files ========================================= .. contents:: :local: This tutorial will give some suggestions to use artificial intelligence (AI) to generate Qbics input files. Qbics is a new program that has been available since 2023, so it is not included in the training corpus of most modern AI models. Fortunately, Qbics has a good documentation, which can be used to train AI models. In the root directory of Qbics documentation, there is a file called ``llms-full.txt``: ``_ ``llms-full.txt`` is a comprehensive plain-text file provided by Qbics, specifically designed to assist AI models (such as large language models, LLMs) in understanding and answering questions about Qbics. For AI or LLM applications, you can uplaod ``llms-full.txt`` to the AI model or ask it to access ``llms-full.txt`` via internet as needed—for example, by segmenting, indexing, or encoding it semantically. You can then integrate it with your chosen large language model to enable knowledge-based Qbics question answering and support. In summary, ``llms-full.txt`` empowers AI solutions to "know" and "understand" Qbics through access to complete documentation, unlocking intelligent services for Qbics users and developers. Example: Using Doubao (豆包) ------------------------------ 1. Open ``_ 2. If you simply ask Doubao to generate a Qbics input file, it will likely generate a file that is **NOT** valid. So, you should **explicitly** ask Kimi to use `llms-full.txt` to generate a valid Qbics input file. Now, download ``llms-full.txt`` from ``_ and upload it to Doubao (for example, drag it to the explorer window of Doubao). 3. Ask Doubao to use ``llms-full.txt`` to generate a valid Qbics input file: .. code-block:: text :caption: Doubao prompt (in English) According to the upload document, write an input file to predict the stable structure of water, using cc-pVDZ basis set .. image:: figs/a49.png Then, Doubao will generate a valid Qbics input file: .. image:: /_images/a50.png This is really very good result. 4. You can also do further modifications, using different languague: .. code-block:: text :caption: Doubao prompt (in Chinese) 帮我把泛函改成tpssh，电荷改成-1，自选多重度改成2 (Help me to change the functional to tpssh, the charge to -1, and the spin multiplicity to 2) Interestingly, I intentionally made a mistake in the prompt ("自选多重度" should be "自旋多重度"), but Doubao still corrected it! Then, Doubao will correctly modify the file: .. image:: /_images/a51.png Example: Using Gemini 3 ------------------------------ 1. Open ``_ 2. If you simply ask Gemini 3 to generate a Qbics input file, it will likely generate a file that is **NOT** valid. So, you should **explicitly** ask Gemini 3 to use `llms-full.txt` to generate a valid Qbics input file. Now, download ``llms-full.txt`` from ``_ and upload it to Gemini 3 (for example, drag it to the explorer window of Gemini 3). 3. Ask Gemini 3 some questions about Qbics: .. code-block:: text :caption: Gemini 3 prompt (in English) I want to predict transition state. What methods are best in Qbics The answers seem to be very good, and examples: .. image:: /_images/a52.png .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these pages: - :doc:`../keywords/opt` - :doc:`../keywords/mecp` Transition State Search ========================================= .. contents:: :local: This tutorial will lead you step by step to search transition states using Qbics. There are two kinds of methods to search transition states in Qbics: - **The QST2/dimer method and the nudged elastic band (NEB) method.** For both methods, a reactant and a product geometry have to be provided. - **The diabatic minimum energy crossing point (dMECP) method.** This method is highly useful for AB+C=A+BC type reactions. Here, only the reactant geometry is needed. .. hint:: In most cases, searching transition states is not a trivial task. You may have to try several starting structures and combine NEB and dimer methods to find the transition state. The following examples are just for demonstration purposes, and may not be suitable for your own calculations. Example: NEB and QST2/Dimer for Amine-Catalyzed Aldol Reaction ----------------------------------------------------------------------------------- In this section, we will search the transition state of the following amine-catalyzed aldol reaction: .. figure:: /_images/a20.jpg The first step is to prepare the input file for the reactant and product geometries. They are given in here: .. tabs:: .. tab:: r1.xyz .. code-block:: :caption: r1.xyz :linenos: 18 Reactant N -0.44812625 -0.05503381 -0.29939653 C 0.28940454 -1.28430107 0.02594994 C 0.42365103 0.85305301 -1.05852939 H 1.14858130 -1.03947388 0.61482595 H -0.34515443 -1.94528943 0.57851603 H 0.60162891 -1.76291266 -0.87867534 C -0.11218661 1.70819672 -1.96305927 H 1.48128134 0.83886150 -0.89692269 H 0.52237224 2.36918599 -2.51562444 H -1.16981687 1.72238788 -2.12466634 C -1.82051925 1.96886205 -0.83651451 H -1.13776031 2.16858444 -0.03723284 C -2.45646906 3.13519149 -1.61551609 O -2.10383295 0.78091580 -1.13997394 H -1.25109519 -0.28384426 -0.84974794 H -3.37275441 3.42197565 -1.14320685 H -1.78384110 3.96729827 -1.62387764 H -2.65467293 2.82667229 -2.62071813 .. tab:: r2.xyz .. code-block:: :caption: r2.xyz :linenos: 18 Product N -0.22474732025333 -0.31730283410046 -0.51491194374209 C 0.54138841877455 -1.42626714378869 0.01659619702235 C 0.37581142979957 0.57244190213102 -1.18506998859001 H 1.59956963538446 -1.37223656022845 -0.26069633867705 H 0.44285772700755 -1.41562576183705 1.10277773062867 H 0.10612456734704 -2.35145036624173 -0.36248430677077 C -0.37357663580959 1.73548805223194 -1.76480799540763 H 1.45524939783346 0.53941227186085 -1.38723095744134 H 0.27481589890769 2.61572199377069 -1.78645396480960 H -0.63716949392230 1.49356209011140 -2.80064855509307 C -1.66735730523003 2.04995476069694 -0.98212699921514 H -1.39146640788106 2.28056626272631 0.06585987026323 C -2.39173812629474 3.24996769168947 -1.58779580073698 O -2.54492763771693 0.95029342074102 -1.01960271506481 H -2.03040745192793 0.17070983855352 -0.71586070424615 H -3.30862690757118 3.43506393231313 -1.02954259805264 H -1.76246901303224 4.13842282177014 -1.54692923821636 H -2.65264077541507 3.04160762759991 -2.62544169185061 .. tabs:: .. tab:: r1.xyz .. figure:: /_images/a21.jpg .. tab:: r2.xyz .. figure:: /_images/a22.jpg Both structures can be constructed by chemical ituition and have been optimized. However, even with these two semmingly reasonable structures, it is not easy to search the transition state. So, we will combine NEB and dimer, semiempirical and DFT methods to search the transition state. **Step 1: NEB Search.** NEB is a method to search the path by connecting the reactant and product geometries. It can be a useful starting point for the dimer method. To rapidly get this, we will use xTB method: .. code-block:: :caption: anion-neb.inp :linenos: mol r1.xyz end mol2 r2.xyz end basis def2-svp end opt type neb num_images 15 neb_k 0.01 end task opt xtb end Let's examine the input file: - The reactant and product geometries are defined by ``mol`` and ``mol2``. - The NEB method is activated by ``opt...end`` with ``type neb``. The default option of ``type`` is ``min`` which is for geometry optimization, so we have to set ``type neb`` explicitly. - ``num_images`` is the number of images in the NEB path, which can be adjusted according to your needs. A good choice is between ``10`` and ``20``. - ``neb_k`` is the spring constant for the NEB path, which can also be adjusted according to your needs. A good choice is between ``0.01``. After running the input file, we can get the following output file: - ``anion-neb-opt.xyz`` The "transition state" structure. But in many cases, we suggest you to visualize it and check whether it is reasonable. - ``anion-neb-opt-traj.xyz`` The NEB trajectory, which can be visualized by `Qbics-MolStar `_: .. figure:: /_images/a23.gif Indeed, this trajectory is our target reaction. We can choose the two closest images on the path that the trasition state may lie between them. In this case, we can choose the 5th and 7th images in ``anion-neb-opt-traj.xyz``, which are saved in ``a5.xyz`` and ``a7.xyz``: .. tabs:: .. tab:: a5.xyz .. code-block:: :caption: a5.xyz :linenos: 18 element x y z N -0.03436 -0.42780 -1.21081 C 0.19877 -1.31325 -0.09641 C 0.54963 0.79676 -1.27792 H 1.21009 -1.16425 0.27978 H -0.51219 -1.13914 0.71792 H 0.09714 -2.34661 -0.43350 C 0.12282 1.79024 -2.06831 H 1.40495 0.93556 -0.62766 H 0.65351 2.72274 -2.12058 H -0.66378 1.63364 -2.78419 C -1.86900 2.10882 -0.51273 H -1.16547 2.64884 0.14563 C -2.61217 2.99713 -1.46905 O -2.13799 0.94532 -0.31815 H -0.98415 -0.45631 -1.55950 H -3.41739 3.47081 -0.90569 H -1.97325 3.77562 -1.87311 H -3.05645 2.41221 -2.27009 .. tab:: a7.xyz .. code-block:: :caption: a7.xyz :linenos: 18 element x y z N -0.04991 -0.40765 -1.08610 C 0.35194 -1.39200 -0.13587 C 0.50298 0.72490 -1.16520 H 1.36153 -1.23389 0.25614 H -0.36195 -1.32388 0.69157 H 0.25447 -2.38320 -0.57375 C -0.26333 1.81516 -1.81912 H 1.42373 0.97712 -0.62468 H 0.32790 2.72274 -1.93602 H -0.65750 1.50523 -2.78663 C -1.50488 2.07052 -0.89479 H -1.14590 2.52877 0.04533 C -2.47962 3.02762 -1.58061 O -2.17108 0.87844 -0.60177 H -1.60693 0.12971 -0.93634 H -3.25074 3.33649 -0.87990 H -1.95994 3.90581 -1.95044 H -2.96008 2.50844 -2.40618 Now we will use the dimer/QST2 algorithm to search the transition state between these two images. Below, we show how to do this on B3LYP/def2-SVP levels of theory: .. code-block:: :caption: anion-dft-qst2.inp :linenos: mol a5.xyz end mol2 a7.xyz end basis def2-svp end scf charge 0 spin2p1 1 end opt type qst2 # You can also use dimer. end task opt b3lyp end Fortunately, we can get the transition state structure, which is saved in ``anion-dft-qst2-opt.xyz`` and is shown below: .. figure:: /_images/a24.jpg Example: dMECP for F\ :sup:`-`\ +CH\ :sub:`3`\ Cl = CH\ :sub:`3`\ F+Cl\ :sup:`-` ----------------------------------------------------------------------------------- For AB+C=A+BC type reactions, we can use the dMECP method to search the transition state. For example, for the reaction F\ :sup:`-`\ +CH\ :sub:`3`\ Cl = CH\ :sub:`3`\ F+Cl\ :sup:`-`, we can use the following input file: .. code-block:: :caption: fch3cl.inp :linenos: basis def2-svp end mol C -0.43654823 1.13197968 0.00000000 H -0.07987539 1.63637787 0.87365150 H -0.07987539 1.63637787 -0.87365150 H -1.50654823 1.13199286 0.00000000 Cl 0.15009830 -0.52737135 0.00000000 F -1.63124586 2.75454539 -0.44024554 end scf type u # This must be set. charge -1 spin2p1 1 end mecp num_steps 200 energy_cov 1.E-5 # Reactant. frag1 0 1 1-5 frag1 -1 1 6 # Product. frag2 0 1 1-4 6 frag2 -1 1 5 end task dmecp b3lyp end We can see that we want to search the transition state at B3LYP/def2-SVP level of theory. The dMECP method is activated by ``dmecp`` in ``task...end``, and is controlled by ``mecp...end`` option. Below are some important points: - dMECP is implemented with the TSO method, so in ``scf...end``, we have to set ``type u``. - ``num_steps`` is the number of steps for the dMECP search, which can be adjusted according to your needs. - The reactant and product connectivity are defined by ``frag1`` and ``frag2``, respectively. Their grammar is similar to ``frag`` in :doc:`../keywords/eda` and :doc:`../keywords/scfguess`, but here we have to define the connectivity of the reactant and product separately by ``frag1`` and ``frag2``. The geometry structure in ``fch3cl.inp`` is shown below: .. figure:: /_images/a16.jpg The ``frag1`` and ``frag2`` definitions are shown below: .. figure:: /_images/a17.jpg Therefore, we just need to **define** the "connectivity" and "charge" of the reactant and product, **no matter what the geometry is.** The dMECP method will automatically optimize the geometry to find the transition state. **dMECP only needs reactant complex struture. This is very convenient for the transition state search.** After running the input file, we can get the following output file: - ``fch3cl-mecp.xyz`` The final transition state. - ``fch3cl-mecp-traj.xyz``. The dMECP trajectory. Both files can be visualized by `Qbics-MolStar `_: .. figure:: /_images/a18.jpg .. figure:: /_images/a19.gif In ``fch3cl.out``, we can find following content: .. code-block:: :caption: fch3cl.out :linenos: Adiabatic state energy: -599.69936976 Hartree Diabatic state 1 energy: -599.62911003 Hartree Diabatic state 2 energy: -599.62485338 Hartree |E(2)-E(1)|: 0.00425665 Hartree delta|E(2)-E(1)|: 0.00000520 Hartree RMS gradient: 0.00008376 Hartree/Bohr RMS displacement: 0.00098426 Angstrom Here, ``Adiabatic state energy`` is the energy of standard DFT. ``Diabatic state 1 energy`` and ``Diabatic state 2 energy`` is the **diabatic** energy of ``frag1`` and ``frag2``. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these keywords: - :doc:`../keywords/eda` Energy Decomposition Analysis ========================================= .. contents:: :local: This tutorial will lead you step by step to do energy decomposition analysis (EDA) using Qbics. Currently, EDA can only be used with DFT. .. hint:: If you use Qbics to do EDA in you paper, please cite the following references: - `J. Chem. Theory Comput. 2023, 19, 1777 `_ - `Phys. Chem. Chem. Phys. 2024, 26, 17549 `_ Example: EDA for (H\ :sub:`2`\ SO\ :sub:`4`)(NH\ :sub:`3`) ------------------------------------------------------------- Here, we will do an EDA for the molecular dimer (H\ :sub:`2`\SO\ :sub:`4`)(NH\ :sub:`3`). The input is given below: .. code-block:: :caption: 1s1n.inp :linenos: basis def2-svp end scf charge 0 spin2p1 1 type U # This is needed for EDA. end grimmedisp type bj # Options: none, zero, bj. end eda type tso frag 0 1 1-7 frag 0 1 8-11 end mol S -0.62161000 -0.11181000 0.09167200 O 0.03138700 -0.14316200 1.35576500 O -1.82120800 -0.82692400 -0.15912300 O 0.38678100 -0.46814500 -1.02324300 O -0.91128600 1.43385100 -0.17168300 H 1.34667100 -0.25497400 -0.71202200 H -1.58729700 1.50230600 -0.85583700 N 2.78190500 0.03915200 -0.05091700 H 3.20716100 0.92239700 -0.30232700 H 3.46881800 -0.69082400 -0.19060100 H 2.55167500 0.07103700 0.93671700 end task eda b3lyp end - Line 8: For EDA, you must explicitly set the ``type`` to ``U`` in ``scf...end``. - Line 16: Do TSO-type EDA. You can also use ``gks`` to do generalized Kohn-Sham (GKS) type EDA. - Line 17-18: The fragments in EDA. Each line defines the charge, spin multiplicity, and atom indices. See below: .. figure:: /_images/a25.jpg After running this calculation, we have the following output: .. code-block:: :caption: 1s1n.out :linenos: WITHOUT BSSE correction: Electrostatic interaction energy: -30.95 kcal/mol Exchange-correlation interaction energy: 27.55 kcal/mol Polarization interaction energy: -5.44 kcal/mol Charge transfer interaction energy: -15.25 kcal/mol Grimme's dispersion interaction: -2.22 kcal/mol ---------------------------------------------------------------- Total interaction energy: -26.31 kcal/mol WITH BSSE correction: Electrostatic interaction energy: -30.95 kcal/mol Exchange-correlation interaction energy: 27.55 kcal/mol Polarization interaction energy: -5.44 kcal/mol Charge transfer interaction energy: -10.44 kcal/mol Grimme's dispersion interaction: -2.22 kcal/mol ---------------------------------------------------------------- Total interaction energy: -21.50 kcal/mol In this output, the interaction energy of the following process H\ :sub:`2`\ SO\ :sub:`4` + NH\ :sub:`3` = (H\ :sub:`2`\ SO\ :sub:`4`)(NH\ :sub:`3`) is decomposed into several components. The interaction energy WITH and WITHOUT BSSE is ``-21.50 kcal/mol`` and ``-26.31 kcal/mol``. The BSSE energy is included in ``Charge transfer interaction energy``. The ``Electrostatic interaction energy``, ``Polarization interaction energy`` and ``Charge transfer interaction energy`` are all stablizing the dimer, the first contributing most. The ``Exchange-correlation interaction energy`` can also be recognized as Pauli exclusion energy, which destablizing the dimer. For different kinds of molecular dimer, the weights of different components are quiet different, indicating the nature of chemical interactions. Example: EDA for (Ca\ :sup:`2+`)(SO\ :sub:`4`\ :sup:`2-`)(H\ :sub:`2`\ O)\ :sub:`5` ---------------------------------------------------------------------------------------- The basic MB-EDA formular is: .. math:: \Delta E^{\text{int}} = \frac{1}{2!} \sum_{I_1 \neq I_2}^{N} \Delta E_{I_1 I_2}^{(2)} +\frac{1}{3!} \sum_{I_1 \neq I_2 \neq I_3}^{N} \Delta E_{I_1 I_2 I_3}^{(3)} + \cdots + \frac{1}{n!} \sum_{I_1 \neq \cdots \neq I_n}^{N} \Delta E_{I_1 \cdots I_n}^{(n)} + \cdots + \Delta E_{I_1 \cdots I_N}^{(N)} \equiv \sum_{n=2}^{N} \Delta E^{(n)} The terms higher than :math:`\Delta E^{(2)}` is the many-body interaction term. Usually the most important one is the three-body effect :math:`\Delta E^{(3)}`, the effects of which can be decomposed into three ones: - :math:`\Delta E^{(3)} < 0`: Indicate a **cooperative effect** of the monomers in a cluster. The many-body interaction is stabilizing the cluster. This is often seen in hydrogen bonding clusters, like water clusters. - :math:`\Delta E^{(3)} > 0`: Indicate an **anti-cooperative effect** of the monomers in a cluster. The many-body interaction is destabilizing the cluster. This is often seen in a cluster of charged species, like ionic liquid clusters. Also see below. - :math:`\Delta E^{(3)} \approx 0`: Indicate a **non-cooperative effect** of the monomers in a cluster. There is little many-body interaction in the cluster. This is often seen in a cluster of molecules without charges or hydrogen bonds. Each order can be decomposed into electrostatic, exchange, polarization, charge transfer, and dispersion terms: .. math:: \Delta E_X^{(n)} = \Delta E_X^{(n)\text{-el}} + \Delta E_X^{(n)\text{-ex/xc}} + \Delta E_X^{(n)\text{-pl}} + \Delta E_X^{(n)\text{-ct}} + \Delta E_X^{(n)\text{-disp}} Usually, electrostatic and exchange terms are highly additive, while polarization and charge transfer terms are non-additive. The dispersion term is always additive. Here we will do an EDA for the microsolvated cluster (Ca\ :sup:`2+`)(SO\ :sub:`4`\ :sup:`2-`)(H\ :sub:`2`\ O)\ :sub:`5`. Since there are more than 2 species, we will use many-body EDA (MB-EDA) to decompose the interaction energy components into contributions from different many-body level. Usually, contributions beyond three-body are very small, so we will truncate the computation at four-body. The input is given below: .. code-block:: :caption: caso4h2o5.inp :linenos: basis def2-svp end scf charge 0 spin2p1 1 type U # This is needed for EDA. end grimmedisp type bj end eda type mb_tso mb_level 4 # The many-body truncation level. frag +2 1 1 frag -2 1 2-6 frag 0 1 7-9 frag 0 1 10-12 frag 0 1 13-15 frag 0 1 16-18 frag 0 1 19-21 end mol Ca 1.98604937 1.24582501 1.89905383 S 0.69103489 3.45226578 0.98237460 O 2.08708072 3.44779165 1.50308184 O 0.24826049 2.05102931 0.73622996 O -0.21032250 4.08940001 1.98323165 O 0.63912085 4.22084216 -0.29304506 O 3.02175028 0.83377391 -0.05175855 H 3.13194669 0.09601115 -0.65158745 H 2.90415260 1.59241194 -0.62348488 O 2.51307423 2.92493798 -1.72944079 H 1.80535522 3.44397361 -1.34738364 H 2.91500306 3.50585612 -2.37536585 O 0.60914213 -0.51387571 1.58896733 H 0.07645358 -1.26917200 1.83796991 H 0.01571971 0.04244367 1.08439778 O 0.73702072 1.93958625 3.70546127 H 0.73393089 2.03509947 4.65787899 H 0.20818330 2.67203308 3.38909995 O 3.87639195 1.93942131 2.91131853 H 4.78820918 1.95286631 3.20224881 H 3.69756418 2.83995160 2.64058309 end task eda b3lyp end - Line 16: To do MB-EDA, you should use ``mb_tso``. - Line 17: ``mb_level 4`` means you truncate the MB-EDA at four-body. - Line 18-24: Set 7 chemical fragements. Note that some species like Ca\ :sup:`2+` and SO\ :sub:`4`\ :sup:`2-` are charged. You should give the correct charge. The atomic indices are shown below: .. figure:: /_images/a26.jpg After running this calculation, we have the following output: .. code-block:: :caption: caso4h2o5.out :linenos: Table 5. Summary (kcal/mol). --------------------------------------------------------------------------------------------------------------------------------- Interactions delE_el delE_xc delE_pl delE_ct delE_bsse delE_disp delE_tot --------------------------------------------------------------------------------------------------------------------------------- SUM of 2-body -6.73148230E+02 1.47696370E+02 -1.11395126E+02 -2.04547116E+02 1.03684957E+02 -2.06082308E+01 -7.58317375E+02 SUM of 3-body 1.42501290E-08 -2.67700179E+00 6.09855572E+01 1.30716087E+02 -4.86421459E+01 1.07484123E+01 1.51130908E+02 SUM of 4-body -2.82504918E-08 5.22296932E-01 -4.66678754E+00 -4.78862109E+01 1.47634652E+01 -1.52639538E+01 -5.25311901E+01 Remain 1.63009297E-08 -9.27025377E-02 2.21610464E-01 1.02616142E+01 -2.89029982E+00 7.47122033E+00 1.49714426E+01 --------------------------------------------------------------------------------------------------------------------------------- SUM -6.73148230E+02 1.45448963E+02 -5.48547462E+01 -1.11455626E+02 6.69159769E+01 -1.76525519E+01 -6.44746214E+02 --------------------------------------------------------------------------------------------------------------------------------- We can see that the total interaction energy is -644.75 kcal/mol, which is decomposed into 2-body, 3-body, 4-body, and remaining terms. The 2-body term is the most important one (-758.32 kcal/mol), while the 3-body term is also significant but **anti-cooperative** (destablizing the cluster) (+151.13 kcal/mol). The 4-body term is small (-52.53 kcal/mol, slightly cooperative). The remaining term (sum of 5-, 6-, and 7-body) is very small (+14.97 kcal/mol) compared to the low-order terms. We can also see that the electrostatic and exchange energy are highly **additive** (beyond 3-body is almost zero), while the polarization and charge-transfer energy are **non-additive**: .. list-table:: :stub-columns: 1 * - Type - 2-body - 3-body - 4-body - Total * - Polarization - -111.40 kcal/mol - +60.99 kcal/mol - -4.67 kcal/mol - -54.85 kcal/mol * - Charge transfer - -204.55 kcal/mol - +130.72 kcal/mol - -47.89 kcal/mol - -111.45 kcal/mol For different kinds of clusters, the 3-body effects (many-body interactions) can be quite different, see `Phys. Chem. Chem. Phys. 2024, 26, 17549 `_ for more information. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these keywords: - :doc:`../keywords/md` Standard Molecular Dynamics Simulations ========================================= .. contents:: :local: This tutorial will lead you step by step to do standard molecular dynamics (MD) simulations using Qbics. Assume you have read :doc:`opt`, :doc:`dft` or :doc:`charmm`. In this tutorial, we will only discuss the standard MD simulations, meaning no enhanced sampling algorithms are used. For enhanced sampling MD, please refer to :doc:`enhanced_md`. Example: NVT MD for Solvated Protein 5VBM -------------------------------------------- Here, we will do a NVT MD simulation for the solvated protein 5VBM given in :doc:`charmm`. The input file is as follows: .. code-block:: :caption: 5vbm-sol.inp :linenos: charmm # Here: # toppar_water_ions.str: the parameter file for water and ions. # par_all36m_prot.prm: the parameter file for proteins. # Both are obtained from website: https://mackerell.umaryland.edu/charmm_ff.shtml. parameters toppar_water_ions.str par_all36m_prot.prm topology 5vbm-sol.psf scaling14 1.0 rcutoff 12.0 rswitch 10.0 use_PBC # Add this line to turn on PBC. Lbox 70 70 70 # Define the box size. electrostatic pme # Use PME for electrostatics. PMEk 72 72 72 end md type nvt dt 0.001 # 0.001 ps = 1 fs num_steps 10000 # 10000*0.001 = 10 ps temp 300 temp_nhc_length 5 temp_nhc_tau 0.5 output_freq 100 # 0.001*100 = 100 fs end mol 5vbm-sol-opt.xyz end task opt charmm end Note that, in ``mol...end``, we use the optimized structure ``5vbm-sol-opt.xyz`` from :doc:`opt`. For biological systems, always use **optimized** structure as initial structure for MD simulations! Now, we will explain the options in ``md...end``: - Line 18: The type of MD. Here we do canonical ensemble MD, which is ``nvt``, i.e. constant number of molecules, volume, and temperature. - Line 19: The time step size of MD in ps. Usually ``0.001`` is a good choice. However, if there is no hydrogen atom, then ``0.002`` or larger can be used. - Line 20: The number of steps to do MD. Here we do ``10000`` steps, so the total simulation time is 10000*0.001 = 10 ps. This short time is for pedagogical purpose. In practice, one should do a much longer simulation for product analysis. - Line 21: The target temperature in Kelvin. - Line 22,23: The parameters for Nose-Hoover chain algorithm to control temperature. The parameters given here are usually OK. - Line 24: The frequency of output. Here, for every ``100`` steps, the coordinates, gradients, velocities, and energies are output. After running this calculation, we have the following output: - ``5vbm-sol-md-traj.xyz``: The trajectory. - ``5vbm-sol-md-vel.xyz``: The velocities of all atoms for every ``output_freq`` steps. - ``5vbm-sol-md-grad.xyz``: The gradients of all atoms for every ``output_freq`` steps. - ``5vbm-sol-md-log.txt``: The energies for every ``output_freq`` steps. For example: .. code-block:: :caption: 5vbm-sol-md-log.txt :linenos: # Time Total Kinetic Potential Temp ConstQ Bond Angle Dihedral Improper Coulombic LennardJones Cost ps kcal/mol kcal/mol kcal/mol Kelvin kcal/mol kcal/mol kcal/mol kcal/mol kcal/mol kcal/mol kcal/mol second 0 0.00000 -134230.56945744 36085.33154757 -170315.90100501 300.00000000 -134230.56945744 6420.14428661 4495.95531110 1531.31406870 20.78944740 -209097.89905045 26313.79486581 0.129 100 0.10000 -133816.54187207 16118.34524766 -149934.88711973 134.00191621 -134016.76556412 7302.41369899 5869.59861893 1666.48807052 75.45725238 -188865.46777364 24016.62295515 6.522 200 0.20000 -133606.24161267 16992.08207064 -150598.32368331 141.26583857 -134065.52297681 6679.22007384 5375.41406643 1657.28109955 67.37158807 -186898.20683159 22520.59626219 6.730 300 0.30000 -133300.87796459 17301.76543332 -150602.64339791 143.84043065 -134046.30803993 6874.09339659 5371.10977271 1657.72694720 75.62709833 -187077.51167460 22496.31100366 7.048 400 0.40000 -132995.61549652 17629.55917628 -150625.17467280 146.56558568 -134041.03818552 6903.10388790 5646.97799910 1681.10341086 ..omitted.. 9400 9.40000 -100271.14965665 32668.17051219 -132939.32016884 271.59099649 -133856.91550183 10568.00534340 8576.31788333 1692.95053586 88.36593747 -172749.73171403 18884.77179376 7.265 9500 9.50000 -99959.15928496 32686.86479432 -132646.02407928 271.74641379 -133845.66058042 10659.61992276 8745.77752012 1703.07775588 96.01140798 -172661.31654362 18810.80580633 7.206 9600 9.60000 -99667.33935998 33043.56346211 -132710.90282209 274.71187359 -133850.81824348 10583.87601581 8824.62198457 1700.19011253 89.59345122 -173007.46226334 19098.27782584 7.214 9700 9.70000 -99370.72733288 32989.96543886 -132360.69277175 274.26627960 -133846.10700977 10640.12182526 8661.17837744 1693.77491115 96.10476851 -172243.89238876 18792.01968350 7.288 9800 9.80000 -99083.18310690 33120.13583885 -132203.31894575 275.34846780 -133847.97704020 10723.48783126 8787.10704944 1698.42095679 98.19639577 -172644.29859784 19133.76736774 7.495 9900 9.90000 -98790.21971731 33390.37977009 -132180.59948741 277.59517514 -133840.46539948 10862.67638260 8744.32303648 1685.93747509 97.87623972 -172406.04428515 18834.63161277 7.240 10000 10.00000 -98511.94567150 33524.11389736 -132036.05956887 278.70699084 -133842.52309227 10850.32141702 8657.09756469 1697.76177767 90.53706975 -172324.05730779 18992.27985877 7.197 We can see that the time, total energy, kinetic energy, potential energy, temperature and other components are output. Here, ``ConstQ`` is a **conserved quantity** for NVT simulation. If it strongly fluctuates during simulaiton, the MD calculation may be problematic. Also, the NVT MD is tried to keep the temperature constant at ``300`` K, so the temperature should not fluctuate too much. At the beginning, the temperature is around ``134`` K, which is not good. This means that the system has **NOT been equillibrated yet.** After 9 ps, the temperature is stabilized around ``300`` K. In practice, one should do a longer MD simulation to ensure the system is equilibrated, and then do production MD simulation. We can visualize the trajectory ``5vbm-sol-md-traj.xyz`` in `Qbics-MolStar `_. In Qbics, we can load topology ``5vbm-sol.psf`` into :guilabel:`Model` and trajectory ``5vbm-sol-md-traj.xyz`` into :guilabel:`Coordinates`, then click :guilabel:`Apply` to load the trajectory. Now click the icon in the left-up corner, and click :guilabel:`Start`. Now you can visualize the trajectory. .. figure:: /_images/a9.png .. figure:: /_images/a10.gif Now you can do various analyses on energies, trajectories, gradients, and velocities. For example, calculating diffusion coefficient, conformation change, etc. Example: NVE MD for Bullvalene -------------------------------------------- The MD using CHARMM force is sometimes called classic MD (CMD). Thus, the MD using quantum chemical force (like DFT, xTB) is called ab initio MD (AIMD). We can use AIMD to study dynamic effects in chemical reactions. Below, we will do a NVE MD simulation for bullvalene. We use NVE since in this case, the system does not exchange energy with environment, thus it is an isolated system, the energy will relax within its internal degrees of freedom. We use the following input: .. code-block:: :caption: bullvalene-xtb.inp :linenos: xtb gbsa CHCl3 end md type nve dt 0.001 # 0.001 ps = 1 fs num_steps 100000 # 10000*0.001 = 10 ps temp 500 output_freq 10 # 0.01*100 = 0.01 ps end mol C -0.62880 1.05561 1.34009 H -0.83035 1.51659 2.30210 C 0.13239 1.54079 0.47336 H 0.64136 2.33325 0.99298 C -0.88383 -0.82066 1.33606 H -1.37100 -1.05330 2.29317 C 0.79049 -0.51831 1.33499 H 1.19125 -0.81191 2.27882 C 0.49419 1.22452 -0.75522 H 1.22559 1.79534 -1.30152 C -1.52626 -0.95189 0.16256 H -2.43289 -1.51994 0.39341 C 1.56332 -0.93823 0.11905 H 2.41452 -1.49844 0.38314 C -0.08122 0.08636 -1.54946 H -0.10037 0.16642 -2.63781 C -1.23434 -0.67040 -1.08946 H -1.91475 -1.01441 -1.86813 C 1.16111 -0.58641 -1.09467 H 1.84928 -0.87572 -1.88796 end task md xtb end Here, we use ``xtb`` (with implicit solvent ``gbsa CHCl3``) since it is much faster than DFT. Of course, you can change ``xtb`` to ``b3lyp`` to do a DFT AIMD. From ``md...end``, we can see that we do an NVE MD for 10 ps, with a step size of 1 fs and initial temperature of 500 K. The initial structure is a transition state. Such AIMD is sometimes called **downhill dynamics.** If we start the AIMD with a structure minimum (reactant), this is called **uphill dynamics.** After this downhill dynamic simulaiton, we can use `Qbics-MolStar `_ to visualize the trajectory: .. figure:: /_images/a11.gif There are several isomerization reactions occurred. For example, during 2.00 - 3.37 ps: .. figure:: /_images/a12.gif which corresponds to a Cope rearrangement: .. figure:: /_images/a13.png With this trajectory, you can study the reaction path or rate. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these keywords: - :doc:`../keywords/md` - `Plumed documentation `_ Metadynamics for Calculating Free Energy Surface ================================================================= .. contents:: :local: This tutorial will lead you step by step to do molecular dynamics (MD) simulations with enhanced sampling using Qbics. We recommend you read :doc:`md` first. Enhanced samping is a method to sample rare events in MD simulations, mostly the overcome of high barrier, including difficult conformational change and chemical reactions. This is not a black-box method and you need some experience to select collective variables (CVs) and sampling methods. In Qbics, enhanced sampling is implemented with `Plumed `_. All CVs and sampling methods in Plumed can be used. They can be combined with (TSO-)DFT, xTB, NDDO, CHARMM, and QM/MM in Qbics. In this tutorial, we will focus on metadynamics, although other methods like OPES can also be used. Example: Conformation Change of Dialaline -------------------------------------------------------------------------- Here, we want to calculate the free energy surface (FES) of 2 dihedral angles (``phi`` and ``psi``) for dialaline with CHARMM force field, see below: .. image:: /_images/a33.png We will use metadynamics, which will add a bias potential to the place it has visited: .. math:: V(\mathbf{s},t) = \sum_{ k \tau < t} W(k \tau) \exp\left( -\sum_{i=1}^{d} \frac{(\mathbf{s}_i-\mathbf{s}_i^{(0)}(k \tau))^2}{2\sigma_i^2} \right) Here, :math:`\mathbf{s}` is the collective variables, :math:`t` is the time, :math:`\tau` is the time step, :math:`W(k \tau)` is the height of the bias potential, :math:`\sigma_i` is the width of the bias potential, :math:`k` is the frequency of adding bias potential. The input file for Qbics is almost same as standard MD simulations: .. code-block:: :caption: diala.inp :linenos: charmm parameters par_all22_prot.prm # Parameter files. There can be several ones. topology diala.psf # Topology file. scaling14 1.0 # Scaling factor of 1-4 interactions. rcutoff 12.0 # The cutoff radius for nonbonded interactions. rswitch 10.0 end mol diala.pdb end md type NVT # Type: NVE, NVT dt 0.001 # The time step in ps. temp 300. # The temperature in Kelvin. temp_nhc_length 5 # The length of temperature Nose-Hoover chain. temp_nhc_tau 0.2 # The time constant of temperature Nose-Hoover chain in ps. num_steps 10000000 # The number of steps: 10 ns output_freq 100000 # The output frequency: 0.1 ns plumed_fn plumed.dat # Plumed settings file. end task md charmm end The only difference is the addition of ``plumed_fn`` in ``md...end``, which is the file that contains the settings for Plumed. With ``plumed_fn`` added, enhanced sampling will be automatically activated; if you delete this line, an ordinary MD simulation will be performed. We can see that a 100 ns NVT MD will be carried out with enhanced sampling set in ``plumed.dat``: .. code-block:: :caption: plumed.dat :linenos: # Compute the backbone dihedral angle phi, defined by atoms C-N-CA-C phi: TORSION ATOMS=5,7,9,15 psi: TORSION ATOMS=7,9,15,17 metad: METAD ... ARG=phi,psi SIGMA=0.20,0.20 HEIGHT=0.0836799999612436 #BIASFACTOR=5 #TEMP=300.0 PACE=100 FILE=HILLS GRID_MIN=-pi,-pi GRID_MAX=pi,pi #GRID_BIN=150,150 ... # Print both collective variables on COLVAR file every 10 steps PRINT ARG=phi,psi FILE=COLVAR STRIDE=10 More details about Plumed can refer to `Plumed documentation `_. Here, we give some explainations: - Line 1: A comment. - Line 2: Defines a CV named ``phi``. The ``TORSION`` keyword specifies that this CV is a dihedral angle (the angle between two planes formed by four atoms). ``ATOMS=5,7,9,15`` lists the indices (5, 7, 9, 15) of the four atoms in the simulation system that form the phi dihedral angle. See the figure below. - Line 3: Similar to Line 2. - Line 5: ``metad: METAD ...`` Starts the definition of a metadynamics simulation block named ``metad`` (the ``METAD`` keyword initializes metadynamics). The ``...`` is a line continuation marker, indicating the configuration for this metadynamics block continues on the next lines. - Line 6: Specifies the CVs to be used in metadynamics. Here, ``ARG=phi,psi`` means the metadynamics simulation will bias the system based on the two dihedral angles ``phi`` and ``psi``. This is :math:`\mathbf{s} = (\phi, \psi)` in the equation above. - Line 7: Sets the width (Gaussian width) of the bias potentials added in metadynamics. The two values ``0.20,0.20`` correspond to the :math:`\sigma_i` for ``phi`` and ``psi`` respectively (units are typically radians for angles), controlling how "spread out" each added Gaussian bias is. - Line 8: Defines the height of each Gaussian bias potential added during metadynamics. The value ``0.0836799999612436`` (units are typically in energy units like kilojoules per mole, kJ/mol) determines how strong each individual bias contribution is. This is :math:`W(k \tau)` in the equation above. - Line 9: Set the ``BIASFACTOR`` (a parameter sometimes used to scale the bias potential) to 5. It is currently commented out. - Line 10: Specify the simulation temperature (``TEMP``) as ``300.0`` Kelvin (K) for metadynamics calculations if uncommented. It is currently commented out. - Line 11: Sets the frequency at which Gaussian bias potentials are added, which is :math:`k` in the equation above. ``PACE=100`` means a new Gaussian bias is added every 100 MD steps. In our case, 100*0.001 = 0.1 ps. - Line 12: Specifies the output file where information about the added Gaussian biases (called "hills" in metadynamics) is stored. The file named ``HILLS`` will record details like the position, height, and width of each added hill for later analysis. - Line 13: Defines the minimum bounds of the grid used for analyzing or visualizing the metadynamics FES. The values ``-pi,-pi`` (in radians) set the lower limit for the ``phi`` and ``psi`` CVs respectively (equivalent to -180 degrees). - Line 14: Similar to Line 13, but defines the maximum bounds of the FES grid. - Line 15: Set the number of grid bins (resolution) for the FES. ``GRID_BIN=150,150`` would divide the ``phi`` and ``psi`` ranges into 150 bins each (resulting in a 150x150 grid). It is currently commented out. - Line 16: Ends the line continuation for the ``metad`` metadynamics block, closing the configuration for this section. - Line 19: Defines an output section using the ``PRINT`` keyword. ``ARG=phi,psi`` specifies the CVs to print (``phi`` and ``psi``), ``FILE=COLVAR`` sets the output file name to ``COLVAR``, and ``STRIDE=10`` means the CV values are written to ``COLVAR`` every 10 MD steps. .. attention:: In Plumed, the default units for length, degree, and energy is nm, radian, and kJ/mol, not Angstrom, degree, and kcal/mol used in Qbics. With this input files, we can run a 100-ns metadynamics simulation for dialaline. After the simulation, a file named ``HILLS`` will be generated. It saves all :math:`V(\mathbf{s},t)` during simulation, with which we can generate free energy data (FES) using the following command: .. code-block:: bash plumed sum_hills --hills HILLS The executable of Plumed can be found in ``plumed/bin`` in the distribution of Qbics. This will generate the file `fes.dat`. With the following Python script, we can plot the FES :math:`F(\phi, \psi)`: .. code-block:: python :caption: plot_fes.py :linenos: import numpy as np import matplotlib.pyplot as plt from matplotlib import cm def plot_contour_from_file(filename): # Read file. data = np.loadtxt(filename) x = data[:, 0] y = data[:, 1] z = data[:, 2] x_unique = np.unique(x) y_unique = np.unique(y) # Create grids. X, Y = np.meshgrid(x_unique, y_unique) Z = np.zeros_like(X) for i, xi in enumerate(x_unique): for j, yi in enumerate(y_unique): mask = (x == xi) & (y == yi) if np.any(mask): Z[j, i] = z[mask][0] X *= 180/3.1415926 # To degree Y *= 180/3.1415926 # To degree Z *= 0.23900574 # To kcal/mol # Plot. plt.figure(figsize=(10, 8)) contourf = plt.contourf(X, Y, Z, levels=25, cmap='jet') contour = plt.contour(X, Y, Z, levels=25, colors='black', linewidths=1) # Style. cbar = plt.colorbar(contourf) cbar.set_label('$F(\phi, \psi)$ (kcal/mol)', fontsize=12) plt.xlabel('$\phi$ (degree)', fontsize=12) plt.ylabel('$\psi$ (degree)', fontsize=12) plt.title('Free Energy Surface $F(\phi, \psi)$', fontsize=14) plt.tight_layout() # Show. plt.show() if __name__ == "__main__": plot_contour_from_file('fes.dat') .. image:: figs/a34.png You can find several free energy minima and maxima on the FES. Example: Proton Transfer of Malonaldehyde ------------------------------------------------------------------------------- Here we consider the following proton transfer reaction of malonaldehyde: .. image:: /_images/a35.png In you just do a standard MD, you may never see a protron transfering to another oxygen atom. To sample this rare event, we will use metadynamics. The intial structure is shown below. A nature set of CVs to describe the proton transfer is the 2 OH distances, but in this case, we want to plot a one-dimensional FES, so we will use the difference between the 2 distances :math:`d\equiv d_1-d_2`: .. image:: /_images/a36.png The input file is: .. code-block:: :caption: malonaldehyde.inp :linenos: mol H 2.60849612 -0.72353966 0.29921536 O 1.96497994 -0.12074426 -0.17095304 C 2.66761718 0.78172105 -0.81146959 C 4.02335932 0.83968127 -0.80715851 C 4.77421680 -0.12520070 -0.05714631 O 4.27344987 -1.03185159 0.59780685 H 2.06272652 1.49828618 -1.35825644 H 4.54176858 1.60740187 -1.35230520 H 5.86993567 -0.01026417 -0.09028312 end md type NVT # Type: NVE, NVT dt 0.001 # The time step in ps. temp 300. # The temperature in Kelvin. temp_nhc_length 5 # The length of temperature Nose-Hoover chain. temp_nhc_tau 0.2 # The time constant of temperature Nose-Hoover chain in ps. num_steps 1000000 # The number of steps: 1 ns output_freq 1000 # The output frequency: 1 ps plumed_fn plumed.dat end task md xtb end So, this will be a 10-ns NVT metadynamics using xTB, since only quantum chemistry can describe chemical reactions. xTB is fast, but less accurate than DFT. The Plumed setting is shown below: .. code-block:: :caption: plumed.dat :linenos: # Compute the OH distances d1: DISTANCE ATOMS=1,2 d2: DISTANCE ATOMS=1,6 d21: COMBINE ARG=d1,d2 COEFFICIENTS=1,-1 PERIODIC=NO metad: METAD ... ARG=d21 SIGMA=0.05 HEIGHT=0.1 PACE=100 FILE=HILLS GRID_MIN=-0.5 GRID_MAX=+0.5 ... # Print both collective variables on COLVAR file every 10 steps PRINT ARG=d1,d2,d21 FILE=COLVAR STRIDE=10 Most settings have already been explained in the last exmaple. Just a few points: - Line 2: Define the CV as distance between atom 1 and 2 named ``d1`` using the keyword ``DISTANCE``. - Line 3: Similar to Line 2, but define the CV as distance between atom 1 and 6 named ``d2``. - Line 4: ``COMBINE`` is used to combine the two CVs, whose operation is ``d1`` times ``1`` + ``d2`` times ``-1``. Others should be self-explanatory. Now you can run the calculation. Before calculating the FES, we can visualize the trajectory using ``malonaldehyde-md-traj.xyz`` in `Qbics-MolStar `_: .. figure:: /_images/a37.gif We can see several proton transfer events between the 2 oxygen atoms. Without bias potentials from metadynamics, this is very difficult to happen. Now, calculate the FES using the following command: .. code-block:: bash plumed sum_hills --hills HILLS This will generate the file `fes.dat`. With the following Python script, we can plot the FES :math:`F(d)`: .. code-block:: python :caption: plot_fes.py :linenos: Below is the FES plot: .. figure:: /_images/a38.png Although there are many local minima, we focus on the transfer region, which is [-1,1] Angstrom: .. figure:: /_images/a39.png We show some representative structures in the picuture. Fiinally, there are 3 points: - The FES should be symmetric, but it is not. This is because the calculation is not completely converged. - The xTB FES is not accurate. One should use DFT to get a more accurate FES in production research. - One can add some restraints in ``plumed.dat`` to let :math:`d` stay in [-1,1] during the metadynamics, but this needs an unbiasing/reweighting process to modify the FES, which is not discussed in this tutorial and can reter to `Plumed documentation `_. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these keywords: - :doc:`./msdft1` - :doc:`./msdft2` - :doc:`../keywords/scf` - :doc:`../keywords/scfguess` TSO-DFT (1): Excited States ============================================================== .. contents:: :local: This tutorial will lead you step by step to do target state optimization DFT (TSO-DFT) using Qbics. TSO-DFT is an originally developed method in Qbics. It is a powerful and accurate method for **excited** and **diabatic** states. In many physical processes like charge transfer, **TSO-DFT** can give **much more reasonable** results than TDDFT. Therefore, it is worth learning this method. .. hint:: If you use Qbics to do TSO-DFT in you paper, please cite the following references: - `J. Chem. Theory Comput. 2023, 19, 1777 `_ In this tutorial, we will introduce how to use TSO-DFT to study **exicted states.** Example: HCHO n→π* Excitation Energy -------------------------------------------- In the first example of TSO-DFT, we will show how to calculate the n→π* excitation energy of HCHO at B3LYP/cc-pVTZ level of theory. .. hint:: Accurate calculations of excited states need basis sets of high quality. We recommend cc-pVTZ or beyond for energy evaluation and cc-pVDZ or beyond for geometry optimization. Ground State ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Before studying excited states, it is always beneficial to look at the ground state first. The input for ground state is: .. code-block:: bash :linenos: :caption: hcho-gs.inp basis cc-pvtz end scf charge 0 spin2p1 1 type R end mol O -0.68710791 0.04339108 0.00000000 C 0.50595906 -0.07524732 0.00000008 H 1.09294418 -0.13258299 -0.93605972 H 1.09294415 -0.13258317 0.93605964 end task energy b3lyp end This is a standard SCF calculation. After calculation, we will obtain the output file ``hcho-gs.out`` and wavefunction file ``hcho-gs.mwfn``. In ``hcho-gs.out``, we can find these: .. code-block:: bash :linenos: :caption: hcho-gs.out SCF Structure: # of electrons: 16 # of alpha electrons: 8 # of beta electrons: 8 2S+1: 1 Spin alignment: Restricted Temperature: 0.00000000 Kelvin # of basis functions: 88 Thus, this system contains 16 electrons and 88 orbitals. We will calculate the excited states based on this information. Excited State ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The n→π* excited state is a state that an electron is excited from orbital 8 to 9. To calculate this state, one can use one of these 2 input files: .. tabs:: .. tab:: hcho-ee-1.inp .. code-block:: bash :linenos: :caption: hcho-ee-1.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type mwfn file hcho-gs.mwfn orb 16 1 1-87 : 1-7 9-88 orb 0 1 88 : 8 end mol O -0.68710791 0.04339108 0.00000000 C 0.50595906 -0.07524732 0.00000008 H 1.09294418 -0.13258299 -0.93605972 H 1.09294415 -0.13258317 0.93605964 end task energy b3lyp end .. tab:: hcho-ee-2.inp .. code-block:: bash :linenos: :caption: hcho-ee-2.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type tso frag 0 1 1-4 orb 16 1 1-87 : 1-7 9-88 orb 0 1 88 : 8 end mol O -0.68710791 0.04339108 0.00000000 C 0.50595906 -0.07524732 0.00000008 H 1.09294418 -0.13258299 -0.93605972 H 1.09294415 -0.13258317 0.93605964 end task energy b3lyp end First, we claim that ``hcho-ee-1.inp`` and ``hcho-ee-2.inp`` have the same task: calculating n→π* excited state. They differ at ``type`` in ``scfguess...end``: - In ``hcho-ee-1.inp``, ``type mwfn`` means that the reference state is given by a MWFN file, whose name is ``file hcho-gs.mwfn``, that is, the ground state calculated above. - In ``hcho-ee-2.inp``, ``type tso`` means that the reference state is calculated automatically by Qbics. The calculated reference state will be saved to ``hcho-ee-2-ref.mwfn``. The reference state is given by the following ``frag 0 1 1-4``. This ``frag`` is to assign the whole molecule (atom ``1-4``) with charge ``0`` and spin multiplicity ``1`` as reference. See :doc:`../keywords/scfguess` for more information. In both ``hcho-ee-1.inp`` and ``hcho-ee-2.inp``, the excited state is assigned by ``orb``. In TSO-DFT, the most important concept is the **partition of orbital subspace**, see below: .. figure:: /_images/a27.jpg As shown by this picture, in the ground state, the alpha and beta orbitals are occupied by 8 electrons, respectively. In the n→π* excited state, i.e., the state that an electron is excited from orbital 8 to 9, we partition orbitals into 2 subspaces (2 ``orb``): - ``orb 16 1 1-87 : 1-7 9-88`` The first subspace contains ``16`` electrons and spin multiplicity is ``1``. The numbers separated by ``:`` are the alpha orbital indices ``1-87`` and beta orbital indices ``1-7 9-88``, respecitively. Here, we remove beta orbital 8, so when the electrons are occupied, it will occupy ``9`` automatically and beta ``8`` is never occupied. So, an n→π* excited state is automatically constructed. Note that we also remove an alpha orbital ``87``, since **in each orbital subspace, the number of alpha and beta orbital must be the same.** Therefore, we remove the highest one. - ``orb 0 1 87 : 8`` The second subspace it the complementary set of the first one, so it is zero-occupied. Now we can calculate the excited states. After calculation, we will obtain the excited state wavefunction ``hcho-ee-1.mwfn`` or ``hcho-ee-2.mwfn``. The excited state properties can be found in ``hcho-ee-1.out`` or ``hcho-ee-2.out``: .. code-block:: bash :linenos: :caption: hcho-ee-1.out or hcho-ee-2.out TSO Transition ============== Reference wave function read from: hcho-ee-2-ref.mwfn Reference energy: -114.54951400 Hartree Current energy: -114.42013176 Hartree E(Current)-E(Ref): 3.52067019 eV Transition dipole moment (Debye): 0.00004 -0.00000 -0.00112 Oscillator strength: 0.00000 Higher order corrections: Transition quadrupole moment (Debye*Angstrom): Qxx: -0.00001; Qyy: 0.00003; Qzz: -0.00002 Qxy: 0.00000; Qxz: -0.06437; Qyz: -0.63367 Quadrupole correction to oscillator strength: 4.31049E-09 Transition angular momentum (au): 0.06258 -0.00609 -0.00032 Magnetic dipole correction to oscillator strength: 4.53975E-09 Thus, the excited energy is 3.52 eV. The oscillator strength is 0.00, suggesting that this is a dark state. Example: HCHO n\ :sup:`2`\ →(π*)\ :sup:`2` Excitation Energy ------------------------------------------------------------------------- Now we consider a **doubly excited state**, where two electons are excited from n to π*. .. hint:: The popular TDDFT code in most programs are implemented with adiabatic approximation, making TDDFT **unable to calculate double excitation.** This is also a reason that you should use TSO-DFT: due to the theoretical flaws in TDDFT, many types of excitation, like double, core, and charge transfer excitations, cannot be studies by TDDFT, but all of them can be studied by TSO-DFT with balanced accuracy. For theoretical details, please refer to: - `J. Chem. Theory Comput. 2023, 19, 1777 `_ To calculate this n\ :sup:`2`\ →(π*)\ :sup:`2` excitation, we can use one of these 2 files: .. tabs:: .. tab:: hcho-de-1.inp .. code-block:: bash :linenos: :caption: hcho-ee-1.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type mwfn file hcho-gs.mwfn orb 16 1 1-7 9-88 : 1-7 9-88 orb 0 1 8 : 8 end mol O -0.68710791 0.04339108 0.00000000 C 0.50595906 -0.07524732 0.00000008 H 1.09294418 -0.13258299 -0.93605972 H 1.09294415 -0.13258317 0.93605964 end task energy b3lyp end .. tab:: hcho-ee-2.inp .. code-block:: bash :linenos: :caption: hcho-ee-2.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type tso frag 0 1 1-4 orb 16 1 1-7 9-88 : 1-7 9-88 orb 0 1 8 : 8 end mol O -0.68710791 0.04339108 0.00000000 C 0.50595906 -0.07524732 0.00000008 H 1.09294418 -0.13258299 -0.93605972 H 1.09294415 -0.13258317 0.93605964 end task energy b3lyp end These input files are very similar to the ones for n→π* excited state: - In ``hcho-de-1.inp``, ``type mwfn`` means that the reference state is given by a MWFN file, whose name is ``file hcho-gs.mwfn``, that is, the ground state calculated above. - In ``hcho-de-2.inp``, ``type tso`` means that the reference state is calculated automatically by Qbics. The calculated reference state will be saved to ``hcho-de-2-ref.mwfn``. The reference state is given by the following ``frag 0 1 1-4``. This ``frag`` is to assign the whole molecule (atom ``1-4``) with charge ``0`` and spin multiplicity ``1`` as reference. See :doc:`../keywords/scfguess` for more information. The orbital partition is given below: - ``orb 16 1 1-7 9-88 : 1-7 9-88`` The first subspace contains ``16`` electrons and spin multiplicity is ``1``. The numbers separated by ``:`` are the alpha orbital indices ``1-7 9-88`` and beta orbital indices ``1-7 9-88``, respecitively. Here, we remove alpha/beta orbital 8, so when the electrons are occupied, they will occupy alpha/beta ``9`` automatically and alpha/beta ``8`` is never occupied. So, an n\ :sup:`2`\ →(π*)\ :sup:`2` doubly excited state is automatically constructed. - ``orb 0 1 8 : 8`` The second subspace it the complementary set of the first one, so it is zero-occupied. Now we can calculate the excited states. After calculation, we will obtain the excited state wavefunction ``hcho-de-1.mwfn`` or ``hcho-de-2.mwfn``. The excited state properties can be found in ``hcho-de-1.out`` or ``hcho-de-2.out``: .. code-block:: bash :linenos: :caption: hcho-de-1.out or hcho-de-2.out TSO Transition ============== Reference wave function read from: hcho-de-2-ref.mwfn Reference energy: -114.54951400 Hartree Current energy: -114.15687470 Hartree E(Current)-E(Ref): 10.68425953 eV Transition dipole moment (Debye): 0.00000 0.00000 0.00000 Oscillator strength: 0.00000 Higher order corrections: Transition quadrupole moment (Debye*Angstrom): Qxx: 0.00000; Qyy: 0.00000; Qzz: 0.00000 Qxy: 0.00000; Qxz: 0.00000; Qyz: 0.00000 Quadrupole correction to oscillator strength: 0.00000E+00 Transition angular momentum (au): 0.00000 0.00000 0.00000 Magnetic dipole correction to oscillator strength: 0.00000E+00 Thus, the excited energy is 10.68 eV. Example: HCHO n→π* Excited State Geometry ---------------------------------------------- Geometry optimization of excited states by TSO-DFT is very easy. Just remember the following 3 points: #. Geometry optimization by TSO-DFT can only use ``type tso`` in ``scfguess...end``; #. Replace ``energy`` to ``opt``; #. Sometimes, excited state geometry have completely different symmtery from the ground state, in this case, some manually symmetry broken is needed. The first 2 points are easy to understand. The third point will be explained by examples. Now we want to optimize the structure of n→π* excited state of HCHO. We just need to replace ``energy`` to ``opt`` in ``hcho-ee-2.inp``. We will call this file ``hcho-ee-geom-1.inp``: .. code-block:: bash :linenos: :caption: hcho-ee-geom-1.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type tso frag 0 1 1-4 orb 16 1 1-87 : 1-7 9-88 orb 0 1 88 : 8 end mol O -0.68710791 0.04339108 0.00000000 C 0.50595906 -0.07524732 0.00000008 H 1.09294418 -0.13258299 -0.93605972 H 1.09294415 -0.13258317 0.93605964 task opt b3lyp end This file will of course do the geometry optimization for excited state of HCHO. However, note that the initial geometry is a planar one, so geometry optimization will always keep this planarity. The n→π* excitation will lead to a broken of planarity of molecules, so we should give this molecule a perturbation to enable geometry optimization to treat non-planar molecules. This is given in ``hcho-ee-geom-2.inp``: .. code-block:: bash :linenos: :caption: hcho-ee-geom-2.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type tso frag 0 1 1-4 orb 16 1 1-87 : 1-7 9-88 orb 0 1 88 : 8 end mol O -0.68710791 0.24339108 0.00000000 # Move O atom C 0.50595906 -0.27524732 0.00000008 # Move C atom H 1.09294418 -0.13258299 -0.93605972 H 1.09294415 -0.13258317 0.93605964 end task opt b3lyp end You can see that, we let C and O move out of the molecular plane by about 0.2 Angstrom. After calculations, we can check the optimized geometry of ``hcho-ee-geom-1-opt.xyz`` and ``hcho-ee-geom-2-opt.xyz`` with `Qbics-MolStar `_: .. figure:: /_images/a28.jpg We found that, the second non-planar geometry is more stable than the planar one by 0.0054 Hartree. Interestingly, if we optimize the non-planar HCHO at ground state, it will return to the planar one. Anyway, since **the potential energy surface of excited states can have completely different topology compared to the ground state one, you must take care if your excited state structure is a global minimum.** Below is another example. Example: HCCH Non-linear Excited State Geometry ----------------------------------------------------- HCCH is a linear molecule. Its ground state geometry can be easily determined. Now, we will determine its geometry for the HOMO→LUMO excited state, which is called S\ :sub:`1` state. First, the initial structure is the ground state minimum: .. code-block:: bash :linenos: :caption: hcch-1.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type tso frag 0 1 1-4 orb 14 1 1-87 : 1-6 8-88 orb 0 1 88 : 7 end mol H 0.0 0.0 -1.65969619 C 0.0 0.0 -0.59806842 C 0.0 0.0 0.59805611 H 0.0 0.0 1.65970850 end task opt b3lyp end However, with a linear initial guess, the local geometry optimization process can only lead to a linear molecule. Chemical intuition tells us that in the excited states, HCCH may bend. So, let's consider 2 cases: the 2 hydrogen atoms are in *cis* and *trans* geometry. In the input file, we will simply move the 2 hydrogen atoms in the same and opposite direction, respecitvely, by a small distance: .. tabs:: .. tab:: hcch-2.inp .. code-block:: bash :linenos: :caption: hcch-2.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type tso frag 0 1 1-4 orb 14 1 1-87 : 1-6 8-88 orb 0 1 88 : 7 end mol H 0.5 0.5 -1.65969619 # Move H in the same direction C 0.0 0.0 -0.59806842 C 0.0 0.0 0.59805611 H 0.5 0.5 1.65970850 # Move H in the same direction end task opt b3lyp end .. tab:: hcch-3.inp .. code-block:: bash :linenos: :caption: hcch-3.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type tso frag 0 1 1-4 orb 14 1 1-87 : 1-6 8-88 orb 0 1 88 : 7 end mol H 0.5 0.5 -1.65969619 # Move H in opposite direction C 0.0 0.0 -0.59806842 C 0.0 0.0 0.59805611 H 0.5 -0.5 1.65970850 # Move H in opposite direction end task opt b3lyp end After calculations, we collect the optimized structures in ``hcch-1-opt.xyz``, ``hcch-2-opt.xyz``, and ``hcch-3-opt.xyz``, shown below: .. figure:: /_images/a29.jpg Obviously, the linear geometry is far from global optimization, being completely different from the ground state. In S\ :sub:`1` state, the *trans* isomer is the most stable one. This example again emphasizes **the compexity of excited state potential energy surfac!** If you start the geometry optimization with a structure of high symmetry, you may **NEVER** arrive at the true minimum, so **try more initial structure!** .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these keywords: - :doc:`../keywords/scf` - :doc:`../keywords/scfguess` TSO-DFT (2): Diabatic States ============================================================== .. contents:: :local: This tutorial will lead you step by step to do target state optimization DFT (TSO-DFT) using Qbics. TSO-DFT is an originally developed method in Qbics. It is a powerful and accurate method for **excited** and **diabatic** states. In many physical processes like charge transfer, **TSO-DFT** can give **much more reasonable** results than TDDFT. Therefore, it is worth learning this method. .. hint:: If you use Qbics to do TSO-DFT in you paper, please cite the following references: - `J. Chem. Theory Comput. 2023, 19, 1777 `_ In this tutorial, we will introduce how to use TSO-DFT to study **dibatic states.** Example: Definition of Diabatic States of NaCl -------------------------------------------------- What is a diabatic state? Its exact definition can be found in textbooks but are not relevant to us here. Here we just use an example to show what a diabatic state is. We will take NaCl **molecule** as an example. Adiabatic State ^^^^^^^^^^^^^^^^^^ We will calculate the ground state of NaCl at B3LYP/def2-TZVP level of theory: .. code-block:: bash :linenos: :caption: nacl-1.inp basis def2-tzvp end scf charge 0 spin2p1 1 type U end mol Na 0.0 0.0 -0.68381052 Cl 0.0 0.0 1.68381052 end task energy b3lyp end Let us check the Mulliken charges in ``nacl-1.out``: .. code-block:: bash :linenos: :caption: nacl-1.out Mulliken Populations ==================== # Symbol Charge Spin ---------------------------------------------- 1 Na 0.64773687 -0.00000889 2 Cl -0.64773687 0.00000889 ---------------------------------------------- Sum -0.00000000 0.00000000 ---------------------------------------------- ...omitted... Final total energy: -622.60503718 Hartree Therefore, the Mulliken charges are ``0.6477`` and ``-0.6477``, respectively, so the charges are delocalzied over the whole molecule. This state is also called **adiabatic state.** Diabatic State: [Na\ :sup:`+`][Cl\ :sup:`-`] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Intuitively, one may think that NaCl is composed of a sodium cation Na\ :sup:`+` and a chloride antion Cl\ :sup:`-`. However, as shown above, in the adiabatic state, charges are delocalized over the molecule. Is it possible to calculate a state that charges are forced to localize on some atoms? Such state is called **diabatic state**. In the following, we will calculate a diabatic state of [Na\ :sup:`+`][Cl\ :sup:`-`]: .. code-block:: bash :linenos: :caption: nacl-2.inp basis def2-tzvp end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type fragden frag +1 1 1 frag -1 1 2 end mol Na 0.0 0.0 -0.68381052 Cl 0.0 0.0 1.68381052 end task energy b3lyp end You can see that, in ``scfguess...end``, we are setting a superposition of fragment density (``fragden``) as SCF initial guess. The only difference is that we set ``no_scf tso`` in ``scf...end``: - ``frag +1 1 1`` We are seeting the fragment of atom ``1`` with charge ``+1`` and spin multiplicity ``1``. See :doc:`../keywords/scfguess` for details. - ``frag -1 1 2`` We are seeting the fragment of atom ``2`` with charge ``-1`` and spin multiplicity ``1``. After calculation, in ``nacl-2.out``, we can find this: .. code-block:: bash :linenos: :caption: nacl-2.out Mulliken Populations ==================== # Symbol Charge Spin ---------------------------------------------- 1 Na 1.00000000 0.00000000 2 Cl -1.00000000 -0.00000000 ---------------------------------------------- Sum -0.00000000 -0.00000000 ---------------------------------------------- ...omitted... Final total energy: -622.58940107 Hartree Indeed, at Na and Cl atom, the Mulliken charge is ``1.00`` and ``-1.00``, respectively, in line with our assumed diabatic state [Na\ :sup:`+`][Cl\ :sup:`-`]. Its is higher than the adiabatic state by -622.58940107 - (-622.60503718) = 0.0156 Hartree = 9.81 kcal/mol Actually, this is the so-called **charge-transfer interaction energy.** By the way, if you check the SCF process of this diabatic state: .. code-block:: bash :linenos: :caption: nacl-2.out #it SCF energy 2e energy |deltaE| |deltaP| Orbital Time/second --------------------------------------------------------------------------------------------- 1 -622.57645781 318.90071152 1.950E-01 1.100E-05 guess 0.046 2 -622.58412894 319.42032296 7.671E-03 3.461E-05 diis 0.054 3 -622.58935124 319.21103043 5.222E-03 3.376E-05 diis 0.052 4 -622.58939707 319.19096764 4.584E-05 5.708E-06 diis 0.052 5 -622.58939958 319.18902943 2.506E-06 9.746E-07 diis 0.051 6 -622.58940082 319.19159833 1.235E-06 3.969E-07 diis 0.053 7 -622.58940107 319.19461843 2.492E-07 9.841E-08 diis 0.052 --------------------------------------------------------------------------------------------- Great (^ _ ^) SCF has converged in 7 iterations. (0.367 seconds) The energy difference of the first and last cycle -622.58940107 - (-622.57645781) = 0.0129 Hartree = 8.12 kcal/mol is the so-called **polarization interaction enerrgy**. Energy Decomposition Analysis of [Na\ :sup:`+`][Cl\ :sup:`-`] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To check this, if you do an EDA (see :doc:`eda`) for [Na\ :sup:`+`][Cl\ :sup:`-`] with the following input: .. code-block:: bash :linenos: :caption: nacl-eda.inp basis def2-tzvp end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. end eda type tso frag +1 1 1 frag -1 1 2 end mol Na 0.0 0.0 -0.68381052 Cl 0.0 0.0 1.68381052 end task eda b3lyp end In the output ``nacl-eda.out``: .. code-block:: bash :linenos: :caption: nacl-eda.out WITHOUT BSSE correction: Electrostatic interaction energy: -146.30 kcal/mol Exchange-correlation interaction energy: 23.91 kcal/mol Polarization interaction energy: -8.12 kcal/mol Charge transfer interaction energy: -9.81 kcal/mol Grimme's dispersion interaction: 0.00 kcal/mol ---------------------------------------------------------------- Total interaction energy: -140.33 kcal/mol Here, ``Charge transfer interaction energy: -9.81 kcal/mol`` and ``Polarization interaction energy: -8.12 kcal/mol`` confirm our previous calculations. Diabatic State: [Na][Cl] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Besides [Na\ :sup:`+`][Cl\ :sup:`-`], we can also assume another diabatic state: NaCl is composed of 2 neutral radical: .. code-block:: bash :linenos: :caption: nacl-3.inp basis def2-tzvp end scf charge 0 spin2p1 1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type fragden frag 0 2 1 frag 0 -2 2 end mol Na 0.0 0.0 -0.68381052 Cl 0.0 0.0 1.68381052 end task energy b3lyp end Here, ``frag 0 2 1`` means that Na has a single alpha electron, while ``frag 0 2 1`` means that Cl has a single **beta** electron, like this: .. figure:: /_images/a30.jpg After calculation, we can find this in ``nacl-3.out``: .. code-block:: bash :linenos: :caption: nacl-3.out --------------------------------------------------------------------------------------------- #it SCF energy 2e energy |deltaE| |deltaP| Orbital Time/second --------------------------------------------------------------------------------------------- 1 -622.42824748 316.12630594 3.002E-02 3.077E-04 guess 0.051 2 -622.43470909 315.62361860 6.462E-03 2.354E-04 diis 0.063 3 -622.43589868 315.69293084 1.190E-03 2.159E-05 diis 0.057 4 -622.43598379 315.69186515 8.511E-05 2.740E-05 diis 0.059 5 -622.43599795 315.67167823 1.417E-05 5.266E-07 diis 0.057 6 -622.43600008 315.68068350 2.120E-06 9.311E-06 diis 0.071 7 -622.43600052 315.68009817 4.407E-07 5.151E-07 diis 0.057 --------------------------------------------------------------------------------------------- ...omitted... Mulliken Populations ==================== # Symbol Charge Spin ---------------------------------------------- 1 Na -0.00000000 0.50000000 2 Cl 0.00000000 -0.50000000 ---------------------------------------------- Sum -0.00000000 -0.00000000 ---------------------------------------------- ...omitted.. Final total energy: -622.43600052 Hartree So, the polarization and charge transfer interaction energy is: -622.43600052 - (-622.42824748) Hartree = -4.88 kcal/mol -622.60503718 - (-622.43600052) Hartree = -106.07 kcal/mol Compared with [Na\ :sup:`+`][Cl\ :sup:`-`], the charge transfer energy of [Na][Cl] is extremely high. You can also try to compute a diabatic state of [Na\ :sup:`-`][Cl\ :sup:`+`] if you wish. In practise, to study diabatic states of molecular dimer or clusters, you can simply use :doc:`../keywords/eda` since all needed calculations will be done automatically. You just need to set the fragment charges and spin multiplicities. Example: Reactant and Product Diabatic States of F\ :sup:`-`\ +CH\ :sub:`3`\ Cl ----------------------------------------------------------------------------------------- Reactant Complex ^^^^^^^^^^^^^^^^^^^ Now we consider the reaction F\ :sup:`-`\ +CH\ :sub:`3`\ Cl. First, we calculate the reactant complex. Now we calculate the **reactant** and **product** diabatic state: .. tabs:: .. tab:: fch3cl-reac-reac.inp .. code-block:: bash :linenos: :caption: fch3cl-reac-reac.inp basis def2-svp end scf charge 0 spin2p1 -1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type fragden frag 0 1 1-5 frag -1 1 6 end mol C -0.43654823 1.13197968 0.00000000 H -0.07987539 1.63637787 0.87365150 H -0.07987539 1.63637787 -0.87365150 H -1.50654823 1.13199286 0.00000000 Cl 0.15009830 -0.52737135 0.00000000 F -1.63124586 2.75454539 -0.44024554 end task energy b3lyp end .. tab:: fch3cl-reac-prod.inp .. code-block:: bash :linenos: :caption: fch3cl-reac-prod.inp basis def2-svp end scf charge 0 spin2p1 -1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type fragden frag 0 1 1-4 6 frag -1 1 5 end mol C -0.43654823 1.13197968 0.00000000 H -0.07987539 1.63637787 0.87365150 H -0.07987539 1.63637787 -0.87365150 H -1.50654823 1.13199286 0.00000000 Cl 0.15009830 -0.52737135 0.00000000 F -1.63124586 2.75454539 -0.44024554 end task energy b3lyp end The two dibatic states can be set using ``frag``: .. figure:: /_images/a31.jpg Transition State ^^^^^^^^^^^^^^^^^^^ In the same way, we calculate the reactant and product diabatic states, but at the transition state: .. tabs:: .. tab:: fch3cl-ts-reac.inp .. code-block:: bash :linenos: :caption: fch3cl-ts-reac.inp basis def2-svp end scf charge 0 spin2p1 -1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type fragden frag 0 1 1-5 frag -1 1 6 end mol C -0.59663490 1.29366556 -0.07171644 H -0.18159761 1.68969864 0.84430018 H -0.12252870 1.52677601 -1.01427388 H -1.59298434 0.87532545 -0.06612308 Cl 0.43269073 -0.72181312 0.13298792 F -1.52293997 3.10024978 -0.26542025 end task energy b3lyp end .. tab:: fch3cl-ts-prod.inp .. code-block:: bash :linenos: :caption: fch3cl-ts-prod.inp basis def2-svp end scf charge 0 spin2p1 -1 type U # This is needed for TSO-DFT. no_scf tso end scfguess type fragden frag 0 1 1-4 6 frag -1 1 5 end mol C -0.59663490 1.29366556 -0.07171644 H -0.18159761 1.68969864 0.84430018 H -0.12252870 1.52677601 -1.01427388 H -1.59298434 0.87532545 -0.06612308 Cl 0.43269073 -0.72181312 0.13298792 F -1.52293997 3.10024978 -0.26542025 end task energy b3lyp end .. figure:: figs/a32.jpg After 4 calculations, we can get the following energies in ``fch3cl-reac-reac/prod.out`` and ``fch3cl-ts-reac/prod.out``: .. list-table:: :stub-columns: 1 * - Structure - Reactant Complex - Transition State * - Reactant Dibatic State - -599.62530856 - -599.62955746 * - Product Dibatic State - -599.49007047 - -599.62959766 Interestingly, we observe that the reactant and product diabatic energy are the same for transition state. Acutally, this is the basis for dibatic MECP method for transition state search. See :doc:`ts` and :doc:`../keywords/mecp` for more information. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these pages: - :doc:`./tso1` - :doc:`./msdft2` - :doc:`./msdft3` - :doc:`./msdft4` - :doc:`../keywords/nosi` - :doc:`../keywords/msdft` MSDFT (1): All Types of Excited States ================================================================================ .. contents:: :local: This tutorial will lead you step by step to study excited states using Multi-State Density Functional Theory (MSDFT). MSDFT is a powerful method for studying excited states. It optimizes excited states using TSO-DFT method, so it is **free of orbital relaxation problem** like in TDDFT. In this section, you will see that MSDFT can give **much more reasonable** results than TDDFT for excited states. In :doc:`tso1`, we have introduced how to use TSO-DFT to study excited states. Actually, MSDFT can be considered as TSO+NOSI. MSDFT is a framework that automaitcally performs TSO-DFT and NOSI for required excited states. Of course, you can also perform TSO-DFT and NOSI separately for special purposes. Example: Broadspectrum for HCHO ------------------------------------------------- HCHO is a typical molecule for studying excited states. As we know, HCHO has 8 occupied molecular orbitals (MOs), 2 of which are core orbitals (1s orbitals of carbon and oxygen atoms), and the remaining 6 are valence orbitals. Therefore, the excited states of HCHO to low-lying virtual orbitals contains 3 types: O K-edge excitation (O(1s) excitation), C K-edge excitation (C(1s) excitation), and valence excitations. TDDFT can show good performance for valence excitations, but it has errors for O and C K-edge excitations as large as 11 eV! A very important point is that MSDFT is balanced for all these 3 types of excitations, so in this example, we will use MSDFT to study all these 3 types of excitations of HCHO. The input file is: .. code-block:: :caption: hcho.inp :linenos: basis cc-pvtz end scf charge 0 spin2p1 1 type U schwarz 1E-14 end msdft single_ex 1-8 : 9-14 end mol O -0.68710791 0.04339108 0.00000000 C 0.50595906 -0.07524732 0.00000008 H 1.09294418 -0.13258299 -0.93605972 H 1.09294415 -0.13258317 0.93605964 end task msdft b3lyp end We explain the input file step by step: - ``basis...end`` indicates the basis set to be used. Here, we use cc-pvtz basis set. - ``scf...end`` Note that we give ``type U`` since MSDFT must be run in unrestricted formalism. - ``msdft...end`` indicates the MSDFT calculation. Here, ``single_ex 1-8 : 9-14`` means we want to study the single excitation from orbitals 1 to 8 and to orbitals 9 to 14. Explicitly, we want to study the following single excitations: - 1 → 9 - 2 → 9 - 3 → 9 - 4 → 9 - 5 → 9 - 6 → 9 - 7 → 9 - 8 → 9 - 1 → 10 - 2 → 10 - 3 → 10 - 4 → 10 - 5 → 10 - 6 → 10 - 7 → 10 - 8 → 10 - ... - 1 → 14 - 2 → 14 - 3 → 14 - 4 → 14 - 5 → 14 - 6 → 14 - 7 → 14 - 8 → 14 So, ``single_ex 1-8 : 9-14`` should be very self-explaining. After running this calculation, you will find the following output files: .. code-block:: bash hcho-1-to-10-se.mwfn hcho-2-to-11-t.mwfn hcho-3-to-13-se.mwfn hcho-4-to-14-t.mwfn hcho-6-to-10-se.mwfn hcho-7-to-11-t.mwfn hcho-8-to-13-se.mwfn hcho-1-to-10-t.mwfn hcho-2-to-12-se.mwfn hcho-3-to-13-t.mwfn hcho-4-to-9-se.mwfn hcho-6-to-10-t.mwfn hcho-7-to-12-se.mwfn hcho-8-to-13-t.mwfn hcho-1-to-11-se.mwfn hcho-2-to-12-t.mwfn hcho-3-to-14-se.mwfn hcho-4-to-9-t.mwfn hcho-6-to-11-se.mwfn hcho-7-to-12-t.mwfn hcho-8-to-14-se.mwfn hcho-1-to-11-t.mwfn hcho-2-to-13-se.mwfn hcho-3-to-14-t.mwfn hcho-5-to-10-se.mwfn hcho-6-to-11-t.mwfn hcho-7-to-13-se.mwfn hcho-8-to-14-t.mwfn hcho-1-to-12-se.mwfn hcho-2-to-13-t.mwfn hcho-3-to-9-se.mwfn hcho-5-to-10-t.mwfn hcho-6-to-12-se.mwfn hcho-7-to-13-t.mwfn hcho-8-to-9-se.mwfn hcho-1-to-12-t.mwfn hcho-2-to-14-se.mwfn hcho-3-to-9-t.mwfn hcho-5-to-11-se.mwfn hcho-6-to-12-t.mwfn hcho-7-to-14-se.mwfn hcho-ci.txt hcho-1-to-13-se.mwfn hcho-2-to-14-t.mwfn hcho-4-to-10-se.mwfn hcho-5-to-11-t.mwfn hcho-6-to-13-se.mwfn hcho-7-to-14-t.mwfn hcho-gs.mwfn hcho-1-to-13-t.mwfn hcho-2-to-9-se.mwfn hcho-4-to-10-t.mwfn hcho-5-to-12-se.mwfn hcho-6-to-13-t.mwfn hcho-7-to-9-se.mwfn hcho.inp hcho-1-to-14-se.mwfn hcho-2-to-9-t.mwfn hcho-4-to-11-se.mwfn hcho-5-to-12-t.mwfn hcho-6-to-14-se.mwfn hcho-7-to-9-t.mwfn hcho.mwfn hcho-1-to-14-t.mwfn hcho-3-to-10-se.mwfn hcho-4-to-11-t.mwfn hcho-5-to-13-se.mwfn hcho-6-to-14-t.mwfn hcho-8-to-10-se.mwfn hcho.out hcho-1-to-9-se.mwfn hcho-3-to-10-t.mwfn hcho-4-to-12-se.mwfn hcho-5-to-13-t.mwfn hcho-6-to-9-se.mwfn hcho-8-to-10-t.mwfn hcho-spectrum.txt hcho-1-to-9-t.mwfn hcho-3-to-11-se.mwfn hcho-4-to-12-t.mwfn hcho-5-to-14-se.mwfn hcho-6-to-9-t.mwfn hcho-8-to-11-se.mwfn hcho-ts.mwfn hcho-2-to-10-se.mwfn hcho-3-to-11-t.mwfn hcho-4-to-13-se.mwfn hcho-5-to-14-t.mwfn hcho-7-to-10-se.mwfn hcho-8-to-11-t.mwfn hcho-2-to-10-t.mwfn hcho-3-to-12-se.mwfn hcho-4-to-13-t.mwfn hcho-5-to-9-se.mwfn hcho-7-to-10-t.mwfn hcho-8-to-12-se.mwfn hcho-2-to-11-se.mwfn hcho-3-to-12-t.mwfn hcho-4-to-14-se.mwfn hcho-5-to-9-t.mwfn hcho-7-to-11-se.mwfn hcho-8-to-12-t.mwfn The meaning of these files should be very self-explaining: - ``hcho-1-to-10-se.mwfn``: Singlet single excitation determinant from orbital 1 to 10. Calculated by TSO-DFT. - ``hcho-1-to-10-t.mwfn``: Triplet single excitation determinant from orbital 1 to 10. Calculated by TSO-DFT. - ``hcho-gs.mwfn``: Ground state determinant. - ``hcho-ci.txt```: Configuration interaction (CI) coefficients between the ground state and the excited states. - ``hcho-spectrum.txt``: Excited state energies and oscillator strengths. It can be used to plot the spectrum. A very good feature of MSDFT module in Qbics is that it can be **restarted from the previous calculation**. For example, with ``hcho.inp``, if your calculation is interrupted, you can restart it from the previous calculation by simply running ``qbics hcho.inp`` again. Excited states that have been computed will not be calculated again. In ``hcho-ci.txt``, you will find the following information: .. code-block:: :caption: hcho-ci.txt :linenos: hcho-gs.mwfn hcho-1-to-9-se.mwfn spin_flip_hcho-1-to-9-se.mwfn hcho-1-to-10-se.mwfn spin_flip_hcho-1-to-10-se.mwfn hcho-1-to-11-se.mwfn spin_flip_hcho-1-to-11-se.mwfn hcho-1-to-12-se.mwfn spin_flip_hcho-1-to-12-se.mwfn hcho-1-to-13-se.mwfn spin_flip_hcho-1-to-13-se.mwfn hcho-1-to-14-se.mwfn spin_flip_hcho-1-to-14-se.mwfn hcho-2-to-9-se.mwfn spin_flip_hcho-2-to-9-se.mwfn hcho-2-to-10-se.mwfn spin_flip_hcho-2-to-10-se.mwfn hcho-2-to-11-se.mwfn spin_flip_hcho-2-to-11-se.mwfn hcho-2-to-12-se.mwfn spin_flip_hcho-2-to-12-se.mwfn hcho-2-to-13-se.mwfn spin_flip_hcho-2-to-13-se.mwfn hcho-2-to-14-se.mwfn spin_flip_hcho-2-to-14-se.mwfn hcho-3-to-9-se.mwfn spin_flip_hcho-3-to-9-se.mwfn hcho-3-to-10-se.mwfn spin_flip_hcho-3-to-10-se.mwfn hcho-3-to-11-se.mwfn spin_flip_hcho-3-to-11-se.mwfn hcho-3-to-12-se.mwfn spin_flip_hcho-3-to-12-se.mwfn hcho-3-to-13-se.mwfn spin_flip_hcho-3-to-13-se.mwfn hcho-3-to-14-se.mwfn spin_flip_hcho-3-to-14-se.mwfn hcho-4-to-9-se.mwfn spin_flip_hcho-4-to-9-se.mwfn hcho-4-to-10-se.mwfn spin_flip_hcho-4-to-10-se.mwfn hcho-4-to-11-se.mwfn spin_flip_hcho-4-to-11-se.mwfn hcho-4-to-12-se.mwfn spin_flip_hcho-4-to-12-se.mwfn hcho-4-to-13-se.mwfn spin_flip_hcho-4-to-13-se.mwfn hcho-4-to-14-se.mwfn spin_flip_hcho-4-to-14-se.mwfn hcho-5-to-9-se.mwfn spin_flip_hcho-5-to-9-se.mwfn hcho-5-to-10-se.mwfn spin_flip_hcho-5-to-10-se.mwfn hcho-5-to-11-se.mwfn spin_flip_hcho-5-to-11-se.mwfn hcho-5-to-12-se.mwfn spin_flip_hcho-5-to-12-se.mwfn hcho-5-to-13-se.mwfn spin_flip_hcho-5-to-13-se.mwfn hcho-5-to-14-se.mwfn spin_flip_hcho-5-to-14-se.mwfn hcho-6-to-9-se.mwfn spin_flip_hcho-6-to-9-se.mwfn hcho-6-to-10-se.mwfn spin_flip_hcho-6-to-10-se.mwfn hcho-6-to-11-se.mwfn spin_flip_hcho-6-to-11-se.mwfn hcho-6-to-12-se.mwfn spin_flip_hcho-6-to-12-se.mwfn hcho-6-to-13-se.mwfn spin_flip_hcho-6-to-13-se.mwfn hcho-6-to-14-se.mwfn spin_flip_hcho-6-to-14-se.mwfn hcho-7-to-9-se.mwfn spin_flip_hcho-7-to-9-se.mwfn hcho-7-to-10-se.mwfn spin_flip_hcho-7-to-10-se.mwfn hcho-7-to-11-se.mwfn spin_flip_hcho-7-to-11-se.mwfn hcho-7-to-12-se.mwfn spin_flip_hcho-7-to-12-se.mwfn hcho-7-to-13-se.mwfn spin_flip_hcho-7-to-13-se.mwfn hcho-7-to-14-se.mwfn spin_flip_hcho-7-to-14-se.mwfn hcho-8-to-9-se.mwfn spin_flip_hcho-8-to-9-se.mwfn hcho-8-to-10-se.mwfn spin_flip_hcho-8-to-10-se.mwfn hcho-8-to-11-se.mwfn spin_flip_hcho-8-to-11-se.mwfn hcho-8-to-12-se.mwfn spin_flip_hcho-8-to-12-se.mwfn hcho-8-to-13-se.mwfn spin_flip_hcho-8-to-13-se.mwfn hcho-8-to-14-se.mwfn spin_flip_hcho-8-to-14-se.mwfn 0.99560913 -0.00000003 -0.00000003 0.00001534 0.00001534 0.00114350 0.00114351 -0.00153370 -0.00153371 0.00000039 0.00000039 -0.00010346 -0.00010346 0.00000179 0.00000179 -0.00107255 -0.00107255 -0.00000000 -0.00000000 -0.00040710 -0.00040710 -0.00000037 -0.00000037 0.00043794 0.00043795 -0.00002795 -0.00002777 -0.00436908 -0.00436911 0.00000000 0.00000002 0.01424106 0.01424114 -0.00000857 -0.00000861 0.00301359 0.00301360 0.00003226 0.00003213 -0.02803909 -0.02803946 -0.00000004 -0.00000023 -0.00129582 -0.00129576 0.00003624 0.00003624 0.01310570 0.01310577 -0.00000017 -0.00000044 0.00000015 0.00000060 0.03456283 0.03456304 -0.00000004 -0.00000007 0.00000004 0.00000004 0.00000030 0.00000035 0.00010560 0.00010920 0.01482854 0.01482881 0.00000010 0.00000017 -0.00405550 -0.00405553 -0.00001639 -0.00001653 0.00200558 0.00200559 -0.03841319 -0.03841054 -0.00006055 -0.00006067 0.00000004 0.00000005 0.00004803 0.00004811 0.01584468 0.01584465 0.00000846 0.00000847 0.00000020 0.00000236 -0.00000058 0.00000053 -0.00159919 -0.00159946 -0.00000014 -0.00000008 0.00000002 -0.00000001 -0.00000035 -0.00000035 0.00000150 -0.00000000 0.00000000 0.00000000 0.00000000 0.00000000 0.00000000 -0.00000000 -0.00000000 0.00000000 -0.00000000 -0.00000000 -0.00000000 -0.00000000 0.00000000 -0.00000000 -0.00000000 0.00000020 -0.00000020 -0.00000000 -0.00000000 0.00000000 -0.00000000 0.00000000 0.00000000 -0.00000003 0.00000003 -0.00000001 -0.00000001 -0.00000069 0.00000069 0.00000000 0.00000004 -0.00000001 0.00000001 -0.00000000 0.00000001 0.00000040 -0.00000040 0.00000001 -0.00000012 -0.00003928 0.00003928 -0.00000002 0.00000002 -0.00000003 0.00000003 0.00000004 0.00000001 0.04484569 -0.04484569 0.00009137 -0.00009137 0.00000003 0.00000010 0.00003755 -0.00003755 0.00284210 -0.00284210 0.00000866 -0.00000866 -0.00000071 0.00000072 -0.00000002 0.00000008 0.00002182 -0.00002182 -0.00000001 -0.00000001 0.00000003 -0.00000003 0.00000001 -0.00000001 0.00000007 -0.00000025 -0.00000000 0.00000000 -0.00331372 0.00331372 -0.00000001 0.00000001 -0.00000002 0.00000008 -0.00000001 0.00000001 0.70584687 -0.70584687 0.00000690 -0.00000690 0.00000028 -0.00000027 -0.00004415 0.00004415 -0.00418456 0.00418456 -0.00001737 0.00001737 0.00000177 0.00000000 0.00000000 0.00000000 0.00000000 0.00000000 0.00000000 -0.00000000 -0.00000000 -0.00000000 -0.00000000 -0.00000000 -0.00000000 0.00000000 0.00000000 -0.00000000 -0.00000000 -0.00000005 -0.00000005 -0.00000000 -0.00000000 -0.00000000 -0.00000000 0.00000000 0.00000000 0.00000003 0.00000003 -0.00000001 -0.00000001 0.00000366 0.00000366 0.00000001 0.00000001 0.00000001 0.00000001 0.00000000 0.00000000 -0.00000040 -0.00000040 -0.00000004 -0.00000004 0.00001763 0.00001763 -0.00000003 -0.00000003 0.00000003 0.00000003 0.00000001 0.00000001 -0.05112536 -0.05112536 -0.00005166 -0.00005166 0.00000004 0.00000004 -0.00002375 -0.00002375 -0.00104504 -0.00104504 0.00002882 0.00002882 0.00000075 0.00000075 -0.00000000 -0.00000000 -0.00000653 -0.00000653 -0.00000001 -0.00000001 -0.00000003 -0.00000003 0.00000001 0.00000001 -0.00000006 -0.00000006 0.00000002 0.00000002 0.00094859 0.00094859 -0.00000001 -0.00000001 -0.00000001 -0.00000001 -0.00000001 -0.00000001 -0.70546067 -0.70546067 -0.00005036 -0.00005036 -0.00000010 -0.00000010 0.00002947 0.00002947 0.00517794 0.00517794 -0.00002117 -0.00002117 -0.00000008 0.00000014 -0.00000014 0.00000064 -0.00000064 -0.00053975 0.00053975 0.00086019 -0.00086019 -0.00000038 0.00000038 0.00008698 -0.00008698 0.00000187 -0.00000187 -0.00047589 0.00047589 -0.00000000 0.00000000 -0.00027619 0.00027619 0.00000007 -0.00000007 0.00031214 -0.00031214 0.00001230 -0.00001230 0.00800444 -0.00800444 -0.00000001 0.00000001 -0.01812879 0.01812879 0.00001604 -0.00001604 -0.01082709 0.01082709 -0.00011444 0.00011444 -0.02131200 0.02131201 0.00000004 -0.00000004 0.00193396 -0.00193396 -0.00000881 0.00000881 0.01598192 -0.01598192 -0.00000044 0.00000044 -0.00000007 0.00000007 0.01268254 -0.01268254 -0.00000002 0.00000002 -0.00000001 0.00000001 -0.00000002 0.00000002 -0.00036683 0.00036683 -0.00437980 0.00437980 -0.00000005 0.00000005 0.00068293 -0.00068293 -0.00000034 0.00000034 0.00219123 -0.00219123 0.71248403 -0.71248402 0.00005779 -0.00005779 -0.00000013 0.00000013 0.00023606 -0.00023606 0.00112889 -0.00112889 0.00006985 -0.00006985 -0.00000013 0.00000013 0.00000035 -0.00000035 -0.00251385 0.00251385 0.00000004 -0.00000004 -0.00000001 0.00000001 0.00000005 -0.00000005 ... Each line is a state with coefficients. They are the same with the following lines in ``hcho.out``, but are more convienent for automatic analysis: .. code-block:: :caption: hcho.out :linenos: ---- NOSI Coefficients Matrix (column vectors are eigenvectors) ---- ==================================================================== 0 1 2 3 4 0 0.99560913 0.00000150 0.00000177 -0.00000008 0.00000018 1 -0.00000003 -0.00000000 0.00000000 0.00000014 0.00000000 2 -0.00000003 0.00000000 0.00000000 -0.00000014 0.00000000 3 0.00001534 0.00000000 0.00000000 0.00000064 -0.00000000 4 0.00001534 0.00000000 0.00000000 -0.00000064 0.00000000 5 0.00114350 0.00000000 0.00000000 -0.00053975 0.00000004 6 0.00114351 0.00000000 0.00000000 0.00053975 -0.00000004 7 -0.00153370 -0.00000000 -0.00000000 0.00086019 -0.00000004 8 -0.00153371 -0.00000000 -0.00000000 -0.00086019 0.00000004 9 0.00000039 0.00000000 -0.00000000 -0.00000038 0.00000000 10 0.00000039 -0.00000000 -0.00000000 0.00000038 -0.00000000 11 -0.00010346 -0.00000000 -0.00000000 0.00008698 0.00000000 12 -0.00010346 -0.00000000 -0.00000000 -0.00008698 -0.00000000 13 0.00000179 -0.00000000 0.00000000 0.00000187 0.00000000 14 0.00000179 0.00000000 0.00000000 -0.00000187 -0.00000000 15 -0.00107255 -0.00000000 -0.00000000 -0.00047589 0.00000000 The following lines are excitation energies and oscillator strengths, which are also in ``hcho-spectrum.txt``: .. code-block:: :caption: hcho.out :linenos: ---- NOSI Results ---- ====================== State NOSI Energies Excited Energy Osc. Str. DX DY DZ (Hartree) (eV) (a.u.) (a.u.) (a.u.) 0 -114.55472122 0.00000000 0.00000000 -1.67410 -0.89631 0.00000 1 -114.43192614 3.34125415 0.00000000 0.00000 0.00000 0.00000 2 -114.41053475 3.92331383 0.00000004 0.00000 0.00000 -0.00088 3 -114.39885445 4.24113491 0.00000000 -0.00000 0.00000 -0.00000 4 -114.27926662 7.49511958 0.00000000 0.00000 -0.00000 -0.00000 5 -114.26311475 7.93461209 0.00000000 0.00000 -0.00000 0.00000 6 -114.26115827 7.98784791 0.10048800 0.00000 -0.00000 -1.01488 7 -114.23545182 8.68732031 0.00000000 -0.00000 0.00000 0.00000 8 -114.22993229 8.83750667 0.00148189 0.01385 0.11635 0.00000 9 -114.22276183 9.03261499 0.00171129 -0.12377 0.01390 -0.00000 10 -114.20424336 9.53650263 0.00000000 -0.00000 -0.00000 0.00000 11 -114.20235213 9.58796291 0.00000000 -0.00000 0.00000 -0.00000 12 -114.18660197 10.01652481 0.03607540 0.00000 0.00000 -0.54302 13 -114.17489121 10.33517463 0.00000022 0.00000 0.00000 -0.00132 The following lines list the states and their high-weighted Slater determinants: .. code-block:: :caption: hcho.out :linenos: ---- NOSI State Identification (Coefficients) ---- ================================================== State |0> = +0.996 |hcho-gs.mwfn> State |1> = +0.706 |hcho-8-to-9-se.mwfn> -0.706 |spin_flip_hcho-8-to-9-se.mwfn> State |2> = -0.705 |hcho-8-to-9-se.mwfn> -0.705 |spin_flip_hcho-8-to-9-se.mwfn> State |3> = +0.712 |hcho-7-to-9-se.mwfn> -0.712 |spin_flip_hcho-7-to-9-se.mwfn> State |4> = -0.700 |hcho-8-to-10-se.mwfn> +0.700 |spin_flip_hcho-8-to-10-se.mwfn> State |5> = +0.703 |hcho-6-to-9-se.mwfn> -0.703 |spin_flip_hcho-6-to-9-se.mwfn> State |6> = +0.704 |hcho-8-to-10-se.mwfn> +0.704 |spin_flip_hcho-8-to-10-se.mwfn> State |7> = -0.695 |hcho-8-to-11-se.mwfn> +0.695 |spin_flip_hcho-8-to-11-se.mwfn> ... ---- NOSI State Identification (Weights) ---- ============================================= State |0> = 0.991 |hcho-gs.mwfn> State |1> = 0.498 |hcho-8-to-9-se.mwfn> 0.498 |spin_flip_hcho-8-to-9-se.mwfn> State |2> = 0.498 |hcho-8-to-9-se.mwfn> 0.498 |spin_flip_hcho-8-to-9-se.mwfn> State |3> = 0.499 |hcho-7-to-9-se.mwfn> 0.499 |spin_flip_hcho-7-to-9-se.mwfn> State |4> = 0.489 |hcho-8-to-10-se.mwfn> 0.489 |spin_flip_hcho-8-to-10-se.mwfn> State |5> = 0.495 |hcho-6-to-9-se.mwfn> 0.495 |spin_flip_hcho-6-to-9-se.mwfn> State |6> = 0.495 |hcho-8-to-10-se.mwfn> 0.495 |spin_flip_hcho-8-to-10-se.mwfn> State |7> = 0.480 |hcho-8-to-11-se.mwfn> 0.480 |spin_flip_hcho-8-to-11-se.mwfn> From these, we can know that the state 0 is the ground state, and the state 1 and 2 are mainly composed of the excited state of MO 8 → 9. Note that **if the coefficients are of the opposite sign, then it is a triplet state; if the coefficients are of the same sign, then it is a singlet state.**, so state 1 is triplet 8 → 9 excitated state; state 2 is singlet 8 → 9 excitated state. Then, state 3 is triplet 7 → 9 excitated state; state 4 is triplet 8 → 10 excitated state; state 5 is triplet 6 → 9 excitated state; state 6 is singlet 8 → 10 excitated state; state 7 is triplet 8 → 11 excitated state, and so on. With ``hcho-spectrum.txt``, we can plot the spectrum of the molecule using the python script provided in ``qbics/tools/plotspec.py``. Copy it to the same directory as ``hcho-spectrum.txt``, and modify the following parameters: .. code-block:: python :linenos: :caption: plotspec.py if __name__ == "__main__": fn = "hcho-spectrum.txt" # Spectrum file name. eL_eV = 3.3 # Lower energy limit. eH_eV = 558.6 # Higher energy limit. sigma_eV = 0.2 # Sigma value. num_ps = 3000 # Number of points. use_angle = False # Whether to use angle dependence. .. tip:: Please cite this paper, if you use this script and formular in it: - `J. Phys. Chem. C 2022, 126, 8720 `_ Here, we want to plot the spectrum from 3.3 (``eL_eV``) to 558.6 (``eH_eV``) eV, with a sigma value of 0.2 (``sigma_eV``) and 3000 (``num_ps``) points. Run ``./plotspec.py`` to get the spectrum plot: .. figure:: /_images/a40.jpg We can see that, MSDFT can plot broadspectrum, ranging from 3.3 eV to 558.6 eV, including valence and core excitations. Example: Valence Excitations for HCHO ------------------------------------------------- Of course, we can use MSDFT to plot only a part of the spectrum. For example, we can only calculate valence excitations, MO 8 → 9 (HOMO → LUMO) and MO 8 → 10 (HOMO → LUMO+1). So use the following input file: .. code-block:: :caption: valence.inp :linenos: basis cc-pvtz end scf charge 0 spin2p1 1 type U schwarz 1E-14 end msdft single_ex 8 : 9 10 end mol O -0.68710791 0.04339108 0.00000000 C 0.50595906 -0.07524732 0.00000008 H 1.09294418 -0.13258299 -0.93605972 H 1.09294415 -0.13258317 0.93605964 end task msdft b3lyp end The output is: .. code-block:: :caption: valence.out :linenos: ---- NOSI Results ---- ====================== State NOSI Energies Excited Energy Osc. Str. DX DY DZ (Hartree) (eV) (a.u.) (a.u.) (a.u.) 0 -114.54951400 0.00000000 0.00000000 -2.00272 -0.86383 0.00000 1 -114.43098101 3.22528264 0.00000000 0.00001 -0.00000 0.00000 2 -114.40928299 3.81568579 0.00000003 0.00005 -0.00001 0.00080 3 -114.27311171 7.52090618 0.00000000 -0.00000 -0.00000 0.00000 4 -114.25847627 7.91913672 0.12823740 -0.00000 0.00000 1.15144 ---- NOSI State Identification (Coefficients) ---- ================================================== State |0> = -1.000 |valence-gs.mwfn> State |1> = +0.707 |valence-8-to-9-se.mwfn> -0.707 |spin_flip_valence-8-to-9-se.mwfn> State |2> = +0.707 |valence-8-to-9-se.mwfn> +0.707 |spin_flip_valence-8-to-9-se.mwfn> State |3> = -0.707 |valence-8-to-10-se.mwfn> +0.707 |spin_flip_valence-8-to-10-se.mwfn> State |4> = +0.707 |valence-8-to-10-se.mwfn> +0.707 |spin_flip_valence-8-to-10-se.mwfn> ---- NOSI State Identification (Weights) ---- ============================================= State |0> = 1.000 |valence-gs.mwfn> State |1> = 0.500 |valence-8-to-9-se.mwfn> 0.500 |spin_flip_valence-8-to-9-se.mwfn> State |2> = 0.500 |valence-8-to-9-se.mwfn> 0.500 |spin_flip_valence-8-to-9-se.mwfn> State |3> = 0.500 |valence-8-to-10-se.mwfn> 0.500 |spin_flip_valence-8-to-10-se.mwfn> State |4> = 0.500 |valence-8-to-10-se.mwfn> 0.500 |spin_flip_valence-8-to-10-se.mwfn> The 5 states are: 0 is the ground state, 1 and 2 are the triplet and singlet excited state of MO 8 → 9, respectively; 3 and 4 are the triplet and singlet excited state of MO 8 → 10, respectively. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these pages: - :doc:`./tso1` - :doc:`./msdft1` - :doc:`./msdft3` - :doc:`./msdft4` - :doc:`../keywords/nosi` - :doc:`../keywords/msdft` MSDFT (2): Core Ionizations and Excitations ================================================================================ .. contents:: :local: This tutorial will lead you step by step to study excited states using Multi-State Density Functional Theory (MSDFT). MSDFT is a powerful method for studying excited states. It optimizes excited states using TSO-DFT method, so it is **free of orbital relaxation problem** like in TDDFT. In this section, you will see that MSDFT can give **much more reasonable** results than TDDFT for excited states. In :doc:`tso1`, we have introduced how to use TSO-DFT to study excited states. In :doc:`msdft1`, we have introduced how to use MSDFT to study excitations generally. In this tutorial, we will introduce how to use MSDFT to study core excitations. We strongly recommend you to read these two tutorials before reading this tutorial. Actually, MSDFT can be considered as TSO+NOSI. MSDFT is a framework that automaitcally performs TSO-DFT and NOSI for required excited states. Of course, you can also perform TSO-DFT and NOSI separately for special purposes. Example: Core Ionization Poteitals of CH\ :sub:`3`\ CN ---------------------------------------------------------- .. tip:: To study core excitations, one should use the (aug-)cc-pCVXZ basis set here instead of the (aug-)cc-pVXZ basis set for heavy atoms. Before going to core excitations, we first discuss how to calculate the core ionization potentials. First, we do a ground state calculation for CH\ :sub:`3`\ CN. .. code-block:: :caption: msdft-2-gs.inp :linenos: basis element H cc-pVTZ N cc-pCVTZ C cc-pCVTZ end scf charge 0 spin2p1 1 type u end mol C -0.04745178 -0.06805384 -0.11694780 H 0.30905509 -1.09741742 -0.13005981 H 0.30945822 0.43682112 -1.01404303 H -1.13674654 -0.07474849 -0.12959758 C 0.43731777 0.61649095 1.07195392 N 0.81994723 1.16084767 2.00936430 end task energy b3lyp end Note that, to study core excitations, we need to use a basis set that can describe core orbitals well. So we use the cc-pCVTZ basis set here instead of the cc-pVTZ basis set for heavy atoms. For hydrogen atoms, we use the cc-pVTZ basis set. In the outpuf wave function file ``msdft-2-gs.mwfn``, we can see the core orbitals are the 1s orbitals of carbon and oxygen atoms using `Qbics-MolStar `_. First drag ``msdft-2-gs.mwfn`` into explorer, and it will be automatically loaded. Right-click :guilabel:`msdft-2-gs.mwfn` and select :guilabel:`View Molecular Orbitals`, click orbital 1, 2, and 3: .. figure:: /_images/a41.jpg Thus, the MO 1,2,3 are the 1s orbitals of nitrogen, methyl group carbon, and cyano group carbon atom, respectively. We will calculate the core ionization potentials of these 3 orbitals. The input file are: .. tabs:: .. tab:: msdft-2-ip1.inp .. code-block:: bash :linenos: :caption: msdft-2-ip1.inp :emphasize-lines: 16-19 basis element H cc-pVTZ N cc-pCVTZ C cc-pCVTZ end scf charge 0 spin2p1 1 type u no_scf tso end scfguess type mwfn file msdft-2-gs.mwfn orb 21 2 1-170 : 2-171 orb 0 1 171 : 1 end mol C -0.04745178 -0.06805384 -0.11694780 H 0.30905509 -1.09741742 -0.13005981 H 0.30945822 0.43682112 -1.01404303 H -1.13674654 -0.07474849 -0.12959758 C 0.43731777 0.61649095 1.07195392 N 0.81994723 1.16084767 2.00936430 end task energy b3lyp end .. tab:: msdft-2-ip2.inp .. code-block:: bash :linenos: :caption: msdft-2-ip2.inp :emphasize-lines: 29 basis element H cc-pVTZ N cc-pCVTZ C cc-pCVTZ end scf charge 0 spin2p1 1 type u no_scf tso end scfguess type mwfn file msdft-2-gs.mwfn orb 21 2 1-170 : 1 3-171 orb 0 1 171 : 2 end mol C -0.04745178 -0.06805384 -0.11694780 H 0.30905509 -1.09741742 -0.13005981 H 0.30945822 0.43682112 -1.01404303 H -1.13674654 -0.07474849 -0.12959758 C 0.43731777 0.61649095 1.07195392 N 0.81994723 1.16084767 2.00936430 end task energy b3lyp end .. tab:: msdft-2-ip3.inp .. code-block:: bash :linenos: :caption: msdft-2-ip3.inp :emphasize-lines: 29 basis element H cc-pVTZ N cc-pCVTZ C cc-pCVTZ end scf charge 0 spin2p1 1 type u no_scf tso end scfguess type mwfn file msdft-2-gs.mwfn orb 21 2 1-170 : 1 2 4-171 orb 0 1 171 : 3 end mol C -0.04745178 -0.06805384 -0.11694780 H 0.30905509 -1.09741742 -0.13005981 H 0.30945822 0.43682112 -1.01404303 H -1.13674654 -0.07474849 -0.12959758 C 0.43731777 0.61649095 1.07195392 N 0.81994723 1.16084767 2.00936430 end task energy b3lyp end Let us take ``msdft-2-ip1.inp`` as an example. As all basis set and coordinates are the same as the ground state calculation, we only need to change the orbital to be calculated. We use TSO-DFT to calculate the core ionization potential of the 1s orbital of nitrogen atom. - Line 16,17: we will use the ground state wave function file ``msdft-2-gs.mwfn`` to generate the initial guess for the ionized state calculation. - Line 18: we build a orbital space containing alpha orbitals 1-171, and beta orbitals 2-170. Note that, the number of electrons is only ``21`` instead of ``22`` in neutral state, so the spin multiplicity is ``2`` instead of ``1``. Note that, with this orbital space, elecrons are automatically assigned to the corresponding orbitals with the nitrogen 1s alpha orbital unoccupied. - Line 19: a remaining orbital space containing only the nitrogen 1s beta orbital is specified and the highest alpha orbital to keep the numbers of alpha and beta orbitals the same. The orbital space is shown below. You can also see :doc:`./tso1` for more details about the orbital space. .. figure:: /_images/a42.jpg After calculation, the output is shown below: .. tabs:: .. tab:: msdft-2-ip1.out .. code-block:: bash :linenos: :caption: msdft-2-ip1.out :emphasize-lines: 6 TSO Transition ============== Reference wave function read from: msdft-2-gs.mwfn Reference energy: -132.81032200 Hartree Current energy: -117.91513595 Hartree E(Current)-E(Ref): 405.31865749 eV .. tab:: msdft-2-ip2.out .. code-block:: bash :linenos: :caption: msdft-2-ip2.out :emphasize-lines: 6 TSO Transition ============== Reference wave function read from: msdft-2-gs.mwfn Reference energy: -132.81032200 Hartree Current energy: -122.05195311 Hartree E(Current)-E(Ref): 292.75012878 eV .. tab:: msdft-2-ip3.out .. code-block:: bash :linenos: :caption: msdft-2-ip3.out :emphasize-lines: 6 TSO Transition ============== Reference wave function read from: msdft-2-gs.mwfn Reference energy: -132.81032200 Hartree Current energy: -122.05109782 Hartree E(Current)-E(Ref): 292.77340232 eV The hightlighted values are the core ionization potentials of the 1s orbitals of nitrogen, methyl group carbon, and cyano group carbon atom, respectively. The results from TSO-DFT are very accurate, see below: .. figure:: /_images/a43.jpg Example: C and N K-edge XAS of CH\ :sub:`3`\ CN ---------------------------------------------------------- Now we can calculate 1s excitation energies, i.e. K-edge XAS. The energy range of C (292 eV) and N (402 eV) K-edge XAS are quiet separated, so we can use 2 files to calculate them. See below: .. tabs:: .. tab:: msdft-2-CXAS.inp .. code-block:: bash :linenos: :caption: msdft-2-CXAS.inp :emphasize-lines: 16-19 basis element H cc-pVTZ N cc-pCVTZ C cc-pCVTZ end scf charge 0 spin2p1 1 type u schwarz 1.E-14 end output not_strict end mol C -0.04745178 -0.06805384 -0.11694780 H 0.30905509 -1.09741742 -0.13005981 H 0.30945822 0.43682112 -1.01404303 H -1.13674654 -0.07474849 -0.12959758 C 0.43731777 0.61649095 1.07195392 N 0.81994723 1.16084767 2.00936430 end msdft single_ex 2-3 : 12-16 end task msdft b3lyp end .. tab:: msdft-2-NXAS.inp .. code-block:: bash :linenos: :caption: msdft-2-NXAS.inp :emphasize-lines: 16-19 basis element H cc-pVTZ N cc-pCVTZ C cc-pCVTZ end scf charge 0 spin2p1 1 type u schwarz 1.E-14 end output not_strict end mol C -0.04745178 -0.06805384 -0.11694780 H 0.30905509 -1.09741742 -0.13005981 H 0.30945822 0.43682112 -1.01404303 H -1.13674654 -0.07474849 -0.12959758 C 0.43731777 0.61649095 1.07195392 N 0.81994723 1.16084767 2.00936430 end msdft single_ex 1 : 12-16 end task msdft b3lyp end Take ``msdft-2-CXAS.inp`` as an example. The MSDFT option: - ``msdft...end`` indicates the MSDFT calculation. Here, ``single_ex 2-3 : 12-16`` means we want to study the single excitation from orbitals 2,3 to orbitals 12 to 16. Explicitly, we want to study the following single excitations: - 2 → 12 - 2 → 13 - 2 → 14 - 2 → 15 - 2 → 16 - 3 → 12 - 3 → 13 - 3 → 14 - 3 → 15 - 3 → 16 ``msdft-2-NXAS.inp`` is similar. After calculation, the output is shown below: .. tabs:: .. tab:: msdft-2-CXAS.out .. code-block:: bash :linenos: :caption: msdft-2-CXAS.out ---- NOSI Results ---- ====================== State NOSI Energies Excited Energy Osc. Str. DX DY DZ (Hartree) (eV) (a.u.) (a.u.) (a.u.) 0 -132.81033068 0.00000000 0.00000000 20.96814 29.62520 51.36982 1 -122.29776407 286.04693739 0.00000000 -0.00000 0.00000 -0.00000 2 -122.29628111 286.08728868 0.00000000 0.00000 -0.00000 0.00000 3 -122.27262763 286.73090010 0.06090910 0.00031 -0.11416 0.06602 4 -122.27184218 286.75227222 0.06054746 -0.12395 0.02131 0.03833 5 -122.22807524 287.94317052 0.00000000 -0.00000 -0.00000 -0.00000 6 -122.20022633 288.70093945 0.00148936 -0.00675 0.00366 0.01906 7 -122.19999870 288.70713325 0.00000000 0.00000 -0.00000 0.00000 8 -122.19931169 288.72582670 0.00000000 0.00000 -0.00000 -0.00000 9 -122.19077081 288.95822418 0.01841754 -0.00426 0.06444 -0.03238 10 -122.18956504 288.99103317 0.01846930 -0.06940 0.00640 0.01937 11 -122.13308009 290.52798857 0.00000000 0.00000 0.00000 -0.00000 12 -122.12598852 290.72095017 0.00000000 -0.00000 -0.00000 0.00000 13 -122.12277134 290.80848975 0.02666731 0.07435 -0.04434 -0.00365 14 -122.11545370 291.00760270 0.02780428 0.03543 0.06347 -0.05038 15 -122.08534743 291.82679427 0.00000000 0.00000 -0.00000 0.00000 16 -122.08400221 291.86339771 0.00255869 0.02421 -0.01085 -0.00373 17 -122.08280065 291.89609221 0.00000000 0.00000 -0.00000 0.00000 18 -122.08151697 291.93102093 0.00252312 0.00672 0.02049 -0.01558 19 -121.85348605 298.13574240 0.00040867 0.00666 -0.00638 -0.00521 20 -121.84404145 298.39272982 0.00000000 0.00000 0.00000 -0.00000 ---- NOSI State Identification (Coefficients) ---- ================================================== State |0> = +1.000 |msdft-2-CXAS-gs.mwfn> State |1> = -0.487 |msdft-2-CXAS-3-to-12-se.mwfn> +0.487 |spin_flip_msdft-2-CXAS-3-to-12-se.mwfn> +0.419 | msdft-2-CXAS-3-to-13-se.mwfn> -0.419 |spin_flip_msdft-2-CXAS-3-to-13-se.mwfn> State |2> = +0.314 |msdft-2-CXAS-3-to-12-se.mwfn> -0.314 |spin_flip_msdft-2-CXAS-3-to-12-se.mwfn> +0.461 | msdft-2-CXAS-3-to-13-se.mwfn> -0.461 |spin_flip_msdft-2-CXAS-3-to-13-se.mwfn> +0.311 |msdft-2-CXAS-3-to-14-se.mwfn> -0.311 |spin_flip_msdft-2-CXAS-3-to-14-se.mwfn> State |3> = -0.445 |msdft-2-CXAS-3-to-12-se.mwfn> -0.445 |spin_flip_msdft-2-CXAS-3-to-12-se.mwfn> +0.372 | msdft-2-CXAS-3-to-13-se.mwfn> +0.372 |spin_flip_msdft-2-CXAS-3-to-13-se.mwfn> -0.041 |msdft-2-CXAS-3-to-14-se.mwfn> -0.041 |spin_flip_msdft-2-CXAS-3-to-14-se.mwfn> State |4> = +0.086 |msdft-2-CXAS-3-to-12-se.mwfn> +0.086 |spin_flip_msdft-2-CXAS-3-to-12-se.mwfn> +0.479 | msdft-2-CXAS-3-to-13-se.mwfn> +0.479 |spin_flip_msdft-2-CXAS-3-to-13-se.mwfn> +0.458 |msdft-2-CXAS-3-to-14-se.mwfn> +0.458 |spin_flip_msdft-2-CXAS-3-to-14-se.mwfn> State |5> = +0.706 |msdft-2-CXAS-2-to-12-se.mwfn> -0.706 |spin_flip_msdft-2-CXAS-2-to-12-se.mwfn> State |6> = -0.696 |msdft-2-CXAS-2-to-12-se.mwfn> -0.696 |spin_flip_msdft-2-CXAS-2-to-12-se.mwfn> .. tab:: msdft-2-NXAS.out .. code-block:: bash :linenos: :caption: msdft-2-NXAS.out :emphasize-lines: 8,9,22,23 ---- NOSI Results ---- ====================== State NOSI Energies Excited Energy Osc. Str. DX DY DZ (Hartree) (eV) (a.u.) (a.u.) (a.u.) 0 -132.81032203 0.00000000 0.00000000 20.96814 29.62523 51.36982 1 -118.14811920 398.95853898 0.00000000 -0.00000 0.00000 -0.00000 2 -118.14680628 398.99426361 0.00000000 0.00000 -0.00000 0.00000 3 -118.12556491 399.57224120 0.05264859 0.08930 -0.05270 -0.00609 4 -118.12410116 399.61206995 0.05267515 0.04016 0.07493 -0.05970 5 -117.94199382 404.56721069 0.00000000 0.00000 -0.00000 -0.00000 6 -117.94127276 404.58683066 0.00171928 -0.01720 0.00646 0.00323 7 -117.93957743 404.63296056 0.00000000 -0.00000 -0.00000 0.00000 8 -117.93889138 404.65162785 0.00169993 -0.00377 -0.01499 0.01025 9 -117.81947316 407.90099772 0.00011256 0.00131 -0.00341 -0.00304 10 -117.81277843 408.08316134 0.00000000 0.00000 0.00000 -0.00000 ---- NOSI State Identification (Coefficients) ---- ================================================== State |0> = +1.000 |msdft-2-NXAS-gs.mwfn> State |1> = -0.530 |msdft-2-NXAS-1-to-12-se.mwfn> +0.530 |spin_flip_msdft-2-NXAS-1-to-12-se.mwfn> +0.360 |msdft-2-NXAS-1-to-13-se.mwfn> -0.360 |spin_flip_msdft-2-NXAS-1-to-13-se.mwfn> State |2> = +0.542 |msdft-2-NXAS-1-to-12-se.mwfn> -0.542 |spin_flip_msdft-2-NXAS-1-to-12-se.mwfn> +0.617 |msdft-2-NXAS-1-to-13-se.mwfn> -0.617 |spin_flip_msdft-2-NXAS-1-to-13-se.mwfn> State |3> = +0.390 |msdft-2-NXAS-1-to-12-se.mwfn> +0.390 |spin_flip_msdft-2-NXAS-1-to-12-se.mwfn> -0.336 |msdft-2-NXAS-1-to-13-se.mwfn> -0.336 |spin_flip_msdft-2-NXAS-1-to-13-se.mwfn> -0.133 |msdft-2-NXAS-1-to-14-se.mwfn> -0.133 |spin_flip_msdft-2-NXAS-1-to-14-se.mwfn> State |4> = -0.526 |msdft-2-NXAS-1-to-12-se.mwfn> -0.526 |spin_flip_msdft-2-NXAS-1-to-12-se.mwfn> -0.621 |msdft-2-NXAS-1-to-13-se.mwfn> -0.621 |spin_flip_msdft-2-NXAS-1-to-13-se.mwfn> The excitation energies, oscillator strengths, and transition dipole moments, and state coefficients can be found here and details can be found in :doc:`./msdft1`. You can use the python script provided in ``qbics/tools/plotspec.py`` to plot the XAS spectra for ``msdft-2-CXAS-spectrum.txt`` and ``msdft-2-NXAS-spectrum.txt``. Copy it to the same directory as the output files, and modify the parameters according to the introductions in :doc:`./msdft1`. For example, to plot the C K-edge XAS spectrum, use: .. tabs:: .. tab:: for C K-edge XAS .. code-block:: python :linenos: :caption: plotspec.py if __name__ == "__main__": fn = "msdft-2-CXAS-spectrum.txt" # Spectrum file name. eL_eV = 286 # Lower energy limit. eH_eV = 298 # Higher energy limit. sigma_eV = 0.2 # Sigma value. num_ps = 3000 # Number of points. use_angle = False # Whether to use angle dependence. .. tab:: for N K-edge XAS .. code-block:: python :linenos: :caption: plotspec.py if __name__ == "__main__": fn = "msdft-2NXAS-spectrum.txt" # Spectrum file name. eL_eV = 308 # Lower energy limit. eH_eV = 408 # Higher energy limit. sigma_eV = 0.2 # Sigma value. num_ps = 3000 # Number of points. use_angle = False # Whether to use angle dependence. The spectra are shown below: .. figure:: /_images/a44.jpg .. tip:: Note that in XAS we indicate the position of IP. This also reminds you that it is **NOT** necessary to calculate core excitated states beyond this IP. Beyond this IP, an accurate calculation of the excitation involves the use of continuous states, which is not considered in this tutorial. You can try to identify the spectrum. For example, the largest peak in N K-edge XAS is 399.5 eV, which corresponds state 3 and 4 in ``msdft-2-NXAS.out`` (see highlighted lines), and the peak turns out to be a mixture of N(1s) → 12(LUMO) and N(1s) → 13(LUMO+1) transitions. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these pages: - :doc:`./tso1` - :doc:`./msdft1` - :doc:`./msdft2` - :doc:`./msdft4` - :doc:`../keywords/nosi` - :doc:`../keywords/msdft` MSDFT (3): Double Excitations ================================================================================ .. contents:: :local: This tutorial will lead you step by step to study excited states using Multi-State Density Functional Theory (MSDFT). MSDFT is a powerful method for studying excited states. It optimizes excited states using TSO-DFT method, so it is **free of orbital relaxation problem** like in TDDFT. In this section, you will see that MSDFT can give **much more reasonable** results than TDDFT for excited states. In :doc:`tso1`, we have introduced how to use TSO-DFT to study excited states. In :doc:`msdft1`, we have introduced how to use MSDFT to study excitations generally. In :doc:`msdft2`, we have introduced how to use MSDFT to study core excitations. In this tutorial, we will introduce how to use MSDFT to study double excitations. We strongly recommend you to read these two tutorials before reading this tutorial. Actually, MSDFT can be considered as TSO+NOSI. MSDFT is a framework that automaitcally performs TSO-DFT and NOSI for required excited states. Of course, you can also perform TSO-DFT and NOSI separately for special purposes. Example: Double Excitations of Glyoxal ---------------------------------------------------------- Below is the input file for calculating double excitations of glyoxal: .. code-block:: :caption: msdft-3.inp :linenos: basis cc-pVTZ end scf charge 0 spin2p1 1 type U end mol C 0.642211002 0.401329163 0. C -0.642211002 -0.401329163 0. O 1.722902738 -0.139984242 0. O -1.722902738 0.139984242 0. H 0.508726009 1.491661991 0. H -0.508726009 -1.491661991 0. end msdft double_ex 15 : 16 17 end task msdft b3lyp end - ``msdft...end`` indicates the MSDFT calculation. Here, ``double_ex 15 : 16 17`` means we want to study the double excitations from orbitals 15 to orbitals 16 and 17. Explicitly, we want to study the following double excitations: - 15 (HOMO) → 16 (LUMO) - 15 (HOMO) → 17 (LUMO+1) In the output file, we can find the following information: Below is the input file for calculating double excitations of glyoxal: .. code-block:: :caption: msdft-3.out :linenos: :emphasize-lines: 6,7,18,19 ---- NOSI Results ---- ====================== State NOSI Energies Excited Energy Osc. Str. DX DY DZ (Hartree) (eV) (a.u.) (a.u.) (a.u.) 0 -227.91006738 0.00000000 0.00000000 -0.00002 -0.00001 0.00000 1 -227.72694413 4.98278376 0.00000000 0.00000 0.00000 -0.00000 2 -227.36327349 14.87826196 0.00000000 -0.00001 -0.00000 0.00000 ---- NOSI State Identification (Coefficients) ---- ================================================== State |0> = -0.999 |msdft-3-gs.mwfn> State |1> = -0.952 |msdft-3-15-to-16-de.mwfn> +0.303 |msdft-3-15-to-17-de.mwfn> State |2> = +0.302 |msdft-3-15-to-16-de.mwfn> +0.953 |msdft-3-15-to-17-de.mwfn> ---- NOSI State Identification (Weights) ---- ============================================= State |0> = 0.997 |msdft-3-gs.mwfn> State |1> = 0.906 |msdft-3-15-to-16-de.mwfn> 0.092 |msdft-3-15-to-17-de.mwfn> State |2> = 0.091 |msdft-3-15-to-16-de.mwfn> 0.908 |msdft-3-15-to-17-de.mwfn> From the highlighted lines, for state 1 (2), the weight of double excitation from orbitals 15 to orbitals 16 (17) is 0.906 (0.908), so state 1 (2) can be identified as the double excitation from orbitals 15 to orbitals 16 (17). For (15)\ :sup:`2` → (16)\ :sup:`2`, i.e. (HOMO)\ :sup:`2` → (LUMO)\ :sup:`2`, the excited energy is 4.98 eV. The theoretical best estimate for this excitation is 5.54 eV(J. Chem. Theory Comput. 2019, 15, 1939). Interestingly, if we only use TSO-DFT to study this excitation, the excited energy is 5.86 eV (see Line 1020 in ``msdft-3.out``). Summarizing the results, we can list them below: .. list-table:: * - State - TSO-DFT - MSDFT - Theoretical Best Estimate * - (15)\ :sup:`2` → (16)\ :sup:`2` - 5.86 eV - 4.98 eV - 5.54 eV * - (15)\ :sup:`2` → (17)\ :sup:`2` - 13.96 eV - 14.88 eV - N/A .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these pages: - :doc:`./tso1` - :doc:`./msdft1` - :doc:`./msdft2` - :doc:`./msdft3` - :doc:`../keywords/nosi` - :doc:`../keywords/msdft` MSDFT (4): Charge Transfer Excitations ================================================================================ .. contents:: :local: This tutorial will lead you step by step to study excited states using Multi-State Density Functional Theory (MSDFT). MSDFT is a powerful method for studying excited states. It optimizes excited states using TSO-DFT method, so it is **free of orbital relaxation problem** like in TDDFT. In this section, you will see that MSDFT can give **much more reasonable** results than TDDFT for excited states. In :doc:`tso1`, we have introduced how to use TSO-DFT to study excited states. In :doc:`msdft1`, we have introduced how to use MSDFT to study excitations generally. In :doc:`msdft2`, we have introduced how to use MSDFT to study core excitations. In :doc:`msdft3`, we have introduced how to use MSDFT to study double excitations. In this tutorial, we will introduce how to use MSDFT to study charge transfer excitations. We strongly recommend you to read these tutorials before reading this tutorial. Actually, MSDFT can be considered as TSO+NOSI. MSDFT is a framework that automaitcally performs TSO-DFT and NOSI for required excited states. Of course, you can also perform TSO-DFT and NOSI separately for special purposes. Example: Charge Transfer Excitations of [TCNE][CH\ :sub:`3`\ OCH=CH\ :sub:`2`] ---------------------------------------------------------------------------------- In this example, we will calculate the charge transfer excitations of the complex [TCNE][CH\ :sub:`3`\ OCH=CH\ :sub:`2`], whiere TCNE is tetracyanoethylene. First, let us calculate its ground state to see its orbitals. .. code-block:: :caption: msdft-4-gs.inp :linenos: basis cc-pVDZ # In product studies, you should use cc-pVTZ at least. end scf charge 0 spin2p1 1 type U end mol C -0.198382 0.676975 0.839378 C -1.315863 0.038931 0.405996 C -2.225365 0.670286 -0.508436 N -2.959552 1.174482 -1.247154 C -1.634267 -1.289698 0.850726 N -1.901673 -2.352749 1.221105 C 0.723624 0.024005 1.725081 N 1.483401 -0.507944 2.417545 C 0.131547 2.005023 0.406927 N 0.406859 3.079229 0.077027 C -0.018608 -1.360064 -2.097094 C 1.086004 -1.277514 -1.352322 H -0.458263 -2.333443 -2.305731 H -0.471114 -0.462748 -2.522620 H 1.590935 -2.157076 -0.934177 O 1.621801 -0.078506 -1.011442 C 2.981195 -0.123945 -0.597217 H 3.629890 -0.409943 -1.438672 H 3.239414 0.887438 -0.263120 H 3.112168 -0.831294 0.237956 end task energy b3lyp end After calculation, we can visualize ``msdft-4-gs.mwfn`` using `Qbics-MolStar `_. First drag ``msdft-4-gs.mwfn`` into explorer, and it will be automatically loaded. Right-click :guilabel:`msdft-4-gs.mwfn` and select :guilabel:`View Molecular Orbitals`, click orbital 48, 49, and 50: .. figure:: /_images/a45.png .. figure:: /_images/a46.png Obviously, MO48 is the HOMO mainly localized on CH\ :sub:`3`\ OCH=CH\ :sub:`2`, and MO49 and MO50 are the unoccupied π* and σ* orbitals mainly localized on TCNE, so excitation 48(HOMO) → 49 (LUMO) and 48(HOMO) → 50 (LUMO+1) are both close to but not perfect charge transfer. It seems that MO50 is more localized on TCNE but MO49 still has a few components on CH\ :sub:`3`\ OCH=CH\ :sub:`2`. We will use MSDFT to calculate these 2 excitations: .. code-block:: :caption: msdft-4-ct.inp :linenos: basis cc-pVDZ # In product studies, you should use cc-pVTZ at least. end scf charge 0 spin2p1 1 type U end mol C -0.198382 0.676975 0.839378 C -1.315863 0.038931 0.405996 C -2.225365 0.670286 -0.508436 N -2.959552 1.174482 -1.247154 C -1.634267 -1.289698 0.850726 N -1.901673 -2.352749 1.221105 C 0.723624 0.024005 1.725081 N 1.483401 -0.507944 2.417545 C 0.131547 2.005023 0.406927 N 0.406859 3.079229 0.077027 C -0.018608 -1.360064 -2.097094 C 1.086004 -1.277514 -1.352322 H -0.458263 -2.333443 -2.305731 H -0.471114 -0.462748 -2.522620 H 1.590935 -2.157076 -0.934177 O 1.621801 -0.078506 -1.011442 C 2.981195 -0.123945 -0.597217 H 3.629890 -0.409943 -1.438672 H 3.239414 0.887438 -0.263120 H 3.112168 -0.831294 0.237956 end msdft single_ex 48 : 49 50 end task msdft b3lyp end - ``msdft...end`` indicates the MSDFT calculation. Here, ``single_ex 48 : 49 50`` means we want to study the single excitation from orbitals 48 to orbitals 49 and 50. Explicitly, we want to study the following single excitations: - 48 → 49 - 48 → 50 In the output file ``msdft-4-ct.out``, we can find the following information: .. code-block:: :caption: msdft-4-ct.out :linenos: ---- NOSI Results ---- ====================== State NOSI Energies Excited Energy Osc. Str. DX DY DZ (Hartree) (eV) (a.u.) (a.u.) (a.u.) 0 -640.67704670 0.00000000 0.00000000 -1.24736 0.66912 0.44355 1 -640.56771187 2.97500080 0.00000000 -0.00000 -0.00000 0.00000 2 -640.55543283 3.30911339 0.17632767 -1.18048 0.77057 1.54122 3 -640.54664537 3.54822018 0.00000000 0.00000 -0.00000 -0.00000 4 -640.42108402 6.96474459 0.55299075 2.03421 0.55834 1.43209 ---- NOSI State Identification (Coefficients) ---- ================================================== State |0> = -0.999 |msdft-4-ct-gs.mwfn> State |1> = +0.710 |msdft-4-ct-48-to-49-se.mwfn> -0.710 |spin_flip_msdft-4-ct-48-to-49-se.mwfn> State |2> = -0.700 |msdft-4-ct-48-to-49-se.mwfn> -0.700 |spin_flip_msdft-4-ct-48-to-49-se.mwfn> State |3> = -0.708 |msdft-4-ct-48-to-50-se.mwfn> +0.708 |spin_flip_msdft-4-ct-48-to-50-se.mwfn> State |4> = -0.707 |msdft-4-ct-48-to-50-se.mwfn> -0.707 |spin_flip_msdft-4-ct-48-to-50-se.mwfn> State 2 and 4 are singlet charge transfer excitations. Example: Distance-Dependence of Charge Transfer Excitations ---------------------------------------------------------------------------------- Theoretical analysis reveals that the charge transfer excitation energies :math:`\omega` and the distance between the acceptor and donor :math:`d` has such a relationship: .. math:: \omega=A+\frac{B}{d} However, conventional TDDFT **cannot** repoduce this relationship because **TDDFT has systematic error for charge transfer excitations!** Let's see if MSDFT can reproduce this relationship for the above example. Generate Structures ^^^^^^^^^^^^^^^^^^^^^^^^^ To study the distance dependence, we will generate a series of [TCNE][CH\ :sub:`3`\ OCH=CH\ :sub:`2`] structures that the donor and acceptor departs. First, we save the structure in ``msdft-4-gs.inp`` in an XYZ file called ``r0.xyz``: .. code-block:: :caption: r0.xyz :linenos: 20 d = 3.21 Angstrom C -0.198382 0.676975 0.839378 C -1.315863 0.038931 0.405996 C -2.225365 0.670286 -0.508436 N -2.959552 1.174482 -1.247154 C -1.634267 -1.289698 0.850726 N -1.901673 -2.352749 1.221105 C 0.723624 0.024005 1.725081 N 1.483401 -0.507944 2.417545 C 0.131547 2.005023 0.406927 N 0.406859 3.079229 0.077027 C -0.018608 -1.360064 -2.097094 C 1.086004 -1.277514 -1.352322 H -0.458263 -2.333443 -2.305731 H -0.471114 -0.462748 -2.522620 H 1.590935 -2.157076 -0.934177 O 1.621801 -0.078506 -1.011442 C 2.981195 -0.123945 -0.597217 H 3.629890 -0.409943 -1.438672 H 3.239414 0.887438 -0.263120 H 3.112168 -0.831294 0.237956 Now, we write a python script to generate a series of structures: .. code-block:: python :caption: generate_structure.py :linenos: #!/usr/bin/python3 def read_xyz(path): with open(path, 'r') as f: lines = f.readlines() natoms = int(lines[0].strip()) title = lines[1].rstrip("\n") coords = [line.rstrip("\n") for line in lines[2:]] if len(coords) != natoms: raise ValueError("The number of atoms is inconsistent with the first line") return natoms, title, coords def write_xyz(path, natoms, title, coords): with open(path, 'w') as f: f.write(f"{natoms}\n") f.write(f"{title}\n") for line in coords: f.write(f"{line}\n") def translate_atoms(coords, vector, start_idx, end_idx): dx, dy, dz = vector for i in range(start_idx, end_idx + 1): if i >= len(coords): break parts = coords[i].split() if len(parts) < 4: raise ValueError(f"Line {i+3} format error: {coords[i]}") sym, x, y, z = parts[0], float(parts[1]), float(parts[2]), float(parts[3]) x += dx y += dy z += dz coords[i] = f"{sym:>2s} {x:15.8f} {y:15.8f} {z:15.8f}" return coords if __name__ == "__main__": dx = (-0.198382)-1.086004 dy = (0.676975)-(-1.277514) dz = (0.839378)-(-1.352322) r = (dx*dx+dy*dy+dz*dz)**0.5 ex = dx/r ey = dy/r ez = dz/r in_file = "r0.xyz" for i in range(1,9): natoms, title, coords = read_xyz(in_file) dr = 0.5*i d = 3.21+dr vector = (ex*dr, ey*dr, ez*dr) coords = translate_atoms(coords, vector, start_idx=0, end_idx=9) out_file = f"r{i:d}.xyz" title = f"d = {d:.2f} Angstrom" write_xyz(out_file, natoms, title, coords) print(f"Write {out_file}.") Run this python script by ``./generate_structure.py`` and we will generate 14 structures, with TCNE moving along axis atom 1-12 by 0.5 Angstorm every time. See below: .. figure:: /_images/a47.jpg Calculate Energies ^^^^^^^^^^^^^^^^^^^^^^^^^ Now, prepare the input file: .. code-block:: :caption: msdft-4-rd.inp :linenos: basis cc-pVDZ # In product studies, you should use cc-pVTZ at least. end scf charge 0 spin2p1 1 type U end mol r0.xyz end msdft single_ex 48 : 49 50 end task msdft b3lyp end Now, we write a shell script to run the 15 calculations by replacing ``r0.xyz`` to ``r1.xyz``, etc.: .. code-block:: bash :caption: run.sh :linenos: inp=msdft-4-rd.inp for i in {0..9}; do sed "s/r0\.xyz/r${i}.xyz/g" "$inp" > "msdft-4-r${i}.inp" # Replace qbics-linux-cpu to the suitable one for your system qbics-linux-cpu "msdft-4-r${i}.inp" -n 24 > "msdft-4-r${i}.out" done When all calculations are completed, we can extract excitation energies to ``energies.txt``: .. code-block:: bash :caption: get_energies.sh :linenos: out="energies.txt" echo "Distance E1 E2" > ${out} for i in {0..9}; do d=$(echo "3.21 + $i * 0.5" | bc -l) read -r e1 e2 < <(awk 'NR==3{printf "%s ",$3} NR==5{printf "%s",$3}' "msdft-4-r${i}-spectrum.txt") echo "$d $e1 $e2" >> ${out} done Fit and Plot Data ^^^^^^^^^^^^^^^^^^^^^^^^^ Now, we write a python script to read the distances and excitation energies, fit the energies with respect to :math:`\omega=A+\frac{B}{d}`, and plot them: .. code-block:: python :caption: plot_fit.py :linenos: #!/usr/bin/python3 import matplotlib.pyplot as plt import numpy as np import matplotlib.gridspec as gridspec from scipy.stats import linregress # Fit data. def fit(a, b): res = linregress(a, b) return a*res.slope+res.intercept, res # Get data. fn = "energies.txt" data = np.loadtxt(fn, skiprows = 1).transpose() d = data[0] e1 = data[1] e2 = data[2] idx1 = 4 idx2 = 2 d1_fit = d[idx1:] d2_fit = d[idx2:] e1_fit, res1 = fit(1/d1_fit, e1[idx1:]) e2_fit, res2 = fit(1/d2_fit, e2[idx2:]) # Draw figures. plt.subplot(1, 2, 1) plt.plot(d, e1, "ro", label="Excitation: 48->49") plt.plot(d1_fit, e1_fit, "r-", label="Fit") plt.text(4, 3.35, f"$\omega = {res1.intercept:.3f}{res1.slope:.3f}/d$", fontsize=12, color='red') plt.text(4, 3.33, f"$R^2$ = {res1.rvalue**2:.3f}", fontsize=12, color='red') plt.xlabel("$d$ (Angstrom)", fontsize=12) plt.ylabel("$\omega$ (eV)", fontsize=12) plt.legend() plt.subplot(1, 2, 2) plt.plot(d, e2, "bo", label="Excitation: 48->50") plt.plot(d2_fit, e2_fit, "b-", label="Fit") plt.text(6, 7.025, f"$\omega = {res2.intercept:.3f}{res2.slope:.3f}/d$", fontsize=12, color='blue') plt.text(6, 7.015, f"$R^2$ = {res2.rvalue**2:.3f}", fontsize=12, color='blue') plt.xlabel("$d$ (Angstrom)", fontsize=12) plt.ylabel("$\omega$ (eV)", fontsize=12) plt.legend() # Finally, plot. plt.show() The plot is shown below: .. figure:: /_images/a48.jpg Interstingly, at the begining, the excitation energies strongly fluctuate, but after 4 or 5 Angstrom, the excitation energy increases following the :math:`\omega=A+\frac{B}{d}` rule with very good R-value (0.969 and 0.994, respectively). It seems that 48 (HOMO) → 50 (LUMO+1) singlet excitation is more charge transfer-like! .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For more information of this section, please refer to these pages: - :doc:`../keywords/qmmm` - :doc:`../tutorials/dft` - :doc:`../tutorials/semi` - :doc:`../tutorials/charmm` QM/MM Simulations ========================================= .. contents:: :local: This tutorial will lead you step by step to do standard molecular dynamics (MD) simulations using Qbics. Assume you have read :doc:`dft`, :doc:`semi`, and :doc:`charmm`. General Considerations ---------------------------- To perform a QM/MM simulation, typically you need to follow the following steps: - Prepare input files that can be used for **pure MM simulations.** Please refer to :doc:`charmm` for details; - Relax the system using MM method. This step is optional, but it is highly **recommended** to ensure the system is in a reasonable state before QM/MM calculations; - Select a QM region, and do QM/MM calculations. The QM method can be DFT, xTB, or NDDO. Please refer to :doc:`dft` and :doc:`semi` for details. During the QM/MM simulation, there should **NOT** be covalent bonds forming or breaking between QM and MM region. Otherwise, the QM region shold be extended. The best case is that there is no covalent bond between QM and MM region. But, Qbics can handle specific cases, where the QM region is covalently bonded to sp\ :sup:`3`\ carbon atoms in the MM region. Note that, in the QM region, **any covalent bonds formation or breaking is allowed,** no matter what connectivity is defined in the topology file. In the following, we will demonstrate how to do QM/MM simulations with Qbics. Example: in Water Box XXX .. tip:: All input files can be downloaded: :download:`Files `. basis ================= .. contents:: :local: This keyword defines the basis functions used for quantum chemical calculations. You can define basis sets in several flexible ways. Using Built-in Basis Sets ------------------------- A lot of important basis sets have been provided in a directory ``basis`` in the same path of Qbics. The files are named after their names well-known in computational chemistry community. For example, ``basis/cc-pvdz`` contains the cc-pVDZ basis. All files are named in small cases. To use them, simple write down the basis set name. It is **case-insensitive.** For example, to use def2-TZVP for all atoms: .. code-block:: bash :linenos: basis def2-TZVP end Qbics will extract basis set information from ``basis/def2-tzvp``. Explicit Basis Set Definitions ------------------------------ You can also explicitly define your own basis sets. For example, your system contains two elements, H and Li, then their basis sets can be defined in this way: .. code-block:: bash :linenos: basis H 0 S 3 1.00 13.0107010 0.19682158E-01 1.9622572 0.13796524 0.4445379 0.47831935 S 1 1.00 0.12194962 1.0000000 P 1 1.00 0.8000000 1.0000000 **** Li 0 S 5 1.00 266.27785516 0.64920150325E-02 40.069783447 0.47747863215E-01 9.0559944389 0.20268796111 2.4503009051 0.48606574817 0.72209571855 0.43626977955 S 1 1.00 0.52810884721E-01 1.0000000 S 1 1.00 0.20960948798E-01 1.0000000 P 2 1.00 1.4500000 0.2586000 0.3000000 1.0000000 P 1 1.00 0.0820000 1.0000000 **** end The analyitcal expression of Gaussian basis function is: .. math:: \chi(\mathbf{r}) = A_{L}(\mathbf{r})\sum_{k=1}^{K} C_k e^{-\alpha_k r_A^2} Here, :math:`A_{L}(\mathbf{r})` is the angular part with angular momentum quantum number :math:`L`, :math:`K` is the contraction degree, :math:`\alpha_k` is the exponent, :math:`C_k` is the contraction coefficient, and :math:`\mathbf{A}` is the atom position. The basis set definition is of standard Gaussian94 format: - The definition of the basis set for each atom ends with 4 asterisks, i.e. ``****``. - The definition starts with the element name like ``Li`` and a ``0``. Currently ``0`` has no meaning. - Then, each GTO shell is defined. The shell definition starts with three parameters: * Angular momentum :math:`L`. It can be any nonnegative numbers like ``0``, ``5``, or one of ``S``, ``P``, ``D``, ``F``, ``G``, ``H``, and ``I``. * Contraction degree :math:`K`. It must be a positive integer. * A real number. Currently it has no meaning. * Then, each line defines the exponent :math:`\alpha_k` and contraction coefficient :math:`C_k` of the primitive GTO to be contracted. They are 2 real numbers. For more about basis function expressions, please refer to :doc:`basinfo`. .. hint:: Basis sets in Gaussian94 format can be obtained from several websites. But, remember to replace ``D`` to ``E`` since the former is not recognized by Qbics. - https://www.basissetexchange.org/ - https://www.cosmologic-services.de/basis-sets/basissets.php - https://comp.chem.umn.edu/basissets/basis.cgi - http://www.grant-hill.group.shef.ac.uk/ccrepo/index.html Using Self-defined Basis Set Files ---------------------------------- You can also put your explicit basis set definitions into some files, say ``/home/zhang/userdef/my-own-basis``. Qbics will automatically read it if you give explicit file name including path. .. code-block:: bash :linenos: basis /home/zhang/userdef/my-own-basis end The format can be found in ``basis`` directory. Define Different Basis Sets for Different Elements --------------------------------------------------- If you want to use different basis set s for different elements, then you can write ``element`` in the first line, then write element and basis set file name line by line. For example: .. code-block:: bash :linenos: basis element # This indicates that Qbics will assign basis set element by element. O aug-cc-pvtz C cc-pvtz N /home/zhang/userdef/my-own-basis end Theoretical Background ------------------------- .. hint:: To determine what basis set you should use, the following guidelines are recommended: - Nowadays, nobody uses STO-nG or basis sets without polarization functions like ``6-31g``, unless you really know what you are doing. - For systems with strongly delocalized electrons, use diffuse basis sets, like ``6-31+g(d)`` or ``aug-cc-pvDZ``. - To consider core-excitations or strong core-valence interactions, use (aug-)cc-p(W)CVnZ. - To get accurate energies, use triple-zeta basis sets or better, like ``6-311g(d)``, ``def2-TZVP`` or ``cc-pVTZ``. - For non-relativistic calculations, use basis set with pseudopotentials instead of all-electron ones. For example, it is better to use cc-pVDZ-PP for Cu than using cc-pVDZ. Karlsruhe Basis Sets ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Karlsruhe family (def2-) is a versatile and widely used series of basis sets in quantum chemistry, particularly effective for calculations involving heavy elements and systems requiring efficient computational performance. **For elements ≥ Rb,** def2- basis sets incorporate **pseudopotentials** to reduce computational cost while maintaining high accuracy for valence electron properties. .. attention:: These basis sets for **elements ≥ Rb** must be used together with corresponding ``def2-ECP`` pseudopotentials! See :ref:`example` below. In Qbics, the following Karlsruhe basis sets are available: .. list-table:: :header-rows: 1 * - Basis set - Applied to * - ``def2-svp`` - H-Xe, Cs-Ba, Hf-Rn, La-Lu * - ``def2-tzvp`` - H-Xe, Cs-Ba, Hf-Rn, La-Lu * - ``def2-tzvpp`` - H-Xe, Cs-Ba, Hf-Rn, La-Lu * - ``def2-qzvp`` - H-Xe, Cs-Ba, Hf-Rn, La-Lu * - ``def2-qzvpp`` - H-Xe, Cs-Ba, Hf-Rn, La-Lu * - ``def2-svpd`` - H-Xe, Cs-Ba, Hf-Rn, La * - ``def2-tzvpd`` - H-Xe, Cs-Ba, Hf-Rn, La * - ``def2-tzvppd`` - H-Xe, Cs-Ba, Hf-Rn, La * - ``def2-qzvpd`` - H-Xe, Cs-Ba, Hf-Rn, La * - ``def2-qzvppd`` - H-Xe, Cs-Ba, Hf-Rn, La Here: - ``pp``: Adds additional polarization functions on both heavy and hydrogen atoms. - ``pd``: Adds diffuse functions on both heavy and hydrogen atoms. - ``ppd``: Adds diffuse functions and additional polarization functions on both heavy and hydrogen atoms. Dunning Correlation-Consistent Basis Sets ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Dunning correlation-consistent basis sets are high-precision basis sets widely used in quantum chemistry, particularly for systems with significant electron correlation. These basis sets aim to ensure consistent treatment of electron correlation across different levels of precision, offering **reliable and accurate** results. They are recommended for **high-precision calculations** and **excitated states**. In Qbics, the following Dunning correlation-consistent basis sets are available: .. list-table:: :header-rows: 1 * - Basis set - Applied to * - ``cc-pVDZ`` - H-He, Li-Ne, Na-Ar, Ca-Kr * - ``cc-pVTZ`` - H-He, Li-Ne, Na-Ar, Ca-Kr * - ``cc-pVQZ`` - H-He, Li-Ne, Na-Ar, Ca-Kr * - ``cc-pCVDZ`` - Li-Ne, Na-Ar, Ca * - ``cc-pCVTZ`` - Li-Ne, Na-Ar, Ca * - ``cc-pCVQZ`` - Li-Ne, Na-Ar, Ca * - ``cc-pwCVDZ`` - B-Ne, Al-Ar * - ``cc-pWCVTZ`` - B-Ne, Al-Ar, Sc-Zn * - ``cc-pWCVQZ`` - B-Ne, Al-Ar, Sc-Zn, Br * - ``aug-cc-pVDZ`` - H-Ar, Sc-Kr * - ``aug-cc-pVTZ`` - H-Ar, Sc-Kr * - ``aug-cc-pVQZ`` - H-Ar, Sc-Kr * - ``aug-cc-pCVDZ`` - Li-Ne, Na-Ar * - ``aug-cc-pCVTZ`` - Li-Ne, Na-Ar * - ``aug-cc-pCVQZ`` - Li-Ne, Na-Ar * - ``aug-cc-pWCVDZ`` - B-Ne, Al-Ar * - ``aug-cc-pWCVTZ`` - B-Ne, Al-Ar * - ``aug-cc-pWCVQZ`` - B-Ne, Al-Ar Here: - ``aug``: Adds diffuse functions on heavy and hydrogen atoms. - ``c``: Adds tight basis functions for core electrons. - ``wc``: Adds tighter basis functions for core electrons. Dunning Correlation-Consistent Basis Sets with Pseudopotentials ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Dunning correlation-consistent basis sets with pseudopotentials simplify calculations for heavy elements by replacing core electrons with pseudopotentials. This reduces computational costs while retaining high accuracy for valence electron interactions. .. attention:: These basis sets must be used together with corresponding ``cc-ECP`` pseudopotentials! See :ref:`example` below. In Qbics, the following Dunning correlation-consistent basis sets with pseudopotentials are available: .. list-table:: :header-rows: 1 * - Basis set - Applied to * - ``cc-pVDZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``cc-pVTZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``cc-pVQZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``cc-pWCVDZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``cc-pWCVTZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``cc-pWCVQZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``aug-cc-pVDZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``aug-cc-pVTZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``aug-cc-pVQZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``aug-cc-pWCVDZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``aug-cc-pWCVTZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn * - ``aug-cc-pWCVQZ-PP`` - Cu-Kr, Y-Xe, Hf-Rn Pople Basis Sets ^^^^^^^^^^^^^^^^^^^^^^ Pople basis sets are widely used in quantum chemical calculations to describe the electronic structure of molecules. These basis sets provide an effective balance between computational efficiency and accuracy for molecules containing H-Ca. In Qbics, the following Pople basis sets are available: .. list-table:: :header-rows: 1 * - Basis set - Applied to * - ``3-21G`` - H-Xe, Cs * - ``4-31G`` - H-He, B-Ne, P-Cl * - ``6-31G`` - H-Zn * - ``6-31G(d)``, ``6-31G(d,p)`` - H-Kr * - ``6-31G(2df,p)``, ``6-31G(3df,3pd)`` - H-Ar * - ``6-31+G``, ``6-31+G(d)``, ``6-31+G(d,p)`` - H-Ar * - ``6-31++G``, ``6-31++G(d)``, ``6-31++G(d,p)`` - H-Ar * - ``6-311G``, ``6-311G(d)``, ``6-311G(d,p)`` - H-Ar, K-Ca, Ga-Kr, I * - ``6-311G(2df,2pd)`` - H-Ne, K-Ca * - ``6-311+G``, ``6-311+G(d)``, ``6-311+G(d,p)``, ``6-311+G(2d,p)`` - H-Ar, K-Ca * - ``6-311++G``, ``6-311++G(d)``, ``6-311++G(d,p)``, ``6-311++G(2d,2p)`` - H, Li-Ar, K-Ca * - ``6-311++G(3df,3pd)`` - H, Li-Ar Here: - ``(d)``: Adds 1 set of *d* functions on heavy atoms. - ``(d,p)``: Adds 1 set of *d* functions on heavy atoms and 1 set of *p* functions on hydrogens. - ``+``: Adds *s* and *p* diffuse functions on heavy atoms. - ``++``: Adds *s* and *p* diffuse functions on heavy atoms and *s* diffuse functions on hydrogens. - ``(2df,p)``: Adds 2 sets of *d* functions and 1 set of *f* functions on heavy atoms, and 2 sets of *p* functions on hydrogens. STO-nG Basis Sets ^^^^^^^^^^^^^^^^^^^^^^ In STO-nG basis sets, each atomic orbital is described by a single-Zeta basis set, where *n* Gaussian functions are used to approximate a Slater orbital. This design provides a compact and efficient representation of atomic wavefunctions. In Qbics, the following STO-nG basis sets are available: .. list-table:: :header-rows: 1 * - Basis set - Applied to * - ``sto-2g``, ``sto-3g``, ``sto-4g``, ``sto-5g``, ``sto-6g`` - H-Xe Los Alamos National Laboratory Pseudopotentials ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Los Alamos National Laboratory (LANL) basis sets are tailored for simplifying quantum chemistry calculations involving heavy elements. For all **elements ≥ Na,** pseudopotentials are used. .. attention:: These basis sets for elements ≥ Na must be used together with corresponding ``lanl-ECP`` pseudopotentials! See :ref:`example` below. In Qbics, the following LANL basis sets are available, listed below: .. list-table:: :header-rows: 1 * - Basis set - Applied to * - ``LANL2DZ`` - H, Li-Xe, Cs-Bi, La, U-Pu * - ``LANL2DZdp`` - H, C-F, Si-Cl, Ge-Br, Sn-I, Pb-Bi * - ``LANL08`` - Na-Xe, Cs-Bi, La * - ``LANL08+`` - Sc-Zn * - ``LANL08(d)`` - Si-Cl, Ge-Br, Sn-I, Pb-Bi * - ``LANL08(f)`` - Sc-Cu, Y-Ag, Hf-Au, La * - ``LANL2TZ`` - Sc-Zn, Y-Cd, Hf-Hg, La * - ``LANL2TZ+`` - Sc-Zn Here: - ``+``: Adds *d* diffuse functions. - ``d`` or ``f``: Adds *d* or *f* polarization functions. .. _example: Input Examples ------------------------- Some examples are also given in :doc:`pseudopotential`. Example: CuH with cc-pvDZ and cc-pvDZ-PP ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Below we show a calculation for CuH with all-electron correlation-consistent basis set and correlation-consistent basis set with pseudopotential. The first is an all-electron one: .. code-block:: bash :linenos: :caption: basis-1.inp # All electrons for CuH. basis cc-pvdz end mol Cu -0.00000000 -0.00000000 -0.23939021 H 0.00000000 0.00000000 1.23939021 end task opt b3lyp end We can see output: .. code-block:: bash :linenos: :caption: basis-1.out SCF Structure: # of electrons: 30 # of alpha electrons: 15 # of beta electrons: 15 The number of electrons is 30. The optimized structure has a bond length of 1.48 Angstrom. Now we use pseudopotential: .. code-block:: bash :linenos: :caption: basis-2.inp # Pseudopotentials for Cu, all-electrons for H. basis element Cu cc-pvdz-pp H cc-pvdz end pseudopotential cc-ecp end mol Cu -0.00000000 -0.00000000 -0.23939021 H 0.00000000 0.00000000 1.23939021 end task opt b3lyp end We can see output: .. code-block:: bash :linenos: :caption: basis-2.out SCF Structure: # of electrons: 20 # of alpha electrons: 10 # of beta electrons: 10 The number of electrons is 20, 10 electrons of Cu (Ne core) were replaced by pseudopotential. The optimized structure has a bond length of 1.46 Angstrom. Example: AuH with Karlsruhe Basis Set ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Calculate AuH with Karlsruhe basis set: .. code-block:: bash :linenos: :caption: basis-3.inp basis def2-TZVP end pseudopotential def2-ecp # If there are elements >= Rb, this must be used! end mol Au 0. 0. 0. H 0. 0. 1.5 end task opt b3lyp end Example: AgI with LANL Basis Set ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Optimize the structure of AgI with LANL basis set: .. code-block:: bash :linenos: :caption: basis-4.inp basis lanl2dz end pseudopotential lanl-ecp # For LANL basis set, this should always be set. end mol Ag 0. 0. 0. I 0. 0. 1.5 end task opt b3lyp end See the output: .. code-block:: bash :linenos: :caption: basis-4.out SCF Structure: # of electrons: 26 # of alpha electrons: 13 # of beta electrons: 13 The number of electrons is 26, so 74 electrons were replaced by pseudopotential. The optimized structure has a bond length of 2.65 Angstrom. .. tip:: All input files can be downloaded: :download:`Files `. basinfo ============== .. contents:: :local: This keyword defines the implementation details of basis functions. Options ------------ .. option:: angular_type .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``Cartesian``. Will use Cartesian basis sets, i.e., 6\ *d*/10\ *f*/15\ *g*. * - - ``spherical``. Will use the spherical basis sets, i.e., 5\ *d*/7\ *f*/9\ *g*. * - Default - ``spherical`` Determine whether to use spherical or Cartesian GTO basis set. Usually, there is **NO** need to use Cartesian GTO basis sets except for test purpose. .. option:: linear_dependence .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-8`` Assign the threshold that admits the linear dependence of the basis set. It should be a positive real number. When linear dependence is detected, Qbics will stop the calculation and raises an error. Linear dependence occurs when: #. There are identical basis functions for the same nuclear; #. Two nuclei of the same element are too close; #. There are many diffuse basis functions for a large molecule. .. option:: ghost .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Atom range * - Default - None Assigning "ghost atoms" means that those atoms defined in ``mol ... end`` have basis functions, but nuclear and electrons disappear. This is often used for some special purposes, like basis set superposition error (BSSE) calculations, although Qbics can automatically do this. Theoretical Background ------------------------- Angular Type of Basis Functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The analyitcal expression of Gaussian basis function is: .. math:: \chi(\mathbf{r}) = A_{L}(\mathbf{r})\sum_{k=1}^{K} C_k e^{-\alpha_k r_{A}^2} Here, :math:`A_{L}(\mathbf{r})` is the angular part with angular momentum quantum number :math:`L`, :math:`K` is the contraction degree, :math:`\alpha_k` is the exponent, :math:`C_k` is the contraction coefficient, and :math:`\mathbf{A}` is the atom position. The angular part :math:`A_{L}(\mathbf{r})` has 2 forms: one is ``Cartesian``, of the form :math:`x_A^{l_x}y_A^{l_y}z_A^{l_z}`, and ``spherical``, of a real solid spherical harmonic function. The spherical basis sets are more efficient and compact for quantum chemical calculations. Ghost Atoms ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In quantum chemistry, ghost atoms are atoms that have basis functions but no nuclear and electrons. They are often used in basis set superposition error (BSSE) calculations, where the interaction between two molecules is calculated. The ghost atoms are used to remove the interaction between the basis functions of the two molecules. One can use ``ghost`` option to calculate BSSE manually, but this is unnecessary. Qbics can automatically handle this by :doc:`eda`. Input Examples -------------------- Example: GeH\ :sub:`3`\ F-NCH with Ghost Atoms ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the complex GeH\ :sub:`3`\ F-NCH, calculate the energy that HCN is the ghost molecule at B3LYP/def2-SVP level of theory: .. code-block:: bash :linenos: :caption: basinfo-1.inp basis def2-svp end basinfo ghost 6-8 # The indices of HCN. end scf charge 0 spin2p1 1 type R end mol Ge 0.00000000 0.00221863 -0.79935317 H 0.00000000 1.48645043 -0.40384625 H 1.28514604 -0.74161126 -0.40477816 H -1.28514603 -0.74161126 -0.40477816 F 0.00000000 0.00108752 -2.56116087 C 0.00000000 -0.00225138 3.35662076 H 0.00000000 -0.00220444 4.43604901 N 0.00000000 -0.00207825 2.20326200 end task energy b3lyp end The ``ghost`` keyword indicates that atom 6,7,8, i.e., C,H,N are ghost ones. .. figure:: /_images/basinfo-1.jpg In the output, you can see: .. code-block:: bash :linenos: :caption: basinfo-1.out # of ghost atoms: 3 Indices: 6 7 8 Sum of ghost atom electrons: 14 ... SCF Structure: # of electrons: 44 # of alpha electrons: 22 # of beta electrons: 22 2S+1: 1 The ghost atoms are listed. Also, the number of electrons are only ``44``, which is exactly the number of electrons for GeH\ :sub:`3`\ F only. .. tip:: All input files can be downloaded: :download:`Files `. charmm ====== .. contents:: :local: This keyword defines the implementation details of CHARMM force field. Options ------------ .. contents:: :local: .. option:: parameters .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - One or more file names * - Default - None Give the CHARMM force field parameter file names (paths may be included). There is no default one so at least one file name must be given. There can be more than one files: .. code-block:: bash :linenos: charmm parameters par_all35_ethers.prm /home/zhang/userdef/par_all35_proteins.prm end Note that if the same term, say bond ``CT-CT``, appears in more than one parameter files, then the latter one will overwrite the previous ones. .. option:: topology .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A file name * - Default - None Give the topology file name of the molecule in PSF format (path may be included). .. option:: scaling14 .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.0`` Define the scaling factor for electrostatic interactions of 1-4 term. For most cases, it is set to ``1.0``. .. option:: rcutoff .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``15.0`` Define the distance in Angstrom to cutoff non-bonded interactions. When ``use_PBC`` is turned on, ``rcutoff`` should be smaller than the half of periodic box size to avoid self interactions. If ``rswitch`` is larger than ``rcutoff``, switching function will not be used and no cutoff is applied on long range forces. .. option:: rswitch .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``10.0`` Define the distance in Angstrom to activate switching function. If ``rswitch`` is larger than ``rcutoff``, switching function will not be used and no cutoff is applied on long range forces. .. option:: use_PBC Turn on periodic boundary condition for the system. If this option is not present, the system will be a non-periodic, gas phase one. .. option:: Lbox .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Three real numbers * - Default - ``0. 0. 0.`` When ``use_PBC`` is present, this option gives the lattice lengths along X, Y, and Z direction in Angstrom. .. code-block:: bash :linenos: charmm use_PBC Lbox 86 86 86 end This creates a simulation box of 86 Angstrom x 86 Angstrom x 86 Angstrom. .. option:: electrostatic .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``Cutoff`` Cutoff scheme for gas phase or periodic systems. * - - ``PME`` Particle mesh Ewald (PME) method. Only available for periodic systems. * - Default - ``Cutoff`` Assign the scheme to calculate electrostatic interaction. For gas phase, ``Cutoff`` is the only possible way. For MM calculations in periodic systems, both are available and it is recommended to use ``PME``. For QM/MM calculations in gas phase or periodic systems, ``Cutoff`` is currently the only possible way. .. option:: PMEk .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Three integers * - Default - ``64 64 64`` Assign the number of grids for PME long range force calculations. It is recommended that **the number should be chosen as an integer close to the lattice length while is a multiply of only 2,3 and/or 5.** For example, if ``Lbox`` is ``109. 109. 77``, then ``PMEk`` can be set to ``108 108 80``. Theoretical Background -------------------------------- CHARMM Force Field ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To do a CHARMM force field calculation, besides system coordinates, one needs to provide the system topology (by ``topology``) and force field parameter files (by ``parameters``). The CHARMM force field is decomposed into bonded interactions and nonbonded interactions. The bonded interactions include bond stretching, angle bending, dihedral angle rotation, and improper torsion. The nonbonded interactions include Lennard-Jones interactions and electrostatic interactions. They are all defined in ``topology`` and ``parameters``. For nonbonded interactions, one can calculate all pair interactions (by setting ``rswitch`` larger than ``rcutoff``) for non-periodic systems. However,sometimes it is computationally expensive to calculate all pair interactions. In this case (for both non-periodic and periodic systems), one can use a cutoff scheme to truncate the long-range interactions. In the **cutoff scheme** (``electrostatic cutoff``), the interactions are truncated at a certain distance ``rcutoff`` and a switching function is used to smoothly turn off the interactions at a distance of ``rswitch``. Such switching functions are different for Lennard-Jones and electrostatic interactions. The expressions are shown below: .. math:: S_{\text{LJ}}(r) = \begin{cases} 1 & \text{if } r \le r_\text{s} \\ \frac{\left(r_\text{c}^{2}-r^{2}\right)^2\left(r_\text{c}^{2}-r^{2}-3\left(r_\text{s}^{2}-r^{2}\right)\right)}{\left(r_\text{c}^{2}-r_\text{s}^{2}\right)^3} & \text{if } r_\text{s} \le r \le r_\text{c} \\ 0 & \text{if } r \ge r_\text{c} \\ \end{cases} .. math:: S_{\text{el}}(r) = \begin{cases} \left(1-\frac{r^2}{r_\text{c}^{2}}\right)^2 & \text{if } r \le r_\text{c}\\ 0 & \text{if } r \le r_\text{c} \\ \end{cases} The plots of these functions are shown below: .. figure:: /_images/charmm-2.png For periodic systems, one can use the **particle mesh Ewald (PME)** (``electrostatic pme``) method to calculate long-range electrostatic interactions. Also, ``rcutoff`` should be smaller than the half of periodic box size to avoid self interactions. PSF File Format ^^^^^^^^^^^^^^^^^^^^^^ A protein structure file (PSF) is a file format utilized to describe the topological information of biological macromolecules. PSF files primarily store information regarding atoms, bonds, angles, dihedral angles, and improper force terms. However, they do not contain atomic coordinates intrinsically. The PSF file consists of the following **sections** related to Qbics: #. **Atoms**: Lists the ID, residue information, atom type, charge, mass, etc. for each atom. #. **Bonds**: Defines the covalent bonding connections. Each line contains the IDs of pairs of atoms. #. **Angles**: Records bond angles formed by three atoms. Each row contains three sets of IDs. #. **Dihedrals**: Defines dihedral (torsion) angles formed by four atoms. Each row contains four atomic IDs. #. **Impropers**: Mechanical constraints used to maintain molecular planes (e.g., the coplanar structure of the benzene ring), four IDs per row. .. code-block:: bash :linenos: 6 !NTITLE REMARKS original generated structure x-plor psf file REMARKS 2 patches were applied to the molecule. REMARKS topology top_all27_prot_lipid.inp REMARKS segment U { first NTER; last CTER; auto angles dihedrals } REMARKS defaultpatch NTER U:1 REMARKS defaultpatch CTER U:76 1231 !NATOM 1 U 1 MET N NH3 -0.300000 14.0070 0 2 U 1 MET HT1 HC 0.330000 1.0080 0 3 U 1 MET HT2 HC 0.330000 1.0080 0 4 U 1 MET HT3 HC 0.330000 1.0080 0 5 U 1 MET CA CT1 0.210000 12.0110 0 6 U 1 MET HA HB 0.100000 1.0080 0 7 U 1 MET CB CT2 -0.180000 12.0110 0 Key Sections of this file: #. **Title Section**: Contains annotation information of the PSF file, such as generation method, topology file path, and so on. #. **Atoms Section**: - **Atom ID**: A unique number (e.g. ``1``, ``2``). - **Segment Name**: e.g. ``U`` for protein chain. - **Residue ID**: The number of the residue to which the atom belongs (e.g. ``1`` for the first residue). - **Residue Name**: e.g. ``MET`` for methionine. - **Atom Name**: e.g. ``N``, ``HT1``, ``HT2``, ``CA`` for nitrogen, hydrogen, carbon, etc. - **Atom Type**: The type used for force field calculations (e.g. ``NH3``, ``HC``, ``CT1``). - **Charge**: Partial charge of the atom (e.g. ``-0.300000``). - **Mass**: Mass of the atom (e.g. ``14.0070``). Then, the **Bonds**, **Angles**, **Dihedrals**, and **Impropers** sections follow, each containing the corresponding information. For example, the **Bonds** section contains the IDs of atoms that are bonded together: .. code-block:: bash :linenos: 7517 !NBOND: bonds 1 2 1 6 1 7 2 3 2 12 3 4 3 8 4 5 4 9 5 6 5 10 6 11 7 13 7 14 12 13 14 15 14 16 17 18 17 19 17 20 17 21 19 22 23 24 23 25 23 26 23 27 25 28 29 30 Here, we have bonds 1-2, 1-6, 1-7, 2-3, and so on. For others, the format is similar. CHARMM Parameter File Format ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ CHARMM force field files define the rules and parameters of interactions between atoms in a molecular system. It contains several **sections** related to Qbics: #. ``BONDS``: Describe the equilibrium lengths of covalent bonds and their corresponding force constants. #. ``ANGLES``: Provides the equilibrium value of the angle within the molecule and its force constant. #. ``DIHEDRALS``: Define the potential energy function and the corresponding parameters of the torsion angle. #. ``IMPROPERS``: Define the potential energy function and the corresponding parameters of the out-of-plane torsion angle. #. ``NONBONDED``: Define the Lennard-Jones potential. Other sections like ``NBFIX`` is **NOT** used by Qbics. .. hint:: CHARMM force field files can be obtained from: - https://mackerell.umaryland.edu/charmm_ff.shtml Input Examples -------------------- Example: Molecular Dynamics Simulation of Ubiquitin in Water ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Below we provide an example of a Qbics input file for simulations of a protein "ubiquitin" in water. Below shows the system. It contains 24696 atoms, a ubiquitin in a 64x64x64 water box: .. figure:: /_images/charmm-1.jpg This system was built by randomly placing water molecules around the ubiquitin. This Usually leads to a high-energy system, and molecular dyanmics starting with this can be highly unstable. So, we first optimize it: .. code-block:: bash :linenos: :caption: charmm-1a.inp charmm # Here: # toppar_water_ions.str: the parameter file for water and ions. # par_all36m_prot.prm: the parameter file for proteins. # Both are obtained from website: https://mackerell.umaryland.edu/charmm_ff.shtml. parameters toppar_water_ions.str par_all36m_prot.prm topology sys.psf scaling14 1.0 rcutoff 12.0 rswitch 10.0 use_PBC # Add this line to turn on PBC. Lbox 64 64 64 # Define the box size. electrostatic pme # Use PME for electrostatics. PMEk 64 64 64 end opt max_step 500 end mol sys.pdb end task opt charmm end After 500 steps, the energy decreased from ``34167803.38107745 kcal/mol`` to ``-82402.25839655 kcal/mol``. Using the optimized structure, we can now perform a NVT MD simulation: .. code-block:: bash :linenos: :caption: charmm-1b.inp charmm # Here: # toppar_water_ions.str: the parameter file for water and ions. # par_all36m_prot.prm: the parameter file for proteins. # Both are obtained from website: https://mackerell.umaryland.edu/charmm_ff.shtml. parameters toppar_water_ions.str par_all36m_prot.prm topology sys.psf scaling14 1.0 rcutoff 12.0 rswitch 10.0 use_PBC # Add this line to turn on PBC. Lbox 64 64 64 # Define the box size. electrostatic pme # Use PME for electrostatics. PMEk 64 64 64 end md type nvt dt 0.001 # 1 fs num_steps 1000 # 1 ps. Just for demonstration. output_freq 100 temp 298 end mol charmm-1a-opt.xyz # Use the optimized structure from the previous step. end task md charmm end .. tip:: All input files can be downloaded: :download:`Files `. eda ===== .. contents:: :local: This keyword defines how to perform an energy decomposition analysis (EDA) calculation. Options ------------ .. option:: type .. list-table:: :stub-columns: 1 * - Value - ``tso`` for block localized wavefunction energy decomposition analysis (TSO-EDA). * - - ``gks`` for generalized Kohn-Sham energy decomposition analysis (GKS-EDA). * - - ``mb_tso`` for many-body interaction TSO-EDA. * - - ``mb_gks`` for many-body interaction GKS-EDA. * - Default - None Both GKS-EDA and TSO-EDA is available for intermolecular interaction analysis. Furthermore, combined with the many-body expansion scheme, two new methods, i.e. many-body GKS-EDA and many-body TSO-EDA, are available for the analysis of many-body interactions. In Qbics, we **recommend to use TSO-EDA for EDA calculations.** .. option:: frag This option defines the fragments' partition of an system. The format is: ``frag num_electrons spin_multiplicity atom_range`` which is the same as the keyword ``frag`` in ``scfguess`` option. See :doc:`scfguess`. .. option:: nobsse Do not do the Boys and Bernardi's counterposise (CP) correction for basis set superposition error (BSSE). Qbics does BSSE correction by default. You can use this keword to avoid it when you don't need to consider BSSE. .. option:: tso_for_guess Do TSO calculation first for the initial guess of fragments' wavefunction, which is necessary for the case there are fragments with C∞ group symmetry such as an atom. For ``tso``` and ``mb_tso``, this is default. While for ``gks`` and ``mb_gks``, this is optional. .. option:: mb_level .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``2`` Truncation level for many-body interaction analysis, i.e. ``mb_gks`` and ``mb_tso`` calculations. The value should **NOT** be smaller than 2 and equal to or greater than the number of fragments. Usually, ``4`` is a good choice, if the number of fragments is larger than 4. Higher order terms are very small and can be ignored. .. warning:: For EDA tasks, you should add ``type U`` in the ``scf`` keyword to ensure the unrestricted calculation. Otherwish, the calculation will be failed. Theoretical Background ------------------------- .. hint:: If you use ``tso`` and ``mb_tso``, please cite the following reference: - `J. Chem. Theory Comput. 2023, 19, 1777 `_ - `Phys. Chem. Chem. Phys. 2024, 26, 17549 `_ If you use ``gks`` and ``mb_gks``, please cite the following reference: - `J. Phys. Chem. A 2014, 118, 2531 `_ - `WIREs Comput. Mol. Sci. 2020, 10, e1460 `_ - `Phys. Chem. Chem. Phys. 2024, 26, 17549 `_ TSO-EDA ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TSO-EDA is based on target state optimization self-consistent field method (`J. Chem. Theory Comput. 2023, 19, 1777 `_) and decomposes the total interaction energy into five terms, i.e. electrostatic, exchange, polarization, charge transfer, and dispersion energies. The sum of electrostattic and exchange energy is the Heitler-London term (`Phys. Chem. Chem. Phys. 2024, 26, 17549 `_): .. figure:: /_images/eda-2.jpg Here: - Ectrostatic term: Represents the semiclassical Coulombic interaction of charged particles from different monomers; - Exchange term: Represents quantum effect due to the antisymmetric character of the electronic wave function and the satisfaction of the Pauli exclusion principle; - Polarization term: Represents the polarization of the electron density of one monomer by the presence of other monomer; - Charge transfer term: Represents the charge transfer between monomers; - Dispersion term: Represents the dispersion interaction between monomers. The BSSE effect is included in charge transfer term. All above terms can be found in Qbics output. Many-Body TSO-EDA ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This method is developed in `Phys. Chem. Chem. Phys. 2024, 26, 17549 `_ and is used to analyze the many-body effects in a molecular cluster. The total interaction energy is decomposed into 2-body, 3-body, and higher-order terms, like this: .. math:: \Delta E^{\text{int}} = \frac{1}{2!} \sum_{I_1 \neq I_2}^{N} \Delta E_{I_1 I_2}^{(2)} +\frac{1}{3!} \sum_{I_1 \neq I_2 \neq I_3}^{N} \Delta E_{I_1 I_2 I_3}^{(3)} + \cdots + \frac{1}{n!} \sum_{I_1 \neq \cdots \neq I_n}^{N} \Delta E_{I_1 \cdots I_n}^{(n)} + \cdots + \Delta E_{I_1 \cdots I_N}^{(N)} \equiv \sum_{n=2}^{N} \Delta E^{(n)} The terms higher than :math:`\Delta E^{(2)}` is the many-body interaction term. Usually the most important one is the three-body effect :math:`\Delta E^{(3)}`, the effects of which can be decomposed into three ones: - :math:`\Delta E^{(3)} < 0`: Indicate a **cooperative effect** of the monomers in a cluster. The many-body interaction is stabilizing the cluster. This is often seen in hydrogen bonding clusters, like water clusters. - :math:`\Delta E^{(3)} > 0`: Indicate an **anti-cooperative effect** of the monomers in a cluster. The many-body interaction is destabilizing the cluster. This is often seen in a cluster of charged species, like ionic liquid clusters. Also see below. - :math:`\Delta E^{(3)} \approx 0`: Indicate a **non-cooperative effect** of the monomers in a cluster. There is little many-body interaction in the cluster. This is often seen in a cluster of molecules without charges or hydrogen bonds. Each order can be decomposed into electrostatic, exchange, polarization, charge transfer, and dispersion terms: .. math:: \Delta E_X^{(n)} = \Delta E_X^{(n)\text{-el}} + \Delta E_X^{(n)\text{-ex/xc}} + \Delta E_X^{(n)\text{-pl}} + \Delta E_X^{(n)\text{-ct}} + \Delta E_X^{(n)\text{-disp}} Usually, electrostatic and exchange terms are highly additive, while polarization and charge transfer terms are non-additive. The dispersion term is always additive. Input Examples -------------------- Example: EDA for GeH\ :sub:`3`\ F-NCH Complex by B3LYP-D3BJ/def2-SVP ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the complex GeH\ :sub:`3`\ F-NCH, we can do EDA calculation by the following input: .. code-block:: bash :linenos: :caption: eda-1.inp mol Ge 0.00000000 0.00221863 -0.79935317 H 0.00000000 1.48645043 -0.40384625 H 1.28514604 -0.74161126 -0.40477816 H -1.28514603 -0.74161126 -0.40477816 F 0.00000000 0.00108752 -2.56116087 C 0.00000000 -0.00225138 3.35662076 H 0.00000000 -0.00220444 4.43604901 N 0.00000000 -0.00207825 2.20326200 end basis def2-svp end scf charge 0 spin2p1 1 type U # For EDA calculations, this must be added explicitly. end grimmedisp type bj end eda type tso # You can also change it to: gks frag 0 1 1-5 # Define GeH3F. frag 0 1 6-8 # Define HCN. end task eda b3lyp end The atom indices are shown below: .. figure:: /_images/basinfo-1.jpg The results are: .. tabs:: .. tab:: TSO-EDA Results .. code-block:: bash :linenos: :caption: eda-tso.out WITH BSSE correction: Electrostatic interaction energy: -4.98 kcal/mol Exchange-correlation interaction energy: 4.22 kcal/mol Polarization interaction energy: -0.62 kcal/mol Charge transfer interaction energy: -1.31 kcal/mol Grimme's dispersion interaction: -1.58 kcal/mol ---------------------------------------------------------------- Total interaction energy: -4.27 kcal/mol .. tab:: GKS-EDA Results .. code-block:: bash :linenos: :caption: eda-gks.out WITH BSSE correction: Electrostatic interaction energy: -6.22 kcal/mol Exchange interaction energy: -9.64 kcal/mol Repulsion interaction energy: 15.94 kcal/mol Polarization interaction energy: -2.52 kcal/mol Correlation interaction energy: -0.24 kcal/mol Grimme's dispersion interaction: -1.58 kcal/mol ---------------------------------------------------------------- Total interaction energy: -4.27 kcal/mol We can see that the total interaction energies (with or without BSSE) are the same for both TSO-EDA and GKS-EDA methods, but components are different. As mentioned, Qbics recommends **TSO-EDA** for calculations. This complex is stabilized by ``Electrostatic interaction eneregy``, which is compatible with the chemical intuition that it is stabilized by sigma-hole. Example: MB-EDA for Molecular Cluster (NH\ :sub:`4`:sup:`+`)\ :sub:`2`\ (H\ :sub:`2`\ SO\ :sub:`4`)(HSO\ :sub:`4`:sup:`-`)\ :sub:`2` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The title cluster is composed of two NH\ :sub:`4`:sup:`+` cations, one H\ :sub:`2`\ SO\ :sub:`4` molecules, and two HSO\ :sub:`4`:sup:`-` anions. This cluster is used in the study of atmopheric chemistry.We can do MB-EDA calculation by the following input: .. code-block:: bash :linenos: :caption: eda-2.inp basis def2-svp end scf charge 0 # Total charge. spin2p1 1 type U end grimmedisp type bj end eda type mb_tso mb_level 4 frag +1 1 1-5 # NH4+ frag +1 1 6-10 # NH4+ frag 0 1 11-17 # H2SO4 frag -1 1 18-23 # HSO4- frag -1 1 24-29 # HSO4- end mol N 0.13124700 -1.86033100 -1.49054300 H -0.68471400 -1.96085700 -0.84840100 H 0.16284500 -2.63375000 -2.14527600 H -0.00155300 -0.97157900 -1.98611500 H 1.02982000 -1.79400200 -0.97437700 N -1.89606400 2.02266900 1.95536400 H -2.33766600 1.07911300 1.78190600 H -1.20423600 1.92734800 2.69193100 H -1.40455300 2.34660500 1.08417600 H -2.60508400 2.69280200 2.23215700 S 3.40269500 -0.73966700 0.43845300 O 4.56636300 -1.26003200 1.03924300 O 2.66268100 -1.55477200 -0.49575900 O 2.42657400 -0.30120000 1.56959800 O 3.78755300 0.58843400 -0.27018200 H 2.99297400 1.01172300 -0.68798600 H 1.56137200 -0.00498400 1.17228000 S -3.05756300 -0.82805000 0.17173500 O -2.21824200 -1.98280100 -0.09354400 O -3.00471800 -0.39464500 1.56194000 O -2.90973700 0.26502300 -0.77053900 O -4.55472700 -1.30387800 -0.08712900 H -4.73898300 -2.05912100 0.48328300 H -1.51856700 0.72871100 -1.53329100 S 0.24159900 1.52238500 -0.65825900 O -0.59336700 0.90131200 -1.85962900 O 1.55183900 1.72430300 -1.22252400 O -0.45708500 2.72297400 -0.23978600 O 0.20716100 0.49864900 0.39894800 end task eda b3lyp end The atom indices are shown below, which is used to define the fragments ``frag``: .. figure:: /_images/eda-1.jpg The results are: .. code-block:: bash :linenos: :caption: eda-2.out Table 5. Summary (kcal/mol). --------------------------------------------------------------------------------------------------------------------------------- Interactions delE_el delE_xc delE_pl delE_ct delE_bsse delE_disp delE_tot --------------------------------------------------------------------------------------------------------------------------------- SUM of 2-body -3.51853640E+02 1.04231044E+02 -5.50310217E+01 -9.70290703E+01 4.35696096E+01 -1.98079059E+01 -3.75920984E+02 SUM of 3-body 1.72107484E-09 1.45358519E+00 2.82254671E+01 2.81735373E+01 -1.24450163E+01 1.01531078E-02 4.54177264E+01 SUM of 4-body -4.14670076E-09 1.70212282E-02 -2.25462767E+00 -5.15894065E+00 1.89758583E+00 2.28017787E-05 -5.49893846E+00 Remain 7.51748885E-09 -8.58522126E-04 6.43113307E-02 4.30266615E-01 -1.22896862E-01 5.97720460E-07 3.70823167E-01 --------------------------------------------------------------------------------------------------------------------------------- SUM -3.51853640E+02 1.05700792E+02 -2.89958710E+01 -7.35842070E+01 3.28992822E+01 -1.97977294E+01 -3.35631373E+02 --------------------------------------------------------------------------------------------------------------------------------- We can see that the total interaction energy is -335.63 kcal/mol, which is decomposed into 2-body, 3-body, 4-body, and remaining terms. The 2-body term is the most important one (-375.92 kcal/mol), while the 3-body term is also significant, but **anti-cooperative** (destablizing the complex) (+45.42 kcal/mol). The 4-body term is small (-5.50 kcal/mol, slightly cooperative). The remaining term (sum of 5- and 6-body) is very small (+0.37 kcal/mol) and can be ignored. We can also see that the electrostatic and exchange energy are highly **additive**, while the polarization and charge-transfer energy are **non-additive**. For different kinds of clusters, the 3-body effects (many-body interactions) can be quite different, see `Phys. Chem. Chem. Phys. 2024, 26, 17549 `_ for more information. .. tip:: All input files can be downloaded: :download:`Files `. grimmedisp =========== .. contents:: :local: This keyword defines how to apply Grimme dispersion correction version 3, i.e. DFT-D3. Options ------------ .. hint:: **Always use DFT-D3 in your DFT calculations,** especially for weak interactions. Actually, it is recommended to use it in all cases. When there is no ``grimmedisp`` in the input file, no DFT-D3 will be applied. .. option:: type .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``bj`` Becke-Johnson DFT-D3 form * - - ``zero`` Zero-damp DFT-D3 form * - Default - None Define form of DFT-D3. There is no default value and you must assign ``bj`` or ``zero``. In most cases, ``bj`` is better, but for some functionals, like M06, M062X, and M06HF, only ``zero`` is available. .. option:: three_body Add three body corrections in DFT-D3. This is useful for large systems. .. option:: tz If triple zeta basis sets are used, this keyword may bring some improvement. Theoretical Background ------------------------ The DFT-D3 method is a dispersion correction to the DFT energy. It is based on the pair-wise summation of the damping functions. In modern DFT calculations, it is almost **always beneficial** to include DFT-D3 correction. So, it is recommended to use it in your **all** calculations. Input Examples ---------------- Examples: Weak Interactions in CH\ :sub:`4`-C\ :sub:`2`\ H\ :sub:`6`\ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This example shows the importance of the DFT-D3 correction in the calculation of weak interactions. For CH\ :sub:`4` and C\ :sub:`2`\ H\ :sub:`6`\ , both are nonpolar, and the interaction between them is very weak. To calculate the interactions, we simply use EDA method at B3LYP+D3BJ/def2-svp level of theory: .. code-block:: bash :linenos: :caption: disp-1.inp mol C -0.99275967 0.12491197 0.13574919 H -1.00662206 -0.95659619 0.18835421 H -0.34007185 0.51620582 0.90571860 H -0.63121516 0.43418579 -0.83650623 H -1.99486438 0.50482451 0.28603834 C 2.95955795 -0.58352084 -0.35430634 H 3.53618084 -1.49857448 -0.47007336 H 3.33520181 -0.05007297 0.51638813 C 3.07143559 0.28355041 -1.59942759 H 1.92316063 -0.85399112 -0.16804950 H 4.10875722 0.55492780 -1.78655076 H 2.69486480 -0.24574724 -2.47236370 H 2.49506428 1.19877654 -1.48025100 end basis def2-svp end scf charge 0 spin2p1 1 type U # For EDA, this must be set explicitly. end grimmedisp type bj end eda type tso frag 0 1 1-5 # Define CH4. frag 0 1 6-13 # Define C2H6. end task eda b3lyp end The output is: .. code-block:: bash :linenos: :caption: disp-1.out WITH BSSE correction: Electrostatic interaction energy: -0.13 kcal/mol Exchange-correlation interaction energy: 0.48 kcal/mol Polarization interaction energy: -0.00 kcal/mol Charge transfer interaction energy: -0.11 kcal/mol Grimme s dispersion interaction: -0.87 kcal/mol ---------------------------------------------------------------- Total interaction energy: -0.62 kcal/mol Thus, the interaction energy between CH\ :sub:`4` and C\ :sub:`2`\ H\ :sub:`6`\ is ``-0.62 kcal/mol``. The dispersion energy is ``-0.87 kcal/mol``, which is the most important part of the interaction energy. Without DFT-D3, the interaction energy would be ``-0.62``-``-0.87`` = ``+0.25`` kcal/mol! Therefore, the complex is unbound without DFT-D3! This leads to a **quantitative error** in the interaction energy. Therefore, **always use DFT-D3 in your DFT calculations.** .. tip:: All input files can be downloaded: :download:`Files `. md ====== .. contents:: :local: This keyword controls the molecular dynamics (MD) simulation details. Options ------------ .. option:: type .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``NVE`` Microcanonical ensemble, constant number of particles, volume, and energy * - - ``NVT`` Canonical ensemble, constant number of particles, volume, and temperature * - - ``fep-NVE`` Free energy perturbation calculation for microcanonical ensemble * - - ``fep-NVT`` Free energy perturbation calculation for canonical ensemble * - Default - ``NVE`` Define the MD simulation type. .. option:: dt .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``0.0005`` The time step in ps. For systems not containing hydrogen atoms, ``dt`` can be set to ``0.001`` ps. .. option:: num_steps .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``10`` The number of MD steps to be run. The total simulation time is ``dt``*\ ``num_steps`` ps. .. option:: output_freq .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``1`` The number of steps that MD information is output. The trajectory, velocity, and gradient will be output to disk. .. option:: temp .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``273.15`` Define the initial temperature for NVE simulation, and the targeted temperature for NVT simulation. .. option:: temp_nhc_length .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``5`` The length of Nose-Hoover chain to control the temperature. Usually an integer larger than 2 is enough. .. option:: temp_nhc_tau .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``0.5`` The time-constant of Nose-Hoover chain to control the temperature in ps. .. option:: vel_fn .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A file name * - Default - None If this is given, the initial velocities will be set from this XYZ file (in Angstrom/ps). Otherwise, velocities will be generated from Boltzmann distribution. For example: .. code-block:: bash :linenos: md vel_fn mol-vel.xyz end Initial velocities will be read from ``mol-vel.xyz``. .. option:: max_dr .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``5`` The maximum allowed atomic displacement per step in Angstrom. If an atom mover more than ``max_dr`` in a step, Qbics will stop the MD simulation since the system may crash due to the too fast motion. .. option:: plumed_fn .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A file name * - Default - None If this is given, Qbics will apply enhanced sampling algorithms of PLUMED defined in this file. For PLUMED input file grammar, please refer to its `PLUMED manual `_. Theoretical Background ----------------------- Molecular Dynamics Simulations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Molecular dynamics (MD) simulations are a computational method to study the time evolution of a system of interacting particles. In MD simulations, the forces between particles are calculated using a potential energy function, and the equations of motion are solved to obtain the trajectory of the particles. In Qbics, the equations of motions are solved using the velocity-Verlet algorithm, which is a symplectic integrator, meaning that it conserves the total energy of the system over long time. The forces can be evaluated on several levels of theory, including DFT, MM, NDDO, xTB, DFT/MM, NDDO/MM, and xTB/MM. During MD simulations, Qbics will output several files: - ``x-md-traj.xyz``: The trajectory of the system in XYZ format. - ``x-md-vel.xyz``: The velocity of the system in XYZ format. - ``x-md-grad.xyz``: The gradient of the system in XYZ format. Note that force is the negative of gradient. - ``x-md-log.txt``: The log file of the MD simulation, containing the step, time, energy components, temperature, and other information. - ``x-md-pressure.txt``: The pressures of the MD simulation, containing the step, time, cell volume, and pressure tensor. If the system is not periodic, this file will not be generated. If ``plumed_fn`` is given, Qbics will also output some data defined in this file. Before doing MD, it is strongly recommended to perform a **geometry optimization** to obtain a stable initial configuration. Each ensemble has its own conserved quantity. - For NVE, the total energy is conserved: .. math:: E = K + V Here :math:`E` is the total energy, :math:`K` is the kinetic energy, and :math:`V` is the potential energy. For example, if you do an NVE MD simulation, you can check the total energy in file ``x-md-log.txt``: .. code-block:: bash :linenos: # Time Total Kinetic Potential Temp Cost ps Hartree Hartree Hartree Kelvin second 0 0.00000 -34.44404963 0.02280104 -34.46685067 300.00000000 0.257 20 0.01000 -34.44402464 0.01224859 -34.45627323 161.15837759 0.260 40 0.02000 -34.44400898 0.01020550 -34.45421449 134.27682685 0.222 60 0.03000 -34.44401439 0.01628312 -34.46029751 214.24190576 0.220 80 0.04000 -34.44402295 0.02160569 -34.46562864 284.27246073 0.279 100 0.05000 -34.44403491 0.03125266 -34.47528758 411.20057981 0.248 120 0.06000 -34.44402767 0.02061378 -34.46464145 271.22164167 0.228 140 0.07000 -34.44403668 0.02599444 -34.47003112 342.01656058 0.226 160 0.08000 -34.44402275 0.01897475 -34.46299751 249.65643218 0.224 - For NVT, the total "virtual" energy is conserved: .. math:: Q = K + V + \sum_{j=1}^{n_\text{NHC}} \frac{p_{\eta_j}^2}{2Q_j} + 3NkT\eta_1+kT \sum_{j=2}^{n_\text{NHC}}\eta_j Here :math:`n_\text{NHC}` is the Nose-Hoover chain length ``nhc_temp_length``, :math:`k` is the Boltzmann constant, :math:`T` is the temperature, :math:`\eta_j` and :math:`p_{\eta_j}` are the thermostat variables ("position" and "momentum"), and :math:`Q_j` is the thermostat mass (determined automatically by Qbics). For example, if you do an NVT MD simulation, you can check the ``ConstQ`` in file ``x-md-log.txt``: .. code-block:: bash :linenos: # Time Total Kinetic Potential Temp ConstQ Cost ps Hartree Hartree Hartree Kelvin Hartree second 0 0.00000 -34.44404963 0.02280104 -34.46685067 300.00000000 -34.44404963 0.000 20 0.01000 -34.44404123 0.01734433 -34.46138557 228.20455596 -34.44404256 0.293 40 0.02000 -34.44401539 0.01535660 -34.45937199 202.05137626 -34.44402161 0.230 60 0.03000 -34.44399789 0.01914301 -34.46314090 251.87027197 -34.44401529 0.213 80 0.04000 -34.44401533 0.03373382 -34.47774915 443.84591789 -34.44404524 0.303 100 0.05000 -34.44399074 0.01808475 -34.46207549 237.94640025 -34.44402711 0.222 120 0.06000 -34.44400165 0.03088255 -34.47488420 406.33083745 -34.44404511 0.218 140 0.07000 -34.44397432 0.01350937 -34.45748370 177.74683071 -34.44402030 0.327 160 0.08000 -34.44397272 0.01886731 -34.46284002 248.24278233 -34.44402353 0.222 180 0.09000 -34.44398418 0.03438731 -34.47837149 452.44411562 -34.44404296 0.225 In all cases, if the conserved quantity is not conserved, it means that the simulation is unstable. You may need: - Reduce the time step; - Do a geometry optimization to obtain a stable initial configuration; - Check if the potential energy function (quantum chemistry or force field parameters) is reasonable for your system. However, if ``plumed_fn`` is given, the conserved quantity may **NOT** be conserved, since the enhanced sampling algorithm may change the total energy. Nose-Hoover Chain algorithm ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Nose-Hoover chain (NHC) algorithm is a method to control the temperature in MD simulations. It is a generalization of the Nose-Hoover thermostat. The NHC is a series of thermostats that are connected to each other. The first thermostat controls the temperature of the system, and the subsequent thermostats control the temperature of the previous thermostat. The length of NHC is controlled by ``temp_nhc_length``. It should be larger than 2. If ``temp_nhc_length`` is set to ``1``, the system may not have a correct canonical distribution of velocities. Input Examples ------------------------- Example: Dynamic Effects for Carbocation Reaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Consider the following reaction: We want to know which group is more likely to migrate. Thus, we will do a 200 fs NVT MD simulation from the optimized structure of this carbocation to see what will happen. We will repeat the MD for 20 times using a shell script ``run.sh``. Here we use xTB for its speed. You can also use DFT if you have enough time. The input files are shown below: .. tabs:: .. tab:: md-1.inp .. code-block:: bash :linenos: :caption: md-1.inp mol C -0.90849 0.15356 -0.48118 C -0.18840 -0.79035 0.24223 C -0.79661 -1.92884 0.73482 C -2.15434 -2.10431 0.51590 C -2.88201 -1.15101 -0.17642 C -2.26735 -0.01407 -0.67971 H -0.22972 -2.66722 1.27887 H -2.64692 -2.98493 0.89733 H -3.93966 -1.29437 -0.33076 H -2.84788 0.72259 -1.21038 C 1.26411 -0.39651 0.38023 C -0.02903 1.30229 -0.93562 C 1.67317 -0.22550 1.85240 H 1.83624 -1.21169 2.27913 H 2.60525 0.32605 1.95669 H 0.88426 0.23363 2.45602 C -0.71228 2.64784 -0.65267 H -0.02047 3.48874 -0.70508 H -1.46470 2.82054 -1.41711 H -1.26222 2.63862 0.29289 C 1.31204 0.95650 -0.38570 H 2.18545 1.61818 -0.54700 C 2.13967 -1.43173 -0.30477 H 1.61435 -2.09539 -0.97595 C 3.43556 -1.57292 -0.10516 H 3.99105 -2.34108 -0.61298 H 4.00084 -0.94936 0.56664 C 0.38001 1.16971 -2.43593 C 1.13470 2.39986 -2.94354 C -0.80675 0.90408 -3.35872 H 1.04783 0.30446 -2.50076 H 1.96481 2.68234 -2.30028 H 1.54266 2.18219 -3.92659 H 0.47031 3.25225 -3.05019 H -1.34333 0.00481 -3.07250 H -1.49736 1.74331 -3.36799 H -0.44263 0.76667 -4.37283 end basis def2-svp end pseudopotential def2-ecp end scf charge +1 spin2p1 1 end xtb chrg +1 end md type nvt dt 0.001 # 0.001 ps = 1 fs num_steps 200 # 0.001*200 = 0.2 ps. In real simultion, you may need > 1 ps. temp 300 temp_nhc_length 5 temp_nhc_tau 0.5 output_freq 10 # 0.001*10 = 10 fs end task md xtb # md m06 # If you want to use DFT. end .. tab:: run.sh .. code-block:: bash :linenos: :caption: run.sh for i in {1..20}; do fn=md-1-$i cp md-1.inp ${fn}.inp qbics ${fn}.inp -n 8 > ${fn}.out done By ``bash run.sh``, you can run 20 MD simulations. The output files will be ``md-1-1-md-traj.xyz``, etc. We observe that both the isopropyl and vinyl group can migrate. For example: .. tabs:: .. tab:: Trajectory: Isopropyl Group Migration .. figure:: /_images/md-1-iso.gif .. tab:: Trajectory: Vinyl Group Migration .. figure:: /_images/md-1-vinyl.gif For this test, we can calculate the migration ratio of the isopropyl group to the vinyl group. For 20 trajectories, the result is: .. list-table:: :stub-columns: 1 :widths: 5 5 * - Isopropyl group migration - 7 * - Vinyl group migration - 7 * - Non-reactive - 2 * - Other reactions - 4 Of course, if the simulation time is longer, the non-reactive trajectory may become reactive. Anyway, the NVT MD result suggests that the migration ratio is about 1:1. Why do we do dynamics? Due to the **nonstatistical effect** of this reaction, we cannot predict the migration ratio by a static calculation. The dynamics result is more reliable. Please refer to the paper `J. Am. Chem. Soc. 2021, 143, 1088 `_ for more details. Example: Classical MD and Metadynamics ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For these, please refer to - :doc:`../tutorials/md` - :doc:`../tutorials/enhanced_md` .. tip:: All input files can be downloaded: :download:`Files `. mecp =============== .. contents:: :local: This keyword defines the arguments for searching minimum energy crossing point (MECP) and using diabatic MECP (dMECP) method to search transition states. For standard MECP search, you can use the ``mecp`` keyword in ``task...end`` block. For using dMECP to search transition states, you can use the ``dmecp`` keyword in ``task...end`` block. .. hint:: When using this keyword, in ``scf...end`` block, you must **ALWAYS** set ``type u``. Options ------------ .. option:: num_steps .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``200`` The maximum number of MECP search. .. option:: energy_cov .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-5`` The energy difference convergence threshold. When ``energy_cov``, ``grad_cov``, and ``dr_cov`` are all met, the MECP will be set to be converged. .. option:: grad_cov .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-3`` The gradient convergence threshold. When ``energy_cov``, ``grad_cov``, and ``dr_cov`` are all met, the MECP will be set to be converged. .. option:: dr_cov .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-3`` The displacement convergence threshold. When ``energy_cov``, ``grad_cov``, and ``dr_cov`` are all met, the MECP will be set to be converged. .. option:: orb1 This defines the electronic configuration of state 1. The format is: ``orb num_electrons spin_multiplicity alpha_MO_indices : beta_MO_indices`` There can be arbitrary number of ``orb1``, but all orbitals must be included once and only once. They are the same as ``orb`` in ``scfguess``. See :doc:`scfguess`. .. option:: orb2 This defines the electronic configuration of state 2. The format is: ``orb num_electrons spin_multiplicity alpha_MO_indices : beta_MO_indices`` There can be arbitrary number of ``orb2``, but all orbitals must be included once and only once. They are the same as ``orb`` in ``scfguess``. See :doc:`scfguess`. .. option:: frag1 This defines the fragmentation of state 1. The format is: ``frag num_electrons spin_multiplicity atom_range`` There can be arbitrary number of ``frag1``, but all atoms must be included once and only once. They are the same as ``frag`` in ``scfguess``. See :doc:`scfguess`. .. option:: frag2 This defines the fragmentation of state 1. The format is: ``frag num_electrons spin_multiplicity atom_range`` There can be arbitrary number of ``frag2``, but all atoms must be included once and only once. They are the same as ``frag`` in ``scfguess``. See :doc:`scfguess`. .. HINT:: When ``frag1/2`` and ``orb1/2`` are defined simultaneously, ``orb1/2`` will be considered in priority. Theoretical Background ----------------------- MECP Between Ground and Excited States ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The minimum energy crossing point (MECP) is a point where two potential energy surfaces (PES) of different electronic states cross each other. In the context of quantum chemistry, it is often used to describe the transition between a ground state and an excited state. The MECP can be found by optimizing the geometry of the system while constraining the energy difference between the two states to be zero. Diabatic MECP (dMECP) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Diabatic MECP (dMECP) is a method used to find the transition state for a AB+C=A+BC reaction. It uses the MECP search algorithm to find the minimum energy crossing point between the reactant and product diabatic states. Input Examples ------------------------- Example: MECP between the Singlet and Triplet States of C\ :sub:`6`\ H\ :sub:`5`:sup:`+` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this example, we will search the MECP between the singlet and triplet states of C\ :sub:`6`\ H\ :sub:`5`:sup:`+`. The input file is as follows: .. code-block:: bash :linenos: :caption: mecp-1.inp basis def2-svp end mol C 0.00000000 1.39661300 0.00000000 C 1.20950300 0.69830700 0.00000000 C 1.20950300 -0.69830700 0.00000000 C 0.00000000 -1.39661300 0.00000000 C -1.20950300 -0.69830700 0.00000000 C -1.20950300 0.69830700 0.00000000 H 2.15088200 1.24181200 0.00000000 H 2.15088200 -1.24181200 0.00000000 H 0.00000000 -2.48362500 0.00000000 H -2.15088200 -1.24181200 0.00000000 H -2.15088200 1.24181200 0.00000000 end mecp num_steps 200 # The number of search steps. energy_cov 1.E-5 # The energy difference convergence threshold. orb1 40 1 1-109 : 1-109 orb2 40 3 1-109 : 1-109 end scf type u charge +1 spin2p1 1 end task mecp b3lyp end In ``mecp...end`` block, we define the two electronic configurations of the singlet and triplet states using ``orb1`` and ``orb2``. The ``num_steps`` is set to ``200``, and the energy convergence threshold is set to ``1.E-5``. The format of ``orb1`` and ``orb2`` is the same as that in :doc:`scfguess`. For example, ``orb1 40 1 1-109 : 1-109`` means that the first state has 40 electrons, a spin multiplicity of 1, and the alpha and beta MOs are from indices 1 to 109. The same applies to ``orb2``. The singlet-triplet MECP is saved to ``mecp-1-mecp.xyz``. The optimized process is saved in ``mecp-1-mecp-traj.xyz``, which can be shown using `Qbics-MolStar `_: .. figure:: /_images/mecp-5.gif Example: Search Transition State of Iodine Atom Transfer Reaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. hint:: To use dMECP, you must use the ``dmecp`` keyword in ``task...end`` block instead of ``mecp``. The obtained structures using ``dmecp`` and ``mecp`` are different. **For transition states, we recommend to use ``dmecp`` instead of ``mecp`` to search the transition state.** In this section, we want to search the transition state of the following reaction: .. figure:: /_images/mecp-1.jpg This is a AB+C=A+BC type reaction. The largest advantage of dMECP algorithm is that the transition state is searched using energy coordinate instead of geometry coordinate, so it is not too sensitive to the initial guess. The input file is as follows. Note that for iodine, we have used pseudopotential with ``pseudopotential`` keyword, ``def2-ecp``. .. code-block:: bash :linenos: :caption: mecp-2a.inp basis def2-svp end pseudopotential def2-ecp end scf type u charge 0 spin2p1 2 end mol C -0.29500 -0.00002 -0.00017 C 1.10016 -0.00002 -0.00017 C 1.79770 1.20773 -0.00017 C 1.10004 2.41624 -0.00137 C -0.29478 2.41616 -0.00185 C -0.99238 1.20795 -0.00085 H -0.84476 -0.95234 0.00028 H 1.64967 -0.95253 0.00114 I 3.87770 1.20788 0.00103 H 1.65024 3.36838 -0.00143 H -0.84490 3.36844 -0.00280 H -2.09199 1.20814 -0.00103 Si 6.95770 1.20810 0.00280 C 7.59353 0.30695 1.56221 C 7.59533 0.30859 -1.55681 C 7.59423 3.00892 0.00412 H 7.23873 -0.70024 -1.55754 H 7.23913 0.81342 -2.43040 H 8.66533 0.30866 -1.55619 H 8.66353 0.30703 1.56282 H 7.23632 0.81087 2.43592 H 7.23694 -0.70188 1.56147 H 8.66423 3.00899 0.00563 H 7.23876 3.51349 -0.86992 H 7.23629 3.51309 0.87738 end mecp num_steps 200 energy_cov 1.E-5 frag1 0 1 1-12 frag1 0 2 13-25 frag2 0 2 1-8 10-12 frag2 0 1 9 13-25 end task dmecp b3lyp # Using dMECP method. end The structure given in ``mol...end`` is shown below: .. figure:: /_images/mecp-2.jpg We can see that the initial structure is a complex that two reactants are simply putting together. Now, according to the reactant and product species, we can define ``frag1`` and ``frag2`` in ``mecp...end`` option block. The definitions are shown below, which is self-explanatory and in line with chemical intuition: .. figure:: /_images/mecp-3.jpg In dMECP method, only a single geometry is needed. Of course, the closer it approaches the transition state, the better. You can also use ``mecp`` keyword instead of ``dmecp`` to to search the real MECP between the two diabatic states, the input files being as follows: .. code-block:: bash :linenos: :caption: mecp-2b.inp basis def2-svp end pseudopotential def2-ecp end scf type u charge 0 spin2p1 2 end mol C -0.29500 -0.00002 -0.00017 C 1.10016 -0.00002 -0.00017 C 1.79770 1.20773 -0.00017 C 1.10004 2.41624 -0.00137 C -0.29478 2.41616 -0.00185 C -0.99238 1.20795 -0.00085 H -0.84476 -0.95234 0.00028 H 1.64967 -0.95253 0.00114 I 3.87770 1.20788 0.00103 H 1.65024 3.36838 -0.00143 H -0.84490 3.36844 -0.00280 H -2.09199 1.20814 -0.00103 Si 6.95770 1.20810 0.00280 C 7.59353 0.30695 1.56221 C 7.59533 0.30859 -1.55681 C 7.59423 3.00892 0.00412 H 7.23873 -0.70024 -1.55754 H 7.23913 0.81342 -2.43040 H 8.66533 0.30866 -1.55619 H 8.66353 0.30703 1.56282 H 7.23632 0.81087 2.43592 H 7.23694 -0.70188 1.56147 H 8.66423 3.00899 0.00563 H 7.23876 3.51349 -0.86992 H 7.23629 3.51309 0.87738 end mecp num_steps 200 energy_cov 1.E-5 frag1 0 1 1-12 frag1 0 2 13-25 frag2 0 2 1-8 10-12 frag2 0 1 9 13-25 end task mecp b3lyp # Search MECP between the two diabatic states. end The initial and optimized structures ``mecp-2*.inp``, ``mecp-2a-mecp.xyz`` and ``mecp-2b-mecp.xyz`` are shown below: .. figure:: /_images/mecp-4.jpg Interestingly, both ``mecp-2a-mecp.xyz`` and ``mecp-2b-mecp.xyz`` have a single imaginary frequency, indicating that they are both close to transition states. However, the transition state obtained by ``dmecp`` is more stable than that obtained by ``mecp``. For ``mecp-2b-mecp.xyz``, we find that the energy difference between the reactant and product diabatic states is about ``0.000008 Hartree``, which is the definition of MECP. **For transition states, we recommend to use ``dmecp`` instead of ``mecp`` to search the transition state.** .. tip:: All input files can be downloaded: :download:`Files `. mol and mol2 ================= .. contents:: :local: The keyword ``mol`` gives the initial molecular coordinates. For some tasks like transition state search, another structure has to be given in option ``mol2``. Explicit XYZ Coordinates ------------------------- You can simply give XYZ coordinates in Angstrom: .. code-block:: bash :linenos: mol O 0.00000000000000 0.05011194954430 0.05011194954224 H 0.00000000000000 -0.06080277603381 1.01069082652926 H 0.00000000000000 1.01069082648951 -0.06080277607149 end XYZ File Name ------------------------- You can give the XYZ file name (path can be included if necessary): .. code-block:: bash :linenos: mol ../mols/water.xyz end PDB File Name ------------------------- You can give the PDB file name (path can be included if necessary): .. code-block:: bash :linenos: mol proteins/ala3.pdb end Theoretical Background ------------------------- XYZ File Format ^^^^^^^^^^^^^^^^^^^^^^ An XYZ file is a text format employed to depict the geometry of a molecule. Its structure is delineated as such: #. Number of atoms: The initial line consists of an integer representing the total number of atoms in the molecule. #. Comment line: The second line typically comprises a comment that can be utilized to provide information regarding the molecule. #. Each subsequent line contains the elemental symbol of an atom and its corresponding Cartesian coordinates (x, y, z), typically expressed in Angstroms. .. code-block:: bash :linenos: 3 water molecule O 0.000000 0.000000 0.116863 H 0.000000 0.764949 -0.467453 H 0.000000 -0.764949 -0.467453 PDB File Format ^^^^^^^^^^^^^^^^^^^^^^ The protein data bank (PDB) file format is a comprehensive textual format widely used to store three-dimensional structural information of biological macromolecules, such as proteins and nucleic acids. Each PDB file contains detailed data, including the molecule's name, source species, sequence, secondary structure, and crystallographic parameters. In Qbics, only **atomic records** is used, i.e., lines starting with ``ATOM`` and ``HETATM``. Each atomic record in a PDB file provides specific information about an atom: #. **Record Type**: Indicates the type of record, such as ``ATOM`` or ``HETATM``. #. **Atom Serial Number**: A unique identifier for each atom. #. **Atom Name**: The element symbol and possibly additional characters to distinguish atoms within the same residue. #. **Residue Name**: The name of the residue (e.g., ``ALA`` for alanine). #. **Residue Sequence Number**: The position of the residue in the sequence. #. **X, Y, Z Coordinates**: The atom's coordinates in Angstrom. #. **Occupancy**: The fraction of the molecule present at this position. This is a crystallographic parameter NOT used by Qbics. #. **Temperature Factor (B-factor)**: Indicates the atomic displacement or mobility. This is a crystallographic parameter NOT used by Qbics. #. **Element Symbol**: The chemical element symbol. .. code-block:: bash :linenos: ATOM 1 N SER 10 9.630 40.740 60.970 0.00 0.00 N ATOM 2 HT1 SER 10 9.940 40.000 61.630 0.00 0.00 H ATOM 3 HT2 SER 10 8.910 41.340 61.420 0.00 0.00 H ATOM 4 HT3 SER 10 10.450 41.360 60.880 0.00 0.00 H ATOM 5 CA SER 10 9.180 40.240 59.600 0.00 0.00 C ATOM 6 HA SER 10 9.510 39.210 59.580 0.00 0.00 H .. warning:: Some software generates a PDB file format **without** "Element Symbol" column. In this case, Qbics will guess the element symbol based on the "Atom Name" column. However, this is dangerous and should be avoided since "Atom Name" is in principle arbitrary and can be misleading. For example, ``CLA`` can mean either chlorine or carbon atom in different PDB files. Therefore, **it is recommended to always include the "Element Symbol" column in the PDB file for Qbics calculations.** Input Examples ------------------------- Example: Transition State Search Using mol and mol2 to Give Reactant and Product ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Search the transition state using NEB at xTB level of theory, with reactant and product structure giving in ``mol`` and ``mol2``, respectively: .. code-block:: bash :linenos: :caption: mol-1.inp opt type neb num_images 10 neb_k 0.01 end mol # N-C-H C 0. 0. 0.289 N 0. 0. -1.128 H 0. 0. 1.099 end mol2 # H-N-C C 0.403 -0.780 -0.690 N -0.021 0.041 0.036 H -0.382 0.739 0.654 end xtb chrg 0 end task opt xtb end In this file, strucutures defined in ``mol`` and ``mol2`` are shown below: .. figure:: /_images/mol-1.jpg .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: For detailed tutorials of MSDFT, please refer to the following ones: - :doc:`../tutorials/msdft1` - :doc:`../tutorials/msdft2` - :doc:`../tutorials/msdft3` - :doc:`../tutorials/msdft4` msdft ====== .. contents:: :local: This option defines the implementation details of multi-state density functional theory (MSDFT) for excited and diabaitc states. .. option:: offdiag_correlation .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``overlap_weighted`` Will use overlap weighted method * - - ``energy_weighted`` Will use energy weighted method * - - ``correlation_potential`` Will use correlation functional method, given by the ``xc_functional`` option * - Default - ``overlap_weighted`` Define the off-diagonal correlation method. .. option:: single_ex .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Single excitations to be considered * - Default - None This option indicates what single excitations are considered. The input format is: ``single_ex occupied_MO_incides : virtual_MO_indices`` For example, ``single_ex 1 5-6 9 : 10-13 15`` considers the following single excitations: - 1 → 10 - 1 → 11 - 1 → 13 - 1 → 15 - 5 → 10 - 5 → 11 - 5 → 13 - 5 → 15 - 6 → 10 - 6 → 11 - 6 → 13 - 6 → 15 - 9 → 10 - 9 → 11 - 9 → 13 - 9 → 15 .. option:: double_ex .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Double excitations to be considered * - Default - None This option indicates what double excitations are considered. The input format is: ``double_ex occupied_MO_incides : virtual_MO_indices`` For example, ``double_ex 1 5-6 9 : 10-13 15`` considers the following double excitations: - 1 → 10 - 1 → 11 - 1 → 13 - 1 → 15 - 5 → 10 - 5 → 11 - 5 → 13 - 5 → 15 - 6 → 10 - 6 → 11 - 6 → 13 - 6 → 15 - 9 → 10 - 9 → 11 - 9 → 13 - 9 → 15 Theoretical Background ------------------------- XXXXXX Input Examples -------------------- .. tip:: For detailed tutorials of MSDFT, please refer to the following ones: - :doc:`../tutorials/msdft1` - :doc:`../tutorials/msdft2` - :doc:`../tutorials/msdft3` - :doc:`../tutorials/msdft4` Example: Excited States of (E)-Dimethyldiazene (Automatically) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this example, we will calculate the ground state and 2 singlet excited states of (E)-Dimethyldiazene with MSDFT methods. We will use B3LYP/cc-pVTZ level of theory. .. tip:: Acutally, in Qbics, the calculation of excited states using MSDFT is close to (but **NOT** the same as) TSO+NOSI. See :doc:`scfguess` and :doc:`nosi` for details. The input file is: .. code-block:: bash :linenos: :caption: msdft-1.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U end mol N -0.11855722 0.06367877 -0.00010027 N 1.11855814 -0.06366086 -0.00010026 C 1.81864333 1.22402113 0.00009549 H 1.12816980 2.07452976 0.00011126 H 2.46787129 1.25512096 0.88302715 H 2.46820089 1.25538193 -0.88260363 C -0.81864582 -1.22402070 0.00009559 H -0.12816015 -2.07453667 0.00011125 H -1.46787530 -1.25512668 0.88303320 H -1.46820496 -1.25538766 -0.88260977 end msdft single_ex 15 16 : 17 end task msdft b3lyp end Here, ``single_ex 15 16 : 17`` indicates that 1 electron in the 15th or 16th MO is excited to the 17th MO, i.e.: - 15 → 17 - 16 → 17 In ``msdft...end``, there is no ``offdiag_correlation`` option. This means that the off-diagonal correlation will be calculated using the (default) overlap weighted method. After calculation, we will obtain the output file ``msdft-1.out`` and wavefunction files ``msdft-1-gs.mwfn``, ``msdft-1-15-to-17-se.mwfn``, ``msdft-1-16-to-17-se.mwfn``. etc. Their names are self-explaining. For example, ``msdft-1-15-to-17-se.mwfn`` is the wavefunction file for the single excitation from 15th to 17th MO. In the output file ``msdft-1.out``, we can find the following information: .. code-block:: bash :linenos: :caption: msdft-1.out Read non-orthogonal determinants: 0 msdft-1-gs.mwfn 1 msdft-1-15-to-17-se.mwfn Spin flipped: msdft-1-15-to-17-se.mwfn 2 msdft-1-16-to-17-se.mwfn Spin flipped: msdft-1-16-to-17-se.mwfn ---- NOSI Overlap Matrix ---- ============================= 0 1 2 3 4 0 1.00000000 0.00000000 0.00004807 0.00000000 0.00000778 1 0.00000000 1.00000000 0.00000000 0.00000000 0.00000000 2 0.00004807 0.00000000 1.00000000 0.00000000 0.00000000 3 0.00000000 0.00000000 0.00000000 1.00000000 0.00000000 4 0.00000778 0.00000000 0.00000000 0.00000000 1.00000000 ---- NO Hamiltonian Matrix Functional ---- ========================================== 0 1 2 3 4 0 -189.34737100 0.00000019 -0.00909719 -0.00000028 -0.00147274 1 0.00000019 -189.11479500 0.09271220 -0.00000307 -0.00000741 2 -0.00909719 0.09271220 -189.11479500 -0.00000741 -0.00000307 3 -0.00000028 -0.00000307 -0.00000741 -189.24112500 0.02098466 4 -0.00147274 -0.00000741 -0.00000307 0.02098466 -189.24112500 ---- NOSI Coefficients Matrix (column vectors are eigenvectors) ---- ==================================================================== 0 1 2 3 4 0 -1.00000000 -0.00000085 -0.00000551 -0.00001218 -0.00002378 1 -0.00000820 0.00005595 0.00003731 -0.70710678 0.70710678 2 0.00002264 -0.00005595 0.00003731 0.70710678 0.70710678 3 -0.00000330 -0.70710678 0.70710678 -0.00005595 -0.00003731 4 0.00000328 0.70710678 0.70710678 0.00005595 -0.00003731 ---- Singlet and Triplet Excitation Energies ---- ================================================= Eigenstate 0: -189.34737100 Hartree; Excitation energy: 0.00000000 eV Eigenstate 1: -189.26210966 Hartree; Excitation energy: 2.32008047 eV Eigenstate 2: -189.22014034 Hartree; Excitation energy: 3.46212432 eV Eigenstate 3: -189.20750727 Hartree; Excitation energy: 3.80588786 eV Eigenstate 4: -189.02208273 Hartree; Excitation energy: 8.85154931 eV ---- Singlet State Weights ---- =============================== 0 1 2 3 4 0 1.00000000 -0.00000000 0.00000000 -0.00000000 -0.00000000 1 0.00000000 0.00000000 0.00000000 0.50000000 0.50000000 2 -0.00000000 0.00000000 0.00000000 0.50000000 0.50000000 3 0.00000000 0.50000000 0.50000000 0.00000000 0.00000000 4 -0.00000000 0.50000000 0.50000000 0.00000000 0.00000000 ---- NOSI Results ---- ====================== State NOSI Energies Excited Energy Osc. Str. DX DY DZ (Hartree) (eV) (a.u.) (a.u.) (a.u.) 0 -189.34737100 0.00000000 0.00000000 42.82334 0.00028 0.00212 1 -189.26210966 2.31996110 0.00000000 0.00000 -0.00000 -0.00001 2 -189.22014034 3.46194620 0.00000000 -0.00000 0.00005 0.00001 3 -189.20750727 3.80569205 0.00000000 -0.00000 -0.00000 -0.00000 4 -189.02208273 8.85109391 0.94030373 2.85146 0.75306 0.00000 In ``Read non-orthogonal determinants:``, the determinants are shown: - :math:`\phi_0` msdft-1-gs.mwfn - :math:`\phi_1` msdft-1-15-to-17-se.mwfn - :math:`\phi_2` msdft-1-15-to-17-se.mwfn (spin flipped) - :math:`\phi_3` msdft-1-16-to-17-se.mwfn - :math:`\phi_4` msdft-1-16-to-17-se.mwfn (spin flipped) In ``NOSI Overlap Matrix``, the matrix elements :math:`\left\langle\phi_i\middle|\phi_j\right\rangle` are calculated. In ``NO Hamiltonian Matrix Functional``, the matrix elements :math:`\left\langle\phi_i\left|\hat{H}\right|\phi_j\right\rangle` are calculated. In ``NOSI Coefficients Matrix``, the column vectors are eigenvectors of the NOSI Hamiltonian matrix. For example, in column ``1``, we have: .. math:: \left|\psi_1\right\rangle = -0.00000085 \left|\phi_0\right\rangle + 0.00005595 \left|\phi_1\right\rangle -0.00005595 \left|\phi_2\right\rangle - 0.70710678\left|\phi_3\right\rangle + 0.70710678 \left|\phi_4\right\rangle When a determinant and its spin flipped counterpart are combined with out-of-phases (``-0.70710678`` and ``-0.70710678``), this is a **triplet** state. When a determinant and its spin flipped counterpart are combined with in-phases (``0.70710678`` and ``0.70710678``), this is a **singlet** state. The excited energies are shown in ``NOSI Results``. A CI coefficient file and a spectrum file are generated. For example, ``msdft-1-ci.txt`` and ``msdft-1-spectrum.txt``. You can see that the energies are slightly different from the results obtained by TSO+NOSI in :doc:`nosi`. This is because the MSDFT method applied triplet correction, which should be more accurate. .. list-table:: * - State - MSDFT (eV) - TSO+NOSI (eV) (see :doc:`nosi`) * - S\ :sub:`0` - 0.00000000 - 0.00000000 * - T\ :sub:`1` - 2.31996110 - 2.32371833 * - S\ :sub:`1` - 3.46194620 - 3.45818894 * - T\ :sub:`2` - 3.80569205 - 3.82320418 * - S\ :sub:`2` - 8.85109391 - 8.83363623 Example: N and O K-Edge XAS of N\ :sub:`2`\ O ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this example, we will calculate the K-edge XAS of N\ :sub:`2`\ O with MSDFT methods. We will use B3LYP/cc-pCVTZ level of theory. Here, "K-edge" means that the excitation is from 1s orbital to virtual ones. We use aug-cc-pCVTZ instead of aug-cc-pVTZ because the "pCVTZ" is highly optimized for core orbitals. First, we do a standard SCF calculation for N\ :sub:`2`O to see orbitals. The input file is: .. code-block:: bash :linenos: :caption: n2o-gs.inp basis aug-cc-pCVTZ end scf charge 0 spin2p1 1 type U end mol N 0. 0. -0.14168067 N 0. 0. 0.97956073 O 0. 0. 2.16211994 end task energy b3lyp end Now we can visualize the molecular orbitals. Open `Qbics-MolStar `_, and drag ``n2o-gs.mwfn`` into explorer, and it will be automatically loaded. Right-click :guilabel:`n2o-gs.mwfn` and select :guilabel:`View Molecular Orbitals`. Click the MOs and see below: .. figure:: /_images/msdft-1.jpg Obviously, the MO 1 is the 1s orbitals for oxygen, and the MO 2,3 are the 1s orbitals for nitrogen. The N and O K-edge XAS are quiet separated, so it is better (but not necessary) to calculate them separately with MSDFT methods. The input files for O and N K-edge XAS are: .. tabs:: .. tab:: msdft-2-O.inp .. code-block:: bash :linenos: :caption: msdft-2-O.inp basis aug-cc-pCVTZ end scf charge 0 spin2p1 1 type U end mol N 0. 0. -0.14168067 N 0. 0. 0.97956073 O 0. 0. 2.16211994 end msdft single_ex 1 : 12-18 end task msdft b3lyp end .. tab:: msdft-2-N.inp .. code-block:: bash :linenos: :caption: msdft-2-N.inp basis aug-cc-pCVTZ end scf charge 0 spin2p1 1 type U end mol N 0. 0. -0.14168067 N 0. 0. 0.97956073 O 0. 0. 2.16211994 end msdft single_ex 2 3 : 12-18 end task msdft b3lyp end Here, ``single_ex 1 : 12-18`` indicates that 1 electron in the 1st MO is excited to the 12th to 18th MO; ``single_ex 2 3 : 12-18`` indicates that 1 electron in the 2nd and 3rd MO is excited to the 12th to 18th MO. You can excite them to higher virtual MOs to get more accurate results. After calculation, we will obtain the output files ``msdft-2-O.out`` and ``msdft-2-N.out``. The excited state MWFN files are also available. There are also files for spertrum plotting: ``msdft-2-O-spectrum.txt`` and ``msdft-2-N-spectrum.txt``. For example, in ``msdft-2-N.out``, we can find the following information: .. code-block:: bash :linenos: :caption: msdft-2-N.out ---- NOSI Results ---- ====================== State NOSI Energies Excited Energy Osc. Str. DX DY DZ (Hartree) (eV) (a.u.) (a.u.) (a.u.) 0 -184.74191466 0.00000000 0.00000000 -0.00000 0.00001 62.02962 1 -170.03989460 400.04196592 0.00000000 0.00000 -0.00000 0.00000 2 -170.03502387 400.17449843 0.00000000 -0.00000 0.00000 -0.00000 3 -170.01752034 400.65076950 0.05261600 0.06433 0.08133 0.00000 4 -170.01547342 400.70646604 0.05144446 0.08040 -0.06362 -0.00000 5 -169.92447560 403.18251673 0.00000000 0.00000 -0.00000 0.00000 6 -169.91893969 403.33314900 0.00000000 0.00000 -0.00000 -0.00000 7 -169.91191435 403.52430858 0.00000000 -0.00000 0.00000 0.00000 8 -169.91076621 403.55554928 0.00534389 0.00000 -0.00000 0.03293 9 -169.88759854 404.18594177 0.06488836 -0.07104 -0.08999 0.00000 10 -169.88267696 404.31985772 0.06490275 0.08998 -0.07104 0.00000 11 -169.83564482 405.59960229 0.00000000 -0.00000 -0.00000 0.00000 12 -169.82950253 405.76673395 0.00925187 -0.00000 0.00000 0.04321 13 -169.81735744 406.09720202 0.00000000 0.00000 0.00000 0.00000 14 -169.81567589 406.14295698 0.00498163 -0.02593 -0.01821 0.00000 15 -169.81376836 406.19486083 0.00000000 -0.00000 0.00000 -0.00000 16 -169.81204070 406.24187047 0.00494890 0.01812 -0.02586 0.00000 17 -169.80681991 406.38392818 0.00000000 -0.00000 -0.00000 0.00000 18 -169.79772608 406.63137137 0.01209756 0.00000 -0.00000 -0.04935 19 -169.74853637 407.96982327 0.00000000 -0.00000 0.00000 -0.00000 20 -169.74401565 408.09283219 0.00113590 0.00000 0.00000 0.01510 21 -169.67330415 410.01689210 0.00000000 0.00000 -0.00000 0.00000 22 -169.67060344 410.09037844 0.00107912 0.00000 -0.00000 -0.01468 23 -169.65887737 410.40944479 0.00000000 0.00000 -0.00000 0.00000 24 -169.63235011 411.13125137 0.00601950 0.00000 0.00000 -0.03462 25 -169.07874371 426.19488170 0.00004203 0.00000 -0.00000 -0.00284 26 -169.07628789 426.26170433 0.00000000 0.00000 0.00000 -0.00000 27 -166.93991246 484.39247991 0.00003223 -0.00000 -0.00000 0.00233 28 -166.93767426 484.45338124 0.00000000 0.00000 -0.00000 -0.00000 You can identify the states from output files. For example, the coefficients of state ``4`` are: .. code-block:: bash :linenos: :caption: msdft-2-N.out ---- NOSI Coefficients Matrix (column vectors are eigenvectors) ---- ==================================================================== 0 1 2 3 4 0 0.99999900 0.00000000 -0.00000000 0.00000000 -0.00000000 1 -0.00000000 -0.00573951 -0.00000102 0.00074472 -0.00000001 2 -0.00000000 0.00573951 0.00000102 0.00074472 -0.00000001 3 -0.00000000 0.00000132 0.00527620 -0.00000167 -0.00020742 4 -0.00000000 -0.00000132 -0.00527620 -0.00000167 -0.00020742 5 -0.00009224 -0.00000000 0.00000000 0.00000000 -0.00000000 6 -0.00009224 0.00000000 -0.00000000 0.00000000 -0.00000000 7 -0.00005050 0.00000004 -0.00000004 -0.00000003 0.00000003 8 -0.00005050 -0.00000004 0.00000004 -0.00000003 0.00000003 9 -0.01938433 0.00000002 0.00000006 0.00000027 0.00000011 10 -0.01938443 -0.00000002 -0.00000006 0.00000027 0.00000011 11 -0.01615554 -0.00000011 0.00000024 -0.00000053 0.00000224 12 -0.01615584 0.00000011 -0.00000024 -0.00000053 0.00000224 13 -0.00408296 0.00000017 -0.00000022 0.00000078 -0.00000210 14 -0.00408276 -0.00000017 0.00000022 0.00000078 -0.00000210 15 0.00000000 0.70440082 0.00016811 -0.70886826 0.00029439 16 0.00000000 -0.70440082 -0.00016811 -0.70886826 0.00029439 17 0.00000000 0.00007913 -0.70442320 0.00045204 0.70883620 18 0.00000000 -0.00007913 0.70442320 0.00045204 0.70883620 19 -0.00027387 0.00000004 -0.00000009 -0.00000007 0.00000003 20 -0.00027386 -0.00000004 0.00000009 -0.00000007 0.00000003 21 -0.00036762 0.00000357 -0.00000375 -0.00000369 0.00000380 22 -0.00036762 -0.00000357 0.00000376 -0.00000369 0.00000380 23 -0.00000001 -0.01231909 -0.00528893 -0.00894872 -0.00371633 24 -0.00000001 0.01231909 0.00528893 -0.00894872 -0.00371633 25 0.00000002 0.00424293 -0.01251586 0.00260869 -0.00878159 26 0.00000002 -0.00424293 0.01251586 0.00260869 -0.00878159 27 0.00040798 -0.00000375 0.00000392 0.00000362 -0.00000376 28 0.00040798 0.00000376 -0.00000392 0.00000362 -0.00000376 The largest coefficients for state ``4`` is :math:`0.70883620\phi_{17}+0.70883620\phi_{18}`, which is the combination of ``msdft-2-N-3-to-13-se.mwfn`` and its spin flipped one. So, this state is mainly the 3→13 single excitation, i.e. terminal-nitrogen :math:`1s\rightarrow\pi^*` excitation (see below for MO 13, which is a :math:`\pi^*` MO) .. figure:: /_images/msdft-2.jpg To plot the spectrum, you can use the script ``tools/plotspec.py`` provided by Qbics (or any tools you like). Assume you want to plot ```` First, copy this file to the same directory as the input file, and modify the following parameters: .. code-block:: python :linenos: :caption: plotspec.py if __name__ == "__main__": fn = "msdft-2-N-spectrum.txt" # Spectrum file name. eL_eV = 400 # Lower energy limit. eH_eV = 410 # Higher energy limit. sigma_eV = 0.2 # Sigma value. num_ps = 500 # Number of points. use_angle = False # Whether to use angle dependence. Here, we want to plot the spectrum from 400 (``eL_eV``) to 410 (``eH_eV``) eV, with a sigma value of 0.2 (``sigma_eV``) and 500 (``num_ps``) points. You can change these parameters to get the desired spectrum. .. tip:: Please cite this paper, if you use this script and formular in it: - `J. Phys. Chem. C 2022, 126, 8720 `_ The N and O K-edge XAS spectra as well as experimental data are shown below: .. figure:: /_images/msdft-3.jpg We can see that, MSDFT can give quite good results for N and O K-edge XAS! .. tip:: All input files can be downloaded: :download:`Files `. nddo ===== .. contents:: :local: This option controls how to perform an NDDO (like AM1, PM3, etc.) calculation. Options ------------ .. option:: charge .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``0`` Define the total charge of the system. .. option:: spin2p1 .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``1`` for even number of electrons * - - ``2`` for odd number of electrons Define the spin multiplicity of the system, i.e., :math:`2S+1`, where :math:`S` is the spin of the system. For example, to consider the singlet and triplet state, one should set :option:`spin2p1` to ``1`` and ``3``, respectively. .. option:: max_it .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A non-negative integer * - Default - ``150`` Define the maximum number of SCF iteration. .. option:: print_MO Print molecular orbital coefficients. Without this, only molecular orbital energies and occupancies are printed. .. option:: use_hcore Use the core Hamiltonian matrix as the initial guess. Without this, the superposition of atomic NDDO densities is used as the initial guess. .. option:: print_level .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``PrintNone`` for restricted SCF (alpha and beta orbitals are restricted to be identical) * - - ``PrintEssentials`` for unrestricted SCF (alpha and beta orbitals are not necessarily identical) * - - ``PrintDetails`` for unrestricted SCF (alpha and beta orbitals are not necessarily identical) * - Default - ``PrintEssentials`` The information printing level. .. option:: density_cov .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-9`` The density matrix convergence threshold for SCF calculations. Theoretical Background -------------------------------- The NDDO (Neglect of Diatomic Differential Overlap) method is a semi-empirical quantum chemistry method that simplifies the calculation of electronic structures in molecules. It is based on the Hartree-Fock theory but introduces several approximations to reduce computational cost while maintaining reasonable accuracy for many systems. The following NDDO-based methods are implemented in Qbics: .. list-table:: * - ``mndo`` * - ``am1`` * - ``am1d`` * - ``rm1`` * - ``pm3`` * - ``pm3d`` * - ``pm6`` * - ``pmo`` * - ``pmow`` Input Examples -------------------- Note that, in all examples below, you can change ``energy`` to ``opt`` to do geometry optimization, or ``md`` to do molecular dynamics. Example: NDDO Geometry Optimization of Congo Red Anion ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We perform an NDDO geometry optimization of the Congo Red anion, which is of **charge -2**. The input file is as follows: .. code-block:: :caption: nddo-1.inp :linenos: mol N -1.54332513 -2.09816265 1.04511234 C -1.24833878 -0.93106019 0.36508274 C -2.25957296 -0.07865002 -0.14856083 N -3.66148390 -0.29307361 -0.15493448 N -4.18863626 -1.27534731 0.37531946 C -5.60908641 -1.45451288 0.28158560 C -6.44457282 -0.83932131 -0.67188202 C -7.79728533 -1.15798249 -0.73630174 C -8.36065510 -2.08786360 0.14739783 C -9.77016879 -2.45880897 0.04894333 C -10.37218322 -2.63400200 -1.20423937 C -11.70230579 -3.02737161 -1.30728487 C -12.47656958 -3.25031163 -0.15160638 N -13.86557539 -3.62919999 -0.14487415 N -14.32966893 -4.17706047 -1.14625475 C -15.69877226 -4.57627884 -1.20899537 C -16.68973206 -4.15262107 -0.27475128 C -18.01024266 -4.49443901 -0.39532055 S -19.17268148 -3.86811281 0.81316397 O -19.75454266 -5.01617220 1.39840350 O -18.38630356 -3.10248890 1.70179250 O -20.10356966 -3.11120162 0.06462974 C -18.41112808 -5.32846881 -1.47222133 C -19.77910594 -5.71132399 -1.62198661 C -20.17834220 -6.53295026 -2.64390564 C -19.22910471 -7.02196171 -3.56998588 C -17.90832650 -6.66645352 -3.45632203 C -17.46190253 -5.80234089 -2.41478734 C -16.07656666 -5.41039373 -2.29229722 N -15.13888043 -5.91803387 -3.19440229 C -11.87474269 -3.05051931 1.11034028 C -10.54202081 -2.66675984 1.20101906 C -7.53790038 -2.67731355 1.11825020 C -6.18479683 -2.37215059 1.18838640 C -1.87591174 1.15335474 -0.77615212 C -0.57261374 1.52889060 -0.93591287 S -0.22263048 3.07410672 -1.76404123 C 0.45596204 0.67936168 -0.44539542 C 1.82678779 1.04190252 -0.60713363 C 2.83356234 0.24415341 -0.12687164 C 2.52009139 -0.95668533 0.54667961 C 1.20940505 -1.33293101 0.71264279 C 0.14025272 -0.53616115 0.21319920 H -2.46523916 -2.46286272 0.99215794 H -0.83173045 -2.78829762 1.08002006 H -6.03185765 -0.10143589 -1.37897310 H -8.43461236 -0.66688250 -1.48777738 H -9.78049223 -2.47062911 -2.11801307 H -12.14290958 -3.16255408 -2.30720734 H -16.38964262 -3.50879982 0.57744179 H -20.50886405 -5.32738427 -0.88397665 H -21.23309870 -6.82252491 -2.75059996 H -19.55988556 -7.69221994 -4.37548943 H -17.19714755 -7.08561026 -4.18243768 H -15.48438601 -6.05340540 -4.11792530 H -14.24364693 -5.48258085 -3.17857290 H -12.46209252 -3.20084844 2.03078572 H -10.08787943 -2.51709145 2.19260752 H -7.96893149 -3.40122514 1.82663096 H -5.56169201 -2.85401081 1.95772702 H -2.67308708 1.82553392 -1.15690810 H 2.05510061 1.99022309 -1.12996590 H 3.88606179 0.53247497 -0.25657336 H 3.33326449 -1.58194610 0.94036557 H 1.01518864 -2.26662032 1.25943530 O -1.49324251 3.61129258 -2.06889525 O 0.51932929 3.83612909 -0.83254053 O 0.53967816 2.71626705 -2.90040345 end nddo charge -2 spin2p1 1 end task opt am1 end You can also change ``am1`` to ``pm3``, ``pm6``, etc. to use other NDDO methods listed in the table above. The final geometry is shown below: .. figure:: /_images/nddo-1.jpg XXXX .. tip:: All input files can be downloaded: :download:`Files `. nosi ====== .. contents:: :local: This option defines the implementation details of nonothorgonal state interaction (NOSI) calculations for excited and diabaitc states. .. option:: offdiag_correlation .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``overlap_weighted`` Will use overlap weighted method * - - ``energy_weighted`` Will use energy weighted method * - - ``correlation_potential`` Will use correlation functional method, given by the ``xc_functional`` option * - Default - ``overlap_weighted`` Define the off-diagonal correlation method. .. option:: xc_functional .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A valid exchange-correlation functional name * - Default - None When ``offdiag_correlation`` is set to ``correlation_potential``, this option is required to specify the exchange-correlation functional to be used. All valid functional names are available in :doc:`scf`. .. option:: zero_threshold .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-6`` When the overlap of two orbitals is smaller than this value, they will be treated as zero .. warning:: Do not set a too large value (like ``1.E-4``). It may leads to wrong results. .. option:: files .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - One or more file names * - Default - None List the mwfn file names of the determinants to be read. .. option:: spin_filp .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - One or more file names * - Default - None List of determinants to perform spin flip (alpha to beta and beta to alpha). .. warning:: Only supported when the numbers of alpha electrons and beta electrons number equal. For example, in the following input: .. code-block:: bash :linenos: nosi files det1.mwfn det2.mwfn det3.mwfn spin_filp det2.mwfn det3.mwfn end In this case, **5** determinants will be used for NOSI calculations: - det1.mwfn - det2.mwfn - det3.mwfn - det2.mwfn (spin flipped) - det3.mwfn (spin flipped) Theoretical Background ------------------------- XXXXXX Input Examples -------------------- Example: Excited States of (E)-Dimethyldiazene (Manually) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this example, we will calculate the ground state and 2 singlet excited states of (E)-Dimethyldiazene with TSO-DFT methods. Then, we will calculate the NOSI for these 3 states. We will use B3LYP/cc-pVTZ level of theory. .. tip:: Acutally, in Qbics, the calculation of excited states using TSO+NOSI can be automatically done by a keyword ``msdft``, see :doc:`msdft` for details. In the following examples, we will calculate the ground and excited states of (E)-Dimethyldiazene using TSO-DFT methods, details of which can be found in :doc:`../tutorials/tso1` and :doc:`./scfguess`. - dma-s0.inp: Ground state; - dma-s1.inp: S\ :sub:`1` state, corresponding to HOMO (16) → LUMO (17) transition; - dma-s2.inp: S\ :sub:`2` state, corresponding to HOMO-1 (15) → LUMO (17) transition. .. tabs:: .. tab:: dma-s0.inp .. code-block:: bash :linenos: :caption: dma-s0.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U # For TSO-DFT, unrestricted SCF is preferred. end mol N -0.11855722 0.06367877 -0.00010027 N 1.11855814 -0.06366086 -0.00010026 C 1.81864333 1.22402113 0.00009549 H 1.12816980 2.07452976 0.00011126 H 2.46787129 1.25512096 0.88302715 H 2.46820089 1.25538193 -0.88260363 C -0.81864582 -1.22402070 0.00009559 H -0.12816015 -2.07453667 0.00011125 H -1.46787530 -1.25512668 0.88303320 H -1.46820496 -1.25538766 -0.88260977 end task energy b3lyp end .. tab:: dma-s1.inp .. code-block:: bash :linenos: :caption: dma-s1.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U no_scf TSO end # 16->17 scfguess type mwfn file dma-s0.mwfn orb 32 1 1-15 17-204 : 1-203 orb 0 1 16 : 204 end mol N -0.11855722 0.06367877 -0.00010027 N 1.11855814 -0.06366086 -0.00010026 C 1.81864333 1.22402113 0.00009549 H 1.12816980 2.07452976 0.00011126 H 2.46787129 1.25512096 0.88302715 H 2.46820089 1.25538193 -0.88260363 C -0.81864582 -1.22402070 0.00009559 H -0.12816015 -2.07453667 0.00011125 H -1.46787530 -1.25512668 0.88303320 H -1.46820496 -1.25538766 -0.88260977 end task energy b3lyp end .. tab:: dma-s2.inp .. code-block:: bash :linenos: :caption: dma-s2.inp basis cc-pvtz end scf charge 0 spin2p1 1 type U no_scf TSO end # 15->17 scfguess type mwfn file dma-s0.mwfn orb 32 1 1-14 16-204 : 1-203 orb 0 1 15 : 204 end mol N -0.11855722 0.06367877 -0.00010027 N 1.11855814 -0.06366086 -0.00010026 C 1.81864333 1.22402113 0.00009549 H 1.12816980 2.07452976 0.00011126 H 2.46787129 1.25512096 0.88302715 H 2.46820089 1.25538193 -0.88260363 C -0.81864582 -1.22402070 0.00009559 H -0.12816015 -2.07453667 0.00011125 H -1.46787530 -1.25512668 0.88303320 H -1.46820496 -1.25538766 -0.88260977 end task energy b3lyp end After calculation, we can collect the results: .. list-table:: * - State - Energy (Hartree) - Excited Energy (eV) * - S\ :sub:`0` - -189.34737058 - 0 * - S\ :sub:`1` - -189.24112513 - 2.89 * - S\ :sub:`2` - -189.11479416 - 6.33 Since TSO-DFT is a **single-determinant method,** S\ :sub:`1` and S\ :sub:`2` are NOT spin eigenfunctions. To be more accurate, we will use NOSI to get more accurate resutls, using the following 3 input files. They only differ in the ``offdiag_correlation`` option. .. tabs:: .. tab:: nosi-1a.inp .. code-block:: bash :linenos: :caption: nosi-1a.inp basis cc-pvtz end mol N -0.11855722 0.06367877 -0.00010027 N 1.11855814 -0.06366086 -0.00010026 C 1.81864333 1.22402113 0.00009549 H 1.12816980 2.07452976 0.00011126 H 2.46787129 1.25512096 0.88302715 H 2.46820089 1.25538193 -0.88260363 C -0.81864582 -1.22402070 0.00009559 H -0.12816015 -2.07453667 0.00011125 H -1.46787530 -1.25512668 0.88303320 H -1.46820496 -1.25538766 -0.88260977 end nosi offdiag_correlation overlap_weighted files dma-s0.mwfn dma-s1.mwfn dma-s2.mwfn spin_flip dma-s1.mwfn dma-s2.mwfn end task energy nosi end .. tab:: nosi-1b.inp .. code-block:: bash :linenos: :caption: nosi-1b.inp basis cc-pvtz end mol N -0.11855722 0.06367877 -0.00010027 N 1.11855814 -0.06366086 -0.00010026 C 1.81864333 1.22402113 0.00009549 H 1.12816980 2.07452976 0.00011126 H 2.46787129 1.25512096 0.88302715 H 2.46820089 1.25538193 -0.88260363 C -0.81864582 -1.22402070 0.00009559 H -0.12816015 -2.07453667 0.00011125 H -1.46787530 -1.25512668 0.88303320 H -1.46820496 -1.25538766 -0.88260977 end nosi offdiag_correlation energy_weighted files dma-s0.mwfn dma-s1.mwfn dma-s2.mwfn spin_flip dma-s1.mwfn dma-s2.mwfn end task energy nosi end .. tab:: nosi-1c.inp .. code-block:: bash :linenos: :caption: nosi-1c.inp basis cc-pvtz end mol N -0.11855722 0.06367877 -0.00010027 N 1.11855814 -0.06366086 -0.00010026 C 1.81864333 1.22402113 0.00009549 H 1.12816980 2.07452976 0.00011126 H 2.46787129 1.25512096 0.88302715 H 2.46820089 1.25538193 -0.88260363 C -0.81864582 -1.22402070 0.00009559 H -0.12816015 -2.07453667 0.00011125 H -1.46787530 -1.25512668 0.88303320 H -1.46820496 -1.25538766 -0.88260977 end nosi offdiag_correlation correlation_potential xc_functional b3lyp files dma-s0.mwfn dma-s1.mwfn dma-s2.mwfn spin_flip dma-s1.mwfn dma-s2.mwfn end task energy nosi end You should pay attention to the following points: - The basis sets and molecular structure should be the same as the ones used for TSO-DFT calculations. (You can copy the input files from the TSO-DFT calculations.) - If ``offdiag_correlation`` is set to ``correlation_potential``, the ``xc_functional`` option should be set as the same as the ones used for TSO-DFT calculations. In ``files`` option, you should list the mwfn file names of the determinants to be read. In ``spin_flip`` option, you should list the mwfn file names of the determinants that will be used for spin flip. For example, in the above input, ``dma-s1.mwfn`` and ``dma-s2.mwfn`` will be used for spin flip. In this case, the NOSI calculation will be performed for the following 5 determinants: - dma-s0.mwfn - dma-s1.mwfn - dma-s1.mwfn (spin flipped) - dma-s2.mwfn - dma-s2.mwfn (spin flipped) After calculation, we can collect the results. Let's see ``nosi-1a.out`` first: .. code-block:: bash :linenos: :caption: nosi-1a.out Read non-orthogonal determinants: 0 dma-s0.mwfn 1 dma-s1.mwfn Spin flipped: dma-s1.mwfn 2 dma-s2.mwfn Spin flipped: dma-s2.mwfn ... ---- NOSI Overlap Matrix ---- ============================= 0 1 2 3 4 0 1.00000000 0.00000000 -0.00001375 0.00000000 0.00004606 1 0.00000000 1.00000000 0.00000000 0.00000000 -0.00000000 2 -0.00001375 0.00000000 1.00000000 -0.00000000 0.00000000 3 0.00000000 0.00000000 -0.00000000 1.00000000 0.00000000 4 0.00004606 -0.00000000 0.00000000 0.00000000 1.00000000 ---- NO Hamiltonian Matrix Functional ---- ========================================== 0 1 2 3 4 0 -189.34737100 0.00000058 0.00260277 -0.00000192 -0.00871858 1 0.00000058 -189.24112500 0.02084657 0.00000885 0.00001057 2 0.00260277 0.02084657 -189.24112500 0.00001057 0.00000885 3 -0.00000192 0.00000885 0.00001057 -189.11479400 0.09206962 4 -0.00871858 0.00001057 0.00000885 0.09206962 -189.11479400 ---- NOSI Coefficients Matrix (column vectors are eigenvectors) ---- ==================================================================== 0 1 2 3 4 0 -1.00000000 0.00000101 -0.00001030 -0.00001197 0.00003201 1 0.00000657 -0.70710678 -0.70710678 0.00002152 -0.00006937 2 -0.00000575 0.70710678 -0.70710678 -0.00002152 -0.00006937 3 -0.00001417 -0.00002152 0.00006937 -0.70710678 -0.70710678 4 0.00001496 0.00002152 0.00006937 0.70710678 -0.70710678 ---- NOSI Results ---- ====================== State NOSI Energies Excited Energy Osc. Str. DX DY DZ (Hartree) (eV) (a.u.) (a.u.) (a.u.) 0 -189.34737100 0.00000000 0.00000000 42.82332 0.00029 0.00187 1 -189.26197158 2.32371833 0.00000000 0.00003 -0.00001 0.00001 2 -189.22027843 3.45818894 0.00000000 -0.00001 -0.00008 0.00000 3 -189.20686368 3.82320418 0.00000000 0.00000 0.00000 -0.00000 4 -189.02272432 8.83363623 0.93845302 2.85145 0.75310 -0.00001 In ``Read non-orthogonal determinants:``, the determinants are shown: - :math:`\phi_0` dma-s0.mwfn - :math:`\phi_1` dma-s1.mwfn - :math:`\phi_2` dma-s1.mwfn (spin flipped) - :math:`\phi_3` dma-s2.mwfn - :math:`\phi_4` dma-s2.mwfn (spin flipped) In ``NOSI Overlap Matrix``, the matrix elements :math:`\left\langle\phi_i\middle|\phi_j\right\rangle` are calculated. In ``NO Hamiltonian Matrix Functional``, the matrix elements :math:`\left\langle\phi_i\left|\hat{H}\right|\phi_j\right\rangle` are calculated. In ``NOSI Coefficients Matrix``, the column vectors are eigenvectors of the NOSI Hamiltonian matrix. For example, in column ``1``, we have: .. math:: \left|\psi_1\right\rangle = 0.00000101 \left|\phi_0\right\rangle -0.70710678 \left|\phi_1\right\rangle +0.70710678 \left|\phi_2\right\rangle - 0.00002152\left|\phi_3\right\rangle + 0.00002152 \left|\phi_4\right\rangle When a determinant and its spin flipped counterpart are combined with out-of-phases (``-0.70710678`` and ``-0.70710678``), this is a **triplet** state. When a determinant and its spin flipped counterpart are combined with in-phases (``0.70710678`` and ``0.70710678``), this is a **singlet** state. The excited energies are shown in ``NOSI Results``. Now, we can collect resutls from ``nosi-1a.out``, ``nosi-1b.out`` and ``nosi-1c.out`` together to get the final results: .. list-table:: * - State - TSO - Overlap Weighted - Energy Weighted - Correlation Potential * - - Excited Energy (eV) - NOSI Excited Energy (eV) - NOSI Excited Energy (eV) - NOSI Excited Energy (eV) * - S\ :sub:`0` - 0 - 0 - 0 - 0 * - T\ :sub:`1` - N/A - 2.32 - 2.32 - 2.35 * - S\ :sub:`1` - 2.89 - 3.46 - 3.46 - 3.43 * - T\ :sub:`2` - N/A - 3.82 - 3.80 - 5.25 * - S\ :sub:`2` - 6.33 - 8.83 - 8.85 - 7.40 We can see that, the NOSI results are generally improved upon TSO results. The results from overlap- and energy-weighted methods are very close to each other, while the results from correlation potential method are slightly different for high-lying states. For every calculation, a CI coefficient file and a spectrum file are generated. For example, ``nosi-1a-ci.txt`` and ``nosi-1a-spectrum.txt``. Example: Diabatic States of a Transition State ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In :doc:`./opt`, we have calculated the transition state of a S\ :sub:`N`\ 2 reaction. In the following examples, we will calculate the diabatic states of Cl-CH\ :sub:`3`-Cl using TSO-DFT methods, details of which can be found in :doc:`../tutorials/tso2` and :doc:`./scfguess`. - ``diab-1.inp``: Diabatic state of Cl···CH\ :sub:`3`-Cl (reactant complex); - ``diab-2.inp``: Diabatic state of Cl-CH\ :sub:`3`···Cl (product complex); .. tabs:: .. tab:: diab-1.inp .. code-block:: bash :linenos: :caption: diab-1.inp basis def2-svp end scf charge -1 spin2p1 1 type U no_scf tso end scfguess type fragden frag 0 1 1-5 frag -1 1 6 end mol C -2.28626983 4.81332375 -0.81110844 H -1.77793692 3.91128195 -1.11951067 H -1.75817077 5.56455137 -0.24234234 H -3.32378354 4.96301934 -1.07305839 Cl -1.62247473 5.87896571 -2.80504772 Cl -2.93223857 3.76141614 1.19669198 end task energy b3lyp end .. tab:: diab-2.inp .. code-block:: bash :linenos: :caption: diab-2.inp basis def2-svp end scf charge -1 spin2p1 1 type U no_scf tso end scfguess type fragden frag 0 1 1-4 6 frag -1 1 5 end mol C -2.28626983 4.81332375 -0.81110844 H -1.77793692 3.91128195 -1.11951067 H -1.75817077 5.56455137 -0.24234234 H -3.32378354 4.96301934 -1.07305839 Cl -1.62247473 5.87896571 -2.80504772 Cl -2.93223857 3.76141614 1.19669198 end task energy b3lyp end After calculation, we will obtain the reactant and product diabatic states: ``diab-1.mwfn`` and ``diab-2.mwfn``. Now, using NOSI, we can combine them to obtain 2 adiabatic states: .. code-block:: bash :linenos: :caption: nosi-2.inp basis def2-svp end mol C -2.28626983 4.81332375 -0.81110844 H -1.77793692 3.91128195 -1.11951067 H -1.75817077 5.56455137 -0.24234234 H -3.32378354 4.96301934 -1.07305839 Cl -1.62247473 5.87896571 -2.80504772 Cl -2.93223857 3.76141614 1.19669198 end nosi files diab-1.mwfn diab-2.mwfn end task energy nosi end In this case, we do not need assign ``spin_flip`` option since the reactant and product diabatic states are closed shell. In ``nosi...end``, there is no ``offdiag_correlation`` option. This means that the off-diagonal correlation will be calculated using the (default) overlap weighted method. After calculation, we will obtain the adiabatic states: ``nosi-2.out``: .. code-block:: bash :linenos: :caption: nosi-2.out ---- NOSI Overlap Matrix ---- ============================= 0 1 0 1.00000000 0.76098229 1 0.76098229 1.00000000 ---- NO Hamiltonian Matrix Functional ---- ========================================== 0 1 0 -959.99564600 -730.60245583 1 -730.60245583 -959.99557700 ---- NOSI Coefficients Matrix (column vectors are eigenvectors) ---- ==================================================================== 0 1 0 -0.53311086 1.44624356 1 -0.53259535 -1.44643349 ---- Singlet and Triplet Excitation Energies ---- ================================================= Eigenstate 0: -960.03127186 Hartree; Excitation energy: 0.00000000 eV Eigenstate 1: -959.73288097 Hartree; Excitation energy: 8.11963379 eV ---- Singlet State Weights ---- =============================== 0 1 0 0.50027469 0.49972531 1 0.49972531 0.50027469 ---- NOSI Results ---- ====================== State NOSI Energies Excited Energy Osc. Str. DX DY DZ (Hartree) (eV) (a.u.) (a.u.) (a.u.) 0 -960.03127186 0.00000000 0.00000000 -268.39724 567.48539 -94.86319 1 -959.73288097 8.11921604 1.46991870 1.07003 1.72943 -3.26904 We can see that, unlike the excited states, the diabatic states are highly overlapping (In ``NOSI Overlap Matrix``, :math:`S_{01} = 0.76098229`). In ``NOSI Coefficients Matrix``, the column vectors are the **adiabatic states**, indicating that the reactant and product diabatic states are mixed in a 1:1 ratio in both the ground and excited states. The adiabatic state energies are shown here (A standard DFT calculation is also given in ``adiab.inp``): .. list-table:: * - NOSI Adiabatic State 0 - NOSI Adiabatic State 1 - DFT Adiabatic * - -960.03127186 Hartree - -959.73288097 Hartree - -960.05738745 Hartree .. tip:: All input files can be downloaded: :download:`Files `. opt ====== .. contents:: :local: This keyword controls the search of geometry minimum, transistion state, and reaction path. Options ------------ .. option:: type .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``Min`` Search the geometry minimum. * - - ``NEB`` Use the nudged elastic band (NEB) algorithm to search the reaction path and transition state. * - - ``Dimer`` Use the dimer algorithm to search the transition state given the reactant and product geometry. * - - ``QST2`` Use the QST2 algorithm to search the transition state given the reactant and product geometry. * - - ``TS`` Search the transition state from a single structure. * - Default - ``Min`` Determine what type of geometry optimization you want to do. For ``Min`` and ``TS``, the initial structure should be given in ``mol``. The optimization process is output to ``x-opt-traj.xyz`` and the final minimum or transition state is output to ``x-opt.xyz``. For ``NEB``, ``Dimer``, and ``QST2``, 2 structures have to be given in ``mol`` and ``mol2``, which represent a reactant and product pose, respectively. Usually, one can first use ``NEB`` to rapidly find a reasonable path and transition state. If ``NEB`` is hard to converge, then use the structures from ``NEB`` result to do a ``Dimer`` or ``QST2`` search. ``Dimer`` and ``QST2`` require reactant and product structures of high quality. For ``NEB``, the reaction path is output to ``x-opt-traj.xyz`` and the final transition state is output to ``x-opt.xyz``. For ``Dimer`` and ``QST2``, the transition state is output to ``x-opt.xyz``. The ``x-opt-traj.xyz`` is **NOT** reaction path! It is just the optimization process as ``Min`` or ``TS``. .. option:: max_step .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``1000`` The maximum number of geometry optimization steps. .. option:: energy_cov .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-4`` The energy convergence threshold. When the energy change is smaller than this value, this energy condition is satisfied. .. option:: grad_cov .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-3`` The gradient convergence threshold. This actually determines 4 convergence thresholds: .. list-table:: * - Maximum gradient component - ``grad_cov`` * - RMS gradient: - ``grad_cov`` * 2/3 * - Maximum atomic displacement - ``grad_cov`` * 4 * - RMS atomic displacement - ``grad_cov`` * 8/3 When all these 4 conditions are met, this gradient condition is satisfied. .. option:: max_dr .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``0.5`` The maximum atomic displacement in an optimization step. If the molecule is highly flexible (Mathematically, the potential energy surface is very flat), or the structure (especially transition state) is very close to the stationary point but not converge, setting a smaller ``max_dr`` like ``0.1`` is very useful. .. option:: num_images .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``10`` The number of images for NEB transition state search. This number canNOT be set **too small**, say, ``5``. .. option:: neb_k .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``0.01`` The force constant for NEB transition state search. For a specific system, the optimal number of ``neb_k`` should be chose by trail-and-error. .. option:: fix_atoms .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Atom range * - Default - None Assign the atoms that are fixed during geometry optimization. For example: .. code-block:: bash :linenos: opt fix_atom 2 5-9 23 26 end The atoms 2,5,6,7,8,9,23,26 will be fixed during geometry optimization. .. option:: fix_bond .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - 2 integers * - Default - None Assign the bond that are fixed during geometry optimization. For example: .. code-block:: bash :linenos: opt fix_bond 1 4 fix_bond 2 6 end The bonds (1,4) and (2,6) will be fixed during geometry optimization. .. option:: fix_angle .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - 3 integers * - Default - None Assign the angle that are fixed during geometry optimization. For example: .. code-block:: bash :linenos: opt fix_angle 1 4 5 fix_angle 2 6 7 end The angles (1, 4, 5) and (2, 6, 7) will be fixed during geometry optimization. .. option:: fix_torsion .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - 4 integers * - Default - None Assign the torsion that are fixed during geometry optimization. For example: .. code-block:: bash :linenos: opt fix_torsion 1 4 5 9 fix_torsion 2 6 7 12 end The torsions (1, 4, 5, 9) and (2, 6, 7, 12) will be fixed during geometry optimization. .. attention:: Currently, the transition state search algorithm ``QST2`` and ``TS`` do **NOT** support constraints. If you want to search a transition state with constraints, please use ``NEB`` or ``Dimer``. Theoretical Background -------------------------------- Minimum ^^^^^^^^^^^^^^^^ The minimum is defined as a stable isomer on its potential energy surface (PES) of a molecule. The gradients on all atoms are zero. The optimization of minimum depends strongly on the initial structure. **For different starters, one can get different isomers.** Transition State ^^^^^^^^^^^^^^^^^^^^^^ Transition state is a short-lived configuration of atoms that in maximum on one direction but minimum on other directions. The gradients on all atoms are also zero. In Qbics, one can use NEB or dimer method to search the transition state. Only (unoptimized) reactant and product structures are needed. No exact Hessian needs to be computed. A good strategy is: - Use cheap method, like xTB, to find a reasonable path and transition state with NEB (``type neb``). - Then, use standard DFT method to refine the transition state with dimer (``type dimer``) or QST2 (``type QST2``), even the previous NEB result is not converged. This strategy is shown below: .. figure:: /_images/optk.jpg Input Examples -------------------- Example: Minimum Structure of Aspirin ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Search the minimum structure of aspirin at B3LYP/def2-SVP level of theory: .. code-block:: bash :linenos: :caption: opt-1.inp basis def2-svp end scf charge 0 spin2p1 1 end mol O 1.23330 0.55400 0.77920 O -0.69520 -2.71480 -0.75020 O 0.79580 -2.18430 0.86850 O 1.78130 0.81050 -1.48210 C -0.08570 0.60880 0.44030 C -0.79270 -0.55150 0.12440 C -0.72880 1.84640 0.41330 C -2.14260 -0.47410 -0.21840 C -2.07870 1.92380 0.07060 C -2.78550 0.76360 -0.24530 C -0.14090 -1.85360 0.14770 C 2.10940 0.67150 -0.31130 C 3.53050 0.59960 0.16350 H -0.18510 2.75450 0.65930 H -2.72470 -1.36050 -0.45640 H -2.57970 2.88720 0.05060 H -3.83740 0.82380 -0.50900 H 3.72900 1.41840 0.85930 H 4.20450 0.69690 -0.69240 H 3.71050 -0.36590 0.64260 H -0.25550 -3.59160 -0.73370 end task opt b3lyp end Example: Minimum Structure with Constraints ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Search the minimum structure of a molecule "1UML" with a bond and a torsion fixed at xTB level of theory: .. tabs:: .. tab:: opt-2.inp .. code-block:: bash :linenos: :caption: opt-2.inp opt fix_bond 7 51 fix_torsion 2 9 12 13 end mol 1uml.xyz end task opt xtb end .. tab:: 1uml.xyz .. code-block:: bash :linenos: :caption: 1uml.xyz 60 1UMl(0) C 0.38066735 2.55219474 1.46267636 N -0.33789766 3.82795956 1.53541195 C -1.09121603 3.87593593 2.64608144 N -0.94245652 2.73117700 3.32171417 C -0.03158842 1.89319979 2.55453525 C 0.37212443 0.52262484 2.93349994 O 0.95733416 -0.14814113 2.10415165 N 0.07166899 0.06707847 4.15265909 C -0.24927084 4.91745505 0.56953160 C 0.93256260 5.84926075 0.89138538 O 0.85638839 6.40073825 2.18023567 C -0.21178237 4.41479892 -0.88585063 C -1.30451123 3.40488529 -1.25181254 N -0.92687172 2.67905416 -2.46663252 C -1.02012131 3.09677073 -3.75965819 C -0.51157942 2.12142921 -4.62384570 C -0.09088312 1.03387236 -3.77904056 C -0.36650560 1.41729423 -2.43324566 C 0.47064744 -0.18584082 -4.05073192 C 0.77451739 -1.04742178 -2.99644766 C 0.51501197 -0.67068355 -1.66606604 C -0.06269010 0.57406126 -1.40267529 N 0.81935074 -1.45803325 -0.60027087 C 1.28805430 -2.72903213 -0.64795569 O 1.47475540 -3.39721237 -1.66461437 C 1.57993549 -3.25675705 0.74748896 C 1.64225207 -4.78720972 0.77417719 C -0.79428279 -4.92640828 1.45233103 C 0.27286077 -5.43783743 0.71500759 C 0.09621230 -6.58712911 -0.05216185 C -1.13149600 -7.23287171 -0.06650889 C -2.18992415 -6.73793686 0.69577410 C -2.02072844 -5.58468177 1.44785223 H 1.08446564 2.21827120 0.70020968 H -1.72176781 4.71224102 2.94804163 H -0.42535733 0.67320222 4.82086735 H 0.33691344 -0.89030993 4.42449590 H -1.16218006 5.52526169 0.70631806 H 0.98220194 6.64417179 0.12373872 H 1.88374201 5.29787879 0.83772723 H 0.29674389 7.26495989 2.15187259 H 0.77353707 3.94775022 -1.06475242 H -0.26304168 5.28737023 -1.55851059 H -2.24791634 3.94699892 -1.42947786 H -1.48837270 2.67328764 -0.45339564 H -1.43235349 4.05491839 -4.07609186 H -0.44710423 2.17375337 -5.71065901 H 0.67778198 -0.47993189 -5.07960408 H 1.21706689 -2.02142178 -3.20534792 H -0.27079576 0.87203324 -0.37507411 H 0.68015960 -1.04879454 0.33459425 H 0.94277827 -2.86688017 1.55772521 H 2.59161906 -2.87935288 0.99367456 H 2.12787894 -5.07775312 1.72353104 H 2.29189074 -5.17230270 -0.02720370 H -0.66818790 -4.01186770 2.03180634 H 0.92422969 -6.97980706 -0.64230710 H -1.26922150 -8.12751976 -0.67371391 H -3.14853209 -7.25672910 0.70037925 H -2.85015656 -5.19299484 2.03675744 Check the constraints during optimization: .. figure:: /_images/opt-2.gif Example: Transition State of S\ :sub:`N`\ 2 Reaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Search the transion state of an S\ :sub:`N`\ 2 reaction with NEB algorithm at B3LYP/def2-SVP level of theory: .. code-block:: bash :linenos: :caption: ts-1.inp basis # Define basis set. def2-svp end opt type NEB # Type: Min, NEB, Dimer, QST2, TS num_images 10 # The number of images for NEB calculations. neb_k 0.01 # The force constant for NEB calculations. end scf charge -1 # The net charge. spin2p1 1 # 2S+1 end xtb chrg -1 end mol C -2.25147439 4.89406277 -1.00469981 H -1.89481996 3.88525277 -1.00469981 H -1.89480154 5.39846096 -0.13104831 H -3.32147439 4.89407596 -1.00469981 Cl -1.66479756 5.72372709 -2.44173406 Cl -2.67350651 4.09697871 0.73250622 end mol2 C -2.36845504 4.69197207 -0.60149770 H -1.76657311 4.00286639 -1.15626927 H -1.80200132 5.57659799 -0.39786281 H -3.23625780 4.94775799 -1.17280492 Cl -1.66479756 5.72372709 -2.44173406 Cl -2.86278952 3.94963672 0.91579319 end task opt b3lyp # opt xtb # You can also try this. end The reaction path is given in ``ts-1-opt-traj.xyz``: .. figure:: /_images/ts-1.gif The energies can be found in the output file ``ts-1.out``: .. code-block:: bash :linenos: :caption: ts-1.out NEB path updated in "ts-1-opt-traj.xyz": ---------------------------------------------------- # Energy Dist Gtang Gperp ---------------------------------------------------- 0 -960.06873748 0.13968 0.00000 0.00000 1 -960.06864683 0.11091 0.00029 0.00035 2 -960.06738628 0.07888 0.00032 0.00028 3 -960.06508634 0.07078 0.00008 0.00030 4 -960.06240481 0.09854 -0.00028 0.00036 5 -960.05912811 0.18516 -0.00087 0.00032 6 -960.05781339 0.21042 -0.00025 0.00051 7 -960.06424460 0.26756 -0.00057 0.00032 8 -960.06880165 0.00000 0.00000 0.00000 9 -960.05738746 0.06067 0.00014 0.00026 ---------------------------------------------------- Geometry optimization step 34: Current energy: -960.05738746 Delta Energy: 8.34686E-08; Target: 1.00000E-04; Converged? Yes Max displacement: 2.30167E-04; Target: 4.00000E-03; Converged? Yes RMS displacement: 1.07545E-04; Target: 2.66667E-03; Converged? Yes Max gradient: 5.45965E-04; Target: 1.00000E-03; Converged? Yes RMS gradient: 2.56874E-04; Target: 6.66667E-04; Converged? Yes Stationary point has reached. In the table, structure ``0`` and ``1`` are the reactant and product, respectively, and structure ``6`` is the transition state, which is also given in ``ts-1-opt.xyz``. You can change ``b3lyp`` to ``xtb`` to perform the calculation in a much more rapid way. You can also try ``type dimer``, which is computationally cheaper than ``NEB`` but requires reactant and product structures must be of high quality. Example: Transion State of Decarboxylation Reaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Search the transion state of the following decarboxylation reaction with NEB algorithm at B3LYP/def2-SVP level of theory: .. tabs:: .. tab:: ts-2.inp .. code-block:: bash :linenos: :caption: ts-2.inp mol a1.xyz end mol2 a2.xyz end scf charge -1 spin2p1 1 end opt type neb # You can also try "dimer". num_images 15 neb_k 0.01 end basis def2-svp end task opt b3lyp end .. tab:: a1.xyz .. code-block:: bash :linenos: :caption: a1.xyz 16 E = -587.26844619 Hartree; coordinates in Angstrom. C 0.04106534 -2.18782379 0.01873379 C -1.35798345 -2.26546988 0.01269198 C -2.17792255 -1.12924287 -0.02333896 C -1.53026482 0.10833393 -0.03797859 C -0.12071906 0.20403755 -0.02314596 C 0.67915283 -0.93908160 -0.00278636 C 0.47143440 -3.57161137 0.04441853 H -3.26722478 -1.21160460 -0.04107296 H -2.12778938 1.02510522 -0.06470926 H 0.34489770 1.19455049 -0.03304010 H 1.77014421 -0.92296985 -0.00764617 O -1.74251880 -3.55390987 0.03659370 N -0.56119829 -4.37040148 0.05822977 C 1.96372187 -4.05774618 0.02851820 O 2.15749685 -5.25776354 0.25204089 O 2.75531543 -3.11946977 -0.21744012 .. tab:: a2.xyz .. code-block:: bash :linenos: :caption: a2.xyz 16 E = -34.49382101 Hartree; coordinates in Angstrom. C -0.31300710 -2.30106195 -0.01428127 C -1.70090129 -2.13170314 -0.01142600 C -2.23889881 -0.83944478 -0.02217974 C -1.41495826 0.23848161 -0.03526503 C -0.02069520 0.06834558 -0.03813291 C 0.51990509 -1.17609015 -0.02785645 C 0.29527044 -3.71579140 -0.00257527 H -3.29999458 -0.70170793 -0.02007771 H -1.83005138 1.22465134 -0.04345765 H 0.61932516 0.92576433 -0.04849442 H 1.58298567 -1.29755818 -0.03013007 O -2.48723821 -3.16847622 0.00114316 N 0.74811153 -4.76914425 0.00614076 C 2.27925143 -4.13711065 0.09555385 O 1.94633923 -5.30045357 0.44105892 O 2.61216378 -2.97376825 -0.24995180 Structures in ``a1.xyz`` and ``a2.xyz`` are shown below. They are put arbitrarily without optimization: .. tabs:: .. tab:: a1.xyz .. figure:: /_images/a1.jpg .. tab:: a2.xyz .. figure:: /_images/a2.jpg The optimized transtion state ``ts-2-opt.xyz`` and path ``ts-2-opt-traj.xyz`` are shown below: .. tabs:: .. tab:: ts-2-opt.xyz .. figure:: /_images/a.jpg .. tab:: ts-2-opt-traj.xyz .. figure:: /_images/ts-2.gif Example: Transion State of Pd(OAc)-Catalyzed Nucleopalladation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Search the transion state of the following Pd(OAc)-catalyzed nucleopalladation with DIMER algorithm at B3LYP/def2-SVP level of theory: .. tabs:: .. tab:: ts-3.inp .. code-block:: bash :linenos: :caption: ts-3.inp mol a1.xyz end mol2 a2.xyz end scf charge 0 spin2p1 1 end opt type dimer # You can also use qst2 end basis def2-svp end pseudopotential def2-ecp # Since Pd is used, you need to use ECP. end task opt b3lyp end .. tab:: a1.xyz .. code-block:: bash :linenos: :caption: a1.xyz 43 element x y z Pd 0.24654 -1.25332 0.40518 N 2.21910 -1.24512 -0.02293 O 4.02373 -2.55737 -0.59458 N 0.71331 0.97790 0.25853 C 2.90583 -2.40807 -0.13902 C 4.14710 0.14624 -0.66749 H 4.76219 -0.71420 -0.85891 C 1.86165 3.54336 0.19530 H 2.32306 4.52041 0.16979 C 2.82401 -0.02669 -0.28507 C 0.56127 3.36146 0.56593 H -0.05640 4.19293 0.87529 C 0.02466 2.06497 0.55234 H -1.01171 1.95668 0.81328 C 2.10089 -3.60617 0.39103 H 2.29784 -3.68424 1.46574 H 2.50312 -4.49514 -0.09449 C 3.99404 2.53651 -0.49534 H 4.44575 3.51746 -0.52470 C 0.63638 -3.41684 0.12343 C 2.02781 1.13223 -0.06025 C 2.63885 2.42073 -0.14140 C 4.72289 1.41237 -0.76883 H 5.76763 1.48006 -1.03642 C -0.35167 -3.32488 1.08900 H -1.30757 -3.58022 0.86748 H -0.08593 -3.27603 2.15625 H 0.32333 -3.63444 -0.90750 N -1.81017 -1.32804 0.64184 O -2.91585 -2.79869 -0.74520 C -2.83467 -1.72049 -0.17802 C -2.07940 -0.18984 1.24478 O -1.43547 0.22090 2.19254 C -3.75316 -0.59348 -0.30558 C -3.63015 1.69613 0.35364 H -3.18847 2.48978 0.92320 C -4.76410 -0.32523 -1.20052 H -5.18473 -1.11145 -1.79977 C -3.23750 0.40158 0.51050 C -4.56763 1.99386 -0.63755 H -4.81215 3.01413 -0.85747 C -5.15401 0.98013 -1.36177 H -5.89024 1.23011 -2.11222 .. tab:: a2.xyz .. code-block:: bash :linenos: :caption: a2.xyz 43 element x y z Pd 0.26512 -0.64711 0.61399 N 2.06999 -0.92815 -0.05458 O 3.65856 -2.55368 -0.43497 N 0.99509 1.45229 0.64166 C 2.54673 -2.20957 -0.08507 C 4.14972 0.20649 -0.71873 H 4.62578 -0.72848 -0.96208 C 2.30494 3.86864 0.23224 H 2.82051 4.80502 0.07331 C 2.84319 0.19559 -0.25035 C 1.03545 3.83626 0.74375 H 0.50815 4.74282 0.99632 C 0.42408 2.59308 0.95757 H -0.55466 2.53340 1.41954 C 1.49284 -3.20295 0.42350 H 1.66001 -3.32238 1.50139 H 1.64757 -4.17628 -0.05294 C 4.28051 2.61430 -0.57548 H 4.82459 3.53688 -0.70941 C 0.10935 -2.62297 0.15412 C 2.24272 1.45031 0.10134 C 2.96211 2.66317 -0.08830 C 4.85325 1.40272 -0.86406 H 5.87106 1.36062 -1.22258 C -1.07037 -3.17687 0.95906 H -1.41934 -4.15247 0.60366 H -0.83933 -3.23046 2.02995 H -0.13100 -2.69707 -0.92522 N -2.14266 -2.22101 0.73663 O -3.47014 -3.49326 -0.64534 C -3.14336 -2.41981 -0.19876 C -1.88727 -0.84977 0.97034 O -1.25091 -0.41692 1.95149 C -3.68247 -1.07281 -0.49566 C -3.19644 1.22329 0.10017 H -2.60860 1.95263 0.63571 C -4.76405 -0.68826 -1.26341 H -5.36566 -1.42688 -1.76954 C -2.89679 -0.12547 0.17462 C -4.28294 1.60635 -0.67387 H -4.53744 2.65330 -0.74569 C -5.05313 0.66777 -1.34699 H -5.89479 0.99766 -1.93734 Structures in ``a1.xyz`` and ``a2.xyz`` are shown below. They are put arbitrarily without optimization: .. tabs:: .. tab:: a1.xyz .. figure:: /_images/a12.jpg .. tab:: a2.xyz .. figure:: /_images/a22.jpg The optimized transtion state is ``ts-3-opt.xyz``, shown below: .. figure:: /_images/ats2.jpg output =================== .. contents:: :local: This keyword defines the details that should be output by Qbics. Options ------------ .. option:: max_num_atoms_print .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``1000`` When the number of atoms is greater than this value, the molecular coordinates will not be output for clarity. .. option:: print_CHARMM Print details of the CHARMM force field used for the molecule, including all terms and their parameters. .. option:: print_GTO_shell Print GTO shell parameters. .. option:: print_GTO_block Print GTO block information. Here, block is the shells that share the same angular momentum, center, and primitive Gaussian exponents but different contraction coefficients. This is useful when general segmented basis set is used. .. option:: print_pp Print pseudopotential parameters. .. option:: not_strict Cancel some sanity check. For example, Qbics will raise an error in situations when calculations are unreasonable, like: - Basis set and pseudopotential do not consistent; - An SCF does not converge. However, if you **really know what you are doing,** you can add this option to cancel such sanity checks. This is very **dangerous!** .. tip:: All input files can be downloaded: :download:`Files `. pcm ====== .. contents:: :local: This option controls the polarized continuum model. Options ------------ .. option:: model .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``IEFPCM``. Will use IEF-PCM (integral equation formalism of PCM) model. * - - ``CPCM``. Will use C-PCM (Conductor-like PCM) model. * - - ``COSMO``. Will use COSMO (conductor-like screening model) model. * - Default - ``IEFPCM`` The PCM model. ``IEFPCM`` is recommended. .. option:: solvent .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - 7 real numbers * - - ``water`` * - - ``acetic acid`` * - - ``acetone`` * - - ``acetonitrile`` * - - ``acetophenone`` * - - ``aniline`` * - - ``anisole`` * - - ``benzaldehyde`` * - - ``benzene`` * - - ``benzonitrile`` * - - ``benzyl chloride`` * - - ``1-bromo-2-methylpropane`` * - - ``bromobenzene`` * - - ``bromoethane`` * - - ``bromoform`` * - - ``1-bromooctane`` * - - ``1-bromopentane`` * - - ``2-bromopropane`` * - - ``1-bromopropane`` * - - ``butanal`` * - - ``butanoic acid`` * - - ``1-butanol`` * - - ``2-butanol`` * - - ``butanone`` * - - ``butanonitrile`` * - - ``butyl acetate`` * - - ``butylamine`` * - - ``n-butylbenzene`` * - - ``sec-butylbenzene`` * - - ``tert-butylbenzene`` * - - ``carbon disulfide`` * - - ``carbon tetrachloride`` * - - ``chlorobenzene`` * - - ``sec-butyl chloride`` * - - ``chloroform`` * - - ``1-chlorohexane`` * - - ``1-chloropentane`` * - - ``1-chloropropane`` * - - ``o-chlorotoluene`` * - - ``m-cresol`` * - - ``o-cresol`` * - - ``cyclohexane`` * - - ``cyclohexanone`` * - - ``cyclopentane`` * - - ``cyclopentanol`` * - - ``cyclopentanone`` * - - ``cis-decalin`` * - - ``trans-decalin`` * - - ``decalin (cis/trans mixture)`` * - - ``n-decane`` * - - ``1-decanol`` * - - ``1,2-dibromoethane`` * - - ``dibromomethane`` * - - ``dibutyl ether`` * - - ``o-dichlorobenzene`` * - - ``1,2-dichloroethane`` * - - ``cis-dichloroethylene`` * - - ``trans-dichloroethylene`` * - - ``dichloromethane`` * - - ``diethyl ether`` * - - ``diethyl sulfide`` * - - ``diethylamine`` * - - ``diiodomethane`` * - - ``diisopropyl ether`` * - - ``dimethyl disulfide`` * - - ``dimethyl sulfoxide`` * - - ``n,n-dimethylacetamide`` * - - ``cis-1,2-dimethylcyclohexane`` * - - ``n,n-dimethylformamide`` * - - ``2,4-dimethylpentane`` * - - ``2,4-dimethylpyridine`` * - - ``2,6-dimethylpyridine`` * - - ``1,4-dioxane`` * - - ``diphenyl ether`` * - - ``dipropylamine`` * - - ``n-dodecane`` * - - ``1,2-ethanediol`` * - - ``ethanethiol`` * - - ``ethanol`` * - - ``ethyl acetate`` * - - ``ethyl formate`` * - - ``ethylbenzene`` * - - ``ethylphenyl ether`` * - - ``fluorobenzene`` * - - ``1-fluorooctane`` * - - ``formamide`` * - - ``formic acid`` * - - ``n-heptane`` * - - ``1-heptanol`` * - - ``2-heptanone`` * - - ``4-heptanone`` * - - ``n-hexadecane`` * - - ``n-hexane`` * - - ``hexanoic acid`` * - - ``1-hexanol`` * - - ``2-hexanone`` * - - ``1-hexene`` * - - ``1-hexyne`` * - - ``iodobenzene`` * - - ``1-iodobutane`` * - - ``iodoethane`` * - - ``1-iodohexadecane`` * - - ``iodomethane`` * - - ``1-iodopentane`` * - - ``1-iodopropane`` * - - ``isopropylbenzene`` * - - ``p-isopropyltoluene`` * - - ``mesitylene`` * - - ``methanol`` * - - ``2-methoxyethanol`` * - - ``methyl acetate`` * - - ``methyl benzoate`` * - - ``methyl butanoate`` * - - ``methyl formate`` * - - ``4-methyl-2-pentanone`` * - - ``methyl propanoate`` * - - ``2-methyl-1-propanol`` * - - ``2-methyl-2-propanol`` * - - ``n-methylaniline`` * - - ``methylcyclohexane`` * - - ``n-methylformamide (e/z mixture)`` * - - ``2-methylpentane`` * - - ``2-methylpyridine`` * - - ``3-methylpyridine`` * - - ``4-methylpyridine`` * - - ``nitrobenzene`` * - - ``nitroethane`` * - - ``nitromethane`` * - - ``1-nitropropane`` * - - ``2-nitropropane`` * - - ``o-nitrotoluene`` * - - ``n-nonane`` * - - ``1-nonanol`` * - - ``5-nonanone`` * - - ``n-octane`` * - - ``1-octanol`` * - - ``2-octanone`` * - - ``n-pentadecane`` * - - ``pentanal`` * - - ``n-pentane`` * - - ``pentanoic acid`` * - - ``1-pentanol`` * - - ``2-pentanone`` * - - ``3-pentanone`` * - - ``1-pentene`` * - - ``e-2-pentene`` * - - ``pentyl acetate`` * - - ``pentylamine`` * - - ``perfluorobenzene`` * - - ``phenylmethanol`` * - - ``propanal`` * - - ``propanoic acid`` * - - ``1-propanol`` * - - ``2-propanol`` * - - ``propanonitrile`` * - - ``2-propen-1-ol`` * - - ``propyl acetate`` * - - ``propylamine`` * - - ``pyridine`` * - - ``tetrachloroethene`` * - - ``tetrahydrofuran`` * - - ``tetrahydrothiophene-s,s-dioxide`` * - - ``tetralin`` * - - ``thiophene`` * - - ``thiophenol`` * - - ``toluene`` * - - ``tributyl phosphate`` * - - ``1,1,1-trichloroethane`` * - - ``1,1,2-trichloroethane`` * - - ``trichloroethene`` * - - ``triethylamine`` * - - ``2,2,2-trifluoroethanol`` * - - ``1,2,4-trimethylbenzene`` * - - ``2,2,4-trimethylpentane`` * - - ``n-undecane`` * - - ``m-xylene`` * - - ``o-xylene`` * - - ``p-xylene`` * - - ``xylene (mixture)`` * - - ``1,1-dichloroethane`` * - - ``1-iodopentene`` * - - ``1-pentyne`` * - - ``2-chlorobutane`` * - - ``benzyl alcohol`` * - Default - None The solvent name. It can be one of the string given in the table above, or 7 real numbers, which are: ``dielectric_constant refraction_index Abraham_alpha Abraham_beta abomaticity halogenicity macro_surface_tension``. If some properties are unknown, you can set them to ``0``. .. option:: radius .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``UFF``. Will use UFF atomic radii for tesselation. * - - ``Bondi``. Will use UFF atomic radii for tesselation. * - Default - ``UFF`` This determines the radius type used for tesselation. ``UFF`` is highly recommended, since Bondi radii data is not complete for some common elements, like Fe. .. option:: tss_method .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``Swig``. Will use Swig algorithm for tesselation. * - - ``Switching``. Will use Switching algorithm for tesselation. * - - ``Sphere``. Will use sphere algorithm for tesselation. * - Default - ``Swig`` The algorithm for tesselation. ``Swig`` is recommended. ``Sphere`` is useful in the study of electron transfer. .. option:: grid_accuracy .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - - ``6``, ``14``, ``26``, ``38``, ``50``, ``86``, ``110`` * - - ``146``, ``170``, ``194``, ``302``, ``350``, ``434``, ``590`` * - - ``770``, ``974``, ``1202``, ``1454``, ``1730``, ``2030``, ``2354`` * - - ``2702``, ``3074``, ``3470``, ``3890``, ``4334``, ``4802``, ``5294`` * - Default - ``302`` The number of Lebedev points generated for tesselation. Usually ``302`` is enough. For higher accuracy, ``590``can be used. Theoretical Background -------------------------------- The Polarizable Continuum Model (PCM) is a widely used implicit solvation model in computational chemistry. In PCM, the solute molecule is placed inside a cavity embedded in a continuous dielectric medium that represents the solvent. Instead of explicitly simulating individual solvent molecules, PCM treats the solvent as a polarizable continuum characterized by its dielectric constant and other macroscopic properties. The interaction between the solute and the solvent is described by the polarization of the continuum in response to the solute's charge distribution. This polarization, in turn, affects the electronic structure of the solute. PCM enables the calculation of solvation effects on molecular properties, such as energies, geometries, and spectra, with relatively low computational cost compared to explicit solvent models. PCM is particularly useful for studying systems in solution, where solvent effects play a significant role in chemical reactivity, stability, and spectroscopic behavior. The model can be combined with various quantum chemical methods, such as Hartree-Fock and Density Functional Theory, to provide a more realistic description of molecules in their solvated environment. Input Examples -------------------- Example: Use Built-in and Self-defined Solvent for CH\ :sub:`3`\ Cl with PCM ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To use PCM in Qbics, we need to add the ``pcm`` keyword in the input file. There are two ways to use PCM: 1. Use the built-in solvent list shown above. 2. Explicitly give 7 numbers: dielectric_constant, refraction_index, Abraham_alpha, Abraham_beta, abomaticity, halogenicity, and macro_surface_tension. If some properties are unknown, you can set them to ``0``, but "dielectric_constant" must be at least given. In the following, in ``pcm-1a.inp``, we use ``aniline`` as solvent; in ``pcm-1b.inp``, we explicitly give the dielectric constant, refraction index, Abraham alpha, Abraham beta, abomaticity, and halogenicity: .. tabs:: .. tab:: pcm-1a.inp .. code-block:: bash :caption: pcm-1a.inp :linenos: basis cc-pvdz end pcm solvent aniline # Use aniline as solvent. end mol C -0.43654823 1.13197968 0.00000000 H -0.07987539 1.63637787 0.87365150 H -0.07987539 1.63637787 -0.87365150 H -1.50654823 1.13199286 0.00000000 Cl 0.15009830 -0.52737135 0.00000000 end task energy b3lyp end .. tab:: pcm-1b.inp .. code-block:: bash :caption: pcm-1b.inp :linenos: basis cc-pvdz end pcm solvent 6.8882 1.5863 0.2600 0.4100 0.8570 0.0000 60.6200 # Explicitly define the solvent. end mol C -0.43654823 1.13197968 0.00000000 H -0.07987539 1.63637787 0.87365150 H -0.07987539 1.63637787 -0.87365150 H -1.50654823 1.13199286 0.00000000 Cl 0.15009830 -0.52737135 0.00000000 end task energy b3lyp end In the output file ``pcm-1a.out`` and ``pcm-1b.out``, you will find the solvent definitions and PCM energies: .. tabs:: .. tab:: pcm-1a.out .. code-block:: bash :caption: pcm-1a.out :linenos: Polarized continuum model is applied. Solvent: aniline Dielectric constant: 6.8882 Refraction index: 1.5863 Abraham alpha: 0.2600 Abraham beta: 0.4100 Abomaticity: 0.8570 Halogenicity: 0.0000 Macro surface tension: 60.6200 Tesselation: ..omitted.. SCF Energies ============ Kinetic energy: 499.00382795 Hartree Electron-nuclear attraction energy: -1290.65493694 Hartree Pseudopotential energy: 0.00000000 Hartree Exchange-correlation energy: -28.07548686 Hartree Electron Coulomb energy: 274.37629685 Hartree Electron exchange energy: -6.76432588 Hartree Nuclear repulsion energy: 51.98869889 Hartree PCM solvation energy: -0.00201126 Hartree Grimme dispersion energy: 0.00000000 Hartree ---------------------------------------------------------------- SCF energy (E): -500.12793727 Hartree Virial quotien (V/T): -2.00225271 .. tab:: pcm-1b.out .. code-block:: bash :caption: pcm-1b.out :linenos: Polarized continuum model is applied. Solvent: defined by user Dielectric constant: 6.8882 Refraction index: 1.5863 Abraham alpha: 0.2600 Abraham beta: 0.4100 Abomaticity: 0.8570 Halogenicity: 0.0000 Macro surface tension: 60.6200 Tesselation: Method: Swig Radius type: UFF ..omitted.. SCF Energies ============ Kinetic energy: 499.00382490 Hartree Electron-nuclear attraction energy: -1290.65493976 Hartree Pseudopotential energy: 0.00000000 Hartree Exchange-correlation energy: -28.07548686 Hartree Electron Coulomb energy: 274.37630261 Hartree Electron exchange energy: -6.76432590 Hartree Nuclear repulsion energy: 51.98869889 Hartree PCM solvation energy: -0.00201136 Hartree Grimme dispersion energy: 0.00000000 Hartree ---------------------------------------------------------------- SCF energy (E): -500.12793747 Hartree Virial quotien (V/T): -2.00225271 To use models other than IEF-PCM model, we need to add the ``model`` keyword in the input file: .. code-block:: bash :caption: pcm-1c.inp :linenos: basis cc-pvdz end pcm model cpcm # You can use IEFPCM, CPCM, or COSMO model. solvent aniline # Use aniline as solvent. end mol C -0.43654823 1.13197968 0.00000000 H -0.07987539 1.63637787 0.87365150 H -0.07987539 1.63637787 -0.87365150 H -1.50654823 1.13199286 0.00000000 Cl 0.15009830 -0.52737135 0.00000000 end task energy b3lyp end The resutl is: .. code-block:: bash :caption: pcm-1c.out :linenos: SCF Energies ============ Kinetic energy: 499.00431927 Hartree Electron-nuclear attraction energy: -1290.65504950 Hartree Pseudopotential energy: 0.00000000 Hartree Exchange-correlation energy: -28.07554137 Hartree Electron Coulomb energy: 274.37599784 Hartree Electron exchange energy: -6.76433296 Hartree Nuclear repulsion energy: 51.98869889 Hartree PCM solvation energy: -0.00212532 Hartree Grimme dispersion energy: 0.00000000 Hartree ---------------------------------------------------------------- SCF energy (E): -500.12803318 Hartree Virial quotien (V/T): -2.00225191 .. tip:: All input files can be downloaded: :download:`Files `. pifep ========= .. contents:: :local: This option controls the path integral free-energy perturbation (PI-FEP) simulation. Options ---------- .. option:: temp .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``298.15`` Simulation temperature in Kelvin. .. option:: sampling .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``bisection`` Bisection beads sampling algorithm. * - Default - ``bisection (must be provided)`` Define the beads sampling method. Chin approximation scheme, ``ca``, does not support bisection sampling algorithm. .. option:: bisection_level .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``6`` The number of PI beads under bisection algorithm which is defined as :math:`2^N`, where :math:`N` denotes bisection level. This keyword must be used in conjunction with ``bisection`` sampling algorithm. .. option:: classical_coord_file .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A filename * - Default - None Filename of an ``.xyz`` file which stores classical nuclear coordinates. .. option:: checkpoint_fn .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A filename * - Default - ``chk`` Checkpoint filename. .. option:: restart .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A filename * - Default - None The checkpoint filename from which the simulation resumes. .. option:: num_pifep_samples .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``100`` The number of PI beads samplings to perform for each classical nuclear coordinate. .. option:: quantised_atoms_list .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - List of integers or range of integers * - Default - None (meaning all atoms are quantised) The indices of atoms which are quantised to PI beads. .. option:: isotope_indices .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - List of integers or range of integers * - Default - None The indices of atoms which are specified for isotope exchange. .. option:: isotope_num .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - List of integers * - Default - None The isotope number based on table below (the atomic masses are hardcoded for now) .. table:: Isotopes table :widths: auto +---------------------------+-----------------+ | Isotope Name | isotope_num | +===========================+=================+ | :math:`^1\mathrm{H}` | 1 | +---------------------------+-----------------+ | :math:`^2\mathrm{H}` | 2 | +---------------------------+-----------------+ | :math:`^3\mathrm{H}` | 3 | +---------------------------+-----------------+ | :math:`^{12}\mathrm{C}` | 1 | +---------------------------+-----------------+ | :math:`^{13}\mathrm{C}` | 2 | +---------------------------+-----------------+ | :math:`^{14}\mathrm{C}` | 3 | +---------------------------+-----------------+ | :math:`^{14}\mathrm{N}` | 1 | +---------------------------+-----------------+ | :math:`^{15}\mathrm{N}` | 2 | +---------------------------+-----------------+ | :math:`^{16}\mathrm{O}` | 1 | +---------------------------+-----------------+ | :math:`^{17}\mathrm{O}` | 2 | +---------------------------+-----------------+ | :math:`^{18}\mathrm{O}` | 3 | +---------------------------+-----------------+ .. option:: write_log .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A file name * - Default - ``log.dat`` Log filename which stores summarised simulation output. .. option:: random_seed (optional) .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integers * - Default - None A seed value used to initialize the pseudo-random number generator (PRNG). Theoretical Background ---------------------------------- Path integral free-energy perturbation (PI-FEP) is an efficient method for computing kinetic isotope effects (KIEs) of chemical reactions. It can be used in conjunction with **QM** methods (e.g., DFT, AM1, xTB), **MM** methods (e.g., **CHARMM**), and, most importantly, combined QM/MM methods. The PI-FEP module within **Qbics** is implemented based on the works below: - Major, D. T.; Gao, J. `Implementation of the bisection sampling method in path integral simulations. `_ *J. Mol. Graphics Model.* **2005**, *24*, 121-127. - Major, D. T.; Garcia-Viloca, M.; Gao, J. `Path Integral Simulations of Proton Transfer Reactions in Aqueous Solution Using Combined QM/MM Potentials. `_ *J. Chem. Theory Comput.* **2006**, *2*, 236–245. - Major, D. T.; Gao, J. `An Integrated Path Integral and Free-Energy Perturbation-Umbrella Sampling Method for Computing Kinetic Isotope Effects of Chemical Reactions in Solution and in Enzymes. `_ *J. Chem. Theory Comput.* **2007**, *3*, 949–960. Input examples --------------------------- The classical reaction path is obtained using classical MD simulation *a priori*. The reaction coordinates in Cartesian coordinates are stored in a ``.xyz`` file and provided using the ``classical_coord_file`` keyword. The molecular definition of classical coordinates provided in the ``.xyz`` file must be identical to that in the ``mol`` section. In the examples below, proton transfer reactions of carbon acid will be studied using PI-FEP simulation. Reactions in the gas phase and in aqueous solution are given in Examples 1 and 2, respectively, for teaching purposes. Two examples used NDDO and NDDOMM methods, HF/DFT, MM, and xTB methods are also supported and used similarly. Example 1: Proton/Deuterium transfer of carbon acid using AM1 model ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We begin by assuming the classical mechanical PMF (CM-PMF) for the reaction has already been determined. The CM-PMF is then divided into small windows with a number of classical nuclear coordinates. For demonstration purposes, here we use the transition state window, which contains only 2 :download:`classical nuclear coordinates `. .. code-block:: bash :linenos: :caption: :download:`pifep-ts.inp ` nddo charge -1 spin2p1 1 end mol C -0.91443957 -0.60832058 0.13234559 C 0.56752523 -0.88854599 -0.01251568 C -1.38098404 0.57350638 -0.39929395 C -1.86640306 -1.49230171 0.66658200 C 1.40989454 0.39927020 0.10774010 H 0.90764801 -1.61825893 0.79377293 H 0.75135566 -1.47355548 -1.02103320 C -2.81217464 0.76351767 -0.60469285 O -0.61312320 1.51868550 -0.90259881 C -3.23488869 -1.24001922 0.62699159 H -1.41778574 -2.42988305 1.05788219 H 0.47186573 1.21971490 -0.39894757 C 1.58524382 0.80585715 1.58203285 N 2.80702371 0.28695417 -0.48459260 C -3.72646798 -0.05196086 0.02804376 H -3.05945315 1.70341266 -1.14865278 H -3.95495955 -2.00324151 0.97518366 H 2.50342196 1.42577625 1.79057995 H 0.70024044 1.30710258 1.99617930 H 1.82497321 -0.12313539 2.15506963 O 3.72131801 0.73970515 0.16512141 O 3.08057940 -0.23586136 -1.53039467 H -4.79156884 0.24245093 0.02696987 end pifep sampling bisection bisection_level 3 # 2^3 beads are used classical_coord_file ts2.xyz checkpoint_fn chk #restart chk num_pifep_samples 50 quantised_atoms_list 1-3 5 8 9 12-14 # -O(Ph)-H-C(donor)- and 3 adjacent atoms isotope_indices 12 # 12th atom, H, is exchanged to D isotope_num 2 # 1H->2D write_log cc2-s50.log end task pi am1 end By default, if one leaves ``quantised_atoms_list`` empty, all atoms will be quantized into PI beads. Consequently, the non-reactive atoms will also contribute to the quantum canonical partition function, and therefore contribute to statistical uncertainty. We can limit the quantization to atoms that are only relevant to the reactive region, **i.e.** the donor C, the migrating proton, the acceptor O(Ph), and the three atoms adjacent to the primary isotopic substitution site are quantized to PI beads. In PI-FEP theory, the quantum mechanical potential of mean force (QM-PMF) has the following expression: .. math:: \begin{align} W_{\mathrm{QM} } &= W_{ \mathrm{CM} } + \Delta G_{\mathrm{QM} } \\ &= W_{ \mathrm{CM} } - \beta ln \langle \delta(\bar{z}) \langle e^{-\beta \Delta \bar{U} } \rangle_{\mathbf{FP} } \rangle_\mathrm{CM} \end{align} where :math:`\beta` denotes reciprocal temperature times Boltzmann constant. :math:`\bar{z}` represents the centroid of PI beads being constrained to the corresponding classical nuclear coordinate. The outer average is based on the number of classical nuclear coordinates contained in the ``.xyz`` file (specified under ``classical_coord_file``), and the inner average is based on the number of samplings of PI beads specified under ``num_pifep_samples``. The ratio of quantum partition functions of the two isotopes, i.e. light(:math:`\mathrm{L}`) and heavy(:math:`\mathrm{H}`), at a given state, :math:`\bar{z}`, can be written as a free energy perturbation: .. math:: \begin{align} e^{-\Delta G^{\mathrm{H} \rightarrow \mathrm{L}}_{\mathrm{QM}}} = \frac{Q^{\mathrm{L}}_{\mathrm{QM}}(\bar{z})}{Q^{\mathrm{H}}_{\mathrm{QM}}(\bar{z})} = \frac{ \langle \delta( \bar{z} ) \langle e^{-\beta \Delta \Delta \bar{ U }^{ \mathrm{H} \rightarrow \mathrm{L} } } e^{-\beta \bar{ U }^{ \mathrm{H} } } \rangle_{ \mathrm{FP} } \rangle_{\mathrm{CM}} }{ \langle \delta( \bar{z}) \langle e^{-\beta \bar{U}^{\mathrm{H}} } \rangle_{\mathrm{FP}} \rangle_{\mathrm{CM}} } \end{align} where :math:`\Delta \bar{U} = \frac{1}{P} \sum_{k}^{P} V_k^{\mathrm{QM}} - V^{\mathrm{CM}}`. This method allows the ratio of partition functions to be computed within a single PI-FEP simulation, which avoids statistical uncertainties that would arise from conducting two independent simulations. In the current reaction, the reactive proton is exchanged with deuterium via ``isotope_indices 12`` and ``isotope_num 2``, which together specify the 12th atom, :math:`^{1}H`, to be exchanged with :math:`^{2}H`. The PI beads distribution of the deuterium atom will be generated by mass-perturbation, which allows the quantum partition functions for H- and D-isotope systems to be computed within a single simulation. In a PI-FEP simulation output, the QM-PMF as well as the ratio of quantum partition functions of the light and heavy isotope systems are displayed at the end. The log file, ``cc2-s50.log``, stores the essential output: .. code-block:: bash :linenos: :caption: cc2-s50.log 1 0.0218207855 +/- 0.0011852039 0.0215333804 +/- 0.0010824629 2 0.0214098885 +/- 0.0014015810 0.0200354439 +/- 0.0016564722 mean delta G (cm -> qm^L) = 0.0215931591 +/- 0.0002022663 Hartree mean delta G (cm -> qm^H) = 0.0205141115 +/- 0.0006233911 Hartree exp(-beta deltaG(H->L)) = 4.2956460285 +/- 0.0317993487 ``ts2.xyz`` contains 2 classical nuclear coordinates. The first two lines display the QM-PMF for light and heavy isotopes at each classical nuclear coordinate, respectively. The total QM-PMF values for light and heavy isotope systems are reported as ``mean delta G(cm->qm^L)`` and ``mean delta G(cm->qm^H)``, respectively. The ratio of quantum partition functions, calculated using the FEP expression, is displayed as ``exp(-beta deltaG(H->L))``. 2 standard errors are used to represent all uncertainties. The KIE can then be easily obtained via: .. math:: \begin{align} \mathrm{KIE} = \frac{k^\mathrm{L}}{k^{\mathrm{H}}} = \left[ \frac{ Q^{ \mathrm{L} }_{ \mathrm{QM} } (\bar{z}^{ \mathrm{TS} } )}{ Q^{ \mathrm{H} }_{ \mathrm{qm} } (\bar{z}^{\mathrm{TS}} ) } \right] / \left[ \frac{ Q^{ \mathrm{L} }_{ \mathrm{QM} } (\bar{z}^{ \mathrm{RS} } )}{ Q^{ \mathrm{H} }_{ \mathrm{qm} } (\bar{z}^{\mathrm{RS}} ) } \right] \end{align} where :math:`\bar{z}^{\mathrm{TS}}` and :math:`\bar{z}^{\mathrm{RS}}` denote the reaction coordinates at the transition and reactant states, respectively. Example 2: Proton/Deuterium transfer of carbon acid in aqueous using AM1/CHARMM model ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We can also use PI-FEP simulations in conjunction with QM/MM methods to study proton transfer reactions in aqueous solution. In this example, we provide a PI-FEP simulation of proton/deuterium transfer of carbon acid in water solvent. The quantum mechanically important carbon acid is described using the AM1 model, and the water solvent is described using the TIP3P model. The carbon acid in a TIP3P waterbox can be built using CHARMM-GUI with appropriate periodic boundary condition (PBC) setup, and equilibrated with a number of steps of MD simulations using the NVT and NPT ensembles. We assume the CM-PMF is already obtained from classical MD simulation with umbrella-sampling/metadynamics. The molecular definition of carbon acid in a 39×39×39 Å water cube is provided in :download:`geom.xyz `, CHARMM parameter (:download:`lig.prm `, :download:`par_all36_cgenff.prm `, :download:`toppar_water_ions.str `), and topology (:download:`step2_solvator.psf `) files are provided. The classical coordinate file, :download:`rs-2.xyz `, which stores 2 classical nuclear coordinates of the reaction at the reactant state, is provided for demonstration purposes. .. code-block:: bash :linenos: :caption: pifep-rs.inp nddo charge -1 spin2p1 1 end mol geom.xyz end charmm parameters lig.prm par_all36_cgenff.prm toppar_water_ions.str topology step2_solvator.psf # rs-opt scaling14 1.0 rcutoff 11.0 rswitch 10.0 use_PBC Lbox 39 39 39 end qmmm qm_region 1-23 end pifep sampling bisection bisection_level 3 classical_coord_file rs-2.xyz checkpoint_fn chk_cc2_p8_s10 #restart chk_cc2_p8_s10 num_pifep_samples 10 quantised_atoms_list 1-3 5 8 9 12-14 # 1-23 if left out in blank isotope_indices 12 isotope_num 2 write_log ie-cc2-p8-s10.log end task pi am1/charmm end The PI beads quantization and isotope exchange settings are identical to those in Example 1. The simulation output format and interpretation follow the same description as provided in Example 1. Checkpoint and restart ------------------------- A text-based checkpoint file (named ``chk`` by default) is written as the simulation runs, if the simulation terminates due to any unexpected reasons, it can be restarted by ``restart`` option with the appropriate checkpoint filename. Code Execution in Parallel ------------------------------- The PI-FEP module supports both serial and MPI parallel computation, and can be used in conjunction with OpenMP. In the MPI parallel approach, each PI bead is assigned to a dedicated MPI worker process, while OpenMP enables further parallelization within each process by distributing computational tasks across multiple threads. Note that the number of MPI processes should not exceed the number of PI beads + 1. Assuming MPI is properly installed and configured, one can execute the program using the following: .. code-block:: bash :linenos: # 8 beads PI-FEP simulation executed using 9 MPI processes, 1 master thread is used to distribute tasks mpirun -np 9 qbics-linux-cpu-mpi pifep-rs.inp # 8 beads PI-FEP simulations executed using 5 MPI processes, each MPI process utilises 4 OpenMP threads mpirun -np 5 qbics-linux-cpu-mpi pifep-rs.inp -n 4 # PI-FEP simulation executed using 24 threads via OpenMP qbics-linux-cpu pifep-rs.inp -n 24 For PI-FEP simulations of any kinds of systems, parallel execution via MPI is strongly recommended for optimal performance. .. tip:: All input files can be downloaded: :download:`Files `. pseudopotential =============== .. contents:: :local: This keyword defines the pseudopotentials used for quantum chemistry calculations. You can define pseudopotentials in several flexible ways. .. WARNING:: ``pseudopotential`` **only** contains pseudopotential and does not contain any valence electron basis set information. You must assign basis sets in ``basis``. The valence basis and core pseudopotential **must match**. See :doc:`basis`. Below is a typical example. H is represented by a def2-TZVP basis set. For Au, the valence electrons are represented by a def2-TZVP basis set, and core electrons are repesented by def2-ecp, i.e. Stuggart-Cologne pseudopotential. .. code-block:: bash :linenos: basis def2-TZVP end pseudopotential def2-ecp end # The Karlsruhe basis sets for Au was developed with Stuggart-Cologne pseudopotential. mol Au 0. 0. 0. # SDD+def2-TZVP H 0. 0. 1. # def2-TZVP end .. warning:: If you write it in this **WRONG** way: .. code-block:: bash :linenos: # A wrong input! basis def2-TZVP end mol Au 0. 0. 0. H 0. 0. 1. end Then, **NO** pseudopotential is applied for any element! Also, keep in mind that the valence basis and core pseudopotential **must match**. The following combinations are usually accepted: .. list-table:: :widths: 8 8 :header-rows: 1 * - Valence Basis Set - Pseudopotential * - def2-X - def2-ecp * - (aug-)cc-X-pp - cc-ecp * - lanlX - lanl-ecp Using Built-in Pseudopotentials -------------------------------- A lot of important pseudopotentials have been provided in a folder ``pseudopotential`` in the same path of Qbics. The files are named after their names well-known in computational chemistry community. For example, ``pseudopotential/def2-ecp`` contains the Stuggart-Cologne pseudopotentials. All files are named in small cases. To use them, simple write down the basis set name. It is case-insensitive. For example, to use def2-ecp: .. code-block:: bash :linenos: pseudopotential def2-ecp end Qbics will extract pseudopotential information from ``pseudopotential/def2-ecp`` for all atoms that **have pseudopotentials**. For example, you molecule contains only C, H, N, Ce, and F. Since in ``pseudopotential/sdd``, there is only pseudopotential for Ce, then for C, H, N, and F, no pseudopotentials are applied. Explicit Pseudopotential Definitions ------------------------------------- You can also explicitly define your pseudopotentials. For example, you want to apply pseudopotentials for Rb and Sr, then their pseudopotentials can be defined in this way: .. code-block:: bash :linenos: pseudopotential RB 0 RB-ECP 3 28 f POTENTIAL 1 2 3.84311400 -12.31690000 s-f POTENTIAL 3 2 5.03655100 89.50019800 2 1.97084900 0.49376100 2 3.84311400 12.31690000 p-f POTENTIAL 3 2 4.25834100 58.56897400 2 1.47070900 0.43179100 2 3.84311400 12.31690000 d-f POTENTIAL 3 2 3.02312700 26.22489800 2 0.65038300 0.96283900 2 3.84311400 12.31690000 **** SR 0 SR-ECP 3 28 f POTENTIAL 1 2 4.63397500 -15.80599200 s-f POTENTIAL 3 2 7.40007400 135.47943000 2 3.60637900 17.53446300 2 4.63397500 15.80599200 p-f POTENTIAL 3 2 6.48486800 88.35970900 2 3.28805300 15.39437200 2 4.63397500 15.80599200 d-f POTENTIAL 3 2 4.62284100 29.88898700 2 2.24690400 6.65941400 2 4.63397500 15.80599200 **** end The analyitcal expression of pseudopotential is: .. math:: V(\mathbf{r}) = V_L(r)+\sum_{l=0}^{L-1}V_l(r)\sum_{m=-l}^{+l}\left|S_{lm}\right\rangle\left\langle S_{lm}\right| .. math:: V_l(r) = \sum_{k=1}^{K}d_{kl}r^{n_{kl}}e^{-\xi_{kl}r^2} The pseudopotential definition is of standard Gaussian94 format: - The definition of the pseudopotential for each atom ends with 4 asterisks, i.e. ``****``. - The definition starts with the element name like ``Rb`` and a ``0``. Currently ``0`` has no meaning. - Then, three parameters are given: pseudopotential name, maximum angular momentum :math:`L`, and number of core electrons. - Then, the semi-local part (:math:`V_l(r) (0\le l < L)`, defined by ``s-f POTENTIAL``, etc.) and the local one (:math:`V_L(r)`, defined by ``f POTENTIAL``) are listed. Each pseudopotential has the form : * The first line is a comment. * The contraction degree :math:`K`. * Then, each line defines the power :math:`n_{kl}` , the exponent :math:`\xi_{kl}`, and the contraction coefficient :math:`d_{kl}`. They are 3 real numbers. .. hint:: Pseudopotentials in Gaussian94 format can be obtained from: - https://www.basissetexchange.org/ - https://www.cosmologic-services.de/basis-sets/basissets.php - https://www.tc.uni-koeln.de/PP/clickpse.en.html But, remember to replace ``D`` to ``E`` since the former is not recognized by Qbics. Also, add ``****`` between elements. Using Self-defined Pseudopotential Files ------------------------------------------ You can also put your explicit pseudopotential definitions into some files, say ``/home/zhang/userdef/my-own-pseudopotential``. Qbics will automatically read it if you give explicit file name including path. .. code-block:: bash :linenos: pseudopotential /home/zhang/userdef/my-own-pseudopotential end Theoretical Background ------------------------- Pseudopotential is widely used in the fields of quantum chemistry, atomic physics, solid state physics, and computational materials science. The basic idea is to replace the influence of the nucleus and core electrons on the valence electrons with an effective potential. It can reduce the size of the basis set and also include relativistic effects on a non-relativistic level. Input Examples ------------------------- Some examples are also given in :doc:`basis`. Example: Using Explicitly Defined Pseudopotentials for Ce(H\ :sub:`2`\ O)\ :sub:`8`\ :sup:`3+` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Below is an example of calculating Ce(H\ :sub:`2`\ O)\ :sub:`8`\ :sup:`3+` using explicitly defined pseudopotentials for Ce and standard def2-svp for Ce, H, and O. Note that, since the pseudopotential has been applied to describe 47 core electrons of Ce ([Kr]4d\ :sup:`10`\ 4f\ :sup:`1`), the apparant spin multiplicity is ``1``, greatly simplifying the calculation. .. code-block:: bash :linenos: :caption: pseudopotential-1.inp basis def2-svp end pseudopotential Ce 0 ECP47MWB 4 47 G-Komponente 1 2 1.000000 0.000000 S-G 2 2 3.522200 95.842155 2 1.761100 -3.775040 P-G 2 2 3.017700 68.092779 2 1.508900 -0.966756 D-G 2 2 2.144300 36.381848 2 1.072200 0.190447 F-G 1 2 4.278500 -40.585328 **** end grimmedisp type bj end scf charge +3 spin2p1 1 end mol Ce -0.0000088 0.0000037 -0.0006635 O 1.8174770 -1.1442674 -1.3565307 O 2.0940885 0.4762325 1.3551096 O 0.4762019 -2.0941013 1.3550928 O -1.1442759 -1.8174502 -1.3565612 O -1.8174735 1.1443092 -1.3565265 O -2.0941079 -0.4762528 1.3550846 O 1.1442883 1.8174686 -1.3565204 O -0.4762411 2.0940836 1.3551277 H -2.7384080 -1.1961061 1.2400375 H -2.4318208 0.0300465 2.1143243 H -1.6982474 1.7415082 -2.1154550 H -2.7821029 1.0904008 -1.2419254 H 0.0300785 2.4317909 2.1143563 H -1.1960900 2.7383918 1.2400978 H 2.7383924 1.1960849 1.2400788 H 2.4317951 -0.0300811 2.1143427 H 1.6982634 -1.7414504 -2.1154737 H 2.7821042 -1.0903611 -1.2419111 H -1.0903471 -2.7820826 -1.2419964 H -1.7414853 -1.6982065 -2.1154789 H 1.7415073 1.6982406 -2.1154327 H 1.0903589 2.7820987 -1.2419353 H 1.1960541 -2.7384032 1.2400470 H -0.0301159 -2.4318311 2.1143124 end task energy b3lyp end .. tip:: All input files can be downloaded: :download:`Files `. qmmm ====== .. contents:: :local: This option controls the quantum mechanics/molecular mechanics (QM/MM) calculation details. Options ------------ .. option:: qm_region .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - Atom range * - Default - None Define the atoms in the QM region. .. code-block:: bash :linenos: qmmm qm_region 1-14 16 23 45-48 end In this input, atom 1,2,3,4,5,6,7,8,9,10,11,12,13,14,16,23,45,46,47,48 will be treated with QM methods, and others will treated with MM methods. .. option:: link .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``imomm`` Integrated molecular-orbital molecular mechanics (IMOMM) mehtod. * - - ``pho`` Porjected hybrid orbital (PHO) method. * - Default - ``imomm`` Define the method to treat of the boundary covalent bonds between QM and MM regions. In Qbics, there are two methods: ``imomm`` and ``pho``. The ``imomm`` method will add a hydrogen atom to saturate the boundary valency; the ``pho`` method will not add any hydrogen atom, but will use a special set of projected hybrid orbital to treat the boundary covalent bonds. **Both methods are implmented in a black-box manner, and users do not need to worry about the details of the methods.** Their details can be found in the references below. - IMOMM: `J. Comput. Chem. 1995, 16, 1170-1179 `_ - PHO: `J. Chem. Theory Comput. 2024, 20, 10574-10587 `_ In Qbics, "covalent bonds" are defined in the PSF file (given by ``topology`` in ``charmm``). In the QM region, all bonds are possible to break and form, while in the MM region, covalent bonds defined in the PSF file **NEVER** break and form. The boundary covalent bonds between QM and MM regions are **NOT** allowed to break. In the figure below, the QM region is defined by the green circle. For the left case, since no covalent bonds are defined between QM and MM regions, the ``link`` option is ignored (no matter what value given). For the right case, there are 3 covalent bond between QM and MM regions (red bonds), and the ``link`` option is used to treat these bonds. In Qbics, only sp\ :sup:`3` carbon can be used at the boundary (It must be included in the **QM region**). .. figure:: /_images/qmmm-1.jpg Both methods can treat the boundary covalent bonds. The ``pho`` method is more accurate for ground states; but ``imomm`` method can be combined with **TSO- or BLE-SCF** (see :doc:`scf`) to calculate the excited and diabatic states. Theoretical Background -------------------------------- Quantum Mechanics / Molecular Mechanics (QM/MM) is a multiscale computational strategy that combines the accuracy of quantum-mechanical (QM) methods for a chemically active region with the speed of molecular-mechanical (MM) force fields for the surrounding environment. In Qbics, the QM region can be treated with DFT, xTB, or NDDO methods, while the MM region is typically described by CHARMM or AMBER force fields. This approach allows for efficienzt simulations of large chemical systems. To do QM/MM simulations, first one have to prepare force field parameters and topology for the whole system, then use ``qm_region`` to define the QM region. If there **ARE** covalent bonds between atoms in QM and MM region, the boundary atoms must be sp\ :sup:`3` carbon (i.e., carbon atom linking to 4 atoms). Other atoms are **NOT** supported to be boundary. This is a reasonable restriction since in these cases the molecular orbitals can be significantly delocalized over QM and MM region, those bonds should not be cut. Based on ``link`` option, Qbics will call the corresponding method to treat boundary atoms. There are two methods for ``link``: ``imomm`` and ``pho``. The IMOMM method adds a hydrogen atom to saturate the boundary valency, while the PHO method uses a special set of projected hybrid orbitals to treat these bonds without adding hydrogen atoms. Both methods are implemented in a black-box manner, allowing users to focus on their calculations without needing to understand the underlying details. The main points are: - IMOMM: will add additional hydrogen atoms. Can be used for *both ground and excited states.** - PHO: will **NOT** add any additional atoms. Can only be used for ground states. Input Examples -------------------- Example: Solvated Organic Anion ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this example, we will do a QM/MM calculation for a water microdroplet of an organic anion. The input is given below: .. code-block:: bash :linenos: :caption: qmmm-1a.inp charmm parameters toppar_water_ions.str 92v-1-naive.prm topology 92v-solvate.psf scaling14 1.0 rcutoff 12.0 rswitch 100.0 # rswitch>rcutoff means no cutoff is applied. end xtb chrg -1 # The charge in QM region! uhf 0 # The number of unpaired electrons in QM region! end qmmm qm_region 1-39 end opt max_step 2000 end mol 92v-solvate.pdb end task opt xtb/charmm end In ``qmmmm-1a.inp``, we have given the ``charmm`` and ``xtb`` blocks to define the force field parameters and the QM method. The ``mol`` block is used to load the cooridnates; The topology is defined in the PSF file (``topology`` in ``charmm``); the parameters are defined in ``parameters`` in ``charmm``. The ``task`` block is used to run the optimization with QM/MM method. Note that this is a gas phase optimization, so no cutoff is applied (``rswitch`` is set to be larger than ``rcutoff``). Another important point is that in ``xtb``, the charge and number of unpaired electrons are defined **only** for in the QM region! After optimization, the structure is stored in ``qmmm-1a-opt.xyz``, shown below: .. figure:: /_images/qmmm-6.jpg We can use it as the structure to do a B3LYP-D3BJ/def2-svp single point energy: .. code-block:: bash :linenos: :caption: qmmm-1b.inp charmm parameters toppar_water_ions.str 92v-1-naive.prm topology 92v-solvate.psf scaling14 1.0 rcutoff 12.0 rswitch 100.0 # rswitch>rcutoff means no cutoff is applied. end xtb chrg -1 # The charge in QM region! uhf 0 # The number of unpaired electrons in QM region! end basis def2-svp end scf charge -1 # The charge in QM region! spin2p1 1 # The spin multiplicity in QM region! end grimmedisp type bj end qmmm qm_region 1-39 end mol qmmm-1a-opt.xyz end task energy b3lyp/charmm end At the end of ``qmmm-1b.out``, you can find this: .. code-block:: bash :linenos: :caption: qmmm-1b.out Total QM/MM energy ================== Polarized QM energy: -1608.98518142 Hartree Whole system MM energy: -90.52845586 Hartree QM/MM energy correction: 16.29439183 Hartree ------------------------------------------------ QM/MM energy: -1683.21924545 Hartree Final total energy: -1683.21924545 Hartree ``QM/MM energy`` is the total energy. In all above cases, you can change ``energy`` or ``opt`` to ``md`` to do a QM/MM MD simulation. Example: Residues in Solvated Protein ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this example, we will show the QM/MM energy calculation of two interacting residues in a protein. Assume we have already prepared a solvated protein, shown below: .. figure:: /_images/qmmm-5.jpg We will choose two residues on a beta-sheet region, i.e. ILE44 and HSD68, which are far away from each other on sequence but are quite close in 3D space. We also include some of their neighboring atoms. The atom indices are shown below: .. figure:: /_images/qmmm-3.jpg The QM region is cut at 4 sp\ :sup:`3` carbon atoms, also shown below. All boundary carbon atoms link to 3 MM atoms: .. figure:: /_images/qmmm-4.jpg Thus, the input file is: .. code-block:: bash :linenos: :caption: qmmm-2.inp charmm parameters toppar_water_ions.str par_all36m_prot.prm topology sys.psf scaling14 1.0 rcutoff 12.0 rswitch 10.0 use_PBC # Add this line to turn on PBC. Lbox 64 64 64 # Define the box size. electrostatic cutoff # Use cutoff or QM/MM. end basis def2-svp end scf charge 0 spin2p1 1 end qmmm qm_region 682 697-720 1062 1077-1098 link imomm # or change to: pho end mol sys.xyz end task energy b3lyp/charmm end The above input should be self-explanatory, if you have already known how to use Qbics to do QM and MM calculations. The only point is that currently, if the periodic boundary condition (PBC) is turned on, it is **recommended** to use ``cutoff`` instead of ``pme`` for QM/MM calculations. After calculation, you can find the following lines: .. code-block:: bash :linenos: :caption: qmmm-2.out Link atoms algorithm: IMOMM Boundary: QM atom 682: A hydrogen is capped at (2.484, -2.583, 3.898) Angstrom. MM atom 680 has 2 bonded MM atoms: 678 681 MM atom 683: No MM atoms bond to it. MM atom 684 has 3 bonded MM atoms: 685 686 687 QM atom 697: No MM atoms bond to it. ...omitted... QM atom 720: A hydrogen is capped at (-2.116, -2.240, 7.935) Angstrom. MM atom 721: No MM atoms bond to it. MM atom 722 has 3 bonded MM atoms: 723 724 725 MM atom 736 has 2 bonded MM atoms: 737 738 QM atom 1062: A hydrogen is capped at (-1.980, 2.584, 5.141) Angstrom. MM atom 1060 has 2 bonded MM atoms: 1058 1061 MM atom 1063: No MM atoms bond to it. MM atom 1064 has 3 bonded MM atoms: 1065 1066 1067 ...omitted... Total QM/MM energy ================== Polarized QM energy: -1200.63363221 Hartree Whole system MM energy: -178.02621763 Hartree QM/MM energy correction: 23.67074974 Hartree ------------------------------------------------ QM/MM energy: -1354.98910010 Hartree Final total energy: -1354.98910010 Hartree Lines 1-16 show how Qbics is treating the boundary atoms, the remaining lines are the QM/MM energies. You can also visualize electronic structures with `Qbics-MolStar `_. Load topology ``sys.psf`` in :guilabel:`Model` and coordinates ``sys.xyz`` in :guilabel:`Coordinates`, click :guilabel:`Apply` to load the solvated protein. Then, drag ``qmmm-2.mwfn`` into `Qbics-MolStar `_ to loead wavefunction. Then, right-click :guilabel:`qmm-2.mwfn`, click :guilabel:`View Molecular Orbitals`, click :guilabel:`91: -0.36206 (occ=2,RHF)`, then the HOMO of this system is shown below. The QM region is rendered using ball-and-stick representation. .. figure:: /_images/qmmm-7.jpg You can also visualize other properties with `Qbics-MolStar `_. .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: Please refer to :doc:`scfguess` for more examples. For a complete tutorial of TSO-DFT, please refer to: - :doc:`../tutorials/tso1` - :doc:`../tutorials/tso2` scf ===== .. contents:: :local: This option controls how to perform an SCF calculation. Options ------------ .. option:: charge .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``0`` Define the total charge of the system. .. option:: spin2p1 .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``1`` for even number of electrons * - - ``2`` for odd number of electrons Define the spin multiplicity of the system, i.e., :math:`2S+1`, where :math:`S` is the spin of the system. For example, to consider the singlet and triplet state, one should set :option:`spin2p1` to ``1`` and ``3``, respectively. Note that :option:`spin2p1` can be either positive or **negative.** Both positive and negative :option:`spin2p1` represent the same spin multiplicity, but for a SCF wave function, alpha and beta orbitals will be occupied first, respectively. For example, for 11 electrons with :option:`spin2p1` being ``1``, there will be 6 alpha electrons and 5 beta electrons, like most quantum chemistry software does; but when :option:`spin2p1` is ``-1``, there will be 5 alpha electrons and 6 beta electrons. For odd number of electrons, a positive ``spin2p1`` will first occupy alpha orbitals. If you want the beta orbitals to be occupied first, use a negative ``spin2p1``. For example: .. code-block:: bash :linenos: scf charge 0 spin2p1 3 end mol H 0. 0. 0. H 0. 0. 0.74 end In this case, the molecule will have 2 alpha electrons and 0 beta ones. For another input: .. code-block:: bash :linenos: scf charge 0 spin2p1 -3 end mol H 0. 0. 0. H 0. 0. 1. end The molecule will have 2 beta electrons and 0 alpha ones. .. option:: type .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``R`` for restricted SCF (alpha and beta orbitals are restricted to be identical) * - - ``U`` for unrestricted SCF (alpha and beta orbitals are not necessarily identical) * - Default - ``R`` for singlet state * - - ``U`` for other states For singlet states, both restricted and unrestricted SCF are available. Unrestricted SCF is very useful in treating spin polarized systems. For non-singlet states, only the unrestricted one can be used. .. option:: max_it .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A non-negative integer * - Default - ``128`` Define the maximum number of SCF iteration. .. hint:: You can set ``max_it`` to ``0`` to do a non-iterative calculation. .. option:: energy_cov .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-6`` The energy convergence threshold for SCF calculations. .. option:: density_cov .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-8`` The density matrix convergence threshold for SCF calculations. .. hint:: The SCF calculation is determined to be convergent when both the energy and density convergence conditions are satisfied. .. hint:: If SCF does not converge, Qbics will exit immediately. If you want Qbics to continue even an SCF calculation does not converge, please refer to :doc:`output`. .. option:: no_diis Do not use direct inversion of the iterative subspace (DIIS) convergence acceleration algorithm. .. option:: no_damping Do not use damping convergence acceleration algorithm. .. option:: damping_factor .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``0.3`` The density matrix damping factor to accelerate SCF convergence. .. option:: print_MO Print molecular orbital coefficients. Without this, only molecular orbital energies and occupancies are printed. .. option:: schwarz .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-10`` Define the Schwarz screening tolerance. All two-electron integral contributions below this tolerance will be discarded to speed up calculations. A positive real number is needed. .. WARNING:: Do **not** set a too large value (like ``1.E-5``). It may leads to wrong results. .. option:: no_scf .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``tso`` Do target state optimization SCF (TSO-SCF). * - - ``ble`` Do block-localized excitation SCF (BLE-SCF). * - Default - None Instead of doing ordinary SCF, do **non-orthogonal** SCF to treat **diabatic and excited states.** This is a powerful method. Some input examples can be found in :doc:`scfguess`. For theoretical details, please refer to: - TSO-DFT: `J. Chem. Theory Comput. 2023, 19, 1777-1789 `_ - BLE-DFT: `J. Chem. Theory Comput. 2021, 17, 240-254 `_ .. tip:: For a complete tutorial of TSO-DFT, please refer to: - :doc:`../tutorials/tso1` - :doc:`../tutorials/tso2`. Theoretical Background -------------------------------- The self-consistent field (SCF) method is the corner stone of modern electronic theory and computational chemistry. In Qbics, both Hartree-Fock and Kohn-Sham methods can be used. After calculations, energies are given in the output file, and the wave function is given in an MWFN file, which can be visualzied in `Qbics-MolStar `_ or `Multiwfn `_. Density Functionals ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For Kohn-Sham methods, the available density functionals are listed below: .. list-table:: * - **Local density approximation (LDA)** * - ``lda`` * - **Generalized gradient approximation (GGA)** * - ``pbe`` * - ``blyp`` * - ``bp86`` * - ``olyp`` * - ``pw91`` * - **Hybrid GGA** * - ``pbe0`` * - ``b3lyp`` * - ``o3lyp`` * - ``b3pw91`` * - ``x3lyp`` * - **Meta-GGA** * - ``tpss`` * - ``m06l`` * - **Hybrid meta-GGA** * - ``tpssh`` * - ``m06`` * - ``m062x`` * - ``m06hf`` In modern computational chemistry, there have been a lot of experience for basis functional selection. Here, we just give a few points: - In most cases, LDA should NOT be used. - For organic compounds, hybrid functionals **B3LYP** and **M06-2X** are often the most reliable ones. - For compounds containing metals, GGAs like **BP86** and **BLYP** sometimes work better than hybrid GGAs. Of course, the best way for basis functional selection is to do calibration for your specific system. Also, in all modern calculations, one should use disperison corrections, like DFT-D3 in :doc:`grimmedisp`. SCF Convergence ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In Qbics, if an SCF does not converg, please try the following methods: - Increase number of iterations, like ``mat_it 200``, although in most cases this does not work; - Set ``schwarz`` to a small value, like ``schwarz 1E-14``; - Use a converged wave function as the initial guess, say the same system with smaller basis sets. See :doc:`scfguess` for details. Non-orthogonal SCF: TSO-DFT ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ XXXXXXXXXXXXXX Non-orthogonal SCF: BLE-DFT ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In QBics, the BLE (Block-Localized Excitation) method is implemented using the TSO (Two-Step Optimization) module to divide orbitals into blocks. In each block, a block-localized SCF equation is solved. The **only difference** between BLE and standard TSO is in the treatment of excited-state configurations: - BLE combines the block-SCF framework with the **Δ-SCF** method proposed by Peter Gill et al., rather than simply excluding certain orbitals. - **Initial Maximum Overlap Method (IMOM)** is employed: - After the reference calculation, the excitation configuration is defined by ``scfguess ble``. - The program stores the occupied orbital coefficients as :math:`\mathbf{C}^{\text{old}}_{\text{occ}}`. - These are then used to construct a new Fock matrix, which is diagonalized to obtain new coefficients :math:`\mathbf{C}^{\text{new}}`. - Instead of assigning occupations based on orbital energies, BLE uses the **overlap projection** between new and old occupied orbitals. The projection is evaluated by: .. math:: P_q = \sum_{i\mu\nu} \left(C^{\text{old}}\right)^\dagger_{i\mu} S_{\mu\nu} C^{\text{new}}_{\nu q} Orbitals with the largest projections are selected as the newly occupied orbitals. Input Examples -------------------- Note that, in all examples below, you can change ``energy`` to ``opt`` to do geometry optimization, or ``md`` to do molecular dynamics. Example: DFT Energy of Dieldrin ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In ``scf-1a.inp``, ``scf-1b.inp``, and ``scf-1c.inp``, we calculate the singlet state, triplet state, and cationic state of dieldrin. For cationic state of dieldrin, since an electron is lost, its spin is ``2`` so it is a doublet state. There are controled by ``charge`` and ``spin2p1``. .. tabs:: .. tab:: scf-1a.inp .. code-block:: bash :linenos: :caption: scf-1a.inp basis def2-svp end scf charge 0 spin2p1 1 end grimmedisp type bj end mol Cl 1.40900 -0.54900 -0.14200 C 2.91800 0.22200 -0.14800 C 3.34900 1.18000 -0.99000 Cl 2.48900 1.91800 -2.24800 C 4.73000 1.60600 -0.53700 Cl 5.24600 3.22500 -0.97500 C 5.80600 0.51900 -0.74700 C 6.83600 -0.13400 -1.70000 C 6.40300 -1.62200 -1.82900 C 6.19900 -1.81300 -0.26300 C 7.62200 -1.50500 0.16600 O 8.02000 -0.22000 0.59300 C 8.09500 -0.42900 -0.82100 C 5.11900 -0.73000 -0.15200 C 4.07300 -0.11600 0.82100 Cl 3.68500 -1.10500 2.20000 C 4.50000 1.37200 1.05000 Cl 5.90100 1.54700 2.17100 Cl 3.22100 2.43400 1.80000 H 6.52400 1.00200 -0.09500 H 7.05500 0.38900 -2.63100 H 7.19900 -2.27000 -2.21800 H 5.50600 -1.77200 -2.43800 H 5.86900 -2.82100 -0.00200 H 8.25600 -2.36000 0.34800 H 9.03900 -0.55400 -1.32700 H 4.42500 -1.17200 -0.89200 end task energy b3lyp end .. tab:: scf-1b.inp .. code-block:: bash :linenos: :caption: scf-1b.inp basis def2-svp end scf charge 0 spin2p1 3 end grimmedisp type bj end mol Cl 1.40900 -0.54900 -0.14200 C 2.91800 0.22200 -0.14800 C 3.34900 1.18000 -0.99000 Cl 2.48900 1.91800 -2.24800 C 4.73000 1.60600 -0.53700 Cl 5.24600 3.22500 -0.97500 C 5.80600 0.51900 -0.74700 C 6.83600 -0.13400 -1.70000 C 6.40300 -1.62200 -1.82900 C 6.19900 -1.81300 -0.26300 C 7.62200 -1.50500 0.16600 O 8.02000 -0.22000 0.59300 C 8.09500 -0.42900 -0.82100 C 5.11900 -0.73000 -0.15200 C 4.07300 -0.11600 0.82100 Cl 3.68500 -1.10500 2.20000 C 4.50000 1.37200 1.05000 Cl 5.90100 1.54700 2.17100 Cl 3.22100 2.43400 1.80000 H 6.52400 1.00200 -0.09500 H 7.05500 0.38900 -2.63100 H 7.19900 -2.27000 -2.21800 H 5.50600 -1.77200 -2.43800 H 5.86900 -2.82100 -0.00200 H 8.25600 -2.36000 0.34800 H 9.03900 -0.55400 -1.32700 H 4.42500 -1.17200 -0.89200 end task energy b3lyp end .. tab:: scf-1c.inp .. code-block:: bash :linenos: :caption: scf-1c.inp basis def2-svp end scf charge +1 spin2p1 2 end grimmedisp type bj end mol Cl 1.40900 -0.54900 -0.14200 C 2.91800 0.22200 -0.14800 C 3.34900 1.18000 -0.99000 Cl 2.48900 1.91800 -2.24800 C 4.73000 1.60600 -0.53700 Cl 5.24600 3.22500 -0.97500 C 5.80600 0.51900 -0.74700 C 6.83600 -0.13400 -1.70000 C 6.40300 -1.62200 -1.82900 C 6.19900 -1.81300 -0.26300 C 7.62200 -1.50500 0.16600 O 8.02000 -0.22000 0.59300 C 8.09500 -0.42900 -0.82100 C 5.11900 -0.73000 -0.15200 C 4.07300 -0.11600 0.82100 Cl 3.68500 -1.10500 2.20000 C 4.50000 1.37200 1.05000 Cl 5.90100 1.54700 2.17100 Cl 3.22100 2.43400 1.80000 H 6.52400 1.00200 -0.09500 H 7.05500 0.38900 -2.63100 H 7.19900 -2.27000 -2.21800 H 5.50600 -1.77200 -2.43800 H 5.86900 -2.82100 -0.00200 H 8.25600 -2.36000 0.34800 H 9.03900 -0.55400 -1.32700 H 4.42500 -1.17200 -0.89200 end task energy b3lyp end In the output, we can find energies: .. tabs:: .. tab:: scf-1a.out .. code-block:: bash :linenos: :caption: scf-1a.out Mulliken Populations ==================== # Symbol Charge Spin ---------------------------------------------- 1 Cl -0.02667453 0.00000000 2 C 0.00442623 0.00000000 3 C 0.07960288 0.00000000 4 Cl -0.03329205 0.00000000 5 C -0.08518096 0.00000000 6 Cl -0.05476695 0.00000000 7 C 0.16951697 0.00000000 8 C -0.10715159 0.00000000 9 C 0.10427346 0.00000000 10 C -0.08217275 0.00000000 11 C 0.17187228 0.00000000 12 O -0.26857284 0.00000000 13 C 0.10869646 0.00000000 14 C 0.11543761 0.00000000 15 C 0.00080890 0.00000000 16 Cl -0.05286360 0.00000000 17 C -0.10222137 0.00000000 18 Cl -0.01739246 0.00000000 19 Cl -0.03082423 0.00000000 20 H 0.05649853 0.00000000 21 H -0.00112520 0.00000000 22 H 0.00490582 0.00000000 23 H 0.00613081 0.00000000 24 H -0.00349217 0.00000000 25 H 0.00514424 0.00000000 26 H 0.01085963 0.00000000 27 H 0.02755688 0.00000000 ---------------------------------------------- Sum 0.00000000 0.00000000 ---------------------------------------------- Electric Multipole Moments ========================== # Total Electronic Nuclear Unit ------------------------------------------------------------------------------------ Charge: 0 -0.0000 -190.0000 190.0000 |e| Dipole moment: X 1.5427 -4249.7734 4251.3161 Debye Y -3.0998 -516.9081 513.8084 Debye Z -2.9629 -61.9991 59.0362 Debye Total 4.5571 Debye Quadrupole moment: XX -131.6546 -23335.2658 23203.6113 Debye*Angstrom XY -18.9204 -1824.1358 1805.2154 Debye*Angstrom XZ -19.3935 -226.0675 206.6740 Debye*Angstrom YY -148.1762 -2656.8691 2508.6930 Debye*Angstrom YZ 0.3190 50.0250 -49.7060 Debye*Angstrom ZZ -149.5476 -2104.9692 1955.4216 Debye*Angstrom ------------------------------------------------------------------------------------ ---- Self Consistent Field Energy Done ------------------ Final total energy: -3297.20331257 Hartree .. tab:: scf-1b.out .. code-block:: bash :linenos: :caption: scf-1b.out Mulliken Populations ==================== # Symbol Charge Spin ---------------------------------------------- 1 Cl 0.00050242 0.06480421 2 C -0.02297255 0.42027475 3 C 0.04197140 0.41450595 4 Cl 0.00210632 0.06884730 5 C -0.07824196 -0.03692263 6 Cl -0.06050498 0.00369721 7 C 0.17682446 0.02328426 8 C -0.10859383 -0.00191029 9 C 0.10443565 0.00083317 10 C -0.08144729 0.00466281 11 C 0.17219425 0.00079567 12 O -0.26819454 0.00027313 13 C 0.10880086 0.00191331 14 C 0.11355660 0.01984239 15 C 0.00237412 -0.03673057 16 Cl -0.05782701 0.00045010 17 C -0.10605427 0.03134455 18 Cl -0.01706027 0.00709001 19 Cl -0.02178593 0.01323355 20 H 0.05573434 0.00106943 21 H -0.00089272 0.00053599 22 H 0.00453855 0.00011638 23 H 0.00534689 0.00001025 24 H -0.00360374 -0.00005744 25 H 0.00499224 0.00021128 26 H 0.01069384 0.00004035 27 H 0.02310712 -0.00221511 ---------------------------------------------- Sum -0.00000000 1.00000000 ---------------------------------------------- Electric Multipole Moments ========================== # Total Electronic Nuclear Unit ------------------------------------------------------------------------------------ Charge: 0 -0.0000 -190.0000 190.0000 |e| Dipole moment: X 1.2321 -4250.0840 4251.3161 Debye Y -3.0209 -516.8293 513.8084 Debye Z -3.0993 -62.1355 59.0362 Debye Total 4.5000 Debye Quadrupole moment: XX -133.5686 -23337.1799 23203.6113 Debye*Angstrom XY -19.1346 -1824.3499 1805.2154 Debye*Angstrom XZ -19.5174 -226.1914 206.6740 Debye*Angstrom YY -148.0570 -2656.7500 2508.6930 Debye*Angstrom YZ 0.5035 50.2094 -49.7060 Debye*Angstrom ZZ -149.1564 -2104.5779 1955.4216 Debye*Angstrom ------------------------------------------------------------------------------------ ---- Self Consistent Field Energy Done ------------------ Final total energy: -3297.07378259 Hartree .. tab:: scf-1c.out .. code-block:: bash :linenos: :caption: scf-1c.out Mulliken Populations ==================== # Symbol Charge Spin ---------------------------------------------- 1 Cl 0.15119087 0.05849971 2 C 0.02320835 0.10413699 3 C 0.11530715 0.10227274 4 Cl 0.14762665 0.06201522 5 C -0.10261555 -0.00892321 6 Cl 0.03049491 0.00815814 7 C 0.16533293 0.02207972 8 C -0.10602506 -0.00233488 9 C 0.09403621 0.00343824 10 C -0.08414937 0.00100276 11 C 0.18370650 0.02469158 12 O -0.24712743 0.01483155 13 C 0.12028486 0.02898236 14 C 0.08667493 0.01029275 15 C 0.00527258 -0.00828766 16 Cl 0.02762102 0.00448934 17 C -0.13876750 0.00141647 18 Cl 0.08563728 0.03050623 19 Cl 0.07042179 0.04061396 20 H 0.07885872 0.00024694 21 H 0.03698109 0.00296145 22 H 0.04565520 -0.00004484 23 H 0.02804737 0.00091680 24 H 0.03460665 0.00193844 25 H 0.05000090 -0.00137480 26 H 0.05564188 -0.00154950 27 H 0.04207709 -0.00097648 ---------------------------------------------- Sum 1.00000000 0.50000000 ---------------------------------------------- Electric Multipole Moments ========================== # Total Electronic Nuclear Unit ------------------------------------------------------------------------------------ Charge: 0 1.0000 -189.0000 190.0000 |e| Dipole moment: X 21.9659 -4229.3502 4251.3161 Debye Y -0.5347 -514.3431 513.8084 Debye Z -4.0803 -63.1165 59.0362 Debye Total 22.3481 Debye Quadrupole moment: XX -14.7654 -23218.3767 23203.6113 Debye*Angstrom XY -12.5519 -1817.7672 1805.2154 Debye*Angstrom XZ -22.8508 -229.5249 206.6740 Debye*Angstrom YY -129.2800 -2637.9729 2508.6930 Debye*Angstrom YZ -0.6554 49.0506 -49.7060 Debye*Angstrom ZZ -132.5362 -2087.9578 1955.4216 Debye*Angstrom ------------------------------------------------------------------------------------ ---- Self Consistent Field Energy Done ------------------ Final total energy: -3296.89315774 Hartree In the output files, we can find energies and propertiels like Mulliken charges and spins and electric multipole moments. We can calculate some energies: - Triple-singlet gap: ``-3297.07378259``-\ ``-3297.20331257`` = 3.52 eV; - Vertical electron detachment energy: ``-3296.89315774``-\ ``-3297.20331257`` = 8.44 eV; We can also visualize the molecular orbitals. Open `Qbics-MolStar `_, and drag ``scf-1a.mwfn`` into explorer, and it will be automatically loaded. Right-click :guilabel:`scf-1a.mwfn` and select :guilabel:`View Molecular Orbitals`, :guilabel:`95: -0.24732 (occ=2, RHF)`, then the HOMO of singlet state of dieldrin is visualized: .. figure:: /_images/scf-1.jpg Other wavefunction proterties can be visualized. For example, dragging ``scf-1b.mwfn`` into `Qbics-MolStar `_, and right-click :guilabel:`scf-1b.mwfn`, then click :guilabel:`View Other Wavefunction Properties`, in :guilabel:`Format`, click :guilabel:`Electron Spin Density`, you can see spin density of this system: .. figure:: /_images/scf-2.jpg These works are supported by `Multiwfn `_ in the backend. Please cite Multiwfn accoring to ``_ if you use these data. Example: TSO-DFT and BLE-DFT ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For a detailed tutorial, please refer to: - :doc:`scfguess` - :doc:`../tutorials/tso1` - :doc:`../tutorials/tso2` .. tip:: All input files can be downloaded: :download:`Files `. .. tip:: Please refer to :doc:`scf` for more examples. For a complete tutorial of TSO-DFT, please refer to: - :doc:`../tutorials/tso1` - :doc:`../tutorials/tso2` scfguess ======== .. contents:: :local: This option defines the initial guess of SCF calculations. Options ------------ .. contents:: :local: .. option:: type .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``hcore`` Will use the eigenvectors of the core matrix as initial guess. Usually, its performance is very bad * - - ``atmden`` Will use the superposition of converged densities of all atoms in the system as initial guess. It is recommended for most cases * - - ``fragden`` Will use the superposition of converged densities of fragments assigned by you as initial guess. This can be used for TSO or treating symmetry-broken systems * - - ``mwfn`` Will read a wave function from a MWFN file as initial guess * - - ``tso`` Will use a reference state (assigned with ``frag``) to perform TSO calculation (assigned with ``orb``). This is only used for TSO calculations * - Default - ``atmden`` Define the type of initial guess. In most cases, ``atmden`` is recommended. ``mwfn`` which reads a guess from a converged SCF is also a good choice. For target state optimization (TSO), symmetry-broken, or other special calculations, ``fragden`` can be used. .. option:: file .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A file name * - Default - job name + ``.mwfn`` When ``type`` is ``mwfn``, Qbics will read wave function with using mwfn file name. When ``type`` is ``tso``, Qbics will save reference wave function using this mwfn file name. .. option:: frag This defines atomic fragments for initial guess. The format is: ``frag num_electrons spin_multiplicity atom_range`` There can be arbitrary number of fragments, but all atoms must be included once and only once. They are only activated when ``type`` is ``fragden`` or ``tso``. For example: .. code-block:: bash :linenos: scfguess type fragden frag 0 1 1-9 frag 0 -3 10-15 18 frag -1 3 16 17 end In this case, the molecule is decomposed into 3 fragments: (1) atom 1,2,3,4,5,6,7,8,9, with charge 0 and spin multiplicity 1; (2) atom 10,11,12,13,14,15,18, with charge 0 and spin multiplicity 3 (beta orbitals occupied first); (3) atom 16,17, with charge -1 and spin multiplicity 3. For this guess, Qbics will perform 3 SCF calculations for all fragments, then superpose them as the initial guess for the SCF of the whole molecule. This can be used for ordinary, symmetry-broken, or TSO SCF. .. HINT:: The total charge of fragments does not have to be the same as the total system. .. HINT:: Please refer to the keyword ``no_scf`` in :doc:`scf` for more details about TSO, when you want to use ``frag``. .. option:: orb This defines the orbitals for initial guess. The format is: ``orb num_electrons spin_multiplicity alpha_MO_indices : beta_MO_indices`` There can be arbitrary number of orbital spaces, but all orbitals must be included once and only once. They are only activated when ``type`` is ``mwfn`` or ``tso``. For example: .. code-block:: bash :linenos: scfguess type mwfn file x.mwfn orb 12 1 1-6 : 1-6 orb 2 1 7 : 8 orb 0 1 8 : 7 end In this case, the orbitals will be read from ``x.mwfn`` and 3 orbital spaces are defined: (1) alpha orbital 1,2,3,4,5,6 and beta orbital 1,2,3,4,5,6, with 12 electron and spin multiplicity 1; (2) alpha orbital 7 and beta orbital 8, with 2 electrons and spin multiplicity 1; (3) alpha orbital 8 and beta orbital 7 with 0 electron and spin multiplicity 1 (since no electrons in this orbital space, actually spin multiplicity can be arbitrary). For this guess, Qbics will read orbitals from ``x.mwfn`` and assign occupation according to ``orb``, then do the following ordinary or TSO SCF calculations. Also, note that in this keyword, orbital order **matters**. For example, .. code-block:: bash :linenos: scfguess type mwfn file x.mwfn orb 14 1 1-6 9 7 8 10-25 : 1-6 9 7 8 10-25 end In this case, the 7 alpha and 7 beta electrons will occupy orbital 1,2,3,4,5,6,9. .. HINT:: Please refer to the keyword ``no_scf`` in :doc:`scf` for more details about TSO, when you want to use ``orb``. .. option:: ble This defines orbital occupations for a specific excited-state configuration. The format is: ``ble block_index alpha_occ_indices : beta_occ_indices`` - ``block_index`` must be **less than the number of blocks** (i.e., the number of ``orb`` commands used to define orbital blocks). - The ``ble`` keyword is only activated when ``type`` is set to ``mwfn`` or ``tso``. For example, .. code-block:: bash :linenos: scfguess type mwfn file x.mwfn orb 12 1 1-6 : 1-6 orb 2 1 7-8 : 7-8 ble 2 1 : 2 end In this example: - Orbitals are read from ``x.mwfn``. - Two orbital blocks are defined. - The ``ble`` keyword specifies the excitation configuration: - In block 2: alpha orbital 7 is occupied, and beta orbital 8 is occupied. - These correspond to occupation numbers `1` and `2`, respectively. If the ``ble`` keyword is **not used**, occupations will be assigned according to the `orb` specification. If ``ble`` **is used**, occupations are overridden and assigned based on `ble`. .. HINT:: Please refer to the keyword ``no_scf`` in :doc:`scf` for more details about BLE. Theoretical Background -------------------------------- XXXXXXX Input Examples -------------------- Example: Using Initial Guess of Neutral Dieldrin for Cationic Dieldrin ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In :doc:`scf`, we have shown hown to do SCF calculations for Dieldrin. For cationic dieldrin, the SCF took 24 cycles to converge. However, if we use the initial guess from the converged neutral dieldrin, the SCF will converge faster. To do this, we can use the following input: .. code-block:: bash :linenos: :caption: scfguess-1.inp basis def2-svp end scf charge +1 spin2p1 2 end scfguess type mwfn file scf-1a.mwfn end grimmedisp type bj end mol Cl 1.40900 -0.54900 -0.14200 C 2.91800 0.22200 -0.14800 C 3.34900 1.18000 -0.99000 Cl 2.48900 1.91800 -2.24800 C 4.73000 1.60600 -0.53700 Cl 5.24600 3.22500 -0.97500 C 5.80600 0.51900 -0.74700 C 6.83600 -0.13400 -1.70000 C 6.40300 -1.62200 -1.82900 C 6.19900 -1.81300 -0.26300 C 7.62200 -1.50500 0.16600 O 8.02000 -0.22000 0.59300 C 8.09500 -0.42900 -0.82100 C 5.11900 -0.73000 -0.15200 C 4.07300 -0.11600 0.82100 Cl 3.68500 -1.10500 2.20000 C 4.50000 1.37200 1.05000 Cl 5.90100 1.54700 2.17100 Cl 3.22100 2.43400 1.80000 H 6.52400 1.00200 -0.09500 H 7.05500 0.38900 -2.63100 H 7.19900 -2.27000 -2.21800 H 5.50600 -1.77200 -2.43800 H 5.86900 -2.82100 -0.00200 H 8.25600 -2.36000 0.34800 H 9.03900 -0.55400 -1.32700 H 4.42500 -1.17200 -0.89200 end task energy b3lyp end Here, in ``scfguess...end`` option, we set the initial guess ``type`` to ``mwfn`` and read the wave function from ``scf-1a.mwfn`` file, which is the converged neutral dieldrin. In ``scfguess-1.out``, you can see that the SCF will converge in 12 cycles, which is much faster than the 24 cycles without this initial guess. Example: Superposition of Fragment Density for [CH\ :sub:`3`\ NH\ :sub:`4`\ :sup:`+`][HSO\ :sub:`4`\ :sup:`-`] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Now we want to calculate the energy of a cantion-anion pair [CH\ :sub:`3`\ NH\ :sub:`4`\ :sup:`+`][HSO\ :sub:`4`\ :sup:`-`]. The total charge of the system is 0, so the input file can be given in ``scfguess-2a.inp``. However, chemical intuition tells us that an initial guess of superposition of CH\ :sub:`3`\ NH\ :sub:`4`\ :sup:`+` and HSO\ :sub:`4`\ :sup:`-` seems to be better. This can be given in ``scfguess-2b.inp``: .. tabs:: .. tab:: scfguess-2a.inp .. code-block:: bash :linenos: :caption: scfguess-2a.inp basis def2-svp end scf charge 0 spin2p1 1 end mol S -0.92132000 0.13553700 0.02022300 O -1.71190900 1.32700700 0.03005900 O -1.95455400 -1.09662200 -0.01287200 O -0.09369700 -0.02457400 -1.18931900 O -0.13508200 -0.13905500 1.21845100 N 2.13478700 -0.64814300 -0.03200000 C 3.06391300 0.49644100 0.01002200 H -2.74409400 -0.79280600 -0.47259900 H 1.37775700 -0.50028000 -0.76845000 H 1.50266300 -0.65123600 0.79672500 H 3.62254900 0.54819100 -0.92118700 H 3.74619000 0.39302500 0.85034900 H 2.46986400 1.39919200 0.12858400 H 2.60115300 -1.54036700 -0.14368500 end task energy b3lyp end .. tab:: scfguess-2b.inp .. code-block:: bash :linenos: :caption: scfguess-2b.inp basis def2-svp end scf charge 0 spin2p1 1 end scfguess type fragden frag -1 1 1-5 8 frag +1 1 6 7 9-14 end mol S -0.92132000 0.13553700 0.02022300 O -1.71190900 1.32700700 0.03005900 O -1.95455400 -1.09662200 -0.01287200 O -0.09369700 -0.02457400 -1.18931900 O -0.13508200 -0.13905500 1.21845100 N 2.13478700 -0.64814300 -0.03200000 C 3.06391300 0.49644100 0.01002200 H -2.74409400 -0.79280600 -0.47259900 H 1.37775700 -0.50028000 -0.76845000 H 1.50266300 -0.65123600 0.79672500 H 3.62254900 0.54819100 -0.92118700 H 3.74619000 0.39302500 0.85034900 H 2.46986400 1.39919200 0.12858400 H 2.60115300 -1.54036700 -0.14368500 end task energy b3lyp end In ``scfguess-2b.inp``, the fragment initial guess is set using .. code-block:: bash :linenos: :caption: scfguess-2b.inp scfguess type fragden frag -1 1 1-5 8 frag +1 1 6 7 9-14 end Here, the atomic indices of CH\ :sub:`3`\ NH\ :sub:`4`\ :sup:`+` and HSO\ :sub:`4`\ :sup:`-` are given in ``1-5 8`` and ``6 7 9-14``, respectively, and charges and spin multiplicities are also given. The atomic indices are shown below: .. figure:: /_images/scfguess-1.jpg In their output ``scfguess-2a.out`` and ``scfguess-2b.out``, both give the same energy, but the SCF cycles are 25 and 11, respectively. Thus, superposition of fragments is indeed a better initial guess. Also, we can check the Mulliken population of this system: .. code-block:: bash :linenos: :caption: scfguess-2b.out Mulliken Populations ==================== # Symbol Charge Spin ---------------------------------------------- 1 S 1.06432061 0.00000000 2 O -0.48154427 0.00000000 3 O -0.35593323 0.00000000 4 O -0.56975508 0.00000000 5 O -0.56231274 0.00000000 6 N -0.03632083 0.00000000 7 C 0.05819466 0.00000000 8 H 0.18495781 0.00000000 9 H 0.18311761 0.00000000 10 H 0.17532487 0.00000000 11 H 0.05607280 0.00000000 12 H 0.05428454 0.00000000 13 H 0.07504981 0.00000000 14 H 0.15454343 0.00000000 ---------------------------------------------- Sum -0.00000000 0.00000000 ---------------------------------------------- We can see that, the sum of Mulliken charge on CH\ :sub:`3`\ NH\ :sub:`4`\ :sup:`+` and HSO\ :sub:`4`\ :sup:`-` are +0.72 and -0.72, respectively, being quite different from their ideal value +1 and -1. This is actually the electron delocalization effect. Example: Diatatic State of [CH\ :sub:`3`\ NH\ :sub:`4`\ :sup:`+`][HSO\ :sub:`4`\ :sup:`-`] with TSO-DFT ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. tip:: For a complete tutorial of TSO-DFT, please refer to: - :doc:`../tutorials/tso1` - :doc:`../tutorials/tso2` In the last example, we have calculated [CH\ :sub:`3`\ NH\ :sub:`4`\ :sup:`+`][HSO\ :sub:`4`\ :sup:`-`], where electron is delocalzied over the entire cluster. Can we calculate a state where all electrons are strictly localzied on each molecule? This can be done easily with Qbics. Such state can be called a **diabatic state.** Diabatic state can be calculated with TSO-DFT method, which can be done with ``scfguess-3.inp``: .. code-block:: bash :linenos: :caption: scfguess-3.inp basis def2-svp end scf charge 0 spin2p1 1 no_scf tso type U # This must be given for TSO calculation. end scfguess type fragden frag -1 1 1-5 8 frag +1 1 6 7 9-14 end mol S -0.92132000 0.13553700 0.02022300 O -1.71190900 1.32700700 0.03005900 O -1.95455400 -1.09662200 -0.01287200 O -0.09369700 -0.02457400 -1.18931900 O -0.13508200 -0.13905500 1.21845100 N 2.13478700 -0.64814300 -0.03200000 C 3.06391300 0.49644100 0.01002200 H -2.74409400 -0.79280600 -0.47259900 H 1.37775700 -0.50028000 -0.76845000 H 1.50266300 -0.65123600 0.79672500 H 3.62254900 0.54819100 -0.92118700 H 3.74619000 0.39302500 0.85034900 H 2.46986400 1.39919200 0.12858400 H 2.60115300 -1.54036700 -0.14368500 end task energy b3lyp end We just need to add ``no_scf tso`` to ``scf...end``, and give fragment definition in ``scfguess...end``. Also, you must explicitly write ``type U`` to enforce unrestricted SCF. Such method can be called TSO-B3LYP. In the output ``scfguess-3.out``: .. code-block:: bash :linenos: :caption: scfguess-3.out Mulliken Populations ==================== # Symbol Charge Spin ---------------------------------------------- 1 S 1.05819195 -0.00000000 2 O -0.49810728 0.00000000 3 O -0.36249350 -0.00000000 4 O -0.71399133 0.00000000 5 O -0.66324621 -0.00000000 6 N -0.09172438 -0.00000000 7 C 0.05015632 0.00000000 8 H 0.17964637 0.00000000 9 H 0.35411645 0.00000000 10 H 0.29719708 0.00000000 11 H 0.06307774 -0.00000000 12 H 0.06123412 -0.00000000 13 H 0.09862277 -0.00000000 14 H 0.16731989 0.00000000 ---------------------------------------------- Sum -0.00000000 -0.00000000 ---------------------------------------------- ..omitted.. Final total energy: -795.63743617 Hartree We can see that, the sum of Mulliken charge on CH\ :sub:`3`\ NH\ :sub:`4`\ :sup:`+` and HSO\ :sub:`4`\ :sup:`-` are +1 and -1. So we have successfully obtained the diabatic state we need. Also, its energy ``-795.63743617 Hartree`` is higher than the one obatained from ``scfguess-2b.out``: ``-795.67538949 Hartree``. Their difference ``-795.67538949 Hartree``-\ ``-795.63743617 Hartree`` = 23.82 kcal/mol is actually the ``Charge transfer interaction energy`` without BSSE correction defined in TSO-EDA, which can be calculated with :doc:`eda`. The following input: .. code-block:: bash :linenos: :caption: scfguess-3eda.inp basis def2-svp end scf charge 0 spin2p1 1 type U # This must be given. end eda type tso frag -1 1 1-5 8 frag +1 1 6 7 9-14 end mol S -0.92132000 0.13553700 0.02022300 O -1.71190900 1.32700700 0.03005900 O -1.95455400 -1.09662200 -0.01287200 O -0.09369700 -0.02457400 -1.18931900 O -0.13508200 -0.13905500 1.21845100 N 2.13478700 -0.64814300 -0.03200000 C 3.06391300 0.49644100 0.01002200 H -2.74409400 -0.79280600 -0.47259900 H 1.37775700 -0.50028000 -0.76845000 H 1.50266300 -0.65123600 0.79672500 H 3.62254900 0.54819100 -0.92118700 H 3.74619000 0.39302500 0.85034900 H 2.46986400 1.39919200 0.12858400 H 2.60115300 -1.54036700 -0.14368500 end task eda b3lyp end At the end of the output ``scfguess-3eda.out``: .. code-block:: bash :linenos: :caption: scfguess-3eda.out Target State Optimized Wavefunction Energy Decomposition Analysis ================================================================= WITHOUT BSSE correction: Electrostatic interaction energy: -129.90 kcal/mol Exchange-correlation interaction energy: 35.20 kcal/mol Polarization interaction energy: -13.18 kcal/mol Charge transfer interaction energy: -23.82 kcal/mol Grimme's dispersion interaction: 0.00 kcal/mol ---------------------------------------------------------------- Total interaction energy: -131.69 kcal/mol WITH BSSE correction: Electrostatic interaction energy: -129.90 kcal/mol Exchange-correlation interaction energy: 35.20 kcal/mol Polarization interaction energy: -13.18 kcal/mol Charge transfer interaction energy: -16.31 kcal/mol Grimme's dispersion interaction: 0.00 kcal/mol ---------------------------------------------------------------- Total interaction energy: -124.18 kcal/mol Line 7 says ``Charge transfer interaction energy: -23.82 kcal/mol``, which is exactly the same value as we calculated. Example: TSO-DFT for Doubly Excited States of HCHO ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. tip:: For a complete tutorial of TSO-DFT, please refer to: - :doc:`../tutorials/tso1` - :doc:`../tutorials/tso2` As mentioned above, TSO-DFT can be used to study diabatic states. It can also be used to study excited states. Here, we demonstrate how to use TSO-DFT to calculate a doubly excitated state of HCHO. We consider HOMO\ :sup:`2` → LUMO\ :sup:`2`: .. code-block:: bash :linenos: :caption: scfguess-4a.inp basis element H cc-pVTZ C cc-pCVTZ O cc-pCVTZ end scf charge 0 spin2p1 1 type U # For TSO-DFT, unrestricted SCF is preferred. no_scf TSO end scfguess type tso file hcho-ref.mwfn frag 0 1 1-4 orb 16 1 1-7 9-114 : 1-7 9-114 orb 0 1 8 : 8 end mol C -0.000756 -0.520733 0. H 0.935697 -1.111766 0. H -0.939631 -1.107897 0. O 0.001792 0.678123 0 end task energy b3lyp end Here: - Line 16: Set ``type`` to ``tso`` enable special initial guess for TSO-DFT; - Line 17: The reference wavefunction (ground state of HCHO) is saved to ``hcho-ref.mwfn``; - Line 18: Define the reference state. Here, the whole molecule is treated as the reference state; - Line 19,20: Define the orbital spaces to set up the required excited state as explained above. After calculation, you can find these lines in ``scfguess-4a.out``: .. code-block:: bash :linenos: :caption: scfguess-4a.out TSO Transition ============== Reference wave function read from: hcho-ref.mwfn Reference energy: -114.55175800 Hartree Current energy: -114.15907196 Hartree E(Current)-E(Ref): 10.68553145 eV Transition dipole moment (Debye): 0.00000 0.00000 0.00000 Oscillator strength: 0.00000 Higher order corrections: Transition quadrupole moment (Debye*Angstrom): Qxx: 0.00000; Qyy: 0.00000; Qzz: 0.00000 Qxy: 0.00000; Qxz: 0.00000; Qyz: 0.00000 Quadrupole correction to oscillator strength: 0.00000E+00 Transition angular momentum (au): 0.00000 0.00000 0.00000 Magnetic dipole correction to oscillator strength: 0.00000E+00 ---- Self Consistent Field Energy Done ------------------ Final total energy: -114.15907196 Hartree The double excitation energy is ``10.68 eV``, which agrees well with the one obtained from EOM-CC (10.34 eV). Note that, by changing ``energy`` in ``scfguess-4a.inp`` to ``opt``, you can do geometry optimization for this excited state! You can also use an MWFN file as the initial guess to do TSO-DFT calculation: .. code-block:: bash :linenos: :caption: scfguess-4b.inp basis element H cc-pVTZ C cc-pCVTZ O cc-pCVTZ end scf charge 0 spin2p1 1 type U # For TSO-DFT, unrestricted SCF is preferred. no_scf TSO end scfguess type mwfn file hcho-ref.mwfn orb 16 1 1-7 9-114 : 1-7 9-114 orb 0 1 8 : 8 end mol C -0.000756 -0.520733 0. H 0.935697 -1.111766 0. H -0.939631 -1.107897 0. O 0.001792 0.678123 0 end task energy b3lyp end Note that we have deleted ``frag 0 1 1-4`` since reference wavefucntion is already given in ``hcho-ref.mwfn``. The obtained energy in ``scfguess-4b.out`` is exactly the same as in ``scfguess-4a.out``. .. tip:: All input files can be downloaded: :download:`Files `. tddft ======= .. contents:: :local: This keyword defines how to perform time-dependent DFT (TDDFT) calculation. Options ------------ .. option:: type .. list-table:: :stub-columns: 1 * - Value - ``TDDFT`` Standard TDDFT. * - - ``TDA`` TDDFT with Tamm-Dancoff approximation (TDA). * - - ``RTDDFT`` Restricted TDDFT. * - - ``UTDDFT`` Unrestricted TDDFT. * - - ``XTDDFT`` Spin-adaptive TDDFT. * - - ``RTDA`` Restricted TDA. * - - ``UTDA`` Unrestricted TDA. * - - ``XTDA`` Spin-adaptive TDA. * - Default - ``TDDFT`` The type of TDDFT calculations. TDA is an approximate case of TDDFT. For closed-shell systems, ``RTDDFT`` and ``RTDA`` are the best choices. For closed- and open-shell systems, ``UTDDFT`` and ``UTDA`` are available. For open-shell systems, ``XTDDFT`` and ``XTDA`` are also available. If ``TDDFT`` or ``TDA`` is used, a suitable method will be automatically selected. .. option:: spin_flip .. list-table:: :stub-columns: 1 * - Value - ``None`` No spin flipping is performed. * - - ``Up`` Flip beta electrons to alpha ones. * - - ``Down`` Flip alpha electrons to beta ones. * - Default - ``None`` Spin flipping way for the excited states. .. option:: num_states .. list-table:: :stub-columns: 1 * - Value - An integer. * - Default - ``5`` The number of excited states to be calculated. .. option:: max_it .. list-table:: :stub-columns: 1 * - Value - An integer. * - Default - ``100`` The maximum number of Davidson iterations for the TDDFT calculation. If TDDFT fails to converge, you can try to increase this number. .. option:: dim_trials .. list-table:: :stub-columns: 1 * - Value - An integer. * - Default - ``50`` The maximum dimension of trial vectors. If TDDFT fails to converge, you can try to increase this number. .. option:: energy_cov .. list-table:: :stub-columns: 1 * - Value - A real number. * - Default - ``1.E-7`` The energy convergence threshold for the TDDFT calculation. .. option:: vec_cov .. list-table:: :stub-columns: 1 * - Value - A real number. * - Default - ``1.E-5`` The excited state vector convergence threshold for the TDDFT calculation. .. option:: precondition_threshold .. list-table:: :stub-columns: 1 * - Value - A real number. * - Default - ``1.E-8`` The precondition convergence threshold for the TDDFT calculation. .. option:: print_coeff_threshold .. list-table:: :stub-columns: 1 * - Value - A real number. * - Default - ``0.01`` Print the excited state coefficients when the absolute value is larger than this threshold. .. option:: transxtdvec Transform the excited state vectors from alpha/beta to spin-adapted ones. Theoretical Background ------------------------- Time-dependent DFT (TDDFT) is a powerful tool for studying the electronic structure of molecules and materials. It is a time-dependent extension of density functional theory (DFT), which allows for the calculation of excited states and transition properties. Input Examples -------------------- Example: TDDFT Calculation of HCHO ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this example, we will perform a TDDFT calculation of HCHO at TD-B3LYP/cc-pVTZ level of theory. The input file is as follows: .. code-block:: :caption: tddft-1.inp :linenos: basis cc-pvtz end scf charge 0 spin2p1 1 type R end mol C -0.000756 -0.520733 0. H 0.935697 -1.111766 0. H -0.939631 -1.107897 0. O 0.001792 0.678123 0 end tddft type tddft num_states 10 max_it 100 dim_trials 50 print_coeff_threshold 0.01 end task tddft b3lyp end After running the calculation, you will find the following lines: .. code-block:: :caption: tddft-1.out :linenos: #1: Absolute energy = -114.39668857 Hartree Excited energy = 4.1600 eV; wavelength = 298.04 nm, oscillator strength = 0.0000 Transition dipole moment (a.u.): -0.00000 -0.00000 -0.00000 CV(0) 8 --> 9: Coefficient = -0.9512, Percentage = 99.7 %, IPA = 6.0538 eV #2: Absolute energy = -114.26455102 Hartree Excited energy = 7.7556 eV; wavelength = 159.86 nm, oscillator strength = 0.0917 Transition dipole moment (a.u.): 0.69575 -0.00144 -0.00000 CV(0) 8 --> 10: Coefficient = 0.9803, Percentage = 99.1 %, IPA = 8.7346 eV #3: Absolute energy = -114.20726662 Hartree Excited energy = 9.3144 eV; wavelength = 133.11 nm, oscillator strength = 0.0004 Transition dipole moment (a.u.): 0.00000 -0.00000 0.03936 CV(0) 6 --> 9: Coefficient = 0.9615, Percentage = 99.0 %, IPA = 11.0312 eV You can find excited state energies, oscillator strengths, transition dipole moments, and orbital transition coefficients. You can also find the spectrum file ``tddft-1-spectrum.txt``. .. code-block:: :caption: tddft-1-spectrum.txt :linenos: # Energy/Hartree dE/eV Osc.Str. DX/a.u. DY/a.u. DZ/a.u. 1 -114.39668857 4.160 0.00000 -0.00000 -0.00000 -0.00000 2 -114.26455102 7.756 0.09170 0.69575 -0.00144 -0.00000 3 -114.20726662 9.314 0.00035 0.00000 -0.00000 0.03936 4 -114.20671875 9.329 0.01909 0.00061 0.28940 0.00000 5 -114.18117786 10.024 0.02217 0.30091 -0.00062 0.00000 6 -114.16908782 10.353 0.00000 -0.00000 -0.00000 -0.00000 7 -114.16561892 10.448 0.32962 0.00236 1.13648 0.00000 8 -114.13865859 11.181 0.01049 -0.00000 -0.00000 -0.19601 9 -114.08206773 12.721 0.00000 -0.00000 0.00000 0.00004 10 -114.08073037 12.758 0.05235 -0.00083 -0.40988 -0.00000 You can plot the spectrum using a script provided by Qbics, i.e., ``tools/plotspec.py``. Copy this file to the same directory as the input file, and modify the following parameters: .. code-block:: python :caption: plotspec.py :linenos: if __name__ == "__main__": fn = "tddft-1-spectrum.txt" # Spectrum file name. eL_eV = 4 # Lower energy limit. eH_eV = 13 # Higher energy limit. sigma_eV = 0.2 # Sigma value. num_ps = 500 # Number of points. use_angle = False # Whether to use angle dependence. incident_angles = [i*30 for i in range(4)] # Incident angles. - Line 2: Change the spectrum file name. - Line 3,4: Change the lower and upper energy limit. - Line 5: Change the sigma value. - Line 6: Change the number of points. The larger the number, the smoother the spectrum. - Line 7: Whether to use angle dependence. - Line 8: Incident angles. Then, you can run the script using the following command: .. code-block:: bash :caption: plotspec.py :linenos: $ python plotspec.py You will find following spectrum plot: .. figure:: /_images/tddft-1.jpg .. tip:: All input files can be downloaded: :download:`Files `. thermo ========= .. contents:: :local: This keyword defines the parameters for thermodynamic analysis based on frequency calculation results. Options ------------ .. option:: temp .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``298.15`` The temperature (in Kelvin) for thermodynamic analysis. The default value is ``298.15`` K. .. option:: pressure .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.`` The pressure (in atm) for thermodynamic analysis. The default value is ``1.0`` atm. .. option:: point_group_delta .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``0.01`` A threshold to determine the point group of the molecule. The default value is ``0.01``. The smaller ``point_group_delta``, the more accurate the symmetry point group will be determined. However, a very small value may lead to failure in point group determination. If you encounter such problem, please increase this value gradually (e.g., to ``0.1``). Theoretical Background ------------------------- Input Examples -------------------- Example: XXXXXXX ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. tip:: All input files can be downloaded: :download:`Files `. wfn ====== .. contents:: :local: This keyword controls the details of wave function analysis. Options ------------ .. option:: file .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - File name * - Default - None The file name of the wave function to be analyzed (in MWFN format). .. option:: loc_max_it .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``500`` The maximum number of steps for orbital localization. .. option:: loc_cov .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``1.E-6`` The convergence threshold for orbital localization. .. option:: print_MO_details When this keyword is presented, much more information will be output for orbital component analysis. Theoretical Background -------------------------------- In Qbics, quantum chemical calculations will produce a wavefunction and store it in a MWFN file. This is a format that contains all the information about the wavefunction, including the molecular coordinates and orbitals. Qbics can read this file and perform some simple wavefunction analysis: - **Orbital localization**: The wavefunction can be localized on atoms. Qbics uses Boys algorithm. - **Orbital component analysis**: The wavefunction can be analyzed in terms of the atomic orbitals. For more kinds of wavefunction analysis, one can use `Qbics-MolStar `_, which uses `Multiwfn `_ as the backend. Please refer to ``_ for more details and correct citation. Input Examples -------------------- Example: Wavefunction Analysis for CH\ :sub:`2`\ O ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Now we perform a wavefunction analysis for CH\ :sub:`2`\ O. The input file is as follows: .. code-block:: bash :linenos: :caption: wfn-1.inp basis def2-tzvp end wfn file wfn-1.mwfn # The file name. print_MO_details # Print more information. end mol O -0.00000001 -0.00000000 1.44310862 C -0.00000001 -0.00000000 0.24425258 H 0.00000004 0.93861213 -0.34368060 H -0.00000002 -0.93861212 -0.34368059 end task energy b3lyp # Do an energy calculation and generate wavefunction file: wfn-1.mwfn wfn # Do analysis. end AFter calculation, there will be 2 MWFN files - ``wfn-1.mwfn``: Stores the original canonical molecular orbitals; - ``wfn-1-loc.mwfn``: Stores the localized molecular orbitals. The output file also contains atomic orbital components: .. code-block:: bash :linenos: :caption: wfn-1.out Molecular orbitals: # Occ O1 C2 H3 H4 total S P D F total S P D F total S P D F total S P D F 1 2.000 0.9997 0.9989 0.0008 0.0000 0.0000 0.0003 0.0001 0.0001 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 2 2.000 0.0009 0.0004 0.0005 0.0000 0.0000 0.9987 0.9986 0.0001 0.0000 0.0000 0.0002 0.0002 0.0000 0.0000 0.0000 0.0002 0.0002 0.0000 0.0000 0.0000 3 2.000 0.9743 0.7996 0.1746 0.0001 0.0000 0.0254 0.0195 0.0058 0.0001 0.0000 0.0001 0.0001 0.0000 0.0000 0.0000 0.0001 0.0001 0.0000 0.0000 0.0000 4 2.000 0.0168 0.0028 0.0138 0.0002 0.0000 0.5906 0.2875 0.3020 0.0011 0.0000 0.3588 0.3571 0.0017 0.0000 0.0000 0.0338 0.0337 0.0001 0.0000 0.0000 5 2.000 0.0168 0.0028 0.0138 0.0002 0.0000 0.5906 0.2875 0.3020 0.0011 0.0000 0.0338 0.0337 0.0001 0.0000 0.0000 0.3588 0.3571 0.0017 0.0000 0.0000 6 2.000 0.5884 0.1161 0.4708 0.0014 0.0000 0.4027 0.1686 0.2318 0.0020 0.0003 0.0044 0.0044 0.0001 0.0000 0.0000 0.0044 0.0044 0.0001 0.0000 0.0000 7 2.000 0.6737 0.0000 0.6716 0.0021 0.0001 0.3259 0.0000 0.3233 0.0024 0.0002 0.0002 0.0000 0.0002 0.0000 0.0000 0.0002 0.0000 0.0002 0.0000 0.0000 8 2.000 0.8530 0.0000 0.8519 0.0010 0.0001 0.0327 0.0000 0.0282 0.0044 0.0001 0.0572 0.0571 0.0000 0.0000 0.0000 0.0572 0.0571 0.0000 0.0000 0.0000 9 0.000 0.4390 0.0000 0.3370 0.0959 0.0061 0.5510 0.0000 0.3801 0.1369 0.0340 0.0050 0.0000 0.0050 0.0000 0.0000 0.0050 0.0000 0.0050 0.0000 0.0000 10 0.000 0.0122 0.0007 0.0114 0.0001 0.0000 0.4747 0.3168 0.1506 0.0060 0.0013 0.5084 0.4970 0.0113 0.0000 0.0000 0.0047 0.0046 0.0001 0.0000 0.0000 11 0.000 0.4033 0.3157 0.0827 0.0049 0.0001 0.5946 0.3464 0.2090 0.0375 0.0018 0.0010 0.0010 0.0000 0.0000 0.0000 0.0010 0.0010 0.0000 0.0000 0.0000 12 0.000 0.0122 0.0007 0.0114 0.0001 0.0000 0.4747 0.3168 0.1506 0.0060 0.0013 0.0047 0.0046 0.0001 0.0000 0.0000 0.5084 0.4970 0.0113 0.0000 0.0000 13 0.000 0.0222 0.0053 0.0167 0.0001 0.0000 0.7300 0.5137 0.2093 0.0054 0.0016 0.2469 0.2432 0.0037 0.0000 0.0000 0.0010 0.0009 0.0001 0.0000 0.0000 14 0.000 0.3324 0.0000 0.1867 0.1329 0.0128 0.6647 0.0000 0.1752 0.3333 0.1562 0.0015 0.0000 0.0015 0.0000 0.0000 0.0015 0.0000 0.0015 0.0000 0.0000 15 0.000 0.0222 0.0053 0.0167 0.0001 0.0000 0.7300 0.5137 0.2093 0.0054 0.0016 0.0010 0.0009 0.0001 0.0000 0.0000 0.2469 0.2432 0.0037 0.0000 0.0000 ... Quantitative atomic contributions for molecular orbitals: Molecular orbitals: 1, occ = 2.000, over 1 centers: O1(99.97%), ==> S(99.91%) + P(0.09%) + D(0.00%) + F(0.00%) 2, occ = 2.000, over 1 centers: C2(99.87%), ==> S(99.93%) + P(0.07%) + D(0.00%) + F(0.00%) 3, occ = 2.000, over 1 centers: O1(97.43%), ==> S(81.93%) + P(18.04%) + D(0.02%) + F(0.00%) 4, occ = 2.000, over 2 centers: C2(59.06%), H3(35.88%), ==> S(68.11%) + P(31.75%) + D(0.13%) + F(0.00%) 5, occ = 2.000, over 2 centers: C2(59.06%), H4(35.88%), ==> S(68.11%) + P(31.75%) + D(0.13%) + F(0.00%) 6, occ = 2.000, over 2 centers: O1(58.84%), C2(40.27%), ==> S(29.35%) + P(70.27%) + D(0.34%) + F(0.04%) 7, occ = 2.000, over 2 centers: O1(67.37%), C2(32.59%), ==> S(0.00%) + P(99.53%) + D(0.45%) + F(0.03%) 8, occ = 2.000, over 1 centers: O1(85.30%), ==> S(11.42%) + P(88.03%) + D(0.53%) + F(0.02%) 9, occ = 0.000, over 2 centers: O1(43.90%), C2(55.10%), ==> S(0.00%) + P(72.70%) + D(23.28%) + F(4.02%) 10, occ = 0.000, over 2 centers: C2(47.47%), H3(50.84%), ==> S(81.91%) + P(17.35%) + D(0.60%) + F(0.14%) 11, occ = 0.000, over 2 centers: O1(40.33%), C2(59.46%), ==> S(66.41%) + P(29.17%) + D(4.24%) + F(0.18%) 12, occ = 0.000, over 2 centers: C2(47.47%), H4(50.84%), ==> S(81.91%) + P(17.35%) + D(0.60%) + F(0.14%) 13, occ = 0.000, over 2 centers: C2(73.00%), H3(24.69%), ==> S(76.31%) + P(22.98%) + D(0.55%) + F(0.16%) For example, Line 11 and 30 shows that the molecular orbital ``8`` has an occupation number of ``2.000`` and is localized on the oxygen atom (O1) with a contribution of ``85.30%``. The orbital is mainly composed of the s orbital (``11.42%``) and p orbital (``88.03%``). This is actually an electron lone pair orbital. Using `Qbics-MolStar `_ to open ``wfn-1.mwfn`` and ``wfn-1-loc.mwfn``, we can visualize the canonical and localized orbitals. For example, right-click :guilabel:`wfn-1.mwfn` and select :guilabel:`View Molecular Orbitals`, then select the orbital you want to visualize. Below is an example. Obviously, the canonical orbital is delocalized over the molecule while the localized one is only localized over a bond. .. figure:: /_images/wfn-1.jpg .. tip:: All input files can be downloaded: :download:`Files `. xtb ====== .. contents:: :local: This keyword controls the xTB calculation options. Options ------------ .. contents:: :local: .. option:: chrg .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``0`` The total charge of the system. .. option:: uhf .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - An integer * - Default - ``0`` The number of unpaired electrons. .. option:: gfn .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``1`` The GFN1-xTB Hamiltonian. * - - ``2`` The GFN2-xTB Hamiltonian. * - Default - ``2`` Define the xTB Hamiltonian type. .. option:: gbsa .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - ``H2O`` * - - ``Acetone`` * - - ``Acetonitrile`` * - - ``Benzene`` * - - ``CH2Cl2`` * - - ``CHCl3`` * - - ``CS2`` * - - ``DMSO`` * - - ``Ether`` * - - ``Hexane`` * - - ``Toluene`` * - - ``THF`` * - Default - None The solvent name. If it is not given, the xTB is calculated in the gas phase. Otherwise, generalized Born model will be used to consider solvent effects. .. option:: etemp .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A real number * - Default - ``300`` The electronic temperature in Kelvin. .. option:: vparam .. list-table:: :stub-columns: 1 :widths: 5 20 * - Value - A file name for the xTB parameter file. * - Default - None If not given, the default parameters stored internally in Qbics will be used. If a file name (path can be included) is given, the xTB calculation will use the parameters in this file. Theoretical Background -------------------------------- xTB is a powerful semiempirical quantum chemical method proposed by Stefan Grimme. It has been designed for the purpose of facilitating rapid and accurate electronic structure calculations of large molecular systems (approximately 1000 atoms). It can be used to rapidly give good initial guess for DFT calculations. xTB has several Hamiltonians. Qbics supports GFN-1 and GFN-2. It seems that: - GFN1-xTB: When a system contains **metal cluster**-like structures, this is better. - GFN2-xTB: For most organic molecules with no or a few metal atoms. To consider solvent effects, one can use ``gbsa``. xTB can also work with CHARMM force field, i.e., xTB/MM method. This is a powerful way to study large, complicated systems. For all features of xTB method, please refer to the `xTB manual `_. Input Examples -------------------- In all examples below, you can change ``opt`` to ``md`` to do molecular dynamics. Example: Geometry Optimization by GFN2-xTB for Cantharidin ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Perform geometry optimization by GFN2-xTb for an organic molecule cantharidin: .. code-block:: bash :linenos: :caption: xtb-1.inp xtb chrg 0 gfn 2 # GFN2-xTB. end # Cantharidin mol C 1.39900 0.71500 1.06800 C 1.92100 -0.06900 -0.14800 C 0.78600 -0.69800 -1.04400 C 0.13800 -2.16200 -0.87800 C 1.29700 -3.05700 -0.50500 C 2.44700 -2.21000 -1.00400 O 1.70700 -1.35300 -1.91200 C 2.98300 -1.16300 -0.03500 C 3.42500 -1.73000 1.31300 C 4.18700 -0.54700 -0.69400 O 5.29000 -1.08800 -0.78200 O 3.91700 0.65900 -1.20900 C 2.61300 0.98300 -0.99400 O 2.10200 2.01700 -1.40000 H 0.94400 0.07300 1.82400 H 0.61300 1.41400 0.73300 H 2.16400 1.34500 1.53700 H 0.05600 -0.55500 -0.22800 H -0.28600 -2.46400 -1.85300 H -0.70400 -2.25200 -0.17500 H 1.22700 -4.00600 -1.04600 H 1.31500 -3.28300 0.56100 H 3.20900 -2.78100 -1.54000 H 2.64400 -2.28900 1.83300 H 3.79300 -0.95400 1.99200 H 4.26100 -2.43200 1.16600 end task opt xtb end Example: Geometry Optimization by GFN1-xTB for Co\ :sub:`6`\ Te\ :sub:`8`\ (P(Et)\ :sub:`3`\ )\ :sub:`6` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Perform geometry optimization by GFN1-xTB for a quantum dot Co\ :sub:`6`\ Te\ :sub:`8`\ (P(Et)\ :sub:`3`\ )\ :sub:`6`. For such inorganic systems, GFN2-xTB may not converge. .. code-block:: bash :linenos: :caption: xtb-2.inp xtb chrg 0 gfn 1 # GFN1-xTB. Do you want to try GFN2-xTB? end # Quantum dot: Co6Te8(P(Et)3)6 mol Co 0.07482 0.19972 2.25274 Co -0.57236 2.10842 -0.12184 Co 2.14275 0.01139 -0.00690 Co 0.05260 -2.18506 -0.00075 Co -0.03312 0.01926 -2.21965 Co -2.27062 -0.26857 0.13243 Te -1.92498 1.48104 1.75344 Te 1.51638 1.80079 -1.53651 Te -1.62601 -1.71313 -1.72073 Te -1.37710 -1.68992 1.91428 Te 1.61324 -1.60191 1.77284 Te -2.00357 1.32469 -1.66240 Te 1.66650 -1.63285 -1.74916 Te 1.57938 1.94121 1.38532 P -4.02850 -1.49064 0.26273 C -5.19829 -1.41084 -1.21441 H -4.71377 -1.92702 -2.04886 H -6.13262 -1.93467 -0.99467 C -5.52751 0.01728 -1.64482 H -6.14156 0.00324 -2.54679 H -6.07317 0.54663 -0.86250 H -4.61066 0.57223 -1.85793 C -5.30003 -1.10968 1.60881 H -5.85560 -0.21489 1.31212 H -6.02467 -1.92631 1.68168 C -4.67909 -0.85880 2.97985 H -5.45790 -0.66760 3.72007 H -4.08936 -1.71732 3.30379 H -4.01919 0.01101 2.93660 C -3.88381 -3.34584 0.48895 H -3.69815 -3.52421 1.55200 H -2.98357 -3.67170 -0.04002 C -5.05361 -4.21895 0.03691 H -4.86097 -5.25352 0.32700 H -5.98965 -3.90442 0.49944 H -5.17056 -4.18666 -1.04614 P 4.26310 -0.30746 0.15884 C 5.20849 0.27270 -1.36436 H 4.75167 1.21294 -1.69163 H 6.25460 0.48490 -1.12936 C 5.15727 -0.72993 -2.51672 H 5.46512 -0.25078 -3.44736 H 5.81933 -1.57520 -2.32685 H 4.14177 -1.11524 -2.64233 C 5.11814 -1.95972 0.40905 H 4.65430 -2.67193 -0.28084 H 6.17155 -1.88201 0.12313 C 5.02841 -2.52709 1.82421 H 5.41753 -3.54657 1.84052 H 5.60186 -1.92517 2.52917 H 3.98817 -2.54672 2.15600 C 5.07249 0.73925 1.49299 H 4.67423 0.39189 2.45186 H 4.69613 1.75999 1.36590 C 6.59882 0.77674 1.57721 H 6.89665 1.35016 2.45694 H 7.01872 -0.22476 1.66541 H 7.03038 1.25623 0.69893 P 0.54020 0.66347 -4.18625 C 0.22564 2.40032 -4.82496 H 0.71085 3.09306 -4.13064 H 0.69956 2.53727 -5.80137 C -1.25205 2.77005 -4.94545 H -1.35213 3.83547 -5.15929 H -1.73005 2.21033 -5.75002 H -1.77854 2.55103 -4.01396 C -0.31031 -0.32739 -5.55031 H -1.38586 -0.13635 -5.48194 H 0.01101 0.00196 -6.54210 C -0.07813 -1.83035 -5.40257 H -0.63237 -2.37433 -6.16909 H 0.97995 -2.07651 -5.49904 H -0.42183 -2.16791 -4.42187 C 2.34305 0.47110 -4.66339 H 2.65871 -0.51529 -4.31013 H 2.90238 1.20335 -4.07212 C 2.73771 0.61134 -6.13325 H 3.82165 0.51779 -6.22187 H 2.28001 -0.16835 -6.74157 H 2.44775 1.58156 -6.53622 P 0.62497 1.10725 4.12138 C 2.39189 1.12488 4.75495 H 2.99045 1.67998 4.02630 H 2.45236 1.66544 5.70425 C 2.99908 -0.26481 4.94187 H 4.06777 -0.18045 5.14607 H 2.52854 -0.78692 5.77566 H 2.86297 -0.86705 4.04081 C -0.20941 0.28666 5.60490 H 0.15369 -0.74420 5.66370 H 0.07196 0.77828 6.54013 C -1.73060 0.25398 5.47187 H -2.17355 -0.26257 6.32492 H -2.14306 1.26238 5.42400 H -2.01420 -0.27566 4.55989 C 0.18744 2.91028 4.39005 H -0.80673 3.06756 3.95946 H 0.88329 3.49228 3.77726 C 0.19716 3.46228 5.81507 H 0.01322 4.53785 5.78327 H -0.58383 3.00325 6.42068 H 1.15764 3.29671 6.30321 P 0.50037 -4.23165 -0.45649 C 0.33638 -4.95275 -2.18024 H 0.88223 -4.28949 -2.85878 H 0.82383 -5.93134 -2.22239 C -1.09935 -5.10086 -2.67831 H -1.09940 -5.40811 -3.72540 H -1.64199 -5.84739 -2.09777 H -1.62712 -4.14741 -2.59715 C -0.42694 -5.55682 0.51882 H -1.48401 -5.50017 0.24082 H -0.08115 -6.55916 0.25173 C -0.31641 -5.35550 2.02886 H -0.92092 -6.09745 2.55307 H 0.71702 -5.44947 2.36437 H -0.67723 -4.36005 2.30237 C 2.28540 -4.69974 -0.10975 H 2.56512 -4.22430 0.83575 H 2.88463 -4.21217 -0.88607 C 2.66107 -6.17949 -0.04535 H 3.74212 -6.26881 0.07682 H 2.18351 -6.67142 0.80162 H 2.37807 -6.70546 -0.95721 P -1.88362 3.80220 0.05043 C -3.72133 3.80113 0.43439 H -3.92611 2.89184 1.00638 H -3.95713 4.64298 1.09168 C -4.66286 3.84410 -0.76765 H -5.68683 3.66404 -0.43496 H -4.62838 4.81311 -1.26529 H -4.39293 3.06880 -1.48575 C -1.85215 4.95783 -1.44558 H -2.32560 4.43432 -2.28107 H -2.43731 5.86170 -1.25698 C -0.43388 5.34449 -1.86016 H -0.45831 5.92448 -2.78423 H 0.05377 5.94199 -1.08916 H 0.16816 4.44750 -2.03047 C -1.28938 4.97422 1.41176 H -0.19434 4.95693 1.40891 H -1.60040 4.51594 2.35618 C -1.76235 6.42709 1.38328 H -1.44247 6.92890 2.29841 H -1.33556 6.96411 0.53662 H -2.84893 6.49209 1.32206 end task opt xtb end Example: Geometry Optimization by GFN2-xTB for Avibactam in Implicit Solvent ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Perform geometry optimization by GFN2-xTB for an organic anion in implicit DMSO solvent: .. code-block:: bash :linenos: :caption: xtb-3.inp xtb chrg -1 # The charge is set here. gfn 2 gbsa DMSO # This is in the list of xtb/gbsa item. end # Avibactam anion. mol N 1.83500 1.56700 0.16500 C 2.12100 0.23900 0.16900 O 1.81100 -0.44100 -0.81200 C 2.91300 -0.26000 1.37900 C 3.39800 -1.72600 1.24400 C 3.05700 -2.71300 2.38100 C 2.33800 -2.11500 3.59200 C 1.27000 -1.15400 3.10000 C 2.15100 0.03200 2.68300 C 3.19600 0.07600 3.78800 O 3.93800 1.02100 3.98300 N 3.17400 -1.18300 4.31100 O 4.05400 -1.65700 5.28400 S 3.38300 -1.70500 6.79900 O 4.42700 -2.31500 7.61600 O 3.08700 -0.30900 7.10900 O 2.19100 -2.53900 6.62800 H 1.26500 1.98900 -0.55600 H 2.09600 2.17600 0.93800 H 3.82300 0.36100 1.36100 H 4.49300 -1.70100 1.15700 H 3.06500 -2.17300 0.29900 H 3.97500 -3.21900 2.70500 H 2.41300 -3.49600 1.96000 H 1.94500 -2.89800 4.24100 H 0.61200 -0.86000 3.92800 H 0.65100 -1.55100 2.29000 H 1.57300 0.96000 2.68200 end task opt xtb end Example: Geometry Optimization by for Organic Radical C\ :sub:`13`\ H\ :sub:`9` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Perform geometry optimization by GFN2-xTB for an organic radical C\ :sub:`13`\ H\ :sub:`9`: .. code-block:: bash :linenos: :caption: xtb-4.inp xtb chrg 0 gfn 2 uhf 1 # The number of unpaired electrons is 1. end # C13H9 mol C 0. -1.2266 -2.135 C 0. 0.0000 -1.424 C 0. 1.2266 -2.135 C 0. -2.4574 -1.388 C 0. 0.0000 0.008 C 0. -1.2295 0.717 C 0. -2.4588 -0.032 C 0. -1.2128 2.117 H 0. -2.1632 2.672 C 0. 0.0000 2.807 C 0. 1.2128 2.117 C 0. 1.2295 0.717 C 0. 2.4588 -0.032 C 0. 2.4574 -1.388 H 0. 3.4035 -1.951 H 0. 3.4010 0.542 H 0. -3.4035 -1.951 H 0. -3.4010 0.542 H 0. 0.0000 3.908 H 0. 2.1632 2.672 H 0. -1.2130 -3.109 H 0. 1.2130 -3.109 end task opt xtb end Developing Tools ================ .. contents:: :local: ------ Auxiliary Development Tools --------------------------- All auxiliary development tools are contained in ``tools``. ``tools/develop.py`` ++++++++++++++++++++ This file adds a new module or class to the project. - To add a new class, say called ``PhysicalConstants``, run this command: .. code-block:: bash $ tools/develop.py addclass PhysicalConstants then two files ``PhysicalConstants.h`` and ``PhysicalConstants.cpp`` will be generated, which can be copied to the path you want to place. - To add a new module, say called ``properties``, run this command **in the root directory**: .. code-block:: bash $ tools/develop.py addmodule properties then a new folder ``src/properties`` will be created. You can add source codes there. ``tools/code_review_list.docx`` +++++++++++++++++++++++++++++++ - Code must pass all the items in this file before it is merged to the master branch of the project. Source Code Editor ------------------ - `Visual Studio Code `_ is used to edit code. - `Code Spell Checker `_ is used for spelling check of all code. It is an extention of Visual Studio Code. A brief Chinese tutorial for Visual Studio Code: - ``_ Developer can also use his/her preferred editor. Static Analysis --------------- - `Cppcheck `_ is used for static analysis of code. Documentation ------------- - `Sphinx `_ is used for general documentation. Two brief Chinese tutorials for Sphinx: - ``_ - ``_ Git Commands ===================== - ``git clone XXXX`` Clone a project from a remote repository, where ``XXXX`` is the URL of the repository. - ``git add -A`` Add all changes (new files, modified files, deleted files) to the staging area. - ``git add XXXX`` Add a specific file or directory to the staging area, where ``XXXX`` is the path to the file or directory. - ``git commit -m XXXX`` Commit the staged changes with a message, where ``XXXX`` is the commit message. - ``git status`` Show the status of the working directory and staging area, including untracked files, modified files, and staged files. - ``git log`` Show the commit history, including commit hashes, authors, dates, and commit messages. - ``git push`` Push the committed changes to the remote repository. - ``git pull`` Fetch and merge changes from the remote repository to the local repository. - ``git branch`` List all branches in the local repository, highlighting the current branch. - ``git branch XXXX`` Create a new branch named ``XXXX``. - ``git checkout XXXX`` Switch to the branch named ``XXXX``. - ``git merge XXXX`` Merge the changes from branch ``XXXX`` into the current branch. - ``git branch`` List all branches in the local repository, highlighting the current branch. Domain Logic ============ .. contents:: :local: ------ Some general developing guide is given here. General Rules ------------- - Do **not** “invent” new functions. For well-defined things, check if it is already realized in STL, Boost, Eigen, in computational chemical communities, or in this project. If you are not sure, consult the project leader. - Always design a **low-coupling** module, class, and function. It should has the least dependence on other code. General Libraries ----------------- STL +++ - STL provides a lot of excellent containers. In this project, ``vector``, ``map``, and ``set`` has been extensively used. For **performance-nonsensitive** code, they are highly flexible and efficient and are strongly recommended. Developer does not have to bother with memory issues. - Remember to use ``reserve`` for efficient implementaion. - For ``vector``, its visit can be done using the traditional ``for (int i = 0; i < size; ++i)``, or ``iterator`` or ``const_iterator`` if read-only. Developer can choose a suitable way according to the context. - ``vector`` can be used as an ordinary array by ``data()``. - For ``map`` or ``set``, their visit must be done with ``iterator`` or ``const_iterator`` if read-only. - Do **not** use things like ``for (auto x : vectorX)``. Boost +++++ - Boost provides a lot of general functions for C++ and developer should use **approved libraries** from the Boost library collection. - In this project, all parsing works are done by ``spirit`` from Boost. - In this project, all graph theory operations are done by ``BGL`` from Boost. - Boost also provides realization of a lot of special functions like Bessel functions. kiseki ------ Error +++++ - When there is an error that the program must terminate, please use the macro ``ErrorTermination`` in ``src/system/RunStatus.h`` to gracefully stop. .. code-block:: cpp :caption: src/system/CodeInfo.h if ((words.size() == 2 || words.size() == 3) && (Parser::ParseInteger(words[1], K))) { // ... } else { ErrorTermination("Basis set format at \"%s\" is incorrect. It should be like \"P(angular momentum) " "5(contraction degree) 1.00(real number)\" or \"0 10 1.00\".", tstr.c_str()); } - The error information should be given as detailed as possible. Print +++++ - When you want to print something on ``stdout``, **always** use ``mprintf`` or ``lmprintf`` in ``src/system/lmfprintf.h``. This guarantees the consistent behaviour of the program in single and multiple-node version. .. code-block:: cpp :caption: src/system/CodeInfo.h mprintf("Platform: %s\n", compiling_info.platform.c_str()); mprintf("Compiled by: %s@%s\n", compiling_info.user.c_str(), compiling_info.machine.c_str()); mprintf("Compiling date: %s\n", compiling_info.time.c_str()); mprintf("C++ compiler: %s\n", compiling_info.compiler.c_str()); mprintf("C++ options: %s\n", compiling_info.compiling_flags.c_str()); mprintf("Libraries: %s\n", compiling_info.libs.c_str()); - ``lmprintf`` is short for logic mprintf. This is use for printing level control. Sometimes a function may be called be many higher level functions, which may have different printing requirement. For example, when SCF energy is called by an energy calculation, it will print long output; but when it is called by a geometry optimization function, only part of the output is needed. In this case, a logic flag can be used to control the behavior easily. .. code-block:: cpp :caption: src/scf/SelfConsistentField.h // When print_details is set to false, these words will not be output. lmprintf(print_details, " ---- Self Consistent Field Gradient Begun -----------------\n"); lmprintf(print_details, " ===========================================================\n"); lmprintf(print_details, "\n"); lmprintf(print_details, " ---- Self Consistent Field Gradient Done ------------------\n"); lmprintf(print_details, "\n"); - Things like ``printf`` or ``cout`` can only be used for debug and should not appear in released codes. Parse +++++ - The class in ``src/system/Parser.h`` gives a lot of functions for parsing strings. +-------------------------------+---------------------------------------------------------------------------------------+ | Function | Example | +===============================+=======================================================================================+ | ``Parser::ParseInteger`` | Transform ``"-34"`` to ``-34``. | +-------------------------------+---------------------------------------------------------------------------------------+ | ``Parser::ParseRealNumber`` | Transform ``"31.4"`` or ``"3.14E+01"`` to ``31.4``. | +-------------------------------+---------------------------------------------------------------------------------------+ | ``Parser::ParseNumberRange`` | Transform ``"3-9"`` to ``{3,9}``, and ``"7"`` to ``{7,7}`` | +-------------------------------+---------------------------------------------------------------------------------------+ | ``Parser::SplitSentence`` | Transform ``"filename a.inp b.inp"`` to a vector: ``{"filename", "a.inp", "b.inp"}``. | +-------------------------------+---------------------------------------------------------------------------------------+ | ``Parser::ToUpperCase`` | Transform ``"aBcD eFgH"`` to ``"ABCD EFGH"``. | +-------------------------------+---------------------------------------------------------------------------------------+ | ``Parser::ToLowerCase`` | Transform ``"aBcD eFgH"`` to ``"abcd efgh"``. | +-------------------------------+---------------------------------------------------------------------------------------+ - One can refer to ``src/scf/SelfConsistentField_SCFArgs.cpp`` to see how the program is parsing configurations from an input file. Running Information +++++++++++++++++++ - To access the running information of the program, one should refer to ``src/system/RunStatus.h``. +-------------------------------+---------------------------------------------------------------------------------------+ | Function | Description | +===============================+=======================================================================================+ | ``RunStatus::GetJobName`` | If the input file is ``water.inp``, then this returns ``water``. | +-------------------------------+---------------------------------------------------------------------------------------+ | ``RunStatus::GetTime`` | Get the current time. | +-------------------------------+---------------------------------------------------------------------------------------+ | ``RunStatus::GetDuration`` | Get the difference between two time objects obtained by ``RunStatus::GetTime``. | +-------------------------------+---------------------------------------------------------------------------------------+ | ``RunStatus::GetScratchPath`` | Get the scratch path provided by user through ``-s`` argument. | +-------------------------------+---------------------------------------------------------------------------------------+ | ``RunStatus::GetMemorySize`` | Get the maximum memory size provided by user through ``-m`` argument. | +-------------------------------+---------------------------------------------------------------------------------------+ | ``RunStatus::GetDiskSize`` | Get the maximum disk size provided by user through ``-d`` argument. | +-------------------------------+---------------------------------------------------------------------------------------+ OpenMP and MPI Parallelization ++++++++++++++++++++++++++++++ - Read ``src/system/ComputationalResource.h`` carefully. It provides all functions needed to manipulate parallelization. - Do not include something like ````, ```` or use ``omp_get_num_threads``, ``MPI_Comm_rank`` explicitly in your code. It has been wrapped in ``src/system/ComputationalResource.h`` so a consistent behavior can be obtained for OpenMP and MPI version of the program. So, please use ``ComputationalResource::GetOpenMPRank();`` to get the current OpenMP ID. +----------------------------------------------+------------------------------------------------------------------------+ | Function | Description | +==============================================+========================================================================+ | ``ComputationalResource::GetOpenMPRank`` | Get the OpenMP thread ID of the current MPI process. | +----------------------------------------------+------------------------------------------------------------------------+ | ``ComputationalResource::GetMPIRank`` | Get the process ID of the current MPI process. | +----------------------------------------------+------------------------------------------------------------------------+ | ``ComputationalResource::GetFreeMemorySize`` | Get the free memory size of current node in byte. | +----------------------------------------------+------------------------------------------------------------------------+ | ``ComputationalResource::GetFreeDiskSize`` | Get the free disk size in byte for the given path. | +----------------------------------------------+------------------------------------------------------------------------+ - For MPI call, please use the macro ``MPI_Check`` in ``src/system/ComputationalResource.h``, like ``MPI_Check(MPI_AllReduce(...))``. Input Design ------------ - TODO Quantum Chemistry Coding ------------------------ - TODO Molecular Mechanics Coding -------------------------- - TODO Code Styles =========== .. contents:: :local: ------ Code Format ----------- Code format in a project usually defines something like "A line length should not exceed 80 characters", "order of including header files", or "One space is needed before and after +". However, in this project, one can write code in somewhat "free format". The standard formatting is **automatically** done by using editors like Visual Studio Code with the format configuration file ``src/.clang-format``. .. hint:: Press :kbd:`Shift+Alt+F` in Visual Studio Code will format the code. C++ Version ----------- - C++17 is used currently. - Do **not** use C++2X features. File Structures --------------- General Rules +++++++++++++ - All C++ header and source files must be placed into ``src``. - Each folder in ``src`` is a **module**, which contains many closely-related classes. .. hint:: For example, ``src/geom`` contains all classes of pure geomertic operations. - Each class must have at least two files: header file ``*.h`` that contains **declaration**, and a source file ``*.cpp`` that contains implementation. .. hint:: Do **not** put any implementation in header files, like the assignment of a static class member. - If the implementation of the class is very large, then the source file can be **split into several ones**, each containing closely-related functions. These files must be named as ``*_*.h``. Splitting should not be done **unless very necessary**. .. hint:: For example, class ``MultiplicationTable`` can have two source files ``MultiplicationTable_integer.cpp`` and ``MultiplicationTable_real.cpp`` that implement the multiplication of integers and real numbers, respectively. Header Files ++++++++++++ - A header file must be protected using ``#ifndef/#define/#endif`` macro. By using ``tools/develop.py``, this is automatically done. - ``namespace kiseki`` is the **only one** allowed in this project. - **No** additional ``using namespace`` is allowed in header files outside ``namespace kiseki``. They can be used inside ``namespace kiseki``. - ``<>`` and ``".h"`` are used to include standard (including STL, Boost, and Eigen) and non-standard header files, respectively. .. code-block:: cpp :caption: MulticationTable.h #ifndef __MULTICATIONTABLE_H__ #define __MULTICATIONTABLE_H__ #include "Addition.h" #include #include namespace kiseki { using namespace std; // This "using namespace" cannot be placed outside "namespace kiseki". class MulticaionTable { ... }; } // namespace kiseki #endif // __MULTICATIONTABLE_H__ Naming ------ General Rules +++++++++++++ - All names must be **max-information** without unambiguities, even they are longer. - Below are some recommended words and abbreviations that used extensively in this project. +------------------+------------------------+------------------------------------+ | Word | Explanation | Examples | +==================+========================+====================================+ | ``num`` | Number of ... | ``num_electrons``, ``GetNumAtoms`` | +------------------+------------------------+------------------------------------+ | ``calc`` | Calculate, calculation | ``AccurateCalc``, ``CalcDensity`` | +------------------+------------------------+------------------------------------+ | ``mol`` | Molecule | ``mol_charge``, ``BuildMol`` | +------------------+------------------------+------------------------------------+ | ``geom`` | Geometry, geometric | ``geom_center``, ``OptimizeGeom`` | +------------------+------------------------+------------------------------------+ | ``coord`` | Coordinate | ``moved_coord``, ``GetCoords`` | +------------------+------------------------+------------------------------------+ | ``param`` | Parameter | ``num_params`` | +------------------+------------------------+------------------------------------+ | ``fn`` | File name | ``param_fn`` | +------------------+------------------------+------------------------------------+ | ``fd`` | File handle | ``param_fd`` | +------------------+------------------------+------------------------------------+ | ``inp`` | Input | ``inp_fd`` | +------------------+------------------------+------------------------------------+ | ``iter`` | Iterator | ``iter`` | +------------------+------------------------+------------------------------------+ | ``str`` | String | ``VectorToStr`` | +------------------+------------------------+------------------------------------+ | ``set``/``get`` | | ``GetEnergy``, ``SetEnergy`` | +------------------+------------------------+------------------------------------+ Module ++++++ Must be named using **a short word in lower case**, like ``algorithm``. Class, Structure, ``typedef`` and Enum ++++++++++++++++++++++++++++++++++++++ Must be named using **capitalized** **meaningful nouns and adjectives**, each word being , like ``MultiplicationTable``. Global and Class Member functions +++++++++++++++++++++++++++++++++ - Must be named using **capitalized** words and should be **verb** or **verb+noun**. For example, class ``Molecule`` has a function to get its number of atoms, then this one is named as ``GetNumElectrons``. - But do **not** contain redundant information. For example, a function that rotate the molecule should not be called ``RotateMol`` but simply ``Rotate``. Global and Class/Structure Member Variables +++++++++++++++++++++++++++++++++++++++++++ Standard Rules ^^^^^^^^^^^^^^ .. hint:: Although it is controversial that whether long variable names should be used, in this project, **unambiguity is over length**, that is, long but clear variable names are always preferred to short but ambiguous ones. For example, the number of alpha-spin electrons is named as ``num_alpha_electrons`` instead of ``nAelec``. - Non-constant variables must be named using **lower-cased** words connected by ``_``. For example, ``num_atoms``, ``geom_center``. - For well-known, professional abbreviations, cases follow the convention. For example, ``hydrogen_NMR_shift``, ``modified_RESP_charge``. - Constant variables must be named using **capitalized** words. **No** ``_`` is recommended. For example, ``LightSpeedInVacuum``, ``WaterEpsilon``. - Numbers are **not** separated by ``_``. For example, ``C12_mass``, ``N15_mass``. - Unless necessary, meaningless numbered variable names are **not** allowed. For example, ``value1`` and ``value2``. - For a lot of objects like array, ``vector``, ``map`` or ``set``, naming should use **plural forms**. .. code-block:: cpp :caption: Examples of naming with plural forms. vector coords; // A lot of things called coord. double coord = coords[0]; // A single coord. - For class/structure member assignment purpose, one the use ``t`` to represent temperary arguments that are to be assigned to the ones with the same name. .. code-block:: cpp :caption: Examples of naming arguments for class/structure member assignment. class Point { public: void SetX(double tx); // "tx" is to set to "x". void SetY(double ty); // "ty" is to set to "y". private: double x; double y; }; void Point::SetX(double tx) { x = tx; } void Point::SetY(double ty) { y = ty; } Exceptions ^^^^^^^^^^ - For unimportant loop variables, one can use ``i``, ``j``, ``k``, ``p`` or other convenient names. .. code-block:: cpp :caption: Examples of unimportant loop variables. for (int i = 0; i < MaxI; ++i) { // ... } for (int i = 0; i < num_atoms; ++i) { for (int j = 0; j <= i; ++j) { // ... } } - For variables that are pure mathematical or physical quantities, a convenient name can be used. .. code-block:: cpp :caption: Examples of mathematical or physical quantities. const double PISquared4 = 39.47841760435743; // 3.14^2*4 // This implements Lennard-Jones energy. double CalcLennardJonesEnergy(double r, double epsilon, double sigma) { // ... } - When third-party code is called, variable names can follow its styles. .. code-block:: cpp :caption: Examples of variable names following third-party code styles. // This is a Win32 API. HWND hWnd; WPARAM wParam; LPARAM lParam; SendMessage(hWnd, WM_FONTCHANGE, wParam, lParam); Class and Structure Format -------------------------- - ``public`` declarations go before ``private`` ones. - Self-defined classes, structures, ``typedef``, or enums go first, then member functions, then member variables. - Static members go before non-static ones. - Constant members go before non-constant ones. .. code-block:: cpp :caption: Examples of a class declarations. class StructureGenerator { public: class Placement { public: enum Way { fix, box }; Placement(const string& text); ~Placement(void); static const int Assigned; static const int Random; string note; Way way; private: void ParseFix(const vector& words);); }; StructureGenerator(const Cluster& clu); ~StructureGenerator(void); void SampleOne(Cluster& clu, bool do_coarse_optimization) const; void RandomOne(Cluster& clu) const; private: void CoarseOptimize(Cluster& clu) const; static const double PI2; static const double ZeroNorm; static const double dS; vector mols; vector num_mols; }; - Initializer list is always preferred. Flow Control ------------ ``++`` and ``--`` +++++++++++++++++ - **Always** use ``++x`` or ``--y``. - **Never** use ``x++`` or ``y--``. ``if`` and ``while`` Statement ++++++++++++++++++++++++++++++ - Do **not** use integers to represent true or false. - Do **not** compare bool variables with ``true`` or ``false`` directly! - Explictly use Boolean expressions! .. code-block:: cpp :caption: Examples of Boolean expressions. while (true) // Do not use "while (1)"! { // ... } if (flag == 0) // Do not use "if (flag)"! { // ... } bool calc_eigen_vectors = true; if (!calc_eigen_vectors) // Do not use "if (calc_eigen_vectors == false)"! { // ... } - Characters must be compared with ``'\0'``. - Pointers must be compared with ``nullptr``. .. code-block:: cpp :caption: Examples of pointer comparison. if (fd != nullptr) // Do not use if (fd) ! { // ... } ``for``, ``switch``, and ``goto`` Statement +++++++++++++++++++++++++++++++++++++++++++ - In condition statement of ``for``, **left-close-right-open** is preferred, like ``for (int i = 0; i < 5; ++i)``. - In ``switch``, there must be ``break`` in all ``case`` and ``default`` blocks unless on purpose. ``default`` **must** be present! - ``goto`` should be used with cautions, and goto label must have a meaningful name. .. code-block:: cpp :caption: Examples of ``goto``. if (key == "rhf") { // ... goto finish_parsing; } if (key == "rmp2") { // ... goto finish_parsing; } ErrorTermination("Unknown keyword \"%s\".", key.c_str()); finish_parsing_assignment_map:; Usage of ``const`` ------------------ .. hint:: Always use ``const`` whenever possible! It will save one a large amount of debugging time! - **Never** use ``#define`` to define constants. - Use ``const`` for constants. Dependencies should be used. .. code-block:: cpp :caption: Examples of constants. const double PI2 = 6.28318530717958623200; const double PI4 = PI2 * 2; // Dependence of this constant to PI2 is used. - Use ``const`` for variables that will not be changed in the following, even it is not a constant! .. code-block:: cpp :caption: Examples of variables that will not be changed in the following. const double r = sqrt(x * x + y * y); // r is never changed in this function. const doulbe r_rec = 1. / r; double energy = 0.; energy += k * pow(r - r0, 1.5); energy += r_rec * q; - For pointer or reference functions arguments, always use ``const`` when they are only input! .. code-block:: cpp :caption: Examples of pointer or reference functions arguments that are only input! void CopyArray(int num, const double* source_array, double* target_array) { // ... } string Reverse(const string& str) { // ... } - For member functions that will not modify member variables, always use ``const``. .. code-block:: cpp :caption: Examples of member functions that will not modify member variables class Point { public: Point(void); ~Point(void); double GetX(void) const; // It will not change anything, so const is added. double GetY(void) const; // It will not change anything, so const is added. void SetX(double tx); void SetY(double ty); private: double x; double y; }; - When go over an STL container in a read-only way, use ``const_iterator`` instead of ``iterator``. Function Design --------------- Arguments and Return ++++++++++++++++++++ - Arguments should be named and ordered **meaningfully**. Input arguments go first. - It there is no argument, use ``void``. - Do **not** use default arguments. - For input pointer or reference arguments, add ``const``. - For member functions that do not modify the class or structure, add ``const``. - For non-native types, **always** use pass by reference or pointers. - Pass by reference is **preferred**. - Pass by pointer is only used when necessary. - Function should **not** return a complicated class or structure. Use output arguments to do that. .. code-block:: cpp :caption: Examples of function arguments and return design. // "source_array" and "target_array" are meaningful. // If one writes "CopyArray(int num, const double* array1, double* array2)", it will take a moment // to distinguish which one is the source or the target. // Note that there is a "const" before "source_array". void CopyArray(int num, const double* source_array, double* target_array); // Note that there is a "const" after the function. // Do not lose "void". const string& GetName(void) const; // Do not use "vecter coords" (pass by value)! // One can also use vecter* coords, but reference is always preferred. void Rotate(vector& coords, double angle); // Do not use "vector GeneratePoints(int num);"! void GeneratePoints(int num, vector& points); - If there are many arguments, consider to design a class or structure of input or output arguments. .. code-block:: cpp :caption: Examples of a function containing many arguments. // This is a bad design! void Parse(const string& mass_fn, const string& position_fn, const string& velocity_fn, const string& experimental_condition_fn, vector& masses, vector& positions, vector& velocities, double& temperature, double& pressure); // This is a good design. struct ParseInputArgs { string mass_fn; string position_fn; string velocity_fn; string experimental_condition_fn; }; struct ParseOutputArgs { vector masses; vector positions; vector velocities; double& temperature; double& pressure; }; void Parse(const ParseInputArgs& input_args, ParseOutputArgs& output_args); - Function arguments should have the highest compatibility, especially for **low-level** functions. .. code-block:: cpp :caption: Examples of function argument compatibility. // Bad compatibility. Can only be used for "vector". void Add(int num, const vector& a, const vector& b, vector& c) { for (int i = 0; i < num; ++i) { c[i] = a[i] + b[i]; } } // Better compatibility. void Add(int num, const double* a, const double* b, double* c) { for (int i = 0; i < num; ++i) { c[i] = a[i] + b[i]; } } const int num = 100; vector a(num, 1.); vector b(num, 2.); vector c(num, 0.); // For "vector", their addresses can be obtained by ".data()". Add(num, a.data(), b.data(), c.data()); Inside Function +++++++++++++++ - Do **not** use static local variables unless necessary! - Do **not** use inline functions. - One function focuses one thing! Numbers ------- - **Never** use ``unsigned`` like ``unsigned int``, unless third-party functions require. - For assignment of floating-point numbers, always use ``.`` or ``E``. - For accurate floating-point numbers, at most 25 decimals are enough. .. code-block:: cpp :caption: Examples of floating-point numbers. double x = 5.93; double y = -1.; // Do not use "y = -1"! double z = 5.E-5; const double PI = 3.1415926535897932384626433; // 25 decimals. Forbidden C++ Features ---------------------- - Do **not** use C++ exceptions. - Do **not** use class friends. - ``auto`` is only used for lambda functions. Comments -------- - In this project, Doxygen is used for docmentation. - Comments should be as readable as narrative text. Important information or algorithms that are not easy for others to understand should be commented in detail. If necessary, use Latex code in ``\f$...\f$`` or ``\f[...\f]`` to give mathematical details. - In all files (head and source files)，at the beginning authors must be listed in the following Doxygen format: .. code-block:: cpp :caption: Format of commenting authors. /** * @file * @author * - Isaac Newton * - Leonhard Euler */ - In head files, all classes, structures, ``typedef``, and enum must be commented with ``@brief`` and ``@details`` (optional) in the following format: .. code-block:: cpp :caption: Format of commenting classes, structures, ``typedef``, and enum. /** * @brief A collection of geometrical operations. * @details * If not necessary, details can be omitted. */ class SpaceTransformation { public: /** * @brief A pre-computed data structure of \ref Cluster::RigidCoord. */ class ProcessedRigidCoord { // ... }; // ... }; - In head files, all functions must be commented with ``@brief``. All parameters must be commented with ``@param`` (with proper ``[in]``, ``[out]``, or ``[in,out]``). Returns must be commented with ``@return`` in the following format. If necessary, ``@details``, ``@note``, ``@warning`` can be given. .. code-block:: cpp :caption: Format of commenting functions. /** * @brief Calculate space-fixed coordinates. * @details * Note that each molecule has its own rigid coordinate, so they only have 6*3*number of atoms in the molecule * components. * @param[out] x The space-fixed coordinates: x0, y0, z0, x1, y1, z1, ... * @param[out] dxdrc If it is not \c nullptr, the derivatives of \p x over rigid coordinates will be calculated: * dx0/dphiZ1, dx0/dphiY2, dx0/dphiZ3, dx0/dmX, dx0/dmY, dx0/dmZ, dy0/dphiZ1, ... * @warning * - The size of \p x should be at least 3*\c GetNumAllAtoms. * - The size of \p dxdrc should be at least 3*6*\c GetNumAllAtoms if it is not \c nullptr. */ void CalcSpaceFixedCoords(double* x, double* dxdrc) const; - In head files, all class, structure, and enum members must be commented with ``///<``: .. code-block:: cpp :caption: Format of commenting class, structure, and enum members. /** * @brief Possible ways of placement. */ enum Way { fix, ///< See \ref ParseFix for details. box, ///< See \ref ParseBox for details. }; string note; ///< Some human-understandable description of how to place a component. Way way; ///< How to place a component. int integer_params[32]; ///< The integer parameters for placing the molecules. Their meanings depend on \ref ///< way. - Use ``@ref``, ``\p``, ``\c``, ``@code ... @endcode`` whenever possible and necessary. Exceptions ---------- In real coding projects, there may be some cases that changing the rules above can significantly improve the performance of the program. In this case, one can consider breaking the rules. But please make sure that this is **absolutely necessary!** Quick Links =============== Qbics Related --------------- - Qbics Home: http://qbics.info - Qbics Download: http://qbics.info/home/download.html - Qbics Tutorial: http://qbics.info/tutorial - Qbics Manual: http://qbics.info/manual